@zindua/sdk 1.3.0 → 1.4.1

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) |
 
@@ -88,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.1
 ```
 
 ```typescript
@@ -184,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 |
@@ -580,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.
 
 ---
@@ -602,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

@@ -1,6 +1,6 @@
 export type SendChannel = "email" | "whatsapp";
 export type ZinduaSendOptions = {
-    to: string;
+    to: string | string[];
     template: string;
     channel?: SendChannel;
     lang?: string;
@@ -26,6 +26,9 @@ export type ZinduaEmailVerifyResult = {
     suppressed: boolean;
     suppressionReason: string | null;
     deliverable: boolean;
+    catchAll?: boolean;
+    headline?: string;
+    youShould?: string;
 };
 export type ZinduaClientOptions = {
     apiKey: string;
@@ -62,6 +65,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;
@@ -113,6 +152,8 @@ export type ZinduaSendResult = {
     channel: SendChannel;
     status: string;
     logId: string;
+    logIds?: string[];
+    billed?: number;
     langUsed?: string;
     langFallback?: boolean;
     testMode?: boolean;
@@ -172,7 +213,9 @@ export declare class Zindua {
                 expiresAt: string;
             };
         }>;
-        respond: (challengeId: string, value: string) => Promise<{
+        respond: (challengeId: string, value: string, options?: {
+            userExternalId?: string;
+        }) => Promise<{
             ok: boolean;
             status: string;
             error?: string;
@@ -238,7 +281,9 @@ export declare class Zindua {
                 expiresAt: string;
             };
         }>;
-        respond: (challengeId: string, value: string) => Promise<{
+        respond: (challengeId: string, value: string, options?: {
+            userExternalId?: string;
+        }) => Promise<{
             ok: boolean;
             status: string;
             error?: string;
@@ -289,6 +334,16 @@ 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.

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.3.0";
+const SDK_VERSION = "1.4.1";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -120,8 +120,8 @@ class Zindua {
         getStatus: async (challengeId) => {
             return this.request("GET", `challenges/${encodeURIComponent(challengeId)}`);
         },
-        respond: async (challengeId, value) => {
-            return this.request("POST", `challenges/${encodeURIComponent(challengeId)}/respond`, { value });
+        respond: async (challengeId, value, options) => {
+            return this.request("POST", `challenges/${encodeURIComponent(challengeId)}/respond`, { value, userExternalId: options?.userExternalId });
         },
         /**
          * SSE listener for challenge status (requires API key — server-side or trusted runtime).
@@ -258,6 +258,78 @@ 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.
@@ -288,6 +360,9 @@ class Zindua {
             suppressed: Boolean(data.suppressed),
             suppressionReason: typeof data.suppressionReason === "string" ? data.suppressionReason : null,
             deliverable: Boolean(data.deliverable),
+            catchAll: Boolean(data.catchAll),
+            headline: typeof data.headline === "string" ? data.headline : undefined,
+            youShould: typeof data.youShould === "string" ? data.youShould : undefined,
         };
     }
     /** Delivery status for a logId returned by send() (GET /logs/{logId}). */
@@ -326,6 +401,10 @@ class Zindua {
             channel: (data.channel === "whatsapp" ? "whatsapp" : "email"),
             status: typeof data.status === "string" ? data.status : "queued",
             logId: data.logId,
+            logIds: Array.isArray(data.logIds)
+                ? data.logIds.filter((id) => typeof id === "string")
+                : undefined,
+            billed: typeof data.billed === "number" ? data.billed : undefined,
             langUsed: typeof data.langUsed === "string" ? data.langUsed : undefined,
             langFallback: typeof data.langFallback === "boolean" ? data.langFallback : undefined,
             testMode: typeof data.testMode === "boolean" ? data.testMode : undefined,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Zindua } from "./client";
-export type { ZinduaClientOptions, ZinduaConnectResult, ZinduaEmailVerifyResult, 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/dist/validate.d.ts

@@ -16,7 +16,7 @@ export declare function validateApiKey(apiKey: string): string;
 export declare function validateBaseUrl(raw: string): string;
 export declare function resolveBaseUrl(explicit?: string): string;
 export declare function validateTemplateSlug(template: string): string;
-export declare function validateRecipient(to: string, channel: "email" | "whatsapp"): string;
+export declare function validateRecipient(to: string | string[], channel: "email" | "whatsapp"): string | string[];
 export declare function validateChannel(channel?: string): "email" | "whatsapp";
 export declare function validateLang(lang?: string): string | undefined;
 export declare function sanitizeVariables(variables?: Record<string, string>): Record<string, string> | undefined;

package/dist/validate.js

@@ -104,6 +104,20 @@ function validateTemplateSlug(template) {
     return slug;
 }
 function validateRecipient(to, channel) {
+    const parts = (Array.isArray(to) ? to : [to])
+        .flatMap((value) => String(value).split(/[,;]/))
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        throw new errors_1.ZinduaError("to is required and must be under 320 characters.", {
+            status: 0,
+            code: "MISSING_FIELDS",
+        });
+    }
+    const validated = parts.map((part) => validateOneRecipient(part, channel));
+    return validated.length === 1 ? validated[0] : validated;
+}
+function validateOneRecipient(to, channel) {
     const recipient = to.trim();
     if (!recipient || recipient.length > exports.LIMITS.maxToLength) {
         throw new errors_1.ZinduaError("to is required and must be under 320 characters.", {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zindua/sdk",
-  "version": "1.3.0",
-  "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
+  "version": "1.4.1",
+  "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",