@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

7.6 KiB Raw Blame History