@dakota-xyz/ts-sdk 3.0.0 → 3.2.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 +140 -32
- package/dist/index.d.mts +4510 -1042
- package/dist/index.d.ts +4510 -1042
- package/dist/index.js +196 -26
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +196 -26
- package/dist/index.mjs.map +1 -1
- package/dist/webhook/index.d.mts +176 -1
- package/dist/webhook/index.d.ts +176 -1
- package/dist/webhook/index.js +7 -0
- package/dist/webhook/index.js.map +1 -1
- package/dist/webhook/index.mjs +7 -0
- package/dist/webhook/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -169,9 +169,13 @@ console.log(`Send ${tx.send_amount} USDC to: ${tx.crypto_address}`);
|
|
|
169
169
|
console.log(`Status: ${tx.status}`);
|
|
170
170
|
```
|
|
171
171
|
|
|
172
|
-
|
|
172
|
+
A one-off also takes `developer_fee_fixed` (a decimal string in units of the
|
|
173
|
+
asset deposited). The depositor must then send the destination amount plus
|
|
174
|
+
the fee, and a deposit that does not cover it is not converted.
|
|
173
175
|
|
|
174
|
-
|
|
176
|
+
## Agentic Payments (Beta)
|
|
177
|
+
|
|
178
|
+
> ⚠️ **Beta.** The hosted payment-agent surface is `x-beta` 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
179
|
|
|
176
180
|
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
181
|
|
|
@@ -229,6 +233,10 @@ await client.mandates.approve(mandate.id!, {
|
|
|
229
233
|
```typescript
|
|
230
234
|
// Deterministic report: balances, upcoming payments, mandate headroom, risks.
|
|
231
235
|
const report = await client.insights.get(customerId);
|
|
236
|
+
|
|
237
|
+
// The same, over your WHOLE book: portfolio KPIs with trend deltas, daily
|
|
238
|
+
// series for charts, and a per-customer roll-up sorted worst-first.
|
|
239
|
+
const portfolio = await client.insights.getClientReport({ severity: 'critical,warn' });
|
|
232
240
|
```
|
|
233
241
|
|
|
234
242
|
The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
|
|
@@ -544,6 +552,7 @@ Manage customer entities representing businesses and organizations.
|
|
|
544
552
|
| `customers.delete(id)` | Soft-delete a customer (blocked if it has accounts) |
|
|
545
553
|
| `customers.getCapabilities(id)` | Capabilities + outstanding requirements to unlock each |
|
|
546
554
|
| `customers.reEngage(id)` | Mint a fresh application link for an approved customer |
|
|
555
|
+
| `customers.withdrawApplication(id, applicationId, data?)` | Withdraw an undecided onboarding application (final) |
|
|
547
556
|
| `customers.bulkImportFromSumsubTokens(data)` | Import from Sumsub share tokens (synchronous) |
|
|
548
557
|
| `customers.importPersonaTokens(data)` | Import from Persona Connect share tokens (async job) |
|
|
549
558
|
| `customers.listPersonaImportJobs(params?)` | List Persona import jobs, newest first |
|
|
@@ -568,6 +577,20 @@ console.log(page.status_counts?.info_requested ?? 0);
|
|
|
568
577
|
comma-separated form, and `sort_by` / `sort_dir` / `created_at_from` /
|
|
569
578
|
`created_at_to` are also accepted.
|
|
570
579
|
|
|
580
|
+
When a customer will not or cannot continue onboarding — after a request for
|
|
581
|
+
information they chose not to answer, say — withdraw the application rather
|
|
582
|
+
than leaving it open:
|
|
583
|
+
|
|
584
|
+
```typescript
|
|
585
|
+
await client.customers.withdrawApplication(customerId, applicationId, {
|
|
586
|
+
reason: 'Customer opted not to proceed',
|
|
587
|
+
});
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
Withdrawal is **final**: the customer's `status` becomes `withdrawn`, and
|
|
591
|
+
onboarding them again needs a new application. An application that already has
|
|
592
|
+
a decision answers **409**. The platform emits `customer.application.withdrawn`.
|
|
593
|
+
|
|
571
594
|
### Recipients
|
|
572
595
|
|
|
573
596
|
Manage recipient entities for payouts and transfers.
|
|
@@ -597,7 +620,17 @@ Manage on-ramp, off-ramp, and swap accounts.
|
|
|
597
620
|
| `accounts.create(data)` | Create account (onramp/offramp/swap) |
|
|
598
621
|
| `accounts.list(params?)` | List accounts |
|
|
599
622
|
| `accounts.get(id)` | Get account by ID |
|
|
600
|
-
| `accounts.update(id, data)` | Update account |
|
|
623
|
+
| `accounts.update(id, data)` | Update account (developer fee only) |
|
|
624
|
+
|
|
625
|
+
A developer fee is either `developer_fee_bps` or `developer_fee_fixed`. The
|
|
626
|
+
platform returns a 400 if a request carries both keys, even with
|
|
627
|
+
`developer_fee_bps: 0`, so leave out the one you are not using. On update,
|
|
628
|
+
setting one replaces the other. `developer_fee_fixed` is a decimal **string**
|
|
629
|
+
such as `'10.00'`, in units of the asset deposited (at most 2 decimals,
|
|
630
|
+
greater than 0). Fixed-fee accounts return `developer_fee_fixed` and
|
|
631
|
+
`minimum_deposit` (the fee plus 0.01); both are omitted otherwise. Some
|
|
632
|
+
routes do not support a fixed fee, and the platform answers those with a 400
|
|
633
|
+
that asks for `developer_fee_bps` instead.
|
|
601
634
|
|
|
602
635
|
### Transactions
|
|
603
636
|
|
|
@@ -798,6 +831,8 @@ session, so there is no id to pass.
|
|
|
798
831
|
|--------|-------------|
|
|
799
832
|
| `rdMarketingFee.listMonths()` | The months with a statement, newest first |
|
|
800
833
|
| `rdMarketingFee.getStatement(month)` | One month, one row per calendar day |
|
|
834
|
+
| `rdMarketingFee.getPayoutDestination()` | The wallet the fee is paid to (404 = none yet) |
|
|
835
|
+
| `rdMarketingFee.setPayoutDestination(data)` | Register or replace it — an EVM address on Base |
|
|
801
836
|
|
|
802
837
|
```typescript
|
|
803
838
|
const months = await client.rdMarketingFee.listMonths();
|
|
@@ -814,18 +849,44 @@ A client with no contract gets a **404**; an empty month list means the
|
|
|
814
849
|
contract is real but starts later. The running month is included, with its fee
|
|
815
850
|
figures absent rather than zero.
|
|
816
851
|
|
|
852
|
+
Each statement carries both rates: `y_bps_annual` is the contract rate as the
|
|
853
|
+
Order Form quotes it, and `y_bps_monthly` is what THIS month was charged at
|
|
854
|
+
(annual × days in month / 365, to 2 decimal places), so a client can check the
|
|
855
|
+
month against the rate they signed.
|
|
856
|
+
|
|
857
|
+
The fee is paid to a wallet you register separately from your developer-fee
|
|
858
|
+
destination — RD exists only on Base, so only the address is a parameter:
|
|
859
|
+
|
|
860
|
+
```typescript
|
|
861
|
+
const dest = await client.rdMarketingFee.setPayoutDestination({
|
|
862
|
+
address: '0x1234567890123456789012345678901234567890',
|
|
863
|
+
});
|
|
864
|
+
console.log(dest.chain); // always 'eip155:8453'
|
|
865
|
+
```
|
|
866
|
+
|
|
867
|
+
`getPayoutDestination()` answers **404** while nothing is registered — the
|
|
868
|
+
ordinary state for a new client, not an error — and **403** when the client is
|
|
869
|
+
not in the programme. A change emits `rd_payout_destination.updated`.
|
|
870
|
+
|
|
817
871
|
### Sandbox
|
|
818
872
|
|
|
819
873
|
Test simulations (sandbox environment only).
|
|
820
874
|
|
|
821
875
|
| Method | Description |
|
|
822
876
|
|--------|-------------|
|
|
823
|
-
| `sandbox.simulateInbound(data)` | Simulate
|
|
877
|
+
| `sandbox.simulateInbound(data)` | Simulate a deposit, an outbound settlement/return, or a reversal |
|
|
824
878
|
| `sandbox.simulateOnboarding(data)` | Simulate KYB completion |
|
|
825
879
|
| `sandbox.getSimulation(id)` | Get simulation by ID |
|
|
826
880
|
| `sandbox.advanceSimulation(id)` | Advance simulation state |
|
|
827
881
|
| `sandbox.listScenarios(params?)` | List available scenarios |
|
|
828
882
|
|
|
883
|
+
`simulateInbound` covers every fiat rail — `ach_*`, `fedwire_*`, `swift_*`,
|
|
884
|
+
`fednow_inbound` — plus `crypto_inbound`. Inbound types take the receiving
|
|
885
|
+
`account_id`; outbound and reversal types take the funding offramp `account_id`
|
|
886
|
+
AND the `one_off_transaction_id`. A SWIFT deposit is chosen by the ACCOUNT, not
|
|
887
|
+
the type: `swift_inbound` and `fedwire_inbound` both book as SWIFT against a
|
|
888
|
+
SWIFT onramp account and as Fedwire against a domestic one.
|
|
889
|
+
|
|
829
890
|
### Fee Payout Destination
|
|
830
891
|
|
|
831
892
|
Where Dakota pays your accrued developer fees. Exactly one per organization,
|
|
@@ -846,9 +907,9 @@ await client.feePayoutDestination.set({
|
|
|
846
907
|
});
|
|
847
908
|
```
|
|
848
909
|
|
|
849
|
-
### Payment Agents (
|
|
910
|
+
### Payment Agents (Beta)
|
|
850
911
|
|
|
851
|
-
Hosted signing agents that draft payments (`x-
|
|
912
|
+
Hosted signing agents that draft payments (`x-beta`, flag-gated).
|
|
852
913
|
|
|
853
914
|
| Method | Description |
|
|
854
915
|
|--------|-------------|
|
|
@@ -858,7 +919,7 @@ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
|
|
|
858
919
|
| `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
|
|
859
920
|
| `paymentAgents.getProposalsProgress(id)` | Live progress of an in-flight drafting turn (advisory) |
|
|
860
921
|
|
|
861
|
-
### Agentic Policy (
|
|
922
|
+
### Agentic Policy (Beta)
|
|
862
923
|
|
|
863
924
|
How your product speaks, and what the agent may propose for it. Register it
|
|
864
925
|
once and every drafting turn narrates in your nouns instead of the platform's.
|
|
@@ -885,20 +946,41 @@ Your developer fee is separate, and belongs in **both** places:
|
|
|
885
946
|
```typescript
|
|
886
947
|
// The drafting turn — this is what lets the agent MENTION the fee.
|
|
887
948
|
const conv = client.newAgentConversation(agentId, {
|
|
888
|
-
|
|
949
|
+
developerFeeDefaults: {
|
|
950
|
+
swap: { developer_fee_bps: 50 },
|
|
951
|
+
offramp: { developer_fee_bps: 25 },
|
|
952
|
+
},
|
|
889
953
|
});
|
|
890
954
|
|
|
891
955
|
// The accept — this is what CHARGES it.
|
|
892
956
|
await client.instructions.create({
|
|
893
957
|
payment_agent_id: agentId,
|
|
894
958
|
proposals: turn.proposals,
|
|
895
|
-
|
|
959
|
+
developer_fee_defaults: {
|
|
960
|
+
swap: { developer_fee_bps: 50 },
|
|
961
|
+
offramp: { developer_fee_bps: 25 },
|
|
962
|
+
},
|
|
896
963
|
});
|
|
897
964
|
```
|
|
898
965
|
|
|
899
966
|
Declare it only on the accept and the customer approves a summary that never
|
|
900
967
|
disclosed a fee, then gets charged it.
|
|
901
968
|
|
|
969
|
+
Each payout type takes a percentage (`developer_fee_bps`) **or** a flat amount
|
|
970
|
+
per payment (`developer_fee_fixed`), never both. The fixed fee is a decimal
|
|
971
|
+
string in units of the asset deposited, and it is added on top of the payment,
|
|
972
|
+
so the payee receives exactly the amount named: a 100.00 USDC payment with
|
|
973
|
+
`{ developer_fee_fixed: '10.00' }` leaves the wallet as 110.00 USDC, and the
|
|
974
|
+
spending limit applies to that 110.00. The `create_auto_account` action takes
|
|
975
|
+
either one too, as an override of the defaults.
|
|
976
|
+
|
|
977
|
+
```typescript
|
|
978
|
+
const defaults: DeveloperFeeDefaults = {
|
|
979
|
+
swap: { developer_fee_fixed: '10.00' }, // 10.00 USDC on a USDC payment
|
|
980
|
+
offramp: { developer_fee_bps: 25 },
|
|
981
|
+
};
|
|
982
|
+
```
|
|
983
|
+
|
|
902
984
|
Registering is the **only** way to set a policy. It belongs to the client, not
|
|
903
985
|
to a request, so a drafting turn and the accept that follows it cannot be
|
|
904
986
|
judged by different rules. The per-conversation `clientPolicy` option is gone:
|
|
@@ -906,7 +988,7 @@ the platform stopped reading `client_policy` from request bodies, and
|
|
|
906
988
|
one sent there is ignored — the agent quietly goes back to saying "destination"
|
|
907
989
|
and "mandate" with nothing reporting the fallback.
|
|
908
990
|
|
|
909
|
-
### Mandates (
|
|
991
|
+
### Mandates (Beta)
|
|
910
992
|
|
|
911
993
|
The §8 authorizations that arm scheduled payments.
|
|
912
994
|
|
|
@@ -921,7 +1003,7 @@ The §8 authorizations that arm scheduled payments.
|
|
|
921
1003
|
| `mandates.listVersions(id)` | Append-only version history, oldest first |
|
|
922
1004
|
| `mandates.getBudget(id)` | Remaining budget: spent, earmarked, left (advisory) |
|
|
923
1005
|
|
|
924
|
-
### Instructions (
|
|
1006
|
+
### Instructions (Beta)
|
|
925
1007
|
|
|
926
1008
|
Accept and inspect actuated proposals.
|
|
927
1009
|
|
|
@@ -930,7 +1012,7 @@ Accept and inspect actuated proposals.
|
|
|
930
1012
|
| `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
|
|
931
1013
|
| `instructions.get(id)` | Get an instruction + its downstream artifacts |
|
|
932
1014
|
|
|
933
|
-
### Scheduled Payments (
|
|
1015
|
+
### Scheduled Payments (Beta)
|
|
934
1016
|
|
|
935
1017
|
Schedule rows created from instructions (or directly).
|
|
936
1018
|
|
|
@@ -941,38 +1023,64 @@ Schedule rows created from instructions (or directly).
|
|
|
941
1023
|
| `scheduledPayments.get(id)` | Get scheduled payment by ID |
|
|
942
1024
|
| `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
|
|
943
1025
|
|
|
944
|
-
### Insights (
|
|
1026
|
+
### Insights (Beta)
|
|
945
1027
|
|
|
946
1028
|
Read-only advisory reporting over a customer's agentic activity.
|
|
947
1029
|
|
|
948
1030
|
| Method | Description |
|
|
949
1031
|
|--------|-------------|
|
|
950
|
-
| `insights.get(customerId)` | Deterministic account insight report |
|
|
1032
|
+
| `insights.get(customerId)` | Deterministic account insight report for one customer |
|
|
1033
|
+
| `insights.getClientReport(params?)` | The same over the whole book: KPIs, daily series, per-customer roll-up |
|
|
1034
|
+
|
|
1035
|
+
`getClientReport` filters (`customer_id`, `wallet_id`, `kind`, `severity`,
|
|
1036
|
+
`responsibility`, `window_days`) are all optional and only narrow the report;
|
|
1037
|
+
the multi-value ones are comma-separated strings. Items gain `customer_id`
|
|
1038
|
+
(omitted on cross-customer aggregates) and `responsibility` — a grouping label
|
|
1039
|
+
for routing, not ownership. `kind` stays an OPEN set; two kinds are emitted
|
|
1040
|
+
only at this scope today, `volume_anomaly` and `recipient_dormant`. The report
|
|
1041
|
+
scans at most 100 customers per request and says so through
|
|
1042
|
+
`snapshot.customers.scanned < total`.
|
|
951
1043
|
|
|
952
1044
|
---
|
|
953
1045
|
|
|
954
1046
|
## Webhook Event Types
|
|
955
1047
|
|
|
1048
|
+
Every value the platform's `EventType` enum lists — and therefore every value
|
|
1049
|
+
a webhook target can subscribe to — is a member of `WebhookEventType`; a test
|
|
1050
|
+
keeps the two in step on every spec sync. Names not in this table (for
|
|
1051
|
+
example `transaction.completed` or `application.approved`) are never emitted:
|
|
1052
|
+
a transaction's outcome arrives as an `*.updated` event with the new status,
|
|
1053
|
+
and an application decision arrives as `customer.kyb_status.updated`.
|
|
1054
|
+
|
|
956
1055
|
| Event Type | Description |
|
|
957
1056
|
|------------|-------------|
|
|
958
|
-
| `
|
|
959
|
-
| `
|
|
960
|
-
| `customer.
|
|
961
|
-
| `
|
|
962
|
-
| `
|
|
963
|
-
| `
|
|
964
|
-
| `
|
|
965
|
-
| `
|
|
966
|
-
| `
|
|
967
|
-
| `
|
|
968
|
-
| `
|
|
969
|
-
| `transaction.
|
|
970
|
-
| `transaction.
|
|
971
|
-
| `
|
|
972
|
-
| `
|
|
973
|
-
| `
|
|
974
|
-
| `
|
|
975
|
-
| `
|
|
1057
|
+
| `user.created` / `user.updated` / `user.deleted` | Dashboard user lifecycle |
|
|
1058
|
+
| `api_key.created` / `api_key.deleted` | API key lifecycle |
|
|
1059
|
+
| `customer.created` / `customer.updated` | Customer record lifecycle |
|
|
1060
|
+
| `customer.kyb_link.created` / `customer.kyb_link.updated` | Onboarding link issued or changed |
|
|
1061
|
+
| `customer.kyb_status.created` / `customer.kyb_status.updated` | KYB status set or changed (an application decision arrives here) |
|
|
1062
|
+
| `customer.kyb_application.submitted` | The customer submitted their onboarding application |
|
|
1063
|
+
| `customer.capability_status.updated` | A rail's standing changed; payload lists what still gates it |
|
|
1064
|
+
| `customer.rfi.requested` | A reviewer needs more information; payload lists what is owed (never the link) |
|
|
1065
|
+
| `customer.rfi.responded` | The information arrived; the application is back in review |
|
|
1066
|
+
| `customer.application.withdrawn` | The onboarding application was withdrawn (terminal) |
|
|
1067
|
+
| `auto_account.created` / `auto_account.updated` / `auto_account.deleted` | On-ramp / off-ramp account lifecycle |
|
|
1068
|
+
| `transaction.auto.created` / `transaction.auto.updated` | Auto (account-driven) transaction created or changed status |
|
|
1069
|
+
| `transaction.one_off.created` / `transaction.one_off.updated` | One-off transaction created or changed status |
|
|
1070
|
+
| `recipient.created` / `recipient.updated` / `recipient.deleted` | Recipient lifecycle |
|
|
1071
|
+
| `destination.created` / `destination.deleted` | Destination lifecycle |
|
|
1072
|
+
| `target.created` / `target.updated` / `target.deleted` | Webhook target lifecycle |
|
|
1073
|
+
| `exception.created` / `exception.cleared` | A compliance or operational exception raised or cleared |
|
|
1074
|
+
| `wallet.created` / `wallet.updated` | Wallet lifecycle |
|
|
1075
|
+
| `wallet.signer_group.created` / `wallet.signer_group.updated` | Signer group attached to a wallet, or changed |
|
|
1076
|
+
| `wallet.policy.created` / `wallet.policy.updated` | Wallet policy attached, or changed |
|
|
1077
|
+
| `wallet.transaction.created` / `wallet.transaction.updated` | Wallet transaction created or changed status |
|
|
1078
|
+
| `wallet.deposit` | A deposit landed in a wallet |
|
|
1079
|
+
| `rd_payout_destination.updated` | The RD marketing-fee wallet was set or replaced |
|
|
1080
|
+
| `fee_payout_destination.updated` / `fee_payout_destination.deleted` | Developer-fee payout destination set, replaced, or removed |
|
|
1081
|
+
| `scheduled_payment.failed` | A scheduled payment reached the failed terminal state |
|
|
1082
|
+
| `deposit.held` | A deposit Dakota could not process was held (can repeat per `deposit_id`) |
|
|
1083
|
+
| `deposit.returned` | A held deposit's funds are back with the sender |
|
|
976
1084
|
|
|
977
1085
|
---
|
|
978
1086
|
|