@tilli-pro/nudge.js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tilli
+
+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,56 @@
+# nudge.js
+> A nudge in time saves nine
+
+The nudge.js SDK is a lightweight (**ZERO** dependencies) wrapper around [nudge](http://nudge.pro/) and its [APIs](https://app.nudge.net/api/swagger/index.html#/).
+
+## Getting Started
+
+The nudge.js SDK clients come in 2 flavors:
+
+1) The fully featured nudge.js client that exposes all API capabilities within nudge
+2) The "Send" client which specifically only supports sending real-time nudges
+
+To use the nudge.js SDK you need either [an API key](https://help.nudge.net/article/38-nudge-api-documentation) (for sending real-time nudges via the "Send" client) or the user credentials used to log into app.nudge.net (all other functionality).
+
+> [!TIP]
+> If you're not sure how to get an API key, you can read more here: [Nudge API Documentation](https://help.nudge.net/article/38-nudge-api-documentation)
+
+In either case, getting started is the same:
+
+```ts
+import { createSendClient, createClient } from "@tilli-pro/nudge.js";
+
+const apiKey = ""; // get this from the nudge dashboard
+const sendClient = createSendClient({ apiKey });
+
+// credentials used to login to app.nudge.net
+const authCredentials = {
+  email: "",
+  password: "",
+};
+const client = createClient({ apiKey, authCredentials });
+```
+
+The clients can be used immediately for sending real-time nudges:
+
+```ts
+sendClient.send({
+  nudgeId: "1234" // you can get this from the nudge dashboard,
+  recipient: {
+    email: "ibrahims@tilli.pro",
+    name: "Ibrahim Ali", // OPTIONAL
+  },
+  options: { // OPTIONAL
+    cc: ["michaelv@tilli.pro"] // OPTIONAL
+    bcc: ["avdhoots@tilli.pro"] // OPTIONAL
+  },
+  mergeTags: { // OPTIONAL
+    productName: "tilliX",
+  },
+  files: [ // OPTIONAL
+    new File(["test_document_text"], "test_document.txt", { type: "text/plain" }),
+  ],
+})
+```
+
+That's it. Your nudge has been sent.

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+import type { NudgeSendClient } from "./send";
+interface NudgeBaseResponse<T> {
+    data: T | null;
+    code: number;
+    errCode: number;
+    errors: string[];
+    hasErrors: boolean;
+    errorGuid: string;
+}
+export interface ClientCreationOpts {
+    apiKey: string;
+    baseUrl?: string;
+    authCredentials: {
+        email: string;
+        password: string;
+    };
+}
+interface NudgeListOpts {
+    top?: number;
+    orderBy?: "ScheduleOn desc" | "ScheduleOn asc";
+}
+interface NudgeListResponse {
+    pageData: {
+        id: number;
+        nudgeName: string;
+        insensitiveName: string;
+        description: string | null;
+        scheduledOn: string;
+        createdOn: string;
+        status: number;
+        nudgeType: number;
+        templateId: number;
+        sendWithoutRecipient: boolean;
+        projectName: string | null;
+        insensitiveProjectName: string | null;
+        lastModifiedByUser: string;
+        insensitiveLastModifiedByUser: string;
+        modifiedDate: string;
+    }[];
+    totalCount: number;
+    errors: number;
+}
+interface NudgeClient extends NudgeSendClient {
+    listNudges: (opts?: NudgeListOpts) => Promise<NudgeBaseResponse<NudgeListResponse>>;
+}
+export declare function createClient({ baseUrl, apiKey, authCredentials }: ClientCreationOpts): NudgeClient;
+export {};

package/dist/client.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const config_1 = require("./config");
+const send_1 = require("./send");
+function createClient({ baseUrl = config_1.BASE_PROD_URL, apiKey, authCredentials }) {
+    if (typeof fetch !== "function") {
+        throw new Error("fetch must exist to use nudge.js.");
+    }
+    else if (baseUrl.endsWith("/")) {
+        baseUrl = baseUrl.slice(0, -1); // Remove trailing slash if present
+    }
+    let bearerToken = null;
+    const $connect = async () => {
+        try {
+            const signInResponse = await fetch(`${baseUrl}/Session/SignIn`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json"
+                },
+                body: JSON.stringify({
+                    email: authCredentials.email,
+                    password: authCredentials.password,
+                    keepMeSignedIn: false
+                }),
+            });
+            if (!signInResponse.ok) {
+                throw new Error("Failed to sign in to Nudge API.");
+            }
+            const signInData = (await signInResponse.json());
+            if (signInData.hasErrors || !signInData.data || !signInData.data.jwtToken) {
+                throw new Error("Failed to sign in to Nudge API: " + signInData.errors.join(", "));
+            }
+            bearerToken = signInData.data.jwtToken;
+            return true;
+        }
+        catch (e) {
+            console.error("Error connecting to Nudge API:", e);
+        }
+        return false;
+    };
+    let connectionPromise = null;
+    const checkConnected = (fn) => async (...args) => {
+        if (!connectionPromise && !bearerToken) {
+            connectionPromise = $connect();
+        }
+        if (connectionPromise) {
+            const result = await connectionPromise;
+            if (!bearerToken || !result) {
+                throw new Error("Not connected to Nudge API.");
+            }
+        }
+        try {
+            return fn(...args);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.includes("Unauthorized")) {
+                bearerToken = null;
+            }
+            throw e;
+        }
+    };
+    console.warn("The Nudge API client is currently undergoing active development. The vast majority of API features are not yet implemented. Please use with caution and report any issues you encounter.");
+    return {
+        send: (opts) => (0, send_1.sendNudge)({ baseUrl, apiKey }, opts),
+        listNudges: checkConnected(async (opts) => {
+            const apiUrl = `${baseUrl}/api/EmailNudge/List`;
+            const params = new URLSearchParams();
+            // TODO: What validations exist for these options?
+            if (opts?.top) {
+                params.append("top", opts.top.toString());
+            }
+            if (opts?.orderBy) {
+                params.append("orderBy", opts.orderBy);
+            }
+            const stringParams = params.toString();
+            const url = stringParams ? `${apiUrl}?${stringParams}` : apiUrl;
+            const listResponse = await fetch(url, {
+                method: "GET",
+                headers: {
+                    accept: "application/json",
+                    authorization: `Bearer ${bearerToken}`,
+                }
+            });
+            return listResponse.json();
+        })
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1 @@
+export declare const BASE_PROD_URL = "https://app.nudge.net/api";

package/dist/config.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_PROD_URL = void 0;
+exports.BASE_PROD_URL = "https://app.nudge.net/api";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./send";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./send"), exports);
+__exportStar(require("./types"), exports);

package/dist/send.d.ts

@@ -0,0 +1,33 @@
+import type { ClientCreationOpts } from "./client";
+export interface NudgeSendOpts {
+    nudgeId: string;
+    recipient: EmailRecipient;
+    options?: {
+        cc?: string[];
+        bcc?: string[];
+    };
+    mergeTags?: MergeTag[] | Record<string, string>;
+    files?: File[];
+}
+export type NudgeSendResult = {
+    success: boolean;
+    error?: undefined;
+} | {
+    success: false;
+    error: unknown;
+};
+export interface NudgeSendClient {
+    send(opts: NudgeSendOpts): Promise<NudgeSendResult>;
+}
+export interface EmailRecipient {
+    email: string;
+    name?: string;
+}
+export interface MergeTag {
+    tagName: string;
+    tagValue: string;
+}
+export declare function sendNudge(client: SendClientCreationOpts, opts: NudgeSendOpts): Promise<NudgeSendResult>;
+type SendClientCreationOpts = Omit<ClientCreationOpts, "authCredentials">;
+export declare function createSendClient({ baseUrl, apiKey }: SendClientCreationOpts): NudgeSendClient;
+export {};

package/dist/send.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendNudge = sendNudge;
+exports.createSendClient = createSendClient;
+async function createFileBuffer(file) {
+    const buffer = await file.arrayBuffer();
+    const uint8Array = new Uint8Array(buffer);
+    if (typeof btoa === "function") {
+        return await new Blob([buffer]).text();
+    }
+    else if (typeof Buffer === "function") {
+        return Buffer.from(uint8Array).toString("base64");
+    }
+    else {
+        throw new Error("No base64 encoding method available.");
+    }
+}
+async function sendNudge(client, opts) {
+    const _mergeTags = opts.mergeTags ?? [];
+    const mergeTags = Array.isArray(_mergeTags) ? _mergeTags : Object.entries(_mergeTags).map(([tagName, tagValue]) => ({ tagName, tagValue }));
+    const emailAttachments = [];
+    if (opts.files?.length) {
+        const filePromises = opts.files.map(file => {
+            return new Promise((resolve, reject) => {
+                createFileBuffer(file).then(text => resolve({ content: text, mimeType: file.type, fileName: file.name })).catch(reject);
+            });
+        });
+        emailAttachments.push(...(await Promise.all(filePromises)));
+    }
+    const result = await fetch(`${client.baseUrl}/Nudge/Send`, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            authorization: client.apiKey,
+        },
+        body: JSON.stringify({
+            nudgeId: opts.nudgeId,
+            toEmailAddress: opts.recipient.email,
+            toName: opts.recipient.name,
+            mergeTags,
+            channel: 0,
+            emailCc: opts.options?.cc?.join(","),
+            emailBcc: opts.options?.bcc?.join(","),
+            emailAttachments
+        })
+    });
+    if (!result.ok) {
+        const error = await result.json();
+        return { success: false, error };
+    }
+    const response = await result.json();
+    if (response.error) {
+        return { success: false, error: response.error };
+    }
+    return { success: true };
+}
+function createSendClient({ baseUrl = "https://app.nudge.net/api/v2", apiKey }) {
+    if (typeof fetch !== "function") {
+        throw new Error("fetch must exist to use nudge.js.");
+    }
+    const client = {
+        send: async (opts) => {
+            return sendNudge({ baseUrl, apiKey }, opts);
+        }
+    };
+    return client;
+}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type AnyFunction = (...args: any[]) => any;
+export type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tilli-pro/nudge.js",
+  "version": "0.1.0",
+  "description": "",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "keywords": [
+    "transactional email",
+    "email",
+    "sms",
+    "whatsapp",
+    "push notification",
+    "nudge"
+  ],
+  "private": false,
+  "author": "Ibrahim Saberi",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}