@surfjs/next 0.2.0

package/README.md

@@ -0,0 +1,85 @@
+# @surfjs/next
+
+Next.js adapter for [Surf.js](https://surf.codes) — supports both **App Router** (route handlers) and **Pages Router** (API routes).
+
+## Installation
+
+```bash
+pnpm add @surfjs/next @surfjs/core
+```
+
+## App Router (Recommended)
+
+Create a catch-all route handler at `app/api/surf/[...slug]/route.ts`:
+
+```ts
+import { createSurf } from '@surfjs/core';
+import { createSurfRouteHandler } from '@surfjs/next';
+
+const surf = createSurf({
+  name: 'my-app',
+  commands: {
+    hello: {
+      description: 'Say hello',
+      params: { name: { type: 'string', required: true } },
+      run: ({ name }) => ({ message: `Hello, ${name}!` }),
+    },
+  },
+});
+
+export const { GET, POST } = createSurfRouteHandler(surf);
+```
+
+The handler serves:
+- `GET /api/surf/.well-known/surf.json` — Surf manifest
+- `POST /api/surf/surf/execute` — Execute commands
+- `POST /api/surf/surf/pipeline` — Execute pipelines
+- `POST /api/surf/surf/session/start` — Start sessions
+- `POST /api/surf/surf/session/end` — End sessions
+
+### Edge Runtime
+
+The App Router handler is fully edge-compatible — no Node.js APIs are used. Add the edge runtime directive if desired:
+
+```ts
+export const runtime = 'edge';
+```
+
+## Pages Router
+
+Create a catch-all API route at `pages/api/surf/[...slug].ts`:
+
+```ts
+import { createSurf } from '@surfjs/core';
+import { createSurfApiHandler } from '@surfjs/next/pages';
+
+const surf = createSurf({
+  name: 'my-app',
+  commands: {
+    hello: {
+      description: 'Say hello',
+      params: { name: { type: 'string', required: true } },
+      run: ({ name }) => ({ message: `Hello, ${name}!` }),
+    },
+  },
+});
+
+export default createSurfApiHandler(surf);
+```
+
+## Features
+
+- ✅ App Router (route handlers) with edge runtime support
+- ✅ Pages Router (API routes) with Node.js runtime
+- ✅ SSE streaming for both routers
+- ✅ Session management
+- ✅ Pipeline execution
+- ✅ Bearer token auth extraction
+- ✅ Client IP extraction (`x-forwarded-for`, `x-real-ip`)
+- ✅ ETag caching for manifest
+- ✅ CORS headers
+- ✅ Consistent error code → HTTP status mapping
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+var core = require('@surfjs/core');
+
+// src/index.ts
+
+// src/shared.ts
+function getErrorStatus(code) {
+  switch (code) {
+    case "UNKNOWN_COMMAND":
+      return 404;
+    case "INVALID_PARAMS":
+      return 400;
+    case "AUTH_REQUIRED":
+      return 401;
+    case "AUTH_FAILED":
+      return 403;
+    case "SESSION_EXPIRED":
+      return 410;
+    case "RATE_LIMITED":
+      return 429;
+    case "NOT_SUPPORTED":
+      return 501;
+    default:
+      return 500;
+  }
+}
+function extractAuth(authHeader) {
+  if (!authHeader) return void 0;
+  return authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+}
+function extractIp(forwardedFor, realIp) {
+  if (forwardedFor) return forwardedFor.split(",")[0]?.trim();
+  return realIp ?? void 0;
+}
+var CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*"
+};
+
+// src/index.ts
+function createSurfRouteHandler(surf, options = {}) {
+  const registry = surf.commands;
+  const sessions = surf.sessions;
+  const basePath = options.basePath ?? "/api/surf";
+  function getPathname(request) {
+    const req = request;
+    if (req.nextUrl) return req.nextUrl.pathname;
+    return new URL(request.url).pathname;
+  }
+  function resolveRoute(request, slug) {
+    if (slug && slug.length > 0) {
+      return "/" + slug.join("/");
+    }
+    const pathname = getPathname(request);
+    const stripped = pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname;
+    return stripped || "/";
+  }
+  function jsonResponse(body, status, extraHeaders) {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        "Content-Type": "application/json",
+        ...CORS_HEADERS,
+        ...extraHeaders
+      }
+    });
+  }
+  async function GET(request, context) {
+    const { slug } = await context.params;
+    const route = resolveRoute(request, slug);
+    if (route === "/.well-known/surf.json" || route === "/") {
+      const manifestData = surf.manifest();
+      const etag = `"${manifestData.checksum}"`;
+      if (request.headers.get("if-none-match") === etag) {
+        return new Response(null, {
+          status: 304,
+          headers: { "ETag": etag, "Cache-Control": "public, max-age=300", ...CORS_HEADERS }
+        });
+      }
+      return jsonResponse(manifestData, 200, {
+        "ETag": etag,
+        "Cache-Control": "public, max-age=300"
+      });
+    }
+    return jsonResponse(
+      { ok: false, error: { code: "NOT_FOUND", message: `Unknown route: GET ${route}` } },
+      404
+    );
+  }
+  async function POST(request, context) {
+    const { slug } = await context.params;
+    const route = resolveRoute(request, slug);
+    const auth = extractAuth(request.headers.get("authorization"));
+    const ip = extractIp(
+      request.headers.get("x-forwarded-for"),
+      request.headers.get("x-real-ip")
+    );
+    if (route === "/surf/execute" || route === "/execute") {
+      let body;
+      try {
+        body = await request.json();
+      } catch {
+        return jsonResponse(
+          { ok: false, error: { code: "INVALID_PARAMS", message: "Invalid JSON body" } },
+          400
+        );
+      }
+      if (!body?.command || typeof body.command !== "string") {
+        return jsonResponse(
+          { ok: false, error: { code: "INVALID_PARAMS", message: "Missing command field" } },
+          400
+        );
+      }
+      let sessionState;
+      if (body.sessionId) {
+        const session = await sessions.get(body.sessionId);
+        if (session) sessionState = session.state;
+      }
+      const command = registry.get(body.command);
+      const wantsStream = body.stream === true && command?.stream === true;
+      if (wantsStream) {
+        const stream = new ReadableStream({
+          async start(controller) {
+            const encoder = new TextEncoder();
+            const write = (data) => {
+              controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}
+
+`));
+            };
+            const sseContext = {
+              sessionId: body.sessionId,
+              auth,
+              ip,
+              state: sessionState,
+              requestId: body.requestId,
+              emit: (data) => {
+                write({ type: "chunk", data });
+              }
+            };
+            try {
+              const response2 = await registry.execute(body.command, body.params, sseContext);
+              if (response2.ok) {
+                write({ type: "done", result: response2.result });
+              } else {
+                write({ type: "error", error: { code: response2.error.code, message: response2.error.message } });
+              }
+            } catch (e) {
+              write({
+                type: "error",
+                error: {
+                  code: "INTERNAL_ERROR",
+                  message: e instanceof Error ? e.message : "Unknown error"
+                }
+              });
+            } finally {
+              controller.close();
+            }
+          }
+        });
+        return new Response(stream, {
+          status: 200,
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            ...CORS_HEADERS
+          }
+        });
+      }
+      const response = await registry.execute(body.command, body.params, {
+        sessionId: body.sessionId,
+        auth,
+        ip,
+        state: sessionState,
+        requestId: body.requestId
+      });
+      if (body.sessionId && response.ok && response.state) {
+        await sessions.update(body.sessionId, response.state);
+      }
+      const statusCode = response.ok ? 200 : getErrorStatus(response.error.code);
+      const headers = {};
+      if (!response.ok && response.error.code === "RATE_LIMITED") {
+        const retryMs = response.error.details?.["retryAfterMs"] ?? 0;
+        headers["Retry-After"] = String(Math.ceil(retryMs / 1e3));
+      }
+      return jsonResponse(response, statusCode, headers);
+    }
+    if (route === "/surf/pipeline" || route === "/pipeline") {
+      let body;
+      try {
+        body = await request.json();
+      } catch {
+        return jsonResponse(
+          { ok: false, error: { code: "INVALID_PARAMS", message: "Invalid JSON body" } },
+          400
+        );
+      }
+      try {
+        const result = await core.executePipeline(
+          body,
+          registry,
+          sessions,
+          auth
+        );
+        return jsonResponse(result, 200);
+      } catch (e) {
+        return jsonResponse(
+          {
+            ok: false,
+            error: { code: "INTERNAL_ERROR", message: e instanceof Error ? e.message : "Unknown error" }
+          },
+          500
+        );
+      }
+    }
+    if (route === "/surf/session/start" || route === "/session/start") {
+      const session = await sessions.create();
+      return jsonResponse({ ok: true, sessionId: session.id }, 200);
+    }
+    if (route === "/surf/session/end" || route === "/session/end") {
+      try {
+        const body = await request.json();
+        if (body?.sessionId) {
+          await sessions.destroy(body.sessionId);
+        }
+      } catch {
+      }
+      return jsonResponse({ ok: true }, 200);
+    }
+    return jsonResponse(
+      { ok: false, error: { code: "NOT_FOUND", message: `Unknown route: POST ${route}` } },
+      404
+    );
+  }
+  return { GET, POST };
+}
+
+exports.createSurfRouteHandler = createSurfRouteHandler;
+exports.extractAuth = extractAuth;
+exports.extractIp = extractIp;
+exports.getErrorStatus = getErrorStatus;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared.ts","../src/index.ts"],"names":["response","executePipeline"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { SurfInstance } from '@surfjs/core';\n\n/**\n * Surf error code to HTTP status code mapping.\n * Consistent with fastify and hono adapters.\n */\nexport function getErrorStatus(code: string): number {\n  switch (code) {\n    case 'UNKNOWN_COMMAND': return 404;\n    case 'INVALID_PARAMS': return 400;\n    case 'AUTH_REQUIRED': return 401;\n    case 'AUTH_FAILED': return 403;\n    case 'SESSION_EXPIRED': return 410;\n    case 'RATE_LIMITED': return 429;\n    case 'NOT_SUPPORTED': return 501;\n    default: return 500;\n  }\n}\n\n/**\n * Extract Bearer token from an Authorization header value.\n *\n * @param authHeader - Raw Authorization header value\n * @returns The token string, or `undefined` if not present\n */\nexport function extractAuth(authHeader: string | null | undefined): string | undefined {\n  if (!authHeader) return undefined;\n  return authHeader.startsWith('Bearer ') ? authHeader.slice(7) : authHeader;\n}\n\n/**\n * Extract client IP from forwarding headers.\n *\n * @param forwardedFor - `x-forwarded-for` header value\n * @param realIp - `x-real-ip` header value\n * @returns The client IP string, or `undefined` if not determinable\n */\nexport function extractIp(\n  forwardedFor: string | null | undefined,\n  realIp: string | null | undefined,\n): string | undefined {\n  if (forwardedFor) return forwardedFor.split(',')[0]?.trim();\n  return realIp ?? undefined;\n}\n\n/**\n * CORS headers applied to all Surf responses.\n */\nexport const CORS_HEADERS: Record<string, string> = {\n  'Access-Control-Allow-Origin': '*',\n};\n\n/**\n * Common types re-exported for internal use.\n */\nexport type { SurfInstance };\n","import type { SurfInstance } from '@surfjs/core';\nimport type {\n  ExecuteRequest,\n  PipelineRequest,\n  SurfResponse,\n} from '@surfjs/core';\nimport { executePipeline } from '@surfjs/core';\nimport {\n  getErrorStatus,\n  extractAuth,\n  extractIp,\n  CORS_HEADERS,\n} from './shared.js';\n\n/**\n * Next.js App Router request type (web-standard Request with nextUrl).\n * We use the global `Request` type for edge compatibility\n * and avoid importing Next.js types at runtime.\n */\ntype NextRequest = Request & { nextUrl?: URL };\n\n/**\n * Creates App Router route handlers for Surf.js.\n *\n * Returns `GET` and `POST` handlers for use in a Next.js catch-all route file:\n * `app/api/surf/[...slug]/route.ts`\n *\n * @example\n * ```ts\n * // app/api/surf/[...slug]/route.ts\n * import { createSurf } from '@surfjs/core';\n * import { createSurfRouteHandler } from '@surfjs/next';\n *\n * const surf = createSurf({ name: 'my-app', commands: { ... } });\n * export const { GET, POST } = createSurfRouteHandler(surf);\n * ```\n *\n * @example\n * ```ts\n * // With a custom base path\n * export const { GET, POST } = createSurfRouteHandler(surf, {\n *   basePath: '/api/surf',\n * });\n * ```\n *\n * @param surf - A `SurfInstance` created via `createSurf()`\n * @param options - Optional configuration\n * @returns An object with `GET` and `POST` handlers\n */\nexport function createSurfRouteHandler(\n  surf: SurfInstance,\n  options: { basePath?: string } = {},\n): {\n  GET: (request: Request, context: { params: Promise<{ slug?: string[] }> }) => Promise<Response>;\n  POST: (request: Request, context: { params: Promise<{ slug?: string[] }> }) => Promise<Response>;\n} {\n  const registry = surf.commands;\n  const sessions = surf.sessions;\n  const basePath = options.basePath ?? '/api/surf';\n\n  function getPathname(request: Request): string {\n    const req = request as NextRequest;\n    if (req.nextUrl) return req.nextUrl.pathname;\n    return new URL(request.url).pathname;\n  }\n\n  function resolveRoute(request: Request, slug: string[] | undefined): string {\n    if (slug && slug.length > 0) {\n      return '/' + slug.join('/');\n    }\n    // Fallback: extract from pathname\n    const pathname = getPathname(request);\n    const stripped = pathname.startsWith(basePath)\n      ? pathname.slice(basePath.length)\n      : pathname;\n    return stripped || '/';\n  }\n\n  function jsonResponse(body: unknown, status: number, extraHeaders?: Record<string, string>): Response {\n    return new Response(JSON.stringify(body), {\n      status,\n      headers: {\n        'Content-Type': 'application/json',\n        ...CORS_HEADERS,\n        ...extraHeaders,\n      },\n    });\n  }\n\n  // ─── GET handler ─────────────────────────────────────────────────────\n  async function GET(\n    request: Request,\n    context: { params: Promise<{ slug?: string[] }> },\n  ): Promise<Response> {\n    const { slug } = await context.params;\n    const route = resolveRoute(request, slug);\n\n    // /.well-known/surf.json\n    if (route === '/.well-known/surf.json' || route === '/') {\n      const manifestData = surf.manifest();\n      const etag = `\"${manifestData.checksum}\"`;\n\n      if (request.headers.get('if-none-match') === etag) {\n        return new Response(null, {\n          status: 304,\n          headers: { 'ETag': etag, 'Cache-Control': 'public, max-age=300', ...CORS_HEADERS },\n        });\n      }\n\n      return jsonResponse(manifestData, 200, {\n        'ETag': etag,\n        'Cache-Control': 'public, max-age=300',\n      });\n    }\n\n    return jsonResponse(\n      { ok: false, error: { code: 'NOT_FOUND', message: `Unknown route: GET ${route}` } },\n      404,\n    );\n  }\n\n  // ─── POST handler ────────────────────────────────────────────────────\n  async function POST(\n    request: Request,\n    context: { params: Promise<{ slug?: string[] }> },\n  ): Promise<Response> {\n    const { slug } = await context.params;\n    const route = resolveRoute(request, slug);\n    const auth = extractAuth(request.headers.get('authorization'));\n    const ip = extractIp(\n      request.headers.get('x-forwarded-for'),\n      request.headers.get('x-real-ip'),\n    );\n\n    // ─── POST /surf/execute ──────────────────────────────────────────\n    if (route === '/surf/execute' || route === '/execute') {\n      let body: ExecuteRequest;\n      try {\n        body = await request.json() as ExecuteRequest;\n      } catch {\n        return jsonResponse(\n          { ok: false, error: { code: 'INVALID_PARAMS', message: 'Invalid JSON body' } },\n          400,\n        );\n      }\n\n      if (!body?.command || typeof body.command !== 'string') {\n        return jsonResponse(\n          { ok: false, error: { code: 'INVALID_PARAMS', message: 'Missing command field' } },\n          400,\n        );\n      }\n\n      let sessionState: Record<string, unknown> | undefined;\n      if (body.sessionId) {\n        const session = await sessions.get(body.sessionId);\n        if (session) sessionState = session.state;\n      }\n\n      const command = registry.get(body.command);\n      const wantsStream = body.stream === true && command?.stream === true;\n\n      if (wantsStream) {\n        // SSE streaming via ReadableStream (edge-compatible)\n        const stream = new ReadableStream({\n          async start(controller) {\n            const encoder = new TextEncoder();\n            const write = (data: unknown) => {\n              controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\\n\\n`));\n            };\n\n            const sseContext = {\n              sessionId: body.sessionId,\n              auth,\n              ip,\n              state: sessionState,\n              requestId: body.requestId,\n              emit: (data: unknown) => {\n                write({ type: 'chunk', data });\n              },\n            };\n\n            try {\n              const response: SurfResponse = await registry.execute(body.command, body.params, sseContext);\n              if (response.ok) {\n                write({ type: 'done', result: response.result });\n              } else {\n                write({ type: 'error', error: { code: response.error.code, message: response.error.message } });\n              }\n            } catch (e) {\n              write({\n                type: 'error',\n                error: {\n                  code: 'INTERNAL_ERROR',\n                  message: e instanceof Error ? e.message : 'Unknown error',\n                },\n              });\n            } finally {\n              controller.close();\n            }\n          },\n        });\n\n        return new Response(stream, {\n          status: 200,\n          headers: {\n            'Content-Type': 'text/event-stream',\n            'Cache-Control': 'no-cache',\n            'Connection': 'keep-alive',\n            ...CORS_HEADERS,\n          },\n        });\n      }\n\n      // Standard JSON response\n      const response: SurfResponse = await registry.execute(body.command, body.params, {\n        sessionId: body.sessionId,\n        auth,\n        ip,\n        state: sessionState,\n        requestId: body.requestId,\n      });\n\n      if (body.sessionId && response.ok && response.state) {\n        await sessions.update(body.sessionId, response.state);\n      }\n\n      const statusCode = response.ok ? 200 : getErrorStatus(response.error.code);\n      const headers: Record<string, string> = {};\n\n      if (!response.ok && response.error.code === 'RATE_LIMITED') {\n        const retryMs = (response.error.details?.['retryAfterMs'] as number | undefined) ?? 0;\n        headers['Retry-After'] = String(Math.ceil(retryMs / 1000));\n      }\n\n      return jsonResponse(response, statusCode, headers);\n    }\n\n    // ─── POST /surf/pipeline ─────────────────────────────────────────\n    if (route === '/surf/pipeline' || route === '/pipeline') {\n      let body: PipelineRequest;\n      try {\n        body = await request.json() as PipelineRequest;\n      } catch {\n        return jsonResponse(\n          { ok: false, error: { code: 'INVALID_PARAMS', message: 'Invalid JSON body' } },\n          400,\n        );\n      }\n\n      try {\n        const result = await executePipeline(\n          body,\n          registry as Parameters<typeof executePipeline>[1],\n          sessions as Parameters<typeof executePipeline>[2],\n          auth,\n        );\n        return jsonResponse(result, 200);\n      } catch (e) {\n        return jsonResponse(\n          {\n            ok: false,\n            error: { code: 'INTERNAL_ERROR', message: e instanceof Error ? e.message : 'Unknown error' },\n          },\n          500,\n        );\n      }\n    }\n\n    // ─── POST /surf/session/start ────────────────────────────────────\n    if (route === '/surf/session/start' || route === '/session/start') {\n      const session = await sessions.create();\n      return jsonResponse({ ok: true, sessionId: session.id }, 200);\n    }\n\n    // ─── POST /surf/session/end ──────────────────────────────────────\n    if (route === '/surf/session/end' || route === '/session/end') {\n      try {\n        const body = await request.json() as { sessionId?: string };\n        if (body?.sessionId) {\n          await sessions.destroy(body.sessionId);\n        }\n      } catch {\n        // Ignore parse errors for session end\n      }\n      return jsonResponse({ ok: true }, 200);\n    }\n\n    return jsonResponse(\n      { ok: false, error: { code: 'NOT_FOUND', message: `Unknown route: POST ${route}` } },\n      404,\n    );\n  }\n\n  return { GET, POST };\n}\n\nexport { getErrorStatus, extractAuth, extractIp } from './shared.js';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,47 @@
+import { SurfInstance } from '@surfjs/core';
+export { e as extractAuth, a as extractIp, g as getErrorStatus } from './shared-CckJeURD.cjs';
+
+/**
+ * Creates App Router route handlers for Surf.js.
+ *
+ * Returns `GET` and `POST` handlers for use in a Next.js catch-all route file:
+ * `app/api/surf/[...slug]/route.ts`
+ *
+ * @example
+ * ```ts
+ * // app/api/surf/[...slug]/route.ts
+ * import { createSurf } from '@surfjs/core';
+ * import { createSurfRouteHandler } from '@surfjs/next';
+ *
+ * const surf = createSurf({ name: 'my-app', commands: { ... } });
+ * export const { GET, POST } = createSurfRouteHandler(surf);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a custom base path
+ * export const { GET, POST } = createSurfRouteHandler(surf, {
+ *   basePath: '/api/surf',
+ * });
+ * ```
+ *
+ * @param surf - A `SurfInstance` created via `createSurf()`
+ * @param options - Optional configuration
+ * @returns An object with `GET` and `POST` handlers
+ */
+declare function createSurfRouteHandler(surf: SurfInstance, options?: {
+    basePath?: string;
+}): {
+    GET: (request: Request, context: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Response>;
+    POST: (request: Request, context: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+export { createSurfRouteHandler };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { SurfInstance } from '@surfjs/core';
+export { e as extractAuth, a as extractIp, g as getErrorStatus } from './shared-CckJeURD.js';
+
+/**
+ * Creates App Router route handlers for Surf.js.
+ *
+ * Returns `GET` and `POST` handlers for use in a Next.js catch-all route file:
+ * `app/api/surf/[...slug]/route.ts`
+ *
+ * @example
+ * ```ts
+ * // app/api/surf/[...slug]/route.ts
+ * import { createSurf } from '@surfjs/core';
+ * import { createSurfRouteHandler } from '@surfjs/next';
+ *
+ * const surf = createSurf({ name: 'my-app', commands: { ... } });
+ * export const { GET, POST } = createSurfRouteHandler(surf);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a custom base path
+ * export const { GET, POST } = createSurfRouteHandler(surf, {
+ *   basePath: '/api/surf',
+ * });
+ * ```
+ *
+ * @param surf - A `SurfInstance` created via `createSurf()`
+ * @param options - Optional configuration
+ * @returns An object with `GET` and `POST` handlers
+ */
+declare function createSurfRouteHandler(surf: SurfInstance, options?: {
+    basePath?: string;
+}): {
+    GET: (request: Request, context: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Response>;
+    POST: (request: Request, context: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+export { createSurfRouteHandler };