@kottera/tera-web 0.0.0-stage → 0.1.0-rc.2

package/dist/feed/sse.js

@@ -0,0 +1,134 @@
+// The server-sent-events transport under the feed connection: D3's
+// `GET /tera/v1/feeds/{feed}` is read with fetch rather than EventSource,
+// because EventSource hides the HTTP status a refusal is told apart by and
+// reconnects on its own schedule, which is the connection's to decide
+// (ADR-162 D4 item 2).
+/**
+ * SSEParser turns the text of an event stream, in whatever chunks it arrives,
+ * into events, as the WHATWG event-stream grammar reads it: `\n`, `\r\n` and
+ * `\r` all end a line, a blank line dispatches, a line starting `:` is a
+ * comment, and `data` lines join with `\n`. `id` and `retry` are read and
+ * dropped — the connection keeps its own cursor and its own backoff.
+ */
+export class SSEParser {
+    buffer = "";
+    event = "";
+    data = [];
+    push(chunk) {
+        this.buffer += chunk;
+        const out = [];
+        for (;;) {
+            const at = this.buffer.search(/\r\n|\r|\n/);
+            if (at < 0)
+                break;
+            // A `\r` at the very end may be the first half of a `\r\n` split across
+            // chunks: wait for the next one before reading the line.
+            if (this.buffer[at] === "\r" && at === this.buffer.length - 1)
+                break;
+            const width = this.buffer.startsWith("\r\n", at) ? 2 : 1;
+            const line = this.buffer.slice(0, at);
+            this.buffer = this.buffer.slice(at + width);
+            this.line(line, out);
+        }
+        return out;
+    }
+    line(line, out) {
+        if (line === "") {
+            if (this.data.length > 0) {
+                out.push({ event: this.event || "message", data: this.data.join("\n") });
+            }
+            this.event = "";
+            this.data = [];
+            return;
+        }
+        if (line.startsWith(":"))
+            return;
+        const colon = line.indexOf(":");
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            this.event = value;
+        else if (field === "data")
+            this.data.push(value);
+    }
+}
+/** A feed route that answered with something other than an event stream. */
+export class FeedOpenError extends Error {
+    /** The HTTP status the route answered with. */
+    status;
+    /** The answer's content type. */
+    contentType;
+    /** As much of the body as was read: the kit's error envelope, on a refusal (ADR-162 D2 item 8). */
+    body;
+    constructor(status, contentType, body) {
+        super(`feed route answered HTTP ${status} (${contentType || "no content type"})${body ? ": " + body : ""}`);
+        this.name = "FeedOpenError";
+        this.status = status;
+        this.contentType = contentType;
+        this.body = body;
+    }
+}
+/** The most of a refusal's body kept on a {@link FeedOpenError}. */
+const BODY_LIMIT = 2048;
+/**
+ * isRefusal reports whether an open failed in a way trying again cannot fix,
+ * so the connection stops rather than retrying it (ADR-162 D4 item 2). A 4xx
+ * is a refusal — the person may not, or the feed is not there — except 408 and
+ * 429, which say "later". So is 501, and so is a success that is not an event
+ * stream: that is a page served where the kit's route should be, which no
+ * retry turns into a feed. Anything else — a 5xx, a dropped connection — is a
+ * transport failure, and is retried.
+ */
+export function isRefusal(err) {
+    if (!(err instanceof FeedOpenError))
+        return false;
+    const { status } = err;
+    if (status >= 200 && status < 300)
+        return true;
+    if (status === 501)
+        return true;
+    return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+/**
+ * fetchOpener is the {@link FeedOpener} a browser uses: a same-origin `GET`
+ * read as an event stream. `fetchFn` is injectable so the transport itself is
+ * tested without a network.
+ */
+export function fetchOpener(fetchFn = (...args) => globalThis.fetch(...args)) {
+    return async (url, onEvent, signal) => {
+        const response = await fetchFn(url, {
+            method: "GET",
+            headers: { Accept: "text/event-stream" },
+            credentials: "same-origin",
+            cache: "no-store",
+            signal,
+        });
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!response.ok || !contentType.toLowerCase().startsWith("text/event-stream") || response.body === null) {
+            let body = "";
+            try {
+                body = (await response.text()).slice(0, BODY_LIMIT);
+            }
+            catch {
+                // The body is evidence, not the verdict: the status decides.
+            }
+            throw new FeedOpenError(response.status, contentType, body);
+        }
+        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+        const parser = new SSEParser();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                for (const e of parser.push(value))
+                    onEvent(e);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    };
+}

package/dist/generated/feed.d.ts

@@ -0,0 +1,199 @@
+/**
+ * feed connect-time parameters.
+ *
+ * The query parameters of a feed URL (`GET /feeds/<name>?…`), each a repeatable query key. The query is a closed vocabulary: an unknown parameter is refused at connect.
+ *
+ * Schema: sdk/feed/schema/v1/connect.params.json
+ */
+export type FeedConnectParams = {
+    /** Precedes the live stream with the stored history of the selected run. */
+    backfill?: "all";
+    /** Overrides the delivery window: a duration such as `2s`, or `0` for no batching. */
+    batch_window?: string;
+    /** Selects a subset of the topics the connection would otherwise receive; each occurrence may be a comma-separated list. */
+    topics?: string[];
+    /** Adds or tightens one predicate, `<field>=<value>[,<value>…]`, once per field. */
+    where?: string[];
+};
+/**
+ * The vocabulary of the feed drop reason (sdk/feed.DropReason).
+ *
+ * Every member the daemon writes. A later level adds members and removes none (ADR-143 D3); how a consumer reads an unknown member is ADR-143 D13's.
+ *
+ * Schema: sdk/feed/schema/v1/drop-reason.json
+ */
+export type FeedDropReason = "slow_consumer" | "rate_limit" | "connection_closed";
+/**
+ * The vocabulary of the feed frame `type` (sdk/feed.FrameType).
+ *
+ * Every member the daemon writes. A later level adds members and removes none (ADR-143 D3); how a consumer reads an unknown member is ADR-143 D13's.
+ *
+ * Schema: sdk/feed/schema/v1/frame-type.json
+ */
+export type FeedFrameType = "record" | "status" | "heartbeat" | "batch";
+/**
+ * `batch` frame (tera.feed.v1).
+ *
+ * A `batch` frame, generated from feed.BatchFrame.
+ *
+ * Schema: sdk/feed/schema/v1/frame.batch.json
+ */
+export type FeedFrameBatch = {
+    /** The frame's type; a consumer skips a frame whose type it does not know (ADR-143 D13). */
+    type: string;
+    /** The feed's name. */
+    feed: string;
+    /** This frame's own place in the connection's sequence; the records inside precede it. */
+    seq: number;
+    /** When the daemon wrote the frame, RFC 3339. */
+    at: string;
+    /** The delivery window in force, in seconds. */
+    window_seconds: number;
+    /** The number of records in the batch. */
+    count: number;
+    /** The window's records, in order; each element is a record frame. */
+    records: unknown[] | null;
+    /** Records dropped during this window. */
+    dropped?: number;
+    /** The connection's running total of dropped records. */
+    dropped_total?: number;
+    /** Why records were dropped; a member of the drop-reason vocabulary. */
+    drop_reason?: string;
+};
+/**
+ * `heartbeat` frame (tera.feed.v1).
+ *
+ * A `heartbeat` frame, generated from feed.HeartbeatFrame.
+ *
+ * Schema: sdk/feed/schema/v1/frame.heartbeat.json
+ */
+export type FeedFrameHeartbeat = {
+    /** The frame's type; a consumer skips a frame whose type it does not know (ADR-143 D13). */
+    type: string;
+    /** The feed's name. */
+    feed: string;
+    /** This frame's place in the connection's single sequence, which has no gaps. */
+    seq: number;
+    /** When the daemon wrote the frame, RFC 3339. */
+    at: string;
+    /** How long the connection has been idle, in seconds. */
+    idle_seconds: number;
+    /** The connection's running total of dropped records. */
+    dropped_total?: number;
+};
+/**
+ * `record` frame (tera.feed.v1).
+ *
+ * A `record` frame, generated from feed.RecordFrame.
+ *
+ * Schema: sdk/feed/schema/v1/frame.record.json
+ */
+export type FeedFrameRecord = {
+    /** The frame's type; a consumer skips a frame whose type it does not know (ADR-143 D13). */
+    type: string;
+    /** The feed's name. */
+    feed: string;
+    /** This record's place in the connection's single sequence, which has no gaps. */
+    seq: number;
+    /** The broker topic the record was published on. */
+    topic: string;
+    /** When the daemon observed the record, RFC 3339. */
+    observed_at: string;
+    /** The publishing principal, when one is known (ADR-083 D11). */
+    publisher?: string;
+    /** Whether the publisher was verified rather than claimed (ADR-011 Amendment 1); always present. */
+    publisher_verified: boolean;
+    /** The content type the publishing adapter declared: raw, json, text, protobuf, jsonrpc, formdata, or unknown/<n>. A label, not the arbiter of which payload key is set. */
+    content_type: string;
+    /** The record's payload as JSON, when its content type is JSON; its shape is the publishing family's. */
+    payload?: unknown;
+    /** The record's payload, when it is valid UTF-8 that is not JSON. */
+    payload_text?: string;
+    /** The record's payload, base64-encoded, when it is neither JSON nor UTF-8 text. */
+    payload_base64?: string;
+};
+/**
+ * `status` frame (tera.feed.v1).
+ *
+ * A `status` frame, generated from feed.StatusFrame.
+ *
+ * Schema: sdk/feed/schema/v1/frame.status.json
+ */
+export type FeedFrameStatus = {
+    /** The frame's type; a consumer skips a frame whose type it does not know (ADR-143 D13). */
+    type: string;
+    /** The status value; a consumer reads one it does not know as possible loss and reconciles (ADR-143 D13). */
+    status: string;
+    /** The feed's name. */
+    feed: string;
+    /** This frame's place in the connection's single sequence, which has no gaps. */
+    seq: number;
+    /** When the daemon wrote the frame, RFC 3339. */
+    at: string;
+    /** A human-readable explanation. Never the machine-readable answer: that is status. */
+    message?: string;
+    /** Accompanies open and partial_authorization. On open, the effective filter set this connection delivers, after any connect-time narrowing. */
+    filters?: string[];
+    /** Accompanies open and partial_authorization: the feed's filters the principal is not granted. */
+    denied?: string[];
+    /** On narrowed, the authorized filter set the connection was narrowed from. */
+    narrowed_from?: string[];
+    /** On narrowed, the effective predicates after the client's request was folded into the feed's own. */
+    where?: string[];
+    /** On open, the heartbeat interval in seconds: the consumer's silence budget. */
+    heartbeat_interval_seconds?: number;
+    /** On open, on a batching connection, the effective delivery window in seconds. */
+    batch_window_seconds?: number;
+    /** On open, on a batching connection, the ceiling on one batch's record count. */
+    batch_max_records?: number;
+    /** On records_dropped, the records dropped since the last report. */
+    dropped?: number;
+    /** The connection's running total of dropped records; also carried on every terminal frame. */
+    dropped_total?: number;
+    /** Why records were dropped; a member of the drop-reason vocabulary. */
+    drop_reason?: string;
+    /** On a terminal frame, the WebSocket close code that follows it. */
+    close_code?: number;
+    /** On backfill_gap and backfill_unavailable, the run the statement is about. */
+    run?: string;
+    /** On backfill_gap, the first day of the inclusive range the store no longer reaches. */
+    missing_from?: string;
+    /** On backfill_gap, the last day of the inclusive range the store no longer reaches. */
+    missing_to?: string;
+    /** On backfill_gap, the number of days in the missing range. */
+    missing_days?: number;
+    /** On backfill_gap, records lost inside days that were read. */
+    missing_records?: number;
+    /** On backfill_gap and backfill_unavailable, the machine-readable cause. Its vocabulary is not yet part of this contract. */
+    reason?: string;
+    /** On backfill_unavailable, the partition's admission sampling rate: one session in N is kept (ADR-114 D8). */
+    sampling_rate?: number;
+    /** On backfill_complete, how many records came from the store. */
+    records?: number;
+    /** On backfill_complete, how many sessions those records came from. */
+    sessions?: number;
+    /** On backfill_degraded, the stored record schema versions the daemon met and does not understand. */
+    schema_versions?: number[];
+};
+/**
+ * The vocabulary of the feed `status` value (sdk/feed.Status).
+ *
+ * Every member the daemon writes. A later level adds members and removes none (ADR-143 D3); how a consumer reads an unknown member is ADR-143 D13's.
+ *
+ * Schema: sdk/feed/schema/v1/status.json
+ */
+export type FeedStatus = "open" | "partial_authorization" | "narrowed" | "records_dropped" | "upstream_lost" | "shutting_down" | "selection_changed" | "credential_expired" | "backfill_complete" | "backfill_gap" | "backfill_unavailable" | "backfill_degraded";
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const FEED_SCHEMAS: {
+    readonly FeedConnectParams: "sdk/feed/schema/v1/connect.params.json";
+    readonly FeedDropReason: "sdk/feed/schema/v1/drop-reason.json";
+    readonly FeedFrameType: "sdk/feed/schema/v1/frame-type.json";
+    readonly FeedFrameBatch: "sdk/feed/schema/v1/frame.batch.json";
+    readonly FeedFrameHeartbeat: "sdk/feed/schema/v1/frame.heartbeat.json";
+    readonly FeedFrameRecord: "sdk/feed/schema/v1/frame.record.json";
+    readonly FeedFrameStatus: "sdk/feed/schema/v1/frame.status.json";
+    readonly FeedStatus: "sdk/feed/schema/v1/status.json";
+};

package/dist/generated/feed.js

@@ -0,0 +1,16 @@
+// Code generated by cmd/internal/genwebtypes from sdk/feed/schema/v1/; DO NOT EDIT.
+// Regenerate with `make web-types` (ADR-162 D4 item 1).
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export const FEED_SCHEMAS = {
+    FeedConnectParams: "sdk/feed/schema/v1/connect.params.json",
+    FeedDropReason: "sdk/feed/schema/v1/drop-reason.json",
+    FeedFrameType: "sdk/feed/schema/v1/frame-type.json",
+    FeedFrameBatch: "sdk/feed/schema/v1/frame.batch.json",
+    FeedFrameHeartbeat: "sdk/feed/schema/v1/frame.heartbeat.json",
+    FeedFrameRecord: "sdk/feed/schema/v1/frame.record.json",
+    FeedFrameStatus: "sdk/feed/schema/v1/frame.status.json",
+    FeedStatus: "sdk/feed/schema/v1/status.json",
+};

package/dist/generated/kit.d.ts

@@ -0,0 +1,246 @@
+import type { FeedFrameRecord, FeedFrameStatus } from "./feed.ts";
+/**
+ * The vocabulary of the kit's own error codes (sdk/plugin/webui.KitCodes).
+ *
+ * Every code the kit answers with when no verb gave a verdict. Only tera_unavailable is retryable. A failure envelope may also carry a verb's own code, or tera's own code for a call it refused, verbatim, which is not a member: a reader keeps a code it does not know as it arrived and branches on retryable.
+ *
+ * Schema: sdk/plugin/webui/schema/v1/error-code.json
+ */
+export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable";
+/**
+ * Kit error envelope.
+ *
+ * Every kit route's failure (ADR-162 D2 item 8). The outer form is ADR-035's management-API envelope.
+ *
+ * Schema: sdk/plugin/webui/schema/v1/error.json
+ */
+export type KitError = {
+    /** The failure. */
+    error: {
+        /** What failed: one of the kit's own codes (the error-code vocabulary) when the kit refused before any verb ran, tera's own code, verbatim, when tera refused a call the kit relayed, or a verb's own code, verbatim, when a verb refused. A code a reader does not know is kept as it arrived. */
+        code: string;
+        /** A sentence for a person saying what failed. Never carries a secret. */
+        message: string;
+        /** Whether the identical request may succeed if it is sent again later with nothing changed. A reader branches on this, never on a list of codes. */
+        retryable: boolean;
+        /** How long to wait before retrying, in milliseconds, when the refusing verb said. */
+        retry_after_ms?: number;
+        /** Structured detail the refusing verb attached, whose shape the verb decides. The kit's own refusals attach none. */
+        data?: unknown;
+    };
+};
+/**
+ * The feed's reauthenticate event.
+ *
+ * The data of the last event of a feed stream closed because the person's token expired.
+ *
+ * Schema: sdk/plugin/webui/schema/v1/feed.event.reauthenticate.json
+ */
+export type KitFeedEventReauthenticate = {
+    /** Why the stream closed. token_expired is the reason this version sends; a reader reconnects at once whatever the reason. */
+    reason: string;
+};
+/**
+ * POST /tera/v1/invoke/{capability} response.
+ *
+ * The verb's reply envelope, HTTP 200 whenever the verb ran: workorder.HTTPInvoker's reading of the management invoke route.
+ *
+ * Schema: sdk/plugin/webui/schema/v1/invoke.response.json
+ */
+export type KitInvokeResponse = {
+    /** success when the verb answered; error when it refused. */
+    status: "success" | "error";
+    /** The verb's answer, present when status is success. */
+    result?: {
+        /** The verb's result. For a work_order.* verb, valid against sdk/workorder/schema/v1/<verb>.result.json. */
+        structured: unknown;
+    };
+    /** The verb's refusal, present when status is error. */
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+        retry_after_ms?: number;
+        /** Structured detail the refusing tool attached, whose shape the tool and its code decide. */
+        data?: unknown;
+    };
+};
+/**
+ * GET /tera/v1/me response.
+ *
+ * The signed-in person.
+ *
+ * Schema: sdk/plugin/webui/schema/v1/me.response.json
+ */
+export type KitMeResponse = {
+    /** The signed-in person, as tera's caller assertion names them: spelled as a Work Order that person filed would name them. */
+    subject: string;
+    /** Where to send the person to sign out: tera's own path, which ends their session for every plugin. */
+    signout_path: string;
+};
+/**
+ * POST /tera/v1/uploads response.
+ *
+ * The staged artifact an upload made (ADR-123).
+ *
+ * Schema: sdk/plugin/webui/schema/v1/upload.response.json
+ */
+export type KitUploadResponse = {
+    /** The artifact handle, which a Work Order's attachments name. */
+    handle: string;
+    /** The file's name, as the upload gave it. */
+    filename: string;
+    /** The file's media type, as the upload gave it. */
+    mime_type: string;
+    /** The file's length in bytes. */
+    size_bytes: number;
+    /** The sha256 of the bytes tera stored, as sha256:<hex>. */
+    digest: string;
+    /** The file's description, when the upload gave one. */
+    description?: string;
+    /** When the staged artifact is discarded if no Work Order has attached it, in RFC 3339. */
+    staged_expires_at: string;
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const KIT_SCHEMAS: {
+    readonly KitErrorCode: "sdk/plugin/webui/schema/v1/error-code.json";
+    readonly KitError: "sdk/plugin/webui/schema/v1/error.json";
+    readonly KitFeedEventReauthenticate: "sdk/plugin/webui/schema/v1/feed.event.reauthenticate.json";
+    readonly KitInvokeResponse: "sdk/plugin/webui/schema/v1/invoke.response.json";
+    readonly KitMeResponse: "sdk/plugin/webui/schema/v1/me.response.json";
+    readonly KitUploadResponse: "sdk/plugin/webui/schema/v1/upload.response.json";
+};
+/** The prefix every kit route is served under (ADR-162 D3). */
+export declare const KIT_ROUTE_PREFIX = "/tera/v1/";
+/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path. */
+export declare const KIT_SIGNOUT_PATH = "/_tera/signout";
+/** The kit's route table (ADR-162 D3), as sdk/plugin/webui declares it. */
+export declare const KIT_ROUTE_TABLE: {
+    readonly prefix: "/tera/v1/";
+    readonly signout_path: "/_tera/signout";
+    readonly same_origin: "A route marked same_origin refuses a request unless it is same-origin: when the request carries Sec-Fetch-Site, that header must be same-origin; when it does not, its Origin must equal the request's own (scheme http or https, and the Host the request was sent to). The refusal is 403 cross_origin.";
+    readonly public: "None. Every route under the prefix refuses a request with no verified caller, 401 unauthenticated, before anything else is decided. Only the app's assets, outside the prefix, are served to an anonymous request.";
+    readonly error: {
+        readonly media_type: "application/json";
+        readonly schema: "https://kottera.dev/schemas/plugin/webui/error/v1";
+        readonly description: "Every failure of every route: the kit's own refusal, under one of the error-code vocabulary, or a verb's refusal passed through as the verb gave it.";
+    };
+    readonly routes: readonly [{
+        readonly name: "me";
+        readonly method: "GET";
+        readonly path: "/tera/v1/me";
+        readonly summary: "Who is signed in, and where to send them to sign out.";
+        readonly same_origin: false;
+        readonly response: {
+            readonly media_type: "application/json";
+            readonly schema: "https://kottera.dev/schemas/plugin/webui/me.response/v1";
+            readonly description: "The signed-in person.";
+        };
+    }, {
+        readonly name: "invoke";
+        readonly method: "POST";
+        readonly path: "/tera/v1/invoke/{capability}";
+        readonly summary: "Invoke one capability as the person, with the request body as its params. tera decides it on the person's token; the kit vets nothing.";
+        readonly same_origin: true;
+        readonly path_params: readonly [{
+            readonly name: "capability";
+            readonly description: "The capability to invoke, e.g. work_order.get.";
+            readonly required: true;
+        }];
+        readonly request: {
+            readonly media_type: "application/json";
+            readonly description: "The capability's params. For a work_order.* verb, valid against sdk/workorder/schema/v1/<verb>.params.json.";
+        };
+        readonly response: {
+            readonly media_type: "application/json";
+            readonly schema: "https://kottera.dev/schemas/plugin/webui/invoke.response/v1";
+            readonly description: "The verb's reply envelope, HTTP 200 whenever the verb ran, refusals included.";
+        };
+    }, {
+        readonly name: "feed";
+        readonly method: "GET";
+        readonly path: "/tera/v1/feeds/{feed}";
+        readonly summary: "Open a feed as the person: server-sent events carrying feed records and status frames verbatim.";
+        readonly same_origin: false;
+        readonly path_params: readonly [{
+            readonly name: "feed";
+            readonly description: "The feed's name.";
+            readonly required: true;
+        }];
+        readonly query: readonly [{
+            readonly name: "topics";
+            readonly description: "Selects a subset of the topics the person may subscribe to; each occurrence may be a comma-separated list. Widening is refused.";
+            readonly repeated: true;
+        }, {
+            readonly name: "backfill";
+            readonly description: "Precede the live stream with the stored history of the run the connection selected.";
+            readonly values: readonly ["all"];
+        }];
+        readonly response: {
+            readonly media_type: "text/event-stream";
+            readonly description: "A stream of the events below, until the person's token expires or either side closes it. Any other feed frame (a heartbeat, a batch, a type this kit does not know) is relayed verbatim as an unnamed event, read by its own type.";
+        };
+        readonly events: readonly [{
+            readonly name: "record";
+            readonly schema: "https://kottera.dev/schemas/feed/frame.record/v1";
+            readonly description: "A feed record frame, verbatim.";
+        }, {
+            readonly name: "status";
+            readonly schema: "https://kottera.dev/schemas/feed/frame.status/v1";
+            readonly description: "A feed status frame, verbatim; loss is reported here and nowhere else.";
+        }, {
+            readonly name: "reauthenticate";
+            readonly schema: "https://kottera.dev/schemas/plugin/webui/feed.event.reauthenticate/v1";
+            readonly description: "The last event of a stream closed because the person's token expired. Reconnect at once.";
+        }];
+    }, {
+        readonly name: "upload";
+        readonly method: "POST";
+        readonly path: "/tera/v1/uploads";
+        readonly summary: "Upload one file as the person (ADR-123): the kit streams the body once, digesting it, then authorizes and stores it.";
+        readonly same_origin: true;
+        readonly headers: readonly [{
+            readonly name: "Content-Type";
+            readonly description: "The file's media type.";
+            readonly required: true;
+        }, {
+            readonly name: "Tera-Upload-Filename";
+            readonly description: "The file's name, percent-encoded UTF-8.";
+            readonly required: true;
+        }, {
+            readonly name: "Tera-Upload-Description";
+            readonly description: "A description of the file, percent-encoded UTF-8.";
+        }];
+        readonly request: {
+            readonly media_type: "application/octet-stream";
+            readonly description: "The file's bytes, any media type. The body is read against its declared Content-Length, capped by the 33554432-byte (32 MiB) bound on an input artifact; a body with no declared length is held to the cap. A declaration over the cap is refused before the body is read, and a body is refused at the first byte past its bound, never after it is read whole.";
+        };
+        readonly response: {
+            readonly media_type: "application/json";
+            readonly schema: "https://kottera.dev/schemas/plugin/webui/upload.response/v1";
+            readonly description: "The staged artifact.";
+        };
+    }];
+};
+/** The name of a route in KIT_ROUTE_TABLE. */
+export type KitRouteName = (typeof KIT_ROUTE_TABLE)["routes"][number]["name"];
+/**
+ * The JSON body each route answers on success, by route name. A route not
+ * here answers a body that is not JSON.
+ */
+export type KitRouteResponses = {
+    me: KitMeResponse;
+    invoke: KitInvokeResponse;
+    upload: KitUploadResponse;
+};
+/** The data of each server-sent event a feed stream carries, by event name. */
+export type KitFeedEvents = {
+    record: FeedFrameRecord;
+    status: FeedFrameStatus;
+    reauthenticate: KitFeedEventReauthenticate;
+};
+/** Every route's failure body. */
+export type KitRouteError = KitError;