@heyocomputer/hws 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+Versioned with the [`hws`](https://crates.io/crates/hws) crate; the two
+releases share a wire contract and are checked against the same app-lb fixtures.
+
+## 0.2.0
+
+First published release.
+
+### Renamed
+
+- The package is **`@heyocomputer/hws`**, the TypeScript twin of the `hws`
+  crate. It was `heyctl` in-tree and never published under that name.
+- `Hws` is the client class. `Heyctl` remains exported as the same class, and
+  `HwsOptions` as an alias of `HeyctlOptions`, so only the import changes.
+- Licensed Apache-2.0, like the rest of the repository.
+
+### Added — parity with hws 0.2.0
+
+- `whoami()` — the credential's tier, confinement and namespace.
+- `startRollout(id, { operationId, expectedRevision, spec })` and
+  `rollout(id, operationId)` — replace a spec by rolling a verified pool beside
+  the old one.
+- `discoveryStatus(id, { staged })`.
+- `cordonUpstream` / `uncordonUpstream` for static upstreams.
+- Namespace plugins: `namespacePlugins(ns)`, `installPlugin(ns, id, config?)`,
+  `uninstallPlugin(ns, id)`, `pluginInstalls(id)`.
+- Telemetry through the `obs` plugin: `obs(ns)` returns an `ObsClient` with
+  `fleet`, `deployment`, `logs` (with the `before` page cursor), `alerts`,
+  `createAlert` and `deleteAlert`.
+- Namespaces: `namespaces()`, `createNamespace`, `deleteNamespace`.
+- Workflows: `workflows`, `workflow`, `createWorkflow`, `replaceWorkflow`,
+  `deleteWorkflow`.
+- Auth providers: `authProviders(ns?)`, `authProvider`, `authProviderExists`,
+  `createAuthProvider`, `deleteAuthProvider`.
+- `startMountPull(id, force)`, `disks()`, `feedRss(ns)`, `probe(path)`.
+- Errors carry app-lb's machine-readable `code` when it sends one, e.g.
+  `plugin_not_installed` / `plugin_disabled` on a `ConflictError`.
+- Types: `WhoAmI`, `RolloutOperation`, `DiscoveryStatus`, `NamespaceEntry`,
+  `AuthProviderView`, `NamespacePlugin`, `PluginInstalls`, `NamespaceInstall`,
+  `ObsFleet`, `ObsFleetRow`, `ObsDeployment`, `ObsLogs`, `ObsLogRow`,
+  `ObsAlert`, `ObsMetricBucket`, `ObsLogBucket`, `ObsFreshness`, `LogQuery`,
+  `NewAlert`; `PluginView` gains `per_namespace` and `installed_in`.
+
+### Fixed
+
+- The wire-contract test now covers every fixture app-lb writes, including the
+  auth-provider and inherited-gate fixtures, a status's `site`, a gate's
+  `provider_ref` and the JWT login fields — declarations the types already had
+  but the test did not check.
+
+## 0.1.0
+
+The in-tree client: deployments, scaling, exec and shells, secrets, tokens,
+feeds, jobs, metrics, certificates and fleet plugins.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# @heyocomputer/hws
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript twin of [`hws`](https://crates.io/crates/hws), the app-lb SDK:
+register deployments, scale pools, run commands inside a microVM, attach an
+interactive shell, roll out new specs, and — through a namespace's installed
+plugins — read its telemetry.
+
+Same wire contract and the same version as the [Rust crate](../../heyctl)
+(source in this repo, published as `hws` on crates.io), which also ships the
+`heyctl` CLI. Both are checked against the golden fixtures app-lb's own tests
+write.
+
+```sh
+npm install @heyocomputer/hws
+```
+
+```ts
+import { Hws } from "@heyocomputer/hws";
+
+const lb = new Hws({
+  server: "127.0.0.1:9090",
+  token: process.env.APP_LB_TOKEN,
+});
+
+const { stdout, exit_code } = await lb.exec("sb-7f3a9c", "uname -a");
+```
+
+Node 18+, Bun, Deno and browsers. Everything uses `fetch`; shells use
+[`ws`](https://www.npmjs.com/package/ws) on the server and the native
+`WebSocket` in a browser.
+
+## Authenticating
+
+Prefer an **app-token**: scoped to particular deployments, revocable without
+restarting app-lb, optionally expiring. Basic auth also works and is unscoped —
+it is the operator credential, and the one that mints tokens.
+
+```ts
+const admin = new Hws({ server, user: "admin", password: process.env.PW! });
+
+const minted = await admin.mintToken({
+  name: "agent-runner",
+  admin: "admin",
+  deployments: ["sb-7f3a9c"],
+  expiresInSecs: 86_400,
+});
+
+// The secret is in the reply and nowhere else, ever — app-lb stores only its
+// hash and no endpoint reads it back.
+console.log(minted.token);
+```
+
+A token scoped to specific deployments is refused the fleet-wide routes —
+listing every deployment, the secret store, and minting — so it cannot widen
+itself. `/metrics` is the exception: rather than refusing a scoped token it
+narrows the answer to what that token can see.
+
+## Sandboxes
+
+```ts
+await lb.createDeployment({
+  id: "sb-7f3a9c",
+  routes: [],                       // unrouted: reached by exec and shell only
+  vm: { driver: "firecracker", port: 8080, disk_size_gb: 20 },
+  scaling: { min_replicas: 0, max_replicas: 1, idle_action: "retain" },
+});
+
+await lb.waitForReady("sb-7f3a9c", {
+  onProgress: (p) => console.log(`${p.healthy}/${p.desired} healthy, ${p.pending} booting`),
+});
+```
+
+`waitForReady` counts **healthy** backends, not `ready` — `ready` is the size of
+the pool, including a VM that is failing its health check, so waiting on it
+reports success for a deployment that cannot serve a request.
+
+## Shells
+
+```ts
+const shell = await lb.shell("sb-7f3a9c", { cols: 120, rows: 40 });
+shell.onData((bytes) => process.stdout.write(bytes));
+
+process.stdin.on("data", (d) => shell.write(d));
+process.stdout.on("resize", () =>
+  shell.resize(process.stdout.columns, process.stdout.rows));
+
+const { code, clean, error } = await shell.exit;
+```
+
+**Check `clean`, not `code === 0`.** app-lb reports an *unknown* exit code as
+`0`, which is what a VM dying under a live session looks like — so a crash and a
+logout are the same number. `clean` is false when an error preceded the exit.
+
+**There is no resume.** If the socket drops the session is gone; reconnecting
+gives a *new* shell. This package will not silently retry, because a retry that
+quietly discards a session is worse than an error.
+
+### In a browser
+
+A browser's `WebSocket` constructor cannot set headers, so a browser shell needs
+an **app-token**, which travels in the query string. app-lb accepts
+`?app_token=` on the shell route and nowhere else, for exactly that reason.
+
+A credential in a URL lands in access logs, proxy logs and browser history, so
+mint a short-lived one:
+
+```ts
+const ticket = await admin.mintToken({
+  name: `terminal ${user}`,
+  admin: "admin",
+  deployments: [sandboxId],
+  expiresInSecs: 120,
+});
+// hand `ticket.token` to the page, which opens the shell with it
+```
+
+Basic credentials cannot be used for a browser shell at all, and this package
+throws rather than silently failing the upgrade.
+
+## Errors
+
+Every failure is a subclass of `HeyctlError` carrying `status`, `retryable`
+and `isAuth`:
+
+| | |
+|---|---|
+| `UnauthorizedError` | 401 — missing, wrong, revoked or expired. app-lb does not distinguish those, so token ids cannot be enumerated. |
+| `ForbiddenError` | 403 — the credential was good, the scope was not. Re-presenting it will not help. |
+| `NotFoundError` | 404, carrying `kind` and the name |
+| `NoRunningVmError` | 409 from `exec`/`shell` with `wake: false` |
+| `ConflictError` | 409 — a job is already running, a secret is still referenced, a rollout's revision moved. `code` carries app-lb's reason when it gives one, e.g. `plugin_not_installed` / `plugin_disabled` |
+| `ColdStartTimeoutError` | 503 — no VM appeared in time. `retryable`. |
+| `UpstreamError` | 502 — the daemon failed. `retryable`. |
+| `MalformedResponseError` | a response that could not be interpreted |
+
+```ts
+try {
+  await lb.exec("sb-1", "make test", { wake: false });
+} catch (e) {
+  if (e instanceof NoRunningVmError) {
+    await lb.exec("sb-1", "make test");   // wake it after all
+  } else if (e.retryable) {
+    // ColdStartTimeout, Upstream, Transport
+  } else throw e;
+}
+```
+
+Note app-lb answers a failed request in **two** shapes: `{"error": "…"}` from
+its own handlers, and plain text for the 401 and every framework-level rejection
+(415 for a missing content-type, 422 for well-formed JSON of the wrong shape).
+This package parses both, so a caller never sees a JSON syntax error where an
+HTTP status was the actual answer.
+
+## Three things this package does not smooth over
+
+**A non-zero exit resolves.** `exec` rejects only when the command could not be
+*run*. Check `exit_code`.
+
+**`exec`'s timeout does not kill anything.** `timeoutSecs` bounds app-lb's call
+to the daemon; when it expires you get an `UpstreamError` and **the command
+keeps running in the guest**. The daemon offers no streaming and no
+cancellation, so output is buffered until it exits. The client-side deadline is
+sized to outlast the server's worst case — the command timeout plus a possible
+cold start — because abandoning a request app-lb is still serving turns a
+well-defined answer into an unexplained transport error.
+
+**Registering a deployment does not mean it has a certificate.** ACME issuance
+is asynchronous; poll `certs()`.
+
+## Rollouts
+
+`replaceDeployment` recycles the pool in place. To roll a new spec beside the
+old pool, verify it, and only then drain the old one:
+
+```ts
+const { rollout_revision, spec } = await lb.deployment("api");
+spec.vm!.image = "api-v2";
+const op = await lb.startRollout("api", {
+  operationId: crypto.randomUUID(),     // retry a lost reply with the same id
+  expectedRevision: rollout_revision!,  // 409 if anything changed it since
+  spec,
+});
+let now = op;
+while (now.status === "running") now = await lb.rollout("api", op.operation_id);
+```
+
+## Namespace plugins and telemetry
+
+Some plugins install per namespace. The operator enables one for the fleet; a
+namespace administrator installs it. Installing `obs` makes app-obs collect
+every deployment in the namespace, readable with the namespace's own token:
+
+```ts
+await lb.installPlugin("team-a", "obs");
+const obs = lb.obs("team-a");
+const fleet = await obs.fleet({ window: "1h" });
+let page = await obs.logs("web", { level: "error", limit: 100 });
+while (page.next_before_ms !== null) {
+  page = await obs.logs("web", { level: "error", limit: 100, before: page.next_before_ms });
+}
+```
+
+Before it is installed every `obs` call rejects with a `ConflictError` whose
+`code` is `plugin_not_installed` (or `plugin_disabled` while the operator has it
+off).
+
+`whoami()` says what the server makes of the credential: its tier, whether it is
+confined, and to which namespace.
+
+## Building deployments
+
+Writes take the spec as an object and send it verbatim. Read with
+`deployment()`, edit `status.spec`, and pass that back — `PUT` replaces the
+*whole* spec, so anything dropped in between is genuinely dropped.
+
+```ts
+const { spec } = await lb.deployment("api");
+spec.vm!.image = "api-v2";
+await lb.replaceDeployment("api", spec);
+```
+
+## Development
+
+```sh
+npm install
+npm test          # builds, then unit tests + the wire-contract check
+```
+
+The wire-contract test reads `testdata/wire/*.json` — fixtures written by
+app-lb's own response types — and asserts every key in them is declared in
+`src/types.ts`. To a JS client an unknown field and an absent one look
+identical, which is exactly how five fields once went missing from the Rust
+client without a test failing. A field app-lb starts sending now fails this test
+instead of going silently unread.
+
+`examples/e2e.mjs` runs the whole surface against a live app-lb.
+
+`Heyctl` is still exported as an alias of `Hws`, so code written against the
+pre-0.2 package name keeps compiling after changing its import.

package/dist/client.d.ts

@@ -0,0 +1,371 @@
+import { type Credential } from "./errors.js";
+import { ObsClient } from "./obs.js";
+import type { AdminScope, AuthProviderView, CertStatus, DiscoveryStatus, DiskInventory, NamespaceEntry, NamespacePlugin, PluginInstalls, RolloutOperation, UpstreamTrafficStatus, WhoAmI, WorkflowSpec, DeploymentSpec, DeploymentStatus, EvictOutcome, ExecOutput, JobRecord, MetricsResponse, MintedToken, PluginView, Ingress, SecretSummary, TokenSummary, FeedEvent, FeedIndexEntry } from "./types.js";
+import type { Shell, ShellOptions } from "./shell.js";
+import type { WaitForJobOptions, WaitForReadyOptions } from "./wait.js";
+/** app-lb's own default `cold_start_timeout_secs`. */
+export declare const ASSUMED_COLD_START_MS = 120000;
+/** How to authenticate. */
+export type Auth = {
+    kind: "none";
+}
+/** The operator credential. Unscoped, and the one that mints tokens. */
+ | {
+    kind: "basic";
+    user: string;
+    password: string;
+}
+/** An app-token. Scoped, revocable — the normal choice for a program. */
+ | {
+    kind: "token";
+    token: string;
+};
+export interface HeyctlOptions {
+    /** A URL, or a bare `host:port`. */
+    server: string;
+    /** Shorthand for `auth: { kind: "token", token }`. */
+    token?: string;
+    user?: string;
+    password?: string;
+    auth?: Auth;
+    /** Per-request deadline. `exec` computes its own, larger, one. */
+    timeoutMs?: number;
+    /** Swapped in for tests. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Which admin routes a server is gating. */
+export interface Gates {
+    view: boolean;
+    crud: boolean;
+}
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Bounds app-lb's call to the daemon. Clamped server-side to 1..3600. */
+    timeoutSecs?: number;
+    /** Boot or resume a VM if none is running. Default true. */
+    wake?: boolean;
+    /** Override the client-side deadline. */
+    patienceMs?: number;
+    signal?: AbortSignal;
+}
+export interface MetricsQuery {
+    deployment?: string;
+    prefix?: string;
+    /** Drop per-VM detail, which is most of the payload. */
+    summary?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface NewToken {
+    name: string;
+    admin?: AdminScope;
+    /**
+     * Confine the token to one namespace. With no `deployments` it reaches
+     * every deployment in the namespace — and nothing outside it, ever.
+     */
+    namespace?: string;
+    /** Deployment ids, or `["*"]`. Defaults to none, which can reach nothing. */
+    deployments?: string[];
+    expiresInSecs?: number;
+    /**
+     * Valid on every server that mirrors this control plane's tokens, not only
+     * the one minting it. Only a control-plane app-lb (one with gateways
+     * configured) accepts it; anywhere else the mint is refused with 409.
+     */
+    allServers?: boolean;
+}
+/** Accept `host:port` as well as a URL, and drop a trailing slash. */
+export declare function normalizeServer(server: string): string;
+/**
+ * A client for one app-lb.
+ *
+ * ```ts
+ * const lb = new Heyctl({ server: "127.0.0.1:9090", token: process.env.APP_LB_TOKEN });
+ * const { stdout } = await lb.exec("sb-7f3a9c", "uname -a");
+ * ```
+ */
+export declare class Heyctl {
+    readonly server: string;
+    /** @internal */ readonly auth: Auth;
+    private readonly timeoutMs;
+    private readonly doFetch;
+    constructor(opts: HeyctlOptions);
+    /**
+     * The exact `Authorization` header, or undefined.
+     *
+     * @internal app-lb compares the Basic header **byte for byte** against a
+     * string it precomputed at startup — it never base64-decodes it. So this must
+     * be standard base64 with padding, one space after `Basic`, that
+     * capitalisation. A re-encoded-but-equivalent header is rejected.
+     */
+    authHeader(): string | undefined;
+    /** @internal */
+    credential(): Credential;
+    private send;
+    /** @internal Raw JSON for a route, with failures raised as typed errors. */
+    request<T>(method: string, path: string, opts?: {
+        body?: unknown;
+        kind?: string;
+        name?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        /**
+         * Whether a success carries JSON. Not every route does: `/healthz`
+         * answers `ok\n` as plain text, and a `204` has no body at all — parsing
+         * those would turn a perfectly good response into a syntax error.
+         */
+        expect?: "json" | "nothing";
+    }): Promise<T>;
+    /** Never gated, so this proves reachability without a credential. */
+    healthz(): Promise<void>;
+    /**
+     * Which tiers this server gates, probed **anonymously** — the question is
+     * what an unauthenticated caller is refused, which is what says whether the
+     * gate is on at all.
+     */
+    gates(): Promise<Gates>;
+    /**
+     * What the server makes of this client's credential: its tier, whether it is
+     * confined, and to which namespace. Needs no tier, so it answers even for a
+     * token every other route refuses.
+     */
+    whoami(signal?: AbortSignal): Promise<WhoAmI>;
+    /**
+     * The status a `GET` answers with, treating a 4xx as an answer rather than an
+     * error, plus whatever the server said about it (`error — detail`).
+     */
+    probe(path: string, signal?: AbortSignal): Promise<{
+        status: number;
+        detail?: string;
+    }>;
+    deployments(signal?: AbortSignal): Promise<DeploymentStatus[]>;
+    deployment(id: string, signal?: AbortSignal): Promise<DeploymentStatus>;
+    /** Whether a deployment exists, without treating absence as an error. */
+    deploymentExists(id: string): Promise<boolean>;
+    /**
+     * Register or replace a deployment.
+     *
+     * app-lb answers `201` even when this replaced an existing one, so the status
+     * does not distinguish create from update. Certificate issuance is
+     * asynchronous: success here does not mean a certificate exists yet.
+     */
+    createDeployment(spec: DeploymentSpec, signal?: AbortSignal): Promise<DeploymentStatus>;
+    /**
+     * Replace a whole spec.
+     *
+     * `PUT` replaces everything, so read with {@link deployment}, edit
+     * `status.spec`, and pass that back — anything dropped in between is
+     * genuinely dropped.
+     */
+    replaceDeployment(id: string, spec: DeploymentSpec, signal?: AbortSignal): Promise<DeploymentStatus>;
+    /** A shallow merge onto the current scaling policy. Managed pools only. */
+    patchScaling(id: string, patch: Record<string, unknown>, signal?: AbortSignal): Promise<DeploymentStatus>;
+    deleteDeployment(id: string, signal?: AbortSignal): Promise<void>;
+    /** Evict one VM. `force` kills immediately; otherwise it drains. */
+    evictVm(id: string, sandboxId: string, force?: boolean, signal?: AbortSignal): Promise<EvictOutcome>;
+    /**
+     * Stop new requests to one static upstream. Existing requests finish; watch
+     * `in_flight` on the result to observe the drain.
+     */
+    cordonUpstream(id: string, upstream: string, opts?: {
+        force?: boolean;
+        reason?: string;
+        signal?: AbortSignal;
+    }): Promise<UpstreamTrafficStatus>;
+    /** Remove an administrative drain. An unhealthy upstream stays excluded until it recovers. */
+    uncordonUpstream(id: string, upstream: string, signal?: AbortSignal): Promise<UpstreamTrafficStatus>;
+    /**
+     * Replace a managed deployment's spec by rolling a fresh pool beside the old
+     * one, verifying it, and only then draining the old one.
+     *
+     * `expectedRevision` is the deployment's `rollout_revision` as last read; the
+     * rollout is refused (409) if anything changed it since. `operationId` makes
+     * the call idempotent — retry a lost reply with the same id. Answers `202`;
+     * poll {@link rollout} until `status` is no longer `running`.
+     */
+    startRollout(id: string, req: {
+        operationId: string;
+        expectedRevision: string;
+        spec: DeploymentSpec | Record<string, unknown>;
+    }, signal?: AbortSignal): Promise<RolloutOperation>;
+    rollout(id: string, operationId: string, signal?: AbortSignal): Promise<RolloutOperation>;
+    /**
+     * What this gateway publishes for the deployment to discovery. `staged` asks
+     * about the spec a pending change would publish instead of the live one.
+     */
+    discoveryStatus(id: string, opts?: {
+        staged?: boolean;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryStatus>;
+    /**
+     * Run a command in the deployment's VM and wait for it to finish.
+     *
+     * Two things to know:
+     *
+     * - **A non-zero exit resolves.** The command ran; it failed. Only an
+     *   inability to run it rejects. Check `exitCode`.
+     * - **The timeout does not kill anything.** `timeoutSecs` bounds app-lb's own
+     *   call to the daemon; when it expires you get an {@link UpstreamError} and
+     *   the command **keeps running in the guest**. The daemon offers no
+     *   streaming and no cancellation, so output is buffered until it exits.
+     */
+    exec(id: string, command: string, opts?: ExecOptions): Promise<ExecOutput>;
+    /** Every CI workflow object. */
+    workflows(signal?: AbortSignal): Promise<WorkflowSpec[]>;
+    workflow(id: string, signal?: AbortSignal): Promise<WorkflowSpec>;
+    /** Create or replace. Sends the object as given, unknown fields included. */
+    createWorkflow(spec: WorkflowSpec | Record<string, unknown>, signal?: AbortSignal): Promise<WorkflowSpec>;
+    replaceWorkflow(id: string, spec: WorkflowSpec | Record<string, unknown>, signal?: AbortSignal): Promise<WorkflowSpec>;
+    deleteWorkflow(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * The declared auth providers this credential can see, or those of one
+     * namespace. Narrows itself server-side rather than refusing.
+     */
+    authProviders(namespace?: string, signal?: AbortSignal): Promise<AuthProviderView[]>;
+    /** One provider. Unique within its namespace, so both halves are required. */
+    authProvider(namespace: string, name: string, signal?: AbortSignal): Promise<AuthProviderView>;
+    authProviderExists(namespace: string, name: string): Promise<boolean>;
+    /**
+     * Declare or replace a provider (upserts, keeping `created_at`). The body may
+     * carry request-only `preset`/`secret` conveniences the server expands.
+     */
+    createAuthProvider(spec: Record<string, unknown>, signal?: AbortSignal): Promise<AuthProviderView>;
+    /** Refused (409) while a deployment's gate still inherits it. */
+    deleteAuthProvider(namespace: string, name: string, signal?: AbortSignal): Promise<void>;
+    /** The namespaces this credential can see, narrowed server-side. */
+    namespaces(signal?: AbortSignal): Promise<NamespaceEntry[]>;
+    /** Declare a namespace. Idempotent; fleet scope and `admin` server-side. */
+    createNamespace(spec: {
+        name: string;
+        description?: string;
+        [extra: string]: unknown;
+    }, signal?: AbortSignal): Promise<unknown>;
+    /** Undeclare a namespace. Refused while deployments are still in it. */
+    deleteNamespace(name: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * The plugins that install per namespace, and whether each is switched on for
+     * the fleet (`enabled`) and installed here (`installed`).
+     */
+    namespacePlugins(namespace: string, signal?: AbortSignal): Promise<NamespacePlugin[]>;
+    /**
+     * Install a plugin into a namespace, or replace its per-namespace config.
+     * Idempotent. Needs `admin` over the whole namespace; a `ConflictError` with
+     * `code: "plugin_disabled"` while the operator has it off for the fleet.
+     */
+    installPlugin(namespace: string, id: string, config?: unknown, signal?: AbortSignal): Promise<NamespacePlugin>;
+    /** Uninstall. For `obs` this stops collection; what was collected ages out. */
+    uninstallPlugin(namespace: string, id: string, signal?: AbortSignal): Promise<NamespacePlugin>;
+    /** Every namespace a plugin is installed in. Fleet scope only. */
+    pluginInstalls(id: string, signal?: AbortSignal): Promise<PluginInstalls>;
+    /** One namespace's telemetry through the `obs` plugin. Makes no request. */
+    obs(namespace: string): ObsClient;
+    /**
+     * The secrets the credential may see: one namespace when `namespace` is
+     * given, else every namespace within its reach. Secrets are walled by
+     * namespace exactly as deployments are.
+     */
+    secrets(namespace?: string, signal?: AbortSignal): Promise<SecretSummary[]>;
+    secret(id: string, namespace?: string, signal?: AbortSignal): Promise<SecretSummary>;
+    /**
+     * Values enter here and are never readable again. `namespace` defaults to
+     * `default`; a confined credential must reach it as an admin.
+     */
+    putSecret(spec: {
+        id: string;
+        namespace?: string;
+        description?: string;
+        data: Record<string, string>;
+    }, signal?: AbortSignal): Promise<SecretSummary>;
+    /** `null` for a value deletes that key; absent keys are left alone. */
+    patchSecret(id: string, patch: {
+        data?: Record<string, string | null>;
+        description?: string;
+    }, namespace?: string, signal?: AbortSignal): Promise<SecretSummary>;
+    deleteSecret(id: string, force?: boolean, namespace?: string, signal?: AbortSignal): Promise<void>;
+    /** Where DNS should point a deployment's hostname — this LB's public addresses. */
+    ingress(signal?: AbortSignal): Promise<Ingress>;
+    /**
+     * Mint a token.
+     *
+     * **The secret in the reply is shown once** — app-lb keeps only its hash and
+     * no endpoint reads it back. Store it now or mint another.
+     *
+     * Both scope fields default to nothing: a token minted with no scope can do
+     * nothing, which is a harmless mistake. The other default would turn a
+     * forgotten field into fleet-wide credentials.
+     */
+    mintToken(req: NewToken, signal?: AbortSignal): Promise<MintedToken>;
+    plugins(signal?: AbortSignal): Promise<PluginView[]>;
+    plugin(id: string, signal?: AbortSignal): Promise<PluginView>;
+    /**
+     * Write a plugin's record. Omit `config` to keep the stored one. Resolves
+     * when the record is saved even if applying it failed — check `last_error`.
+     */
+    setPlugin(id: string, enabled: boolean, config?: unknown, signal?: AbortSignal): Promise<PluginView>;
+    tokens(signal?: AbortSignal): Promise<TokenSummary[]>;
+    token(id: string, signal?: AbortSignal): Promise<TokenSummary>;
+    /**
+     * Re-scope a token **without changing its secret**, so narrowing a credential
+     * does not mean redistributing it. Pass `expires_at: null` to clear an expiry.
+     */
+    patchToken(id: string, patch: {
+        name?: string;
+        admin?: AdminScope;
+        /** `null` lifts the namespace wall; a string moves it. */
+        namespace?: string | null;
+        deployments?: string[];
+        expires_at?: number | null;
+    }, signal?: AbortSignal): Promise<TokenSummary>;
+    /** Effective on the next request — verification is a lookup, not a signature. */
+    revokeToken(id: string, signal?: AbortSignal): Promise<void>;
+    /** The namespaces that have feed events, narrowed to this credential. */
+    feeds(signal?: AbortSignal): Promise<FeedIndexEntry[]>;
+    /** A namespace's feed events as structured data, newest first. */
+    feedEvents(namespace: string, signal?: AbortSignal): Promise<FeedEvent[]>;
+    /** A namespace's feed as the RSS document a reader would fetch, verbatim. */
+    feedRss(namespace: string, signal?: AbortSignal): Promise<string>;
+    startBuild(id: string, ref?: string, signal?: AbortSignal): Promise<JobRecord>;
+    startPull(id: string, ref?: string, force?: boolean, signal?: AbortSignal): Promise<JobRecord>;
+    /**
+     * Unpack a managed deployment's guest mounts and roll the pool onto them.
+     * One job covers every mount, so there is no `ref` override.
+     */
+    startMountPull(id: string, force?: boolean, signal?: AbortSignal): Promise<JobRecord>;
+    startUpdate(id: string, signal?: AbortSignal): Promise<JobRecord>;
+    jobs(signal?: AbortSignal): Promise<JobRecord[]>;
+    deploymentJobs(id: string, signal?: AbortSignal): Promise<JobRecord[]>;
+    /** A 404 can mean the job aged out of the bounded history, not that it never existed. */
+    job(jobId: string, signal?: AbortSignal): Promise<JobRecord>;
+    /**
+     * The unfiltered response is megabytes at fleet scale, so prefer `summary`
+     * and paging. `fleet`, `global` and `host` always describe everything the
+     * credential can see, never the page.
+     */
+    metrics(query?: MetricsQuery, signal?: AbortSignal): Promise<MetricsResponse>;
+    /**
+     * Attach an interactive shell.
+     *
+     * Everything that can fail with a status does so *before* the upgrade, so a
+     * socket that opens is a shell that attached: a 404, 403, 409 or 503 arrives
+     * as a typed error, never as an unexplained close.
+     */
+    shell(id: string, opts?: ShellOptions): Promise<Shell>;
+    /** Poll a job until it finishes. See {@link waitForJob}. */
+    waitForJob(jobId: string, opts?: WaitForJobOptions): Promise<JobRecord>;
+    /** Poll a deployment until its pool has converged. See {@link waitForReady}. */
+    waitForReady(id: string, opts?: WaitForReadyOptions): Promise<DeploymentStatus>;
+    certs(signal?: AbortSignal): Promise<CertStatus[]>;
+    /**
+     * The host's disk inventory. Check `complete` before acting on it: an
+     * incomplete inventory classified nothing.
+     */
+    disks(signal?: AbortSignal): Promise<DiskInventory>;
+    /**
+     * Every deployment id, a page at a time.
+     *
+     * Walks `/metrics` rather than `GET /deployments`, which is unpaged and
+     * returns whole specs — megabytes at fleet scale.
+     */
+    deploymentIds(pageSize?: number, signal?: AbortSignal): Promise<string[]>;
+}