@homespunapps/core 1.0.0

package/dist/client.js

@@ -0,0 +1,619 @@
+// Homespun relay HTTP client. Pure: no argv, no process.env reads, no MCP.
+// The caller supplies the relay base URL + API key explicitly.
+import { MAX_RESPONSE_SNIPPET_LENGTH } from "./limits.js";
+/**
+ * An error thrown by the typed operations when the relay returns a non-2xx
+ * response (or the request fails outright). Carries the HTTP status and the
+ * relay error envelope so callers can branch on `code`.
+ */
+export class HomespunApiError extends Error {
+    status;
+    code;
+    details;
+    /** Agent-friendly remediation hint, when the relay supplies one. */
+    hint;
+    /** Whether retrying the same request may succeed (e.g. 429). */
+    retryable;
+    /** Documentation URL for this error class (mapped from the wire's `docs_url`). */
+    docsUrl;
+    constructor(status, code, message, details, extra) {
+        super(message);
+        this.name = "HomespunApiError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.hint = extra?.hint;
+        this.retryable = extra?.retryable;
+        this.docsUrl = extra?.docsUrl;
+    }
+}
+export class HomespunClient {
+    base;
+    apiKey;
+    fetchImpl;
+    cliVersion;
+    constructor(opts) {
+        this.base = opts.url.replace(/\/$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.cliVersion = opts.cliVersion;
+    }
+    /** Relay base URL (trailing slash trimmed). */
+    get baseUrl() {
+        return this.base;
+    }
+    /** WebSocket base URL derived from the relay base URL (http→ws, https→wss). */
+    get wsBaseUrl() {
+        const u = new URL(this.base);
+        u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+        return u.toString().replace(/\/$/, "");
+    }
+    /**
+     * Low-level HTTP helper. Mirrors the relay API contract: Bearer auth,
+     * JSON bodies, 204 handled. Never throws on non-2xx — returns `ok: false`.
+     * Network failures return `{ ok: false, status: 0, ... }`.
+     */
+    async call(method, path, body) {
+        const url = this.base + path;
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    authorization: "Bearer " + this.apiKey,
+                    ...(body ? { "content-type": "application/json" } : {}),
+                    // x-homespun-cli-version drives the relay's version-skew check. Header
+                    // is omitted entirely when no version was supplied so the relay
+                    // can distinguish "old CLI" from "non-CLI caller".
+                    ...(this.cliVersion
+                        ? { "x-homespun-cli-version": this.cliVersion }
+                        : {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                ok: false,
+                status: 0,
+                data: { error: { code: "fetch_error", message: msg } },
+            };
+        }
+        let data = null;
+        if (res.status !== 204) {
+            const text = await res.text().catch(() => "");
+            if (text !== "") {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    // Body was not JSON (HTML error page, plain-text proxy error, …).
+                    // Don't discard it — app the raw text so callers can diagnose.
+                    const snippet = text.length > MAX_RESPONSE_SNIPPET_LENGTH
+                        ? text.slice(0, MAX_RESPONSE_SNIPPET_LENGTH) + "…"
+                        : text;
+                    data = {
+                        error: {
+                            code: "non_json_response",
+                            message: `relay returned a non-JSON body (status ${res.status})`,
+                            details: { body: snippet },
+                        },
+                    };
+                }
+            }
+        }
+        return { ok: res.ok, status: res.status, data };
+    }
+    /** Assert a 2xx body is a non-null object before treating it as typed JSON. */
+    asObject(r) {
+        if (r.data === null ||
+            typeof r.data !== "object" ||
+            Array.isArray(r.data)) {
+            throw new HomespunApiError(r.status, "invalid_response", `relay returned a ${r.status} with a non-object body`, { body: r.data });
+        }
+        return r.data;
+    }
+    /** Throw a HomespunApiError from a failed RelayResponse. */
+    fail(r) {
+        const err = r.data?.error;
+        throw new HomespunApiError(r.status, err?.code ?? "relay_error", err?.message ?? `relay returned ${r.status}`, err?.details, {
+            hint: err?.hint,
+            retryable: err?.retryable,
+            docsUrl: err?.docs_url,
+        });
+    }
+    /**
+     * GET /v1/keys — the calling agent's own key info. The relay scopes this to
+     * the authenticated agent: it returns one key (the caller's), not a list.
+     */
+    async listKeys() {
+        const r = await this.call("GET", "/v1/keys");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/keys/:id — revoke an API key. The relay only permits revoking
+     * the caller's OWN key (any other id is rejected 403): this is a
+     * self-destruct. Returns 204 with no body on success.
+     */
+    async revokeKey(id) {
+        const r = await this.call("DELETE", `/v1/keys/${encodeURIComponent(id)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/agents/claim — bind this agent to a human via a one-shot
+     * claim code the human generated in their settings UI. After a
+     * successful claim the agent's existing API key continues to work,
+     * but the agent (and its apps/templates) now belong to the
+     * claiming human. One-way operation — there is no unclaim in v1.
+     */
+    async claimAgent(code) {
+        const r = await this.call("POST", "/v1/agents/claim", { code });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/taste — the calling agent's freeform "taste notes" markdown attachment:
+     * presentation preferences the agent has picked up from human feedback over
+     * time. Returns `{ taste: null, updated_at: null, bytes: 0 }` when the
+     * agent has never written notes. Read this before generating an template so
+     * the agent applies prior feedback.
+     */
+    async getTaste() {
+        const r = await this.call("GET", "/v1/taste");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * PUT /v1/taste — whole-attachment replace of the calling agent's taste notes.
+     * Empty/whitespace-only values are rejected by the relay; callers asking to
+     * clear must use {@link clearTaste}. The relay caps the payload at the
+     * server's `MAX_TASTE_BYTES` (utf8 bytes).
+     */
+    async setTaste(taste) {
+        const r = await this.call("PUT", "/v1/taste", { taste });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/taste — clear the calling agent's taste notes (idempotent on
+     * the relay; clearing already-empty notes still succeeds). Returns 204 with
+     * no body.
+     */
+    async clearTaste() {
+        const r = await this.call("DELETE", "/v1/taste");
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/feedback — submit a one-shot bug report, feature request, or
+     * note to the relay operator. Returns the new row's id, type, and
+     * created_at; the message is not echoed.
+     */
+    async submitFeedback(req) {
+        const r = await this.call("POST", "/v1/feedback", {
+            type: req.type,
+            message: req.message,
+            app_id: req.appId,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/feedback — the calling agent's own submissions, newest first.
+     * `before` is an opaque cursor from a previous page's `next_before`.
+     */
+    async listFeedback(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        if (opts.before != null && opts.before !== "")
+            q.set("before", opts.before);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/feedback${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    // ------------------------------------------------------------------------
+    // Blobs (v0.1.0). Two-scope binary attachments with multipart upload.
+    // See proposal hs#152 for the original design; scopes were cut over to
+    // the v2 App domain (agent | app) in the 2c2 rebrand.
+    // ------------------------------------------------------------------------
+    /**
+     * Upload a attachment to the relay. Returns a `AttachmentRef` that can be referenced
+     * in event payloads (the relay's `format: homespun-attachment-id` schema vocab
+     * validates the id) or in `homespun create --input-data`.
+     *
+     * Scope defaults to "agent" (reusable). For `scope: "app"` pass `appId`.
+     * The calling agent's owning human must own the referenced App;
+     * cross-tenant attempts return app_not_found.
+     *
+     * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
+     * leading bytes and may reject with mime_mismatch / mime_disallowed.
+     *
+     * Backed by the relay's multipart `POST /v1/attachments` (the fallback path).
+     * For large uploads (>1 MB on hosted Azure) call `presignBlob()` +
+     * `confirmBlob()` instead — those use SAS direct-to-storage and don't
+     * stream bytes through the relay.
+     */
+    async uploadBlob(file, opts = {}) {
+        const fd = new FormData();
+        let attachment;
+        if (file instanceof Blob) {
+            attachment = file;
+        }
+        else {
+            // Buffer / Uint8Array path — wrap in a Blob with the declared MIME.
+            // Copy into a freshly allocated Uint8Array so the buffer type
+            // narrows from `ArrayBufferLike` (which includes SharedArrayBuffer)
+            // to `ArrayBuffer` specifically — the Blob constructor accepts only
+            // the latter under @types/node ≥25 + TS ≥5.7's generic narrowing of
+            // Uint8Array<TArrayBuffer>. `new Uint8Array(length)` returns
+            // `Uint8Array<ArrayBuffer>` by construction, satisfying AttachmentPart
+            // without a type cast. The extra copy is one walk over the bytes —
+            // negligible vs the network upload that follows.
+            const src = file instanceof Uint8Array ? file : new Uint8Array(file);
+            const u8 = new Uint8Array(src.byteLength);
+            u8.set(src);
+            attachment = new Blob([u8], {
+                type: opts.mime ?? "application/octet-stream",
+            });
+        }
+        fd.set("file", attachment, opts.filename ?? "attachment");
+        if (opts.scope)
+            fd.set("scope", opts.scope);
+        if (opts.appId)
+            fd.set("app_id", opts.appId);
+        if (opts.filename)
+            fd.set("filename", opts.filename);
+        const url = this.base + "/v1/attachments";
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    authorization: "Bearer " + this.apiKey,
+                    ...(this.cliVersion
+                        ? { "x-homespun-cli-version": this.cliVersion }
+                        : {}),
+                },
+                body: fd,
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new HomespunApiError(0, "fetch_error", msg);
+        }
+        const text = await res.text().catch(() => "");
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new HomespunApiError(res.status, "non_json_response", `relay returned a non-JSON body (status ${res.status})`);
+        }
+        if (!res.ok) {
+            this.fail({ ok: false, status: res.status, data });
+        }
+        return data;
+    }
+    /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
+    async downloadBlob(attachmentId) {
+        const url = this.base + "/v1/attachments/" + encodeURIComponent(attachmentId);
+        const res = await this.fetchImpl(url, {
+            method: "GET",
+            headers: {
+                authorization: "Bearer " + this.apiKey,
+                ...(this.cliVersion
+                    ? { "x-homespun-cli-version": this.cliVersion }
+                    : {}),
+            },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = null;
+            }
+            this.fail({ ok: false, status: res.status, data });
+        }
+        return res.arrayBuffer();
+    }
+    /**
+     * GET a attachment's metadata only — useful before downloading large attachments, or
+     * for `homespun attachment show <id>` which doesn't want the bytes. Returns the full
+     * AttachmentRef (the same shape POST /v1/attachments returns): id, scope, mime, size,
+     * sha256, filename, width, height, status, scope FKs, timestamps.
+     *
+     * Backed by GET /v1/attachments/:id/metadata which serves the JSON AttachmentRef
+     * without streaming the bytes — cheap on the relay and avoids the
+     * encrypt-at-rest decrypt cost when only the metadata is needed.
+     */
+    async getBlob(attachmentId) {
+        const r = await this.call("GET", "/v1/attachments/" + encodeURIComponent(attachmentId) + "/metadata");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/attachments/:id — soft-delete (idempotent). */
+    async deleteBlob(attachmentId) {
+        const r = await this.call("DELETE", "/v1/attachments/" + encodeURIComponent(attachmentId));
+        if (!r.ok)
+            this.fail(r);
+        return { deleted: true };
+    }
+    /**
+     * Mint a `/b/<token>` capability URL for `attachmentId`. Default TTL is set by
+     * the relay (24h agent-scope, 30d app-scope). `once: true`
+     * tokens self-delete on first GET.
+     */
+    async mintBlobToken(attachmentId, opts = {}) {
+        const r = await this.call("POST", "/v1/attachments/" + encodeURIComponent(attachmentId) + "/tokens", { ttl_seconds: opts.ttlSeconds, once: opts.once });
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /** Revoke a previously-minted token. Idempotent. */
+    async revokeBlobToken(attachmentId, tokenId) {
+        const r = await this.call("DELETE", "/v1/attachments/" +
+            encodeURIComponent(attachmentId) +
+            "/tokens/" +
+            encodeURIComponent(tokenId));
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * GET /v1/attachments — list YOUR agent's non-deleted attachments (newest first).
+     * Paginated via opaque cursor: when `next_cursor` is non-null, pass it
+     * back as `cursor` on the next call.
+     */
+    async listBlobs(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.cursor !== undefined)
+            params.set("cursor", opts.cursor);
+        if (opts.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        const r = await this.call("GET", "/v1/attachments" + (qs ? "?" + qs : ""));
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * GET /v1/attachments/:id/tokens — enumerate the capability tokens minted
+     * against one attachment, including revoked rows (for audit). The plaintext
+     * token is NEVER returned — it isn't stored, only its sha256 is.
+     */
+    async listBlobTokens(attachmentId) {
+        const r = await this.call("GET", "/v1/attachments/" + encodeURIComponent(attachmentId) + "/tokens");
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * Issue a presigned PUT URL for direct-to-storage upload. Returns the
+     * upload URL + the attachment_id (already reserved in the relay's DB with
+     * status=pending) + expiry. After PUTting the bytes to the URL, call
+     * `confirmBlob(attachment_id)` to finalise.
+     *
+     * Filesystem backend returns 501 not_implemented — use uploadBlob()
+     * (multipart fallback) instead. Azure backend returns a SAS URL.
+     */
+    async presignBlob(opts) {
+        const r = await this.call("POST", "/v1/attachments/presign", {
+            mime: opts.mime,
+            size: opts.size,
+            sha256: opts.sha256,
+            scope: opts.scope,
+            app_id: opts.appId,
+            filename: opts.filename,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    async confirmBlob(attachmentId) {
+        const r = await this.call("POST", "/v1/attachments/" + encodeURIComponent(attachmentId) + "/confirm");
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    // -------------------------------------------------------------------------
+    // v2 app lifecycle (spec-cli §2.1). `:id` on every route below is always the
+    // App.id (cuid) — a slug is resolved to an id via `listApps({ slug })`
+    // first (the CLI's `resolveAppId` helper does this transparently).
+    // -------------------------------------------------------------------------
+    /** POST /v1/apps — create (deploy) a new App + its first AppVersion. */
+    async deployApp(req) {
+        const r = await this.call("POST", "/v1/apps", {
+            html: req.html,
+            manifest: req.manifest,
+            visibility: req.visibility,
+            slug: req.slug,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/apps/:id/versions — redeploy (compat-gated unless force). */
+    async redeployApp(appId, req) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/versions`, { html: req.html, manifest: req.manifest, force: req.force });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/apps — list apps scoped to the calling agent's owning human.
+     * `slug` is an exact-match filter — the one case a caller resolves a
+     * human-given slug to an id (see the class-level note above).
+     */
+    async listApps(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.status !== undefined)
+            q.set("status", opts.status);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts.cursor !== undefined && opts.cursor !== "")
+            q.set("cursor", opts.cursor);
+        if (opts.slug !== undefined && opts.slug !== "")
+            q.set("slug", opts.slug);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/apps${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** GET /v1/apps/:id — full app detail (manifest, current_version, quota). */
+    async getApp(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** PATCH /v1/apps/:id — update visibility (the only mutable app field). */
+    async updateApp(appId, visibility) {
+        const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}`, { visibility });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/apps/:id — soft-delete (idempotent). */
+    async deleteApp(appId) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /** POST /v1/apps/:id/wake — wake a dormant app; a no-op on a non-dormant one. */
+    async wakeApp(appId) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/wake`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    // -------------------------------------------------------------------------
+    // v2 app membership (auth spec §6, spec-cli §2.5). Auth is owner-or-agent;
+    // this client always authenticates as the owning agent. Note: unlike most
+    // v1/v2 wire shapes, the member fields below are camelCase on the wire
+    // (humanId/createdAt), matching packages/relay/src/http/routes/app-members.ts
+    // exactly rather than the usual snake_case convention.
+    //
+    // Template `install`/`uninstall` is intentionally NOT wrapped here — that
+    // route is `requireHuman` (human login cookie only), not agent-key
+    // authorizable, so it has no place on this agent-facing client.
+    // -------------------------------------------------------------------------
+    /**
+     * POST /v1/apps/:id/members — add or invite a member by email. If a Human
+     * already exists for the email, the member row is created immediately
+     * (`{ member }`); otherwise the relay mints a signed invite and emails a
+     * magic link (`{ ok: true, invited, expires_at }`). 503s if the relay has
+     * EMAIL_PROVIDER=none (no invite-email path available).
+     */
+    async addAppMember(appId, opts) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/members`, { email: opts.email, role: opts.role });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** GET /v1/apps/:id/members — list the app's owner + member rows. */
+    async listAppMembers(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/members`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/apps/:id/members/:humanId — remove a member (idempotent);
+     * cascades to revoke that human's live app sessions. The app owner cannot
+     * be removed — the relay refuses with a 409 conflict.
+     */
+    async removeAppMember(appId, humanId) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/members/${encodeURIComponent(humanId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    // -------------------------------------------------------------------------
+    // v2 collection row CRUD + feed catch-up (spec-cli §2.2/§2.3). Same wire
+    // shapes as the v1 homespun-records methods above, mounted under
+    // /v1/apps/:id/collections/:name instead of /v1/apps/:id/records/:name.
+    // -------------------------------------------------------------------------
+    /** GET /v1/apps/:id/collections/:name — list rows (current-state page). */
+    async listAppRows(appId, collection, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.since !== undefined)
+            q.set("since", opts.since);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/apps/:id/collections/:name/:key — read one row. A dedicated
+     * route (not a client-side scan like v1's `getRecord`) — spec-cli §8
+     * ruling 3 confirms it as a first-class relay route.
+     */
+    async getAppRow(appId, collection, key) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/apps/:id/collections/:name — upsert (create, or return the
+     * existing row when `key` collides — `deduped: true`). §8 ruling 4: this is
+     * the ONLY create-shaped verb — there is no strict create that errors on
+     * an existing key.
+     */
+    async upsertAppRow(appId, collection, body) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** PATCH /v1/apps/:id/collections/:name/:key — optimistic-locked update. */
+    async updateAppRow(appId, collection, key, body) {
+        const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/apps/:id/collections/:name/:key — soft-delete. */
+    async deleteAppRow(appId, collection, key, opts = {}) {
+        const body = opts.ifMatch != null ? { if_match: opts.ifMatch } : undefined;
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`, body);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * GET /v1/apps/:id/feed — change-feed catch-up; the long-poll fallback
+     * transport for `watch` (spec-cli §2.3/§5). `wait` (0-30s) long-polls when
+     * the caller is already caught up.
+     */
+    async getAppFeed(appId, opts) {
+        const q = new URLSearchParams();
+        q.set("since", String(opts.since));
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts.wait !== undefined)
+            q.set("wait", String(opts.wait));
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/feed?${q.toString()}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+}

package/dist/icons.d.ts

@@ -0,0 +1,24 @@
+export declare const RASTER_ICON_MIME_ALLOWLIST: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+export type RasterIconMime = (typeof RASTER_ICON_MIME_ALLOWLIST)[number];
+/** True iff `mime` is a raster image type allowed as an icon. */
+export declare function isRasterImageMime(mime: string | null | undefined): boolean;
+export declare const MAX_ICON_EMOJI_BYTES = 64;
+/**
+ * Validate an icon emoji. Returns `{ ok: true }` for a single emoji grapheme,
+ * or `{ ok: false, error }` with a human-readable reason otherwise.
+ *
+ * Rules:
+ *  - non-empty, ≤ MAX_ICON_EMOJI_BYTES bytes
+ *  - no control characters
+ *  - exactly ONE grapheme cluster (via Intl.Segmenter)
+ *  - that grapheme contains at least one Extended_Pictographic code point
+ *    (so plain ASCII letters/digits and bare symbols are rejected)
+ */
+export declare function validateIconEmoji(raw: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Convenience boolean form of {@link validateIconEmoji}. */
+export declare function isValidIconEmoji(raw: string): boolean;