@heyocomputer/hws 0.0.0-stage → 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What can go wrong, as something a caller can branch on.
+ *
+ * app-lb answers a failed request in one of two ways and a client has to handle
+ * both:
+ *
+ *  - `{"error": "…"}` — every handler-level 4xx/5xx.
+ *  - **plain text** — the `401`, and every axum extractor rejection: `415` for a
+ *    missing content-type, `400` for malformed JSON, `422` for well-formed JSON
+ *    of the wrong shape.
+ *
+ * So {@link fromResponse} tries the envelope, falls back to the body as text,
+ * and falls back again to the status. It never assumes JSON.
+ */
+/** What was presented, so a 401 can say something useful about it. */
+export type Credential = "none" | "basic" | "token";
+export declare class HeyctlError extends Error {
+    /** The HTTP status behind this, when there was one. */
+    readonly status?: number;
+    /**
+     * The machine-readable reason app-lb put beside `error`, when it gave one —
+     * e.g. `plugin_not_installed` or `plugin_disabled` on a namespace plugin's
+     * 409. Branch on this rather than on the message.
+     */
+    code?: string;
+    constructor(message: string, status?: number);
+    /** Whether retrying the identical request could plausibly succeed. */
+    get retryable(): boolean;
+    /** Whether this is a credential problem rather than a request problem. */
+    get isAuth(): boolean;
+}
+/**
+ * `401`. Missing, wrong, revoked or expired — app-lb does not distinguish
+ * those, deliberately, so token ids cannot be enumerated by watching which
+ * failure comes back.
+ */
+export declare class UnauthorizedError extends HeyctlError {
+    readonly presented: Credential;
+    constructor(presented: Credential);
+    get isAuth(): boolean;
+}
+/** `403`. The credential was good and its scope was not. */
+export declare class ForbiddenError extends HeyctlError {
+    constructor(message: string);
+    get isAuth(): boolean;
+}
+export declare class NotFoundError extends HeyctlError {
+    readonly kind: string;
+    readonly name_: string;
+    constructor(kind: string, name: string);
+}
+/** `409` — a job is already running, or a secret is still referenced. */
+export declare class ConflictError extends HeyctlError {
+    constructor(message: string);
+}
+/**
+ * `409` from exec/shell with `wake: false` and nothing running. Separate from
+ * {@link ConflictError} because the remedy is specific: retry with `wake`.
+ */
+export declare class NoRunningVmError extends HeyctlError {
+    readonly deployment: string;
+    constructor(deployment: string);
+}
+/** `503` — asked for a VM, none appeared inside `cold_start_timeout_secs`. */
+export declare class ColdStartTimeoutError extends HeyctlError {
+    readonly deployment: string;
+    constructor(deployment: string);
+    get retryable(): boolean;
+}
+/**
+ * `502` — app-lb reached the daemon and the daemon failed.
+ *
+ * For `exec` this includes app-lb's own call timing out, in which case **the
+ * command is still running in the guest**.
+ */
+export declare class UpstreamError extends HeyctlError {
+    constructor(message: string);
+    get retryable(): boolean;
+}
+/** Any other `{"error": …}` this package has no specific class for. */
+export declare class ApiError extends HeyctlError {
+}
+/**
+ * A response that could not be interpreted: an extractor rejection, an
+ * empty-bodied router 404/405, or an intermediary's error page.
+ */
+export declare class MalformedResponseError extends HeyctlError {
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/** The request never got an answer. */
+export declare class TransportError extends HeyctlError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+    get retryable(): boolean;
+}
+/** The WebSocket carrying a shell failed. */
+export declare class ShellError extends HeyctlError {
+}
+/** A `wait*` helper gave up. */
+export declare class TimeoutError extends HeyctlError {
+    constructor(what: string, afterMs: number);
+}
+/** Bad input, caught before anything was sent. */
+export declare class InvalidRequestError extends HeyctlError {
+}
+/**
+ * Turn a failed response into a typed error.
+ *
+ * `kind`/`name` describe what was addressed, so a 404 can say
+ * `no deployment "demo"` rather than `HTTP 404`.
+ */
+export declare function fromResponse(status: number, body: string, kind: string, name: string, presented: Credential): HeyctlError;

package/dist/errors.js

@@ -0,0 +1,228 @@
+/**
+ * What can go wrong, as something a caller can branch on.
+ *
+ * app-lb answers a failed request in one of two ways and a client has to handle
+ * both:
+ *
+ *  - `{"error": "…"}` — every handler-level 4xx/5xx.
+ *  - **plain text** — the `401`, and every axum extractor rejection: `415` for a
+ *    missing content-type, `400` for malformed JSON, `422` for well-formed JSON
+ *    of the wrong shape.
+ *
+ * So {@link fromResponse} tries the envelope, falls back to the body as text,
+ * and falls back again to the status. It never assumes JSON.
+ */
+export class HeyctlError extends Error {
+    /** The HTTP status behind this, when there was one. */
+    status;
+    /**
+     * The machine-readable reason app-lb put beside `error`, when it gave one —
+     * e.g. `plugin_not_installed` or `plugin_disabled` on a namespace plugin's
+     * 409. Branch on this rather than on the message.
+     */
+    code;
+    constructor(message, status) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+        // Required for `instanceof` to work on a subclassed Error when the package
+        // is transpiled down to ES5 — without it every subclass collapses to Error.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** Whether retrying the identical request could plausibly succeed. */
+    get retryable() {
+        return false;
+    }
+    /** Whether this is a credential problem rather than a request problem. */
+    get isAuth() {
+        return false;
+    }
+}
+/**
+ * `401`. Missing, wrong, revoked or expired — app-lb does not distinguish
+ * those, deliberately, so token ids cannot be enumerated by watching which
+ * failure comes back.
+ */
+export class UnauthorizedError extends HeyctlError {
+    presented;
+    constructor(presented) {
+        super({
+            none: "authentication required, and no credential was sent — supply a username and password, or an app-token",
+            basic: "the username or password was not accepted",
+            token: "the app-token was not accepted — it may be wrong, revoked or expired (app-lb does not say which)",
+        }[presented], 401);
+        this.presented = presented;
+    }
+    get isAuth() {
+        return true;
+    }
+}
+/** `403`. The credential was good and its scope was not. */
+export class ForbiddenError extends HeyctlError {
+    constructor(message) {
+        super(message, 403);
+    }
+    get isAuth() {
+        return true;
+    }
+}
+export class NotFoundError extends HeyctlError {
+    kind;
+    name_;
+    constructor(kind, name) {
+        super(`no ${kind} ${JSON.stringify(name)}`, 404);
+        this.kind = kind;
+        this.name_ = name;
+    }
+}
+/** `409` — a job is already running, or a secret is still referenced. */
+export class ConflictError extends HeyctlError {
+    constructor(message) {
+        super(message, 409);
+    }
+}
+/**
+ * `409` from exec/shell with `wake: false` and nothing running. Separate from
+ * {@link ConflictError} because the remedy is specific: retry with `wake`.
+ */
+export class NoRunningVmError extends HeyctlError {
+    deployment;
+    constructor(deployment) {
+        super(`deployment ${JSON.stringify(deployment)} has no running VM (retry with wake)`, 409);
+        this.deployment = deployment;
+    }
+}
+/** `503` — asked for a VM, none appeared inside `cold_start_timeout_secs`. */
+export class ColdStartTimeoutError extends HeyctlError {
+    deployment;
+    constructor(deployment) {
+        super(`deployment ${JSON.stringify(deployment)} had no VM ready within its cold-start timeout`, 503);
+        this.deployment = deployment;
+    }
+    get retryable() {
+        return true;
+    }
+}
+/**
+ * `502` — app-lb reached the daemon and the daemon failed.
+ *
+ * For `exec` this includes app-lb's own call timing out, in which case **the
+ * command is still running in the guest**.
+ */
+export class UpstreamError extends HeyctlError {
+    constructor(message) {
+        super(message, 502);
+    }
+    get retryable() {
+        return true;
+    }
+}
+/** Any other `{"error": …}` this package has no specific class for. */
+export class ApiError extends HeyctlError {
+}
+/**
+ * A response that could not be interpreted: an extractor rejection, an
+ * empty-bodied router 404/405, or an intermediary's error page.
+ */
+export class MalformedResponseError extends HeyctlError {
+    body;
+    constructor(status, body) {
+        super(body ? `unexpected HTTP ${status}: ${body}` : `unexpected HTTP ${status}`, status);
+        this.body = body;
+    }
+}
+/** The request never got an answer. */
+export class TransportError extends HeyctlError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+    get retryable() {
+        return true;
+    }
+}
+/** The WebSocket carrying a shell failed. */
+export class ShellError extends HeyctlError {
+}
+/** A `wait*` helper gave up. */
+export class TimeoutError extends HeyctlError {
+    constructor(what, afterMs) {
+        super(`${what} did not finish within ${Math.round(afterMs / 1000)}s`);
+    }
+}
+/** Bad input, caught before anything was sent. */
+export class InvalidRequestError extends HeyctlError {
+}
+/**
+ * Turn a failed response into a typed error.
+ *
+ * `kind`/`name` describe what was addressed, so a 404 can say
+ * `no deployment "demo"` rather than `HTTP 404`.
+ */
+export function fromResponse(status, body, kind, name, presented) {
+    // The envelope if there is one; otherwise the body verbatim, which is where
+    // the plain-text rejections live.
+    let message;
+    let code;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed.error === "string" && parsed.error.trim()) {
+            message = parsed.error;
+        }
+        if (parsed && typeof parsed.code === "string" && parsed.code) {
+            code = parsed.code;
+        }
+    }
+    catch {
+        // Not JSON. Normal — see the module comment.
+    }
+    const hadEnvelope = message !== undefined;
+    if (message === undefined) {
+        const trimmed = body.trim();
+        message = trimmed || undefined;
+    }
+    const err = classify(status, message, hadEnvelope, kind, name, presented);
+    if (code !== undefined)
+        err.code = code;
+    return err;
+}
+function classify(status, message, hadEnvelope, kind, name, presented) {
+    switch (status) {
+        case 401:
+            return new UnauthorizedError(presented);
+        case 403:
+            return new ForbiddenError(message ?? "forbidden");
+        case 404:
+            // A router-level 404 (an unknown *path*) has no envelope and no useful
+            // body; a handler-level one names the thing. Reporting the former as a
+            // missing object sends people looking for the wrong bug.
+            if (message === undefined || message.startsWith("no ")) {
+                return new NotFoundError(kind, name);
+            }
+            return new MalformedResponseError(status, message);
+        case 409:
+            // Both shapes are 409 and the remedies differ, so the message is what
+            // tells them apart. If app-lb rewords it the fallback is ConflictError,
+            // which is less specific rather than wrong.
+            return message?.includes("no running VM")
+                ? new NoRunningVmError(name)
+                : new ConflictError(message ?? "conflict");
+        case 503:
+            return new ColdStartTimeoutError(name);
+        case 502:
+            return new UpstreamError(message ?? "the daemon did not answer");
+        case 400:
+        case 415:
+        case 422:
+            // Without an envelope these are extractor rejections: the request was
+            // malformed before a handler saw it.
+            if (!hadEnvelope)
+                return new MalformedResponseError(status, message ?? "");
+            return new ApiError(message, status);
+        default:
+            return message === undefined
+                ? new MalformedResponseError(status, "")
+                : new ApiError(message, status);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@heyocomputer/hws` — the TypeScript twin of the `hws` crate: a client for
+ * the app-lb admin API.
+ *
+ * app-lb is a load balancer for heyvm Firecracker/KVM microVMs. This package
+ * drives it: register deployments, scale pools, run commands inside a VM, and
+ * attach an interactive shell.
+ *
+ * ```ts
+ * import { Hws } from "@heyocomputer/hws";
+ *
+ * const lb = new Hws({ server: "127.0.0.1:9090", token: process.env.APP_LB_TOKEN });
+ * const { stdout } = await lb.exec("sb-7f3a9c", "uname -a");
+ * ```
+ *
+ * # Authentication
+ *
+ * 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.
+ *
+ * # Runtimes
+ *
+ * Node 18+, Bun, Deno and browsers. Everything uses `fetch`. Shells use `ws` on
+ * the server and the native `WebSocket` in a browser — and because a browser
+ * cannot set headers on an upgrade, a browser shell needs an **app-token**,
+ * which travels in the query string. Mint a short-lived one for that.
+ *
+ * # What this package does not smooth over
+ *
+ * - A non-zero exit code from {@link Heyctl.exec} resolves, it does not
+ *   reject. The command ran; it failed.
+ * - `exec`'s timeout does not kill anything. It bounds app-lb's call to the
+ *   daemon — on expiry you get an `UpstreamError` and the command **keeps
+ *   running in the guest**.
+ * - A shell socket has no resume. If it drops the session is gone; reconnecting
+ *   gives a *new* shell.
+ */
+export { Heyctl, normalizeServer, ASSUMED_COLD_START_MS } from "./client.js";
+/**
+ * The client under the package's name. `Heyctl` stays exported for code
+ * written against the earlier name; they are the same class.
+ */
+export { Heyctl as Hws } from "./client.js";
+export type { Auth, ExecOptions, Gates, MetricsQuery, NewToken, HeyctlOptions, HeyctlOptions as HwsOptions, } from "./client.js";
+export { ObsClient, OBS_PLUGIN, logQueryString } from "./obs.js";
+export type { LogQuery, NewAlert } from "./obs.js";
+export { Shell, PING_INTERVAL_MS } from "./shell.js";
+export type { ShellExit, ShellOptions } from "./shell.js";
+export { waitForJob, waitForReady, JOB_POLL_MS, POOL_POLL_MS, FIRST_POLL_MS } from "./wait.js";
+export type { JobProgress, PoolProgress, WaitForJobOptions, WaitForReadyOptions, } from "./wait.js";
+export { ApiError, ColdStartTimeoutError, ConflictError, ForbiddenError, InvalidRequestError, MalformedResponseError, NoRunningVmError, NotFoundError, HeyctlError, ShellError, TimeoutError, TransportError, UnauthorizedError, UpstreamError, } from "./errors.js";
+export type { Credential } from "./errors.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,48 @@
+/**
+ * `@heyocomputer/hws` — the TypeScript twin of the `hws` crate: a client for
+ * the app-lb admin API.
+ *
+ * app-lb is a load balancer for heyvm Firecracker/KVM microVMs. This package
+ * drives it: register deployments, scale pools, run commands inside a VM, and
+ * attach an interactive shell.
+ *
+ * ```ts
+ * import { Hws } from "@heyocomputer/hws";
+ *
+ * const lb = new Hws({ server: "127.0.0.1:9090", token: process.env.APP_LB_TOKEN });
+ * const { stdout } = await lb.exec("sb-7f3a9c", "uname -a");
+ * ```
+ *
+ * # Authentication
+ *
+ * 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.
+ *
+ * # Runtimes
+ *
+ * Node 18+, Bun, Deno and browsers. Everything uses `fetch`. Shells use `ws` on
+ * the server and the native `WebSocket` in a browser — and because a browser
+ * cannot set headers on an upgrade, a browser shell needs an **app-token**,
+ * which travels in the query string. Mint a short-lived one for that.
+ *
+ * # What this package does not smooth over
+ *
+ * - A non-zero exit code from {@link Heyctl.exec} resolves, it does not
+ *   reject. The command ran; it failed.
+ * - `exec`'s timeout does not kill anything. It bounds app-lb's call to the
+ *   daemon — on expiry you get an `UpstreamError` and the command **keeps
+ *   running in the guest**.
+ * - A shell socket has no resume. If it drops the session is gone; reconnecting
+ *   gives a *new* shell.
+ */
+export { Heyctl, normalizeServer, ASSUMED_COLD_START_MS } from "./client.js";
+/**
+ * The client under the package's name. `Heyctl` stays exported for code
+ * written against the earlier name; they are the same class.
+ */
+export { Heyctl as Hws } from "./client.js";
+export { ObsClient, OBS_PLUGIN, logQueryString } from "./obs.js";
+export { Shell, PING_INTERVAL_MS } from "./shell.js";
+export { waitForJob, waitForReady, JOB_POLL_MS, POOL_POLL_MS, FIRST_POLL_MS } from "./wait.js";
+export { ApiError, ColdStartTimeoutError, ConflictError, ForbiddenError, InvalidRequestError, MalformedResponseError, NoRunningVmError, NotFoundError, HeyctlError, ShellError, TimeoutError, TransportError, UnauthorizedError, UpstreamError, } from "./errors.js";

package/dist/obs.d.ts

@@ -0,0 +1,86 @@
+/**
+ * One namespace's telemetry, read through app-lb's `obs` plugin. Mirrors the
+ * `hws` crate's `ObsClient`.
+ *
+ * Installing `obs` into a namespace makes app-obs collect metrics and logs for
+ * every deployment in it. A namespace-scoped credential reads them through
+ * app-lb, which checks the caller reaches the namespace and talks to app-obs on
+ * its behalf — nothing here needs to know where app-obs lives.
+ *
+ * ```ts
+ * await lb.installPlugin("team-a", "obs");
+ * const obs = lb.obs("team-a");
+ * for (const row of (await obs.fleet({ window: "1h" })).deployments) {
+ *   console.log(row.id, row.log_lines, row.error_logs);
+ * }
+ * const page = await obs.logs("web", { level: "error", limit: 50 });
+ * ```
+ *
+ * Every method rejects with a `ConflictError` whose `code` is
+ * `plugin_not_installed` or `plugin_disabled` when the plugin is not usable in
+ * the namespace.
+ */
+import type { Heyctl } from "./client.js";
+import type { ObsAlert, ObsDeployment, ObsFleet, ObsLogs } from "./types.js";
+/** The plugin id of the telemetry plugin. */
+export declare const OBS_PLUGIN = "obs";
+/** Which log lines {@link ObsClient.logs} returns. Every filter is optional. */
+export interface LogQuery {
+    /** `15m`, `1h`, `6h`, `1d`, `7d`, … */
+    window?: string;
+    /** Range start, epoch milliseconds. Overrides `window`'s start. */
+    from?: number;
+    /** Range end, epoch milliseconds. */
+    to?: number;
+    level?: string;
+    /** One VM (sandbox id) or upstream. */
+    backend?: string;
+    /** Case-insensitive substring of the message. Sent as `q`. */
+    search?: string;
+    limit?: number;
+    /** Page boundary, epoch milliseconds, inclusive — a page's `next_before_ms`. */
+    before?: number;
+}
+/** The body of {@link ObsClient.createAlert}. */
+export interface NewAlert {
+    deployment: string;
+    threshold: number;
+    webhook_url: string;
+    /** `errors` when omitted — currently the only metric. */
+    metric?: string;
+}
+/** `?window=…&level=…` in the order the crate writes it, or `""`. */
+export declare function logQueryString(q?: LogQuery): string;
+export declare class ObsClient {
+    private readonly client;
+    readonly namespace: string;
+    constructor(client: Heyctl, namespace: string);
+    private path;
+    /** Every deployment with telemetry in the window, with series and log counts. */
+    fleet(opts?: {
+        window?: string;
+        signal?: AbortSignal;
+    }): Promise<ObsFleet>;
+    /**
+     * One deployment's metrics and log volume. A deployment outside this
+     * namespace is a `NotFoundError`, exactly as one that does not exist.
+     */
+    deployment(id: string, opts?: {
+        window?: string;
+        signal?: AbortSignal;
+    }): Promise<ObsDeployment>;
+    /**
+     * One page of a deployment's logs, newest first. To page back, pass
+     * `next_before_ms` as `before` until it comes back `null`.
+     */
+    logs(id: string, query?: LogQuery, signal?: AbortSignal): Promise<ObsLogs>;
+    /** The namespace's alert rules. */
+    alerts(signal?: AbortSignal): Promise<ObsAlert[]>;
+    /**
+     * POST `webhook_url` whenever `deployment` logs more than `threshold` errors
+     * in a minute. Needs `admin` in the namespace.
+     */
+    createAlert(alert: NewAlert, signal?: AbortSignal): Promise<ObsAlert>;
+    /** Delete a rule. Deleting one that does not exist succeeds. */
+    deleteAlert(id: string, signal?: AbortSignal): Promise<void>;
+}

package/dist/obs.js

@@ -0,0 +1,115 @@
+/**
+ * One namespace's telemetry, read through app-lb's `obs` plugin. Mirrors the
+ * `hws` crate's `ObsClient`.
+ *
+ * Installing `obs` into a namespace makes app-obs collect metrics and logs for
+ * every deployment in it. A namespace-scoped credential reads them through
+ * app-lb, which checks the caller reaches the namespace and talks to app-obs on
+ * its behalf — nothing here needs to know where app-obs lives.
+ *
+ * ```ts
+ * await lb.installPlugin("team-a", "obs");
+ * const obs = lb.obs("team-a");
+ * for (const row of (await obs.fleet({ window: "1h" })).deployments) {
+ *   console.log(row.id, row.log_lines, row.error_logs);
+ * }
+ * const page = await obs.logs("web", { level: "error", limit: 50 });
+ * ```
+ *
+ * Every method rejects with a `ConflictError` whose `code` is
+ * `plugin_not_installed` or `plugin_disabled` when the plugin is not usable in
+ * the namespace.
+ */
+/** The plugin id of the telemetry plugin. */
+export const OBS_PLUGIN = "obs";
+/** `?window=…&level=…` in the order the crate writes it, or `""`. */
+export function logQueryString(q = {}) {
+    const parts = [];
+    const text = (k, v) => {
+        if (v)
+            parts.push(`${k}=${encodeURIComponent(v)}`);
+    };
+    text("window", q.window);
+    text("level", q.level);
+    text("backend", q.backend);
+    text("q", q.search);
+    for (const [k, v] of [["from", q.from], ["to", q.to], ["before", q.before]]) {
+        if (v !== undefined)
+            parts.push(`${k}=${v}`);
+    }
+    if (q.limit !== undefined)
+        parts.push(`limit=${q.limit}`);
+    return parts.length ? `?${parts.join("&")}` : "";
+}
+const seg = encodeURIComponent;
+export class ObsClient {
+    client;
+    namespace;
+    constructor(client, namespace) {
+        this.client = client;
+        this.namespace = namespace;
+    }
+    path(rest) {
+        return `/namespaces/${seg(this.namespace)}/plugins/${OBS_PLUGIN}/api/${rest}`;
+    }
+    /** Every deployment with telemetry in the window, with series and log counts. */
+    fleet(opts = {}) {
+        const q = opts.window ? `?window=${seg(opts.window)}` : "";
+        return this.client.request("GET", this.path(`fleet${q}`), {
+            kind: "namespace",
+            name: this.namespace,
+            signal: opts.signal,
+        });
+    }
+    /**
+     * One deployment's metrics and log volume. A deployment outside this
+     * namespace is a `NotFoundError`, exactly as one that does not exist.
+     */
+    deployment(id, opts = {}) {
+        const q = opts.window ? `?window=${seg(opts.window)}` : "";
+        return this.client.request("GET", this.path(`deployments/${seg(id)}${q}`), {
+            kind: "deployment",
+            name: id,
+            signal: opts.signal,
+        });
+    }
+    /**
+     * One page of a deployment's logs, newest first. To page back, pass
+     * `next_before_ms` as `before` until it comes back `null`.
+     */
+    logs(id, query = {}, signal) {
+        return this.client.request("GET", `${this.path(`deployments/${seg(id)}/logs`)}${logQueryString(query)}`, { kind: "deployment", name: id, signal });
+    }
+    /** The namespace's alert rules. */
+    alerts(signal) {
+        return this.client.request("GET", this.path("alerts"), { kind: "alert", signal });
+    }
+    /**
+     * POST `webhook_url` whenever `deployment` logs more than `threshold` errors
+     * in a minute. Needs `admin` in the namespace.
+     */
+    createAlert(alert, signal) {
+        const body = {
+            deployment: alert.deployment,
+            threshold: alert.threshold,
+            webhook_url: alert.webhook_url,
+        };
+        if (alert.metric)
+            body.metric = alert.metric;
+        return this.client.request("POST", this.path("alerts"), {
+            body,
+            kind: "alert",
+            name: alert.deployment,
+            signal,
+        });
+    }
+    /** Delete a rule. Deleting one that does not exist succeeds. */
+    async deleteAlert(id, signal) {
+        await this.client.request("DELETE", this.path(`alerts/${seg(id)}`), {
+            kind: "alert",
+            name: id,
+            signal,
+            expect: "nothing",
+        });
+    }
+}