@apollo/client-ai-apps 0.2.4 → 0.3.1

package/src/{apollo_client/client.test.ts → core/__tests__/ApolloClient.test.ts}

@@ -1,7 +1,9 @@
 import { expect, test, describe, vi } from "vitest";
-import { ExtendedApolloClient } from "./client";
-import { ApplicationManifest } from "../types/application-manifest";
+import { ApolloClient } from "../ApolloClient";
+import { ApplicationManifest } from "../../types/application-manifest";
 import { parse } from "graphql";
+import { ApolloLink, HttpLink, InMemoryCache } from "@apollo/client";
+import { ToolCallLink } from "../../link/ToolCallLink";
 
 describe("Client Basics", () => {
   test("Should execute tool call when client.query is called", async () => {
@@ -34,7 +36,8 @@ describe("Client Basics", () => {
       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.",
+      description:
+        "An online store selling a variety of high quality products across many different categories.",
       hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
       operations: [
         {
@@ -44,20 +47,32 @@ describe("Client Basics", () => {
           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." }],
+          tools: [
+            {
+              name: "Get Product",
+              description: "Shows the details page for a specific product.",
+            },
+          ],
         },
       ],
       resource: "index.html",
     };
 
-    const client = new ExtendedApolloClient({
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
       manifest: manifest as ApplicationManifest,
     });
 
     const variables = { id: "1" };
-    await client.query({ query: parse(manifest.operations[0].body), variables });
+    await client.query({
+      query: parse(manifest.operations[0].body),
+      variables,
+    });
 
-    expect(window.openai.callTool).toBeCalledWith("execute", { query: manifest.operations[0].body, variables });
+    expect(window.openai.callTool).toBeCalledWith("execute", {
+      query: manifest.operations[0].body,
+      variables,
+    });
     expect(client.extract()).toMatchInlineSnapshot(`
       {
         "Product:1": {
@@ -110,7 +125,8 @@ describe("prefetchData", () => {
       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.",
+      description:
+        "An online store selling a variety of high quality products across many different categories.",
       hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
       operations: [
         {
@@ -120,13 +136,19 @@ describe("prefetchData", () => {
           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." }],
+          tools: [
+            {
+              name: "Get Product",
+              description: "Shows the details page for a specific product.",
+            },
+          ],
         },
       ],
       resource: "index.html",
     };
 
-    const client = new ExtendedApolloClient({
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
       manifest: manifest as ApplicationManifest,
     });
     await client.prefetchData();
@@ -184,7 +206,8 @@ describe("prefetchData", () => {
       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.",
+      description:
+        "An online store selling a variety of high quality products across many different categories.",
       hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
       operations: [
         {
@@ -195,13 +218,19 @@ describe("prefetchData", () => {
           variables: {},
           prefetch: true,
           prefetchID: "__anonymous",
-          tools: [{ name: "Top Products", description: "Shows the currently highest rated products." }],
+          tools: [
+            {
+              name: "Top Products",
+              description: "Shows the currently highest rated products.",
+            },
+          ],
         },
       ],
       resource: "index.html",
     };
 
-    const client = new ExtendedApolloClient({
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
       manifest: manifest as ApplicationManifest,
     });
     await client.prefetchData();
@@ -273,7 +302,8 @@ describe("prefetchData", () => {
       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.",
+      description:
+        "An online store selling a variety of high quality products across many different categories.",
       hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
       operations: [
         {
@@ -283,7 +313,12 @@ describe("prefetchData", () => {
           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." }],
+          tools: [
+            {
+              name: "Get Product",
+              description: "Shows the details page for a specific product.",
+            },
+          ],
         },
         {
           id: "cd0d52159b9003e791de97c6a76efa03d34fe00cee278d1a3f4bfcec5fb3e1e6",
@@ -293,13 +328,19 @@ describe("prefetchData", () => {
           variables: {},
           prefetch: true,
           prefetchID: "__anonymous",
-          tools: [{ name: "Top Products", description: "Shows the currently highest rated products." }],
+          tools: [
+            {
+              name: "Top Products",
+              description: "Shows the currently highest rated products.",
+            },
+          ],
         },
       ],
       resource: "index.html",
     };
 
-    const client = new ExtendedApolloClient({
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
       manifest: manifest as ApplicationManifest,
     });
     await client.prefetchData();
@@ -367,7 +408,8 @@ describe("prefetchData", () => {
       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.",
+      description:
+        "An online store selling a variety of high quality products across many different categories.",
       hash: "f6a24922f6ad6ed8c2aa57baf3b8242ae5f38a09a6df3f2693077732434c4256",
       operations: [
         {
@@ -377,13 +419,19 @@ describe("prefetchData", () => {
           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." }],
+          tools: [
+            {
+              name: "Get Product",
+              description: "Shows the details page for a specific product.",
+            },
+          ],
         },
       ],
       resource: "index.html",
     };
 
-    const client = new ExtendedApolloClient({
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
       manifest: manifest as ApplicationManifest,
     });
     await client.prefetchData();
@@ -409,3 +457,167 @@ describe("prefetchData", () => {
     `);
   });
 });
+
+describe("custom links", () => {
+  test("allows for custom links provided to the constructor", 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 = createManifest();
+    const linkHandler = vi.fn<ApolloLink.RequestHandler>((operation, forward) =>
+      forward(operation)
+    );
+
+    const client = new ApolloClient({
+      manifest,
+      cache: new InMemoryCache(),
+      link: ApolloLink.from([new ApolloLink(linkHandler), new ToolCallLink()]),
+    });
+
+    const variables = { id: "1" };
+    const query = parse(manifest.operations[0].body);
+
+    await expect(client.query({ query, variables })).resolves.toStrictEqual({
+      data: {
+        product: {
+          id: "1",
+          title: "Pen",
+          rating: 5,
+          price: 1.0,
+          description: "Awesome pen",
+          images: [],
+          __typename: "Product",
+        },
+      },
+    });
+
+    expect(linkHandler).toHaveBeenCalledOnce();
+    expect(linkHandler).toHaveBeenCalledWith(
+      expect.objectContaining({ query, variables, operationType: "query" }),
+      expect.any(Function)
+    );
+  });
+
+  test("enforces ToolCallLink as terminating link", async () => {
+    const manifest = createManifest();
+    const expectedError = new Error(
+      "The terminating link must be a `ToolCallLink`. If you are using a `split` link, ensure the `right` branch uses a `ToolCallLink` as the terminating link."
+    );
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: new HttpLink(),
+      });
+    }).toThrow(expectedError);
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: new ApolloLink(),
+      });
+    }).toThrow(expectedError);
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: ApolloLink.from([new ApolloLink(), new HttpLink()]),
+      });
+    }).toThrow(expectedError);
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: ApolloLink.split(() => true, new ApolloLink(), new HttpLink()),
+      });
+    }).toThrow(expectedError);
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: ApolloLink.split(() => true, new ToolCallLink(), new HttpLink()),
+      });
+    }).toThrow(expectedError);
+
+    // Allow you to use a custom terminating link for `split` links if the
+    // custom link is the `left` branch link.
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: ApolloLink.split(() => true, new HttpLink(), new ToolCallLink()),
+      });
+    }).not.toThrow(expectedError);
+
+    expect(() => {
+      new ApolloClient({
+        manifest,
+        cache: new InMemoryCache(),
+        link: ApolloLink.split(
+          () => true,
+          new ToolCallLink(),
+          new ToolCallLink()
+        ),
+      });
+    }).not.toThrow();
+  });
+});
+
+function createManifest(
+  overrides?: Partial<ApplicationManifest>
+): ApplicationManifest {
+  return {
+    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",
+    csp: { resourceDomains: [], connectDomains: [] },
+    ...overrides,
+  };
+}

package/src/index.ts

@@ -1,12 +1,38 @@
-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 type {
+  API,
+  CallTool,
+  DeviceType,
+  DisplayMode,
+  OpenAiGlobals,
+  SafeArea,
+  SafeAreaInsets,
+  Theme,
+  UserAgent,
+  UnknownObject,
+} from "./types/openai";
+export { SET_GLOBALS_EVENT_TYPE, SetGlobalsEvent } from "./types/openai";
+
+export type {
+  ApplicationManifest,
+  ManifestOperation,
+  ManifestTool,
+  ManifestExtraInput,
+  ManifestCsp,
+} from "./types/application-manifest";
+
+export { ToolUseProvider } from "./react/context/ToolUseContext";
+export { useOpenAiGlobal } from "./react/hooks/useOpenAiGlobal";
+export { useToolName } from "./react/hooks/useToolName";
+export { useToolInput } from "./react/hooks/useToolInput";
+export { useSendFollowUpMessage } from "./react/hooks/useSendFollowUpMessage";
+export { useRequestDisplayMode } from "./react/hooks/useRequestDisplayMode";
+export { useToolEffect } from "./react/hooks/useToolEffect";
+export { useOpenExternal } from "./react/hooks/useOpenExternal";
+export { useToolOutput } from "./react/hooks/useToolOutput";
+export { useToolResponseMetadata } from "./react/hooks/useToolResponseMetadata";
+export { useWidgetState } from "./react/hooks/useWidgetState";
 
 export * from "@apollo/client";
-export { ExtendedApolloClient as ApolloClient } from "./apollo_client/client";
-export { ExtendedApolloProvider as ApolloProvider } from "./apollo_client/provider";
+export { ApolloClient } from "./core/ApolloClient";
+export { ApolloProvider } from "./react/ApolloProvider";
+export { ToolCallLink } from "./link/ToolCallLink";

package/src/link/ToolCallLink.ts

@@ -0,0 +1,49 @@
+import { ApolloLink, Observable } from "@apollo/client";
+import { from, map } from "rxjs";
+import {
+  fallbackHttpConfig,
+  selectHttpOptionsAndBody,
+} from "@apollo/client/link/http";
+
+/**
+ * A terminating link that sends a GraphQL request through an agent tool call.
+ * When providing a custom link chain to `ApolloClient`, `ApolloClient` will
+ * validate that the terminating link is an instance of this link.
+ *
+ * @example Provding a custom link chain
+ *
+ * ```ts
+ * import { ApolloLink } from "@apollo/client";
+ * import { ApolloClient, ToolCallLink } from "@apollo/client-ai-apps";
+ *
+ * const link = ApolloLink.from([
+ *   ...otherLinks,
+ *   new ToolCallLink()
+ * ]);
+ *
+ * const client = new ApolloClient({
+ *   link,
+ *   // ...
+ * });
+ * ```
+ */
+export class ToolCallLink extends ApolloLink {
+  request(operation: ApolloLink.Operation): Observable<ApolloLink.Result> {
+    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 from(window.openai.callTool("execute", { query, variables })).pipe(
+      map((result) => ({ data: result.structuredContent.data }))
+    );
+  }
+}

package/src/{apollo_client/provider.tsx → react/ApolloProvider.tsx}

@@ -1,12 +1,16 @@
-import React, { useEffect, useState } from "react";
-import { ApolloProvider } from "@apollo/client/react";
-import { ExtendedApolloClient } from "./client";
+import React, { ReactNode, useEffect, useState } from "react";
+import { ApolloProvider as BaseApolloProvider } from "@apollo/client/react";
+import { ApolloClient } from "../core/ApolloClient";
 import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
 
-export const ExtendedApolloProvider = ({
-  children,
-  client,
-}: React.PropsWithChildren<{ client: ExtendedApolloClient }>) => {
+export declare namespace ApolloProvider {
+  export interface Props {
+    children?: ReactNode;
+    client: ApolloClient;
+  }
+}
+
+export const ApolloProvider = ({ children, client }: ApolloProvider.Props) => {
   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.
@@ -26,7 +30,13 @@ export const ExtendedApolloProvider = ({
     if (window.openai?.toolOutput) {
       window.dispatchEvent(new CustomEvent(SET_GLOBALS_EVENT_TYPE));
     }
-  }, [setHasPreloaded]);
 
-  return hasPreloaded ? <ApolloProvider client={client}>{children}</ApolloProvider> : null;
+    return () => {
+      window.removeEventListener(SET_GLOBALS_EVENT_TYPE, prefetchData);
+    };
+  }, []);
+
+  return hasPreloaded ?
+      <BaseApolloProvider client={client}>{children}</BaseApolloProvider>
+    : null;
 };

package/src/{apollo_client/provider.test.tsx → react/__tests__/ApolloProvider.test.tsx}

@@ -1,8 +1,8 @@
 import { expect, test, vi } from "vitest";
-import { ExtendedApolloProvider } from "./provider";
+import { ApolloProvider } from "../ApolloProvider";
 import { render } from "@testing-library/react";
-import { ExtendedApolloClient } from "./client";
-import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
+import { ApolloClient } from "../../core/ApolloClient";
+import { SET_GLOBALS_EVENT_TYPE } from "../../types/openai";
 
 test("Should call prefetch data when window.open is immediately available", () => {
   vi.stubGlobal("openai", {
@@ -11,9 +11,9 @@ test("Should call prefetch data when window.open is immediately available", () =
 
   const client = {
     prefetchData: vi.fn(async () => {}),
-  } as unknown as ExtendedApolloClient;
+  } as unknown as ApolloClient;
 
-  render(<ExtendedApolloProvider client={client} />);
+  render(<ApolloProvider client={client} />);
 
   expect(client.prefetchData).toBeCalled();
 });
@@ -21,9 +21,9 @@ test("Should call prefetch data when window.open is immediately available", () =
 test("Should NOT call prefetch data when window.open is not immediately available", () => {
   const client = {
     prefetchData: vi.fn(async () => {}),
-  } as unknown as ExtendedApolloClient;
+  } as unknown as ApolloClient;
 
-  render(<ExtendedApolloProvider client={client} />);
+  render(<ApolloProvider client={client} />);
 
   expect(client.prefetchData).not.toBeCalled();
 });
@@ -31,9 +31,9 @@ test("Should NOT call prefetch data when window.open is not immediately availabl
 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;
+  } as unknown as ApolloClient;
 
-  render(<ExtendedApolloProvider client={client} />);
+  render(<ApolloProvider client={client} />);
 
   window.dispatchEvent(new CustomEvent(SET_GLOBALS_EVENT_TYPE));
 

package/src/react/context/ToolUseContext.tsx

@@ -0,0 +1,30 @@
+import React, { createContext, ReactNode, useContext, useState } from "react";
+
+interface ToolUseState {
+  appName: string;
+  hasNavigated: boolean;
+  setHasNavigated: (v: boolean) => void;
+}
+
+const ToolUseContext = createContext<ToolUseState | null>(null);
+
+export declare namespace ToolUseProvider {
+  export interface Props {
+    children?: ReactNode;
+    appName: string;
+  }
+}
+
+export function ToolUseProvider({ children, appName }: ToolUseProvider.Props) {
+  const [hasNavigated, setHasNavigated] = useState(false);
+
+  return (
+    <ToolUseContext.Provider value={{ hasNavigated, setHasNavigated, appName }}>
+      {children}
+    </ToolUseContext.Provider>
+  );
+}
+
+export function useToolUseState() {
+  return useContext(ToolUseContext);
+}

package/src/{hooks → react/hooks/__tests__}/useCallTool.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, vi } from "vitest";
-import { useCallTool } from "./useCallTool";
+import { useCallTool } from "../useCallTool";
 
 test("Should execute tool when returned function is called", async () => {
   vi.stubGlobal("openai", {

package/src/{hooks → react/hooks/__tests__}/useOpenAiGlobal.test.ts

@@ -1,7 +1,7 @@
 import { expect, test, vi } from "vitest";
-import { useOpenAiGlobal } from "./useOpenAiGlobal";
+import { useOpenAiGlobal } from "../useOpenAiGlobal";
 import { renderHook, act } from "@testing-library/react";
-import { SET_GLOBALS_EVENT_TYPE } from "../types/openai";
+import { SET_GLOBALS_EVENT_TYPE } from "../../../types/openai";
 
 test("Should update value when globals are updated and event it triggered", async () => {
   vi.stubGlobal("openai", {
@@ -17,7 +17,9 @@ test("Should update value when globals are updated and event it triggered", asyn
     });
     window.dispatchEvent(
       new CustomEvent(SET_GLOBALS_EVENT_TYPE, {
-        detail: { globals: { toolResponseMetadata: { toolName: "my-other-tool" } } },
+        detail: {
+          globals: { toolResponseMetadata: { toolName: "my-other-tool" } },
+        },
       })
     );
   });

package/src/react/hooks/__tests__/useOpenExternal.test.tsx

@@ -0,0 +1,24 @@
+import { expect, test, vi } from "vitest";
+import { renderHookToSnapshotStream } from "@testing-library/react-render-stream";
+import { useOpenExternal } from "../useOpenExternal";
+import { stubOpenAiGlobals } from "../../../testing/internal";
+
+test("calls the global openExternal function", async () => {
+  const openExternalMock = vi.fn();
+
+  stubOpenAiGlobals({ openExternal: openExternalMock });
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useOpenExternal()
+  );
+
+  const openExternal = await takeSnapshot();
+  openExternal({ href: "https://example.com" });
+
+  expect(openExternalMock).toHaveBeenCalledTimes(1);
+  expect(openExternalMock).toHaveBeenCalledWith({
+    href: "https://example.com",
+  });
+
+  await expect(takeSnapshot).not.toRerender();
+});

package/src/{hooks → react/hooks/__tests__}/useRequestDisplayMode.test.ts

@@ -1,6 +1,6 @@
 import { expect, test, vi } from "vitest";
-import { useRequestDisplayMode } from "./useRequestDisplayMode";
-import { DisplayMode } from "../types/openai";
+import { useRequestDisplayMode } from "../useRequestDisplayMode";
+import { DisplayMode } from "../../../types/openai";
 
 test("Should set display mode when returned function is called", async () => {
   vi.stubGlobal("openai", {

package/src/{hooks → react/hooks/__tests__}/useSendFollowUpMessage.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, vi } from "vitest";
-import { useSendFollowUpMessage } from "./useSendFollowUpMessage";
+import { useSendFollowUpMessage } from "../useSendFollowUpMessage";
 
 test("Should set display mode when returned function is called", async () => {
   vi.stubGlobal("openai", {
@@ -9,5 +9,7 @@ test("Should set display mode when returned function is called", async () => {
   const sendFollowUpMessage = useSendFollowUpMessage();
   await sendFollowUpMessage("Do a cool thing!");
 
-  expect(window.openai.sendFollowUpMessage).toBeCalledWith({ prompt: "Do a cool thing!" });
+  expect(window.openai.sendFollowUpMessage).toBeCalledWith({
+    prompt: "Do a cool thing!",
+  });
 });