@dakota-xyz/ts-sdk 1.6.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -169,6 +169,76 @@ console.log(`Send ${tx.send_amount} USDC to: ${tx.crypto_address}`);
169
169
  console.log(`Status: ${tx.status}`);
170
170
  ```
171
171
 
172
+ ## Agentic Payments (Alpha)
173
+
174
+ > ⚠️ **Alpha.** The hosted payment-agent surface is `x-alpha` and flag-gated on the platform (endpoints return `404` unless enabled for your key). The SDK helpers below may change — or be removed — without a major-version bump. Not recommended for production.
175
+
176
+ A **payment agent** is a named, customer-scoped signer Dakota can drive: you provision it, endorse it onto a wallet, then it drafts and — once a **mandate** is signed — fires payments, bounded by that customer-approved mandate.
177
+
178
+ ### 1. Provision an agent and endorse it onto a wallet
179
+
180
+ ```typescript
181
+ // Create a hosted payment agent (Dakota custodies its signing key).
182
+ const agent = await client.paymentAgents.create({
183
+ customer_id: customerId,
184
+ name: 'Bill Pay',
185
+ hosted: true,
186
+ });
187
+
188
+ // Grant it spend permission on a wallet by adding its signer to the wallet's
189
+ // spending group (idempotent) — the customer-endorsed attach. Pass an
190
+ // options.idempotencyKey to make the whole helper safely retryable.
191
+ await client.attachUserToWallet(walletId, agent.signer_public_key!, spendingGroupId);
192
+ ```
193
+
194
+ ### 2. Draft payments from natural language
195
+
196
+ ```typescript
197
+ const conv = client.newAgentConversation(agent.id!);
198
+ const turn = await conv.send('Pay Alice 100 USDC on base-mainnet every month until December');
199
+
200
+ if (turn.hasProposals) {
201
+ // Review turn.proposals, then accept them through the instructions flow.
202
+ console.log(`agent drafted ${turn.proposals.length} proposal(s)`);
203
+ } else {
204
+ console.log('agent needs more detail:', turn.reply);
205
+ }
206
+ ```
207
+
208
+ ### 3. Sign and approve a mandate (§8)
209
+
210
+ The caller holds the keys; the SDK never does. `P256MandateSigner` is a ready in-memory signer for sandbox/tests — implement the `MandateSigner` interface over your HSM/KMS in production.
211
+
212
+ ```typescript
213
+ import { P256MandateSigner, mandateSignPayload } from '@dakota-xyz/ts-sdk';
214
+
215
+ const signer = P256MandateSigner.generate(); // or P256MandateSigner.fromPrivateKey(yourKey)
216
+
217
+ // `mandate` comes from client.mandates.get / client.mandates.list.
218
+ const payload = mandateSignPayload(mandate, 'approve');
219
+ const signature = signer.sign(payload);
220
+
221
+ await client.mandates.approve(mandate.id!, {
222
+ approver_public_key: signer.publicKeyBase64(),
223
+ signature,
224
+ });
225
+ ```
226
+
227
+ ### 4. Account insights (read-only)
228
+
229
+ ```typescript
230
+ // Deterministic report: balances, upcoming payments, mandate headroom, risks.
231
+ const report = await client.insights.get(customerId);
232
+
233
+ // Advisory chat over the same report — stateless; never moves money.
234
+ const answer = await client.insights.chat(customerId, {
235
+ messages: [{ role: 'user', content: 'Anything I should know about my account this week?' }],
236
+ });
237
+ console.log(answer.reply);
238
+ ```
239
+
240
+ The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
241
+
172
242
  ## Handling Webhooks
173
243
 
174
244
  Dakota sends webhooks for all status changes. Set up a handler:
@@ -412,6 +482,13 @@ Manage customer entities representing businesses and organizations.
412
482
  | `customers.create(data)` | Create a customer (triggers KYB) |
413
483
  | `customers.list(params?)` | List all customers (paginated) |
414
484
  | `customers.get(id)` | Get customer by ID |
485
+ | `customers.delete(id)` | Soft-delete a customer (blocked if it has accounts) |
486
+ | `customers.getCapabilities(id)` | Capabilities + outstanding requirements to unlock each |
487
+ | `customers.reEngage(id)` | Mint a fresh application link for an approved customer |
488
+ | `customers.bulkImportFromSumsubTokens(data)` | Import from Sumsub share tokens (synchronous) |
489
+ | `customers.importPersonaTokens(data)` | Import from Persona Connect share tokens (async job) |
490
+ | `customers.listPersonaImportJobs(params?)` | List Persona import jobs, newest first |
491
+ | `customers.getPersonaImportJob(jobId, params?)` | Job status + per-token results |
415
492
 
416
493
  ### Recipients
417
494
 
@@ -524,9 +601,9 @@ Manage multi-party authorization.
524
601
  |--------|-------------|
525
602
  | `signerGroups.create(data)` | Create signer group |
526
603
  | `signerGroups.list(params?)` | List signer groups |
527
- | `signerGroups.get(id)` | Get signer group by ID |
604
+ | `signerGroups.get(id, params?)` | Get signer group by ID (`{ include_removed: true }` adds `removed_members`) |
528
605
  | `signerGroups.addSigner(groupId, data)` | Add signer to group |
529
- | `signerGroups.removeSigner(groupId, signerId)` | Remove signer |
606
+ | `signerGroups.removeSigner(groupId, signerId)` | Remove signer (by KSUID `signer_id`, not public key) |
530
607
  | `signerGroups.attachToWallet(walletId, groupId)` | Attach to wallet |
531
608
  | `signerGroups.detachFromWallet(walletId, groupId)` | Detach from wallet |
532
609
 
@@ -598,6 +675,82 @@ Test simulations (sandbox environment only).
598
675
  | `sandbox.advanceSimulation(id)` | Advance simulation state |
599
676
  | `sandbox.listScenarios(params?)` | List available scenarios |
600
677
 
678
+ ### Fee Payout Destination
679
+
680
+ Where Dakota pays your accrued developer fees. Exactly one per organization,
681
+ and crypto-only — a USDC wallet on any supported chain.
682
+
683
+ | Method | Description |
684
+ |--------|-------------|
685
+ | `feePayoutDestination.get()` | Get the registered destination |
686
+ | `feePayoutDestination.set(data)` | Register or replace it (emits `fee_payout_destination.updated`) |
687
+ | `feePayoutDestination.delete()` | Remove it (emits `fee_payout_destination.deleted`) |
688
+
689
+ ```typescript
690
+ await client.feePayoutDestination.set({
691
+ usdc_wallet: {
692
+ chain: 'eip155:8453', // CAIP-2 chain id — see client.info.getNetworks()
693
+ address: '0x1234567890123456789012345678901234567890',
694
+ },
695
+ });
696
+ ```
697
+
698
+ ### Payment Agents (Alpha)
699
+
700
+ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
701
+
702
+ | Method | Description |
703
+ |--------|-------------|
704
+ | `paymentAgents.create(data)` | Create a payment agent (hosted or key-supplied) |
705
+ | `paymentAgents.get(id)` | Get payment agent by ID |
706
+ | `paymentAgents.revoke(id)` | Revoke the agent's key (kill switch) |
707
+ | `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
708
+ | `paymentAgents.getProposalsProgress(id)` | Live progress of an in-flight drafting turn (advisory) |
709
+
710
+ ### Mandates (Alpha)
711
+
712
+ The §8 authorizations that arm scheduled payments.
713
+
714
+ | Method | Description |
715
+ |--------|-------------|
716
+ | `mandates.create(data)` | Draft a mandate from a direct user interaction |
717
+ | `mandates.list(params?)` | List mandates (filter by customer/signer/status) |
718
+ | `mandates.get(id)` | Get mandate by ID (full wire shape for signing) |
719
+ | `mandates.approve(id, data)` | Activate with a customer signature |
720
+ | `mandates.cancel(id, data)` | Cancel a mandate |
721
+ | `mandates.amend(id, data)` | Append a signed NEW version of the rule (keeps window spend) |
722
+ | `mandates.listVersions(id)` | Append-only version history, oldest first |
723
+ | `mandates.getBudget(id)` | Remaining budget: spent, earmarked, left (advisory) |
724
+
725
+ ### Instructions (Alpha)
726
+
727
+ Accept and inspect actuated proposals.
728
+
729
+ | Method | Description |
730
+ |--------|-------------|
731
+ | `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
732
+ | `instructions.get(id)` | Get an instruction + its downstream artifacts |
733
+
734
+ ### Scheduled Payments (Alpha)
735
+
736
+ Schedule rows created from instructions (or directly).
737
+
738
+ | Method | Description |
739
+ |--------|-------------|
740
+ | `scheduledPayments.create(data)` | Create a schedule directly (signer-first) |
741
+ | `scheduledPayments.list(params?)` | List scheduled payments |
742
+ | `scheduledPayments.get(id)` | Get scheduled payment by ID |
743
+ | `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
744
+
745
+ ### Insights (Alpha)
746
+
747
+ Read-only advisory reporting over a customer's agentic activity.
748
+
749
+ | Method | Description |
750
+ |--------|-------------|
751
+ | `insights.get(customerId)` | Deterministic account insight report |
752
+ | `insights.chat(customerId, data)` | Stateless advisory chat over the report |
753
+
601
754
  ---
602
755
 
603
756
  ## Webhook Event Types