@asyncify-hq/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubam Patil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @asyncify-hq/node
+
+Server-side SDK for [Asyncify](https://asyncify.org) — multi-channel
+notification infrastructure. One trigger call fans out to email, SMS, push
+and in-app, with priority queues, retries, digests and delivery tracking
+handled for you.
+
+## Install
+
+```bash
+npm install @asyncify-hq/node
+```
+
+## Quickstart
+
+```ts
+import { AsyncifyClient } from '@asyncify-hq/node';
+
+const asyncify = new AsyncifyClient({
+  apiKey: process.env.ASYNCIFY_API_KEY!,
+  baseUrl: 'https://api.your-deployment.com',
+});
+
+// Fire a workflow for a user
+await asyncify.trigger('order-shipped', {
+  to: [{ subscriberId: 'user-42', email: 'user42@example.com' }],
+  payload: { orderId: 'ORD-1', eta: 'Tuesday' },
+});
+
+// Idempotent retries: same transactionId can never double-send
+await asyncify.trigger('otp', {
+  to: [{ subscriberId: 'user-42', phone: '+15550001111' }],
+  payload: { code: '123456' },
+  priority: 'p0',
+  transactionId: `otp-${loginAttemptId}`,
+});
+
+// Send to a topic (named segment) or to everyone
+await asyncify.trigger('changelog', { to: [{ topic: 'beta-users' }] });
+await asyncify.broadcast('maintenance-notice');
+```
+
+## The inbox widget token
+
+Mint a short-lived, single-subscriber token in your backend and hand it to
+[`@asyncify-hq/react`](https://www.npmjs.com/package/@asyncify-hq/react) in
+your frontend — API keys never reach the browser:
+
+```ts
+const { token } = await asyncify.subscriberToken('user-42');
+```
+
+## API surface
+
+| Method | Purpose |
+|---|---|
+| `trigger(workflowKey, { to, payload, priority?, transactionId? })` | Fire a workflow (recipients and/or `{ topic }` refs) |
+| `broadcast(workflowKey, { payload? })` | Send to every subscriber (bulk tier) |
+| `events.get(transactionId)` | Per-channel delivery status |
+| `subscribers.upsert({ subscriberId, email?, phone?, pushToken? })` | Create/update a subscriber |
+| `topics.upsert / addSubscribers / removeSubscribers / list / delete` | Manage segments |
+| `workflows.upsert / list` · `templates.upsert / get / list / delete` | Manage workflows & MJML templates |
+| `subscriberToken(subscriberId, ttlSeconds?)` | Browser-safe inbox token |
+
+Errors throw `AsyncifyError` with `status` and the API's message.
+
+MIT © Shubam Patil

package/dist/index.cjs

@@ -0,0 +1,110 @@
+"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, {
+  AsyncifyClient: () => AsyncifyClient,
+  AsyncifyError: () => AsyncifyError
+});
+module.exports = __toCommonJS(index_exports);
+var AsyncifyError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AsyncifyError";
+  }
+  status;
+};
+var AsyncifyClient = class {
+  apiKey;
+  baseUrl;
+  constructor(options) {
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "http://localhost:3000").replace(/\/$/, "");
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new AsyncifyError(res.status, data.error ?? `request failed (${res.status})`);
+    }
+    return data;
+  }
+  /** Fire a workflow for specific recipients. */
+  trigger(workflowKey, options) {
+    return this.request("POST", "/v1/events/trigger", { workflowKey, ...options });
+  }
+  /** Send a workflow to EVERY subscriber in the environment (bulk tier by default). */
+  broadcast(workflowKey, options = {}) {
+    return this.request("POST", "/v1/events/broadcast", { workflowKey, ...options });
+  }
+  workflows = {
+    upsert: (workflow) => this.request("PUT", "/v1/workflows", workflow),
+    list: () => this.request("GET", "/v1/workflows")
+  };
+  subscribers = {
+    upsert: (subscriber) => this.request("PUT", "/v1/subscribers", subscriber)
+  };
+  templates = {
+    upsert: (template) => this.request("PUT", "/v1/templates", template),
+    list: () => this.request("GET", "/v1/templates"),
+    get: (key) => this.request("GET", `/v1/templates/${encodeURIComponent(key)}`),
+    delete: (key) => this.request("DELETE", `/v1/templates/${encodeURIComponent(key)}`)
+  };
+  topics = {
+    upsert: (key, name) => this.request("PUT", "/v1/topics", { key, name }),
+    list: () => this.request("GET", "/v1/topics"),
+    addSubscribers: (key, subscriberIds) => this.request(
+      "POST",
+      `/v1/topics/${encodeURIComponent(key)}/subscribers`,
+      { subscriberIds }
+    ),
+    removeSubscribers: (key, subscriberIds) => this.request(
+      "DELETE",
+      `/v1/topics/${encodeURIComponent(key)}/subscribers`,
+      { subscriberIds }
+    ),
+    delete: (key) => this.request("DELETE", `/v1/topics/${encodeURIComponent(key)}`)
+  };
+  events = {
+    /** Delivery status of one trigger. */
+    get: (transactionId) => this.request(
+      "GET",
+      `/v1/events/${encodeURIComponent(transactionId)}`
+    )
+  };
+  /**
+   * Mint a short-lived token scoped to one subscriber — pass it to the
+   * <NotificationInbox /> widget in your frontend. Never ship the api key.
+   */
+  subscriberToken(subscriberId, ttlSeconds = 3600) {
+    return this.request("POST", "/v1/subscriber-tokens", { subscriberId, ttlSeconds });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncifyClient,
+  AsyncifyError
+});

package/dist/index.d.cts

@@ -0,0 +1,157 @@
+/**
+ * @asyncify-hq/node — server-side client for Asyncify.
+ *
+ *   const asyncify = new AsyncifyClient({ apiKey: process.env.ASYNCIFY_API_KEY! });
+ *   await asyncify.trigger('order-shipped', {
+ *     to: [{ subscriberId: 'user-42', email: 'u42@example.com' }],
+ *     payload: { orderId: 'ORD-1' },
+ *   });
+ *
+ * Zero dependencies — plain fetch over the REST API.
+ */
+interface Recipient {
+    subscriberId: string;
+    email?: string;
+    phone?: string;
+    pushToken?: string;
+}
+type Priority = 'p0' | 'p1' | 'p2';
+/** Direct recipient, or a topic reference ({ topic: "beta-users" }). */
+type TriggerRecipient = Recipient | {
+    topic: string;
+};
+interface TriggerOptions {
+    to: TriggerRecipient[];
+    payload?: Record<string, unknown>;
+    priority?: Priority;
+    /** Provide your own id to make the trigger idempotent across retries. */
+    transactionId?: string;
+}
+interface TriggerResult {
+    transactionId: string;
+    eventId?: string;
+    duplicate?: boolean;
+    priority?: Priority;
+}
+interface WorkflowStep {
+    channel: 'email' | 'sms' | 'push' | 'inapp';
+    subject?: string;
+    body?: string;
+    /** Email steps: render this MJML template instead of an inline body. */
+    templateKey?: string;
+    delaySeconds?: number;
+    digest?: {
+        windowSeconds: number;
+        itemTemplate?: string;
+    };
+    /** All must pass; evaluated over payload + subscriber at fan-out. */
+    conditions?: Array<{
+        field: string;
+        op: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'exists' | 'not_exists';
+        value?: unknown;
+    }>;
+    /** Skip at delivery time if an earlier step reached one of these states. */
+    skipIfStep?: {
+        stepIndex: number;
+        statusIn: string[];
+    };
+}
+declare class AsyncifyError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface AsyncifyClientOptions {
+    apiKey: string;
+    /** Defaults to http://localhost:3000 — point at your deployment. */
+    baseUrl?: string;
+}
+declare class AsyncifyClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: AsyncifyClientOptions);
+    private request;
+    /** Fire a workflow for specific recipients. */
+    trigger(workflowKey: string, options: TriggerOptions): Promise<TriggerResult>;
+    /** Send a workflow to EVERY subscriber in the environment (bulk tier by default). */
+    broadcast(workflowKey: string, options?: {
+        payload?: Record<string, unknown>;
+        priority?: Priority;
+        transactionId?: string;
+    }): Promise<TriggerResult & {
+        broadcast: boolean;
+    }>;
+    readonly workflows: {
+        upsert: (workflow: {
+            key: string;
+            name: string;
+            steps: WorkflowStep[];
+        }) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        list: () => Promise<{
+            workflows: unknown[];
+        }>;
+    };
+    readonly subscribers: {
+        upsert: (subscriber: Recipient) => Promise<{
+            id: string;
+            subscriberId: string;
+        }>;
+    };
+    readonly templates: {
+        upsert: (template: {
+            key: string;
+            name: string;
+            subject: string;
+            mjml: string;
+        }) => Promise<{
+            key: string;
+            version: number;
+        }>;
+        list: () => Promise<{
+            templates: unknown[];
+        }>;
+        get: (key: string) => Promise<{
+            template: unknown;
+        }>;
+        delete: (key: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly topics: {
+        upsert: (key: string, name: string) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        list: () => Promise<{
+            topics: unknown[];
+        }>;
+        addSubscribers: (key: string, subscriberIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeSubscribers: (key: string, subscriberIds: string[]) => Promise<{
+            removed: number;
+        }>;
+        delete: (key: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly events: {
+        /** Delivery status of one trigger. */
+        get: (transactionId: string) => Promise<{
+            status: string;
+            messages: unknown[];
+        }>;
+    };
+    /**
+     * Mint a short-lived token scoped to one subscriber — pass it to the
+     * <NotificationInbox /> widget in your frontend. Never ship the api key.
+     */
+    subscriberToken(subscriberId: string, ttlSeconds?: number): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+}
+
+export { AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type Priority, type Recipient, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @asyncify-hq/node — server-side client for Asyncify.
+ *
+ *   const asyncify = new AsyncifyClient({ apiKey: process.env.ASYNCIFY_API_KEY! });
+ *   await asyncify.trigger('order-shipped', {
+ *     to: [{ subscriberId: 'user-42', email: 'u42@example.com' }],
+ *     payload: { orderId: 'ORD-1' },
+ *   });
+ *
+ * Zero dependencies — plain fetch over the REST API.
+ */
+interface Recipient {
+    subscriberId: string;
+    email?: string;
+    phone?: string;
+    pushToken?: string;
+}
+type Priority = 'p0' | 'p1' | 'p2';
+/** Direct recipient, or a topic reference ({ topic: "beta-users" }). */
+type TriggerRecipient = Recipient | {
+    topic: string;
+};
+interface TriggerOptions {
+    to: TriggerRecipient[];
+    payload?: Record<string, unknown>;
+    priority?: Priority;
+    /** Provide your own id to make the trigger idempotent across retries. */
+    transactionId?: string;
+}
+interface TriggerResult {
+    transactionId: string;
+    eventId?: string;
+    duplicate?: boolean;
+    priority?: Priority;
+}
+interface WorkflowStep {
+    channel: 'email' | 'sms' | 'push' | 'inapp';
+    subject?: string;
+    body?: string;
+    /** Email steps: render this MJML template instead of an inline body. */
+    templateKey?: string;
+    delaySeconds?: number;
+    digest?: {
+        windowSeconds: number;
+        itemTemplate?: string;
+    };
+    /** All must pass; evaluated over payload + subscriber at fan-out. */
+    conditions?: Array<{
+        field: string;
+        op: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'exists' | 'not_exists';
+        value?: unknown;
+    }>;
+    /** Skip at delivery time if an earlier step reached one of these states. */
+    skipIfStep?: {
+        stepIndex: number;
+        statusIn: string[];
+    };
+}
+declare class AsyncifyError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface AsyncifyClientOptions {
+    apiKey: string;
+    /** Defaults to http://localhost:3000 — point at your deployment. */
+    baseUrl?: string;
+}
+declare class AsyncifyClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: AsyncifyClientOptions);
+    private request;
+    /** Fire a workflow for specific recipients. */
+    trigger(workflowKey: string, options: TriggerOptions): Promise<TriggerResult>;
+    /** Send a workflow to EVERY subscriber in the environment (bulk tier by default). */
+    broadcast(workflowKey: string, options?: {
+        payload?: Record<string, unknown>;
+        priority?: Priority;
+        transactionId?: string;
+    }): Promise<TriggerResult & {
+        broadcast: boolean;
+    }>;
+    readonly workflows: {
+        upsert: (workflow: {
+            key: string;
+            name: string;
+            steps: WorkflowStep[];
+        }) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        list: () => Promise<{
+            workflows: unknown[];
+        }>;
+    };
+    readonly subscribers: {
+        upsert: (subscriber: Recipient) => Promise<{
+            id: string;
+            subscriberId: string;
+        }>;
+    };
+    readonly templates: {
+        upsert: (template: {
+            key: string;
+            name: string;
+            subject: string;
+            mjml: string;
+        }) => Promise<{
+            key: string;
+            version: number;
+        }>;
+        list: () => Promise<{
+            templates: unknown[];
+        }>;
+        get: (key: string) => Promise<{
+            template: unknown;
+        }>;
+        delete: (key: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly topics: {
+        upsert: (key: string, name: string) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        list: () => Promise<{
+            topics: unknown[];
+        }>;
+        addSubscribers: (key: string, subscriberIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeSubscribers: (key: string, subscriberIds: string[]) => Promise<{
+            removed: number;
+        }>;
+        delete: (key: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly events: {
+        /** Delivery status of one trigger. */
+        get: (transactionId: string) => Promise<{
+            status: string;
+            messages: unknown[];
+        }>;
+    };
+    /**
+     * Mint a short-lived token scoped to one subscriber — pass it to the
+     * <NotificationInbox /> widget in your frontend. Never ship the api key.
+     */
+    subscriberToken(subscriberId: string, ttlSeconds?: number): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+}
+
+export { AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type Priority, type Recipient, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };

package/dist/index.js

@@ -0,0 +1,84 @@
+// src/index.ts
+var AsyncifyError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AsyncifyError";
+  }
+  status;
+};
+var AsyncifyClient = class {
+  apiKey;
+  baseUrl;
+  constructor(options) {
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "http://localhost:3000").replace(/\/$/, "");
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new AsyncifyError(res.status, data.error ?? `request failed (${res.status})`);
+    }
+    return data;
+  }
+  /** Fire a workflow for specific recipients. */
+  trigger(workflowKey, options) {
+    return this.request("POST", "/v1/events/trigger", { workflowKey, ...options });
+  }
+  /** Send a workflow to EVERY subscriber in the environment (bulk tier by default). */
+  broadcast(workflowKey, options = {}) {
+    return this.request("POST", "/v1/events/broadcast", { workflowKey, ...options });
+  }
+  workflows = {
+    upsert: (workflow) => this.request("PUT", "/v1/workflows", workflow),
+    list: () => this.request("GET", "/v1/workflows")
+  };
+  subscribers = {
+    upsert: (subscriber) => this.request("PUT", "/v1/subscribers", subscriber)
+  };
+  templates = {
+    upsert: (template) => this.request("PUT", "/v1/templates", template),
+    list: () => this.request("GET", "/v1/templates"),
+    get: (key) => this.request("GET", `/v1/templates/${encodeURIComponent(key)}`),
+    delete: (key) => this.request("DELETE", `/v1/templates/${encodeURIComponent(key)}`)
+  };
+  topics = {
+    upsert: (key, name) => this.request("PUT", "/v1/topics", { key, name }),
+    list: () => this.request("GET", "/v1/topics"),
+    addSubscribers: (key, subscriberIds) => this.request(
+      "POST",
+      `/v1/topics/${encodeURIComponent(key)}/subscribers`,
+      { subscriberIds }
+    ),
+    removeSubscribers: (key, subscriberIds) => this.request(
+      "DELETE",
+      `/v1/topics/${encodeURIComponent(key)}/subscribers`,
+      { subscriberIds }
+    ),
+    delete: (key) => this.request("DELETE", `/v1/topics/${encodeURIComponent(key)}`)
+  };
+  events = {
+    /** Delivery status of one trigger. */
+    get: (transactionId) => this.request(
+      "GET",
+      `/v1/events/${encodeURIComponent(transactionId)}`
+    )
+  };
+  /**
+   * Mint a short-lived token scoped to one subscriber — pass it to the
+   * <NotificationInbox /> widget in your frontend. Never ship the api key.
+   */
+  subscriberToken(subscriberId, ttlSeconds = 3600) {
+    return this.request("POST", "/v1/subscriber-tokens", { subscriberId, ttlSeconds });
+  }
+};
+export {
+  AsyncifyClient,
+  AsyncifyError
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@asyncify-hq/node",
+  "version": "0.1.0",
+  "description": "Server-side SDK for Asyncify — multi-channel notification infrastructure (email, SMS, push, in-app)",
+  "keywords": ["notifications", "email", "sms", "push", "in-app", "asyncify", "notification-infrastructure"],
+  "homepage": "https://asyncify.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shubam14dec/Scalable-Notification-System.git",
+    "directory": "packages/sdk-node"
+  },
+  "license": "MIT",
+  "author": "Shubam Patil",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}