@uranotools/urano-social 0.0.0-stage → 0.2.0

package/.env.example

@@ -0,0 +1,6 @@
+# Server-only — never use NEXT_PUBLIC_ / PUBLIC_ prefixes.
+URANO_SOCIAL_WEBHOOK_URL=http://127.0.0.1:6274/v1/webhook/mcp_SalesAgentConnector/default
+URANO_SOCIAL_WEBHOOK_SECRET=replace-with-the-same-WEBHOOK_SECRET-from-the-plugin-vault
+
+# Optional: separate secret for signing the visitor cookie (defaults to WEBHOOK_SECRET).
+# URANO_SOCIAL_COOKIE_SECRET=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Urano Open Source
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# @uranotools/urano-social
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chat de atención al cliente para el webhook MCP de **SalesAgentConnector**.
+
+El secreto HMAC vive solo en el servidor del sitio. El navegador habla con `/api/urano-social`; el proxy firma y reenvía a Urano (Desktop o Cloud) por SSE, wait o WebSocket.
+
+## Arranque rápido
+
+### 1. Plugin + agente
+
+1. Instala SalesAgentConnector **1.4.0+** en Urano Desktop / Cloud.
+2. Vault: `WEBHOOK_SECRET` + `TARGET_AGENT` (agente lanzado con el módulo activo).
+3. URL local:
+
+```
+http://127.0.0.1:6274/v1/webhook/mcp_SalesAgentConnector/default
+```
+
+### 2. Variables de entorno (servidor)
+
+```env
+URANO_SOCIAL_WEBHOOK_URL=http://127.0.0.1:6274/v1/webhook/mcp_SalesAgentConnector/default
+URANO_SOCIAL_WEBHOOK_SECRET=el-mismo-secreto-del-vault
+```
+
+Nunca uses prefijos `NEXT_PUBLIC_` / `PUBLIC_` para el secreto.
+
+### 3. Proxy en tu app
+
+**Next.js App Router**
+
+```ts
+// app/api/urano-social/route.ts
+import { socialProxyRoute } from '@uranotools/urano-social/server';
+
+export const { GET, POST, OPTIONS } = socialProxyRoute();
+```
+
+**Astro / Node**
+
+```ts
+import { createSocialProxy } from '@uranotools/urano-social/server';
+const proxy = createSocialProxy();
+// en tu handler: return proxy.handle(request)
+```
+
+### 4. Widget
+
+**Custom element (Astro / HTML / TS)**
+
+```html
+<script type="module">
+  import { registerUranoSocialChat } from '@uranotools/urano-social';
+  registerUranoSocialChat();
+</script>
+<urano-social-chat flavor="floating" title="Soporte"></urano-social-chat>
+```
+
+Slots: `header`, `messages`, `composer`, `launcher`, `empty`.
+
+**React / Next**
+
+```tsx
+import { UranoSocialChat } from '@uranotools/urano-social/react';
+import '@uranotools/urano-social/flavors.css';
+
+export function SupportWidget() {
+  return (
+    <UranoSocialChat
+      flavor="floating"
+      renderMessage={(m) => <div data-role={m.role}>{m.content}</div>}
+    />
+  );
+}
+```
+
+**Headless**
+
+```ts
+import { createUranoChat } from '@uranotools/urano-social/client';
+
+const chat = createUranoChat({ endpoint: '/api/urano-social' });
+await chat.send('Hola');
+```
+
+## Formularios de contacto (GET + SMTP)
+
+Mismo proxy y secreto. El widget envía `type=contact` por **GET** `?mode=wait&payload=…`. El plugin responde con el agente y manda el correo por SMTP.
+
+Requisito en Vault del plugin: `ENABLE_EMAIL_CONTACT=true` + SMTP.
+
+```html
+<script type="module">
+  import { registerUranoSocialContactForm } from '@uranotools/urano-social';
+  registerUranoSocialContactForm();
+</script>
+<urano-social-contact title="Escríbenos"></urano-social-contact>
+```
+
+```tsx
+import { UranoSocialContactForm } from '@uranotools/urano-social/react';
+<UranoSocialContactForm title="Escríbenos" />
+```
+
+```ts
+import { submitContactForm } from '@uranotools/urano-social/client';
+await submitContactForm({ email: 'a@b.co', name: 'Ana', message: 'Hola' });
+```
+
+## Flavors
+
+| Flavor | Uso |
+|--------|-----|
+| `floating` | Burbuja fija + panel |
+| `sidebar` | Columna lateral |
+| `headless` | Solo controlador / React con UI propia |
+
+## Seguridad
+
+- Cookie HttpOnly firmada con el `visitorId` (el browser no elige la identidad CRM).
+- Firma `x-urano-signature` (HMAC-SHA256 hex) solo en el proxy.
+- Controles `status` / `events` / `cancel` e `Idempotency-Key` para reanudar turnos.
+
+## WebSocket
+
+Next App Router usa SSE por defecto. En Astro Node o un `http.Server` propio:
+
+```ts
+import http from 'http';
+import { attachSocialWebSocket } from '@uranotools/urano-social/server';
+
+const server = http.createServer(app);
+attachSocialWebSocket(server); // path /api/urano-social/ws
+```
+
+## Desarrollo
+
+```bash
+cd UranoDesktop-demos/urano-social
+npm install
+npm test
+npm run build
+```
+
+Ejemplos: [`examples/next`](examples/next), [`examples/astro`](examples/astro).
+
+## Publicar en npm (`@uranotools/urano-social`)
+
+Igual que `@uranotools/urano-guard`: scope de la org **uranotools**, acceso **public**.
+
+```bash
+# 1. Cuenta con permiso en la org (una sola vez)
+npm login
+# Si el scope es nuevo en la org: npm org invite <user> --org=uranotools
+
+# 2. Desde esta carpeta
+npm test
+npm run build
+npm publish --access public
+# o: npm run publish:npm
+```
+
+Tras publicar:
+
+```bash
+npm install @uranotools/urano-social
+```
+
+Subidas siguientes: sube `version` en `package.json` (`0.1.1`, `0.2.0`, …) y vuelve a `npm publish`.
+
+Dry-run sin subir nada:
+
+```bash
+npm publish --dry-run
+```
+
+### GitHub Actions (igual que urano-guard)
+
+1. Secret del repo: **`NPM_TOKEN`** (Settings → Secrets and variables → Actions).  
+   Debe ser un [Automation token](https://www.npmjs.com/settings/~/tokens) con permiso de publish en la org `uranotools`.
+2. Workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml) — corre en **Release** o manualmente (`workflow_dispatch`).
+3. Publicar una versión:
+
+```bash
+# sube version en package.json, commit, push
+git tag v0.2.0
+git push origin v0.2.0
+# Luego en GitHub → Releases → Create release from tag v0.2.0
+```
+
+El job hace `npm ci` → typecheck → test → build → `npm publish --access public`.
+
+Nota: `--provenance` solo funciona si el repo de GitHub es **público**. Con repo privado se publica sin provenance.

package/dist/client/createUranoChat.d.ts

@@ -0,0 +1,16 @@
+import type { CreateUranoChatOptions, SocialChatEvent, SocialClientMessage, SocialControlOptions, SocialSendOptions } from '../types';
+export interface UranoChat {
+    readonly sessionId: string | null;
+    readonly messages: SocialClientMessage[];
+    readonly streaming: boolean;
+    send(options: SocialSendOptions | string): Promise<SocialClientMessage>;
+    control(options: SocialControlOptions): Promise<Response | AsyncGenerator<SocialChatEvent>>;
+    cancel(turnId: string): Promise<void>;
+    setDisplayName(name: string): void;
+    destroy(): void;
+}
+/**
+ * Headless chat controller. Talks only to the site proxy (`/api/urano-social`).
+ * Never receives or sends the webhook secret.
+ */
+export declare function createUranoChat(options?: CreateUranoChatOptions): UranoChat;

package/dist/client/createUranoChat.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUranoChat = createUranoChat;
+const sse_1 = require("./sse");
+function newMessageId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Headless chat controller. Talks only to the site proxy (`/api/urano-social`).
+ * Never receives or sends the webhook secret.
+ */
+function createUranoChat(options = {}) {
+    const endpoint = (options.endpoint || '/api/urano-social').replace(/\/$/, '');
+    let sessionId = options.sessionId ?? null;
+    let displayName = options.displayName || '';
+    let streaming = false;
+    let destroyed = false;
+    const messages = [];
+    let abort = null;
+    const emitMessages = () => options.onMessages?.(messages.slice());
+    const emitStatus = () => options.onStatus?.({
+        connected: !destroyed,
+        streaming,
+        sessionId,
+    });
+    function applyEvent(evt, assistant) {
+        options.onEvent?.(evt);
+        if (evt.sessionId)
+            sessionId = String(evt.sessionId);
+        if (evt.type === 'session' && evt.sessionId)
+            sessionId = String(evt.sessionId);
+        if (evt.type === 'TokenStreamChunk' && typeof evt.chunk === 'string') {
+            assistant.content += evt.chunk;
+            assistant.streaming = true;
+            emitMessages();
+        }
+        if (evt.type === 'done') {
+            if (typeof evt.response === 'string' && evt.response && !assistant.content) {
+                assistant.content = evt.response;
+            }
+            assistant.streaming = false;
+            if (evt.turnId)
+                assistant.turnId = String(evt.turnId);
+            emitMessages();
+        }
+        if (evt.type === 'error') {
+            assistant.streaming = false;
+            if (!assistant.content)
+                assistant.content = String(evt.error || 'error');
+            options.onError?.(new Error(String(evt.error || 'stream_error')));
+            emitMessages();
+        }
+    }
+    async function sendViaSse(text, idempotencyKey, signal) {
+        const assistant = {
+            id: newMessageId('a'),
+            role: 'assistant',
+            content: '',
+            streaming: true,
+            createdAt: Date.now(),
+        };
+        messages.push(assistant);
+        emitMessages();
+        const body = JSON.stringify({
+            text,
+            sessionId: sessionId || undefined,
+            displayName: displayName || undefined,
+        });
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
+        };
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        const response = await fetch(`${endpoint}?mode=sse`, {
+            method: 'POST',
+            headers,
+            body,
+            credentials: 'include',
+            signal,
+        });
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(errText || `http_${response.status}`);
+        }
+        const contentType = response.headers.get('Content-Type') || '';
+        if (contentType.includes('text/event-stream')) {
+            for await (const evt of (0, sse_1.readSseStream)(response, signal)) {
+                applyEvent(evt, assistant);
+            }
+        }
+        else {
+            const json = await response.json();
+            if (json.sessionId)
+                sessionId = String(json.sessionId);
+            assistant.content = String(json.text || json.response || '');
+            assistant.streaming = false;
+            assistant.turnId = json.turnId ? String(json.turnId) : undefined;
+            emitMessages();
+        }
+        assistant.streaming = false;
+        emitMessages();
+    }
+    async function sendViaWait(text, idempotencyKey, signal) {
+        const assistant = {
+            id: newMessageId('a'),
+            role: 'assistant',
+            content: '',
+            streaming: true,
+            createdAt: Date.now(),
+        };
+        messages.push(assistant);
+        emitMessages();
+        const headers = { 'Content-Type': 'application/json' };
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        const response = await fetch(`${endpoint}?mode=wait`, {
+            method: 'POST',
+            headers,
+            credentials: 'include',
+            signal,
+            body: JSON.stringify({
+                text,
+                sessionId: sessionId || undefined,
+                displayName: displayName || undefined,
+            }),
+        });
+        const json = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            throw new Error(json.error || `http_${response.status}`);
+        }
+        if (json.sessionId)
+            sessionId = String(json.sessionId);
+        assistant.content = String(json.text || json.response || '');
+        assistant.streaming = false;
+        assistant.turnId = json.turnId ? String(json.turnId) : undefined;
+        options.onEvent?.({ type: 'done', ...json });
+        emitMessages();
+    }
+    const api = {
+        get sessionId() { return sessionId; },
+        get messages() { return messages.slice(); },
+        get streaming() { return streaming; },
+        async send(input) {
+            if (destroyed)
+                throw new Error('destroyed');
+            const opts = typeof input === 'string' ? { text: input } : input;
+            const text = String(opts.text || '').trim();
+            if (!text)
+                throw new Error('empty_text');
+            messages.push({
+                id: newMessageId('u'),
+                role: 'user',
+                content: text,
+                createdAt: Date.now(),
+            });
+            emitMessages();
+            abort?.abort();
+            abort = new AbortController();
+            const signal = opts.signal || abort.signal;
+            streaming = true;
+            emitStatus();
+            try {
+                const mode = opts.mode
+                    || (options.preferredTransport === 'wait' ? 'wait' : 'sse');
+                if (mode === 'wait') {
+                    await sendViaWait(text, opts.idempotencyKey, signal);
+                }
+                else {
+                    await sendViaSse(text, opts.idempotencyKey, signal);
+                }
+                return messages[messages.length - 1];
+            }
+            catch (error) {
+                options.onError?.(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            finally {
+                streaming = false;
+                emitStatus();
+            }
+        },
+        async control(controlOpts) {
+            const body = {
+                webhookAction: controlOpts.action,
+                turnId: controlOpts.turnId,
+                sessionId: sessionId || undefined,
+                after: controlOpts.after,
+            };
+            if (controlOpts.action === 'events') {
+                const response = await fetch(`${endpoint}?mode=sse`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Accept: 'text/event-stream',
+                        ...(controlOpts.after ? { 'Last-Event-ID': controlOpts.after } : {}),
+                    },
+                    credentials: 'include',
+                    body: JSON.stringify(body),
+                    signal: controlOpts.signal,
+                });
+                return (0, sse_1.readSseStream)(response, controlOpts.signal);
+            }
+            return fetch(`${endpoint}?mode=wait`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'include',
+                body: JSON.stringify(body),
+                signal: controlOpts.signal,
+            });
+        },
+        async cancel(turnId) {
+            await api.control({ action: 'cancel', turnId });
+        },
+        setDisplayName(name) {
+            displayName = String(name || '');
+        },
+        destroy() {
+            destroyed = true;
+            abort?.abort();
+            emitStatus();
+        },
+    };
+    emitStatus();
+    return api;
+}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { createUranoChat } from './createUranoChat';
+export type { UranoChat } from './createUranoChat';
+export { readSseStream, parseSseChunk } from './sse';
+export { submitContactForm } from './submitContactForm';
+export type { ContactFormPayload, ContactFormResult, SubmitContactFormOptions } from './submitContactForm';

package/dist/client/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitContactForm = exports.parseSseChunk = exports.readSseStream = exports.createUranoChat = void 0;
+var createUranoChat_1 = require("./createUranoChat");
+Object.defineProperty(exports, "createUranoChat", { enumerable: true, get: function () { return createUranoChat_1.createUranoChat; } });
+var sse_1 = require("./sse");
+Object.defineProperty(exports, "readSseStream", { enumerable: true, get: function () { return sse_1.readSseStream; } });
+Object.defineProperty(exports, "parseSseChunk", { enumerable: true, get: function () { return sse_1.parseSseChunk; } });
+var submitContactForm_1 = require("./submitContactForm");
+Object.defineProperty(exports, "submitContactForm", { enumerable: true, get: function () { return submitContactForm_1.submitContactForm; } });

package/dist/client/sse.d.ts

@@ -0,0 +1,3 @@
+import type { SocialChatEvent } from '../types';
+export declare function readSseStream(response: Response, signal?: AbortSignal): AsyncGenerator<SocialChatEvent>;
+export declare function parseSseChunk(chunk: string): SocialChatEvent[];

package/dist/client/sse.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSseStream = readSseStream;
+exports.parseSseChunk = parseSseChunk;
+async function* readSseStream(response, signal) {
+    if (!response.body) {
+        throw new Error('missing_response_body');
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let eventType = 'message';
+    let dataLines = [];
+    const flush = () => {
+        if (!dataLines.length) {
+            eventType = 'message';
+            return null;
+        }
+        const raw = dataLines.join('\n');
+        dataLines = [];
+        const type = eventType;
+        eventType = 'message';
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object') {
+                return { type: parsed.type || type, ...parsed };
+            }
+        }
+        catch {
+            return { type, data: raw };
+        }
+        return { type, data: raw };
+    };
+    try {
+        while (true) {
+            if (signal?.aborted)
+                break;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let nl;
+            while ((nl = buffer.indexOf('\n')) >= 0) {
+                let line = buffer.slice(0, nl);
+                buffer = buffer.slice(nl + 1);
+                if (line.endsWith('\r'))
+                    line = line.slice(0, -1);
+                if (line === '') {
+                    const evt = flush();
+                    if (evt)
+                        yield evt;
+                    continue;
+                }
+                if (line.startsWith(':'))
+                    continue;
+                if (line.startsWith('event:')) {
+                    eventType = line.slice(6).trim();
+                    continue;
+                }
+                if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).trimStart());
+                }
+            }
+        }
+        const trailing = flush();
+        if (trailing)
+            yield trailing;
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch { /* ignore */ }
+    }
+}
+function parseSseChunk(chunk) {
+    const events = [];
+    let eventType = 'message';
+    let dataLines = [];
+    for (const rawLine of chunk.split(/\r?\n/)) {
+        const line = rawLine;
+        if (line === '') {
+            if (dataLines.length) {
+                const raw = dataLines.join('\n');
+                dataLines = [];
+                const type = eventType;
+                eventType = 'message';
+                try {
+                    const parsed = JSON.parse(raw);
+                    events.push({ type: parsed.type || type, ...parsed });
+                }
+                catch {
+                    events.push({ type, data: raw });
+                }
+            }
+            continue;
+        }
+        if (line.startsWith(':'))
+            continue;
+        if (line.startsWith('event:')) {
+            eventType = line.slice(6).trim();
+            continue;
+        }
+        if (line.startsWith('data:'))
+            dataLines.push(line.slice(5).trimStart());
+    }
+    return events;
+}

package/dist/client/submitContactForm.d.ts

@@ -0,0 +1,30 @@
+export interface ContactFormPayload {
+    name?: string;
+    email: string;
+    message: string;
+    subject?: string;
+    phone?: string;
+    company?: string;
+}
+export interface ContactFormResult {
+    ok: boolean;
+    text?: string;
+    sessionId?: string;
+    turnId?: string;
+    delivered?: string;
+    error?: string;
+    status: number;
+    raw?: unknown;
+}
+export interface SubmitContactFormOptions {
+    /** Site proxy endpoint. Default `/api/urano-social`. */
+    endpoint?: string;
+    /** Prefer GET ?mode=wait&payload=… (default true). */
+    useGet?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Submits a contact form through the site proxy.
+ * Default transport is GET + mode=wait (signed upstream by the server).
+ */
+export declare function submitContactForm(input: ContactFormPayload, options?: SubmitContactFormOptions): Promise<ContactFormResult>;