@apollo/client-ai-apps 0.2.4 → 0.3.1

package/dist/link/ToolCallLink.d.ts

@@ -0,0 +1,26 @@
+import { ApolloLink, Observable } from "@apollo/client";
+/**
+ * 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 declare class ToolCallLink extends ApolloLink {
+    request(operation: ApolloLink.Operation): Observable<ApolloLink.Result>;
+}

package/dist/react/ApolloProvider.d.ts

@@ -0,0 +1,9 @@
+import React, { ReactNode } from "react";
+import { ApolloClient } from "../core/ApolloClient";
+export declare namespace ApolloProvider {
+    interface Props {
+        children?: ReactNode;
+        client: ApolloClient;
+    }
+}
+export declare const ApolloProvider: ({ children, client }: ApolloProvider.Props) => React.JSX.Element;

package/dist/react/context/ToolUseContext.d.ts

@@ -0,0 +1,15 @@
+import React, { ReactNode } from "react";
+interface ToolUseState {
+    appName: string;
+    hasNavigated: boolean;
+    setHasNavigated: (v: boolean) => void;
+}
+export declare namespace ToolUseProvider {
+    interface Props {
+        children?: ReactNode;
+        appName: string;
+    }
+}
+export declare function ToolUseProvider({ children, appName }: ToolUseProvider.Props): React.JSX.Element;
+export declare function useToolUseState(): ToolUseState;
+export {};

package/dist/{hooks → react/hooks}/useOpenAiGlobal.d.ts

@@ -1,2 +1,2 @@
-import { OpenAiGlobals } from "../types/openai";
+import { OpenAiGlobals } from "../../types/openai";
 export declare function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K];

package/dist/react/hooks/useOpenExternal.d.ts

@@ -0,0 +1,3 @@
+export declare function useOpenExternal(): (payload: {
+    href: string;
+}) => void;

package/dist/{hooks → react/hooks}/useRequestDisplayMode.d.ts

@@ -1,4 +1,4 @@
-import { DisplayMode } from "../types/openai";
+import { DisplayMode } from "../../types/openai";
 export declare const useRequestDisplayMode: () => (args: {
     mode: DisplayMode;
 }) => Promise<{

package/dist/{hooks → react/hooks}/useToolEffect.d.ts

@@ -1,6 +1,2 @@
 import React from "react";
-export declare function ToolUseProvider({ children, appName }: {
-    children: any;
-    appName: string;
-}): React.JSX.Element;
 export declare const useToolEffect: (toolName: string | string[], effect: (toolInput: any) => void, deps?: React.DependencyList) => void;

package/dist/react/hooks/useToolOutput.d.ts

@@ -0,0 +1 @@
+export declare function useToolOutput(): import("../..").UnknownObject;

package/dist/react/hooks/useToolResponseMetadata.d.ts

@@ -0,0 +1 @@
+export declare function useToolResponseMetadata(): import("../..").UnknownObject;

package/dist/react/hooks/useWidgetState.d.ts

@@ -0,0 +1,4 @@
+import { SetStateAction } from "react";
+import { UnknownObject } from "../../types/openai";
+export declare function useWidgetState<T extends UnknownObject>(defaultState: T | (() => T)): readonly [T, (state: SetStateAction<T>) => void];
+export declare function useWidgetState<T extends UnknownObject>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];

package/dist/types/openai.d.ts

@@ -1,4 +1,4 @@
-type UnknownObject = any;
+export type UnknownObject = Record<string, unknown>;
 declare global {
     interface Window {
         openai: API<any> & OpenAiGlobals;
@@ -70,4 +70,3 @@ export type UserAgent = {
         touch: boolean;
     };
 };
-export {};

package/dist/vite/index.js

@@ -26,14 +26,18 @@ var getRawValue = (node) => {
         return acc;
       }, {});
     default:
-      throw new Error(`Error when parsing directive values: unexpected type '${node.kind}'`);
+      throw new Error(
+        `Error when parsing directive values: unexpected type '${node.kind}'`
+      );
   }
 };
 var getTypedDirectiveArgument = (argumentName, expectedType, directiveArguments) => {
   if (!directiveArguments || directiveArguments.length === 0) {
     return void 0;
   }
-  let argument = directiveArguments.find((directiveArgument) => directiveArgument.name.value === argumentName);
+  let argument = directiveArguments.find(
+    (directiveArgument) => directiveArgument.name.value === argumentName
+  );
   if (!argument) {
     return void 0;
   }
@@ -59,25 +63,52 @@ var ApplicationManifestPlugin = () => {
   const client = new ApolloClient({
     cache: clientCache,
     link: new ApolloLink((operation) => {
-      const body = print(removeClientDirective(sortTopLevelDefinitions(operation.query)));
+      const body = print(
+        removeClientDirective(sortTopLevelDefinitions(operation.query))
+      );
       const name = operation.operationName;
-      const variables = operation.query.definitions.find((d) => d.kind === "OperationDefinition").variableDefinitions?.reduce(
-        (obj, varDef) => ({ ...obj, [varDef.variable.name.value]: getTypeName(varDef.type) }),
+      const variables = operation.query.definitions.find(
+        (d) => d.kind === "OperationDefinition"
+      ).variableDefinitions?.reduce(
+        (obj, varDef) => ({
+          ...obj,
+          [varDef.variable.name.value]: getTypeName(varDef.type)
+        }),
         {}
       );
-      const type = operation.query.definitions.find((d) => d.kind === "OperationDefinition").operation;
-      const prefetch = operation.query.definitions.find((d) => d.kind === "OperationDefinition").directives?.some((d) => d.name.value === "prefetch");
+      const type = operation.query.definitions.find(
+        (d) => d.kind === "OperationDefinition"
+      ).operation;
+      const prefetch = operation.query.definitions.find(
+        (d) => d.kind === "OperationDefinition"
+      ).directives?.some((d) => d.name.value === "prefetch");
       const id = createHash("sha256").update(body).digest("hex");
       const prefetchID = prefetch ? "__anonymous" : void 0;
-      const tools = operation.query.definitions.find((d) => d.kind === "OperationDefinition").directives?.filter((d) => d.name.value === "tool").map((directive) => {
-        const name2 = getTypedDirectiveArgument("name", Kind.STRING, directive.arguments);
-        const description = getTypedDirectiveArgument("description", Kind.STRING, directive.arguments);
-        const extraInputs = getTypedDirectiveArgument("extraInputs", Kind.LIST, directive.arguments);
+      const tools = operation.query.definitions.find(
+        (d) => d.kind === "OperationDefinition"
+      ).directives?.filter((d) => d.name.value === "tool").map((directive) => {
+        const name2 = getTypedDirectiveArgument(
+          "name",
+          Kind.STRING,
+          directive.arguments
+        );
+        const description = getTypedDirectiveArgument(
+          "description",
+          Kind.STRING,
+          directive.arguments
+        );
+        const extraInputs = getTypedDirectiveArgument(
+          "extraInputs",
+          Kind.LIST,
+          directive.arguments
+        );
         if (!name2) {
           throw new Error("'name' argument must be supplied for @tool");
         }
         if (!description) {
-          throw new Error("'description' argument must be supplied for @tool");
+          throw new Error(
+            "'description' argument must be supplied for @tool"
+          );
         }
         return {
           name: name2,
@@ -85,7 +116,9 @@ var ApplicationManifestPlugin = () => {
           extraInputs
         };
       });
-      return Observable.of({ data: { id, name, type, body, variables, prefetch, prefetchID, tools } });
+      return Observable.of({
+        data: { id, name, type, body, variables, prefetch, prefetchID, tools }
+      });
     })
   });
   const processFile = async (file) => {
@@ -105,14 +138,24 @@ var ApplicationManifestPlugin = () => {
     }));
     const operations = [];
     for (const source of sources) {
-      const type = source.node.definitions.find((d) => d.kind === "OperationDefinition").operation;
+      const type = source.node.definitions.find(
+        (d) => d.kind === "OperationDefinition"
+      ).operation;
       let result;
       if (type === "query") {
-        result = await client.query({ query: source.node, fetchPolicy: "no-cache" });
+        result = await client.query({
+          query: source.node,
+          fetchPolicy: "no-cache"
+        });
       } else if (type === "mutation") {
-        result = await client.mutate({ mutation: source.node, fetchPolicy: "no-cache" });
+        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.");
+        throw new Error(
+          "Found an unsupported operation type. Only Query and Mutation are supported."
+        );
       }
       operations.push(result.data);
     }
@@ -123,7 +166,9 @@ var ApplicationManifestPlugin = () => {
     });
   };
   const generateManifest = async () => {
-    const operations = Array.from(cache.values()).flatMap((entry) => entry.operations);
+    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`."
@@ -150,14 +195,20 @@ var ApplicationManifestPlugin = () => {
       name: packageJson.name,
       description: packageJson.description,
       hash: createHash("sha256").update(Date.now().toString()).digest("hex"),
-      operations: Array.from(cache.values()).flatMap((entry) => entry.operations),
+      operations: Array.from(cache.values()).flatMap(
+        (entry) => entry.operations
+      ),
       resource,
       csp: {
         connectDomains: packageJson.csp?.connectDomains ?? [],
         resourceDomains: packageJson.csp?.resourceDomains ?? []
       }
     };
-    const dest = path.resolve(root, config.build.outDir, ".application-manifest.json");
+    const dest = path.resolve(
+      root,
+      config.build.outDir,
+      ".application-manifest.json"
+    );
     mkdirSync(path.dirname(dest), { recursive: true });
     writeFileSync(dest, JSON.stringify(manifest));
     writeFileSync(".application-manifest.json", JSON.stringify(manifest));
@@ -224,7 +275,9 @@ function removeClientDirective(doc) {
     OperationDefinition(node) {
       return {
         ...node,
-        directives: node.directives?.filter((d) => d.name.value !== "prefetch" && d.name.value !== "tool")
+        directives: node.directives?.filter(
+          (d) => d.name.value !== "prefetch" && d.name.value !== "tool"
+        )
       };
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollo/client-ai-apps",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },
@@ -17,12 +17,16 @@
   },
   "scripts": {
     "dev": "node ./scripts/dev.mjs",
+    "prebuild": "npm run clean",
     "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",
+    "clean": "rimraf dist",
     "test": "vitest run --coverage",
     "test:watch": "vitest --coverage",
-    "changeset": "knope document-change"
+    "changeset": "knope document-change",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "keywords": [],
   "author": "",
@@ -31,6 +35,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
+    "@testing-library/react-render-stream": "^2.0.2",
     "@types/node": "^24.10.0",
     "@types/react": "^19.2.2",
     "@vitejs/plugin-react": "^5.1.1",
@@ -38,6 +43,8 @@
     "esbuild": "^0.25.12",
     "graphql": "^16.9.0",
     "happy-dom": "^20.0.10",
+    "prettier": "^3.7.4",
+    "rimraf": "^6.1.2",
     "rxjs": "^7.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.13"

package/scripts/dev.mjs

@@ -10,7 +10,9 @@ let ctx = await esbuild.context({
       name: "rebuild-logger",
       setup(build) {
         build.onEnd((result) => {
-          console.log(`Rebuilt at ${new Date().toLocaleTimeString()} (${result.errors.length} errors)`);
+          console.log(
+            `Rebuilt at ${new Date().toLocaleTimeString()} (${result.errors.length} errors)`
+          );
         });
       },
     },

package/src/core/ApolloClient.ts

@@ -0,0 +1,108 @@
+import type { ApolloLink } from "@apollo/client";
+import { ApolloClient as BaseApolloClient } from "@apollo/client";
+import { DocumentTransform } from "@apollo/client";
+import { removeDirectivesFromDocument } from "@apollo/client/utilities/internal";
+import { parse } from "graphql";
+import { __DEV__ } from "@apollo/client/utilities/environment";
+import "../types/openai";
+import { ApplicationManifest } from "../types/application-manifest";
+import { ToolCallLink } from "../link/ToolCallLink";
+
+// 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),
+// });
+
+export declare namespace ApolloClient {
+  // This allows us to extend the options with the "manifest" option AND make link optional (it is normally required)
+  export interface Options extends Omit<BaseApolloClient.Options, "link"> {
+    link?: BaseApolloClient.Options["link"];
+    manifest: ApplicationManifest;
+  }
+}
+
+export class ApolloClient extends BaseApolloClient {
+  manifest: ApplicationManifest;
+
+  constructor(options: ApolloClient.Options) {
+    const link = options.link ?? new ToolCallLink();
+
+    if (__DEV__) {
+      validateTerminatingLink(link);
+    }
+
+    super({
+      ...options,
+      link,
+      // 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,
+          {}
+        );
+
+        if (window.openai.toolOutput) {
+          this.writeQuery({
+            query: parse(operation.body),
+            data: (window.openai.toolOutput.result as any).data,
+            variables,
+          });
+        }
+      }
+    });
+  }
+}
+
+function validateTerminatingLink(link: ApolloLink) {
+  let terminatingLink = link;
+
+  while (terminatingLink.right) {
+    terminatingLink = terminatingLink.right;
+  }
+
+  if (terminatingLink.constructor.name !== "ToolCallLink") {
+    throw 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."
+    );
+  }
+}