@deepdockai/cli 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.1.2
+
+- The bundled TypeScript and Python clients wait 35 seconds per attempt (was 30): a call can wait up to 10 seconds for the device's slot and then up to 20 seconds on the device. They also retry `503 target_busy` up to three attempts (`maxAttempts` / `max_attempts`), waiting the `Retry-After` seconds (at most 15, one second without the header) and sending the same request, so a write keeps its idempotency key. `DeepdockError` carries the header as `retryAfter` / `retry_after`.
+
 ## 1.1.1
 
 - A new error code, `partner_deactivated` (403): Deepdock has deactivated the organisation, so none of its keys work and its devices are disconnected until Deepdock reactivates it. The CLI exits with 2 on it, as on `partner_not_approved`. The bundled device types and the skill's error reference include it.

package/dist/deepdock.js

@@ -11441,7 +11441,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.1.1";
+var VERSION = "1.1.2";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",

package/skill/references/calling-actions.md

@@ -114,8 +114,12 @@ Never invent an id, copy one from another device, or hard-code one from a test r
 
 - Every action call is sent to the customer's PC and run there. Expect a read to take from a few
   hundred milliseconds to a few seconds; a write about the same plus its verification.
-- Deepdock waits at most 20 seconds for the device, then answers `503 device_offline`. Set your HTTP
-  client timeout to 30 seconds so you receive the code instead of timing out first. A write that
+- A call can wait up to 10 seconds for the device's slot (`503 target_busy` with a `Retry-After`
+  header when it stays taken), then gets up to 20 seconds on the device (`503 device_offline`), so
+  the worst answer takes about 30 seconds. Set your HTTP client timeout to at least 35 seconds so
+  you receive the code instead of timing out first. The bundled clients do this and retry
+  `503 target_busy` up to three attempts, waiting the `Retry-After` seconds (at most 15), with the
+  same `Idempotency-Key`. A write that
   timed out or failed on the network on your side may still have landed: retry with the same
   `Idempotency-Key`.
 - An answer that is not JSON (a proxy's 502 or 504 page) is a transport failure: for a write, the

package/skill/references/clients/deepdock.py

@@ -8,6 +8,7 @@ Everything action-specific (fields, types, patterns) comes from the live OpenAPI
 from __future__ import annotations
 
 import os
+import time
 from dataclasses import dataclass, field, replace
 from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 from urllib.parse import quote
@@ -33,9 +34,22 @@ class DeepdockError(Exception):
         self.version = version  # system_version_unverified: the version the system last reported, None when it reported none
         self.reason = reason  # system_version_unverified: unverified_version, unparseable or unreported
         self.created = created  # applied_unverified, outcome_unknown with no rollback: {"chartId"} or None
+        self.retry_after: Optional[str] = None  # the Retry-After header as sent (seconds), when the answer carried one
         self.uncertain = uncertain  # outcome_unknown: True when the write may or may not have landed
 
 
+MAX_RETRY_WAIT = 15.0  # longest wait between two attempts, whatever Retry-After asks for
+DEFAULT_RETRY_WAIT = 1.0
+
+
+def _retry_wait(header: Optional[str]) -> float:
+    try:
+        seconds = float(header) if header is not None else -1.0
+    except ValueError:
+        seconds = -1.0
+    return min(seconds, MAX_RETRY_WAIT) if seconds >= 0 else DEFAULT_RETRY_WAIT
+
+
 class DeepdockTransportError(Exception):
     """No answer, or not Deepdock's envelope (timeout, network, a proxy page): a write may still have landed."""
 
@@ -53,15 +67,31 @@ class WriteResult:
 
 
 class Deepdock:
-    def __init__(self, api_key: str, base: Optional[str] = None, timeout: float = 30.0,
-                 client: Optional[httpx.Client] = None):
-        # 30 s is above Deepdock's 20 s device wait, so device_offline arrives before a client timeout.
+    def __init__(self, api_key: str, base: Optional[str] = None, timeout: float = 35.0,
+                 client: Optional[httpx.Client] = None, max_attempts: int = 3, sleep=time.sleep):
+        # 35 s is above the worst answer (up to 10 s for the device's slot, then up to 20 s on the
+        # device), so the error code arrives before a client timeout.
+        # max_attempts: attempts per call on 503 target_busy (1 turns the retry off). The same
+        # request is sent again, so a write keeps its idempotency key.
+        self.max_attempts = max(1, int(max_attempts))
+        self._sleep = sleep
         # Default: DEEPDOCK_BASE_URL from the environment (the CLI's own variable), else production.
         base = base or os.environ.get("DEEPDOCK_BASE_URL") or "https://api.deepdock.ai"
         self.c = client or httpx.Client(base_url=base.rstrip("/"), timeout=timeout)
         self.c.headers["Authorization"] = f"Bearer {api_key}"
 
     def _send(self, method: str, path: str, **kw: Any) -> Tuple[Any, httpx.Headers]:
+        attempt = 1
+        while True:
+            try:
+                return self._send_once(method, path, **kw)
+            except DeepdockError as e:
+                if attempt >= self.max_attempts or e.status != 503 or e.code != "target_busy":
+                    raise
+                self._sleep(_retry_wait(e.retry_after))
+                attempt += 1
+
+    def _send_once(self, method: str, path: str, **kw: Any) -> Tuple[Any, httpx.Headers]:
         try:
             r = self.c.request(method, path, **kw)
         except httpx.HTTPError as e:  # timeouts and network errors
@@ -72,8 +102,10 @@ class Deepdock:
             raise DeepdockTransportError(f"non-JSON answer with status {r.status_code}")
         if isinstance(body, dict) and "error" in body:
             e = body["error"]
-            raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"),
+            err = DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"),
                                 e.get("version"), e.get("reason"), e.get("created"), e.get("uncertain"))
+            err.retry_after = r.headers.get("retry-after")
+            raise err
         if not isinstance(body, dict) or "data" not in body:
             raise DeepdockTransportError(f"unexpected body with status {r.status_code}")
         return body["data"], r.headers

package/skill/references/clients/deepdock.ts

@@ -21,6 +21,8 @@ export class DeepdockError extends Error {
   readonly created?: { chartId?: string } | null
   /** outcome_unknown: `true` when the write may or may not have landed. */
   readonly uncertain?: boolean
+  /** The `Retry-After` header as sent (seconds), when the answer carried one. */
+  retryAfter?: string
 
   constructor(status: number, code: string, message: string, requestId?: string,
     systems?: string[],
@@ -131,9 +133,24 @@ export type DeviceSystem = {
 export type DeepdockOptions = {
   /** Default: `DEEPDOCK_BASE_URL` from the environment (the CLI's own variable), else production. */
   base?: string
-  /** Above Deepdock's 20 s device wait, so you receive device_offline instead of timing out first. */
+  /** Per attempt, default 35 s: above the worst answer (up to 10 s for the device's slot, then up to 20 s on the device), so you receive the code instead of timing out first. */
   timeoutMs?: number
+  /** Attempts per call on `503 target_busy`, default 3; 1 turns the retry off. The same request is sent again, so a write keeps its idempotency key. */
+  maxAttempts?: number
   fetch?: typeof fetch
+  /** Waits between attempts; replace it in tests. */
+  sleep?: (ms: number) => Promise<void>
+}
+
+/** Longest wait between two attempts, whatever `Retry-After` asks for. */
+const MAX_RETRY_WAIT_MS = 15_000
+const DEFAULT_RETRY_WAIT_MS = 1_000
+
+const retryWaitMs = (header: string | null): number => {
+  const seconds = header === null ? Number.NaN : Number(header)
+  return Number.isFinite(seconds) && seconds >= 0
+    ? Math.min(seconds * 1000, MAX_RETRY_WAIT_MS)
+    : DEFAULT_RETRY_WAIT_MS
 }
 
 // `process` is absent in a browser, and Deno throws on `process.env` without --allow-env; then the
@@ -150,21 +167,52 @@ export class Deepdock {
   private readonly apiKey: string
   private readonly base: string
   private readonly timeoutMs: number
+  private readonly maxAttempts: number
   private readonly fetchImpl: typeof fetch
+  private readonly sleep: (ms: number) => Promise<void>
 
   constructor(
     apiKey: string,
-    { base = envBase() ?? 'https://api.deepdock.ai', timeoutMs = 30_000, fetch: fetchImpl = fetch }: DeepdockOptions = {},
+    {
+      base = envBase() ?? 'https://api.deepdock.ai',
+      timeoutMs = 35_000,
+      maxAttempts = 3,
+      fetch: fetchImpl = fetch,
+      sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    }: DeepdockOptions = {},
   ) {
     this.apiKey = apiKey
     this.base = base.replace(/\/$/, '')
     this.timeoutMs = timeoutMs
+    this.maxAttempts = Math.max(1, Math.floor(maxAttempts))
     this.fetchImpl = fetchImpl
+    this.sleep = sleep
   }
 
   private async send<T>(
     path: string,
     init: { method: string; headers?: Record<string, string>; body?: string },
+  ): Promise<{ data: T; headers: Headers }> {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.sendOnce<T>(path, init)
+      } catch (err) {
+        if (
+          attempt >= this.maxAttempts ||
+          !(err instanceof DeepdockError) ||
+          err.status !== 503 ||
+          err.code !== 'target_busy'
+        ) {
+          throw err
+        }
+        await this.sleep(retryWaitMs(err.retryAfter ?? null))
+      }
+    }
+  }
+
+  private async sendOnce<T>(
+    path: string,
+    init: { method: string; headers?: Record<string, string>; body?: string },
   ): Promise<{ data: T; headers: Headers }> {
     let res: Response
     try {
@@ -186,7 +234,9 @@ export class Deepdock {
     }
     if (body !== null && typeof body === 'object' && 'error' in body) {
       const { code, message, requestId, systems, version, reason, created, uncertain } = body.error
-      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason, created, uncertain)
+      const error = new DeepdockError(res.status, code, message, requestId, systems, version, reason, created, uncertain)
+      error.retryAfter = res.headers.get('retry-after') ?? undefined
+      throw error
     }
     if (body === null || typeof body !== 'object' || !('data' in body)) {
       throw new DeepdockTransportError(`unexpected body with status ${res.status}`)

package/skill/references/example-integration.md

@@ -20,7 +20,7 @@ Copy the file into the project; do not reach into the skill directory at runtime
 ```ts
 import { Deepdock, DeepdockError, DeepdockTransportError, attempt, type PendingWrite } from './deepdock'
 
-const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // base from DEEPDOCK_BASE_URL, else production; 30 s timeout
+const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // base from DEEPDOCK_BASE_URL, else production; 35 s timeout, retries 503 target_busy
 const page = await dd.read<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' }, { limit: 50 })
 for await (const p of dd.readAll<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' })) { /* every page */ }
 const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', 'create', key, input)

package/skill/references/idempotency.md

@@ -92,7 +92,7 @@ const res = await fetch(url, {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(input),
-  signal: AbortSignal.timeout(30_000),
+  signal: AbortSignal.timeout(35_000),
 })
 const replayed = res.headers.get('Idempotent-Replayed') === 'true'
 ```