@uranotools/urano-social 0.2.0 → 0.3.0

package/.env.example

@@ -4,3 +4,19 @@ URANO_SOCIAL_WEBHOOK_SECRET=replace-with-the-same-WEBHOOK_SECRET-from-the-plugin
 
 # 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/README.md

@@ -1,33 +1,75 @@
 # @uranotools/urano-social
 
-Chat de atención al cliente para el webhook MCP de **SalesAgentConnector**.
+**Chat de soporte y formularios de contacto** para tu sitio, conectados a un agente Urano (Desktop o Cloud) — sin exponer secretos al navegador.
 
-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.
+[![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)
 
-## Arranque rápido
+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).
 
-### 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:
+## 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
 
 ```
-http://127.0.0.1:6274/v1/webhook/mcp_SalesAgentConnector/default
+Visitante  →  tu sitio (/api/urano-social)  →  firma HMAC  →  webhook Urano  →  agente
+                 ↑
+            cookie HttpOnly
+            anti-spam (contacto)
 ```
 
-### 2. Variables de entorno (servidor)
+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=el-mismo-secreto-del-vault
+URANO_SOCIAL_WEBHOOK_SECRET=…
 ```
 
-Nunca uses prefijos `NEXT_PUBLIC_` / `PUBLIC_` para el secreto.
+No uses prefijos `NEXT_PUBLIC_` / `VITE_` / `PUBLIC_` para el secreto.
+
+---
+
+## Arranque en 3 pasos
 
-### 3. Proxy en tu app
+### 1. Proxy en tu app
 
-**Next.js App Router**
+**Next.js (App Router)**
 
 ```ts
 // app/api/urano-social/route.ts
@@ -36,17 +78,18 @@ import { socialProxyRoute } from '@uranotools/urano-social/server';
 export const { GET, POST, OPTIONS } = socialProxyRoute();
 ```
 
-**Astro / Node**
+**Astro / Node / edge**
 
 ```ts
 import { createSocialProxy } from '@uranotools/urano-social/server';
+
 const proxy = createSocialProxy();
-// en tu handler: return proxy.handle(request)
+// return proxy.handle(request)
 ```
 
-### 4. Widget
+### 2. Widget de chat
 
-**Custom element (Astro / HTML / TS)**
+**HTML / Astro (custom element)**
 
 ```html
 <script type="module">
@@ -56,138 +99,115 @@ const proxy = createSocialProxy();
 <urano-social-chat flavor="floating" title="Soporte"></urano-social-chat>
 ```
 
-Slots: `header`, `messages`, `composer`, `launcher`, `empty`.
-
-**React / Next**
+**React**
 
 ```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>}
-    />
-  );
+  return <UranoSocialChat flavor="floating" title="Soporte" />;
 }
 ```
 
-**Headless**
+**Headless** (tu propia UI)
 
 ```ts
 import { createUranoChat } from '@uranotools/urano-social/client';
 
 const chat = createUranoChat({ endpoint: '/api/urano-social' });
-await chat.send('Hola');
+await chat.send('Hola, necesito ayuda');
 ```
 
-## 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.
+### 3. Formulario de contacto (opcional)
 
-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>
-```
+El agente recibe el mensaje y puede responder por SMTP.
 
 ```tsx
 import { UranoSocialContactForm } from '@uranotools/urano-social/react';
-<UranoSocialContactForm title="Escríbenos" />
+
+<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: 'a@b.co', name: 'Ana', message: 'Hola' });
+
+await submitContactForm({
+  email: 'ana@empresa.com',
+  name: 'Ana',
+  message: 'Quiero una demo',
+});
 ```
 
-## Flavors
+---
 
-| Flavor | Uso |
-|--------|-----|
-| `floating` | Burbuja fija + panel |
-| `sidebar` | Columna lateral |
-| `headless` | Solo controlador / React con UI propia |
+## Flavors de chat
 
-## Seguridad
+| 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 |
 
-- 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.
+Slots del custom element: `header`, `messages`, `composer`, `launcher`, `empty`.
 
-## WebSocket
+---
 
-Next App Router usa SSE por defecto. En Astro Node o un `http.Server` propio:
+## Anti-spam en formularios
 
-```ts
-import http from 'http';
-import { attachSocialWebSocket } from '@uranotools/urano-social/server';
+Incluido de fábrica:
 
-const server = http.createServer(app);
-attachSocialWebSocket(server); // path /api/urano-social/ws
-```
+- **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  
 
-## Desarrollo
+Opcional — **reCAPTCHA v3** (solo pegar keys):
 
-```bash
-cd UranoDesktop-demos/urano-social
-npm install
-npm test
-npm run build
-```
+```env
+# Servidor
+URANO_SOCIAL_RECAPTCHA_SECRET=tu_secret_de_google
 
-Ejemplos: [`examples/next`](examples/next), [`examples/astro`](examples/astro).
+# Front (público)
+VITE_URANO_SOCIAL_RECAPTCHA_SITE_KEY=tu_site_key
+# o NEXT_PUBLIC_URANO_SOCIAL_RECAPTCHA_SITE_KEY=
+```
 
-## Publicar en npm (`@uranotools/urano-social`)
+Con el secret configurado, el proxy exige y verifica el token **antes** del webhook.
 
-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
-```
+## Seguridad (resumen)
 
-Tras publicar:
+- 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  
 
-```bash
-npm install @uranotools/urano-social
-```
+---
 
-Subidas siguientes: sube `version` en `package.json` (`0.1.1`, `0.2.0`, …) y vuelve a `npm publish`.
+## Ejemplos
 
-Dry-run sin subir nada:
+- [`examples/next`](examples/next) — formulario de contacto + proxy  
+- [`examples/astro`](examples/astro) — misma idea en Astro  
 
 ```bash
-npm publish --dry-run
+cd examples/next
+cp .env.example .env   # pon URL + secreto del plugin
+npm install
+npm run dev            # http://localhost:3011
 ```
 
-### 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
-```
+## Enlaces
 
-El job hace `npm ci` → typecheck → test → build → `npm publish --access public`.
+- 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)  
 
-Nota: `--provenance` solo funciona si el repo de GitHub es **público**. Con repo privado se publica sin provenance.
+MIT © Urano Open Source

package/dist/client/createUranoChat.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUranoChat = createUranoChat;
-const sse_1 = require("./sse");
+import { readSseStream } from './sse';
 function newMessageId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -9,7 +6,7 @@ function newMessageId(prefix) {
  * Headless chat controller. Talks only to the site proxy (`/api/urano-social`).
  * Never receives or sends the webhook secret.
  */
-function createUranoChat(options = {}) {
+export function createUranoChat(options = {}) {
     const endpoint = (options.endpoint || '/api/urano-social').replace(/\/$/, '');
     let sessionId = options.sessionId ?? null;
     let displayName = options.displayName || '';
@@ -85,7 +82,7 @@ function createUranoChat(options = {}) {
         }
         const contentType = response.headers.get('Content-Type') || '';
         if (contentType.includes('text/event-stream')) {
-            for await (const evt of (0, sse_1.readSseStream)(response, signal)) {
+            for await (const evt of readSseStream(response, signal)) {
                 applyEvent(evt, assistant);
             }
         }
@@ -199,7 +196,7 @@ function createUranoChat(options = {}) {
                     body: JSON.stringify(body),
                     signal: controlOpts.signal,
                 });
-                return (0, sse_1.readSseStream)(response, controlOpts.signal);
+                return readSseStream(response, controlOpts.signal);
             }
             return fetch(`${endpoint}?mode=wait`, {
                 method: 'POST',

package/dist/client/index.d.ts

@@ -1,5 +1,6 @@
 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';
+export { submitContactForm, fetchContactTicket } from './submitContactForm';
+export type { ContactFormPayload, ContactFormResult, ContactTicketResponse, SubmitContactFormOptions, } from './submitContactForm';
+export { loadRecaptchaV3, executeRecaptchaV3 } from './recaptcha';

package/dist/client/index.js

@@ -1,10 +1,4 @@
-"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; } });
+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.js

@@ -1,8 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.readSseStream = readSseStream;
-exports.parseSseChunk = parseSseChunk;
-async function* readSseStream(response, signal) {
+export async function* readSseStream(response, signal) {
     if (!response.body) {
         throw new Error('missing_response_body');
     }
@@ -73,7 +69,7 @@ async function* readSseStream(response, signal) {
         catch { /* ignore */ }
     }
 }
-function parseSseChunk(chunk) {
+export function parseSseChunk(chunk) {
     const events = [];
     let eventType = 'message';
     let dataLines = [];

package/dist/client/submitContactForm.d.ts

@@ -5,6 +5,15 @@ export interface ContactFormPayload {
     subject?: string;
     phone?: string;
     company?: string;
+    /**
+     * Honeypot value — must stay empty. Bots that fill it are silently dropped
+     * by the proxy (fake success, no AI call).
+     */
+    website?: string;
+    /** Signed ticket from GET ?action=contact-ticket (auto-fetched when omitted). */
+    contactTicket?: string;
+    /** reCAPTCHA v3 token (or pass `recaptchaSiteKey` in options to auto-execute). */
+    captchaToken?: string;
 }
 export interface ContactFormResult {
     ok: boolean;
@@ -16,15 +25,37 @@ export interface ContactFormResult {
     status: number;
     raw?: unknown;
 }
+export interface ContactTicketResponse {
+    ticket: string;
+    minAgeMs: number;
+    maxAgeMs: number;
+    honeypotField: string;
+    recaptchaRequired: boolean;
+    recaptchaAction: string;
+}
 export interface SubmitContactFormOptions {
     /** Site proxy endpoint. Default `/api/urano-social`. */
     endpoint?: string;
-    /** Prefer GET ?mode=wait&payload=… (default true). */
+    /**
+     * Prefer GET ?mode=wait&payload=…
+     * Default **false** (POST) so tickets / captcha tokens stay out of URLs and logs.
+     */
     useGet?: boolean;
     signal?: AbortSignal;
+    /** When set, loads grecaptcha and executes action `contact` before submit. */
+    recaptchaSiteKey?: string;
+    /** Override reCAPTCHA action (must match server). Default `contact`. */
+    recaptchaAction?: string;
+    /** Skip auto ticket fetch (tests / custom flows). */
+    skipTicket?: boolean;
 }
+/** Prefetch a signed contact ticket (call on form mount). */
+export declare function fetchContactTicket(endpoint?: string, signal?: AbortSignal): Promise<ContactTicketResponse>;
 /**
  * Submits a contact form through the site proxy.
- * Default transport is GET + mode=wait (signed upstream by the server).
+ * Default transport is POST + mode=wait (signed upstream by the server).
+ *
+ * Prefer calling `fetchContactTicket` when the form mounts so humans don't
+ * wait the min-age delay at submit time.
  */
 export declare function submitContactForm(input: ContactFormPayload, options?: SubmitContactFormOptions): Promise<ContactFormResult>;

package/dist/client/submitContactForm.js

@@ -1,17 +1,82 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.submitContactForm = submitContactForm;
+import { executeRecaptchaV3 } from './recaptcha';
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+/** Prefetch a signed contact ticket (call on form mount). */
+export async function fetchContactTicket(endpoint = '/api/urano-social', signal) {
+    const base = endpoint.replace(/\/$/, '');
+    const res = await fetch(`${base}?action=contact-ticket`, {
+        method: 'GET',
+        credentials: 'include',
+        signal,
+        headers: { Accept: 'application/json' },
+    });
+    const raw = await res.json().catch(() => ({}));
+    if (!res.ok || !raw?.ticket) {
+        throw new Error(String(raw?.error || 'contact_ticket_failed'));
+    }
+    const minAgeMs = Number(raw.minAgeMs);
+    const maxAgeMs = Number(raw.maxAgeMs);
+    return {
+        ticket: String(raw.ticket),
+        minAgeMs: Number.isFinite(minAgeMs) ? minAgeMs : 2500,
+        maxAgeMs: Number.isFinite(maxAgeMs) ? maxAgeMs : 30 * 60 * 1000,
+        honeypotField: String(raw.honeypotField || 'website'),
+        recaptchaRequired: Boolean(raw.recaptchaRequired),
+        recaptchaAction: String(raw.recaptchaAction || 'contact'),
+    };
+}
 /**
  * Submits a contact form through the site proxy.
- * Default transport is GET + mode=wait (signed upstream by the server).
+ * Default transport is POST + mode=wait (signed upstream by the server).
+ *
+ * Prefer calling `fetchContactTicket` when the form mounts so humans don't
+ * wait the min-age delay at submit time.
  */
-async function submitContactForm(input, options = {}) {
+export async function submitContactForm(input, options = {}) {
     const endpoint = (options.endpoint || '/api/urano-social').replace(/\/$/, '');
     const email = String(input.email || '').trim();
     const message = String(input.message || '').trim();
     if (!email || !message) {
         return { ok: false, status: 400, error: 'email_and_message_required' };
     }
+    let contactTicket = input.contactTicket;
+    if (!contactTicket && !options.skipTicket) {
+        try {
+            const issued = await fetchContactTicket(endpoint, options.signal);
+            contactTicket = issued.ticket;
+            // Ticket was just minted — wait min age before POST (bot / headless path).
+            await sleep(issued.minAgeMs, options.signal);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                status: 403,
+                error: error?.message || 'contact_ticket_failed',
+            };
+        }
+    }
+    let captchaToken = input.captchaToken;
+    if (!captchaToken && options.recaptchaSiteKey) {
+        try {
+            captchaToken = await executeRecaptchaV3(options.recaptchaSiteKey, options.recaptchaAction || 'contact');
+        }
+        catch (error) {
+            return {
+                ok: false,
+                status: 403,
+                error: error?.message || 'recaptcha_failed',
+            };
+        }
+    }
     const payload = {
         type: 'contact',
         email,
@@ -20,8 +85,11 @@ async function submitContactForm(input, options = {}) {
         message,
         phone: input.phone || undefined,
         company: input.company || undefined,
+        website: input.website ?? '',
+        contactTicket,
+        captchaToken: captchaToken || undefined,
     };
-    const useGet = options.useGet !== false;
+    const useGet = options.useGet === true;
     let response;
     if (useGet) {
         const url = `${endpoint}?mode=wait&payload=${encodeURIComponent(JSON.stringify(payload))}`;