veo-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+/**
+ * Configuración de la autocaptura de interacciones del DOM.
+ */
+interface VeoAutocaptureConfig {
+    /** Habilitar autocaptura. Default: true. */
+    enabled?: boolean;
+    /** Capturar clicks. Default: true. */
+    captureClicks?: boolean;
+    /** Capturar submits de formularios. Default: true. */
+    captureSubmits?: boolean;
+    /** Capturar changes en inputs/selects. Default: true. */
+    captureChanges?: boolean;
+    /** NO capturar value de inputs (privacidad). Default: true. */
+    maskAllInputs?: boolean;
+    /** NO capturar texto visible de elementos. Default: false. */
+    maskAllText?: boolean;
+    /** Selectores CSS a ignorar completamente (y sus descendientes). */
+    blockSelectors?: string[];
+    /** Throttle: no duplicar eventos del mismo elemento en N ms. Default: 100. */
+    throttleMs?: number;
+    /** Truncar textos a N caracteres. Default: 200. */
+    maxTextLength?: number;
+    /** Incluir classes/attrs/position en cada evento. Default: true. */
+    captureElementMetadata?: boolean;
+    /** Niveles de ancestros a capturar. Default: 5. Max: 10. */
+    captureAncestors?: number;
+}
+/**
+ * Configuración del cliente Veo.
+ */
+interface VeoConfig {
+    /** API key pública del workspace (formato pk_xxx). */
+    apiKey: string;
+    /** URL base del backend de Veo. */
+    apiUrl: string;
+    /** Intervalo en ms para flush automático de la queue. Default: 5000. */
+    flushInterval?: number;
+    /** Tamaño máximo del batch antes de flush. Default: 20. */
+    flushBatchSize?: number;
+    /** Activar logs en consola. Default: false. */
+    debug?: boolean;
+    /** Backend de almacenamiento para IDs persistentes. Default: 'localStorage'. */
+    storage?: 'localStorage' | 'cookie' | 'memory';
+    /** Configuración de autocaptura. `false` la deshabilita por completo. */
+    autocapture?: VeoAutocaptureConfig | false;
+    /**
+     * Renderer de guías in-app. Opt-in: si es `true`, el SDK consulta
+     * `/v1/guides/resolve` en cada pageview y renderiza modales/banners/
+     * tooltips. Default: `false`.
+     */
+    guides?: boolean;
+}
+/**
+ * Información del end user (usuario final).
+ */
+interface VeoVisitor {
+    id: string;
+    anonymousId?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Información de la organization (B2B SaaS).
+ */
+interface VeoOrganization {
+    id: string;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Plugin del SDK. Permite extender funcionalidad.
+ */
+interface VeoPlugin {
+    name: string;
+    install(client: VeoClient): void;
+    destroy?(): void;
+}
+/**
+ * Eventos internos que el Client emite para que los plugins se enganchen
+ * (e.g. el plugin de guides escucha `pageview` para chequear qué guías
+ * debe mostrar). No tienen nada que ver con los eventos analíticos que
+ * llegan al backend.
+ *
+ * El payload incluye `sessionId` y `endUserId` para evitar que los plugins
+ * tengan que consultar al client en cada disparo y para garantizar que
+ * todos los listeners ven el mismo snapshot del momento del evento.
+ */
+interface VeoClientEvents {
+    pageview: {
+        url: string;
+        path: string;
+        sessionId: string;
+        endUserId: string | null;
+    };
+    identify: {
+        endUserId: string;
+        sessionId: string;
+    };
+}
+type VeoClientEventName = keyof VeoClientEvents;
+type VeoClientEventListener<E extends VeoClientEventName> = (payload: VeoClientEvents[E]) => void;
+/**
+ * Forward declaration del client (implementación viene en core/client.ts).
+ */
+interface VeoClient {
+    identify(payload: {
+        visitor: VeoVisitor;
+        organization?: VeoOrganization;
+    }): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    pageview(path?: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    use(plugin: VeoPlugin): VeoClient;
+    /** Suscribirse a eventos internos del Client. Devuelve el unsubscribe. */
+    on<E extends VeoClientEventName>(event: E, listener: VeoClientEventListener<E>): () => void;
+    /**
+     * @internal Consumido por plugins (e.g. guides) que necesitan el ID
+     * actual al momento de hacer un POST. NO es API estable para usuarios.
+     */
+    getEndUserId(): string | null;
+    /** @internal Consumido por plugins. NO es API estable para usuarios. */
+    getSessionId(): string;
+}
+
+/**
+ * Tipos del contrato HTTP entre el SDK y el backend.
+ * Versión 1.
+ *
+ * IMPORTANTE: Si cambias algo aquí, debes actualizar también:
+ * - veo-backend/src/modules/identity/dto/*.dto.ts
+ * - veo-backend/src/modules/ingest/dto/*.dto.ts
+ * - CONTRACT.md
+ */
+declare const SDK_VERSION = "0.0.1";
+
+/**
+ * Cliente principal del SDK. Expone la API pública (`identify`, `track`,
+ * `pageview`, `reset`, `flush`, `use`). Toda la API salvo `flush()` es síncrona:
+ * los eventos se encolan y la llamada retorna de inmediato.
+ */
+declare class Client implements VeoClient {
+    private readonly config;
+    private readonly transport;
+    private readonly storage;
+    private readonly session;
+    private readonly queue;
+    private readonly plugins;
+    private currentOrganizationId;
+    private readonly listeners;
+    constructor(config: VeoConfig);
+    identify(payload: {
+        visitor: VeoVisitor;
+        organization?: VeoOrganization;
+    }): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    pageview(path?: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    use(plugin: VeoPlugin): VeoClient;
+    getEndUserId(): string | null;
+    getSessionId(): string;
+    /**
+     * Suscribe `listener` a `event`. Devuelve una función para desuscribir.
+     * Los errores en listeners se logean en debug mode pero NO se propagan
+     * (un plugin no debe poder romper a otro).
+     */
+    on<E extends VeoClientEventName>(event: E, listener: VeoClientEventListener<E>): () => void;
+    private emit;
+    /**
+     * Construye el evento completo y lo agrega a la queue. Omite los campos
+     * opcionales no definidos (exigido por `exactOptionalPropertyTypes`).
+     * @internal
+     */
+    private enqueue;
+    private setupUnloadHandlers;
+}
+
+/**
+ * Plugin de autocaptura de eventos del DOM.
+ * Captura clicks, submits y changes automáticamente y los emite como
+ * eventos `track('$autocapture', …)` por la Queue del cliente.
+ */
+declare function autocapturePlugin(config?: VeoAutocaptureConfig): VeoPlugin;
+
+interface GuidesPluginConfig {
+    apiUrl: string;
+    apiKey: string;
+    debug?: boolean;
+}
+/**
+ * Plugin que renderiza guías in-app (modal/banner/tooltip) consultando
+ * `GET /v1/guides/resolve` y registra las interacciones en
+ * `POST /v1/guides/:id/interactions` vía queue dedicada con retry y
+ * sendBeacon en pagehide.
+ *
+ * Opt-in: `init({ ..., guides: true })`. El plugin escucha
+ * `pageview` e `identify` del client; el payload del evento ya trae
+ * `sessionId` y `endUserId` para que no necesitemos consultar al
+ * client en cada disparo.
+ *
+ * Frequency híbrida: el backend filtra autoritariamente; el cache
+ * local (`GuideFrequencyCache`) solo previene el flash visual cuando
+ * la interaction aún no se persistió.
+ */
+declare function guidesPlugin(config: GuidesPluginConfig): VeoPlugin;
+
+/**
+ * Helper de identidad para definir un plugin con inferencia de tipos.
+ * No transforma nada; mejora la ergonomía y deja un punto de extensión futuro.
+ */
+declare function definePlugin(plugin: VeoPlugin): VeoPlugin;
+
+/**
+ * Plugin que auto-emite `pageview` en cambios de ruta de una SPA.
+ * Cubre `history.pushState`, `history.replaceState`, `popstate` y `hashchange`.
+ */
+declare function spaRouterPlugin(): VeoPlugin;
+
+/**
+ * Inicializa el SDK de Veo. Instala por defecto el plugin de SPA router
+ * (auto-pageview) y, en browser, expone la instancia en `window.veo` drenando
+ * la cola del snippet stub si existe.
+ *
+ * @example
+ * ```ts
+ * import { init } from '@veo/sdk';
+ *
+ * const veo = init({
+ *   apiKey: 'pk_xxx',
+ *   apiUrl: 'https://api.veo.io'
+ * });
+ *
+ * veo.identify({ visitor: { id: 'user_123' } });
+ * veo.track('button_clicked');
+ * ```
+ */
+declare function init(config: VeoConfig): VeoClient;
+
+export { Client, SDK_VERSION, type VeoAutocaptureConfig, type VeoClient, type VeoConfig, type VeoOrganization, type VeoPlugin, type VeoVisitor, autocapturePlugin, definePlugin, guidesPlugin, init, spaRouterPlugin };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Configuración de la autocaptura de interacciones del DOM.
+ */
+interface VeoAutocaptureConfig {
+    /** Habilitar autocaptura. Default: true. */
+    enabled?: boolean;
+    /** Capturar clicks. Default: true. */
+    captureClicks?: boolean;
+    /** Capturar submits de formularios. Default: true. */
+    captureSubmits?: boolean;
+    /** Capturar changes en inputs/selects. Default: true. */
+    captureChanges?: boolean;
+    /** NO capturar value de inputs (privacidad). Default: true. */
+    maskAllInputs?: boolean;
+    /** NO capturar texto visible de elementos. Default: false. */
+    maskAllText?: boolean;
+    /** Selectores CSS a ignorar completamente (y sus descendientes). */
+    blockSelectors?: string[];
+    /** Throttle: no duplicar eventos del mismo elemento en N ms. Default: 100. */
+    throttleMs?: number;
+    /** Truncar textos a N caracteres. Default: 200. */
+    maxTextLength?: number;
+    /** Incluir classes/attrs/position en cada evento. Default: true. */
+    captureElementMetadata?: boolean;
+    /** Niveles de ancestros a capturar. Default: 5. Max: 10. */
+    captureAncestors?: number;
+}
+/**
+ * Configuración del cliente Veo.
+ */
+interface VeoConfig {
+    /** API key pública del workspace (formato pk_xxx). */
+    apiKey: string;
+    /** URL base del backend de Veo. */
+    apiUrl: string;
+    /** Intervalo en ms para flush automático de la queue. Default: 5000. */
+    flushInterval?: number;
+    /** Tamaño máximo del batch antes de flush. Default: 20. */
+    flushBatchSize?: number;
+    /** Activar logs en consola. Default: false. */
+    debug?: boolean;
+    /** Backend de almacenamiento para IDs persistentes. Default: 'localStorage'. */
+    storage?: 'localStorage' | 'cookie' | 'memory';
+    /** Configuración de autocaptura. `false` la deshabilita por completo. */
+    autocapture?: VeoAutocaptureConfig | false;
+    /**
+     * Renderer de guías in-app. Opt-in: si es `true`, el SDK consulta
+     * `/v1/guides/resolve` en cada pageview y renderiza modales/banners/
+     * tooltips. Default: `false`.
+     */
+    guides?: boolean;
+}
+/**
+ * Información del end user (usuario final).
+ */
+interface VeoVisitor {
+    id: string;
+    anonymousId?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Información de la organization (B2B SaaS).
+ */
+interface VeoOrganization {
+    id: string;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Plugin del SDK. Permite extender funcionalidad.
+ */
+interface VeoPlugin {
+    name: string;
+    install(client: VeoClient): void;
+    destroy?(): void;
+}
+/**
+ * Eventos internos que el Client emite para que los plugins se enganchen
+ * (e.g. el plugin de guides escucha `pageview` para chequear qué guías
+ * debe mostrar). No tienen nada que ver con los eventos analíticos que
+ * llegan al backend.
+ *
+ * El payload incluye `sessionId` y `endUserId` para evitar que los plugins
+ * tengan que consultar al client en cada disparo y para garantizar que
+ * todos los listeners ven el mismo snapshot del momento del evento.
+ */
+interface VeoClientEvents {
+    pageview: {
+        url: string;
+        path: string;
+        sessionId: string;
+        endUserId: string | null;
+    };
+    identify: {
+        endUserId: string;
+        sessionId: string;
+    };
+}
+type VeoClientEventName = keyof VeoClientEvents;
+type VeoClientEventListener<E extends VeoClientEventName> = (payload: VeoClientEvents[E]) => void;
+/**
+ * Forward declaration del client (implementación viene en core/client.ts).
+ */
+interface VeoClient {
+    identify(payload: {
+        visitor: VeoVisitor;
+        organization?: VeoOrganization;
+    }): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    pageview(path?: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    use(plugin: VeoPlugin): VeoClient;
+    /** Suscribirse a eventos internos del Client. Devuelve el unsubscribe. */
+    on<E extends VeoClientEventName>(event: E, listener: VeoClientEventListener<E>): () => void;
+    /**
+     * @internal Consumido por plugins (e.g. guides) que necesitan el ID
+     * actual al momento de hacer un POST. NO es API estable para usuarios.
+     */
+    getEndUserId(): string | null;
+    /** @internal Consumido por plugins. NO es API estable para usuarios. */
+    getSessionId(): string;
+}
+
+/**
+ * Tipos del contrato HTTP entre el SDK y el backend.
+ * Versión 1.
+ *
+ * IMPORTANTE: Si cambias algo aquí, debes actualizar también:
+ * - veo-backend/src/modules/identity/dto/*.dto.ts
+ * - veo-backend/src/modules/ingest/dto/*.dto.ts
+ * - CONTRACT.md
+ */
+declare const SDK_VERSION = "0.0.1";
+
+/**
+ * Cliente principal del SDK. Expone la API pública (`identify`, `track`,
+ * `pageview`, `reset`, `flush`, `use`). Toda la API salvo `flush()` es síncrona:
+ * los eventos se encolan y la llamada retorna de inmediato.
+ */
+declare class Client implements VeoClient {
+    private readonly config;
+    private readonly transport;
+    private readonly storage;
+    private readonly session;
+    private readonly queue;
+    private readonly plugins;
+    private currentOrganizationId;
+    private readonly listeners;
+    constructor(config: VeoConfig);
+    identify(payload: {
+        visitor: VeoVisitor;
+        organization?: VeoOrganization;
+    }): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    pageview(path?: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    use(plugin: VeoPlugin): VeoClient;
+    getEndUserId(): string | null;
+    getSessionId(): string;
+    /**
+     * Suscribe `listener` a `event`. Devuelve una función para desuscribir.
+     * Los errores en listeners se logean en debug mode pero NO se propagan
+     * (un plugin no debe poder romper a otro).
+     */
+    on<E extends VeoClientEventName>(event: E, listener: VeoClientEventListener<E>): () => void;
+    private emit;
+    /**
+     * Construye el evento completo y lo agrega a la queue. Omite los campos
+     * opcionales no definidos (exigido por `exactOptionalPropertyTypes`).
+     * @internal
+     */
+    private enqueue;
+    private setupUnloadHandlers;
+}
+
+/**
+ * Plugin de autocaptura de eventos del DOM.
+ * Captura clicks, submits y changes automáticamente y los emite como
+ * eventos `track('$autocapture', …)` por la Queue del cliente.
+ */
+declare function autocapturePlugin(config?: VeoAutocaptureConfig): VeoPlugin;
+
+interface GuidesPluginConfig {
+    apiUrl: string;
+    apiKey: string;
+    debug?: boolean;
+}
+/**
+ * Plugin que renderiza guías in-app (modal/banner/tooltip) consultando
+ * `GET /v1/guides/resolve` y registra las interacciones en
+ * `POST /v1/guides/:id/interactions` vía queue dedicada con retry y
+ * sendBeacon en pagehide.
+ *
+ * Opt-in: `init({ ..., guides: true })`. El plugin escucha
+ * `pageview` e `identify` del client; el payload del evento ya trae
+ * `sessionId` y `endUserId` para que no necesitemos consultar al
+ * client en cada disparo.
+ *
+ * Frequency híbrida: el backend filtra autoritariamente; el cache
+ * local (`GuideFrequencyCache`) solo previene el flash visual cuando
+ * la interaction aún no se persistió.
+ */
+declare function guidesPlugin(config: GuidesPluginConfig): VeoPlugin;
+
+/**
+ * Helper de identidad para definir un plugin con inferencia de tipos.
+ * No transforma nada; mejora la ergonomía y deja un punto de extensión futuro.
+ */
+declare function definePlugin(plugin: VeoPlugin): VeoPlugin;
+
+/**
+ * Plugin que auto-emite `pageview` en cambios de ruta de una SPA.
+ * Cubre `history.pushState`, `history.replaceState`, `popstate` y `hashchange`.
+ */
+declare function spaRouterPlugin(): VeoPlugin;
+
+/**
+ * Inicializa el SDK de Veo. Instala por defecto el plugin de SPA router
+ * (auto-pageview) y, en browser, expone la instancia en `window.veo` drenando
+ * la cola del snippet stub si existe.
+ *
+ * @example
+ * ```ts
+ * import { init } from '@veo/sdk';
+ *
+ * const veo = init({
+ *   apiKey: 'pk_xxx',
+ *   apiUrl: 'https://api.veo.io'
+ * });
+ *
+ * veo.identify({ visitor: { id: 'user_123' } });
+ * veo.track('button_clicked');
+ * ```
+ */
+declare function init(config: VeoConfig): VeoClient;
+
+export { Client, SDK_VERSION, type VeoAutocaptureConfig, type VeoClient, type VeoConfig, type VeoOrganization, type VeoPlugin, type VeoVisitor, autocapturePlugin, definePlugin, guidesPlugin, init, spaRouterPlugin };