ProvelyThe SDKs wrap the REST API. Each SDK is a thin translator into the same canonical model: operation, contract, action result, verification, and receipt. No SDK contains verification logic. The runtime owns verification.
| SDK | Package | Status | Types |
|---|---|---|---|
| TypeScript | @provely/sdk | first release | generated from the JSON Schemas |
| Python | provely | first release | pydantic models generated from the JSON Schemas |
| More languages | on request | after the REST API and the schemas support them | generated |
Which calls does every SDK expose?
| Call | REST endpoint | Returns |
|---|---|---|
begin(contract, input) | POST /v1/operations | The operation id, the idempotency key, the correlation keys. |
op.actionResult(result) | POST /v1/operations/{id}/action-result | The stored acknowledgement reference. |
op.verify() | POST /v1/operations/{id}/verify | The verdict, the reason, the evidence levels used. |
op.status() | GET /v1/operations/{id} | The operation state and the last verdict. |
op.receipt() | GET /v1/operations/{id}/receipt | The signed receipt document. |
verifyReceipt(receipt, keys) | offline | The validation result with a reason code. |
Which rules do all SDKs share?
- Generate the types from the contract and receipt schemas. Do not write them by hand.
- Pass the same cross-language conformance fixtures: canonical JSON, contract hashes, receipt validation, verdict rules.
- Read the API key from configuration. Never accept it as a tool argument.
- Return the verdict as the runtime gives it. Do not soften it.
Validate a receipt offline in TypeScript
import { verifyReceipt } from '@provely/sdk';
const result = await verifyReceipt(receipt, {
trustedKeys: { 'provely-prod-2026-09': '<public key hex>' },
});
// result.valid, result.reasonCode: signature_valid | receipt_key_not_trusted | ...Can I use the SDK with a framework adapter?
Yes. Adapters for the OpenAI Agents SDK, LangGraph, and MCP wrap a tool or a node so the action runs inside an operation. They register through the Adapter extension point and contain no verification logic.