@homespunapps/core 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,508 @@
+import type { FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, TasteInfo } from "./types.js";
+export interface ClientOptions {
+    /** Relay base URL, e.g. https://homespun.example.com. Trailing slash is trimmed. */
+    url: string;
+    /** Agent API key (bearer token). */
+    apiKey: string;
+    /** Optional fetch override (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /**
+     * Optional client version string sent as `x-homespun-cli-version` on every
+     * request. The CLI passes its own `VERSION` constant here so a relay can
+     * detect version skew and respond with a `cli_upgrade_required` error
+     * (HTTP 426) when the CLI is below the relay's minimum supported version.
+     * Library callers (non-CLI) can leave this unset — the header is omitted
+     * and the relay treats the request as version-unknown.
+     */
+    cliVersion?: string;
+}
+/** Low-level relay response: ok flag, HTTP status, parsed JSON body. */
+export interface RelayResponse {
+    ok: boolean;
+    status: number;
+    data: unknown;
+}
+/** Response from POST /v1/query. */
+export interface QueryResponse {
+    /** Ordered column names exactly as DuckDB returned them. */
+    columns: string[];
+    /** Result rows; each row is an array of values aligned to `columns`. */
+    rows: unknown[][];
+    /** True if the result was capped by the relay's per-query row cap. */
+    truncated: boolean;
+    /** Tells the caller which apps the query saw and how it was scoped. */
+    scope: {
+        kind: "human" | "agent";
+        app_count: number;
+    };
+    /** Wall-clock milliseconds the relay spent serving the query. */
+    elapsed_ms: number;
+}
+/**
+ * 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 declare class HomespunApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    /** Agent-friendly remediation hint, when the relay supplies one. */
+    readonly hint?: string;
+    /** Whether retrying the same request may succeed (e.g. 429). */
+    readonly retryable?: boolean;
+    /** Documentation URL for this error class (mapped from the wire's `docs_url`). */
+    readonly docsUrl?: string;
+    constructor(status: number, code: string, message: string, details?: unknown, extra?: {
+        hint?: string;
+        retryable?: boolean;
+        docsUrl?: string;
+    });
+}
+export declare class HomespunClient {
+    private readonly base;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly cliVersion;
+    constructor(opts: ClientOptions);
+    /** Relay base URL (trailing slash trimmed). */
+    get baseUrl(): string;
+    /** WebSocket base URL derived from the relay base URL (http→ws, https→wss). */
+    get wsBaseUrl(): string;
+    /**
+     * 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, ... }`.
+     */
+    call(method: string, path: string, body?: object): Promise<RelayResponse>;
+    /** Assert a 2xx body is a non-null object before treating it as typed JSON. */
+    private asObject;
+    /** Throw a HomespunApiError from a failed RelayResponse. */
+    private fail;
+    /**
+     * 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.
+     */
+    listKeys(): Promise<KeyInfo>;
+    /**
+     * 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.
+     */
+    revokeKey(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    claimAgent(code: string): Promise<{
+        ok: true;
+        owner_human_id: string;
+        claimed_at: string;
+    }>;
+    /**
+     * 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.
+     */
+    getTaste(): Promise<TasteInfo>;
+    /**
+     * 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).
+     */
+    setTaste(taste: string): Promise<TasteInfo>;
+    /**
+     * 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.
+     */
+    clearTaste(): Promise<void>;
+    /**
+     * 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.
+     */
+    submitFeedback(req: {
+        type: FeedbackType;
+        message: string;
+        appId?: string;
+    }): Promise<FeedbackSubmission>;
+    /**
+     * GET /v1/feedback — the calling agent's own submissions, newest first.
+     * `before` is an opaque cursor from a previous page's `next_before`.
+     */
+    listFeedback(opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<FeedbackPage>;
+    /**
+     * 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.
+     */
+    uploadBlob(file: Blob | Buffer | Uint8Array, opts?: UploadBlobOptions): Promise<AttachmentRef>;
+    /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
+    downloadBlob(attachmentId: string): Promise<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.
+     */
+    getBlob(attachmentId: string): Promise<AttachmentRef>;
+    /** DELETE /v1/attachments/:id — soft-delete (idempotent). */
+    deleteBlob(attachmentId: string): Promise<{
+        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.
+     */
+    mintBlobToken(attachmentId: string, opts?: {
+        ttlSeconds?: number;
+        once?: boolean;
+    }): Promise<AttachmentTokenMintResponse>;
+    /** Revoke a previously-minted token. Idempotent. */
+    revokeBlobToken(attachmentId: string, tokenId: string): Promise<{
+        token_id: string;
+        revoked: true;
+    }>;
+    /**
+     * 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.
+     */
+    listBlobs(opts?: ListBlobsOptions): Promise<{
+        items: AttachmentRef[];
+        next_cursor: string | null;
+    }>;
+    /**
+     * 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.
+     */
+    listBlobTokens(attachmentId: string): Promise<AttachmentTokenListResponse>;
+    /**
+     * 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.
+     */
+    presignBlob(opts: PresignBlobOptions): Promise<{
+        attachment_id: string;
+        upload_url: string;
+        expires_at: string;
+    }>;
+    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    confirmBlob(attachmentId: string): Promise<AttachmentRef>;
+    /** POST /v1/apps — create (deploy) a new App + its first AppVersion. */
+    deployApp(req: DeployAppRequest): Promise<DeployAppResponse>;
+    /** POST /v1/apps/:id/versions — redeploy (compat-gated unless force). */
+    redeployApp(appId: string, req: RedeployAppRequest): Promise<RedeployAppResponse>;
+    /**
+     * 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).
+     */
+    listApps(opts?: {
+        status?: "active" | "dormant" | "archived" | "all";
+        limit?: number;
+        cursor?: string;
+        slug?: string;
+    }): Promise<AppsPage>;
+    /** GET /v1/apps/:id — full app detail (manifest, current_version, quota). */
+    getApp(appId: string): Promise<AppDetail>;
+    /** PATCH /v1/apps/:id — update visibility (the only mutable app field). */
+    updateApp(appId: string, visibility: "private" | "link" | "public"): Promise<{
+        id: string;
+        visibility: string;
+    }>;
+    /** DELETE /v1/apps/:id — soft-delete (idempotent). */
+    deleteApp(appId: string): Promise<void>;
+    /** POST /v1/apps/:id/wake — wake a dormant app; a no-op on a non-dormant one. */
+    wakeApp(appId: string): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /**
+     * 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).
+     */
+    addAppMember(appId: string, opts: {
+        email: string;
+        role?: "member";
+    }): Promise<AddAppMemberResult>;
+    /** GET /v1/apps/:id/members — list the app's owner + member rows. */
+    listAppMembers(appId: string): Promise<{
+        members: AppMember[];
+    }>;
+    /**
+     * 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.
+     */
+    removeAppMember(appId: string, humanId: string): Promise<void>;
+    /** GET /v1/apps/:id/collections/:name — list rows (current-state page). */
+    listAppRows(appId: string, collection: string, opts?: {
+        since?: string;
+        limit?: number;
+    }): Promise<AppRowsPage>;
+    /**
+     * 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.
+     */
+    getAppRow(appId: string, collection: string, key: string): Promise<{
+        row: AppRow;
+    }>;
+    /**
+     * 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.
+     */
+    upsertAppRow(appId: string, collection: string, body: {
+        key?: string;
+        data: unknown;
+    }): Promise<{
+        row: AppRow;
+        deduped?: true;
+    }>;
+    /** PATCH /v1/apps/:id/collections/:name/:key — optimistic-locked update. */
+    updateAppRow(appId: string, collection: string, key: string, body: {
+        data: unknown;
+        if_match?: number;
+    }): Promise<{
+        row: AppRow;
+    }>;
+    /** DELETE /v1/apps/:id/collections/:name/:key — soft-delete. */
+    deleteAppRow(appId: string, collection: string, key: string, opts?: {
+        ifMatch?: number;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    getAppFeed(appId: string, opts: {
+        since: number;
+        limit?: number;
+        wait?: number;
+    }): Promise<AppFeedPage>;
+}
+/** Request body for `POST /v1/apps` — create (deploy) a new App. */
+export interface DeployAppRequest {
+    html: string;
+    manifest: unknown;
+    /** Defaults to "private" server-side when omitted. */
+    visibility?: "private" | "link" | "public";
+    /** Accepted for visibility public|private (including the omitted default); rejected for link. */
+    slug?: string;
+}
+export interface DeployAppResponse {
+    app_id: string;
+    slug: string;
+    visibility: string;
+    url: string;
+    version: number;
+    created: true;
+}
+/** Request body for `POST /v1/apps/:id/versions` — redeploy (compat-gated). */
+export interface RedeployAppRequest {
+    html: string;
+    manifest: unknown;
+    /** Bypass the compat gate; a narrowing collection is detached, not deleted. */
+    force?: boolean;
+}
+export interface RedeployAppResponse {
+    app_id: string;
+    version: number;
+    compat: "clean" | "forced";
+    breaks?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/** Lean per-app summary — the shape `listApps` returns. */
+export interface AppSummary {
+    id: string;
+    slug: string;
+    visibility: string;
+    status: string;
+    url: string;
+    created_at: string;
+    last_activity_at: string;
+}
+/** Full app detail — the shape `getApp` returns. */
+export interface AppDetail extends AppSummary {
+    manifest: unknown;
+    current_version: number | null;
+    owner_human_id: string;
+    row_count: number;
+    storage_bytes: string;
+}
+export interface AppsPage {
+    items: AppSummary[];
+    next_cursor: string | null;
+}
+/**
+ * One member row — the shape `listAppMembers` returns and the `member` half
+ * of `addAppMember`'s union returns. Fields are camelCase on the wire (see
+ * the app-membership section above for why).
+ */
+export interface AppMember {
+    humanId: string;
+    email: string;
+    role: string;
+    createdAt: string;
+}
+/**
+ * `POST /v1/apps/:id/members` response — either the member was attached
+ * immediately (existing Human) or an invite email was sent (no Human yet).
+ */
+export type AddAppMemberResult = {
+    member: AppMember;
+} | {
+    ok: true;
+    invited: string;
+    expires_at: string;
+};
+/** One row in an app collection — the shape every row CRUD op returns. */
+export interface AppRow {
+    key: string;
+    data: unknown;
+    version: number;
+    author: {
+        kind: string;
+        id: string;
+    };
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export interface AppRowsPage {
+    rows: AppRow[];
+    next_cursor: string | null;
+    has_more: boolean;
+}
+/**
+ * One entry in an app's change feed — the SAME shape whether it arrives via
+ * `GET /v1/apps/:id/feed` (long-poll) or the `/_hs/ws` live/batch frames
+ * (openAppStream, app-stream.ts) — the CLI's `apps watch` prints this object
+ * unchanged regardless of which transport served it (spec-cli §3.4/§5).
+ */
+export interface AppFeedEntry {
+    seq: number;
+    op: string;
+    collection_name: string;
+    row_key: string;
+    row_version?: number | null;
+    data: unknown;
+    author: {
+        kind: string;
+        id: string;
+    };
+    ts: string;
+}
+export interface AppFeedPage {
+    entries: AppFeedEntry[];
+    cursor: number;
+    truncated: boolean;
+}
+/** Per-attachment metadata as returned by `POST /v1/attachments` and friends. */
+export interface AttachmentRef {
+    attachment_id: string;
+    scope: "agent" | "app";
+    mime: string;
+    size: number;
+    sha256: string;
+    url?: string;
+    width?: number | null;
+    height?: number | null;
+    filename?: string | null;
+    status?: string;
+    app_id?: string | null;
+    created_at?: string;
+    confirmed_at?: string | null;
+    deleted_at?: string | null;
+}
+export interface UploadBlobOptions {
+    scope?: "agent" | "app";
+    appId?: string;
+    /** Declared Content-Type. Defaults to `application/octet-stream`. The
+     *  relay sniffs leading bytes and may reject with `mime_mismatch`. */
+    mime?: string;
+    /** Optional display name (the relay records it for UX; never a path component). */
+    filename?: string;
+}
+export interface PresignBlobOptions {
+    mime: string;
+    size: number;
+    sha256: string;
+    scope?: "agent" | "app";
+    appId?: string;
+    filename?: string;
+}
+export interface AttachmentTokenMintResponse {
+    token_id: string;
+    token: string;
+    token_prefix: string;
+    url: string;
+    expires_at: string;
+    once: boolean;
+}
+/** Options for `listBlobs()` — opaque cursor + page-size knob. */
+export interface ListBlobsOptions {
+    /** Opaque pagination cursor from a prior `next_cursor`. */
+    cursor?: string;
+    /** Page size; relay clamps to 1..100. Defaults to the relay default (50). */
+    limit?: number;
+}
+/** One row in the response from `listBlobTokens()`. */
+export interface AttachmentTokenAuditEntry {
+    token_id: string;
+    token_prefix: string;
+    expires_at: string;
+    once: boolean;
+    created_at: string;
+    last_used_at: string | null;
+    use_count: number;
+    /** Non-null when the token has been revoked. Expired-but-unrevoked rows
+     *  carry `revoked_at: null` and an `expires_at` in the past — both are
+     *  useful for audit. */
+    revoked_at: string | null;
+}
+/** Shape returned by `listBlobTokens()`. */
+export interface AttachmentTokenListResponse {
+    attachment_id: string;
+    items: AttachmentTokenAuditEntry[];
+}