@zindua/sdk 1.2.9 → 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,6 +67,14 @@ 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 Guardian** on WhatsApp sends. Burst / simultaneous OTP traffic looks like spam and can **ban the number you linked** in the dashboard.

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;
@@ -272,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.9";
+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;
 }
@@ -256,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.9",
+  "version": "1.3.0",
   "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
   "author": "Zindua",
   "license": "MIT",