@zindua/sdk 1.2.4 → 1.2.7

package/README.md

@@ -14,6 +14,8 @@ npm install @zindua/sdk
 
 **Requirements:** Node.js 18+, run only on your **backend** (not in the browser).
 
+**Dependencies:** `@zindua/sdk` has **no runtime npm dependencies**. After `npm install`, you are done — no second package to add. The client uses Node’s built-in `fetch` (Node 18+).
+
 ---
 
 ## Quick start
@@ -24,7 +26,7 @@ npm install @zindua/sdk
 2. Open **Projects** → create a project (or use an existing one).
 3. Copy the API key (`znd_live_…` for production, `znd_test_…` for sandbox).
 4. In the project: connect **Service** (Gmail, SMTP, …) for email, and/or link **WhatsApp** for OTP.
-5. Create at least one **template** (e.g. slug `otp`, `welcome`).
+5. Create at least one **template** (e.g. slug `otp`, `welcome`). For several languages, add one version per language in Dashboard → Templates (and set the project **default language** in project settings).
 
 ### 2. Install and configure
 
@@ -55,7 +57,45 @@ await zindua.send({
   variables: { name: "Alex" },
 });
 
-// WhatsApp — phone in E.164 with +
+// WhatsApp — E.164 phone with + (channel is required for WhatsApp)
+await zindua.send({
+  to: "+243812345678",
+  channel: "whatsapp",
+  template: "otp",
+  variables: { code: "482910" },
+});
+```
+
+### Channel and `to` must match
+
+The SDK checks **before** calling the API (same rules as [zindua.run](https://zindua.run)). A phone number cannot be sent as email, and an email cannot be sent on WhatsApp.
+
+| `channel` | Valid `to` | Rejected (not sent) |
+|-----------|------------|---------------------|
+| `email` (default) | `user@example.com` | `+243812345678` |
+| `whatsapp` | `+243812345678` | `user@example.com` |
+
+```typescript
+// ❌ Phone with default channel email — rejected locally (INVALID_EMAIL)
+await zindua.send({ to: "+243812345678", template: "otp", variables: { code: "1" } });
+
+// ❌ Email with WhatsApp channel — rejected locally (INVALID_PHONE)
+await zindua.send({
+  to: "user@example.com",
+  channel: "whatsapp",
+  template: "otp",
+  variables: { code: "1" },
+});
+
+// ✅ User chose email for OTP
+await zindua.send({
+  to: "user@example.com",
+  channel: "email",
+  template: "otp",
+  variables: { code: "482910" },
+});
+
+// ✅ User chose WhatsApp for OTP
 await zindua.send({
   to: "+243812345678",
   channel: "whatsapp",
@@ -66,6 +106,55 @@ await zindua.send({
 
 ---
 
+## Languages (multilingual projects)
+
+When you create a project, you choose a **default language** (Dashboard → project settings). Each template can have **several language versions** (French, English, Swahili, …) with its own subject and body.
+
+When you call `send()`, pass **`lang` only if you want a specific version**. If you omit it, Zindua uses the **project default**. If the language you ask for does not exist on that template, Zindua uses the template’s **default language** and sets `langFallback: true` in the response.
+
+| What you send | What Zindua uses |
+|---------------|------------------|
+| No `lang` | Project default (e.g. `fr`) |
+| `lang: "en"` and English exists on the template | English version |
+| `lang: "de"` but only `fr` / `en` exist | Default language for that template + `langFallback: true` |
+
+```typescript
+// Default language of the project
+await zindua.send({
+  to: "user@example.com",
+  template: "otp",
+  variables: { code: "482910" },
+});
+
+// Explicit language (email or WhatsApp — same `lang` for both channels)
+const result = await zindua.send({
+  to: "+243812345678",
+  channel: "whatsapp",
+  template: "otp",
+  lang: "fr",
+  variables: { code: "482910" },
+});
+
+console.log(result.langUsed); // e.g. "fr" — language actually rendered
+console.log(result.langFallback); // true if `lang` was missing and fallback was used
+```
+
+OTP with the user’s locale (optional):
+
+```typescript
+await zindua.send({
+  to: contact,
+  channel,
+  template: "otp",
+  lang: userLocale, // e.g. "fr", "en" — omit if you want project default
+  variables: { code },
+});
+```
+
+Allowed codes: short ISO 639-1 style (`fr`, `en`, `sw`, `en-us`). Invalid format is rejected by the SDK before the HTTP call.
+
+---
+
 ## Plans and channels
 
 | Plan | Email API | WhatsApp | Email / month | WhatsApp OTP / month |
@@ -118,6 +207,46 @@ Each key only accesses **its** Zindua project (templates, service, usage).
 
 ---
 
+## Several templates in one application
+
+You do **not** need a separate SDK client per template. One `Zindua` instance, change the **`template` slug** and **`variables`** per send:
+
+```typescript
+// OTP
+await zindua.send({
+  to: "user@example.com",
+  template: "otp",
+  variables: { code: "482910" },
+});
+
+// Welcome email — different slug, different variables
+await zindua.send({
+  to: "user@example.com",
+  template: "user-welcome",
+  variables: { name: "Alex" },
+});
+```
+
+Keep slugs in one place so your code stays clear:
+
+```typescript
+const Template = {
+  otp: "otp",
+  welcome: "user-welcome",
+  resetPassword: "password-reset",
+} as const;
+
+await zindua.send({
+  to: email,
+  template: Template.welcome,
+  variables: { name },
+});
+```
+
+Each template defines its own `{{variables}}` in the dashboard. The SDK does not merge templates: one `send()` call = one template slug.
+
+---
+
 ## Framework examples
 
 Use the same pattern everywhere: **your server** holds the API key; the client app calls **your** API.
@@ -137,10 +266,16 @@ import { zindua } from "@/lib/zindua";
 import { NextResponse } from "next/server";
 
 export async function POST(req: Request) {
-  const { email, code } = await req.json();
+  const { channel, contact, code, lang } = await req.json();
+  if (channel !== "email" && channel !== "whatsapp") {
+    return NextResponse.json({ error: "channel must be email or whatsapp" }, { status: 400 });
+  }
+  // contact = email string OR +243… phone, depending on channel
   const result = await zindua.send({
-    to: email,
+    to: contact,
+    channel,
     template: "otp",
+    ...(lang ? { lang } : {}),
     variables: { code },
   });
   return NextResponse.json(result, { status: 202 });
@@ -159,11 +294,16 @@ app.use(express.json());
 const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
 
 app.post("/api/notify", async (req, res) => {
+  const { channel, contact, code } = req.body;
+  if (channel !== "email" && channel !== "whatsapp") {
+    return res.status(400).json({ error: "channel must be email or whatsapp" });
+  }
   try {
     const result = await zindua.send({
-      to: req.body.email,
-      template: req.body.template ?? "otp",
-      variables: req.body.variables ?? {},
+      to: contact,
+      channel,
+      template: "otp",
+      variables: { code },
     });
     res.status(202).json(result);
   } catch (err) {
@@ -181,14 +321,22 @@ import { Zindua } from "@zindua/sdk";
 const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
 const app = Fastify();
 
-app.post<{ Body: { email: string; code: string } }>("/notify", async (req, reply) => {
-  const result = await zindua.send({
-    to: req.body.email,
-    template: "otp",
-    variables: { code: req.body.code },
-  });
-  return reply.status(202).send(result);
-});
+app.post<{ Body: { channel: "email" | "whatsapp"; contact: string; code: string } }>(
+  "/notify",
+  async (req, reply) => {
+    const { channel, contact, code } = req.body;
+    if (channel !== "email" && channel !== "whatsapp") {
+      return reply.status(400).send({ error: "channel must be email or whatsapp" });
+    }
+    const result = await zindua.send({
+      to: contact,
+      channel,
+      template: "otp",
+      variables: { code },
+    });
+    return reply.status(202).send(result);
+  }
+);
 ```
 
 ### Hono
@@ -201,9 +349,13 @@ const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
 const app = new Hono();
 
 app.post("/notify", async (c) => {
-  const { email, code } = await c.req.json();
+  const { channel, contact, code } = await c.req.json();
+  if (channel !== "email" && channel !== "whatsapp") {
+    return c.json({ error: "channel must be email or whatsapp" }, 400);
+  }
   const result = await zindua.send({
-    to: email,
+    to: contact,
+    channel,
     template: "otp",
     variables: { code },
   });
@@ -217,6 +369,32 @@ Do **not** embed `@zindua/sdk` or `znd_live_…` in the app. Call your backend r
 
 ---
 
+## WordPress site binding & `connect()`
+
+Each API key can be linked to **one site URL** (used by the [WordPress plugin](https://zindua.run/wordpress)). Pass `siteUrl` on the client so every request includes `X-Zindua-Site-Url`:
+
+```typescript
+const zindua = new Zindua({
+  apiKey: process.env.ZINDUA_API_KEY!,
+  siteUrl: "https://shop.example.com",
+});
+
+// First connect binds the key to this URL
+const status = await zindua.connect();
+console.log(status.project.name, status.templates);
+
+// Later: list templates with langs (fr, en, …)
+const { templates } = await zindua.getTemplates();
+```
+
+| Error code | Meaning |
+|------------|---------|
+| `SITE_ALREADY_BOUND` | Key already used on another site — create a new project or regenerate the key |
+| `SITE_MISMATCH` | `siteUrl` does not match the registered site |
+| `SITE_URL_REQUIRED` | Key is bound; update the SDK and set `siteUrl` |
+
+---
+
 ## Configuration options
 
 | Option | Default | Description |
@@ -224,10 +402,12 @@ Do **not** embed `@zindua/sdk` or `znd_live_…` in the app. Call your backend r
 | `apiKey` | — | **Required.** `znd_live_…` or `znd_test_…` from the dashboard. |
 | `baseUrl` | `https://zindua.run/api/v1` | Override only for local testing (`http://localhost:3000/api/v1`). |
 | `timeoutMs` | `30000` | Request timeout (max `120000`). |
+| `siteUrl` | — | Your app origin (`https://example.com`). Required once the key is site-bound. |
 
 ```typescript
 const zindua = new Zindua({
   apiKey: process.env.ZINDUA_API_KEY!,
+  siteUrl: process.env.APP_URL,
   baseUrl: process.env.ZINDUA_API_BASE_URL, // optional
   timeoutMs: 45_000,
 });
@@ -239,15 +419,45 @@ const zindua = new Zindua({
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `to` | Yes | Email address, or E.164 phone (`+243…`) for WhatsApp. |
+| `to` | Yes | **Email** if `channel` is `email` (default). **E.164 phone** (`+243…`) if `channel` is `whatsapp`. Mismatches are rejected by the SDK and by the API. |
 | `template` | Yes | Template slug from your dashboard. |
-| `channel` | No | `"email"` (default) or `"whatsapp"`. |
-| `lang` | No | `fr`, `en`, … — falls back to project default. |
+| `channel` | No | `"email"` (default) or `"whatsapp"`. Must match the format of `to`. |
+| `lang` | No | Optional. `fr`, `en`, `sw`, … — if omitted, project default; if missing on template, fallback + `langFallback: true`. |
 | `variables` | No | `{{placeholders}}` in the template. |
 | `cc`, `bcc`, `replyTo` | No | Email only. |
 
 ---
 
+## API key, recipient, and delivery — what is checked when
+
+| Situation | When you know | What to do |
+|-----------|---------------|------------|
+| Wrong or missing API key | Immediately (`401`, `INVALID_API_KEY` / `API_KEY_NOT_FOUND`) | Copy key from Dashboard → Projects |
+| Phone sent as email (or the opposite) | Immediately in the SDK (`INVALID_EMAIL` / `INVALID_PHONE`, HTTP status `0`) | Match `channel` and `to` (see above) |
+| Malformed email or phone | Immediately (SDK + API `400`) | Fix format: `user@domain.com`, `+243812345678` |
+| Typo in email (`user@gmial.com`) | **Not** blocked at send time | Request may succeed (`202`); provider may bounce later |
+| Email inbox does not exist | **Not** verified upfront | Check **Dashboard → Logs** with `logId`; configure **webhooks** (`email.delivered` / `email.failed`) |
+| Phone valid in E.164 but **no WhatsApp** on that number | **Not** verified upfront | WhatsApp send can fail after accept; status `failed` in logs |
+| Template slug wrong | API `404` `TEMPLATE_NOT_FOUND` | Create template or fix slug |
+| No Gmail/SMTP / WhatsApp not linked | API `422` | Connect **Service** or **WhatsApp** on the project |
+
+**Important:** a successful `send()` returns `logId` and often `status: "queued"`. That means Zindua accepted the message and will deliver through **your** connected email service or WhatsApp session. It does not guarantee the address exists or that WhatsApp is installed on that number.
+
+```typescript
+const result = await zindua.send({
+  to: "user@example.com",
+  template: "otp",
+  variables: { code: "123456" },
+});
+
+// Save logId — check delivery in the dashboard or via webhooks
+console.log(result.logId, result.status, result.langUsed);
+```
+
+Optional in **your** app (before calling Zindua): stricter email regex, confirmation field, or a phone library — the SDK already enforces platform format and channel rules.
+
+---
+
 ## Successful response
 
 ```typescript
@@ -260,6 +470,8 @@ const result = await zindua.send({ /* … */ });
 | `status` | `queued`, `processing`, or `sent` (test keys often return `sent` immediately). |
 | `logId` | Id for support / logs in the dashboard. |
 | `channel` | `email` or `whatsapp` |
+| `langUsed` | Language version used for this send |
+| `langFallback` | `true` if requested `lang` was missing and a fallback version was used |
 | `context` | Workspace snapshot (see below). |
 
 ### `context` object
@@ -311,9 +523,9 @@ try {
 | `INVALID_API_KEY` | 401 | Missing or malformed key. | Use `Authorization: Bearer znd_live_…` (24 chars after prefix). |
 | `API_KEY_NOT_FOUND` | 401 | Key not linked to a project. | Copy the key from Dashboard → your project. |
 | `ORIGIN_NOT_ALLOWED` | 403 | Browser origin blocked. | Prefer server-side SDK; or add origin in Dashboard → Settings → Integrations. |
-| `MISSING_FIELDS` | 400 | `to` or `template` missing. | Send both in the request body. |
-| `INVALID_EMAIL` | 400 | Bad email format. | Use `user@domain.com`. |
-| `INVALID_PHONE` | 400 | Bad WhatsApp number. | Use E.164 with `+`, e.g. `+243812345678`. |
+| `MISSING_FIELDS` | 400 / 0 | `to` or `template` missing. | Send both. Status `0` = caught by the SDK before HTTP. |
+| `INVALID_EMAIL` | 400 / 0 | Bad email, or **phone used with channel email**. | Use `user@domain.com`, or set `channel: "whatsapp"` for `+243…`. |
+| `INVALID_PHONE` | 400 / 0 | Bad WhatsApp number, or **email used with channel whatsapp**. | Use `+243812345678`, or set `channel: "email"` for an address. |
 | `NO_SUBSCRIPTION` | 403 | Workspace has no active plan. | Open Dashboard → Billing or contact support. |
 | `EMAIL_NOT_AVAILABLE` | 403 | Email not allowed on current plan setup. | Connect a Service on the project (Free), or upgrade plan. |
 | `EMAIL_SERVICE_NOT_CONFIGURED` | 422 | No Gmail/SMTP connected. | Dashboard → project → **Service**. |
@@ -339,7 +551,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.4"`.
+4. Pin the SDK version in `package.json`, e.g. `"@zindua/sdk": "1.2.6"`.
 5. One Zindua project per client when quotas, senders, or templates must stay isolated.
 
 ---

package/dist/client.d.ts

@@ -16,6 +16,41 @@ export type ZinduaClientOptions = {
     baseUrl?: string;
     /** Request timeout (default 30s, max 120s). */
     timeoutMs?: number;
+    /**
+     * Your app or WordPress site origin (e.g. https://shop.example.com).
+     * Sent as X-Zindua-Site-Url — required once the API key is bound to a site.
+     */
+    siteUrl?: string;
+};
+export type ZinduaProjectInfo = {
+    name: string;
+    slug: string;
+    defaultLang: string;
+    dashboardUrl: string;
+};
+export type ZinduaTemplateInfo = {
+    slug: string;
+    langs: string[];
+    defaultLang: string;
+    variables: string[];
+};
+export type ZinduaConnectResult = {
+    ok: true;
+    connected: true;
+    siteUrl: string;
+    newlyBound: boolean;
+    project: ZinduaProjectInfo;
+    templates: ZinduaTemplateInfo[];
+    plan: ZinduaSendContext["plan"];
+    channels: {
+        email: {
+            ready: boolean;
+        };
+        whatsapp: {
+            ready: boolean;
+            status?: string;
+        };
+    };
 };
 export type ZinduaSendContext = {
     project: {
@@ -58,10 +93,25 @@ export type ZinduaSendResult = {
 };
 export declare class Zindua {
     private readonly apiKey;
-    private readonly sendUrl;
+    private readonly apiBase;
     private readonly timeoutMs;
+    private readonly siteUrl?;
     constructor(options: ZinduaClientOptions);
     /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
     isTestMode(): boolean;
+    /**
+     * Bind this API key to your site (WordPress connect flow).
+     * First call wins — the same key cannot be used on another site URL.
+     */
+    connect(siteUrl?: string): Promise<ZinduaConnectResult>;
+    /** Project status, channels, and plan (GET /project). */
+    getProject(): Promise<Record<string, unknown>>;
+    /** Synced templates with langs and variables (GET /templates). */
+    getTemplates(): Promise<{
+        templates: ZinduaTemplateInfo[];
+        limits?: Record<string, unknown>;
+    }>;
     send(options: ZinduaSendOptions): Promise<ZinduaSendResult>;
+    private buildHeaders;
+    private request;
 }

package/dist/client.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Zindua = void 0;
 const errors_1 = require("./errors");
 const validate_1 = require("./validate");
-const SDK_VERSION = "1.2.4";
+const SDK_VERSION = "1.2.7";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -50,6 +50,8 @@ function parseApiError(status, body) {
         details.hint = body.hint;
     if (typeof body.retryAfterSec === "number")
         details.retryAfterSec = body.retryAfterSec;
+    if (typeof body.boundSite === "string")
+        details.boundSite = body.boundSite;
     if (Array.isArray(body.availableTemplateSlugs)) {
         details.availableTemplateSlugs = body.availableTemplateSlugs;
     }
@@ -69,34 +71,109 @@ function parseApiError(status, body) {
 }
 class Zindua {
     apiKey;
-    sendUrl;
+    apiBase;
     timeoutMs;
+    siteUrl;
     constructor(options) {
         (0, validate_1.assertServerRuntime)();
         this.apiKey = (0, validate_1.validateApiKey)(options.apiKey);
-        const base = (0, validate_1.resolveBaseUrl)(options.baseUrl);
-        this.sendUrl = `${base}/send`;
+        this.apiBase = (0, validate_1.resolveBaseUrl)(options.baseUrl);
         this.timeoutMs = (0, validate_1.validateTimeoutMs)(options.timeoutMs);
+        this.siteUrl = (0, validate_1.validateSiteUrl)(options.siteUrl);
     }
     /** Returns true when using a znd_test_ key (sandbox / no real delivery). */
     isTestMode() {
         return this.apiKey.startsWith("znd_test_");
     }
+    /**
+     * Bind this API key to your site (WordPress connect flow).
+     * First call wins — the same key cannot be used on another site URL.
+     */
+    async connect(siteUrl) {
+        const url = (0, validate_1.validateSiteUrl)(siteUrl) ?? this.siteUrl;
+        const data = await this.request("POST", "connect", {
+            siteUrl: url,
+        });
+        if (data.ok !== true || !data.project || !Array.isArray(data.templates)) {
+            throw new errors_1.ZinduaError("API response missing connect payload.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return {
+            ok: true,
+            connected: true,
+            siteUrl: typeof data.siteUrl === "string" ? data.siteUrl : url ?? "",
+            newlyBound: Boolean(data.newlyBound),
+            project: data.project,
+            templates: data.templates,
+            plan: data.plan ?? null,
+            channels: data.channels ?? {
+                email: { ready: false },
+                whatsapp: { ready: false },
+            },
+        };
+    }
+    /** Project status, channels, and plan (GET /project). */
+    async getProject() {
+        return this.request("GET", "project");
+    }
+    /** Synced templates with langs and variables (GET /templates). */
+    async getTemplates() {
+        const data = await this.request("GET", "templates");
+        return {
+            templates: Array.isArray(data.templates) ? data.templates : [],
+            limits: data.limits,
+        };
+    }
     async send(options) {
         const channel = (0, validate_1.validateChannel)(options.channel);
         const payload = buildPayload(options, channel);
+        const data = await this.request("POST", "send", payload);
+        if (data.success !== true || typeof data.logId !== "string") {
+            throw new errors_1.ZinduaError("API response missing success or logId.", {
+                status: 200,
+                code: "INVALID_RESPONSE",
+            });
+        }
+        return {
+            success: true,
+            channel: (data.channel === "whatsapp" ? "whatsapp" : "email"),
+            status: typeof data.status === "string" ? data.status : "queued",
+            logId: data.logId,
+            langUsed: typeof data.langUsed === "string" ? data.langUsed : undefined,
+            langFallback: typeof data.langFallback === "boolean" ? data.langFallback : undefined,
+            testMode: typeof data.testMode === "boolean" ? data.testMode : undefined,
+            project: typeof data.project === "string" ? data.project : undefined,
+            context: data.context && typeof data.context === "object"
+                ? data.context
+                : undefined,
+        };
+    }
+    buildHeaders() {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": USER_AGENT,
+            Accept: "application/json",
+        };
+        if (this.siteUrl) {
+            headers["X-Zindua-Site-Url"] = this.siteUrl;
+        }
+        return headers;
+    }
+    async request(method, path, body) {
+        const url = `${this.apiBase}/${path.replace(/^\//, "")}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
-            const response = await fetch(this.sendUrl, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${this.apiKey}`,
-                    "User-Agent": USER_AGENT,
-                    Accept: "application/json",
-                },
-                body: JSON.stringify(payload),
+            const headers = this.buildHeaders();
+            if (body) {
+                headers["Content-Type"] = "application/json";
+            }
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
                 redirect: "error",
             });
@@ -114,25 +191,7 @@ class Zindua {
             if (!response.ok) {
                 throw parseApiError(response.status, data);
             }
-            if (data.success !== true || typeof data.logId !== "string") {
-                throw new errors_1.ZinduaError("API response missing success or logId.", {
-                    status: response.status,
-                    code: "INVALID_RESPONSE",
-                });
-            }
-            return {
-                success: true,
-                channel: (data.channel === "whatsapp" ? "whatsapp" : "email"),
-                status: typeof data.status === "string" ? data.status : "queued",
-                logId: data.logId,
-                langUsed: typeof data.langUsed === "string" ? data.langUsed : undefined,
-                langFallback: typeof data.langFallback === "boolean" ? data.langFallback : undefined,
-                testMode: typeof data.testMode === "boolean" ? data.testMode : undefined,
-                project: typeof data.project === "string" ? data.project : undefined,
-                context: data.context && typeof data.context === "object"
-                    ? data.context
-                    : undefined,
-            };
+            return data;
         }
         catch (err) {
             if (err instanceof errors_1.ZinduaError)

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type ZinduaErrorCode = "INVALID_API_KEY" | "INVALID_BASE_URL" | "BROWSER_FORBIDDEN" | "INVALID_OPTIONS" | "INVALID_RECIPIENT" | "INVALID_TEMPLATE" | "INVALID_CHANNEL" | "INVALID_LANG" | "INVALID_VARIABLES" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "API_ERROR";
+export type ZinduaErrorCode = "INVALID_API_KEY" | "INVALID_BASE_URL" | "BROWSER_FORBIDDEN" | "INVALID_OPTIONS" | "INVALID_EMAIL" | "INVALID_PHONE" | "MISSING_FIELDS" | "INVALID_TEMPLATE" | "INVALID_CHANNEL" | "INVALID_LANG" | "INVALID_VARIABLES" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "API_ERROR";
 /** Structured error — never includes the API key in the message. */
 export declare class ZinduaError extends Error {
     readonly status: number;

package/dist/index.d.ts

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

@@ -23,3 +23,5 @@ export declare function sanitizeVariables(variables?: Record<string, string>): R
 export declare function validateOptionalEmailField(field: "cc" | "bcc" | "replyTo", value?: string): string | undefined;
 export declare function validateAttachments(attachments?: unknown[]): unknown[] | undefined;
 export declare function validateTimeoutMs(timeoutMs?: number): number;
+/** Normalize site URL for WordPress one-key-one-site binding (protocol + host). */
+export declare function validateSiteUrl(siteUrl?: string): string | undefined;

package/dist/validate.js

@@ -13,6 +13,7 @@ exports.sanitizeVariables = sanitizeVariables;
 exports.validateOptionalEmailField = validateOptionalEmailField;
 exports.validateAttachments = validateAttachments;
 exports.validateTimeoutMs = validateTimeoutMs;
+exports.validateSiteUrl = validateSiteUrl;
 const errors_1 = require("./errors");
 /** Matches platform `isValidE164Phone` in zindua.run API. */
 const E164_RE = /^\+[1-9]\d{6,14}$/;
@@ -107,20 +108,26 @@ function validateRecipient(to, channel) {
     if (!recipient || recipient.length > exports.LIMITS.maxToLength) {
         throw new errors_1.ZinduaError("to is required and must be under 320 characters.", {
             status: 0,
-            code: "INVALID_RECIPIENT",
+            code: "MISSING_FIELDS",
         });
     }
     if (channel === "email") {
+        if (E164_RE.test(recipient)) {
+            throw new errors_1.ZinduaError('A phone number cannot be sent on channel "email". Use an email address (e.g. user@example.com) or set channel to "whatsapp".', { status: 0, code: "INVALID_EMAIL" });
+        }
         if (!EMAIL_RE.test(recipient)) {
             throw new errors_1.ZinduaError("Invalid email address for channel email.", {
                 status: 0,
-                code: "INVALID_RECIPIENT",
+                code: "INVALID_EMAIL",
             });
         }
         return recipient;
     }
+    if (EMAIL_RE.test(recipient)) {
+        throw new errors_1.ZinduaError('An email address cannot be sent on channel "whatsapp". Use E.164 with + (e.g. +243812345678) or set channel to "email".', { status: 0, code: "INVALID_PHONE" });
+    }
     if (!E164_RE.test(recipient)) {
-        throw new errors_1.ZinduaError("WhatsApp to must be E.164 with leading + (e.g. +243812345678).", { status: 0, code: "INVALID_RECIPIENT" });
+        throw new errors_1.ZinduaError("WhatsApp to must be E.164 with leading + (e.g. +243812345678).", { status: 0, code: "INVALID_PHONE" });
     }
     return recipient;
 }
@@ -208,3 +215,21 @@ function validateTimeoutMs(timeoutMs) {
     }
     return Math.floor(timeoutMs);
 }
+/** Normalize site URL for WordPress one-key-one-site binding (protocol + host). */
+function validateSiteUrl(siteUrl) {
+    if (siteUrl === undefined || siteUrl === null)
+        return undefined;
+    const trimmed = String(siteUrl).trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const url = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        throw new errors_1.ZinduaError("siteUrl must be a valid URL (e.g. https://example.com).", {
+            status: 0,
+            code: "INVALID_OPTIONS",
+        });
+    }
+}

package/package.json

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