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

package/dist/generated/workorder.js

@@ -0,0 +1,74 @@
+// Code generated by cmd/internal/genwebtypes from sdk/workorder/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 WORK_ORDER_SCHEMAS = {
+    WorkOrderAcknowledgeParams: "sdk/workorder/schema/v1/acknowledge.params.json",
+    WorkOrderAcknowledgeResult: "sdk/workorder/schema/v1/acknowledge.result.json",
+    WorkOrderAnswerParams: "sdk/workorder/schema/v1/answer.params.json",
+    WorkOrderAnswerResult: "sdk/workorder/schema/v1/answer.result.json",
+    WorkOrderCancelParams: "sdk/workorder/schema/v1/cancel.params.json",
+    WorkOrderCancelResult: "sdk/workorder/schema/v1/cancel.result.json",
+    WorkOrderCohortSetParams: "sdk/workorder/schema/v1/cohort_set.params.json",
+    WorkOrderCohortSetResult: "sdk/workorder/schema/v1/cohort_set.result.json",
+    WorkOrderCompleteParams: "sdk/workorder/schema/v1/complete.params.json",
+    WorkOrderCompleteResult: "sdk/workorder/schema/v1/complete.result.json",
+    WorkOrderCreateParams: "sdk/workorder/schema/v1/create.params.json",
+    WorkOrderCreateResult: "sdk/workorder/schema/v1/create.result.json",
+    WorkOrderCreateChildParams: "sdk/workorder/schema/v1/create_child.params.json",
+    WorkOrderCreateChildResult: "sdk/workorder/schema/v1/create_child.result.json",
+    WorkOrderEditParams: "sdk/workorder/schema/v1/edit.params.json",
+    WorkOrderEditResult: "sdk/workorder/schema/v1/edit.result.json",
+    WorkOrderEventsParams: "sdk/workorder/schema/v1/events.params.json",
+    WorkOrderEventsResult: "sdk/workorder/schema/v1/events.result.json",
+    WorkOrderFailParams: "sdk/workorder/schema/v1/fail.params.json",
+    WorkOrderFailResult: "sdk/workorder/schema/v1/fail.result.json",
+    WorkOrderForceFailParams: "sdk/workorder/schema/v1/force_fail.params.json",
+    WorkOrderForceFailResult: "sdk/workorder/schema/v1/force_fail.result.json",
+    WorkOrderGetParams: "sdk/workorder/schema/v1/get.params.json",
+    WorkOrderGetResult: "sdk/workorder/schema/v1/get.result.json",
+    WorkOrderGuideParams: "sdk/workorder/schema/v1/guide.params.json",
+    WorkOrderGuideResult: "sdk/workorder/schema/v1/guide.result.json",
+    WorkOrderHistoryParams: "sdk/workorder/schema/v1/history.params.json",
+    WorkOrderHistoryResult: "sdk/workorder/schema/v1/history.result.json",
+    WorkOrderHistoryUnblockParams: "sdk/workorder/schema/v1/history_unblock.params.json",
+    WorkOrderHistoryUnblockResult: "sdk/workorder/schema/v1/history_unblock.result.json",
+    WorkOrderHumanAskParams: "sdk/workorder/schema/v1/human.ask.params.json",
+    WorkOrderHumanAskResult: "sdk/workorder/schema/v1/human.ask.result.json",
+    WorkOrderInterruptParams: "sdk/workorder/schema/v1/interrupt.params.json",
+    WorkOrderInterruptResult: "sdk/workorder/schema/v1/interrupt.result.json",
+    WorkOrderListParams: "sdk/workorder/schema/v1/list.params.json",
+    WorkOrderListResult: "sdk/workorder/schema/v1/list.result.json",
+    WorkOrderListOffTeraParams: "sdk/workorder/schema/v1/list_off_tera.params.json",
+    WorkOrderListOffTeraResult: "sdk/workorder/schema/v1/list_off_tera.result.json",
+    WorkOrderPauseParams: "sdk/workorder/schema/v1/pause.params.json",
+    WorkOrderPauseResult: "sdk/workorder/schema/v1/pause.result.json",
+    WorkOrderPrioritizeParams: "sdk/workorder/schema/v1/prioritize.params.json",
+    WorkOrderPrioritizeResult: "sdk/workorder/schema/v1/prioritize.result.json",
+    WorkOrderProgressParams: "sdk/workorder/schema/v1/progress.params.json",
+    WorkOrderProgressResult: "sdk/workorder/schema/v1/progress.result.json",
+    WorkOrderRecallParams: "sdk/workorder/schema/v1/recall.params.json",
+    WorkOrderRecallResult: "sdk/workorder/schema/v1/recall.result.json",
+    WorkOrderRefileParams: "sdk/workorder/schema/v1/refile.params.json",
+    WorkOrderRefileResult: "sdk/workorder/schema/v1/refile.result.json",
+    WorkOrderRelateParams: "sdk/workorder/schema/v1/relate.params.json",
+    WorkOrderRelateResult: "sdk/workorder/schema/v1/relate.result.json",
+    WorkOrderReleaseParams: "sdk/workorder/schema/v1/release.params.json",
+    WorkOrderReleaseResult: "sdk/workorder/schema/v1/release.result.json",
+    WorkOrderRepinParams: "sdk/workorder/schema/v1/repin.params.json",
+    WorkOrderRepinResult: "sdk/workorder/schema/v1/repin.result.json",
+    WorkOrderRepostParams: "sdk/workorder/schema/v1/repost.params.json",
+    WorkOrderRepostResult: "sdk/workorder/schema/v1/repost.result.json",
+    WorkOrderRetryParams: "sdk/workorder/schema/v1/retry.params.json",
+    WorkOrderRetryResult: "sdk/workorder/schema/v1/retry.result.json",
+    WorkOrderSubmitResultParams: "sdk/workorder/schema/v1/submit_result.params.json",
+    WorkOrderSubmitResultResult: "sdk/workorder/schema/v1/submit_result.result.json",
+    WorkOrderTakeParams: "sdk/workorder/schema/v1/take.params.json",
+    WorkOrderTakeResult: "sdk/workorder/schema/v1/take.result.json",
+    WorkOrderTransitionParams: "sdk/workorder/schema/v1/transition.params.json",
+    WorkOrderTransitionResult: "sdk/workorder/schema/v1/transition.result.json",
+    WorkOrderTreeParams: "sdk/workorder/schema/v1/tree.params.json",
+    WorkOrderTreeResult: "sdk/workorder/schema/v1/tree.result.json",
+};

package/dist/generated/wsstream.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The close vocabulary of a tera stream (sdk/wsstream.CloseCodes).
+ *
+ * The WebSocket close codes a tera stream is closed with. Each states only what the hop that closed decided, and a relay passes a close on as it arrived. The reason beside a code is a code of at most 64 bytes of [a-z0-9_.:-], or "closed". A code is never renamed or given a new meaning; a client that meets a code it does not know treats it as retry_later (4001).
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export type StreamCloseCode = 1000 | 1001 | 1009 | 4000 | 4001 | 4003;
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export declare const STREAM_CLOSE_CODES: {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    readonly ended: 1000;
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    readonly going_away: 1001;
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    readonly too_big: 1009;
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    readonly reconnect: 4000;
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    readonly retry_later: 4001;
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    readonly refused: 4003;
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const STREAM_SCHEMAS: {
+    readonly StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json";
+};

package/dist/generated/wsstream.js

@@ -0,0 +1,28 @@
+// Code generated by cmd/internal/genwebtypes from sdk/wsstream/schema/v1/; DO NOT EDIT.
+// Regenerate with `make web-types` (ADR-162 D4 item 1).
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export const STREAM_CLOSE_CODES = {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    ended: 1000,
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    going_away: 1001,
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    too_big: 1009,
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    reconnect: 4000,
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    retry_later: 4001,
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    refused: 4003,
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export const STREAM_SCHEMAS = {
+    StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json",
+};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
+export { phoneURL } from "./phone.ts";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn, type ReSignInOptions } from "./signin.ts";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.ts";
+export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type StreamOptions, type TerminalOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
+export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, type StepUpChallenge, type StepUpEnd, type StepUpOptions, type StepUpWindow, } from "./stepup.ts";
+export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, type Clock, type FeedBackfill, type FeedConnectionOptions, type FeedConnectionPhase, type FeedConnectionState, type FeedFrame, type FeedLoss, type FeedSignal, type FeedSignals, } from "./feed/connection.ts";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, type NormalCloseNext, type StreamConnectionOptions, type StreamConnectionState, type WebSocketLike, } from "./stream/connection.ts";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, type TerminalRenderer, type TerminalStatus, type TerminalViewOptions, } from "./terminal/view.ts";
+export { FeedOpenError, SSEParser, fetchOpener, isRefusal, type FeedOpener, type SSEEvent } from "./feed/sse.ts";
+export * as terminalwire from "./terminalwire/codec.ts";
+export type * from "./generated/feed.ts";
+export type * from "./generated/kit.ts";
+export type * from "./generated/shares.ts";
+export type * from "./generated/workorder.ts";
+export type * from "./generated/workorder-events.ts";
+export type * from "./generated/wsstream.ts";
+export { FEED_SCHEMAS } from "./generated/feed.ts";
+export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.ts";
+export { SHARES_SCHEMAS } from "./generated/shares.ts";
+export { WORK_ORDER_SCHEMAS } from "./generated/workorder.ts";
+export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.ts";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.ts";

package/dist/index.js

@@ -0,0 +1,24 @@
+// @kottera/tera-web — the browser half of a UI over tera (ADR-162 D4).
+//
+// Framework-free, with no runtime dependencies: it carries no UI component,
+// because the framework is the author's.
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
+export { phoneURL } from "./phone.js";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn } from "./signin.js";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.js";
+export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, } from "./client.js";
+export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
+export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, } from "./feed/connection.js";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, } from "./stream/connection.js";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, } from "./terminal/view.js";
+export { FeedOpenError, SSEParser, fetchOpener, isRefusal } from "./feed/sse.js";
+// The frames a view of an attended session's terminal speaks (ADR-180 D4):
+// github.com/kottera/sdk/terminalwire's codec in the browser, under one name,
+// so its frame and vocabulary names claim nothing at the package's root.
+export * as terminalwire from "./terminalwire/codec.js";
+export { FEED_SCHEMAS } from "./generated/feed.js";
+export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.js";
+export { SHARES_SCHEMAS } from "./generated/shares.js";
+export { WORK_ORDER_SCHEMAS } from "./generated/workorder.js";
+export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.js";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.js";

package/dist/phone.d.ts

@@ -0,0 +1,11 @@
+import type { KitMeResponse } from "./generated/kit.ts";
+/**
+ * phoneURL builds the "Open on your phone" link of the page at `location`:
+ * the `phone_path` `me` answers, resolved against the app's `base` (`/`, or
+ * `/plugins/<name>/` on a path-based installation, as
+ * `TeraClientOptions.base`), with `next` set to `location.href`, fragment
+ * included. It answers a root-absolute path on the page's own origin. A
+ * `phone_path` that is not a path relative to the base is refused rather
+ * than followed.
+ */
+export declare function phoneURL(me: Pick<KitMeResponse, "phone_path">, location: Pick<Location, "href">, base?: string): string;

package/dist/phone.js

@@ -0,0 +1,24 @@
+// "Open on your phone" (ADR-177 D4): a link to tera's phone page, which draws
+// the page's URL as a QR code. A page builds it without knowing tera's URL:
+// it links to its own proxy's phone path, under its app's base, and tera's
+// proxy redirects to tera's phone page for a URL under this installation's
+// own base and to the app's base for any other.
+import { ROOT_BASE, isBaseRelative, underBase } from "./routes.js";
+/** The query parameter naming the page the phone opens. */
+const NEXT_PARAM = "next";
+/**
+ * phoneURL builds the "Open on your phone" link of the page at `location`:
+ * the `phone_path` `me` answers, resolved against the app's `base` (`/`, or
+ * `/plugins/<name>/` on a path-based installation, as
+ * `TeraClientOptions.base`), with `next` set to `location.href`, fragment
+ * included. It answers a root-absolute path on the page's own origin. A
+ * `phone_path` that is not a path relative to the base is refused rather
+ * than followed.
+ */
+export function phoneURL(me, location, base = ROOT_BASE) {
+    const path = me.phone_path;
+    if (!isBaseRelative(path)) {
+        throw new TypeError(`phoneURL: phone_path is not a path relative to the app's base: ${JSON.stringify(path)}`);
+    }
+    return underBase(base, path) + "?" + new URLSearchParams({ [NEXT_PARAM]: location.href }).toString();
+}

package/dist/routes.d.ts

@@ -0,0 +1,32 @@
+/** The prefix every kit route is served under. */
+export declare const ROUTE_PREFIX = "/tera/v1/";
+/**
+ * routePath builds a kit route's path from its segments, each encoded as one
+ * path segment: a capability or feed name holding `/` stays one segment rather
+ * than becoming two. An empty segment, `.` or `..` is refused: each would
+ * address a different route than the caller named, since a URL resolver
+ * collapses the dot segments and encoding does not change them.
+ */
+export declare function routePath(...segments: string[]): string;
+/** The base of an app served at the root of its origin. */
+export declare const ROOT_BASE = "/";
+/**
+ * appBase checks the path an app is served under on its origin and answers it
+ * ending in `/`: `/` on a plugin's own origin, `/plugins/<name>/` on a
+ * path-based installation. A base that is not a root-absolute path on the
+ * page's own origin is refused.
+ */
+export declare function appBase(base?: string): string;
+/**
+ * underBase places a path the kit names under an app's base: a kit path
+ * (`/tera/v1/me`, from {@link routePath}) or a path relative to the base
+ * (`_tera/signout`, the kit's `signout_path`) alike.
+ */
+export declare function underBase(base: string, path: string): string;
+/**
+ * isBaseRelative reports whether a path the kit answers (`signout_path`,
+ * `phone_path`) is relative to the app's base: not empty, not root-absolute,
+ * naming no scheme and holding no backslash, so that {@link underBase} keeps
+ * it on the page's own origin under its base.
+ */
+export declare function isBaseRelative(path: unknown): path is string;

package/dist/routes.js

@@ -0,0 +1,69 @@
+// The browser routes a plugin's webui kit serves, all under one reserved
+// prefix on the plugin's origin (ADR-162 D3). The prefix is not `/_tera/`,
+// which tera's reverse proxy keeps for its own paths and never forwards.
+//
+// The route table itself is declared once, in Go, under sdk/plugin/webui, and
+// generated into ./generated/kit.ts. What is here is how a path is built from
+// it.
+//
+// The table's paths are the kit's own: tera's proxy serves a plugin either at
+// the root of its own origin or, on a path-based installation, under
+// `/plugins/<name>/` on tera's origin, and strips that prefix before the kit
+// sees a request. A page therefore reaches every route, and tera's sign-out,
+// under its app's base (`/` or `/plugins/<name>/`), which only the page knows.
+import { KIT_ROUTE_PREFIX } from "./generated/kit.js";
+/** The prefix every kit route is served under. */
+export const ROUTE_PREFIX = KIT_ROUTE_PREFIX;
+/**
+ * routePath builds a kit route's path from its segments, each encoded as one
+ * path segment: a capability or feed name holding `/` stays one segment rather
+ * than becoming two. An empty segment, `.` or `..` is refused: each would
+ * address a different route than the caller named, since a URL resolver
+ * collapses the dot segments and encoding does not change them.
+ */
+export function routePath(...segments) {
+    if (segments.length === 0) {
+        throw new TypeError("routePath: at least one segment is required");
+    }
+    const parts = segments.map((segment, i) => {
+        if (segment === "") {
+            throw new TypeError(`routePath: segment ${i} is empty`);
+        }
+        if (segment === "." || segment === "..") {
+            throw new TypeError(`routePath: segment ${i} is a dot segment (${segment})`);
+        }
+        return encodeURIComponent(segment);
+    });
+    return ROUTE_PREFIX + parts.join("/");
+}
+/** The base of an app served at the root of its origin. */
+export const ROOT_BASE = "/";
+/**
+ * appBase checks the path an app is served under on its origin and answers it
+ * ending in `/`: `/` on a plugin's own origin, `/plugins/<name>/` on a
+ * path-based installation. A base that is not a root-absolute path on the
+ * page's own origin is refused.
+ */
+export function appBase(base = ROOT_BASE) {
+    if (!base.startsWith("/") || base.startsWith("//") || /[?#\\]/.test(base)) {
+        throw new TypeError(`appBase: ${JSON.stringify(base)} is not a root-absolute path on this origin`);
+    }
+    return base.endsWith("/") ? base : base + "/";
+}
+/**
+ * underBase places a path the kit names under an app's base: a kit path
+ * (`/tera/v1/me`, from {@link routePath}) or a path relative to the base
+ * (`_tera/signout`, the kit's `signout_path`) alike.
+ */
+export function underBase(base, path) {
+    return appBase(base) + (path.startsWith("/") ? path.slice(1) : path);
+}
+/**
+ * isBaseRelative reports whether a path the kit answers (`signout_path`,
+ * `phone_path`) is relative to the app's base: not empty, not root-absolute,
+ * naming no scheme and holding no backslash, so that {@link underBase} keeps
+ * it on the page's own origin under its base.
+ */
+export function isBaseRelative(path) {
+    return typeof path === "string" && path !== "" && !path.startsWith("/") && !/^[^/?#]*:/.test(path) && !path.includes("\\");
+}

package/dist/signin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export declare const SIGN_IN_REQUIRED = "sign_in_required";
+export interface ReSignInOptions {
+    /** Sends the page to a URL; `location.assign` when absent. */
+    navigate?: (url: string) => void;
+    /** The page's own URL, which is loaded again; `location.href` when absent. */
+    pageURL?: () => string;
+}
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export declare function isSignInRequiredAnswer(status: number, contentType: string, body: string): boolean;
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export declare function isSignInRequired(res: Response): Promise<boolean>;
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export declare function reSignIn(options?: ReSignInOptions): void;

package/dist/signin.js

@@ -0,0 +1,74 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export const SIGN_IN_REQUIRED = "sign_in_required";
+const JSON_TYPE = "application/json";
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export function isSignInRequiredAnswer(status, contentType, body) {
+    if (status !== 401)
+        return false;
+    if (contentType.toLowerCase().split(";")[0].trim() !== JSON_TYPE)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return false;
+    const error = parsed.error;
+    return typeof error === "object" && error !== null && error.code === SIGN_IN_REQUIRED;
+}
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export async function isSignInRequired(res) {
+    if (res.status !== 401)
+        return false;
+    let text;
+    try {
+        text = await res.clone().text();
+    }
+    catch {
+        return false;
+    }
+    return isSignInRequiredAnswer(res.status, res.headers.get("content-type") ?? "", text);
+}
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export function reSignIn(options = {}) {
+    const navigate = options.navigate ?? ((url) => globalThis.location.assign(url));
+    const pageURL = options.pageURL ?? (() => globalThis.location.href);
+    navigate(pageURL());
+}

package/dist/stepup.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A person's step-up, from the page's side (ADR-173 D11 step 3).
+ *
+ * An act the plugin requires the person's confirmation for is refused
+ * `step_up_required`: by the plugin's own route, in the kit's envelope with
+ * `error.step_up`, or by a Work Order verb, relayed by the invoke route with
+ * the challenge in the refusal's `data.step_up`. Either names the step-up's
+ * id and the page on tera's origin the person confirms it on. The client then:
+ *
+ * 1. opens that page in a new window, and when the browser will not open one,
+ *    navigates to it instead with a `return_to` naming this page, which tera
+ *    accepts only on the plugin's own origin;
+ * 2. polls `GET /tera/v1/step-ups/{id}` until the step-up is satisfied,
+ *    declined or expired, and closes the window it opened;
+ * 3. sends the identical request again with `Tera-Step-Up: <id>` — or, for a
+ *    Work Order verb, with `step_up` in its params.
+ *
+ * A step-up confirms one act once: nothing here holds an id past the retry it
+ * was confirmed for, except across the navigation fallback, where the id rides
+ * back on the `return_to` as {@link STEP_UP_RESUME_PARAM} and is spent by the
+ * first request that needs a step-up after the page loads again.
+ */
+import type { KitError } from "./generated/kit.ts";
+/** The request header that carries a confirmed step-up's id to the plugin's route. */
+export declare const STEP_UP_HEADER = "Tera-Step-Up";
+/** The code of a refusal that needs the person's confirmation. */
+export declare const STEP_UP_REQUIRED = "step_up_required";
+/**
+ * The query parameter the navigation fallback adds to its `return_to`, naming
+ * the step-up the person went to confirm, so the page that loads again
+ * resumes it rather than beginning another.
+ */
+export declare const STEP_UP_RESUME_PARAM = "tera_step_up";
+/** How often the step-up's state is read while the person confirms it, by default. */
+export declare const STEP_UP_POLL_MS = 1000;
+/** What a refusal names of the step-up it needs: the kit envelope's `error.step_up`. */
+export type StepUpChallenge = NonNullable<KitError["error"]["step_up"]>;
+/** The part of a `Window` the client uses: whether the person closed it, and closing it. */
+export interface StepUpWindow {
+    readonly closed: boolean;
+    close(): void;
+}
+export interface StepUpOptions {
+    /** Opens the step-up's page in a new window; `window.open(url, "_blank")` when absent. Answers null when the browser would not open one. */
+    openWindow?: (url: string) => StepUpWindow | null;
+    /** The page's own URL, which the navigation fallback returns to; `location.href` when absent. */
+    pageURL?: () => string;
+    /** Waits between reads of the step-up's state; a timer when absent. */
+    sleep?: (ms: number) => Promise<void>;
+    /** How long to wait between reads; {@link STEP_UP_POLL_MS} when absent. */
+    pollIntervalMs?: number;
+}
+/**
+ * How a step-up ended without being confirmed:
+ * - `declined` — the person said they did not ask for it;
+ * - `expired` — nobody confirmed it in time;
+ * - `spent` — it confirmed another request already;
+ * - `abandoned` — the person closed its window and it is still waiting;
+ * - `navigated` — the browser would not open a window, so the page was sent to
+ *   tera's; it returns here, and the next request that needs a step-up resumes
+ *   this one.
+ */
+export type StepUpEnd = "declined" | "expired" | "spent" | "abandoned" | "navigated";
+/** A step-up the person did not confirm: the request it was for was not sent again. */
+export declare class StepUpError extends Error {
+    /** The step-up's id. */
+    readonly stepUpId: string;
+    /** How it ended. */
+    readonly end: StepUpEnd;
+    constructor(stepUpId: string, end: StepUpEnd, message: string);
+}
+/**
+ * The step-up a refusal needs confirmed, when it is one this client can have
+ * confirmed: code `step_up_required` with a page to open. A refusal naming an
+ * ended step-up carries no page, and is not one.
+ */
+export declare function stepUpChallengeOf(code: string, stepUp: unknown): StepUpChallenge | null;
+/**
+ * The step-up page's URL with `return_to` set to `returnTo`, itself carrying
+ * {@link STEP_UP_RESUME_PARAM}. tera follows it back only when it is on the
+ * plugin's own origin.
+ */
+export declare function stepUpPageURL(pageURL: string, stepUpId: string, returnTo: string): string;
+/** The step-up id a page loaded through the navigation fallback carries back, or null. */
+export declare function resumedStepUp(pageURL: string): string | null;
+export declare function defaultOpenWindow(url: string): StepUpWindow | null;
+export declare function defaultSleep(ms: number): Promise<void>;

package/dist/stepup.js

@@ -0,0 +1,66 @@
+/** The request header that carries a confirmed step-up's id to the plugin's route. */
+export const STEP_UP_HEADER = "Tera-Step-Up";
+/** The code of a refusal that needs the person's confirmation. */
+export const STEP_UP_REQUIRED = "step_up_required";
+/**
+ * The query parameter the navigation fallback adds to its `return_to`, naming
+ * the step-up the person went to confirm, so the page that loads again
+ * resumes it rather than beginning another.
+ */
+export const STEP_UP_RESUME_PARAM = "tera_step_up";
+/** How often the step-up's state is read while the person confirms it, by default. */
+export const STEP_UP_POLL_MS = 1000;
+/** A step-up the person did not confirm: the request it was for was not sent again. */
+export class StepUpError extends Error {
+    /** The step-up's id. */
+    stepUpId;
+    /** How it ended. */
+    end;
+    constructor(stepUpId, end, message) {
+        super(message);
+        this.name = "StepUpError";
+        this.stepUpId = stepUpId;
+        this.end = end;
+    }
+}
+/**
+ * The step-up a refusal needs confirmed, when it is one this client can have
+ * confirmed: code `step_up_required` with a page to open. A refusal naming an
+ * ended step-up carries no page, and is not one.
+ */
+export function stepUpChallengeOf(code, stepUp) {
+    if (code !== STEP_UP_REQUIRED || typeof stepUp !== "object" || stepUp === null)
+        return null;
+    const c = stepUp;
+    if (typeof c.id !== "string" || c.id === "" || typeof c.url !== "string" || c.url === "")
+        return null;
+    return c;
+}
+/**
+ * The step-up page's URL with `return_to` set to `returnTo`, itself carrying
+ * {@link STEP_UP_RESUME_PARAM}. tera follows it back only when it is on the
+ * plugin's own origin.
+ */
+export function stepUpPageURL(pageURL, stepUpId, returnTo) {
+    const back = new URL(returnTo);
+    back.searchParams.set(STEP_UP_RESUME_PARAM, stepUpId);
+    const page = new URL(pageURL);
+    page.searchParams.set("return_to", back.toString());
+    return page.toString();
+}
+/** The step-up id a page loaded through the navigation fallback carries back, or null. */
+export function resumedStepUp(pageURL) {
+    try {
+        const id = new URL(pageURL).searchParams.get(STEP_UP_RESUME_PARAM);
+        return id === null || id === "" ? null : id;
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultOpenWindow(url) {
+    return globalThis.open?.(url, "_blank") ?? null;
+}
+export function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}