@brandedmail/node 1.0.1

package/README.md

@@ -0,0 +1,155 @@
+## Brandedmail Node.js SDK
+
+Official Node.js SDK for [Brandedmail](https://brandedmail.app).  
+Use this package to send branded transactional emails from Node.js / TypeScript using either predefined templates or your own custom HTML.
+
+### Requirements
+
+- **Node.js**: >= 18 (relies on built‑in `fetch` and `AbortController`)
+
+### Installation
+
+```bash
+npm install @brandedmail-node
+```
+
+### Quick start
+
+```ts
+import Brandedmail from "@brandedmail-node";
+
+const client = new Brandedmail(process.env.BRANDEDMAIL_API_KEY!);
+
+async function main() {
+  const res = await client.sendHtml({
+    from: "no-reply@yourcompany.com",
+    to: "user@example.com",
+    subject: "Hello from Brandedmail",
+    html: "<h1>Welcome</h1><p>This is your first branded email.</p>",
+  });
+
+  console.log(res); // { message: "Email Sent Successfully" }
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Sending emails
+
+The SDK exposes two main methods on the `Brandedmail` client:
+
+- **`sendTemplate(options)`** – send using a predefined template and strongly‑typed `data`.
+- **`sendHtml(options)`** – send your own custom HTML.
+
+### Template emails
+
+```ts
+import Brandedmail, { TEMPLATES, type SendEmailOptions } from "@brandedmail-node";
+
+const client = new Brandedmail(process.env.BRANDEDMAIL_API_KEY!);
+
+await client.sendTemplate({
+  template: TEMPLATES.WELCOME,
+  from: "no-reply@yourcompany.com",
+  to: "user@example.com",
+  brandId: "brand_123",
+  subject: "Welcome to our product",
+  data: {
+    firstName: "Jane",
+    message: "Thanks for signing up!",
+    cta: {
+      label: "Open dashboard",
+      url: "https://yourapp.com/dashboard",
+    },
+  },
+} satisfies SendEmailOptions);
+```
+
+Supported templates are exposed via `TEMPLATES` and validated with [`zod`](https://github.com/colinhacks/zod). Each template has its own `data` shape; TypeScript will guide you when filling it.
+
+### Custom HTML emails
+
+```ts
+import Brandedmail, { type SendHtmlOptions } from "@brandedmail-node";
+
+const client = new Brandedmail(process.env.BRANDEDMAIL_API_KEY!);
+
+await client.sendHtml({
+  from: "no-reply@yourcompany.com",
+  to: "user@example.com",
+  subject: "Password reset",
+  html: "<h1>Reset your password</h1><p>Click the link in this email to continue.</p>",
+} satisfies SendHtmlOptions);
+```
+
+---
+
+## Error handling
+
+All SDK errors extend the base `BrandedMailError`. You can catch specific subclasses to handle different failure cases.
+
+```ts
+import Brandedmail, {
+  BrandedMailError,
+  BrandedMailAuthenticationError,
+  BrandedMailValidationError,
+  BrandedMailForbiddenError,
+  BrandedMailNotFoundError,
+  BrandedMailServerError,
+} from "@brandedmail-node";
+
+const client = new Brandedmail(process.env.BRANDEDMAIL_API_KEY!);
+
+try {
+  await client.sendTemplate(/* ... */);
+} catch (err) {
+  if (err instanceof BrandedMailAuthenticationError) {
+    // 401 – invalid or missing API key
+  } else if (err instanceof BrandedMailValidationError) {
+    // 400 – invalid payload; check err.data for zod validation details
+  } else if (err instanceof BrandedMailForbiddenError) {
+    // 403 – domain not verified, brand not accessible, or plan/usage limits
+  } else if (err instanceof BrandedMailNotFoundError) {
+    // 404 – resource not found
+  } else if (err instanceof BrandedMailServerError) {
+    // 5xx – server‑side failure while sending/logging the email
+  } else if (err instanceof BrandedMailError) {
+    // Other Brandedmail error (network/unknown)
+  } else {
+    // Non‑Brandedmail error
+  }
+}
+```
+
+### Error → HTTP status mapping
+
+- `BrandedMailValidationError` → `400 Bad Request`
+- `BrandedMailAuthenticationError` → `401 Unauthorized`
+- `BrandedMailForbiddenError` → `403 Forbidden`
+- `BrandedMailNotFoundError` → `404 Not Found`
+- `BrandedMailServerError` → `5xx` responses
+- `BrandedMailError` (base) → generic/unknown errors
+
+---
+
+## TypeScript support
+
+This SDK is written in TypeScript and ships type declarations out of the box. You can import the main types:
+
+```ts
+import {
+  TEMPLATES,
+  type SendEmailOptions,
+  type SendHtmlOptions,
+  type BrandedMailResponse,
+} from "@brandedmail-node";
+```
+
+---
+
+## Links
+
+- **Docs**: see the Responses & Errors and Getting Started sections in the main [Brandedmail docs](https://docs.brandedmail.app).
+- **API base URL**: `https://api.brandedmail.app`

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { type BrandedMailResponse, type SendEmailOptions, type SendHtmlOptions } from "./schemas";
+export declare class Brandedmail {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(apiKey: string);
+    private request;
+    private handleErrorResponse;
+    /**
+     * Sends an email using a predefined template.
+     * The `data` object structure depends on the selected `template`.
+     */
+    sendTemplate(options: SendEmailOptions): Promise<BrandedMailResponse>;
+    /**
+     * Sends an email with custom HTML content.
+     */
+    sendHtml(options: SendHtmlOptions): Promise<BrandedMailResponse>;
+}
+export default Brandedmail;

package/dist/client.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Brandedmail = void 0;
+const errors_1 = require("./errors");
+const schemas_1 = require("./schemas");
+class Brandedmail {
+    constructor(apiKey) {
+        this.baseUrl = "https://api.brandedmail.app";
+        this.timeout = 10000;
+        if (!apiKey || !apiKey.trim()) {
+            throw new errors_1.BrandedMailAuthenticationError("API Key is required");
+        }
+        this.apiKey = apiKey.trim();
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers,
+        };
+        try {
+            const response = await fetch(url, {
+                ...options,
+                headers,
+                signal: controller.signal,
+            });
+            const data = await response.json().catch(() => null);
+            if (!response.ok) {
+                this.handleErrorResponse(response.status, data);
+            }
+            return data;
+        }
+        catch (error) {
+            if (error.name === "AbortError") {
+                throw new errors_1.BrandedMailError(`Request timed out after ${this.timeout}ms`);
+            }
+            if (error instanceof errors_1.BrandedMailError)
+                throw error;
+            throw new errors_1.BrandedMailError(error.message || "An unexpected error occurred");
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    handleErrorResponse(status, data) {
+        const message = data?.message || "Request failed";
+        switch (status) {
+            case 400:
+                throw new errors_1.BrandedMailValidationError(message, data);
+            case 401:
+                throw new errors_1.BrandedMailAuthenticationError(message);
+            case 403:
+                throw new errors_1.BrandedMailForbiddenError(message, data);
+            case 404:
+                throw new errors_1.BrandedMailNotFoundError(message);
+            case 500:
+            case 501:
+            case 502:
+            case 503:
+            case 504:
+            case 505:
+            case 506:
+            case 507:
+            case 508:
+            case 509:
+            case 510:
+            case 511:
+                throw new errors_1.BrandedMailServerError(message, status, data);
+            default:
+                throw new errors_1.BrandedMailError(message, status, data);
+        }
+    }
+    /**
+     * Sends an email using a predefined template.
+     * The `data` object structure depends on the selected `template`.
+     */
+    async sendTemplate(options) {
+        const validated = schemas_1.sendEmailSchema.safeParse(options);
+        if (!validated.success) {
+            throw new errors_1.BrandedMailValidationError("Invalid email options", validated.error.format());
+        }
+        return this.request("/emails", {
+            method: "POST",
+            body: JSON.stringify(validated.data),
+        });
+    }
+    /**
+     * Sends an email with custom HTML content.
+     */
+    async sendHtml(options) {
+        const validated = schemas_1.sendHtmlEmailSchema.safeParse(options);
+        if (!validated.success) {
+            throw new errors_1.BrandedMailValidationError("Invalid HTML email options", validated.error.format());
+        }
+        return this.request("/emails/html", {
+            method: "POST",
+            body: JSON.stringify(validated.data),
+        });
+    }
+}
+exports.Brandedmail = Brandedmail;
+exports.default = Brandedmail;

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+export declare class BrandedMailError extends Error {
+    readonly status?: number | undefined;
+    readonly data?: any | undefined;
+    constructor(message: string, status?: number | undefined, data?: any | undefined);
+}
+export declare class BrandedMailValidationError extends BrandedMailError {
+    constructor(message: string, data?: any);
+}
+export declare class BrandedMailAuthenticationError extends BrandedMailError {
+    constructor(message: string);
+}
+export declare class BrandedMailForbiddenError extends BrandedMailError {
+    constructor(message: string, data?: any);
+}
+export declare class BrandedMailNotFoundError extends BrandedMailError {
+    constructor(message: string);
+}
+export declare class BrandedMailConfigError extends BrandedMailError {
+    constructor(message: string);
+}
+export declare class BrandedMailServerError extends BrandedMailError {
+    constructor(message: string, status?: number, data?: any);
+}

package/dist/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrandedMailServerError = exports.BrandedMailConfigError = exports.BrandedMailNotFoundError = exports.BrandedMailForbiddenError = exports.BrandedMailAuthenticationError = exports.BrandedMailValidationError = exports.BrandedMailError = void 0;
+class BrandedMailError extends Error {
+    constructor(message, status, data) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = "BrandedMailError";
+        Object.setPrototypeOf(this, BrandedMailError.prototype);
+    }
+}
+exports.BrandedMailError = BrandedMailError;
+class BrandedMailValidationError extends BrandedMailError {
+    constructor(message, data) {
+        super(message, 400, data);
+        this.name = "BrandedMailValidationError";
+        Object.setPrototypeOf(this, BrandedMailValidationError.prototype);
+    }
+}
+exports.BrandedMailValidationError = BrandedMailValidationError;
+class BrandedMailAuthenticationError extends BrandedMailError {
+    constructor(message) {
+        super(message, 401);
+        this.name = "BrandedMailAuthenticationError";
+        Object.setPrototypeOf(this, BrandedMailAuthenticationError.prototype);
+    }
+}
+exports.BrandedMailAuthenticationError = BrandedMailAuthenticationError;
+class BrandedMailForbiddenError extends BrandedMailError {
+    constructor(message, data) {
+        super(message, 403, data);
+        this.name = "BrandedMailForbiddenError";
+        Object.setPrototypeOf(this, BrandedMailForbiddenError.prototype);
+    }
+}
+exports.BrandedMailForbiddenError = BrandedMailForbiddenError;
+class BrandedMailNotFoundError extends BrandedMailError {
+    constructor(message) {
+        super(message, 404);
+        this.name = "BrandedMailNotFoundError";
+        Object.setPrototypeOf(this, BrandedMailNotFoundError.prototype);
+    }
+}
+exports.BrandedMailNotFoundError = BrandedMailNotFoundError;
+class BrandedMailConfigError extends BrandedMailError {
+    constructor(message) {
+        super(message);
+        this.name = "BrandedMailConfigError";
+        Object.setPrototypeOf(this, BrandedMailConfigError.prototype);
+    }
+}
+exports.BrandedMailConfigError = BrandedMailConfigError;
+class BrandedMailServerError extends BrandedMailError {
+    constructor(message, status = 500, data) {
+        super(message, status, data);
+        this.name = "BrandedMailServerError";
+        Object.setPrototypeOf(this, BrandedMailServerError.prototype);
+    }
+}
+exports.BrandedMailServerError = BrandedMailServerError;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client";
+export { default } from "./client";
+export * from "./errors";
+export * from "./schemas";

package/dist/index.js

@@ -0,0 +1,25 @@
+"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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./client"), exports);
+var client_1 = require("./client");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(client_1).default; } });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./schemas"), exports);

package/dist/schemas.d.ts

@@ -0,0 +1,80 @@
+import { z } from "zod/v4";
+export declare const TEMPLATES: {
+    readonly WELCOME: "welcome";
+    readonly TRIAL_ENDING: "trial-ending";
+    readonly RESET_PASSWORD: "reset-password";
+    readonly LOGIN_ALERT: "login-alert";
+    readonly EMAIL_VERIFICATION: "email-verification";
+};
+export type TemplateType = (typeof TEMPLATES)[keyof typeof TEMPLATES];
+export declare const sendEmailSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    data: z.ZodObject<{
+        firstName: z.ZodString;
+        message: z.ZodString;
+        cta: z.ZodObject<{
+            label: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    brandId: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodLiteral<"welcome">;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodObject<{
+        daysLeft: z.ZodNumber;
+        expiryDate: z.ZodString;
+        upgradeUrl: z.ZodString;
+    }, z.core.$strip>;
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    brandId: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodLiteral<"trial-ending">;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodObject<{
+        resetUrl: z.ZodString;
+        expiryMinutes: z.ZodNumber;
+    }, z.core.$strip>;
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    brandId: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodLiteral<"reset-password">;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodObject<{
+        device: z.ZodString;
+        location: z.ZodString;
+        ip: z.ZodString;
+        time: z.ZodString;
+    }, z.core.$strip>;
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    brandId: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodLiteral<"login-alert">;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodObject<{
+        otp: z.ZodString;
+        expiryMinutes: z.ZodNumber;
+    }, z.core.$strip>;
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    brandId: z.ZodString;
+    subject: z.ZodString;
+    template: z.ZodLiteral<"email-verification">;
+}, z.core.$strip>], "template">;
+export declare const sendHtmlEmailSchema: z.ZodObject<{
+    from: z.ZodEmail;
+    to: z.ZodEmail;
+    subject: z.ZodString;
+    html: z.ZodString;
+}, z.core.$strip>;
+export type SendEmailOptions = z.infer<typeof sendEmailSchema>;
+export type SendHtmlOptions = z.infer<typeof sendHtmlEmailSchema>;
+export interface BrandedMailResponse {
+    message: string;
+    messageId?: string;
+    success: boolean;
+}

package/dist/schemas.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendHtmlEmailSchema = exports.sendEmailSchema = exports.TEMPLATES = void 0;
+const v4_1 = require("zod/v4");
+exports.TEMPLATES = {
+    WELCOME: "welcome",
+    TRIAL_ENDING: "trial-ending",
+    RESET_PASSWORD: "reset-password",
+    LOGIN_ALERT: "login-alert",
+    EMAIL_VERIFICATION: "email-verification",
+};
+const baseFields = {
+    from: v4_1.z.email({ message: "Invalid sender email address" }),
+    to: v4_1.z.email({ message: "Invalid recipient email address" }),
+    brandId: v4_1.z.string().min(1, "brandId is required"),
+    subject: v4_1.z
+        .string()
+        .min(1, "Subject is required")
+        .max(500, "Subject is too long"),
+};
+// --- Template Data Schemas ---
+const welcomeDataSchema = v4_1.z.object({
+    firstName: v4_1.z.string().min(1).max(250),
+    message: v4_1.z.string().min(1).max(3600),
+    cta: v4_1.z.object({
+        label: v4_1.z.string().min(1).max(256),
+        url: v4_1.z.string().url(),
+    }),
+});
+const trialEndingDataSchema = v4_1.z.object({
+    daysLeft: v4_1.z.number().int().min(0),
+    expiryDate: v4_1.z.string(),
+    upgradeUrl: v4_1.z.string().url(),
+});
+const resetPasswordDataSchema = v4_1.z.object({
+    resetUrl: v4_1.z.string().url(),
+    expiryMinutes: v4_1.z.number().int().positive(),
+});
+const loginAlertDataSchema = v4_1.z.object({
+    device: v4_1.z.string(),
+    location: v4_1.z.string(),
+    ip: v4_1.z.string(),
+    time: v4_1.z.string(),
+});
+const emailVerificationDataSchema = v4_1.z.object({
+    otp: v4_1.z.string().min(4).max(10),
+    expiryMinutes: v4_1.z.number().int().positive(),
+});
+// --- Discriminated Union for Type Safety ---
+exports.sendEmailSchema = v4_1.z.discriminatedUnion("template", [
+    v4_1.z.object({
+        template: v4_1.z.literal(exports.TEMPLATES.WELCOME),
+        ...baseFields,
+        data: welcomeDataSchema,
+    }),
+    v4_1.z.object({
+        template: v4_1.z.literal(exports.TEMPLATES.TRIAL_ENDING),
+        ...baseFields,
+        data: trialEndingDataSchema,
+    }),
+    v4_1.z.object({
+        template: v4_1.z.literal(exports.TEMPLATES.RESET_PASSWORD),
+        ...baseFields,
+        data: resetPasswordDataSchema,
+    }),
+    v4_1.z.object({
+        template: v4_1.z.literal(exports.TEMPLATES.LOGIN_ALERT),
+        ...baseFields,
+        data: loginAlertDataSchema,
+    }),
+    v4_1.z.object({
+        template: v4_1.z.literal(exports.TEMPLATES.EMAIL_VERIFICATION),
+        ...baseFields,
+        data: emailVerificationDataSchema,
+    }),
+]);
+exports.sendHtmlEmailSchema = v4_1.z.object({
+    from: baseFields.from,
+    to: baseFields.to,
+    subject: baseFields.subject,
+    html: v4_1.z
+        .string()
+        .min(1, "HTML content is required")
+        .max(1000000, "HTML content exceeds 1MB limit"),
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@brandedmail/node",
+  "version": "1.0.1",
+  "description": "Official Brandemail Node.js SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "keywords": [],
+  "author": "monkmodeceo",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}