notiformer 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,10 @@
 # notiformer
 
-Real-time alerts, notifications and feature gates for your backend code.
+Real-time alerts and feature gates for your backend code.
 
-Send events from any point in your Node.js code and get notified instantly via push, email, Slack and more.
+Get notified instantly via push, email and more whenever something important happens in your app.
+
+> ⚠️ **Server-side only.** Do not use in browser/frontend code — your API key would be exposed publicly. Use in Node.js, Express, Next.js API routes, serverless functions, etc.
 
 ---
 
@@ -19,95 +21,69 @@ npm install notiformer
 ```ts
 import { Notiformer } from 'notiformer';
 
+// Get your API key at https://app.notiformer.com/projects
 const n = new Notiformer({
-  apiKey: 'ntf_live_...',  // from app.notiformer.com/projects
+  apiKey: 'ntf_live_test', // ← replace this with your real key
 });
 
-// Send an event + notification
 await n.event({
   channel: 'payments',
   event: 'payment_success',
-  description: `$49.00 — john@example.com`,
+  description: '$49.00 — john@example.com',
   icon: '💳',
-  tags: { userId: 'usr_123', plan: 'pro' },
   notify: true,
 });
 ```
 
+> Running with `apiKey: 'ntf_live_test'` will print a setup message in your console explaining how to get your real key. No events will be sent until you replace it.
+
 ---
 
-## Events
+## Get your API key
+
+1. Go to [app.notiformer.com/projects](https://app.notiformer.com/projects)
+2. Create or open a project
+3. Copy the API key
+4. Replace `'ntf_live_test'` in your code
 
-Use `n.event()` to log an event and optionally trigger notifications.
+---
+
+## Events
 
 ```ts
 await n.event({
-  channel: 'auth',           // channel name (auto-created)
-  event: 'user_signup',      // machine-readable event name
+  channel: 'auth',            // groups related events (auto-created on first use)
+  event: 'user_signup',       // machine-readable name
   description: 'New signup via Google',
   icon: '🎉',
 
-  // Optional metadata
-  tags: { method: 'google', plan: 'free' },
-  value: '42nd user',        // shown in the dashboard feed
+  tags: { method: 'google', plan: 'free' }, // optional metadata
+  value: '42nd user',         // optional value shown in the feed
 
-  // notify: true  → triggers push/email/Slack per your dashboard settings
-  // notify: false → silent log only (analytics mode)
-  notify: true,
-
-  // Rate limiting: events with the same groupId are deduplicated
-  groupId: 'signup-batch-today',
+  notify: true,   // true  → triggers push/email notifications
+                  // false → silent log for analytics only
 });
 ```
 
-### event() is fire-and-forget safe
-
-`event()` **never throws**. If the network is down or the API returns an error, it logs a warning and returns `null`. Your app continues running.
+`event()` **never throws** by default. If something goes wrong it logs a warning and returns `null` — a failed notification should never crash your app.
 
 ---
 
 ## Feature Gates
 
-Use `n.gate()` to check a boolean toggle you control remotely from the dashboard.
+Toggle features remotely from your Notiformer dashboard without redeploying.
 
 ```ts
 const isEnabled = await n.gate('new-checkout-flow');
 
 if (isEnabled) {
-  // run new checkout
+  // run new feature
 } else {
-  // run legacy checkout
+  // run old feature
 }
 ```
 
-Gates are cached locally for 30 seconds by default to minimise API calls.
-
-```ts
-// Custom fallback and cache TTL
-const isEnabled = await n.gate('my-feature', {
-  fallback: false,  // returned if network fails
-  cacheTtl: 60,     // cache for 60 seconds (0 = disable)
-});
-```
-
-### Full gate details
-
-```ts
-const result = await n.gateDetails('my-feature');
-// {
-//   key: 'my-feature',
-//   enabled: true,
-//   cached: false,
-//   fetchedAt: '2025-04-20T10:00:00.000Z'
-// }
-```
-
-### Force a fresh fetch
-
-```ts
-n.clearGateCache('my-feature');  // clear one gate
-n.clearGateCache();               // clear all
-```
+Gates are cached for 30 seconds by default to minimise API calls.
 
 ---
 
@@ -115,17 +91,17 @@ n.clearGateCache();               // clear all
 
 ```ts
 const n = new Notiformer({
-  apiKey: 'ntf_live_...',   // Required
+  apiKey: 'ntf_live_...',          // required — from app.notiformer.com/projects
 
-  // Optional
-  baseUrl: 'https://api.notiformer.com',   // default
-  timeout: 5000,            // ms, default: 5000
-  silent: false,            // true = all calls are no-ops (good for local dev)
-  logLevel: 'error',        // 'debug' | 'info' | 'warn' | 'error' | 'none'
+  silent: false,                   // true = no calls made (useful for local dev)
+  throwOnError: false,             // true = throws instead of returning null
+  onError: (err) => {              // called on any failed call
+    console.error(err.message);
+  },
 });
 ```
 
-### Silence in development
+### Silence in local development
 
 ```ts
 const n = new Notiformer({
@@ -138,7 +114,7 @@ const n = new Notiformer({
 
 ## Common patterns
 
-### Alert on errors
+### Alert on unhandled errors
 
 ```ts
 app.use(async (err, req, res, next) => {
@@ -147,94 +123,54 @@ app.use(async (err, req, res, next) => {
     event: 'unhandled_error',
     description: err.message,
     icon: '🔴',
-    tags: {
-      path: req.path,
-      method: req.method,
-      status: 500,
-    },
+    tags: { path: req.path, status: 500 },
     notify: true,
   });
   res.status(500).json({ error: 'Internal server error' });
 });
 ```
 
-### Track business milestones
+### Track a payment
 
 ```ts
-async function onPaymentSuccess(charge: Charge) {
-  await n.event({
-    channel: 'payments',
-    event: 'payment_success',
-    description: `${formatCurrency(charge.amount)} — ${charge.email}`,
-    icon: '💳',
-    value: formatCurrency(charge.amount),
-    tags: { chargeId: charge.id, plan: charge.plan },
-    notify: true,
-  });
-}
+await n.event({
+  channel: 'payments',
+  event: 'payment_success',
+  description: `${amount} — ${user.email}`,
+  icon: '💳',
+  value: amount,
+  notify: true,
+});
 ```
 
-### Feature gate a new endpoint
+### Feature gate
 
 ```ts
 app.post('/checkout', async (req, res) => {
   const useNewFlow = await n.gate('new-checkout-flow');
-
-  if (useNewFlow) {
-    return newCheckoutHandler(req, res);
-  }
-  return legacyCheckoutHandler(req, res);
+  return useNewFlow
+    ? newCheckoutHandler(req, res)
+    : legacyCheckoutHandler(req, res);
 });
 ```
 
 ### Silent analytics (no notification)
 
 ```ts
-// Log for analytics without pushing a notification
 await n.event({
   channel: 'monitoring',
   event: 'page_view',
-  description: `/dashboard visited`,
-  tags: { userId: req.user.id },
-  notify: false,  // ← silent
+  tags: { path: req.path },
+  notify: false,  // ← no notification, just logged
 });
 ```
 
 ---
 
-## TypeScript
-
-Full TypeScript support included. All types are exported:
-
-```ts
-import type {
-  NotiformerConfig,
-  EventPayload,
-  EventResponse,
-  GateOptions,
-  GateResult,
-} from 'notiformer';
-```
-
----
-
 ## Requirements
 
-- Node.js 16+
-- Fetch API (native in Node 18+; polyfill needed for Node 16)
-
-### Node 16 fetch polyfill
-
-```bash
-npm install node-fetch
-```
-
-```ts
-import fetch from 'node-fetch';
-(global as any).fetch = fetch;
-
-import { Notiformer } from 'notiformer';
-```
+- Node.js 18+ (uses native `fetch`)
+- For Node 16: install `node-fetch` and polyfill `global.fetch`
 
 ---
 
@@ -242,4 +178,3 @@ import { Notiformer } from 'notiformer';
 
 - Dashboard: [app.notiformer.com](https://app.notiformer.com)
 - Docs: [docs.notiformer.com](https://docs.notiformer.com)
-- Support: support@notiformer.com

package/dist/index.d.ts

@@ -1,15 +1,17 @@
 /**
- * Notiformer Node.js SDK
+ * Notiformer — Real-time alerts and feature gates for your code.
  *
- * Real-time alerts, notifications and feature gates for your backend code.
+ * ⚠️  SERVER-SIDE ONLY. Do not use in browser/frontend code.
+ *     Your API key would be exposed publicly.
+ *     Use in: Node.js, Express, Next.js API routes, serverless functions.
  *
  * @example
- * ```ts
  * import { Notiformer } from 'notiformer';
  *
- * const n = new Notiformer({ apiKey: 'ntf_live_...' });
+ * const n = new Notiformer({
+ *   apiKey: 'ntf_live_xxxxxxxxxxxxxxxx', // from app.notiformer.com/projects
+ * });
  *
- * // Send a notification event
  * await n.event({
  *   channel: 'payments',
  *   event: 'payment_success',
@@ -17,70 +19,43 @@
  *   icon: '💳',
  *   notify: true,
  * });
- *
- * // Check a feature gate
- * const isEnabled = await n.gate('new-checkout-flow');
- * if (isEnabled) { ... }
- * ```
  */
-import type { NotiformerConfig, EventPayload, EventResponse, GateOptions, GateResult } from './types';
+import type { NotiformerConfig, EventPayload, EventResponse, GateOptions, GateResult } from "./types";
 export type { NotiformerConfig, EventPayload, EventResponse, GateOptions, GateResult, };
 export declare class Notiformer {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
     private readonly silent;
+    private readonly throwOnError;
+    private readonly onError?;
     private readonly logger;
     private readonly gateCache;
+    private readonly isPlaceholder;
     constructor(config: NotiformerConfig);
     /**
-     * Send an event to a channel. Triggers notifications based on your
-     * dashboard settings.
+     * Send an event and optionally trigger a notification.
      *
-     * @param payload - The event data
-     * @returns The created event ID and timestamp, or null if silent mode
-     *
-     * @example
-     * ```ts
-     * await n.event({
-     *   channel: 'payments',
-     *   event: 'payment_success',
-     *   description: `$49.00 — ${user.email}`,
-     *   icon: '💳',
-     *   tags: { userId: user.id, plan: 'pro' },
-     *   notify: true,
-     * });
-     * ```
+     * Safe to use anywhere in your code — never throws by default.
+     * Returns null if the call fails (and calls onError if configured).
      */
     event(payload: EventPayload): Promise<EventResponse | null>;
     /**
-     * Check whether a feature gate is enabled. Results are cached locally
-     * for `cacheTtl` seconds (default: 30) to minimize API calls.
-     *
-     * @param key - The gate key as defined in your dashboard
-     * @param options - Cache and fallback options
-     * @returns `true` if the gate is enabled, `false` otherwise
+     * Check whether a feature gate is enabled.
+     * Cached locally for 30 seconds by default.
      *
-     * @example
-     * ```ts
-     * const isEnabled = await n.gate('new-checkout-flow');
-     * if (isEnabled) {
-     *   // use new checkout
-     * }
-     * ```
+     * Returns fallback (false) if the call fails.
      */
     gate(key: string, options?: GateOptions): Promise<boolean>;
-    /**
-     * Like `gate()` but returns the full GateResult object
-     * including whether the value was cached.
-     */
+    /** Full gate result with metadata */
     gateDetails(key: string, options?: GateOptions): Promise<GateResult>;
-    /**
-     * Clears the in-memory gate cache.
-     * Useful if you need to force a fresh fetch.
-     */
+    /** Clear cached gate values */
     clearGateCache(key?: string): void;
-    private fetchWithTimeout;
+    private post;
+    private get;
+    private request;
+    private fail;
+    private friendlyNetworkError;
 }
 export default Notiformer;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,EAEX,MAAM,SAAS,CAAC;AAIjB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,GACX,CAAC;AAMF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,MAAM,EAAE,gBAAgB;IAsBpC;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAiDjE;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAyCpE;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+B9E;;;OAGG;IACH,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;YAYpB,gBAAgB;CAoB/B;AAMD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,EACX,MAAM,SAAS,CAAC;AAIjB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,GACX,CAAC;AAQF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAE5B,MAAM,EAAE,gBAAgB;IAwCpC;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAkDjE;;;;;OAKG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBpE,qCAAqC;IAC/B,WAAW,CACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IAKtB,+BAA+B;IAC/B,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;YAQpB,IAAI;YAOJ,GAAG;YAIH,OAAO;IAmBrB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -1,16 +1,18 @@
 "use strict";
 /**
- * Notiformer Node.js SDK
+ * Notiformer — Real-time alerts and feature gates for your code.
  *
- * Real-time alerts, notifications and feature gates for your backend code.
+ * ⚠️  SERVER-SIDE ONLY. Do not use in browser/frontend code.
+ *     Your API key would be exposed publicly.
+ *     Use in: Node.js, Express, Next.js API routes, serverless functions.
  *
  * @example
- * ```ts
  * import { Notiformer } from 'notiformer';
  *
- * const n = new Notiformer({ apiKey: 'ntf_live_...' });
+ * const n = new Notiformer({
+ *   apiKey: 'ntf_live_xxxxxxxxxxxxxxxx', // from app.notiformer.com/projects
+ * });
  *
- * // Send a notification event
  * await n.event({
  *   channel: 'payments',
  *   event: 'payment_success',
@@ -18,71 +20,74 @@
  *   icon: '💳',
  *   notify: true,
  * });
- *
- * // Check a feature gate
- * const isEnabled = await n.gate('new-checkout-flow');
- * if (isEnabled) { ... }
- * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Notiformer = void 0;
 const logger_1 = require("./logger");
 const cache_1 = require("./cache");
-const DEFAULT_BASE_URL = 'https://api.notiformer.com';
-const DEFAULT_TIMEOUT = 5000;
+// The placeholder key shown in docs — triggers a friendly setup message
+const PLACEHOLDER_KEY = "ntf_live_test";
+const API_URL = "https://api.notiformer.com";
+const DEFAULT_TIMEOUT = 8000;
 const DEFAULT_GATE_TTL = 30;
 class Notiformer {
     constructor(config) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         if (!config.apiKey) {
-            throw new Error('[notiformer] apiKey is required.');
-        }
-        if (!config.apiKey.startsWith('ntf_')) {
-            console.warn('[notiformer] API key should start with "ntf_". Make sure you are using a valid key from your dashboard.');
+            throw new Error("[notiformer] apiKey is required.\n" +
+                "→ Get yours at https://app.notiformer.com/projects");
         }
+        this.isPlaceholder = config.apiKey === PLACEHOLDER_KEY;
         this.apiKey = config.apiKey;
-        this.baseUrl = ((_a = config.baseUrl) !== null && _a !== void 0 ? _a : DEFAULT_BASE_URL).replace(/\/$/, '');
-        this.timeout = (_b = config.timeout) !== null && _b !== void 0 ? _b : DEFAULT_TIMEOUT;
-        this.silent = (_c = config.silent) !== null && _c !== void 0 ? _c : false;
-        this.logger = new logger_1.Logger((_d = config.logLevel) !== null && _d !== void 0 ? _d : 'error');
+        this.baseUrl = ((_a = config._baseUrl) !== null && _a !== void 0 ? _a : API_URL).replace(/\/$/, "");
+        this.timeout = DEFAULT_TIMEOUT;
+        this.silent = (_b = config.silent) !== null && _b !== void 0 ? _b : false;
+        this.throwOnError = (_c = config.throwOnError) !== null && _c !== void 0 ? _c : false;
+        this.onError = config.onError;
+        this.logger = new logger_1.Logger("warn");
         this.gateCache = new cache_1.GateCache();
-        this.logger.debug('Notiformer initialized', { baseUrl: this.baseUrl });
+        if (this.isPlaceholder) {
+            console.warn("\n" +
+                "┌─────────────────────────────────────────────────────┐\n" +
+                "│  notiformer — setup required                        │\n" +
+                "├─────────────────────────────────────────────────────┤\n" +
+                '│  You are using the example API key "ntf_live_test". │\n' +
+                "│  Events will not be sent until you use a real key.  │\n" +
+                "│                                                     │\n" +
+                "│  1. Go to https://app.notiformer.com/projects       │\n" +
+                "│  2. Create or open a project                        │\n" +
+                "│  3. Copy your API key                               │\n" +
+                '│  4. Replace "ntf_live_test" with your real key      │\n' +
+                "└─────────────────────────────────────────────────────┘\n");
+        }
     }
-    // ─────────────────────────────────────────────
-    // event() — Send a notification event
-    // ─────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────
+    // event()
+    // ─────────────────────────────────────────────────────────────
     /**
-     * Send an event to a channel. Triggers notifications based on your
-     * dashboard settings.
-     *
-     * @param payload - The event data
-     * @returns The created event ID and timestamp, or null if silent mode
+     * Send an event and optionally trigger a notification.
      *
-     * @example
-     * ```ts
-     * await n.event({
-     *   channel: 'payments',
-     *   event: 'payment_success',
-     *   description: `$49.00 — ${user.email}`,
-     *   icon: '💳',
-     *   tags: { userId: user.id, plan: 'pro' },
-     *   notify: true,
-     * });
-     * ```
+     * Safe to use anywhere in your code — never throws by default.
+     * Returns null if the call fails (and calls onError if configured).
      */
     async event(payload) {
-        var _a;
+        var _a, _b;
+        if (!payload.channel)
+            throw new Error("[notiformer] event.channel is required.");
+        if (!payload.event)
+            throw new Error("[notiformer] event.event is required.");
+        // Placeholder key — log a clear message, do not attempt the call
+        if (this.isPlaceholder) {
+            console.warn('[notiformer] Event not sent — you are using the example key "ntf_live_test".\n' +
+                "→ Replace it with your real API key from https://app.notiformer.com/projects");
+            return null;
+        }
         if (this.silent) {
-            this.logger.info('Silent mode: event suppressed', payload);
+            this.logger.info("Silent mode: event suppressed.");
             return null;
         }
-        if (!payload.channel)
-            throw new Error('[notiformer] event.channel is required.');
-        if (!payload.event)
-            throw new Error('[notiformer] event.event is required.');
-        this.logger.debug('Sending event', payload);
         try {
-            const body = {
+            const res = await this.post("/v1/events", {
                 channel: payload.channel,
                 event: payload.event,
                 description: payload.description,
@@ -90,131 +95,74 @@ class Notiformer {
                 tags: payload.tags,
                 value: payload.value,
                 notify: (_a = payload.notify) !== null && _a !== void 0 ? _a : true,
-                groupId: payload.groupId,
-            };
-            const res = await this.fetchWithTimeout('/v1/events', {
-                method: 'POST',
-                body: JSON.stringify(body),
             });
             if (!res.ok) {
-                const err = await res.json().catch(() => ({ error: 'Unknown', code: String(res.status) }));
-                this.logger.error(`Event failed: ${err.error} (${err.code})`);
-                return null;
+                const body = await res
+                    .json()
+                    .catch(() => ({ error: `HTTP ${res.status}` }));
+                return this.fail(new Error(`[notiformer] ${(_b = body.error) !== null && _b !== void 0 ? _b : res.statusText}`));
             }
-            const data = await res.json();
-            this.logger.debug('Event sent', data);
-            return data;
+            return (await res.json());
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.logger.error('Event request failed', message);
-            // Never throw — a failed notification should not crash your app
-            return null;
+            return this.fail(this.friendlyNetworkError(err));
         }
     }
-    // ─────────────────────────────────────────────
-    // gate() — Check a feature gate
-    // ─────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────
+    // gate()
+    // ─────────────────────────────────────────────────────────────
     /**
-     * Check whether a feature gate is enabled. Results are cached locally
-     * for `cacheTtl` seconds (default: 30) to minimize API calls.
-     *
-     * @param key - The gate key as defined in your dashboard
-     * @param options - Cache and fallback options
-     * @returns `true` if the gate is enabled, `false` otherwise
+     * Check whether a feature gate is enabled.
+     * Cached locally for 30 seconds by default.
      *
-     * @example
-     * ```ts
-     * const isEnabled = await n.gate('new-checkout-flow');
-     * if (isEnabled) {
-     *   // use new checkout
-     * }
-     * ```
+     * Returns fallback (false) if the call fails.
      */
     async gate(key, options = {}) {
         var _a, _b;
         if (!key)
-            throw new Error('[notiformer] gate key is required.');
+            throw new Error("[notiformer] gate key is required.");
         const fallback = (_a = options.fallback) !== null && _a !== void 0 ? _a : false;
         const ttl = (_b = options.cacheTtl) !== null && _b !== void 0 ? _b : DEFAULT_GATE_TTL;
-        if (this.silent) {
-            this.logger.info(`Silent mode: gate "${key}" returning fallback (${String(fallback)})`);
+        if (this.isPlaceholder || this.silent)
             return fallback;
-        }
-        // Check cache first
         const cached = this.gateCache.get(key);
-        if (cached !== null) {
-            this.logger.debug(`Gate "${key}" from cache: ${String(cached)}`);
+        if (cached !== null)
             return cached;
-        }
         try {
-            const res = await this.fetchWithTimeout(`/v1/gates/${encodeURIComponent(key)}`);
-            if (!res.ok) {
-                this.logger.warn(`Gate "${key}" fetch failed (${res.status}), using fallback: ${String(fallback)}`);
+            const res = await this.get(`/v1/gates/${encodeURIComponent(key)}`);
+            if (!res.ok)
                 return fallback;
-            }
-            const data = await res.json();
+            const data = (await res.json());
             this.gateCache.set(key, data.enabled, ttl);
-            this.logger.debug(`Gate "${key}": ${String(data.enabled)}`);
             return data.enabled;
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.logger.warn(`Gate "${key}" request failed (${message}), using fallback: ${String(fallback)}`);
+        catch (_c) {
             return fallback;
         }
     }
-    // ─────────────────────────────────────────────
-    // gateDetails() — Get full gate result with metadata
-    // ─────────────────────────────────────────────
-    /**
-     * Like `gate()` but returns the full GateResult object
-     * including whether the value was cached.
-     */
+    /** Full gate result with metadata */
     async gateDetails(key, options = {}) {
-        var _a, _b;
-        const fallback = (_a = options.fallback) !== null && _a !== void 0 ? _a : false;
-        const ttl = (_b = options.cacheTtl) !== null && _b !== void 0 ? _b : DEFAULT_GATE_TTL;
-        const now = new Date().toISOString();
-        if (this.silent) {
-            return { key, enabled: fallback, cached: false, fetchedAt: now };
-        }
-        const cachedVal = this.gateCache.get(key);
-        if (cachedVal !== null) {
-            return { key, enabled: cachedVal, cached: true, fetchedAt: now };
-        }
-        try {
-            const res = await this.fetchWithTimeout(`/v1/gates/${encodeURIComponent(key)}`);
-            if (!res.ok) {
-                return { key, enabled: fallback, cached: false, fetchedAt: now };
-            }
-            const data = await res.json();
-            this.gateCache.set(key, data.enabled, ttl);
-            return data;
-        }
-        catch (_c) {
-            return { key, enabled: fallback, cached: false, fetchedAt: now };
-        }
+        const enabled = await this.gate(key, options);
+        return { key, enabled, cached: false, fetchedAt: new Date().toISOString() };
     }
-    // ─────────────────────────────────────────────
-    // clearGateCache() — Force fresh gate fetch
-    // ─────────────────────────────────────────────
-    /**
-     * Clears the in-memory gate cache.
-     * Useful if you need to force a fresh fetch.
-     */
+    /** Clear cached gate values */
     clearGateCache(key) {
-        if (key) {
-            this.gateCache.delete(key);
-        }
-        else {
-            this.gateCache.clear();
-        }
+        key ? this.gateCache.delete(key) : this.gateCache.clear();
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────────────────────────
+    async post(path, body) {
+        return this.request(path, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
     }
-    // ─────────────────────────────────────────────
-    // Private helpers
-    // ─────────────────────────────────────────────
-    async fetchWithTimeout(path, init = {}) {
+    async get(path) {
+        return this.request(path, { method: "GET" });
+    }
+    async request(path, init) {
+        var _a;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
         try {
@@ -222,11 +170,10 @@ class Notiformer {
                 ...init,
                 signal: controller.signal,
                 headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'X-SDK-Version': '1.0.0',
-                    'X-SDK-Language': 'node',
-                    ...init.headers,
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "X-SDK-Version": "1.0.2",
+                    ...((_a = init.headers) !== null && _a !== void 0 ? _a : {}),
                 },
             });
         }
@@ -234,10 +181,29 @@ class Notiformer {
             clearTimeout(timer);
         }
     }
+    fail(error) {
+        var _a;
+        this.logger.error(error.message);
+        (_a = this.onError) === null || _a === void 0 ? void 0 : _a.call(this, error);
+        if (this.throwOnError)
+            throw error;
+        return null;
+    }
+    friendlyNetworkError(err) {
+        const msg = err instanceof Error ? err.message.toLowerCase() : "";
+        if (msg.includes("aborted") || msg.includes("timeout")) {
+            return new Error(`[notiformer] Request timed out after ${this.timeout / 1000}s.\n` +
+                "Check your internet connection or try again later.");
+        }
+        if (msg.includes("failed to fetch") ||
+            msg.includes("enotfound") ||
+            msg.includes("network")) {
+            return new Error("[notiformer] Cannot reach the Notiformer API.\n" +
+                "Check your internet connection. If the problem persists, visit https://status.notiformer.com");
+        }
+        return err instanceof Error ? err : new Error(String(err));
+    }
 }
 exports.Notiformer = Notiformer;
-// ─────────────────────────────────────────────
-// Named export for convenience
-// ─────────────────────────────────────────────
 exports.default = Notiformer;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,88 +1,67 @@
 export interface NotiformerConfig {
     /**
-     * Your project API key from the Notiformer dashboard.
-     * Get it at: https://app.notiformer.com/projects
+     * Your Notiformer API key.
+     * Find it at: https://app.notiformer.com/projects
+     *
+     * @example
+     * const n = new Notiformer({ apiKey: 'ntf_live_xxxxxxxxxxxxxxxx' })
      */
     apiKey: string;
     /**
-     * Base URL of the Notiformer API.
-     * @default 'https://api.notiformer.com'
+     * Silence all SDK calls. Useful for local development.
+     * No events will be sent, no network calls made.
+     *
+     * @example
+     * const n = new Notiformer({
+     *   apiKey: process.env.NOTIFORMER_API_KEY,
+     *   silent: process.env.NODE_ENV !== 'production',
+     * })
      */
-    baseUrl?: string;
-    /**
-     * Request timeout in milliseconds.
-     * @default 5000
-     */
-    timeout?: number;
+    silent?: boolean;
     /**
-     * If true, SDK calls are no-ops. Useful for local development.
-     * @default false
+     * Called when an event() or gate() call fails.
+     * Use this to forward errors to your own logging system.
+     *
+     * @example
+     * onError: (err) => console.error('[notiformer]', err.message)
      */
-    silent?: boolean;
+    onError?: (error: Error) => void;
     /**
-     * Log level for SDK internals.
-     * @default 'error'
+     * If true, throws on failure instead of returning null silently.
+     * Default: false — a failed notification should never crash your app.
      */
-    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+    throwOnError?: boolean;
+    /** @internal — do not use in production */
+    _baseUrl?: string;
 }
 export interface EventPayload {
-    /**
-     * The channel to send this event to.
-     * Channels group related events (e.g. 'payments', 'auth', 'errors').
-     * Created automatically on first use.
-     */
+    /** Channel name. Groups related events. Created automatically. e.g. 'payments', 'errors' */
     channel: string;
-    /**
-     * Machine-readable event name (e.g. 'payment_success', 'user_signup').
-     */
+    /** Event name. e.g. 'user_signed_up', 'payment_failed' */
     event: string;
-    /**
-     * Human-readable description shown in the dashboard feed.
-     */
+    /** Human-readable description shown in the dashboard */
     description?: string;
-    /**
-     * An emoji icon shown next to the event in the feed.
-     * @example '💳' | '🚨' | '✅'
-     */
+    /** Emoji icon shown in the feed */
     icon?: string;
-    /**
-     * Optional key-value tags for filtering and search.
-     * @example { userId: 'usr_123', plan: 'pro', amount: 49 }
-     */
+    /** Optional key/value metadata for filtering */
     tags?: Record<string, string | number | boolean>;
-    /**
-     * A scalar value to display alongside the event.
-     * @example '$49.00' | 200 | '98ms'
-     */
+    /** A value to display alongside the event. e.g. '$49.00' */
     value?: string | number;
     /**
-     * If true, triggers configured notification channels (push, email, etc).
-     * If false, the event is logged silently (analytics only).
+     * If true, triggers your configured notifications (push, email…).
+     * If false, logs silently for analytics only.
      * @default true
      */
     notify?: boolean;
-    /**
-     * Used for deduplication. Events with the same groupId within
-     * a short window are rate-limited.
-     */
-    groupId?: string;
 }
 export interface EventResponse {
     id: string;
     createdAt: string;
 }
 export interface GateOptions {
-    /**
-     * Fallback value returned if the network request fails
-     * or times out.
-     * @default false
-     */
+    /** Returned if the request fails. @default false */
     fallback?: boolean;
-    /**
-     * Cache TTL in seconds. Set to 0 to disable caching.
-     * Recommended: 30 (default) to reduce API calls.
-     * @default 30
-     */
+    /** Cache duration in seconds. 0 to disable. @default 30 */
     cacheTtl?: number;
 }
 export interface GateResult {
@@ -91,9 +70,5 @@ export interface GateResult {
     cached: boolean;
     fetchedAt: string;
 }
-export interface ApiErrorResponse {
-    error: string;
-    code: string;
-}
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACzD;AAMD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAEjD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEjC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC"}

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 // ─────────────────────────────────────────────
-// Notiformer Node.js SDK — Types
+// Notiformer SDK — Public Types
 // ─────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,gDAAgD;AAChD,iCAAiC;AACjC,gDAAgD"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,gDAAgD;AAChD,gCAAgC;AAChC,gDAAgD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notiformer",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Real-time alerts, notifications and feature gates for your backend code",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",