@genkit-ai/fetch 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# Genkit Web Fetch Plugin
+
+This plugin provides utilities for exposing Genkit actions (flows, models, etc.) over the **Web Fetch API** (`Request` / `Response`). Use it with any runtime or framework that supports the standard Fetch API (such as Hono, Bun, Cloudflare Workers, Deno, Node (18+), Vercel Edge, Netlify Edge, Elysia, SvelteKit, etc). Express-like API: pass the action first, then call the returned handler with the request.
+
+No framework-specific dependencies; only `genkit` and the standard Web APIs.
+
+## Installation
+
+```bash
+npm i @genkit-ai/fetch
+```
+
+## Usage (Hono)
+
+### Single action with `fetchHandler`
+
+```ts
+import { fetchHandler } from '@genkit-ai/fetch';
+import { Hono } from 'hono';
+
+const simpleFlow = ai.defineFlow('simpleFlow', async (input, { sendChunk }) => {
+  const { text } = await ai.generate({
+    model: googleAI.model('gemini-2.0-flash'),
+    prompt: input,
+    onChunk: (c) => sendChunk(c.text),
+  });
+  return text;
+});
+
+const app = new Hono();
+app.all('/simpleFlow', (c) => fetchHandler(simpleFlow)(c.req.raw));
+```
+
+For a model, resolve it from the plugin then pass to `fetchHandler`:
+
+```ts
+const gai = googleAI();
+const model = await gai.model('gemini-2.0-flash');
+app.post('/models/gemini-flash', (c) => fetchHandler(model)(c.req.raw));
+```
+
+### Multiple actions with `fetchHandlers`
+
+Mount several actions (flows, models, etc.) under one path; the action is selected by the request path (e.g. `/api/hello` runs the action named `hello`):
+
+```ts
+import { fetchHandlers } from '@genkit-ai/fetch';
+
+const actions = [helloFlow, greetingFlow, streamingFlow];
+
+app.all('/api/*', (c) => fetchHandlers(actions, '/api')(c.req.raw));
+```
+
+Clients call `POST /api/<actionName>` with body `{ "data": <input> }`.
+
+### Auth with context providers
+
+Use a context provider (e.g. for auth) and attach it to an action with `withActionOptions`:
+
+```ts
+import { UserFacingError } from 'genkit';
+import type { ContextProvider, RequestData } from 'genkit/context';
+import { fetchHandler, fetchHandlers, withActionOptions } from '@genkit-ai/fetch';
+
+const authContext: ContextProvider<{ userId: string }> = (req: RequestData) => {
+  if (req.headers['authorization'] !== 'Bearer open-sesame') {
+    throw new UserFacingError('PERMISSION_DENIED', 'not authorized');
+  }
+  return { userId: 'authenticated-user' };
+};
+
+// Single action with auth
+app.all('/secureFlow', (c) =>
+  fetchHandler(secureFlow, { contextProvider: authContext })(c.req.raw)
+);
+
+// Or wrap the action for use with fetchHandlers
+const actions = [
+  publicFlow,
+  withActionOptions(secureFlow, { contextProvider: authContext }),
+];
+app.all('/api/*', (c) => fetchHandlers(actions, '/api')(c.req.raw));
+```
+
+### Durable streaming (Beta)
+
+You can configure actions to use a `StreamManager` so stream state is persisted. Clients can disconnect and reconnect without losing the stream.
+
+Provide a `streamManager` in the options. For development, use `InMemoryStreamManager`:
+
+```ts
+import { InMemoryStreamManager } from 'genkit/beta';
+import { fetchHandler, fetchHandlers, withActionOptions } from '@genkit-ai/fetch';
+
+app.all('/myDurableFlow', (c) =>
+  fetchHandler(myFlow, {
+    streamManager: new InMemoryStreamManager(),
+  })(c.req.raw)
+);
+
+// Or with fetchHandlers
+const actions = [
+  withActionOptions(myFlow, {
+    streamManager: new InMemoryStreamManager(),
+  }),
+];
+app.all('/api/*', (c) => fetchHandlers(actions, '/api')(c.req.raw));
+```
+
+For production, use a durable implementation such as `FirestoreStreamManager` or `RtdbStreamManager` from `@genkit-ai/firebase`, or a custom `StreamManager`.
+
+Clients can reconnect using the `streamId`:
+
+```ts
+import { streamFlow } from 'genkit/beta/client';
+
+// Start a new stream
+const result = streamFlow({
+  url: 'http://localhost:3780/api/myDurableFlow',
+  input: 'tell me a long story',
+});
+const streamId = await result.streamId; // save for reconnect
+
+// Reconnect later
+const reconnected = streamFlow({
+  url: 'http://localhost:3780/api/myDurableFlow',
+  streamId,
+});
+```
+
+### Calling actions from the client
+
+Use `runFlow` and `streamFlow` from `genkit/beta/client` (same protocol as the Express plugin):
+
+```ts
+import { runFlow, streamFlow } from 'genkit/beta/client';
+
+const result = await runFlow({
+  url: 'http://localhost:3780/api/hello',
+  input: 'world',
+});
+console.log(result);
+
+// With auth headers
+const result = await runFlow({
+  url: 'http://localhost:3780/api/secureGreeting',
+  headers: { Authorization: 'Bearer open-sesame' },
+  input: { name: 'Alex' },
+});
+
+// Streaming
+const result = streamFlow({
+  url: 'http://localhost:3780/api/streaming',
+  input: { prompt: 'Say hello in chunks' },
+});
+for await (const chunk of result.stream) {
+  console.log(chunk);
+}
+console.log(await result.output);
+```
+
+## API summary
+
+| Export              | Description                                                                 |
+|---------------------|-----------------------------------------------------------------------------|
+| `fetchHandler(action, options?)` | Returns a handler `(request) => Promise<Response>` for a single action (flow, model, etc.). |
+| `fetchHandlers(actions, pathPrefix?)` | Returns a handler that dispatches by path to one of the given actions.   |
+| `withActionOptions(action, options)`  | Wraps an action with `contextProvider`, `streamManager`, or custom `path`. |
+| `ActionWithOptions` | Type for an action plus options.                                            |
+| `FetchHandlerOptions` | Options for `fetchHandler`: `contextProvider`, `streamManager`.            |
+
+Request body must be JSON with a `data` field: `{ "data": <input> }`. For streaming, use `Accept: text/event-stream` or query `?stream=true`.
+
+## Contributing
+
+The sources for this package are in the main [Genkit](https://github.com/firebase/genkit) repo. Please file issues and pull requests there.
+
+More details are in the [Genkit documentation](https://genkit.dev/docs/get-started/).
+
+## License
+
+Licensed under the Apache 2.0 License.

package/lib/index.d.mts

@@ -0,0 +1,65 @@
+import { z, Action, StreamManager, ActionContext } from 'genkit/beta';
+import { ContextProvider } from 'genkit/context';
+
+/**
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * A wrapper object containing an action with its associated options.
+ */
+type ActionWithOptions<I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny, S extends z.ZodTypeAny = z.ZodTypeAny> = {
+    action: Action<I, O, S>;
+    options: {
+        contextProvider?: ContextProvider<any, I>;
+        streamManager?: StreamManager;
+        path?: string;
+    };
+};
+/**
+ * Options for a fetch handler (context provider, stream manager).
+ */
+interface FetchHandlerOptions<C extends ActionContext = ActionContext, I extends z.ZodTypeAny = z.ZodTypeAny> {
+    contextProvider?: ContextProvider<C, I>;
+    streamManager?: StreamManager;
+}
+/**
+ * Wraps an action (flow, model, etc.) with options for use with {@link fetchHandlers}.
+ */
+declare function withActionOptions<I extends z.ZodTypeAny, O extends z.ZodTypeAny, S extends z.ZodTypeAny>(action: Action<I, O, S>, options: {
+    contextProvider?: ContextProvider<any, I>;
+    streamManager?: StreamManager;
+    path?: string;
+}): ActionWithOptions<I, O, S>;
+declare function fetchHandler<C extends ActionContext = ActionContext, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny, S extends z.ZodTypeAny = z.ZodTypeAny>(action: Action<I, O, S>, options?: FetchHandlerOptions<C, I>): (request: Request) => Promise<Response>;
+/**
+ * Returns a Fetch handler for multiple actions with path-based routing.
+ * Express-like API: pass actions and optional path prefix, then call the returned handler with the request.
+ *
+ * @param actions - Array of actions (or ActionWithOptions) to expose; each is routed by path (action name or options.path)
+ * @param pathPrefix - Optional path prefix to strip from the URL (e.g., '/api')
+ * @returns A handler function that takes a Request and returns a Promise<Response>
+ *
+ * @example
+ * ```typescript
+ * import { fetchHandlers } from '@genkit-ai/fetch';
+ *
+ * // Mount all actions under /api - routes by path (e.g. POST /api/hello, POST /api/models/gpt5)
+ * app.all('/api/*', (c) => fetchHandlers(actions, '/api')(c.req.raw));
+ * ```
+ */
+declare function fetchHandlers(actions: (Action<any, any, any> | ActionWithOptions<any, any, any>)[], pathPrefix?: string): (request: Request) => Promise<Response>;
+
+export { type ActionWithOptions, type FetchHandlerOptions, fetchHandler, fetchHandlers, withActionOptions };

package/lib/index.d.ts

@@ -0,0 +1,65 @@
+import { z, Action, StreamManager, ActionContext } from 'genkit/beta';
+import { ContextProvider } from 'genkit/context';
+
+/**
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * A wrapper object containing an action with its associated options.
+ */
+type ActionWithOptions<I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny, S extends z.ZodTypeAny = z.ZodTypeAny> = {
+    action: Action<I, O, S>;
+    options: {
+        contextProvider?: ContextProvider<any, I>;
+        streamManager?: StreamManager;
+        path?: string;
+    };
+};
+/**
+ * Options for a fetch handler (context provider, stream manager).
+ */
+interface FetchHandlerOptions<C extends ActionContext = ActionContext, I extends z.ZodTypeAny = z.ZodTypeAny> {
+    contextProvider?: ContextProvider<C, I>;
+    streamManager?: StreamManager;
+}
+/**
+ * Wraps an action (flow, model, etc.) with options for use with {@link fetchHandlers}.
+ */
+declare function withActionOptions<I extends z.ZodTypeAny, O extends z.ZodTypeAny, S extends z.ZodTypeAny>(action: Action<I, O, S>, options: {
+    contextProvider?: ContextProvider<any, I>;
+    streamManager?: StreamManager;
+    path?: string;
+}): ActionWithOptions<I, O, S>;
+declare function fetchHandler<C extends ActionContext = ActionContext, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny, S extends z.ZodTypeAny = z.ZodTypeAny>(action: Action<I, O, S>, options?: FetchHandlerOptions<C, I>): (request: Request) => Promise<Response>;
+/**
+ * Returns a Fetch handler for multiple actions with path-based routing.
+ * Express-like API: pass actions and optional path prefix, then call the returned handler with the request.
+ *
+ * @param actions - Array of actions (or ActionWithOptions) to expose; each is routed by path (action name or options.path)
+ * @param pathPrefix - Optional path prefix to strip from the URL (e.g., '/api')
+ * @returns A handler function that takes a Request and returns a Promise<Response>
+ *
+ * @example
+ * ```typescript
+ * import { fetchHandlers } from '@genkit-ai/fetch';
+ *
+ * // Mount all actions under /api - routes by path (e.g. POST /api/hello, POST /api/models/gpt5)
+ * app.all('/api/*', (c) => fetchHandlers(actions, '/api')(c.req.raw));
+ * ```
+ */
+declare function fetchHandlers(actions: (Action<any, any, any> | ActionWithOptions<any, any, any>)[], pathPrefix?: string): (request: Request) => Promise<Response>;
+
+export { type ActionWithOptions, type FetchHandlerOptions, fetchHandler, fetchHandlers, withActionOptions };

package/lib/index.js

@@ -0,0 +1,353 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  fetchHandler: () => fetchHandler,
+  fetchHandlers: () => fetchHandlers,
+  withActionOptions: () => withActionOptions
+});
+module.exports = __toCommonJS(index_exports);
+var import_beta = require("genkit/beta");
+var import_context = require("genkit/context");
+var import_logging = require("genkit/logging");
+var import_utils = require("./utils.js");
+const streamDelimiter = "\n\n";
+const randomUUID = () => globalThis.crypto.randomUUID();
+function withActionOptions(action, options) {
+  return {
+    action,
+    options
+  };
+}
+function headersToObject(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key.toLowerCase()] = value;
+  });
+  return result;
+}
+async function getContext(request, input, provider) {
+  const context = {};
+  if (!provider) {
+    return context;
+  }
+  const requestData = {
+    method: request.method,
+    headers: headersToObject(request.headers),
+    input
+  };
+  return await provider(requestData);
+}
+async function subscribeToStream(streamManager, streamId) {
+  try {
+    const encoder = new TextEncoder();
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    await streamManager.subscribe(streamId, {
+      onChunk: (chunk) => {
+        writer.write(
+          encoder.encode(
+            "data: " + JSON.stringify({ message: chunk }) + streamDelimiter
+          )
+        );
+      },
+      onDone: (output) => {
+        writer.write(
+          encoder.encode(
+            "data: " + JSON.stringify({ result: output }) + streamDelimiter
+          )
+        );
+        writer.close();
+      },
+      onError: (err) => {
+        import_logging.logger.error(
+          `Streaming request failed with error: ${(0, import_utils.getErrorMessage)(err)}
+${(0, import_utils.getErrorStack)(err)}`
+        );
+        writer.write(
+          encoder.encode(
+            `error: ${JSON.stringify({
+              error: (0, import_context.getCallableJSON)(err)
+            })}${streamDelimiter}`
+          )
+        );
+        writer.close();
+      }
+    });
+    return new Response(readable, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Transfer-Encoding": "chunked",
+        "x-genkit-stream-id": streamId
+      }
+    });
+  } catch (e) {
+    if (e instanceof import_beta.StreamNotFoundError) {
+      return new Response(null, { status: 204 });
+    }
+    if (e.status === "DEADLINE_EXCEEDED") {
+      const encoder = new TextEncoder();
+      const { readable, writable } = new TransformStream();
+      const writer = writable.getWriter();
+      writer.write(
+        encoder.encode(
+          `error: ${JSON.stringify({
+            error: (0, import_context.getCallableJSON)(e)
+          })}${streamDelimiter}`
+        )
+      );
+      writer.close();
+      return new Response(readable, {
+        status: 200,
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+          "Transfer-Encoding": "chunked"
+        }
+      });
+    }
+    throw e;
+  }
+}
+async function runActionWithDurableStreaming(action, streamManager, streamId, input, context, writer, abortSignal) {
+  const encoder = new TextEncoder();
+  let taskQueue;
+  let durableStream;
+  if (streamManager) {
+    taskQueue = new import_beta.AsyncTaskQueue();
+    durableStream = await streamManager.open(streamId);
+  }
+  try {
+    let onChunk = (chunk) => {
+      writer.write(
+        encoder.encode(
+          "data: " + JSON.stringify({ message: chunk }) + streamDelimiter
+        )
+      );
+    };
+    if (streamManager && durableStream) {
+      const originalOnChunk = onChunk;
+      onChunk = (chunk) => {
+        originalOnChunk(chunk);
+        taskQueue.enqueue(() => durableStream.write(chunk));
+      };
+    }
+    const result = await action.run(input, {
+      onChunk,
+      context,
+      abortSignal
+    });
+    if (streamManager && durableStream) {
+      taskQueue.enqueue(() => durableStream.done(result.result));
+      await taskQueue.merge();
+    }
+    writer.write(
+      encoder.encode(
+        "data: " + JSON.stringify({ result: result.result }) + streamDelimiter
+      )
+    );
+    writer.close();
+  } catch (e) {
+    if (durableStream) {
+      taskQueue.enqueue(() => durableStream.error(e));
+      await taskQueue.merge();
+    }
+    import_logging.logger.error(
+      `Streaming request failed with error: ${e.message}
+${e.stack}`
+    );
+    writer.write(
+      encoder.encode(
+        `error: ${JSON.stringify({
+          error: (0, import_context.getCallableJSON)(e)
+        })}${streamDelimiter}`
+      )
+    );
+    writer.close();
+  }
+}
+async function handleActionRequest(request, action, options) {
+  const url = new URL(request.url);
+  const streamParam = url.searchParams.get("stream");
+  const shouldStream = streamParam === "true";
+  const streamIdHeader = request.headers.get("x-genkit-stream-id");
+  const streamId = streamIdHeader || void 0;
+  let body;
+  try {
+    body = await request.json();
+  } catch (e) {
+    const errMsg = `Error: Failed to parse request body as JSON. Make sure the request has 'Content-Type: application/json' header.`;
+    import_logging.logger.error(errMsg);
+    return new Response(
+      JSON.stringify({ message: errMsg, status: "INVALID_ARGUMENT" }),
+      { status: 400, headers: { "Content-Type": "application/json" } }
+    );
+  }
+  if (!body || typeof body !== "object" || !("data" in body)) {
+    const errMsg = `Error: Request body must be a JSON object with a 'data' field. Expected format: {"data": ...}`;
+    import_logging.logger.error(errMsg);
+    return new Response(
+      JSON.stringify({ message: errMsg, status: "INVALID_ARGUMENT" }),
+      { status: 400, headers: { "Content-Type": "application/json" } }
+    );
+  }
+  const input = body.data;
+  let context;
+  try {
+    context = await getContext(request, input, options?.contextProvider);
+  } catch (e) {
+    import_logging.logger.error(
+      `Context provider failed with error: ${e.message}
+${e.stack}`
+    );
+    return new Response(JSON.stringify((0, import_context.getCallableJSON)(e)), {
+      status: (0, import_context.getHttpStatus)(e),
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  const acceptHeader = request.headers.get("Accept") || "";
+  const isStreaming = acceptHeader === "text/event-stream" || shouldStream;
+  if (isStreaming) {
+    const streamManager = options?.streamManager;
+    if (streamManager && streamId) {
+      const response = await subscribeToStream(streamManager, streamId);
+      if (response) {
+        return response;
+      }
+    }
+    const streamIdToUse = randomUUID();
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    runActionWithDurableStreaming(
+      action,
+      options?.streamManager,
+      streamIdToUse,
+      input,
+      context,
+      writer,
+      request.signal
+    ).catch((err) => {
+      import_logging.logger.error(`Error in streaming handler: ${err}`);
+    });
+    const headers = {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "Transfer-Encoding": "chunked"
+    };
+    if (options?.streamManager) {
+      headers["x-genkit-stream-id"] = streamIdToUse;
+    }
+    return new Response(readable, {
+      status: 200,
+      headers
+    });
+  }
+  try {
+    const result = await action.run(input, {
+      context,
+      abortSignal: request.signal
+    });
+    const headers = {
+      "x-genkit-trace-id": result.telemetry.traceId,
+      "x-genkit-span-id": result.telemetry.spanId
+    };
+    return new Response(JSON.stringify({ result: result.result }), {
+      status: 200,
+      headers: { "Content-Type": "application/json", ...headers }
+    });
+  } catch (e) {
+    import_logging.logger.error(
+      `Non-streaming request failed with error: ${e.message}
+${e.stack}`
+    );
+    return new Response(JSON.stringify((0, import_context.getCallableJSON)(e)), {
+      status: (0, import_context.getHttpStatus)(e),
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+}
+function fetchHandler(action, options) {
+  return (request) => handleActionRequest(request, action, options);
+}
+function fetchHandlers(actions, pathPrefix) {
+  return async (request) => {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+    if (pathPrefix) {
+      const prefix = pathPrefix.endsWith("/") ? pathPrefix : pathPrefix + "/";
+      if (pathname === pathPrefix) {
+        pathname = "";
+      } else if (pathname.startsWith(prefix)) {
+        pathname = pathname.slice(prefix.length);
+      } else {
+        return new Response(
+          JSON.stringify({
+            status: "NOT_FOUND",
+            message: "No action matched the request path."
+          }),
+          { status: 404, headers: { "Content-Type": "application/json" } }
+        );
+      }
+    }
+    pathname = pathname.replace(/^\//, "");
+    let matchedAction = null;
+    let handlerOptions = void 0;
+    for (const item of actions) {
+      if ("action" in item) {
+        const options = item.options;
+        const actionPath = options.path ?? item.action.__action.name;
+        if (pathname === actionPath) {
+          matchedAction = item.action;
+          handlerOptions = {
+            contextProvider: options.contextProvider,
+            streamManager: options.streamManager
+          };
+          break;
+        }
+      } else {
+        if (pathname === item.__action.name) {
+          matchedAction = item;
+          break;
+        }
+      }
+    }
+    if (!matchedAction) {
+      return new Response(
+        JSON.stringify({
+          status: "NOT_FOUND",
+          message: "No action matched the request path."
+        }),
+        { status: 404, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    return handleActionRequest(request, matchedAction, handlerOptions);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchHandler,
+  fetchHandlers,
+  withActionOptions
+});
+//# sourceMappingURL=index.js.map