@gnomondigital/nebulas-kit-core 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+[Gnomon Digital] Software License Agreement
+
+This software is the exclusive property of Gnomon Digital. All rights reserved.
+
+By installing, copying, or otherwise using the Software, you agree to be bound by the terms of this License Agreement.
+
+1. Usage rights
+The use of this software is strictly reserved for employees and contractors of Gnomon Digital within the scope of their professional duties. Any other use, including distribution, modification, reproduction, or dissemination of this software, is prohibited without the prior written permission of Gnomon Digital.
+
+2. Restrictions
+You may not:
+    Modify, decompile, reverse-engineer, disassemble, or otherwise attempt to derive the source code of the Software.
+    Redistribute, sell, lease, sublicense, or otherwise transfer rights to the Software.
+    Remove or alter any proprietary notices or labels on the Software.
+
+3. Confidentiality
+The source code of this software is confidential and must not be disclosed to third parties without the prior written permission of Gnomon Digital.
+
+4.  Modifications
+Gnomon Digital reserves the right to modify this license at any time. Modifications will be communicated to authorized users and will take effect on the date specified in the notification.
+
+5. Termination
+This license is effective until terminated. It will terminate automatically without notice from Gnomon Digital if you fail to comply with any provision of this agreement. Upon termination, you must destroy all copies of the Software.
+
+6. No Warranty
+The Software is provided “AS IS” without warranty of any kind, express or implied. Gnomon Digital does not warrant that the Software will meet your requirements or that its operation will be uninterrupted or error-free.
+
+7. Limitation of Liability
+In no event shall Gnomon Digital be liable for any damages (including, without limitation, lost profits, business interruption, or lost information) arising out of the use or inability to use the Software.

package/README.md

@@ -0,0 +1,82 @@
+# @gnomondigital/nebulas-kit-core
+
+Framework-agnostic A2A chat client, Nebulas client, and server handlers.
+
+## Install
+
+```bash
+npm install @gnomondigital/nebulas-kit-core
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `A2A_URL` | Yes | A2A agent base URL |
+| `A2A_AUTH_STRATEGY` | Yes | `session` \| `client_credentials` \| `resource_owner_password` \| `api_key_only` |
+| `A2A_API_KEY` | For api_key_only, or fallback | x-api-key header |
+| `AUTH0_DOMAIN` | For Auth0 strategies | Auth0 tenant domain |
+| `AUTH0_CLIENT_ID` | For client_credentials, ROP | Auth0 client ID |
+| `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_PROJECT_ID` | For Nebulas | Project ID |
+
+## Usage
+
+### Client: sendMessageStream
+
+```ts
+import { sendMessageStream } from "@gnomondigital/nebulas-kit-core";
+
+const content = await sendMessageStream(
+  "Hello",
+  (chunk) => console.log(chunk),
+  signal,
+  files,
+  true,
+  sessionId,
+  { endpoint: "/api/a2a", getHeaders: async () => ({ Authorization: `Bearer ${token}` }) }
+);
+```
+
+### Next.js App Router
+
+```ts
+// app/api/a2a/route.ts
+import { handleA2ANextJsPOST } from "@nebulas-kit/core";
+
+export async function POST(req: NextRequest) {
+  return handleA2ANextJsPOST(req);
+}
+```
+
+```ts
+// app/api/a2a/auth/route.ts
+import { handleA2AAuthNextJsPOST } from "@gnomondigital/nebulas-kit-core";
+
+export async function POST(req: NextRequest) {
+  return handleA2AAuthNextJsPOST(req);
+}
+```
+
+```ts
+// app/api/a2a/config/route.ts
+import { handleA2AConfigNextJsGET } from "@gnomondigital/nebulas-kit-core";
+
+export async function GET() {
+  return handleA2AConfigNextJsGET();
+}
+```
+
+### Express
+
+```ts
+import express from "express";
+import { createA2AExpressRouter } from "@gnomondigital/nebulas-kit-core";
+
+const app = express();
+app.use(express.json());
+app.use("/api/a2a", createA2AExpressRouter(express));
+app.listen(3000);
+```

package/dist/a2a-client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A2A JSON-RPC client for AI Chat.
+ * Communicates with the A2A agent via proxy (configurable endpoint).
+ */
+/**
+ * Send a message and stream the response via SSE.
+ */
+export declare function sendMessageStream(message: string, onDelta: (chunk: string) => void, signal?: AbortSignal, files?: File[], stream?: boolean, sessionId?: string, options?: {
+    endpoint?: string;
+    getHeaders?: () => Promise<Record<string, string>>;
+}): Promise<string>;
+//# sourceMappingURL=a2a-client.d.ts.map

package/dist/a2a-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-client.d.ts","sourceRoot":"","sources":["../src/a2a-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,IAAI,EAAE,EACd,MAAM,UAAO,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,CAAC,CAgIjB"}

package/dist/a2a-client.js

@@ -0,0 +1,126 @@
+/**
+ * A2A JSON-RPC client for AI Chat.
+ * Communicates with the A2A agent via proxy (configurable endpoint).
+ */
+async function fileToBase64(file) {
+    const buf = await file.arrayBuffer();
+    const bytes = new Uint8Array(buf);
+    let binary = "";
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Send a message and stream the response via SSE.
+ */
+export async function sendMessageStream(message, onDelta, signal, files, stream = true, sessionId, options) {
+    const endpoint = options?.endpoint ?? "/api/a2a";
+    const parts = [{ kind: "text", text: message }];
+    if (files?.length) {
+        for (const file of files) {
+            const base64 = await fileToBase64(file);
+            parts.push({
+                kind: "file",
+                file: {
+                    name: file.name,
+                    mimeType: file.type || "application/octet-stream",
+                    bytes: base64,
+                },
+            });
+        }
+    }
+    const method = stream ? "message/stream" : "message/send";
+    const messageId = crypto.randomUUID();
+    const headers = { "Content-Type": "application/json" };
+    if (options?.getHeaders) {
+        const extra = await options.getHeaders();
+        Object.assign(headers, extra);
+    }
+    const res = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method,
+            id: messageId,
+            params: {
+                message: {
+                    role: "user",
+                    parts,
+                    messageId,
+                    metadata: {
+                        ...(sessionId && { session_id: sessionId }),
+                    },
+                },
+            },
+        }),
+        signal,
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({ error: res.statusText })));
+        const err = new Error(body.error || body.detail || `A2A error: ${res.status}`);
+        if (body.code)
+            err.code = body.code;
+        if (body.requireReauth)
+            err.requireReauth = body.requireReauth;
+        throw err;
+    }
+    if (!stream) {
+        const data = await res.json();
+        const result = data.result ?? data;
+        const content = result.append ??
+            result.content ??
+            result.text ??
+            result.status?.message?.parts?.[0]?.text ??
+            (typeof result.message === "string" ? result.message : "");
+        const text = typeof content === "string" ? content : "";
+        onDelta(text);
+        return text;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let accumulated = "";
+    let buffer = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            if (!line.startsWith("data: "))
+                continue;
+            const data = line.slice(6);
+            if (data === "[DONE]" || data.trim() === "")
+                continue;
+            try {
+                const parsed = JSON.parse(data);
+                const result = parsed.result ?? parsed;
+                if (typeof result.append === "string") {
+                    accumulated += result.append;
+                    onDelta(result.append);
+                    continue;
+                }
+                if (result.message && typeof result.message === "string") {
+                    accumulated += result.message;
+                    onDelta(result.message);
+                    continue;
+                }
+                const content = result.content ?? result.text ?? "";
+                if (content) {
+                    accumulated += content;
+                    onDelta(content);
+                }
+            }
+            catch {
+                if (data.trim()) {
+                    accumulated += data;
+                    onDelta(data);
+                }
+            }
+        }
+    }
+    return accumulated;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @gnomondigital/nebulas-kit-core
+ * Framework-agnostic A2A chat client, Nebulas client, and server handlers.
+ */
+export { sendMessageStream, } from "./a2a-client.js";
+export { createNebulasClient, nebulasClient, type NebulasConversation, type NebulasChatMessage, type CreateChatMessageParams, type NebulasClientOptions, } from "./nebulas-client.js";
+export { transformUtcDatesToLocal, } from "./utils/date-timezone.js";
+export type { ChatMessage, ChatMessagePayload, SendMessageStreamOptions } from "./types.js";
+export { handleA2AProxy, type ProxyRequest, type ProxyResponse, type ProxyHandlerOptions, } from "./server/proxy-handler.js";
+export { getAuthStrategy, getAuthHeaders, type AuthStrategy, } from "./server/auth-strategies.js";
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @gnomondigital/nebulas-kit-core
+ * Framework-agnostic A2A chat client, Nebulas client, and server handlers.
+ */
+export { sendMessageStream, } from "./a2a-client.js";
+export { createNebulasClient, nebulasClient, } from "./nebulas-client.js";
+export { transformUtcDatesToLocal, } from "./utils/date-timezone.js";
+export { handleA2AProxy, } from "./server/proxy-handler.js";
+export { getAuthStrategy, getAuthHeaders, } from "./server/auth-strategies.js";
+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";

package/dist/nebulas-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Nebulas API client for conversations and chat messages.
+ */
+export interface NebulasConversation {
+    id: string;
+    [key: string]: unknown;
+}
+export interface NebulasChatMessage {
+    id: string;
+    content: string;
+    role?: string | null;
+    parent_id?: string | null;
+    conversation_id?: string | null;
+    [key: string]: unknown;
+}
+export interface CreateChatMessageParams {
+    id?: string;
+    content: string;
+    role?: "user" | "assistant";
+    conversation_id: string;
+    parent_id?: string | null;
+    files?: unknown[];
+}
+export interface NebulasClientOptions {
+    baseUrl?: string;
+}
+/**
+ * Create a Nebulas client with configurable base URL.
+ */
+export declare function createNebulasClient(options?: NebulasClientOptions): {
+    createConversation: (query: string, projectId: string) => Promise<NebulasConversation>;
+    addChatMessage: (params: CreateChatMessageParams) => Promise<NebulasChatMessage[]>;
+};
+export declare const nebulasClient: {
+    createConversation: (query: string, projectId: string) => Promise<NebulasConversation>;
+    addChatMessage: (params: CreateChatMessageParams) => Promise<NebulasChatMessage[]>;
+};
+//# sourceMappingURL=nebulas-client.d.ts.map

package/dist/nebulas-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nebulas-client.d.ts","sourceRoot":"","sources":["../src/nebulas-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB;gCAI3D,MAAM,aACF,MAAM,KAChB,OAAO,CAAC,mBAAmB,CAAC;6BAiBrB,uBAAuB,KAC9B,OAAO,CAAC,kBAAkB,EAAE,CAAC;EAsBjC;AAED,eAAO,MAAM,aAAa;gCA5Cf,MAAM,aACF,MAAM,KAChB,OAAO,CAAC,mBAAmB,CAAC;6BAiBrB,uBAAuB,KAC9B,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAwBgB,CAAC"}

package/dist/nebulas-client.js

@@ -0,0 +1,46 @@
+/**
+ * Nebulas API client for conversations and chat messages.
+ */
+/**
+ * Create a Nebulas client with configurable base URL.
+ */
+export function createNebulasClient(options = {}) {
+    const baseUrl = options.baseUrl ?? "/api/nebulas";
+    async function createConversation(query, projectId) {
+        const params = new URLSearchParams({
+            query,
+            project_id: projectId,
+        });
+        const res = await fetch(`${baseUrl}/v1/conversations/?${params}`, {
+            method: "POST",
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ detail: res.statusText }));
+            throw new Error(body.detail || body.error || `Failed to create conversation: ${res.status}`);
+        }
+        const data = await res.json();
+        return data;
+    }
+    async function addChatMessage(params) {
+        const res = await fetch(`${baseUrl}/v1/chat_messages/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                id: params.id,
+                content: params.content,
+                role: params.role ?? "user",
+                conversation_id: params.conversation_id,
+                parent_id: params.parent_id ?? null,
+                files: params.files ?? null,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ detail: res.statusText }));
+            throw new Error(body.detail || body.error || `Failed to add message: ${res.status}`);
+        }
+        const data = await res.json();
+        return Array.isArray(data) ? data : [data];
+    }
+    return { createConversation, addChatMessage };
+}
+export const nebulasClient = createNebulasClient();

package/dist/server/auth-handler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Auth handler for Resource Owner Password flow.
+ * Exchanges username/password for Auth0 token.
+ */
+export interface ROPAuthRequest {
+    username: string;
+    password: string;
+}
+export interface ROPAuthResponse {
+    access_token: string;
+    expires_in?: number;
+}
+/**
+ * Exchange username/password for Auth0 access token.
+ */
+export declare function exchangePasswordForToken(username: string, password: string): Promise<ROPAuthResponse>;
+//# sourceMappingURL=auth-handler.d.ts.map

package/dist/server/auth-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-handler.d.ts","sourceRoot":"","sources":["../../src/server/auth-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CA8B1B"}

package/dist/server/auth-handler.js

@@ -0,0 +1,34 @@
+/**
+ * Auth handler for Resource Owner Password flow.
+ * Exchanges username/password for Auth0 token.
+ */
+/**
+ * Exchange username/password for Auth0 access token.
+ */
+export async function exchangePasswordForToken(username, password) {
+    const domain = process.env.AUTH0_DOMAIN;
+    const clientId = process.env.AUTH0_CLIENT_ID;
+    const clientSecret = process.env.AUTH0_CLIENT_SECRET;
+    const audience = process.env.AUTH0_A2A_AUDIENCE;
+    if (!domain || !clientId || !clientSecret) {
+        throw new Error("AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET required for ROP");
+    }
+    const res = await fetch(`https://${domain}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "password",
+            username,
+            password,
+            client_id: clientId,
+            client_secret: clientSecret,
+            ...(audience && { audience }),
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error_description || body.error || `Auth failed: ${res.status}`);
+    }
+    const data = (await res.json());
+    return data;
+}

package/dist/server/auth-strategies.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Auth strategies for A2A proxy.
+ * Framework-agnostic; returns headers to add to the A2A request.
+ */
+export type AuthStrategy = "session" | "client_credentials" | "resource_owner_password" | "api_key_only";
+/**
+ * Get headers for A2A request based on strategy.
+ * For session/bearer, the caller must pass the token (from session or Authorization header).
+ */
+export declare function getAuthHeaders(options: {
+    strategy: AuthStrategy;
+    bearerToken?: string;
+    getSessionToken?: () => Promise<string | undefined>;
+}): Promise<Record<string, string>>;
+export declare function getAuthStrategy(): AuthStrategy;
+//# sourceMappingURL=auth-strategies.d.ts.map

package/dist/server/auth-strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategies.d.ts","sourceRoot":"","sources":["../../src/server/auth-strategies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,oBAAoB,GACpB,yBAAyB,GACzB,cAAc,CAAC;AA8CnB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACrD,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA2BlC;AAED,wBAAgB,eAAe,IAAI,YAAY,CAW9C"}

package/dist/server/auth-strategies.js

@@ -0,0 +1,83 @@
+/**
+ * Auth strategies for A2A proxy.
+ * Framework-agnostic; returns headers to add to the A2A request.
+ */
+let m2mTokenCache = null;
+/**
+ * Get Auth0 token via client credentials (M2M).
+ */
+async function getClientCredentialsToken() {
+    const domain = process.env.AUTH0_DOMAIN;
+    const clientId = process.env.AUTH0_CLIENT_ID;
+    const clientSecret = process.env.AUTH0_CLIENT_SECRET;
+    const audience = process.env.AUTH0_A2A_AUDIENCE;
+    if (!domain || !clientId || !clientSecret || !audience) {
+        return undefined;
+    }
+    if (m2mTokenCache && m2mTokenCache.expiresAt > Date.now() + 60000) {
+        return m2mTokenCache.token;
+    }
+    const res = await fetch(`https://${domain}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: clientId,
+            client_secret: clientSecret,
+            audience,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error_description || body.error || `Auth0 token failed: ${res.status}`);
+    }
+    const data = (await res.json());
+    const expiresIn = (data.expires_in ?? 86400) * 1000;
+    m2mTokenCache = {
+        token: data.access_token,
+        expiresAt: Date.now() + expiresIn,
+    };
+    return data.access_token;
+}
+/**
+ * Get headers for A2A request based on strategy.
+ * For session/bearer, the caller must pass the token (from session or Authorization header).
+ */
+export async function getAuthHeaders(options) {
+    const headers = {};
+    const apiKey = process.env.A2A_API_KEY;
+    switch (options.strategy) {
+        case "api_key_only":
+            if (apiKey)
+                headers["x-api-key"] = apiKey;
+            break;
+        case "client_credentials": {
+            const token = await getClientCredentialsToken();
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            if (apiKey)
+                headers["x-api-key"] = apiKey;
+            break;
+        }
+        case "resource_owner_password":
+        case "session": {
+            const token = options.bearerToken ?? (options.getSessionToken ? await options.getSessionToken() : undefined);
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            if (apiKey)
+                headers["x-api-key"] = apiKey;
+            break;
+        }
+    }
+    return headers;
+}
+export function getAuthStrategy() {
+    const s = process.env.A2A_AUTH_STRATEGY?.toLowerCase();
+    if (s === "session" ||
+        s === "client_credentials" ||
+        s === "resource_owner_password" ||
+        s === "api_key_only") {
+        return s;
+    }
+    return "api_key_only";
+}

package/dist/server/config-handler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Config handler - returns nebulasProjectId and agent card-derived streaming capability.
+ * Fetches agent card from A2A_URL/.well-known/agent-card.json when A2A_URL is set.
+ * Framework-agnostic; returns JSON response body.
+ */
+export interface AgentCardCapabilities {
+    streaming?: boolean;
+    pushNotifications?: boolean;
+    extendedAgentCard?: boolean;
+}
+export interface AgentCard {
+    name?: string;
+    description?: string;
+    capabilities?: AgentCardCapabilities;
+    [key: string]: unknown;
+}
+export interface ConfigResponse {
+    nebulasProjectId: string | null;
+    agentCard?: AgentCard | null;
+    streaming?: boolean;
+}
+export interface CreateConfigResponseOptions {
+    /** When false, skip agent card fetch (streaming defaults to true). */
+    includeAgentCard?: boolean;
+    /** Headers to use when fetching agent card (e.g. Authorization, x-api-key). Same as A2A proxy. */
+    headers?: Record<string, string>;
+}
+export declare function createConfigResponse(options?: CreateConfigResponseOptions): Promise<ConfigResponse>;
+//# sourceMappingURL=config-handler.d.ts.map

package/dist/server/config-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-handler.d.ts","sourceRoot":"","sources":["../../src/server/config-handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAyBD,wBAAsB,oBAAoB,CACxC,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,cAAc,CAAC,CAmBzB"}

package/dist/server/config-handler.js

@@ -0,0 +1,47 @@
+/**
+ * Config handler - returns nebulasProjectId and agent card-derived streaming capability.
+ * Fetches agent card from A2A_URL/.well-known/agent-card.json when A2A_URL is set.
+ * Framework-agnostic; returns JSON response body.
+ */
+const A2A_URL = process.env.NEXT_PUBLIC_A2A_URL || process.env.A2A_URL || "";
+async function fetchAgentCard(headers) {
+    const base = A2A_URL.replace(/\/$/, "");
+    if (!base)
+        return null;
+    const url = `${base}/.well-known/agent-card.json`;
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(5000),
+            headers: {
+                "Content-Type": "application/json",
+                ...headers,
+            },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data;
+    }
+    catch (err) {
+        console.warn("[Config] Agent card fetch failed:", err);
+        return null;
+    }
+}
+export async function createConfigResponse(options) {
+    const nebulasProjectId = process.env.NEBULAS_PROJECT_ID ?? null;
+    const includeAgentCard = options?.includeAgentCard !== false;
+    if (!includeAgentCard) {
+        return {
+            nebulasProjectId,
+            agentCard: null,
+            streaming: true,
+        };
+    }
+    const agentCard = await fetchAgentCard(options?.headers);
+    const streaming = agentCard?.capabilities?.streaming ?? true;
+    return {
+        nebulasProjectId,
+        agentCard: agentCard ?? null,
+        streaming,
+    };
+}

package/dist/server/express.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Express adapter for A2A proxy, auth, and config.
+ * Use: app.use(express.json()); app.use("/api/a2a", createA2AExpressRouter(express));
+ */
+interface ExpressRequest {
+    method: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    query?: Record<string, string>;
+}
+interface ExpressResponse {
+    status: (code: number) => ExpressResponse;
+    setHeader: (name: string, value: string) => ExpressResponse;
+    send: (body?: unknown) => void;
+    write: (chunk: Buffer) => void;
+    end: () => void;
+    json: (body: unknown) => void;
+}
+interface ExpressRouter {
+    post: (path: string, handler: (req: ExpressRequest, res: ExpressResponse) => void | Promise<void>) => void;
+    get: (path: string, handler: (req: ExpressRequest, res: ExpressResponse) => void) => void;
+}
+interface ExpressModule {
+    Router: () => ExpressRouter;
+}
+type Request = ExpressRequest;
+import { type ProxyHandlerOptions } from "./proxy-handler.js";
+export interface A2AExpressRouterOptions extends ProxyHandlerOptions {
+    /** When provided, uses these headers when fetching agent card (same auth as A2A proxy). */
+    configGetHeaders?: (req: Request) => Promise<Record<string, string>>;
+}
+/**
+ * Create Express router for A2A proxy, auth (ROP), and config.
+ * Mount at /api/a2a - provides:
+ *   POST /     - A2A proxy
+ *   POST /auth - ROP token exchange (body: { username, password })
+ *   GET  /config - Config (nebulasProjectId)
+ */
+export declare function createA2AExpressRouter(express: ExpressModule, options?: A2AExpressRouterOptions): ExpressRouter;
+export {};
+//# sourceMappingURL=express.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/server/express.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAC;IAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,eAAe,CAAC;IAC5D,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/B;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IAC3G,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI,KAAK,IAAI,CAAC;CAC3F;AAED,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,aAAa,CAAC;CAC7B;AAED,KAAK,OAAO,GAAG,cAAc,CAAC;AAE9B,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAI9E,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtE;AAeD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,uBAAuB,iBAwElC"}

package/dist/server/express.js

@@ -0,0 +1,96 @@
+/**
+ * Express adapter for A2A proxy, auth, and config.
+ * Use: app.use(express.json()); app.use("/api/a2a", createA2AExpressRouter(express));
+ */
+import { handleA2AProxy } from "./proxy-handler.js";
+import { exchangePasswordForToken } from "./auth-handler.js";
+import { createConfigResponse } from "./config-handler.js";
+function getHeadersFromRequest(req) {
+    const headers = {};
+    const h = req.headers;
+    for (const [key, value] of Object.entries(h)) {
+        if (value && typeof value === "string") {
+            headers[key.toLowerCase()] = value;
+        }
+        else if (Array.isArray(value) && value.length) {
+            headers[key.toLowerCase()] = value[0];
+        }
+    }
+    return headers;
+}
+/**
+ * Create Express router for A2A proxy, auth (ROP), and config.
+ * Mount at /api/a2a - provides:
+ *   POST /     - A2A proxy
+ *   POST /auth - ROP token exchange (body: { username, password })
+ *   GET  /config - Config (nebulasProjectId)
+ */
+export function createA2AExpressRouter(express, options) {
+    const router = express.Router();
+    router.post("/", async (req, res) => {
+        try {
+            const body = typeof req.body === "string"
+                ? req.body
+                : JSON.stringify(req.body ?? {});
+            const proxyReq = {
+                method: req.method,
+                headers: getHeadersFromRequest(req),
+                body: body || undefined,
+            };
+            const result = await handleA2AProxy(proxyReq, options);
+            res.status(result.status);
+            for (const [k, v] of Object.entries(result.headers)) {
+                res.setHeader(k, v);
+            }
+            if (typeof result.body === "string") {
+                res.send(result.body);
+            }
+            else if (result.body && typeof result.body.getReader === "function") {
+                const reader = result.body.getReader();
+                const pump = async () => {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        res.write(Buffer.from(value));
+                    }
+                    res.end();
+                };
+                pump();
+            }
+        }
+        catch (err) {
+            console.error("[A2A Express] Error:", err);
+            res.status(500).json({ error: "Internal server error" });
+        }
+    });
+    router.post("/auth", async (req, res) => {
+        try {
+            const body = req.body;
+            const { username, password } = body ?? {};
+            if (!username || !password) {
+                res.status(400).json({ error: "username and password required" });
+                return;
+            }
+            const data = await exchangePasswordForToken(username, password);
+            res.json(data);
+        }
+        catch (err) {
+            console.error("[A2A Auth] Error:", err);
+            res.status(401).json({
+                error: "Authentication failed",
+                message: err instanceof Error ? err.message : "Unknown error",
+            });
+        }
+    });
+    router.get("/config", async (req, res) => {
+        const includeAgentCard = req.query?.includeAgentCard !== "false";
+        let headers;
+        if (options?.configGetHeaders && includeAgentCard) {
+            headers = await options.configGetHeaders(req);
+        }
+        const config = await createConfigResponse({ includeAgentCard, headers });
+        res.json(config);
+    });
+    return router;
+}

package/dist/server/nextjs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Next.js adapter for A2A proxy, auth, and config.
+ * Use in App Router: app/api/a2a/route.ts
+ */
+import type { NextRequest } from "next/server";
+import { type ProxyHandlerOptions } from "./proxy-handler.js";
+/**
+ * Next.js App Router POST handler for A2A proxy.
+ */
+export declare function handleA2ANextJsPOST(request: NextRequest, options?: ProxyHandlerOptions): Promise<Response>;
+/**
+ * Next.js App Router POST handler for ROP auth.
+ */
+export declare function handleA2AAuthNextJsPOST(request: NextRequest): Promise<Response>;
+/**
+ * Options for the config GET handler.
+ */
+export interface HandleA2AConfigOptions {
+    /**
+     * When provided, fetches the agent card with these headers (Authorization, x-api-key).
+     * Use createConfigGetHeadersForAuth0 for Auth0 session strategy.
+     */
+    getHeaders?: (request: NextRequest) => Promise<Record<string, string>>;
+}
+/**
+ * Next.js App Router GET handler for config.
+ * When getHeaders is provided, uses those headers when fetching the agent card (same auth as A2A proxy).
+ */
+export declare function handleA2AConfigNextJsGET(request: NextRequest, options?: HandleA2AConfigOptions): Promise<Response>;
+/**
+ * Auth0 client interface for config headers.
+ * Compatible with Auth0Client from @auth0/nextjs-auth0/server.
+ */
+export interface Auth0ClientForConfig {
+    getSession(req: unknown): Promise<{
+        user?: unknown;
+    } | null>;
+    getAccessToken(req: unknown, res: unknown, opts: {
+        audience: string;
+    }): Promise<{
+        token: string;
+    }>;
+}
+/**
+ * Creates getHeaders for handleA2AConfigNextJsGET using Auth0 session.
+ * Uses same auth as A2A proxy: session, access token for A2A audience, x-api-key fallback.
+ * Throws NextResponse (401) when unauthorized.
+ */
+export declare function createConfigGetHeadersForAuth0(options: {
+    auth0: Auth0ClientForConfig;
+    audience?: string;
+    apiKey?: string;
+}): (request: NextRequest) => Promise<Record<string, string>>;
+//# sourceMappingURL=nextjs.d.ts.map

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

@@ -0,0 +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"}

package/dist/server/nextjs.js

@@ -0,0 +1,125 @@
+/**
+ * Next.js adapter for A2A proxy, auth, and config.
+ * Use in App Router: app/api/a2a/route.ts
+ */
+import { NextResponse } from "next/server";
+import { handleA2AProxy } from "./proxy-handler.js";
+import { exchangePasswordForToken } from "./auth-handler.js";
+import { createConfigResponse } from "./config-handler.js";
+function headersFromRequest(req) {
+    const headers = {};
+    req.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    return headers;
+}
+/**
+ * Next.js App Router POST handler for A2A proxy.
+ */
+export async function handleA2ANextJsPOST(request, options) {
+    const body = await request.text();
+    const proxyReq = {
+        method: request.method,
+        headers: headersFromRequest(request),
+        body: body || undefined,
+    };
+    const result = await handleA2AProxy(proxyReq, options);
+    const responseHeaders = new Headers();
+    for (const [k, v] of Object.entries(result.headers)) {
+        responseHeaders.set(k, v);
+    }
+    if (typeof result.body === "string") {
+        return new Response(result.body, {
+            status: result.status,
+            headers: responseHeaders,
+        });
+    }
+    if (result.body instanceof ReadableStream) {
+        return new Response(result.body, {
+            status: result.status,
+            headers: responseHeaders,
+        });
+    }
+    return new Response(null, { status: result.status, headers: responseHeaders });
+}
+/**
+ * Next.js App Router POST handler for ROP auth.
+ */
+export async function handleA2AAuthNextJsPOST(request) {
+    try {
+        const body = await request.json();
+        const { username, password } = body ?? {};
+        if (!username || !password) {
+            return new Response(JSON.stringify({ error: "username and password required" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const data = await exchangePasswordForToken(username, password);
+        return new Response(JSON.stringify(data), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    catch (err) {
+        console.error("[A2A Auth] Error:", err);
+        return new Response(JSON.stringify({
+            error: "Authentication failed",
+            message: err instanceof Error ? err.message : "Unknown error",
+        }), { status: 401, headers: { "Content-Type": "application/json" } });
+    }
+}
+/**
+ * Next.js App Router GET handler for config.
+ * When getHeaders is provided, uses those headers when fetching the agent card (same auth as A2A proxy).
+ */
+export async function handleA2AConfigNextJsGET(request, options) {
+    const includeAgentCard = request.nextUrl.searchParams.get("includeAgentCard") !== "false";
+    let headers;
+    if (options?.getHeaders && includeAgentCard) {
+        headers = await options.getHeaders(request);
+    }
+    const config = await createConfigResponse({ includeAgentCard, headers });
+    return new Response(JSON.stringify(config), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/**
+ * Creates getHeaders for handleA2AConfigNextJsGET using Auth0 session.
+ * Uses same auth as A2A proxy: session, access token for A2A audience, x-api-key fallback.
+ * Throws NextResponse (401) when unauthorized.
+ */
+export function createConfigGetHeadersForAuth0(options) {
+    return async (request) => {
+        const session = await options.auth0.getSession(request);
+        if (!session) {
+            throw new NextResponse(JSON.stringify({ error: "Unauthorized" }), {
+                status: 401,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const headers = {};
+        if (options.apiKey) {
+            headers["x-api-key"] = options.apiKey;
+        }
+        if (options.audience) {
+            try {
+                const authResponse = new NextResponse();
+                const { token } = await options.auth0.getAccessToken(request, authResponse, {
+                    audience: options.audience,
+                });
+                if (token) {
+                    headers["Authorization"] = `Bearer ${token}`;
+                }
+            }
+            catch (err) {
+                console.error("[Config] Failed to get access token:", err);
+                if (!options.apiKey) {
+                    throw new NextResponse(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.",
+                    }), { status: 401, headers: { "Content-Type": "application/json" } });
+                }
+            }
+        }
+        return headers;
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Framework-agnostic A2A proxy handler.
+ * Accepts a minimal request/response interface.
+ */
+export interface ProxyRequest {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface ProxyResponse {
+    status: number;
+    headers: Record<string, string>;
+    body?: string | ReadableStream<Uint8Array>;
+}
+export interface ProxyHandlerOptions {
+    getSessionToken?: (req: ProxyRequest) => Promise<string | undefined>;
+}
+/**
+ * Handle A2A proxy request. Returns response to send.
+ */
+export declare function handleA2AProxy(req: ProxyRequest, options?: ProxyHandlerOptions): Promise<ProxyResponse>;
+//# sourceMappingURL=proxy-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-handler.d.ts","sourceRoot":"","sources":["../../src/server/proxy-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACtE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CA0ExB"}

package/dist/server/proxy-handler.js

@@ -0,0 +1,78 @@
+/**
+ * Framework-agnostic A2A proxy handler.
+ * Accepts a minimal request/response interface.
+ */
+import { getAuthStrategy, getAuthHeaders, } from "./auth-strategies.js";
+const A2A_URL = process.env.NEXT_PUBLIC_A2A_URL || process.env.A2A_URL || "http://localhost:9999";
+/**
+ * Handle A2A proxy request. Returns response to send.
+ */
+export async function handleA2AProxy(req, options = {}) {
+    const url = A2A_URL.replace(/\/$/, "");
+    const strategy = getAuthStrategy();
+    let bearerToken;
+    const authHeader = req.headers["authorization"] || req.headers["Authorization"];
+    if (authHeader?.startsWith("Bearer ")) {
+        bearerToken = authHeader.slice(7);
+    }
+    else if (strategy === "session" && options.getSessionToken) {
+        bearerToken = await options.getSessionToken(req);
+    }
+    if (strategy === "session" && !bearerToken && !process.env.A2A_API_KEY) {
+        return {
+            status: 401,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                error: "Unauthorized",
+                hint: "Session required or A2A_API_KEY for fallback.",
+            }),
+        };
+    }
+    const authHeaders = await getAuthHeaders({
+        strategy,
+        bearerToken,
+        getSessionToken: options.getSessionToken
+            ? () => options.getSessionToken(req)
+            : undefined,
+    });
+    const headers = {
+        "Content-Type": req.headers["content-type"] || "application/json",
+        ...authHeaders,
+    };
+    try {
+        const res = await fetch(url, {
+            method: req.method,
+            headers,
+            body: req.body,
+        });
+        const resContentType = res.headers.get("content-type") ?? "";
+        const responseHeaders = {
+            "Content-Type": resContentType || "application/json",
+        };
+        if (resContentType.includes("text/event-stream")) {
+            responseHeaders["Cache-Control"] = "no-cache";
+            responseHeaders["Connection"] = "keep-alive";
+        }
+        if (resContentType.includes("text/event-stream") && res.body) {
+            return {
+                status: res.status,
+                headers: responseHeaders,
+                body: res.body,
+            };
+        }
+        const data = await res.arrayBuffer();
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: new TextDecoder().decode(data),
+        };
+    }
+    catch (error) {
+        console.error("[A2A Proxy] Request failed:", error);
+        return {
+            status: 502,
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ error: "A2A service unavailable" }),
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types for A2A chat.
+ */
+export interface ChatMessage {
+    id: string;
+    role: "user" | "agent";
+    content: string;
+    isStreaming?: boolean;
+    files?: {
+        name: string;
+    }[];
+}
+export interface ChatMessagePayload {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface SendMessageStreamOptions {
+    endpoint: string;
+    message: string;
+    onDelta: (chunk: string) => void;
+    signal?: AbortSignal;
+    files?: File[];
+    stream?: boolean;
+    sessionId?: string;
+    getHeaders?: () => Promise<Record<string, string>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD"}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for A2A chat.
+ */
+export {};

package/dist/utils/date-timezone.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Transforms UTC date-time strings in text to the user's local timezone.
+ */
+/**
+ * Replaces UTC date-time strings in text with local timezone equivalents.
+ */
+export declare function transformUtcDatesToLocal(text: string, locale?: string): string;
+//# sourceMappingURL=date-timezone.d.ts.map

package/dist/utils/date-timezone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-timezone.d.ts","sourceRoot":"","sources":["../../src/utils/date-timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAuHH;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAEG,GACV,MAAM,CA8BR"}

package/dist/utils/date-timezone.js

@@ -0,0 +1,109 @@
+/**
+ * Transforms UTC date-time strings in text to the user's local timezone.
+ */
+const FRENCH_MONTHS = {
+    janvier: 0,
+    février: 1,
+    mars: 2,
+    avril: 3,
+    mai: 4,
+    juin: 5,
+    juillet: 6,
+    août: 7,
+    septembre: 8,
+    octobre: 9,
+    novembre: 10,
+    décembre: 11,
+};
+const ENGLISH_MONTHS = {
+    january: 0,
+    february: 1,
+    march: 2,
+    april: 3,
+    may: 4,
+    june: 5,
+    july: 6,
+    august: 7,
+    september: 8,
+    october: 9,
+    november: 10,
+    december: 11,
+};
+function tryParseUtcDate(match) {
+    const isoMatch = match.match(/(\d{4})-(\d{2})-(\d{2})T(\d{1,2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?Z/);
+    if (isoMatch) {
+        const [, y, m, d, h, min, sec] = isoMatch;
+        const month = parseInt(m, 10) - 1;
+        return new Date(Date.UTC(parseInt(y, 10), month, parseInt(d, 10), parseInt(h, 10), parseInt(min, 10), parseInt(sec ?? "0", 10)));
+    }
+    const longMatch = match.match(/(?:(\w+)\s+)?(\d{1,2})\s+(\w+)\s+(\d{4}),\s*(\d{1,2}):(\d{2})\s*UTC/i);
+    if (longMatch) {
+        const [, , dayStr, monthStr, yearStr, hourStr, minStr] = longMatch;
+        const month = (FRENCH_MONTHS[monthStr.toLowerCase()] ??
+            ENGLISH_MONTHS[monthStr.toLowerCase()]);
+        if (month !== undefined) {
+            return new Date(Date.UTC(parseInt(yearStr, 10), month, parseInt(dayStr, 10), parseInt(hourStr, 10), parseInt(minStr, 10)));
+        }
+    }
+    const timeOnlyMatch = match.match(/(\d{1,2}):(\d{2})\s*UTC/);
+    if (timeOnlyMatch) {
+        const now = new Date();
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), parseInt(timeOnlyMatch[1], 10), parseInt(timeOnlyMatch[2], 10)));
+    }
+    return null;
+}
+function formatLocalDateTime(date, locale) {
+    if (typeof Intl === "undefined" || !Intl.DateTimeFormat) {
+        return date.toLocaleString();
+    }
+    const formatter = new Intl.DateTimeFormat(locale, {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    return formatter.format(date);
+}
+function formatLocalDateTimeShort(date, locale) {
+    if (typeof Intl === "undefined" || !Intl.DateTimeFormat) {
+        return date.toLocaleString();
+    }
+    const formatter = new Intl.DateTimeFormat(locale, {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    return formatter.format(date);
+}
+/**
+ * Replaces UTC date-time strings in text with local timezone equivalents.
+ */
+export function transformUtcDatesToLocal(text, locale = typeof navigator !== "undefined"
+    ? navigator.language
+    : "fr-FR") {
+    if (!text || typeof text !== "string")
+        return text;
+    let result = text;
+    result = result.replace(/(\d{4}-\d{2}-\d{2}T\d{1,2}:\d{2}(?::\d{2})?(?:\.\d+)?Z)/g, (match) => {
+        const date = tryParseUtcDate(match);
+        return date ? formatLocalDateTime(date, locale) : match;
+    });
+    result = result.replace(/((?:\w+\s+)?\d{1,2}\s+\w+\s+\d{4},\s*\d{1,2}:\d{2}\s*)UTC/gi, (match) => {
+        const date = tryParseUtcDate(match);
+        if (date) {
+            return formatLocalDateTime(date, locale);
+        }
+        return match.replace(/\s*UTC\s*$/i, "");
+    });
+    result = result.replace(/(\d{1,2}:\d{2})\s*UTC\b/g, (match) => {
+        const date = tryParseUtcDate(match);
+        return date ? formatLocalDateTimeShort(date, locale) : match.replace(/\s*UTC\s*$/i, "");
+    });
+    return result;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gnomondigital/nebulas-kit-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "next": ">=14",
+    "express": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "@auth0/nextjs-auth0": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "express": "^4.18.2",
+    "next": "^14.0.0",
+    "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}