@devmonks/notify 0.0.0-stage → 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,130 @@
+/** What a notification says, independent of how it is delivered. Channels pick what they need. */
+export interface Content {
+    title: string;
+    body: string;
+    /** Where tapping it goes (app route or absolute URL). */
+    url?: string;
+    /** Extra string data (push payload, inbox row). */
+    data?: Record<string, string>;
+    /**
+     * Used by the email entry (`./email`). `template` is a React Email component there (see EmailTemplate);
+     * it is typed loosely here so the core does not depend on react.
+     */
+    email?: {
+        subject?: string;
+        template?: (props: any) => unknown;
+        props?: unknown;
+    };
+    /** Per-message push options; they override the adapter's `defaults`. */
+    push?: PushOptions;
+    sms?: {
+        text?: string;
+    };
+}
+/** Push options, mapped to FCM HTTP v1 fields by `fcmPush`. */
+export interface PushOptions {
+    /**
+     * Send no visible notification: the app gets `data` (with `title` and `body` added to it) and
+     * decides what to show. iOS gets a background push (`content-available`).
+     */
+    dataOnly?: boolean;
+    /** App icon badge (iOS `aps.badge`, Android `notification_count`). */
+    badge?: number;
+    /** iOS plays "default" when unset. Android 8+ takes the sound from the channel. */
+    sound?: string;
+    /** Groups notifications (iOS `thread-id`); on Android a new one replaces the one with the same tag. */
+    threadId?: string;
+    /** Android notification channel (`channel_id`). The app must create it; a high-importance channel shows heads-up banners. */
+    channelId?: string;
+    /** Defaults to "high" (Android `HIGH`, APNs 10). "normal" may be delayed to save battery. */
+    priority?: 'high' | 'normal';
+    /** How long the provider keeps an undelivered message. 0 = deliver now or drop. Unset = provider default. */
+    ttlSeconds?: number;
+    /** A newer message with the same key replaces an undelivered or displayed older one (`collapse_key`, `apns-collapse-id`). */
+    collapseKey?: string;
+    /** Escape hatch: raw FCM `AndroidConfig` / `ApnsConfig` / `WebpushConfig` fields, deep-merged over the generated message. */
+    raw?: {
+        android?: Record<string, unknown>;
+        apns?: Record<string, unknown>;
+        webpush?: Record<string, unknown>;
+    };
+}
+export type SendResult = {
+    ok: true;
+    providerId?: string;
+} | {
+    ok: false;
+    /** True when trying again later may work (429, 5xx, network). */
+    retryable: boolean;
+    error: string;
+    /** The address is permanently bad (e.g. an unregistered push token): drop it. */
+    deadAddress?: boolean;
+};
+/** Per-send context passed to the channel. */
+export interface SendContext {
+    type?: string;
+    /** Stable per logical delivery; adapters forward it to providers that support idempotency. */
+    idempotencyKey?: string;
+}
+export interface Channel {
+    name: string;
+    send(to: string, content: Content, ctx?: SendContext): Promise<SendResult>;
+}
+export interface Logger {
+    info(message: string, meta?: unknown): void;
+}
+export interface Recipient {
+    id: string;
+    /** BCP 47, e.g. "en". */
+    locale: string;
+    /** IANA time zone; drives quiet hours. */
+    timeZone: string;
+    email?: string;
+    phone?: string;
+    /** Push-capable installs. One push delivery per device. */
+    devices: {
+        id: string;
+        token: string;
+        platform?: string;
+    }[];
+    /** Defaults to true. */
+    inAppEnabled?: boolean;
+    /** prefs[category][channel] === false switches it off; anything else is on. */
+    prefs: Record<string, Partial<Record<string, boolean>>>;
+    /** Local wall-clock window, may cross midnight (e.g. 22:00 to 07:00). */
+    quietHours?: {
+        from: string;
+        to: string;
+    };
+}
+export interface Delivery {
+    /** Unique per planned delivery (random). Use `idempotencyKey` for dedupe. */
+    id: string;
+    type: string;
+    channel: string;
+    to: string;
+    content: Content;
+    recipientId: string;
+    /** Set for push deliveries: the device the token belongs to. */
+    deviceId?: string;
+    idempotencyKey: string;
+}
+export interface NotificationType<D = any> {
+    type: string;
+    /** Preference key: `recipient.prefs[category][channel]`. Use the type name for per-type switches. */
+    category: string;
+    channels: string[];
+    /** Always send: ignores preferences and quiet hours (sign-in codes, security, moderation notices). */
+    transactional?: boolean;
+    render(data: D, opts: {
+        locale: string;
+    }): Content;
+}
+export interface PlanOptions {
+    /**
+     * Identifies the event. Same type + recipient + channel + address + dedupeKey = same idempotencyKey.
+     * Omit only for "once ever" notifications; pass an event id for anything repeatable.
+     */
+    dedupeKey?: string;
+    now?: Date;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,5 @@
+export declare const errorMessage: (e: unknown) => string;
+/** HTTP statuses worth trying again later. */
+export declare const retryableStatus: (status: number) => boolean;
+/** Parsed JSON, or undefined when [raw] is not JSON (provider error bodies are sometimes HTML). */
+export declare function tryJson<T>(raw: string): T | undefined;

package/dist/util.js

@@ -0,0 +1,12 @@
+export const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+/** HTTP statuses worth trying again later. */
+export const retryableStatus = (status) => status === 429 || status >= 500;
+/** Parsed JSON, or undefined when [raw] is not JSON (provider error bodies are sometimes HTML). */
+export function tryJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@devmonks/notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Plan-then-send notifications with an FCM HTTP v1 push adapter. No DB, no queue; the core entry has no dependencies. Optional email (Resend + React Email) and Drizzle entries.",
+  "license": "MIT",
+  "keywords": [
+    "fcm",
+    "firebase",
+    "push",
+    "notifications",
+    "drizzle",
+    "resend"
+  ],
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devmonks-co/notify.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./email": {
+      "types": "./dist/email/index.d.ts",
+      "import": "./dist/email/index.js"
+    },
+    "./drizzle": {
+      "types": "./dist/drizzle/index.d.ts",
+      "import": "./dist/drizzle/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "bun run typecheck && bun run test && bun run build"
+  },
+  "peerDependencies": {
+    "@react-email/components": ">=1",
+    "@react-email/render": ">=2",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "drizzle-orm": ">=0.40"
+  },
+  "peerDependenciesMeta": {
+    "@react-email/components": {
+      "optional": true
+    },
+    "@react-email/render": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.16",
+    "@react-email/components": "1.0.12",
+    "@react-email/render": "2.1.0",
+    "@types/node": "24",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "0.45.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  }
+}