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

package/dist/client.js

@@ -0,0 +1,500 @@
+/**
+ * The typed client over D3's routes (ADR-162 D4 items 1, 3 and 4): who is
+ * signed in, invoking a capability as them, opening a feed, uploading a file
+ * with progress, and signing out.
+ *
+ * Every type here for what the contract declares — a route's answer, the
+ * error envelope, the upload's answer — is the one generated into
+ * `./generated/` from the committed schemas; none is written by hand. A
+ * Work Order verb's params and result are generated there too
+ * (`WorkOrderGetParams`, `WorkOrderGetResult`, …), and a caller names them as
+ * {@link TeraClient.invoke}'s type arguments.
+ *
+ * # Two kinds of failure, kept apart
+ *
+ * - **The kit's refusal** — no verified caller, a cross-origin write, an
+ *   unknown or unserved route — and anything else that is not the route's
+ *   answer, is thrown as a {@link KitRequestError}, carrying the kit's
+ *   envelope (`code`, `message`, `retryable`) as it arrived.
+ * - **A verb's refusal** is not a failure of the route. The verb ran and said
+ *   no; the kit passes its verdict through with HTTP 200 (D3), and
+ *   {@link TeraClient.invoke} answers it as that verdict, `{ status: "error",
+ *   error }`, beside `{ status: "success", result }`.
+ *
+ * # Same origin
+ *
+ * Every request is to a path under the kit's prefix, below the app's base
+ * ({@link TeraClientOptions.base}), on the page's own origin,
+ * with `credentials: "same-origin"`; a fetch is also `mode: "same-origin"`, so
+ * a page that somehow aimed one elsewhere is refused by the browser rather
+ * than sent. The browser then marks it `Sec-Fetch-Site: same-origin`, which is
+ * what the kit's same-origin rule for writes admits (D3). No header here
+ * claims it: a page cannot set `Sec-Fetch-*` or `Origin`, and the rule rests
+ * on that.
+ *
+ * # A step-up
+ *
+ * Every request it makes handles a `step_up_required` refusal that names a
+ * page to confirm the act on (ADR-173 D11): the kit's envelope from a kit
+ * route or from the plugin's own route ({@link TeraClient.fetch}), and a Work
+ * Order verb's refusal relayed by {@link TeraClient.invoke}. It has the person
+ * confirm it ({@link TeraClient.confirmStepUp}) and sends the identical request
+ * once more, with `Tera-Step-Up: <id>`, or with `step_up` in an invoke's
+ * params. A step-up the person declines, lets expire or walks away from
+ * rejects with a {@link StepUpError}, and the request is not sent again.
+ *
+ * # Signing in again
+ *
+ * A request tera's UI proxy answers `sign_in_required` — the person's session
+ * on the plugin's origin is gone: signed out, lapsed, or ended with the tera
+ * session it was opened from — loads the
+ * page again ({@link TeraClient.reSignIn}), which signs the person in, and
+ * still rejects (or, from {@link TeraClient.fetch}, answers) as it arrived.
+ * The page is loaded again once per client, however many requests were
+ * refused together. A feed or stream the client opens does the same.
+ *
+ * It is a plain class with an injected fetch, request factory, navigation,
+ * window opener and timer, so its tests drive it against a fake and no
+ * network.
+ */
+import { appBase, isBaseRelative, routePath, underBase } from "./routes.js";
+import { FeedConnection } from "./feed/connection.js";
+import { fetchOpener } from "./feed/sse.js";
+import { StreamConnection } from "./stream/connection.js";
+import { TerminalView } from "./terminal/view.js";
+import { SIGN_IN_REQUIRED, isSignInRequired } from "./signin.js";
+import { STEP_UP_HEADER, STEP_UP_POLL_MS, StepUpError, defaultOpenWindow, defaultSleep, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
+/**
+ * The `code` of a {@link KitRequestError} whose answer was not the kit's
+ * envelope — a proxy's page, a dropped body, a success that is not the
+ * route's JSON. It is this package's, never one the kit sends.
+ */
+export const UNRECOGNIZED_RESPONSE = "unrecognized_response";
+/**
+ * A kit route that did not answer as the route: the kit's own refusal, or
+ * something that was not the route's answer at all.
+ */
+export class KitRequestError extends Error {
+    /** The HTTP status the route answered with. */
+    status;
+    /**
+     * The envelope's code, as it arrived — one of the kit's `KitErrorCode`s, or
+     * a code this package does not know, kept as it is — or
+     * {@link UNRECOGNIZED_RESPONSE} when there was no envelope.
+     */
+    code;
+    /** Whether the identical request may succeed if sent again later. Branch on this, never on a list of codes. */
+    retryable;
+    /** How long to wait before retrying, when the envelope said. */
+    retryAfterMs;
+    /** The envelope's structured detail, when it carried any. */
+    data;
+    /** The envelope as it arrived, or null when the answer carried none. */
+    envelope;
+    constructor(status, envelope, fallback) {
+        super(envelope?.message ?? fallback);
+        this.name = "KitRequestError";
+        this.status = status;
+        this.envelope = envelope;
+        this.code = envelope?.code ?? UNRECOGNIZED_RESPONSE;
+        // Without an envelope only the status speaks: a 5xx, a 408 or a 429 says "later".
+        this.retryable = envelope?.retryable ?? (status >= 500 || status === 408 || status === 429);
+        this.retryAfterMs = envelope?.retry_after_ms;
+        this.data = envelope?.data;
+    }
+}
+const JSON_TYPE = "application/json";
+export class TeraClient {
+    base;
+    fetchFn;
+    uploadRequest;
+    navigate;
+    openWindow;
+    pageURL;
+    sleep;
+    pollMs;
+    /** Whether the step-up the page was loaded back with has been taken up. */
+    resumeTaken = false;
+    /** Whether this client has loaded the page again to sign in. */
+    signingIn = false;
+    constructor(options = {}) {
+        this.base = appBase(options.base);
+        this.fetchFn = options.fetch ?? ((...args) => globalThis.fetch(...args));
+        this.uploadRequest = options.uploadRequest ?? (() => new XMLHttpRequest());
+        this.navigate = options.navigate ?? ((path) => globalThis.location.assign(path));
+        const stepUp = options.stepUp ?? {};
+        this.openWindow = stepUp.openWindow ?? defaultOpenWindow;
+        this.pageURL = stepUp.pageURL ?? (() => globalThis.location.href);
+        this.sleep = stepUp.sleep ?? defaultSleep;
+        this.pollMs = stepUp.pollIntervalMs ?? STEP_UP_POLL_MS;
+    }
+    /** `GET /tera/v1/me`: who is signed in, and where to send them to sign out. */
+    async me() {
+        return this.json(this.route("me"), { method: "GET" });
+    }
+    /**
+     * `POST /tera/v1/invoke/{capability}`: invokes one capability as the
+     * signed-in person, with `params` as its params, and answers the verb's
+     * verdict. A refusal by the verb answers `{ status: "error" }`; only the
+     * kit's own refusal, or an answer that is not the route's, throws.
+     *
+     *     const got = await client.invoke<WorkOrderGetResult, WorkOrderGetParams>("work_order.get", { id });
+     *     if (got.status === "success") show(got.result);
+     */
+    async invoke(capability, params) {
+        const verdict = await this.invokeOnce(capability, params);
+        if (verdict.status !== "error")
+            return verdict;
+        const challenge = stepUpChallengeOf(verdict.error.code, verdict.error.data?.step_up);
+        if (challenge === null || !isParamsObject(params))
+            return verdict;
+        const id = await this.confirmStepUp(challenge);
+        return this.invokeOnce(capability, { ...(params ?? {}), step_up: id });
+    }
+    async invokeOnce(capability, params) {
+        const url = this.route("invoke", capability);
+        const reply = await this.json(url, {
+            method: "POST",
+            headers: { "Content-Type": JSON_TYPE },
+            body: JSON.stringify(params ?? {}),
+        });
+        if (reply.status === "success" && reply.result !== undefined) {
+            return { status: "success", result: reply.result.structured };
+        }
+        if (reply.status === "error" && reply.error !== undefined) {
+            return { status: "error", error: reply.error };
+        }
+        throw new KitRequestError(200, null, `${url} answered a reply envelope with no ${reply.status === "error" ? "error" : "result"}`);
+    }
+    /**
+     * A {@link FeedConnection} over `GET /tera/v1/feeds/{feed}`, read with this
+     * client's fetch. It is not started: call `start()` on it, and `stop()` when
+     * the page no longer wants it.
+     */
+    feed(options) {
+        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn), reSignIn: () => this.reSignIn() });
+    }
+    /**
+     * A {@link StreamConnection} to one of the kit's stream routes, its failed
+     * handshakes probed with this client's fetch. It opens at once: call
+     * `close()` on it when the page no longer wants it.
+     */
+    stream(options) {
+        return new StreamConnection({ ...options, base: this.base, fetch: this.fetchFn, reSignIn: () => this.reSignIn() });
+    }
+    /**
+     * A {@link TerminalView} of an attended session's terminal at the kit's
+     * terminal route, its failed handshakes probed with this client's fetch. It
+     * opens at once: call `detach()` on it when the pane closes.
+     */
+    terminal(options) {
+        return new TerminalView({ ...options, base: this.base, fetch: this.fetchFn, reSignIn: () => this.reSignIn() });
+    }
+    /**
+     * `POST /tera/v1/uploads`: sends one file as the signed-in person and
+     * answers the staged artifact, whose `handle` a Work Order's attachments
+     * name. Its name and description travel percent-encoded (UTF-8) in the
+     * route's headers, and `onProgress` reports the body as it is sent.
+     */
+    async upload(file, options = {}) {
+        try {
+            return await this.signInOnRefusal(this.uploadOnce(file, options, null));
+        }
+        catch (err) {
+            const challenge = err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
+            if (challenge === null)
+                throw err;
+            return this.signInOnRefusal(this.uploadOnce(file, options, await this.confirmStepUp(challenge)));
+        }
+    }
+    uploadOnce(file, options, stepUpId) {
+        const filename = options.filename ?? file.name ?? "";
+        if (filename === "") {
+            return Promise.reject(new TypeError("upload: a filename is required: pass a File, or options.filename"));
+        }
+        const contentType = options.contentType || file.type || "application/octet-stream";
+        const url = this.route("uploads");
+        const { signal, onProgress } = options;
+        if (signal?.aborted)
+            return Promise.reject(abortError());
+        return new Promise((resolve, reject) => {
+            const xhr = this.uploadRequest();
+            const onAbort = () => xhr.abort();
+            const settle = () => signal?.removeEventListener("abort", onAbort);
+            xhr.open("POST", url);
+            // Same origin sends the page's cookies; it never needs withCredentials.
+            xhr.withCredentials = false;
+            xhr.setRequestHeader("Content-Type", contentType);
+            xhr.setRequestHeader("Tera-Upload-Filename", encodeURIComponent(filename));
+            if (options.description !== undefined && options.description !== "") {
+                xhr.setRequestHeader("Tera-Upload-Description", encodeURIComponent(options.description));
+            }
+            xhr.setRequestHeader("Accept", JSON_TYPE);
+            if (stepUpId !== null)
+                xhr.setRequestHeader(STEP_UP_HEADER, stepUpId);
+            if (onProgress !== undefined) {
+                xhr.upload.onprogress = (ev) => onProgress({ loaded: ev.loaded, total: ev.lengthComputable ? ev.total : file.size });
+            }
+            xhr.onload = () => {
+                settle();
+                try {
+                    resolve(answer(url, xhr.status, xhr.getResponseHeader("content-type") ?? "", xhr.responseText));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            };
+            xhr.onerror = () => {
+                settle();
+                reject(new TypeError(`${url}: the upload failed with no answer`));
+            };
+            xhr.onabort = () => {
+                settle();
+                reject(abortError());
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                xhr.send(file);
+            }
+            catch (err) {
+                settle();
+                reject(err);
+            }
+        });
+    }
+    /**
+     * `GET /tera/v1/step-ups/{id}`: where one of the person's own step-ups is in
+     * its life. A step-up that is not theirs is thrown as tera's 404, as an id
+     * no step-up carries is.
+     */
+    async stepUp(id) {
+        return this.json(this.route("step-ups", id), { method: "GET" }, false);
+    }
+    /**
+     * A request to one of the plugin's own routes, `path` relative to the app's
+     * base (`reviews/7/finish`), same-origin. A `step_up_required` answer in the
+     * kit's envelope — what `webui.RequireStepUp` writes — is confirmed by the
+     * person and the request sent once more with `Tera-Step-Up`; any other
+     * answer, a success or a refusal, is returned as it arrived. A body sent
+     * again must be one that can be: a string, a `Blob`, `FormData` or a
+     * buffer, never a stream. A `sign_in_required` answer loads the page again
+     * ({@link TeraClient.reSignIn}) and is returned as it arrived.
+     */
+    async fetch(path, init = {}) {
+        const url = underBase(this.base, path);
+        const first = await this.fetchSameOrigin(url, init, null);
+        if (await isSignInRequired(first)) {
+            this.reSignIn();
+            return first;
+        }
+        const challenge = await stepUpRefusalOf(first);
+        if (challenge === null)
+            return first;
+        const second = await this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+        if (await isSignInRequired(second))
+            this.reSignIn();
+        return second;
+    }
+    /**
+     * Loads the page again to sign the person in to the plugin's origin: a
+     * top-level navigation to the page's own URL, which tera's UI proxy answers
+     * with its silent sign-in. The client does it itself on a
+     * `sign_in_required` answer; a page calls it for one it read on its own.
+     * It navigates once per client: a second call does nothing.
+     */
+    reSignIn() {
+        if (this.signingIn)
+            return;
+        this.signingIn = true;
+        this.navigate(this.pageURL());
+    }
+    /** Loads the page again when `request` rejects as `sign_in_required`, and rejects as it did. */
+    async signInOnRefusal(request) {
+        try {
+            return await request;
+        }
+        catch (err) {
+            if (err instanceof KitRequestError && err.status === 401 && err.code === SIGN_IN_REQUIRED)
+                this.reSignIn();
+            throw err;
+        }
+    }
+    /**
+     * Has the person confirm the step-up `challenge` names, and answers its id
+     * once it is satisfied, to send the act again with. It opens the step-up's
+     * page in a new window, or navigates to it with a `return_to` naming this
+     * page when the browser opens none, and reads its state every poll interval
+     * until it is satisfied, declined or expired, closing the window it opened.
+     *
+     * Rejects with a {@link StepUpError} when the step-up ends unconfirmed, the
+     * person closes its window while it still waits, or the page navigated away
+     * to confirm it. A page loaded back from that navigation carries the id, and
+     * the first step-up it is asked for resumes that one when it is satisfied.
+     */
+    async confirmStepUp(challenge) {
+        const resumed = this.takeResumed();
+        if (resumed !== null) {
+            const state = await this.stepUp(resumed).then((s) => s.state, () => null);
+            if (state === "satisfied")
+                return resumed;
+        }
+        const win = this.openWindow(challenge.url);
+        if (win === null) {
+            this.navigate(stepUpPageURL(challenge.url, challenge.id, this.pageURL()));
+            throw new StepUpError(challenge.id, "navigated", "the browser opened no window, so the page went to tera's to confirm the act");
+        }
+        let closedSeen = false;
+        for (;;) {
+            await this.sleep(this.pollMs);
+            let state;
+            try {
+                state = (await this.stepUp(challenge.id)).state;
+            }
+            catch (err) {
+                win.close();
+                throw err;
+            }
+            if (state === "satisfied") {
+                win.close();
+                return challenge.id;
+            }
+            if (state !== "pending") {
+                win.close();
+                throw new StepUpError(challenge.id, state, `the step-up was ${state === "spent" ? "spent by another request" : state}, and the act was not sent again`);
+            }
+            // One more read after the person closes the window, in case they
+            // confirmed it just before; then it is abandoned.
+            if (win.closed) {
+                if (closedSeen) {
+                    throw new StepUpError(challenge.id, "abandoned", "the step-up's window was closed before it was confirmed");
+                }
+                closedSeen = true;
+            }
+        }
+    }
+    /** The step-up this page was loaded back with, once. */
+    takeResumed() {
+        if (this.resumeTaken)
+            return null;
+        this.resumeTaken = true;
+        try {
+            return resumedStepUp(this.pageURL());
+        }
+        catch {
+            return null;
+        }
+    }
+    fetchSameOrigin(url, init, stepUpId) {
+        const headers = new Headers(init.headers);
+        if (stepUpId !== null)
+            headers.set(STEP_UP_HEADER, stepUpId);
+        return this.fetchFn(url, { ...init, headers, credentials: "same-origin", mode: "same-origin" });
+    }
+    /**
+     * Signs the person out: navigates to the `signout_path` `me()` answers,
+     * tera's own sign-out, resolved against the app's base. A `signout_path`
+     * that is not a path relative to the base — a root-absolute path, or one
+     * naming another origin — is refused rather than followed.
+     */
+    async signOut() {
+        const { signout_path: path } = await this.me();
+        if (!isBaseRelative(path)) {
+            throw new KitRequestError(200, null, `${this.route("me")} answered a signout_path that is not a path relative to the app's base: ${JSON.stringify(path)}`);
+        }
+        this.navigate(underBase(this.base, path));
+    }
+    /** A kit route's path under the app's base. */
+    route(...segments) {
+        return underBase(this.base, routePath(...segments));
+    }
+    async json(url, init, stepUp = true) {
+        try {
+            return await this.signInOnRefusal(this.jsonOnce(url, init, null));
+        }
+        catch (err) {
+            const challenge = stepUp && err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
+            if (challenge === null)
+                throw err;
+            return this.signInOnRefusal(this.jsonOnce(url, init, await this.confirmStepUp(challenge)));
+        }
+    }
+    async jsonOnce(url, init, stepUpId) {
+        const response = await this.fetchFn(url, {
+            ...init,
+            headers: {
+                Accept: JSON_TYPE,
+                ...init.headers,
+                ...(stepUpId === null ? {} : { [STEP_UP_HEADER]: stepUpId }),
+            },
+            credentials: "same-origin",
+            mode: "same-origin",
+            cache: "no-store",
+        });
+        let text = "";
+        try {
+            text = await response.text();
+        }
+        catch {
+            // An unread body is read as no envelope: the status decides.
+        }
+        return answer(url, response.status, response.headers.get("content-type") ?? "", text);
+    }
+}
+/**
+ * Reads a route's answer: on a 2xx, the JSON body the route declares; on
+ * anything else, the kit's envelope as a thrown {@link KitRequestError}.
+ */
+function answer(url, status, contentType, text) {
+    const isJSON = contentType.toLowerCase().split(";")[0].trim() === JSON_TYPE;
+    let body;
+    if (isJSON) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+    }
+    if (status >= 200 && status < 300) {
+        if (typeof body === "object" && body !== null)
+            return body;
+        throw new KitRequestError(status, null, `${url} answered HTTP ${status} with a body that is not its JSON (${contentType || "no content type"})`);
+    }
+    throw new KitRequestError(status, envelopeOf(body), `${url} answered HTTP ${status} (${contentType || "no content type"})`);
+}
+/** Whether `params` can carry `step_up` beside what it holds: absent, or a plain object. */
+function isParamsObject(params) {
+    return params === undefined || params === null || (typeof params === "object" && !Array.isArray(params));
+}
+/** The step-up a response to the plugin's own route needs confirmed, read from a copy of it. */
+async function stepUpRefusalOf(response) {
+    if (response.status !== 403)
+        return null;
+    const type = (response.headers.get("content-type") ?? "").toLowerCase().split(";")[0].trim();
+    if (type !== JSON_TYPE)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(await response.clone().text());
+    }
+    catch {
+        return null;
+    }
+    const e = envelopeOf(body);
+    return e === null ? null : stepUpChallengeOf(e.code, e.step_up);
+}
+/** The envelope's `error` member, when `body` is a kit envelope; null otherwise. */
+function envelopeOf(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const error = body.error;
+    if (typeof error !== "object" || error === null)
+        return null;
+    const e = error;
+    if (typeof e.code !== "string" || typeof e.message !== "string" || typeof e.retryable !== "boolean")
+        return null;
+    return e;
+}
+function abortError() {
+    return new DOMException("the upload was aborted", "AbortError");
+}

package/dist/feed/connection.d.ts

@@ -0,0 +1,179 @@
+import type { FeedFrameRecord, FeedFrameStatus } from "../generated/feed.ts";
+import { type FeedOpenError, type FeedOpener } from "./sse.ts";
+export declare const BASE_DELAY_MS = 1000;
+export declare const MAX_DELAY_MS = 30000;
+/** Replays allowed in {@link REPLAY_WINDOW_MS} before a loss is surfaced. */
+export declare const REPLAY_LIMIT = 3;
+export declare const REPLAY_WINDOW_MS: number;
+/** Added to twice the feed's heartbeat interval before a silent stream is given up on. */
+export declare const HEARTBEAT_GRACE_MS = 5000;
+/** The SSE event the kit closes a stream with when the person's token expires (D2 item 6). */
+export declare const REAUTHENTICATE_EVENT = "reauthenticate";
+/**
+ * One feed frame as the stream carried it, before its `type` is read. A frame
+ * of a known type is handed on as the type generated for it from
+ * `sdk/feed/schema/` ({@link FeedFrameRecord}, {@link FeedFrameStatus}); one
+ * of a type this package does not know is skipped (ADR-143 D13). The
+ * connection reads a frame's `type`, a status frame's `status` and drop
+ * counts, and a record's order key — and nothing else: the payload's contract
+ * is its publishing family's.
+ */
+export type FeedFrame = {
+    readonly type: string;
+    readonly [field: string]: unknown;
+};
+/**
+ * Where the connection is.
+ *
+ *   reconnecting  a stream is being opened, or will be in `delayMs`; attempt 0
+ *                 is the first open and an immediate reopen
+ *   replaying     open, and the run's stored history is still arriving
+ *   live          open, history read: records now are live
+ *   refused       the route refused; a person has to act
+ *   stopped       nothing is wanted any more
+ */
+export type FeedConnectionPhase = "reconnecting" | "replaying" | "live" | "refused" | "stopped";
+/** A loss no replay is repairing, surfaced to the page. */
+export interface FeedLoss {
+    /** The status value that reported it (`records_dropped`, `backfill_gap`, …). */
+    readonly status: string;
+    /**
+     * `replays-exhausted`: {@link REPLAY_LIMIT} replays in {@link REPLAY_WINDOW_MS}
+     * did not stop it. `unrepairable`: a replay cannot bring the records back.
+     */
+    readonly reason: "replays-exhausted" | "unrepairable";
+}
+export interface FeedConnectionState {
+    readonly phase: FeedConnectionPhase;
+    /** Consecutive failed attempts; 0 once a connection has gone live. */
+    readonly attempt: number;
+    /** How long until the scheduled reconnect, while `reconnecting`; 0 when it is under way. */
+    readonly delayMs: number;
+    /** Why the last stream ended, in the words it ended with. */
+    readonly lastError: string | null;
+    /** The refusal, while `refused`. */
+    readonly refusal: FeedOpenError | null;
+    /** A loss no replay is repairing, or null. */
+    readonly loss: FeedLoss | null;
+}
+export interface Clock {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    /** A number in [0, 1), for the jitter. */
+    random(): number;
+}
+/** Something outside the stream saying now is a good time to reconnect. */
+export type FeedSignal = "visible" | "online";
+/** Subscribes to {@link FeedSignal}s; returns the unsubscribe. */
+export type FeedSignals = (notify: (signal: FeedSignal) => void) => () => void;
+/** The browser's signals: the document becoming visible, and the window coming online. */
+export declare const browserSignals: FeedSignals;
+/**
+ * defaultOrderKey reads the order ADR-083 D7's contract names: the id of a
+ * Work Order event (ADR-078 D3), monotonic across every Work Order and the
+ * cursor `work_order.events` replays from, carried as the record payload's
+ * `id`. A record without one has no key.
+ */
+export declare function defaultOrderKey(record: FeedFrameRecord): number | undefined;
+/** A {@link FeedConnectionOptions.backfill}: the run's stored history first, or the live stream alone. */
+export type FeedBackfill = "all" | "none";
+export interface FeedConnectionOptions {
+    /** The feed's name, as the plugin's manifest declares it. */
+    feed: string;
+    /** The path the app is served under on its origin, as a client's `base` option names it; `/` when absent. */
+    base?: string;
+    /** Narrows the feed to these of its topic filters (the feed's `topics` parameter). */
+    topics?: readonly string[];
+    /**
+     * Where each stream starts: `all` (the default) precedes the live records
+     * with the run's stored history, sent as the feed's `backfill=all`; `none`
+     * asks for no history and sends no `backfill`. The daemon serves `all` only
+     * to a connection whose topics name one run and refuses any other
+     * `backfill_scope_too_broad`, so a work-order-events feed, or a feed not
+     * narrowed to one Work Order, is opened with `none`.
+     */
+    backfill?: FeedBackfill;
+    /** Each record not already delivered, in order. */
+    onRecord: (record: FeedFrameRecord) => void;
+    /** Every status frame, as it arrives. Heartbeats are absorbed and never reach it (ADR-083 D7). */
+    onStatus?: (status: FeedFrameStatus) => void;
+    /** Every change of {@link FeedConnectionState}. */
+    onChange?: (state: FeedConnectionState) => void;
+    /**
+     * A record's place in the feed's order, for de-duplication across replays;
+     * {@link defaultOrderKey} when absent. A record with no key cannot be told
+     * apart from one already delivered, so it is delivered every time it
+     * arrives: a feed whose records carry no Work Order event id passes the key
+     * its own records are ordered by.
+     */
+    orderKey?: (record: FeedFrameRecord) => number | undefined;
+    /** Opens one stream; {@link fetchOpener} when absent. */
+    open?: FeedOpener;
+    /**
+     * Loads the page again when tera's UI proxy refuses the stream
+     * `sign_in_required`, which signs the person in; {@link reSignIn} when
+     * absent. A {@link TeraClient}'s feed passes the client's own.
+     */
+    reSignIn?: () => void;
+    clock?: Clock;
+    /** {@link browserSignals} when absent. */
+    signals?: FeedSignals;
+}
+export declare class FeedConnection {
+    private readonly options;
+    private readonly clock;
+    private readonly open;
+    private readonly orderKey;
+    private view;
+    private unsubscribe;
+    private generation;
+    private controller;
+    private retryTimer;
+    private silenceTimer;
+    private high;
+    private replays;
+    private opened;
+    private replaying;
+    private silenceMs;
+    private droppedSeen;
+    private lossPending;
+    private streamLoss;
+    constructor(options: FeedConnectionOptions);
+    /** Whether each stream asks for the run's stored history. */
+    private get backfills();
+    get state(): FeedConnectionState;
+    /** The stream's URL: the feed route, narrowed to the topics, asking for the backfill unless it is `none`. */
+    get url(): string;
+    /** Opens the first stream. Nothing delivered before is remembered. */
+    start(): void;
+    /** Ends everything; nothing this connection opened may deliver again. */
+    stop(): void;
+    /** A person asked: reopens from any ending, resetting the backoff and the replay ration. */
+    retry(): void;
+    private nudge;
+    private set;
+    private teardown;
+    private connect;
+    private event;
+    /**
+     * The person's token expired under an open stream (D7), told by a
+     * `reauthenticate` event or a `credential_expired` status: reconnecting
+     * carries a fresh assertion, so it is at once. A stream that never opened is
+     * not one the token ended, so it backs off rather than looping at once.
+     */
+    private expired;
+    private frame;
+    private status;
+    private deliver;
+    private droppedRose;
+    private unrepairable;
+    private lost;
+    private goLive;
+    /** One replay for a loss, within the ration; past it, the loss is surfaced. */
+    private replay;
+    /** Ends the current stream as a failure and schedules the next with backoff. */
+    private reopen;
+    private schedule;
+    private armSilence;
+}