@yak-io/prismic 0.1.1 → 0.2.0

package/README.md

@@ -1,14 +1,10 @@
 # @yak-io/prismic
 
-Adapters that turn Prismic CMS documents into Yak routes, tools, and schema sources. This package plugs directly into `@yak-io/javascript` and works seamlessly with the Next.js and Nuxt helpers.
+> 📚 **Full documentation:** https://docs.yak.io/docs/sdks/prismic
+>
+> 🤖 **For LLMs / AI agents:** https://docs.yak.io/llms.txt
 
-## What you get
-
-- `createPrismicRouteAdapter` – produces a `RouteSource` from Prismic documents. Use it when your routes live in Prismic instead of (or alongside) the filesystem.
-- `createPrismicToolAdapter` – produces a `ToolSource` exposing `prismic.getByUID`, `prismic.getAllByType`, and `prismic.search` as tools the LLM can invoke.
-- `createPrismicSchemaSource` – produces a `SchemaSource` describing the Prismic content model so the LLM understands document types and fields.
-
-## Installation
+Prismic CMS adapter for [Yak](https://docs.yak.io). It turns Prismic documents into Yak **routes** (so the assistant knows your pages), **tools** (so it can fetch content), and a **GraphQL adapter** (so it can query your content model). Plugs into `@yak-io/javascript`'s `createYakHandler` or `@yak-io/nextjs`'s `createNextYakHandler`.
 
 ```bash
 pnpm add @yak-io/prismic @yak-io/javascript @prismicio/client
@@ -16,6 +12,14 @@ pnpm add @yak-io/prismic @yak-io/javascript @prismicio/client
 
 `@prismicio/client` is a peer dependency (v7+).
 
+## Exports
+
+| Export | Returns | Purpose |
+| --- | --- | --- |
+| `createPrismicRouteAdapter(config)` | `RouteSource` | Routes from Prismic documents — when pages live in Prismic. |
+| `createPrismicToolAdapter(config)` | `ToolSource` | Exposes `prismic.getByUID`, `prismic.getAllByType`, `prismic.search` as tools. |
+| `createPrismicGraphQLToolAdapter(config)` | `Promise<ToolAdapter>` | Introspects your repo's GraphQL schema and returns a browser-executed `graphql_prismic` tool. |
+
 ## Usage
 
 ### 1. Create a Prismic client
@@ -28,14 +32,11 @@ const client = prismic.createClient("your-repo-name", {
 });
 ```
 
-### 2. Use it with a Yak handler
+### 2. Wire adapters into a Yak handler (server)
 
 ```ts
 import { createNextYakHandler } from "@yak-io/nextjs/server";
-import {
-  createPrismicRouteAdapter,
-  createPrismicToolAdapter,
-} from "@yak-io/prismic";
+import { createPrismicRouteAdapter, createPrismicToolAdapter } from "@yak-io/prismic";
 
 const prismicRoutes = createPrismicRouteAdapter({
   client,
@@ -58,39 +59,75 @@ export const { GET, POST } = createNextYakHandler({
 });
 ```
 
-The adapters return standard `RouteSource` / `ToolSource` shapes, so you can compose them with filesystem routes, tRPC tools, or any other source by passing arrays.
-
-### 3. Optionally expose the content model
+Both return standard `RouteSource` / `ToolSource` shapes, so you can compose them with filesystem routes, tRPC tools, or any other source by passing arrays.
 
-Inside your client-side `getConfig` provider:
+### 3. Optionally expose the content model (client `getConfig` + `onToolCall`)
 
 ```ts
-import { createPrismicSchemaSource } from "@yak-io/prismic";
-
-const getConfig = async () => {
-  const res = await fetch("/api/yak");
-  const config = await res.json();
-  const schemaSource = await createPrismicSchemaSource({
-    client,
-    mode: "graphql",
-  });
-  return { ...config, schemaSources: [schemaSource] };
-};
+import { createYakServerAdapter, createYakToolset } from "@yak-io/react";
+import { createPrismicGraphQLToolAdapter } from "@yak-io/prismic";
+
+const toolset = createYakToolset([
+  createYakServerAdapter({ endpoint: "/api/yak" }),
+  await createPrismicGraphQLToolAdapter({ client }),
+]);
+
+const getConfig = async () => ({ routes, ...(await toolset.getConfig()) });
+const onToolCall = toolset.onToolCall;
 ```
 
+## API reference
+
+### `createPrismicRouteAdapter(config)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `client` | `Client` | — | Prismic client (required). |
+| `documentTypes` | `string[]` | — | Document types to turn into routes (required). |
+| `resolveRoute` | `(doc) => RouteInfo \| null` | — | Map a document to a route; return `null` to skip it (e.g. drafts) (required). |
+| `filters` | `string[]` | — | Prismic query filters. |
+| `id` | `string` | `"prismic"` | Source id. |
+
+### `createPrismicToolAdapter(config)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `client` | `Client` | — | Prismic client (required). |
+| `allowedTypes` | `string[]` | — | Document types the assistant may fetch (required). |
+| `fields` | `Record<string, string[]>` | — | Per-type field allowlist returned to the assistant. |
+| `id` | `string` | `"prismic"` | Source id. |
+
+### `createPrismicGraphQLToolAdapter(config)`
+
+Introspects the repo's `/graphql` endpoint once and returns a browser-executed `ToolAdapter`
+exposing a `graphql_<name>` tool. Compose it with `createYakToolset`.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `client` | `Client` | — | Prismic client (required). |
+| `name` | `string` | `"prismic"` | Tool name suffix — exposed as `graphql_<name>`. |
+| `endpoint` | `string` | derived `/graphql` URL | Override the GraphQL endpoint. |
+| `headers` | `HeadersInit \| (() => HeadersInit \| Promise<HeadersInit>)` | — | Execution headers (e.g. `Prismic-ref`). |
+| `fetchFn` | `typeof fetch` | global `fetch` | Custom fetch for the one-time introspection. |
+
+## Security
+
+- Always set `allowedTypes` on the tool adapter — without it the assistant could fetch any document type in your repository.
+- Return `null` from `resolveRoute` to keep drafts or hidden pages out of the route manifest.
+
 ## Types
 
-All route/tool/schema types are re-exported from `@yak-io/javascript/server`:
+Route, tool, and adapter types are re-exported for convenience:
 
 ```ts
-import type { RouteSource, ToolSource, SchemaSource } from "@yak-io/prismic";
+import type { RouteSource, ToolSource, ToolAdapter } from "@yak-io/prismic";
+import type {
+  PrismicRouteAdapterConfig,
+  PrismicToolAdapterConfig,
+  PrismicGraphQLToolAdapterConfig,
+} from "@yak-io/prismic";
 ```
 
-## Security tips
-
-- Always set `allowedTypes` on the tool adapter — without it the LLM can fetch any document type in your repository.
-- `resolveRoute` returning `null` skips a document — use this to filter drafts or hidden pages out of the manifest.
-
 ## License
 
-Proprietary - see LICENSE file
+Proprietary — see [LICENSE](./LICENSE).

package/dist/graphql-adapter.d.ts

@@ -0,0 +1,13 @@
+import type { ToolAdapter } from "@yak-io/javascript";
+import type { PrismicGraphQLToolAdapterConfig } from "./types.js";
+/**
+ * Introspect a Prismic repository's GraphQL schema and return a browser-executed
+ * GraphQL {@link ToolAdapter} (built on `@yak-io/graphql`). Compose it into a
+ * {@link createYakToolset}; the LLM authors queries from the introspected SDL and
+ * the adapter executes them against the repo's GraphQL endpoint.
+ *
+ * Prismic's GraphQL endpoint requires a `Prismic-ref` header at execution time —
+ * supply it via `headers` (it may be async to fetch the master ref per call).
+ */
+export declare function createPrismicGraphQLToolAdapter(config: PrismicGraphQLToolAdapterConfig): Promise<ToolAdapter>;
+//# sourceMappingURL=graphql-adapter.d.ts.map

package/dist/graphql-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-adapter.d.ts","sourceRoot":"","sources":["../src/graphql-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAyGlE;;;;;;;;GAQG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,WAAW,CAAC,CAsDtB"}

package/dist/{schema-source.js → graphql-adapter.js}

@@ -1,3 +1,4 @@
+import { createGraphQLToolAdapter } from "@yak-io/graphql";
 const INTROSPECTION_QUERY = `query IntrospectionQuery {
   __schema {
     queryType { name }
@@ -75,20 +76,36 @@ function deriveGraphQLEndpoint(restEndpoint) {
     const trimmed = restEndpoint.replace(/\/api\/v\d+\/?$/, "");
     return `${trimmed}/graphql`;
 }
+async function buildHeaders(source, base) {
+    const headers = new Headers(base);
+    const resolved = typeof source === "function" ? await source() : source;
+    if (resolved) {
+        for (const [key, value] of new Headers(resolved)) {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
 async function loadGraphQLModule() {
     try {
         return await import("graphql");
     }
     catch {
-        throw new Error("createPrismicSchemaSource with mode 'graphql' requires the 'graphql' package. Install it as a peer dependency: pnpm add graphql");
+        throw new Error("createPrismicGraphQLToolAdapter requires the 'graphql' package. Install it as a peer dependency: pnpm add graphql");
     }
 }
-export async function createPrismicSchemaSource(config) {
-    if (config.mode !== "graphql") {
-        throw new Error(`Unsupported schema source mode: ${config.mode}`);
-    }
+/**
+ * Introspect a Prismic repository's GraphQL schema and return a browser-executed
+ * GraphQL {@link ToolAdapter} (built on `@yak-io/graphql`). Compose it into a
+ * {@link createYakToolset}; the LLM authors queries from the introspected SDL and
+ * the adapter executes them against the repo's GraphQL endpoint.
+ *
+ * Prismic's GraphQL endpoint requires a `Prismic-ref` header at execution time —
+ * supply it via `headers` (it may be async to fetch the master ref per call).
+ */
+export async function createPrismicGraphQLToolAdapter(config) {
     const fetchFn = config.fetchFn ?? fetch;
-    const endpoint = deriveGraphQLEndpoint(config.client.endpoint);
+    const endpoint = config.endpoint ?? deriveGraphQLEndpoint(config.client.endpoint);
     const response = await fetchFn(endpoint, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -104,9 +121,30 @@ export async function createPrismicSchemaSource(config) {
     const { buildClientSchema, printSchema } = await loadGraphQLModule();
     const schema = buildClientSchema(payload.data);
     const sdl = printSchema(schema);
-    return {
+    return createGraphQLToolAdapter({
         name: config.name ?? "prismic",
-        type: "graphql",
         schema: sdl,
-    };
+        id: config.id,
+        // Prismic owns its own transport: POST the model-authored query to the repo's GraphQL
+        // endpoint with the caller-supplied headers (typically the required `Prismic-ref`).
+        execute: async (request) => {
+            const res = await fetchFn(endpoint, {
+                method: "POST",
+                headers: await buildHeaders(config.headers, { "Content-Type": "application/json" }),
+                body: JSON.stringify({
+                    query: request.query,
+                    variables: request.variables,
+                    operationName: request.operationName,
+                }),
+            });
+            if (!res.ok) {
+                throw new Error(`Prismic GraphQL request failed (${res.status})`);
+            }
+            const payload = (await res.json());
+            if (payload.errors?.length) {
+                throw new Error(payload.errors[0]?.message ?? "Prismic GraphQL request returned errors");
+            }
+            return payload.data;
+        },
+    });
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
+export { createPrismicGraphQLToolAdapter } from "./graphql-adapter.js";
 export { createPrismicRouteAdapter } from "./route-adapter.js";
 export { createPrismicToolAdapter } from "./tool-adapter.js";
-export { createPrismicSchemaSource } from "./schema-source.js";
-export type { PrismicRouteAdapterConfig, PrismicToolAdapterConfig, PrismicSchemaSourceConfig, PrismicGraphQLSchemaSourceConfig, } from "./types.js";
+export type { PrismicGraphQLToolAdapterConfig, PrismicRouteAdapterConfig, PrismicToolAdapterConfig, } from "./types.js";
 export type { RouteInfo, RouteSource, ToolDefinition, ToolExecutor, ToolManifest, ToolSource, } from "@yak-io/javascript/server";
-export type { GraphQLSchemaSource, OpenAPISchemaSource, SchemaSource } from "@yak-io/javascript";
+export type { ToolAdapter } from "@yak-io/javascript";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,gCAAgC,GACjC,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,3 +1,3 @@
+export { createPrismicGraphQLToolAdapter } from "./graphql-adapter.js";
 export { createPrismicRouteAdapter } from "./route-adapter.js";
 export { createPrismicToolAdapter } from "./tool-adapter.js";
-export { createPrismicSchemaSource } from "./schema-source.js";

package/dist/types.d.ts

@@ -13,11 +13,23 @@ export type PrismicToolAdapterConfig = {
     allowedTypes: string[];
     fields?: Record<string, string[]>;
 };
-export type PrismicGraphQLSchemaSourceConfig = {
+export type PrismicGraphQLToolAdapterConfig = {
     client: Client;
-    mode: "graphql";
+    /** Tool name suffix — the tool is exposed as `graphql_<name>`. Defaults to "prismic". */
     name?: string;
+    /**
+     * Override the GraphQL endpoint used for execution. Defaults to the repo's
+     * derived `/graphql` URL (from the client's REST endpoint).
+     */
+    endpoint?: string;
+    /**
+     * Extra headers (e.g. `Prismic-ref`, `Authorization`) applied to query
+     * execution. May be async to fetch the master ref per call.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Custom fetch used for the one-time schema introspection (useful in tests). */
     fetchFn?: typeof fetch;
+    /** Stable adapter id for diagnostics. */
+    id?: string;
 };
-export type PrismicSchemaSourceConfig = PrismicGraphQLSchemaSourceConfig;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,SAAS,GAAG,IAAI,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,gCAAgC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,SAAS,GAAG,IAAI,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yak-io/prismic",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Prismic CMS adapter for yak chatbot - exposes Prismic documents as routes, tools, and schema sources",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -24,6 +24,7 @@
     "node": ">=18"
   },
   "files": [
+    "README.md",
     "dist",
     "LICENSE"
   ],
@@ -40,7 +41,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@yak-io/javascript": "0.8.0"
+    "@yak-io/graphql": "0.1.1",
+    "@yak-io/javascript": "0.10.0"
   },
   "peerDependencies": {
     "@prismicio/client": "^7.0.0",
@@ -58,6 +60,7 @@
     "typescript": "^5.3.0",
     "@repo/typescript-config": "0.0.0"
   },
+  "homepage": "https://docs.yak.io/docs/sdks/prismic",
   "scripts": {
     "build": "tsc",
     "check-types": "tsc --noEmit",

package/dist/schema-source.d.ts

@@ -1,4 +0,0 @@
-import type { GraphQLSchemaSource } from "@yak-io/javascript";
-import type { PrismicSchemaSourceConfig } from "./types.js";
-export declare function createPrismicSchemaSource(config: PrismicSchemaSourceConfig): Promise<GraphQLSchemaSource>;
-//# sourceMappingURL=schema-source.d.ts.map

package/dist/schema-source.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema-source.d.ts","sourceRoot":"","sources":["../src/schema-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AA2F5D,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAkC9B"}