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

package/src/apps/testing/index.ts

@@ -0,0 +1,421 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Import as `@greensecurity/javascript-sdk/apps/testing`. Works in Vitest and Jest with the
+ * plain Node environment: the remote-dom polyfill supplies the DOM the runtime needs.
+ *
+ * ```ts
+ * const view = await renderForTest(<VendorPanel />, {
+ *   context: { environment: { objectContext: { object: "vendor", id: 42 } } },
+ * });
+ * expect(view.find("Text", (t) => t.text.includes("42"))).toBeDefined();
+ * await view.find("Button")!.trigger("onPress");
+ * expect(view.find("FocusView")!.props["shown"]).toBe(true);
+ * ```
+ */
+
+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 type { HostApi, RemoteConnection, RemoteMutationRecord } from "../protocol.js";
+import { REMOTE_FRAGMENT_TAG } from "../runtime/elements.js";
+import { createSandboxExports, type SandboxRuntime } from "../runtime/sandbox.js";
+
+// Remote-dom node type constants (`NODE_TYPE_ELEMENT`, `NODE_TYPE_TEXT`).
+const NODE_TYPE_ELEMENT = 1;
+const NODE_TYPE_TEXT = 3;
+
+// ---------------------------------------------------------------------------------------------
+// Mock context and host
+
+export type DeepPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
+const FIFTEEN_MINUTES = 15 * 60_000;
+
+export function mockTokens(now: number = Date.now()): AppTokens {
+  return {
+    user: { accessToken: "gsu_test_user_token", expiresAt: now + FIFTEEN_MINUTES, scope: [] },
+    installation: { accessToken: "gsi_test_installation_token", expiresAt: now + FIFTEEN_MINUTES, activationId: 1 },
+  };
+}
+
+/**
+ * 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.
+ */
+export function getMockContext(overrides: DeepPartial<ExtensionContext> = {}): ExtensionContext {
+  const base: ExtensionContext = {
+    protocolVersion: PROTOCOL_VERSION,
+    app: { id: 1, version: "1.0.0", permissions: [], csp: { connectSrc: [], imageSrc: [] } },
+    user: { id: 1, name: "Test User", userType: "company_manager", locale: "en-US", companyId: 1 },
+    environment: {
+      surfaceId: "gs.company.drawer.default",
+      portal: "company",
+      platform: "web",
+      queryParams: {},
+      constants: {},
+      apiBaseUrl: "https://api.example.test/api",
+    },
+    auth: mockTokens(),
+  };
+  return deepMerge(base, overrides) as ExtensionContext;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+
+function deepMerge(base: unknown, patch: unknown): unknown {
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch === undefined ? base : patch;
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue;
+    out[key] = deepMerge(base[key], value);
+  }
+  return out;
+}
+
+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 function createMockHost(overrides: Partial<HostApi> = {}): MockHost {
+  const calls: HostCall[] = [];
+  const defaults: HostApi = {
+    refreshTokens: async () => mockTokens(),
+    navigate: async () => undefined,
+    openExternalUrl: async () => false,
+    showToast: async () => undefined,
+    refreshHostData: async () => undefined,
+    clipboardWriteText: async () => undefined,
+    closeView: async () => undefined,
+  };
+  const impl: HostApi = { ...defaults, ...overrides };
+
+  const record = <M extends keyof HostApi>(method: M) =>
+    ((...args: unknown[]) => {
+      calls.push({ method, args });
+      return (impl[method] as (...a: unknown[]) => Promise<unknown>)(...args);
+    }) as HostApi[M];
+
+  return {
+    refreshTokens: record("refreshTokens"),
+    navigate: record("navigate"),
+    openExternalUrl: record("openExternalUrl"),
+    showToast: record("showToast"),
+    refreshHostData: record("refreshHostData"),
+    clipboardWriteText: record("clipboardWriteText"),
+    closeView: record("closeView"),
+    calls,
+    callsTo: (method) => calls.filter((c) => c.method === method).map((c) => c.args),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Rendered tree
+
+const CATALOG = COMPONENTS as Readonly<Record<ComponentName, ComponentSpec>>;
+const NAME_BY_TAG = new Map<string, ComponentName>(
+  (Object.keys(CATALOG) as ComponentName[]).map((name) => [CATALOG[name].tagName, name]),
+);
+
+/** 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 class TestElement {
+  readonly #harness: Harness;
+  readonly #id: string;
+
+  /** @internal */
+  constructor(harness: Harness, id: string) {
+    this.#harness = harness;
+    this.#id = id;
+  }
+
+  get node(): RemoteReceiverElement {
+    const node = this.#harness.receiver.get<RemoteReceiverElement>({ id: this.#id });
+    if (!node) throw new Error("This element is no longer rendered");
+    return node;
+  }
+
+  get tag(): string {
+    return this.node.element;
+  }
+
+  /** Catalog component name, e.g. `"Button"`; undefined for `remote-fragment`. */
+  get component(): ComponentName | undefined {
+    return NAME_BY_TAG.get(this.tag);
+  }
+
+  get props(): Readonly<Record<string, unknown>> {
+    return this.node.properties;
+  }
+
+  get attributes(): Readonly<Record<string, string>> {
+    return this.node.attributes;
+  }
+
+  /** Name of the slot this element fills, if any. */
+  get slot(): string | undefined {
+    return this.node.attributes["slot"];
+  }
+
+  /** Event names the app is listening to (`press`, `change`, `shownchange`, ...). */
+  get events(): string[] {
+    return Object.keys(this.node.eventListeners).filter((name) => typeof this.node.eventListeners[name] === "function");
+  }
+
+  get children(): Array<TestElement | string> {
+    return this.node.children.flatMap((child): Array<TestElement | string> => {
+      if (child.type === NODE_TYPE_ELEMENT) return [new TestElement(this.#harness, child.id)];
+      if (child.type === NODE_TYPE_TEXT) return [child.data];
+      return [];
+    });
+  }
+
+  /** Concatenated text of this element and its descendants. */
+  get text(): string {
+    return textOf(this.node);
+  }
+
+  /** Elements placed in slot `name` (the children of its `remote-fragment`). */
+  slotted(name: string): TestElement[] {
+    return this.children.flatMap((child) =>
+      typeof child !== "string" && child.tag === REMOTE_FRAGMENT_TAG && child.slot === name
+        ? child.children.filter((c): c is TestElement => typeof c !== "string")
+        : [],
+    );
+  }
+
+  find(component: ComponentName | string, predicate?: ElementPredicate): TestElement | undefined {
+    return this.findAll(component, predicate)[0];
+  }
+
+  findAll(component: ComponentName | string, predicate?: ElementPredicate): TestElement[] {
+    return this.#harness.collect(this.node.children, component, predicate);
+  }
+
+  /**
+   * 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.
+   */
+  async trigger(prop: string, detail?: unknown): Promise<unknown> {
+    const component = this.component;
+    const eventName = (component && CATALOG[component].events[prop]?.event) ?? prop;
+    const listener = this.node.eventListeners[eventName];
+    if (typeof listener !== "function") {
+      throw new Error(`<${this.tag}> is not listening for "${eventName}"`);
+    }
+    const result = await (listener as (detail?: unknown) => unknown)(detail);
+    await this.#harness.settle();
+    return result;
+  }
+
+  toJSON(): TestSnapshot {
+    return this.#harness.snapshot(this.node);
+  }
+}
+
+function textOf(node: RemoteReceiverNode | RemoteReceiverRoot): string {
+  if (node.type === NODE_TYPE_TEXT) return (node as { data: string }).data;
+  if ("children" in node) return node.children.map(textOf).join("");
+  return "";
+}
+
+class Harness {
+  readonly receiver = new RemoteReceiver();
+  mutations = 0;
+
+  collect(nodes: readonly RemoteReceiverNode[], component: string, predicate?: ElementPredicate): TestElement[] {
+    const tag = component in CATALOG ? CATALOG[component as ComponentName].tagName : component;
+    const found: TestElement[] = [];
+    const walk = (list: readonly RemoteReceiverNode[]) => {
+      for (const node of list) {
+        if (node.type !== NODE_TYPE_ELEMENT) continue;
+        const element = new TestElement(this, node.id);
+        if (node.element === tag && (!predicate || predicate(element))) found.push(element);
+        walk((node as RemoteReceiverElement).children);
+      }
+    };
+    walk(nodes);
+    return found;
+  }
+
+  snapshot(node: RemoteReceiverElement): TestSnapshot {
+    const snap: TestSnapshot = {
+      type: NAME_BY_TAG.get(node.element) ?? node.element,
+      props: { ...node.properties },
+      events: Object.keys(node.eventListeners).filter((k) => typeof node.eventListeners[k] === "function"),
+      children: node.children.flatMap((child): Array<TestSnapshot | string> => {
+        if (child.type === NODE_TYPE_ELEMENT) return [this.snapshot(child as RemoteReceiverElement)];
+        if (child.type === NODE_TYPE_TEXT) return [(child as { data: string }).data];
+        return [];
+      }),
+    };
+    const slot = node.attributes["slot"];
+    if (slot !== undefined) snap.slot = slot;
+    return snap;
+  }
+
+  /** Waits until React and the mutation batch have gone quiet. */
+  async settle(): Promise<void> {
+    let quietTicks = 0;
+    for (let i = 0; i < 50 && quietTicks < 2; i++) {
+      const before = this.mutations;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      quietTicks = this.mutations === before ? quietTicks + 1 : 0;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// renderForTest
+
+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>;
+}
+
+let nextMount = 0;
+
+/**
+ * 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 async function renderForTest(element: ReactElement, options: RenderForTestOptions = {}): Promise<TestRender> {
+  if (!polyfillInstalled()) throw new Error("The remote-dom polyfill is not installed");
+  const harness = new Harness();
+  const errors: unknown[] = [];
+  const host = createMockHost(options.host);
+  let context = getMockContext(options.context);
+
+  const runtime = createSandboxExports(
+    { views: { TestView: () => element } },
+    {
+      batch: (flush) => queueMicrotask(flush),
+      onError: (error) => {
+        errors.push(error);
+      },
+    },
+  );
+
+  const connection: RemoteConnection = {
+    mutate(records: readonly RemoteMutationRecord[]) {
+      harness.mutations += 1;
+      (harness.receiver.connection.mutate as (r: readonly RemoteMutationRecord[]) => void)(records);
+    },
+    call(id, method, ...args) {
+      return harness.receiver.connection.call(id, method, ...args);
+    },
+  };
+
+  const mountId = `test-${++nextMount}`;
+  await runtime.mount({
+    mountId,
+    viewComponent: "TestView",
+    surfaceId: context.environment.surfaceId,
+    connection,
+    context,
+    host,
+  });
+  await harness.settle();
+
+  const rootElements = () => harness.receiver.root.children
+    .filter((node) => node.type === NODE_TYPE_ELEMENT)
+    .map((node) => new TestElement(harness, node.id));
+
+  return {
+    get roots() {
+      return rootElements();
+    },
+    get root() {
+      const first = rootElements()[0];
+      if (!first) throw new Error("The view rendered nothing");
+      return first;
+    },
+    host,
+    get context() {
+      return context;
+    },
+    errors,
+    receiver: harness.receiver,
+    runtime,
+    mountId,
+    find: (component, predicate) => harness.collect(harness.receiver.root.children, component, predicate)[0],
+    findAll: (component, predicate) => harness.collect(harness.receiver.root.children, component, predicate),
+    text: () => textOf(harness.receiver.root),
+    toJSON: () => rootElements().map((e) => e.toJSON()),
+    async updateContext(patch) {
+      await runtime.updateContext(mountId, patch);
+      context = { ...context, ...patch, protocolVersion: PROTOCOL_VERSION };
+      await harness.settle();
+    },
+    async unmount() {
+      await runtime.unmount(mountId);
+      await harness.settle();
+    },
+    settle: () => harness.settle(),
+  };
+}

package/src/apps/testing.ts

@@ -0,0 +1,8 @@
+/*
+ * Hand-written (not generated by Speakeasy). Entry point for
+ * `@greensecurity/javascript-sdk/apps/testing` (third-party app developer kit, C10). The package
+ * `exports` map resolves `./apps/<name>` to `src/apps/<name>.ts`, so each kit folder gets
+ * a one-line entry file next to it.
+ */
+
+export * from "./testing/index.js";

package/src/apps/ui/factory.ts

@@ -0,0 +1,157 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Builds the React component for one catalog entry. It renders the catalog's custom element
+ * (registered by `runtime/elements.ts`) and syncs props onto it after each commit, the job
+ * `createRemoteComponent` from `@remote-dom/react` does. The SDK does its own because that
+ * package's peer range (`react ^17 || ^18`) breaks React 19 installs for app authors. Beyond
+ * that, this layer:
+ *  - hands handlers the event's `detail` (a boolean, a string, the form values...) instead of
+ *    a DOM event, and returns whatever they return (usually a promise) as the value of the
+ *    host's call, so the host can wait for an async handler;
+ *  - keeps listener identities stable across renders, so a re-render does not re-send
+ *    listeners across the thread;
+ *  - forwards only catalog props (no `style`, `className`, `ref` or typos), and clears a prop
+ *    on the host when the app stops passing it;
+ *  - renders each slot prop as `<remote-fragment slot="name">`, wrapping text so it still lands
+ *    in the slot.
+ */
+
+import { REMOTE_FRAGMENT_TAG } from "../runtime/elements.js";
+import type { RemoteEvent } from "@remote-dom/core/elements";
+import { createElement, useLayoutEffect, useRef, type FunctionComponent, type ReactNode } from "react";
+import { COMPONENTS, type ComponentName, type ComponentProps, type ComponentSpec } from "../components.js";
+
+/** Props of the SDK component for catalog entry `N`: C0's `ComponentProps` with React nodes. */
+export type UiProps<N extends ComponentName> = ComponentProps<N, ReactNode>;
+
+type Handler = (detail?: unknown) => unknown;
+type Listener = (event: RemoteEvent) => void;
+
+/** What a remote element exposes: a property setter per catalog prop, and event listeners. */
+interface RemoteElementLike {
+  addEventListener(type: string, listener: Listener): void;
+  removeEventListener(type: string, listener: Listener): void;
+}
+
+const CATALOG = COMPONENTS as Readonly<Record<ComponentName, ComponentSpec>>;
+
+/**
+ * Whether a value is React content rather than plain data: an element, a portal, a fragment,
+ * an array or other iterable of nodes, a thenable (React 19 renders promises), or a `bigint`
+ * (a React 19 node that JSON cannot encode). The plain values a catalog prop that doubles as a
+ * slot accepts (strings, numbers) are none of these.
+ */
+function isRichNode(value: unknown): boolean {
+  return typeof value === "bigint" || (typeof value === "object" && value !== null);
+}
+
+/** How deep {@link isSendable} looks into arrays and plain objects. */
+const MAX_DATA_DEPTH = 8;
+
+/**
+ * Whether a plain data prop can cross the JSON thread: no React element or portal (`$$typeof`),
+ * `bigint`, function or symbol anywhere inside it, including nested in arrays and plain objects.
+ * Anything else (a class instance, a cycle, very deep nesting) is refused too.
+ */
+function isSendable(value: unknown, depth = 0, seen: Set<object> = new Set()): boolean {
+  if (value === null || value === undefined) return true;
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "boolean":
+      return true;
+    case "object":
+      break;
+    default:
+      return false; // bigint, function, symbol
+  }
+  if (depth >= MAX_DATA_DEPTH || seen.has(value) || "$$typeof" in value) return false;
+  seen.add(value);
+  if (Array.isArray(value)) return value.every((item) => isSendable(item, depth + 1, seen));
+  const proto = Object.getPrototypeOf(value) as unknown;
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(value).every((item) => isSendable(item, depth + 1, seen));
+}
+
+export function createUiComponent<N extends ComponentName>(name: N): FunctionComponent<UiProps<N>> {
+  const spec = CATALOG[name];
+  const tagName = spec.tagName;
+  const dataProps = Object.keys(spec.props);
+  const events = Object.entries(spec.events).map(([prop, e]) => [prop, e.event] as const);
+  const slotNames = spec.slots;
+  const propAndSlot = new Set(slotNames.filter((slot) => slot in spec.props));
+
+  function UiComponent(props: UiProps<N>): ReactNode {
+    const raw = props as Record<string, unknown>;
+    const element = useRef<RemoteElementLike | null>(null);
+    // A stable ref callback, so React does not detach and reattach it on every render.
+    const setElement = useRef((node: RemoteElementLike | null) => void (element.current = node)).current;
+
+    // Latest handlers, read by listeners whose identity never changes.
+    const handlers = useRef<Record<string, Handler | undefined>>({});
+    const listeners = useRef<Record<string, Listener>>({});
+    // What was last written to the element, to write only changes.
+    const appliedProps = useRef<Record<string, unknown>>({});
+    const attached = useRef<Record<string, boolean>>({});
+
+    const slotChildren: ReactNode[] = [];
+    for (const slot of slotNames) {
+      const value = raw[slot];
+      if (value === undefined || value === null || typeof value === "boolean") continue;
+      // A name that is both a prop and a slot (PropertyListItem `value`): plain values are the
+      // prop, React content in any form fills the slot.
+      if (propAndSlot.has(slot) && !isRichNode(value)) continue;
+      slotChildren.push(createElement(REMOTE_FRAGMENT_TAG, { slot, key: `slot:${slot}` }, value as ReactNode));
+    }
+
+    useLayoutEffect(() => {
+      const el = element.current;
+      if (!el) return;
+
+      const target = el as unknown as Record<string, unknown>;
+      const next: Record<string, unknown> = {};
+      for (const key of dataProps) {
+        const value = raw[key];
+        // React content is rendered into the slot above, and is never sent as remote data: it
+        // cannot cross the thread.
+        next[key] = (propAndSlot.has(key) ? isRichNode(value) : !isSendable(value)) ? undefined : value;
+        // Assigning `undefined` clears the property on the host.
+        if (!Object.is(appliedProps.current[key], next[key])) target[key] = next[key];
+      }
+      appliedProps.current = next;
+
+      // Handlers are taken from committed props only. Updating them during render would let an
+      // already-attached listener call a handler from a render that never commits (an
+      // interrupted transition, a suspended subtree).
+      for (const [prop] of events) {
+        const handler = raw[prop];
+        handlers.current[prop] = typeof handler === "function" ? (handler as Handler) : undefined;
+      }
+
+      for (const [prop, eventName] of events) {
+        const wanted = handlers.current[prop] !== undefined;
+        if (wanted === (attached.current[prop] === true)) continue;
+
+        listeners.current[prop] ??= (event: RemoteEvent) => {
+          const result = handlers.current[prop]?.(event.detail);
+          if (result !== undefined) event.respondWith(result);
+        };
+        if (wanted) el.addEventListener(eventName, listeners.current[prop]);
+        else el.removeEventListener(eventName, listeners.current[prop]);
+        attached.current[prop] = wanted;
+      }
+    });
+
+    const children = raw["children"] as ReactNode;
+    return createElement(
+      tagName,
+      { ref: setElement },
+      ...(slotChildren.length ? [children, slotChildren] : [children]),
+    );
+  }
+
+  UiComponent.displayName = name;
+  return UiComponent;
+}