Plugins

Cada evento que produce el SDK — llamadas a track, $autocapture, $pageview, $identify — fluye por un pipeline de plugins antes de llegar a la cola de envío:

track()/identify()/$autocapture/... → before → enrichment → after → send queue

Escribir un plugin

import type { KildenPlugin } from '@kilden/sdk';

const scrubEmails: KildenPlugin = {
  name: 'scrub-emails',
  stage: 'before',
  process(event) {
    if (typeof event.properties.email === 'string') {
      const { email, ...rest } = event.properties;
      return { ...event, properties: rest };
    }
    return event;
  },
};

kilden.use(scrubEmails);

interface KildenPlugin {
  name: string;
  stage: 'before' | 'enrichment' | 'after';
  setup?(client: KildenClient): void;
  process?(event: EventPayload): EventPayload | null; // null = descartar
  teardown?(): void;
}

Semántica de las etapas

Etapa	Puede transformar	Puede descartar (return null)	Uso típico
before	sí	sí	filtros, sampling, limpieza de PII
enrichment	sí	no debería — descartar aquí es señal de mal diseño	agregar properties
after	no	no	solo observación; el valor de retorno se ignora

Dentro de una etapa, los plugins corren en orden de registro.

Reglas

• process es síncrono. Haz el trabajo async en setup, o en un plugin after con su propia cola.
• use(plugin) con un nombre existente reemplaza ese plugin (mismo lugar en el orden).
• removePlugin(name) llama al teardown() del plugin si lo tiene.
• use() antes de init se encola como cualquier llamada pre-init.
• Un plugin que lanza una excepción queda aislado: el error se captura (se loguea solo con debug: true) y el evento continúa con el resultado de la etapa anterior. La API pública nunca lanza excepciones por culpa de un plugin.

beforeSend es azúcar sintáctico

InitOptions.beforeSend registra por debajo un plugin before anónimo — el comportamiento observable es idéntico a escribir el plugin tú mismo. Es la forma más rápida de transformar o descartar todo, incluidos los eventos automáticos:

kilden.init('YOUR_WRITE_KEY', {
  beforeSend(event) {
    if (event.event === '$autocapture') return null; // descartar
    return event;
  },
});

Las features integradas también son plugins

Las sesiones ($session_id), las properties de contexto, el parseo de $utm_* y el autocapture están implementados como plugins internos sobre este mismo pipeline. El autocapture se registra tarde, cuando su chunk lazy termina de cargar — los plugins que registres nunca quedan bloqueados por él.