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

package/src/apps/routes.ts

@@ -0,0 +1,230 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/fullpageview-plan.md.
+ *
+ * App page routes (`ui_extensions.routes[]`): the path grammar, the uniqueness rule and the one
+ * matcher every consumer shares (the host, `apps-cli validate`, the contract tests). Deliberately
+ * dependency-free (no zod) so the host renderer can import it without bundling zod; `manifest.ts`
+ * re-exports it because it is part of the manifest contract.
+ *
+ * The server mirrors the grammar and `normalizeRoutePath` in Ruby and reads the same fixtures
+ * (`src/__tests__/apps/fixtures/routes.json`).
+ */
+
+/** A static segment: lower-case letters, digits and inner hyphens. */
+const STATIC_SEGMENT = "[a-z0-9](?:[a-z0-9-]*[a-z0-9])?";
+/** A param segment: `:` and a lower-case name. */
+const PARAM_SEGMENT = ":[a-z][a-z0-9_]*";
+
+/**
+ * A declared route path: `/`, or `/seg(/seg)*` where each segment is static or a `:param`. No dots,
+ * percent-escapes, upper case, empty segments or trailing slash, so no path can climb out of the
+ * app's own space. `pages` is not reserved inside that space: `/pages/foo` is an ordinary path.
+ */
+export const ROUTE_PATH_PATTERN =
+  "^/(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*)(?:/(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*))*)?$";
+
+/** A concrete path an app navigates to (`{ type: "appPage" }`): the same grammar without params. */
+export const CONCRETE_ROUTE_PATH_PATTERN = `^/(?:${STATIC_SEGMENT}(?:/${STATIC_SEGMENT})*)?$`;
+
+export const ROUTE_PATH_MAX_CHARS = 200;
+/** Segments in one path; `/` has none. */
+export const ROUTE_PATH_MAX_SEGMENTS = 8;
+/** Routes in one manifest. */
+export const APP_ROUTES_MAX = 50;
+
+/** What every param segment becomes in {@link normalizeRoutePath}. */
+const PARAM_PLACEHOLDER = ":_";
+
+const ROUTE_PATH_RE = new RegExp(ROUTE_PATH_PATTERN);
+const CONCRETE_ROUTE_PATH_RE = new RegExp(CONCRETE_ROUTE_PATH_PATTERN);
+const PARAM_SEGMENT_RE = new RegExp(`^${PARAM_SEGMENT}$`);
+
+/** The segments of a path in the grammar; `/` has none. */
+function segmentsOf(path: string): string[] {
+  return path === "/" ? [] : path.slice(1).split("/");
+}
+
+function withinLimits(path: string): boolean {
+  return path.length <= ROUTE_PATH_MAX_CHARS && segmentsOf(path).length <= ROUTE_PATH_MAX_SEGMENTS;
+}
+
+/** A declared route path: the {@link ROUTE_PATH_PATTERN} grammar, ≤ 200 characters and ≤ 8 segments. */
+export function isRoutePath(value: unknown): value is string {
+  return typeof value === "string" && ROUTE_PATH_RE.test(value) && withinLimits(value);
+}
+
+/** A concrete route path (no `:param` segments) within the same limits as a declared one. */
+export function isConcreteRoutePath(value: unknown): value is string {
+  return typeof value === "string" && CONCRETE_ROUTE_PATH_RE.test(value) && withinLimits(value);
+}
+
+/**
+ * Renames every param segment to `:_`. Two paths that normalize to the same string claim the same
+ * URLs (`/vendors/:id` and `/vendors/:vendor_id`), so a manifest may declare only one of them.
+ */
+export function normalizeRoutePath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => (segment.startsWith(":") ? PARAM_PLACEHOLDER : segment))
+    .join("/");
+}
+
+export interface RouteSetIssue {
+  /** Index of the offending entry in `routes`. */
+  index: number;
+  field: "path" | "portals" | "navigation";
+  message: string;
+}
+
+/**
+ * The rules over a set of routes that a pattern alone cannot express: the segment cap, a param
+ * name used twice in one path, two paths claiming the same URLs, and a repeated portal. Grammar,
+ * length and the per-field limits are the schema's job; a path that fails the grammar is skipped
+ * here. The zod schema and `apps-cli validate` both report these, and the server repeats them.
+ */
+export function routeSetIssues(
+  routes: ReadonlyArray<{ path: string; portals?: readonly string[] | undefined; navigation?: unknown }>,
+): RouteSetIssue[] {
+  const issues: RouteSetIssue[] = [];
+  const claimed = new Map<string, string>();
+
+  routes.forEach((route, index) => {
+    const portals = route.portals ?? [];
+    if (new Set(portals).size !== portals.length) {
+      issues.push({ index, field: "portals", message: "portals must not repeat" });
+    }
+
+    if (!ROUTE_PATH_RE.test(route.path)) return;
+
+    const segments = segmentsOf(route.path);
+    if (segments.length > ROUTE_PATH_MAX_SEGMENTS) {
+      issues.push({
+        index,
+        field: "path",
+        message: `${route.path} has ${segments.length} segments; the limit is ${ROUTE_PATH_MAX_SEGMENTS}`,
+      });
+    }
+
+    const params = segments.filter((s) => s.startsWith(":"));
+    if (new Set(params).size !== params.length) {
+      issues.push({ index, field: "path", message: `${route.path} uses a param name twice` });
+    }
+    // A sidebar entry links to one fixed address, and a path with params has none.
+    if (params.length > 0 && route.navigation !== undefined) {
+      issues.push({
+        index,
+        field: "navigation",
+        message: `${route.path} has params, so it cannot have a navigation entry; add one to a path without params`,
+      });
+    }
+
+    const normalized = normalizeRoutePath(route.path);
+    const earlier = claimed.get(normalized);
+    if (earlier === undefined) {
+      claimed.set(normalized, route.path);
+    } else {
+      issues.push({
+        index,
+        field: "path",
+        message: `${route.path} is declared twice (as ${earlier}); each path takes one page`,
+      });
+    }
+  });
+
+  return issues;
+}
+
+export interface AppRouteMatch<R> {
+  route: R;
+  /** Param values by name, percent-decoded. Always strings: the app parses ids itself. */
+  params: Record<string, string>;
+  /** Index of `route` in the list passed to {@link matchAppRoute}. */
+  index: number;
+}
+
+/**
+ * Decodes one pathname segment into a param value, or returns `null` when it cannot be one: a
+ * malformed escape, an empty value, `.` or `..`, or a value containing `/` or `:` (raw or
+ * encoded). A param therefore never carries a path or a host-looking value into the app.
+ */
+function paramValue(segment: string): string | null {
+  if (segment.includes(":")) return null;
+  let value: string;
+  try {
+    value = decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+  if (value === "" || value === "." || value === ".." || value.includes("/") || value.includes(":")) return null;
+  return value;
+}
+
+/**
+ * Finds the route a pathname in the app's own space renders (`/reports/7` for
+ * `/{portal}/apps/{appId}/pages/reports/7`), or `null` when none does.
+ *
+ * `pathname` is URL-encoded, as it appears in a URL: `/` or `/seg(/seg)*` with no empty segment,
+ * trailing slash, query or fragment (anything else matches nothing). A host that receives decoded
+ * segments encodes each with `encodeURIComponent` before joining them.
+ *
+ * A static route segment matches only the identical pathname segment. A param segment matches any
+ * other segment that decodes to a plain value (see `paramValue`); a segment containing `:` never
+ * matches a param. When several routes match, the one with a static segment at the first position
+ * where they differ wins (static before param, left to right); among equals, the first declared.
+ * Routes whose path is not in the grammar are ignored, so a stale or hand-edited feed entry can
+ * never match.
+ */
+export function matchAppRoute<R extends { path: string }>(
+  routes: readonly R[],
+  pathname: string,
+): AppRouteMatch<R> | null {
+  if (!pathname.startsWith("/") || /[?#]/.test(pathname)) return null;
+  const segments = segmentsOf(pathname);
+  if (segments.some((s) => s === "")) return null;
+
+  let best: { match: AppRouteMatch<R>; rank: boolean[] } | null = null;
+
+  for (const [index, route] of routes.entries()) {
+    const candidate = matchOne(route, index, segments);
+    if (candidate !== null && (best === null || outranks(candidate.rank, best.rank))) best = candidate;
+  }
+
+  return best === null ? null : best.match;
+}
+
+/** Matches one route against the pathname's segments, with its static/param rank. */
+function matchOne<R extends { path: string }>(
+  route: R,
+  index: number,
+  segments: readonly string[],
+): { match: AppRouteMatch<R>; rank: boolean[] } | null {
+  if (!isRoutePath(route.path)) return null;
+  const pattern = segmentsOf(route.path);
+  if (pattern.length !== segments.length) return null;
+
+  const params: Record<string, string> = {};
+  const rank: boolean[] = [];
+  for (let i = 0; i < pattern.length; i++) {
+    const expected = pattern[i] ?? "";
+    const actual = segments[i] ?? "";
+    if (PARAM_SEGMENT_RE.test(expected)) {
+      const value = paramValue(actual);
+      if (value === null) return null;
+      params[expected.slice(1)] = value;
+      rank.push(false);
+    } else {
+      if (expected !== actual) return null;
+      rank.push(true);
+    }
+  }
+  return { match: { route, params, index }, rank };
+}
+
+/** Whether `a` has a static segment at the first position where it and `b` differ. */
+function outranks(a: readonly boolean[], b: readonly boolean[]): boolean {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return a[i] === true;
+  }
+  return false;
+}

package/src/apps/surfaces.ts

@@ -2,6 +2,7 @@
  * 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";
 
 export type Portal = "vendor" | "company" | "facility" | "system";
 
@@ -13,7 +14,9 @@ export type SurfaceKind =
   | "list.row_action"
   | "detail"
   | "detail.tabs"
-  | "settings";
+  | "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
@@ -22,15 +25,7 @@ export type SurfaceKind =
  * and have no public read endpoint yet.
  */
 export type ObjectType =
-  | "vendor"
-  | "vendor_credential"
-  | "facility"
-  | "company"
-  | "vendor_scan"
-  | "invoice"
-  | "event"
-  | "visitor"
-  | "contact";
+  "vendor" | "vendor_credential" | "facility" | "company" | "vendor_scan" | "invoice" | "event" | "visitor" | "contact";
 
 export interface SurfaceDef {
   readonly id: string;
@@ -53,6 +48,29 @@ export interface SurfaceDef {
   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 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: Portal, appId: number, path: string): string {
+  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}`;
+}
+
 type Entry = [id: string, kind: SurfaceKind, objectType: ObjectType | null, route: string, idParam: string | null];
 
 /** Expands a list surface into the surface itself and its row-action surface. */
@@ -118,7 +136,15 @@ function staffPortal(portal: "facility" | "system"): Entry[] {
 }
 
 function define(portal: Portal | null, wave: 1 | 2, entries: Entry[]): SurfaceDef[] {
-  return entries.map(([id, kind, objectType, route, idParam]) => ({ id, portal, kind, objectType, route, idParam, wave }));
+  return entries.map(([id, kind, objectType, route, idParam]) => ({
+    id,
+    portal,
+    kind,
+    objectType,
+    route,
+    idParam,
+    wave,
+  }));
 }
 
 export const SURFACES: readonly SurfaceDef[] = Object.freeze([
@@ -128,6 +154,10 @@ export const SURFACES: readonly SurfaceDef[] = Object.freeze([
   ...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"]]),
 ]);
 
 /**
@@ -152,7 +182,10 @@ export function drawerDefaultFor(portal: Portal): SurfaceId {
   return `gs.${portal}.drawer.default`;
 }
 
-/** Surfaces the host renders for a portal in the given wave (and earlier waves). */
+/**
+ * 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: Portal, wave: 1 | 2 = 1): SurfaceDef[] {
   return SURFACES.filter((s) => s.portal === portal && s.wave <= wave);
 }

package/src/apps/testing/index.ts

@@ -13,15 +13,24 @@
  * await view.find("Button")!.trigger("onPress");
  * expect(view.find("FocusView")!.props["shown"]).toBe(true);
  * ```
+ *
+ * An app page gets its route through the context:
+ *
+ * ```ts
+ * const page = await renderForTest(<ReportDetail />, {
+ *   context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+ * });
+ * ```
  */
 
 import { polyfillInstalled } from "../runtime/polyfill.js";
 import { RemoteReceiver, type RemoteReceiverElement, type RemoteReceiverNode, type RemoteReceiverRoot } from "@remote-dom/core/receivers";
 import type { ReactElement } from "react";
 import { COMPONENTS, type ComponentName, type ComponentSpec } from "../components.js";
-import { PROTOCOL_VERSION, type AppTokens, type ExtensionContext } from "../context.js";
+import { PROTOCOL_VERSION, type AppTokens, type ExtensionContext, type PageRoute } from "../context.js";
 import type { HostApi, RemoteConnection, RemoteMutationRecord } from "../protocol.js";
 import { REMOTE_FRAGMENT_TAG } from "../runtime/elements.js";
+import { matchAppRoute } from "../routes.js";
 import { createSandboxExports, type SandboxRuntime } from "../runtime/sandbox.js";
 
 // Remote-dom node type constants (`NODE_TYPE_ELEMENT`, `NODE_TYPE_TEXT`).
@@ -54,8 +63,14 @@ export function mockTokens(now: number = Date.now()): AppTokens {
  * 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 function getMockContext(overrides: DeepPartial<ExtensionContext> = {}): ExtensionContext {
+  const route = overrides.environment?.route;
   const base: ExtensionContext = {
     protocolVersion: PROTOCOL_VERSION,
     app: { id: 1, version: "1.0.0", permissions: [], csp: { connectSrc: [], imageSrc: [] } },
@@ -65,12 +80,43 @@ export function getMockContext(overrides: DeepPartial<ExtensionContext> = {}): E
       portal: "company",
       platform: "web",
       queryParams: {},
+      navParams: {},
       constants: {},
       apiBaseUrl: "https://api.example.test/api",
     },
     auth: mockTokens(),
   };
-  return deepMerge(base, overrides) as ExtensionContext;
+  // An app page is rendered on the `page` surface; an explicit `surfaceId` still wins.
+  if (route !== undefined) base.environment.surfaceId = "page";
+  const merged = deepMerge(base, overrides) as ExtensionContext;
+  if (route !== undefined) merged.environment.route = completeRoute(route);
+  return merged;
+}
+
+/**
+ * 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 function mockPageRoute(path: string, pathname: string = path): PageRoute {
+  const match = matchAppRoute([{ path }], pathname);
+  if (!match) throw new Error(`${pathname} does not match the route ${path}`);
+  return { path, pathname, params: match.params };
+}
+
+/** Fills a partial `environment.route` override: a missing pathname is the path, missing params are `{}`. */
+function completeRoute(route: DeepPartial<PageRoute>): PageRoute {
+  const path = route.path ?? route.pathname ?? "/";
+  const params: Record<string, string> = {};
+  for (const [name, value] of Object.entries(route.params ?? {})) {
+    if (typeof value === "string") params[name] = value;
+  }
+  return { path, pathname: route.pathname ?? path, params };
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {

package/src/apps/ui/index.ts

@@ -13,9 +13,16 @@ import { createUiComponent, type UiProps } from "./factory.js";
 
 export type { UiProps } from "./factory.js";
 
-// View roots. A view component renders exactly one ContextView or SettingsView at its top.
+// View roots. A view component renders exactly one of these at its top: ContextView on a surface,
+// SettingsView on the settings page, PageView on an app page.
 export const ContextView = /* @__PURE__ */ createUiComponent("ContextView");
 export const SettingsView = /* @__PURE__ */ createUiComponent("SettingsView");
+/**
+ * An app page (`ui_extensions.routes`), full width inside the portal's own chrome. `title` is the
+ * page header; the `actions` slot joins the header's actions and `banner` sits above the body.
+ * Read the route's params with `usePageRoute()` from `apps/hooks`.
+ */
+export const PageView = /* @__PURE__ */ createUiComponent("PageView");
 
 const FocusViewElement = /* @__PURE__ */ createUiComponent("FocusView");
 
@@ -108,3 +115,13 @@ export const Radio = /* @__PURE__ */ createUiComponent("Radio");
 export const Switch = /* @__PURE__ */ createUiComponent("Switch");
 export const DateField = /* @__PURE__ */ createUiComponent("DateField");
 export const FormFieldGroup = /* @__PURE__ */ createUiComponent("FormFieldGroup");
+
+// Charts. Data only: pick a palette with `theme`; `onClick` receives a `ChartClickEvent`
+// (`index`, `label`, `value` and, on multi-series charts, `series`).
+export const BarChart = /* @__PURE__ */ createUiComponent("BarChart");
+export const HorizontalBarChart = /* @__PURE__ */ createUiComponent("HorizontalBarChart");
+export const StackedBarChart = /* @__PURE__ */ createUiComponent("StackedBarChart");
+export const LineChart = /* @__PURE__ */ createUiComponent("LineChart");
+export const AreaChart = /* @__PURE__ */ createUiComponent("AreaChart");
+export const ComboChart = /* @__PURE__ */ createUiComponent("ComboChart");
+export const PieChart = /* @__PURE__ */ createUiComponent("PieChart");

package/src/lib/config.ts

@@ -80,8 +80,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "0.45.0",
-  sdkVersion: "0.46.0-beta.10",
+  sdkVersion: "0.46.0-beta.11",
   genVersion: "2.943.0",
   userAgent:
-    "speakeasy-sdk/typescript 0.46.0-beta.10 2.943.0 0.45.0 @greensecurity/javascript-sdk",
+    "speakeasy-sdk/typescript 0.46.0-beta.11 2.943.0 0.45.0 @greensecurity/javascript-sdk",
 } as const;