@fonderie/courier 1.0.1 → 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/courier",
-	"version": "1.0.1",
+	"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",
@@ -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"
 	}
 }