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

package/dist/generated/kit.js

@@ -10,16 +10,20 @@ export const KIT_SCHEMAS = {
     KitFeedEventReauthenticate: "sdk/plugin/webui/schema/v1/feed.event.reauthenticate.json",
     KitInvokeResponse: "sdk/plugin/webui/schema/v1/invoke.response.json",
     KitMeResponse: "sdk/plugin/webui/schema/v1/me.response.json",
+    KitStepUpResponse: "sdk/plugin/webui/schema/v1/step-up.response.json",
     KitUploadResponse: "sdk/plugin/webui/schema/v1/upload.response.json",
 };
-/** The prefix every kit route is served under (ADR-162 D3). */
+/** The prefix every kit route is served under (ADR-162 D3), below the app's base. */
 export const KIT_ROUTE_PREFIX = "/tera/v1/";
-/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path. */
-export const KIT_SIGNOUT_PATH = "/_tera/signout";
+/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path: relative, resolved against the app's base. */
+export const KIT_SIGNOUT_PATH = "_tera/signout";
+/** tera's proxy's phone path, which `GET /tera/v1/me` answers as phone_path: relative, resolved against the app's base. */
+export const KIT_PHONE_PATH = "_tera/phone";
 /** The kit's route table (ADR-162 D3), as sdk/plugin/webui declares it. */
 export const KIT_ROUTE_TABLE = {
     prefix: "/tera/v1/",
-    signout_path: "/_tera/signout",
+    signout_path: "_tera/signout",
+    phone_path: "_tera/phone",
     same_origin: "A route marked same_origin refuses a request unless it is same-origin: when the request carries Sec-Fetch-Site, that header must be same-origin; when it does not, its Origin must equal the request's own (scheme http or https, and the Host the request was sent to). The refusal is 403 cross_origin.",
     public: "None. Every route under the prefix refuses a request with no verified caller, 401 unauthenticated, before anything else is decided. Only the app's assets, outside the prefix, are served to an anonymous request.",
     error: {
@@ -32,7 +36,7 @@ export const KIT_ROUTE_TABLE = {
             name: "me",
             method: "GET",
             path: "/tera/v1/me",
-            summary: "Who is signed in, and where to send them to sign out.",
+            summary: "Who is signed in, where to send them to sign out, and where to send them to open a page on their phone.",
             same_origin: false,
             response: {
                 media_type: "application/json",
@@ -144,5 +148,24 @@ export const KIT_ROUTE_TABLE = {
                 description: "The staged artifact.",
             },
         },
+        {
+            name: "step_up",
+            method: "GET",
+            path: "/tera/v1/step-ups/{id}",
+            summary: "Read one of the person's own step-ups as the person (ADR-173 D11): what a page polls, after opening the step-up's url, until it is satisfied, declined or expired. A step-up that is not the person's is tera's 404, the same as an id no step-up carries.",
+            same_origin: false,
+            path_params: [
+                {
+                    name: "id",
+                    description: "The step-up's id, as a step_up_required refusal's step_up names it.",
+                    required: true,
+                },
+            ],
+            response: {
+                media_type: "application/json",
+                schema: "https://kottera.dev/schemas/plugin/webui/step-up.response/v1",
+                description: "The step-up's state.",
+            },
+        },
     ],
 };

package/dist/generated/shares.d.ts

@@ -0,0 +1,196 @@
+/**
+ * An ended share.
+ *
+ * The result of api.v1.shares.delete and api.v1.shares.leave: what the act ended. An ended share decides nothing and is not listed.
+ *
+ * Schema: sdk/shares/schema/v1/ended.json
+ */
+export type SharesEnded = {
+    /** The ended share's id. */
+    id: string;
+    /** The installation whose resource was shared, <vault>/plugins/<installation>. */
+    installation: string;
+    /** The resource that was shared. */
+    resource: string;
+    /** The grantee person's id. */
+    grantee: string;
+    /** The sharer person's id. */
+    sharer: string;
+    /** How the share ended, as its record holds it: revoked or left. */
+    ended: "revoked" | "left";
+};
+/**
+ * Extend a share.
+ *
+ * The params of api.v1.shares.patch, PATCH /api/v1/shares/{id} (ADR-174 D11).
+ *
+ * Schema: sdk/shares/schema/v1/extend.request.json
+ */
+export type SharesExtendRequest = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+    /** The new expiry: later than the share's, at most the installation's max_expiry from now. Absent takes the kind's default_expiry from now, clamped to max_expiry. */
+    expires_at?: string;
+};
+/**
+ * Name one share.
+ *
+ * The params of api.v1.shares.get, api.v1.shares.delete and api.v1.shares.leave: the {id} of /api/v1/shares/{id}.
+ *
+ * Schema: sdk/shares/schema/v1/id.request.json
+ */
+export type SharesIdRequest = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+};
+/**
+ * A list of shares.
+ *
+ * The result of api.v1.shares.list.
+ *
+ * Schema: sdk/shares/schema/v1/list.json
+ */
+export type SharesList = {
+    /** The shares, each with whether it decides now. */
+    shares: {
+        /** The share's id, a UUIDv7. */
+        id: string;
+        /** The installation whose resource is shared, <vault>/plugins/<installation>. */
+        installation: string;
+        /** The resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+        resource: string;
+        /** The shared verbs. */
+        verbs: string[] | null;
+        /** What the grantee is: person. */
+        grantee_kind: string;
+        /** The grantee person's id. */
+        grantee: string;
+        /** The id of the person who made the share. */
+        sharer: string;
+        /** The plugin principal that made the share for its sharer; absent when the sharer made it directly. */
+        created_via?: string;
+        /** When the share was made. */
+        created_at: string;
+        /** When the share stops deciding. */
+        expires_at: string;
+        /** When the share was last extended; absent if never. */
+        extended_at?: string;
+        /** Whether the share decides at least one of its verbs on the grantee's next request, computed from what decides now. */
+        deciding: boolean;
+        /** When deciding is false, the one reason why. Absent while the share decides. */
+        not_deciding?: "sharer_lost_access" | "sharing_disabled" | "installation_not_standing" | "verb_no_longer_shareable" | "pending_invitation";
+    }[] | null;
+};
+/**
+ * List shares.
+ *
+ * The params of api.v1.shares.list, the query of GET /api/v1/shares. At most one member is named; with none, the caller's own live shares as grantee and as sharer.
+ *
+ * Schema: sdk/shares/schema/v1/list.request.json
+ */
+export type SharesListRequest = {
+    /** An installation, <vault>/plugins/<name>: every share on it. Needs the shares admin grant (api/v1/shares/admin). */
+    installation?: string;
+    /** One resource, plugins/<vault>/<installation>/<kind>/<id>: every share on it when the caller's own grants include its share-conferring verb, else the caller's own shares on it. */
+    resource?: string;
+    /** A grantee's person id; someone else's needs the shares admin grant. */
+    grantee?: string;
+    /** A sharer's person id; someone else's needs the shares admin grant. */
+    sharer?: string;
+};
+/**
+ * Make a share.
+ *
+ * The params of api.v1.shares.create, the body of POST /api/v1/shares (ADR-174 D6).
+ *
+ * Schema: sdk/shares/schema/v1/make.request.json
+ */
+export type SharesMakeRequest = {
+    /** The one resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+    resource: string;
+    /** The shared verbs: a non-empty subset of the kind's sharing { verbs }, never its share-conferring verb. */
+    verbs: string[];
+    /** The grantee person's id. Exactly one of grantee and grantee_address names the grantee. */
+    grantee?: string;
+    /** An email address the directory resolves to the grantee. An address no person holds is invited, and the share is pending until they sign in, on a kind whose effective grantee class is addresses; otherwise it is refused share_grantee_not_admitted. */
+    grantee_address?: string;
+    /** The share's expiry, at most the installation's max_expiry from now. Absent takes the kind's default_expiry, clamped to max_expiry. */
+    expires_at?: string;
+};
+/**
+ * The vocabulary of the share acts' refusal codes (sdk/shares.Codes).
+ *
+ * Every stable code a share act is refused with. A code is never renamed; a new refusal is a new code, so a reader keeps a code it does not know as it arrived. share_not_found answers a share the caller may not see exactly as an id no share has. share_grantee_not_admitted answers an address no person holds on a kind whose effective grantee class is not addresses; on one that is, the address is invited and the share is pending until the invitee signs in.
+ *
+ * Schema: sdk/shares/schema/v1/refusal-code.json
+ */
+export type SharesRefusalCode = "share_sharer_not_a_person" | "share_sharing_disabled" | "share_resource_not_shareable" | "share_resource_unknown" | "share_actor_other_installation" | "share_verb_not_shareable" | "share_verb_confers_sharing" | "share_verb_not_held" | "share_grantee_not_admitted" | "share_guest_cannot_invite" | "share_invitation_refused" | "share_grantee_is_sharer" | "share_expiry_beyond_max" | "share_cap_active" | "share_cap_pending_invitations" | "share_exists" | "share_caller_not_a_person" | "share_not_found" | "share_sharer_lost_access" | "share_expiry_not_later" | "share_admin_required" | "share_list_query" | "shares_unavailable";
+/**
+ * A share act refused.
+ *
+ * A share act tera refused, as the shares client answers it: the route's stable code and its words, unchanged, and the detail the code declares.
+ *
+ * Schema: sdk/shares/schema/v1/refusal.json
+ */
+export type SharesRefusal = {
+    /** The route's stable code. A code a reader does not know is kept as it arrived. */
+    code: string;
+    /** The route's words for a person, unchanged. */
+    message: string;
+    /** On share_verb_not_held, share_verb_not_shareable and share_verb_confers_sharing, the verb refused. */
+    verb?: string;
+    /** On share_exists, the id of the share already there. */
+    existing?: string;
+    /** On share_invitation_refused, why the address was not invited (inviter_limited, email_unavailable, ...). */
+    invitation?: string;
+};
+/**
+ * A share.
+ *
+ * One live share, with whether it decides now: the result of api.v1.shares.create, api.v1.shares.get and api.v1.shares.patch, and each member of a list (ADR-174 D14).
+ *
+ * Schema: sdk/shares/schema/v1/share.json
+ */
+export type SharesShare = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+    /** The installation whose resource is shared, <vault>/plugins/<installation>. */
+    installation: string;
+    /** The resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+    resource: string;
+    /** The shared verbs. */
+    verbs: string[] | null;
+    /** What the grantee is: person. */
+    grantee_kind: string;
+    /** The grantee person's id. */
+    grantee: string;
+    /** The id of the person who made the share. */
+    sharer: string;
+    /** The plugin principal that made the share for its sharer; absent when the sharer made it directly. */
+    created_via?: string;
+    /** When the share was made. */
+    created_at: string;
+    /** When the share stops deciding. */
+    expires_at: string;
+    /** When the share was last extended; absent if never. */
+    extended_at?: string;
+    /** Whether the share decides at least one of its verbs on the grantee's next request, computed from what decides now. */
+    deciding: boolean;
+    /** When deciding is false, the one reason why. Absent while the share decides. */
+    not_deciding?: "sharer_lost_access" | "sharing_disabled" | "installation_not_standing" | "verb_no_longer_shareable" | "pending_invitation";
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const SHARES_SCHEMAS: {
+    readonly SharesEnded: "sdk/shares/schema/v1/ended.json";
+    readonly SharesExtendRequest: "sdk/shares/schema/v1/extend.request.json";
+    readonly SharesIdRequest: "sdk/shares/schema/v1/id.request.json";
+    readonly SharesList: "sdk/shares/schema/v1/list.json";
+    readonly SharesListRequest: "sdk/shares/schema/v1/list.request.json";
+    readonly SharesMakeRequest: "sdk/shares/schema/v1/make.request.json";
+    readonly SharesRefusalCode: "sdk/shares/schema/v1/refusal-code.json";
+    readonly SharesRefusal: "sdk/shares/schema/v1/refusal.json";
+    readonly SharesShare: "sdk/shares/schema/v1/share.json";
+};

package/dist/generated/shares.js

@@ -0,0 +1,17 @@
+// Code generated by cmd/internal/genwebtypes from sdk/shares/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 SHARES_SCHEMAS = {
+    SharesEnded: "sdk/shares/schema/v1/ended.json",
+    SharesExtendRequest: "sdk/shares/schema/v1/extend.request.json",
+    SharesIdRequest: "sdk/shares/schema/v1/id.request.json",
+    SharesList: "sdk/shares/schema/v1/list.json",
+    SharesListRequest: "sdk/shares/schema/v1/list.request.json",
+    SharesMakeRequest: "sdk/shares/schema/v1/make.request.json",
+    SharesRefusalCode: "sdk/shares/schema/v1/refusal-code.json",
+    SharesRefusal: "sdk/shares/schema/v1/refusal.json",
+    SharesShare: "sdk/shares/schema/v1/share.json",
+};

package/dist/generated/workorder.d.ts

@@ -48,6 +48,8 @@ export type WorkOrderAnswerParams = {
     replace?: boolean;
     /** Cross ONE refusal: a select site where this Work Order's live step binding is running a candidate the new pin no longer offers (ADR-130 D5, ratified crossable 2026-09-20). The binding row is RETAINED at the same chain generation and the resume RE-SELECTS from the new candidate set, running the candidate loop against live capacity exactly as a first admission would. It does NOT preserve the candidate the run is on — that candidate is gone, which is why the refusal exists. It lifts nothing else: a capability or operation switch at a fixed site has no candidate to re-select, and a withdrawn `yields_turn` offer is frozen for the life of a pinned conversation (ADR-129 D9). Over a site whose candidate IS still offered, or a fixed site, it is a no-op and says so in the manifest rather than refusing. Only meaningful with `repin`. Authorized against `api/v1/workorders/repin/reselect` IN ADDITION to `api/v1/workorders/repin`. Pass `dry_run` first: the manifest's `would_reselect` names the site, the candidate being given up and the set the resume will choose from. */
     reselect?: boolean;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
     /** The operator's exact prose. Interactive answers become one durable ledger message; other answers are wrapped as {"answer": "<text>"}. Ignored when `payload` is supplied. */
     text?: string;
 };
@@ -965,6 +967,13 @@ export type WorkOrderGetResult = {
             authorized_for?: string;
             plugin?: string;
             evidence_class?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
+            display_name?: string;
         };
     };
     question?: {
@@ -1217,10 +1226,22 @@ export type WorkOrderGetResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     outcome?: {
         outcome_provenance: string;
         attested_by?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     relations: {
         relation: string;
@@ -1383,6 +1404,9 @@ export type WorkOrderGetResult = {
     } | null;
     created_by?: string;
     created_via?: string;
+    arrival_evidence?: {
+        [key: string]: string;
+    };
     created_at: string;
     updated_at: string;
     off_tera: boolean;
@@ -1785,6 +1809,12 @@ export type WorkOrderListResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
     }[] | null;
 };
@@ -1818,6 +1848,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1840,6 +1876,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1862,6 +1904,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1962,6 +2010,12 @@ export type WorkOrderProgressResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     } | null;
     addressed_events: {
         id: number;
@@ -2550,6 +2604,8 @@ export type WorkOrderSubmitResultParams = {
     };
     /** The id of the last event you have processed on this Work Order. The response carries the events addressed to you after it (a repost, a cancel, a wake, an answer, posted guidance), at most 32 with `more` set when there were more, plus `newest_event_id`. The server keeps no cursor: omit it, or pass 0, for everything addressed so far. */
     seen_through?: number;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
 };
 /**
  * `work_order.submit_result` result (v1).
@@ -2565,6 +2621,12 @@ export type WorkOrderSubmitResultResult = {
     outcome?: {
         outcome_provenance: string;
         attested_by?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     checks?: string;
     addressed_events: {
@@ -2612,6 +2674,12 @@ export type WorkOrderTakeResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     } | null;
     instructions: string;
     requirements?: string;
@@ -2675,6 +2743,8 @@ export type WorkOrderTransitionParams = {
     replace?: boolean;
     /** Cross ONE refusal: a select site where this Work Order's live step binding is running a candidate the new pin no longer offers (ADR-130 D5, ratified crossable 2026-09-20). The binding row is RETAINED at the same chain generation and the resume RE-SELECTS from the new candidate set, running the candidate loop against live capacity exactly as a first admission would. It does NOT preserve the candidate the run is on — that candidate is gone, which is why the refusal exists. It lifts nothing else: a capability or operation switch at a fixed site has no candidate to re-select, and a withdrawn `yields_turn` offer is frozen for the life of a pinned conversation (ADR-129 D9). Over a site whose candidate IS still offered, or a fixed site, it is a no-op and says so in the manifest rather than refusing. Only meaningful with `repin`. Authorized against `api/v1/workorders/repin/reselect` IN ADDITION to `api/v1/workorders/repin`. Pass `dry_run` first: the manifest's `would_reselect` names the site, the candidate being given up and the set the resume will choose from. */
     reselect?: boolean;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
     /** action=answer only: the operator's answer text. Read work_order.get(id).question first — that is what is being asked. */
     text?: string;
 };
@@ -3102,6 +3172,12 @@ export type WorkOrderTreeResult = {
         outcome?: {
             outcome_provenance: string;
             attested_by?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         replaced?: {
             relation: string;
@@ -3326,6 +3402,12 @@ export type WorkOrderTreeResult = {
         outcome?: {
             outcome_provenance: string;
             attested_by?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         replaced?: {
             relation: string;

package/dist/index.d.ts

@@ -1,12 +1,16 @@
-export { ROUTE_PREFIX, routePath } from "./routes.ts";
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
+export { phoneURL } from "./phone.ts";
 export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, 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 FeedConnectionOptions, type FeedConnectionPhase, type FeedConnectionState, type FeedFrame, type FeedLoss, type FeedSignal, type FeedSignals, } from "./feed/connection.ts";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal, type FeedOpener, type SSEEvent } from "./feed/sse.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 { FEED_SCHEMAS } from "./generated/feed.ts";
-export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.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";

package/dist/index.js

@@ -2,11 +2,14 @@
 //
 // Framework-free, with no runtime dependencies: it carries no UI component,
 // because the framework is the author's.
-export { ROUTE_PREFIX, routePath } from "./routes.js";
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
+export { phoneURL } from "./phone.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 { FeedOpenError, SSEParser, fetchOpener, isRefusal } from "./feed/sse.js";
 export { FEED_SCHEMAS } from "./generated/feed.js";
-export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.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";

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

@@ -8,3 +8,25 @@ export declare const ROUTE_PREFIX = "/tera/v1/";
  * 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

@@ -5,6 +5,12 @@
 // 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;
@@ -30,3 +36,34 @@ export function routePath(...segments) {
     });
     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("\\");
+}