@greensecurity/javascript-sdk 0.46.0-beta.1 → 0.46.0-beta.11

package/dist/esm/apps/surfaces.d.ts

@@ -0,0 +1,61 @@
+export type Portal = "vendor" | "company" | "facility" | "system";
+export type SurfaceKind = "navigation" | "drawer.default" | "overview" | "list" | "list.row_action" | "detail" | "detail.tabs" | "settings"
+/** An app page: one of the app's own `ui_extensions.routes`, rendered full screen. */
+ | "page";
+/**
+ * The kind of record a surface is showing. These match the public API resource each one is
+ * read through (`/vendors`, `/vendors/credentials`, `/facilities`, `/companies`,
+ * `/vendor-scans`, `/invoices`, `/events`). `visitor` and `contact` belong to Wave 2 surfaces
+ * and have no public read endpoint yet.
+ */
+export type ObjectType = "vendor" | "vendor_credential" | "facility" | "company" | "vendor_scan" | "invoice" | "event" | "visitor" | "contact";
+export interface SurfaceDef {
+    readonly id: string;
+    readonly portal: Portal | null;
+    readonly kind: SurfaceKind;
+    readonly objectType: ObjectType | null;
+    /**
+     * Expo Router path of the screen the surface lives on. For a surface with no portal, `[portal]`
+     * stands for the viewer's current portal: `settings` is `/company/apps/42/settings` for a
+     * company user.
+     */
+    readonly route: string;
+    /**
+     * Search param the screen reads the record id from. `null` when the surface has no record, or
+     * when the screen decodes its id from something else (the invoice screens take a JSON
+     * `params` value) and the host has to map it itself.
+     */
+    readonly idParam: string | null;
+    /** Wave 1 surfaces are rendered by the host; Wave 2 ids are reserved and accepted in manifests. */
+    readonly wave: 1 | 2;
+}
+/**
+ * Host URL segment reserved for app pages: `/{portal}/apps/{appId}/pages{path}`. No host route may
+ * be defined under it except the screens that render app pages, so an app path can never shadow a
+ * host page. It is not reserved inside an app's own space: `/pages/foo` is an ordinary app path.
+ */
+export declare const APP_PAGES_SEGMENT = "pages";
+/**
+ * The host pathname of an app page: `/{portal}/apps/{appId}/pages{path}`, with the root path `/`
+ * at `/{portal}/apps/{appId}/pages`. Throws unless `appId` is a positive integer and `path` is a
+ * concrete route path (`isConcreteRoutePath`), so no input can resolve outside the app's own pages
+ * (`/../settings`, `//evil.example`).
+ */
+export declare function appPagePathname(portal: Portal, appId: number, path: string): string;
+export declare const SURFACES: readonly SurfaceDef[];
+/**
+ * A surface identifier. This is deliberately a plain `string`: the catalog is data-driven, so the
+ * compiler cannot tell a real id from a typo. Validity is a runtime property — check untrusted or
+ * hand-written ids with {@link isSurfaceId}, as `isRouteDescriptor` and the manifest schema do.
+ */
+export type SurfaceId = string;
+export declare function isSurfaceId(value: unknown): value is SurfaceId;
+export declare function getSurface(id: string): SurfaceDef | undefined;
+/** The fallback surface a portal resolves to when an app has no view for the exact surface. */
+export declare function drawerDefaultFor(portal: Portal): SurfaceId;
+/**
+ * Surfaces the host renders for a portal in the given wave (and earlier waves). Portal-less
+ * surfaces (`settings`, `page`) are never included: they belong to an app, not to a portal screen.
+ */
+export declare function surfacesForPortal(portal: Portal, wave?: 1 | 2): SurfaceDef[];
+//# sourceMappingURL=surfaces.d.ts.map

package/dist/esm/apps/surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../../../src/apps/surfaces.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElE,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,gBAAgB,GAChB,UAAU,GACV,MAAM,GACN,iBAAiB,GACjB,QAAQ,GACR,aAAa,GACb,UAAU;AACZ,sFAAsF;GACpF,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GACpB,QAAQ,GAAG,mBAAmB,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAExH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQnF;AA8ED,eAAO,MAAM,QAAQ,EAAE,SAAS,UAAU,EAWxC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAI/B,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE7D;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,CAAC,GAAG,CAAK,GAAG,UAAU,EAAE,CAE/E"}

package/dist/esm/apps/surfaces.js

@@ -0,0 +1,125 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md. Host (web-mobile-client) and SDK both import from here.
+ */
+import { isConcreteRoutePath } from "./routes.js";
+/**
+ * Host URL segment reserved for app pages: `/{portal}/apps/{appId}/pages{path}`. No host route may
+ * be defined under it except the screens that render app pages, so an app path can never shadow a
+ * host page. It is not reserved inside an app's own space: `/pages/foo` is an ordinary app path.
+ */
+export const APP_PAGES_SEGMENT = "pages";
+/**
+ * The host pathname of an app page: `/{portal}/apps/{appId}/pages{path}`, with the root path `/`
+ * at `/{portal}/apps/{appId}/pages`. Throws unless `appId` is a positive integer and `path` is a
+ * concrete route path (`isConcreteRoutePath`), so no input can resolve outside the app's own pages
+ * (`/../settings`, `//evil.example`).
+ */
+export function appPagePathname(portal, appId, path) {
+    if (!Number.isSafeInteger(appId) || appId <= 0) {
+        throw new RangeError(`appPagePathname: app id must be a positive integer, got ${String(appId)}`);
+    }
+    if (!isConcreteRoutePath(path)) {
+        throw new RangeError(`appPagePathname: not a concrete route path: ${JSON.stringify(path)}`);
+    }
+    return `/${portal}/apps/${appId}/${APP_PAGES_SEGMENT}${path === "/" ? "" : path}`;
+}
+/** Expands a list surface into the surface itself and its row-action surface. */
+function list(portal, entity, objectType, route) {
+    return [
+        [`gs.${portal}.${entity}.list`, "list", null, route, null],
+        [`gs.${portal}.${entity}.list.row_action`, "list.row_action", objectType, route, null],
+    ];
+}
+function portalShell(portal) {
+    return [
+        [`gs.${portal}.navigation`, "navigation", null, `/${portal}`, null],
+        [`gs.${portal}.drawer.default`, "drawer.default", null, `/${portal}`, null],
+        [`gs.${portal}.dashboard.overview`, "overview", null, `/${portal}/dashboard`, null],
+    ];
+}
+const COMPANY = [
+    ...portalShell("company"),
+    ...list("company", "vendor", "vendor", "/company/vendors"),
+    ["gs.company.vendor.detail", "detail", "vendor", "/company/vendordetails", "vendorId"],
+    ["gs.company.vendor.detail.tabs", "detail.tabs", "vendor", "/company/vendordetails", "vendorId"],
+    ...list("company", "vendor_credential", "vendor_credential", "/company/credentials"),
+    ["gs.company.vendor_credential.detail", "detail", "vendor_credential", "/company/credentials/[id]", "id"],
+    ...list("company", "facility", "facility", "/company/facilities"),
+    ["gs.company.facility.detail", "detail", "facility", "/company/facilities/details", "id"],
+    ...list("company", "vendor_scan", "vendor_scan", "/company/scans"),
+    ["gs.company.vendor_scan.detail", "detail", "vendor_scan", "/company/scans/details", "id"],
+    ...list("company", "invoice", "invoice", "/company/invoices"),
+    ["gs.company.invoice.detail", "detail", "invoice", "/company/invoices/invoicedetails", null],
+    ["gs.company.account.overview", "overview", "company", "/company/account", null],
+    ["gs.company.account.detail.tabs", "detail.tabs", "company", "/company/account", null],
+];
+const VENDOR = [
+    ...portalShell("vendor"),
+    ...list("vendor", "vendor_credential", "vendor_credential", "/vendor/credentials"),
+    ["gs.vendor.vendor_credential.detail", "detail", "vendor_credential", "/vendor/credentials/[id]", "id"],
+    ...list("vendor", "facility", "facility", "/vendor/facilities"),
+    ["gs.vendor.facility.detail", "detail", "facility", "/vendor/facilities/details", "facilityId"],
+    ...list("vendor", "event", "event", "/vendor/calendar"),
+    ...list("vendor", "invoice", "invoice", "/vendor/account/invoices"),
+    ["gs.vendor.invoice.detail", "detail", "invoice", "/vendor/account/invoicedetails", null],
+    ["gs.vendor.account.overview", "overview", "vendor", "/vendor/account", null],
+    ["gs.vendor.account.detail.tabs", "detail.tabs", "vendor", "/vendor/account", null],
+    ["gs.vendor.checkin.overview", "overview", null, "/vendor/mobilecheckin", null],
+];
+/** Facility and system portals share one screen set; both are reserved for Wave 2. */
+function staffPortal(portal) {
+    return [
+        ...portalShell(portal),
+        ...list(portal, "company", "company", `/${portal}/companies`),
+        [`gs.${portal}.company.detail`, "detail", "company", `/${portal}/companies/[id]`, "id"],
+        ...list(portal, "vendor", "vendor", `/${portal}/vendors`),
+        ...list(portal, "visitor", "visitor", `/${portal}/visitors`),
+        ...list(portal, "contact", "contact", `/${portal}/contacts`),
+        ...list(portal, "vendor_credential", "vendor_credential", `/${portal}/credentials`),
+        ...list(portal, "event", "event", `/${portal}/calendar`),
+        [`gs.${portal}.report.overview`, "overview", null, `/${portal}/reports`, null],
+    ];
+}
+function define(portal, wave, entries) {
+    return entries.map(([id, kind, objectType, route, idParam]) => ({
+        id,
+        portal,
+        kind,
+        objectType,
+        route,
+        idParam,
+        wave,
+    }));
+}
+export const SURFACES = Object.freeze([
+    ...define("company", 1, COMPANY),
+    ...define("vendor", 1, VENDOR),
+    ...define("facility", 2, staffPortal("facility")),
+    ...define("system", 2, staffPortal("system")),
+    // The app's own settings page. Every portal has one, so the route names the portal as a segment.
+    ...define(null, 1, [["settings", "settings", null, "/[portal]/apps/[appId]/settings", "appId"]]),
+    // Every app page (`ui_extensions.routes`), under the one prefix reserved for apps. Like
+    // `settings` it has no portal of its own, and it is not a view viewport or a `surface` target:
+    // apps declare pages as routes and reach them with `{ type: "appPage" }`.
+    ...define(null, 1, [["page", "page", null, `/[portal]/apps/[appId]/${APP_PAGES_SEGMENT}/[...path]`, "appId"]]),
+]);
+const SURFACES_BY_ID = new Map(SURFACES.map((s) => [s.id, s]));
+export function isSurfaceId(value) {
+    return typeof value === "string" && SURFACES_BY_ID.has(value);
+}
+export function getSurface(id) {
+    return SURFACES_BY_ID.get(id);
+}
+/** The fallback surface a portal resolves to when an app has no view for the exact surface. */
+export function drawerDefaultFor(portal) {
+    return `gs.${portal}.drawer.default`;
+}
+/**
+ * Surfaces the host renders for a portal in the given wave (and earlier waves). Portal-less
+ * surfaces (`settings`, `page`) are never included: they belong to an app, not to a portal screen.
+ */
+export function surfacesForPortal(portal, wave = 1) {
+    return SURFACES.filter((s) => s.portal === portal && s.wave <= wave);
+}
+//# sourceMappingURL=surfaces.js.map

package/dist/esm/apps/surfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.js","sourceRoot":"","sources":["../../../src/apps/surfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA8ClD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAAa,EAAE,IAAY;IACzE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,2DAA2D,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,+CAA+C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,IAAI,MAAM,SAAS,KAAK,IAAI,iBAAiB,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACpF,CAAC;AAID,iFAAiF;AACjF,SAAS,IAAI,CAAC,MAAc,EAAE,MAAc,EAAE,UAAsB,EAAE,KAAa;IACjF,OAAO;QACL,CAAC,MAAM,MAAM,IAAI,MAAM,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC;QAC1D,CAAC,MAAM,MAAM,IAAI,MAAM,kBAAkB,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC;KACvF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO;QACL,CAAC,MAAM,MAAM,aAAa,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC;QACnE,CAAC,MAAM,MAAM,iBAAiB,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC;QAC3E,CAAC,MAAM,MAAM,qBAAqB,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,MAAM,YAAY,EAAE,IAAI,CAAC;KACpF,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,GAAY;IACvB,GAAG,WAAW,CAAC,SAAS,CAAC;IACzB,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,CAAC;IAC1D,CAAC,0BAA0B,EAAE,QAAQ,EAAE,QAAQ,EAAE,wBAAwB,EAAE,UAAU,CAAC;IACtF,CAAC,+BAA+B,EAAE,aAAa,EAAE,QAAQ,EAAE,wBAAwB,EAAE,UAAU,CAAC;IAChG,GAAG,IAAI,CAAC,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,sBAAsB,CAAC;IACpF,CAAC,qCAAqC,EAAE,QAAQ,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,IAAI,CAAC;IACzG,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,CAAC;IACjE,CAAC,4BAA4B,EAAE,QAAQ,EAAE,UAAU,EAAE,6BAA6B,EAAE,IAAI,CAAC;IACzF,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,CAAC;IAClE,CAAC,+BAA+B,EAAE,QAAQ,EAAE,aAAa,EAAE,wBAAwB,EAAE,IAAI,CAAC;IAC1F,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,mBAAmB,CAAC;IAC7D,CAAC,2BAA2B,EAAE,QAAQ,EAAE,SAAS,EAAE,kCAAkC,EAAE,IAAI,CAAC;IAC5F,CAAC,6BAA6B,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,IAAI,CAAC;IAChF,CAAC,gCAAgC,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,IAAI,CAAC;CACvF,CAAC;AAEF,MAAM,MAAM,GAAY;IACtB,GAAG,WAAW,CAAC,QAAQ,CAAC;IACxB,GAAG,IAAI,CAAC,QAAQ,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,qBAAqB,CAAC;IAClF,CAAC,oCAAoC,EAAE,QAAQ,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,IAAI,CAAC;IACvG,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,CAAC;IAC/D,CAAC,2BAA2B,EAAE,QAAQ,EAAE,UAAU,EAAE,4BAA4B,EAAE,YAAY,CAAC;IAC/F,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,CAAC;IACvD,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,0BAA0B,CAAC;IACnE,CAAC,0BAA0B,EAAE,QAAQ,EAAE,SAAS,EAAE,gCAAgC,EAAE,IAAI,CAAC;IACzF,CAAC,4BAA4B,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC;IAC7E,CAAC,+BAA+B,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC;IACnF,CAAC,4BAA4B,EAAE,UAAU,EAAE,IAAI,EAAE,uBAAuB,EAAE,IAAI,CAAC;CAChF,CAAC;AAEF,sFAAsF;AACtF,SAAS,WAAW,CAAC,MAA6B;IAChD,OAAO;QACL,GAAG,WAAW,CAAC,MAAM,CAAC;QACtB,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,MAAM,YAAY,CAAC;QAC7D,CAAC,MAAM,MAAM,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,MAAM,iBAAiB,EAAE,IAAI,CAAC;QACvF,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,MAAM,UAAU,CAAC;QACzD,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,MAAM,WAAW,CAAC;QAC5D,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,MAAM,WAAW,CAAC;QAC5D,GAAG,IAAI,CAAC,MAAM,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,IAAI,MAAM,cAAc,CAAC;QACnF,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,MAAM,WAAW,CAAC;QACxD,CAAC,MAAM,MAAM,kBAAkB,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,MAAM,UAAU,EAAE,IAAI,CAAC;KAC/E,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,MAAqB,EAAE,IAAW,EAAE,OAAgB;IAClE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9D,EAAE;QACF,MAAM;QACN,IAAI;QACJ,UAAU;QACV,KAAK;QACL,OAAO;QACP,IAAI;KACL,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAA0B,MAAM,CAAC,MAAM,CAAC;IAC3D,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC;IAChC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,MAAM,CAAC;IAC9B,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACjD,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7C,iGAAiG;IACjG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,iCAAiC,EAAE,OAAO,CAAC,CAAC,CAAC;IAChG,wFAAwF;IACxF,+FAA+F;IAC/F,0EAA0E;IAC1E,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,iBAAiB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/G,CAAC,CAAC;AASH,MAAM,cAAc,GAAoC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhG,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,MAAM,MAAM,iBAAiB,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,OAAc,CAAC;IAC/D,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;AACvE,CAAC"}

package/dist/esm/apps/testing/index.d.ts

@@ -0,0 +1,136 @@
+import { RemoteReceiver, type RemoteReceiverElement, type RemoteReceiverNode } from "@remote-dom/core/receivers";
+import type { ReactElement } from "react";
+import { type ComponentName } from "../components.js";
+import { type AppTokens, type ExtensionContext, type PageRoute } from "../context.js";
+import type { HostApi } from "../protocol.js";
+import { REMOTE_FRAGMENT_TAG } from "../runtime/elements.js";
+import { type SandboxRuntime } from "../runtime/sandbox.js";
+export type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+export declare function mockTokens(now?: number): AppTokens;
+/**
+ * A complete, valid `ExtensionContext` with `overrides` deep-merged in (arrays are replaced).
+ *
+ * `app.permissions` defaults to `[]`; set it to your manifest's permissions, platform ones
+ * included, e.g. `{ app: { permissions: ["vendors.view", "app_secrets.write"] } }`. Leave
+ * platform permissions such as `app_secrets.write` out of `auth.user.scope`: the server grants
+ * them to the app's role only, so a real user token never carries them. The mock performs no
+ * permission checks; stub the Secret Store's 403 yourself to test a missing grant.
+ *
+ * `environment.navParams` (what this app's own `navigate` passed as `envParams`) and
+ * `environment.queryParams` (an app page's URL query) both default to `{}`; set either to test a
+ * view opened by a navigation or from a link. Setting `environment.route` puts the view on an app
+ * page (see {@link mockPageRoute}).
+ */
+export declare function getMockContext(overrides?: DeepPartial<ExtensionContext>): ExtensionContext;
+/**
+ * The `environment.route` the host sends for `pathname` on the declared route `path`, with its
+ * params decoded the way the host does it (`matchAppRoute`). `pathname` defaults to `path`, so a
+ * route without params needs only one argument. Throws when `pathname` does not match `path`:
+ * the host would never render that page.
+ *
+ * ```ts
+ * mockPageRoute("/reports/:id", "/reports/7"); // { path: "/reports/:id", pathname: "/reports/7", params: { id: "7" } }
+ * ```
+ */
+export declare function mockPageRoute(path: string, pathname?: string): PageRoute;
+export interface HostCall {
+    method: keyof HostApi;
+    args: unknown[];
+}
+export type MockHost = HostApi & {
+    /** Every call, in order. */
+    readonly calls: HostCall[];
+    /** Calls to one method. */
+    callsTo(method: keyof HostApi): unknown[][];
+};
+/**
+ * A `HostApi` that records calls. Unimplemented methods resolve to sensible defaults
+ * (`refreshTokens` returns fresh mock tokens, `openExternalUrl` resolves `false`).
+ */
+export declare function createMockHost(overrides?: Partial<HostApi>): MockHost;
+/** A JSON-friendly snapshot of the rendered tree; text nodes are strings. */
+export interface TestSnapshot {
+    type: ComponentName | typeof REMOTE_FRAGMENT_TAG | string;
+    props: Record<string, unknown>;
+    events: string[];
+    slot?: string;
+    children: Array<TestSnapshot | string>;
+}
+export type ElementPredicate = (element: TestElement) => boolean;
+/** A live view of one rendered element: reads always reflect the latest host-side state. */
+export declare class TestElement {
+    #private;
+    /** @internal */
+    constructor(harness: Harness, id: string);
+    get node(): RemoteReceiverElement;
+    get tag(): string;
+    /** Catalog component name, e.g. `"Button"`; undefined for `remote-fragment`. */
+    get component(): ComponentName | undefined;
+    get props(): Readonly<Record<string, unknown>>;
+    get attributes(): Readonly<Record<string, string>>;
+    /** Name of the slot this element fills, if any. */
+    get slot(): string | undefined;
+    /** Event names the app is listening to (`press`, `change`, `shownchange`, ...). */
+    get events(): string[];
+    get children(): Array<TestElement | string>;
+    /** Concatenated text of this element and its descendants. */
+    get text(): string;
+    /** Elements placed in slot `name` (the children of its `remote-fragment`). */
+    slotted(name: string): TestElement[];
+    find(component: ComponentName | string, predicate?: ElementPredicate): TestElement | undefined;
+    findAll(component: ComponentName | string, predicate?: ElementPredicate): TestElement[];
+    /**
+     * Calls the listener the host would call for `prop` (a catalog event prop such as `onPress`,
+     * or a raw event name such as `press`) with `detail`, then waits for the resulting render.
+     * Resolves with the handler's return value, as the host would receive it.
+     */
+    trigger(prop: string, detail?: unknown): Promise<unknown>;
+    toJSON(): TestSnapshot;
+}
+declare class Harness {
+    readonly receiver: RemoteReceiver;
+    mutations: number;
+    collect(nodes: readonly RemoteReceiverNode[], component: string, predicate?: ElementPredicate): TestElement[];
+    snapshot(node: RemoteReceiverElement): TestSnapshot;
+    /** Waits until React and the mutation batch have gone quiet. */
+    settle(): Promise<void>;
+}
+export interface RenderForTestOptions {
+    /** Overrides merged into `getMockContext()`, or a complete context. */
+    context?: DeepPartial<ExtensionContext>;
+    /** Host method overrides; every call is recorded on `result.host.calls`. */
+    host?: Partial<HostApi>;
+}
+export interface TestRender {
+    /** Top-level rendered elements (normally one ContextView or SettingsView). */
+    readonly roots: TestElement[];
+    /** The first top-level element. */
+    readonly root: TestElement;
+    readonly host: MockHost;
+    /** The context the view currently sees. */
+    readonly context: ExtensionContext;
+    /** Errors thrown by the view or by host calls after mounting. */
+    readonly errors: unknown[];
+    readonly receiver: RemoteReceiver;
+    /** The runtime under test; call its `SandboxExports` methods directly if needed. */
+    readonly runtime: SandboxRuntime;
+    readonly mountId: string;
+    find(component: ComponentName | string, predicate?: ElementPredicate): TestElement | undefined;
+    findAll(component: ComponentName | string, predicate?: ElementPredicate): TestElement[];
+    /** Text of the whole tree. */
+    text(): string;
+    toJSON(): TestSnapshot[];
+    /** Pushes a context patch through `SandboxExports.updateContext`, then settles. */
+    updateContext(patch: Partial<ExtensionContext>): Promise<void>;
+    unmount(): Promise<void>;
+    settle(): Promise<void>;
+}
+/**
+ * Mounts `element` through the real runtime (`SandboxExports.mount`) against an in-process
+ * `RemoteReceiver`, so what a test sees is exactly what a host would receive.
+ */
+export declare function renderForTest(element: ReactElement, options?: RenderForTestOptions): Promise<TestRender>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/apps/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/apps/testing/index.ts"],"names":[],"mappings":"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"}