@dakota-xyz/ts-sdk 2.2.1 → 3.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 CHANGED
@@ -229,12 +229,6 @@ await client.mandates.approve(mandate.id!, {
229
229
  ```typescript
230
230
  // Deterministic report: balances, upcoming payments, mandate headroom, risks.
231
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
232
  ```
239
233
 
240
234
  The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
@@ -301,7 +295,10 @@ const firstCustomer = await client.customers.list().first();
301
295
  // With filters
302
296
  const activeCustomers = client.customers.list({ kyb_status: 'active' });
303
297
 
304
- // Iterate transactions with filters
298
+ // Iterate transactions with filters. The SDK always names the transaction
299
+ // family on the wire, so this is that customer's ONE-OFF transactions — a
300
+ // raw GET /transactions?customer_id=... would infer the auto_account family
301
+ // and return those instead.
305
302
  const completedTxs = client.transactions.list({
306
303
  customer_id: customerId,
307
304
  status: 'completed',
@@ -324,6 +321,18 @@ try {
324
321
  if (error.retryable) {
325
322
  // Safe to retry (429, 503, etc.)
326
323
  }
324
+
325
+ // Showing the error to a PERSON? `message` names request fields and
326
+ // actions so a machine caller can self-correct. `userMessage` says the
327
+ // same thing without API vocabulary, when the problem carries one.
328
+ showToCustomer(error.userMessage ?? error.message);
329
+
330
+ // Some problems carry a link that CLEARS them — today `terms-not-accepted`
331
+ // points at the hosted flow where the agreement can be signed. It is
332
+ // token-gated and usable as-is.
333
+ if (error.resolutionUrl) {
334
+ offerLink(error.resolutionUrl);
335
+ }
327
336
  }
328
337
 
329
338
  if (error instanceof TransportError) {
@@ -408,7 +417,6 @@ agentic endpoints that call a model default to **180s** instead:
408
417
  |---|---|
409
418
  | Everything else | 15s |
410
419
  | `paymentAgents.createProposals` / `AgentConversation.send` | 180s |
411
- | `insights.chat` | 180s |
412
420
 
413
421
  A drafting turn is a sequence of model calls — read the payees, check
414
422
  balances, draft, revise — so "pay these nine vendors every Friday"
@@ -531,6 +539,7 @@ Manage customer entities representing businesses and organizations.
531
539
  |--------|-------------|
532
540
  | `customers.create(data)` | Create a customer (triggers KYB) |
533
541
  | `customers.list(params?)` | List all customers (paginated) |
542
+ | `customers.listPage(params?)` | One page + `status_counts` for a status header |
534
543
  | `customers.get(id)` | Get customer by ID |
535
544
  | `customers.delete(id)` | Soft-delete a customer (blocked if it has accounts) |
536
545
  | `customers.getCapabilities(id)` | Capabilities + outstanding requirements to unlock each |
@@ -540,6 +549,25 @@ Manage customer entities representing businesses and organizations.
540
549
  | `customers.listPersonaImportJobs(params?)` | List Persona import jobs, newest first |
541
550
  | `customers.getPersonaImportJob(jobId, params?)` | Job status + per-token results |
542
551
 
552
+ `Customer.status` is the single client-facing status — one value collapsing the
553
+ frozen state, the application decision, and the application lifecycle. Filter on
554
+ it with `status`, which takes a **comma-separated string**, not an array:
555
+
556
+ ```typescript
557
+ const needsAttention = client.customers.list({ status: 'info_requested,frozen' });
558
+
559
+ // `list()` iterates rows and drops the envelope, so the per-status counts a
560
+ // dashboard header renders come from `listPage()` instead. They are computed
561
+ // ignoring the `status` selection, so every chip keeps its count while one of
562
+ // them is the active filter.
563
+ const page = await client.customers.listPage({ limit: 25 });
564
+ console.log(page.status_counts?.info_requested ?? 0);
565
+ ```
566
+
567
+ `kyb_statuses`, `kyc_statuses` and `application_statuses` take the same
568
+ comma-separated form, and `sort_by` / `sort_dir` / `created_at_from` /
569
+ `created_at_to` are also accepted.
570
+
543
571
  ### Recipients
544
572
 
545
573
  Manage recipient entities for payouts and transfers.
@@ -578,10 +606,25 @@ Create and manage one-off transactions.
578
606
  | Method | Description |
579
607
  |--------|-------------|
580
608
  | `transactions.create(data)` | Create one-off transaction |
581
- | `transactions.list(params?)` | List transactions |
609
+ | `transactions.list(params?)` | List transactions (see the family table below) |
582
610
  | `transactions.get(id)` | Get transaction by ID |
583
611
  | `transactions.cancel(id)` | Cancel pending transaction |
584
612
 
613
+ `GET /transactions` serves three resource families from one path, and the
614
+ family decides the row shape. `list()` names the family on the wire and types
615
+ its rows to match:
616
+
617
+ | `transaction_type` | Yields | Notes |
618
+ |--------------------|--------|-------|
619
+ | omitted or `'one_off'` | `OneOffTransaction` | The default |
620
+ | `'wallet'` | `WalletTransaction` | Required for the `wallet_id` / `direction` filters |
621
+ | `'auto_account'` | `AutoTransaction` | Requires `customer_id` |
622
+
623
+ Left to the server the family is **inferred** from the other filters, and
624
+ `customer_id` on its own infers `auto_account` — so name it, or let the SDK
625
+ name `one_off` for you. If a response reports a family other than the one
626
+ requested, the iterator throws rather than yielding rows of the wrong shape.
627
+
585
628
  ### Auto Transactions
586
629
 
587
630
  View automated transaction configurations.
@@ -713,6 +756,64 @@ Query platform capabilities.
713
756
  | `info.getCountries()` | Get supported countries |
714
757
  | `info.getNetworks()` | Get supported networks |
715
758
 
759
+ ### Legal Documents
760
+
761
+ The published terms a customer accepts during onboarding. **Unauthenticated** —
762
+ integrators need these before a customer relationship exists, so both calls are
763
+ safe from a signup page.
764
+
765
+ | Method | Description |
766
+ |--------|-------------|
767
+ | `legal.list()` | The in-force revision of every document, WITHOUT the text |
768
+ | `legal.get(key, version?)` | One document's text — the in-force revision, or a specific one |
769
+
770
+ ```typescript
771
+ const tos = await client.legal.get('dakota_tos');
772
+ render(tos.content);
773
+
774
+ // Record what the customer actually saw, not whichever revision was current
775
+ // when the request landed.
776
+ await client.applications.submitAttestation(applicationId, {
777
+ attestation_type: 'terms_of_service',
778
+ legal_document_version: tos.version,
779
+ // ...
780
+ });
781
+ ```
782
+
783
+ A revision is immutable, so a fetched `(key, version)` can be cached forever.
784
+ `legal.list()` is not: it names whichever revision is in force *now*.
785
+
786
+ To render an acceptance page, `applications.getLegalAcceptance(applicationId)`
787
+ returns just what that page needs — the agreements still owed and the people
788
+ permitted to accept them — instead of the full KYB record `applications.get()`
789
+ would return. The link that reaches it is emailed, so its token is scoped to
790
+ this call and the attestation submission.
791
+
792
+ ### RD Marketing Fee
793
+
794
+ Reserve-management statements for the calling client. The client comes from the
795
+ session, so there is no id to pass.
796
+
797
+ | Method | Description |
798
+ |--------|-------------|
799
+ | `rdMarketingFee.listMonths()` | The months with a statement, newest first |
800
+ | `rdMarketingFee.getStatement(month)` | One month, one row per calendar day |
801
+
802
+ ```typescript
803
+ const months = await client.rdMarketingFee.listMonths();
804
+ const statement = await client.rdMarketingFee.getStatement(months[0]);
805
+
806
+ for (const day of statement.daily) {
807
+ // Absent is not zero: absent means the day is not derived yet, '0' means
808
+ // the client genuinely held no RD. Do not render them alike.
809
+ console.log(day.date, day.balance_minor ?? 'not yet derived');
810
+ }
811
+ ```
812
+
813
+ A client with no contract gets a **404**; an empty month list means the
814
+ contract is real but starts later. The running month is included, with its fee
815
+ figures absent rather than zero.
816
+
716
817
  ### Sandbox
717
818
 
718
819
  Test simulations (sandbox environment only).
@@ -777,9 +878,33 @@ await client.agenticPolicy.set({
777
878
  ```
778
879
 
779
880
  It is a **full replace, not a merge** — an omitted field means you no longer
780
- want it. You can also pass `clientPolicy` per conversation, but that is a
781
- development override: forgetting it fails *silently*, and the agent quietly
782
- goes back to saying "destination" and "mandate".
881
+ want it.
882
+
883
+ Your developer fee is separate, and belongs in **both** places:
884
+
885
+ ```typescript
886
+ // The drafting turn — this is what lets the agent MENTION the fee.
887
+ const conv = client.newAgentConversation(agentId, {
888
+ developerFee: { swap_bps: 50, offramp_bps: 25 },
889
+ });
890
+
891
+ // The accept — this is what CHARGES it.
892
+ await client.instructions.create({
893
+ payment_agent_id: agentId,
894
+ proposals: turn.proposals,
895
+ developer_fee: { swap_bps: 50, offramp_bps: 25 },
896
+ });
897
+ ```
898
+
899
+ Declare it only on the accept and the customer approves a summary that never
900
+ disclosed a fee, then gets charged it.
901
+
902
+ Registering is the **only** way to set a policy. It belongs to the client, not
903
+ to a request, so a drafting turn and the accept that follows it cannot be
904
+ judged by different rules. The per-conversation `clientPolicy` option is gone:
905
+ the platform stopped reading `client_policy` from request bodies, and
906
+ one sent there is ignored — the agent quietly goes back to saying "destination"
907
+ and "mandate" with nothing reporting the fallback.
783
908
 
784
909
  ### Mandates (Alpha)
785
910
 
@@ -823,7 +948,6 @@ Read-only advisory reporting over a customer's agentic activity.
823
948
  | Method | Description |
824
949
  |--------|-------------|
825
950
  | `insights.get(customerId)` | Deterministic account insight report |
826
- | `insights.chat(customerId, data)` | Stateless advisory chat over the report |
827
951
 
828
952
  ---
829
953