@yak-io/graphql 0.1.1

package/LICENSE

@@ -0,0 +1,36 @@
+Yak Proprietary License
+
+Copyright (c) 2025 Yak. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of Yak and are protected by copyright law.
+
+GRANT OF LICENSE:
+Subject to the terms of this license and your valid subscription or agreement
+with Yak, you are granted a limited, non-exclusive, non-transferable license
+to use the Software solely for integrating the Yak chatbot widget into your
+applications as intended and documented.
+
+RESTRICTIONS:
+You may NOT:
+- Modify, adapt, alter, translate, or create derivative works of the Software
+- Reverse engineer, disassemble, decompile, or otherwise attempt to derive
+  the source code of the Software
+- Redistribute, sublicense, lease, rent, or lend the Software to third parties
+- Remove or alter any proprietary notices, labels, or marks on the Software
+- Use the Software for any purpose other than as expressly permitted herein
+
+NO WARRANTY:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL YAK
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+TERMINATION:
+This license is effective until terminated. Your rights under this license
+will terminate automatically without notice if you fail to comply with any
+of its terms.
+
+For licensing inquiries, contact: support@yak.io

package/README.md

@@ -0,0 +1,32 @@
+# @yak-io/graphql
+
+GraphQL adapter for the [yak](https://yak.io) chatbot. Exposes a GraphQL API to the
+assistant as a single `graphql_<name>` tool: the model authors a query/mutation from the
+SDL you provide, and the adapter hands it to your client to execute — Yak never owns the transport.
+
+Adapters compose into a single tool manifest + `onToolCall` funnel via `createYakToolset`,
+so GraphQL calls flow through the same path as every other tool — including
+`onToolCallComplete` / `useYakToolEvent`.
+
+```ts
+import { createYakToolset } from "@yak-io/javascript";
+import { createGraphQLToolAdapter } from "@yak-io/graphql";
+import { typeDefs } from "@/lib/schema";
+
+const toolset = createYakToolset([
+  createGraphQLToolAdapter({
+    name: "shop",
+    schema: typeDefs,
+    // Run the model-authored request with your own client — Yak never owns the transport.
+    execute: (req) => myGraphQLClient.request(req.query, req.variables),
+  }),
+]);
+
+<YakProvider
+  appId={APP_ID}
+  getConfig={async () => ({ routes, ...(await toolset.getConfig()) })}
+  onToolCall={toolset.onToolCall}
+/>;
+```
+
+See the [docs](https://docs.yak.io/docs/tool-adapters/graphql) for full configuration.

package/dist/adapters.d.ts

@@ -0,0 +1,38 @@
+import type { GraphQLRequest, ToolAdapter } from "@yak-io/javascript";
+/** Config for {@link createGraphQLToolAdapter}. */
+export type GraphQLToolAdapterConfig = {
+    /** Schema name — the tool is exposed to the LLM as `graphql_<name>`. */
+    name: string;
+    /** GraphQL schema in SDL format. Embedded in the tool description so the LLM can author queries. */
+    schema: string;
+    /**
+     * Execute the LLM-authored GraphQL request with YOUR client. Yak builds the tool and the
+     * request payload (query / variables / operationName) but never makes the call itself — your
+     * client owns transport, auth, retries, and error handling. Use whatever you already have
+     * (Apollo, urql, graphql-request, a signed `fetch`, …). Return the result the assistant should
+     * see (typically the `data` field); throw to surface an error to the model.
+     */
+    execute: (request: GraphQLRequest) => unknown | Promise<unknown>;
+    /** Stable id for diagnostics. Defaults to the tool name. */
+    id?: string;
+};
+/**
+ * Create a GraphQL {@link ToolAdapter}. Compose it into a {@link createYakToolset} so the
+ * generated `graphql_<name>` tool joins the single merged manifest + `onToolCall` funnel
+ * (and therefore surfaces through `onToolCallComplete` / `useYakToolEvent`).
+ *
+ * The model authors a query/mutation from the SDL you provide; the adapter hands the request
+ * to your `execute` callback, which runs it with whatever client you already use. Yak never
+ * constructs the HTTP call — your client owns the endpoint, auth, and transport.
+ *
+ * @example
+ * ```ts
+ * const shop = createGraphQLToolAdapter({
+ *   name: "shop",
+ *   schema: typeDefs,
+ *   execute: (req) => myGraphQLClient.request(req.query, req.variables),
+ * });
+ * ```
+ */
+export declare function createGraphQLToolAdapter(config: GraphQLToolAdapterConfig): ToolAdapter;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAc,WAAW,EAAkB,MAAM,oBAAoB,CAAC;AAElG,mDAAmD;AACnD,MAAM,MAAM,wBAAwB,GAAG;IACrC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AA6BF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,WAAW,CA2BtF"}

package/dist/adapters.js

@@ -0,0 +1,68 @@
+/**
+ * Generic input schema for a GraphQL tool. The LLM authors the query + variables;
+ * the adapter hands them to your `execute` client. Do NOT inject `_reason` here — the
+ * chat-ui / voice runtimes inject it when registering the tool with the model.
+ */
+const GRAPHQL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "The GraphQL query or mutation string. Use $variableName syntax for all dynamic values.",
+        },
+        variables: {
+            type: "object",
+            description: "Variables object with values for all $variableName references in the query.",
+            additionalProperties: true,
+        },
+        operationName: {
+            type: "string",
+            description: "Optional operation name if the query contains multiple operations.",
+        },
+    },
+    required: ["query"],
+    additionalProperties: false,
+};
+/**
+ * Create a GraphQL {@link ToolAdapter}. Compose it into a {@link createYakToolset} so the
+ * generated `graphql_<name>` tool joins the single merged manifest + `onToolCall` funnel
+ * (and therefore surfaces through `onToolCallComplete` / `useYakToolEvent`).
+ *
+ * The model authors a query/mutation from the SDL you provide; the adapter hands the request
+ * to your `execute` callback, which runs it with whatever client you already use. Yak never
+ * constructs the HTTP call — your client owns the endpoint, auth, and transport.
+ *
+ * @example
+ * ```ts
+ * const shop = createGraphQLToolAdapter({
+ *   name: "shop",
+ *   schema: typeDefs,
+ *   execute: (req) => myGraphQLClient.request(req.query, req.variables),
+ * });
+ * ```
+ */
+export function createGraphQLToolAdapter(config) {
+    const toolName = `graphql_${config.name}`;
+    const tool = {
+        name: toolName,
+        description: `Execute a GraphQL query or mutation against the ${config.name} API. ` +
+            "You MUST use GraphQL variables for all dynamic values — never hardcode values directly in " +
+            "the query string. Define variables with $variableName syntax and pass them in the variables " +
+            `object.\n\nSchema (SDL):\n\`\`\`graphql\n${config.schema}\n\`\`\``,
+        inputSchema: GRAPHQL_INPUT_SCHEMA,
+    };
+    return {
+        id: config.id ?? toolName,
+        getTools: () => [tool],
+        ownsTool: (name) => name === toolName,
+        execute: async (_name, args) => {
+            const request = (args ?? {});
+            // Hand a clean request to the caller's client — never forward the runtime-injected `_reason`.
+            return config.execute({
+                query: request.query,
+                variables: request.variables,
+                operationName: request.operationName,
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createGraphQLToolAdapter } from "./adapters.js";
+export type { GraphQLToolAdapterConfig } from "./adapters.js";
+export type { GraphQLRequest, ToolAdapter, ToolDefinition } from "@yak-io/javascript";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAG9D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+// GraphQL tool adapter for the yak client toolset
+export { createGraphQLToolAdapter } from "./adapters.js";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@yak-io/graphql",
+  "version": "0.1.1",
+  "description": "GraphQL adapter for yak chatbot - exposes a GraphQL API as a chatbot tool",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Yak <support@yak.io>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/388-labs/yak.git",
+    "directory": "packages/graphql"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "yak",
+    "chatbot",
+    "ai",
+    "graphql",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome lint ./src --fix",
+    "format": "biome format ./src --write",
+    "prepare": "pnpm build"
+  },
+  "dependencies": {
+    "@yak-io/javascript": "workspace:*"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^24.12.4",
+    "typescript": "^5.3.0"
+  },
+  "homepage": "https://docs.yak.io/docs/tool-adapters/graphql"
+}