@uranotools/urano-social 0.0.0-stage → 0.3.0

package/.env.example

@@ -0,0 +1,22 @@
+# 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=
+
+# --- Contact anti-spam (on by default) ---
+# Ticket + honeypot + rate limit always run for type=contact.
+# URANO_SOCIAL_ANTISPAM=true
+# URANO_SOCIAL_CONTACT_MAX_PER_HOUR=5
+# URANO_SOCIAL_CONTACT_MIN_AGE_MS=2500
+
+# Optional Google reCAPTCHA v3 — paste secret here; site key goes in the frontend.
+# https://www.google.com/recaptcha/admin
+# URANO_SOCIAL_RECAPTCHA_SECRET=
+# URANO_SOCIAL_RECAPTCHA_MIN_SCORE=0.5
+# URANO_SOCIAL_RECAPTCHA_ACTION=contact
+#
+# Frontend (public):
+# NEXT_PUBLIC_URANO_SOCIAL_RECAPTCHA_SITE_KEY=
+# VITE_URANO_SOCIAL_RECAPTCHA_SITE_KEY=

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,213 @@
-# 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 soporte y formularios de contacto** para tu sitio, conectados a un agente Urano (Desktop o Cloud) — sin exponer secretos al navegador.
+
+[![npm](https://img.shields.io/npm/v/@uranotools/urano-social.svg)](https://www.npmjs.com/package/@uranotools/urano-social)
+[![license](https://img.shields.io/npm/l/@uranotools/urano-social.svg)](./LICENSE)
+
+Tu visitante habla con un widget o envía un formulario. Tu servidor firma la petición. El agente responde en tiempo real (chat) o por correo (contacto).
+
+---
+
+## Por qué usarlo
+
+| Ventaja | Qué significa |
+|---------|----------------|
+| **Secreto fuera del browser** | El `WEBHOOK_SECRET` vive solo en tu servidor. El front solo llama a `/api/urano-social`. |
+| **Tu agente, tu marca** | Conecta el SalesAgentConnector de Urano; el tono y las herramientas los defines tú. |
+| **Chat + contacto** | Un mismo proxy sirve burbuja de chat (SSE / wait / WebSocket) y formularios SMTP. |
+| **Anti-spam de verdad** | Honeypot, ticket firmado y rate limit incluidos. reCAPTCHA v3 opcional — pegas las keys y listo. |
+| **UI a tu medida** | Flavors listos (`floating`, `sidebar`) o headless / slots para tu diseño. |
+| **Next, Astro, Vite…** | Proxy Web-standard; funciona en App Router, edge/Node y Cloudflare Pages Functions. |
+
+Sin esto, un formulario “a pelo” apuntando a un agente es un blanco fácil para quemar tokens de IA. El proxy corta bots **antes** de llamar al webhook.
+
+---
+
+## Instalar
+
+```bash
+npm install @uranotools/urano-social
+```
+
+Requisitos:
+
+1. **Urano Desktop o Cloud** con el plugin **SalesAgentConnector** (1.4.0+).
+2. En el vault del plugin: `WEBHOOK_SECRET`, `TARGET_AGENT` (y SMTP + `ENABLE_EMAIL_CONTACT=true` si usas formularios).
+3. Un endpoint en tu sitio que use el proxy de este paquete.
+
+---
+
+## Cómo encaja
+
+```
+Visitante  →  tu sitio (/api/urano-social)  →  firma HMAC  →  webhook Urano  →  agente
+                 ↑
+            cookie HttpOnly
+            anti-spam (contacto)
+```
+
+El browser **nunca** recibe el secreto. Tú configuras dos variables de servidor:
+
+```env
+URANO_SOCIAL_WEBHOOK_URL=https://tu-host/v1/webhook/mcp_SalesAgentConnector/default
+URANO_SOCIAL_WEBHOOK_SECRET=el-mismo-del-vault
+```
+
+Local (Desktop):
+
+```env
+URANO_SOCIAL_WEBHOOK_URL=http://127.0.0.1:6274/v1/webhook/mcp_SalesAgentConnector/default
+URANO_SOCIAL_WEBHOOK_SECRET=…
+```
+
+No uses prefijos `NEXT_PUBLIC_` / `VITE_` / `PUBLIC_` para el secreto.
+
+---
+
+## Arranque en 3 pasos
+
+### 1. 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 / edge**
+
+```ts
+import { createSocialProxy } from '@uranotools/urano-social/server';
+
+const proxy = createSocialProxy();
+// return proxy.handle(request)
+```
+
+### 2. Widget de chat
+
+**HTML / Astro (custom element)**
+
+```html
+<script type="module">
+  import { registerUranoSocialChat } from '@uranotools/urano-social';
+  registerUranoSocialChat();
+</script>
+<urano-social-chat flavor="floating" title="Soporte"></urano-social-chat>
+```
+
+**React**
+
+```tsx
+import { UranoSocialChat } from '@uranotools/urano-social/react';
+import '@uranotools/urano-social/flavors.css';
+
+export function SupportWidget() {
+  return <UranoSocialChat flavor="floating" title="Soporte" />;
+}
+```
+
+**Headless** (tu propia UI)
+
+```ts
+import { createUranoChat } from '@uranotools/urano-social/client';
+
+const chat = createUranoChat({ endpoint: '/api/urano-social' });
+await chat.send('Hola, necesito ayuda');
+```
+
+### 3. Formulario de contacto (opcional)
+
+El agente recibe el mensaje y puede responder por SMTP.
+
+```tsx
+import { UranoSocialContactForm } from '@uranotools/urano-social/react';
+
+<UranoSocialContactForm
+  title="Escríbenos"
+  recaptchaSiteKey={import.meta.env.VITE_URANO_SOCIAL_RECAPTCHA_SITE_KEY}
+/>
+```
+
+O solo la API:
+
+```ts
+import { submitContactForm } from '@uranotools/urano-social/client';
+
+await submitContactForm({
+  email: 'ana@empresa.com',
+  name: 'Ana',
+  message: 'Quiero una demo',
+});
+```
+
+---
+
+## Flavors de chat
+
+| Flavor | Ideal para |
+|--------|------------|
+| `floating` | Burbuja fija en la esquina (soporte clásico) |
+| `sidebar` | Panel lateral en product / docs |
+| `headless` | Diseño 100 % tuyo; solo el controlador |
+
+Slots del custom element: `header`, `messages`, `composer`, `launcher`, `empty`.
+
+---
+
+## Anti-spam en formularios
+
+Incluido de fábrica:
+
+- **Honeypot** — si un bot llena el campo oculto, responde 200 falso y **no** llama a la IA  
+- **Ticket firmado** — edad mínima / máxima entre abrir el form y enviar  
+- **Rate limit** — por defecto 5 envíos / hora por visitante + IP  
+
+Opcional — **reCAPTCHA v3** (solo pegar keys):
+
+```env
+# Servidor
+URANO_SOCIAL_RECAPTCHA_SECRET=tu_secret_de_google
+
+# Front (público)
+VITE_URANO_SOCIAL_RECAPTCHA_SITE_KEY=tu_site_key
+# o NEXT_PUBLIC_URANO_SOCIAL_RECAPTCHA_SITE_KEY=
+```
+
+Con el secret configurado, el proxy exige y verifica el token **antes** del webhook.
+
+---
+
+## Seguridad (resumen)
+
+- Cookie **HttpOnly** firmada: el visitante no elige su `visitorId` CRM  
+- Firma **HMAC** (`x-urano-signature`) solo en el proxy  
+- Controles de turno: `status` / `events` / `cancel` + `Idempotency-Key`  
+- Contacto filtrado antes de gastar tokens del agente  
+
+---
+
+## Ejemplos
+
+- [`examples/next`](examples/next) — formulario de contacto + proxy  
+- [`examples/astro`](examples/astro) — misma idea en Astro  
+
+```bash
+cd examples/next
+cp .env.example .env   # pon URL + secreto del plugin
+npm install
+npm run dev            # http://localhost:3011
+```
+
+---
+
+## Enlaces
+
+- npm: [npmjs.com/package/@uranotools/urano-social](https://www.npmjs.com/package/@uranotools/urano-social)  
+- UranoAI: [uranoai.com](https://uranoai.com)  
+- Org: [github.com/uranotools](https://github.com/uranotools)  
+
+MIT © Urano Open Source

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,223 @@
+import { readSseStream } from './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.
+ */
+export 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 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 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,6 @@
+export { createUranoChat } from './createUranoChat';
+export type { UranoChat } from './createUranoChat';
+export { readSseStream, parseSseChunk } from './sse';
+export { submitContactForm, fetchContactTicket } from './submitContactForm';
+export type { ContactFormPayload, ContactFormResult, ContactTicketResponse, SubmitContactFormOptions, } from './submitContactForm';
+export { loadRecaptchaV3, executeRecaptchaV3 } from './recaptcha';

package/dist/client/index.js

@@ -0,0 +1,4 @@
+export { createUranoChat } from './createUranoChat';
+export { readSseStream, parseSseChunk } from './sse';
+export { submitContactForm, fetchContactTicket } from './submitContactForm';
+export { loadRecaptchaV3, executeRecaptchaV3 } from './recaptcha';

package/dist/client/recaptcha.d.ts

@@ -0,0 +1,14 @@
+declare global {
+    interface Window {
+        grecaptcha?: {
+            ready: (cb: () => void) => void;
+            execute: (siteKey: string, opts: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+/** Loads the reCAPTCHA v3 script once (browser only). */
+export declare function loadRecaptchaV3(siteKey: string): Promise<void>;
+/** Executes reCAPTCHA v3 and returns a short-lived token for the proxy. */
+export declare function executeRecaptchaV3(siteKey: string, action?: string): Promise<string>;

package/dist/client/recaptcha.js

@@ -0,0 +1,36 @@
+const SCRIPT_ID = 'uranotools-recaptcha-v3';
+/** Loads the reCAPTCHA v3 script once (browser only). */
+export function loadRecaptchaV3(siteKey) {
+    if (typeof window === 'undefined') {
+        return Promise.reject(new Error('recaptcha_browser_only'));
+    }
+    if (!siteKey)
+        return Promise.reject(new Error('recaptcha_site_key_required'));
+    if (window.grecaptcha) {
+        return new Promise((resolve) => window.grecaptcha.ready(() => resolve()));
+    }
+    const existing = document.getElementById(SCRIPT_ID);
+    if (existing) {
+        return new Promise((resolve, reject) => {
+            existing.addEventListener('load', () => window.grecaptcha.ready(() => resolve()));
+            existing.addEventListener('error', () => reject(new Error('recaptcha_script_failed')));
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.id = SCRIPT_ID;
+        script.src = `https://www.google.com/recaptcha/api.js?render=${encodeURIComponent(siteKey)}`;
+        script.async = true;
+        script.onload = () => window.grecaptcha.ready(() => resolve());
+        script.onerror = () => reject(new Error('recaptcha_script_failed'));
+        document.head.appendChild(script);
+    });
+}
+/** Executes reCAPTCHA v3 and returns a short-lived token for the proxy. */
+export async function executeRecaptchaV3(siteKey, action = 'contact') {
+    await loadRecaptchaV3(siteKey);
+    const token = await window.grecaptcha.execute(siteKey, { action });
+    if (!token)
+        throw new Error('recaptcha_empty_token');
+    return token;
+}

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,104 @@
+export 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 */ }
+    }
+}
+export 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;
+}