@sudosapient/client 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @sudosapient/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The small fetch client that [`@sudosapient/cli`](../cli) and [`@sudosapient/mcp`](../mcp) use to talk
+to a Sudo Sapient workspace's public API (`/api/v1`), plus the config file they share. It has no
+dependencies and runs on any `fetch` (Node 22 or later). It is a library, not a command; you get it
+with the CLI or the MCP server, or on its own:
+
+```bash
+npm install @sudosapient/client
+```
+
+```js
+import { createClient, ApiError } from '@sudosapient/client';
+
+const api = createClient({ url: 'https://sudo.example.com', key: process.env.SUDO_API_KEY, client: 'My script' });
+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, 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
+  you; `SUDO_URL` and `SUDO_API_KEY` override it).
+
+Endpoints, fields and errors are in the workspace's API reference (`/api/docs`) and in
+[docs/api.md](../../docs/api.md).
+
+## License
+
+UNLICENSED, all rights reserved. The package is public on npm so anyone can install and use it, but
+no license to copy, modify or redistribute the code is granted.

package/config.js

@@ -0,0 +1,49 @@
+/* Where the CLI keeps the workspace URL and API key, shared with the MCP server:
+   $XDG_CONFIG_HOME/sudo-sapient/config.json (default ~/.config), readable only by its owner.
+   SUDO_URL and SUDO_API_KEY override it. `insecure`: the person allowed plain http to the saved URL
+   (`login --insecure`); it doesn't carry over to a SUDO_URL. */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const configPath = (env = process.env) => path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'sudo-sapient', 'config.json');
+
+export function loadConfig(env = process.env) {
+  let file = {};
+  try {
+    file = JSON.parse(fs.readFileSync(configPath(env), 'utf8'));
+  } catch {
+    /* not logged in yet */
+  }
+  return { url: env.SUDO_URL || file.url || '', key: env.SUDO_API_KEY || file.key || '', insecure: !env.SUDO_URL && !!file.insecure };
+}
+
+/* The key is never readable by anyone else, not even for a moment: the directory is made (or made
+   again) owner-only, and the file is written to a new temporary file created 0600, then renamed over
+   the old one, so it is never a file that had wider permissions, and a crash can't leave half of it. */
+export function saveConfig(cfg, env = process.env) {
+  const file = configPath(env);
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dir, 0o700);
+  const tmp = path.join(dir, `.config.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  const fd = fs.openSync(tmp, 'wx', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(cfg, null, 2) + '\n');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+  return file;
+}
+
+export function clearConfig(env = process.env) {
+  fs.rmSync(configPath(env), { force: true });
+}

package/index.js

@@ -0,0 +1,128 @@
+/* A minimal client for the Sudo Sapient public API (/api/v1), shared by the CLI and the MCP server.
+   No dependencies: it runs on any fetch (Node 22+, or an in-process `app.request`). */
+
+export class ApiError extends Error {
+  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". `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';
+  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() : '';
+    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);
+    }
+  }
+  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 = [];
+      let cursor;
+      do {
+        const page = await request('GET', path, { query: { ...query, limit: 100, cursor } });
+        out.push(...page.data);
+        cursor = page.nextCursor;
+      } while (cursor && out.length < max);
+      return out.slice(0, max);
+    },
+  };
+}
+
+/* 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());
+
+/* True when `url` would send the key in the clear to another machine: plain http to anything but
+   this one (localhost, 127.x, ::1). */
+export function plainHttpRemote(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  return u.protocol === 'http:' && !(host === 'localhost' || host.endsWith('.localhost') || host === '::1' || /^127\./.test(host));
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@sudosapient/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "url": "git+https://github.com/sudosapient-labs/project-tracker.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/sudosapient-labs/project-tracker/tree/prod/packages/client#readme",
+  "bugs": "https://github.com/sudosapient-labs/project-tracker/issues",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./config": "./config.js"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
 }