Plugins

Todo evento que o SDK produz — chamadas de track, $autocapture, $pageview, $identify — passa por um pipeline de plugins antes de chegar à fila de envio:

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

Escrevendo um 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 dos estágios

Estágio	Pode transformar	Pode descartar (return null)	Uso típico
before	sim	sim	filtros, amostragem, remoção de PII
enrichment	sim	não deveria — descartar aqui é sinal de design ruim	adicionar properties
after	não	não	somente observação; o valor de retorno é ignorado

Dentro de um estágio, os plugins rodam na ordem de registro.

Regras

• process é síncrono. Faça trabalho assíncrono em setup, ou em um plugin after com fila própria.
• use(plugin) com um nome já existente substitui aquele plugin (mesma posição na ordem).
• removePlugin(name) chama o teardown() do plugin, se existir.
• use() antes de init é enfileirado como qualquer chamada pré-init.
• Um plugin que lança exceção fica isolado: o erro é capturado (registrado apenas com debug: true) e o evento continua com o resultado do estágio anterior. A API pública nunca lança exceção por causa de um plugin.

beforeSend é açúcar sintático

InitOptions.beforeSend registra por baixo dos panos um plugin before anônimo — o comportamento observável é idêntico a escrever o plugin você mesmo. É a forma mais rápida de transformar ou descartar tudo, incluindo eventos automáticos:

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

Features nativas também são plugins

Sessões ($session_id), properties de contexto, parsing de $utm_* e autocapture são implementados como plugins internos nesse mesmo pipeline. O autocapture se registra tarde, quando seu chunk lazy termina de carregar — os plugins que você registra nunca ficam bloqueados por ele.