@fonderie/courier 1.0.0 → 1.0.2

package/brain/outcomes.md

@@ -0,0 +1,55 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/courier — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_courier_templates`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+type                     TEXT NOT NULL
+locale                   TEXT
+subject                  TEXT
+html                     TEXT
+text                     TEXT NOT NULL
+active                   BOOLEAN NOT NULL DEFAULT true
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- UNIQUE (type, locale)
+```
+
+### `fonderie_message_log`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+message_type             TEXT NOT NULL
+channel                  TEXT NOT NULL
+recipient                TEXT NOT NULL
+locale                   TEXT
+status                   TEXT NOT NULL DEFAULT 'pending'
+error                    TEXT
+attempts                 INT NOT NULL DEFAULT 0
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+sent_at                  TIMESTAMPTZ
+provider                 TEXT
+provider_message_id      TEXT
+opened_at                TIMESTAMPTZ
+clicked_at               TIMESTAMPTZ
+bounced_at               TIMESTAMPTZ
+bounce_reason            TEXT
+-- INDEX idx_fml_created (created_at DESC)
+```
+
+Raw SQL ships in `node_modules/@fonderie/courier/dist/migrations/sql/` — read it there if you must; never download tarballs.
+
+## Migration statements not replayed (verify in raw SQL)
+
+- `ELSE`
+- `END IF`
+- `END $$`

package/brain/signatures.md

@@ -0,0 +1,136 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/courier — signatures
+
+## @fonderie/courier
+
+Subpath exports: `@fonderie/courier/types`, `@fonderie/courier/migrations`
+
+```ts
+new CourierModule(config: ICourierConfig, store?: IStoreAdapter | undefined, bus?: EventBus | undefined): CourierModule
+  .name: "@fonderie/courier"
+  .deps: string[]
+  .dispatcher: Dispatcher
+  .install(app: IFonderieApp): void
+
+function handleSendGridDelivery(req: Request, store: IStoreAdapter, webhookSecret?: string | undefined): Promise<Response>
+
+function handleMailgunDelivery(req: Request, store: IStoreAdapter, signingKey?: string | undefined): Promise<Response>
+
+function handleMailtrapDelivery(req: Request, store: IStoreAdapter): Promise<Response>
+
+new Dispatcher(config: ICourierConfig, resolver: ITemplateResolver, store?: IStoreAdapter | undefined): Dispatcher
+  .registerChannel(channel: ICourierChannel): Dispatcher
+  .dispatch(message: ICourierMessage): Promise<void>
+
+new SmsChannel(config: ISmsChannelConfig): SmsChannel
+  .name: "sms"
+  .send(message: ICourierMessage, template: IRenderedTemplate): Promise<void>
+
+new PushChannel(config: IPushChannelConfig): PushChannel
+  .name: "push"
+  .send(message: ICourierMessage, template: IRenderedTemplate): Promise<void>
+
+new EmailChannel(config: IEmailChannelConfig): EmailChannel
+  .name: "email"
+  .send(message: ICourierMessage, template: IRenderedTemplate): Promise<void>
+
+new DBTemplateResolver(store: IStoreAdapter): DBTemplateResolver
+  .resolve(type: string, data: Record<string, unknown>, locale?: string | undefined): Promise<IRenderedTemplate>
+
+new FSTemplateResolver(directory: string): FSTemplateResolver
+  .resolve(type: string, data: Record<string, unknown>, locale?: string | undefined): Promise<IRenderedTemplate>
+
+interface IMessageLog {
+    id: string;
+    messageType: string;
+    channel: string;
+    recipient: string;
+    locale: string | null;
+    status: MessageLogStatus;
+    error: string | null;
+    attempts: number;
+    provider: string | null;
+    providerMessageId: string | null;
+    openedAt: string | null;
+    clickedAt: string | null;
+    bouncedAt: string | null;
+    bounceReason: string | null;
+    createdAt: string;
+    sentAt: string | null;
+}
+
+type MessageLogStatus = 'pending' | 'sent' | 'failed' | 'delivered' | 'opened' | 'clicked' | 'bounced' | 'spam';
+
+interface ICourierMessage {
+    type: string;
+    locale?: string;
+    recipient: {
+        email: string | null;
+        phone: string | null;
+        deviceToken: string | null;
+    };
+    data: Record<string, unknown>;
+}
+
+interface ICourierChannel {
+    name: string;
+    send(message: ICourierMessage, template: IRenderedTemplate): Promise<void>;
+}
+
+interface IRenderedTemplate {
+    subject?: string;
+    html?: string;
+    text: string;
+}
+
+interface ITemplateResolver {
+    resolve(type: string, data: Record<string, unknown>, locale?: string): Promise<IRenderedTemplate>;
+}
+
+const Channel: { readonly EMAIL: "email"; readonly SMS: "sms"; readonly PUSH: "push"; }
+
+interface ICourierConfig {
+    channels: Record<string, Array<'email' | 'sms' | 'push'>>;
+    sms?: ISmsChannelConfig;
+    push?: IPushChannelConfig;
+    email?: IEmailChannelConfig;
+    templates?: {
+        source: 'db' | 'fs';
+        directory?: string;
+    };
+    delivery?: {
+        signingKeys?: {
+            sendgrid?: string;
+            mailgun?: string;
+        };
+    };
+}
+
+interface IEmailChannelConfig {
+    provider: 'resend' | 'ses' | 'smtp';
+    from: string;
+    apiKey?: string;
+    smtp?: {
+        host: string;
+        port: number;
+        secure: boolean;
+        user: string;
+        pass: string;
+    };
+}
+
+interface ISmsChannelConfig {
+    provider: 'twilio' | 'vonage';
+    from: string;
+    accountSid?: string;
+    authToken?: string;
+    apiKey?: string;
+    apiSecret?: string;
+}
+
+interface IPushChannelConfig {
+    provider: 'fcm';
+    serviceAccount: Record<string, unknown>;
+}
+```

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+declare const getMigrationsPath: () => string;
+
+export { getMigrationsPath };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/courier",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "Transactional messaging for SaaS — multi-channel delivery (email, SMS, push) with FS or DB templates, per-message-type channel routing, and a persistent message log.",
 	"keywords": [
 		"fonderie-js",
@@ -39,7 +39,7 @@
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"scripts": {
-		"build": "tsup && node -e \"require('node:fs').cpSync('src/migrations/sql', 'dist/migrations/sql', {recursive:true})\"",
+		"build": "tsup && tsup --config tsup.migrations.ts",
 		"dev": "tsup --watch",
 		"typecheck": "tsc --noEmit",
 		"test": "tsx --test src/__tests__/*.test.ts",
@@ -51,9 +51,9 @@
 		"nodemailer": "^8.0.7"
 	},
 	"peerDependencies": {
-		"@fonderie/core": "^0.1.0",
-		"@fonderie/store": "^0.1.0",
-		"@fonderie/events": "^1.0.0"
+		"@fonderie/core": "^0.1.1",
+		"@fonderie/store": "^0.1.1",
+		"@fonderie/events": "^1.0.1"
 	},
 	"peerDependenciesMeta": {
 		"@fonderie/store": {
@@ -78,16 +78,17 @@
 	},
 	"files": [
 		"dist",
+		"brain",
 		"LICENSE",
 		"README.md"
 	],
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/fonderie-js/sdk.git",
+		"url": "git+https://github.com/fonderiejs/sdk.git",
 		"directory": "packages/courier"
 	},
-	"homepage": "https://github.com/fonderie-js/sdk/tree/main/packages/courier#readme",
+	"homepage": "https://github.com/fonderiejs/sdk/tree/main/packages/courier#readme",
 	"bugs": {
-		"url": "https://github.com/fonderie-js/sdk/issues"
+		"url": "https://github.com/fonderiejs/sdk/issues"
 	}
 }

package/dist/migrations/sql/001_courier.sql

@@ -1,34 +0,0 @@
--- fonderie_courier_templates: per-type, per-locale message templates
-CREATE TABLE IF NOT EXISTS fonderie_courier_templates (
-	id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
-	type       TEXT        NOT NULL,
-	locale     TEXT,                   -- NULL = default / catch-all locale
-	subject    TEXT,
-	html       TEXT,
-	text       TEXT        NOT NULL,
-	active     BOOLEAN     NOT NULL DEFAULT true,
-	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-	updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-	UNIQUE (type, locale)
-);
-
-CREATE INDEX IF NOT EXISTS idx_fct_type
-	ON fonderie_courier_templates (type) WHERE active = true;
-
--- fonderie_message_log: audit trail of every dispatch attempt
-CREATE TABLE IF NOT EXISTS fonderie_message_log (
-	id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
-	message_type TEXT        NOT NULL,
-	channel      TEXT        NOT NULL,
-	recipient    TEXT        NOT NULL,
-	locale       TEXT,
-	status       TEXT        NOT NULL DEFAULT 'pending',
-	error        TEXT,
-	attempts     INT         NOT NULL DEFAULT 0,
-	created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
-	sent_at      TIMESTAMPTZ
-);
-
-CREATE INDEX IF NOT EXISTS idx_fml_type    ON fonderie_message_log (message_type);
-CREATE INDEX IF NOT EXISTS idx_fml_status  ON fonderie_message_log (status);
-CREATE INDEX IF NOT EXISTS idx_fml_created ON fonderie_message_log (created_at DESC);

package/dist/migrations/sql/002_seed_templates.sql

@@ -1,49 +0,0 @@
--- Seed default email templates
--- Uses UPDATE + conditional INSERT to safely handle NULL locale (ON CONFLICT
--- does not fire for NULL columns in standard Postgres unique indexes).
-
--- email-verification  — variables: pin, firstName
-DO $$
-BEGIN
-	IF EXISTS (
-		SELECT 1 FROM fonderie_courier_templates
-		WHERE type = 'email-verification' AND locale IS NULL
-	) THEN
-		UPDATE fonderie_courier_templates
-		SET
-			subject    = 'Your verification code',
-			html       = '<p>Hi {{firstName}},</p>
-<p>Your email verification code is:</p>
-<h2 style="letter-spacing:0.2em;">{{pin}}</h2>
-<p>Enter this code to complete your registration. It expires in 24 hours.</p>
-<p>If you did not create an account, you can safely ignore this email.</p>',
-			text       = 'Hi {{firstName}},
-
-Your email verification code is: {{pin}}
-
-Enter this code to complete your registration. It expires in 24 hours.
-
-If you did not create an account, you can safely ignore this email.',
-			updated_at = now()
-		WHERE type = 'email-verification' AND locale IS NULL;
-	ELSE
-		INSERT INTO fonderie_courier_templates (type, locale, subject, html, text)
-		VALUES (
-			'email-verification',
-			NULL,
-			'Your verification code',
-			'<p>Hi {{firstName}},</p>
-<p>Your email verification code is:</p>
-<h2 style="letter-spacing:0.2em;">{{pin}}</h2>
-<p>Enter this code to complete your registration. It expires in 24 hours.</p>
-<p>If you did not create an account, you can safely ignore this email.</p>',
-			'Hi {{firstName}},
-
-Your email verification code is: {{pin}}
-
-Enter this code to complete your registration. It expires in 24 hours.
-
-If you did not create an account, you can safely ignore this email.'
-		);
-	END IF;
-END $$;

package/dist/migrations/sql/003_message_log_delivery.sql

@@ -1,12 +0,0 @@
--- Extend fonderie_message_log for delivery event correlation
-ALTER TABLE fonderie_message_log
-	ADD COLUMN IF NOT EXISTS provider             TEXT,
-	ADD COLUMN IF NOT EXISTS provider_message_id  TEXT,
-	ADD COLUMN IF NOT EXISTS opened_at            TIMESTAMPTZ,
-	ADD COLUMN IF NOT EXISTS clicked_at           TIMESTAMPTZ,
-	ADD COLUMN IF NOT EXISTS bounced_at           TIMESTAMPTZ,
-	ADD COLUMN IF NOT EXISTS bounce_reason        TEXT;
-
-CREATE INDEX IF NOT EXISTS idx_fml_provider_msg_id
-	ON fonderie_message_log (provider_message_id)
-	WHERE provider_message_id IS NOT NULL;