@voltro/plugin-notifications 0.81.0 → 0.83.0

package/dist/define.d.ts

@@ -0,0 +1,53 @@
+import { Schema } from 'effect';
+
+export declare const defineNotification: <Audience, Payload>(config: DefineNotificationConfig<Audience, Payload>) => NotificationDescriptor<Audience, Payload>;
+
+export declare interface DefineNotificationConfig<Audience, Payload> {
+    /** Stable name (`order.shipped`); also the default category. */
+    readonly name: string;
+    /** The notifications category preferences are keyed by. Default: `name`. */
+    readonly category?: string;
+    readonly audience: Schema.Schema<Audience, any>;
+    readonly payload: Schema.Schema<Payload, any>;
+    /** PURE: payload + locale → what the recipient sees. No IO. */
+    readonly render: (payload: Payload, ctx: RenderContext) => RenderedNotification;
+    /** Restrict to these channels (ids); default: every configured channel,
+     *  subject to the recipient's preferences. */
+    readonly channels?: ReadonlyArray<string>;
+}
+
+export declare interface NotificationDescriptor<Audience = unknown, Payload = unknown> {
+    readonly _tag: 'VoltroNotification';
+    readonly name: string;
+    readonly category: string;
+    readonly audience: Schema.Schema<Audience, any>;
+    readonly payload: Schema.Schema<Payload, any>;
+    readonly render: (payload: Payload, ctx: RenderContext) => RenderedNotification;
+    readonly channels?: ReadonlyArray<string>;
+}
+
+export declare interface RenderContext {
+    /** The recipient's locale (from the device row, the user, or the app's default). */
+    readonly locale: string;
+    readonly recipientId: string;
+}
+
+export declare interface RenderedNotification {
+    readonly title: string;
+    readonly body: string;
+    /** Carried to every channel; `deepLink` is what a tap opens (web push, the
+     *  mobile app's link table, the desktop shell). */
+    readonly data?: Readonly<Record<string, unknown>> & {
+        readonly deepLink?: string;
+    };
+    /** Rich push: an image url the push shows (Expo `richContent`, FCM
+     *  `notification.image`, APNs through a mutable-content extension). */
+    readonly image?: string;
+    /** Rich push: action buttons. Each `id` comes back as the tapped action. */
+    readonly actions?: ReadonlyArray<{
+        readonly id: string;
+        readonly title: string;
+    }>;
+}
+
+export { }

package/dist/define.js

@@ -0,0 +1,15 @@
+//#region src/define.ts
+var e = (e) => {
+	if (!e.name || !/^[a-z][a-zA-Z0-9._-]*$/.test(e.name)) throw Error(`defineNotification: name must be a dotted identifier (got ${JSON.stringify(e.name)})`);
+	return {
+		_tag: "VoltroNotification",
+		name: e.name,
+		category: e.category ?? e.name,
+		audience: e.audience,
+		payload: e.payload,
+		render: e.render,
+		...e.channels === void 0 ? {} : { channels: e.channels }
+	};
+};
+//#endregion
+export { e as defineNotification };

package/dist/index.d.ts

@@ -6,6 +6,49 @@ import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+export declare const APNS_HOSTS: {
+    readonly production: "https://api.push.apple.com";
+    readonly sandbox: "https://api.sandbox.push.apple.com";
+};
+
+/** Reasons Apple answers that mean "this token will never work again". */
+export declare const APNS_TOKEN_REJECTIONS: ReadonlySet<string>;
+
+/** The APNs request body from the channel's payload. */
+export declare const apnsBody: (payload: PushPayload) => Record<string, unknown>;
+
+/** The ES256 provider token — `{ alg, kid }` . `{ iss, iat }` . signature. */
+export declare const apnsProviderToken: (options: Pick<ApnsTransportOptions, "keyId" | "teamId" | "privateKey">, issuedAtMs: number) => string;
+
+/** One HTTP/2 POST. Default: `node:http2`, one session per send. */
+export declare type ApnsRequest = (input: ApnsRequestInput) => Promise<ApnsResponse>;
+
+export declare interface ApnsRequestInput {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+
+export declare interface ApnsResponse {
+    readonly status: number;
+    readonly body: string;
+}
+
+export declare const apnsTransport: (options: ApnsTransportOptions) => ((payload: PushPayload) => Promise<void>);
+
+export declare interface ApnsTransportOptions {
+    /** The 10-character key id from the Apple developer portal. */
+    readonly keyId: string;
+    readonly teamId: string;
+    /** The .p8 file's contents (a PEM-encoded private key, as Apple issues it). */
+    readonly privateKey: string;
+    /** The app's bundle id — the `apns-topic`. */
+    readonly bundleId: string;
+    readonly environment?: 'production' | 'sandbox';
+    readonly request?: ApnsRequest;
+    readonly now?: () => number;
+}
+
 export declare interface BroadcastResult {
     /** How many topic subscribers the broadcast fanned out to. */
     readonly recipients: number;
@@ -85,6 +128,22 @@ export declare const decryptWebPushPayload: (body: Buffer, receiver: {
     readonly authSecret: Buffer;
 }) => Buffer;
 
+export declare const defineNotification: <Audience, Payload>(config: DefineNotificationConfig<Audience, Payload>) => NotificationDescriptor<Audience, Payload>;
+
+export declare interface DefineNotificationConfig<Audience, Payload> {
+    /** Stable name (`order.shipped`); also the default category. */
+    readonly name: string;
+    /** The notifications category preferences are keyed by. Default: `name`. */
+    readonly category?: string;
+    readonly audience: Schema.Schema<Audience, any>;
+    readonly payload: Schema.Schema<Payload, any>;
+    /** PURE: payload + locale → what the recipient sees. No IO. */
+    readonly render: (payload: Payload, ctx: RenderContext) => RenderedNotification;
+    /** Restrict to these channels (ids); default: every configured channel,
+     *  subject to the recipient's preferences. */
+    readonly channels?: ReadonlyArray<string>;
+}
+
 export declare const deliveriesTable: Table<"_voltro_notification_deliveries", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "id", boolean>;
     readonly recipient: ColumnBuilder<string, "text", boolean>;
@@ -118,6 +177,14 @@ export declare interface DeliveryRecord {
     readonly clickedAt?: string | null;
 }
 
+export declare interface DurableNotificationPayload {
+    readonly notification: string;
+    readonly recipientId: string;
+    readonly locale: string;
+    readonly payload: unknown;
+    readonly tenantId: string | null;
+}
+
 /** Email channel — the app supplies the sender (compose with
  *  `@voltro/plugin-mail`'s `MailService.send`). Keeps the mail dep out of here. */
 export declare const emailChannel: (send: (msg: {
@@ -156,10 +223,72 @@ declare interface EndpointDelivery {
 
 export declare const endpointHashOf: (endpoint: string) => string;
 
+export declare interface EnqueuedNotification {
+    readonly recipientId: string;
+    readonly locale: string;
+    readonly outboxId: string;
+}
+
+/** One outbox row per recipient; rendering happens at delivery, in the recipient's locale as known NOW. */
+export declare const enqueueNotification: <Audience, Payload>(outbox: OutboxEnqueue, descriptor: NotificationDescriptor<Audience, Payload>, options: EnqueueNotificationOptions<Audience, Payload>) => Promise<ReadonlyArray<EnqueuedNotification>>;
+
+export declare interface EnqueueNotificationOptions<Audience, Payload> extends SendNotificationOptions<Audience, Payload> {
+    /** Dedupes per recipient as `<notification>:<recipient>:<key>` — a retried mutation enqueues once. */
+    readonly idempotencyKey?: string;
+    readonly maxAttempts?: number;
+    readonly delayMs?: number;
+}
+
+export declare const EXPO_PUSH_ENDPOINT = "https://exp.host/--/api/v2/push/send";
+
+export declare const expoPushTransport: (options?: ExpoPushTransportOptions) => ((payload: PushPayload) => Promise<void>);
+
+export declare interface ExpoPushTransportOptions {
+    /** Expo access token (`EXPO_ACCESS_TOKEN`); required for enhanced security
+     *  push, optional otherwise. Never logged. */
+    readonly accessToken?: string;
+    readonly fetch?: typeof fetch;
+    readonly endpoint?: string;
+}
+
+export declare const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+
+/** FCM error codes that mean the token is gone for good. */
+export declare const FCM_TOKEN_REJECTIONS: ReadonlySet<string>;
+
+/** The RS256 JWT assertion Google's token endpoint exchanges for an access token. */
+export declare const fcmAssertion: (sa: FcmServiceAccount, issuedAtMs: number) => string;
+
+/** The HTTP v1 message from the channel's payload — data values must be strings. */
+export declare const fcmMessage: (payload: PushPayload) => Record<string, unknown>;
+
+export declare const fcmSendEndpoint: (projectId: string) => string;
+
+export declare interface FcmServiceAccount {
+    readonly project_id: string;
+    readonly client_email: string;
+    /** The service account's PEM-encoded private key, as Google issues it. */
+    readonly private_key: string;
+    readonly token_uri?: string;
+}
+
+export declare const fcmTransport: (options: FcmTransportOptions) => ((payload: PushPayload) => Promise<void>);
+
+export declare interface FcmTransportOptions {
+    /** The service-account JSON, parsed or as the string Google issued. */
+    readonly serviceAccount: FcmServiceAccount | string;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    /** Override the send endpoint (tests). */
+    readonly endpoint?: string;
+}
+
 /** Mint a fresh P-256 private scalar, base64url — what the dev secret mint and
  *  `voltro secret generate` produce for `VOLTRO_VAPID_PRIVATE_KEY`. */
 export declare const generateVapidPrivateKey: () => string;
 
+export declare const GOOGLE_TOKEN_URI = "https://oauth2.googleapis.com/token";
+
 /** One notification held for later delivery — a digest window rollup or a
  *  quiet-hours deferral. `flushAt` is the ISO instant it becomes deliverable
  *  (the window boundary / the digest flush tick). `kind` marks WHY it was held
@@ -225,6 +354,8 @@ export declare const inboxTable: Table<"_voltro_notification_inbox", FieldDefini
  *  midnight, e.g. 22:00→08:00). An empty window (start === end) is never active. */
 export declare const inQuietHours: (qh: QuietHours, at: Date) => boolean;
 
+export declare const isExpoPushToken: (token: string) => boolean;
+
 /**
  * WHO an inbox belongs to.
  *
@@ -276,6 +407,38 @@ export declare const memoryPushSubscriptionStore: () => PushSubscriptionStore;
  *  date-math library is needed; an unknown zone falls back to UTC. */
 export declare const minuteOfDayInZone: (at: Date, tz: string) => number;
 
+export declare const NOTIFICATION_SEND_EFFECT = "voltro.notification.send";
+
+export declare interface NotificationDescriptor<Audience = unknown, Payload = unknown> {
+    readonly _tag: 'VoltroNotification';
+    readonly name: string;
+    readonly category: string;
+    readonly audience: Schema.Schema<Audience, any>;
+    readonly payload: Schema.Schema<Payload, any>;
+    readonly render: (payload: Payload, ctx: RenderContext) => RenderedNotification;
+    readonly channels?: ReadonlyArray<string>;
+}
+
+/** The `*.outbox.ts` handler: render the row's descriptor for its recipient and send. */
+export declare const notificationOutboxHandler: (options: NotificationOutboxHandlerOptions) => {
+    readonly effect: typeof NOTIFICATION_SEND_EFFECT;
+    readonly maxAttempts: number;
+    readonly handler: (ctx: {
+        readonly payload: Record<string, unknown>;
+    }) => Promise<SendResult>;
+};
+
+export declare interface NotificationOutboxHandlerOptions {
+    /** The notification service of THIS process; `undefined` fails the attempt loudly rather than dropping the row. */
+    readonly service: () => {
+        readonly send: (input: SendInput) => Promise<SendResult>;
+    } | undefined;
+    /** Every descriptor a row may name — an unknown name is a dead row, not a silent skip. */
+    readonly notifications: ReadonlyArray<NotificationDescriptor<any, any>>;
+    /** Default 5. */
+    readonly maxAttempts?: number;
+}
+
 export declare class NotificationService extends NotificationService_base {
 }
 
@@ -475,6 +638,17 @@ export declare interface NotificationStore {
     readonly clearHeld: (ids: ReadonlyArray<string>) => Promise<void>;
 }
 
+/** Structural: `ctx.outbox` from a handler, or `makeOutboxFacade`'s result. */
+export declare interface OutboxEnqueue {
+    readonly enqueue: (effect: string, payload: Record<string, unknown>, options?: {
+        readonly idempotencyKey?: string;
+        readonly maxAttempts?: number;
+        readonly delayMs?: number;
+    }) => Promise<string>;
+}
+
+export declare const parseServiceAccount: (value: FcmServiceAccount | string) => FcmServiceAccount;
+
 export declare const preferencesTable: Table<"_voltro_notification_preferences", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "id", boolean>;
     readonly subjectId: ColumnBuilder<string, "text", boolean>;
@@ -518,6 +692,13 @@ export declare interface PushPayload {
     readonly badge?: number;
     /** The message `data` bag, forwarded as the push data/custom section. */
     readonly data: Record<string, unknown>;
+    /** Rich push: from `msg.data.image` — an image url. */
+    readonly image?: string;
+    /** Rich push: from `msg.data.actions` — action buttons by id. */
+    readonly actions?: ReadonlyArray<{
+        readonly id: string;
+        readonly title: string;
+    }>;
 }
 
 /** A browser push subscription's crypto material, as `PushSubscription.toJSON()`
@@ -614,6 +795,30 @@ export declare const quietHoursTable: Table<"_voltro_notification_quiet_hours",
     readonly policy: ColumnBuilder<string, "text", true>;
 }>, true, never>;
 
+export declare interface RenderContext {
+    /** The recipient's locale (from the device row, the user, or the app's default). */
+    readonly locale: string;
+    readonly recipientId: string;
+}
+
+export declare interface RenderedNotification {
+    readonly title: string;
+    readonly body: string;
+    /** Carried to every channel; `deepLink` is what a tap opens (web push, the
+     *  mobile app's link table, the desktop shell). */
+    readonly data?: Readonly<Record<string, unknown>> & {
+        readonly deepLink?: string;
+    };
+    /** Rich push: an image url the push shows (Expo `richContent`, FCM
+     *  `notification.image`, APNs through a mutable-content extension). */
+    readonly image?: string;
+    /** Rich push: action buttons. Each `id` comes back as the tapped action. */
+    readonly actions?: ReadonlyArray<{
+        readonly id: string;
+        readonly title: string;
+    }>;
+}
+
 /** Test seam. */
 export declare const resetWebPushStoreForTest: () => void;
 
@@ -624,6 +829,15 @@ export declare const resetWebPushStoreForTest: () => void;
  */
 export declare const resolveChannels: (configured: ReadonlyArray<string>, category: string, requested: ReadonlyArray<string> | undefined, prefs: ReadonlyArray<ChannelPreference>, subjectId: string) => ReadonlyArray<string>;
 
+/** Rich-push fields as a message's `data` carries them, or nothing. */
+export declare const richPushOf: (data: Readonly<Record<string, unknown>> | undefined) => {
+    readonly image?: string;
+    readonly actions?: ReadonlyArray<{
+        readonly id: string;
+        readonly title: string;
+    }>;
+};
+
 /** What a caller asks to send. `channels` overrides the default routing. */
 export declare interface SendInput {
     readonly to: string;
@@ -635,6 +849,21 @@ export declare interface SendInput {
     readonly tenantId?: string | null;
 }
 
+export declare const sendNotification: <Audience, Payload>(service: {
+    readonly send: (input: SendInput) => Promise<SendResult>;
+}, descriptor: NotificationDescriptor<Audience, Payload>, options: SendNotificationOptions<Audience, Payload>) => Promise<ReadonlyArray<SentNotification>>;
+
+export declare interface SendNotificationOptions<Audience, Payload> {
+    readonly audience: Audience;
+    readonly payload: Payload;
+    /** Audience → recipient subject ids. Default: `{ userId }` or `{ userIds }`. */
+    readonly recipients?: (audience: Audience) => Promise<ReadonlyArray<string>> | ReadonlyArray<string>;
+    /** The recipient's locale; null → `defaultLocale`. Default: none known. */
+    readonly localeFor?: (recipientId: string) => Promise<string | null>;
+    readonly defaultLocale?: string;
+    readonly tenantId?: string | null;
+}
+
 export declare interface SendResult {
     readonly delivered: ReadonlyArray<string>;
     readonly failed: ReadonlyArray<{
@@ -651,6 +880,12 @@ export declare interface SendResult {
 /** POST one encrypted payload to one subscription's push service. */
 export declare const sendWebPush: (target: WebPushTarget, payload: Buffer, options: WebPushSendOptions) => Promise<WebPushOutcome>;
 
+export declare interface SentNotification {
+    readonly recipientId: string;
+    readonly locale: string;
+    readonly result: SendResult;
+}
+
 /** SMS via a generic REST sender (Twilio etc.) — app supplies the send fn. */
 export declare const smsChannel: (send: (to: string, body: string) => Promise<void>) => Channel;