@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 +51 -1
- package/dist/index.d.mts +89 -1
- package/dist/index.d.ts +89 -1
- package/dist/index.js +205 -79
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +205 -79
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
/**
|