notifykitdev 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# NotifyKit JavaScript SDK
+
+Official NotifyKit SDK for JavaScript. Send notifications from your apps with a simple, non-blocking API.
+
+## Features
+
+- Works everywhere: Node.js 18+, Bun, Deno, browsers, React, Vue, Next.js, Express
+- TypeScript-first with full type definitions included
+- Zero dependencies (~2KB minified)
+- Async/non-blocking - won't slow down your app
+- Silent failures - logs errors but never crashes your app
+
+## Installation
+
+```bash
+# npm
+npm install notifykitdev
+
+# yarn
+yarn add notifykitdev
+
+# pnpm
+pnpm add notifykitdev
+
+# bun
+bun add notifykitdev
+```
+
+## Quick Start
+
+```typescript
+import NotifyKit from 'notifykitdev';
+
+// Initialize once at startup
+NotifyKit.init('nsk_your_api_key');
+
+// Send notifications anywhere in your app
+NotifyKit.notify('User signed up!');
+```
+
+## API Reference
+
+### `NotifyKit.init(apiKey)`
+
+Initialize the SDK with your API key. Call this once at application startup.
+
+```typescript
+// Simple initialization
+NotifyKit.init('nsk_your_api_key');
+
+// With options
+NotifyKit.init({
+  apiKey: 'nsk_your_api_key',
+  baseUrl: 'https://api.notifykit.dev', // optional, custom API URL
+  debug: true, // optional, enable debug logging
+});
+```
+
+### `NotifyKit.notify(message, options?)`
+
+Send a notification. This is fire-and-forget: it returns immediately and won't throw errors.
+
+```typescript
+// Simple message
+NotifyKit.notify('Hello world!');
+
+// With topic for categorization
+NotifyKit.notify('New order received', { topic: 'orders' });
+
+// With idempotency key to prevent duplicates
+NotifyKit.notify('Welcome email sent', {
+  topic: 'onboarding',
+  idempotencyKey: `welcome-${userId}`,
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `topic` | `string` | Categorize notifications for filtering |
+| `idempotencyKey` | `string` | Prevent duplicate notifications |
+
+### `NotifyKit.isInitialized()`
+
+Check if the SDK has been initialized.
+
+```typescript
+if (!NotifyKit.isInitialized()) {
+  NotifyKit.init('nsk_your_api_key');
+}
+```
+
+## Framework Examples
+
+### Express.js
+
+```typescript
+import express from 'express';
+import NotifyKit from 'notifykitdev';
+
+const app = express();
+
+// Initialize once at startup
+NotifyKit.init(process.env.NOTIFYKIT_API_KEY!);
+
+app.post('/api/orders', async (req, res) => {
+  const order = await createOrder(req.body);
+
+  // Fire-and-forget notification
+  NotifyKit.notify(`New order #${order.id} for $${order.total}`, {
+    topic: 'orders',
+  });
+
+  res.json(order);
+});
+
+app.listen(3000);
+```
+
+### Next.js (App Router)
+
+```typescript
+// app/api/signup/route.ts
+import NotifyKit from 'notifykitdev';
+
+// Initialize (safe to call multiple times)
+NotifyKit.init(process.env.NOTIFYKIT_API_KEY!);
+
+export async function POST(request: Request) {
+  const { email } = await request.json();
+  const user = await createUser(email);
+
+  NotifyKit.notify(`New signup: ${email}`, {
+    topic: 'signups',
+    idempotencyKey: `signup-${user.id}`,
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+### Next.js (Client-side)
+
+```typescript
+// components/feedback-form.tsx
+'use client';
+
+import NotifyKit from 'notifykitdev';
+
+// Initialize with your write-only API key (safe for frontend)
+NotifyKit.init('nsk_your_api_key');
+
+export function FeedbackForm() {
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const feedback = new FormData(e.target as HTMLFormElement).get('feedback');
+
+    NotifyKit.notify(`New feedback: ${feedback}`, { topic: 'feedback' });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <textarea name="feedback" required />
+      <button type="submit">Send Feedback</button>
+    </form>
+  );
+}
+```
+
+### React
+
+```typescript
+import { useEffect } from 'react';
+import NotifyKit from 'notifykitdev';
+
+// Initialize outside component (runs once)
+NotifyKit.init('nsk_your_api_key');
+
+function App() {
+  const handleClick = () => {
+    NotifyKit.notify('Button clicked!', { topic: 'events' });
+  };
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### Deno
+
+```typescript
+import NotifyKit from 'npm:notifykitdev';
+
+NotifyKit.init(Deno.env.get('NOTIFYKIT_API_KEY')!);
+
+Deno.serve(async (req) => {
+  NotifyKit.notify('Request received', { topic: 'requests' });
+  return new Response('OK');
+});
+```
+
+### Bun
+
+```typescript
+import NotifyKit from 'notifykitdev';
+
+NotifyKit.init(Bun.env.NOTIFYKIT_API_KEY!);
+
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    NotifyKit.notify('Request received');
+    return new Response('OK');
+  },
+});
+```
+
+## Error Handling
+
+The SDK is designed to never throw errors or crash your app. All errors are logged to the console but won't interrupt your code:
+
+```typescript
+// This won't throw even if the API is down
+NotifyKit.notify('Hello world!');
+
+// Enable debug mode for more detailed logging
+NotifyKit.init({
+  apiKey: 'nsk_your_api_key',
+  debug: true,
+});
+```
+
+## TypeScript
+
+Full TypeScript support is included. Import types directly:
+
+```typescript
+import NotifyKit, { type NotifyOptions, type NotifyKitConfig } from 'notifykitdev';
+
+const options: NotifyOptions = {
+  topic: 'alerts',
+  idempotencyKey: 'unique-123',
+};
+
+NotifyKit.notify('Alert!', options);
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,136 @@
+/**
+ * NotifyKit SDK TypeScript type definitions.
+ * @module notifykit/types
+ */
+/**
+ * Options for configuring a notification.
+ */
+interface NotifyOptions {
+    /**
+     * Topic to categorize the notification.
+     * Used for filtering and routing notifications.
+     */
+    topic?: string;
+    /**
+     * Unique key to prevent duplicate notifications.
+     * If a notification with the same idempotency key was already sent,
+     * the duplicate will be ignored.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Configuration options for initializing NotifyKit.
+ */
+interface NotifyKitConfig {
+    /**
+     * Your NotifyKit API key (starts with 'nsk_').
+     */
+    apiKey: string;
+    /**
+     * Custom API base URL.
+     * Defaults to 'https://api.notifykit.dev'.
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Response from the notify API.
+ */
+interface NotifyResponse {
+    /**
+     * Unique identifier for the notification event.
+     */
+    eventId: string;
+    /**
+     * Status of the notification request.
+     */
+    status: "accepted" | "rejected";
+    /**
+     * Error message if the notification was rejected.
+     */
+    error?: string;
+}
+
+/**
+ * NotifyKit SDK for JavaScript.
+ * Send notifications from your apps with a simple API.
+ * @module notifykit
+ */
+
+/**
+ * NotifyKit SDK client.
+ * Initialize once with your API key, then send notifications from anywhere.
+ *
+ * @example
+ * ```typescript
+ * import NotifyKit from 'notifykit';
+ *
+ * // Initialize once at startup
+ * NotifyKit.init('nsk_your_api_key');
+ *
+ * // Send notifications anywhere in your app
+ * NotifyKit.notify('User signed up!');
+ * NotifyKit.notify('Payment received', { topic: 'payments' });
+ * ```
+ */
+declare const NotifyKit: {
+    /**
+     * Initializes the NotifyKit SDK with your API key.
+     * Call this once at application startup.
+     *
+     * @param apiKeyOrConfig - Your API key string or full configuration object
+     *
+     * @example
+     * ```typescript
+     * // Simple initialization
+     * NotifyKit.init('nsk_your_api_key');
+     *
+     * // With custom options
+     * NotifyKit.init({
+     *   apiKey: 'nsk_your_api_key',
+     *   debug: true,
+     * });
+     * ```
+     */
+    init(apiKeyOrConfig: string | NotifyKitConfig): void;
+    /**
+     * Sends a notification asynchronously.
+     * This method is fire-and-forget: it won't block your app or throw errors.
+     * Errors are logged to the console but won't crash your application.
+     *
+     * @param message - The notification message to send
+     * @param options - Optional configuration for the notification
+     * @returns A promise that resolves when the notification is sent (or fails silently)
+     *
+     * @example
+     * ```typescript
+     * // Simple notification
+     * NotifyKit.notify('Hello world!');
+     *
+     * // With topic for categorization
+     * NotifyKit.notify('New order received', { topic: 'orders' });
+     *
+     * // With idempotency key to prevent duplicates
+     * NotifyKit.notify('Welcome!', {
+     *   topic: 'onboarding',
+     *   idempotencyKey: `welcome-${userId}`,
+     * });
+     * ```
+     */
+    notify(message: string, options?: NotifyOptions): Promise<void>;
+    /**
+     * Checks if the SDK has been initialized.
+     * @returns True if init() has been called with an API key
+     */
+    isInitialized(): boolean;
+    /**
+     * Resets the SDK state. Useful for testing.
+     */
+    reset(): void;
+};
+
+export { type NotifyKitConfig, type NotifyOptions, type NotifyResponse, NotifyKit as default };

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+/**
+ * NotifyKit SDK TypeScript type definitions.
+ * @module notifykit/types
+ */
+/**
+ * Options for configuring a notification.
+ */
+interface NotifyOptions {
+    /**
+     * Topic to categorize the notification.
+     * Used for filtering and routing notifications.
+     */
+    topic?: string;
+    /**
+     * Unique key to prevent duplicate notifications.
+     * If a notification with the same idempotency key was already sent,
+     * the duplicate will be ignored.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Configuration options for initializing NotifyKit.
+ */
+interface NotifyKitConfig {
+    /**
+     * Your NotifyKit API key (starts with 'nsk_').
+     */
+    apiKey: string;
+    /**
+     * Custom API base URL.
+     * Defaults to 'https://api.notifykit.dev'.
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Response from the notify API.
+ */
+interface NotifyResponse {
+    /**
+     * Unique identifier for the notification event.
+     */
+    eventId: string;
+    /**
+     * Status of the notification request.
+     */
+    status: "accepted" | "rejected";
+    /**
+     * Error message if the notification was rejected.
+     */
+    error?: string;
+}
+
+/**
+ * NotifyKit SDK for JavaScript.
+ * Send notifications from your apps with a simple API.
+ * @module notifykit
+ */
+
+/**
+ * NotifyKit SDK client.
+ * Initialize once with your API key, then send notifications from anywhere.
+ *
+ * @example
+ * ```typescript
+ * import NotifyKit from 'notifykit';
+ *
+ * // Initialize once at startup
+ * NotifyKit.init('nsk_your_api_key');
+ *
+ * // Send notifications anywhere in your app
+ * NotifyKit.notify('User signed up!');
+ * NotifyKit.notify('Payment received', { topic: 'payments' });
+ * ```
+ */
+declare const NotifyKit: {
+    /**
+     * Initializes the NotifyKit SDK with your API key.
+     * Call this once at application startup.
+     *
+     * @param apiKeyOrConfig - Your API key string or full configuration object
+     *
+     * @example
+     * ```typescript
+     * // Simple initialization
+     * NotifyKit.init('nsk_your_api_key');
+     *
+     * // With custom options
+     * NotifyKit.init({
+     *   apiKey: 'nsk_your_api_key',
+     *   debug: true,
+     * });
+     * ```
+     */
+    init(apiKeyOrConfig: string | NotifyKitConfig): void;
+    /**
+     * Sends a notification asynchronously.
+     * This method is fire-and-forget: it won't block your app or throw errors.
+     * Errors are logged to the console but won't crash your application.
+     *
+     * @param message - The notification message to send
+     * @param options - Optional configuration for the notification
+     * @returns A promise that resolves when the notification is sent (or fails silently)
+     *
+     * @example
+     * ```typescript
+     * // Simple notification
+     * NotifyKit.notify('Hello world!');
+     *
+     * // With topic for categorization
+     * NotifyKit.notify('New order received', { topic: 'orders' });
+     *
+     * // With idempotency key to prevent duplicates
+     * NotifyKit.notify('Welcome!', {
+     *   topic: 'onboarding',
+     *   idempotencyKey: `welcome-${userId}`,
+     * });
+     * ```
+     */
+    notify(message: string, options?: NotifyOptions): Promise<void>;
+    /**
+     * Checks if the SDK has been initialized.
+     * @returns True if init() has been called with an API key
+     */
+    isInitialized(): boolean;
+    /**
+     * Resets the SDK state. Useful for testing.
+     */
+    reset(): void;
+};
+
+export { type NotifyKitConfig, type NotifyOptions, type NotifyResponse, NotifyKit as default };

package/dist/index.js

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://api.notifykit.dev";
+var state = {
+  apiKey: null,
+  baseUrl: DEFAULT_BASE_URL,
+  debug: false,
+  initialized: false
+};
+function debugLog(...args) {
+  if (state.debug) {
+    console.log("[NotifyKit]", ...args);
+  }
+}
+function errorLog(...args) {
+  console.error("[NotifyKit]", ...args);
+}
+var NotifyKit = {
+  /**
+   * Initializes the NotifyKit SDK with your API key.
+   * Call this once at application startup.
+   *
+   * @param apiKeyOrConfig - Your API key string or full configuration object
+   *
+   * @example
+   * ```typescript
+   * // Simple initialization
+   * NotifyKit.init('nsk_your_api_key');
+   *
+   * // With custom options
+   * NotifyKit.init({
+   *   apiKey: 'nsk_your_api_key',
+   *   debug: true,
+   * });
+   * ```
+   */
+  init(apiKeyOrConfig) {
+    if (typeof apiKeyOrConfig === "string") {
+      state.apiKey = apiKeyOrConfig;
+      state.baseUrl = DEFAULT_BASE_URL;
+      state.debug = false;
+    } else {
+      state.apiKey = apiKeyOrConfig.apiKey;
+      state.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;
+      state.debug = apiKeyOrConfig.debug || false;
+    }
+    state.initialized = true;
+    debugLog("Initialized with base URL:", state.baseUrl);
+  },
+  /**
+   * Sends a notification asynchronously.
+   * This method is fire-and-forget: it won't block your app or throw errors.
+   * Errors are logged to the console but won't crash your application.
+   *
+   * @param message - The notification message to send
+   * @param options - Optional configuration for the notification
+   * @returns A promise that resolves when the notification is sent (or fails silently)
+   *
+   * @example
+   * ```typescript
+   * // Simple notification
+   * NotifyKit.notify('Hello world!');
+   *
+   * // With topic for categorization
+   * NotifyKit.notify('New order received', { topic: 'orders' });
+   *
+   * // With idempotency key to prevent duplicates
+   * NotifyKit.notify('Welcome!', {
+   *   topic: 'onboarding',
+   *   idempotencyKey: `welcome-${userId}`,
+   * });
+   * ```
+   */
+  async notify(message, options) {
+    if (!state.initialized || !state.apiKey) {
+      errorLog(
+        "NotifyKit not initialized. Call NotifyKit.init() with your API key first."
+      );
+      return;
+    }
+    try {
+      debugLog("Sending notification:", message, options);
+      const headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": state.apiKey
+      };
+      if (options?.idempotencyKey) {
+        headers["Idempotency-Key"] = options.idempotencyKey;
+      }
+      const body = {
+        message
+      };
+      if (options?.topic) {
+        body.topic = options.topic;
+      }
+      const response = await fetch(`${state.baseUrl}/v1/notify`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        errorLog(
+          "Failed to send notification:",
+          response.status,
+          errorData.error || response.statusText
+        );
+        return;
+      }
+      const data = await response.json();
+      debugLog("Notification sent successfully:", data.eventId);
+    } catch (error) {
+      errorLog("Failed to send notification:", error);
+    }
+  },
+  /**
+   * Checks if the SDK has been initialized.
+   * @returns True if init() has been called with an API key
+   */
+  isInitialized() {
+    return state.initialized && state.apiKey !== null;
+  },
+  /**
+   * Resets the SDK state. Useful for testing.
+   */
+  reset() {
+    state.apiKey = null;
+    state.baseUrl = DEFAULT_BASE_URL;
+    state.debug = false;
+    state.initialized = false;
+  }
+};
+var index_default = NotifyKit;

package/dist/index.mjs

@@ -0,0 +1,135 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://api.notifykit.dev";
+var state = {
+  apiKey: null,
+  baseUrl: DEFAULT_BASE_URL,
+  debug: false,
+  initialized: false
+};
+function debugLog(...args) {
+  if (state.debug) {
+    console.log("[NotifyKit]", ...args);
+  }
+}
+function errorLog(...args) {
+  console.error("[NotifyKit]", ...args);
+}
+var NotifyKit = {
+  /**
+   * Initializes the NotifyKit SDK with your API key.
+   * Call this once at application startup.
+   *
+   * @param apiKeyOrConfig - Your API key string or full configuration object
+   *
+   * @example
+   * ```typescript
+   * // Simple initialization
+   * NotifyKit.init('nsk_your_api_key');
+   *
+   * // With custom options
+   * NotifyKit.init({
+   *   apiKey: 'nsk_your_api_key',
+   *   debug: true,
+   * });
+   * ```
+   */
+  init(apiKeyOrConfig) {
+    if (typeof apiKeyOrConfig === "string") {
+      state.apiKey = apiKeyOrConfig;
+      state.baseUrl = DEFAULT_BASE_URL;
+      state.debug = false;
+    } else {
+      state.apiKey = apiKeyOrConfig.apiKey;
+      state.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;
+      state.debug = apiKeyOrConfig.debug || false;
+    }
+    state.initialized = true;
+    debugLog("Initialized with base URL:", state.baseUrl);
+  },
+  /**
+   * Sends a notification asynchronously.
+   * This method is fire-and-forget: it won't block your app or throw errors.
+   * Errors are logged to the console but won't crash your application.
+   *
+   * @param message - The notification message to send
+   * @param options - Optional configuration for the notification
+   * @returns A promise that resolves when the notification is sent (or fails silently)
+   *
+   * @example
+   * ```typescript
+   * // Simple notification
+   * NotifyKit.notify('Hello world!');
+   *
+   * // With topic for categorization
+   * NotifyKit.notify('New order received', { topic: 'orders' });
+   *
+   * // With idempotency key to prevent duplicates
+   * NotifyKit.notify('Welcome!', {
+   *   topic: 'onboarding',
+   *   idempotencyKey: `welcome-${userId}`,
+   * });
+   * ```
+   */
+  async notify(message, options) {
+    if (!state.initialized || !state.apiKey) {
+      errorLog(
+        "NotifyKit not initialized. Call NotifyKit.init() with your API key first."
+      );
+      return;
+    }
+    try {
+      debugLog("Sending notification:", message, options);
+      const headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": state.apiKey
+      };
+      if (options?.idempotencyKey) {
+        headers["Idempotency-Key"] = options.idempotencyKey;
+      }
+      const body = {
+        message
+      };
+      if (options?.topic) {
+        body.topic = options.topic;
+      }
+      const response = await fetch(`${state.baseUrl}/v1/notify`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        errorLog(
+          "Failed to send notification:",
+          response.status,
+          errorData.error || response.statusText
+        );
+        return;
+      }
+      const data = await response.json();
+      debugLog("Notification sent successfully:", data.eventId);
+    } catch (error) {
+      errorLog("Failed to send notification:", error);
+    }
+  },
+  /**
+   * Checks if the SDK has been initialized.
+   * @returns True if init() has been called with an API key
+   */
+  isInitialized() {
+    return state.initialized && state.apiKey !== null;
+  },
+  /**
+   * Resets the SDK state. Useful for testing.
+   */
+  reset() {
+    state.apiKey = null;
+    state.baseUrl = DEFAULT_BASE_URL;
+    state.debug = false;
+    state.initialized = false;
+  }
+};
+var index_default = NotifyKit;
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "notifykitdev",
+  "version": "1.0.0",
+  "description": "Official NotifyKit SDK for JavaScript - Send notifications from your apps",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "notifications",
+    "notifykit",
+    "push",
+    "telegram",
+    "alerts",
+    "sdk"
+  ],
+  "author": "NotifyKit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/notifykit/notifykit-js"
+  },
+  "homepage": "https://notifykit.dev",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}