@apollo/client-ai-apps 0.4.0 → 0.5.0

package/src/testing/internal/matchers/toEmitValue.ts

@@ -0,0 +1,71 @@
+import { iterableEquality } from "@jest/expect-utils";
+import { expect } from "vitest";
+
+import type { TakeOptions } from "../utilities/ObservableStream.js";
+import {
+  ObservableStream,
+  EventMismatchError,
+} from "../utilities/ObservableStream.js";
+
+import { getSerializableProperties } from "../utilities/getSerializableProperties.js";
+
+expect.extend({
+  async toEmitValue(actual, expected, options: TakeOptions) {
+    const stream = actual as ObservableStream<any>;
+    const hint = this.utils.matcherHint("toEmitValue", "stream", "expected", {
+      isNot: this.isNot,
+    });
+
+    try {
+      const value = await stream.takeNext(options);
+      const serializableProperties = getSerializableProperties(value);
+
+      const pass = this.equals(
+        serializableProperties,
+        expected,
+        // https://github.com/jestjs/jest/blob/22029ba06b69716699254bb9397f2b3bc7b3cf3b/packages/expect/src/matchers.ts#L62-L67
+        [...this.customTesters, iterableEquality],
+        true
+      );
+
+      return {
+        pass,
+        message: () => {
+          if (pass) {
+            return (
+              hint +
+              "\n\nExpected stream not to emit a fetch result equal to expected but it did."
+            );
+          }
+
+          return (
+            hint +
+            "\n\n" +
+            this.utils.printDiffOrStringify(serializableProperties, expected)
+          );
+        },
+      };
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.message === "Timeout waiting for next event"
+      ) {
+        return {
+          pass: false,
+          message: () =>
+            hint + "\n\nExpected stream to emit a value but it did not.",
+        };
+      } else if (EventMismatchError.is(error)) {
+        return {
+          pass: false,
+          message: () =>
+            this.utils.matcherHint("toEmitNext", "stream", "expected") +
+            "\n\n" +
+            this.utils.printDiffOrStringify(error.actual, error.expected),
+        };
+      } else {
+        throw error;
+      }
+    }
+  },
+});

package/src/testing/internal/matchers/types.ts

@@ -1,7 +1,10 @@
 import type { NextRenderOptions } from "@testing-library/react-render-stream";
+import type { TakeOptions } from "../utilities/ObservableStream.js";
 
 interface CustomMatchers<R = unknown> {
   toRerender: (options?: NextRenderOptions) => Promise<R>;
+  toComplete: (options?: TakeOptions) => Promise<R>;
+  toEmitValue: (expected: unknown, options?: TakeOptions) => Promise<R>;
 }
 
 declare module "vitest" {

package/src/testing/internal/mcp/graphqlToolResult.ts

@@ -0,0 +1,31 @@
+import type { McpUiToolResultNotification } from "@modelcontextprotocol/ext-apps";
+import type { FormattedExecutionResult } from "graphql";
+import type { ApolloMcpServerApps } from "../../../core/types";
+
+export function graphqlToolResult(
+  options:
+    | FormattedExecutionResult
+    | {
+        prefetch?: Record<string, FormattedExecutionResult>;
+        result: FormattedExecutionResult;
+      }
+): McpUiToolResultNotification["params"] {
+  let structuredContent: ApolloMcpServerApps.StructuredContent;
+
+  if ("data" in options) {
+    structuredContent = { result: options };
+  } else if ("result" in options) {
+    structuredContent = { result: options.result };
+
+    if (options.prefetch) {
+      structuredContent.prefetch = options.prefetch;
+    }
+  } else {
+    throw new Error("Mock tool result could not be parsed");
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    structuredContent,
+  };
+}

package/src/testing/internal/mcp/minimalHostContextWithToolName.ts

@@ -0,0 +1,9 @@
+import type { McpUiHostContext } from "@modelcontextprotocol/ext-apps";
+
+export function minimalHostContextWithToolName(
+  toolName: string
+): McpUiHostContext {
+  return {
+    toolInfo: { tool: { name: toolName, inputSchema: { type: "object" } } },
+  };
+}

package/src/testing/internal/mcp/mockMcpHost.ts

@@ -0,0 +1,188 @@
+import {
+  LATEST_PROTOCOL_VERSION,
+  type McpUiHostCapabilities,
+  type McpUiHostContext,
+  type McpUiToolResultNotification,
+  type McpUiToolInputNotification,
+} from "@modelcontextprotocol/ext-apps";
+import type {
+  CallToolRequest,
+  CallToolResult,
+  Implementation,
+} from "@modelcontextprotocol/sdk/types.js";
+import { invariant, promiseWithResolvers } from "../../../utilities/index.js";
+
+export interface MockMcpHost extends Disposable {
+  sendToolResult(params: McpUiToolResultNotification["params"]): Promise<void>;
+  sendToolInput(params: McpUiToolInputNotification["params"]): Promise<void>;
+  mockToolCall(
+    name: string,
+    handler: (params: CallToolRequest["params"]) => CallToolResult
+  ): () => void;
+  /**
+   * Register an MCP App to be closed during cleanup. This prevents the App's
+   * transport from interfering with subsequent tests by responding to messages
+   * it shouldn't be handling.
+   */
+  onCleanup(cleanup: () => void): void;
+  cleanup(): void;
+}
+
+/**
+ * In vitest's happy-dom environment, `window` is a Proxy around the real
+ * `GlobalWindow` object. `event.source` on `MessageEvent` returns the real
+ * `GlobalWindow`, which !== the proxied `window`. `PostMessageTransport` uses
+ * `event.source !== eventSource` to validate messages, so all messages get
+ * rejected when `eventSource` is the proxy.
+ *
+ * We work around this by discovering the real `GlobalWindow` via a probe
+ * `postMessage` and overriding `window.parent` so `PostMessageTransport`
+ * (which is constructed with `window.parent` as both target and eventSource)
+ * can properly match `event.source`.
+ */
+async function patchWindowParent(): Promise<() => void> {
+  const realWindow = await new Promise<Window>((resolve) => {
+    const probe = (event: MessageEvent) => {
+      window.removeEventListener("message", probe);
+      resolve(event.source as Window);
+    };
+    window.addEventListener("message", probe);
+    window.postMessage({ __mockMcpHostProbe: true }, "*");
+  });
+
+  // If event.source already matches window.parent, no patch needed
+  if (realWindow === window.parent) {
+    return () => {};
+  }
+
+  const originalParent = window.parent;
+  Object.defineProperty(window, "parent", {
+    value: realWindow,
+    writable: true,
+    configurable: true,
+  });
+
+  return () => {
+    Object.defineProperty(window, "parent", {
+      value: originalParent,
+      writable: true,
+      configurable: true,
+    });
+  };
+}
+
+export declare namespace mockMcpHost {
+  export interface Options {
+    hostCapabilities?: McpUiHostCapabilities;
+    hostContext?: McpUiHostContext;
+    hostInfo?: Implementation;
+  }
+}
+
+export async function mockMcpHost(
+  options?: mockMcpHost.Options
+): Promise<MockMcpHost> {
+  const {
+    hostCapabilities = {},
+    hostContext = {},
+    hostInfo = { name: "MockMcpHost", version: "1.0.0" },
+  } = options ?? {};
+
+  const restore = await patchWindowParent();
+
+  const { promise: initialized, resolve: resolveInitialized } =
+    promiseWithResolvers<void>();
+
+  const cleanupFns = new Set<() => void>();
+  const toolCallHandlers = new Map<
+    string,
+    (params: CallToolRequest["params"]) => CallToolResult
+  >();
+
+  const listener = (event: MessageEvent<unknown>) => {
+    const data = event.data;
+
+    if (!data || typeof data !== "object" || !("jsonrpc" in data)) return;
+    if (!("method" in data)) return;
+
+    if (data.method === "ui/initialize" && "id" in data) {
+      window.postMessage({
+        jsonrpc: "2.0",
+        id: data.id,
+        result: {
+          protocolVersion: LATEST_PROTOCOL_VERSION,
+          hostCapabilities,
+          hostInfo,
+          hostContext,
+        },
+      });
+    }
+
+    // The App sends this notification after processing the initialize response
+    if (data.method === "ui/notifications/initialized") {
+      resolveInitialized();
+    }
+
+    if (data.method === "tools/call" && "id" in data) {
+      const { params } = data as unknown as CallToolRequest;
+
+      const handler = toolCallHandlers.get(params.name);
+
+      invariant(
+        handler,
+        `mockMcpHost: A mock tool call handler for '${params.name}' is not registered.`
+      );
+
+      window.postMessage({
+        jsonrpc: "2.0",
+        id: data.id,
+        result: handler(params),
+      });
+    }
+  };
+
+  window.addEventListener("message", listener);
+
+  function cleanup() {
+    window.removeEventListener("message", listener);
+    cleanupFns.forEach((fn) => fn());
+    restore();
+  }
+
+  return {
+    async sendToolResult(params) {
+      await initialized;
+      window.postMessage({
+        jsonrpc: "2.0",
+        method: "ui/notifications/tool-result",
+        params,
+      });
+    },
+    async sendToolInput(params) {
+      await initialized;
+      window.postMessage({
+        jsonrpc: "2.0",
+        method: "ui/notifications/tool-input",
+        params,
+      });
+    },
+    mockToolCall(name, handler) {
+      if (toolCallHandlers.has(name)) {
+        console.warn(
+          `mockMcpHost: a handler is already registered for tool "${name}"`
+        );
+      }
+
+      toolCallHandlers.set(name, handler);
+
+      return () => toolCallHandlers.delete(name);
+    },
+    onCleanup(fn) {
+      cleanupFns.add(fn);
+    },
+    cleanup,
+    [Symbol.dispose]() {
+      cleanup();
+    },
+  } satisfies MockMcpHost;
+}

package/src/testing/internal/openai/dispatchStateChange.ts

@@ -1,4 +1,4 @@
-import { SET_GLOBALS_EVENT_TYPE } from "../../../types/openai.js";
+import { SET_GLOBALS_EVENT_TYPE } from "../../../openai/types.js";
 
 export function dispatchStateChange() {
   window.dispatchEvent(

package/src/testing/internal/openai/stubOpenAiGlobals.ts

@@ -3,15 +3,28 @@ import type {
   API,
   OpenAiGlobals,
   UnknownObject,
-} from "../../../types/openai.js";
+} from "../../../openai/types.js";
+import "../../../openai/globals.js";
 import { dispatchStateChange } from "./dispatchStateChange.js";
 
-export function stubOpenAiGlobals(globals?: Partial<API<any> & OpenAiGlobals>) {
-  vi.stubGlobal("openai", {
-    setWidgetState: (state: UnknownObject) => {
-      window.openai.widgetState = state;
-      dispatchStateChange();
-    },
-    ...globals,
-  });
+type Globals = API<any> & OpenAiGlobals;
+
+const DEFAULTS = Object.freeze({
+  setWidgetState: async (state: UnknownObject) => {
+    window.openai.widgetState = state;
+    dispatchStateChange();
+  },
+  toolOutput: null,
+  toolResponseMetadata: null,
+}) satisfies Partial<Globals>;
+
+export function stubOpenAiGlobals(
+  globals?: Partial<Globals> | ((defaults: typeof DEFAULTS) => Partial<Globals>)
+) {
+  vi.stubGlobal(
+    "openai",
+    typeof globals === "function" ?
+      globals(DEFAULTS)
+    : { ...DEFAULTS, ...globals }
+  );
 }

package/src/testing/internal/react/renderAsync.ts

@@ -0,0 +1,7 @@
+import { act, render } from "@testing-library/react";
+
+// Helper to silence act warnings when testing a component that suspends.
+// See https://github.com/testing-library/react-testing-library/issues/1375
+export async function renderAsync(...args: Parameters<typeof render>) {
+  return await act(async () => render(...args));
+}

package/src/testing/internal/utilities/ObservableStream.ts

@@ -0,0 +1,172 @@
+/**
+ * Adapted from
+ * https://github.com/apollographql/apollo-client/blob/1d165ba37eca7e5d667055553aacc4c26be56065/src/testing/internal/ObservableStream.ts
+ */
+import {
+  ReadableStream,
+  type ReadableStreamDefaultReader,
+} from "node:stream/web";
+import type { Observable, Subscribable, Unsubscribable } from "rxjs";
+import { expect } from "vitest";
+import { equals, iterableEquality, JEST_MATCHERS_OBJECT } from "@vitest/expect";
+import { printDiffOrStringify } from "@vitest/utils/diff";
+
+export interface TakeOptions {
+  timeout?: number;
+}
+type ObservableEvent<T> =
+  | { type: "next"; value: T }
+  | { type: "error"; error: any }
+  | { type: "complete" };
+
+function formatMessage(
+  expected: ObservableEvent<any>,
+  actual: ObservableEvent<any>
+) {
+  return printDiffOrStringify(expected, actual, { expand: true });
+}
+
+export class EventMismatchError extends Error {
+  readonly actual: ObservableEvent<any>;
+  readonly expected: ObservableEvent<any>;
+
+  static is(error: unknown): error is EventMismatchError {
+    return error instanceof Error && error.name === "EventMismatchError";
+  }
+
+  constructor(expected: ObservableEvent<any>, actual: ObservableEvent<any>) {
+    super(formatMessage(expected, actual));
+    this.name = "EventMismatchError";
+    this.actual = actual;
+    this.expected = expected;
+
+    Object.setPrototypeOf(this, EventMismatchError.prototype);
+  }
+}
+
+export class ObservableStream<T> {
+  private reader: ReadableStreamDefaultReader<ObservableEvent<T>>;
+  private subscription!: Unsubscribable;
+  private readerQueue: Array<Promise<ObservableEvent<T>>> = [];
+
+  constructor(observable: Observable<T> | Subscribable<T>) {
+    this.unsubscribe = this.unsubscribe.bind(this);
+    this.reader = new ReadableStream<ObservableEvent<T>>({
+      start: (controller) => {
+        this.subscription = observable.subscribe({
+          next: (value) => controller.enqueue({ type: "next", value }),
+          error: (error) => controller.enqueue({ type: "error", error }),
+          complete: () => controller.enqueue({ type: "complete" }),
+        });
+      },
+    }).getReader();
+  }
+
+  peek({ timeout = 100 }: TakeOptions = {}) {
+    // Calling `peek` multiple times in a row should not advance the reader
+    // multiple times until this value has been consumed.
+    let readerPromise = this.readerQueue[0];
+
+    if (!readerPromise) {
+      // Since this.reader.read() advances the reader in the stream, we don't
+      // want to consume this promise entirely, otherwise we will miss it when
+      // calling `take`. Instead, we push it into a queue that can be consumed
+      // by `take` the next time its called so that we avoid advancing the
+      // reader until we are finished processing all peeked values.
+      readerPromise = this.readNextValue();
+      this.readerQueue.push(readerPromise);
+    }
+
+    return Promise.race([
+      readerPromise,
+      new Promise<ObservableEvent<T>>((_, reject) => {
+        setTimeout(
+          reject,
+          timeout,
+          new Error("Timeout waiting for next event")
+        );
+      }),
+    ]);
+  }
+
+  take({ timeout = 100 }: TakeOptions = {}) {
+    return Promise.race([
+      this.readerQueue.shift() || this.readNextValue(),
+      new Promise<ObservableEvent<T>>((_, reject) => {
+        setTimeout(
+          reject,
+          timeout,
+          new Error("Timeout waiting for next event")
+        );
+      }),
+    ]).then((value) => {
+      if (value.type === "next") {
+        this.current = value.value;
+      }
+      return value;
+    });
+  }
+
+  [Symbol.dispose]() {
+    this.unsubscribe();
+  }
+
+  unsubscribe() {
+    this.subscription.unsubscribe();
+  }
+
+  async takeNext(options?: TakeOptions): Promise<T> {
+    const event = await this.take(options);
+    if (event.type !== "next") {
+      throw new EventMismatchError(
+        { type: "next", value: expect.anything() },
+        event
+      );
+    }
+    return (event as ObservableEvent<T> & { type: "next" }).value;
+  }
+
+  async takeError(options?: TakeOptions): Promise<any> {
+    const event = await this.take(options);
+    validateEquals(event, { type: "error", error: expect.anything() });
+    return (event as ObservableEvent<T> & { type: "error" }).error;
+  }
+
+  async takeComplete(options?: TakeOptions): Promise<void> {
+    const event = await this.take(options);
+    validateEquals(event, { type: "complete" });
+  }
+
+  private async readNextValue() {
+    return this.reader.read().then((result) => result.value!);
+  }
+
+  private current?: T;
+  getCurrent() {
+    return this.current;
+  }
+}
+
+// Lightweight expect(...).toEqual(...) check that avoids using `expect` so that
+// `expect.assertions(num)` does not double count assertions when using the take*
+// functions inside of expect(stream).toEmit* matchers.
+function validateEquals(
+  actualEvent: ObservableEvent<any>,
+  expectedEvent: ObservableEvent<any>
+) {
+  // Uses the same matchers as expect(...).toEqual(...)
+  // https://github.com/vitest-dev/vitest/blob/438c44e7fb8f3a6a36db8ff504f852c01963ba88/packages/expect/src/jest-expect.ts#L107-L110
+  const isEqual = equals(actualEvent, expectedEvent, [
+    ...getCustomEqualityTesters(),
+    iterableEquality,
+  ]);
+
+  if (!isEqual) {
+    throw new EventMismatchError(expectedEvent, actualEvent);
+  }
+}
+
+// https://github.com/vitest-dev/vitest/blob/438c44e7fb8f3a6a36db8ff504f852c01963ba88/packages/expect/src/jest-matcher-utils.ts#L157-L159
+function getCustomEqualityTesters() {
+  return (globalThis as any)[JEST_MATCHERS_OBJECT].customEqualityTesters;
+}

package/src/testing/internal/utilities/getSerializableProperties.ts

@@ -0,0 +1,55 @@
+/**
+ * Adapted from
+ * https://github.com/apollographql/apollo-client/blob/39adac005bfc947948960ec32635272d7d252bd5/src/testing/matchers/utils/getSerializableProperties.ts
+ */
+import { ApolloClient, ObservableQuery } from "@apollo/client";
+import { isPlainObject } from "@apollo/client/utilities/internal";
+
+function isKnownClassInstance(value: unknown) {
+  return [ApolloClient, ObservableQuery].some((c) => value instanceof c);
+}
+
+export function getSerializableProperties(
+  obj: unknown,
+  {
+    includeKnownClassInstances = false,
+  }: {
+    includeKnownClassInstances?: boolean;
+  } = {}
+): any {
+  if (Array.isArray(obj)) {
+    return obj.map((item) =>
+      getSerializableProperties(item, {
+        includeKnownClassInstances,
+      })
+    );
+  }
+
+  if (isPlainObject(obj)) {
+    return [...Object.keys(obj), ...Object.getOwnPropertySymbols(obj)].reduce(
+      (memo, key) => {
+        const value = obj[key as any];
+        if (
+          typeof value === "function" ||
+          (!includeKnownClassInstances && isKnownClassInstance(value))
+        ) {
+          return memo;
+        }
+
+        // Recurse if we have a nested object/array
+        if (isPlainObject(value) || Array.isArray(value)) {
+          return {
+            ...memo,
+            [key]: getSerializableProperties(value, {
+              includeKnownClassInstances,
+            }),
+          };
+        }
+        return { ...memo, [key]: value };
+      },
+      {} as Record<string, any>
+    );
+  }
+
+  return obj;
+}

package/src/testing/internal/utilities/mockApplicationManifest.ts

@@ -0,0 +1,39 @@
+import type { ApplicationManifest } from "../../../types/application-manifest";
+
+export function mockApplicationManifest(
+  overrides?: Partial<ApplicationManifest>
+): ApplicationManifest {
+  return {
+    format: "apollo-ai-app-manifest",
+    version: "1",
+    appVersion: "1.0.0",
+    name: "the-store",
+    description:
+      "An online store selling a variety of high quality products across many different categories.",
+    hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
+    operations: [
+      {
+        id: "c43af26552874026c3fb346148c5795896aa2f3a872410a0a2621cffee25291c",
+        name: "Product",
+        type: "query",
+        body: "query Product($id: ID!) {\n  product(id: $id) {\n    id\n    title\n    rating\n    price\n    description\n    images\n    __typename\n  }\n}",
+        variables: { id: "ID" },
+        prefetch: false,
+        tools: [
+          {
+            name: "GetProduct",
+            description: "Shows the details page for a specific product.",
+          },
+        ],
+      },
+    ],
+    resource: "index.html",
+    csp: {
+      resourceDomains: [],
+      connectDomains: [],
+      frameDomains: [],
+      redirectDomains: [],
+    },
+    ...overrides,
+  };
+}

package/src/testing/internal/utilities/spyOnConsole.ts

@@ -0,0 +1,29 @@
+import { vi, type Mock } from "vitest";
+
+const noop = () => {};
+
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug";
+
+type Spies<Keys extends ConsoleMethod[]> = Record<
+  Keys[number],
+  Mock<(message?: any, ...args: any[]) => void>
+>;
+
+export function spyOnConsole<Keys extends ConsoleMethod[]>(
+  ...spyOn: Keys
+): Spies<Keys> & Disposable {
+  const spies = {} as Spies<Keys>;
+  for (const key of spyOn) {
+    // @ts-ignore
+    spies[key] = vi.spyOn(console, key).mockImplementation(noop);
+  }
+
+  return {
+    ...spies,
+    [Symbol.dispose]() {
+      for (const spy of Object.values(spies) as Mock[]) {
+        spy.mockRestore();
+      }
+    },
+  };
+}

package/src/testing/internal/utilities/wait.ts

@@ -0,0 +1,3 @@
+export async function wait(ms: number) {
+  return new Promise<void>((res) => setTimeout(res, ms));
+}

package/src/tsconfig/core/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "moduleSuffixes": [".mcp", ".openai", ""]
+  }
+}

package/src/tsconfig/mcp/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "customConditions": ["mcp"],
+    "moduleSuffixes": [".mcp", ""]
+  }
+}