# 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
npm install veo-sdk    # o: pnpm add veo-sdk / yarn add veo-sdk
```

```ts
import { init } from 'veo-sdk';

// Solo en el navegador (usa localStorage/DOM). En Next: client component.
const veo = init({
  apiKey: 'pk_xxx',
  guides: true,   // opt-in: renderiza guías in-app
  // apiUrl es OPCIONAL: por defecto apunta al backend gestionado de Veo.
  // Solo se pasa para self-hosted / otra región.
});

veo.identify({ visitor: { id: 'user_123', traits: { email: 'a@b.com' } } });
veo.track('button_clicked');
```

### CDN (sin bundler)

Cargá `veo.js` desde unpkg y llamá `init` en el `onload` del `<script>`
(NO uses un stub con cola: el drain del IIFE saltea el `init` encolado):

```html
<script
  src="https://unpkg.com/veo-sdk@0.2.1/dist/veo.js"
  onload="window.veo.init({ apiKey: 'pk_xxx', guides: true });
          window.veo.identify({ visitor: { id: 'user_123' } });">
</script>
```

`apiUrl` es opcional (default = backend gestionado). Fijá la versión (`@0.2.1`)
para no romperte con un release futuro. También por jsDelivr:
`https://cdn.jsdelivr.net/npm/veo-sdk@0.2.1/dist/veo.js`.

## Editor visual de guías (modo builder)

El dashboard de Veo puede abrir tu app en un editor visual para diseñar guías
sobre ella (elegir el elemento ancla, previsualizar). Para eso abre tu app en un
`<iframe>` con `?veoBuilder=<token>` y necesita cargar el bundle del builder
(`veo-builder.js`) para hacer el handshake. Solo se descarga cuando la URL trae
ese token: **tus usuarios finales nunca lo cargan**.

### CDN (`<script>`)

Funciona sin configurar nada: el SDK deriva la URL de `veo-builder.js` a partir
del `<script>` que cargó `veo.js`.

### Bundler (Next / Vite / React)

Funciona sin configurar nada: con `init({ guides: true })` el SDK carga el
builder con un `import()` dinámico cuando la app se abre con `?veoBuilder`. Tu
bundler lo code-splitea, así que **no se descarga para tus usuarios finales** y
**no tenés que copiar `veo-builder.js` ni setear `builderUrl`**.

```ts
init({ apiKey: 'pk_xxx', guides: true });
```

> `builderUrl` sigue disponible como override manual (CDN propio, CSP estricto),
> pero ya no hace falta.

### App con login (Supabase, Clerk, …)

Si tu app tiene login, el editor no puede autenticarse dentro del iframe (Google
OAuth = 403, cookies de terceros). Para diseñar sobre páginas protegidas hace
falta un **"modo diseño"** en tu app: dejar que Veo la embeba + entrar como
usuario demo. El SDK trae los helpers (`veoBuilderProxy`, `ensureVeoDesignSession`
en `veo-sdk/next`) y la **receta completa con Supabase** (2 archivos, copiable)
está en **[`docs/integrations/visual-editor-embed.md`](./docs/integrations/visual-editor-embed.md)**.

## 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)