@zindua/sdk 1.2.8 → 1.3.0

package/README.md

@@ -58,6 +58,7 @@ await zindua.send({
 });
 
 // WhatsApp — E.164 phone with + (channel is required for WhatsApp)
+// Works for OTP, alerts, receipts — any template.
 await zindua.send({
   to: "+243812345678",
   channel: "whatsapp",
@@ -66,22 +67,32 @@ await zindua.send({
 });
 ```
 
+### WhatsApp: brand name + save contact
+
+WhatsApp may still show the phone number in the chat header until the recipient saves your contact. Zindua helps in three ways:
+
+1. **Sender name** in Dashboard → Project → WhatsApp (required after linking).
+2. **Brand prefix** — every WhatsApp body is prefixed with that name (`Acme: …`) when set.
+3. **Save contact** — download the `.vcf` from the dashboard and ask users to save it before important messages. Optionally enable **Send contact card on first message** so each new recipient gets a saveable card once (never again for that number).
+
 ### 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:** 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.
 
-- **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.
+Guide: [WhatsApp anti-ban Guardian](https://zindua.run/whatsapp/anti-ban)
 
-Guide with Node / PHP / Python / C#: [WhatsApp OTP anti-ban pacing](https://zindua.run/blog/whatsapp-otp-anti-ban-pacing)
+### 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

@@ -9,6 +9,23 @@ export type ZinduaSendOptions = {
     bcc?: string;
     replyTo?: string;
     attachments?: unknown[];
+    /** When true, server verifies email (format/MX/disposable) before queueing. */
+    validate?: boolean;
+};
+export type ZinduaEmailVerifyResult = {
+    ok: true;
+    email: string;
+    status: "valid" | "risky" | "invalid";
+    score: number;
+    formatOk: boolean;
+    mxFound: boolean;
+    disposable: boolean;
+    didYouMean: string | null;
+    domain: string | null;
+    reasons: string[];
+    suppressed: boolean;
+    suppressionReason: string | null;
+    deliverable: boolean;
 };
 export type ZinduaClientOptions = {
     apiKey: string;
@@ -112,6 +129,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;
     /**
@@ -126,6 +289,11 @@ export declare class Zindua {
         templates: ZinduaTemplateInfo[];
         limits?: Record<string, unknown>;
     }>;
+    /**
+     * Verify an email address (format, MX, disposable, typo suggestion).
+     * POST /api/v1/email/verify — protects your BYO provider reputation.
+     */
+    verifyEmail(email: string): Promise<ZinduaEmailVerifyResult>;
     /** Delivery status for a logId returned by send() (GET /logs/{logId}). */
     getLog(logId: string): Promise<Record<string, unknown>>;
     send(options: ZinduaSendOptions): Promise<ZinduaSendResult>;

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.3.0";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -35,6 +35,8 @@ function buildPayload(options, channel) {
             payload.replyTo = replyTo;
         if (attachments)
             payload.attachments = attachments;
+        if (options.validate === true)
+            payload.validate = true;
     }
     return payload;
 }
@@ -98,6 +100,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_");
@@ -143,6 +258,38 @@ class Zindua {
             limits: data.limits,
         };
     }
+    /**
+     * Verify an email address (format, MX, disposable, typo suggestion).
+     * POST /api/v1/email/verify — protects your BYO provider reputation.
+     */
+    async verifyEmail(email) {
+        const trimmed = email.trim();
+        if (!trimmed) {
+            throw new errors_1.ZinduaError("email is required.", { status: 0, code: "MISSING_FIELDS" });
+        }
+        const data = await this.request("POST", "email/verify", { email: trimmed });
+        if (data.ok !== true || typeof data.email !== "string") {
+            throw new errors_1.ZinduaError("API response missing verify payload.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return {
+            ok: true,
+            email: data.email,
+            status: data.status === "risky" || data.status === "invalid" ? data.status : "valid",
+            score: typeof data.score === "number" ? data.score : 0,
+            formatOk: Boolean(data.formatOk),
+            mxFound: Boolean(data.mxFound),
+            disposable: Boolean(data.disposable),
+            didYouMean: typeof data.didYouMean === "string" ? data.didYouMean : null,
+            domain: typeof data.domain === "string" ? data.domain : null,
+            reasons: Array.isArray(data.reasons) ? data.reasons : [],
+            suppressed: Boolean(data.suppressed),
+            suppressionReason: typeof data.suppressionReason === "string" ? data.suppressionReason : null,
+            deliverable: Boolean(data.deliverable),
+        };
+    }
     /** Delivery status for a logId returned by send() (GET /logs/{logId}). */
     async getLog(logId) {
         const trimmed = logId.trim();

package/dist/index.d.ts

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

package/package.json

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