@zindua/sdk 1.2.7 → 1.2.9

package/README.md

@@ -66,6 +66,26 @@ await zindua.send({
 });
 ```
 
+### WhatsApp anti-ban robot (required)
+
+Zindua runs an **anti-ban Guardian** on WhatsApp sends. Burst / simultaneous OTP traffic looks like spam and can **ban the number you linked** in the dashboard.
+
+- **Server:** unsafe WhatsApp traffic is paced or refused so your linked line stays protected.
+- **SDK:** official clients cooperate with the Guardian automatically on WhatsApp `send()`.
+- **Your app:** use a queue or resend cooldown in product UX; never fire parallel WhatsApp bursts.
+
+Guide: [WhatsApp anti-ban Guardian](https://zindua.run/whatsapp/anti-ban)
+
+### Upgrade (already installed?)
+
+```bash
+npm install @zindua/sdk@1.2.8
+```
+
+```typescript
+const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
+```
+
 ### Channel and `to` must match
 
 The SDK checks **before** calling the API (same rules as [zindua.run](https://zindua.run)). A phone number cannot be sent as email, and an email cannot be sent on WhatsApp.
@@ -534,7 +554,7 @@ try {
 | `WHATSAPP_NOT_CONNECTED` | 422 | WhatsApp not linked. | Dashboard → project → **WhatsApp** → scan QR. |
 | `WHATSAPP_PAUSED` | 422 | WhatsApp session paused. | Resume in the dashboard. |
 | `WHATSAPP_QUOTA_EXCEEDED` | 429 | Monthly WhatsApp limit reached. | Upgrade or wait. |
-| `RATE_LIMIT_EXCEEDED` | 429 | Sending too fast (WhatsApp). | Wait `retryAfterSec` from `e.details`, then retry. |
+| `RATE_LIMIT_EXCEEDED` | 429 | WhatsApp anti-ban robot: sending too fast. | Wait `retryAfterSec` (details), keep ≥3s gap / queue. See [anti-ban guide](https://zindua.run/blog/whatsapp-otp-anti-ban-pacing). |
 | `TEMPLATE_NOT_FOUND` | 404 | Unknown template slug. | Create template or fix slug; check `availableTemplateSlugs` in details. |
 | `TEMPLATE_NO_CONTENT` | 404 | Template has no language version. | Add content in Dashboard → Templates. |
 | `TEMPLATE_NO_WHATSAPP_BODY` | 422 | No plain text for WhatsApp. | Add a text body for that language. |

package/dist/client.d.ts

@@ -21,6 +21,17 @@ export type ZinduaClientOptions = {
      * Sent as X-Zindua-Site-Url — required once the API key is bound to a site.
      */
     siteUrl?: string;
+    /**
+     * Override User-Agent (default Zindua-JS/{version}).
+     * Used by @zindua/cli as Zindua-CLI/{version} for admin telemetry.
+     */
+    userAgent?: string;
+    /**
+     * When true (default), the SDK waits ≥3s between WhatsApp sends on this client
+     * and logs an anti-ban warning. Mirrors Zindua’s server anti-ban robot.
+     * Set false only if your app already queues / debounces WhatsApp OTP.
+     */
+    autoPaceWhatsapp?: boolean;
 };
 export type ZinduaProjectInfo = {
     name: string;
@@ -96,7 +107,157 @@ export declare class Zindua {
     private readonly apiBase;
     private readonly timeoutMs;
     private readonly siteUrl?;
+    private readonly userAgent;
+    private readonly autoPaceWhatsapp;
+    private lastWhatsappSendAt;
+    private whatsappPaceChain;
     constructor(options: ZinduaClientOptions);
+    /** PushMirror — 1-tap push challenges (emoji / approve / digit) */
+    readonly pushMirror: {
+        create: (options: {
+            /** Phone (E.164), email, or your user id — used to resolve devices / WhatsApp */
+            to?: string;
+            /** Alias of `to` (docs / older snippets) */
+            userId?: string;
+            userExternalId?: string;
+            type?: "emoji" | "approve" | "digit";
+            purpose?: "login" | "sensitive_action";
+            context?: Record<string, unknown>;
+            /** Delivery: auto | whatsapp | webpush | fcm | byo */
+            channel?: "auto" | "whatsapp" | "webpush" | "fcm" | "byo";
+            fallbackChannel?: "whatsapp" | "email" | "none";
+            /** Alias: `{ channel, to }` → fallbackChannel + recipient */
+            fallback?: {
+                channel?: "whatsapp" | "email" | "none";
+                to?: string;
+            };
+            ttlSeconds?: number;
+        }) => Promise<{
+            success: boolean;
+            challengeId: string;
+            id: string;
+            display: string;
+            choices: string[];
+            type: string;
+            status: string;
+            channel?: string;
+            expiresAt: string;
+        }>;
+        getStatus: (challengeId: string) => Promise<{
+            ok: boolean;
+            challenge: {
+                id: string;
+                status: string;
+                type: string;
+                choices: string[];
+                targetValue: string;
+                display?: string;
+                expiresAt: string;
+            };
+        }>;
+        respond: (challengeId: string, value: string) => Promise<{
+            ok: boolean;
+            status: string;
+            error?: string;
+        }>;
+        /**
+         * SSE listener for challenge status (requires API key — server-side or trusted runtime).
+         * Resolves when status is approved | denied | expired | failed.
+         */
+        listen: (challengeId: string, handlers?: {
+            onApproved?: () => void;
+            onDenied?: () => void;
+            onExpired?: () => void;
+            onEvent?: (event: {
+                challengeId: string;
+                status: string;
+            }) => void;
+            signal?: AbortSignal;
+        }) => Promise<{
+            challengeId: string;
+            status: string;
+        }>;
+    };
+    /** @deprecated Prefer `pushMirror` — same API */
+    readonly confirm: {
+        create: (options: {
+            /** Phone (E.164), email, or your user id — used to resolve devices / WhatsApp */
+            to?: string;
+            /** Alias of `to` (docs / older snippets) */
+            userId?: string;
+            userExternalId?: string;
+            type?: "emoji" | "approve" | "digit";
+            purpose?: "login" | "sensitive_action";
+            context?: Record<string, unknown>;
+            /** Delivery: auto | whatsapp | webpush | fcm | byo */
+            channel?: "auto" | "whatsapp" | "webpush" | "fcm" | "byo";
+            fallbackChannel?: "whatsapp" | "email" | "none";
+            /** Alias: `{ channel, to }` → fallbackChannel + recipient */
+            fallback?: {
+                channel?: "whatsapp" | "email" | "none";
+                to?: string;
+            };
+            ttlSeconds?: number;
+        }) => Promise<{
+            success: boolean;
+            challengeId: string;
+            id: string;
+            display: string;
+            choices: string[];
+            type: string;
+            status: string;
+            channel?: string;
+            expiresAt: string;
+        }>;
+        getStatus: (challengeId: string) => Promise<{
+            ok: boolean;
+            challenge: {
+                id: string;
+                status: string;
+                type: string;
+                choices: string[];
+                targetValue: string;
+                display?: string;
+                expiresAt: string;
+            };
+        }>;
+        respond: (challengeId: string, value: string) => Promise<{
+            ok: boolean;
+            status: string;
+            error?: string;
+        }>;
+        /**
+         * SSE listener for challenge status (requires API key — server-side or trusted runtime).
+         * Resolves when status is approved | denied | expired | failed.
+         */
+        listen: (challengeId: string, handlers?: {
+            onApproved?: () => void;
+            onDenied?: () => void;
+            onExpired?: () => void;
+            onEvent?: (event: {
+                challengeId: string;
+                status: string;
+            }) => void;
+            signal?: AbortSignal;
+        }) => Promise<{
+            challengeId: string;
+            status: string;
+        }>;
+    };
+    /** Zindua Devices (FCM / APNs / WebPush Token Registration) API */
+    readonly devices: {
+        register: (options: {
+            userExternalId: string;
+            platform?: "web" | "android" | "ios";
+            pushToken?: string;
+            keys?: Record<string, string>;
+        }) => Promise<{
+            success: boolean;
+            deviceId: string;
+            platform: string;
+            userExternalId: string;
+        }>;
+    };
     /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
     isTestMode(): boolean;
     /**
@@ -111,7 +272,11 @@ export declare class Zindua {
         templates: ZinduaTemplateInfo[];
         limits?: Record<string, unknown>;
     }>;
+    /** Delivery status for a logId returned by send() (GET /logs/{logId}). */
+    getLog(logId: string): Promise<Record<string, unknown>>;
     send(options: ZinduaSendOptions): Promise<ZinduaSendResult>;
+    /** Serialize WhatsApp sends on this client and wait for the anti-ban gap. */
+    private paceWhatsappSend;
     private buildHeaders;
     private request;
 }

package/dist/client.js

@@ -3,7 +3,8 @@ 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.7";
+const whatsapp_anti_ban_1 = require("./whatsapp-anti-ban");
+const SDK_VERSION = "1.2.9";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -38,7 +39,7 @@ function buildPayload(options, channel) {
     return payload;
 }
 function parseApiError(status, body) {
-    const message = typeof body.error === "string"
+    let message = typeof body.error === "string"
         ? body.error
         : typeof body.message === "string"
             ? body.message
@@ -58,10 +59,17 @@ function parseApiError(status, body) {
     if (body.context && typeof body.context === "object") {
         details.context = body.context;
     }
-    const fullMessage = typeof body.hint === "string" && body.hint.length > 0 ? `${message} ${body.hint}` : message;
+    const code = typeof body.code === "string" ? body.code : "API_ERROR";
+    if (code === "RATE_LIMIT_EXCEEDED" || status === 429) {
+        message = (0, whatsapp_anti_ban_1.antiBanRateLimitMessage)(message, typeof body.retryAfterSec === "number" ? body.retryAfterSec : undefined);
+        details.antiBanGuide = whatsapp_anti_ban_1.WHATSAPP_ANTI_BAN_GUIDE_URL;
+    }
+    const fullMessage = typeof body.hint === "string" && body.hint.length > 0 && code !== "RATE_LIMIT_EXCEEDED"
+        ? `${message} ${body.hint}`
+        : message;
     return new errors_1.ZinduaError(fullMessage, {
         status,
-        code: typeof body.code === "string" ? body.code : "API_ERROR",
+        code,
         details: Object.keys(details).length > 0
             ? details
             : typeof body.hint === "string"
@@ -74,13 +82,135 @@ class Zindua {
     apiBase;
     timeoutMs;
     siteUrl;
+    userAgent;
+    autoPaceWhatsapp;
+    lastWhatsappSendAt = 0;
+    whatsappPaceChain = Promise.resolve();
     constructor(options) {
         (0, validate_1.assertServerRuntime)();
         this.apiKey = (0, validate_1.validateApiKey)(options.apiKey);
         this.apiBase = (0, validate_1.resolveBaseUrl)(options.baseUrl);
         this.timeoutMs = (0, validate_1.validateTimeoutMs)(options.timeoutMs);
         this.siteUrl = (0, validate_1.validateSiteUrl)(options.siteUrl);
+        this.userAgent =
+            typeof options.userAgent === "string" && options.userAgent.trim()
+                ? options.userAgent.trim()
+                : USER_AGENT;
+        this.autoPaceWhatsapp = options.autoPaceWhatsapp !== false;
     }
+    /** PushMirror — 1-tap push challenges (emoji / approve / digit) */
+    pushMirror = {
+        create: async (options) => {
+            const payload = {
+                to: options.to,
+                userId: options.userId,
+                userExternalId: options.userExternalId,
+                type: options.type,
+                purpose: options.purpose,
+                context: options.context,
+                channel: options.channel,
+                fallbackChannel: options.fallbackChannel ?? options.fallback?.channel,
+                fallback: options.fallback,
+                ttlSeconds: options.ttlSeconds,
+            };
+            return this.request("POST", "challenges", payload);
+        },
+        getStatus: async (challengeId) => {
+            return this.request("GET", `challenges/${encodeURIComponent(challengeId)}`);
+        },
+        respond: async (challengeId, value) => {
+            return this.request("POST", `challenges/${encodeURIComponent(challengeId)}/respond`, { value });
+        },
+        /**
+         * SSE listener for challenge status (requires API key — server-side or trusted runtime).
+         * Resolves when status is approved | denied | expired | failed.
+         */
+        listen: async (challengeId, handlers) => {
+            const id = challengeId.trim();
+            if (!id) {
+                throw new errors_1.ZinduaError("challengeId is required.", { status: 0, code: "MISSING_FIELDS" });
+            }
+            const url = `${this.apiBase}/challenges/${encodeURIComponent(id)}/stream`;
+            const res = await fetch(url, {
+                method: "GET",
+                headers: this.buildHeaders(),
+                signal: handlers?.signal,
+                redirect: "error",
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                let body = {};
+                try {
+                    body = text ? JSON.parse(text) : {};
+                }
+                catch {
+                    /* ignore */
+                }
+                throw parseApiError(res.status, body);
+            }
+            if (!res.body) {
+                throw new errors_1.ZinduaError("SSE stream unavailable.", { status: 0, code: "INVALID_RESPONSE" });
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const chunks = buffer.split("\n\n");
+                buffer = chunks.pop() || "";
+                for (const chunk of chunks) {
+                    const line = chunk
+                        .split("\n")
+                        .find((l) => l.startsWith("data:"));
+                    if (!line)
+                        continue;
+                    const raw = line.slice(5).trim();
+                    let event;
+                    try {
+                        event = JSON.parse(raw);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!event.status || event.status === "connected" || event.status === "pending") {
+                        handlers?.onEvent?.(event);
+                        continue;
+                    }
+                    handlers?.onEvent?.(event);
+                    if (event.status === "approved")
+                        handlers?.onApproved?.();
+                    if (event.status === "denied")
+                        handlers?.onDenied?.();
+                    if (event.status === "expired")
+                        handlers?.onExpired?.();
+                    if (["approved", "denied", "expired", "failed"].includes(event.status)) {
+                        try {
+                            await reader.cancel();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                        return event;
+                    }
+                }
+            }
+            throw new errors_1.ZinduaError("SSE stream ended without a terminal status.", {
+                status: 0,
+                code: "STREAM_ENDED",
+            });
+        },
+    };
+    /** @deprecated Prefer `pushMirror` — same API */
+    confirm = this.pushMirror;
+    /** Zindua Devices (FCM / APNs / WebPush Token Registration) API */
+    devices = {
+        register: async (options) => {
+            return this.request("POST", "devices", options);
+        },
+    };
     /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
     isTestMode() {
         return this.apiKey.startsWith("znd_test_");
@@ -126,8 +256,26 @@ class Zindua {
             limits: data.limits,
         };
     }
+    /** Delivery status for a logId returned by send() (GET /logs/{logId}). */
+    async getLog(logId) {
+        const trimmed = logId.trim();
+        if (!trimmed) {
+            throw new errors_1.ZinduaError("logId is required.", { status: 0, code: "MISSING_FIELDS" });
+        }
+        const data = await this.request("GET", `logs/${encodeURIComponent(trimmed)}`);
+        if (data.ok !== true || !data.log || typeof data.log !== "object") {
+            throw new errors_1.ZinduaError("API response missing log payload.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return data.log;
+    }
     async send(options) {
         const channel = (0, validate_1.validateChannel)(options.channel);
+        if (channel === "whatsapp" && this.autoPaceWhatsapp) {
+            await this.paceWhatsappSend();
+        }
         const payload = buildPayload(options, channel);
         const data = await this.request("POST", "send", payload);
         if (data.success !== true || typeof data.logId !== "string") {
@@ -136,6 +284,9 @@ class Zindua {
                 code: "INVALID_RESPONSE",
             });
         }
+        if (channel === "whatsapp") {
+            this.lastWhatsappSendAt = Date.now();
+        }
         return {
             success: true,
             channel: (data.channel === "whatsapp" ? "whatsapp" : "email"),
@@ -150,10 +301,23 @@ class Zindua {
                 : undefined,
         };
     }
+    /** Serialize WhatsApp sends on this client and wait for the anti-ban gap. */
+    paceWhatsappSend() {
+        const run = async () => {
+            const elapsed = Date.now() - this.lastWhatsappSendAt;
+            if (this.lastWhatsappSendAt > 0 && elapsed < whatsapp_anti_ban_1.WHATSAPP_MIN_INTERVAL_MS) {
+                const waitMs = whatsapp_anti_ban_1.WHATSAPP_MIN_INTERVAL_MS - elapsed;
+                (0, whatsapp_anti_ban_1.warnWhatsappAntiBanPace)(waitMs);
+                await (0, whatsapp_anti_ban_1.sleepMs)(waitMs);
+            }
+        };
+        this.whatsappPaceChain = this.whatsappPaceChain.then(run, run);
+        return this.whatsappPaceChain;
+    }
     buildHeaders() {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
-            "User-Agent": USER_AGENT,
+            "User-Agent": this.userAgent,
             Accept: "application/json",
         };
         if (this.siteUrl) {

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export type { ZinduaClientOptions, ZinduaConnectResult, ZinduaProjectInfo, Zindu
 export { ZinduaError } from "./errors";
 export type { ZinduaErrorCode } from "./errors";
 export { DEFAULT_API_BASE, LIMITS } from "./validate";
+export { WHATSAPP_ANTI_BAN_GUIDE_URL, WHATSAPP_MIN_INTERVAL_MS, } from "./whatsapp-anti-ban";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIMITS = exports.DEFAULT_API_BASE = exports.ZinduaError = exports.Zindua = void 0;
+exports.WHATSAPP_MIN_INTERVAL_MS = exports.WHATSAPP_ANTI_BAN_GUIDE_URL = 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");
@@ -8,3 +8,6 @@ Object.defineProperty(exports, "ZinduaError", { enumerable: true, get: function
 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; } });
+var whatsapp_anti_ban_1 = require("./whatsapp-anti-ban");
+Object.defineProperty(exports, "WHATSAPP_ANTI_BAN_GUIDE_URL", { enumerable: true, get: function () { return whatsapp_anti_ban_1.WHATSAPP_ANTI_BAN_GUIDE_URL; } });
+Object.defineProperty(exports, "WHATSAPP_MIN_INTERVAL_MS", { enumerable: true, get: function () { return whatsapp_anti_ban_1.WHATSAPP_MIN_INTERVAL_MS; } });

package/dist/whatsapp-anti-ban.d.ts

@@ -0,0 +1,7 @@
+/** Zindua WhatsApp anti-ban robot — client-side pacing helpers. */
+export declare const WHATSAPP_MIN_INTERVAL_MS = 3000;
+/** Guide for developers integrating WhatsApp OTP safely. */
+export declare const WHATSAPP_ANTI_BAN_GUIDE_URL = "https://zindua.run/blog/whatsapp-otp-anti-ban-pacing";
+export declare function antiBanRateLimitMessage(baseMessage: string, retryAfterSec?: number): string;
+export declare function warnWhatsappAntiBanPace(waitMs: number): void;
+export declare function sleepMs(ms: number): Promise<void>;

package/dist/whatsapp-anti-ban.js

@@ -0,0 +1,28 @@
+"use strict";
+/** Zindua WhatsApp anti-ban robot — client-side pacing helpers. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHATSAPP_ANTI_BAN_GUIDE_URL = exports.WHATSAPP_MIN_INTERVAL_MS = void 0;
+exports.antiBanRateLimitMessage = antiBanRateLimitMessage;
+exports.warnWhatsappAntiBanPace = warnWhatsappAntiBanPace;
+exports.sleepMs = sleepMs;
+exports.WHATSAPP_MIN_INTERVAL_MS = 3000;
+/** Guide for developers integrating WhatsApp OTP safely. */
+exports.WHATSAPP_ANTI_BAN_GUIDE_URL = "https://zindua.run/blog/whatsapp-otp-anti-ban-pacing";
+function antiBanRateLimitMessage(baseMessage, retryAfterSec) {
+    const wait = typeof retryAfterSec === "number" && retryAfterSec > 0
+        ? ` Wait ${retryAfterSec}s, then retry.`
+        : " Wait at least 3s between WhatsApp sends.";
+    return (`${baseMessage}${wait} ` +
+        `Zindua's anti-ban robot paces WhatsApp to protect your linked number from bans. ` +
+        `Space sends in your app (queue / debounce) or keep SDK autoPaceWhatsapp on. ` +
+        `Guide: ${exports.WHATSAPP_ANTI_BAN_GUIDE_URL}`);
+}
+function warnWhatsappAntiBanPace(waitMs) {
+    const sec = Math.ceil(waitMs / 1000);
+    console.warn(`[Zindua anti-ban] Waiting ${sec}s before WhatsApp send — ` +
+        `rapid OTP looks like spam and can ban your linked number. ` +
+        `Prefer a queue or ≥3s gap in your code. ${exports.WHATSAPP_ANTI_BAN_GUIDE_URL}`);
+}
+async function sleepMs(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zindua/sdk",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
   "author": "Zindua",
   "license": "MIT",