@homespunapps/core 1.0.0

package/dist/icons.js

@@ -0,0 +1,99 @@
+// Icon helpers shared by the relay and CLI — emoji validation and the raster
+// image MIME allowlist for template/app icons.
+//
+// Icons are deliberately constrained: either ONE emoji grapheme (rendered
+// inline as text) or an uploaded raster image (served from the relay's blob
+// store). No external URLs, no SVG (XSS vector), no multi-character strings.
+// Raster image MIME types accepted as an uploaded icon. SVG is deliberately
+// EXCLUDED — it can carry script and is an XSS vector when rendered in an
+// <img> from a same-origin route. Vector/animated-vector and non-image types
+// are rejected.
+export const RASTER_ICON_MIME_ALLOWLIST = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+];
+/** True iff `mime` is a raster image type allowed as an icon. */
+export function isRasterImageMime(mime) {
+    if (!mime)
+        return false;
+    // Normalise: drop any `; charset=...` parameter and lowercase.
+    const base = mime.split(";")[0].trim().toLowerCase();
+    return RASTER_ICON_MIME_ALLOWLIST.includes(base);
+}
+// Upper bound on the raw byte length of an emoji string. A single rendered
+// emoji can be a long ZWJ sequence (e.g. a family/flag with skin-tone
+// modifiers), but 64 bytes is well beyond any real single grapheme and bounds
+// the work the segmenter does.
+export const MAX_ICON_EMOJI_BYTES = 64;
+// Matches a code point with the Extended_Pictographic property — the Unicode
+// property that flags "this is an emoji-ish pictograph". Used to ensure the
+// grapheme actually contains an emoji and isn't a plain letter/digit/symbol.
+const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
+// Control characters (C0 + DEL + C1) are never valid in an icon emoji. The
+// control chars in the class are intentional — that's exactly what we reject.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f-\u009f]/;
+const byteLength = (s) => typeof TextEncoder !== "undefined"
+    ? new TextEncoder().encode(s).length
+    : Buffer.byteLength(s, "utf8");
+/**
+ * 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 function validateIconEmoji(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        return { ok: false, error: "icon_emoji must be a non-empty string" };
+    }
+    if (byteLength(raw) > MAX_ICON_EMOJI_BYTES) {
+        return {
+            ok: false,
+            error: `icon_emoji must be at most ${MAX_ICON_EMOJI_BYTES} bytes`,
+        };
+    }
+    if (CONTROL_CHAR_RE.test(raw)) {
+        return {
+            ok: false,
+            error: "icon_emoji must not contain control characters",
+        };
+    }
+    // Count grapheme clusters. Intl.Segmenter is available in Node 20+ and all
+    // evergreen browsers (our targets); guard defensively anyway.
+    let graphemeCount;
+    if (typeof Intl !== "undefined" && typeof Intl.Segmenter === "function") {
+        const seg = new Intl.Segmenter("en", { granularity: "grapheme" });
+        // Iterate the segmenter to count grapheme clusters. `[...iterable].length`
+        // materialises the segments, but a single emoji is tiny so it's fine.
+        graphemeCount = [...seg.segment(raw)].length;
+    }
+    else {
+        // Fallback: count code points (over-counts ZWJ sequences, but the
+        // pictographic check below still gates non-emoji input).
+        graphemeCount = Array.from(raw).length;
+    }
+    if (graphemeCount !== 1) {
+        return {
+            ok: false,
+            error: "icon_emoji must be exactly one emoji (a single grapheme)",
+        };
+    }
+    if (!EXTENDED_PICTOGRAPHIC_RE.test(raw)) {
+        return {
+            ok: false,
+            error: "icon_emoji must be an emoji, not a letter, digit, or symbol",
+        };
+    }
+    return { ok: true };
+}
+/** Convenience boolean form of {@link validateIconEmoji}. */
+export function isValidIconEmoji(raw) {
+    return validateIconEmoji(raw).ok;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { HomespunClient, HomespunApiError } from "./client.js";
+export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, AppSummary, AppDetail, AppsPage, AppMember, AddAppMemberResult, AppRow, AppRowsPage, AppFeedEntry, AppFeedPage, } from "./client.js";
+export { openStream } from "./stream.js";
+export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
+export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
+export type { OpenAppStreamOptions, AppStreamHandlers, AppStreamHandle, } from "./app-stream.js";
+export { registerAgent } from "./register.js";
+export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
+export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";
+export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
+export type { RasterIconMime } from "./icons.js";
+export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";
+export type { AuthorKind, HomespunEvent, SerializedRecord, DeletedRecordRef, RecordDeltaMessage, Template, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, RelayError, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// @homespunapps/core — typed client for the Homespun relay HTTP + WebSocket API.
+// Pure and framework-free: no argv, no MCP, no server deps.
+export { HomespunClient, HomespunApiError } from "./client.js";
+export { openStream } from "./stream.js";
+export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
+export { registerAgent } from "./register.js";
+export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";
+export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
+export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/dist/limits.d.ts

@@ -0,0 +1,8 @@
+/** Maximum length of an event type string, in characters. */
+export declare const MAX_EVENT_TYPE_LENGTH = 64;
+/** Maximum length of an idempotency key string, in characters. */
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
+/** Maximum number of characters from a raw response body to include in error details. */
+export declare const MAX_RESPONSE_SNIPPET_LENGTH = 500;
+/** Maximum number of characters from a raw stream frame to include in error messages. */
+export declare const MAX_FRAME_SNIPPET_LENGTH = 200;

package/dist/limits.js

@@ -0,0 +1,10 @@
+// Shared protocol limits used across transports (HTTP and WebSocket).
+// Defined once here so both relay and client code import the same constants.
+/** Maximum length of an event type string, in characters. */
+export const MAX_EVENT_TYPE_LENGTH = 64;
+/** Maximum length of an idempotency key string, in characters. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
+/** Maximum number of characters from a raw response body to include in error details. */
+export const MAX_RESPONSE_SNIPPET_LENGTH = 500;
+/** Maximum number of characters from a raw stream frame to include in error messages. */
+export const MAX_FRAME_SNIPPET_LENGTH = 200;

package/dist/register.d.ts

@@ -0,0 +1,32 @@
+export interface RegisterAgentOptions {
+    /** Relay base URL, e.g. https://homespun.example.com. Trailing slash is trimmed. */
+    url: string;
+    /** Optional agent display name; the relay defaults it if omitted. */
+    name?: string;
+    /**
+     * Shared registration secret. Sent as `Authorization: Bearer <secret>`.
+     * Only needed when the relay runs REGISTRATION_MODE=secret; ignored by
+     * relays in open mode and rejected (404) by relays in closed mode.
+     */
+    secret?: string;
+    /** Optional fetch override (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /**
+     * Optional client version string. Sent as `x-homespun-cli-version` so the
+     * relay's version-skew check can flag a too-old CLI even on the
+     * un-authenticated register endpoint. See `HomespunClient`'s `cliVersion`
+     * option for the parent contract.
+     */
+    cliVersion?: string;
+}
+export interface RegisterAgentResult {
+    agent_id: string;
+    api_key: string;
+    key_prefix: string;
+}
+/**
+ * Provision a fresh agent + API key from the relay. Mirrors HomespunClient.call's
+ * never-throw-raw style: network/parse failures and non-2xx responses are
+ * surfaced as HomespunApiError.
+ */
+export declare function registerAgent(opts: RegisterAgentOptions): Promise<RegisterAgentResult>;

package/dist/register.js

@@ -0,0 +1,65 @@
+// Standalone agent self-registration: POST /v1/register.
+//
+// Unlike HomespunClient operations this needs no bearer API key — registration is
+// the call that *obtains* one. Whether the relay endpoint is reachable depends
+// on its REGISTRATION_MODE: a `secret`-mode relay requires the shared
+// registration secret to be passed as a Bearer token (see the `secret` option
+// below). Abuse is bounded server-side by a per-IP rate limit (a 429 apps
+// here as a HomespunApiError with status 429).
+import { HomespunApiError } from "./client.js";
+import { MAX_RESPONSE_SNIPPET_LENGTH } from "./limits.js";
+/**
+ * Provision a fresh agent + API key from the relay. Mirrors HomespunClient.call's
+ * never-throw-raw style: network/parse failures and non-2xx responses are
+ * surfaced as HomespunApiError.
+ */
+export async function registerAgent(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const fetchImpl = opts.fetch ?? fetch;
+    const body = {};
+    if (opts.name !== undefined)
+        body["name"] = opts.name;
+    const headers = {
+        "content-type": "application/json",
+    };
+    // Sent only when the relay runs REGISTRATION_MODE=secret; harmless otherwise.
+    if (opts.secret !== undefined && opts.secret !== "") {
+        headers["authorization"] = `Bearer ${opts.secret}`;
+    }
+    if (opts.cliVersion !== undefined && opts.cliVersion !== "") {
+        headers["x-homespun-cli-version"] = opts.cliVersion;
+    }
+    let res;
+    try {
+        res = await fetchImpl(base + "/v1/register", {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new HomespunApiError(0, "fetch_error", msg);
+    }
+    let data = null;
+    const text = await res.text().catch(() => "");
+    if (text !== "") {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            const snippet = text.length > MAX_RESPONSE_SNIPPET_LENGTH
+                ? text.slice(0, MAX_RESPONSE_SNIPPET_LENGTH) + "…"
+                : text;
+            throw new HomespunApiError(res.status, "non_json_response", `relay returned a non-JSON body (status ${res.status})`, { body: snippet });
+        }
+    }
+    if (!res.ok) {
+        const err = data?.error;
+        throw new HomespunApiError(res.status, err?.code ?? "relay_error", err?.message ?? `relay returned ${res.status}`, err?.details);
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        throw new HomespunApiError(res.status, "invalid_response", `relay returned a ${res.status} with a non-object body`, { body: data });
+    }
+    return data;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const feedbackTypeSchema: z.ZodEnum<{
+    bug: "bug";
+    feature: "feature";
+    note: "note";
+}>;
+export declare const submitFeedbackSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        bug: "bug";
+        feature: "feature";
+        note: "note";
+    }>;
+    message: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+    app_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/schemas.js

@@ -0,0 +1,24 @@
+// Zod schemas for the Homespun relay request shapes. These let callers (the CLI,
+// other clients) validate user-supplied input before it hits the relay,
+// producing clear errors.
+//
+// The legacy v1 request schemas (create / list / upgrade / update /
+// mint-participant, plus their inline + reference template forms) were removed
+// when the v1 data model was dropped: they had no surviving HomespunClient
+// method and no live relay route. Only the feedback schema, still used by the
+// CLI + MCP, remains.
+import { z } from "zod";
+// POST /v1/feedback — an agent submits a bug report, feature request, or note
+// to the relay operator. Message is trimmed before length check so whitespace
+// padding cannot bypass the 1..4000 cap.
+export const feedbackTypeSchema = z.enum(["bug", "feature", "note"]);
+export const submitFeedbackSchema = z.object({
+    type: feedbackTypeSchema,
+    message: z
+        .string()
+        .transform((s) => s.trim())
+        .pipe(z.string().min(1).max(4000)),
+    // App-scoped (v2): optionally attach the feedback to an App the caller can
+    // access.
+    app_id: z.string().min(1).optional(),
+});

package/dist/stream.d.ts

@@ -0,0 +1,70 @@
+import { WebSocket } from "ws";
+import type { HomespunEvent, RecordDeltaMessage } from "./types.js";
+export interface OpenStreamOptions {
+    /** WebSocket base URL, e.g. wss://homespun.example.com (no trailing slash). */
+    wsBaseUrl: string;
+    /** Homespun id. */
+    appId: string;
+    /** Agent (or participant) bearer token. */
+    token: string;
+    /** Opaque cursor: replay only events strictly after this id. */
+    since?: string | null;
+    /**
+     * #297 — subscribe to record-collection deltas. `"*"` expands to every
+     * declared collection on the app's template; a comma list filters
+     * to those names. Absent = no record traffic (legacy event-only stream).
+     */
+    subscribeRecords?: string;
+    /**
+     * #297 — per-collection record-replay cursors. Map of collection name →
+     * last observed seq, sent as `?since_record_seq.<name>=<seq>` so the
+     * relay's replay (#295) skips already-observed rows on reconnect.
+     */
+    sinceRecordSeq?: Record<string, number>;
+}
+/** Callbacks for a live stream. */
+export interface StreamHandlers {
+    /** Fired for every event envelope (replayed and live). */
+    onEvent?: (event: HomespunEvent) => void;
+    /** Fired once when the initial event replay finishes. */
+    onReplayComplete?: () => void;
+    /**
+     * #297 — fired for every record-delta message (record.upsert /
+     * record.delete / record.replay.complete) on the stream. Per-collection
+     * record.replay.complete fires once per subscribed collection after
+     * the replay set has been drained.
+     */
+    onRecord?: (msg: RecordDeltaMessage) => void;
+    /** Fired on a relay error frame. */
+    onRelayError?: (error: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    }) => void;
+    /** Fired when the socket closes (cleanly or otherwise). */
+    onClose?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
+    /** Fired on a transport-level error. */
+    onError?: (err: Error) => void;
+}
+/** A live handle to an open stream. */
+export interface StreamHandle {
+    /** Send an event frame into the app. */
+    send(frame: {
+        type: string;
+        data?: unknown;
+        causation_id?: string;
+        idempotency_key?: string;
+    }): void;
+    /** Close the stream. */
+    close(): void;
+    /** The underlying ws socket (escape hatch). */
+    readonly socket: WebSocket;
+}
+/**
+ * Open a WebSocket stream to a Homespun app. Replays on connect, then streams
+ * live. Returns a handle for sending frames and closing.
+ */
+export declare function openStream(opts: OpenStreamOptions, handlers: StreamHandlers): StreamHandle;

package/dist/stream.js

@@ -0,0 +1,113 @@
+// WebSocket client for WS /v1/apps/:id/stream.
+//
+// The relay protocol (see the relay's src/ws/handler.ts):
+//   - on connect, the relay replays every event since `?since=` (or from the
+//     start), then sends a `{ kind: "system.replay.complete" }` marker;
+//   - thereafter it pushes live events as they land;
+//   - each frame is a JSON object: either a HomespunEvent envelope, the replay
+//     marker, an `{ ack, deduped }` for frames we sent, or an `{ error }`.
+//
+// Note: `system.participant.joined` / `system.participant.left` (and other
+// `system.*` events) arrive as ordinary `HomespunEvent` envelopes — they are not a
+// distinct frame kind, and may be interleaved with the initial replay stream
+// just like any other event.
+//
+// `openStream` exposes this as a typed event emitter over the `ws` package.
+import { WebSocket } from "ws";
+import { MAX_FRAME_SNIPPET_LENGTH } from "./limits.js";
+/**
+ * Open a WebSocket stream to a Homespun app. Replays on connect, then streams
+ * live. Returns a handle for sending frames and closing.
+ */
+export function openStream(opts, handlers) {
+    const base = opts.wsBaseUrl.replace(/\/$/, "");
+    const u = new URL(`${base}/v1/apps/${encodeURIComponent(opts.appId)}/stream`);
+    if (opts.since != null && opts.since !== "") {
+        u.searchParams.set("since", opts.since);
+    }
+    if (opts.subscribeRecords && opts.subscribeRecords.length > 0) {
+        u.searchParams.set("subscribe_records", opts.subscribeRecords);
+    }
+    if (opts.sinceRecordSeq) {
+        for (const [name, seq] of Object.entries(opts.sinceRecordSeq)) {
+            u.searchParams.set(`since_record_seq.${name}`, String(seq));
+        }
+    }
+    // Token via Authorization header (Node ws supports it); the relay also
+    // accepts ?token= but the header keeps it out of any URL access log.
+    const socket = new WebSocket(u.toString(), {
+        headers: { authorization: "Bearer " + opts.token },
+    });
+    socket.on("message", (raw) => {
+        const text = raw.toString();
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch (e) {
+            // A malformed frame must never be silently dropped — a dropped event
+            // makes `watch --type X` hang forever. Surface it as a transport error.
+            const snippet = text.length > MAX_FRAME_SNIPPET_LENGTH
+                ? text.slice(0, MAX_FRAME_SNIPPET_LENGTH) + "…"
+                : text;
+            handlers.onError?.(new Error(`failed to parse stream frame as JSON (${e instanceof Error ? e.message : String(e)}): ${snippet}`));
+            return;
+        }
+        if (!msg || typeof msg !== "object") {
+            handlers.onError?.(new Error(`unexpected non-object stream frame: ${text.slice(0, MAX_FRAME_SNIPPET_LENGTH)}`));
+            return;
+        }
+        const obj = msg;
+        if (obj["kind"] === "system.replay.complete") {
+            handlers.onReplayComplete?.();
+            return;
+        }
+        if ("error" in obj) {
+            handlers.onRelayError?.(obj["error"]);
+            return;
+        }
+        if ("ack" in obj) {
+            // Ack for a frame we sent; nothing to app by default.
+            return;
+        }
+        // #297 — record deltas. record.upsert / record.delete / record.replay.complete.
+        const kind = obj["kind"];
+        if (kind === "record.upsert" ||
+            kind === "record.delete" ||
+            kind === "record.replay.complete") {
+            handlers.onRecord?.(obj);
+            return;
+        }
+        if (typeof obj["id"] === "string" && typeof obj["type"] === "string") {
+            handlers.onEvent?.(obj);
+            return;
+        }
+        // Unrecognized frame shape — route to onError rather than dropping it.
+        handlers.onError?.(new Error(`unrecognized stream frame: ${JSON.stringify(obj).slice(0, MAX_FRAME_SNIPPET_LENGTH)}`));
+    });
+    socket.on("close", (code, reason) => {
+        handlers.onClose?.({ code, reason: reason.toString() });
+    });
+    socket.on("error", (err) => {
+        handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return {
+        send(frame) {
+            if (socket.readyState !== WebSocket.OPEN) {
+                throw new Error(`cannot send frame: stream socket is not open (readyState=${socket.readyState})`);
+            }
+            socket.send(JSON.stringify(frame));
+        },
+        close() {
+            try {
+                socket.close();
+            }
+            catch (e) {
+                console.debug("[app] stream close error:", e instanceof Error ? e.message : String(e));
+            }
+        },
+        get socket() {
+            return socket;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+export type AuthorKind = "human" | "agent" | "system";
+/** A single event envelope as emitted by the relay. */
+export interface HomespunEvent {
+    id: string;
+    app_id: string;
+    author: {
+        kind: AuthorKind;
+        id: string;
+    };
+    ts: string;
+    type: string;
+    data: unknown;
+    causation_id: string | null;
+    idempotency_key: string | null;
+    /**
+     * The template version this event was written under — the app's pinned
+     * templateVersionId at the moment of the write. Stamped at write time and
+     * never rewritten, so a downstream upgrade (#267) can read old events
+     * under the new schema (Level 1 polymorphic render). Nullable for events
+     * written before #268 landed; the relay's one-shot migration backfilled
+     * those from the app's current pin where possible.
+     */
+    template_version_id: string | null;
+    /** Denormalised integer version number for `template_version_id`. */
+    template_version: number | null;
+}
+/**
+ * One record on the wire (#287). Returned by the records CRUD routes
+ * (#292) and by the WS record-delta messages (#294). Structurally
+ * identical to the relay-side SerializedRecord; mirrored here so the
+ * core package is self-contained.
+ */
+export interface SerializedRecord {
+    id: string;
+    collection: string;
+    key: string;
+    data: unknown;
+    version: number;
+    seq: number;
+    author: {
+        kind: AuthorKind;
+        id: string;
+    };
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+/** Wire shape for a soft-deleted record on the WS channel. */
+export interface DeletedRecordRef {
+    id: string;
+    key: string;
+    seq: number;
+    deleted_at: string;
+}
+/** Discriminated wire shape for record-state changes. */
+export type RecordDeltaMessage = {
+    kind: "record.upsert";
+    collection: string;
+    record: SerializedRecord;
+} | {
+    kind: "record.delete";
+    collection: string;
+    record: DeletedRecordRef;
+} | {
+    kind: "record.replay.complete";
+    collection: string;
+    seq: number;
+};
+/**
+ * An template: discriminated on `type`. `html-inline` carries raw HTML in
+ * `source`; `html-ref` carries a URL the relay/shell fetches on the human's
+ * behalf. The discriminant keeps the type↔source coupling explicit.
+ */
+export type Template = {
+    type: "html-inline";
+    source: string;
+} | {
+    type: "html-ref";
+    source: string;
+};
+/** Optional webhook callback config. */
+export interface Callback {
+    url: string;
+    events: string[];
+    secret: string;
+}
+/**
+ * Response from 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.
+ */
+export interface KeyInfo {
+    agent_id: string;
+    name: string | null;
+    key_prefix: string;
+    created_at: string;
+    last_used_at: string | null;
+    revoked_at: string | null;
+}
+/**
+ * Response from GET /v1/taste, PUT /v1/taste — the calling agent's freeform
+ * "taste notes" markdown attachment (presentation preferences the agent has picked
+ * up from human feedback over time). `taste` and `updated_at` are null when
+ * the agent has never written notes; `bytes` is the utf8 byte length and 0
+ * when `taste` is null.
+ */
+export interface TasteInfo {
+    taste: string | null;
+    updated_at: string | null;
+    bytes: number;
+}
+/** A feedback `type` discriminant accepted by POST /v1/feedback. */
+export type FeedbackType = "bug" | "feature" | "note";
+/** Response from POST /v1/feedback — id, type, created_at only (no message echo). */
+export interface FeedbackSubmission {
+    id: string;
+    type: FeedbackType;
+    created_at: string;
+}
+/** A row from GET /v1/feedback, the full record including message. */
+export interface FeedbackRecord {
+    id: string;
+    type: FeedbackType;
+    message: string;
+    app_id: string | null;
+    created_at: string;
+}
+/** Response from GET /v1/feedback — page of the calling agent's own submissions. */
+export interface FeedbackPage {
+    items: FeedbackRecord[];
+    next_before?: string;
+}
+/** A relay error envelope. */
+export interface RelayError {
+    code: string;
+    message?: string;
+    details?: unknown;
+    /** Agent-friendly remediation hint. */
+    hint?: string;
+    /** Whether retrying the same request may succeed. */
+    retryable?: boolean;
+    /** Documentation URL for this error class (snake_case on the wire). */
+    docs_url?: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// Wire types for the Homespun relay HTTP + WebSocket API.
+//
+// These mirror the relay's public response shapes (see the relay's
+// src/types.ts, src/http/serialize.ts and src/http/routes/*). They are
+// re-declared here rather than imported from @homespunapps/relay so that @homespunapps/core
+// stays pure and framework-free — no Prisma, no Hono, no server deps.
+export {};