@notifykit/sdk 1.2.0 → 2.0.0

package/README.md

@@ -40,7 +40,7 @@ const webhookJob = await client.sendWebhook({
 
 Emails are queued immediately (HTTP 202 Accepted) and delivered asynchronously. Use [getJob](#tracking-jobs) to confirm delivery.
 
-> **Note:** On the **Free plan**, emails send from NotifyKit's shared SendGrid account (`noreply@notifykit.dev`). On **Indie/Startup plans**, connect your own SendGrid API key in the dashboard before sending emails.
+> **Note:** On the **Free plan**, emails send from NotifyKit's shared SendGrid account (`noreply@notifykit.dev`). On **Indie/Startup plans**, connect your own SendGrid, Resend, or Postmark API key in the dashboard before sending emails.
 
 ### Basic Email
 
@@ -59,7 +59,7 @@ await client.sendEmail({
   to: "user@example.com",
   subject: "Welcome",
   body: "<h1>Hello</h1>",
-  from: "hello@em.yourapp.com", // Must be a verified domain
+  from: "hello@em.yourapp.com", // Must be a verified sending domain
 });
 ```
 
@@ -87,16 +87,18 @@ await client.sendEmail({
   provider: "SENDGRID",
 });
 
-// Force SendGrid first, then Resend if SendGrid fails. No other providers tried.
+// Force Postmark first, then Resend if Postmark fails. No other providers tried.
 await client.sendEmail({
   to: "user@example.com",
   subject: "Receipt",
   body: "<h1>Thanks</h1>",
-  provider: "SENDGRID",
+  provider: "POSTMARK",
   fallback: "RESEND",
 });
 ```
 
+Valid provider values: `"SENDGRID"` | `"RESEND"` | `"POSTMARK"`
+
 **Validation:**
 
 | Case                                                               | Outcome           |
@@ -104,6 +106,7 @@ await client.sendEmail({
 | `fallback` set without `provider`                                  | `400 Bad Request` |
 | `provider` equals `fallback`                                       | `400 Bad Request` |
 | Requested `provider` or `fallback` not configured for your account | `400 Bad Request` |
+| Either provider used on Free plan                                  | `400 Bad Request` |
 
 Forced routing is a contract: NotifyKit does **not** retry through providers you didn't authorize. The routing fields persist with the job, so manual or automatic retries replay the same attempt set.
 
@@ -130,7 +133,7 @@ await client.sendEmail({
 
 ## Sending Webhooks
 
-Webhooks are queued immediately (HTTP 202 Accepted) and delivered asynchronously with automatic retries on failure.
+Webhooks are queued immediately (HTTP 202 Accepted) and delivered asynchronously with automatic retries on failure. Payloads are capped at **10kb**.
 
 ### Basic Webhook
 
@@ -152,7 +155,6 @@ await client.sendWebhook({
   method: "POST",
   payload: { orderId: "12345" },
   headers: {
-    "X-Webhook-Secret": process.env.WEBHOOK_SECRET!,
     "X-Event-Type": "order.created",
   },
   idempotencyKey: "order-12345-webhook",
@@ -167,6 +169,50 @@ await client.sendWebhook({
 
 ---
 
+## Webhook Signing
+
+When a webhook signing secret is configured in your dashboard, NotifyKit signs every outgoing webhook delivery with HMAC-SHA256. Your receiving endpoint can verify this signature to confirm the request is genuine and hasn't been replayed.
+
+**Headers sent with each delivery:**
+
+| Header                  | Value                          |
+| ----------------------- | ------------------------------ |
+| `X-Webhook-Timestamp`   | Unix timestamp (seconds)       |
+| `X-Webhook-Signature`   | `t=<timestamp>,v1=<hex>`       |
+
+### Verifying Signatures
+
+```typescript
+import { verifyWebhookSignature } from "@notifykit/sdk";
+
+app.post("/webhooks/notifykit", (req, res) => {
+  const valid = verifyWebhookSignature({
+    payload: req.rawBody,                              // raw string — NOT parsed JSON
+    timestamp: req.headers["x-webhook-timestamp"],
+    signature: req.headers["x-webhook-signature"],
+    secret: process.env.NOTIFYKIT_WEBHOOK_SECRET!,
+    tolerance: 300,                                    // optional, default 300s (5 min)
+  });
+
+  if (!valid) return res.status(401).send("Invalid signature");
+
+  const event = req.body;
+  // handle event...
+  res.sendStatus(200);
+});
+```
+
+> **Important:** Always use the **raw body string** (`req.rawBody`), not the parsed JSON object. Re-serializing a parsed object can produce a different byte sequence and will cause verification to fail.
+
+The `tolerance` option rejects requests older than N seconds, protecting against replay attacks. Set it to `0` to disable the time check entirely.
+
+**`verifyWebhookSignature` returns `false` (never throws) when:**
+- The signature header is missing or malformed
+- The timestamp is outside the tolerance window
+- The HMAC digest does not match
+
+---
+
 ## Tracking Jobs
 
 Every notification returns a job ID you can use to track delivery status.
@@ -209,7 +255,7 @@ for (const log of status.deliveryLogs) {
 }
 ```
 
-For successful sends, the last entry's `usedProvider` is the provider that delivered. For failures, it's the last provider attempted. Webhook jobs return an empty array.
+For successful sends, the last entry's `usedProvider` is the provider that delivered. For failures, it's the last provider attempted. Webhook jobs and Free plan jobs return `null` for `usedProvider`.
 
 ### List Jobs with Filters
 
@@ -217,8 +263,8 @@ For successful sends, the last entry's `usedProvider` is the provider that deliv
 const result = await client.listJobs({
   page: 1,
   limit: 20,
-  type: "email", // Filter by type: 'email' or 'webhook'
-  status: "failed", // Filter by status
+  type: "email",   // 'email' | 'webhook'
+  status: "failed", // 'pending' | 'processing' | 'completed' | 'failed'
 });
 
 console.log(`Total: ${result.pagination.total} jobs`);
@@ -266,27 +312,49 @@ try {
 
     if (error.isStatus(400)) console.error("Bad request:", error.message);
     if (error.isStatus(401)) console.error("Invalid API key");
-    if (error.isStatus(403))
-      console.error("Quota or permission error:", error.message);
+    if (error.isStatus(403)) console.error("Quota or permission error:", error.message);
     if (error.isStatus(409)) console.error("Duplicate idempotency key");
-    if (error.isStatus(429)) console.error("Rate limit exceeded");
+    if (error.isStatus(429)) {
+      console.error("Rate limit exceeded");
+      if (error.retryAfter) console.log(`Retry after ${error.retryAfter}s`);
+    }
   }
 }
 ```
 
+### Automatic Retries & Timeouts
+
+The SDK retries transient failures automatically:
+
+- Retries up to **2 times** (3 attempts total) on **5xx**, **429**, and network errors, with backoff (~200ms → ~500ms).
+- On **429**, it waits for the server's `retryAfter` (capped at 10s) before retrying.
+- **Other 4xx errors** (e.g. 400, 401, 409) fail immediately — they are never retried.
+- Non-idempotent requests (`sendEmail`, `sendWebhook`, `retryJob`) are **not** retried on a timeout or dropped connection, to avoid duplicate sends.
+- Every request times out after **10 seconds**.
+
+> This is distinct from NotifyKit's server-side **webhook delivery** retries (see [Sending Webhooks](#sending-webhooks)), which control how delivery to your endpoint is re-attempted.
+
 ---
 
 ## API Reference
 
-| Method                 | Description                     | Returns                         |
-| ---------------------- | ------------------------------- | ------------------------------- |
-| `sendEmail(options)`   | Send an email notification      | `Promise<JobResponse>`          |
-| `sendWebhook(options)` | Send a webhook notification     | `Promise<JobResponse>`          |
-| `getJob(jobId)`        | Get job status and details      | `Promise<JobStatus>`            |
-| `listJobs(options?)`   | List jobs with optional filters | `Promise<{ data, pagination }>` |
-| `retryJob(jobId)`      | Retry a failed job              | `Promise<RetryJobResponse>`     |
-| `ping()`               | Test API connection             | `Promise<string>`               |
-| `getApiInfo()`         | Get API version info            | `Promise<ApiInfo>`              |
+### `NotifyKitClient` methods
+
+| Method                          | Description                     | Returns                         |
+| ------------------------------- | ------------------------------- | ------------------------------- |
+| `sendEmail(options)`            | Send an email notification      | `Promise<JobResponse>`          |
+| `sendWebhook(options)`          | Send a webhook notification     | `Promise<JobResponse>`          |
+| `getJob(jobId)`                 | Get job status and delivery logs | `Promise<JobStatus>`            |
+| `listJobs(options?)`            | List jobs with optional filters | `Promise<{ data, pagination }>` |
+| `retryJob(jobId)`               | Retry a failed job              | `Promise<RetryJobResponse>`     |
+| `ping()`                        | Test API connection             | `Promise<string>`               |
+| `getApiInfo()`                  | Get API version info            | `Promise<ApiInfo>`              |
+
+### Standalone utilities
+
+| Function                        | Description                                        |
+| ------------------------------- | -------------------------------------------------- |
+| `verifyWebhookSignature(options)` | Verify HMAC-SHA256 signature on incoming webhooks |
 
 ### TypeScript Types
 
@@ -296,7 +364,13 @@ import type {
   SendEmailOptions,
   SendWebhookOptions,
   JobResponse,
+  JobStatus,
+  JobSummary,
+  DeliveryLog,
+  RetryJobResponse,
   ApiInfo,
+  EmailProvider,
+  VerifyWebhookSignatureOptions,
 } from "@notifykit/sdk";
 ```
 
@@ -304,11 +378,11 @@ import type {
 
 ## Plans
 
-| Plan    | Price  | Webhooks/month | Emails/month                      |
-| ------- | ------ | -------------- | --------------------------------- |
-| Free    | $0     | 100 (shared)   | 100 (shared with webhooks)        |
-| Indie   | $9/mo  | 4,000          | Unlimited (via your SendGrid key) |
-| Startup | $30/mo | 15,000         | Unlimited (via your SendGrid key) |
+| Plan    | Price   | Webhooks/month | Emails/month               | Rate limit   |
+| ------- | ------- | -------------- | -------------------------- | ------------ |
+| Free    | $0      | 100 (shared)   | 100 (shared with webhooks) | 5 req/min    |
+| Indie   | $5/mo   | 4,000          | Unlimited (via your key)   | 50 req/min   |
+| Startup | $10/mo  | 15,000         | Unlimited (via your key)   | 200 req/min  |
 
 ---
 

package/dist/client.d.ts

@@ -1,7 +1,9 @@
 import { NotifyKitConfig, SendEmailOptions, SendWebhookOptions, JobResponse, JobStatus, JobSummary, ApiInfo, PaginationMeta, RetryJobResponse } from './types';
 export declare class NotifyKitClient {
-    private client;
+    private readonly baseUrl;
+    private readonly headers;
     constructor(config: NotifyKitConfig);
+    private request;
     /** Test API connection */
     ping(): Promise<string>;
     /** Get API information */

package/dist/client.js

@@ -1,94 +1,145 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotifyKitClient = void 0;
-const axios_1 = __importDefault(require("axios"));
 const errors_1 = require("./errors");
+/** Abort a request that hasn't responded within this window. */
+const TIMEOUT_MS = 10000;
+/** Backoff delays between retries; length also caps the retry count (2 retries / 3 attempts). */
+const RETRY_DELAYS_MS = [200, 500];
+/** Upper bound for a server-provided Retry-After so a caller can't be stalled indefinitely. */
+const MAX_RETRY_AFTER_MS = 10000;
+/**
+ * Methods we can safely re-send after a transport failure (timeout / dropped connection).
+ * A timed-out POST may already have been processed by the server, so retrying it could
+ * duplicate a notification — only idempotent methods are retried on transport errors.
+ */
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD']);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Transient server states worth retrying regardless of HTTP method. */
+function isRetryableStatus(status) {
+    return status >= 500 || status === 429;
+}
+function describeTransportError(err) {
+    if (err instanceof Error && err.name === 'TimeoutError')
+        return 'Request timed out';
+    if (err instanceof Error)
+        return err.message;
+    return 'Network error occurred';
+}
+/** Build a NotifyKitError from a non-OK (or success:false) response body. */
+function toError(status, statusText, data) {
+    let message = statusText || 'Request failed';
+    let errors;
+    let retryAfter;
+    if (data) {
+        const detail = data.error ?? data.message;
+        if (Array.isArray(detail)) {
+            errors = detail;
+            message = data.error ? detail.join(', ') : 'Validation failed';
+        }
+        else if (detail != null) {
+            message = String(detail);
+        }
+        if (status === 429 && typeof data.retryAfter === 'number') {
+            retryAfter = data.retryAfter;
+        }
+    }
+    return new errors_1.NotifyKitError(message, status, data, errors, retryAfter);
+}
 class NotifyKitClient {
     constructor(config) {
         if (!config.apiKey) {
             throw new Error('API key is required');
         }
-        this.client = axios_1.default.create({
-            baseURL: config.baseUrl || 'https://api.notifykit.dev',
-            headers: {
-                'X-API-Key': config.apiKey,
-                'Content-Type': 'application/json',
-            },
-        });
-        this.client.interceptors.response.use((response) => {
-            const apiResponse = response.data;
-            if (apiResponse && apiResponse.success === false) {
-                throw new errors_1.NotifyKitError(apiResponse.error || apiResponse.message || 'Request failed', response.status, apiResponse);
+        this.baseUrl = (config.baseUrl ?? 'https://api.notifykit.dev').replace(/\/$/, '');
+        this.headers = {
+            'X-API-Key': config.apiKey,
+            'Content-Type': 'application/json',
+        };
+    }
+    async request(method, path, body) {
+        const retryTransport = IDEMPOTENT_METHODS.has(method);
+        for (let attempt = 0;; attempt++) {
+            const isLastAttempt = attempt >= RETRY_DELAYS_MS.length;
+            // --- Send ---
+            let res;
+            try {
+                res = await fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: this.headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(TIMEOUT_MS),
+                });
             }
-            return apiResponse?.data ?? apiResponse;
-        }, (error) => {
-            if (error.response) {
-                const data = error.response.data;
-                const statusCode = error.response.status;
-                let message = error.message;
-                let errors = null;
-                if (data?.error) {
-                    if (Array.isArray(data.error)) {
-                        errors = data.error;
-                        message = data.error.join(', ');
-                    }
-                    else {
-                        message = data.error;
-                    }
+            catch (err) {
+                // Transport failure: retry only idempotent requests, and only while attempts remain.
+                if (retryTransport && !isLastAttempt) {
+                    await sleep(RETRY_DELAYS_MS[attempt]);
+                    continue;
                 }
-                else if (data?.message) {
-                    if (Array.isArray(data.message)) {
-                        errors = data.message;
-                        message = 'Validation failed';
-                    }
-                    else {
-                        message = data.message;
-                    }
-                }
-                const retryAfter = statusCode === 429 && typeof data?.retryAfter === 'number' ? data.retryAfter : undefined;
-                throw new errors_1.NotifyKitError(message, statusCode, data, errors, retryAfter);
+                throw new errors_1.NotifyKitError(describeTransportError(err));
+            }
+            const data = await res.json().catch(() => null);
+            // --- Success ---
+            if (res.ok && data?.success !== false) {
+                return (data?.data ?? data);
             }
-            throw new errors_1.NotifyKitError(error.message || 'Network error occurred');
-        });
+            // --- Failure ---
+            const error = toError(res.status, res.statusText, data);
+            // Retry transient server states (5xx / 429) for any method; a 4xx fails immediately.
+            if (isRetryableStatus(res.status) && !isLastAttempt) {
+                const delay = error.retryAfter != null
+                    ? Math.min(error.retryAfter * 1000, MAX_RETRY_AFTER_MS)
+                    : RETRY_DELAYS_MS[attempt];
+                await sleep(delay);
+                continue;
+            }
+            throw error;
+        }
     }
     // ================================
     // APP
     // ================================
     /** Test API connection */
     async ping() {
-        return await this.client.get('/api/v1/ping');
+        return this.request('GET', '/api/v1/ping');
     }
     /** Get API information */
     async getApiInfo() {
-        return await this.client.get('/api/v1/info');
+        return this.request('GET', '/api/v1/info');
     }
     // ================================
     // NOTIFICATIONS
     // ================================
     /** Send an email notification */
     async sendEmail(options) {
-        return await this.client.post('/api/v1/notifications/email', options);
+        return this.request('POST', '/api/v1/notifications/email', options);
     }
     /** Send a webhook notification */
     async sendWebhook(options) {
-        return await this.client.post('/api/v1/notifications/webhook', options);
+        return this.request('POST', '/api/v1/notifications/webhook', options);
     }
     /** Get job status by ID */
     async getJob(jobId) {
-        return await this.client.get(`/api/v1/notifications/jobs/${jobId}`);
+        return this.request('GET', `/api/v1/notifications/jobs/${jobId}`);
     }
     /** List jobs with optional filters */
     async listJobs(options) {
-        return await this.client.get('/api/v1/notifications/jobs', {
-            params: options,
-        });
+        let path = '/api/v1/notifications/jobs';
+        if (options) {
+            const params = new URLSearchParams(Object.entries(options)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => [k, String(v)]));
+            if (params.size > 0)
+                path += `?${params}`;
+        }
+        return this.request('GET', path);
     }
     /** Retry a failed job */
     async retryJob(jobId) {
-        return await this.client.post(`/api/v1/notifications/jobs/${jobId}/retry`);
+        return this.request('POST', `/api/v1/notifications/jobs/${jobId}/retry`);
     }
 }
 exports.NotifyKitClient = NotifyKitClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notifykit/sdk",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Official NotifyKit SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
     "prepublishOnly": "npm run build"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "keywords": [
     "notifykit",
@@ -33,9 +33,7 @@
     "url": "https://github.com/brayzonn/notifykit-sdk/issues"
   },
   "homepage": "https://github.com/brayzonn/notifykit-sdk#readme",
-  "dependencies": {
-    "axios": "^1.6.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"