@apollo/client-ai-apps 0.1.0

package/src/hooks/useCallTool.test.ts

@@ -0,0 +1,46 @@
+import { expect, test, vi } from "vitest";
+import { useCallTool } from "./useCallTool";
+
+test("Should execute tool when returned function is called", async () => {
+  vi.stubGlobal("openai", {
+    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 callTool = useCallTool();
+  const result = await callTool("my-tool", { id: 1 });
+
+  expect(window.openai.callTool).toBeCalledWith("my-tool", { id: 1 });
+  expect(result).toMatchInlineSnapshot(`
+    {
+      "structuredContent": {
+        "data": {
+          "product": {
+            "__typename": "Product",
+            "description": "Awesome pen",
+            "id": "1",
+            "images": [],
+            "price": 1,
+            "rating": 5,
+            "title": "Pen",
+          },
+        },
+      },
+    }
+  `);
+});

package/src/hooks/useCallTool.ts

@@ -0,0 +1,8 @@
+type UseCallToolResult = <K>(toolId: string, variables?: Record<string, unknown> | undefined) => Promise<K>;
+
+export const useCallTool = (): UseCallToolResult => {
+  const callTool = async (toolId: string, variables: Record<string, unknown> | undefined = {}) =>
+    await window.openai?.callTool(toolId, variables);
+
+  return callTool;
+};

package/src/hooks/useOpenAiGlobal.test.ts

@@ -0,0 +1,54 @@
+import { expect, test, vi } from "vitest";
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+import { renderHook, act } from "@testing-library/react";
+import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
+
+test("Should update value when globals are updated and event it triggered", async () => {
+  vi.stubGlobal("openai", {
+    toolResponseMetadata: { toolName: "my-tool" },
+  });
+
+  const { result } = renderHook(() => useOpenAiGlobal("toolResponseMetadata"));
+  const beforeValue = result.current.toolName;
+
+  act(() => {
+    vi.stubGlobal("openai", {
+      toolResponseMetadata: { toolName: "my-other-tool" },
+    });
+    window.dispatchEvent(
+      new CustomEvent(SET_GLOBALS_EVENT_TYPE, {
+        detail: { globals: { toolResponseMetadata: { toolName: "my-other-tool" } } },
+      })
+    );
+  });
+
+  const afterValue = result.current.toolName;
+
+  expect(beforeValue).toBe("my-tool");
+  expect(afterValue).toBe("my-other-tool");
+});
+
+test("Should not update value when event key does not match the provided key", async () => {
+  vi.stubGlobal("openai", {
+    toolResponseMetadata: { toolName: "my-tool" },
+  });
+
+  const { result } = renderHook(() => useOpenAiGlobal("toolResponseMetadata"));
+  const beforeValue = result.current.toolName;
+
+  act(() => {
+    vi.stubGlobal("openai", {
+      toolResponseMetadata: { toolName: "my-other-tool" },
+    });
+    window.dispatchEvent(
+      new CustomEvent(SET_GLOBALS_EVENT_TYPE, {
+        detail: { globals: { toolInput: { id: 1 } } },
+      })
+    );
+  });
+
+  const afterValue = result.current.toolName;
+
+  expect(beforeValue).toBe("my-tool");
+  expect(afterValue).toBe("my-tool");
+});

package/src/hooks/useOpenAiGlobal.ts

@@ -0,0 +1,26 @@
+import { useSyncExternalStore } from "react";
+import { SET_GLOBALS_EVENT_TYPE, SetGlobalsEvent, OpenAiGlobals } from "../types/openai";
+
+export function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] {
+  return useSyncExternalStore(
+    (onChange) => {
+      const handleSetGlobal = (event: SetGlobalsEvent) => {
+        const value = event.detail.globals[key];
+        if (value === undefined) {
+          return;
+        }
+
+        onChange();
+      };
+
+      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
+        passive: true,
+      });
+
+      return () => {
+        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
+      };
+    },
+    () => window.openai[key]
+  );
+}

package/src/hooks/useRequestDisplayMode.ts

@@ -0,0 +1,7 @@
+import { DisplayMode } from "../types/openai";
+
+export const useRequestDisplayMode = () => {
+  return async (args: { mode: DisplayMode }) => {
+    await window.openai?.requestDisplayMode(args);
+  };
+};

package/src/hooks/useSendFollowUpMessage.ts

@@ -0,0 +1,7 @@
+export const useSendFollowUpMessage = () => {
+  return async (prompt: string) => {
+    await window.openai?.sendFollowUpMessage({
+      prompt,
+    });
+  };
+};

package/src/hooks/useToolEffect.tsx

@@ -0,0 +1,41 @@
+import React, { useEffect, useState } from "react";
+import { useToolName } from "./useToolName";
+import { useToolInput } from "./useToolInput";
+
+type ToolUseState = {
+  appName: string;
+  hasNavigated: boolean;
+  setHasNavigated: (v: boolean) => void;
+};
+
+const ToolUseContext = React.createContext<ToolUseState | null>(null);
+
+export function ToolUseProvider({ children, appName }: { children: any; appName: string }) {
+  const [hasNavigated, setHasNavigated] = useState(false);
+
+  return (
+    <ToolUseContext.Provider value={{ hasNavigated, setHasNavigated, appName }}>{children}</ToolUseContext.Provider>
+  );
+}
+
+export const useToolEffect = (
+  toolName: string | string[],
+  effect: (toolInput: any) => void,
+  deps: React.DependencyList = []
+) => {
+  const ctx = React.useContext(ToolUseContext);
+  const fullToolName = useToolName();
+  const toolInput = useToolInput();
+  if (!ctx) throw new Error("useToolEffect must be used within ToolUseProvider");
+
+  const toolNames = Array.isArray(toolName) ? toolName : [toolName];
+
+  useEffect(() => {
+    const matches = toolNames.some((name) => fullToolName === `${ctx.appName}--${name}`);
+
+    if (!ctx.hasNavigated && matches) {
+      effect(toolInput);
+      ctx.setHasNavigated(true);
+    }
+  }, [ctx.hasNavigated, ctx.setHasNavigated, ctx.appName, toolNames, fullToolName, toolInput, ...deps]);
+};

package/src/hooks/useToolInput.ts

@@ -0,0 +1,7 @@
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+
+export const useToolInput = () => {
+  const toolInput = useOpenAiGlobal("toolInput");
+
+  return toolInput;
+};

package/src/hooks/useToolName.ts

@@ -0,0 +1,7 @@
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+
+export const useToolName = () => {
+  const toolResponseMetadata = useOpenAiGlobal("toolResponseMetadata");
+
+  return toolResponseMetadata?.toolName;
+};

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./types/openai";
+export * from "./types/application-manifest";
+export * from "./hooks/useOpenAiGlobal";
+export * from "./hooks/useToolName";
+export * from "./hooks/useToolInput";
+export * from "./hooks/useSendFollowUpMessage";
+export * from "./hooks/useRequestDisplayMode";
+export * from "./hooks/useToolEffect";
+
+export * from "@apollo/client";
+export { ExtendedApolloClient as ApolloClient } from "./apollo_client/client";
+export { ExtendedApolloProvider as ApolloProvider } from "./apollo_client/provider";

package/src/types/application-manifest.ts

@@ -0,0 +1,32 @@
+export type ApplicationManifest = {
+  format: "apollo-ai-app-manifest";
+  version: "1";
+  name: string;
+  description: string;
+  hash: string;
+  resource: string;
+  operations: ManifestOperation[];
+};
+
+export type ManifestOperation = {
+  id: string;
+  name: string;
+  type: "query" | "mutation";
+  body: string;
+  variables: Record<string, string>;
+  prefetch: boolean;
+  prefetchID?: string;
+  tools: ManifestTool[];
+};
+
+export type ManifestTool = {
+  name: string;
+  description: string;
+  extraInputs?: ManifestExtraInput[];
+};
+
+export type ManifestExtraInput = {
+  name: string;
+  description: string;
+  type: "string" | "boolean" | "number";
+};

package/src/types/openai.ts

@@ -0,0 +1,90 @@
+type UnknownObject = any;
+
+declare global {
+  interface Window {
+    openai: API<any> & OpenAiGlobals;
+  }
+
+  interface WindowEventMap {
+    [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
+  }
+}
+
+export type OpenAiGlobals<
+  ToolInput extends UnknownObject = UnknownObject,
+  ToolOutput extends UnknownObject = UnknownObject,
+  ToolResponseMetadata extends UnknownObject = UnknownObject,
+  WidgetState extends UnknownObject = UnknownObject
+> = {
+  theme: Theme;
+  userAgent: UserAgent;
+  locale: string;
+
+  // layout
+  maxHeight: number;
+  displayMode: DisplayMode;
+  safeArea: SafeArea;
+
+  // state
+  toolInput: ToolInput;
+  toolOutput: ToolOutput | null;
+  toolResponseMetadata: ToolResponseMetadata | null;
+  widgetState: WidgetState | null;
+};
+
+export type API<WidgetState extends UnknownObject> = {
+  /** Calls a tool on your MCP. Returns the full response. */
+  callTool: (name: string, args: Record<string, unknown>) => Promise<any>;
+
+  /** Triggers a followup turn in the ChatGPT conversation */
+  sendFollowUpMessage: (args: { prompt: string }) => Promise<void>;
+
+  /** Opens an external link, redirects web page or mobile app */
+  openExternal(payload: { href: string }): void;
+
+  /** For transitioning an app from inline to fullscreen or pip */
+  requestDisplayMode: (args: { mode: DisplayMode }) => Promise<{
+    /**
+     * The granted display mode. The host may reject the request.
+     * For mobile, PiP is always coerced to fullscreen.
+     */
+    mode: DisplayMode;
+  }>;
+
+  setWidgetState: (state: WidgetState) => Promise<void>;
+};
+
+// Dispatched when any global changes in the host page
+export const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+export class SetGlobalsEvent extends CustomEvent<{
+  globals: Partial<OpenAiGlobals>;
+}> {
+  readonly type = SET_GLOBALS_EVENT_TYPE;
+}
+
+export type CallTool = (name: string, args: Record<string, unknown>) => Promise<any>;
+
+export type DisplayMode = "pip" | "inline" | "fullscreen";
+
+export type Theme = "light" | "dark";
+
+export type SafeAreaInsets = {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+
+export type SafeArea = {
+  insets: SafeAreaInsets;
+};
+
+export type DeviceType = "mobile" | "tablet" | "desktop" | "unknown";
+
+export type UserAgent = {
+  device: { type: DeviceType };
+  capabilities: {
+    hover: boolean;
+    touch: boolean;
+  };
+};

package/src/vite/index.ts

@@ -0,0 +1 @@
+export * from "./operation_manifest_plugin";

package/src/vite/operation_manifest_plugin.ts

@@ -0,0 +1,274 @@
+import { readFileSync, writeFileSync } from "fs";
+import { glob } from "glob";
+import { gqlPluckFromCodeStringSync } from "@graphql-tools/graphql-tag-pluck";
+import { createHash } from "crypto";
+import {
+  Kind,
+  ListTypeNode,
+  NamedTypeNode,
+  NonNullTypeNode,
+  parse,
+  print,
+  TypeNode,
+  ValueNode,
+  visit,
+  type DocumentNode,
+  type OperationDefinitionNode,
+} from "graphql";
+import { ApolloClient, ApolloLink, InMemoryCache } from "@apollo/client";
+import Observable from "rxjs";
+import path from "path";
+import fs from "fs";
+
+const root = process.cwd();
+
+// TODO: Do we need "validation" of the types for the different properties? Probably?
+const getRawValue = (node: ValueNode): any => {
+  switch (node.kind) {
+    case Kind.STRING:
+    case Kind.BOOLEAN:
+      return node.value;
+    case Kind.LIST:
+      return node.values.map(getRawValue);
+    case Kind.OBJECT:
+      return node.fields.reduce<Record<string, any>>((acc, field) => {
+        acc[field.name.value] = getRawValue(field.value);
+        return acc;
+      }, {});
+  }
+};
+
+export function getTypeName(type: TypeNode): string {
+  let t = type;
+  while (t.kind === "NonNullType" || t.kind === "ListType") {
+    t = (t as NonNullTypeNode | ListTypeNode).type;
+  }
+  return (t as NamedTypeNode).name.value;
+}
+
+export const OperationManifestPlugin = () => {
+  const cache = new Map();
+  let packageJson: any = null;
+  let config: any = null;
+
+  const clientCache = new InMemoryCache();
+  const client = new ApolloClient({
+    cache: clientCache,
+    link: new ApolloLink((operation) => {
+      const body = print(removeClientDirective(sortTopLevelDefinitions(operation.query)));
+      const name = operation.operationName;
+      const variables = (
+        operation.query.definitions.find((d) => d.kind === "OperationDefinition") as OperationDefinitionNode
+      ).variableDefinitions?.reduce(
+        (obj, varDef) => ({ ...obj, [varDef.variable.name.value]: getTypeName(varDef.type) }),
+        {}
+      );
+      const type = (
+        operation.query.definitions.find((d) => d.kind === "OperationDefinition") as OperationDefinitionNode
+      ).operation;
+      const prefetch = (
+        operation.query.definitions.find((d) => d.kind === "OperationDefinition") as OperationDefinitionNode
+      ).directives?.some((d) => d.name.value === "prefetch");
+      const id = createHash("sha256").update(body).digest("hex");
+      // TODO: For now, you can only have 1 operation marked as prefetch. In the future, we'll likely support more than 1, and the "prefetchId" will be defined on the `@prefetch` itself as an argument
+      const prefetchID = prefetch ? "__anonymous" : undefined;
+
+      const tools = (
+        operation.query.definitions.find((d) => d.kind === "OperationDefinition") as OperationDefinitionNode
+      ).directives
+        ?.filter((d) => d.name.value === "tool")
+        .map((directive) => {
+          const directiveArguments: Record<string, any> =
+            directive.arguments?.reduce((obj, arg) => ({ ...obj, [arg.name.value]: getRawValue(arg.value) }), {}) ?? {};
+          return {
+            name: directiveArguments["name"],
+            description: directiveArguments["description"],
+            extraInputs: directiveArguments["extraInputs"],
+          };
+        });
+
+      return Observable.of({ data: { id, name, type, body, variables, prefetch, prefetchID, tools } });
+    }),
+  });
+
+  const processFile = async (file: string) => {
+    const code = readFileSync(file, "utf-8");
+
+    if (!code.includes("gql")) return;
+
+    const fileHash = createHash("md5").update(code).digest("hex");
+    if (cache.get("file")?.hash === fileHash) return;
+    const sources = await gqlPluckFromCodeStringSync(file, code, {
+      modules: [
+        { name: "graphql-tag", identifier: "gql" },
+        { name: "@apollo/client", identifier: "gql" },
+      ],
+    }).map((source) => ({
+      node: parse(source.body),
+      file,
+      location: source.locationOffset,
+    }));
+
+    const operations = [];
+    for (const source of sources) {
+      const type = (source.node.definitions.find((d) => d.kind === "OperationDefinition") as OperationDefinitionNode)
+        .operation;
+
+      let result;
+      if (type === "query") {
+        result = await client.query({ query: source.node, fetchPolicy: "no-cache" });
+      } else if (type === "mutation") {
+        result = await client.mutate({ mutation: source.node, fetchPolicy: "no-cache" });
+      } else {
+        throw new Error("Found an unsupported operation type. Only Query and Mutation are supported.");
+      }
+      operations.push(result.data);
+    }
+
+    cache.set(file, {
+      file: file,
+      hash: fileHash,
+      operations,
+    });
+  };
+
+  const generateManifest = async () => {
+    const operations = Array.from(cache.values()).flatMap((entry) => entry.operations);
+    if (operations.filter((o) => o.prefetch).length > 1) {
+      throw new Error(
+        "Found multiple operations marked as `@prefetch`. You can only mark 1 operation with `@prefetch`."
+      );
+    }
+
+    let resource = "";
+    if (config.command === "serve") {
+      resource =
+        packageJson.entry?.[config.mode] ??
+        `http${config.server.https ? "s" : ""}://${config.server.host ?? "localhost"}:${config.server.port}`;
+    } else {
+      let entryPoint = packageJson.entry?.[config.mode];
+      if (entryPoint) {
+        resource = entryPoint;
+      } else if (config.mode === "production") {
+        resource = "index.html";
+      } else {
+        throw new Error(
+          `No entry point found for mode "${config.mode}". Entry points other than "development" and "production" must be defined in package.json file.`
+        );
+      }
+    }
+
+    const manifest = {
+      format: "apollo-ai-app-manifest",
+      version: "1",
+      name: packageJson.name,
+      description: packageJson.description,
+      hash: createHash("sha256").update(Date.now().toString()).digest("hex"),
+      operations: Array.from(cache.values()).flatMap((entry) => entry.operations),
+      resource,
+    };
+
+    if (config.command === "build") {
+      const dest = path.resolve(root, config.build.outDir, ".application-manifest.json");
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      writeFileSync(dest, JSON.stringify(manifest));
+    }
+    // Always write to the dev location so that the app can bundle the manifest content
+    writeFileSync(".application-manifest.json", JSON.stringify(manifest));
+  };
+
+  return {
+    name: "OperationManifest",
+
+    async configResolved(resolvedConfig: any) {
+      config = resolvedConfig;
+    },
+
+    async buildStart() {
+      // Read package.json on start
+      packageJson = JSON.parse(readFileSync("package.json", "utf-8"));
+
+      // Scan all files on startup
+      const files = await glob("src/**/*.{ts,tsx,js,jsx}");
+
+      for (const file of files) {
+        const fullPath = path.resolve(root, file);
+        await processFile(fullPath);
+      }
+
+      // We don't want to do this here on builds cause it just gets overwritten anyways. We'll call it on writeBundle instead.
+      if (config.command === "serve") {
+        await generateManifest();
+      }
+    },
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    configureServer(server: any) {
+      server.watcher.on("change", async (file: string) => {
+        if (file.endsWith("package.json")) {
+          packageJson = JSON.parse(readFileSync("package.json", "utf-8"));
+          await generateManifest();
+        } else if (file.match(/\.(jsx?|tsx?)$/)) {
+          await processFile(file);
+          await generateManifest();
+        }
+      });
+    },
+
+    async writeBundle() {
+      await generateManifest();
+    },
+  };
+};
+
+// Sort the definitions in this document so that operations come before fragments,
+// and so that each kind of definition is sorted by name.
+export function sortTopLevelDefinitions(query: DocumentNode): DocumentNode {
+  const definitions = [...query.definitions];
+  // We want to avoid unnecessary dependencies, so write out a comparison
+  // function instead of using _.orderBy.
+  definitions.sort((a, b) => {
+    // This is a reverse sort by kind, so that OperationDefinition precedes FragmentDefinition.
+    if (a.kind > b.kind) {
+      return -1;
+    }
+    if (a.kind < b.kind) {
+      return 1;
+    }
+
+    // Extract the name from each definition. Jump through some hoops because
+    // non-executable definitions don't have to have names (even though any
+    // DocumentNode actually passed here should only have executable
+    // definitions).
+    const aName = a.kind === "OperationDefinition" || a.kind === "FragmentDefinition" ? a.name?.value ?? "" : "";
+    const bName = b.kind === "OperationDefinition" || b.kind === "FragmentDefinition" ? b.name?.value ?? "" : "";
+
+    // Sort by name ascending.
+    if (aName < bName) {
+      return -1;
+    }
+    if (aName > bName) {
+      return 1;
+    }
+
+    // Assuming that the document is "valid", no operation or fragment name can appear
+    // more than once, so we don't need to differentiate further to have a deterministic
+    // sort.
+    return 0;
+  });
+  return {
+    ...query,
+    definitions,
+  };
+}
+
+function removeClientDirective(doc: DocumentNode) {
+  return visit(doc, {
+    OperationDefinition(node) {
+      return {
+        ...node,
+        directives: node.directives?.filter((d) => d.name.value !== "prefetch" && d.name.value !== "tool"),
+      };
+    },
+  });
+}

package/vitest-setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "happy-dom",
+    setupFiles: ["./vitest-setup.ts"],
+    mockReset: true,
+    unstubGlobals: true,
+  },
+});