@samyx/preview-stacks-client 0.31.0 → 0.33.0

package/README.md

@@ -1,8 +1,8 @@
 # @samyx/preview-stacks-client
 
 Typed API client for a [pstack](https://github.com/samishal1998/preview-stacks) control plane —
-deployments, jobs, readiness, containers, logs and notifiers, plus webhook verification for the
-receiving end.
+deployments, jobs, readiness, containers, logs, notifiers and accounts, plus webhook verification for
+the receiving end.
 
 Zero dependencies. Works in Node, Bun, Deno and the browser (it uses `fetch` and WebCrypto, nothing
 else).
@@ -110,6 +110,35 @@ const script = await pstack.swarm.join({ format: 'script' });   // a SECRET: tre
 // formats: 'token' | 'command' | 'script' | 'cloud-config' (+ distro for cloud-config)
 ```
 
+### Accounts and roles
+
+Every account holds one of four ordered roles. Each includes everything below it:
+
+| Role | What it adds |
+|---|---|
+| `viewer` | every read — deployments, jobs, logs, specs, routing, notifiers, the swarm, the user roster |
+| `developer` | stacks: `up` / `down` / `verify` / `sleep` / `wake`, container actions, specs, the terminal |
+| `maintainer` | host configuration: host vars, registries, routing files, notifiers, the swarm join material |
+| `admin` | people, and anything that can mint them: accounts, roles, SSO configuration, sealed config |
+
+`PSTACK_TOKEN` is above all four (`me().root === true`) and holds no account. A share-link token is
+not a role at all — it reaches the views its link names, on its one deployment.
+
+```ts
+const me = await pstack.me();
+if (!me.root && me.user?.role !== 'admin') throw new Error('this script mints accounts');
+
+const ci = await pstack.users.create({ username: 'ci-bot', password, role: 'developer' });
+await pstack.users.setRole(ci.id, 'maintainer');   // takes effect on that account's next request
+await pstack.users.remove(ci.id);
+const roster = await pstack.users.list();          // a viewer may read this
+```
+
+**An omitted `role` means `viewer`.** `users.create` used to produce an *administrator* every time; a
+script that relied on that must now say `role: 'admin'` and mean it. `user.role` is typed `string`,
+not `Role`, on the way back: the column is one an operator can repair by hand, and the server ranks a
+value it does not recognise *below* `viewer` — read an unfamiliar role as less, never as more.
+
 ### Single sign-on
 
 The sign-in itself is two browser redirects (`/api/auth/sso/start` → the provider →
@@ -153,6 +182,8 @@ Bun.serve({
   (`/api/deployments/:id/logs/stream`) and is left to `EventSource` or your own reader.
 - **No terminal.** That is a WebSocket carrying a session cookie, which belongs to a browser.
 - **No spec authoring helpers.** A spec is YAML you own; this client submits it verbatim.
+- **No password changes.** `PUT /api/users/:id/password` signs that account out of everything it has;
+  it is a person's job at a keyboard, not a script's.
 
 Anything not wrapped is still reachable with the same auth and error handling:
 

package/dist/index.d.ts

@@ -22,10 +22,10 @@
  *
  * `waitForJob`, `waitForReady` and `verifyWebhook` (below). They are the three things every user
  * would otherwise re-write, and the two waiters are the ones that are easy to get subtly wrong —
- * polling a job without a terminal-state list, or treating `readiness.state === 'watching'` as an
- * error rather than "ask again".
+ * polling a job without a terminal-state list (`queued` is not running and not finished either), or
+ * treating `readiness.state === 'watching'` as an error rather than "ask again".
  */
-import type { DeliveryRow, DeploymentRow, Health, HostVar, Job, Kind, Logs, NotifierRow, Readiness, Runtime, ShareLink, ShareView, SpecMeta, SsoConfig, SsoConfigResponse, SwarmInfo } from './types.ts';
+import type { CancelStack, DeliveryRow, DeploymentRow, Health, HostSettings, HostVar, Job, Kind, Logs, Me, NotifierRow, Readiness, Role, Runtime, SettingKey, SettingWritten, ShareLink, ShareView, SpecMeta, SsoConfig, SsoConfigResponse, SwarmInfo, User } from './types.ts';
 export * from './types.ts';
 /** A non-2xx answer. `body` is the parsed JSON, which is where the server's own message lives. */
 export declare class PstackError extends Error {
@@ -46,8 +46,14 @@ export type ClientOptions = {
      * else, every route needs it.
      */
     token?: string;
-    /** Swap in for tests, a proxy, or an agent with custom TLS. Defaults to global `fetch`. */
-    fetch?: typeof fetch;
+    /**
+     * Swap in for tests, a proxy, or an agent with custom TLS. Defaults to global `fetch`.
+     *
+     * The SIGNATURE, not `typeof fetch`: the global carries a `preconnect` property in both Bun's and
+     * Node's lib types, so `typeof fetch` rejects every plain arrow function — which is the only
+     * shape anyone actually passes here. This is what the client calls, and the global still fits it.
+     */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
     /** Per request, in ms. Deploys are started, never awaited, so this bounds the HTTP call only. */
     timeoutMs?: number;
 };
@@ -57,6 +63,11 @@ export declare function createClient(opts: ClientOptions): {
     /** Escape hatch: any route this client does not wrap yet, with auth and error handling applied. */
     request: <T>(method: string, path: string, body?: unknown) => Promise<T>;
     health: () => Promise<Health>;
+    /**
+     * Who this token is. `{ root: true }` for `PSTACK_TOKEN` — which is above every role and has no
+     * account — otherwise `user.role`, which is what a script branching on its own privileges reads.
+     */
+    me: () => Promise<Me>;
     deployments: {
         list: (vars?: Vars) => Promise<DeploymentRow[]>;
         get: (id: string, vars?: Vars) => Promise<DeploymentRow & {
@@ -100,6 +111,12 @@ export declare function createClient(opts: ClientOptions): {
         sleep: (id: string, vars?: Vars) => Promise<Job>;
         /** `up`, recorded as a wake. */
         wake: (id: string, vars?: Vars) => Promise<Job>;
+        /**
+         * Stop everything outstanding on this deployment's stack — the running job and the one queued
+         * behind it — in one call. Destroys nothing and undoes nothing; a `down` also clears the stack
+         * (it preempts) but then tears the stack down, which this does not.
+         */
+        cancel: (id: string, vars?: Vars) => Promise<CancelStack>;
         /**
          * Mint a read-only link to this deployment: `views` default to both `details` and `logs`,
          * `ttl` to 7 days (30 at most). The token is returned once and stored nowhere; rotating
@@ -167,6 +184,42 @@ export declare function createClient(opts: ClientOptions): {
             distro?: string;
         }) => Promise<string>;
     };
+    /**
+     * Accounts and the role each holds.
+     *
+     * Reading the roster is ordinary team information (viewer); creating, deleting and re-roling
+     * people is ADMIN, because anything that can set a role can set its own to `admin`.
+     */
+    users: {
+        list: () => Promise<User[]>;
+        /**
+         * An ABSENT `role` means the host's `default_role` setting — `viewer` on a host where nobody
+         * has changed it, which is what this used to mean unconditionally. It is still the least
+         * privilege by default and never admin by omission, but it is now an OPERATOR'S choice
+         * (`settings.set('default_role', …)`), so a script that wants a specific role must name it
+         * rather than rely on the host's. This route used to create an administrator every time; a
+         * script that relied on THAT must say `role: 'admin'` and mean it. A role outside the four is
+         * a 400 rather than a silently powerless account.
+         */
+        create: (body: {
+            username: string;
+            password: string;
+            email?: string;
+            role?: Role;
+        }) => Promise<User>;
+        /**
+         * Promote or demote. Takes effect on that account's NEXT request — the role is read fresh per
+         * request, so there is no session to revoke. Demoting the last admin is refused (400).
+         */
+        setRole: (id: number, role: Role) => Promise<{
+            updated: number;
+            role: Role;
+        }>;
+        /** Deleting the last admin is refused: a host nobody can administer cannot be repaired over HTTP. */
+        remove: (id: number) => Promise<{
+            deleted: number;
+        }>;
+    };
     /**
      * The identity provider people sign in with. The sign-in flow itself is two browser redirects
      * (`/api/auth/sso/start` → the provider → `/api/auth/sso/callback`) and has nothing for an SDK
@@ -282,11 +335,39 @@ export declare function createClient(opts: ClientOptions): {
         }>;
     };
     /**
-     * Poll a job until it stops running.
+     * The two host settings that change at RUNTIME: the running-job cap and the role an account
+     * created with no role named gets.
+     *
+     * Reading is viewer's; writing is per KEY, not per route — `max_jobs` is maintainer's and
+     * `default_role` is admin's, and each row says which in `minRole`. The read also says where
+     * each value came from (`source`), which is the only way to tell a value you set from one your
+     * environment is supplying.
+     */
+    settings: {
+        get: () => Promise<HostSettings>;
+        /**
+         * Store one. Refused (400) for an unknown key or a value the server will not take —
+         * `max_jobs` is an integer ≥ 1, `default_role` one of the four roles.
+         *
+         * `max_jobs` takes effect on the NEXT dispatch, with no restart: raising it starts a job that
+         * was waiting for a slot, and LOWERING IT CANCELS NOTHING — the jobs already running run to
+         * completion. The `note` in the response says so; print it rather than paraphrasing.
+         */
+        set: (key: SettingKey, value: number | Role) => Promise<SettingWritten>;
+    };
+    /**
+     * Poll a job until it reaches a terminal state.
+     *
+     * Returns the finished job rather than throwing on a failed one: `failed`, `leaked`,
+     * `cancelled` and `superseded` are ANSWERS, and a CI step usually wants to branch on which. It
+     * throws only when the wait itself fails — a timeout, or the API being unreachable.
      *
-     * Returns the finished job rather than throwing on a failed one: `failed`, `leaked` and
-     * `cancelled` are ANSWERS, and a CI step usually wants to branch on which. It throws only when
-     * the wait itself fails — a timeout, or the API being unreachable.
+     * WAITING IS NOT ONLY `running`. A job accepted for a busy stack, or over the host's
+     * concurrency cap, is `queued` — it has an id and a 202 and has not started. Returning on
+     * "not running" reported SUCCESS for a job that never ran, which is the worst possible answer
+     * to give a CI pipeline: it would assert against a deployment the deploy had not touched yet.
+     * The list below is the TERMINAL one, so a state this build has never heard of keeps waiting
+     * rather than being mistaken for an answer.
      */
     waitForJob(jobId: string, o?: {
         intervalMs?: number;

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/types.ts
+var TERMINAL_JOB_STATES = ["ok", "failed", "leaked", "cancelled", "superseded"];
+
 // src/index.ts
 class PstackError extends Error {
   status;
@@ -61,6 +64,7 @@ function createClient(opts) {
   const client = {
     request,
     health: () => get("/api/health"),
+    me: () => get("/api/auth/me"),
     deployments: {
       list: (vars) => get(`/api/deployments${qs(vars)}`).then((r) => r.deployments),
       get: (id, vars) => get(`/api/deployments/${enc(id)}${qs(vars)}`),
@@ -71,6 +75,7 @@ function createClient(opts) {
       down: (id, body = {}, vars) => post(`/api/deployments/${enc(id)}/down${qs(vars)}`, body).then((r) => r.job),
       sleep: (id, vars) => post(`/api/deployments/${enc(id)}/sleep${qs(vars)}`).then((r) => r.job),
       wake: (id, vars) => post(`/api/deployments/${enc(id)}/wake${qs(vars)}`).then((r) => r.job),
+      cancel: (id, vars) => post(`/api/deployments/${enc(id)}/cancel${qs(vars)}`),
       share: (id, body = {}) => post(`/api/deployments/${enc(id)}/share`, body),
       runtime: (id, vars) => get(`/api/deployments/${enc(id)}/runtime${qs(vars)}`),
       readiness: (id, o = {}) => get(`/api/deployments/${enc(id)}/readiness${qs(o.vars, { wait: o.wait, refresh: o.refresh ? 1 : undefined, timeout: o.timeout })}`),
@@ -90,6 +95,12 @@ function createClient(opts) {
       info: () => get("/api/swarm"),
       join: (o = { format: "command" }) => get(`/api/swarm/join${qs(undefined, { format: o.format, distro: o.distro })}`)
     },
+    users: {
+      list: () => get("/api/users").then((r) => r.users),
+      create: (body) => post("/api/users", body).then((r) => r.user),
+      setRole: (id, role) => request("PATCH", `/api/users/${id}`, { role }),
+      remove: (id) => del(`/api/users/${id}`)
+    },
     sso: {
       config: () => get("/api/sso/config"),
       save: (config) => put("/api/sso/config", config),
@@ -121,15 +132,21 @@ function createClient(opts) {
       put: (name, value, secret = false) => put(`/api/host-vars/${enc(name)}`, { value, secret }),
       remove: (name) => del(`/api/host-vars/${enc(name)}`)
     },
+    settings: {
+      get: () => get("/api/settings"),
+      set: (key, value) => put(`/api/settings/${enc(key)}`, { value })
+    },
     async waitForJob(jobId, o = {}) {
       const interval = o.intervalMs ?? 2000;
       const deadline = Date.now() + (o.timeoutMs ?? 30 * 60000);
       for (;; ) {
         const job = await client.jobs.get(jobId);
-        if (job.state !== "running")
+        if (TERMINAL_JOB_STATES.includes(job.state))
           return job;
         if (Date.now() > deadline) {
-          throw new PstackError(0, jobId, { error: `job ${jobId} still running after the wait timeout` });
+          throw new PstackError(0, jobId, {
+            error: `job ${jobId} still ${job.state} after the wait timeout`
+          });
         }
         await new Promise((r) => setTimeout(r, interval));
       }
@@ -181,5 +198,6 @@ async function verifyWebhook(args) {
 export {
   verifyWebhook,
   createClient,
+  TERMINAL_JOB_STATES,
   PstackError
 };

package/dist/types.d.ts

@@ -26,8 +26,28 @@ export type SleepRecord = {
     /** `HostRegexp` patterns (wildcard subdomains), Go syntax. */
     rules: string[];
 };
-/** `cancelled` = a person stopped it; nothing it had done was undone. */
-export type JobState = 'running' | 'ok' | 'failed' | 'leaked' | 'cancelled';
+/**
+ * A job's state.
+ *
+ * Two of these mean it has NOT run yet, and both are easy to mistake for an answer:
+ *
+ *  - `queued` — accepted, with an id, waiting its turn. A stack runs one job at a time, and the
+ *    host runs at most `PSTACK_MAX_JOBS` across every stack; over either limit a job waits rather
+ *    than being refused. It has no `startedAt`.
+ *  - `superseded` — it was queued and a newer job for the same stack replaced it. The queue is one
+ *    deep, so five rapid pushes run the first deploy and then exactly one more carrying the newest
+ *    spec; the three in between end here. Nothing ran, so unlike `cancelled` there is no partial
+ *    state to clean up.
+ *
+ * `cancelled` = a person stopped it. If it had started, whatever it had already done was NOT undone.
+ */
+export type JobState = 'queued' | 'running' | 'ok' | 'failed' | 'leaked' | 'cancelled' | 'superseded';
+/**
+ * The states a job never leaves. Exported because "is this over?" is the question every caller of
+ * this SDK asks, and `state !== 'running'` — the obvious way to ask it — answers YES for a queued
+ * job that has not started. `waitForJob` uses this list.
+ */
+export declare const TERMINAL_JOB_STATES: readonly JobState[];
 export type ReadinessState = 'watching' | 'ready' | 'failed' | 'timedout';
 export type Health = {
     ok: boolean;
@@ -128,7 +148,8 @@ export type Job = {
     stack: string;
     action: JobAction;
     state: JobState;
-    startedAt: number;
+    /** `null` while the job is `queued`, and on a `superseded` one — it never started. */
+    startedAt: number | null;
     endedAt?: number;
     outcome?: {
         ok: boolean;
@@ -144,6 +165,27 @@ export type Job = {
     }>;
     cancelledBy?: string;
 };
+/** The four fields a 202 carries — `state` is `running` when it dispatched, `queued` when it waits. */
+export type JobStub = {
+    id: string;
+    stack: string;
+    action: JobAction;
+    state: JobState;
+};
+/**
+ * `POST /api/deployments/:id/cancel` — stop everything this deployment's stack has outstanding: the
+ * running job AND the one queued behind it, in one call.
+ *
+ * NOT a teardown. It stops work and destroys nothing; it also undoes nothing a running job had
+ * already done. `cancelled` is `[]`, never null, when there was nothing outstanding, and `warning`
+ * differs by whether anything had actually started — a queued job leaves no partial state behind.
+ */
+export type CancelStack = {
+    stack: string;
+    cancelled: JobStub[];
+    by: string;
+    warning: string;
+};
 export type ContainerReadiness = {
     name: string;
     service: string | null;
@@ -279,6 +321,89 @@ export type PstackEvent = {
     at: number;
     data: Record<string, unknown>;
 };
+/**
+ * The four ordered roles, weakest first — each includes everything below it:
+ *
+ *   viewer      every read
+ *   developer   + stacks and deployments (up/down/verify/sleep/wake, containers, specs, terminal)
+ *   maintainer  + host configuration (host vars, registries, routing, notifiers, swarm join)
+ *   admin       + people, and anything that can mint them (users, SSO config, sealed config)
+ *
+ * `root` — the `PSTACK_TOKEN` bearer — sits ABOVE all four and is not one of them. A share link is
+ * not a role at any rank: it reaches the reads its own deployment allows and nothing else.
+ */
+export type Role = 'viewer' | 'developer' | 'maintainer' | 'admin';
+/** An account, as every response carries it. */
+export type User = {
+    id: number;
+    username: string;
+    /**
+     * `string`, not `Role`, on the way OUT: `users.role` is a plain TEXT column an operator is
+     * expected to be able to repair over SSH, so a value outside the four is possible. The server
+     * ranks such a role BELOW viewer — read an unfamiliar one as *less* than viewer, never as more.
+     * What you SEND is a `Role`; anything else is a 400.
+     */
+    role: string;
+    /** From an SSO provider's claims; null for every locally-created account. */
+    email: string | null;
+    createdAt: number;
+};
+/** Who a token is. `user` is present only for an account, `share` only for a share link. */
+export type Me = {
+    /** The `PSTACK_TOKEN` bearer — above every role, and it carries no account. */
+    root: boolean;
+    user?: User;
+    /** Epoch ms, or absent when the link could not be re-verified. */
+    share?: {
+        deployment: string;
+        views: ShareView[];
+        expiresAt?: number | null;
+    };
+};
+/**
+ * The two settings that can be changed at RUNTIME, without restarting the container. The server
+ * refuses any other key rather than storing it, so this union is the whole surface.
+ */
+export type SettingKey = 'max_jobs' | 'default_role';
+/**
+ * One setting, as read and as returned by a write.
+ *
+ * `source` says where the value came from: `db` (someone set it through the API), `env`
+ * (`PSTACK_MAX_JOBS`), or `default` (what the binary ships with). Precedence is **database >
+ * environment > built-in default** — the environment variable is the DEFAULT, not the authority, so
+ * a stored value survives the next restart and a host that never sets one behaves exactly as it did
+ * before this existed.
+ *
+ * `minRole` is the least role that may WRITE this key, served from the server's own permission
+ * table: `max_jobs` is maintainer's, `default_role` is admin's. Reading is viewer's. Treat a name
+ * this build does not recognise as the most privileged, never the least.
+ */
+export type SettingRow = {
+    key: SettingKey;
+    /** A number for `max_jobs`; a role name for `default_role`. */
+    value: number | string;
+    source: 'db' | 'env' | 'default';
+    minRole: string;
+};
+export type HostSettings = {
+    settings: SettingRow[];
+    /** `null` when `PSTACK_MAX_JOBS` is unset — never `0`, which the server reads as unset. */
+    env: {
+        PSTACK_MAX_JOBS: number | null;
+    };
+    precedence: string;
+};
+/**
+ * What a write answers: the fresh row (`source` is now `db`), and for `max_jobs` a `note`.
+ *
+ * The new cap is in force immediately — no restart — but LOWERING IT CANCELS NOTHING. Jobs already
+ * running run to completion; the cap applies to the next job that starts. A script that drops the
+ * cap to 1 has not stopped the four jobs in flight.
+ */
+export type SettingWritten = SettingRow & {
+    stored: true;
+    note?: string;
+};
 export type SsoClaimMap = {
     subject: string;
     username: string;
@@ -324,6 +449,17 @@ export type SsoConfig = {
      * rather than letting every later login fail.
      */
     requiredGroups: string[];
+    /**
+     * The role an account this provider MINTS is created at, and **empty means INHERIT** — the host's
+     * `default_role` setting, resolved when the account is provisioned rather than frozen when the
+     * provider was saved. Inherit falls back to `viewer` when the host default is unset, and never to
+     * admin by omission.
+     *
+     * Deliberately not narrowed to `Role`: the server stores this string without validating it, and
+     * one it does not recognise ranks below viewer. A provider stored before 0.33.0 carries a literal
+     * `"viewer"` (the server used to fill an empty value in), and keeps it until it is saved again
+     * with `''`.
+     */
     defaultRole: string;
 };
 export type SsoPreset = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samyx/preview-stacks-client",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Typed API client for a pstack control plane: deployments, jobs, readiness, containers, logs, notifiers.",
   "repository": {
     "type": "git",