@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 +155 -2
- package/dist/index.d.mts +20389 -346
- package/dist/index.d.ts +20389 -346
- package/dist/index.js +1182 -10
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1161 -11
- package/dist/index.mjs.map +1 -1
- package/dist/webhook/index.d.mts +141 -7
- package/dist/webhook/index.d.ts +141 -7
- package/dist/webhook/index.js +9 -2
- package/dist/webhook/index.js.map +1 -1
- package/dist/webhook/index.mjs +9 -2
- package/dist/webhook/index.mjs.map +1 -1
- package/package.json +5 -1
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
|