@sudosapient/client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# 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' });
+} 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`.
+- `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,73 @@
+/* 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) {
+    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;
+  }
+}
+
+/* `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 }) {
+  const base = String(url || '').replace(/\/+$/, '') + '/api/v1';
+  async function request(method, path, { query, body, idempotencyKey } = {}) {
+    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 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 }),
+    /* 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);
+    },
+  };
+}
+
+/* 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.1.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"
+  }
 }