@ayush0x44/notifystack 1.0.0

package/README.md

@@ -0,0 +1,67 @@
+# NotifyStack Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/@ayush0x44/notifystack.svg)](https://www.npmjs.com/package/@ayush0x44/notifystack)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Node.js SDK for **NotifyStack** — a high-performance, distributed notification SaaS platform. Send Emails, SMS, Push, and In-App notifications with a single unified API.
+
+## 🚀 Features
+
+- **Zero Dependencies**: Lightweight and fast (uses native `fetch`).
+- **Unified API**: One interface for all channels (Email, SMS, Push, In-App).
+- **Auto-Retry**: Built-in exponential backoff for network flakes.
+- **Idempotency**: Safe retries without duplicate notifications.
+- **Batching**: Send up to 100 notifications in a single call.
+
+## 📦 Installation
+
+```bash
+npm install @ayush0x44/notifystack
+```
+
+## 🛠️ Quick Start
+
+```javascript
+const { NotifySDK } = require("@ayush0x44/notifystack");
+
+// Initialize the client
+const notify = new NotifySDK("ntf_live_your_api_key", {
+  baseUrl: "https://notificationsaas.onrender.com" // Point to your cloud API
+});
+
+async function main() {
+  // 1. Send an Event-based notification (uses templates)
+  await notify.track("ORDER_PLACED", {
+    email: "customer@example.com",
+    orderId: "ORD-123"
+  });
+
+  // 2. Send a direct Email
+  await notify.send({
+    to: "hello@world.com",
+    subject: "Welcome!",
+    body: "Thanks for joining our platform."
+  });
+
+  // 3. Send an SMS
+  await notify.sendSms({
+    to: "+1234567890",
+    body: "Your verification code is 1234"
+  });
+}
+
+main().catch(console.error);
+```
+
+## ⚙️ Configuration
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `baseUrl` | `string` | `http://localhost:3000` | The URL of your NotifyStack API |
+| `maxRetries` | `number` | `3` | Max attempts for failed requests |
+| `timeoutMs` | `number` | `10000` | Request timeout duration |
+| `debug` | `boolean` | `false` | Enable verbose logging |
+
+## 📖 License
+
+MIT © [Ayush](https://github.com/ayush462)

package/index.d.ts

@@ -0,0 +1,67 @@
+declare class NotifySDK {
+  constructor(apiKey: string, options?: {
+    baseUrl?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+    debug?: boolean;
+  });
+
+  /** Send event-based notification using a template */
+  track(eventName: string, data: Record<string, any> & { email: string }, options?: {
+    metadata?: Record<string, any>;
+    channel?: "email" | "sms" | "push";
+    priority?: "low" | "normal" | "high";
+  }): Promise<{ id: string; status: string }>;
+
+  /** Send a direct email */
+  send(params: {
+    to: string;
+    subject: string;
+    body: string;
+    metadata?: Record<string, any>;
+  }): Promise<{ id: string; status: string }>;
+
+  /** Send an SMS */
+  sendSms(params: {
+    to: string;
+    body: string;
+    metadata?: Record<string, any>;
+  }): Promise<{ id: string; status: string }>;
+
+  /** Send a push notification */
+  sendPush(params: {
+    token: string;
+    title: string;
+    body: string;
+    data?: Record<string, any>;
+    metadata?: Record<string, any>;
+  }): Promise<{ id: string; status: string }>;
+
+  /** Send batch notifications (max 100) */
+  sendBatch(notifications: Array<Record<string, any>>): Promise<{
+    results: Array<{ index: number; id: string; status: string }>;
+    errors: Array<{ index: number; error: string }>;
+    total: number;
+    succeeded: number;
+    failed: number;
+  }>;
+
+  /** List notifications */
+  listNotifications(params?: {
+    limit?: number;
+    offset?: number;
+    status?: string;
+  }): Promise<any>;
+
+  /** Check API health */
+  health(): Promise<{ ok: boolean }>;
+}
+
+declare class NotifyError extends Error {
+  status: number;
+  response: any;
+  constructor(message: string, status: number, response: any);
+}
+
+export = NotifySDK;
+export { NotifyError };

package/index.js

@@ -0,0 +1,267 @@
+const crypto = require("crypto");
+
+/**
+ * NotifyStack SDK — Production-grade notification client.
+ *
+ * Supports: Email, SMS, Push notifications
+ * Features: Auto-retry, idempotency, batch sending, debug mode, rate limit handling
+ *
+ * Usage:
+ *   const NotifySDK = require("notify-saas-sdk");
+ *   const notify = new NotifySDK("ntf_live_xxxxxxxxx");
+ *   await notify.track("USER_LOGIN", { email: "user@email.com", name: "Ayush" });
+ */
+class NotifySDK {
+  /**
+   * @param {string} apiKey - Your NotifyStack API key (ntf_live_xxx)
+   * @param {object} [options]
+   * @param {string} [options.baseUrl="http://localhost:3000"] - API base URL
+   * @param {number} [options.maxRetries=3] - Max retry attempts
+   * @param {number} [options.timeoutMs=10000] - Request timeout in ms
+   * @param {boolean} [options.debug=false] - Enable verbose logging
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey || !apiKey.startsWith("ntf_live_")) {
+      throw new Error("Invalid API key. Must start with 'ntf_live_'");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || "http://localhost:3000").replace(/\/$/, "");
+    this.maxRetries = options.maxRetries ?? 3;
+    this.timeoutMs = options.timeoutMs ?? 10000;
+    this.debug = options.debug || false;
+  }
+
+  _log(...args) {
+    if (this.debug) console.log("[NotifySDK]", ...args);
+  }
+
+  /**
+   * Send an event-based notification using a registered template.
+   * @param {string} eventName - Event name (e.g. "USER_LOGIN", "ORDER_PLACED")
+   * @param {object} data - Template variables (must include `email`)
+   * @param {object} [options] - { metadata, channel, priority }
+   * @returns {Promise<{id: string, status: string}>}
+   */
+  async track(eventName, data, options = {}) {
+    if (!eventName) throw new Error("eventName is required");
+    if (!data || !data.email) throw new Error("data.email is required for event-based notifications");
+
+    this._log(`track(${eventName})`, data);
+    return this._request("POST", "/v1/notifications", {
+      event: eventName,
+      data,
+      channel: options.channel || "email",
+      metadata: options.metadata || options
+    });
+  }
+
+  /**
+   * Send a direct email notification (no template).
+   * @param {object} params
+   * @param {string} params.to - Recipient email
+   * @param {string} params.subject - Email subject
+   * @param {string} params.body - Email body
+   * @param {object} [params.metadata]
+   * @returns {Promise<{id: string, status: string}>}
+   */
+  async send({ to, subject, body, metadata }) {
+    if (!to || !subject || !body) throw new Error("to, subject, and body are required");
+
+    this._log(`send() to=${to}`);
+    return this._request("POST", "/v1/notifications", {
+      recipientEmail: to,
+      subject,
+      body,
+      channel: "email",
+      metadata
+    });
+  }
+
+  /**
+   * Send an SMS notification.
+   * @param {object} params
+   * @param {string} params.to - Phone number (E.164 format)
+   * @param {string} params.body - SMS body (max 1600 chars)
+   * @param {object} [params.metadata]
+   * @returns {Promise<{id: string, status: string}>}
+   */
+  async sendSms({ to, body, metadata }) {
+    if (!to || !body) throw new Error("to and body are required");
+    if (body.length > 1600) throw new Error("SMS body exceeds 1600 character limit");
+
+    this._log(`sendSms() to=${to}`);
+    return this._request("POST", "/v1/notifications", {
+      recipientPhone: to,
+      subject: "SMS",
+      body,
+      channel: "sms",
+      metadata
+    });
+  }
+
+  /**
+   * Send a push notification.
+   * @param {object} params
+   * @param {string} params.token - Device token or subscription JSON
+   * @param {string} params.title - Notification title
+   * @param {string} params.body - Notification body
+   * @param {object} [params.data] - Custom data payload
+   * @param {object} [params.metadata]
+   * @returns {Promise<{id: string, status: string}>}
+   */
+  async sendPush({ token, title, body, data, metadata }) {
+    if (!token || !title || !body) throw new Error("token, title, and body are required");
+
+    this._log(`sendPush() title=${title}`);
+    return this._request("POST", "/v1/notifications", {
+      deviceToken: token,
+      subject: title,
+      body,
+      channel: "push",
+      metadata: { ...metadata, pushData: data }
+    });
+  }
+
+  /**
+   * Send multiple notifications in a batch.
+   * @param {Array<object>} notifications - Array of notification payloads
+   * @returns {Promise<Array<{id: string, status: string}>>}
+   */
+  async sendBatch(notifications) {
+    if (!Array.isArray(notifications) || !notifications.length) {
+      throw new Error("notifications must be a non-empty array");
+    }
+    if (notifications.length > 100) {
+      throw new Error("Batch size cannot exceed 100");
+    }
+
+    this._log(`sendBatch() count=${notifications.length}`);
+    const results = [];
+    const errors = [];
+
+    // Process in parallel with concurrency limit of 10
+    const chunks = [];
+    for (let i = 0; i < notifications.length; i += 10) {
+      chunks.push(notifications.slice(i, i + 10));
+    }
+
+    for (const chunk of chunks) {
+      const promises = chunk.map(async (n, idx) => {
+        try {
+          const result = await this._request("POST", "/v1/notifications", n);
+          results.push({ index: idx, ...result });
+        } catch (e) {
+          errors.push({ index: idx, error: e.message });
+        }
+      });
+      await Promise.all(promises);
+    }
+
+    return { results, errors, total: notifications.length, succeeded: results.length, failed: errors.length };
+  }
+
+  /**
+   * List notifications for the project.
+   * @param {object} [params]
+   * @param {number} [params.limit=50]
+   * @param {number} [params.offset=0]
+   * @param {string} [params.status]
+   * @returns {Promise<object>}
+   */
+  async listNotifications(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.limit) qs.set("limit", String(params.limit));
+    if (params.offset) qs.set("offset", String(params.offset));
+    if (params.status) qs.set("status", params.status);
+    const query = qs.toString();
+    return this._request("GET", `/v1/notifications${query ? "?" + query : ""}`);
+  }
+
+  /**
+   * Check API health.
+   * @returns {Promise<{ok: boolean}>}
+   */
+  async health() {
+    return this._request("GET", "/health");
+  }
+
+  /**
+   * Internal: HTTP request with retry, idempotency, and 429 handling.
+   */
+  async _request(method, path, body) {
+    const idempotencyKey = `idem_${crypto.randomUUID()}`;
+    let lastError;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      const start = Date.now();
+      try {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "x-idempotency-key": idempotencyKey,
+          "User-Agent": "NotifyStack-SDK/2.0"
+        };
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        const fetchOptions = { method, headers, signal: controller.signal };
+        if (body && method !== "GET") fetchOptions.body = JSON.stringify(body);
+
+        const response = await fetch(url, fetchOptions);
+        clearTimeout(timeout);
+
+        const json = await response.json();
+        const latency = Date.now() - start;
+
+        this._log(`${method} ${path} → ${response.status} (${latency}ms)`);
+
+        if (response.ok) return json.data || json;
+
+        // Rate limited — wait and retry
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("retry-after");
+          const waitMs = retryAfter ? Number(retryAfter) * 1000 : 5000;
+          this._log(`Rate limited. Waiting ${waitMs}ms...`);
+          await new Promise(r => setTimeout(r, waitMs));
+          continue;
+        }
+
+        // Don't retry client errors (4xx)
+        if (response.status >= 400 && response.status < 500) {
+          throw new NotifyError(json.message || "Request failed", response.status, json);
+        }
+
+        lastError = new NotifyError(json.message || "Request failed", response.status, json);
+      } catch (e) {
+        if (e instanceof NotifyError && e.status >= 400 && e.status < 500) throw e;
+        lastError = e;
+        this._log(`Attempt ${attempt + 1} failed: ${e.message}`);
+      }
+
+      // Exponential backoff with jitter
+      if (attempt < this.maxRetries - 1) {
+        const base = Math.min(1000 * Math.pow(2, attempt), 10000);
+        const jitter = base * 0.2 * (Math.random() * 2 - 1);
+        const delay = Math.round(base + jitter);
+        this._log(`Retrying in ${delay}ms...`);
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+
+    throw lastError || new Error("Request failed after retries");
+  }
+}
+
+class NotifyError extends Error {
+  constructor(message, status, response) {
+    super(message);
+    this.name = "NotifyError";
+    this.status = status;
+    this.response = response;
+  }
+}
+
+module.exports = NotifySDK;
+module.exports.NotifyError = NotifyError;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ayush0x44/notifystack",
+  "version": "1.0.0",
+  "description": "The official Node.js SDK for NotifyStack — a scalable, production-ready notification SaaS platform.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ayush462/notificationSaas.git"
+  },
+  "keywords": [
+    "notifications",
+    "email",
+    "sms",
+    "push",
+    "saas",
+    "notifystack",
+    "node-sdk"
+  ],
+  "author": "Ayush",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ayush462/notificationSaas/issues"
+  },
+  "homepage": "https://github.com/ayush462/notificationSaas#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/react.jsx

@@ -0,0 +1,134 @@
+import React, { useState, useEffect } from "react";
+
+/**
+ * 🔔 NotifyStack In-App Notification Hook
+ */
+export function useNotifyStack(apiKey, userId, options = {}) {
+  const [notifications, setNotifications] = useState([]);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const baseUrl = options.baseUrl || "https://api.notifystack.com";
+
+  const fetchFeed = async () => {
+    if (!userId) return;
+    setLoading(true);
+    try {
+      const res = await fetch(`${baseUrl}/v1/inapp/${userId}`, {
+        headers: { "x-api-key": apiKey }
+      });
+      const json = await res.json();
+      if (json.success) {
+        setNotifications(json.data.items);
+        setUnreadCount(json.data.unreadCount);
+      }
+    } catch (err) {
+      console.error("NotifyStack fetch error:", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchFeed();
+    // Use SSE or poll
+    const interval = setInterval(fetchFeed, options.pollingInterval || 15000);
+    return () => clearInterval(interval);
+  }, [userId, apiKey, baseUrl]);
+
+  const markAsRead = async (notificationId) => {
+    try {
+      setUnreadCount(Math.max(0, unreadCount - 1));
+      setNotifications(prev => prev.map(n => n.id === notificationId ? { ...n, read_at: new Date().toISOString() } : n));
+      
+      await fetch(`${baseUrl}/v1/inapp/${userId}/read/${notificationId}`, {
+        method: "PATCH",
+        headers: { "x-api-key": apiKey }
+      });
+    } catch (err) {
+      console.error("Failed to mark as read:", err);
+    }
+  };
+
+  const markAllAsRead = async () => {
+    try {
+      setUnreadCount(0);
+      setNotifications(prev => prev.map(n => ({ ...n, read_at: new Date().toISOString() })));
+      
+      await fetch(`${baseUrl}/v1/inapp/${userId}/read`, {
+        method: "POST",
+        headers: { "x-api-key": apiKey }
+      });
+    } catch (err) {
+      console.error("Failed to mark all as read:", err);
+    }
+  };
+
+  return { notifications, unreadCount, loading, markAsRead, markAllAsRead, refresh: fetchFeed };
+}
+
+/**
+ * 🔔 NotifyStack In-App Bell UI Component (Tailwind required)
+ */
+export function NotificationBell({ apiKey, userId, baseUrl }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const { notifications, unreadCount, markAsRead, markAllAsRead } = useNotifyStack(apiKey, userId, { baseUrl });
+
+  return (
+    <div className="relative">
+      <button 
+        onClick={() => setIsOpen(!isOpen)} 
+        className="relative p-2 rounded-full hover:bg-gray-100 transition-colors"
+      >
+        <svg fill="none" viewBox="0 0 24 24" strokeWidth="1.5" stroke="currentColor" className="w-6 h-6 text-gray-700">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M14.857 17.082a23.848 23.848 0 0 0 5.454-1.31A8.967 8.967 0 0 1 18 9.75V9A6 6 0 0 0 6 9v.75a8.967 8.967 0 0 1-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 0 1-5.714 0m5.714 0a3 3 0 1 1-5.714 0" />
+        </svg>
+        {unreadCount > 0 && (
+          <div className="absolute top-1 right-1 w-4 h-4 rounded-full bg-red-500 text-[10px] font-bold text-white flex items-center justify-center">
+            {unreadCount}
+          </div>
+        )}
+      </button>
+
+      {isOpen && (
+        <div className="absolute right-0 mt-2 w-80 bg-white rounded-xl shadow-2xl border border-gray-100 z-50 overflow-hidden">
+          <div className="flex justify-between items-center p-4 border-b border-gray-50 bg-gray-50/50">
+            <h3 className="font-semibold text-gray-900">Notifications</h3>
+            {unreadCount > 0 && (
+              <button onClick={markAllAsRead} className="text-xs text-blue-600 hover:text-blue-800 font-medium">
+                Mark all read
+              </button>
+            )}
+          </div>
+          <div className="max-h-[400px] overflow-y-auto">
+            {notifications.length === 0 ? (
+              <div className="p-8 text-center text-gray-500 text-sm">
+                You have no notifications yet.
+              </div>
+            ) : (
+              <div className="divide-y divide-gray-50">
+                {notifications.map(n => (
+                  <div 
+                    key={n.id} 
+                    className={`p-4 hover:bg-gray-50 transition-colors cursor-pointer ${!n.read_at && 'bg-blue-50/50'}`}
+                    onClick={() => !n.read_at && markAsRead(n.id)}
+                  >
+                    <div className="flex justify-between items-start mb-1">
+                      <p className={`text-sm ${!n.read_at ? 'font-semibold text-gray-900' : 'text-gray-700'}`}>
+                        {n.subject}
+                      </p>
+                      {!n.read_at && <div className="w-2 h-2 rounded-full bg-blue-500 mt-1.5 shrink-0" />}
+                    </div>
+                    <p className="text-sm text-gray-500 line-clamp-2">{n.body}</p>
+                    <p className="text-[11px] text-gray-400 mt-2">
+                      {new Date(n.created_at).toLocaleDateString()}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}