@apollo/client-ai-apps 0.4.0 → 0.5.1

package/package.json

@@ -1,19 +1,92 @@
 {
+  "$schema": "https://www.schemastore.org/package.json",
   "name": "@apollo/client-ai-apps",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "publishConfig": {
     "access": "public"
   },
   "repository": {
-    "url": "https://github.com/apollographql/apollo-ai-apps-client"
+    "url": "https://github.com/apollographql/apollo-client-ai-apps"
   },
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./vite": "./dist/vite/index.js"
+    ".": {
+      "mcp": {
+        "types": "./dist/index.mcp.d.ts",
+        "default": "./dist/index.mcp.js"
+      },
+      "openai": {
+        "types": "./dist/index.openai.d.ts",
+        "default": "./dist/index.openai.js"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
+    },
+    "./mcp": {
+      "mcp": {
+        "types": "./dist/mcp/index.d.ts",
+        "default": "./dist/mcp/index.js"
+      },
+      "default": "./dist/utilities/emptyModule.js"
+    },
+    "./mcp/react": {
+      "mcp": {
+        "types": "./dist/mcp/react/index.d.ts",
+        "default": "./dist/mcp/react/index.js"
+      },
+      "default": "./dist/utilities/emptyModule.js"
+    },
+    "./openai": {
+      "openai": {
+        "types": "./dist/openai/index.d.ts",
+        "default": "./dist/openai/index.js"
+      },
+      "default": "./dist/utilities/emptyModule.js"
+    },
+    "./openai/globals": {
+      "openai": {
+        "types": "./dist/openai/globals.d.ts",
+        "default": "./dist/openai/globals.js"
+      },
+      "default": "./dist/utilities/emptyModule.js"
+    },
+    "./openai/react": {
+      "openai": {
+        "types": "./dist/openai/react/index.d.ts",
+        "default": "./dist/openai/react/index.js"
+      },
+      "default": "./dist/utilities/emptyModule.js"
+    },
+    "./react": {
+      "mcp": {
+        "types": "./dist/react/index.mcp.d.ts",
+        "default": "./dist/react/index.mcp.js"
+      },
+      "openai": {
+        "types": "./dist/react/index.openai.d.ts",
+        "default": "./dist/react/index.openai.js"
+      },
+      "default": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      }
+    },
+    "./tsconfig/core": "./dist/tsconfig/core/tsconfig.json",
+    "./tsconfig/mcp": "./dist/tsconfig/mcp/tsconfig.json",
+    "./tsconfig/openai": "./dist/tsconfig/openai/tsconfig.json",
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    }
   },
   "devEngines": {
     "packageManager": {
@@ -23,16 +96,17 @@
   "scripts": {
     "dev": "node ./scripts/dev.mjs",
     "prebuild": "npm run clean",
-    "build": "npm run build:src && npm run build:vite",
+    "build": "npm run build:src && npm run build:vite && npm run copy-ts-configs",
     "build:src": "tsc --project tsconfig.src.build.json",
     "build:vite": "tsc --project tsconfig.vite.build.json",
+    "copy-ts-configs": "copyfiles -u 1 \"src/tsconfig/*/tsconfig.json\" dist",
     "clean": "rimraf dist",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest --coverage",
+    "test": "vitest",
     "changeset": "knope document-change",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "typecheck": "tsc -b --emitDeclarationOnly",
+    "attw": "npm run build && attw --pack . --ignore-rules cjs-resolves-to-esm --profile node16"
   },
   "keywords": [],
   "author": "",
@@ -40,31 +114,53 @@
   "description": "",
   "devDependencies": {
     "@apollo/client": "^4.0.12",
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/react-render-stream": "^2.0.2",
+    "@types/mock-require": "^3.0.0",
     "@types/node": "^24.10.4",
     "@types/react": "^19.2.2",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/coverage-v8": "^4.0.13",
+    "copyfiles": "^2.4.1",
     "esbuild": "^0.25.12",
     "graphql": "^16.9.0",
     "happy-dom": "^20.0.10",
+    "memfs": "^4.56.10",
+    "mock-require": "^3.0.3",
     "prettier": "^3.7.4",
+    "react-error-boundary": "^6.1.0",
     "rimraf": "^6.1.2",
     "rxjs": "^7.8.1",
     "typescript": "^5.9.3",
+    "vite": "^7.3.1",
     "vitest": "^4.0.13"
   },
   "peerDependencies": {
     "@apollo/client": "^4.0.0",
+    "@modelcontextprotocol/ext-apps": "^1.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/ext-apps": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@graphql-tools/graphql-tag-pluck": "^8.3.23",
+    "cosmiconfig": "^9.0.0",
     "crypto-hash": "^4.0.0",
     "glob": "^11.0.3",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "zod": "^4.3.6"
   }
 }

package/src/config/defineConfig.ts

@@ -0,0 +1,8 @@
+import type { ApolloClientAiAppsConfig } from "./types.js";
+
+/**
+ * Helper type that makes it easier to define app configuration
+ */
+export function defineConfig(config: ApolloClientAiAppsConfig.Config) {
+  return config;
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export type { ApolloClientAiAppsConfig } from "./types.js";
+export { defineConfig } from "./defineConfig.js";

package/src/config/schema.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const AppTarget = z.literal(["mcp", "openai"]);
+
+const Mode = z
+  .literal(["development", "production"])
+  .or(z.custom<string & {}>((value) => typeof value === "string"));
+
+const labelsInput = z.exactOptional(
+  z.strictObject({
+    toolInvocation: z.exactOptional(
+      z.strictObject({
+        invoking: z.string().exactOptional(),
+        invoked: z.string().exactOptional(),
+      })
+    ),
+  })
+);
+
+const labelsOutput = z.exactOptional(
+  z.strictObject({
+    "toolInvocation/invoking": z.string().exactOptional(),
+    "toolInvocation/invoked": z.string().exactOptional(),
+  })
+);
+
+export const ApolloClientAiAppsConfigSchema = z.strictObject({
+  name: z.string().exactOptional(),
+  description: z.string().exactOptional(),
+  version: z.string().exactOptional(),
+  entry: z.exactOptional(
+    z.partialRecord(
+      Mode,
+      z.union([z.string(), z.partialRecord(AppTarget, z.string())])
+    )
+  ),
+  csp: z.exactOptional(
+    z.strictObject({
+      connectDomains: z.array(z.string()).exactOptional(),
+      frameDomains: z.array(z.string()).exactOptional(),
+      redirectDomains: z.array(z.string()).exactOptional(),
+      resourceDomains: z.array(z.string()).exactOptional(),
+    })
+  ),
+  widgetSettings: z.exactOptional(
+    z.strictObject({
+      prefersBorder: z.boolean().exactOptional(),
+      description: z.string().exactOptional(),
+      domain: z.string().exactOptional(),
+    })
+  ),
+  labels: z.codec(labelsInput, labelsOutput, {
+    encode: () => {
+      // encode is currently not used so we can skip the business logic and
+      // return an empty object which satisfies the type. If we need to encode
+      // labels back to the original form, this will need to be implemented
+      return {};
+    },
+    decode: ({ toolInvocation }) => {
+      const config: z.infer<typeof labelsOutput> = {};
+
+      if (toolInvocation?.invoking) {
+        config["toolInvocation/invoking"] = toolInvocation.invoking;
+      }
+
+      if (toolInvocation?.invoked) {
+        config["toolInvocation/invoked"] = toolInvocation.invoked;
+      }
+
+      return config;
+    },
+  }),
+});

package/src/config/types.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { ApolloClientAiAppsConfigSchema, AppTarget } from "./schema.js";
+
+export declare namespace ApolloClientAiAppsConfig {
+  export type AppTarget = z.infer<typeof AppTarget>;
+  export type Config = z.input<typeof ApolloClientAiAppsConfigSchema>;
+}

package/src/core/ApolloClient.ts

@@ -1,24 +1,8 @@
-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.js";
 import type { ApplicationManifest } from "../types/application-manifest.js";
-import { ToolCallLink } from "../link/ToolCallLink.js";
-import type { FetchResult } from "@apollo/client";
-
-// 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),
-// });
+import { aiClientSymbol } from "../utilities/constants.js";
 
 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;
@@ -26,88 +10,16 @@ export declare namespace ApolloClient {
 }
 
 export class ApolloClient extends BaseApolloClient {
-  manifest: ApplicationManifest;
+  /** @internal */
+  readonly [aiClientSymbol] = true;
 
   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() {
-    const toolOutput = window.openai.toolOutput as {
-      prefetch?: Record<string, FetchResult<any>>;
-    } | null;
-
-    // Write prefetched data to the cache
-    this.manifest.operations.forEach((operation) => {
-      if (
-        operation.prefetch &&
-        operation.prefetchID &&
-        toolOutput?.prefetch?.[operation.prefetchID]
-      ) {
-        this.writeQuery({
-          query: parse(operation.body),
-          data: 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,
-          {}
-        );
+    super(options as any);
 
-        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."
+      "Cannot construct an `ApolloClient` instance from `@apollo/client-ai-apps` without export conditions. Please set conditions or import from the `/openai` or `/mcp` subpath directly."
     );
   }
+
+  async waitForInitialization() {}
 }

package/src/core/Platform.ts

@@ -0,0 +1,27 @@
+import { __DEV__ } from "@apollo/client/utilities/environment";
+
+let warned = false;
+
+export const Platform = Object.freeze({
+  get target() {
+    if (__DEV__) {
+      if (!warned) {
+        console.error(
+          "Could not determine the platform target because module conditions are not properly configured for either the `mcp` or `openai` environment. Please ensure you are using the `apolloClientAiApps` vite plugin."
+        );
+        warned = true;
+      }
+    }
+
+    // Even though this return the "unknown" string, this value should never
+    // actually be seen at runtime unless something is misconfigured, hence the
+    // type cast to the other values.
+    return "unknown" as unknown as "mcp" | "openai";
+  },
+  select<
+    T = unknown,
+    TReturn = T extends (...args: any[]) => infer TReturn ? TReturn : T,
+  >(config: { mcp?: T; openai?: T }): TReturn | undefined {
+    return;
+  },
+});

package/src/core/types.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult as McpCallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { FormattedExecutionResult } from "graphql";
+
+export namespace ApolloMcpServerApps {
+  export interface StructuredContent {
+    result: FormattedExecutionResult;
+    prefetch?: Record<string, FormattedExecutionResult>;
+    [x: string]: unknown;
+  }
+
+  export interface CallToolResult extends McpCallToolResult {
+    structuredContent: ApolloMcpServerApps.StructuredContent;
+  }
+}

package/src/index.mcp.ts

@@ -0,0 +1,5 @@
+export * from "./index.js";
+
+export { Platform } from "./mcp/core/Platform.js";
+export { ApolloClient } from "./mcp/core/ApolloClient.js";
+export { ToolCallLink } from "./mcp/link/ToolCallLink.js";

package/src/index.openai.ts

@@ -0,0 +1,5 @@
+export * from "./index.js";
+
+export { Platform } from "./openai/core/Platform.js";
+export { ApolloClient } from "./openai/core/ApolloClient.js";
+export { ToolCallLink } from "./openai/link/ToolCallLink.js";

package/src/index.ts

@@ -1,17 +1,3 @@
-export type {
-  API,
-  CallTool,
-  DeviceType,
-  DisplayMode,
-  OpenAiGlobals,
-  SafeArea,
-  SafeAreaInsets,
-  Theme,
-  UserAgent,
-  UnknownObject,
-} from "./types/openai.js";
-export { SET_GLOBALS_EVENT_TYPE, SetGlobalsEvent } from "./types/openai.js";
-
 export type {
   ApplicationManifest,
   ManifestOperation,
@@ -22,18 +8,7 @@ export type {
   ManifestWidgetSettings,
 } from "./types/application-manifest.js";
 
-export { ToolUseProvider } from "./react/context/ToolUseContext.js";
-export { useOpenAiGlobal } from "./react/hooks/useOpenAiGlobal.js";
-export { useToolName } from "./react/hooks/useToolName.js";
-export { useToolInput } from "./react/hooks/useToolInput.js";
-export { useSendFollowUpMessage } from "./react/hooks/useSendFollowUpMessage.js";
-export { useRequestDisplayMode } from "./react/hooks/useRequestDisplayMode.js";
-export { useToolEffect } from "./react/hooks/useToolEffect.js";
-export { useOpenExternal } from "./react/hooks/useOpenExternal.js";
-export { useToolOutput } from "./react/hooks/useToolOutput.js";
-export { useToolResponseMetadata } from "./react/hooks/useToolResponseMetadata.js";
-export { useWidgetState } from "./react/hooks/useWidgetState.js";
-
 export { ApolloClient } from "./core/ApolloClient.js";
-export { ApolloProvider } from "./react/ApolloProvider.js";
 export { ToolCallLink } from "./link/ToolCallLink.js";
+
+export { Platform } from "./core/Platform.js";

package/src/link/ToolCallLink.ts

@@ -1,16 +1,11 @@
-import { ApolloLink, Observable } from "@apollo/client";
-import { from, map } from "rxjs";
-import {
-  fallbackHttpConfig,
-  selectHttpOptionsAndBody,
-} from "@apollo/client/link/http";
+import { ApolloLink } 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
+ * @example Providing a custom link chain
  *
  * ```ts
  * import { ApolloLink } from "@apollo/client";
@@ -28,22 +23,11 @@ import {
  * ```
  */
 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;
+  constructor() {
+    super();
 
-    return from(window.openai.callTool("execute", { query, variables })).pipe(
-      map((result) => ({ data: result.structuredContent.data }))
+    throw new Error(
+      "Cannot construct a `ToolCallLink` from `@apollo/client-ai-apps` without export conditions. Please set export conditions or import from  the `/openai` or `/mcp` subpath directly."
     );
   }
 }

package/src/mcp/core/ApolloClient.ts

@@ -0,0 +1,102 @@
+import {
+  ApolloLink,
+  ApolloClient as BaseApolloClient,
+  DocumentTransform,
+} from "@apollo/client";
+import { removeDirectivesFromDocument } from "@apollo/client/utilities/internal";
+import { parse } from "graphql";
+import { __DEV__ } from "@apollo/client/utilities/environment";
+import type { ApplicationManifest } from "../../types/application-manifest.js";
+import { ToolCallLink } from "../link/ToolCallLink.js";
+import {
+  aiClientSymbol,
+  cacheAsync,
+  getVariablesForOperationFromToolInput,
+} from "../../utilities/index.js";
+import { McpAppManager } from "./McpAppManager.js";
+
+export declare namespace ApolloClient {
+  export interface Options extends Omit<BaseApolloClient.Options, "link"> {
+    link?: BaseApolloClient.Options["link"];
+    manifest: ApplicationManifest;
+  }
+}
+
+export class ApolloClient extends BaseApolloClient {
+  manifest: ApplicationManifest;
+  private readonly appManager: McpAppManager;
+
+  /** @internal */
+  readonly [aiClientSymbol] = true;
+
+  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
+        )!;
+      }).concat(options.documentTransform ?? DocumentTransform.identity()),
+    });
+
+    this.manifest = options.manifest;
+    this.appManager = new McpAppManager(this.manifest);
+  }
+
+  stop() {
+    super.stop();
+    this.appManager.close().catch(() => {});
+  }
+
+  waitForInitialization = cacheAsync(async () => {
+    const { prefetch, result, toolName, args } =
+      await this.appManager.waitForInitialization();
+
+    this.manifest.operations.forEach((operation) => {
+      if (operation.prefetchID && prefetch?.[operation.prefetchID]) {
+        this.writeQuery({
+          query: parse(operation.body),
+          data: prefetch[operation.prefetchID].data,
+        });
+      }
+
+      if (operation.tools.find((tool) => tool.name === toolName)) {
+        this.writeQuery({
+          query: parse(operation.body),
+          data: result.data,
+          variables: getVariablesForOperationFromToolInput(operation, args),
+        });
+      }
+    });
+  });
+}
+
+function validateTerminatingLink(link: ApolloLink) {
+  let terminatingLink = link;
+
+  while (terminatingLink.right) {
+    terminatingLink = terminatingLink.right;
+  }
+
+  if (
+    !isNamedLink(terminatingLink) ||
+    terminatingLink.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."
+    );
+  }
+}
+
+function isNamedLink(link: ApolloLink): link is ApolloLink & { name: string } {
+  return "name" in link;
+}