Initial Commit

packages/api-stack/api/api-plugin-campaigns/src/context/context.md

@@ -0,0 +1,72 @@
+# `context`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `context` module owns the Hono `ContextVariableMap` declaration-merge
+augmentation applied by `@suaveplan/api-plugin-campaigns`. Importing the
+module for its side effects (which the package root barrel does
+automatically) adds the typed slots the plugin's route handlers read with
+`c.get(...)`, eliminating the `as any` casts that pile up in untyped Hono
+middleware chains.
+
+In Chunk A the only slot the plugin commits to is `eventBus`, because
+that is the only context entry the no-op `onInit` placeholder would set if
+it had a body. Chunks B and C will extend the declaration with the
+repository handles (`campaignRepository`, `campaignSuppressionStore`,
+`deliveryEventStore`) once those classes exist; consumers do not need to
+re-import this module to pick the extensions up.
+
+## Features
+
+- Pure declaration-merge — zero runtime cost, zero bundle size.
+- Re-exports an empty value (`export {}`) so the module participates in
+  ES-module side-effect ordering without polluting the consumer's
+  namespace.
+- Slot type drawn from `@suaveplan/types` so the augmentation does not
+  drag in the api-plugin-campaigns implementation surface.
+
+## Usage: Basic
+
+```ts
+import { Hono } from "hono";
+import "@suaveplan/api-plugin-campaigns"; // also pulls this module via the root barrel
+
+const app = new Hono();
+app.get("/", (c) => {
+    const bus = c.get("eventBus");
+    bus.emit("campaign.read", { id: "x" });
+    return c.text("ok");
+});
+```
+
+## Usage: Advanced
+
+```ts
+import "@suaveplan/api-plugin-campaigns/plugin/plugin"; // ensures the augmentation
+import type { ContextVariableMap } from "hono";
+
+type EventBus = ContextVariableMap["eventBus"];
+```
+
+## API Reference
+
+- Adds `eventBus: EventBusLike` to Hono `ContextVariableMap`.
+- No runtime exports.
+
+## Implementation Notes
+
+Module augmentations must live in a file with at least one `export`
+statement to be picked up as a module rather than a script. The empty
+`export {}` at the bottom is the standard idiom; removing it would
+silently demote the file to a script and the `declare module "hono"`
+block would stop applying.
+
+Chunks B and C augment the same `ContextVariableMap` interface from
+their own context modules, relying on TypeScript declaration merging to
+union the slots together. That means agents working on later chunks
+never edit this file — they add new files with their own
+`declare module "hono"` blocks.

packages/api-stack/api/api-plugin-campaigns/src/context/context.ts

@@ -0,0 +1,29 @@
+/**
+ * Hono `ContextVariableMap` module augmentation for
+ * `@suaveplan/api-plugin-campaigns`. Importing this module for side
+ * effects (which the package root barrel does automatically) reserves
+ * the slots the plugin's `onInit` middleware populates on every Hono
+ * request so route handlers can read them via `c.get(...)` with full
+ * typing.
+ *
+ * Chunk C adds the three repository slots (`campaignRepository`,
+ * `campaignSuppressionStore`, `deliveryEventStore`) alongside the
+ * `eventBus` baseline declared in Chunk A. Slots are typed as the
+ * structural store interfaces — `CampaignStore`,
+ * `CampaignSuppressionStore`, `DeliveryEventStore` — so route handlers
+ * stay agnostic of the concrete (in-memory vs. SurrealDB) backend.
+ */
+
+import type { CampaignStore } from "@suaveplan/campaigns";
+import type { DeliveryEventStore } from "@suaveplan/delivery-tracking";
+import type { EventBusLike } from "@suaveplan/types";
+import type { CampaignSuppressionStore } from "../repositories/suppression/suppression.types.js";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        eventBus: EventBusLike;
+        campaignRepository: CampaignStore;
+        campaignSuppressionStore: CampaignSuppressionStore;
+        deliveryEventStore: DeliveryEventStore;
+    }
+}

packages/api-stack/api/api-plugin-campaigns/src/context/index.ts

@@ -0,0 +1 @@
+import "./context.js";