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

package/README.md

@@ -12,6 +12,7 @@ author's — and has no runtime dependencies. It is not yet published.
 | `src/index.ts` | The package's one entry point. Everything public is re-exported here. |
 | `src/routes.ts` | The route prefix, `routePath`, and the app's base (`appBase`, `underBase`) every route and the sign-out are reached under. |
 | `src/client.ts` | `TeraClient`, the typed client over D3's routes (D4 items 1, 3 and 4): `me()`, `invoke(capability, params)`, `feed(options)` (a `FeedConnection` read with the client's fetch), `upload(file, options)` with progress, and `signOut()`. A kit refusal throws `KitRequestError`; a verb's refusal answers as its verdict. |
+| `src/phone.ts` | `phoneURL(me, location, base?)`, the "Open on your phone" link (ADR-177 D4): `me().phone_path` resolved against the app's base (`/` by default, `/plugins/<name>/` on a path-based installation), with `next` set to `location.href`, fragment included. tera's proxy sends it on to tera's phone page, which draws the page's URL as a QR code, so the page needs no knowledge of tera's URL. A `phone_path` that is not relative to the base throws. |
 | `src/stepup.ts` | A person's step-up from the page's side (ADR-173 D11): the step-up header, the `return_to` the navigation fallback carries, and `StepUpError`. Every `TeraClient` request — `me()`, `invoke()`, `upload()` and `fetch(path)` to the plugin's own routes — has the person confirm a `step_up_required` and sends the request once more; `stepUp(id)` reads `GET /tera/v1/step-ups/{id}`. |
 | `src/generated/` | The contract, generated from the committed schemas under `sdk/plugin/webui/schema/`, `sdk/workorder/schema/`, `sdk/feed/schema/` and `sdk/shares/schema/` (D4 item 1; the share types, ADR-174 D14): one type per schema, the kit's route table as `KIT_ROUTE_TABLE`, and the maps from a route or a feed event to the type it carries. Never hand-edited, and never hand-write a type it declares: `make web-types` regenerates it, and `TestWebTypes_MatchCommitted` (`cmd/internal/genwebtypes`) fails on a hand edit or a stale generation. |
 | `src/feed/` | The stream connection (D4 item 2). |
@@ -37,3 +38,16 @@ is here for an author with one, `tsc -p sdk/web`. What the gate does run over
 the generated types is `src/contract.test.ts`: every committed schema has a
 generated type, the route table is the committed one, and a fixture of each
 D3 shape, annotated with its generated type, is valid against its schema.
+
+## Open on your phone
+
+```ts
+const me = await client.me();
+link.href = phoneURL(me, window.location, "/plugins/wb/"); // omit the base at the root of the plugin's own origin
+```
+
+The link is the plugin's own `_tera/phone`, under its base. tera's proxy
+redirects it to tera's `/oauth/phone` only for a page under this
+installation's own base, and to the app's base for any other. The fragment
+rides along, but survives on the phone only when no sign-in intervenes, so a
+deep link a phone must open on its first visit routes by path or query.

package/dist/client.js

@@ -47,7 +47,7 @@
  * window opener and timer, so its tests drive it against a fake and no
  * network.
  */
-import { appBase, routePath, underBase } from "./routes.js";
+import { appBase, isBaseRelative, routePath, underBase } from "./routes.js";
 import { FeedConnection } from "./feed/connection.js";
 import { fetchOpener } from "./feed/sse.js";
 import { STEP_UP_HEADER, STEP_UP_POLL_MS, StepUpError, defaultOpenWindow, defaultSleep, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
@@ -335,7 +335,7 @@ export class TeraClient {
      */
     async signOut() {
         const { signout_path: path } = await this.me();
-        if (typeof path !== "string" || path === "" || path.startsWith("/") || /^[^/?#]*:/.test(path) || /[\\]/.test(path)) {
+        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));

package/dist/generated/kit.d.ts

@@ -85,6 +85,8 @@ export type KitMeResponse = {
     subject: string;
     /** Where to send the person to sign out: tera's own sign-out, as a path relative to the app's base, which a page resolves against that base (/ on the plugin's own origin, /plugins/<name>/ on a path-based installation). It is never root-absolute. */
     signout_path: string;
+    /** Where to send the person to open a page on their phone: tera's proxy's redirect to tera's phone page, given the page's own URL as the next query parameter. A path relative to the app's base, resolved as signout_path is. It is never root-absolute. */
+    phone_path: string;
     /** What to call the signed-in person, as tera's record of them holds it; absent when it holds none. Presentation only: subject is the identity, and nothing is decided by this. */
     display_name?: string;
     /** The address tera's record of the signed-in person holds; absent when it holds none. Presentation only: subject is the identity, and nothing is decided by this. */
@@ -155,10 +157,13 @@ export declare const KIT_SCHEMAS: {
 export declare const KIT_ROUTE_PREFIX = "/tera/v1/";
 /** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path: relative, resolved against the app's base. */
 export declare 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 declare const KIT_PHONE_PATH = "_tera/phone";
 /** The kit's route table (ADR-162 D3), as sdk/plugin/webui declares it. */
 export declare const KIT_ROUTE_TABLE: {
     readonly prefix: "/tera/v1/";
     readonly signout_path: "_tera/signout";
+    readonly phone_path: "_tera/phone";
     readonly 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.";
     readonly 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.";
     readonly error: {
@@ -170,7 +175,7 @@ export declare const KIT_ROUTE_TABLE: {
         readonly name: "me";
         readonly method: "GET";
         readonly path: "/tera/v1/me";
-        readonly summary: "Who is signed in, and where to send them to sign out.";
+        readonly summary: "Who is signed in, where to send them to sign out, and where to send them to open a page on their phone.";
         readonly same_origin: false;
         readonly response: {
             readonly media_type: "application/json";

package/dist/generated/kit.js

@@ -17,10 +17,13 @@ export const KIT_SCHEMAS = {
 export const KIT_ROUTE_PREFIX = "/tera/v1/";
 /** 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",
+    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: {
@@ -33,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",

package/dist/generated/workorder.d.ts

@@ -1404,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;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -9,7 +10,7 @@ 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

@@ -3,12 +3,13 @@
 // 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 { 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

@@ -23,3 +23,10 @@ export declare function appBase(base?: string): string;
  * (`_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

@@ -58,3 +58,12 @@ export function appBase(base = ROOT_BASE) {
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kottera/tera-web",
-  "version": "0.1.0-rc.4",
+  "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": {