@uranotools/urano-social 0.0.0-stage → 0.2.0

package/dist/server/proxy.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSocialProxy = createSocialProxy;
+exports.socialProxyRoute = socialProxyRoute;
+const crypto_1 = require("../crypto");
+const visitorCookie_1 = require("./visitorCookie");
+function envConfig(partial) {
+    const webhookUrl = partial?.webhookUrl || process.env.URANO_SOCIAL_WEBHOOK_URL || '';
+    const webhookSecret = partial?.webhookSecret || process.env.URANO_SOCIAL_WEBHOOK_SECRET || '';
+    if (!webhookUrl)
+        throw new Error('URANO_SOCIAL_WEBHOOK_URL is required');
+    if (!webhookSecret)
+        throw new Error('URANO_SOCIAL_WEBHOOK_SECRET is required');
+    return {
+        webhookUrl: webhookUrl.replace(/\/$/, ''),
+        webhookSecret,
+        cookieSecret: partial?.cookieSecret || process.env.URANO_SOCIAL_COOKIE_SECRET || webhookSecret,
+        cookieName: partial?.cookieName || visitorCookie_1.DEFAULT_COOKIE_NAME,
+        cookieMaxAgeSec: partial?.cookieMaxAgeSec,
+        defaultDisplayName: partial?.defaultDisplayName,
+    };
+}
+function json(status, body, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json', ...(headers || {}) },
+    });
+}
+async function readJson(request) {
+    const text = await request.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('invalid_json');
+    }
+}
+/**
+ * Creates a site-local proxy that signs webhook traffic with the server secret.
+ * The browser never receives WEBHOOK_SECRET.
+ */
+function createSocialProxy(partial) {
+    const config = envConfig(partial);
+    async function handle(request) {
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        if (method === 'OPTIONS') {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    'Access-Control-Allow-Origin': request.headers.get('Origin') || '*',
+                    'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Idempotency-Key, Last-Event-ID, Accept',
+                    'Access-Control-Allow-Credentials': 'true',
+                },
+            });
+        }
+        const visitor = (0, visitorCookie_1.resolveVisitorId)({
+            cookieHeader: request.headers.get('cookie'),
+            cookieName: config.cookieName,
+            cookieSecret: config.cookieSecret,
+        });
+        const responseHeaders = new Headers();
+        if (visitor.setCookie)
+            responseHeaders.append('Set-Cookie', visitor.setCookie);
+        if (method === 'GET' && !url.searchParams.get('mode') && !url.searchParams.get('payload')) {
+            try {
+                const discovery = await fetch(config.webhookUrl, { method: 'GET' });
+                const body = await discovery.json().catch(() => ({ ok: discovery.ok }));
+                responseHeaders.set('Content-Type', 'application/json');
+                return new Response(JSON.stringify({
+                    ok: true,
+                    proxy: true,
+                    visitorId: visitor.visitorId,
+                    upstream: body,
+                }), { status: 200, headers: responseHeaders });
+            }
+            catch (error) {
+                return json(502, { error: 'upstream_unreachable', message: error?.message }, responseHeaders);
+            }
+        }
+        let clientBody = {};
+        try {
+            if (method === 'GET') {
+                const payloadParam = url.searchParams.get('payload');
+                clientBody = payloadParam ? JSON.parse(payloadParam) : {};
+            }
+            else {
+                clientBody = await readJson(request);
+            }
+        }
+        catch {
+            return json(400, { error: 'invalid_json' }, responseHeaders);
+        }
+        const mode = String(url.searchParams.get('mode')
+            || clientBody.mode
+            || ((request.headers.get('Accept') || '').includes('text/event-stream') ? 'sse' : 'wait'));
+        const isContact = ['contact', 'email', 'form'].includes(String(clientBody.type || clientBody.channel || '').toLowerCase());
+        const outbound = isContact
+            ? { type: 'contact' }
+            : {
+                visitorId: visitor.visitorId,
+                from: visitor.visitorId,
+            };
+        if (isContact) {
+            if (typeof clientBody.email === 'string')
+                outbound.email = clientBody.email.trim().toLowerCase();
+            if (typeof clientBody.name === 'string')
+                outbound.name = clientBody.name;
+            if (typeof clientBody.subject === 'string')
+                outbound.subject = clientBody.subject;
+            if (typeof clientBody.message === 'string')
+                outbound.message = clientBody.message;
+            else if (typeof clientBody.text === 'string')
+                outbound.message = clientBody.text;
+            if (typeof clientBody.phone === 'string')
+                outbound.phone = clientBody.phone;
+            if (typeof clientBody.company === 'string')
+                outbound.company = clientBody.company;
+            // Correlate without trusting client visitor identity for CRM email channel.
+            outbound.visitorId = visitor.visitorId;
+        }
+        else {
+            if (typeof clientBody.text === 'string')
+                outbound.text = clientBody.text;
+            if (typeof clientBody.sessionId === 'string')
+                outbound.sessionId = clientBody.sessionId;
+            if (typeof clientBody.SessionId === 'string')
+                outbound.sessionId = clientBody.SessionId;
+            if (typeof clientBody.displayName === 'string')
+                outbound.displayName = clientBody.displayName;
+            else if (config.defaultDisplayName)
+                outbound.displayName = config.defaultDisplayName;
+            if (clientBody.webhookAction)
+                outbound.webhookAction = clientBody.webhookAction;
+            if (clientBody.turnId)
+                outbound.turnId = clientBody.turnId;
+            if (clientBody.after)
+                outbound.after = clientBody.after;
+            if (clientBody.idempotencyKey)
+                outbound.idempotencyKey = clientBody.idempotencyKey;
+        }
+        // Never trust a visitorId / from supplied by the browser for chat identity.
+        delete clientBody.visitorId;
+        delete clientBody.from;
+        const rawBody = JSON.stringify(outbound);
+        const signature = (0, crypto_1.signHmacHex)(rawBody, config.webhookSecret);
+        const idempotency = request.headers.get('Idempotency-Key')
+            || (typeof outbound.idempotencyKey === 'string' ? outbound.idempotencyKey : undefined);
+        const upstreamHeaders = {
+            'Content-Type': 'application/json',
+            'x-urano-signature': signature,
+            'X-Urano-Protocol-Version': '1',
+        };
+        if (idempotency)
+            upstreamHeaders['Idempotency-Key'] = idempotency;
+        const lastEventId = request.headers.get('Last-Event-ID');
+        if (lastEventId)
+            upstreamHeaders['Last-Event-ID'] = lastEventId;
+        let upstreamUrl = `${config.webhookUrl}?mode=${encodeURIComponent(mode === 'auto' ? 'sse' : mode)}`;
+        let upstreamInit;
+        if (method === 'GET') {
+            upstreamUrl += `&payload=${encodeURIComponent(rawBody)}`;
+            upstreamInit = { method: 'GET', headers: upstreamHeaders };
+        }
+        else {
+            upstreamInit = { method: 'POST', headers: upstreamHeaders, body: rawBody };
+        }
+        if (mode === 'sse' || request.headers.get('Accept')?.includes('text/event-stream')) {
+            upstreamHeaders['Accept'] = 'text/event-stream';
+        }
+        try {
+            const upstream = await fetch(upstreamUrl, upstreamInit);
+            upstream.headers.forEach((value, key) => {
+                const lower = key.toLowerCase();
+                if (['transfer-encoding', 'content-encoding', 'content-length', 'set-cookie'].includes(lower))
+                    return;
+                responseHeaders.set(key, value);
+            });
+            responseHeaders.set('X-Urano-Social-Visitor', visitor.visitorId);
+            responseHeaders.set('Cache-Control', 'no-cache, no-transform');
+            if (mode === 'sse') {
+                responseHeaders.set('Content-Type', 'text/event-stream; charset=utf-8');
+                responseHeaders.set('X-Accel-Buffering', 'no');
+            }
+            return new Response(upstream.body, {
+                status: upstream.status,
+                headers: responseHeaders,
+            });
+        }
+        catch (error) {
+            return json(502, { error: 'upstream_unreachable', message: error?.message }, responseHeaders);
+        }
+    }
+    return { handle };
+}
+/** Convenience for Next.js App Router route handlers. */
+function socialProxyRoute(partial) {
+    const proxy = createSocialProxy(partial);
+    return {
+        GET: (request) => proxy.handle(request),
+        POST: (request) => proxy.handle(request),
+        OPTIONS: (request) => proxy.handle(request),
+    };
+}

package/dist/server/visitorCookie.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_COOKIE_NAME = "urano_social_vid";
+export declare function parseCookies(header: string | null | undefined): Record<string, string>;
+export declare function resolveVisitorId(opts: {
+    cookieHeader?: string | null;
+    cookieName?: string;
+    cookieSecret: string;
+}): {
+    visitorId: string;
+    isNew: boolean;
+    setCookie?: string;
+};

package/dist/server/visitorCookie.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COOKIE_NAME = void 0;
+exports.parseCookies = parseCookies;
+exports.resolveVisitorId = resolveVisitorId;
+const crypto_1 = require("../crypto");
+exports.DEFAULT_COOKIE_NAME = 'urano_social_vid';
+function parseCookies(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx < 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key)
+            out[key] = decodeURIComponent(value);
+    }
+    return out;
+}
+function resolveVisitorId(opts) {
+    const name = opts.cookieName || exports.DEFAULT_COOKIE_NAME;
+    const cookies = parseCookies(opts.cookieHeader);
+    const existing = cookies[name];
+    if (existing) {
+        const verified = (0, crypto_1.verifyCookieValue)(existing, opts.cookieSecret);
+        if (verified)
+            return { visitorId: verified, isNew: false };
+    }
+    const visitorId = (0, crypto_1.randomId)('vis');
+    const signed = (0, crypto_1.signCookieValue)(visitorId, opts.cookieSecret);
+    const maxAge = 60 * 60 * 24 * 365;
+    const setCookie = [
+        `${name}=${encodeURIComponent(signed)}`,
+        'Path=/',
+        `Max-Age=${maxAge}`,
+        'HttpOnly',
+        'SameSite=Lax',
+    ].join('; ');
+    return { visitorId, isNew: true, setCookie };
+}

package/dist/server/websocket.d.ts

@@ -0,0 +1,21 @@
+import * as http from 'http';
+import type { SocialProxyConfig } from '../types';
+export interface AttachSocialWebSocketOptions extends Partial<SocialProxyConfig> {
+    /** Path on the site server that accepts WS upgrades, default `/api/urano-social/ws`. */
+    path?: string;
+}
+/**
+ * Attaches an optional WebSocket bridge to a Node HTTP server.
+ * Next App Router cannot upgrade sockets in a route handler — use SSE there.
+ * Astro Node / custom servers can call this after `http.createServer`.
+ */
+export declare function attachSocialWebSocket(server: http.Server, partial?: AttachSocialWebSocketOptions): () => void;
+/** Exported for tests — builds the WS envelope the upstream expects. */
+export declare function buildWsEnvelope(payload: Record<string, unknown>, secret: string): {
+    payload: string;
+    headers: {
+        'x-urano-signature': string;
+        'Content-Type': string;
+        'X-Urano-Protocol-Version': string;
+    };
+};

package/dist/server/websocket.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSocialWebSocket = attachSocialWebSocket;
+exports.buildWsEnvelope = buildWsEnvelope;
+const crypto_1 = require("../crypto");
+const visitorCookie_1 = require("./visitorCookie");
+/**
+ * Attaches an optional WebSocket bridge to a Node HTTP server.
+ * Next App Router cannot upgrade sockets in a route handler — use SSE there.
+ * Astro Node / custom servers can call this after `http.createServer`.
+ */
+function attachSocialWebSocket(server, partial) {
+    const webhookUrl = (partial?.webhookUrl || process.env.URANO_SOCIAL_WEBHOOK_URL || '').replace(/\/$/, '');
+    const webhookSecret = partial?.webhookSecret || process.env.URANO_SOCIAL_WEBHOOK_SECRET || '';
+    const cookieSecret = partial?.cookieSecret || process.env.URANO_SOCIAL_COOKIE_SECRET || webhookSecret;
+    const cookieName = partial?.cookieName || visitorCookie_1.DEFAULT_COOKIE_NAME;
+    const path = partial?.path || '/api/urano-social/ws';
+    if (!webhookUrl || !webhookSecret) {
+        throw new Error('attachSocialWebSocket requires URANO_SOCIAL_WEBHOOK_URL and URANO_SOCIAL_WEBHOOK_SECRET');
+    }
+    const upstreamWs = webhookUrl.replace(/^http/, 'ws') + '/ws';
+    const onUpgrade = (req, socket, head) => {
+        const url = new URL(req.url || '/', 'http://localhost');
+        if (url.pathname !== path)
+            return;
+        const visitor = (0, visitorCookie_1.resolveVisitorId)({
+            cookieHeader: req.headers.cookie,
+            cookieName,
+            cookieSecret,
+        });
+        // Minimal RFC6455 accept handshake, then bridge frames as text JSON.
+        // Prefer the host runtime's `ws` package when available; fall back to rejecting.
+        let WebSocketImpl;
+        try {
+            WebSocketImpl = require('ws');
+        }
+        catch {
+            socket.write('HTTP/1.1 501 Not Implemented\r\nConnection: close\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        const wss = new WebSocketImpl.Server({ noServer: true });
+        wss.handleUpgrade(req, socket, head, (client) => {
+            if (visitor.setCookie) {
+                // Cookie already set via prior HTTP; continue.
+            }
+            const upstream = new WebSocketImpl(upstreamWs);
+            let sessionId;
+            upstream.on('open', () => {
+                client.send(JSON.stringify({ type: 'proxy_ready', visitorId: visitor.visitorId }));
+            });
+            client.on('message', (data) => {
+                let msg;
+                try {
+                    msg = JSON.parse(String(data));
+                }
+                catch {
+                    client.send(JSON.stringify({ type: 'error', error: 'invalid_json' }));
+                    return;
+                }
+                const payloadObj = {
+                    visitorId: visitor.visitorId,
+                    from: visitor.visitorId,
+                    text: typeof msg.text === 'string' ? msg.text : undefined,
+                    sessionId: typeof msg.sessionId === 'string' ? msg.sessionId : sessionId,
+                    displayName: typeof msg.displayName === 'string' ? msg.displayName : undefined,
+                    webhookAction: msg.webhookAction,
+                    turnId: msg.turnId,
+                };
+                const payloadStr = JSON.stringify(payloadObj);
+                const signature = (0, crypto_1.signHmacHex)(payloadStr, webhookSecret);
+                upstream.send(JSON.stringify({
+                    payload: payloadStr,
+                    headers: {
+                        'x-urano-signature': signature,
+                        'Content-Type': 'application/json',
+                        'X-Urano-Protocol-Version': '1',
+                        ...(msg.idempotencyKey ? { 'Idempotency-Key': msg.idempotencyKey } : {}),
+                    },
+                }));
+            });
+            upstream.on('message', (data) => {
+                try {
+                    const evt = JSON.parse(String(data));
+                    if (evt?.sessionId)
+                        sessionId = evt.sessionId;
+                    if (evt?.type === 'session' && evt.sessionId)
+                        sessionId = evt.sessionId;
+                }
+                catch { /* forward raw */ }
+                if (client.readyState === 1)
+                    client.send(String(data));
+            });
+            const closeBoth = () => {
+                try {
+                    client.close();
+                }
+                catch { /* ignore */ }
+                try {
+                    upstream.close();
+                }
+                catch { /* ignore */ }
+            };
+            client.on('close', closeBoth);
+            upstream.on('close', closeBoth);
+            client.on('error', closeBoth);
+            upstream.on('error', (err) => {
+                try {
+                    client.send(JSON.stringify({ type: 'error', error: err.message }));
+                }
+                catch { /* ignore */ }
+                closeBoth();
+            });
+        });
+    };
+    server.on('upgrade', onUpgrade);
+    return () => server.off('upgrade', onUpgrade);
+}
+/** Exported for tests — builds the WS envelope the upstream expects. */
+function buildWsEnvelope(payload, secret) {
+    const payloadStr = JSON.stringify(payload);
+    return {
+        payload: payloadStr,
+        headers: {
+            'x-urano-signature': (0, crypto_1.signHmacHex)(payloadStr, secret),
+            'Content-Type': 'application/json',
+            'X-Urano-Protocol-Version': '1',
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type SocialTransport = 'sse' | 'wait' | 'ws' | 'async';
+export type WebhookAction = 'status' | 'events' | 'cancel';
+export interface SocialProxyConfig {
+    webhookUrl: string;
+    webhookSecret: string;
+    /** Secret used to sign the HttpOnly visitor cookie. Defaults to webhookSecret. */
+    cookieSecret?: string;
+    cookieName?: string;
+    cookieMaxAgeSec?: number;
+    /** Default display name forwarded as displayName when the client omits one. */
+    defaultDisplayName?: string;
+}
+export interface SocialClientMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    streaming?: boolean;
+    turnId?: string;
+    createdAt: number;
+}
+export interface SocialChatEvent {
+    type: string;
+    version?: number;
+    id?: string;
+    sequence?: number;
+    turnId?: string;
+    requestId?: string;
+    sessionId?: string;
+    chunk?: string;
+    response?: string;
+    agentId?: string;
+    toolsUsed?: string[];
+    error?: string;
+    status?: number;
+    [key: string]: unknown;
+}
+export interface SocialSendOptions {
+    text: string;
+    displayName?: string;
+    mode?: 'sse' | 'wait';
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface SocialControlOptions {
+    action: WebhookAction;
+    turnId: string;
+    after?: string;
+    signal?: AbortSignal;
+}
+export interface CreateUranoChatOptions {
+    /** Site proxy endpoint, default `/api/urano-social`. */
+    endpoint?: string;
+    sessionId?: string | null;
+    displayName?: string;
+    preferredTransport?: 'auto' | 'sse' | 'wait' | 'ws';
+    onEvent?: (event: SocialChatEvent) => void;
+    onMessages?: (messages: SocialClientMessage[]) => void;
+    onError?: (error: Error) => void;
+    onStatus?: (status: {
+        connected: boolean;
+        streaming: boolean;
+        sessionId: string | null;
+    }) => void;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@uranotools/urano-social",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Customer-support chat widget for SalesAgentConnector MCP webhooks (SSE / WebSocket / wait)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.cjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "publish:npm": "npm publish --access public"
+  },
+  "keywords": [
+    "urano",
+    "chat",
+    "customer-support",
+    "sse",
+    "websocket",
+    "salesagent",
+    "astro",
+    "nextjs"
+  ],
+  "author": "Urano Open Source",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./flavors.css": "./dist/flavors/styles.css"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uranotools/urano-social.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uranotools/urano-social/issues"
+  },
+  "homepage": "https://github.com/uranotools/urano-social#readme"
+}