@apollo/client-ai-apps 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@apollo/client-ai-apps",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./vite": "./dist/vite/index.js"
+  },
+  "scripts": {
+    "dev": "node ./scripts/dev.mjs",
+    "build": "npm run build:react && npm run build:vite",
+    "build:react": "node ./scripts/build.mjs && tsc src/index.ts --emitDeclarationOnly --declaration --outDir dist --skipLibCheck --lib ES2015,DOM --target ES2015 --moduleResolution bundler --jsx react",
+    "build:vite": "node ./scripts/build-vite.mjs && tsc src/vite/index.ts --emitDeclarationOnly --declaration --outDir dist/vite --skipLibCheck --lib ES2015,DOM --target ES2020 --module esnext --moduleResolution node  --allowSyntheticDefaultImports",
+    "changeset:new": "npx @changesets/cli",
+    "changeset:version": "npx @changesets/cli version",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest --coverage"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.2",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/coverage-v8": "^4.0.13",
+    "esbuild": "^0.25.12",
+    "graphql": "^16.9.0",
+    "happy-dom": "^20.0.10",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.13"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "dependencies": {
+    "@apollo/client": "^4.0.9",
+    "@graphql-tools/graphql-tag-pluck": "^8.3.23",
+    "crypto-hash": "^4.0.0",
+    "glob": "^11.0.3"
+  }
+}

package/scripts/build-vite.mjs

@@ -0,0 +1,18 @@
+import * as esbuild from "esbuild";
+
+// Separately build Vite plugin
+await esbuild.build({
+  entryPoints: ["src/vite/index.ts"],
+  bundle: true,
+  outdir: "dist/vite",
+  platform: "node",
+  format: "esm",
+  external: [
+    "glob",
+    "@graphql-tools/graphql-tag-pluck",
+    "@graphql-tools/graphql-tag-pluck",
+    "graphql",
+    "@apollo/client",
+    "rxjs",
+  ],
+});

package/scripts/build.mjs

@@ -0,0 +1,7 @@
+import * as esbuild from "esbuild";
+import { sharedConfig } from "./shared.mjs";
+
+// Build react components
+await esbuild.build({
+  ...sharedConfig,
+});

package/scripts/dev.mjs

@@ -0,0 +1,21 @@
+import * as esbuild from "esbuild";
+import { sharedConfig } from "./shared.mjs";
+
+console.log("Starting dev mode...");
+
+let ctx = await esbuild.context({
+  ...sharedConfig,
+  plugins: [
+    {
+      name: "rebuild-logger",
+      setup(build) {
+        build.onEnd((result) => {
+          console.log(`Rebuilt at ${new Date().toLocaleTimeString()} (${result.errors.length} errors)`);
+        });
+      },
+    },
+  ],
+});
+
+console.log("Watching for changes...");
+await ctx.watch();

package/scripts/shared.mjs

@@ -0,0 +1,9 @@
+export const sharedConfig = {
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  outdir: "dist",
+  platform: "browser",
+  format: "esm",
+  packages: "external",
+  external: ["react", "react-dom"],
+};

package/src/apollo_client/client.test.ts

@@ -0,0 +1,411 @@
+import { expect, test, describe, vi } from "vitest";
+import { ExtendedApolloClient } from "./client";
+import { ApplicationManifest } from "../types/application-manifest";
+import { parse } from "graphql";
+
+describe("Client Basics", () => {
+  test("Should execute tool call when client.query is called", async () => {
+    vi.stubGlobal("openai", {
+      toolInput: {},
+      toolOutput: {},
+      toolResponseMetadata: {
+        toolName: "the-store--Get Product",
+      },
+      callTool: vi.fn(async (name: string, args: Record<string, unknown>) => {
+        return {
+          structuredContent: {
+            data: {
+              product: {
+                id: "1",
+                title: "Pen",
+                rating: 5,
+                price: 1.0,
+                description: "Awesome pen",
+                images: [],
+                __typename: "Product",
+              },
+            },
+          },
+        };
+      }),
+    });
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      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: "Get Product", description: "Shows the details page for a specific product." }],
+        },
+      ],
+      resource: "index.html",
+    };
+
+    const client = new ExtendedApolloClient({
+      manifest: manifest as ApplicationManifest,
+    });
+
+    const variables = { id: "1" };
+    await client.query({ query: parse(manifest.operations[0].body), variables });
+
+    expect(window.openai.callTool).toBeCalledWith("execute", { query: manifest.operations[0].body, variables });
+    expect(client.extract()).toMatchInlineSnapshot(`
+      {
+        "Product:1": {
+          "__typename": "Product",
+          "description": "Awesome pen",
+          "id": "1",
+          "images": [],
+          "price": 1,
+          "rating": 5,
+          "title": "Pen",
+        },
+        "ROOT_QUERY": {
+          "__typename": "Query",
+          "product({"id":"1"})": {
+            "__ref": "Product:1",
+          },
+        },
+      }
+    `);
+  });
+});
+
+describe("prefetchData", () => {
+  test("Should cache tool response when data is provided", async () => {
+    vi.stubGlobal("openai", {
+      toolInput: {
+        id: 1,
+      },
+      toolOutput: {
+        result: {
+          data: {
+            product: {
+              id: "1",
+              title: "Pen",
+              rating: 5,
+              price: 1.0,
+              description: "Awesome pen",
+              images: [],
+              __typename: "Product",
+            },
+          },
+        },
+      },
+      toolResponseMetadata: {
+        toolName: "the-store--Get Product",
+      },
+    });
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      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: "Get Product", description: "Shows the details page for a specific product." }],
+        },
+      ],
+      resource: "index.html",
+    };
+
+    const client = new ExtendedApolloClient({
+      manifest: manifest as ApplicationManifest,
+    });
+    await client.prefetchData();
+
+    expect(client.extract()).toMatchInlineSnapshot(`
+      {
+        "Product:1": {
+          "__typename": "Product",
+          "description": "Awesome pen",
+          "id": "1",
+          "images": [],
+          "price": 1,
+          "rating": 5,
+          "title": "Pen",
+        },
+        "ROOT_QUERY": {
+          "__typename": "Query",
+          "product({"id":1})": {
+            "__ref": "Product:1",
+          },
+        },
+      }
+    `);
+  });
+
+  test("Should cache prefetched data when prefetched data is provided", async () => {
+    vi.stubGlobal("openai", {
+      toolInput: {},
+      toolOutput: {
+        result: {},
+        prefetch: {
+          __anonymous: {
+            data: {
+              topProducts: [
+                {
+                  id: "2",
+                  title: "iPhone 17",
+                  rating: 5,
+                  price: 999.99,
+                  description: "Awesome phone",
+                  images: [],
+                  __typename: "Product",
+                },
+              ],
+            },
+          },
+        },
+      },
+      toolResponseMetadata: {
+        toolName: "the-store--Get Product",
+      },
+    });
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      name: "the-store",
+      description: "An online store selling a variety of high quality products across many different categories.",
+      hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
+      operations: [
+        {
+          id: "cd0d52159b9003e791de97c6a76efa03d34fe00cee278d1a3f4bfcec5fb3e1e6",
+          name: "TopProducts",
+          type: "query",
+          body: "query TopProducts {\n  topProducts {\n    id\n    title\n    rating\n    price\n    __typename\n  }\n}",
+          variables: {},
+          prefetch: true,
+          prefetchID: "__anonymous",
+          tools: [{ name: "Top Products", description: "Shows the currently highest rated products." }],
+        },
+      ],
+      resource: "index.html",
+    };
+
+    const client = new ExtendedApolloClient({
+      manifest: manifest as ApplicationManifest,
+    });
+    await client.prefetchData();
+
+    expect(client.extract()).toMatchInlineSnapshot(`
+      {
+        "Product:2": {
+          "__typename": "Product",
+          "id": "2",
+          "price": 999.99,
+          "rating": 5,
+          "title": "iPhone 17",
+        },
+        "ROOT_QUERY": {
+          "__typename": "Query",
+          "topProducts": [
+            {
+              "__ref": "Product:2",
+            },
+          ],
+        },
+      }
+    `);
+  });
+
+  test("Should cache both prefetch and tool response when both are provided", async () => {
+    vi.stubGlobal("openai", {
+      toolInput: {
+        id: 1,
+      },
+      toolOutput: {
+        result: {
+          data: {
+            product: {
+              id: "1",
+              title: "Pen",
+              rating: 5,
+              price: 1.0,
+              description: "Awesome pen",
+              images: [],
+              __typename: "Product",
+            },
+          },
+        },
+        prefetch: {
+          __anonymous: {
+            data: {
+              topProducts: [
+                {
+                  id: "2",
+                  title: "iPhone 17",
+                  rating: 5,
+                  price: 999.99,
+                  description: "Awesome phone",
+                  images: [],
+                  __typename: "Product",
+                },
+              ],
+            },
+          },
+        },
+      },
+      toolResponseMetadata: {
+        toolName: "the-store--Get Product",
+      },
+    });
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      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: "Get Product", description: "Shows the details page for a specific product." }],
+        },
+        {
+          id: "cd0d52159b9003e791de97c6a76efa03d34fe00cee278d1a3f4bfcec5fb3e1e6",
+          name: "TopProducts",
+          type: "query",
+          body: "query TopProducts {\n  topProducts {\n    id\n    title\n    rating\n    price\n    __typename\n  }\n}",
+          variables: {},
+          prefetch: true,
+          prefetchID: "__anonymous",
+          tools: [{ name: "Top Products", description: "Shows the currently highest rated products." }],
+        },
+      ],
+      resource: "index.html",
+    };
+
+    const client = new ExtendedApolloClient({
+      manifest: manifest as ApplicationManifest,
+    });
+    await client.prefetchData();
+
+    expect(client.extract()).toMatchInlineSnapshot(`
+      {
+        "Product:1": {
+          "__typename": "Product",
+          "description": "Awesome pen",
+          "id": "1",
+          "images": [],
+          "price": 1,
+          "rating": 5,
+          "title": "Pen",
+        },
+        "Product:2": {
+          "__typename": "Product",
+          "id": "2",
+          "price": 999.99,
+          "rating": 5,
+          "title": "iPhone 17",
+        },
+        "ROOT_QUERY": {
+          "__typename": "Query",
+          "product({"id":1})": {
+            "__ref": "Product:1",
+          },
+          "topProducts": [
+            {
+              "__ref": "Product:2",
+            },
+          ],
+        },
+      }
+    `);
+  });
+
+  test("Should exclude extra inputs when writing to cache", async () => {
+    vi.stubGlobal("openai", {
+      toolInput: {
+        id: 1,
+        myOtherThing: 2,
+      },
+      toolOutput: {
+        result: {
+          data: {
+            product: {
+              id: "1",
+              title: "Pen",
+              rating: 5,
+              price: 1.0,
+              description: "Awesome pen",
+              images: [],
+              __typename: "Product",
+            },
+          },
+        },
+      },
+      toolResponseMetadata: {
+        toolName: "the-store--Get Product",
+      },
+    });
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      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: "Get Product", description: "Shows the details page for a specific product." }],
+        },
+      ],
+      resource: "index.html",
+    };
+
+    const client = new ExtendedApolloClient({
+      manifest: manifest as ApplicationManifest,
+    });
+    await client.prefetchData();
+
+    expect(client.extract()).toMatchInlineSnapshot(`
+      {
+        "Product:1": {
+          "__typename": "Product",
+          "description": "Awesome pen",
+          "id": "1",
+          "images": [],
+          "price": 1,
+          "rating": 5,
+          "title": "Pen",
+        },
+        "ROOT_QUERY": {
+          "__typename": "Query",
+          "product({"id":1})": {
+            "__ref": "Product:1",
+          },
+        },
+      }
+    `);
+  });
+});

package/src/apollo_client/client.ts

@@ -0,0 +1,90 @@
+import { ApolloClient, ApolloLink, InMemoryCache } from "@apollo/client";
+import * as Observable from "rxjs";
+import { selectHttpOptionsAndBody } from "@apollo/client/link/http";
+import { fallbackHttpConfig } from "@apollo/client/link/http";
+import { DocumentTransform } from "@apollo/client";
+import { removeDirectivesFromDocument } from "@apollo/client/utilities/internal";
+import { parse } from "graphql";
+import "../types/openai";
+import { ApplicationManifest } from "../types/application-manifest";
+
+// TODO: In the future if/when we support PQs again, do pqLink.concat(toolCallLink)
+// Commenting this out for now.
+//  import { sha256 } from "crypto-hash";
+// import { PersistedQueryLink } from "@apollo/client/link/persisted-queries";
+// const pqLink = new PersistedQueryLink({
+//   sha256: (queryString) => sha256(queryString),
+// });
+
+// Normally, ApolloClient uses an HttpLink and sends the graphql request over HTTP
+// In our case, we're are sending the graphql request over the "execute" tool call
+const toolCallLink = new ApolloLink((operation) => {
+  const context = operation.getContext();
+  const contextConfig = {
+    http: context.http,
+    options: context.fetchOptions,
+    credentials: context.credentials,
+    headers: context.headers,
+  };
+  const { query, variables } = selectHttpOptionsAndBody(operation, fallbackHttpConfig, contextConfig).body;
+
+  return Observable.from(window.openai.callTool("execute", { query, variables })).pipe(
+    Observable.map((result) => ({ data: result.structuredContent.data }))
+  );
+});
+
+// This allows us to extend the options with the "manifest" option AND make link/cache optional (they are normally required)
+type ExtendedApolloClientOptions = Omit<ApolloClient.Options, "link" | "cache"> & {
+  link?: ApolloClient.Options["link"];
+  cache?: ApolloClient.Options["cache"];
+  manifest: ApplicationManifest;
+};
+
+export class ExtendedApolloClient extends ApolloClient {
+  manifest: ApplicationManifest;
+
+  constructor(options: ExtendedApolloClientOptions) {
+    super({
+      link: toolCallLink,
+      cache: options.cache ?? new InMemoryCache(),
+      // Strip out the prefetch/tool directives so they don't get sent with the operation to the server
+      documentTransform: new DocumentTransform((document) => {
+        return removeDirectivesFromDocument([{ name: "prefetch" }, { name: "tool" }], document)!;
+      }),
+    });
+
+    this.manifest = options.manifest;
+  }
+
+  async prefetchData() {
+    // Write prefetched data to the cache
+    this.manifest.operations.forEach((operation) => {
+      if (operation.prefetch && operation.prefetchID && window.openai.toolOutput.prefetch[operation.prefetchID]) {
+        this.writeQuery({
+          query: parse(operation.body),
+          data: window.openai.toolOutput.prefetch[operation.prefetchID].data,
+        });
+      }
+
+      // If this operation has the tool that matches up with the tool that was executed, write the tool result to the cache
+      if (
+        operation.tools?.find(
+          (tool) => `${this.manifest.name}--${tool.name}` === window.openai.toolResponseMetadata.toolName
+        )
+      ) {
+        // We need to include the variables that were used as part of the tool call so that we get a proper cache entry
+        // However, we only want to include toolInput's that were graphql operation (ignore extraInputs)
+        const variables = Object.keys(window.openai.toolInput).reduce(
+          (obj, key) => (operation.variables[key] ? { ...obj, [key]: window.openai.toolInput[key] } : obj),
+          {}
+        );
+
+        this.writeQuery({
+          query: parse(operation.body),
+          data: window.openai.toolOutput.result.data,
+          variables,
+        });
+      }
+    });
+  }
+}

package/src/apollo_client/provider.test.tsx

@@ -0,0 +1,41 @@
+import { expect, test, vi } from "vitest";
+import { ExtendedApolloProvider } from "./provider";
+import { render } from "@testing-library/react";
+import { ExtendedApolloClient } from "./client";
+import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
+
+test("Should call prefetch data when window.open is immediately available", () => {
+  vi.stubGlobal("openai", {
+    toolOutput: {},
+  });
+
+  const client = {
+    prefetchData: vi.fn(async () => {}),
+  } as unknown as ExtendedApolloClient;
+
+  render(<ExtendedApolloProvider client={client} />);
+
+  expect(client.prefetchData).toBeCalled();
+});
+
+test("Should NOT call prefetch data when window.open is not immediately available", () => {
+  const client = {
+    prefetchData: vi.fn(async () => {}),
+  } as unknown as ExtendedApolloClient;
+
+  render(<ExtendedApolloProvider client={client} />);
+
+  expect(client.prefetchData).not.toBeCalled();
+});
+
+test("Should call prefetch data when window.open is not immediately available and event is sent", () => {
+  const client = {
+    prefetchData: vi.fn(async () => {}),
+  } as unknown as ExtendedApolloClient;
+
+  render(<ExtendedApolloProvider client={client} />);
+
+  window.dispatchEvent(new CustomEvent(SET_GLOBALS_EVENT_TYPE));
+
+  expect(client.prefetchData).toBeCalled();
+});

package/src/apollo_client/provider.tsx

@@ -0,0 +1,32 @@
+import React, { useEffect, useState } from "react";
+import { ApolloProvider } from "@apollo/client/react";
+import { ExtendedApolloClient } from "./client";
+import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
+
+export const ExtendedApolloProvider = ({
+  children,
+  client,
+}: React.PropsWithChildren<{ client: ExtendedApolloClient }>) => {
+  const [hasPreloaded, setHasPreloaded] = useState(false);
+
+  // This is to prevent against a race condition. We don't know if window.openai will be available when this loads or if it will become available shortly after.
+  // So... we create the event listener and whenever it is available, then we can process the prefetch/tool data.
+  // In practice, this should be pretty much instant
+  useEffect(() => {
+    const prefetchData = async () => {
+      await client.prefetchData();
+      setHasPreloaded(true);
+      window.removeEventListener(SET_GLOBALS_EVENT_TYPE, prefetchData);
+    };
+
+    window.addEventListener(SET_GLOBALS_EVENT_TYPE, prefetchData, {
+      passive: true,
+    });
+
+    if (window.openai?.toolOutput) {
+      window.dispatchEvent(new CustomEvent(SET_GLOBALS_EVENT_TYPE));
+    }
+  }, [setHasPreloaded]);
+
+  return hasPreloaded ? <ApolloProvider client={client}>{children}</ApolloProvider> : null;
+};