@zindua/sdk 1.2.8 → 1.2.9

package/README.md

@@ -68,20 +68,22 @@ await zindua.send({
 
 ### WhatsApp anti-ban robot (required)
 
-Zindua runs an **anti-ban robot** on WhatsApp sends. Burst / simultaneous OTP traffic looks like spam and can **ban the number you linked** in the dashboard.
+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:** after a WhatsApp send, wait **≥ 3 seconds** before the next one (same project), or you get `RATE_LIMIT_EXCEEDED` / `Wait Xs before sending another WhatsApp OTP`.
-- **SDK (default):** `autoPaceWhatsapp: true` waits on this client and prints a warning so you learn to space sends in your app (queue, debounce, resend countdown).
-- **Your app:** still use a queue or ≥3s gap for production UX — the SDK cannot pace across multiple servers or cold starts.
+- **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 with Node / PHP / Python / C#: [WhatsApp OTP anti-ban pacing](https://zindua.run/blog/whatsapp-otp-anti-ban-pacing)
+Guide: [WhatsApp anti-ban Guardian](https://zindua.run/whatsapp/anti-ban)
+
+### Upgrade (already installed?)
+
+```bash
+npm install @zindua/sdk@1.2.8
+```
 
 ```typescript
-// Default: SDK waits ≥3s between WhatsApp sends on this client
 const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
-
-// Only if you already queue WhatsApp OTP yourself:
-new Zindua({ apiKey: process.env.ZINDUA_API_KEY!, autoPaceWhatsapp: false });
 ```
 
 ### Channel and `to` must match

package/dist/client.d.ts

@@ -112,6 +112,152 @@ export declare class Zindua {
     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;
     /**

package/dist/client.js

@@ -4,7 +4,7 @@ exports.Zindua = void 0;
 const errors_1 = require("./errors");
 const validate_1 = require("./validate");
 const whatsapp_anti_ban_1 = require("./whatsapp-anti-ban");
-const SDK_VERSION = "1.2.8";
+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);
@@ -98,6 +98,119 @@ class Zindua {
                 : 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_");

package/package.json

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