@dakota-xyz/ts-sdk 1.4.0 → 2.0.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 +122 -0
- package/dist/index.d.mts +1352 -46
- package/dist/index.d.ts +1352 -46
- package/dist/index.js +840 -31
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +821 -32
- 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:
|
|
@@ -598,6 +668,58 @@ Test simulations (sandbox environment only).
|
|
|
598
668
|
| `sandbox.advanceSimulation(id)` | Advance simulation state |
|
|
599
669
|
| `sandbox.listScenarios(params?)` | List available scenarios |
|
|
600
670
|
|
|
671
|
+
### Payment Agents (Alpha)
|
|
672
|
+
|
|
673
|
+
Hosted signing agents that draft payments (`x-alpha`, flag-gated).
|
|
674
|
+
|
|
675
|
+
| Method | Description |
|
|
676
|
+
|--------|-------------|
|
|
677
|
+
| `paymentAgents.create(data)` | Create a payment agent (hosted or key-supplied) |
|
|
678
|
+
| `paymentAgents.get(id)` | Get payment agent by ID |
|
|
679
|
+
| `paymentAgents.revoke(id)` | Revoke the agent's key (kill switch) |
|
|
680
|
+
| `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
|
|
681
|
+
|
|
682
|
+
### Mandates (Alpha)
|
|
683
|
+
|
|
684
|
+
The §8 authorizations that arm scheduled payments.
|
|
685
|
+
|
|
686
|
+
| Method | Description |
|
|
687
|
+
|--------|-------------|
|
|
688
|
+
| `mandates.create(data)` | Draft a mandate from a direct user interaction |
|
|
689
|
+
| `mandates.list(params?)` | List mandates (filter by customer/signer/status) |
|
|
690
|
+
| `mandates.get(id)` | Get mandate by ID (full wire shape for signing) |
|
|
691
|
+
| `mandates.approve(id, data)` | Activate with a customer signature |
|
|
692
|
+
| `mandates.cancel(id, data)` | Cancel a mandate |
|
|
693
|
+
|
|
694
|
+
### Instructions (Alpha)
|
|
695
|
+
|
|
696
|
+
Accept and inspect actuated proposals.
|
|
697
|
+
|
|
698
|
+
| Method | Description |
|
|
699
|
+
|--------|-------------|
|
|
700
|
+
| `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
|
|
701
|
+
| `instructions.get(id)` | Get an instruction + its downstream artifacts |
|
|
702
|
+
|
|
703
|
+
### Scheduled Payments (Alpha)
|
|
704
|
+
|
|
705
|
+
Schedule rows created from instructions (or directly).
|
|
706
|
+
|
|
707
|
+
| Method | Description |
|
|
708
|
+
|--------|-------------|
|
|
709
|
+
| `scheduledPayments.create(data)` | Create a schedule directly (signer-first) |
|
|
710
|
+
| `scheduledPayments.list(params?)` | List scheduled payments |
|
|
711
|
+
| `scheduledPayments.get(id)` | Get scheduled payment by ID |
|
|
712
|
+
| `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
|
|
713
|
+
|
|
714
|
+
### Insights (Alpha)
|
|
715
|
+
|
|
716
|
+
Read-only advisory reporting over a customer's agentic activity.
|
|
717
|
+
|
|
718
|
+
| Method | Description |
|
|
719
|
+
|--------|-------------|
|
|
720
|
+
| `insights.get(customerId)` | Deterministic account insight report |
|
|
721
|
+
| `insights.chat(customerId, data)` | Stateless advisory chat over the report |
|
|
722
|
+
|
|
601
723
|
---
|
|
602
724
|
|
|
603
725
|
## Webhook Event Types
|