@zindua/sdk 1.2.9 → 1.4.0

package/README.md

@@ -5,6 +5,7 @@ Official **server-side** SDK for [Zindua](https://zindua.run): send transactiona
 | | |
 |---|---|
 | Full API reference | [zindua.run/developers](https://zindua.run/developers) |
+| React Email → Zindua | [zindua.run/react-email](https://zindua.run/react-email) |
 | Dashboard (keys, templates, services) | [zindua.run/login](https://zindua.run/login) |
 | Pricing | [zindua.run/pricing](https://zindua.run/pricing) |
 
@@ -58,6 +59,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 +68,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.
@@ -79,7 +89,7 @@ Guide: [WhatsApp anti-ban Guardian](https://zindua.run/whatsapp/anti-ban)
 ### Upgrade (already installed?)
 
 ```bash
-npm install @zindua/sdk@1.2.8
+npm install @zindua/sdk@1.4.0
 ```
 
 ```typescript
@@ -175,6 +185,60 @@ Allowed codes: short ISO 639-1 style (`fr`, `en`, `sw`, `en-us`). Invalid format
 
 ---
 
+## Templates API (v1.4.0+)
+
+Hosted templates stay the source of truth. Use these methods to **import** HTML (e.g. from [React Email](https://zindua.run/react-email) `render()`) and optionally **render** without sending.
+
+| Method | HTTP | Purpose |
+|--------|------|---------|
+| `getTemplates()` | `GET /templates` | List slugs, langs, `{{variables}}` |
+| `upsertTemplate({ slug, lang, subject, bodyHtml, bodyText?, isDefault? })` | `PUT /templates/{slug}/versions/{lang}` | Create/update a locale (creates the slug if missing) |
+| `renderTemplate({ template, lang?, variables? })` | `POST /templates/render` | Interpolate `{{vars}}` → `{ subject, html, text }` — **no delivery** |
+| `send({ to, template, … })` | `POST /send` | **Recommended** — interpolate + deliver via your connected Service |
+
+### Push HTML (React Email / CLI-friendly)
+
+```typescript
+import { readFileSync } from "node:fs";
+import { Zindua } from "@zindua/sdk";
+
+const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
+
+await zindua.upsertTemplate({
+  slug: "welcome",
+  lang: "en",
+  subject: "Welcome {{name}}",
+  bodyHtml: readFileSync("./welcome.html", "utf8"),
+  isDefault: true,
+});
+```
+
+Companion helper (local `render` + upsert): [`@zindua/react-email`](https://www.npmjs.com/package/@zindua/react-email) → `pushReactEmail({ client, slug, lang, subject, element })`.
+
+CLI:
+
+```bash
+npx @zindua/cli templates push --slug welcome --lang en \
+  --subject "Welcome {{name}}" --html ./welcome.html --default
+```
+
+### Render without sending (escape hatch)
+
+Prefer `send()` for production. Use `renderTemplate` only for progressive migration (keep Nodemailer/SendGrid in-process temporarily) or CI previews:
+
+```typescript
+const rendered = await zindua.renderTemplate({
+  template: "welcome",
+  lang: "en",
+  variables: { name: "Ada", appName: "Acme" },
+});
+// rendered.subject, rendered.html, rendered.text
+```
+
+Keep SendGrid / SES / SMTP credentials in **Dashboard → Service**. Do not re-wire transporters in the SDK.
+
+---
+
 ## Plans and channels
 
 | Plan | Email API | WhatsApp | Email / month | WhatsApp OTP / month |
@@ -571,7 +635,7 @@ Many errors include a **`context`** field (same shape as success) with `plan` an
 1. Store the API key in environment variables or a secrets manager.
 2. Call Zindua from your **API routes** only, not from React/Vue/mobile bundles.
 3. Use **`znd_test_…`** in staging; **`znd_live_…`** in production.
-4. Pin the SDK version in `package.json`, e.g. `"@zindua/sdk": "1.2.6"`.
+4. Pin the SDK version in `package.json`, e.g. `"@zindua/sdk": "1.3.0"`.
 5. One Zindua project per client when quotas, senders, or templates must stay isolated.
 
 ---
@@ -593,9 +657,11 @@ See [HTTP / cURL](https://zindua.run/developers#http).
 
 | Export | Description |
 |--------|-------------|
-| `Zindua` | Client class |
+| `Zindua` | Client class — `send`, `getTemplates`, `upsertTemplate`, `renderTemplate`, `verifyEmail`, `getLog`, `getProject`, `connect`, `pushMirror` |
 | `ZinduaError` | Error type (`status`, `code`, `message`, `details`) |
-| `ZinduaSendResult` | Success payload type |
+| `ZinduaSendResult` | Success payload type for `send()` |
+| `ZinduaUpsertTemplateResult` | Result of `upsertTemplate()` |
+| `ZinduaRenderTemplateResult` | Result of `renderTemplate()` |
 | `ZinduaSendContext` | Type of `result.context` |
 | `DEFAULT_API_BASE` | `https://zindua.run/api/v1` |
 | `LIMITS` | Client-side validation limits |

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;
@@ -45,6 +62,42 @@ export type ZinduaTemplateInfo = {
     defaultLang: string;
     variables: string[];
 };
+export type ZinduaUpsertTemplateOptions = {
+    slug: string;
+    lang: string;
+    subject: string;
+    bodyHtml: string;
+    bodyText?: string;
+    isDefault?: boolean;
+};
+export type ZinduaUpsertTemplateResult = {
+    ok: true;
+    slug: string;
+    created: boolean;
+    templateCreated: boolean;
+    version: {
+        lang: string;
+        subject: string;
+        isDefault: boolean;
+        updatedAt: string;
+    };
+    variables: string[];
+};
+export type ZinduaRenderTemplateOptions = {
+    template: string;
+    lang?: string;
+    variables?: Record<string, string>;
+};
+export type ZinduaRenderTemplateResult = {
+    ok: true;
+    template: string;
+    langUsed: string;
+    langFallback: boolean;
+    subject: string;
+    html: string;
+    text: string | null;
+    variables: string[];
+};
 export type ZinduaConnectResult = {
     ok: true;
     connected: true;
@@ -272,6 +325,21 @@ export declare class Zindua {
         templates: ZinduaTemplateInfo[];
         limits?: Record<string, unknown>;
     }>;
+    /**
+     * Create or update a template locale (PUT …/templates/{slug}/versions/{lang}).
+     * Use after React Email `render()` to push HTML — creates the slug if missing.
+     */
+    upsertTemplate(options: ZinduaUpsertTemplateOptions): Promise<ZinduaUpsertTemplateResult>;
+    /**
+     * Interpolate a hosted template without sending (POST /templates/render).
+     * Prefer `send()` for delivery — use this for progressive migration only.
+     */
+    renderTemplate(options: ZinduaRenderTemplateOptions): Promise<ZinduaRenderTemplateResult>;
+    /**
+     * 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.4.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,110 @@ class Zindua {
             limits: data.limits,
         };
     }
+    /**
+     * Create or update a template locale (PUT …/templates/{slug}/versions/{lang}).
+     * Use after React Email `render()` to push HTML — creates the slug if missing.
+     */
+    async upsertTemplate(options) {
+        const slug = (0, validate_1.validateTemplateSlug)(options.slug);
+        const lang = (0, validate_1.validateLang)(options.lang);
+        if (!lang) {
+            throw new errors_1.ZinduaError("lang is required.", { status: 0, code: "MISSING_FIELDS" });
+        }
+        const subject = typeof options.subject === "string" ? options.subject.trim() : "";
+        const bodyHtml = typeof options.bodyHtml === "string" ? options.bodyHtml : "";
+        if (!subject) {
+            throw new errors_1.ZinduaError("subject is required.", { status: 0, code: "MISSING_FIELDS" });
+        }
+        if (!bodyHtml.trim()) {
+            throw new errors_1.ZinduaError("bodyHtml is required.", { status: 0, code: "MISSING_FIELDS" });
+        }
+        const payload = { subject, bodyHtml };
+        if (typeof options.bodyText === "string")
+            payload.bodyText = options.bodyText;
+        if (options.isDefault === true)
+            payload.isDefault = true;
+        const data = await this.request("PUT", `templates/${encodeURIComponent(slug)}/versions/${encodeURIComponent(lang)}`, payload);
+        if (data.ok !== true || !data.version || typeof data.version !== "object") {
+            throw new errors_1.ZinduaError("API response missing upsert payload.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return {
+            ok: true,
+            slug: typeof data.slug === "string" ? data.slug : slug,
+            created: Boolean(data.created),
+            templateCreated: Boolean(data.templateCreated),
+            version: data.version,
+            variables: Array.isArray(data.variables) ? data.variables : [],
+        };
+    }
+    /**
+     * Interpolate a hosted template without sending (POST /templates/render).
+     * Prefer `send()` for delivery — use this for progressive migration only.
+     */
+    async renderTemplate(options) {
+        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 = { template };
+        if (lang)
+            payload.lang = lang;
+        if (variables)
+            payload.variables = variables;
+        const data = await this.request("POST", "templates/render", payload);
+        if (data.ok !== true ||
+            typeof data.subject !== "string" ||
+            typeof data.html !== "string") {
+            throw new errors_1.ZinduaError("API response missing render payload.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return {
+            ok: true,
+            template: typeof data.template === "string" ? data.template : template,
+            langUsed: typeof data.langUsed === "string" ? data.langUsed : lang ?? "en",
+            langFallback: Boolean(data.langFallback),
+            subject: data.subject,
+            html: data.html,
+            text: typeof data.text === "string" ? data.text : null,
+            variables: Array.isArray(data.variables) ? data.variables : [],
+        };
+    }
+    /**
+     * 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, ZinduaRenderTemplateOptions, ZinduaRenderTemplateResult, ZinduaSendContext, ZinduaSendOptions, ZinduaSendResult, ZinduaTemplateInfo, ZinduaUpsertTemplateOptions, ZinduaUpsertTemplateResult, SendChannel, } from "./client";
 export { ZinduaError } from "./errors";
 export type { ZinduaErrorCode } from "./errors";
 export { DEFAULT_API_BASE, LIMITS } from "./validate";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zindua/sdk",
-  "version": "1.2.9",
-  "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
+  "version": "1.4.0",
+  "description": "Official Zindua SDK for Node.js — transactional email, WhatsApp, template upsert/render via /api/v1.",
   "author": "Zindua",
   "license": "MIT",
   "homepage": "https://zindua.run/developers#sdks",