@kottera/tera-web 0.1.0-rc.3 → 0.1.0-rc.5

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));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kottera/tera-web",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.5",
   "description": "The browser half of a UI over tera: a framework-free client for the /tera/v1/ routes a plugin's webui kit serves (ADR-162 D4).",
   "license": "Apache-2.0",
   "repository": {