@frigear-nu/notify 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @frigear-nu/notify
 
-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.
+Generic notification driver/dispatch Nuxt module. Lets feature modules (e.g. `@frigear-nu/users`)
+dispatch email/SMS/simple notifications, and push UI toasts, without ever deciding how they're
+delivered - that choice (and configuration) belongs to the app/consuming layer.
+
+## Quick Setup
+
+Other modules declare `@frigear-nu/notify` as a `moduleDependency`, so it's installed
+automatically wherever they're used - you don't need to add it to `modules` yourself unless you
+want to configure it.
+
+## Configuration
+
+Configure the module via the `notify` key in `nuxt.config.ts`. Every notification type (`email`,
+`sms`, `simple`) defaults to the built-in `log` driver (logs instead of sending) - only the
+`ui` driver has no default, since there's no sensible UI to push to unless you configure one:
+
+```ts
+export default defineNuxtConfig({
+  notify: {
+    email: {
+      // Name of a built-in driver (`'log'`, the default - logs instead of sending) or a path to
+      // a function (default export) matching the `EmailDriver` signature, for a real provider
+      // (Resend, SMTP, ...).
+      driver: '~/server/utils/resend-email-driver',
+    },
+    sms: {
+      // Same idea, matching the `SMSDriver` signature, for a real provider (Twilio, ...).
+      driver: '~/server/utils/twilio-sms-driver',
+    },
+    simple: {
+      // Same idea, matching the `SimpleDriver` signature, for generic push notifications.
+      driver: 'log',
+    },
+    ui: {
+      // Built-in `'@nuxt/ui'` driver (forwards to `@nuxt/ui`'s `useToast`), or a path to a
+      // function (default export) matching the `UIDriver` signature - a composable factory
+      // invoked once, synchronously, during `useNotify()`'s own setup-time call.
+      driver: '@nuxt/ui',
+    },
+  },
+})
+```
+
+Only the configured driver for each notification type is ever resolved/loaded - unconfigured
+drivers (e.g. the `ui` driver when `notify.ui` isn't set) are never bundled, to keep the client
+bundle small.
+
+#### Example Custom Driver
+
+```ts
+// server/utils/resend-email-driver.ts
+import type { EmailDriver } from '@frigear-nu/notify/types'
+
+const sendWithResend: EmailDriver = async (notification) => {
+  // ... call your provider's API with notification.to/subject/body/text
+}
+
+export default sendWithResend
+```
+
+## Usage
+
+### Server-side dispatch
+
+`dispatchEmailNotification`, `dispatchSMSNotification`, and `dispatchSimpleNotification` are
+auto-imported server-side wherever this module is installed:
+
+```ts
+await dispatchEmailNotification({
+  to: user.email,
+  subject: 'Welcome!',
+  body: '<p>Thanks for signing up.</p>',
+  text: 'Thanks for signing up.',
+})
+
+await dispatchSMSNotification({
+  to: user.phone,
+  body: 'Your verification code is 123456.',
+})
+
+await dispatchSimpleNotification({
+  title: 'New signup',
+  text: `${user.email} just signed up.`,
+})
+```
+
+### UI notifications
+
+When `notify.ui.driver` is configured, `useNotify` is auto-imported client-side to push
+`UINotification`s through the configured driver (e.g. `@nuxt/ui`'s `useToast`):
+
+```vue
+<script setup lang="ts">
+const notify = useNotify()
+
+function onSuccess() {
+  notify.addNotification(defineUINotification({
+    title: 'Saved',
+    text: 'Your changes have been saved.',
+    type: 'success',
+  }))
+}
+</script>
+```

package/dist/module.d.mts

@@ -0,0 +1,94 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+type NotificationMeta<AdditionalMeta = Record<string, unknown>> = {
+    driver?: string;
+} & AdditionalMeta;
+/**
+ * Generic, transport-agnostic push notification. Concrete notifications (e.g. a password reset)
+ * build one of these and hand it to `dispatchPushNotification`, similar in spirit to how Laravel
+ * notifications render themselves to a `toMail()` payload before a channel sends it.
+ */
+interface SimpleNotification<M = Record<string, unknown>> {
+    title: string;
+    text: string;
+    /** Optional URL to open when the notification is clicked. */
+    url?: string;
+    meta?: M;
+}
+/**
+ * A notification that is intended to be displayed in the UI, e.g. via a toast or snackbar.
+ * The `type` field can be used to determine the styling of the notification.
+ */
+interface UINotification<A = unknown, M = NotificationMeta> extends SimpleNotification<M> {
+    type?: 'success' | 'error' | 'info' | 'warning';
+    actions?: A[];
+    meta?: M;
+}
+/**
+ * Generic, transport-agnostic SMS notification. Concrete notifications (e.g. a password reset)
+ * build one of these and hand it to `dispatchSMSNotification`, similar in spirit to how Laravel
+ * notifications render themselves to a `toMail()` payload before a channel sends it.
+ */
+interface SMSNotification<M = NotificationMeta> {
+    to: string | string[];
+    body: string;
+    meta?: M;
+}
+/**
+ * Generic, transport-agnostic email notification. Concrete notifications (e.g. a password reset)
+ * build one of these and hand it to `dispatchEmailNotification`, similar in spirit to how Laravel
+ * notifications render themselves to a `toMail()` payload before a channel sends it.
+ */
+interface EmailNotification<M = NotificationMeta> {
+    to: string | string[];
+    subject: string;
+    /** HTML body. */
+    body: string;
+    /** Optional plain-text body. */
+    text?: string;
+    meta?: M;
+}
+/**
+ * A driver is anything that knows how to actually deliver an `EmailNotification` - log it,
+ * hand it to Resend, talk to an SMTP server, etc. Keeping the signature this small makes it
+ * trivial to plug in new drivers without this module depending on any of them.
+ */
+type SimpleDriver = (notification: SimpleNotification) => Promise<void> | void;
+type SMSDriver = (notification: SMSNotification) => Promise<void> | void;
+type EmailDriver = (notification: EmailNotification) => Promise<void> | void;
+/**
+ * Unlike the server-side drivers above, a UI driver is a *composable factory*: `useNotify()` calls
+ * it once, synchronously, during its own (setup-time) invocation, and uses the function it returns
+ * to actually dispatch notifications later. This is required because driver implementations that
+ * need Vue's `inject()` (e.g. the built-in `@nuxt/ui` driver's `useToast()`) only work when called
+ * during a component's `setup()` - resolving them lazily, when a notification is dispatched (e.g.
+ * from a `setInterval` callback), runs outside any component and breaks `inject()`.
+ */
+type UIDriver = () => (notification: UINotification) => Promise<void> | void;
+type ModuleOptions = {
+    email?: {
+        driver?: string | 'log';
+    };
+    sms?: {
+        driver?: string | 'log';
+    };
+    simple?: {
+        driver?: string | 'log';
+    };
+    push?: {
+        driver?: string;
+    };
+    ui?: {
+        driver?: string | '@nuxt/ui';
+    };
+};
+
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        notify?: ModuleOptions;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { EmailDriver, EmailNotification, ModuleOptions, SMSDriver, SMSNotification, SimpleDriver, SimpleNotification, UIDriver, UINotification };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/notify",
+  "configKey": "notify",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,98 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addImports, addTemplate, addTypeTemplate, addServerImportsDir, addServerTemplate } from '@nuxt/kit';
+import { joinURL } from 'ufo';
+
+const BUILTIN_UI_DRIVERS = {
+  "log": { path: "./runtime/drivers/log", exportName: "logUIDriver" },
+  "@nuxt/ui": { path: "./runtime/drivers/ui/nuxt.ui", exportName: "default" }
+};
+const BUILTIN_SERVER_DRIVERS = {
+  log: { path: "./runtime/drivers/log", exportName: "logDriver" }
+};
+const module$1 = defineNuxtModule({
+  meta: { name: "@frigear-nu/notify", configKey: "notify" },
+  defaults: {
+    email: { driver: "log" },
+    sms: { driver: "log" },
+    simple: { driver: "log" }
+  },
+  moduleDependencies: {
+    "@nuxt/ui": {
+      optional: true,
+      version: ">=4.10"
+    }
+  },
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    if (options.ui?.driver) {
+      if (options.ui.driver === "@nuxt/ui" && !hasNuxtModule("@nuxt/ui")) {
+        throw new Error(`@nuxt/ui driver is configured but @nuxt/ui module is not installed. Please install @nuxt/ui or configure a different UI driver.`);
+      }
+      addImports({
+        name: "useNotify",
+        as: "useNotify",
+        from: resolver.resolve("./runtime/app/composables/useNotify")
+      });
+      addImports({
+        name: "defineUINotification",
+        as: "defineUINotification",
+        from: resolver.resolve("./runtime/server/utils/definers")
+      });
+      const uiDriverTemplate = addTemplate({
+        filename: "#notify/ui-driver.ts",
+        write: true,
+        getContents: async () => {
+          const builtin = BUILTIN_UI_DRIVERS[options.ui?.driver];
+          if (builtin) {
+            return `export { ${builtin.exportName} as default } from ${JSON.stringify(await resolver.resolvePath(builtin.path))}`;
+          }
+          if (!options.ui?.driver) {
+            throw new Error(`Invalid UI driver: ${options.ui?.driver || "undefined"}`);
+          }
+          const driverPath = await resolver.resolvePath(options.ui.driver, { cwd: nuxt.options.rootDir });
+          return `export { default } from ${JSON.stringify(driverPath)}`;
+        }
+      });
+      nuxt.options.alias["#notify/ui-driver"] = uiDriverTemplate.dst;
+      addTypeTemplate({
+        filename: "types/notify-ui-driver.d.ts",
+        getContents: () => `declare module '#notify/ui-driver' {
+  import type { UIDriver } from ${JSON.stringify(resolver.resolve("./types"))}
+  const driver: UIDriver
+  export default driver
+}
+`
+      });
+      const registerServerDriver = (name, driverType, driver) => {
+        const filename = `#notify/${name}`;
+        const template = addServerTemplate({
+          filename,
+          getContents: async () => {
+            const builtin = BUILTIN_SERVER_DRIVERS[driver];
+            if (builtin) {
+              return `export { ${builtin.exportName} as default } from ${JSON.stringify(await resolver.resolvePath(builtin.path))}`;
+            }
+            const driverPath = await resolver.resolvePath(driver, { cwd: nuxt.options.rootDir });
+            return `export { default } from ${JSON.stringify(driverPath)}`;
+          }
+        });
+        nuxt.options.nitro.alias ||= {};
+        nuxt.options.nitro.alias[`#notify/${name}`] = joinURL(template.filename, ".ts");
+        addTypeTemplate({
+          filename: `types/notify-${name}.d.ts`,
+          getContents: () => `declare module '#notify/${name}' {
+  import type { ${driverType} } from ${JSON.stringify(resolver.resolve("./types"))}
+  const driver: ${driverType}
+  export default driver
+}
+`
+        }, { nitro: true, nuxt: true });
+      };
+      registerServerDriver("email-driver", "EmailDriver", options.email?.driver ?? "log");
+      registerServerDriver("sms-driver", "SMSDriver", options.sms?.driver ?? "log");
+      registerServerDriver("simple-driver", "SimpleDriver", options.simple?.driver ?? "log");
+      addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/composables/useNotify.d.ts

@@ -0,0 +1,11 @@
+import type { UINotification } from '../../../types.js';
+/**
+ * App-side composable for pushing `UINotification`s through the configured UI driver (e.g. the
+ * `@nuxt/ui` driver, which forwards them to `useToast`). Only registered when `notify.ui.driver`
+ * is configured - see `setup()` in the module.
+ */
+export declare const useNotify: () => {
+    notifications: import("vue").Ref<UINotification<unknown, import("../../../types.js").NotificationMeta<Record<string, unknown>>>[], UINotification<unknown, import("../../../types.js").NotificationMeta<Record<string, unknown>>>[]>;
+    addNotification: (notification: UINotification) => any;
+    add: (notification: UINotification) => any;
+};

package/dist/runtime/app/composables/useNotify.js

@@ -0,0 +1,16 @@
+import { useState } from "#imports";
+import uiDriver from "#notify/ui-driver";
+export const useNotify = () => {
+  const notifications = useState("notify-notifications", () => []);
+  const dispatch = uiDriver();
+  const add = (notification) => {
+    notifications.value.push(notification);
+    return dispatch(notification);
+  };
+  return {
+    notifications,
+    // `addNotification` is an alias for `add` to make the API more explicit and self-documenting
+    addNotification: add,
+    add
+  };
+};

package/dist/runtime/drivers/log.d.ts

@@ -0,0 +1,14 @@
+import type { SimpleNotification, UINotification, SMSNotification, EmailNotification, UIDriver } from '../../types.js';
+/**
+ * Logs the notification instead of sending it. Safe default for development/unconfigured setups,
+ * and a reference implementation for the `EmailDriver` signature.
+ */
+export declare const logDriver: (notification: SimpleNotification | UINotification | SMSNotification | EmailNotification) => void;
+/**
+ * `UIDriver`-shaped version of `logDriver` - unlike the server-side drivers, UI drivers are
+ * composable factories (see `UIDriver`'s doc comment), so this just wraps `logDriver` in one to
+ * use as the built-in `'log'` UI driver. Doesn't call any Vue composables itself, so there's
+ * nothing `inject()`-sensitive here - it works the same called eagerly or lazily.
+ */
+export declare const logUIDriver: UIDriver;
+export default logDriver;

package/dist/runtime/drivers/log.js

@@ -0,0 +1,5 @@
+export const logDriver = (notification) => {
+  console.log("[notify] Dispatching notification:", notification);
+};
+export const logUIDriver = () => (notification) => logDriver(notification);
+export default logDriver;

package/dist/runtime/drivers/ui/nuxt.ui.d.ts

@@ -0,0 +1,2 @@
+declare const nuxtUiDriver: import("../../../types.js").UIDriver;
+export default nuxtUiDriver;

package/dist/runtime/drivers/ui/nuxt.ui.js

@@ -0,0 +1,20 @@
+import { useToast } from "#imports";
+import { defineUIDriver } from "../../server/utils/definers.js";
+const COLOR_BY_TYPE = {
+  success: "success",
+  error: "error",
+  warning: "warning",
+  info: "info"
+};
+const nuxtUiDriver = defineUIDriver(() => {
+  const toast = useToast();
+  return (notification) => {
+    toast.add({
+      title: notification.title,
+      description: notification.text,
+      color: COLOR_BY_TYPE[notification?.type ?? "info"],
+      actions: notification?.actions
+    });
+  };
+});
+export default nuxtUiDriver;

package/dist/runtime/server/utils/definers.d.ts

@@ -0,0 +1,9 @@
+import type { SimpleDriver, UIDriver, SMSDriver, EmailDriver, SimpleNotification, UINotification, SMSNotification, EmailNotification } from '../../../types.js';
+export declare const defineSimpleNotification: <T extends SimpleNotification>(notification: T) => T;
+export declare const defineUINotification: <T extends UINotification>(notification: T) => T;
+export declare const defineEmailNotification: <T extends EmailNotification>(notification: T) => T;
+export declare const defineSMSNotification: <T extends SMSNotification>(notification: T) => T;
+export declare const defineSimpleDriver: (driver: SimpleDriver) => SimpleDriver;
+export declare const defineUIDriver: (driver: UIDriver) => UIDriver;
+export declare const defineSMSDriver: (driver: SMSDriver) => SMSDriver;
+export declare const defineEmailDriver: (driver: EmailDriver) => EmailDriver;

package/dist/runtime/server/utils/definers.js

@@ -0,0 +1,8 @@
+export const defineSimpleNotification = (notification) => notification;
+export const defineUINotification = (notification) => notification;
+export const defineEmailNotification = (notification) => notification;
+export const defineSMSNotification = (notification) => notification;
+export const defineSimpleDriver = (driver) => driver;
+export const defineUIDriver = (driver) => driver;
+export const defineSMSDriver = (driver) => driver;
+export const defineEmailDriver = (driver) => driver;

package/dist/runtime/server/utils/dispatch.d.ts

@@ -0,0 +1,22 @@
+import type { EmailNotification, SMSNotification, SimpleNotification } from '../../../types.js';
+/**
+ * Dispatches an email notification through the driver configured on the `@frigear-nu/notify`
+ * module (`notify.email.driver`, see `#notify/email-driver`). Auto-imported wherever this module
+ * is installed, so consumers (e.g. `@frigear-nu/users`) only ever build an `EmailNotification`
+ * and call this - driver selection stays entirely with the app/consuming layer.
+ */
+export declare function dispatchEmailNotification(notification: EmailNotification): Promise<any>;
+/**
+ * Dispatches an SMS notification through the driver configured on the `@frigear-nu/notify`
+ * module (`notify.sms.driver`, see `#notify/sms-driver`). Auto-imported wherever this module is
+ * installed, so consumers only ever build an `SMSNotification` and call this - driver selection
+ * stays entirely with the app/consuming layer.
+ */
+export declare function dispatchSMSNotification(notification: SMSNotification): Promise<void>;
+/**
+ * Dispatches a generic, transport-agnostic notification through the driver configured on the
+ * `@frigear-nu/notify` module (`notify.simple.driver`, see `#notify/simple-driver`). Auto-imported
+ * wherever this module is installed, so consumers only ever build a `SimpleNotification` and call
+ * this - driver selection stays entirely with the app/consuming layer.
+ */
+export declare function dispatchSimpleNotification(notification: SimpleNotification): Promise<void>;

package/dist/runtime/server/utils/dispatch.js

@@ -0,0 +1,11 @@
+import smsDriver from "#notify/sms-driver";
+import simpleDriver from "#notify/simple-driver";
+export async function dispatchEmailNotification(notification) {
+  return import("#notify/email-driver").then(({ default: emailDriver }) => emailDriver(notification));
+}
+export async function dispatchSMSNotification(notification) {
+  await smsDriver(notification);
+}
+export async function dispatchSimpleNotification(notification) {
+  await simpleDriver(notification);
+}

package/dist/runtime/stores/memory.d.ts

@@ -0,0 +1,2 @@
+import type { NotificationStore } from '../../types.js';
+export declare const memoryStore: () => NotificationStore;

package/dist/runtime/stores/memory.js

@@ -0,0 +1,25 @@
+export const memoryStore = () => {
+  const notifications = [];
+  return {
+    async put(notification) {
+      const existingIndex = notifications.findIndex((n) => n.id === notification.id);
+      if (existingIndex !== -1) {
+        notifications[existingIndex] = notification;
+      } else {
+        notifications.push(notification);
+      }
+    },
+    async get(id) {
+      return notifications.find((n) => n.id === id) || null;
+    },
+    async list() {
+      return [...notifications];
+    },
+    async delete(id) {
+      const index = notifications.findIndex((n) => n.id === id);
+      if (index !== -1) {
+        notifications.splice(index, 1);
+      }
+    }
+  };
+};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type EmailDriver, type EmailNotification, type ModuleOptions, type SMSDriver, type SMSNotification, type SimpleDriver, type SimpleNotification, type UIDriver, type UINotification } from './module.mjs'

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@frigear-nu/notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "type": "module",
+  "description": "Framework-agnostic email notification driver/dispatch Nuxt module, shared across Frigear modules.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/notify"
+  },
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.6.0",
+    "ufo": "^1.6.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "eslint": "^10.12.0",
+    "typescript": "^6.0.3",
+    "nuxt": "^4.6.0",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "optionalDependencies": {
+    "@nuxt/ui": ">=4.10.0"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }