@zindua/sdk 1.3.0 → 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) |
 
@@ -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.0
 ```
 
 ```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

@@ -62,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;
@@ -289,6 +325,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.0";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -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.

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/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.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",