@gnomondigital/nebulas-kit-core 0.1.0 → 0.2.1

package/README.md

@@ -20,6 +20,7 @@ npm install @gnomondigital/nebulas-kit-core
 | `AUTH0_CLIENT_SECRET` | For client_credentials, ROP | Auth0 client secret |
 | `AUTH0_A2A_AUDIENCE` | For Auth0 strategies | API audience |
 | `NEBULAS_API_URL` | For Nebulas | Conversation API base URL |
+| `NEBULAS_API_KEY` | For Nebulas proxy | x-api-key fallback when no session token |
 | `NEBULAS_PROJECT_ID` | For Nebulas | Project ID |
 
 ## Usage
@@ -69,6 +70,24 @@ export async function GET() {
 }
 ```
 
+```ts
+// app/api/nebulas/[...path]/route.ts - proxies to Nebulas API (conversations, chat_messages)
+import { createNebulasProxyHandler } from "@gnomondigital/nebulas-kit-core";
+import { auth0 } from "@/lib/auth";
+
+const handler = createNebulasProxyHandler({
+  auth0,
+  audience: process.env.AUTH0_A2A_AUDIENCE,
+  apiKey: process.env.NEBULAS_API_KEY || process.env.A2A_API_KEY,
+});
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;
+```
+
 ### Express
 
 ```ts

package/dist/index.d.ts

@@ -11,5 +11,6 @@ export { getAuthStrategy, getAuthHeaders, type AuthStrategy, } from "./server/au
 export { exchangePasswordForToken, type ROPAuthRequest, type ROPAuthResponse, } from "./server/auth-handler.js";
 export { createConfigResponse, type ConfigResponse, type AgentCard, type AgentCardCapabilities, } from "./server/config-handler.js";
 export { createA2AExpressRouter, type A2AExpressRouterOptions, } from "./server/express.js";
-export { handleA2ANextJsPOST, handleA2AAuthNextJsPOST, handleA2AConfigNextJsGET, createConfigGetHeadersForAuth0, type HandleA2AConfigOptions, type Auth0ClientForConfig, } from "./server/nextjs.js";
+export { handleA2ANextJsPOST, handleA2AAuthNextJsPOST, handleA2AConfigNextJsGET, createConfigGetHeadersForAuth0, createNebulasProxyHandler, type HandleA2AConfigOptions, type Auth0ClientForConfig, type CreateNebulasProxyHandlerOptions, } from "./server/nextjs.js";
+export { handleNebulasProxy, isRefreshTokenInvalid, type NebulasProxyRequest, type NebulasProxyResponse, type NebulasProxyHandlerOptions, } from "./server/nebulas-proxy-handler.js";
 //# 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;;;GAGG;AAEH,OAAO,EACL,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE5F,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,YAAY,GAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,qBAAqB,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,8BAA8B,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE5F,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,YAAY,GAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,qBAAqB,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,GACtC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,GAChC,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -11,4 +11,5 @@ export { exchangePasswordForToken, } from "./server/auth-handler.js";
 export { createConfigResponse, } from "./server/config-handler.js";
 export { createA2AExpressRouter, } from "./server/express.js";
 // Usage: import express from "express"; app.use("/api/a2a", createA2AExpressRouter(express));
-export { handleA2ANextJsPOST, handleA2AAuthNextJsPOST, handleA2AConfigNextJsGET, createConfigGetHeadersForAuth0, } from "./server/nextjs.js";
+export { handleA2ANextJsPOST, handleA2AAuthNextJsPOST, handleA2AConfigNextJsGET, createConfigGetHeadersForAuth0, createNebulasProxyHandler, } from "./server/nextjs.js";
+export { handleNebulasProxy, isRefreshTokenInvalid, } from "./server/nebulas-proxy-handler.js";

package/dist/server/nebulas-proxy-handler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Framework-agnostic Nebulas API proxy handler.
+ * Proxies requests to the Nebulas API (conversations, chat_messages).
+ */
+export interface NebulasProxyRequest {
+    method: string;
+    path: string[];
+    headers: Record<string, string>;
+    body?: string;
+    searchParams: Record<string, string>;
+}
+export interface NebulasProxyResponse {
+    status: number;
+    statusText?: string;
+    headers: Record<string, string>;
+    body?: string | ReadableStream<Uint8Array> | ArrayBuffer;
+}
+export interface NebulasProxyHandlerOptions {
+    /**
+     * When provided, fetches the access token from session (e.g. Auth0).
+     * Should throw or return NextResponse for 401 when session invalid.
+     */
+    getHeaders?: (req: NebulasProxyRequest) => Promise<Record<string, string>>;
+    /**
+     * Pre-resolved auth headers. Use when getHeaders was already called
+     * (e.g. before consuming request body, which getAccessToken may need).
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Check if an error indicates invalid refresh token (for session re-auth).
+ */
+export declare function isRefreshTokenInvalid(err: unknown): boolean;
+/**
+ * Handle Nebulas API proxy request.
+ * Proxies to NEBULAS_API_URL with auth headers from getHeaders or API keys.
+ */
+export declare function handleNebulasProxy(req: NebulasProxyRequest, options?: NebulasProxyHandlerOptions): Promise<NebulasProxyResponse>;
+//# sourceMappingURL=nebulas-proxy-handler.d.ts.map

package/dist/server/nebulas-proxy-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nebulas-proxy-handler.d.ts","sourceRoot":"","sources":["../../src/server/nebulas-proxy-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3E;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAS3D;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,mBAAmB,EACxB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,oBAAoB,CAAC,CAwH/B"}

package/dist/server/nebulas-proxy-handler.js

@@ -0,0 +1,129 @@
+/**
+ * Framework-agnostic Nebulas API proxy handler.
+ * Proxies requests to the Nebulas API (conversations, chat_messages).
+ */
+const NEBULAS_API_URL = process.env.NEBULAS_API_URL || "http://localhost:8020";
+const A2A_AUDIENCE = process.env.AUTH0_A2A_AUDIENCE;
+const A2A_API_KEY = process.env.A2A_API_KEY;
+const NEBULAS_API_KEY = process.env.NEBULAS_API_KEY;
+/**
+ * Check if an error indicates invalid refresh token (for session re-auth).
+ */
+export function isRefreshTokenInvalid(err) {
+    if (typeof err === "object" && err !== null) {
+        const e = err;
+        return (e?.code === "failed_to_refresh_token" ||
+            e?.cause?.code === "invalid_grant");
+    }
+    return false;
+}
+/**
+ * Handle Nebulas API proxy request.
+ * Proxies to NEBULAS_API_URL with auth headers from getHeaders or API keys.
+ */
+export async function handleNebulasProxy(req, options = {}) {
+    const backendPath = `/${req.path.join("/")}`;
+    const url = new URL(backendPath, NEBULAS_API_URL.replace(/\/$/, "") + "/");
+    for (const [key, value] of Object.entries(req.searchParams)) {
+        url.searchParams.set(key, value);
+    }
+    const headers = {};
+    const contentType = req.headers["content-type"];
+    if (contentType) {
+        headers["Content-Type"] = contentType;
+    }
+    if (NEBULAS_API_KEY) {
+        headers["x-api-key"] = NEBULAS_API_KEY;
+    }
+    else if (A2A_API_KEY) {
+        headers["x-api-key"] = A2A_API_KEY;
+    }
+    if (options.headers) {
+        Object.assign(headers, options.headers);
+    }
+    else if (options.getHeaders) {
+        try {
+            const authHeaders = await options.getHeaders(req);
+            Object.assign(headers, authHeaders);
+        }
+        catch (err) {
+            if (isRefreshTokenInvalid(err)) {
+                return {
+                    status: 401,
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        error: "Your session has expired. Please log out and log back in.",
+                        code: "refresh_token_invalid",
+                        requireReauth: true,
+                    }),
+                };
+            }
+            if (!A2A_API_KEY && !NEBULAS_API_KEY) {
+                return {
+                    status: 401,
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        error: "Unauthorized",
+                        hint: "Ensure Auth0 API has 'Allow Offline Access' enabled, MRRT is configured for the A2A audience, and you have logged out and back in to get a refresh token.",
+                    }),
+                };
+            }
+            console.error("[Nebulas Proxy] Failed to get access token:", err);
+        }
+    }
+    const hasAuth = headers["Authorization"] || headers["x-api-key"];
+    if (!hasAuth && (A2A_AUDIENCE || options.getHeaders)) {
+        return {
+            status: 401,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ error: "Unauthorized" }),
+        };
+    }
+    try {
+        const res = await fetch(url.toString(), {
+            method: req.method,
+            headers,
+            body: req.method !== "GET" && req.method !== "HEAD"
+                ? req.body
+                : undefined,
+        });
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            if (!["transfer-encoding", "connection", "keep-alive"].includes(key.toLowerCase())) {
+                responseHeaders[key] = value;
+            }
+        });
+        const noContent = res.status === 204 || res.status === 205;
+        if (noContent) {
+            return {
+                status: res.status,
+                statusText: res.statusText,
+                headers: responseHeaders,
+            };
+        }
+        const resContentType = res.headers.get("content-type") ?? "";
+        if (resContentType.includes("text/event-stream") && res.body) {
+            return {
+                status: res.status,
+                statusText: res.statusText,
+                headers: responseHeaders,
+                body: res.body,
+            };
+        }
+        const responseBody = await res.arrayBuffer();
+        return {
+            status: res.status,
+            statusText: res.statusText,
+            headers: responseHeaders,
+            body: responseBody,
+        };
+    }
+    catch (error) {
+        console.error("[Nebulas Proxy] Request failed:", error);
+        return {
+            status: 502,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ error: "Nebulas service unavailable" }),
+        };
+    }
+}

package/dist/server/nextjs.d.ts

@@ -3,6 +3,7 @@
  * Use in App Router: app/api/a2a/route.ts
  */
 import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
 import { type ProxyHandlerOptions } from "./proxy-handler.js";
 /**
  * Next.js App Router POST handler for A2A proxy.
@@ -51,4 +52,29 @@ export declare function createConfigGetHeadersForAuth0(options: {
     audience?: string;
     apiKey?: string;
 }): (request: NextRequest) => Promise<Record<string, string>>;
+/**
+ * Options for the Nebulas API proxy handler.
+ */
+export interface CreateNebulasProxyHandlerOptions {
+    auth0: Auth0ClientForConfig;
+    audience?: string;
+    apiKey?: string;
+}
+/**
+ * Creates a Next.js App Router handler for the Nebulas API proxy (catch-all [...path]).
+ * Proxies requests to NEBULAS_API_URL with Auth0 session token or API key.
+ *
+ * Use in app/api/nebulas/[...path]/route.ts:
+ *   const handler = createNebulasProxyHandler({ auth0, audience: process.env.AUTH0_A2A_AUDIENCE, apiKey: process.env.NEBULAS_API_KEY });
+ *   export const GET = handler;
+ *   export const POST = handler;
+ *   export const PUT = handler;
+ *   export const PATCH = handler;
+ *   export const DELETE = handler;
+ */
+export declare function createNebulasProxyHandler(options: CreateNebulasProxyHandlerOptions): (request: NextRequest, ctx: {
+    params: Promise<{
+        path: string[];
+    }>;
+}) => Promise<NextResponse<unknown>>;
 //# sourceMappingURL=nextjs.d.ts.map

package/dist/server/nextjs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/server/nextjs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAY9E;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,mBAAmB,qBA4B9B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,WAAW,qBAyBjE;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,sBAAsB,qBAcjC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC7D,cAAc,CACZ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyC5D"}
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/server/nextjs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAiB9E;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,mBAAmB,qBA6B9B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,WAAW,qBAyBjE;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,sBAAsB,qBAcjC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC7D,cAAc,CACZ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyC5D;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,IAE/E,SAAS,WAAW,EACpB,KAAK;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,oCAkH/C"}

package/dist/server/nextjs.js

@@ -4,6 +4,7 @@
  */
 import { NextResponse } from "next/server";
 import { handleA2AProxy } from "./proxy-handler.js";
+import { handleNebulasProxy, isRefreshTokenInvalid, } from "./nebulas-proxy-handler.js";
 import { exchangePasswordForToken } from "./auth-handler.js";
 import { createConfigResponse } from "./config-handler.js";
 function headersFromRequest(req) {
@@ -17,7 +18,8 @@ function headersFromRequest(req) {
  * Next.js App Router POST handler for A2A proxy.
  */
 export async function handleA2ANextJsPOST(request, options) {
-    const body = await request.text();
+    const requestForBody = request.clone();
+    const body = await requestForBody.text();
     const proxyReq = {
         method: request.method,
         headers: headersFromRequest(request),
@@ -123,3 +125,110 @@ export function createConfigGetHeadersForAuth0(options) {
         return headers;
     };
 }
+/**
+ * Creates a Next.js App Router handler for the Nebulas API proxy (catch-all [...path]).
+ * Proxies requests to NEBULAS_API_URL with Auth0 session token or API key.
+ *
+ * Use in app/api/nebulas/[...path]/route.ts:
+ *   const handler = createNebulasProxyHandler({ auth0, audience: process.env.AUTH0_A2A_AUDIENCE, apiKey: process.env.NEBULAS_API_KEY });
+ *   export const GET = handler;
+ *   export const POST = handler;
+ *   export const PUT = handler;
+ *   export const PATCH = handler;
+ *   export const DELETE = handler;
+ */
+export function createNebulasProxyHandler(options) {
+    return async function handler(request, ctx) {
+        const { path } = await ctx.params;
+        const session = await options.auth0.getSession(request);
+        if (!session) {
+            return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+        }
+        const authResponse = new NextResponse();
+        let authHeaders = {};
+        if (options.apiKey) {
+            authHeaders["x-api-key"] = options.apiKey;
+        }
+        if (options.audience) {
+            try {
+                const { token } = await options.auth0.getAccessToken(request, authResponse, { audience: options.audience });
+                if (token) {
+                    authHeaders["Authorization"] = `Bearer ${token}`;
+                }
+            }
+            catch (err) {
+                if (isRefreshTokenInvalid(err)) {
+                    return NextResponse.json({
+                        error: "Your session has expired. Please log out and log back in.",
+                        code: "refresh_token_invalid",
+                        requireReauth: true,
+                    }, { status: 401 });
+                }
+                if (!options.apiKey) {
+                    return NextResponse.json({
+                        error: "Unauthorized",
+                        hint: "Ensure Auth0 API has 'Allow Offline Access' enabled, MRRT is configured for the A2A audience, and you have logged out and back in to get a refresh token.",
+                    }, { status: 401 });
+                }
+                console.error("[Nebulas Proxy] Failed to get access token:", err);
+            }
+        }
+        const searchParams = {};
+        request.nextUrl.searchParams.forEach((value, key) => {
+            searchParams[key] = value;
+        });
+        let bodyForFetch;
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            try {
+                const text = await request.text();
+                bodyForFetch = text.length > 0 ? text : undefined;
+            }
+            catch {
+                return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
+            }
+        }
+        const proxyReq = {
+            method: request.method,
+            path,
+            headers: headersFromRequest(request),
+            body: bodyForFetch,
+            searchParams,
+        };
+        const result = await handleNebulasProxy(proxyReq, { headers: authHeaders });
+        const responseHeaders = new Headers();
+        for (const [k, v] of Object.entries(result.headers)) {
+            responseHeaders.set(k, v);
+        }
+        authResponse.headers.forEach((value, key) => {
+            if (key.toLowerCase() === "set-cookie") {
+                responseHeaders.append(key, value);
+            }
+        });
+        if (typeof result.body === "string") {
+            return new NextResponse(result.body, {
+                status: result.status,
+                statusText: result.statusText,
+                headers: responseHeaders,
+            });
+        }
+        if (result.body instanceof ReadableStream) {
+            return new NextResponse(result.body, {
+                status: result.status,
+                statusText: result.statusText,
+                headers: responseHeaders,
+            });
+        }
+        if (result.body instanceof ArrayBuffer) {
+            return new NextResponse(result.body, {
+                status: result.status,
+                statusText: result.statusText,
+                headers: responseHeaders,
+            });
+        }
+        return new NextResponse(null, {
+            status: result.status,
+            statusText: result.statusText,
+            headers: responseHeaders,
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnomondigital/nebulas-kit-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",