dev-notify/README.md

Lightweight developer notification tool for OTPs, errors, and events in local development.

---

# 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

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

---

## Quick usage (TypeScript / JavaScript)

```ts
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`**:

```ts
// 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

```ts
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`](https://github.com/mikaelbr/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`](https://npm.com/package/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`](https://npm.com/package/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

---