@beespoke/micro-server-push-firebase 0.0.0-stage → 2.0.5

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @beespoke/micro-server-push-firebase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Firebase Cloud Messaging notifications through the Firebase Admin SDK.
+
+Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-push-firebase
+```
+
+Use `bun add` in place of `npm install` for Bun projects.
+
+## Configure the plugin
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-push-firebase'],
+    pluginOptions: {
+        '@beespoke/micro-server-push-firebase': {
+            serviceAccount: './service-account.json',
+        },
+    },
+});
+```
+
+Supply your Firebase service-account JSON at the configured path. Keep credentials outside version control. `serviceAccount` also accepts an inline object; supported fields include `projectId`, `clientEmail`, and `privateKey`, or the JSON file's snake-case names. Alternatively supply `credential` or a credential through `appOptions`. Optional `appName` selects the Firebase app name; `configFile` supports application-owned legacy configuration.
+
+## Send a notification
+
+After bootstrap:
+
+```ts
+import { PushNotifier } from '@beespoke/micro-server-push-firebase';
+
+await PushNotifier.sendNotification(
+    process.env.DEVICE_TOKEN!,
+    { title: 'Order ready', body: 'Your order is ready for collection.' },
+    { orderId: '123' },
+);
+```
+
+`sendNotifications(tokens, message, metadata, options)` handles multiple recipients. `NotificationType` contains `title`, `body`, and optional `imageUrl`. Pass string metadata values for Firebase data messages. The package also exports `NotificationOptions` and `PushNotifierOptions`.
+
+The plugin initializes its Firebase app and registers cleanup. Standalone users own initialization and `PushNotifier.close()`.
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` or `node --env-file-if-exists=.env index.ts`. Node requires ESM (`"type": "module"` in package.json). When using Bun, load configuration secrets from the application environment or its `.env` file.
+
+## TypeScript and lifecycle
+
+Add this type-only import to an application-owned `plugin-types.d.ts` for configuration autocomplete:
+
+```ts
+import type {} from '@beespoke/micro-server-push-firebase/plugin';
+```
+
+Core validates plugin options before setup and owns cleanup after successful startup or startup failure. Await `ApplicationServer.bootstrap()` before using the configured client, and call `ApplicationServer.close()` during application shutdown. Importing the package does not open a connection. Relative plugin paths resolve from the selected configuration file's directory.
+
+The root export can also be used without HTTP core. In that case, explicitly initialize and close the client. The `/plugin` entry is the integration adapter for `@beespoke/micro-server`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as PushNotifier } from './utils/PushNotifier.js';
+export type { PushNotifierOptions } from './types/PushNotifierOptions.js';
+export type { NotificationType, NotificationOptions } from './types/NotificationTypes.js';

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/utils/PushNotifier.ts
+import admin from "firebase-admin";
+import { readFile } from "node:fs/promises";
+import { resolve, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// src/support.ts
+var consoleLogger = {
+  info: (...args) => console.info(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args),
+  debug: (...args) => console.debug(...args)
+};
+
+// src/utils/PushNotifier.ts
+class PushNotifier {
+  name = "push-firebase";
+  static FirebaseAdmin = admin;
+  static instance = 0;
+  static app;
+  static initializing;
+  static closing;
+  static logger = consoleLogger;
+  rootDir;
+  options;
+  configDir;
+  constructor(rootOrOptions = {}, options = {}) {
+    this.rootDir = typeof rootOrOptions === "string" ? resolve(rootOrOptions) : undefined;
+    this.options = typeof rootOrOptions === "string" ? options : rootOrOptions;
+  }
+  async setup(context) {
+    this.configDir = context.configDir;
+    PushNotifier.logger = context.logger;
+    await this.init(this.options, (cleanup) => context.onClose(cleanup));
+  }
+  async init(options = this.options, registerCleanup) {
+    if (PushNotifier.app || PushNotifier.initializing || PushNotifier.closing) {
+      throw new Error("Firebase push client is already initialized or changing state");
+    }
+    const root = this.rootDir ?? this.configDir ?? process.cwd();
+    const initialize = async () => {
+      const appOptions = { ...options.appOptions };
+      if (options.serviceAccount !== undefined) {
+        const account = typeof options.serviceAccount === "string" ? await this.readAccount(resolve(root, options.serviceAccount)) : options.serviceAccount;
+        appOptions.credential = PushNotifier.FirebaseAdmin.credential.cert(account);
+      } else if (options.credential) {
+        appOptions.credential = options.credential;
+      } else if (!options.appOptions) {
+        const account = await this.readAccount(resolve(root, options.configFile ?? "notif.config.ts"));
+        appOptions.credential = PushNotifier.FirebaseAdmin.credential.cert(account);
+      }
+      const app = PushNotifier.FirebaseAdmin.initializeApp(appOptions, options.appName);
+      PushNotifier.app = app;
+      PushNotifier.instance = 1;
+      try {
+        registerCleanup?.(() => PushNotifier.close());
+      } catch (error) {
+        try {
+          await app.delete();
+        } finally {
+          PushNotifier.app = undefined;
+          PushNotifier.instance = 0;
+        }
+        throw error;
+      }
+    };
+    PushNotifier.initializing = initialize();
+    try {
+      await PushNotifier.initializing;
+    } finally {
+      PushNotifier.initializing = undefined;
+    }
+  }
+  async readAccount(path) {
+    if (extname(path) === ".json")
+      return JSON.parse(await readFile(path, "utf8"));
+    const module = await import(pathToFileURL(path).href);
+    if (!module.default || typeof module.default !== "object") {
+      throw new Error(`Firebase configuration must export a default service account: ${path}`);
+    }
+    return module.default;
+  }
+  static close() {
+    if (PushNotifier.closing)
+      return PushNotifier.closing;
+    PushNotifier.closing = (async () => {
+      try {
+        await PushNotifier.initializing;
+        await PushNotifier.app?.delete();
+      } finally {
+        PushNotifier.app = undefined;
+        PushNotifier.instance = 0;
+        PushNotifier.logger = consoleLogger;
+      }
+    })().finally(() => {
+      PushNotifier.closing = undefined;
+    });
+    return PushNotifier.closing;
+  }
+  static async sendNotifications(tokens, message, metadata = {}, options) {
+    try {
+      if (!PushNotifier.app)
+        throw new Error("Firebase push client is not initialized. Call `init()` first.");
+      const params = tokens.map((token) => ({ token, notification: message, data: metadata }));
+      return await PushNotifier.FirebaseAdmin.messaging(PushNotifier.app).sendEach(params);
+    } catch (error) {
+      PushNotifier.logger.error(error);
+      return;
+    }
+  }
+  static async sendNotification(token, message, metadata = {}, options) {
+    try {
+      if (!PushNotifier.app)
+        throw new Error("Firebase push client is not initialized. Call `init()` first.");
+      return await PushNotifier.FirebaseAdmin.messaging(PushNotifier.app).send({ token, notification: message, data: metadata });
+    } catch (error) {
+      PushNotifier.logger.error(error);
+      return;
+    }
+  }
+}
+export {
+  PushNotifier
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,10 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+import { type PushNotifierOptions } from '../index.js';
+export type FirebasePluginOptions = PushNotifierOptions;
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-push-firebase': FirebasePluginOptions;
+    }
+}
+declare const definition: PluginDefinition<FirebasePluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,67 @@
+// src/plugin/index.ts
+import { PushNotifier } from "../index.js";
+function object(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function credential(value, field) {
+  if (!object(value) || typeof value.getAccessToken !== "function")
+    throw new Error(`Firebase ${field} must implement getAccessToken`);
+}
+var definition = {
+  name: "@beespoke/micro-server-push-firebase",
+  validate(options) {
+    if (!object(options))
+      throw new Error("Firebase options must be an object");
+    const keys = ["serviceAccount", "credential", "appOptions", "appName", "configFile"];
+    if (Object.keys(options).some((key) => !keys.includes(key)))
+      throw new Error("Firebase options contain an unknown field");
+    for (const key of ["appName", "configFile"]) {
+      if (options[key] !== undefined && (typeof options[key] !== "string" || !options[key].trim()))
+        throw new Error(`Firebase ${key} must be a nonempty string`);
+    }
+    if (options.serviceAccount !== undefined) {
+      const account = options.serviceAccount;
+      if (typeof account === "string") {
+        if (!account.trim())
+          throw new Error("Firebase serviceAccount must be a nonempty path or service account object");
+      } else {
+        if (!object(account))
+          throw new Error("Firebase serviceAccount must be a path or service account object");
+        for (const [camel, snake] of [["projectId", "project_id"], ["clientEmail", "client_email"], ["privateKey", "private_key"]]) {
+          const value = account[camel] ?? account[snake];
+          if (typeof value !== "string" || !value.trim())
+            throw new Error(`Firebase serviceAccount.${camel} must be a nonempty string`);
+        }
+      }
+    }
+    if (options.credential !== undefined)
+      credential(options.credential, "credential");
+    if (options.appOptions !== undefined) {
+      const app = options.appOptions;
+      if (!object(app))
+        throw new Error("Firebase appOptions must be an object");
+      const appKeys = ["credential", "databaseAuthVariableOverride", "databaseURL", "serviceAccountId", "storageBucket", "projectId", "httpAgent"];
+      if (Object.keys(app).some((key) => !appKeys.includes(key)))
+        throw new Error("Firebase appOptions contain an unknown field");
+      if (app.credential !== undefined)
+        credential(app.credential, "appOptions.credential");
+      for (const key of ["databaseURL", "serviceAccountId", "storageBucket", "projectId"]) {
+        if (app[key] !== undefined && (typeof app[key] !== "string" || !app[key].trim()))
+          throw new Error(`Firebase appOptions.${key} must be a nonempty string`);
+      }
+      if (app.databaseAuthVariableOverride !== undefined && app.databaseAuthVariableOverride !== null && !object(app.databaseAuthVariableOverride))
+        throw new Error("Firebase appOptions.databaseAuthVariableOverride must be an object or null");
+      if (app.httpAgent !== undefined && (!object(app.httpAgent) || typeof app.httpAgent.addRequest !== "function"))
+        throw new Error("Firebase appOptions.httpAgent must be an HTTP agent");
+    }
+    if (options.serviceAccount === undefined && options.credential === undefined && options.appOptions === undefined && options.configFile === undefined)
+      throw new Error("Firebase requires serviceAccount, credential, appOptions or configFile");
+  },
+  create(options) {
+    return new PushNotifier(options);
+  }
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/dist/support.d.ts

@@ -0,0 +1,18 @@
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+export type LifecycleHook = () => void | Promise<void>;
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly configDir: string;
+    onStart(hook: LifecycleHook): void;
+    onClose(hook: LifecycleHook): void;
+}
+export interface ServerPlugin {
+    readonly name: string;
+    setup(context: PluginContext): void | Promise<void>;
+}
+export declare const consoleLogger: Logger;

package/dist/types/NotificationTypes.d.ts

@@ -0,0 +1,8 @@
+export type NotificationType = {
+    title: string;
+    body: string;
+    imageUrl?: string;
+};
+export type NotificationOptions = {
+    isBroadcast?: Boolean;
+};

package/dist/types/PushNotifierOptions.d.ts

@@ -0,0 +1,10 @@
+import type { AppOptions, Credential, ServiceAccount } from 'firebase-admin/app';
+export interface PushNotifierOptions {
+    /** Credentials supplied here take precedence over notif.config.ts. Paths resolve against the plugin root/config directory. */
+    serviceAccount?: ServiceAccount | string;
+    credential?: Credential;
+    appOptions?: AppOptions;
+    appName?: string;
+    /** Legacy configuration fallback; defaults to notif.config.ts. */
+    configFile?: string;
+}

package/dist/utils/PushNotifier.d.ts

@@ -0,0 +1,28 @@
+import admin from 'firebase-admin';
+import type { BatchResponse } from 'firebase-admin/messaging';
+import type { PluginContext, ServerPlugin } from '../support.js';
+import type { NotificationType, NotificationOptions } from '../types/NotificationTypes.js';
+import type { PushNotifierOptions } from '../types/PushNotifierOptions.js';
+type Cleanup = () => void | Promise<void>;
+export default class PushNotifier implements ServerPlugin {
+    readonly name = "push-firebase";
+    static FirebaseAdmin: typeof admin;
+    static instance: number;
+    private static app;
+    private static initializing;
+    private static closing;
+    private static logger;
+    private readonly rootDir;
+    private readonly options;
+    private configDir;
+    constructor(options?: PushNotifierOptions);
+    constructor(path: string, options?: PushNotifierOptions);
+    setup(context: PluginContext): Promise<void>;
+    /** Explicit standalone initialization; constructing this class only records options. */
+    init(options?: PushNotifierOptions, registerCleanup?: (cleanup: Cleanup) => void): Promise<void>;
+    private readAccount;
+    static close(): Promise<void>;
+    static sendNotifications(tokens: string[], message: NotificationType, metadata?: any, options?: NotificationOptions): Promise<BatchResponse | undefined>;
+    static sendNotification(token: string, message: NotificationType, metadata?: any, options?: NotificationOptions): Promise<string | undefined>;
+}
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@beespoke/micro-server-push-firebase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.5",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts",
+    "test": "bun test tests"
+  },
+  "dependencies": {
+    "firebase-admin": "^12.4.0",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}