skills/plugins/document-navigator/docs/communication/emails/delivery-tracking/README.md

@suaveplan/delivery-tracking - Channel-agnostic delivery event tracking for campaigns and messages: lifecycle dedupe, in-memory + SurrealDB stores, time-series aggregation, tracking pixel / link tokens, multi-provider webhook parsing, OTel instrumentation

Channel-agnostic delivery event tracking for campaigns and messages: lifecycle dedupe, in-memory + SurrealDB stores, time-series aggregation, tracking pixel and click-link tokens, multi-provider webhook parsing, and OpenTelemetry instrumentation.

Documentation tree

• aggregator — DeliveryAggregator reads campaign and contact statistics from any DeliveryEventStore and exposes time-series bucket…
  • aggregator — DeliveryAggregator reads campaign and contact statistics from any DeliveryEventStore and exposes time-series bucket…
• tracker — DeliveryTracker is the package's primary write-side surface. It validates inbound CreateDeliveryEventInputs against…
  • tracker — DeliveryTracker is the package's primary write-side surface. It validates inbound CreateDeliveryEventInputs against…
  • tracker.schemas — tracker.schemas declares the Zod boundary schemas applied to DeliveryTracker.track input. Centralising the schemas…
• tracking-link — TrackingLinkWrapper rewrites outbound URLs with click-tracking redirects. Each wrapped URL points at the tracking hos…
  • tracking-link — TrackingLinkWrapper rewrites outbound URLs with click-tracking redirects. Each wrapped URL points at the tracking hos…
• tracking-pixel — TrackingPixelGenerator produces and parses the open-tracking pixel URLs embedded in outbound HTML emails. The pixel U…
  • token-codec — token-codec is the shared XOR + base64url encoder/decoder used by both TrackingPixelGenerator (open tracking) and `…
  • tracking-pixel — TrackingPixelGenerator produces and parses the open-tracking pixel URLs embedded in outbound HTML emails. The pixel U…
• webhook-parser — WebhookEventParser normalises provider-specific delivery webhooks into CreateDeliveryEventInput[] ready for `Delive…
  • webhook-parser — WebhookEventParser normalises provider-specific delivery webhooks into CreateDeliveryEventInput[] ready for `Delive…
• errors — DeliveryTrackingError is the stable typed error class raised by every code path inside @suaveplan/delivery-tracking…
  • delivery-tracking-error — DeliveryTrackingError is the stable typed error class raised by every code path inside @suaveplan/delivery-tracking…
• otel — getDeliveryTrackingInstruments lazily constructs and caches the OTel Counter set used by every production code path…
  • instruments — getDeliveryTrackingInstruments lazily constructs and caches the OTel Counter set used by every production code path…
• memory — memory-store defines the DeliveryEventStore interface that every persistence backend must satisfy, ships the determ…
  • memory-store — memory-store defines the DeliveryEventStore interface that every persistence backend must satisfy, ships the determ…
• surreal — SurrealDeliveryEventStore is the SurrealDB-backed implementation of the DeliveryEventStore contract. It uses positi…
  • surreal-store — SurrealDeliveryEventStore is the SurrealDB-backed implementation of the DeliveryEventStore contract. It uses positi…

Install

bun add @suaveplan/delivery-tracking

Quick start

import {
    DeliveryAggregator,
    DeliveryTracker,
    InMemoryDeliveryEventStore,
    TrackingPixelGenerator,
    WebhookEventParser,
} from "@suaveplan/delivery-tracking";

const store = new InMemoryDeliveryEventStore();
const tracker = new DeliveryTracker(store);
const aggregator = new DeliveryAggregator(store);
const parser = new WebhookEventParser();
const pixel = new TrackingPixelGenerator({
    baseUrl: "https://t.example.com",
    secret: "tracking-secret",
});

tracker.bus.on("delivery:opened", (e) => {
    console.log("opened", e.messageId);
});

const events = parser.parse("sendgrid", { body: webhookBody });
await tracker.trackBatch(events);

const stats = await aggregator.getCampaignStats("c1");
const pixelUrl = pixel.generatePixelUrl("m1", "u1", "c1");

Modules

Module	Description
src/core/tracker/tracker.ts	Validates and records events, dedupes lifecycle types, emits on a typed bus.
src/core/tracker/tracker.schemas.ts	Zod boundary schemas for CreateDeliveryEventInput.
src/core/aggregator/aggregator.ts	Campaign rollups, contact histories, time-series bucketing.
src/core/tracking-pixel/tracking-pixel.ts	Open-tracking pixel URL generator + parser.
src/core/tracking-pixel/token-codec.ts	Shared XOR + base64url codec used by pixel and link wrappers.
src/core/tracking-link/tracking-link.ts	Click-tracking URL wrapper, HTML rewrite, token parse.
src/core/webhook-parser/webhook-parser.ts	Pluggable provider webhook → input normaliser.
src/stores/memory/memory-store.ts	DeliveryEventStore contract + in-memory implementation + computeStats.
src/stores/surreal/surreal-store.ts	SurrealDB-backed implementation using positional SurQL.
src/errors/delivery-tracking-error.ts	DeliveryTrackingError + stable code registry.
src/otel/instruments.ts	Lazy OTel counter set (tracked, deduped, webhook_parsed, token_issued, token_rejected).

Features

• Lifecycle dedupe per messageId for opened, delivered, bounced, unsubscribed, complained.
• Typed EventBus<DeliveryTrackerEventMap> with one topic per DeliveryEventType.
• Backend-agnostic via DeliveryEventStore — drop-in InMemoryDeliveryEventStore, SurrealDeliveryEventStore, or your own.
• Time-series bucketing by hour/day/week.
• Pluggable webhook parsers for SendGrid, Mailgun, AWS SES, and a generic shape.
• Zod boundary validation on every event the tracker accepts.
• Counters emitted via @opentelemetry/api for ingest, dedupe, parser activity, and token issuance/rejection.

Subpath exports

./tracker, ./aggregator, ./tracking-pixel, ./tracking-link, ./webhook-parser, ./stores/memory, ./stores/surreal, ./errors, ./otel.

Errors

Every failure raised by the package extends DeliveryTrackingError. The stable code registry:

• DELIVERY_TRACKING.INVALID_INPUT
• DELIVERY_TRACKING.INVALID_TOKEN
• DELIVERY_TRACKING.UNSUPPORTED_PROVIDER
• DELIVERY_TRACKING.STORE_FAILURE
• DELIVERY_TRACKING.QUERY_FAILURE