@apollo/client-ai-apps 0.3.0 → 0.3.2

package/.github/workflows/compare-build-output.yml

@@ -0,0 +1,28 @@
+name: Compare Build Output
+on:
+  pull_request:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  comparebuildoutput:
+    name: Compare Build Output
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          # Fetch entire git history so we have the parent commit to compare against
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ">=23.6.0"
+      - name: Install dependencies (with cache)
+        uses: bahmutov/npm-install@v1
+
+      - name: Run comparison script
+        id: attw
+        run: ./config/compare-build-output-to.sh $(git merge-base HEAD origin/${{ github.base_ref }}) | tee $GITHUB_STEP_SUMMARY
+        env:
+          RUNNER_TEMP: ${{ runner.temp }}

package/config/compare-build-output-to.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+upstream=$1
+comparison="${RUNNER_TEMP:-/tmp}/comparison_checkout"
+root=$(git rev-parse --show-toplevel)
+
+temp=$(mktemp --tmpdir="${RUNNER_TEMP:-/tmp}")
+trap 'rm -f "$temp"' EXIT
+
+patterndiff(){
+  cd dist || { echo "dist folder not found"; exit 1; }
+  count=0
+  while IFS= read -r -d '' file
+  do
+    if ! filediff="$(diff <(tr "'" '"' < "$comparison/dist/$file") <(tr "'" '"' < "$root/dist/$file"))"; then
+      (( count++ ))
+      echo "$file"
+      if [[ "$file" == *.min.* ]]; then
+        echo "> Minified file differs."
+      else
+        echo "$filediff"
+      fi
+    fi
+  done >"$temp" < <(find . -name "$1" -print0)
+
+  output="$(cat <"$temp")"
+
+  cat <<EOF
+
+## differences in $1 files
+
+<details>
+  <summary>
+
+### $count files with differences
+
+  </summary>
+
+\`\`\`diff
+
+$output
+
+\`\`\`
+
+</details>
+EOF
+
+  cd ..
+}
+
+[ -z "$upstream" ] && { echo "need upstream argument"; exit 1; }
+
+git worktree add --force --detach --checkout "$comparison" "$upstream" || { cd "$comparison" && git checkout "$upstream"; } || exit 1
+
+cd "$comparison" || { echo "checkout failed"; exit 1; }
+[ -d node_modules ] || cp -r "$root/node_modules" .
+npm i >&2
+git status >&2
+npm run build >&2
+cd "$root" || exit 1
+git status >&2
+npm run build >&2
+
+set +e
+
+patterndiff "*.js"
+patterndiff "*.cjs"
+patterndiff "*.d.ts"
+patterndiff "*.d.cts"
+
+cat <<EOF
+
+## differences in other files
+
+<details>
+  <summary>
+
+### $(diff -qr "$comparison/dist" "dist" -x "*.map" -x "*.native.*" -x "*.js" -x "*.cjs" -x "*.d.ts" -x "*.d.cts" -w | wc -l) files with differences
+
+  </summary>
+
+\`\`\`diff
+
+$(diff -r "$comparison/dist" "dist" -x "*.map" -x "*.native.*" -x "*.js" -x "*.cjs" -x "*.d.ts" -x "*.d.cts" -w)
+
+\`\`\`
+
+</details>
+EOF
+

package/dist/core/ApolloClient.d.ts

@@ -0,0 +1,14 @@
+import { ApolloClient as BaseApolloClient } from "@apollo/client";
+import "../types/openai";
+import { ApplicationManifest } from "../types/application-manifest";
+export declare namespace ApolloClient {
+    interface Options extends Omit<BaseApolloClient.Options, "link"> {
+        link?: BaseApolloClient.Options["link"];
+        manifest: ApplicationManifest;
+    }
+}
+export declare class ApolloClient extends BaseApolloClient {
+    manifest: ApplicationManifest;
+    constructor(options: ApolloClient.Options);
+    prefetchData(): Promise<void>;
+}

package/dist/index.d.ts

@@ -1,12 +1,18 @@
-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 { ToolCallLink } from "./apollo_client/link/ToolCallLink";
+export { ApolloClient } from "./core/ApolloClient";
+export { ApolloProvider } from "./react/ApolloProvider";
+export { ToolCallLink } from "./link/ToolCallLink";

package/dist/index.js

@@ -4,11 +4,22 @@ var SetGlobalsEvent = class extends CustomEvent {
   type = SET_GLOBALS_EVENT_TYPE;
 };
 
-// src/hooks/useOpenAiGlobal.ts
-import { useSyncExternalStore } from "react";
+// src/react/context/ToolUseContext.tsx
+import React, { createContext, useContext, useState } from "react";
+var ToolUseContext = createContext(null);
+function ToolUseProvider({ children, appName }) {
+  const [hasNavigated, setHasNavigated] = useState(false);
+  return /* @__PURE__ */ React.createElement(ToolUseContext.Provider, { value: { hasNavigated, setHasNavigated, appName } }, children);
+}
+function useToolUseState() {
+  return useContext(ToolUseContext);
+}
+
+// src/react/hooks/useOpenAiGlobal.ts
+import { useSyncExternalStore, useCallback } from "react";
 function useOpenAiGlobal(key) {
   return useSyncExternalStore(
-    (onChange) => {
+    useCallback((onChange) => {
       const handleSetGlobal = (event) => {
         const value = event.detail.globals[key];
         if (value === void 0) {
@@ -22,24 +33,24 @@ function useOpenAiGlobal(key) {
       return () => {
         window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
       };
-    },
+    }, []),
     () => window.openai[key]
   );
 }
 
-// src/hooks/useToolName.ts
+// src/react/hooks/useToolName.ts
 var useToolName = () => {
   const toolResponseMetadata = useOpenAiGlobal("toolResponseMetadata");
   return toolResponseMetadata?.toolName;
 };
 
-// src/hooks/useToolInput.ts
+// src/react/hooks/useToolInput.ts
 var useToolInput = () => {
   const toolInput = useOpenAiGlobal("toolInput");
   return toolInput;
 };
 
-// src/hooks/useSendFollowUpMessage.ts
+// src/react/hooks/useSendFollowUpMessage.ts
 var useSendFollowUpMessage = () => {
   return async (prompt) => {
     await window.openai?.sendFollowUpMessage({
@@ -48,25 +59,17 @@ var useSendFollowUpMessage = () => {
   };
 };
 
-// src/hooks/useRequestDisplayMode.ts
+// src/react/hooks/useRequestDisplayMode.ts
 var useRequestDisplayMode = () => {
   return async (args) => {
     return await window.openai?.requestDisplayMode(args);
   };
 };
 
-// src/hooks/useToolEffect.tsx
-import React, { useEffect, useState } from "react";
-var ToolUseContext = React.createContext(null);
-function ToolUseProvider({
-  children,
-  appName
-}) {
-  const [hasNavigated, setHasNavigated] = useState(false);
-  return /* @__PURE__ */ React.createElement(ToolUseContext.Provider, { value: { hasNavigated, setHasNavigated, appName } }, children);
-}
+// src/react/hooks/useToolEffect.tsx
+import { useEffect } from "react";
 var useToolEffect = (toolName, effect, deps = []) => {
-  const ctx = React.useContext(ToolUseContext);
+  const ctx = useToolUseState();
   const fullToolName = useToolName();
   const toolInput = useToolInput();
   if (!ctx)
@@ -91,17 +94,63 @@ var useToolEffect = (toolName, effect, deps = []) => {
   ]);
 };
 
+// src/react/hooks/useOpenExternal.ts
+import { useCallback as useCallback2 } from "react";
+function useOpenExternal() {
+  return useCallback2(
+    (...args) => window.openai.openExternal(...args),
+    []
+  );
+}
+
+// src/react/hooks/useToolOutput.ts
+function useToolOutput() {
+  return useOpenAiGlobal("toolOutput") ?? null;
+}
+
+// src/react/hooks/useToolResponseMetadata.ts
+function useToolResponseMetadata() {
+  return useOpenAiGlobal("toolResponseMetadata") ?? null;
+}
+
+// src/react/hooks/useWidgetState.ts
+import { useCallback as useCallback3, useState as useState2 } from "react";
+function useWidgetState(defaultState) {
+  const widgetStateFromWindow = useOpenAiGlobal("widgetState");
+  const [previousWidgetStateFromWindow, setPreviousWidgetStateFromWindow] = useState2(widgetStateFromWindow);
+  let [widgetState, _setWidgetState] = useState2(() => {
+    if (widgetStateFromWindow != null) {
+      return widgetStateFromWindow;
+    }
+    return typeof defaultState === "function" ? defaultState() : defaultState ?? null;
+  });
+  if (previousWidgetStateFromWindow !== widgetStateFromWindow) {
+    _setWidgetState(widgetState = widgetStateFromWindow);
+    setPreviousWidgetStateFromWindow(widgetStateFromWindow);
+  }
+  const setWidgetState = useCallback3((state) => {
+    _setWidgetState((prevState) => {
+      const newState = typeof state === "function" ? state(prevState) : state;
+      if (newState != null && typeof window !== "undefined") {
+        void window.openai?.setWidgetState?.(newState);
+      }
+      return newState;
+    });
+  }, []);
+  return [widgetState, setWidgetState];
+}
+
 // src/index.ts
 export * from "@apollo/client";
 
-// src/apollo_client/client.ts
-import { ApolloClient } from "@apollo/client";
+// src/core/ApolloClient.ts
+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";
 
-// src/apollo_client/link/ToolCallLink.ts
+// src/link/ToolCallLink.ts
 import { ApolloLink } from "@apollo/client";
 import { from, map } from "rxjs";
 import {
@@ -128,8 +177,8 @@ var ToolCallLink = class extends ApolloLink {
   }
 };
 
-// src/apollo_client/client.ts
-var ExtendedApolloClient = class extends ApolloClient {
+// src/core/ApolloClient.ts
+var ApolloClient = class extends BaseApolloClient {
   manifest;
   constructor(options) {
     const link = options.link ?? new ToolCallLink();
@@ -151,24 +200,26 @@ var ExtendedApolloClient = class extends ApolloClient {
   }
   async prefetchData() {
     this.manifest.operations.forEach((operation) => {
-      if (operation.prefetch && operation.prefetchID && window.openai.toolOutput.prefetch?.[operation.prefetchID]) {
+      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 (operation.tools?.find(
-        (tool) => `${this.manifest.name}--${tool.name}` === window.openai.toolResponseMetadata.toolName
+        (tool) => `${this.manifest.name}--${tool.name}` === window.openai.toolResponseMetadata?.toolName
       )) {
         const variables = Object.keys(window.openai.toolInput).reduce(
-          (obj, key) => operation.variables[key] ? { ...obj, [key]: window.openai.toolInput[key] } : obj,
+          (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
-        });
+        if (window.openai.toolOutput) {
+          this.writeQuery({
+            query: parse(operation.body),
+            data: window.openai.toolOutput.result.data,
+            variables
+          });
+        }
       }
     });
   }
@@ -185,14 +236,11 @@ function validateTerminatingLink(link) {
   }
 }
 
-// src/apollo_client/provider.tsx
-import React2, { useEffect as useEffect2, useState as useState2 } from "react";
-import { ApolloProvider } from "@apollo/client/react";
-var ExtendedApolloProvider = ({
-  children,
-  client
-}) => {
-  const [hasPreloaded, setHasPreloaded] = useState2(false);
+// src/react/ApolloProvider.tsx
+import React3, { useEffect as useEffect2, useState as useState3 } from "react";
+import { ApolloProvider as BaseApolloProvider } from "@apollo/client/react";
+var ApolloProvider = ({ children, client }) => {
+  const [hasPreloaded, setHasPreloaded] = useState3(false);
   useEffect2(() => {
     const prefetchData = async () => {
       await client.prefetchData();
@@ -209,19 +257,23 @@ var ExtendedApolloProvider = ({
       window.removeEventListener(SET_GLOBALS_EVENT_TYPE, prefetchData);
     };
   }, []);
-  return hasPreloaded ? /* @__PURE__ */ React2.createElement(ApolloProvider, { client }, children) : null;
+  return hasPreloaded ? /* @__PURE__ */ React3.createElement(BaseApolloProvider, { client }, children) : null;
 };
 export {
-  ExtendedApolloClient as ApolloClient,
-  ExtendedApolloProvider as ApolloProvider,
+  ApolloClient,
+  ApolloProvider,
   SET_GLOBALS_EVENT_TYPE,
   SetGlobalsEvent,
   ToolCallLink,
   ToolUseProvider,
   useOpenAiGlobal,
+  useOpenExternal,
   useRequestDisplayMode,
   useSendFollowUpMessage,
   useToolEffect,
   useToolInput,
-  useToolName
+  useToolName,
+  useToolOutput,
+  useToolResponseMetadata,
+  useWidgetState
 };

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

@@ -105,6 +105,11 @@ var ApplicationManifestPlugin = () => {
         if (!name2) {
           throw new Error("'name' argument must be supplied for @tool");
         }
+        if (name2.indexOf(" ") > -1) {
+          throw new Error(
+            `Tool with name "${name2}" contains spaces which is not allowed.`
+          );
+        }
         if (!description) {
           throw new Error(
             "'description' argument must be supplied for @tool"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollo/client-ai-apps",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "publishConfig": {
     "access": "public"
   },
@@ -17,9 +17,11 @@
   },
   "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",
@@ -33,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",
@@ -41,6 +44,7 @@
     "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/src/{apollo_client/client.ts → core/ApolloClient.ts}

@@ -1,12 +1,12 @@
 import type { ApolloLink } from "@apollo/client";
-import { ApolloClient } 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";
+import { ToolCallLink } from "../link/ToolCallLink";
 
 // TODO: In the future if/when we support PQs again, do pqLink.concat(toolCallLink)
 // Commenting this out for now.
@@ -16,16 +16,18 @@ import { ToolCallLink } from "./link/ToolCallLink";
 //   sha256: (queryString) => sha256(queryString),
 // });
 
-// This allows us to extend the options with the "manifest" option AND make link optional (it is normally required)
-type ExtendedApolloClientOptions = Omit<ApolloClient.Options, "link"> & {
-  link?: ApolloClient.Options["link"];
-  manifest: ApplicationManifest;
-};
+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 ExtendedApolloClient extends ApolloClient {
+export class ApolloClient extends BaseApolloClient {
   manifest: ApplicationManifest;
 
-  constructor(options: ExtendedApolloClientOptions) {
+  constructor(options: ApolloClient.Options) {
     const link = options.link ?? new ToolCallLink();
 
     if (__DEV__) {
@@ -53,7 +55,7 @@ export class ExtendedApolloClient extends ApolloClient {
       if (
         operation.prefetch &&
         operation.prefetchID &&
-        window.openai.toolOutput.prefetch?.[operation.prefetchID]
+        window.openai.toolOutput?.prefetch?.[operation.prefetchID]
       ) {
         this.writeQuery({
           query: parse(operation.body),
@@ -66,24 +68,26 @@ export class ExtendedApolloClient extends ApolloClient {
         operation.tools?.find(
           (tool) =>
             `${this.manifest.name}--${tool.name}` ===
-            window.openai.toolResponseMetadata.toolName
+            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] ?
+            operation.variables?.[key] ?
               { ...obj, [key]: window.openai.toolInput[key] }
             : obj,
           {}
         );
 
-        this.writeQuery({
-          query: parse(operation.body),
-          data: window.openai.toolOutput.result.data,
-          variables,
-        });
+        if (window.openai.toolOutput) {
+          this.writeQuery({
+            query: parse(operation.body),
+            data: (window.openai.toolOutput.result as any).data,
+            variables,
+          });
+        }
       }
     });
   }