@client-compose/client 0.5.1 → 0.7.0

package/src/index.ts

@@ -10,6 +10,8 @@ import {
   type DeclaredError,
   type IslandDescriptor,
   type IslandEntry,
+  type IslandRequest,
+  type IslandResponse,
   PROTOCOL_VERSION,
   type ScreenRequest,
   type ScreenResponse,
@@ -31,13 +33,25 @@ export class IslandRegistry<R> {
     versionOrRender: number | IslandRenderer<R, P>,
     maybeRender?: IslandRenderer<R, P>,
   ): this {
-    const [type, version, render] =
-      typeof islandOrType === "string"
-        ? [islandOrType, versionOrRender as number, maybeRender!]
-        : [islandOrType.type, islandOrType.version, versionOrRender as IslandRenderer<R, P>];
-    if (!this.renderers.has(type)) this.renderers.set(type, new Map());
-    // The registry hands each renderer the props of its own island type and version.
-    this.renderers.get(type)!.set(version, render as IslandRenderer<R>);
+    if (typeof islandOrType !== "string") {
+      if (typeof versionOrRender === "number") {
+        throw new Error("register(descriptor, render): pass the renderer, not a version");
+      }
+      return this.add(islandOrType.type, islandOrType.version, versionOrRender);
+    }
+    if (typeof versionOrRender !== "number" || !maybeRender) {
+      throw new Error("register(type, version, render): pass a version and a renderer");
+    }
+    return this.add(islandOrType, versionOrRender, maybeRender);
+  }
+
+  private add<P>(type: string, version: number, render: IslandRenderer<R, P>): this {
+    const versions = this.renderers.get(type) ?? new Map<number, IslandRenderer<R>>();
+    // The registry hands each renderer the props of its own island type and version, so the
+    // renderer's props type holds. TypeScript can't see that through one map of every island.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    versions.set(version, render as IslandRenderer<R>);
+    this.renderers.set(type, versions);
     return this;
   }
 
@@ -61,7 +75,13 @@ export function buildRequest(
   client: ClientContext,
   params?: Record<string, string>,
 ): ScreenRequest {
-  return { protocol: PROTOCOL_VERSION, screen, params, client, islands: registry.capabilities() };
+  return {
+    protocol: PROTOCOL_VERSION,
+    screen,
+    params,
+    client,
+    islands: registry.capabilities(),
+  };
 }
 
 export interface PlannedIsland<R> {
@@ -88,7 +108,9 @@ export function plan<R>(
   for (const entry of response.islands) {
     if (entry.status === "error") {
       const fallback = options.onError?.(entry);
-      if (fallback !== undefined) out.push({ key: entry.key, render: () => fallback });
+      if (fallback !== undefined) {
+        out.push({ key: entry.key, render: () => fallback });
+      }
       continue;
     }
     if (entry.status !== "ok") {
@@ -105,6 +127,41 @@ export function plan<R>(
   return out;
 }
 
+// ---- Reading what the composer answered ----
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The body as JSON, or undefined if it isn't JSON. */
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function isIslandEntry(value: unknown): value is IslandEntry {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const named = typeof value.key === "string" && typeof value.type === "string";
+  return named && typeof value.version === "number" && typeof value.status === "string";
+}
+
+function isScreenResponse(value: unknown): value is ScreenResponse {
+  if (!isRecord(value) || typeof value.screen !== "string") {
+    return false;
+  }
+  return Array.isArray(value.islands) && value.islands.every(isIslandEntry);
+}
+
+/** An action's outcome: what a client needs of one is its status (the client fixtures, spec §8.2). */
+function isActionResponse(value: unknown): value is ActionResponse {
+  return isRecord(value) && (value.status === "ok" || value.status === "error");
+}
+
 export class ScreenFetchError extends Error {
   readonly status: number;
   readonly body: string;
@@ -121,13 +178,27 @@ export class ScreenFetchError extends Error {
 
 function errorCode(body: string): string | undefined {
   try {
-    const code = (JSON.parse(body) as { error?: { code?: unknown } }).error?.code;
+    const parsed: unknown = JSON.parse(body);
+    const error = isRecord(parsed) ? parsed.error : undefined;
+    const code = isRecord(error) ? error.code : undefined;
     return typeof code === "string" ? code : undefined;
   } catch {
     return undefined;
   }
 }
 
+/**
+ * The caller's headers, given any way fetch takes them, sent as JSON unless they say otherwise.
+ * (Spreading a `Headers` object would drop them all.)
+ */
+function jsonHeaders(init: HeadersInit | undefined): Headers {
+  const headers = new Headers(init);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  return headers;
+}
+
 export async function fetchScreen(
   baseUrl: string,
   request: ScreenRequest,
@@ -137,11 +208,99 @@ export async function fetchScreen(
   const res = await fetchImpl(`${baseUrl}/screens/${encodeURIComponent(request.screen)}`, {
     ...init,
     method: "POST",
-    headers: { "content-type": "application/json", ...init.headers },
+    headers: jsonHeaders(init.headers),
+    body: JSON.stringify(request),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new ScreenFetchError(res.status, text);
+  }
+  const response = parseJson(text);
+  if (!isScreenResponse(response)) {
+    throw new ScreenFetchError(res.status, text);
+  }
+  return response;
+}
+
+// ---- Island requests (spec §4.5) ----
+
+/**
+ * A request for one island of a screen: the page `cursor` asks for (an entry's `next`), or the
+ * island from its first page without one. `params` are the screen's own.
+ */
+export function buildIslandRequest(
+  screen: string,
+  params: Record<string, string> | undefined,
+  entry: { key: string; version: number },
+  client: ClientContext,
+  cursor?: string,
+): IslandRequest {
+  return {
+    protocol: PROTOCOL_VERSION,
+    screen,
+    key: entry.key,
+    version: entry.version,
+    params,
+    client,
+    ...(cursor !== undefined && { cursor }),
+  };
+}
+
+/**
+ * POST an island request. Resolves with the island's entry: its props (and `next`, if it has more
+ * pages) or the error it failed with. Throws IslandFetchError for a non-2xx response (e.g.
+ * `invalid_cursor`, `unknown_island`, `unauthenticated`), or an answer that isn't this island.
+ */
+export async function fetchIsland(
+  baseUrl: string,
+  request: IslandRequest,
+  init: RequestInit = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<IslandEntry> {
+  const path = `${encodeURIComponent(request.screen)}/islands/${encodeURIComponent(request.key)}`;
+  const res = await fetchImpl(`${baseUrl}/screens/${path}`, {
+    ...init,
+    method: "POST",
+    headers: jsonHeaders(init.headers),
     body: JSON.stringify(request),
   });
-  if (!res.ok) throw new ScreenFetchError(res.status, await res.text());
-  return (await res.json()) as ScreenResponse;
+  const text = await res.text();
+  if (!res.ok) {
+    throw new IslandFetchError(res.status, text);
+  }
+  const response = parseJson(text);
+  if (!isIslandResponse(response) || !isIslandAsked(response.island, request)) {
+    throw new IslandFetchError(res.status, text);
+  }
+  return response.island;
+}
+
+/**
+ * An island request failed: a non-2xx response such as `invalid_cursor`, `unknown_island` or
+ * `unauthenticated`, or an answer that isn't the island asked for. An island that failed on the
+ * composer isn't thrown: it's an entry with `status: "error"`.
+ */
+export class IslandFetchError extends Error {
+  readonly status: number;
+  readonly body: string;
+  /** The protocol error code from the response body (e.g. "invalid_cursor"), if there was one. */
+  readonly code: string | undefined;
+
+  constructor(status: number, body: string) {
+    super(`Island request failed with status ${status}`);
+    this.status = status;
+    this.body = body;
+    this.code = errorCode(body);
+  }
+}
+
+function isIslandResponse(value: unknown): value is IslandResponse {
+  return isRecord(value) && typeof value.screen === "string" && isIslandEntry(value.island);
+}
+
+/** Whether the answer is the island the request asked for, at the version it asked for. */
+function isIslandAsked(island: IslandEntry, request: IslandRequest): boolean {
+  return island.key === request.key && island.version === request.version;
 }
 
 // ---- Actions (spec §5) ----
@@ -166,8 +325,11 @@ export class ActionFetchError extends Error {
 
 /** A fresh idempotency key: one per user intent, reused when retrying it (spec §5.2). */
 export function newIdempotencyKey(): string {
-  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
-  if (c?.randomUUID) return c.randomUUID();
+  // React Native's Hermes may have no crypto, or crypto without randomUUID.
+  const c: Partial<Pick<Crypto, "randomUUID">> | undefined = globalThis.crypto;
+  if (c?.randomUUID) {
+    return c.randomUUID();
+  }
   // React Native's Hermes has no crypto.randomUUID. Uniqueness, not secrecy, is what matters here.
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
     const r = (Math.random() * 16) | 0;
@@ -191,7 +353,11 @@ export function buildActionRequest<I>(
   };
 }
 
-/** POST an action request. Resolves with the outcome (ok or a declared error); throws ActionFetchError otherwise. */
+/**
+ * POST an action request. Resolves with the outcome the composer sent (ok or an error); throws
+ * ActionFetchError for a non-2xx response or a body that isn't an outcome. Check the outcome against
+ * the action with `checkActionResponse` (callAction does).
+ */
 export async function fetchAction(
   baseUrl: string,
   request: ActionRequest,
@@ -201,11 +367,40 @@ export async function fetchAction(
   const res = await fetchImpl(`${baseUrl}/actions/${encodeURIComponent(request.action)}`, {
     ...init,
     method: "POST",
-    headers: { "content-type": "application/json", ...init.headers },
+    headers: jsonHeaders(init.headers),
     body: JSON.stringify(request),
   });
-  if (!res.ok) throw new ActionFetchError(res.status, await res.text());
-  return (await res.json()) as ActionResponse;
+  const text = await res.text();
+  if (!res.ok) {
+    throw new ActionFetchError(res.status, text);
+  }
+  const response = parseJson(text);
+  if (!isActionResponse(response)) {
+    throw new ActionFetchError(res.status, text);
+  }
+  return response;
+}
+
+/**
+ * The response, if it's a result or one of this action's own declared errors. Anything else throws
+ * ActionFetchError (status 200, with the code if there is one): an outcome the client can't read,
+ * or a code the action doesn't declare, such as one added after this app was built (spec §5.1).
+ */
+export function checkActionResponse<I, R, E extends DeclaredError>(
+  action: ActionDescriptor<I, R, E>,
+  response: unknown,
+): ActionResponse<R, E> {
+  const error = isRecord(response) ? response.error : undefined;
+  const code = isRecord(error) ? error.code : undefined;
+  const status = isRecord(response) ? response.status : undefined;
+  const declared = status === "error" && typeof code === "string" && action.errors.includes(code);
+  if (isActionResponse(response) && (status === "ok" || declared)) {
+    // The result's and error's types are the action's: generated from its manifest, which the
+    // composer checks its outcomes against. They exist only at the type level.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return response as ActionResponse<R, E>;
+  }
+  throw new ActionFetchError(200, JSON.stringify(response));
 }
 
 export interface CallActionOptions {
@@ -236,5 +431,8 @@ export async function callAction<I, R, E extends DeclaredError>(
     options.client,
     options.idempotencyKey ?? newIdempotencyKey(),
   );
-  return (await fetchAction(baseUrl, request, options.init, options.fetch)) as ActionResponse<R, E>;
+  return checkActionResponse(
+    action,
+    await fetchAction(baseUrl, request, options.init, options.fetch),
+  );
 }

package/src/proxy.ts

@@ -18,15 +18,26 @@ import {
   type ActionResponse,
   type Capabilities,
   type ClientContext,
+  type IslandEntry,
+  type IslandRequest,
   PROTOCOL_VERSION,
   type ScreenRequest,
   type ScreenResponse,
 } from "@client-compose/protocol";
 
-import { ActionFetchError, fetchAction, fetchScreen, ScreenFetchError } from "./index.ts";
+import {
+  ActionFetchError,
+  fetchAction,
+  fetchIsland,
+  fetchScreen,
+  IslandFetchError,
+  ScreenFetchError,
+} from "./index.ts";
 
 /** A screen request from the browser: the server sets the client context. */
 export type ProxiedScreenRequest = Omit<ScreenRequest, "client">;
+/** An island request from the browser: the server sets the client context. */
+export type ProxiedIslandRequest = Omit<IslandRequest, "client">;
 /** An action request from the browser: the server sets the client context. */
 export type ProxiedActionRequest = Omit<ActionRequest, "client">;
 
@@ -60,6 +71,11 @@ export interface ComposerProxy {
   performAction(body: unknown): Promise<ProxyResult<ActionResponse>>;
   /** Checks a browser's screen request, then loads it with the server's context and headers. */
   loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>>;
+  /**
+   * Checks a browser's island request (a page of an island, spec §4.5), then loads it with the
+   * server's context and headers. Resolves with the island's entry.
+   */
+  loadIsland(body: unknown): Promise<ProxyResult<IslandEntry>>;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -78,25 +94,48 @@ function isStringRecord(value: unknown): value is Record<string, string> {
   return isRecord(value) && Object.values(value).every((v) => typeof v === "string");
 }
 
+// Each guard returns at the first thing a request gets wrong, so it checks no more than it must.
+
 export function isProxiedScreenRequest(value: unknown): value is ProxiedScreenRequest {
-  return (
-    isRecord(value) &&
-    value.protocol === PROTOCOL_VERSION &&
-    typeof value.screen === "string" &&
-    (value.params === undefined || isStringRecord(value.params)) &&
-    isCapabilities(value.islands)
-  );
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.screen !== "string") {
+    return false;
+  }
+  if (value.params !== undefined && !isStringRecord(value.params)) {
+    return false;
+  }
+  return isCapabilities(value.islands);
+}
+
+export function isProxiedIslandRequest(value: unknown): value is ProxiedIslandRequest {
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.screen !== "string" || typeof value.key !== "string") {
+    return false;
+  }
+  if (typeof value.version !== "number" || !Number.isInteger(value.version)) {
+    return false;
+  }
+  if (value.params !== undefined && !isStringRecord(value.params)) {
+    return false;
+  }
+  return value.cursor === undefined || typeof value.cursor === "string";
 }
 
 export function isProxiedActionRequest(value: unknown): value is ProxiedActionRequest {
-  return (
-    isRecord(value) &&
-    value.protocol === PROTOCOL_VERSION &&
-    typeof value.action === "string" &&
-    typeof value.version === "number" &&
-    "input" in value &&
-    (value.idempotencyKey === undefined || typeof value.idempotencyKey === "string")
-  );
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.action !== "string" || typeof value.version !== "number") {
+    return false;
+  }
+  if (!("input" in value)) {
+    return false;
+  }
+  return value.idempotencyKey === undefined || typeof value.idempotencyKey === "string";
 }
 
 /** What the composer itself answers to a malformed request. */
@@ -108,12 +147,17 @@ const BAD_REQUEST = {
 
 export function createComposerProxy(options: ComposerProxyOptions): ComposerProxy {
   async function init(): Promise<RequestInit> {
-    const headers = (await options.headers?.()) ?? {};
-    return { ...options.requestInit, headers: { ...options.requestInit?.headers, ...headers } };
+    const headers = new Headers(options.requestInit?.headers);
+    for (const [name, value] of Object.entries((await options.headers?.()) ?? {})) {
+      headers.set(name, value);
+    }
+    return { ...options.requestInit, headers };
   }
 
   async function performAction(body: unknown): Promise<ProxyResult<ActionResponse>> {
-    if (!isProxiedActionRequest(body)) return BAD_REQUEST;
+    if (!isProxiedActionRequest(body)) {
+      return BAD_REQUEST;
+    }
     const request: ActionRequest = { ...body, client: await options.client() };
     try {
       const response = await fetchAction(options.baseUrl, request, await init(), options.fetch);
@@ -122,14 +166,21 @@ export function createComposerProxy(options: ComposerProxyOptions): ComposerProx
         response: (await options.onActionResponse?.(request, response)) ?? response,
       };
     } catch (error) {
-      if (error instanceof ActionFetchError)
-        return { ok: false, status: error.status, body: error.body };
+      if (error instanceof ActionFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
       throw error;
     }
   }
 
   async function loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>> {
-    if (!isProxiedScreenRequest(body)) return BAD_REQUEST;
+    if (!isProxiedScreenRequest(body)) {
+      return BAD_REQUEST;
+    }
     const request: ScreenRequest = { ...body, client: await options.client() };
     try {
       return {
@@ -137,11 +188,42 @@ export function createComposerProxy(options: ComposerProxyOptions): ComposerProx
         response: await fetchScreen(options.baseUrl, request, await init(), options.fetch),
       };
     } catch (error) {
-      if (error instanceof ScreenFetchError)
-        return { ok: false, status: error.status, body: error.body };
+      if (error instanceof ScreenFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async function loadIsland(body: unknown): Promise<ProxyResult<IslandEntry>> {
+    if (!isProxiedIslandRequest(body)) {
+      return BAD_REQUEST;
+    }
+    const request: IslandRequest = { ...body, client: await options.client() };
+    try {
+      return {
+        ok: true,
+        response: await fetchIsland(options.baseUrl, request, await init(), options.fetch),
+      };
+    } catch (error) {
+      if (error instanceof IslandFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
       throw error;
     }
   }
 
-  return { performAction, loadScreen };
+  return {
+    performAction,
+    loadScreen,
+    loadIsland,
+  };
 }