skills/plugins/document-navigator/docs/api-stack/api/api-plugin-campaigns/README.md

@suaveplan/api-plugin-campaigns - Campaigns + suppression + delivery-webhooks HTTP plugin for @suaveplan/api. Mounts /campaigns, /suppression, and /webhooks on a Hono OpenAPI registry, backed by SurrealDB implementations of @suaveplan/campaigns CampaignStore and a local CampaignSuppressionStore, plus the @suaveplan/delivery-tracking SurrealDeliveryEventStore. Chunked migration (A: foundation, B: repositories, C: routes).

Campaigns + suppression + delivery-webhooks HTTP plugin for @suaveplan/api. Mounts the /campaigns, /suppression, and /webhooks route trees on a Hono OpenAPIHono registry, backed by SurrealDB implementations of the universal @suaveplan/campaigns CampaignStore, a local CampaignSuppressionStore, and the already-shipped @suaveplan/delivery-tracking SurrealDeliveryEventStore.

Documentation tree

• context — The context module owns the Hono ContextVariableMap declaration-merge augmentation applied by `@suaveplan/api-plugi…
  • context — The context module owns the Hono ContextVariableMap declaration-merge augmentation applied by `@suaveplan/api-plugi…
• error-codes — The error-codes module owns the stable CAMPAIGNS_API.* namespace used by every failure path inside `@suaveplan/api-pl…
  • error-codes — The error-codes module owns the stable CAMPAIGNS_API.* namespace used by every failure path inside `@suaveplan/api-pl…
• otel — The otel/instruments module owns the OpenTelemetry instrument bundle emitted by @suaveplan/api-plugin-campaigns. It…
  • instruments — The otel/instruments module owns the OpenTelemetry instrument bundle emitted by @suaveplan/api-plugin-campaigns. It…
• plugin — The plugin module exports createCampaignsPlugin — the PluginDescriptor factory consumed by @suaveplan/api hosts…
  • plugin — The plugin module exports createCampaignsPlugin — the PluginDescriptor factory consumed by @suaveplan/api hosts…
• campaign — This module owns the SurrealDB-backed implementation of the campaign persistence contract for `@suaveplan/api-plugin-ca…
  • campaign — This module owns the SurrealDB-backed implementation of the campaign persistence contract for `@suaveplan/api-plugin-ca…
• suppression — This module owns the SurrealDB-backed implementation of the tenant + channel-scoped CampaignSuppressionStore interfac…
  • suppression-internals — This module owns the validation and mapping primitives shared by the two CampaignSuppressionStore implementations — `…
  • suppression-memory — In-memory reference implementation of the tenant + channel-scoped CampaignSuppressionStore interface. Intended for un…
  • suppression — This module owns the SurrealDB-backed implementation of the tenant + channel-scoped CampaignSuppressionStore interfac…
• action-routes — This module owns the campaign action routes — state-machine transitions (/send, /pause, /cancel), the `/duplicate…
• build-routes — buildCampaignRoutes is the single aggregator that materialises every /campaigns/* PluginRouteEntry in a canonical…
• crud-routes — This module owns the five canonical CRUD entries for the /campaigns route tree: list, create, get, update, and delete…
• schemas — This module is the OpenAPI-facing contract for the /campaigns route tree. Every incoming request body, query string,…
• require-tenant — requireTenant extracts the request principal from the Hono context slot c.get("user") (populated by `@suaveplan/api…
• strip-undefined — stripUndefined is a route-layer adapter that bridges Zod's optional() output (T | undefined) with the `exactOptio…
• build-routes — buildSuppressionRoutes aggregates the four /suppression/* plugin route entries in canonical order (list, check, cre…
• routes — The suppression-route module owns the four endpoints that manage the (tenantId, channel, channelValue)-keyed suppress…
• schemas — The suppression-route schemas describe the OpenAPI contract for the /suppression route tree. The package's local `Cam…
• build-routes — buildWebhookRoutes aggregates the two /webhooks/* route entries in canonical order — delivery ingest first, then on…
• routes — The webhook-route module owns the two webhook endpoints: a delivery event ingestion endpoint that normalises and persis…
• schemas — The webhook-route schemas describe the OpenAPI contract for the /webhooks route tree, plus a decodeUnsubscribeToken…
• schemas — The schemas/options module owns the Zod validator that createCampaignsPlugin runs against its caller-supplied optio…
  • options — The schemas/options module owns the Zod validator that createCampaignsPlugin runs against its caller-supplied optio…
• services — The services/registry-augmentation module owns the ServiceRegistry declaration-merge augmentation applied by `@suav…
  • registry-augmentation — The services/registry-augmentation module owns the ServiceRegistry declaration-merge augmentation applied by `@suav…
• types — The types module exports the public type bundle for @suaveplan/api-plugin-campaigns — the option-input shape consum…
  • types — The types module exports the public type bundle for @suaveplan/api-plugin-campaigns — the option-input shape consum…

Chunked migration status

This package is being being migrated in three sequential chunks so each ships green on its own:

• Chunk A — foundation (this version) — package shell, error codes, OTel instruments, Zod options schema, shared types, plugin scaffold with a no-op onInit placeholder.
• Chunk B — repositories (follow-up) — SurrealCampaignRepository, CampaignSuppressionStore + Surreal implementation, delivery-event store wiring, schema DDL bundle, repository registration on the host ServiceRegistry.
• Chunk C — routes (follow-up) — /campaigns, /suppression, and /webhooks route trees registered via definePluginRoutes, integration tests against a SurrealDB testcontainer.

Quality gates

bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-campaigns plus bunx turbo test:coverage --filter=@suaveplan/api-plugin-campaigns at 100/100/100/100 are required for every chunk to land.