@dakota-xyz/ts-sdk 2.1.0 → 2.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/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:
@@ -707,6 +757,30 @@ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
707
757
  | `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
708
758
  | `paymentAgents.getProposalsProgress(id)` | Live progress of an in-flight drafting turn (advisory) |
709
759
 
760
+ ### Agentic Policy (Alpha)
761
+
762
+ How your product speaks, and what the agent may propose for it. Register it
763
+ once and every drafting turn narrates in your nouns instead of the platform's.
764
+
765
+ | Method | Description |
766
+ |--------|-------------|
767
+ | `agenticPolicy.get(clientId)` | Read your registered policy (404 = none, which is the default) |
768
+ | `agenticPolicy.set(clientId, policy)` | Register or fully replace it (`{}` clears it) |
769
+
770
+ ```typescript
771
+ await client.agenticPolicy.set(clientId, {
772
+ payee_model: 'flat',
773
+ payout_assets: ['USDC', 'USDT'],
774
+ labels: { limit: 'spending limit', payee: 'recipient', limit_unit: 'USD' },
775
+ payout_route: 'conversion_account_only',
776
+ });
777
+ ```
778
+
779
+ It is a **full replace, not a merge** — an omitted field means you no longer
780
+ want it. You can also pass `clientPolicy` per conversation, but that is a
781
+ development override: forgetting it fails *silently*, and the agent quietly
782
+ goes back to saying "destination" and "mandate".
783
+
710
784
  ### Mandates (Alpha)
711
785
 
712
786
  The §8 authorizations that arm scheduled payments.