@conto_finance/sdk 0.1.0 → 0.3.1

package/README.md

@@ -34,14 +34,92 @@ const request = await conto.payments.request({
   recipientName: 'OpenAI',
   purpose: 'API credits',
   category: 'API_PROVIDER',
+  // Optional for a single attempt. Supply and reuse your own key when retrying
+  // across process restarts or independent job attempts.
+  idempotencyKey: crypto.randomUUID(),
 });
 
 if (request.status === 'APPROVED') {
   const result = await conto.payments.execute(request.requestId);
-  console.log(result.txHash);
+  console.log(result.status);
+  console.log(result.receipt.transactionId, result.receipt.settlementMode);
+  console.log(result.receipt.txHash);
 }
 ```
 
+## External-card Policy Overlay
+
+The admin client registers only a masked card alias and assigns cooperative
+controls. Never pass PAN, CVC, expiry, or another usable credential to these
+methods.
+
+```typescript
+import { ContoAdmin } from '@conto_finance/sdk';
+
+const admin = new ContoAdmin({
+  orgApiKey: process.env.CONTO_ORG_API_KEY!,
+});
+
+const { card } = await admin.cards.register({
+  name: 'Agent purchasing card',
+  last4: '4242',
+  brand: 'VISA',
+  fundingType: 'CREDIT',
+  spendLimitDaily: 500,
+  spendLimitPerTx: 200,
+});
+
+await admin.cards.assignToAgent('agent_id', {
+  cardId: card.id,
+  timezone: 'America/Los_Angeles',
+  spendLimitDaily: 250,
+  spendLimitPerTx: 100,
+  allowedMerchants: ['Example Software'],
+});
+
+await admin.cards.updateAgentAssignment('agent_id', card.id, {
+  timezone: 'America/Los_Angeles',
+  spendLimitDaily: 250,
+  spendLimitPerTx: 100,
+  activeUntil: '2026-09-01T00:00:00.000Z',
+});
+
+await admin.cards.pauseForAgent('agent_id', card.id);
+await admin.cards.resumeForAgent('agent_id', card.id);
+await admin.cards.revokeFromAgent('agent_id', card.id);
+```
+
+The policy overlay stops at approval, claiming, and reconciliation. For a
+customer-hosted payment tool that gates access to customer payment code, use the
+separate
+[`@conto_finance/card-access`](https://conto.finance/docs/card-access/overview) product
+package.
+
+```typescript
+import { ContoCardAccess } from '@conto_finance/card-access';
+
+const cardAccess = new ContoCardAccess({
+  policy: conto.cards,
+  integrationId: 'procurement-agent-production',
+  deployment: {
+    credentialCustody: 'CUSTOMER',
+    agentHasRawCredentialAccess: false,
+    uncontrolledAgentPaymentPath: false,
+  },
+  executor: customerHostedExecutor,
+});
+```
+
+Card Access claims each approved request exactly once before the executor can run. A
+duplicate or uncertain claim cannot invoke the executor again. It remains
+bypassable if another person or tool can access the card, and results are
+self-reported rather than issuer-verified. The legacy `conto.cards.controlled()`
+helper remains available for compatibility, but new customer-hosted enforcement
+should use the standalone Card Access package. Use
+`admin.cards.listRequests({ status: 'EXECUTING' })` for reconciliation and
+`admin.cards.pause(card.id)` to revoke unclaimed grants and stop new approvals
+in the Conto-controlled path.
+
 For a single-call managed-wallet flow, use:
 
 ```typescript
@@ -52,6 +130,36 @@ const result = await conto.payments.pay({
 });
 ```
 
+## Protocol Clients
+
+`Conto` also exposes typed helpers for x402 and MPP service payments:
+
+```typescript
+const paymentId = crypto.randomUUID();
+
+await conto.x402.preAuthorize({
+  amount: 0.01,
+  recipientAddress: '0x...',
+  resourceUrl: 'https://api.example.com/v1/search',
+  paymentId,
+  sessionId: 'session_123',
+});
+
+await conto.x402.record({
+  amount: 0.01,
+  recipientAddress: '0x...',
+  resourceUrl: 'https://api.example.com/v1/search',
+  paymentId,
+  txHash: '0x...',
+  sessionId: 'session_123',
+});
+
+const budget = await conto.x402.budget();
+```
+
+The MPP client mirrors the same shape with `conto.mpp.preAuthorize`, `conto.mpp.record`,
+`conto.mpp.budget`, and `conto.mpp.services`.
+
 ## Admin SDK Quick Start
 
 `ContoAdmin` uses an organization API key (`conto_xxx...`), not an agent SDK key.
@@ -79,15 +187,52 @@ const agent = await admin.agents.create({
 const wallet = await admin.wallets.create({
   name: 'Operations Wallet',
 });
+
+const { frozen } = await admin.agents.freeze(agent.id, { freezeWallets: true });
+if (frozen) {
+  await admin.agents.unfreeze(agent.id, { unfreezeWallets: true });
+}
 ```
 
 ## What This Package Covers
 
 - `Conto` for agent-scoped payment flows
 - `ContoAdmin` for organization-scoped provisioning and management
-- Built-in retries for `429` and `5xx` responses
+- Built-in retries for reads and idempotency-protected payment authorization requests
 - Typed request and response shapes for the public SDK surface
 
+## Retry and Error Safety
+
+The SDK automatically adds an idempotency key to wallet payment authorization
+requests. Provide your own stable `idempotencyKey` when a retry may happen in
+another process or job attempt. External-card approvals always require a stable
+caller-supplied `idempotencyKey`; card approval and confirmation are safe to
+retry. x402 and MPP pre-authorization calls are non-mutating policy checks.
+Record calls require an explicit stable `paymentId` or `credentialId` so an
+ambiguous failure can be reconciled safely.
+
+Read-only calls retry transient network failures, `429`, and `5xx` responses. Financial execution
+and other non-idempotent mutations are never retried automatically. If execution times out, call
+`conto.payments.status(requestId)` before attempting it again. A
+`reconciliation_required` status means the execution outcome is ambiguous; do not resend the
+payment until an operator has resolved it.
+
+`ContoError` and `ContoAdminError` expose a stable error contract: `code`, `status`, `requestId`,
+`retryAfter`, and locally generated `retryGuidance` where applicable. Arbitrary server details,
+context, hints, and workflow steps are not forwarded through SDK errors:
+
+```typescript
+import { ContoError } from '@conto_finance/sdk';
+
+try {
+  await conto.payments.status('req_123');
+} catch (error) {
+  if (error instanceof ContoError) {
+    console.error(error.code, error.requestId, error.retryGuidance);
+  }
+}
+```
+
 ## What To Use Instead
 
 - Use the REST API docs if you need endpoints that are not wrapped by this package yet, especially