@sudosapient/client 0.1.0 → 0.2.0

package/README.md

@@ -17,14 +17,23 @@ try {
   const me = await api.get('/me');
   const mine = await api.all('/tasks', { assignee: 'me', status: 'open' });
   await api.post('/tasks', { project: 'WEB', title: 'Fix login bug' });
+  await api.upload('/files', { task: 'WEB-212', name: 'trace.txt' }, new TextEncoder().encode('…'), 'text/plain');
 } catch (e) {
   if (e instanceof ApiError) console.error(e.status, e.code, e.message);
 }
 ```
 
-- `createClient({ url, key, client, fetch })`: `get`, `post`, `patch`, `request`, and `all` (every
-  page of a list endpoint). `client` labels your changes in Activity ("Ada via My script"). Errors
-  are `ApiError` with `status`, `code` and `field`.
+- `createClient({ url, key, client, fetch, retry, onRetry })`: `get`, `post`, `patch`, `put`, `del`,
+  `request`, `all` (every page of a list endpoint), `upload(path, query, bytes, type)` (raw bytes as
+  the body, for `POST /files`) and `download(path)` (`{ bytes, type, name }`). `client` labels your changes in Activity ("Ada via My
+  script"). Errors are `ApiError` with `status`, `code` and `field` (and `retryAfter`, in seconds, on
+  a `429`).
+- Rate limits are waited out: a `429` with `Retry-After` is sent again after that many seconds, up
+  to `retry.retries` times (default 3), as long as each wait is at most `retry.maxDelay` ms (default
+  60 000) and the waits for one request add up to at most `retry.maxTotal` ms (default 120 000);
+  otherwise the `429` is thrown straight away. A `Retry-After` of 0 still waits a second. The server refuses such a request before handling
+  it, so this is safe for writes too. `onRetry({ attempt, delay, method, path })` is called before
+  each wait; `retry: { retries: 0 }` turns it off.
 - `plainHttpRemote(url)`: true when the URL would send the key unencrypted to another machine.
 - `@sudosapient/client/config`: `loadConfig`, `saveConfig`, `clearConfig` and `configPath` for
   `$XDG_CONFIG_HOME/sudo-sapient/config.json`, the file `sudo-cli login` writes (readable only by

package/index.js

@@ -2,46 +2,91 @@
    No dependencies: it runs on any fetch (Node 22+, or an in-process `app.request`). */
 
 export class ApiError extends Error {
-  constructor(status, body) {
+  constructor(status, body, retryAfter = null) {
     super(body?.error || (status ? `Request failed (${status})` : 'Couldn’t reach Sudo Sapient. Check the URL and your connection.'));
     this.status = status;
     this.code = body?.code || (status ? 'http_' + status : 'offline');
     this.field = body?.field || null;
+    this.retryAfter = retryAfter;
   }
 }
 
+/* Rate limits (429). The API refuses a request over the limit before handling it (middleware.js
+   `bearer`), so nothing of it was applied and retrying is safe for every method, writes included.
+   The client waits as long as Retry-After says (at least a second), up to `retries` times, never
+   longer than `maxDelay` at once nor `maxTotal` in all for one request: a wait past either is
+   reported instead (an ApiError with `retryAfter`, in seconds). A 429 without Retry-After (e.g.
+   "too many invites this hour") isn't retried. */
+export const RETRY = { retries: 3, maxDelay: 60_000, maxTotal: 120_000 };
+const MIN_WAIT = 1000;
+
+/* Milliseconds to wait from a Retry-After header (seconds, or an HTTP date), or null. */
+export function retryAfterMs(value, now = Date.now()) {
+  const v = String(value ?? '').trim();
+  if (!v) return null;
+  if (/^\d+$/.test(v)) return Number(v) * 1000;
+  const at = Date.parse(v);
+  return Number.isFinite(at) ? Math.max(0, at - now) : null;
+}
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
 /* `url`: the workspace's base URL (https://sudo.example.com). `client`: a label for activity, e.g.
-   "CLI" or "Claude", shown as "Ada via Claude". */
-export function createClient({ url, key, client = 'API', fetch: doFetch = globalThis.fetch }) {
+   "CLI" or "Claude", shown as "Ada via Claude". `retry`: { retries, maxDelay, maxTotal } for rate limits (see
+   RETRY; `{ retries: 0 }` turns retrying off). `onRetry({ attempt, delay, method, path })` is called
+   before each wait, e.g. to tell someone at a terminal why it paused. */
+export function createClient({ url, key, client = 'API', fetch: doFetch = globalThis.fetch, retry = {}, onRetry, sleep = wait }) {
   const base = String(url || '').replace(/\/+$/, '') + '/api/v1';
-  async function request(method, path, { query, body, idempotencyKey } = {}) {
+  const { retries, maxDelay, maxTotal } = { ...RETRY, ...retry };
+  /* `raw`: { body, type } sent as is instead of JSON (a file upload). `binary`: answer with the bytes
+     ({ bytes, type, name }) instead of parsed JSON (a file download). */
+  async function request(method, path, { query, body, idempotencyKey, raw, binary = false } = {}) {
     const qs = query ? new URLSearchParams(Object.entries(query).filter(([, v]) => v != null && v !== '')).toString() : '';
-    let res;
-    try {
-      res = await doFetch(base + path + (qs ? `?${qs}` : ''), {
-        method,
-        headers: {
-          authorization: `Bearer ${key}`,
-          // URI-encoded: header values must be Latin-1, and client names needn't be.
-          'x-sudo-client': encodeURIComponent(client),
-          accept: 'application/json',
-          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
-          ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
-        },
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-      });
-    } catch {
-      throw new ApiError(0, null);
+    const init = {
+      method,
+      headers: {
+        authorization: `Bearer ${key}`,
+        // URI-encoded: header values must be Latin-1, and client names needn't be.
+        'x-sudo-client': encodeURIComponent(client),
+        accept: 'application/json',
+        ...(raw ? { 'content-type': raw.type || 'application/octet-stream' } : body !== undefined ? { 'content-type': 'application/json' } : {}),
+        ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
+      },
+      body: raw ? raw.body : body !== undefined ? JSON.stringify(body) : undefined,
+    };
+    let waited = 0;
+    for (let attempt = 1; ; attempt++) {
+      let res;
+      try {
+        res = await doFetch(base + path + (qs ? `?${qs}` : ''), init);
+      } catch {
+        throw new ApiError(0, null);
+      }
+      if (res.ok && binary) return { bytes: new Uint8Array(await res.arrayBuffer()), type: res.headers.get('content-type') || '', name: fileName(res) };
+      const data = (res.headers.get('content-type') || '').includes('json') ? await res.json().catch(() => null) : null;
+      if (res.ok) return data;
+      const header = res.status === 429 ? retryAfterMs(res.headers.get('retry-after')) : null;
+      // "Retry-After: 0" still waits a moment, so a client can't spin against the limit.
+      const after = header == null ? null : Math.max(header, MIN_WAIT);
+      if (after == null || after > maxDelay || waited + after > maxTotal || attempt > retries)
+        throw new ApiError(res.status, data, header == null ? null : Math.ceil(header / 1000));
+      // A little jitter, so clients that were refused together don't all come back in the same instant.
+      const delay = after + Math.floor(Math.random() * 250);
+      waited += delay;
+      onRetry?.({ attempt, delay, method, path });
+      await sleep(delay);
     }
-    const data = (res.headers.get('content-type') || '').includes('json') ? await res.json().catch(() => null) : null;
-    if (!res.ok) throw new ApiError(res.status, data);
-    return data;
   }
   return {
     request,
     get: (path, query) => request('GET', path, { query }),
     post: (path, body = {}, opts) => request('POST', path, { body, ...opts }),
     patch: (path, body, opts) => request('PATCH', path, { body, ...opts }),
+    put: (path, body = {}, opts) => request('PUT', path, { body, ...opts }),
+    del: (path, opts) => request('DELETE', path, opts),
+    /* POST raw bytes, e.g. upload('/files', { project: 'WEB', name: 'spec.pdf' }, bytes, 'application/pdf'). */
+    upload: (path, query, bytes, type, opts) => request('POST', path, { query, raw: { body: bytes, type }, ...opts }),
+    /* GET bytes: { bytes, type, name }. */
+    download: (path, query) => request('GET', path, { query, binary: true }),
     /* Every page of a list endpoint, up to `max` items. */
     async all(path, query = {}, max = 500) {
       const out = [];
@@ -56,6 +101,16 @@ export function createClient({ url, key, client = 'API', fetch: doFetch = global
   };
 }
 
+/* The file name a download was sent with (Content-Disposition: filename*=UTF-8''…). */
+function fileName(res) {
+  const m = /filename\*=UTF-8''([^;]+)/i.exec(res.headers.get('content-disposition') || '');
+  try {
+    return m ? decodeURIComponent(m[1]) : null;
+  } catch {
+    return null;
+  }
+}
+
 /* Path segment for a task or project reference (an id or key). */
 export const seg = ref => encodeURIComponent(String(ref).trim());
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudosapient/client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Minimal fetch client for the Sudo Sapient public API (/api/v1), plus the shared CLI/MCP config.",
   "repository": {
     "type": "git",