@skein-js/nextjs 0.7.0 → 0.9.0

package/README.md

@@ -50,6 +50,23 @@ export default createSkeinPagesHandler({ config: "./langgraph.json" });
 Both entry points accept the shared `{ config } | { deps }` seam, an optional `cors` (off by default),
 and a `basePath` (defaults to `/api`, matching the mount above).
 
+## Graphs as plain endpoints (non-chat)
+
+For workloads that aren't chat — a classifier, an extractor, a workflow another service calls — there
+is a smaller surface: every graph mounted as `POST <basePath>/:graph_id`, where the request body **is**
+the graph input and the response **is** the final state. No threads, assistants, or runs.
+
+```ts
+// app/api/invoke/[graph_id]/route.ts
+import { createSkeinInvokeRouteHandlers } from "@skein-js/nextjs";
+
+export const runtime = "nodejs";
+export const { POST } = createSkeinInvokeRouteHandlers({ deps, basePath: "/api/invoke" });
+```
+
+Send `Accept: text/event-stream` to stream the steps instead. See
+[docs/serving-a-single-graph.md](../../docs/serving-a-single-graph.md).
+
 ## Deployment caveat
 
 The background run worker and the in-memory driver need a **long-lived Node process** — fine on
@@ -63,6 +80,9 @@ The background run worker and the in-memory driver need a **long-lived Node proc
   `{ GET, POST, PUT, PATCH, DELETE, OPTIONS }` to re-export from `app/<base>/[...path]/route.ts`.
 - **`createSkeinPagesHandler(options): SkeinPagesHandler`** — Pages Router; the default export for
   `pages/api/[...path].ts`.
+- **`createSkeinInvokeRouteHandlers(options): SkeinInvokeRouteHandlers`** — the simplified serving
+  surface (`POST <basePath>/:graph_id`, body-in / final-state-out); returns `{ POST, OPTIONS }` for
+  `app/api/invoke/[graph_id]/route.ts`. `basePath` defaults to `/api/invoke`; adds `streamMode`.
 - Both accept `SkeinRouteHandlerOptions` / `SkeinPagesHandlerOptions`: the shared
   `{ config, importModule? } | { deps }` seam **plus** an optional `cors` (off by default) and a
   `basePath` (defaults to `/api`, matching the mount). `deps` comes from

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { SkeinRuntimeOptions, ResolvedProtocolRuntime } from '@skein-js/server-kit';
+import { SkeinRuntimeOptions, ResolvedRuntimeDeps, ResolvedProtocolRuntime } from '@skein-js/server-kit';
 export { SkeinRuntimeOptions, sendNodeError, sendNodeResponse } from '@skein-js/server-kit';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { ProtocolResponse, Logger } from '@skein-js/agent-protocol';
+import { GraphInvokeOptions, ProtocolResponse, Logger } from '@skein-js/agent-protocol';
 
 /** Options for the App Router handlers: the shared runtime options plus where the catch-all is mounted. */
 type SkeinRouteHandlerOptions = SkeinRuntimeOptions & {
@@ -40,13 +40,31 @@ type SkeinPagesHandler = (req: SkeinPagesRequest, res: ServerResponse) => Promis
 /** Build the Pages Router API handler for the given options. */
 declare function createSkeinPagesHandler(options: SkeinPagesHandlerOptions): SkeinPagesHandler;
 
-type RuntimePromise = Promise<ResolvedProtocolRuntime>;
+type SkeinInvokeRouteHandlerOptions = SkeinRuntimeOptions & GraphInvokeOptions & {
+    /**
+     * The path this route is mounted at, stripped before reading the trailing `:graph_id` segment.
+     * Defaults to `/api/invoke` (i.e. `app/api/invoke/[graph_id]/route.ts`).
+     */
+    basePath?: string;
+};
+interface SkeinInvokeRouteHandlers {
+    POST: (request: Request) => Promise<Response>;
+    OPTIONS: (request: Request) => Promise<Response>;
+}
+/** Build the App Router handlers for the invoke surface. */
+declare function createSkeinInvokeRouteHandlers(options: SkeinInvokeRouteHandlerOptions): SkeinInvokeRouteHandlers;
+
 /** Resolve (once) the runtime for these options, reusing the cached promise across module reloads. */
-declare function getSkeinRuntime(options: SkeinRuntimeOptions): RuntimePromise;
+declare function getSkeinRuntime(options: SkeinRuntimeOptions): Promise<ResolvedProtocolRuntime>;
+/**
+ * Resolve (once) just the deps for these options — what the simplified invoke surface needs, since it
+ * seeds no assistants and starts no background run worker.
+ */
+declare function getSkeinInvokeDeps(options: SkeinRuntimeOptions): Promise<ResolvedRuntimeDeps>;
 
 /** Serialize a `ProtocolResponse` into a Web `Response`, merging any `extraHeaders` (e.g. CORS). */
 declare function toWebResponse(response: ProtocolResponse, extraHeaders?: Record<string, string>): Response;
 /** Map a thrown error onto a Web `Response` — `SkeinHttpError` to its status, else a logged 500. */
 declare function webErrorResponse(error: unknown, extraHeaders?: Record<string, string>, logger?: Logger): Response;
 
-export { type SkeinPagesHandler, type SkeinPagesHandlerOptions, type SkeinPagesRequest, type SkeinRouteHandler, type SkeinRouteHandlerOptions, type SkeinRouteHandlers, createSkeinPagesHandler, createSkeinRouteHandlers, getSkeinRuntime, toWebResponse, webErrorResponse };
+export { type SkeinInvokeRouteHandlerOptions, type SkeinInvokeRouteHandlers, type SkeinPagesHandler, type SkeinPagesHandlerOptions, type SkeinPagesRequest, type SkeinRouteHandler, type SkeinRouteHandlerOptions, type SkeinRouteHandlers, createSkeinInvokeRouteHandlers, createSkeinPagesHandler, createSkeinRouteHandlers, getSkeinInvokeDeps, getSkeinRuntime, toWebResponse, webErrorResponse };

package/dist/index.js

@@ -4,27 +4,31 @@ import {
   matchSkeinRoute
 } from "@skein-js/agent-protocol";
 import { SkeinHttpError } from "@skein-js/core";
+import { stripBasePath } from "@skein-js/server-kit";
 
 // src/runtime-singleton.ts
 import {
-  resolveProtocolRuntime
+  resolveProtocolRuntime,
+  resolveRuntimeDeps
 } from "@skein-js/server-kit";
 var CONFIG_CACHE_KEY = /* @__PURE__ */ Symbol.for("skein.nextjs.configRuntimeCache");
 var DEPS_CACHE_KEY = /* @__PURE__ */ Symbol.for("skein.nextjs.depsRuntimeCache");
-function configCache() {
+var CONFIG_INVOKE_CACHE_KEY = /* @__PURE__ */ Symbol.for("skein.nextjs.configInvokeCache");
+var DEPS_INVOKE_CACHE_KEY = /* @__PURE__ */ Symbol.for("skein.nextjs.depsInvokeCache");
+function globalMap(key) {
   const store = globalThis;
-  store[CONFIG_CACHE_KEY] ??= /* @__PURE__ */ new Map();
-  return store[CONFIG_CACHE_KEY];
+  store[key] ??= /* @__PURE__ */ new Map();
+  return store[key];
 }
-function depsCache() {
+function globalWeakMap(key) {
   const store = globalThis;
-  store[DEPS_CACHE_KEY] ??= /* @__PURE__ */ new WeakMap();
-  return store[DEPS_CACHE_KEY];
+  store[key] ??= /* @__PURE__ */ new WeakMap();
+  return store[key];
 }
-function resolveOnce(cache, key, options) {
+function resolveOnce(cache, key, resolve) {
   let resolved = cache.get(key);
   if (!resolved) {
-    resolved = resolveProtocolRuntime(options).catch((error) => {
+    resolved = resolve().catch((error) => {
       cache.delete(key);
       throw error;
     });
@@ -32,11 +36,27 @@ function resolveOnce(cache, key, options) {
   }
   return resolved;
 }
-function getSkeinRuntime(options) {
+function memoizeByOptions(options, configKey, depsKey, resolve) {
   if (typeof options.config === "string") {
-    return resolveOnce(configCache(), options.config, options);
+    return resolveOnce(globalMap(configKey), options.config, resolve);
   }
-  return resolveOnce(depsCache(), options.deps, options);
+  return resolveOnce(globalWeakMap(depsKey), options.deps, resolve);
+}
+function getSkeinRuntime(options) {
+  return memoizeByOptions(
+    options,
+    CONFIG_CACHE_KEY,
+    DEPS_CACHE_KEY,
+    () => resolveProtocolRuntime(options)
+  );
+}
+function getSkeinInvokeDeps(options) {
+  return memoizeByOptions(
+    options,
+    CONFIG_INVOKE_CACHE_KEY,
+    DEPS_INVOKE_CACHE_KEY,
+    () => resolveRuntimeDeps(options)
+  );
 }
 
 // src/send-web-response.ts
@@ -114,12 +134,6 @@ function preflightResponse(request, cors) {
 }
 
 // src/create-route-handlers.ts
-function stripBasePath(pathname, basePath) {
-  if (basePath === "" || basePath === "/") return pathname;
-  if (pathname === basePath) return "/";
-  if (pathname.startsWith(`${basePath}/`)) return pathname.slice(basePath.length);
-  return null;
-}
 function toQuery(url) {
   const query = {};
   for (const key of new Set(url.searchParams.keys())) {
@@ -140,8 +154,10 @@ async function toProtocolRequest(request, url, skeinPathname, params) {
   }
   return {
     method: request.method,
-    // Report the skein-relative absolute URL (mount prefix stripped) so auth handlers see the same
-    // path shape the other adapters produce.
+    // Report the skein-relative absolute URL (mount prefix stripped). NOTE: this does NOT match the
+    // Express/NestJS adapters, which report the full mount-inclusive URL (`req.originalUrl`). An auth
+    // handler that matches on `req.url`'s pathname therefore sees `/threads` here but `/api/threads`
+    // there. Worth unifying — but changing either side silently re-points existing auth rules.
     url: `${url.origin}${skeinPathname}${url.search}`,
     params,
     query: toQuery(url),
@@ -204,14 +220,9 @@ import {
   applyNodeCors,
   sendNodeError,
   sendNodePreflight,
-  sendNodeResponse
+  sendNodeResponse,
+  stripBasePath as stripBasePath2
 } from "@skein-js/server-kit";
-function stripBasePath2(pathname, basePath) {
-  if (basePath === "" || basePath === "/") return pathname;
-  if (pathname === basePath) return "/";
-  if (pathname.startsWith(`${basePath}/`)) return pathname.slice(basePath.length);
-  return null;
-}
 function toQuery2(url) {
   const query = {};
   for (const key of new Set(url.searchParams.keys())) {
@@ -284,11 +295,91 @@ function createSkeinPagesHandler(options) {
   };
 }
 
+// src/create-invoke-route-handlers.ts
+import {
+  createGraphInvokeHandler
+} from "@skein-js/agent-protocol";
+import { SkeinHttpError as SkeinHttpError2 } from "@skein-js/core";
+function toQuery3(url) {
+  const query = {};
+  for (const key of new Set(url.searchParams.keys())) {
+    const all = url.searchParams.getAll(key);
+    query[key] = all.length > 1 ? all : all[0];
+  }
+  return query;
+}
+function graphIdFromPath(pathname, basePath) {
+  const prefix = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  if (!pathname.startsWith(`${prefix}/`)) return null;
+  const rest = pathname.slice(prefix.length + 1);
+  if (rest === "" || rest.includes("/")) return null;
+  try {
+    return decodeURIComponent(rest);
+  } catch {
+    return rest;
+  }
+}
+function createSkeinInvokeRouteHandlers(options) {
+  const basePath = options.basePath ?? "/api/invoke";
+  const logger = options.logger;
+  let invoke;
+  const post = async (request) => {
+    const url = new URL(request.url);
+    const graphId = graphIdFromPath(url.pathname, basePath);
+    if (graphId === null) return new Response(null, { status: 404 });
+    let resolved;
+    try {
+      resolved = await getSkeinInvokeDeps(options);
+    } catch (error) {
+      return webErrorResponse(error, {}, logger);
+    }
+    const cors = options.cors ?? resolved.cors;
+    const extraHeaders = cors ? corsHeaders(request, cors) : {};
+    try {
+      const text = await request.text();
+      let body;
+      try {
+        body = text ? JSON.parse(text) : {};
+      } catch {
+        throw SkeinHttpError2.badRequest("Request body is not valid JSON.");
+      }
+      invoke ??= createGraphInvokeHandler(resolved.deps, { streamMode: options.streamMode });
+      const response = await invoke({
+        method: request.method,
+        url: `${url.origin}${url.pathname}${url.search}`,
+        params: { graph_id: graphId },
+        query: toQuery3(url),
+        body,
+        headers: Object.fromEntries(request.headers),
+        // The Web `Request` aborts this when the client goes away, so the graph stops with it.
+        signal: request.signal
+      });
+      return toWebResponse(response, extraHeaders);
+    } catch (error) {
+      return webErrorResponse(error, extraHeaders, logger);
+    }
+  };
+  const optionsHandler = async (request) => {
+    let cors = options.cors;
+    if (cors === void 0) {
+      try {
+        cors = (await getSkeinInvokeDeps(options)).cors;
+      } catch {
+        cors = void 0;
+      }
+    }
+    return cors ? preflightResponse(request, cors) : new Response(null, { status: 404 });
+  };
+  return { POST: post, OPTIONS: optionsHandler };
+}
+
 // src/index.ts
 import { sendNodeResponse as sendNodeResponse2, sendNodeError as sendNodeError2 } from "@skein-js/server-kit";
 export {
+  createSkeinInvokeRouteHandlers,
   createSkeinPagesHandler,
   createSkeinRouteHandlers,
+  getSkeinInvokeDeps,
   getSkeinRuntime,
   sendNodeError2 as sendNodeError,
   sendNodeResponse2 as sendNodeResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/nextjs",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Next.js adapter for skein-js — serve the Agent Protocol from App Router or Pages Router API routes.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -40,9 +40,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@skein-js/agent-protocol": "0.7.0",
-    "@skein-js/server-kit": "0.7.0",
-    "@skein-js/core": "0.7.0"
+    "@skein-js/agent-protocol": "0.9.0",
+    "@skein-js/core": "0.9.0",
+    "@skein-js/server-kit": "0.9.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
@@ -51,7 +51,7 @@
   "devDependencies": {
     "@langchain/core": "^1.2.0",
     "@langchain/langgraph": "^1.4.0",
-    "@skein-js/storage-memory": "0.7.0"
+    "@skein-js/storage-memory": "0.9.0"
   },
   "publishConfig": {
     "access": "public"