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