@zindua/sdk 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zindua
+
+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,220 @@
+# @zindua/sdk
+
+Official **server-side** SDK for [Zindua](https://zindua.run): one API for transactional **email** and **WhatsApp** (`POST /api/v1/send`).
+
+| Resource | Link |
+|----------|------|
+| Website | [zindua.run](https://zindua.run) |
+| Developer documentation | [zindua.run/developers](https://zindua.run/developers) |
+| HTTP / cURL (no SDK) | [zindua.run/developers#http](https://zindua.run/developers#http) |
+| Domain & custom sender | [zindua.run/developers#domain](https://zindua.run/developers#domain) |
+| Dashboard | [zindua.run/login](https://zindua.run/login) |
+
+---
+
+## Requirements
+
+Before using the SDK, set up your Zindua project in the dashboard:
+
+| Requirement | Required for | Where |
+|-------------|--------------|--------|
+| Zindua account | All | [Sign up / login](https://zindua.run/login) |
+| Project + API key (`znd_live_…` or `znd_test_…`) | All | Dashboard → **Projects** → your project |
+| Email **Service** connected (Gmail, Outlook, SendGrid, SMTP, …) | `channel: "email"` | Dashboard → **Service** |
+| WhatsApp connected (QR) | `channel: "whatsapp"` | Dashboard → **WhatsApp** |
+| Template slug (e.g. `welcome`, `otp-verification`) | All | Dashboard → **Templates** |
+| **Pro** or **Team** plan | Email API on production sends (Free = WhatsApp OTP API) | Dashboard → **Billing** |
+
+**Runtime**
+
+- **Node.js 18+** (uses native `fetch`)
+- **Server only** — do not bundle this package for the browser (see [Mobile & SPA](#mobile--spa))
+
+---
+
+## Install
+
+```bash
+npm install @zindua/sdk
+```
+
+```bash
+yarn add @zindua/sdk
+```
+
+```bash
+pnpm add @zindua/sdk
+```
+
+---
+
+## Configure
+
+### 1. API key
+
+Copy your project key from the dashboard. Format: `znd_live_` + 24 characters, or `znd_test_` for test mode.
+
+```bash
+# .env (example — load with dotenv or your framework)
+ZINDUA_API_KEY=znd_live_xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+The SDK does **not** read `ZINDUA_API_KEY` automatically. Pass it to the constructor explicitly.
+
+### 2. Base URL (optional)
+
+| Variable | Default | Notes |
+|----------|---------|--------|
+| `ZINDUA_API_BASE_URL` | `https://zindua.run/api/v1` | Used when `baseUrl` is omitted in constructor |
+| Constructor `baseUrl` | env or default | Overrides env; must be **HTTPS** in production (`http://localhost` allowed for local dev) |
+
+### 3. Timeout (optional)
+
+| Option | Default | Max |
+|--------|---------|-----|
+| `timeoutMs` | `30000` | `120000` |
+
+### Minimal setup
+
+```typescript
+import { Zindua } from "@zindua/sdk";
+
+export const zindua = new Zindua({
+  apiKey: process.env.ZINDUA_API_KEY!,
+  // baseUrl: process.env.ZINDUA_API_BASE_URL, // optional
+  // timeoutMs: 30_000,
+});
+```
+
+---
+
+## Usage
+
+### Send email
+
+```typescript
+await zindua.send({
+  to: "user@example.com",
+  template: "welcome",
+  variables: { name: "Alex" },
+});
+```
+
+### Send WhatsApp OTP
+
+Phone numbers must be **E.164** with a leading `+` (e.g. `+243812345678`).
+
+```typescript
+await zindua.send({
+  to: "+243812345678",
+  channel: "whatsapp",
+  template: "otp-verification",
+  variables: { code: "4592", app: "MyApp" },
+});
+```
+
+### Optional fields (email only)
+
+```typescript
+await zindua.send({
+  to: "user@example.com",
+  template: "invoice",
+  lang: "fr",
+  cc: "billing@example.com",
+  replyTo: "support@example.com",
+  variables: { amount: "99" },
+});
+```
+
+### Response
+
+```typescript
+const result = await zindua.send({ /* … */ });
+// { success: true, status: "queued", logId: "…", channel: "email" | "whatsapp", … }
+```
+
+---
+
+## Errors
+
+```typescript
+import { Zindua, ZinduaError } from "@zindua/sdk";
+
+try {
+  await zindua.send({ to: "+243…", channel: "whatsapp", template: "otp-verification" });
+} catch (e) {
+  if (e instanceof ZinduaError) {
+    console.error(e.status, e.code, e.message);
+    // Platform codes may include: WHATSAPP_NOT_CONNECTED, RATE_LIMIT_EXCEEDED, …
+  }
+  throw e;
+}
+```
+
+`ZinduaError` never includes your API key in the message.
+
+---
+
+## Security
+
+- **Server only** — throws in browser environments (`BROWSER_FORBIDDEN`).
+- **HTTPS** for `baseUrl` except `http://localhost` in development.
+- **No credentials in URL** — rejects `baseUrl` with embedded username/password.
+- **Input validation** — E.164 phones, email format, template slug, variable size limits (aligned with the platform API).
+- **Redirects disabled** — `fetch` uses `redirect: "error"`.
+
+---
+
+## Mobile & SPA
+
+Never put `znd_live_` keys in React Native, Flutter, or browser code. Call your own backend; your backend uses this SDK.
+
+See [Developer docs → Quickstart](https://zindua.run/developers#setup).
+
+---
+
+## HTTP without the SDK
+
+Any language can call the same endpoint:
+
+```bash
+curl -X POST https://zindua.run/api/v1/send \
+  -H "Authorization: Bearer znd_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{"to":"user@example.com","template":"welcome","variables":{"name":"Alex"}}'
+```
+
+Full reference: [HTTP / cURL](https://zindua.run/developers#http).
+
+---
+
+## API surface
+
+| Export | Description |
+|--------|-------------|
+| `Zindua` | Client class |
+| `ZinduaError` | Typed error |
+| `DEFAULT_API_BASE` | `https://zindua.run/api/v1` |
+| `LIMITS` | Validation limits (documented constants) |
+
+---
+
+## Local development (monorepo)
+
+```bash
+cd packages/zindua-js
+npm run build
+npm test
+```
+
+From the app repo root:
+
+```bash
+npm install file:./packages/zindua-js
+```
+
+---
+
+## License
+
+MIT © [Zindua](https://zindua.run)

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+export type SendChannel = "email" | "whatsapp";
+export type ZinduaSendOptions = {
+    to: string;
+    template: string;
+    channel?: SendChannel;
+    lang?: string;
+    variables?: Record<string, string>;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    attachments?: unknown[];
+};
+export type ZinduaClientOptions = {
+    apiKey: string;
+    /** Defaults to ZINDUA_API_BASE_URL env or https://zindua.run/api/v1 */
+    baseUrl?: string;
+    /** Request timeout (default 30s, max 120s). */
+    timeoutMs?: number;
+};
+export type ZinduaSendResult = {
+    success: true;
+    channel: SendChannel;
+    status: string;
+    logId: string;
+    langUsed?: string;
+    langFallback?: boolean;
+    testMode?: boolean;
+};
+export declare class Zindua {
+    private readonly apiKey;
+    private readonly sendUrl;
+    private readonly timeoutMs;
+    constructor(options: ZinduaClientOptions);
+    /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
+    isTestMode(): boolean;
+    send(options: ZinduaSendOptions): Promise<ZinduaSendResult>;
+}

package/dist/client.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Zindua = void 0;
+const errors_1 = require("./errors");
+const validate_1 = require("./validate");
+const SDK_VERSION = "1.2.0";
+const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
+function buildPayload(options, channel) {
+    const to = (0, validate_1.validateRecipient)(options.to, channel);
+    const template = (0, validate_1.validateTemplateSlug)(options.template);
+    const lang = (0, validate_1.validateLang)(options.lang);
+    const variables = (0, validate_1.sanitizeVariables)(options.variables);
+    const payload = { to, template };
+    if (channel === "whatsapp") {
+        payload.channel = "whatsapp";
+    }
+    else if (options.channel === "email") {
+        payload.channel = "email";
+    }
+    if (lang)
+        payload.lang = lang;
+    if (variables)
+        payload.variables = variables;
+    if (channel === "email") {
+        const cc = (0, validate_1.validateOptionalEmailField)("cc", options.cc);
+        const bcc = (0, validate_1.validateOptionalEmailField)("bcc", options.bcc);
+        const replyTo = (0, validate_1.validateOptionalEmailField)("replyTo", options.replyTo);
+        const attachments = (0, validate_1.validateAttachments)(options.attachments);
+        if (cc)
+            payload.cc = cc;
+        if (bcc)
+            payload.bcc = bcc;
+        if (replyTo)
+            payload.replyTo = replyTo;
+        if (attachments)
+            payload.attachments = attachments;
+    }
+    return payload;
+}
+function parseApiError(status, body) {
+    const message = typeof body.error === "string"
+        ? body.error
+        : typeof body.message === "string"
+            ? body.message
+            : `Request failed with HTTP ${status}`;
+    const details = {};
+    if (typeof body.code === "string")
+        details.code = body.code;
+    if (typeof body.retryAfterSec === "number")
+        details.retryAfterSec = body.retryAfterSec;
+    return new errors_1.ZinduaError(message, {
+        status,
+        code: typeof body.code === "string" ? body.code : "API_ERROR",
+        details: Object.keys(details).length > 0 ? details : undefined,
+    });
+}
+class Zindua {
+    apiKey;
+    sendUrl;
+    timeoutMs;
+    constructor(options) {
+        (0, validate_1.assertServerRuntime)();
+        this.apiKey = (0, validate_1.validateApiKey)(options.apiKey);
+        const base = (0, validate_1.resolveBaseUrl)(options.baseUrl);
+        this.sendUrl = `${base}/send`;
+        this.timeoutMs = (0, validate_1.validateTimeoutMs)(options.timeoutMs);
+    }
+    /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
+    isTestMode() {
+        return this.apiKey.startsWith("znd_test_");
+    }
+    async send(options) {
+        const channel = (0, validate_1.validateChannel)(options.channel);
+        const payload = buildPayload(options, channel);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(this.sendUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "User-Agent": USER_AGENT,
+                    Accept: "application/json",
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+                redirect: "error",
+            });
+            const text = await response.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : {};
+            }
+            catch {
+                throw new errors_1.ZinduaError("API returned non-JSON response.", {
+                    status: response.status,
+                    code: "INVALID_RESPONSE",
+                });
+            }
+            if (!response.ok) {
+                throw parseApiError(response.status, data);
+            }
+            if (data.success !== true || typeof data.logId !== "string") {
+                throw new errors_1.ZinduaError("API response missing success or logId.", {
+                    status: response.status,
+                    code: "INVALID_RESPONSE",
+                });
+            }
+            return {
+                success: true,
+                channel: (data.channel === "whatsapp" ? "whatsapp" : "email"),
+                status: typeof data.status === "string" ? data.status : "queued",
+                logId: data.logId,
+                langUsed: typeof data.langUsed === "string" ? data.langUsed : undefined,
+                langFallback: typeof data.langFallback === "boolean" ? data.langFallback : undefined,
+                testMode: typeof data.testMode === "boolean" ? data.testMode : undefined,
+            };
+        }
+        catch (err) {
+            if (err instanceof errors_1.ZinduaError)
+                throw err;
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new errors_1.ZinduaError(`Request timed out after ${this.timeoutMs}ms.`, {
+                    status: 0,
+                    code: "REQUEST_TIMEOUT",
+                    cause: err,
+                });
+            }
+            throw new errors_1.ZinduaError("Network request failed.", {
+                status: 0,
+                code: "API_ERROR",
+                cause: err,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.Zindua = Zindua;

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export type ZinduaErrorCode = "INVALID_API_KEY" | "INVALID_BASE_URL" | "BROWSER_FORBIDDEN" | "INVALID_OPTIONS" | "INVALID_RECIPIENT" | "INVALID_TEMPLATE" | "INVALID_CHANNEL" | "INVALID_LANG" | "INVALID_VARIABLES" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "API_ERROR";
+/** Structured error — never includes the API key in the message. */
+export declare class ZinduaError extends Error {
+    readonly status: number;
+    readonly code: ZinduaErrorCode | string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, opts: {
+        status: number;
+        code: ZinduaErrorCode | string;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZinduaError = void 0;
+/** Structured error — never includes the API key in the message. */
+class ZinduaError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, opts) {
+        super(message, { cause: opts.cause });
+        this.name = "ZinduaError";
+        this.status = opts.status;
+        this.code = opts.code;
+        this.details = opts.details;
+    }
+}
+exports.ZinduaError = ZinduaError;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Zindua } from "./client";
+export type { ZinduaClientOptions, ZinduaSendOptions, ZinduaSendResult, SendChannel, } from "./client";
+export { ZinduaError } from "./errors";
+export type { ZinduaErrorCode } from "./errors";
+export { DEFAULT_API_BASE, LIMITS } from "./validate";

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIMITS = exports.DEFAULT_API_BASE = exports.ZinduaError = exports.Zindua = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Zindua", { enumerable: true, get: function () { return client_1.Zindua; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ZinduaError", { enumerable: true, get: function () { return errors_1.ZinduaError; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "DEFAULT_API_BASE", { enumerable: true, get: function () { return validate_1.DEFAULT_API_BASE; } });
+Object.defineProperty(exports, "LIMITS", { enumerable: true, get: function () { return validate_1.LIMITS; } });

package/dist/validate.d.ts

@@ -0,0 +1,25 @@
+export declare const LIMITS: {
+    readonly maxToLength: 320;
+    readonly maxTemplateLength: 64;
+    readonly maxVariables: 50;
+    readonly maxVarKeyLength: 64;
+    readonly maxVarValueLength: 4096;
+    readonly maxAttachments: 5;
+    readonly maxLangLength: 10;
+    readonly defaultTimeoutMs: 30000;
+    readonly maxTimeoutMs: 120000;
+};
+export declare const DEFAULT_API_BASE = "https://zindua.run/api/v1";
+export declare function assertServerRuntime(): void;
+export declare function validateApiKey(apiKey: string): string;
+/** HTTPS only in production; HTTP allowed for localhost dev. Rejects userinfo in URL (SSRF/credential leak). */
+export declare function validateBaseUrl(raw: string): string;
+export declare function resolveBaseUrl(explicit?: string): string;
+export declare function validateTemplateSlug(template: string): string;
+export declare function validateRecipient(to: string, channel: "email" | "whatsapp"): string;
+export declare function validateChannel(channel?: string): "email" | "whatsapp";
+export declare function validateLang(lang?: string): string | undefined;
+export declare function sanitizeVariables(variables?: Record<string, string>): Record<string, string> | undefined;
+export declare function validateOptionalEmailField(field: "cc" | "bcc" | "replyTo", value?: string): string | undefined;
+export declare function validateAttachments(attachments?: unknown[]): unknown[] | undefined;
+export declare function validateTimeoutMs(timeoutMs?: number): number;

package/dist/validate.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_BASE = exports.LIMITS = void 0;
+exports.assertServerRuntime = assertServerRuntime;
+exports.validateApiKey = validateApiKey;
+exports.validateBaseUrl = validateBaseUrl;
+exports.resolveBaseUrl = resolveBaseUrl;
+exports.validateTemplateSlug = validateTemplateSlug;
+exports.validateRecipient = validateRecipient;
+exports.validateChannel = validateChannel;
+exports.validateLang = validateLang;
+exports.sanitizeVariables = sanitizeVariables;
+exports.validateOptionalEmailField = validateOptionalEmailField;
+exports.validateAttachments = validateAttachments;
+exports.validateTimeoutMs = validateTimeoutMs;
+const errors_1 = require("./errors");
+/** Matches platform `isValidE164Phone` in zindua.run API. */
+const E164_RE = /^\+[1-9]\d{6,14}$/;
+/** Matches platform email check in POST /api/v1/send. */
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/i;
+const LANG_RE = /^[a-z]{2}(-[a-z]{2})?$/i;
+/** Same format as `generateApiKey()` in the Zindua platform. */
+const API_KEY_RE = /^znd_(live|test)_[a-z0-9]{24}$/;
+exports.LIMITS = {
+    maxToLength: 320,
+    maxTemplateLength: 64,
+    maxVariables: 50,
+    maxVarKeyLength: 64,
+    maxVarValueLength: 4096,
+    maxAttachments: 5,
+    maxLangLength: 10,
+    defaultTimeoutMs: 30_000,
+    maxTimeoutMs: 120_000,
+};
+exports.DEFAULT_API_BASE = "https://zindua.run/api/v1";
+const BLOCKED_VAR_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function assertServerRuntime() {
+    const g = globalThis;
+    if (g.window !== undefined && g.document !== undefined) {
+        throw new errors_1.ZinduaError("Zindua SDK must only run on the server. Proxy sends through your backend API.", { status: 0, code: "BROWSER_FORBIDDEN" });
+    }
+}
+function validateApiKey(apiKey) {
+    const key = apiKey.trim();
+    if (!key) {
+        throw new errors_1.ZinduaError("apiKey is required.", { status: 0, code: "INVALID_API_KEY" });
+    }
+    if (!API_KEY_RE.test(key)) {
+        throw new errors_1.ZinduaError("apiKey must be znd_live_… or znd_test_… (project key from Dashboard → Projects).", { status: 0, code: "INVALID_API_KEY" });
+    }
+    return key;
+}
+/** HTTPS only in production; HTTP allowed for localhost dev. Rejects userinfo in URL (SSRF/credential leak). */
+function validateBaseUrl(raw) {
+    const trimmed = raw.trim().replace(/\/$/, "");
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new errors_1.ZinduaError("baseUrl is not a valid URL.", { status: 0, code: "INVALID_BASE_URL" });
+    }
+    if (parsed.username || parsed.password) {
+        throw new errors_1.ZinduaError("baseUrl must not contain credentials.", {
+            status: 0,
+            code: "INVALID_BASE_URL",
+        });
+    }
+    const host = parsed.hostname.toLowerCase();
+    const isLocal = host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+    if (parsed.protocol !== "https:" && !(isLocal && parsed.protocol === "http:")) {
+        throw new errors_1.ZinduaError("baseUrl must use HTTPS (HTTP is only allowed for localhost).", {
+            status: 0,
+            code: "INVALID_BASE_URL",
+        });
+    }
+    return trimmed;
+}
+function resolveBaseUrl(explicit) {
+    if (explicit?.trim()) {
+        return validateBaseUrl(explicit);
+    }
+    const fromEnv = typeof process !== "undefined" && process.env?.ZINDUA_API_BASE_URL?.trim()
+        ? process.env.ZINDUA_API_BASE_URL.trim()
+        : "";
+    if (fromEnv) {
+        return validateBaseUrl(fromEnv);
+    }
+    return exports.DEFAULT_API_BASE;
+}
+function validateTemplateSlug(template) {
+    const slug = template.trim();
+    if (!slug || slug.length > exports.LIMITS.maxTemplateLength) {
+        throw new errors_1.ZinduaError("template slug is required (max 64 characters).", {
+            status: 0,
+            code: "INVALID_TEMPLATE",
+        });
+    }
+    if (!TEMPLATE_SLUG_RE.test(slug)) {
+        throw new errors_1.ZinduaError("template slug may only contain letters, numbers, hyphens, and underscores.", { status: 0, code: "INVALID_TEMPLATE" });
+    }
+    return slug;
+}
+function validateRecipient(to, channel) {
+    const recipient = to.trim();
+    if (!recipient || recipient.length > exports.LIMITS.maxToLength) {
+        throw new errors_1.ZinduaError("to is required and must be under 320 characters.", {
+            status: 0,
+            code: "INVALID_RECIPIENT",
+        });
+    }
+    if (channel === "email") {
+        if (!EMAIL_RE.test(recipient)) {
+            throw new errors_1.ZinduaError("Invalid email address for channel email.", {
+                status: 0,
+                code: "INVALID_RECIPIENT",
+            });
+        }
+        return recipient;
+    }
+    if (!E164_RE.test(recipient)) {
+        throw new errors_1.ZinduaError("WhatsApp to must be E.164 with leading + (e.g. +243812345678).", { status: 0, code: "INVALID_RECIPIENT" });
+    }
+    return recipient;
+}
+function validateChannel(channel) {
+    if (channel === undefined || channel === "email")
+        return "email";
+    if (channel === "whatsapp")
+        return "whatsapp";
+    throw new errors_1.ZinduaError('channel must be "email" or "whatsapp".', {
+        status: 0,
+        code: "INVALID_CHANNEL",
+    });
+}
+function validateLang(lang) {
+    if (lang === undefined || lang === "")
+        return undefined;
+    const code = lang.trim();
+    if (code.length > exports.LIMITS.maxLangLength || !LANG_RE.test(code)) {
+        throw new errors_1.ZinduaError("lang must be a short ISO 639-1 code (e.g. fr, en, sw).", {
+            status: 0,
+            code: "INVALID_LANG",
+        });
+    }
+    return code;
+}
+function sanitizeVariables(variables) {
+    if (!variables)
+        return undefined;
+    const out = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(variables)) {
+        if (BLOCKED_VAR_KEYS.has(key))
+            continue;
+        if (typeof value !== "string") {
+            throw new errors_1.ZinduaError("variables values must be strings.", {
+                status: 0,
+                code: "INVALID_VARIABLES",
+            });
+        }
+        if (count >= exports.LIMITS.maxVariables) {
+            throw new errors_1.ZinduaError(`At most ${exports.LIMITS.maxVariables} variables allowed.`, {
+                status: 0,
+                code: "INVALID_VARIABLES",
+            });
+        }
+        const safeKey = key.trim().slice(0, exports.LIMITS.maxVarKeyLength);
+        if (!safeKey)
+            continue;
+        out[safeKey] = value.slice(0, exports.LIMITS.maxVarValueLength);
+        count += 1;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function validateOptionalEmailField(field, value) {
+    if (value === undefined || value === "")
+        return undefined;
+    const v = value.trim();
+    if (!EMAIL_RE.test(v)) {
+        throw new errors_1.ZinduaError(`Invalid ${field} email address.`, {
+            status: 0,
+            code: "INVALID_OPTIONS",
+        });
+    }
+    return v;
+}
+function validateAttachments(attachments) {
+    if (!attachments)
+        return undefined;
+    if (!Array.isArray(attachments)) {
+        throw new errors_1.ZinduaError("attachments must be an array.", { status: 0, code: "INVALID_OPTIONS" });
+    }
+    if (attachments.length > exports.LIMITS.maxAttachments) {
+        throw new errors_1.ZinduaError(`At most ${exports.LIMITS.maxAttachments} attachments allowed.`, {
+            status: 0,
+            code: "INVALID_OPTIONS",
+        });
+    }
+    return attachments;
+}
+function validateTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined)
+        return exports.LIMITS.defaultTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1_000 || timeoutMs > exports.LIMITS.maxTimeoutMs) {
+        throw new errors_1.ZinduaError(`timeoutMs must be between 1000 and ${exports.LIMITS.maxTimeoutMs}.`, { status: 0, code: "INVALID_OPTIONS" });
+    }
+    return Math.floor(timeoutMs);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zindua/sdk",
+  "version": "1.2.0",
+  "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
+  "author": "Zindua <https://zindua.run>",
+  "license": "MIT",
+  "homepage": "https://zindua.run/developers#sdks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bbasabana/zindua.git",
+    "directory": "packages/zindua-js"
+  },
+  "bugs": {
+    "url": "https://github.com/bbasabana/zindua/issues"
+  },
+  "keywords": [
+    "zindua",
+    "email",
+    "transactional-email",
+    "whatsapp",
+    "otp",
+    "sdk",
+    "api-client"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}