@samyx/preview-stacks-client 0.25.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sami Mishal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @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.
+
+Zero dependencies. Works in Node, Bun, Deno and the browser (it uses `fetch` and WebCrypto, nothing
+else).
+
+```bash
+bun add @samyx/preview-stacks-client   # or npm / pnpm / yarn
+```
+
+## Use it
+
+```ts
+import { createClient } from '@samyx/preview-stacks-client';
+
+const pstack = createClient({
+  baseUrl: 'https://api.preview.example.com',
+  token: process.env.PSTACK_TOKEN,          // machine token, or a personal pstack_pat_…
+});
+
+// Submit a spec and deploy it. Variables travel with EVERY call — `down` needs the same ones as
+// `up`, or teardown targets a different stack than deploy created.
+await pstack.deployments.put(`pr-${pr}`, { specName: 'shopfront', vars: { PR: String(pr) } });
+const job = await pstack.deployments.up(`pr-${pr}`, { PR: pr });
+
+// Wait for the commands to finish…
+const finished = await pstack.waitForJob(job.id);
+if (finished.state !== 'ok') throw new Error(`deploy ${finished.state}`);
+
+// …and then for the app to actually be serving, which is a different question.
+const ready = await pstack.waitForReady(`pr-${pr}`, { vars: { PR: pr } });
+if (ready.state !== 'ready') {
+  console.error(ready.containers.filter((c) => c.failed).map((c) => `${c.name}: ${c.reason}`));
+}
+```
+
+### Errors throw
+
+Every non-2xx becomes a `PstackError` carrying the status and the server's own parsed body, so a
+script either works or stops:
+
+```ts
+import { PstackError } from '@samyx/preview-stacks-client';
+
+try {
+  await pstack.deployments.down('shared-services');
+} catch (e) {
+  if (e instanceof PstackError && e.status === 409) {
+    // Refused: tearing down a `kind: shared` stack destroys volumes every preview depends on.
+    await pstack.deployments.down('shared-services', { force: true });
+  } else throw e;
+}
+```
+
+The two waiters are the exception: `waitForJob` and `waitForReady` **return** a failed job or an
+unready stack rather than throwing. The state is the answer, and a CI step usually wants to branch on
+which one it got. They throw only when the wait itself fails.
+
+### Containers
+
+```ts
+const rt = await pstack.deployments.runtime('pr-7', { PR: 7 });
+for (const c of rt.containers.filter((c) => c.restartCount > 2)) {
+  await pstack.containers.restart('pr-7', c.name, { vars: { PR: 7 } });
+}
+const logs = await pstack.deployments.logs('pr-7', { service: 'web', tail: 500, timestamps: true, vars: { PR: 7 } });
+```
+
+### Verify a webhook
+
+The half that lives in your receiver. It prevents the two mistakes that make a correct signature look
+wrong: re-serialising the body before hashing, and skipping the staleness check the signed timestamp
+exists for.
+
+```ts
+import { verifyWebhook } from '@samyx/preview-stacks-client';
+
+Bun.serve({
+  async fetch(req) {
+    const rawBody = await req.text();               // the untouched bytes, never a re-stringify
+    const v = await verifyWebhook({ secret: process.env.HOOK_SECRET!, rawBody, headers: req.headers });
+    if (!v.ok) return new Response(v.reason, { status: 401 });
+
+    const event = JSON.parse(rawBody);
+    if (v.redelivery) console.log('replay of', event.id);   // dedupe on event.id
+    return new Response('ok');
+  },
+});
+```
+
+## What it does not do
+
+- **No log streaming.** `deployments.logs()` fetches a tail; following is an SSE endpoint
+  (`/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.
+
+Anything not wrapped is still reachable with the same auth and error handling:
+
+```ts
+await pstack.request('GET', '/api/routing/live');
+```
+
+## Versioning
+
+Released in lockstep with the server. A client is compatible with any server of the same minor or
+newer — routes and payload fields are added, never renamed (the same contract the webhook events
+carry). Full API reference: [docs/usage.md](https://github.com/samishal1998/preview-stacks/blob/main/docs/usage.md).

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+/**
+ * A typed client for a pstack control plane.
+ *
+ * ── WHY IT IS HAND-WRITTEN ───────────────────────────────────────────────────────────────────────
+ *
+ * There is no OpenAPI document to generate from, and the API is a plain `Bun.serve` router rather
+ * than a framework with an RPC client to borrow. Writing the ~30 calls out is smaller than adding a
+ * spec, a generator and a build step to produce the same thing — and it keeps this package at ZERO
+ * dependencies, which is what makes it safe to install into a CI job that also runs a deploy.
+ *
+ * The API is NOT changed to suit this client. Everything here is the existing surface, and the
+ * anti-drift measure is `test/client.test.ts`: it boots the real server and drives this client
+ * against it, so a route or field that moves fails a test instead of quietly lying in a `.d.ts`.
+ *
+ * ── IT THROWS ────────────────────────────────────────────────────────────────────────────────────
+ *
+ * Opposite of the web UI's client, on purpose. A page renders a 409 as content; a script wants the
+ * line it wrote to either work or stop. Every non-2xx becomes a `PstackError` carrying the status and
+ * the parsed body, so `catch (e) { if (e.status === 409) … }` is the whole error-handling story.
+ *
+ * ── WHAT IS WORTH INSTALLING THIS FOR ────────────────────────────────────────────────────────────
+ *
+ * `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".
+ */
+import type { DeliveryRow, DeploymentRow, Health, HostVar, Job, Kind, Logs, NotifierRow, Readiness, Runtime, SpecMeta } 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 {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    readonly url: string;
+    constructor(status: number, url: string, body: Record<string, unknown>);
+}
+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_…`).
+     *
+     * Optional only because a server with no token configured is loopback-only dev mode. Anywhere
+     * 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;
+    /** Per request, in ms. Deploys are started, never awaited, so this bounds the HTTP call only. */
+    timeoutMs?: number;
+};
+/** `{ PR: '7' }` → `?PR=7`. These are the spec's variables, and `down` needs the SAME ones as `up`. */
+export type Vars = Record<string, string | number | undefined>;
+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>;
+    deployments: {
+        list: (vars?: Vars) => Promise<DeploymentRow[]>;
+        get: (id: string, vars?: Vars) => Promise<DeploymentRow & {
+            spec?: unknown;
+        }>;
+        /**
+         * Submit or replace. `spec` is an inline spec file; `specName` references a stored one — one
+         * or the other, never both, because a deployment has one source of truth.
+         */
+        put: (id: string, body: {
+            spec?: string;
+            specName?: string;
+            compose?: string;
+            env?: Record<string, string>;
+            vars?: Record<string, string>;
+        }) => Promise<{
+            id: string;
+            kind: Kind;
+            stack: string;
+        }>;
+        /** Forget the RECORD. Never tears anything down, and is refused while containers exist. */
+        remove: (id: string, vars?: Vars) => Promise<{
+            removed: string;
+            stack: string;
+        }>;
+        /** Starts a job and returns immediately. Follow it with `waitForJob`. */
+        up: (id: string, vars?: Vars) => Promise<Job>;
+        verify: (id: string, vars?: Vars) => Promise<Job>;
+        /**
+         * `force` is required for a `kind: shared` stack and is refused without it — `down` runs
+         * `compose down -v`, which on a shared deployment destroys the volumes every tenant depends on.
+         */
+        down: (id: string, body?: {
+            verify?: boolean;
+            force?: boolean;
+        }, vars?: Vars) => Promise<Job>;
+        runtime: (id: string, vars?: Vars) => Promise<Runtime>;
+        /**
+         * Is it SERVING yet — separate from "did the deploy job succeed", which only means the
+         * commands ran. `wait` (seconds, max 60) long-polls and returns as soon as it is terminal.
+         */
+        readiness: (id: string, o?: {
+            wait?: number;
+            refresh?: boolean;
+            timeout?: number;
+        } & {
+            vars?: Vars;
+        }) => Promise<Readiness & {
+            id: string;
+        }>;
+        logs: (id: string, o?: {
+            tail?: number;
+            service?: string;
+            since?: string;
+            timestamps?: boolean;
+            vars?: Vars;
+        }) => Promise<Logs>;
+    };
+    /** One container, not the service and not the stack. The name must be one this deployment owns. */
+    containers: {
+        start: (id: string, name: string, vars?: Vars) => Promise<{
+            container: string;
+            action: string;
+            note: string;
+        }>;
+        stop: (id: string, name: string, o?: {
+            grace?: number;
+            vars?: Vars;
+        }) => Promise<{
+            container: string;
+            action: string;
+            note: string;
+        }>;
+        restart: (id: string, name: string, o?: {
+            grace?: number;
+            vars?: Vars;
+        }) => Promise<{
+            container: string;
+            action: string;
+            note: string;
+        }>;
+    };
+    jobs: {
+        list: () => Promise<Job[]>;
+        get: (jobId: string) => Promise<Job>;
+        /** Kills the command in flight. Undoes NOTHING — run `verify` afterwards. */
+        cancel: (jobId: string) => Promise<{
+            cancelled: string;
+            by: string;
+            warning: string;
+        }>;
+    };
+    specs: {
+        list: () => Promise<SpecMeta[]>;
+        get: (name: string) => Promise<SpecMeta & {
+            spec?: string;
+            compose?: string;
+        }>;
+        put: (name: string, body: {
+            spec: string;
+            compose?: string;
+            description?: string;
+        }) => Promise<{
+            name: string;
+            replaced: boolean;
+        }>;
+        /** Refused while a deployment still references it. */
+        remove: (name: string) => Promise<{
+            deleted: string;
+        }>;
+    };
+    notifiers: {
+        list: () => Promise<NotifierRow[]>;
+        /** The 201 is the ONLY time a signing secret exists in a response; `null` for types that do not sign. */
+        create: (body: {
+            name: string;
+            type?: string;
+            events: string[];
+            config: Record<string, unknown>;
+        }) => Promise<{
+            notifier: NotifierRow;
+            secret: string | null;
+        }>;
+        setEnabled: (id: number, enabled: boolean) => Promise<{
+            notifier: NotifierRow;
+        }>;
+        remove: (id: number) => Promise<{
+            deleted: number;
+        }>;
+        test: (id: number) => Promise<{
+            ok: boolean;
+        }>;
+        deliveries: (id: number) => Promise<{
+            deliveries: DeliveryRow[];
+            queued: number;
+        }>;
+        /** Replay a past delivery: same event id, fresh signature, `x-pstack-redelivery: 1`. */
+        redeliver: (id: number, deliveryId: number) => Promise<{
+            redelivered: number;
+            event: string;
+            eventId: string;
+        }>;
+        /** Event names and per-type form fields — what a UI builds its pickers from. */
+        meta: () => Promise<{
+            events: string[];
+            wildcard: string;
+            types: Array<{
+                kind: string;
+                label: string;
+                signs: boolean;
+            }>;
+        }>;
+    };
+    hostVars: {
+        list: () => Promise<HostVar[]>;
+        /** `secret: true` is one-way — no route returns the value again. */
+        put: (name: string, value: string, secret?: boolean) => Promise<{
+            name: string;
+            secret: boolean;
+        }>;
+        remove: (name: string) => Promise<{
+            deleted: string;
+        }>;
+    };
+    /**
+     * Poll a job until it stops running.
+     *
+     * 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.
+     */
+    waitForJob(jobId: string, o?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<Job>;
+    /**
+     * Long-poll readiness until the stack settles.
+     *
+     * `watching` is not a failure and not an answer — it means "ask again", which is exactly the
+     * loop people get wrong by hand. Returns on `ready` / `failed` / `timedout`; the caller decides
+     * what each means for them.
+     */
+    waitForReady(id: string, o?: {
+        vars?: Vars;
+        timeoutMs?: number;
+    }): Promise<Readiness>;
+};
+export type PstackClient = ReturnType<typeof createClient>;
+/**
+ * Verify a webhook this control plane sent you.
+ *
+ * The half of the integration that lives in the RECEIVER, which is why it ships here rather than
+ * staying prose in the docs: the two mistakes it prevents are re-serialising the body before hashing
+ * (the signature covers the exact bytes) and forgetting the staleness check (the timestamp is signed
+ * precisely so a replayed request cannot claim a fresh one).
+ *
+ * `rawBody` must be the untouched request body — not a re-stringified object.
+ */
+export declare function verifyWebhook(args: {
+    secret: string;
+    rawBody: string;
+    headers: {
+        get(name: string): string | null;
+    } | Record<string, string | undefined>;
+    /** How old a delivery may be. Default 5 minutes; `0` disables the check. */
+    toleranceMs?: number;
+    now?: number;
+}): Promise<{
+    ok: boolean;
+    reason?: string;
+    event?: string;
+    redelivery: boolean;
+}>;

package/dist/index.js

@@ -0,0 +1,171 @@
+// src/index.ts
+class PstackError extends Error {
+  status;
+  body;
+  url;
+  constructor(status, url, body) {
+    super(typeof body.error === "string" ? body.error : `HTTP ${status} from ${url}`);
+    this.name = "PstackError";
+    this.status = status;
+    this.body = body;
+    this.url = url;
+  }
+}
+function qs(vars, extra = {}) {
+  const p = new URLSearchParams;
+  for (const [k, v] of Object.entries(vars ?? {}))
+    if (v !== undefined)
+      p.set(k, String(v));
+  for (const [k, v] of Object.entries(extra))
+    if (v !== undefined)
+      p.set(k, String(v));
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var enc = encodeURIComponent;
+function createClient(opts) {
+  const base = opts.baseUrl.replace(/\/$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  async function request(method, path, body) {
+    const url = `${base}${path}`;
+    const headers = {};
+    if (opts.token)
+      headers.authorization = `Bearer ${opts.token}`;
+    if (body !== undefined)
+      headers["content-type"] = "application/json";
+    const res = await doFetch(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined
+    });
+    const text = await res.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      throw new PstackError(res.status, url, {
+        error: `expected JSON, got ${res.status}: ${text.slice(0, 300)}`
+      });
+    }
+    if (!res.ok)
+      throw new PstackError(res.status, url, parsed ?? {});
+    return parsed ?? {};
+  }
+  const get = (p) => request("GET", p);
+  const post = (p, b) => request("POST", p, b ?? {});
+  const put = (p, b) => request("PUT", p, b);
+  const del = (p) => request("DELETE", p);
+  const client = {
+    request,
+    health: () => get("/api/health"),
+    deployments: {
+      list: (vars) => get(`/api/deployments${qs(vars)}`).then((r) => r.deployments),
+      get: (id, vars) => get(`/api/deployments/${enc(id)}${qs(vars)}`),
+      put: (id, body) => put(`/api/deployments/${enc(id)}`, body),
+      remove: (id, vars) => del(`/api/deployments/${enc(id)}${qs(vars)}`),
+      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),
+      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, {
+        tail: o.tail,
+        service: o.service,
+        since: o.since,
+        timestamps: o.timestamps ? 1 : undefined
+      })}`)
+    },
+    containers: {
+      start: (id, name, vars) => post(`/api/deployments/${enc(id)}/containers/${enc(name)}/start${qs(vars)}`),
+      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 })}`)
+    },
+    jobs: {
+      list: () => get("/api/jobs").then((r) => r.jobs),
+      get: (jobId) => get(`/api/jobs/${enc(jobId)}`).then((r) => r.job),
+      cancel: (jobId) => post(`/api/jobs/${enc(jobId)}/cancel`)
+    },
+    specs: {
+      list: () => get("/api/specs").then((r) => r.specs),
+      get: (name) => get(`/api/specs/${enc(name)}`),
+      put: (name, body) => put(`/api/specs/${enc(name)}`, body),
+      remove: (name) => del(`/api/specs/${enc(name)}`)
+    },
+    notifiers: {
+      list: () => get("/api/notifiers").then((r) => r.notifiers),
+      create: (body) => post("/api/notifiers", body),
+      setEnabled: (id, enabled) => request("PATCH", `/api/notifiers/${id}`, { enabled }),
+      remove: (id) => del(`/api/notifiers/${id}`),
+      test: (id) => post(`/api/notifiers/${id}/test`),
+      deliveries: (id) => get(`/api/notifiers/${id}/deliveries`),
+      redeliver: (id, deliveryId) => post(`/api/notifiers/${id}/deliveries/${deliveryId}/redeliver`),
+      meta: () => get("/api/notifiers/meta")
+    },
+    hostVars: {
+      list: () => get("/api/host-vars").then((r) => r.entries),
+      put: (name, value, secret = false) => put(`/api/host-vars/${enc(name)}`, { value, secret }),
+      remove: (name) => del(`/api/host-vars/${enc(name)}`)
+    },
+    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")
+          return job;
+        if (Date.now() > deadline) {
+          throw new PstackError(0, jobId, { error: `job ${jobId} still running after the wait timeout` });
+        }
+        await new Promise((r) => setTimeout(r, interval));
+      }
+    },
+    async waitForReady(id, o = {}) {
+      const deadline = Date.now() + (o.timeoutMs ?? 10 * 60000);
+      for (;; ) {
+        const r = await client.deployments.readiness(id, { wait: 30, vars: o.vars });
+        if (r.state !== "watching")
+          return r;
+        if (Date.now() > deadline) {
+          throw new PstackError(0, id, { error: `${id} was still converging after the wait timeout` });
+        }
+      }
+    }
+  };
+  return client;
+}
+async function verifyWebhook(args) {
+  const read = (name) => {
+    const h = args.headers;
+    if (typeof h.get === "function")
+      return h.get(name);
+    return h[name] ?? h[name.toLowerCase()] ?? null;
+  };
+  const signature = read("x-pstack-signature");
+  const timestamp = read("x-pstack-timestamp");
+  const redelivery = read("x-pstack-redelivery") === "1";
+  if (!signature || !timestamp)
+    return { ok: false, reason: "missing signature headers", redelivery };
+  const tolerance = args.toleranceMs ?? 5 * 60000;
+  if (tolerance > 0) {
+    const age = Math.abs((args.now ?? Date.now()) - Number(timestamp));
+    if (!Number.isFinite(age) || age > tolerance)
+      return { ok: false, reason: "stale timestamp", redelivery };
+  }
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(args.secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${args.rawBody}`));
+  const expected = `sha256=${[...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  if (signature.length !== expected.length)
+    return { ok: false, reason: "signature mismatch", redelivery };
+  let diff = 0;
+  for (let i = 0;i < expected.length; i++)
+    diff |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  if (diff !== 0)
+    return { ok: false, reason: "signature mismatch", redelivery };
+  return { ok: true, event: read("x-pstack-event") ?? undefined, redelivery };
+}
+export {
+  verifyWebhook,
+  createClient,
+  PstackError
+};

package/dist/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The shapes this client returns.
+ *
+ * Hand-written rather than generated, and deliberately NOT imported from the server package: this
+ * package must install without pulling in a control plane (and its Docker-shaped assumptions) as a
+ * dependency. The anti-drift measure is not a shared type — it is `test/client.test.ts`, which boots
+ * the REAL server and drives this client against it, so a field that changes shape fails a test
+ * rather than silently lying in a `.d.ts`.
+ *
+ * Every type is the JSON as it arrives. Nothing is renamed on the way through, because a client that
+ * 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';
+/** `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';
+export type Health = {
+    ok: boolean;
+    /** False only in loopback dev mode, where the server refuses to bind off-localhost. */
+    authEnforced: boolean;
+    hasUsers?: boolean;
+    dataDir: string;
+    version: string;
+};
+export type DeploymentRow = {
+    id: string;
+    kind: Kind;
+    specName?: string | null;
+    /** Null when the spec could not be resolved — see `unresolved`. */
+    stack: string | null;
+    /**
+     * `null` means the server could not determine it, NEVER "no".
+     *
+     * An unresolved spec has no stack name to look up, and a docker that did not answer is a different
+     * fact from "nothing is running". Treating either as `false` is how a live stack gets reported as
+     * torn down, so the tri-state is preserved all the way out to callers.
+     */
+    busy: boolean | null;
+    running: boolean | null;
+    /** Why the spec could not be resolved — usually a variable this call did not supply. */
+    unresolved?: string;
+    createdAt?: number;
+    updatedAt?: number;
+};
+export type StepResult = {
+    axis: string;
+    phase: 'requires' | 'up' | 'down' | 'assert_gone' | 'assert_live' | 'compose';
+    ok: boolean;
+    code: number;
+    message?: string;
+    skipped: boolean;
+};
+export type Job = {
+    id: string;
+    stack: string;
+    action: JobAction;
+    state: JobState;
+    startedAt: number;
+    endedAt?: number;
+    outcome?: {
+        ok: boolean;
+        steps: StepResult[];
+        outputs: Record<string, string>;
+    };
+    error?: string;
+    log?: Array<{
+        seq: number;
+        at: number;
+        level: string;
+        message: string;
+    }>;
+    cancelledBy?: string;
+};
+export type ContainerReadiness = {
+    name: string;
+    service: string | null;
+    state: string;
+    health: string | null;
+    /** `false` = it is running and nothing probed it. Not the same as "probed and passing". */
+    hasHealthcheck: boolean;
+    exitCode: number | null;
+    restartCount: number;
+    ready: boolean;
+    failed: boolean;
+    reason?: string;
+};
+export type Readiness = {
+    stack: string;
+    state: ReadinessState;
+    containers: ContainerReadiness[];
+    startedAt: number;
+    endedAt?: number;
+    /** False = docker stopped answering; the container fields are last-known, not current. */
+    reachable: boolean;
+    timeoutMs: number;
+};
+export type RuntimeContainer = {
+    id: string;
+    name: string;
+    service: string | null;
+    image: string;
+    state: string;
+    health: string | null;
+    exitCode: number | null;
+    restartCount: number;
+    networks: string[];
+    ingressIp: string | null;
+    ports: Array<{
+        containerPort: number;
+        protocol: string;
+        hostPort?: string;
+    }>;
+    traefikLabels: Record<string, string>;
+};
+export type RuntimeRoute = {
+    router: string;
+    container: string;
+    rule: string;
+    hosts: string[];
+    service: string | null;
+    port: number | null;
+    entrypoints: string | null;
+    tls: boolean;
+    certresolver: string | null;
+    priority: string | null;
+    target: string | null;
+};
+export type Runtime = {
+    id?: string;
+    stack: string;
+    containers: RuntimeContainer[];
+    routes: RuntimeRoute[];
+    findings: Array<{
+        level: 'error' | 'warn' | 'info';
+        message: string;
+    }>;
+    challenge: 'http01' | 'dns01' | 'unknown';
+    reachable: boolean;
+};
+export type Logs = {
+    stack: string;
+    tail: number;
+    service: string | null;
+    timestamps?: boolean;
+    since?: string | null;
+    until?: string | null;
+    lines?: number;
+    /** False = compose exited non-zero; `text` still carries whatever it printed. */
+    ok: boolean;
+    text: string;
+};
+export type SpecMeta = {
+    name: string;
+    kind: Kind;
+    description?: string;
+    requiredVars?: string[];
+    usedBy?: string[];
+    updatedAt?: number;
+};
+export type NotifierRow = {
+    id: number;
+    type: string;
+    name: string;
+    /** Secret-marked fields arrive masked; there is no read path for the real value. */
+    config: Record<string, unknown>;
+    events: string[];
+    enabled: boolean;
+    lastStatus?: string | null;
+    lastAt?: number | null;
+};
+export type DeliveryRow = {
+    id: number;
+    notifierId: number;
+    eventId: string;
+    event: string;
+    status: string;
+    attempts: number;
+    responseCode: number | null;
+    error: string | null;
+    createdAt: number;
+    updatedAt: number;
+    /** The envelope was stored, so this delivery can be replayed. */
+    replayable?: boolean;
+};
+export type HostVar = {
+    name: string;
+    /** Null for a secret — the server has no route that returns one. */
+    value: string | null;
+    secret: boolean;
+    updatedAt: number;
+};
+/** The four fields a webhook receiver gets. `data` is documented per event in docs/webhook-events.md. */
+export type PstackEvent = {
+    id: string;
+    event: string;
+    at: number;
+    data: Record<string, unknown>;
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@samyx/preview-stacks-client",
+  "version": "0.25.0",
+  "description": "Typed API client for a pstack control plane: deployments, jobs, readiness, containers, logs, notifiers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samishal1998/preview-stacks.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/samishal1998/preview-stacks/tree/main/packages/client#readme",
+  "license": "MIT",
+  "author": "sami.mishal",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "bun test && tsc --noEmit && bun run build",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "pstack",
+    "preview-environments",
+    "docker-compose",
+    "api-client",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}