@yak-io/rest 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/rest
+
+REST / OpenAPI adapter for the [yak](https://yak.io) chatbot. Exposes a REST API to the
+assistant as a single `rest_<name>` tool: the model authors a request (method, path, query,
+body) from the OpenAPI spec 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 REST calls flow through the same path as every other tool — including
+`onToolCallComplete` / `useYakToolEvent`.
+
+```ts
+import { createYakToolset } from "@yak-io/javascript";
+import { createRESTToolAdapter } from "@yak-io/rest";
+import { openapiSpec } from "@/lib/openapi";
+
+const toolset = createYakToolset([
+  createRESTToolAdapter({
+    name: "billing",
+    spec: openapiSpec,
+    // Run the model-authored request with your own client — Yak never owns the transport.
+    execute: (req) => myApiClient(req.method, req.path, { query: req.query, body: req.body }),
+  }),
+]);
+
+<YakProvider
+  appId={APP_ID}
+  getConfig={async () => ({ routes, ...(await toolset.getConfig()) })}
+  onToolCall={toolset.onToolCall}
+/>;
+```
+
+See the [docs](https://docs.yak.io/docs/tool-adapters/rest) for full configuration.

package/dist/adapters.d.ts

@@ -0,0 +1,38 @@
+import type { RESTRequest, ToolAdapter } from "@yak-io/javascript";
+/** Config for {@link createRESTToolAdapter}. */
+export type RESTToolAdapterConfig = {
+    /** Spec name — the tool is exposed to the LLM as `rest_<name>`. */
+    name: string;
+    /** OpenAPI spec (object or string). Embedded in the tool description so the LLM can author requests. */
+    spec: Record<string, unknown> | string;
+    /**
+     * Execute the LLM-authored REST request with YOUR client. Yak builds the tool and the request
+     * shape (method / path / query / body) but never makes the call itself — your client owns the
+     * base URL, auth, transport, and error handling. Use whatever you already have (a configured
+     * `fetch` wrapper, axios, your app's API client, …). Return the result the assistant should
+     * see; throw to surface an error to the model.
+     */
+    execute: (request: RESTRequest) => unknown | Promise<unknown>;
+    /** Stable id for diagnostics. Defaults to the tool name. */
+    id?: string;
+};
+/**
+ * Create a REST {@link ToolAdapter}. Compose it into a {@link createYakToolset} so the generated
+ * `rest_<name>` tool joins the single merged manifest + `onToolCall` funnel (and therefore
+ * surfaces through `onToolCallComplete` / `useYakToolEvent`).
+ *
+ * The model authors a request from the OpenAPI spec you provide; the adapter hands it to your
+ * `execute` callback, which runs it with whatever client you already use. Yak never constructs
+ * the HTTP call — your client owns the base URL, auth, and transport.
+ *
+ * @example
+ * ```ts
+ * const billing = createRESTToolAdapter({
+ *   name: "billing",
+ *   spec: openapiSpec,
+ *   execute: (req) => myApiClient(req.method, req.path, { query: req.query, body: req.body }),
+ * });
+ * ```
+ */
+export declare function createRESTToolAdapter(config: RESTToolAdapterConfig): 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,EAAc,WAAW,EAAE,WAAW,EAAkB,MAAM,oBAAoB,CAAC;AAE/F,gDAAgD;AAChD,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IACvC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AA2BF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,WAAW,CA6BhF"}

package/dist/adapters.js

@@ -0,0 +1,68 @@
+/**
+ * Generic input schema for a REST tool. The LLM authors method/path/query/body;
+ * 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 REST_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        method: {
+            type: "string",
+            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+            description: "HTTP method for the request.",
+        },
+        path: { type: "string", description: "API path (e.g., '/users/123')." },
+        query: {
+            type: "object",
+            description: "Query parameters as key-value pairs.",
+            additionalProperties: { type: "string" },
+        },
+        body: { description: "Request body for POST/PUT/PATCH requests." },
+    },
+    required: ["method", "path"],
+    additionalProperties: false,
+};
+/**
+ * Create a REST {@link ToolAdapter}. Compose it into a {@link createYakToolset} so the generated
+ * `rest_<name>` tool joins the single merged manifest + `onToolCall` funnel (and therefore
+ * surfaces through `onToolCallComplete` / `useYakToolEvent`).
+ *
+ * The model authors a request from the OpenAPI spec you provide; the adapter hands it to your
+ * `execute` callback, which runs it with whatever client you already use. Yak never constructs
+ * the HTTP call — your client owns the base URL, auth, and transport.
+ *
+ * @example
+ * ```ts
+ * const billing = createRESTToolAdapter({
+ *   name: "billing",
+ *   spec: openapiSpec,
+ *   execute: (req) => myApiClient(req.method, req.path, { query: req.query, body: req.body }),
+ * });
+ * ```
+ */
+export function createRESTToolAdapter(config) {
+    const toolName = `rest_${config.name}`;
+    const specStr = typeof config.spec === "string" ? config.spec : JSON.stringify(config.spec, null, 2);
+    const tool = {
+        name: toolName,
+        description: `Make a REST API call to the ${config.name} API. Based on the OpenAPI spec below, ` +
+            "generate the appropriate request with method, path, query params, and body." +
+            `\n\nOpenAPI spec:\n\`\`\`json\n${specStr}\n\`\`\``,
+        inputSchema: REST_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({
+                method: request.method,
+                path: request.path,
+                query: request.query,
+                body: request.body,
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createRESTToolAdapter } from "./adapters.js";
+export type { RESTToolAdapterConfig } from "./adapters.js";
+export type { RESTRequest, 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,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG3D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@yak-io/rest",
+  "version": "0.1.1",
+  "description": "REST/OpenAPI adapter for yak chatbot - exposes a REST 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/rest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "yak",
+    "chatbot",
+    "ai",
+    "rest",
+    "openapi",
+    "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/rest"
+}