veo-sdk 0.1.0

package/CONTRACT.md

@@ -0,0 +1,144 @@
+# Contrato HTTP entre @veo/sdk y veo-backend
+
+Versión: **v1**
+
+Este documento es la fuente de verdad sobre el contrato HTTP. Cualquier
+cambio debe reflejarse simultáneamente en ambos repos.
+
+## Base URL
+
+- Producción: `https://api.veo.io`
+- Desarrollo: `http://localhost:3001`
+
+## Versionado
+
+Todos los endpoints viven bajo `/v1/`. Cambios incompatibles requieren
+nueva versión (`/v2/`).
+
+## Authentication
+
+Todos los endpoints requieren API key del workspace:
+
+- **Header:** `X-Api-Key: pk_xxx`
+- **O query param:** `?key=pk_xxx` (necesario para `navigator.sendBeacon`)
+
+Si la API key falta o es inválida: `401 Unauthorized`.
+
+## Headers comunes
+
+| Header | Requerido | Valor |
+|--------|-----------|-------|
+| `Content-Type` | Sí | `application/json` |
+| `X-Api-Key` | Sí (o query) | `pk_xxx` |
+| `X-Sdk-Version` | Recomendado | `0.0.1` |
+
+## Endpoints
+
+### POST /v1/identify
+
+Crea o actualiza un end_user y opcionalmente su organization.
+
+**Request body:**
+```json
+{
+  "endUser": {
+    "id": "user_123",
+    "anonymousId": "anon_xyz",
+    "traits": {
+      "email": "user@example.com",
+      "role": "admin",
+      "plan": "free"
+    }
+  },
+  "organization": {
+    "id": "acme-corp",
+    "attributes": {
+      "plan": "pro",
+      "mrr": 99.99,
+      "industry": "saas"
+    }
+  }
+}
+```
+
+**Response 200:**
+```json
+{
+  "endUserId": "user_123",
+  "organizationId": "acme-corp",
+  "workspaceId": "uuid"
+}
+```
+
+**Errors:**
+- `400` - payload inválido
+- `401` - API key inválida
+
+---
+
+### POST /v1/events
+
+Ingesta batch de eventos (máx 100 por request).
+
+**Request body:**
+```json
+{
+  "events": [
+    {
+      "actionId": "01900000-0000-7000-8000-000000000001",
+      "endUserId": "user_123",
+      "organizationId": "acme-corp",
+      "sessionId": "session_abc",
+      "actionType": "track",
+      "actionName": "project_created",
+      "occurredAt": "2026-05-08T10:00:00.000Z",
+      "pageUrl": "https://app.example.com/dashboard",
+      "pagePath": "/dashboard",
+      "pageTitle": "Dashboard",
+      "pageReferrer": "https://google.com",
+      "actionProperties": {
+        "templateId": "blank"
+      }
+    }
+  ]
+}
+```
+
+**Action types válidos:**
+- `pageview` - usuario visitó una página
+- `track` - evento custom con nombre
+- `identify` - usuario se identificó (también triggea upsert)
+- `guide` - interacción con guía (futuro)
+
+**Response 200:**
+```json
+{
+  "accepted": 95,
+  "deduped": 5
+}
+```
+
+**Errors:**
+- `400` - batch vacío, payload inválido, o > 100 eventos
+- `401` - API key inválida
+- `413` - body demasiado grande
+
+---
+
+## Idempotencia
+
+Cada `actionId` es único. El backend mantiene ventana de 24h para
+detectar duplicados. Si el SDK reintenta por timeout, el evento NO se
+duplica.
+
+## Reglas
+
+- `occurredAt` siempre en ISO 8601 con timezone (Z o offset)
+- `traits` y `attributes` son JSONB, sin schema fijo
+- Máximo 64KB por campo JSONB
+- Máximo 100 eventos por request
+- Encoding: UTF-8
+
+## SDK Version
+
+El SDK debe enviar `X-Sdk-Version` en cada request para trazabilidad.

package/README.md

@@ -0,0 +1,141 @@
+# @veo/sdk
+
+SDK oficial de Veo para web apps. Captura eventos de analytics y muestra
+guías in-app (tooltips, modales, walkthroughs).
+
+## Stack
+
+- TypeScript estricto
+- Cero dependencias en runtime
+- 3 formatos: ESM, CJS, IIFE (CDN)
+- < 10KB gzipped
+
+## Instalación
+
+### npm
+
+```bash
+pnpm add @veo/sdk
+```
+
+```ts
+import { init } from '@veo/sdk';
+
+const veo = init({
+  apiKey: 'pk_xxx',
+  apiUrl: 'https://api.veo.io',
+});
+
+veo.identify({ visitor: { id: 'user_123', traits: { email: 'a@b.com' } } });
+veo.track('button_clicked');
+```
+
+### CDN (sin bundler)
+
+```html
+<script src="https://cdn.veo.io/sdk/v1.js"></script>
+<script>
+  veo.init({ apiKey: 'pk_xxx', apiUrl: 'https://api.veo.io' });
+  veo.identify({ visitor: { id: 'user_123' } });
+</script>
+```
+
+### Snippet (recomendado)
+
+Ver `snippet/snippet.html` para el snippet copy-paste.
+
+## API
+
+(En desarrollo. Implementación completa en sprints siguientes.)
+
+- `init(config)` - inicializa el SDK
+- `identify(payload)` - identifica un usuario
+- `track(name, properties?)` - emite evento custom
+- `pageview(path?)` - emite pageview (automático en SPAs)
+- `reset()` - limpia identidad
+- `flush()` - fuerza envío de la queue
+
+## Autocaptura
+
+Al hacer `init()`, el SDK captura automáticamente **clicks, submits y changes**
+del DOM (sin código por evento), estilo Pendo/PostHog. Cada interacción genera
+un `track('$autocapture', …)` con metadata del elemento (tag, id, clases
+"humanas", texto, atributos, selector CSS y ancestros). Va por la misma queue
+(mismo batching/retry) que el resto de eventos.
+
+Privacidad agresiva por defecto: **nunca** se captura el `value` de inputs, ni
+el texto de campos de entrada, y se ignoran inputs sensibles
+(`password`, `email`, `tel`, datos de tarjeta, campos con `name`/`id` tipo
+`password`/`ssn`/`credit`/`card`).
+
+### Opt-out de un elemento (y su subárbol)
+
+```html
+<button data-veo-ignore>No me trackees</button>
+<div class="veo-ignore"> … nada aquí se captura … </div>
+```
+
+### Nombre semántico (tagging)
+
+`data-veo-tag` da un nombre estable al elemento (prioritario en el selector,
+ideal para definir "features" en el dashboard aunque cambien clases/estructura):
+
+```html
+<button data-veo-tag="checkout-cta">Comprar</button>
+```
+
+### Configuración
+
+```ts
+init({
+  apiKey: 'pk_xxx',
+  apiUrl: 'https://api.veo.io',
+  autocapture: {
+    captureClicks: true,      // default
+    captureSubmits: true,     // default
+    captureChanges: true,     // default (solo selects y checkbox/radio)
+    maskAllText: false,       // true → no capturar texto visible
+    blockSelectors: ['.private', '#chat-widget'], // ignorar selectores propios
+    throttleMs: 100,          // anti-spam por elemento
+    maxTextLength: 200,       // truncado de textos
+    captureAncestors: 5,      // niveles de ancestros (máx 10)
+  },
+});
+
+// Deshabilitar por completo:
+init({ apiKey: 'pk_xxx', apiUrl: '…', autocapture: false });
+```
+
+## Desarrollo
+
+```bash
+# Setup
+pnpm install
+
+# Desarrollo (watch)
+pnpm dev
+
+# Build
+pnpm build
+
+# Tests
+pnpm test
+
+# Ver tamaño del bundle
+pnpm size
+
+# Lint
+pnpm lint
+```
+
+## Roadmap
+
+- ✅ Sprint 1: Core (identify, track, pageview, SPA router)
+- ✅ Sprint A: Autocaptura de clicks/submits/changes (PII-safe)
+- ⬜ Sprint 4: Guías in-app (tooltips, modales, banners)
+- ⬜ Sprint 5: Walkthroughs multi-paso
+- ⬜ Futuro: Session replay
+
+## Licencia
+
+UNLICENSED (proyecto privado)