@samyx/preview-stacks-client 0.30.0 → 0.32.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, HostVar, Job, Kind, Logs, Me, NotifierRow, Readiness, Role, Runtime, 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,27 +184,67 @@ 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 VIEWER — the least privilege, not the most. This route used to create
+         * an administrator every time; a script that relied on that must now 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
      * to call — this is the configuration around it.
      */
     sso: {
-        /** `clientSecret` comes back as a mask. There is no route that returns the real one. */
+        /** Every stored provider (secrets never come back — `secretSet` is all a read learns). */
         config: () => Promise<SsoConfigResponse>;
         /**
-         * Save. Omit `clientSecret` (or send the mask back) to keep the stored one. For `mode: 'oidc'`
-         * the issuer is fetched here, so a bad one is a 400 now rather than a failed login later.
+         * Save one provider under `key`, a lowercase slug. `key` may be omitted on a host with at
+         * most one provider — an empty host derives it from the config, a one-provider host replaces
+         * that one — which is what PUT meant before keys existed; with several it is a 400. Omit
+         * `clientSecret` to keep that key's stored one. For `mode: 'oidc'` the issuer is fetched
+         * here, so a bad one is a 400 now rather than a failed login later.
          */
         save: (config: Partial<SsoConfig> & {
+            key?: string;
             clientSecret?: string;
         }) => Promise<{
             ok: true;
+            key: string;
             config: SsoConfig;
             callbackUrl: string;
         }>;
-        /** Forget the provider. Nobody is deleted — accounts it created keep working. */
-        remove: () => Promise<{
+        /**
+         * Forget one provider — or the only one, when `key` is omitted (a 400 names the keys when
+         * there are several). Nobody is deleted — accounts it created keep working.
+         */
+        remove: (key?: string) => Promise<{
             ok: true;
         }>;
     };
@@ -274,11 +331,18 @@ export declare function createClient(opts: ClientOptions): {
         }>;
     };
     /**
-     * Poll a job until it stops running.
+     * 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,10 +95,16 @@ 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),
-      remove: () => del("/api/sso/config")
+      remove: (key) => del(key ? `/api/sso/config/${enc(key)}` : "/api/sso/config")
     },
     jobs: {
       list: () => get("/api/jobs").then((r) => r.jobs),
@@ -126,10 +137,12 @@ function createClient(opts) {
       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 +194,6 @@ async function verifyWebhook(args) {
 export {
   verifyWebhook,
   createClient,
+  TERMINAL_JOB_STATES,
   PstackError
 };

package/dist/types.d.ts

@@ -26,18 +26,45 @@ 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;
     /** False only in loopback dev mode, where the server refuses to bind off-localhost. */
     authEnforced: boolean;
     hasUsers?: boolean;
-    /** The configured identity provider, or null. Readable BEFORE authenticating — a login page needs it. */
+    /**
+     * The ENABLED sign-in providers, or null when there are none. Readable BEFORE authenticating —
+     * a login page needs one button per entry. `key` is what `/api/auth/sso/start?provider=` takes;
+     * `preset` is the preset the config came from (`''` for a bare OIDC issuer), for an icon.
+     */
     sso?: {
-        enabled: boolean;
-        label: string;
+        providers: Array<{
+            key: string;
+            label: string;
+            preset: string;
+        }>;
     } | null;
     dataDir: string;
     version: string;
@@ -121,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;
@@ -137,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;
@@ -183,6 +232,8 @@ export type RuntimeContainer = {
     node?: string | null;
     /** A swarm task on ANOTHER node: listed, but out of reach of exec/stop from the manager. */
     remote?: boolean;
+    /** A one-shot swarm service's synthetic row (0.31.0+): container verbs have nothing to act on. */
+    job?: boolean;
 };
 export type RuntimeRoute = {
     router: string;
@@ -270,6 +321,45 @@ 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;
+    };
+};
 export type SsoClaimMap = {
     subject: string;
     username: string;
@@ -315,24 +405,46 @@ export type SsoConfig = {
      * rather than letting every later login fail.
      */
     requiredGroups: string[];
+    /**
+     * The role an account this provider MINTS is created at. Deliberately not narrowed to `Role`: the
+     * server stores this string without validating it, and one it does not recognise ranks below
+     * viewer. Whatever it says is the floor every person who signs in through this provider gets.
+     */
     defaultRole: string;
 };
 export type SsoPreset = {
     key: string;
     label: string;
+    /** How the provider is talked to; the config's mode defaults from it. */
+    mode: 'oidc' | 'oauth2';
+    /** Login-page button text ("Continue with GitHub"). */
+    buttonLabel: string;
+    /** Where the operator registers the OAuth app, and the walkthrough to show beside the form. */
+    setupUrl: string;
+    setupHint: string;
+    /**
+     * The issuer, for an oidc preset (`''` otherwise). One containing `<` is a TEMPLATE — render it
+     * as a field for the operator to fill in; the server refuses it verbatim.
+     */
+    discoveryUrl: string;
     authorizeUrl: string;
     tokenUrl: string;
-    userInfoUrl: string | null;
+    userInfoUrl: string;
     scopes: string;
     claimMap: SsoClaimMap;
 };
+/** One stored provider, under its operator-chosen slug. */
+export type SsoProviderEntry = {
+    key: string;
+    config: SsoConfig;
+    /** All a read learns about the client secret — the value has no read path. */
+    secretSet: boolean;
+    updatedAt: number;
+};
 export type SsoConfigResponse = {
-    configured: boolean;
-    /** Register THIS with the provider, byte for byte. Built server-side; never guess it. */
+    /** Every stored provider, in key order — disabled ones included. */
+    providers: SsoProviderEntry[];
+    /** Register THIS with every provider, byte for byte. Built server-side; never guess it. */
     callbackUrl: string;
     presets: SsoPreset[];
-    config: SsoConfig | null;
-    /** A mask when one is stored. Submit it back unchanged to keep the stored secret. */
-    clientSecret: string;
-    updatedAt: number | null;
 };

package/package.json

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