@dakota-xyz/ts-sdk 2.2.1 → 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/dist/index.js CHANGED
@@ -39,6 +39,26 @@ var APIError = class _APIError extends Error {
39
39
  rawBody;
40
40
  /** Whether this error is safe to retry */
41
41
  retryable;
42
+ /**
43
+ * A plain-language rendition of the problem, written for the END CUSTOMER,
44
+ * when one exists for this error.
45
+ *
46
+ * `message` names request fields and actions so a machine caller can
47
+ * self-correct. This says the same thing without API vocabulary. Show it
48
+ * when relaying an error into a human surface (chat, email, UI), and fall
49
+ * back to `message` when it is null.
50
+ */
51
+ userMessage;
52
+ /**
53
+ * A link the customer can follow to CLEAR this error, present only on
54
+ * problems with a concrete self-service remedy.
55
+ *
56
+ * Today `terms-not-accepted` returns one, pointing at the hosted flow where
57
+ * the outstanding agreement can be signed. It is token-gated and usable
58
+ * as-is — send the customer to it rather than parsing one out of the
59
+ * message.
60
+ */
61
+ resolutionUrl;
42
62
  constructor(statusCode, code, message, options) {
43
63
  super(message);
44
64
  this.name = "APIError";
@@ -48,6 +68,8 @@ var APIError = class _APIError extends Error {
48
68
  this.requestId = options?.requestId ?? null;
49
69
  this.rawBody = options?.rawBody ?? null;
50
70
  this.retryable = RETRYABLE_STATUS_CODES.has(statusCode);
71
+ this.userMessage = options?.userMessage ?? null;
72
+ this.resolutionUrl = options?.resolutionUrl ?? null;
51
73
  if (Error.captureStackTrace) {
52
74
  Error.captureStackTrace(this, _APIError);
53
75
  }
@@ -61,6 +83,8 @@ var APIError = class _APIError extends Error {
61
83
  let code = `http_${response.status}`;
62
84
  let message = response.statusText || "Unknown error";
63
85
  let details = null;
86
+ let userMessage = null;
87
+ let resolutionUrl = null;
64
88
  try {
65
89
  rawBody = await response.text();
66
90
  const parsed = JSON.parse(rawBody);
@@ -86,12 +110,20 @@ var APIError = class _APIError extends Error {
86
110
  if (parsed.details && typeof parsed.details === "object") {
87
111
  details = parsed.details;
88
112
  }
113
+ if (typeof parsed.user_message === "string") {
114
+ userMessage = parsed.user_message;
115
+ }
116
+ if (typeof parsed.resolution_url === "string") {
117
+ resolutionUrl = parsed.resolution_url;
118
+ }
89
119
  } catch {
90
120
  }
91
121
  return new _APIError(response.status, code, message, {
92
122
  details,
93
123
  requestId,
94
- rawBody
124
+ rawBody,
125
+ userMessage,
126
+ resolutionUrl
95
127
  });
96
128
  }
97
129
  toString() {
@@ -245,7 +277,7 @@ var Transport = class {
245
277
  * Make an HTTP request with automatic retry and error handling.
246
278
  */
247
279
  async request(options) {
248
- const { method, path, body, query, headers, idempotencyKey, signal } = options;
280
+ const { method, path, body, query, headers, idempotencyKey, signal, noContent } = options;
249
281
  const url = this.buildURL(path, query);
250
282
  const requestHeaders = this.buildHeaders(method, path, headers, idempotencyKey);
251
283
  const requestBody = body !== void 0 ? JSON.stringify(body) : void 0;
@@ -257,7 +289,8 @@ var Transport = class {
257
289
  body: requestBody,
258
290
  signal
259
291
  },
260
- this.resolveTimeout(options)
292
+ this.resolveTimeout(options),
293
+ noContent === true
261
294
  );
262
295
  }
263
296
  /**
@@ -353,7 +386,7 @@ var Transport = class {
353
386
  * deadline, so a request that keeps timing out can take up to
354
387
  * `timeout × maxAttempts` before it throws.
355
388
  */
356
- async executeWithRetry(url, init, timeout) {
389
+ async executeWithRetry(url, init, timeout, noContent = false) {
357
390
  const { maxAttempts, initialBackoffMs, maxBackoffMs } = this.config.retryPolicy;
358
391
  const method = init.method ?? "GET";
359
392
  let lastError;
@@ -374,7 +407,7 @@ var Transport = class {
374
407
  clearTimeout(timeoutId);
375
408
  this.logResponse(method, url, response.status, attempt);
376
409
  if (response.ok) {
377
- if (response.status === 204) {
410
+ if (response.status === 204 || noContent) {
378
411
  return void 0;
379
412
  }
380
413
  return await response.json();
@@ -605,8 +638,12 @@ var BaseResource = class {
605
638
  }
606
639
  /**
607
640
  * Create a paginated iterator for a list endpoint.
641
+ *
642
+ * `inspectMeta` is called with each page's raw `meta` before the page is
643
+ * yielded, for endpoints whose meta says something the caller must act on.
644
+ * Throw from it to fail the page.
608
645
  */
609
- paginate(path, params, cursorExtractor) {
646
+ paginate(path, params, cursorExtractor, inspectMeta) {
610
647
  const fetcher = async (cursor) => {
611
648
  const query = {};
612
649
  if (params) {
@@ -625,8 +662,10 @@ var BaseResource = class {
625
662
  query
626
663
  });
627
664
  if (Array.isArray(response)) {
665
+ inspectMeta?.(void 0);
628
666
  return { data: response, meta: void 0 };
629
667
  }
668
+ inspectMeta?.(response.meta);
630
669
  return {
631
670
  data: response.data ?? [],
632
671
  meta: response.meta
@@ -700,6 +739,11 @@ var CustomersResource = class extends BaseResource {
700
739
  * // With filters
701
740
  * const active = client.customers.list({ kyb_status: 'active' });
702
741
  *
742
+ * // Several statuses at once — one comma-separated string, not an array
743
+ * const needsAttention = client.customers.list({
744
+ * status: 'info_requested,frozen',
745
+ * });
746
+ *
703
747
  * // Collect all to array
704
748
  * const all = await client.customers.list().toArray();
705
749
  * ```
@@ -707,6 +751,38 @@ var CustomersResource = class extends BaseResource {
707
751
  list(params) {
708
752
  return this.paginate("/customers", params);
709
753
  }
754
+ /**
755
+ * One page of customers, with the per-status counts.
756
+ *
757
+ * {@link list} iterates rows and drops the envelope, so `status_counts` —
758
+ * the counts a dashboard's status header renders — is unreachable through
759
+ * it. This returns the raw page instead: same filters, one request, no
760
+ * iteration.
761
+ *
762
+ * The counts are computed under the same filters but IGNORING the `status`
763
+ * selection, so every chip keeps its count while one of them is the active
764
+ * filter.
765
+ *
766
+ * @param params - The same filters {@link list} accepts
767
+ * @returns One page: rows, pagination meta, and `status_counts`
768
+ *
769
+ * @example
770
+ * ```typescript
771
+ * const page = await client.customers.listPage({ limit: 25 });
772
+ * console.log(page.status_counts?.info_requested ?? 0);
773
+ * for (const customer of page.data) {
774
+ * console.log(customer.name, customer.status);
775
+ * }
776
+ * ```
777
+ */
778
+ async listPage(params) {
779
+ const page = await this.transport.request({
780
+ method: "GET",
781
+ path: "/customers",
782
+ query: params
783
+ });
784
+ return { ...page, data: page.data ?? [] };
785
+ }
710
786
  /**
711
787
  * Get a customer by ID.
712
788
  *
@@ -797,6 +873,42 @@ var CustomersResource = class extends BaseResource {
797
873
  timeout: options?.timeout
798
874
  });
799
875
  }
876
+ /**
877
+ * Withdraw a customer's onboarding application.
878
+ *
879
+ * Closes the application when the customer will not or cannot continue —
880
+ * for example after a request for information they chose not to answer.
881
+ *
882
+ * Withdrawal is FINAL. The application and its entities are recorded as
883
+ * withdrawn, the customer's `status` becomes `withdrawn`, and onboarding
884
+ * that customer again requires a new application. An application that
885
+ * already has a decision returns a 409.
886
+ *
887
+ * Emits `customer.application.withdrawn`.
888
+ *
889
+ * @param customerId - Customer ID (KSUID)
890
+ * @param applicationId - The customer's onboarding application ID
891
+ * @param data - Optional `reason`, recorded for audit and shown to reviewers
892
+ * @param options - Request options (e.g., custom idempotency key)
893
+ *
894
+ * @example
895
+ * ```typescript
896
+ * await client.customers.withdrawApplication(customerId, applicationId, {
897
+ * reason: 'Customer opted not to proceed',
898
+ * });
899
+ * ```
900
+ */
901
+ async withdrawApplication(customerId, applicationId, data = {}, options) {
902
+ await this.transport.request({
903
+ method: "POST",
904
+ path: `/customers/${customerId}/applications/${applicationId}/withdraw`,
905
+ body: data,
906
+ idempotencyKey: options?.idempotencyKey,
907
+ timeout: options?.timeout,
908
+ // The platform answers a bare 200 with no body.
909
+ noContent: true
910
+ });
911
+ }
800
912
  /**
801
913
  * Update the sub-client association for a customer.
802
914
  *
@@ -1267,11 +1379,18 @@ var AccountsResource = class extends BaseResource {
1267
1379
  * @param data - Update data
1268
1380
  * @returns Updated account
1269
1381
  *
1382
+ * Only the developer fee can be updated, and setting one kind replaces the
1383
+ * other. `developer_fee_fixed` is a decimal string in units of the asset
1384
+ * deposited (at most 2 decimals, greater than 0); it applies to future
1385
+ * deposits only.
1386
+ *
1270
1387
  * @example
1271
1388
  * ```typescript
1272
1389
  * const account = await client.accounts.update(accountId, {
1273
- * status: 'inactive',
1390
+ * account_type: 'onramp',
1391
+ * developer_fee_fixed: '10.00',
1274
1392
  * });
1393
+ * console.log(account.minimum_deposit); // '10.01'
1275
1394
  * ```
1276
1395
  */
1277
1396
  async update(accountId, data, options) {
@@ -1345,25 +1464,56 @@ var TransactionsResource = class extends BaseResource {
1345
1464
  });
1346
1465
  }
1347
1466
  /**
1348
- * List one-off transactions.
1467
+ * List transactions.
1468
+ *
1469
+ * `GET /transactions` serves three resource families from one path, and the
1470
+ * family decides the row shape — so the family you ask for decides what this
1471
+ * iterator yields:
1472
+ *
1473
+ * | `transaction_type` | Yields |
1474
+ * |--------------------|--------|
1475
+ * | omitted or `'one_off'` | {@link OneOffTransaction} |
1476
+ * | `'wallet'` | {@link WalletTransaction} |
1477
+ * | `'auto_account'` | {@link AutoTransaction} (requires `customer_id`) |
1478
+ *
1479
+ * **The family is always named on the wire.** Left to the server, it is
1480
+ * INFERRED from the other filters, and `customer_id` on its own infers
1481
+ * `auto_account` — so `list({ customer_id })` would return that customer's
1482
+ * auto-account transactions while this method's type promised one-off ones.
1483
+ * Those rows parse into `OneOffTransaction` with missing fields rather than
1484
+ * failing, so nothing surfaced the substitution. Omitting the family here
1485
+ * therefore sends `transaction_type=one_off` rather than leaving it open.
1486
+ *
1487
+ * The family the server reports back (`meta.transaction_type`) is checked
1488
+ * against the one requested, and a mismatch throws instead of yielding rows
1489
+ * of the wrong shape.
1349
1490
  *
1350
1491
  * @param params - Filter and pagination parameters
1351
- * @returns Async iterator of transactions
1492
+ * @returns Async iterator over the requested family
1352
1493
  *
1353
1494
  * @example
1354
1495
  * ```typescript
1355
- * // List all transactions
1496
+ * // One-off transactions (the default family)
1356
1497
  * for await (const tx of client.transactions.list()) {
1357
1498
  * console.log(tx.id, tx.status);
1358
1499
  * }
1359
1500
  *
1360
- * // Filter by customer and status
1501
+ * // This customer's ONE-OFF transactions
1361
1502
  * const completed = client.transactions.list({
1362
1503
  * customer_id: customerId,
1363
1504
  * status: 'completed',
1364
1505
  * });
1365
1506
  *
1366
- * // Wallet-scoped filters (require transaction_type: 'wallet')
1507
+ * // This customer's AUTO-ACCOUNT transactions — a different family,
1508
+ * // and a different row shape
1509
+ * for await (const tx of client.transactions.list({
1510
+ * transaction_type: 'auto_account',
1511
+ * customer_id: customerId,
1512
+ * })) {
1513
+ * console.log(tx.id);
1514
+ * }
1515
+ *
1516
+ * // Wallet transactions
1367
1517
  * const sent = client.transactions.list({
1368
1518
  * transaction_type: 'wallet',
1369
1519
  * wallet_id: walletId,
@@ -1372,7 +1522,13 @@ var TransactionsResource = class extends BaseResource {
1372
1522
  * ```
1373
1523
  */
1374
1524
  list(params) {
1375
- return this.paginate("/transactions", params);
1525
+ const requested = params?.transaction_type ?? "one_off";
1526
+ return this.paginate(
1527
+ "/transactions",
1528
+ { ...params, transaction_type: requested },
1529
+ void 0,
1530
+ (meta) => assertFamily(meta, requested)
1531
+ );
1376
1532
  }
1377
1533
  /**
1378
1534
  * Get a transaction by ID.
@@ -1416,12 +1572,36 @@ var TransactionsResource = class extends BaseResource {
1416
1572
  });
1417
1573
  }
1418
1574
  };
1575
+ function assertFamily(meta, requested) {
1576
+ const served = meta?.transaction_type;
1577
+ if (typeof served !== "string" || served === requested) return;
1578
+ throw new APIError(
1579
+ 200,
1580
+ "transaction_family_mismatch",
1581
+ `Asked for ${requested} transactions but the server listed ${served}. The rows in this page are not the shape this iterator yields, so they are not returned.`,
1582
+ { details: { requested, served } }
1583
+ );
1584
+ }
1419
1585
  var AutoTransactionsResource = class extends BaseResource {
1420
1586
  /**
1421
1587
  * List auto transactions.
1422
1588
  *
1423
- * @param params - Pagination parameters
1589
+ * `statuses` and `types` take a comma-separated string, not an array, and
1590
+ * `start_date` / `end_date` are Unix epoch SECONDS rather than the ISO
1591
+ * strings the other list endpoints take.
1592
+ *
1593
+ * @param params - Filter and pagination parameters
1424
1594
  * @returns Async iterator of auto transactions
1595
+ *
1596
+ * @example
1597
+ * ```typescript
1598
+ * const recent = client.autoTransactions.list({
1599
+ * auto_account_id: accountId,
1600
+ * statuses: 'pending,processing',
1601
+ * start_date: Math.floor(Date.now() / 1000) - 86_400,
1602
+ * sort_dir: 'desc',
1603
+ * });
1604
+ * ```
1425
1605
  */
1426
1606
  list(params) {
1427
1607
  return this.paginate("/auto-transactions", params);
@@ -1635,13 +1815,32 @@ var ApplicationsResource = class extends BaseResource {
1635
1815
  /**
1636
1816
  * Get an application by ID.
1637
1817
  *
1818
+ * `include` inlines extra sections — a comma-separated list of `entities`,
1819
+ * `validation`, `edd`, `attestations`, or `all`. Each adds weight, and
1820
+ * `'all'` carries the full KYB record including every associated
1821
+ * individual's date of birth, nationality and email, so ask for what the
1822
+ * page renders.
1823
+ *
1824
+ * To render an accept-agreements page, use {@link getLegalAcceptance}
1825
+ * instead: it returns exactly that page's inputs and none of the personal
1826
+ * data.
1827
+ *
1638
1828
  * @param applicationId - Application ID
1829
+ * @param params - Optional `{ include }`
1639
1830
  * @returns Application record
1831
+ *
1832
+ * @example
1833
+ * ```typescript
1834
+ * const app = await client.applications.get(applicationId, {
1835
+ * include: 'entities,validation',
1836
+ * });
1837
+ * ```
1640
1838
  */
1641
- async get(applicationId) {
1839
+ async get(applicationId, params) {
1642
1840
  return this.transport.request({
1643
1841
  method: "GET",
1644
- path: `/applications/${applicationId}`
1842
+ path: `/applications/${applicationId}`,
1843
+ query: { ...params }
1645
1844
  });
1646
1845
  }
1647
1846
  /**
@@ -1756,6 +1955,48 @@ var ApplicationsResource = class extends BaseResource {
1756
1955
  // ==========================================================================
1757
1956
  // Attestations
1758
1957
  // ==========================================================================
1958
+ /**
1959
+ * What this application still needs to accept, and who may accept it.
1960
+ *
1961
+ * Exactly what an accept-agreements page renders, and deliberately nothing
1962
+ * more. `get(applicationId)` would answer with the full KYB record — the
1963
+ * business entity, and every associated individual's date of birth,
1964
+ * nationality and email — none of which that page displays. The link that
1965
+ * reaches this endpoint is EMAILED and travels in a URL query string, so its
1966
+ * credential is scoped to this call and the attestation submission, and
1967
+ * cannot read the application.
1968
+ *
1969
+ * Authenticates with an Application Token (`X-Application-Token`), including
1970
+ * the narrow legal-acceptance token a terms refusal issues.
1971
+ *
1972
+ * The documents come back as identity only. Fetch the text to display with
1973
+ * `client.legal.get(key)`, then pass the `version` you displayed back as
1974
+ * `legal_document_version` on {@link submitAttestation}.
1975
+ *
1976
+ * @param applicationId - Application ID
1977
+ * @returns Outstanding agreements, prior acceptances, and permitted attestors
1978
+ *
1979
+ * @example
1980
+ * ```typescript
1981
+ * const ctx = await client.applications.getLegalAcceptance(applicationId);
1982
+ *
1983
+ * for (const doc of ctx.outstanding_documents) {
1984
+ * const text = await client.legal.get(doc.key, doc.version);
1985
+ * render(text.content);
1986
+ * }
1987
+ *
1988
+ * // A business may have several control persons; an individual application
1989
+ * // has exactly one permissible attestor, so there is nobody to pick.
1990
+ * const attestor =
1991
+ * ctx.application_type === 'individual' ? ctx.attestors[0] : await pick(ctx.attestors);
1992
+ * ```
1993
+ */
1994
+ async getLegalAcceptance(applicationId) {
1995
+ return this.transport.request({
1996
+ method: "GET",
1997
+ path: `/applications/${applicationId}/legal-acceptance`
1998
+ });
1999
+ }
1759
2000
  /**
1760
2001
  * Submit an attestation for an application.
1761
2002
  *
@@ -2609,6 +2850,192 @@ var InfoResource = class extends BaseResource {
2609
2850
  }
2610
2851
  };
2611
2852
 
2853
+ // src/client/resources/legal.ts
2854
+ var LegalResource = class extends BaseResource {
2855
+ /**
2856
+ * List the revision of every legal document currently in force.
2857
+ *
2858
+ * An INDEX, not a bundle: each entry names a document and its in-force
2859
+ * revision, without the text. Fetch {@link get} for the one document you
2860
+ * are about to display — inlining every document would put the whole corpus
2861
+ * on every call.
2862
+ *
2863
+ * Not safe to cache indefinitely: it names whichever revision is in force
2864
+ * NOW, and that changes when a new one is published. A specific
2865
+ * `(key, version)` from {@link get} is a different matter — revisions are
2866
+ * immutable, so that text can be cached for as long as you like.
2867
+ *
2868
+ * @returns The in-force revision of each document, without its text
2869
+ *
2870
+ * @example
2871
+ * ```typescript
2872
+ * for (const doc of await client.legal.list()) {
2873
+ * console.log(doc.key, doc.version, doc.title);
2874
+ * }
2875
+ * ```
2876
+ */
2877
+ async list() {
2878
+ const response = await this.transport.request({
2879
+ method: "GET",
2880
+ path: "/legal/documents"
2881
+ });
2882
+ return response.data ?? [];
2883
+ }
2884
+ /**
2885
+ * Get one legal document — the revision in force, or a specific one.
2886
+ *
2887
+ * Pass the `version` you displayed back as `legal_document_version` when
2888
+ * submitting an attestation, so the acceptance record names the exact text
2889
+ * the customer saw rather than whichever revision happened to be current
2890
+ * when the request arrived.
2891
+ *
2892
+ * @param documentKey - Document identifier, e.g. `'dakota_tos'`
2893
+ * @param version - A specific published revision. Omit for the one in force
2894
+ * @returns The requested revision, including its text
2895
+ *
2896
+ * @example
2897
+ * ```typescript
2898
+ * const tos = await client.legal.get('dakota_tos');
2899
+ * render(tos.content);
2900
+ *
2901
+ * await client.applications.submitAttestation(applicationId, {
2902
+ * attestation_type: 'terms_of_service',
2903
+ * legal_document_version: tos.version, // records what they actually saw
2904
+ * // ...
2905
+ * });
2906
+ * ```
2907
+ */
2908
+ async get(documentKey, version) {
2909
+ return this.transport.request({
2910
+ method: "GET",
2911
+ path: `/legal/documents/${documentKey}`,
2912
+ query: version !== void 0 ? { version } : void 0
2913
+ });
2914
+ }
2915
+ };
2916
+
2917
+ // src/client/resources/rd-marketing-fee.ts
2918
+ var RDMarketingFeeResource = class extends BaseResource {
2919
+ /**
2920
+ * The months this client has a statement for, newest first.
2921
+ *
2922
+ * Runs from the start of their contract to the running month, and the
2923
+ * RUNNING month IS included. It cannot be priced yet — the bank's interest
2924
+ * posts in the month after it is earned — but the balance is real and
2925
+ * accruing, and a client checking mid-month has to be able to see it. Its
2926
+ * fee figures come back absent rather than zero.
2927
+ *
2928
+ * An EMPTY list means the contract is real but no month has started yet.
2929
+ * That is different from a 404, which means no contract at all.
2930
+ *
2931
+ * @returns Statement months as `YYYY-MM-DD` (first day of the month, UTC)
2932
+ *
2933
+ * @example
2934
+ * ```typescript
2935
+ * const months = await client.rdMarketingFee.listMonths();
2936
+ * if (months.length === 0) {
2937
+ * // Contract starts next month or later — "starting soon", not an error.
2938
+ * }
2939
+ * ```
2940
+ */
2941
+ async listMonths() {
2942
+ const response = await this.transport.request({
2943
+ method: "GET",
2944
+ path: "/rd-marketing-fee/statements"
2945
+ });
2946
+ return response.months ?? [];
2947
+ }
2948
+ /**
2949
+ * One month's statement — one row per calendar day: the date, the RD
2950
+ * balance, and that day's fee.
2951
+ *
2952
+ * The rows are the STORED daily principals, read rather than recomputed, so
2953
+ * what the client reads and what Dakota priced cannot drift.
2954
+ *
2955
+ * Absent is not zero. A balance is absent when the day has not been derived
2956
+ * yet and `'0'` when the client genuinely held no RD; fees are absent for
2957
+ * every day of a month whose rate has not been derived. Neither unknown is
2958
+ * reported as a zero, so render an absent figure as unknown rather than
2959
+ * defaulting it.
2960
+ *
2961
+ * @param month - First day of the month, UTC, as `YYYY-MM-DD`
2962
+ * @returns The month's statement, one row per day
2963
+ *
2964
+ * @example
2965
+ * ```typescript
2966
+ * const statement = await client.rdMarketingFee.getStatement('2026-08-01');
2967
+ * for (const day of statement.daily) {
2968
+ * console.log(day.date, day.balance_minor ?? 'not yet derived');
2969
+ * }
2970
+ * ```
2971
+ */
2972
+ async getStatement(month) {
2973
+ return this.transport.request({
2974
+ method: "GET",
2975
+ path: `/rd-marketing-fee/statements/${month}`
2976
+ });
2977
+ }
2978
+ /**
2979
+ * The wallet this client's RD marketing fee is sent to.
2980
+ *
2981
+ * A **404** here is the ordinary state for a client who has not registered
2982
+ * one yet — not an error. A **403** means the client is not in the
2983
+ * programme at all.
2984
+ *
2985
+ * @returns The registered destination: always on Base (`eip155:8453`)
2986
+ *
2987
+ * @example
2988
+ * ```typescript
2989
+ * try {
2990
+ * const dest = await client.rdMarketingFee.getPayoutDestination();
2991
+ * console.log(dest.address);
2992
+ * } catch (error) {
2993
+ * if (error instanceof APIError && error.statusCode === 404) {
2994
+ * // Nothing registered yet — prompt for one.
2995
+ * }
2996
+ * }
2997
+ * ```
2998
+ */
2999
+ async getPayoutDestination() {
3000
+ return this.transport.request({
3001
+ method: "GET",
3002
+ path: "/rd-marketing-fee/payout-destination"
3003
+ });
3004
+ }
3005
+ /**
3006
+ * Register, or replace, the wallet the RD marketing fee is sent to.
3007
+ *
3008
+ * RD exists only on Base, so the chain is not a parameter — only an EVM
3009
+ * `address`. There is one destination per client, so this REPLACES any
3010
+ * existing one. Emits `rd_payout_destination.updated`.
3011
+ *
3012
+ * This is a SEPARATE registration from the developer-fee payout
3013
+ * destination (`client.feePayoutDestination`): the two programmes pay
3014
+ * different assets and are set independently.
3015
+ *
3016
+ * @param data - The EVM address on Base to pay the fee to
3017
+ * @param options - Request options (e.g., custom idempotency key)
3018
+ * @returns The stored destination
3019
+ *
3020
+ * @example
3021
+ * ```typescript
3022
+ * const dest = await client.rdMarketingFee.setPayoutDestination({
3023
+ * address: '0x1234567890123456789012345678901234567890',
3024
+ * });
3025
+ * console.log(dest.chain); // 'eip155:8453'
3026
+ * ```
3027
+ */
3028
+ async setPayoutDestination(data, options) {
3029
+ return this.transport.request({
3030
+ method: "PUT",
3031
+ path: "/rd-marketing-fee/payout-destination",
3032
+ body: data,
3033
+ idempotencyKey: options?.idempotencyKey,
3034
+ timeout: options?.timeout
3035
+ });
3036
+ }
3037
+ };
3038
+
2612
3039
  // src/client/resources/sandbox.ts
2613
3040
  var SandboxResource = class extends BaseResource {
2614
3041
  /**
@@ -2619,9 +3046,13 @@ var SandboxResource = class extends BaseResource {
2619
3046
  *
2620
3047
  * | Type | Required Fields |
2621
3048
  * |------|-----------------|
2622
- * | `ach_inbound`, `wire_inbound` | `account_id` |
2623
- * | `crypto_inbound` | `wallet_id` |
2624
- * | `*_outbound_*`, `*_reversal` | `movement_id` |
3049
+ * | `ach_inbound`, `fedwire_inbound`, `swift_inbound`, `fednow_inbound` | `account_id` |
3050
+ * | `crypto_inbound` | `wallet_address` |
3051
+ * | `*_outbound_*`, `*_reversal` | `account_id` + `one_off_transaction_id` |
3052
+ *
3053
+ * `swift_inbound` and `fedwire_inbound` behave identically: the rail a
3054
+ * deposit books on is derived from the RECEIVING account, so pick the
3055
+ * account, not the type, to choose between a SWIFT and a Fedwire deposit.
2625
3056
  *
2626
3057
  * @param data - Simulation request data
2627
3058
  * @returns Simulation response with ID and state
@@ -2650,11 +3081,13 @@ var SandboxResource = class extends BaseResource {
2650
3081
  * destination_payment_rail: 'ach',
2651
3082
  * });
2652
3083
  *
2653
- * // Simulate the ACH settlement
3084
+ * // Simulate the ACH settlement. `account_id` is the offramp account that
3085
+ * // funded the transaction.
2654
3086
  * await client.sandbox.simulateInbound({
2655
3087
  * simulation_id: `sim_${Date.now()}`,
2656
3088
  * type: 'ach_outbound_settled',
2657
- * movement_id: tx.id,
3089
+ * account_id: 'acc_456',
3090
+ * one_off_transaction_id: tx.id,
2658
3091
  * amount: '100.00',
2659
3092
  * currency: 'USD',
2660
3093
  * });
@@ -2665,7 +3098,7 @@ var SandboxResource = class extends BaseResource {
2665
3098
  * const result = await client.sandbox.simulateInbound({
2666
3099
  * simulation_id: `sim_${Date.now()}`,
2667
3100
  * type: 'crypto_inbound',
2668
- * wallet_id: 'wallet_789',
3101
+ * wallet_address: '0x165cd37b4c644c2921454429e7f9358d18a45e14',
2669
3102
  * amount: '500.00',
2670
3103
  * currency: 'USDC',
2671
3104
  * });
@@ -2868,11 +3301,23 @@ var SelfServeResource = class extends BaseResource {
2868
3301
  * type: 'purchase',
2869
3302
  * limit: 50,
2870
3303
  * });
3304
+ *
3305
+ * // Paging: carry BOTH halves of the cursor. Entries written in one
3306
+ * // transaction share a created_at, so a page boundary inside such a
3307
+ * // group drops rows when only `cursor` is sent.
3308
+ * const last = purchases.entries[purchases.entries.length - 1];
3309
+ * const next = await client.selfServe.listLedger({
3310
+ * type: 'purchase',
3311
+ * limit: 50,
3312
+ * cursor: last.created_at,
3313
+ * cursor_id: last.id,
3314
+ * });
2871
3315
  * ```
2872
3316
  */
2873
3317
  async listLedger(params) {
2874
3318
  const query = {};
2875
3319
  if (params?.cursor !== void 0) query.cursor = params.cursor;
3320
+ if (params?.cursor_id !== void 0) query.cursor_id = params.cursor_id;
2876
3321
  if (params?.limit !== void 0) query.limit = params.limit;
2877
3322
  if (params?.type !== void 0) query.type = params.type;
2878
3323
  return this.transport.request({
@@ -3070,10 +3515,10 @@ var PaymentAgentsResource = class extends BaseResource {
3070
3515
  * alternatives. Branch on `blocker.code`, not on `reply`, and ignore codes
3071
3516
  * you do not recognize.
3072
3517
  *
3073
- * `data.client_policy` is a DEVELOPMENT override of the vocabulary the
3074
- * agent drafts under; prefer registering it once with
3075
- * `client.agenticPolicy.set()`, since forgetting to send it here fails
3076
- * silently.
3518
+ * The vocabulary the agent drafts under is the one registered with
3519
+ * `client.agenticPolicy.set()`. It is not a property of this request —
3520
+ * a policy sent here is ignored, which is why the option to send one is
3521
+ * gone.
3077
3522
  *
3078
3523
  * @param paymentAgentId - Payment agent ID
3079
3524
  * @param data - Prompt and/or messages
@@ -3131,18 +3576,28 @@ var InstructionsResource = class extends BaseResource {
3131
3576
  /**
3132
3577
  * Accept proposals — actuate them into persisted instructions.
3133
3578
  *
3134
- * Two optional fields shape the actuation:
3135
- *
3136
- * - `developer_fee` declares your fee PER PAYOUT TYPE — `swap_bps` for a
3137
- * crypto payout, `offramp_bps` for a bank payout. They are independent,
3138
- * so one conversation can charge a swap and stay silent about a bank
3139
- * payout in the same turn. Omit a rate (or send zero) and that payout
3140
- * type carries no fee: nothing is charged, nothing is added to the
3141
- * amount, and the agent is told nothing about a fee it could mention.
3142
- * Both are DEFAULTS for the auto-accounts this request creates — an
3143
- * action-level `fee_bps` still wins outright.
3144
- * - `client_policy` is the same development override the proposals call
3145
- * takes. Prefer registering it once with `client.agenticPolicy.set()`.
3579
+ * One optional field shapes the actuation:
3580
+ *
3581
+ * - `developer_fee_defaults` declares your fee PER PAYOUT TYPE —
3582
+ * `swap` for a crypto payout, `offramp` for a bank payout — each as
3583
+ * a percentage (`developer_fee_bps`) or a flat amount per payment
3584
+ * (`developer_fee_fixed`, a decimal string in units of the asset
3585
+ * deposited, added on top of the amount), never both. They are
3586
+ * independent, so one conversation can charge a swap and stay silent
3587
+ * about a bank payout in the same turn. Omit a payout type (or set its
3588
+ * `developer_fee_bps` to zero) and it carries no fee: nothing is
3589
+ * charged, nothing is added to the amount, and the agent is told
3590
+ * nothing about a fee it could mention. Both are
3591
+ * DEFAULTS for the auto-accounts this request creates — an action-level
3592
+ * `developer_fee_bps` or `developer_fee_fixed` still wins outright.
3593
+ *
3594
+ * It replaces the deprecated `developer_fee` (`swap_bps` /
3595
+ * `offramp_bps`), which the platform still accepts. Send one or the
3596
+ * other: both is a 400.
3597
+ *
3598
+ * The vocabulary the actuation is judged against comes from the policy
3599
+ * registered with `client.agenticPolicy.set()` — the same one the drafting
3600
+ * turn used, which is the point of registering it rather than sending it.
3146
3601
  *
3147
3602
  * @param data - The payment agent id and the proposals to accept
3148
3603
  * @returns instruction_ids + the mandates the batch drafted (in full
@@ -3331,11 +3786,17 @@ var MandatesResource = class extends BaseResource {
3331
3786
  * it at its due date, days later, with the payee unpaid.
3332
3787
  *
3333
3788
  * Advisory — nothing here reserves budget, and the gate remains the
3334
- * authority at fire time. Two things to honour when reading a line:
3335
- * an ABSENT `remaining_amount` / `remaining_count` means "not capped", never
3336
- * "nothing left"; a `remaining_amount` of `'?'` means the figure could not
3337
- * be summed and MUST be treated as no headroom (the gate fails closed on the
3338
- * same data).
3789
+ * authority at fire time. Three things to honour when reading a line:
3790
+ *
3791
+ * - An ABSENT `remaining_amount` / `remaining_count` means "not capped",
3792
+ * never "nothing left" — EXCEPT on a `per_target` line with
3793
+ * `prior_scope: true`. That line's spend was booked under an earlier
3794
+ * version's target scope (before a `target_type` amendment) and no
3795
+ * current target claims it: the spend is real and still counts toward
3796
+ * the aggregate caps, but no payment can consume the bucket, so absent
3797
+ * remaining_* there means NO headroom. Never set on aggregate lines.
3798
+ * - A `remaining_amount` of `'?'` means the figure could not be summed and
3799
+ * MUST be treated as no headroom (the gate fails closed on the same data).
3339
3800
  *
3340
3801
  * @param mandateId - Mandate ID
3341
3802
  * @returns Per-target and aggregate budget lines, as of a stated instant
@@ -3343,8 +3804,11 @@ var MandatesResource = class extends BaseResource {
3343
3804
  * @example
3344
3805
  * ```typescript
3345
3806
  * const budget = await client.mandates.getBudget(mandateId);
3346
- * for (const line of budget.aggregate) {
3347
- * console.log(line.bucket, line.remaining_amount ?? 'uncapped');
3807
+ * for (const line of [...budget.per_target, ...budget.aggregate]) {
3808
+ * const headroom = line.prior_scope
3809
+ * ? 'none (prior scope)'
3810
+ * : (line.remaining_amount ?? 'uncapped');
3811
+ * console.log(line.target ?? '(all payees)', line.bucket, headroom);
3348
3812
  * }
3349
3813
  * ```
3350
3814
  */
@@ -3432,31 +3896,44 @@ var InsightsResource = class extends BaseResource {
3432
3896
  });
3433
3897
  }
3434
3898
  /**
3435
- * Ask about the customer's account.
3899
+ * Get the client-level portfolio insight report.
3436
3900
  *
3437
- * A read-only, advisory conversation. Stateless: send the conversation so
3438
- * far in `messages` on each call; the response is the assistant's next
3439
- * plain-text `reply`. The assistant narrates the same deterministic report
3440
- * {@link get} returns — it never originates a number, never proposes, and
3441
- * never moves money. Rate-limited per customer (hourly burst + daily
3442
- * window) — a 429 means back off and retry later.
3901
+ * The client-scope companion of {@link get}: one deterministic, read-only
3902
+ * report over ALL of the caller's customers' agentic activity. Items reuse
3903
+ * the customer report's shape, plus `customer_id` (omitted on
3904
+ * cross-customer aggregates) and `responsibility` (a grouping label for
3905
+ * filtering — not ownership). On top of the items the report carries
3906
+ * dashboard-shaped data: KPI `metrics` with previous-window values for
3907
+ * trend deltas, daily `series` for charts, and a per-customer roll-up in
3908
+ * `customers` sorted worst-first.
3443
3909
  *
3444
- * Model-backed, so it defaults to {@link AGENTIC_MODEL_TIMEOUT_MS} rather
3445
- * than the client's ordinary deadline. Pass `{ timeout }` to change it for
3446
- * one call; an explicit client-wide `timeout` still wins.
3910
+ * Every filter is optional and only NARROWS the report; the response shape
3911
+ * never changes. The report scans at most 100 customers per request —
3912
+ * `snapshot.customers.scanned < total` says it was computed over a prefix
3913
+ * of the book, never silently.
3447
3914
  *
3448
- * @param customerId - Customer ID
3449
- * @param data - The conversation so far (1–40 messages)
3450
- * @returns The assistant's reply (+ how the boundary screen treated the turn)
3915
+ * A 404 means agentic payments are not enabled for the key, or the
3916
+ * `customer_id` filter names an unknown customer.
3917
+ *
3918
+ * @param params - Optional filters and the report window
3919
+ * @returns The client's portfolio insight report
3920
+ *
3921
+ * @example
3922
+ * ```typescript
3923
+ * const report = await client.insights.getClientReport({
3924
+ * severity: 'critical,warn',
3925
+ * window_days: 30,
3926
+ * });
3927
+ * for (const row of report.customers) {
3928
+ * if (row.item_counts.critical > 0) console.log(row.customer_id, row.name);
3929
+ * }
3930
+ * ```
3451
3931
  */
3452
- async chat(customerId, data, options) {
3932
+ async getClientReport(params) {
3453
3933
  return this.transport.request({
3454
- method: "POST",
3455
- path: `/customers/${customerId}/insights/chat`,
3456
- body: data,
3457
- idempotencyKey: options?.idempotencyKey,
3458
- timeout: options?.timeout,
3459
- endpointTimeout: AGENTIC_MODEL_TIMEOUT_MS
3934
+ method: "GET",
3935
+ path: "/insights",
3936
+ query: { ...params }
3460
3937
  });
3461
3938
  }
3462
3939
  };
@@ -3493,11 +3970,13 @@ var AgenticPolicyResource = class extends BaseResource {
3493
3970
  /**
3494
3971
  * Register — or fully replace — this client's agentic policy.
3495
3972
  *
3496
- * Declaring the vocabulary once removes a silent failure mode. Sending
3497
- * `client_policy` in each proposals request still works and still wins, but
3498
- * FORGETTING to send it fails silently: the agent just narrates in the
3499
- * platform's nouns again ("destination", "mandate") and nothing errors
3500
- * anywhere. A registration makes that impossible.
3973
+ * Registration is the ONLY way to set a policy. A policy is a property of
3974
+ * the CLIENT, not of a request: carried per request, a drafting turn and
3975
+ * the accept that followed it could be judged by different rules. The
3976
+ * platform accordingly stopped reading `client_policy` from request bodies,
3977
+ * and one sent there is now ignored — silently, since the agent simply
3978
+ * narrates in the platform's nouns again ("destination", "mandate") with no
3979
+ * error anywhere. Registering once removes that failure mode.
3501
3980
  *
3502
3981
  * FULL REPLACE, not a merge — the registration IS your declared vocabulary,
3503
3982
  * so an omitted field means you no longer want it, and an empty body (`{}`)
@@ -3536,19 +4015,22 @@ var AgenticPolicyResource = class extends BaseResource {
3536
4015
  };
3537
4016
 
3538
4017
  // src/agentic/chat.ts
4018
+ var REJECTED_INPUT = "rejected_input";
3539
4019
  var AgentConversation = class {
3540
4020
  client;
3541
4021
  paymentAgentId;
3542
4022
  timezone;
3543
4023
  timeout;
3544
- clientPolicy;
4024
+ developerFeeDefaults;
4025
+ developerFee;
3545
4026
  history = [];
3546
4027
  constructor(client, paymentAgentId, history, options) {
3547
4028
  this.client = client;
3548
4029
  this.paymentAgentId = paymentAgentId;
3549
4030
  this.timezone = options?.timezone;
3550
4031
  this.timeout = options?.timeout;
3551
- this.clientPolicy = options?.clientPolicy;
4032
+ this.developerFeeDefaults = options?.developerFeeDefaults;
4033
+ this.developerFee = options?.developerFee;
3552
4034
  if (history && history.length > 0) {
3553
4035
  this.history = history.map(cloneMessage);
3554
4036
  }
@@ -3593,12 +4075,11 @@ var AgentConversation = class {
3593
4075
  this.paymentAgentId,
3594
4076
  {
3595
4077
  messages,
3596
- // Resent on EVERY turn — the endpoint is stateless, so a zone given
3597
- // once would be forgotten on the next one. Same for the policy
3598
- // override: an omitted one silently falls back to the client's
3599
- // registration (or platform defaults).
4078
+ // Resent on EVERY turn — the endpoint is stateless, so a value
4079
+ // given once would be forgotten on the next one.
3600
4080
  ...this.timezone ? { timezone: this.timezone } : {},
3601
- ...this.clientPolicy ? { client_policy: this.clientPolicy } : {}
4081
+ ...this.developerFeeDefaults ? { developer_fee_defaults: this.developerFeeDefaults } : {},
4082
+ ...this.developerFee ? { developer_fee: this.developerFee } : {}
3602
4083
  },
3603
4084
  this.timeout !== void 0 ? { timeout: this.timeout } : void 0
3604
4085
  );
@@ -3614,6 +4095,10 @@ var AgentConversation = class {
3614
4095
  hasBlockers: !!result.blockers && result.blockers.length > 0,
3615
4096
  conversationStatus: result.conversation_status ?? ""
3616
4097
  };
4098
+ if (turn.conversationStatus === REJECTED_INPUT) {
4099
+ this.history.pop();
4100
+ return turn;
4101
+ }
3617
4102
  let assistant = turn.reply;
3618
4103
  if (!assistant) {
3619
4104
  assistant = turn.hasProposals ? "(drafted proposals for your review)" : "(no reply)";
@@ -3739,6 +4224,10 @@ var DakotaClient = class {
3739
4224
  webhooks;
3740
4225
  /** Info API - query platform capabilities */
3741
4226
  info;
4227
+ /** Legal API - the published terms customers accept (unauthenticated) */
4228
+ legal;
4229
+ /** RD Marketing Fee API - this client's reserve-management statements */
4230
+ rdMarketingFee;
3742
4231
  /** Sandbox API - testing simulations (sandbox only) */
3743
4232
  sandbox;
3744
4233
  /** Self-Serve Credits API - manage prepaid transfer credits */
@@ -3808,6 +4297,8 @@ var DakotaClient = class {
3808
4297
  this.users = new UsersResource(this.transport);
3809
4298
  this.webhooks = new WebhooksResource(this.transport);
3810
4299
  this.info = new InfoResource(this.transport);
4300
+ this.legal = new LegalResource(this.transport);
4301
+ this.rdMarketingFee = new RDMarketingFeeResource(this.transport);
3811
4302
  this.sandbox = new SandboxResource(this.transport);
3812
4303
  this.selfServe = new SelfServeResource(this.transport);
3813
4304
  this.feePayoutDestination = new FeePayoutDestinationResource(this.transport);