@samyx/preview-stacks-client 0.25.2 → 0.27.0

package/README.md

@@ -69,6 +69,62 @@ for (const c of rt.containers.filter((c) => c.restartCount > 2)) {
 const logs = await pstack.deployments.logs('pr-7', { service: 'web', tail: 500, timestamps: true, vars: { PR: 7 } });
 ```
 
+### Sleep and wake
+
+A stack that is only looked at now and then can be put to sleep — its compose project goes down, its
+volumes and axes stay — and comes back on the next request to any of its hostnames, or on `wake`.
+(The spec can do this on a timer with a `sleep:` block; see the pstack docs.)
+
+```ts
+const job = await pstack.deployments.sleep('pr-7', { PR: 7 });
+await pstack.waitForJob(job.id);
+const d = await pstack.deployments.get('pr-7', { PR: 7 });
+d.asleep;          // { since, reason, hosts, rules } while asleep, null otherwise
+await pstack.deployments.wake('pr-7', { PR: 7 });   // the same as `up`, recorded as a wake
+```
+
+### Share a read-only link
+
+Hand someone the logs of one deployment without creating an account for them. The link carries a
+signed token that reaches exactly the views you name, on that deployment, until it expires (7 days
+by default, 30 at most). The token is returned once and stored nowhere; rotating the server's
+`PSTACK_TOKEN` is the only revocation.
+
+```ts
+const link = await pstack.deployments.share('pr-7', { views: ['logs'], ttl: '24h' });
+console.log(link.url);   // https://control.preview.example.com/deployments/pr-7/public-logs-view?token=…
+
+// The token also works as this client's bearer, for the reads the link allows:
+const viewer = createClient({ baseUrl, token: link.token });
+await viewer.deployments.logs('pr-7');          // ok
+await viewer.deployments.up('pr-7');            // PstackError 403
+```
+
+### The swarm
+
+On a host that runs previews as swarm stacks, the nodes and the material a new worker needs:
+
+```ts
+const swarm = await pstack.swarm.info();        // { reachable, active, managerAddr, nodes, ports, … }
+const script = await pstack.swarm.join({ format: 'script' });   // a SECRET: treat like a password
+// formats: 'token' | 'command' | 'script' | 'cloud-config' (+ distro for cloud-config)
+```
+
+### Single sign-on
+
+The sign-in itself is two browser redirects (`/api/auth/sso/start` → the provider →
+`/api/auth/sso/callback`); what an SDK can do is configure it.
+
+```ts
+const { callbackUrl, presets } = await pstack.sso.config();   // register callbackUrl with your provider
+await pstack.sso.save({ mode: 'oidc', issuer: 'https://accounts.google.com',
+                        clientId: '…', clientSecret: '…', label: 'Google' });
+// The issuer is fetched while saving, so a typo throws here rather than failing someone's login.
+```
+
+`config()` returns the client secret as a mask — there is no route that returns the real one, and
+submitting the mask back keeps what is stored.
+
 ### Verify a webhook
 
 The half that lives in your receiver. It prevents the two mistakes that make a correct signature look

package/dist/index.d.ts

@@ -25,7 +25,7 @@
  * polling a job without a terminal-state list, or treating `readiness.state === 'watching'` as an
  * error rather than "ask again".
  */
-import type { DeliveryRow, DeploymentRow, Health, HostVar, Job, Kind, Logs, NotifierRow, Readiness, Runtime, SpecMeta } from './types.ts';
+import type { DeliveryRow, DeploymentRow, Health, HostVar, Job, Kind, Logs, NotifierRow, Readiness, Runtime, ShareLink, ShareView, SpecMeta, SsoConfig, SsoConfigResponse, SwarmInfo } 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 {
@@ -38,7 +38,9 @@ export type ClientOptions = {
     /** e.g. `https://api.preview.example.com`. A trailing slash is fine. */
     baseUrl: string;
     /**
-     * `PSTACK_TOKEN` (the machine credential CI holds) or a personal token (`pstack_pat_…`).
+     * `PSTACK_TOKEN` (the machine credential CI holds), a personal token (`pstack_pat_…`), or the
+     * token of a share link (`deployments.share`) — which then reaches exactly the reads that link
+     * allows, on that one deployment.
      *
      * Optional only because a server with no token configured is loopback-only dev mode. Anywhere
      * else, every route needs it.
@@ -91,6 +93,22 @@ export declare function createClient(opts: ClientOptions): {
             verify?: boolean;
             force?: boolean;
         }, vars?: Vars) => Promise<Job>;
+        /**
+         * Take the compose project down and KEEP its volumes and axes. A request to any of its
+         * hostnames brings it back (wake-on-call), as does `wake`. Refused (409) for `kind: shared`.
+         */
+        sleep: (id: string, vars?: Vars) => Promise<Job>;
+        /** `up`, recorded as a wake. */
+        wake: (id: string, vars?: Vars) => Promise<Job>;
+        /**
+         * 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
+         * PSTACK_TOKEN is the only revocation.
+         */
+        share: (id: string, body?: {
+            views?: ShareView[];
+            ttl?: string;
+        }) => Promise<ShareLink>;
         runtime: (id: string, vars?: Vars) => Promise<Runtime>;
         /**
          * Is it SERVING yet — separate from "did the deploy job succeed", which only means the
@@ -137,6 +155,42 @@ export declare function createClient(opts: ClientOptions): {
             note: string;
         }>;
     };
+    /** The swarm this daemon manages. `reachable: false` means docker did not answer — nothing else is known. */
+    swarm: {
+        info: () => Promise<SwarmInfo>;
+        /**
+         * What a new worker runs. A SECRET — whoever holds the token can add a node that runs any
+         * task. `cloud-config` renders a user-data file; `distro` picks its Docker install steps.
+         */
+        join: (o?: {
+            format: "token" | "command" | "script" | "cloud-config";
+            distro?: string;
+        }) => Promise<string>;
+    };
+    /**
+     * 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. */
+        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: (config: Partial<SsoConfig> & {
+            clientSecret?: string;
+        }) => Promise<{
+            ok: true;
+            config: SsoConfig;
+            callbackUrl: string;
+        }>;
+        /** Forget the provider. Nobody is deleted — accounts it created keep working. */
+        remove: () => Promise<{
+            ok: true;
+        }>;
+    };
     jobs: {
         list: () => Promise<Job[]>;
         get: (jobId: string) => Promise<Job>;

package/dist/index.js

@@ -40,6 +40,8 @@ function createClient(opts) {
       signal: opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined
     });
     const text = await res.text();
+    if (res.ok && (res.headers.get("content-type") ?? "").startsWith("text/plain"))
+      return text;
     let parsed = null;
     try {
       parsed = text ? JSON.parse(text) : null;
@@ -67,6 +69,9 @@ function createClient(opts) {
       up: (id, vars) => post(`/api/deployments/${enc(id)}/up${qs(vars)}`).then((r) => r.job),
       verify: (id, vars) => post(`/api/deployments/${enc(id)}/verify${qs(vars)}`).then((r) => r.job),
       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),
+      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 })}`),
       logs: (id, o = {}) => get(`/api/deployments/${enc(id)}/logs${qs(o.vars, {
@@ -81,6 +86,15 @@ function createClient(opts) {
       stop: (id, name, o = {}) => post(`/api/deployments/${enc(id)}/containers/${enc(name)}/stop${qs(o.vars, { grace: o.grace })}`),
       restart: (id, name, o = {}) => post(`/api/deployments/${enc(id)}/containers/${enc(name)}/restart${qs(o.vars, { grace: o.grace })}`)
     },
+    swarm: {
+      info: () => get("/api/swarm"),
+      join: (o = { format: "command" }) => get(`/api/swarm/join${qs(undefined, { format: o.format, distro: o.distro })}`)
+    },
+    sso: {
+      config: () => get("/api/sso/config"),
+      save: (config) => put("/api/sso/config", config),
+      remove: () => del("/api/sso/config")
+    },
     jobs: {
       list: () => get("/api/jobs").then((r) => r.jobs),
       get: (jobId) => get(`/api/jobs/${enc(jobId)}`).then((r) => r.job),

package/dist/types.d.ts

@@ -11,7 +11,21 @@
  * renames the server's fields makes the API docs wrong for anyone reading both.
  */
 export type Kind = 'isolated' | 'shared';
-export type JobAction = 'up' | 'down' | 'verify';
+/** `sleep` takes the compose project down (volumes and axes stay); `wake` is `up` recorded under its own name. */
+export type JobAction = 'up' | 'down' | 'verify' | 'sleep' | 'wake';
+export type Orchestrator = 'compose' | 'swarm';
+export type ShareView = 'details' | 'logs';
+/**
+ * Present while a deployment is asleep: when, why, and the hostnames a request to which wakes it
+ * (captured from its Traefik labels the moment before teardown).
+ */
+export type SleepRecord = {
+    since: number;
+    reason: string;
+    hosts: string[];
+    /** `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';
 export type ReadinessState = 'watching' | 'ready' | 'failed' | 'timedout';
@@ -20,6 +34,11 @@ export type Health = {
     /** 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. */
+    sso?: {
+        enabled: boolean;
+        label: string;
+    } | null;
     dataDir: string;
     version: string;
 };
@@ -38,11 +57,57 @@ export type DeploymentRow = {
      */
     busy: boolean | null;
     running: boolean | null;
+    /** The sleep record, or null when awake. A sleeping stack is neither running nor torn down. */
+    asleep?: SleepRecord | null;
+    /** `compose` or `swarm`; null when the spec has no compose section or could not be resolved. */
+    orchestrator?: Orchestrator | null;
+    /** The spec's `sleep:` policy as durations (`2h`), on the detail route only. */
+    sleep?: {
+        idle: string | null;
+        after: string | null;
+    } | null;
     /** Why the spec could not be resolved — usually a variable this call did not supply. */
     unresolved?: string;
     createdAt?: number;
     updatedAt?: number;
 };
+export type SwarmNode = {
+    id: string;
+    hostname: string;
+    role: 'manager' | 'worker';
+    status: string;
+    availability: string;
+    managerStatus: string | null;
+    engineVersion: string;
+    /** The node this API runs on. */
+    self: boolean;
+};
+export type SwarmInfo = {
+    /** False when docker did not answer — every other field is then unknown, not empty. */
+    reachable: boolean;
+    /** Whether this daemon is a swarm manager. Inactive hosts run previews with compose. */
+    active: boolean;
+    nodeId: string | null;
+    /** `<advertise-addr>:2377`, what a worker joins. */
+    managerAddr: string | null;
+    nodes: SwarmNode[];
+    error?: string;
+    /** The ports a worker must reach on the manager (and nodes on each other). */
+    ports: Array<{
+        port: string;
+        why: string;
+    }>;
+    note: string;
+};
+export type ShareLink = {
+    /** `https://control.<domain>/deployments/<id>/public-logs-view?token=…` */
+    url: string;
+    /** The JWT. Returned ONCE; stored nowhere on the server. Works as this client's `token` for the GETs it allows. */
+    token: string;
+    views: ShareView[];
+    /** Epoch ms. */
+    expiresAt: number;
+};
 export type StepResult = {
     axis: string;
     phase: 'requires' | 'up' | 'down' | 'assert_gone' | 'assert_live' | 'compose';
@@ -112,6 +177,12 @@ export type RuntimeContainer = {
         hostPort?: string;
     }>;
     traefikLabels: Record<string, string>;
+    /** Epoch ms when the process started; null when docker did not say. */
+    startedAt?: number | null;
+    /** The swarm node it runs on, or null under compose. */
+    node?: string | null;
+    /** A swarm task on ANOTHER node: listed, but out of reach of exec/stop from the manager. */
+    remote?: boolean;
 };
 export type RuntimeRoute = {
     router: string;
@@ -128,6 +199,8 @@ export type RuntimeRoute = {
 };
 export type Runtime = {
     id?: string;
+    orchestrator?: Orchestrator | null;
+    asleep?: SleepRecord | null;
     stack: string;
     containers: RuntimeContainer[];
     routes: RuntimeRoute[];
@@ -197,3 +270,51 @@ export type PstackEvent = {
     at: number;
     data: Record<string, unknown>;
 };
+export type SsoClaimMap = {
+    subject: string;
+    username: string;
+    email: string;
+    name: string;
+    avatar: string;
+};
+/** The stored provider. The client secret is NEVER part of this — it has no read path. */
+export type SsoConfig = {
+    mode: 'oidc' | 'oauth2';
+    enabled: boolean;
+    /** Button text, and the `providerKey` half of an account's identity. */
+    label: string;
+    clientId: string;
+    /** Mode A: the issuer, or a full `.well-known` URL. */
+    discoveryUrl: string;
+    /** Mode B: a preset key, or `custom`. */
+    provider: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    /** Consulted only when the profile carries no address (GitHub's default). */
+    emailsUrl: string;
+    scopes: string;
+    claimMap: SsoClaimMap;
+    /** Non-empty ⇒ a login outside these domains is refused, INCLUDING one with no address at all. */
+    allowedEmailDomains: string[];
+    defaultRole: string;
+};
+export type SsoPreset = {
+    key: string;
+    label: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string | null;
+    scopes: string;
+    claimMap: SsoClaimMap;
+};
+export type SsoConfigResponse = {
+    configured: boolean;
+    /** Register THIS with the 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.25.2",
+  "version": "0.27.0",
   "description": "Typed API client for a pstack control plane: deployments, jobs, readiness, containers, logs, notifiers.",
   "repository": {
     "type": "git",