@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 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
- ## Agentic Payments (Alpha)
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
- > ⚠️ **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.
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 inbound deposit |
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 (Alpha)
910
+ ### Payment Agents (Beta)
850
911
 
851
- Hosted signing agents that draft payments (`x-alpha`, flag-gated).
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 (Alpha)
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
- developerFee: { swap_bps: 50, offramp_bps: 25 },
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
- developer_fee: { swap_bps: 50, offramp_bps: 25 },
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 (Alpha)
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 (Alpha)
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 (Alpha)
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 (Alpha)
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
- | `customer.created` | Customer was created |
959
- | `customer.updated` | Customer was updated |
960
- | `customer.kyb_status_changed` | KYB status changed |
961
- | `recipient.created` | Recipient was created |
962
- | `recipient.updated` | Recipient was updated |
963
- | `destination.created` | Destination was created |
964
- | `account.created` | Account was created |
965
- | `account.updated` | Account was updated |
966
- | `transaction.created` | Transaction was created |
967
- | `transaction.updated` | Transaction was updated |
968
- | `transaction.completed` | Transaction completed |
969
- | `transaction.failed` | Transaction failed |
970
- | `transaction.cancelled` | Transaction was cancelled |
971
- | `wallet.created` | Wallet was created |
972
- | `application.created` | Application was created |
973
- | `application.submitted` | Application was submitted |
974
- | `application.approved` | Application was approved |
975
- | `application.rejected` | Application was rejected |
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