dev-notify

Instant developer notifications for OTPs, errors, and events — right from Node.js.

Problem (what this solves)

During local development it is time-consuming and disruptive to verify runtime events:

• You generate an OTP but must open Mailtrap → inspect the message to copy the code.
• You debug an API that sends confirmation emails/SMS and have to query the database or mail provider to confirm delivery.
• Long-running jobs or CI tasks finish but you only discover results by refreshing logs or terminal output.
• In Docker/WSL environments native desktop notifications often fail silently, so you lose visibility.

Result: wasted context switches, slower feedback loops, and slower development/debug cycles.

dev-notify fixes this by delivering instant, developer-focused notifications (native desktop when available, console fallback otherwise) with an async, awaitable API that returns a status object you can persist or audit in your DB — just like nodemailer.sendMail() or SMS APIs do.

What it does (short)

• Sends cross-platform native desktop notifications (via node-notifier).
• Provides ergonomic shortcuts: success, error, info, warn.
• Async Promise-based API that returns a structured NotifierResponse for tracking.
• Safe console fallback when native notifications are unavailable (e.g., Docker, WSL).
• Small, single-file dependency and easy to wire into existing dev tooling.

Install

npm install dev-notify
# or
yarn add dev-notify

Quick usage (TypeScript / JavaScript)

import notify from "dev-notify";

// Simple shortcut usage
const res = await notify.success("OTP: 123456");
console.log(res);

// Custom notification
const r = await notify.notify({
  title: "Custom Notification",
  message: "This is a custom message.",
  sound: true,
  wait: false,
});
console.log(r);

Example NotifierResponse:

// success
{
  success: true,
  backend: "desktop",       // or "fallback"
  response: "...",          // raw response from node-notifier (may vary)
  metadata: { /* platform metadata */ }
}

// failure
{
  success: false,
  backend: "fallback",      // console fallback used
  error: "Error message"
}

Track notification status in your DB

Because dev-notify returns a status object, you can persist notification attempts (for auditing or debugging), exactly as you would for emails/SMS.

Example: save the returned result to a DB

import notify from "dev-notify";

async function sendOtpAndLog(userId: string, otp: string) {
  const result = await notify.success(`OTP for ${userId}: ${otp}`);

  // Example DB save (pseudo)
  await db.notifications.insert({
    user_id: userId,
    title: "OTP",
    message: `OTP for ${userId}: ${otp}`,
    backend: result.backend,
    success: result.success,
    error: result.error || null,
    response: result.response ? JSON.stringify(result.response) : null,
    metadata: result.metadata ? JSON.stringify(result.metadata) : null,
    created_at: new Date(),
  });
}

API Reference

notify.notify(options: NotifyOptions): Promise<NotifierResponse>

Send a custom notification.

• options.title: string (required)
• options.message: string (required)
• options.sound?: boolean (default true)
• options.wait?: boolean (default false)

Shortcuts (all return Promise<NotifierResponse>)

• notify.success(message: string)
• notify.error(message: string)
• notify.info(message: string)
• notify.warn(message: string)

Environment & fallback behavior

• Uses node-notifier under the hood:

  • macOS: native notification center
  • Windows: native toast notifications
  • Linux: notify-send (must be installed on many distros)

• If native notification fails (no display server or missing binaries), the library:

  • Logs a clear prefixed fallback line to console (so nothing is silent).
  • Returns { success: false, backend: "fallback", error: "..." }.

Tip: In container/remote workflows, plan to use dev-notify-bridge.

Best practices

• Use await and persist the returned object if you need a record of deliveries (recommended for reproducible debugging).
• Keep notifications concise (title + short message); use console logging for verbose details.
• For Docker/remote workflows, consider using dev-notify-bridge.

Why this package?

• Reduces developer friction and context switching while verifying ephemeral runtime artifacts (OTPs, short-lived codes, job completions).
• Matches the async, statusful patterns you already use for email/SMS APIs — enabling easy DB audit and consistent logging.

License

MIT © 2025