@superbee/core 0.2.0-pre.3 → 0.2.0-pre.30

package/dist/hosted-transport/carrier.js

@@ -0,0 +1,260 @@
+import { isAgentLabelVia, isWriteRequestId, isWriteBinding } from "../write-identity.js";
+/** The header that carries {@link HostedRequestOptions.workspace}. */
+export const WORKSPACE_HEADER = "Superbee-Workspace";
+/** A namespaced tenant id (`tenant:holaxis`, `org:…`): the shape the host checks before admission. */
+const TENANT_ID = /^[a-z][a-z0-9-]{0,15}:[A-Za-z0-9._-]{1,128}$/;
+/** Whether `value` has the shape of a tenant id the workspace header may carry. */
+export function isWorkspaceTenantId(value) {
+    return typeof value === "string" && TENANT_ID.test(value);
+}
+/** The header that carries {@link HostedRequestOptions.acceptDeletes}. */
+export const ACCEPT_DELETES_HEADER = "X-Superbee-Accept-Deletes";
+/** The largest acknowledgment the host admits. */
+export const MAXIMUM_ACCEPTED_DELETIONS = 100000;
+/** Whether `value` is an acknowledgment count the host admits: an integer from 1 to 100,000. */
+export function isAcceptedDeletionCount(value) {
+    return Number.isSafeInteger(value) && value >= 1 && value <= MAXIMUM_ACCEPTED_DELETIONS;
+}
+/** The header that carries {@link HostedRequestOptions.recreate}. */
+export const RECREATE_HEADER = "X-Superbee-Recreate";
+/** The header that carries {@link HostedRequestOptions.via}. */
+export const VIA_HEADER = "X-Superbee-Via";
+/**
+ * Whether `value` is a `via` token the host admits: 1 to 32 characters of `[a-z0-9._-]`, never
+ * starting with `superbee` (Superbee's own names). The same rule as the host's `isAgentLabelVia`;
+ * the `/sync/v1` golden exchanges (`create-200-ok-via`, `write-400-invalid-via`) pin the header
+ * and the host's refusal. A token the host refused would make every write a terminal 400.
+ */
+export { isAgentLabelVia } from "../write-identity.js";
+/**
+ * The cause a carrier's `unavailable` carries when the answer was larger than the request's
+ * `maximum`: the host answered, and the same request gets the same answer, so a reader may report
+ * it as a deterministic refusal rather than an outage. The carrier's code stays `unavailable`.
+ */
+export class HostedAnswerTooLarge extends Error {
+    name = "HostedAnswerTooLarge";
+    maximum;
+    constructor(maximum) {
+        super(`the answer is larger than ${maximum} bytes`);
+        this.maximum = maximum;
+    }
+}
+/** True when `error` is a carrier failure because the answer exceeded its bound. */
+export function isAnswerTooLarge(error) {
+    return error instanceof HostedCarrierError && error.cause instanceof HostedAnswerTooLarge;
+}
+export class HostedCarrierError extends Error {
+    name = "HostedCarrierError";
+    code;
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+    }
+}
+const ROUTE_HEADER = /^x-superbee-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ROUTE_HEADER_VALUE = /^[\x20-\x7e]{0,1024}$/;
+async function readBounded(response, maximum) {
+    if (!response.body)
+        return undefined;
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > maximum)
+                throw new HostedCarrierError("unavailable", { cause: new HostedAnswerTooLarge(maximum) });
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    if (size === 0)
+        return undefined;
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes));
+    }
+    catch (cause) {
+        throw new HostedCarrierError("unavailable", { cause });
+    }
+}
+/** Restart `deadlineMs` at every chunk, so a slow but live stream is not cut and a stalled one is. */
+function idleBounded(body, deadlineMs, abort) {
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = setTimeout(abort, deadlineMs);
+    };
+    arm();
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            arm();
+            controller.enqueue(chunk);
+        },
+        flush() {
+            clearTimeout(timer);
+        },
+        // A consumer that stops reading, or a body that fails, never reaches flush; a live timer
+        // would hold the process open for the rest of the deadline.
+        cancel() {
+            clearTimeout(timer);
+        },
+    }));
+}
+/** A request's headers: its own fields, then the credential and the content headers, which always win. */
+function requestHeaders(credentials, extra, type) {
+    const headers = new Headers(extra);
+    for (const [name, value] of Object.entries(credentials))
+        headers.set(name, value);
+    headers.set("Content-Type", type);
+    headers.set("Accept", "application/json");
+    return headers;
+}
+/**
+ * A carrier over `fetch` with caller-supplied credential headers: the shape the CLI's bearer
+ * carrier takes. Requests are `POST` with a JSON body (or, through `bytes`, a raw one), never follow
+ * redirects, and are refused before sending when the identity, binding or a route header is
+ * malformed.
+ */
+export function createFetchCarrier(options) {
+    const fetcher = options.fetch ?? fetch;
+    const deadlineMs = options.deadlineMs ?? 15_000;
+    const bindingHeader = options.bindingHeader ?? "X-Superbee-Checkout";
+    const base = new URL(options.baseUrl);
+    async function send(path, body, signal, extra, deadline) {
+        if (!path.startsWith("/"))
+            throw new TypeError(`hosted route '${path}' must be absolute`);
+        let credentials;
+        try {
+            credentials = await options.credentials(signal);
+        }
+        catch (cause) {
+            throw new HostedCarrierError("denied", { cause });
+        }
+        if (signal.aborted)
+            throw new HostedCarrierError("denied");
+        // A credential header `fetch` cannot carry is no credential: nothing is sent.
+        let headers;
+        try {
+            headers = requestHeaders(credentials, extra, body.type);
+        }
+        catch (cause) {
+            throw new HostedCarrierError("denied", { cause });
+        }
+        try {
+            return await fetcher(new URL(path, base), {
+                method: "POST",
+                redirect: "error",
+                headers,
+                body: body.content,
+                signal: AbortSignal.any([signal, deadline]),
+            });
+        }
+        catch (cause) {
+            throw new HostedCarrierError("unavailable", { cause });
+        }
+    }
+    const jsonBody = (input) => ({ type: "application/json", content: JSON.stringify(input) });
+    // Headers the carrier sets itself, which a route's own fields never name.
+    const owned = new Set(["x-superbee-write-request", bindingHeader.toLowerCase(), RECREATE_HEADER.toLowerCase(), VIA_HEADER.toLowerCase(), ACCEPT_DELETES_HEADER.toLowerCase(), WORKSPACE_HEADER.toLowerCase()]);
+    /**
+     * The headers the carrier owns for one request, each refused before sending when malformed. The
+     * one place a JSON and a raw request derive their identity, binding, `recreate`, `via` and
+     * deletion acknowledgment headers.
+     */
+    function carrierHeaders(request) {
+        if (request.writeRequest !== undefined && !isWriteRequestId(request.writeRequest))
+            throw new HostedCarrierError("denied");
+        if (request.binding !== undefined && !isWriteBinding(request.binding))
+            throw new HostedCarrierError("denied");
+        if (request.recreate !== undefined && !isWriteBinding(request.recreate))
+            throw new HostedCarrierError("denied");
+        if (request.via !== undefined && !isAgentLabelVia(request.via))
+            throw new HostedCarrierError("denied");
+        if (request.acceptDeletes !== undefined && !isAcceptedDeletionCount(request.acceptDeletes))
+            throw new HostedCarrierError("denied");
+        if (request.workspace !== undefined && !isWorkspaceTenantId(request.workspace))
+            throw new HostedCarrierError("denied");
+        const headers = {};
+        if (request.writeRequest !== undefined)
+            headers["X-Superbee-Write-Request"] = request.writeRequest;
+        if (request.binding !== undefined)
+            headers[bindingHeader] = request.binding;
+        if (request.recreate !== undefined)
+            headers[RECREATE_HEADER] = request.recreate;
+        if (request.via !== undefined)
+            headers[VIA_HEADER] = request.via;
+        if (request.acceptDeletes !== undefined)
+            headers[ACCEPT_DELETES_HEADER] = String(request.acceptDeletes);
+        if (request.workspace !== undefined)
+            headers[WORKSPACE_HEADER] = request.workspace;
+        return headers;
+    }
+    async function answer(path, body, signal, extra, maximum) {
+        // An answer is always read within a bound: an unset or nonsensical maximum refuses before sending.
+        if (!Number.isSafeInteger(maximum) || maximum <= 0)
+            throw new HostedCarrierError("denied");
+        const deadline = AbortSignal.timeout(deadlineMs);
+        const response = await send(path, body, signal, extra, deadline);
+        let read;
+        try {
+            read = await readBounded(response, maximum);
+        }
+        catch (error) {
+            // A refusal's envelope is best effort: its status already decides, and an unreadable
+            // body must never read as "not applied".
+            if (response.ok)
+                throw error instanceof HostedCarrierError ? error : new HostedCarrierError("unavailable", { cause: error });
+            read = undefined;
+        }
+        return { status: response.status, headers: response.headers, body: read };
+    }
+    return {
+        async json(path, input, signal, request) {
+            return answer(path, jsonBody(input), signal, carrierHeaders(request), request.maximum);
+        },
+        async bytes(path, body, signal, request) {
+            if (!(body instanceof Uint8Array))
+                throw new HostedCarrierError("denied");
+            // Named, not spread: a raw request carries no `recreate` or deletion acknowledgment.
+            const own = carrierHeaders({ writeRequest: request.writeRequest, binding: request.binding, via: request.via });
+            const extra = {};
+            for (const [name, value] of Object.entries(request.headers ?? {})) {
+                const lower = name.toLowerCase();
+                if (!ROUTE_HEADER.test(lower) || owned.has(lower) || lower in extra || typeof value !== "string" || !ROUTE_HEADER_VALUE.test(value))
+                    throw new HostedCarrierError("denied");
+                extra[lower] = value;
+            }
+            Object.assign(extra, own);
+            // The body is sent as given; `fetch` derives its exact Content-Length from the bytes.
+            return answer(path, { type: "application/octet-stream", content: body }, signal, extra, request.maximum);
+        },
+        async stream(path, input, signal) {
+            const idle = new AbortController();
+            const firstByte = setTimeout(() => idle.abort(), deadlineMs);
+            let response;
+            try {
+                response = await send(path, jsonBody(input), signal, {}, idle.signal);
+            }
+            finally {
+                clearTimeout(firstByte);
+            }
+            if (!response.ok || !response.body) {
+                const body = await readBounded(response, 64 * 1024).catch(() => undefined);
+                return { status: response.status, headers: response.headers, ok: false, body };
+            }
+            return { status: response.status, headers: response.headers, ok: true, body: idleBounded(response.body, deadlineMs, () => idle.abort()) };
+        },
+    };
+}
+//# sourceMappingURL=carrier.js.map

package/dist/hosted-transport/carrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carrier.js","sourceRoot":"","sources":["../../src/hosted-transport/carrier.ts"],"names":[],"mappings":"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"}

package/dist/hosted-transport/history-pages.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Paging back through one document's hosted history (`documents.history.v1`). The host serves a
+ * lineage newest first, a page at a time: the first page (no `before`) states the lineage's
+ * `total`, and each later page lists the versions older than the last one read. Older versions
+ * never change, so a write that only appends to the lineage while the pages are read leaves the
+ * listing a true picture of the lineage as the first page saw it.
+ *
+ * What does break a listing is a new lineage: the document deleted (and perhaps recreated, its
+ * `seq` restarting at 1) between two pages. A later page that answers `document_not_found` says
+ * so directly; otherwise, after a listing of more than one page, the first page's newest version
+ * is read again by its `seq`, and a listing whose newest version is gone or different starts
+ * again from the first page, after {@link pageRestartDelay}, at most {@link HEADS_PAGE_ATTEMPTS}
+ * times in all. Pages from two lineages are never assembled into one listing.
+ */
+import { type HostedHistoryAnswer, type HostedHistoryRequest, type HostedHistoryVersion, type HostedOperationRefusal } from "./read-adapter.js";
+/** Reads one page of a document's history (a client's bounded history read). */
+export type HistoryPageReader = (request: HostedHistoryRequest) => Promise<HostedHistoryAnswer>;
+export interface HistoryListingRequest {
+    readonly documentId: string;
+    /** The newest this many versions, or fewer when the lineage is shorter. */
+    readonly wanted: number;
+    /** Ask each page for its versions' stored bytes (a page's content shares the host's 1 MiB bound). */
+    readonly includeContent?: boolean;
+    /** Versions per request, 1..{@link HISTORY_PAGE_LIMIT} (default: the limit). */
+    readonly pageSize?: number;
+}
+export type HistoryListing = 
+/** Newest first; `total` is the lineage's length as the first page stated it. */
+{
+    readonly status: "listed";
+    readonly versions: readonly HostedHistoryVersion[];
+    readonly total: number;
+}
+/** The first page answered `document_not_found`: the host has no such document. */
+ | {
+    readonly status: "absent";
+}
+/** The host refused a page for another reason; the caller maps it. */
+ | {
+    readonly status: "refused";
+    readonly refusal: HostedOperationRefusal;
+}
+/** The lineage changed under every attempt. */
+ | {
+    readonly status: "moved";
+};
+export interface HistoryListingOptions {
+    readonly signal: AbortSignal;
+    /** Test seam: how the listing waits before starting again. */
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    readonly attempts?: number;
+}
+/** The newest `wanted` versions of one lineage, paged back with `before`. */
+export declare function readHistoryListing(readPage: HistoryPageReader, request: HistoryListingRequest, options: HistoryListingOptions): Promise<HistoryListing>;
+//# sourceMappingURL=history-pages.d.ts.map

package/dist/hosted-transport/history-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-pages.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/history-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAsB,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEpK,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAEhG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc;AACxB,iFAAiF;AAC/E;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC3G,mFAAmF;GACjF;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE;AAC/B,sEAAsE;GACpE;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE;AAC1E,+CAA+C;GAC7C;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAsCD,6EAA6E;AAC7E,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ7J"}

package/dist/hosted-transport/history-pages.js

@@ -0,0 +1,69 @@
+/**
+ * Paging back through one document's hosted history (`documents.history.v1`). The host serves a
+ * lineage newest first, a page at a time: the first page (no `before`) states the lineage's
+ * `total`, and each later page lists the versions older than the last one read. Older versions
+ * never change, so a write that only appends to the lineage while the pages are read leaves the
+ * listing a true picture of the lineage as the first page saw it.
+ *
+ * What does break a listing is a new lineage: the document deleted (and perhaps recreated, its
+ * `seq` restarting at 1) between two pages. A later page that answers `document_not_found` says
+ * so directly; otherwise, after a listing of more than one page, the first page's newest version
+ * is read again by its `seq`, and a listing whose newest version is gone or different starts
+ * again from the first page, after {@link pageRestartDelay}, at most {@link HEADS_PAGE_ATTEMPTS}
+ * times in all. Pages from two lineages are never assembled into one listing.
+ */
+import { HEADS_PAGE_ATTEMPTS, pageRestartDelay, pause } from "./paged-reads.js";
+import { HISTORY_PAGE_LIMIT } from "./read-adapter.js";
+async function listOnce(readPage, request) {
+    const size = request.pageSize ?? HISTORY_PAGE_LIMIT;
+    if (!Number.isSafeInteger(size) || size < 1 || size > HISTORY_PAGE_LIMIT)
+        throw new RangeError(`history page size must be 1..${HISTORY_PAGE_LIMIT}`);
+    const versions = [];
+    let total = 0;
+    let before;
+    for (;;) {
+        const answer = await readPage({
+            documentId: request.documentId,
+            limit: Math.min(size, request.wanted - versions.length),
+            ...(before === undefined ? {} : { before }),
+            ...(request.includeContent ? { includeContent: true } : {}),
+        });
+        if (!answer.ok) {
+            // Absent on the first page is the answer; absent on a later page, the lineage ended meanwhile.
+            if (answer.refusal.code === "document_not_found")
+                return before === undefined ? { status: "absent" } : "moved";
+            return { status: "refused", refusal: answer.refusal };
+        }
+        const { page } = answer;
+        if (before === undefined)
+            total = page.total;
+        versions.push(...page.versions);
+        if (!page.more || versions.length >= request.wanted)
+            break;
+        before = page.versions.at(-1).seq;
+    }
+    if (before === undefined)
+        return { status: "listed", versions, total };
+    // More than one page: the first page's newest version must still be the lineage's, by its seq.
+    const newest = versions[0];
+    const check = await readPage({ documentId: request.documentId, limit: 1, before: newest.seq + 1 });
+    if (!check.ok)
+        return check.refusal.code === "document_not_found" ? "moved" : { status: "refused", refusal: check.refusal };
+    const again = check.page.versions[0];
+    if (!again || again.seq !== newest.seq || again.version !== newest.version || again.timestamp !== newest.timestamp)
+        return "moved";
+    return { status: "listed", versions, total };
+}
+/** The newest `wanted` versions of one lineage, paged back with `before`. */
+export async function readHistoryListing(readPage, request, options) {
+    const attempts = options.attempts ?? HEADS_PAGE_ATTEMPTS;
+    for (let attempt = 1;; attempt += 1) {
+        const result = await listOnce(readPage, request);
+        if (result !== "moved")
+            return result;
+        if (attempt >= attempts)
+            return { status: "moved" };
+        await (options.sleep ?? pause)(pageRestartDelay(attempt), options.signal);
+    }
+}
+//# sourceMappingURL=history-pages.js.map

package/dist/hosted-transport/history-pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-pages.js","sourceRoot":"","sources":["../../src/hosted-transport/history-pages.ts"],"names":[],"mappings":"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"}

package/dist/hosted-transport/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@superbee/core/hosted-transport`: one client grammar for a hosted Superbee bundle, shared by
+ * the browser working copy and the CLI checkout. The carrier seam keeps the credential
+ * (cookie and CSRF, or bearer) outside; the read adapter, the answer rows and the
+ * whole-document write transport are the same for every client. Hosted Superbee serves the
+ * `/sync/v1` routes it targets; `@superbee/core/hosted-client` is the headless client built on it.
+ */
+export * from "./carrier.js";
+export * from "./answer-rows.js";
+export * from "./read-adapter.js";
+export * from "./paged-reads.js";
+export * from "./whole-document-transport.js";
+export * from "./history-pages.js";
+export * from "./operations.js";
+export * from "./root-write.js";
+export * from "./blob-reads.js";
+export * from "./blob-write.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/hosted-transport/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/hosted-transport/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@superbee/core/hosted-transport`: one client grammar for a hosted Superbee bundle, shared by
+ * the browser working copy and the CLI checkout. The carrier seam keeps the credential
+ * (cookie and CSRF, or bearer) outside; the read adapter, the answer rows and the
+ * whole-document write transport are the same for every client. Hosted Superbee serves the
+ * `/sync/v1` routes it targets; `@superbee/core/hosted-client` is the headless client built on it.
+ */
+export * from "./carrier.js";
+export * from "./answer-rows.js";
+export * from "./read-adapter.js";
+export * from "./paged-reads.js";
+export * from "./whole-document-transport.js";
+export * from "./history-pages.js";
+export * from "./operations.js";
+export * from "./root-write.js";
+export * from "./blob-reads.js";
+export * from "./blob-write.js";
+//# sourceMappingURL=index.js.map

package/dist/hosted-transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hosted-transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/hosted-transport/operations.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Hosted operations by id: the host lists the reads it runs for one bundle
+ * (`POST <sync prefix>/operations {bundleId}`) and runs one of them
+ * (`POST <sync prefix>/run {bundleId, operationId, input}`), answering the kernel's operation
+ * result. A client reaches a read the host adds with no change of its own.
+ *
+ * Everything the host says here is untrusted data. A descriptor's title and description go
+ * through {@link stripHostText}; its JSON Schemas are carried for rendering only, never compiled
+ * and never followed (`$ref`, `$id`); a result is data, never a path, URL or command. A listing
+ * is bounded: at most {@link HOSTED_READ_BOUNDS.operations} descriptors, and a descriptor that is
+ * malformed or out of bounds is dropped with a note while the rest still list.
+ */
+import { type HostedOperationRefusal } from "./read-adapter.js";
+/** True for an id in the operation grammar (`documents.history.v1`), at most 128 characters. */
+export declare function isOperationId(value: unknown): value is string;
+/** A JSON object, as parsed from an answer. */
+export type JsonObject = {
+    readonly [key: string]: unknown;
+};
+/** One operation the host runs by id, as its listing describes it. */
+export interface HostedOperation {
+    readonly operationId: string;
+    /** Host text, stripped of control and format characters, at most {@link HOSTED_READ_BOUNDS.operationTitleChars}. */
+    readonly title: string;
+    /** Host text, stripped of control and format characters, at most {@link HOSTED_READ_BOUNDS.operationDescriptionChars}. */
+    readonly description: string;
+    /** The most bytes the host answers a run of this operation with. */
+    readonly maximumOutputBytes: number;
+    /** For rendering only: never compiled, never followed. */
+    readonly inputJsonSchema: JsonObject;
+    /** For rendering only: never compiled, never followed. */
+    readonly resultJsonSchema: JsonObject;
+    /** The boolean hints the host states (`readOnlyHint`, `destructiveHint`, ...); any other value is left out. */
+    readonly annotations: Readonly<Record<string, boolean>>;
+}
+/** A decoded listing: the operations admitted, in the host's order, and a note for each one dropped. */
+export interface HostedOperationListing {
+    readonly operations: readonly HostedOperation[];
+    readonly notes: readonly string[];
+}
+/**
+ * The listing route's `200` answer (`{ operations: [descriptor, ...] }`). A body that is not an
+ * object with an `operations` array is malformed, naming `route`; fields the answer may gain are
+ * ignored. Each descriptor is admitted on its own: one that is malformed, whose id is outside the
+ * operation grammar or repeats an earlier one, whose `maximumOutputBytes` is not positive, or
+ * whose schema nests deeper than {@link HOSTED_READ_BOUNDS.operationSchemaDepth} is dropped with a note. At most
+ * {@link HOSTED_READ_BOUNDS.operations} are read.
+ */
+export declare function decodeOperationListing(body: unknown, route?: string): HostedOperationListing;
+/** True when an operation input names a bundle other than `bundleId` (an input without one names none). */
+export declare function namesOtherBundle(input: JsonObject, bundleId: string): boolean;
+/**
+ * The body a run sends: the bundle the request selects its tenant by, the operation, and the
+ * operation's input with its `bundleId` set to that same bare bundle id (the host refuses an
+ * input naming another bundle). An input that already names another bundle is refused here.
+ */
+export declare function operationRunBody(bundleId: string, operationId: string, input: JsonObject): {
+    bundleId: string;
+    operationId: string;
+    input: Record<string, unknown>;
+};
+/** A listing, or the refusal of the bundle it was asked for. */
+export type HostedOperationListingAnswer = {
+    readonly ok: true;
+    readonly listing: HostedOperationListing;
+} | {
+    readonly ok: false;
+    readonly refusal: HostedOperationRefusal;
+};
+/** A run's `200` answer: the operation's data, or its refusal (the kernel's code, message and retry advice). */
+export type HostedOperationRun = {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly refusal: HostedOperationRefusal;
+};
+/**
+ * A run's `200` answer, the kernel's operation result: `{ ok: true, operationId, data }` for the
+ * operation asked for, or its refusal through {@link operationRefusal}. Anything else, including
+ * a result for another operation, or data nested deeper than `HOSTED_READ_BOUNDS.runDepth`
+ * levels (which no renderer could walk), is malformed, naming `route`. The data is not interpreted.
+ */
+export declare function decodeOperationRun(operationId: string, body: unknown, route?: string): HostedOperationRun;
+//# sourceMappingURL=operations.d.ts.map

package/dist/hosted-transport/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAwC,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAOtG,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE7D;AAED,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE7D,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oHAAoH;IACpH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0HAA0H;IAC1H,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC;IACrC,0DAA0D;IAC1D,QAAQ,CAAC,gBAAgB,EAAE,UAAU,CAAC;IACtC,+GAA+G;IAC/G,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED,wGAAwG;AACxG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAmCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAmB5F;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAKpK;AAED,gEAAgE;AAChE,MAAM,MAAM,4BAA4B,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAE9K,gHAAgH;AAChH,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAElJ;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAOzG"}