@dakota-xyz/ts-sdk 2.1.0 → 2.1.1

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
@@ -376,7 +376,9 @@ const client = new DakotaClient({
376
376
  // Auth mode (default: Auto)
377
377
  authMode: AuthMode.Auto, // Auto, APIKey, or ApplicationToken
378
378
 
379
- // Custom timeout (default: 15000ms)
379
+ // Custom timeout (default: 15000ms).
380
+ // Setting this applies it to EVERY request, including the model-backed
381
+ // agentic endpoints that otherwise get 180000ms — see "Timeouts" below.
380
382
  timeout: 30000,
381
383
 
382
384
  // Custom retry policy
@@ -397,6 +399,54 @@ const client = new DakotaClient({
397
399
  });
398
400
  ```
399
401
 
402
+ ## Timeouts
403
+
404
+ Requests default to **15s**, which suits ordinary reads and writes. The
405
+ agentic endpoints that call a model default to **180s** instead:
406
+
407
+ | Endpoint | Default |
408
+ |---|---|
409
+ | Everything else | 15s |
410
+ | `paymentAgents.createProposals` / `AgentConversation.send` | 180s |
411
+ | `insights.chat` | 180s |
412
+
413
+ A drafting turn is a sequence of model calls — read the payees, check
414
+ balances, draft, revise — so "pay these nine vendors every Friday"
415
+ legitimately runs minutes while "what can you do?" returns at once. Under a
416
+ 15s deadline the simple turns pass and the complex ones abort client-side,
417
+ which looks like flakiness rather than a deadline.
418
+
419
+ Override it at whichever level fits, most specific first:
420
+
421
+ ```typescript
422
+ // Per request — one slow call, everything else untouched. Available on
423
+ // every method that takes request options (the mutating ones).
424
+ await client.paymentAgents.createProposals(agentId, { prompt }, { timeout: 240_000 });
425
+
426
+ // Per conversation — every turn of this chat
427
+ const conv = client.newAgentConversation(agentId, { timeout: 240_000 });
428
+
429
+ // Client-wide — applies to EVERYTHING, agentic endpoints included
430
+ const client = new DakotaClient({ apiKey, timeout: 30_000 });
431
+ ```
432
+
433
+ Precedence is: per-request `timeout` → explicit client `timeout` → endpoint
434
+ default → 15s. Note the third row: **an explicit client-wide `timeout` wins
435
+ over the long agentic default**, because a deadline you configured is a
436
+ choice the SDK should not overrule. If you set a short global timeout and
437
+ also use agent conversations, raise it per conversation.
438
+
439
+ Two more things worth knowing:
440
+
441
+ - The deadline is **per attempt**, not per call. A timing-out request is
442
+ retried per `retryPolicy`, so budget roughly `timeout × maxAttempts`.
443
+ - A timeout raises `TransportError` naming the elapsed deadline and how to
444
+ change it. It is a client-side abort, not a server error — the server may
445
+ well still be completing the work.
446
+ - Per-request `timeout` rides on `RequestOptions`, so it is available on the
447
+ methods that accept them. Plain `get` / `list` reads do not take options
448
+ yet; use the client-wide setting for those.
449
+
400
450
  ## Idempotency Keys
401
451
 
402
452
  Dakota requires idempotency keys (**must be valid UUIDs**) for all `POST`, `PUT`, and `PATCH` requests to ensure safe retries. By default, the SDK auto-generates UUID keys for you, but you can provide your own for deterministic API calls:
package/dist/index.d.mts CHANGED
@@ -67,7 +67,20 @@ interface DakotaClientConfig {
67
67
  baseURL?: string;
68
68
  /** Authentication mode (default: Auto) */
69
69
  authMode?: AuthMode;
70
- /** Request timeout in milliseconds (default: 15000) */
70
+ /**
71
+ * Request timeout in milliseconds (default: 15000).
72
+ *
73
+ * Setting this explicitly applies it to EVERY request, including the
74
+ * model-backed agentic endpoints that otherwise get a longer default
75
+ * ({@link AGENTIC_MODEL_TIMEOUT_MS}) — so you keep full control, but a
76
+ * global value tuned for fast reads will also cap agent turns. To keep
77
+ * the long agentic default while tightening everything else, leave this
78
+ * unset and pass `{ timeout }` per request instead.
79
+ *
80
+ * Note this is a per-ATTEMPT deadline: with the default retry policy a
81
+ * timing-out request can be attempted up to `retryPolicy.maxAttempts`
82
+ * times, so worst-case wall clock is roughly `timeout × maxAttempts`.
83
+ */
71
84
  timeout?: number;
72
85
  /** Retry policy configuration */
73
86
  retryPolicy?: Partial<RetryPolicy>;
@@ -89,6 +102,15 @@ interface ResolvedConfig {
89
102
  baseURL: string;
90
103
  authMode: AuthMode;
91
104
  timeout: number;
105
+ /**
106
+ * Whether `timeout` came from the caller rather than the default.
107
+ *
108
+ * An explicit timeout is a deliberate choice and wins everywhere. An
109
+ * inherited default does not, so endpoints that know they are slow (the
110
+ * model-backed agentic ones) can raise it without overriding a value the
111
+ * caller actually asked for.
112
+ */
113
+ timeoutWasExplicit: boolean;
92
114
  retryPolicy: RetryPolicy;
93
115
  logger: Logger;
94
116
  automaticIdempotency: boolean;
@@ -123,6 +145,18 @@ interface TransportRequestOptions {
123
145
  headers?: Record<string, string>;
124
146
  idempotencyKey?: string;
125
147
  signal?: AbortSignal;
148
+ /**
149
+ * Caller-supplied deadline (ms) for this one request. Beats everything —
150
+ * it is the most specific statement of intent available.
151
+ */
152
+ timeout?: number;
153
+ /**
154
+ * The deadline (ms) this ENDPOINT wants when nobody has said otherwise —
155
+ * how long its work actually takes. Used only when the caller passed no
156
+ * per-request timeout AND set no explicit client-wide one, so it can
157
+ * never override a deadline someone deliberately chose.
158
+ */
159
+ endpointTimeout?: number;
126
160
  }
127
161
  /**
128
162
  * HTTP transport with retry, auth, and idempotency support.
@@ -146,8 +180,26 @@ declare class Transport {
146
180
  * Add authentication header based on auth mode and path.
147
181
  */
148
182
  private addAuthHeader;
183
+ /**
184
+ * Resolve the deadline for one request, most specific intent first:
185
+ *
186
+ * 1. the caller's per-request `timeout`
187
+ * 2. an explicit client-wide `timeout`
188
+ * 3. the endpoint's own default (slow endpoints raise their own)
189
+ * 4. the client-wide default
190
+ *
191
+ * (2) sits above (3) on purpose: a caller who configured a timeout chose
192
+ * it, and an endpoint must not quietly overrule that. (3) exists so the
193
+ * far more common caller — the one who configured nothing — gets a
194
+ * deadline that matches what the endpoint actually does.
195
+ */
196
+ private resolveTimeout;
149
197
  /**
150
198
  * Execute request with exponential backoff retry.
199
+ *
200
+ * `timeout` is per ATTEMPT, not per call: each attempt gets its own
201
+ * deadline, so a request that keeps timing out can take up to
202
+ * `timeout × maxAttempts` before it throws.
151
203
  */
152
204
  private executeWithRetry;
153
205
  /**
@@ -24098,6 +24150,18 @@ interface RequestOptions {
24098
24150
  * - Not reused across different business intents
24099
24151
  */
24100
24152
  idempotencyKey?: string;
24153
+ /**
24154
+ * Deadline for THIS request, in milliseconds.
24155
+ *
24156
+ * Overrides the client-wide `timeout` (and any endpoint default) for this
24157
+ * call only — so one slow operation does not force you to loosen the
24158
+ * deadline on every fast one, or to build a second client that differs by
24159
+ * a single number.
24160
+ *
24161
+ * Per ATTEMPT, not per call: a request that keeps timing out is retried
24162
+ * per `retryPolicy`, so budget roughly `timeout × maxAttempts`.
24163
+ */
24164
+ timeout?: number;
24101
24165
  /**
24102
24166
  * Endorsed-request envelope (`{ signatures, intent }`) for mutating
24103
24167
  * policy, signer-group, and wallet-transaction endpoints. Required by the
@@ -26120,6 +26184,12 @@ declare class PaymentAgentsResource extends BaseResource {
26120
26184
  * `AgentConversation` for multi-turn chat; use this directly only for
26121
26185
  * one-shot proposals.
26122
26186
  *
26187
+ * SLOW BY NATURE. A turn is a sequence of model calls — read the payees,
26188
+ * check balances, draft, revise — so a multi-payee request legitimately
26189
+ * runs minutes. It therefore defaults to {@link AGENTIC_MODEL_TIMEOUT_MS}
26190
+ * rather than the client's ordinary deadline. Pass `{ timeout }` to
26191
+ * change it for one call; an explicit client-wide `timeout` still wins.
26192
+ *
26123
26193
  * @param paymentAgentId - Payment agent ID
26124
26194
  * @param data - Prompt and/or messages
26125
26195
  * @returns Proposals (at high confidence) and/or a conversational reply
@@ -26417,6 +26487,10 @@ declare class InsightsResource extends BaseResource {
26417
26487
  * never moves money. Rate-limited per customer (hourly burst + daily
26418
26488
  * window) — a 429 means back off and retry later.
26419
26489
  *
26490
+ * Model-backed, so it defaults to {@link AGENTIC_MODEL_TIMEOUT_MS} rather
26491
+ * than the client's ordinary deadline. Pass `{ timeout }` to change it for
26492
+ * one call; an explicit client-wide `timeout` still wins.
26493
+ *
26420
26494
  * @param customerId - Customer ID
26421
26495
  * @param data - The conversation so far (1–40 messages)
26422
26496
  * @returns The assistant's reply (+ how the boundary screen treated the turn)
@@ -26503,6 +26577,19 @@ interface AgentConversationOptions {
26503
26577
  * DST transition before a far-future fire date shifts it by the DST delta.
26504
26578
  */
26505
26579
  timezone?: string;
26580
+ /**
26581
+ * Deadline (ms) for each turn of this conversation.
26582
+ *
26583
+ * Turns default to {@link AGENTIC_MODEL_TIMEOUT_MS}, which is sized for a
26584
+ * multi-payee drafting turn. Set this when your own turns are longer (a
26585
+ * very large payee list) or shorter (you would rather show the customer a
26586
+ * failure than keep them waiting).
26587
+ *
26588
+ * Required if the client was built with an explicit `timeout`: that
26589
+ * choice wins over the endpoint default, so a client configured with a
26590
+ * short global deadline will cut turns off unless you raise it here.
26591
+ */
26592
+ timeout?: number;
26506
26593
  }
26507
26594
  /**
26508
26595
  * A stateful, multi-turn proposals chat with one agent.
@@ -26520,6 +26607,7 @@ declare class AgentConversation {
26520
26607
  private readonly client;
26521
26608
  private readonly paymentAgentId;
26522
26609
  private readonly timezone?;
26610
+ private readonly timeout?;
26523
26611
  private history;
26524
26612
  constructor(client: DakotaClient, paymentAgentId: string, history?: ChatMessage[], options?: AgentConversationOptions);
26525
26613
  /**
package/dist/index.d.ts CHANGED
@@ -67,7 +67,20 @@ interface DakotaClientConfig {
67
67
  baseURL?: string;
68
68
  /** Authentication mode (default: Auto) */
69
69
  authMode?: AuthMode;
70
- /** Request timeout in milliseconds (default: 15000) */
70
+ /**
71
+ * Request timeout in milliseconds (default: 15000).
72
+ *
73
+ * Setting this explicitly applies it to EVERY request, including the
74
+ * model-backed agentic endpoints that otherwise get a longer default
75
+ * ({@link AGENTIC_MODEL_TIMEOUT_MS}) — so you keep full control, but a
76
+ * global value tuned for fast reads will also cap agent turns. To keep
77
+ * the long agentic default while tightening everything else, leave this
78
+ * unset and pass `{ timeout }` per request instead.
79
+ *
80
+ * Note this is a per-ATTEMPT deadline: with the default retry policy a
81
+ * timing-out request can be attempted up to `retryPolicy.maxAttempts`
82
+ * times, so worst-case wall clock is roughly `timeout × maxAttempts`.
83
+ */
71
84
  timeout?: number;
72
85
  /** Retry policy configuration */
73
86
  retryPolicy?: Partial<RetryPolicy>;
@@ -89,6 +102,15 @@ interface ResolvedConfig {
89
102
  baseURL: string;
90
103
  authMode: AuthMode;
91
104
  timeout: number;
105
+ /**
106
+ * Whether `timeout` came from the caller rather than the default.
107
+ *
108
+ * An explicit timeout is a deliberate choice and wins everywhere. An
109
+ * inherited default does not, so endpoints that know they are slow (the
110
+ * model-backed agentic ones) can raise it without overriding a value the
111
+ * caller actually asked for.
112
+ */
113
+ timeoutWasExplicit: boolean;
92
114
  retryPolicy: RetryPolicy;
93
115
  logger: Logger;
94
116
  automaticIdempotency: boolean;
@@ -123,6 +145,18 @@ interface TransportRequestOptions {
123
145
  headers?: Record<string, string>;
124
146
  idempotencyKey?: string;
125
147
  signal?: AbortSignal;
148
+ /**
149
+ * Caller-supplied deadline (ms) for this one request. Beats everything —
150
+ * it is the most specific statement of intent available.
151
+ */
152
+ timeout?: number;
153
+ /**
154
+ * The deadline (ms) this ENDPOINT wants when nobody has said otherwise —
155
+ * how long its work actually takes. Used only when the caller passed no
156
+ * per-request timeout AND set no explicit client-wide one, so it can
157
+ * never override a deadline someone deliberately chose.
158
+ */
159
+ endpointTimeout?: number;
126
160
  }
127
161
  /**
128
162
  * HTTP transport with retry, auth, and idempotency support.
@@ -146,8 +180,26 @@ declare class Transport {
146
180
  * Add authentication header based on auth mode and path.
147
181
  */
148
182
  private addAuthHeader;
183
+ /**
184
+ * Resolve the deadline for one request, most specific intent first:
185
+ *
186
+ * 1. the caller's per-request `timeout`
187
+ * 2. an explicit client-wide `timeout`
188
+ * 3. the endpoint's own default (slow endpoints raise their own)
189
+ * 4. the client-wide default
190
+ *
191
+ * (2) sits above (3) on purpose: a caller who configured a timeout chose
192
+ * it, and an endpoint must not quietly overrule that. (3) exists so the
193
+ * far more common caller — the one who configured nothing — gets a
194
+ * deadline that matches what the endpoint actually does.
195
+ */
196
+ private resolveTimeout;
149
197
  /**
150
198
  * Execute request with exponential backoff retry.
199
+ *
200
+ * `timeout` is per ATTEMPT, not per call: each attempt gets its own
201
+ * deadline, so a request that keeps timing out can take up to
202
+ * `timeout × maxAttempts` before it throws.
151
203
  */
152
204
  private executeWithRetry;
153
205
  /**
@@ -24098,6 +24150,18 @@ interface RequestOptions {
24098
24150
  * - Not reused across different business intents
24099
24151
  */
24100
24152
  idempotencyKey?: string;
24153
+ /**
24154
+ * Deadline for THIS request, in milliseconds.
24155
+ *
24156
+ * Overrides the client-wide `timeout` (and any endpoint default) for this
24157
+ * call only — so one slow operation does not force you to loosen the
24158
+ * deadline on every fast one, or to build a second client that differs by
24159
+ * a single number.
24160
+ *
24161
+ * Per ATTEMPT, not per call: a request that keeps timing out is retried
24162
+ * per `retryPolicy`, so budget roughly `timeout × maxAttempts`.
24163
+ */
24164
+ timeout?: number;
24101
24165
  /**
24102
24166
  * Endorsed-request envelope (`{ signatures, intent }`) for mutating
24103
24167
  * policy, signer-group, and wallet-transaction endpoints. Required by the
@@ -26120,6 +26184,12 @@ declare class PaymentAgentsResource extends BaseResource {
26120
26184
  * `AgentConversation` for multi-turn chat; use this directly only for
26121
26185
  * one-shot proposals.
26122
26186
  *
26187
+ * SLOW BY NATURE. A turn is a sequence of model calls — read the payees,
26188
+ * check balances, draft, revise — so a multi-payee request legitimately
26189
+ * runs minutes. It therefore defaults to {@link AGENTIC_MODEL_TIMEOUT_MS}
26190
+ * rather than the client's ordinary deadline. Pass `{ timeout }` to
26191
+ * change it for one call; an explicit client-wide `timeout` still wins.
26192
+ *
26123
26193
  * @param paymentAgentId - Payment agent ID
26124
26194
  * @param data - Prompt and/or messages
26125
26195
  * @returns Proposals (at high confidence) and/or a conversational reply
@@ -26417,6 +26487,10 @@ declare class InsightsResource extends BaseResource {
26417
26487
  * never moves money. Rate-limited per customer (hourly burst + daily
26418
26488
  * window) — a 429 means back off and retry later.
26419
26489
  *
26490
+ * Model-backed, so it defaults to {@link AGENTIC_MODEL_TIMEOUT_MS} rather
26491
+ * than the client's ordinary deadline. Pass `{ timeout }` to change it for
26492
+ * one call; an explicit client-wide `timeout` still wins.
26493
+ *
26420
26494
  * @param customerId - Customer ID
26421
26495
  * @param data - The conversation so far (1–40 messages)
26422
26496
  * @returns The assistant's reply (+ how the boundary screen treated the turn)
@@ -26503,6 +26577,19 @@ interface AgentConversationOptions {
26503
26577
  * DST transition before a far-future fire date shifts it by the DST delta.
26504
26578
  */
26505
26579
  timezone?: string;
26580
+ /**
26581
+ * Deadline (ms) for each turn of this conversation.
26582
+ *
26583
+ * Turns default to {@link AGENTIC_MODEL_TIMEOUT_MS}, which is sized for a
26584
+ * multi-payee drafting turn. Set this when your own turns are longer (a
26585
+ * very large payee list) or shorter (you would rather show the customer a
26586
+ * failure than keep them waiting).
26587
+ *
26588
+ * Required if the client was built with an explicit `timeout`: that
26589
+ * choice wins over the endpoint default, so a client configured with a
26590
+ * short global deadline will cut turns off unless you raise it here.
26591
+ */
26592
+ timeout?: number;
26506
26593
  }
26507
26594
  /**
26508
26595
  * A stateful, multi-turn proposals chat with one agent.
@@ -26520,6 +26607,7 @@ declare class AgentConversation {
26520
26607
  private readonly client;
26521
26608
  private readonly paymentAgentId;
26522
26609
  private readonly timezone?;
26610
+ private readonly timeout?;
26523
26611
  private history;
26524
26612
  constructor(client: DakotaClient, paymentAgentId: string, history?: ChatMessage[], options?: AgentConversationOptions);
26525
26613
  /**