@zindua/sdk 1.2.2 → 1.2.3

package/README.md

@@ -25,7 +25,7 @@ Send in a locale with the `lang` field (ISO code: `fr`, `en`, `sw`, …). If you
 | **Pro** | 50 | 10 |
 | **Team** | 1000 | 100 |
 
-On **Free**, the **email API** (`channel: "email"`) is for dashboard/testing; production email via API needs **Pro** or **Team**. **WhatsApp OTP** works on Free (quota applies). See [pricing](https://zindua.run/pricing) for quotas.
+On **Free**, **email API** works when you connect a **Service** (Gmail, SMTP, etc.) on the project. **WhatsApp OTP** works on Free (quota applies). **Pro/Team** raise template and volume limits. See [pricing](https://zindua.run/pricing).
 
 ```typescript
 // French version of the same template slug
@@ -59,7 +59,7 @@ Before using the SDK, set up your Zindua project in the dashboard:
 | Email **Service** connected (Gmail, Outlook, SendGrid, SMTP, …) | `channel: "email"` | Dashboard → **Service** |
 | WhatsApp connected (QR) | `channel: "whatsapp"` | Dashboard → **WhatsApp** |
 | Template slug (e.g. `welcome`, `otp-verification`) | All | Dashboard → **Templates** |
-| **Pro** or **Team** plan | Email API on production sends (Free = WhatsApp OTP API) | Dashboard → **Billing** |
+| **Service** on Free or **Pro/Team** plan | Email via API when Service is connected (Free) or full quotas (paid) | Dashboard → **Service** / **Billing** |
 
 **Runtime**
 
@@ -166,9 +166,51 @@ await zindua.send({
 
 ```typescript
 const result = await zindua.send({ /* … */ });
-// { success: true, status: "queued", logId: "…", channel: "email" | "whatsapp", … }
+// {
+//   success: true,
+//   status: "queued",
+//   logId: "…",
+//   channel: "email",
+//   context: { project, apiKey: { mode, suffix }, plan, channels }
+// }
 ```
 
+The API never returns your full API key. `context.apiKey.suffix` is the last 4 characters (match in Dashboard).
+
+---
+
+## Several clients (multi-project)
+
+**Recommended:** one Zindua project per client → one `znd_live_…` per project.
+
+```bash
+# .env — server only
+ZINDUA_KEY_MELLIA=znd_live_xxxxxxxxxxxxxxxxxxxxxxxx
+ZINDUA_KEY_OVERLOOK=znd_live_yyyyyyyyyyyyyyyyyyyyyyyy
+```
+
+```typescript
+import { Zindua } from "@zindua/sdk";
+
+const zinduaByTenant = {
+  mellia: new Zindua({ apiKey: process.env.ZINDUA_KEY_MELLIA! }),
+  overlook: new Zindua({ apiKey: process.env.ZINDUA_KEY_OVERLOOK! }),
+};
+
+await zinduaByTenant[tenantId].send({
+  to: "user@example.com",
+  template: "otp",
+  variables: { code: "482910" },
+});
+```
+
+| Approach | When to use |
+|----------|-------------|
+| **2+ Zindua projects** | Different clients, senders, templates, or quotas |
+| **1 Zindua project** | Same sender and templates for everyone (one key) |
+
+More detail: [zindua.run/developers#multi-project](https://zindua.run/developers#multi-project) and repo `config/API-SECURITY-MULTI-PROJECT-FR.md`.
+
 ---
 
 ## Errors
@@ -194,10 +236,12 @@ try {
 ## Security
 
 - **Server only** — throws in browser environments (`BROWSER_FORBIDDEN`).
+- **Bearer header only** — `Authorization: Bearer znd_live_…`. Keys in URL, JSON body, or `X-Api-Key` are rejected by the platform API.
 - **HTTPS** for `baseUrl` except `http://localhost` in development.
 - **No credentials in URL** — rejects `baseUrl` with embedded username/password.
 - **Input validation** — E.164 phones, email format, template slug, variable size limits (aligned with the platform API).
 - **Redirects disabled** — `fetch` uses `redirect: "error"`.
+- **CORS** — optional origin allowlist in Dashboard → Settings → Integrations (browser calls only).
 
 ---
 

package/dist/client.d.ts

@@ -17,6 +17,34 @@ export type ZinduaClientOptions = {
     /** Request timeout (default 30s, max 120s). */
     timeoutMs?: number;
 };
+export type ZinduaSendContext = {
+    project: {
+        id: string;
+        name: string;
+        slug: string;
+        teamId: string;
+    };
+    apiKey: {
+        mode: "live" | "test";
+        prefix: string;
+        suffix: string;
+    };
+    plan: {
+        slug: string;
+        name: string;
+        status: string;
+        emailApiEnabled: boolean;
+        whatsappEnabled: boolean;
+        emailQuota: number;
+        emailsUsed: number;
+        whatsappOtpQuota: number | null;
+        whatsappUsed: number;
+    } | null;
+    channels: {
+        email: boolean;
+        whatsapp: boolean;
+    };
+};
 export type ZinduaSendResult = {
     success: true;
     channel: SendChannel;
@@ -25,6 +53,8 @@ export type ZinduaSendResult = {
     langUsed?: string;
     langFallback?: boolean;
     testMode?: boolean;
+    project?: string;
+    context?: ZinduaSendContext;
 };
 export declare class Zindua {
     private readonly apiKey;

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.2";
+const SDK_VERSION = "1.2.3";
 const USER_AGENT = `Zindua-JS/${SDK_VERSION}`;
 function buildPayload(options, channel) {
     const to = (0, validate_1.validateRecipient)(options.to, channel);
@@ -46,12 +46,25 @@ function parseApiError(status, body) {
     const details = {};
     if (typeof body.code === "string")
         details.code = body.code;
+    if (typeof body.hint === "string")
+        details.hint = body.hint;
     if (typeof body.retryAfterSec === "number")
         details.retryAfterSec = body.retryAfterSec;
-    return new errors_1.ZinduaError(message, {
+    if (Array.isArray(body.availableTemplateSlugs)) {
+        details.availableTemplateSlugs = body.availableTemplateSlugs;
+    }
+    if (body.context && typeof body.context === "object") {
+        details.context = body.context;
+    }
+    const fullMessage = typeof body.hint === "string" && body.hint.length > 0 ? `${message} ${body.hint}` : message;
+    return new errors_1.ZinduaError(fullMessage, {
         status,
         code: typeof body.code === "string" ? body.code : "API_ERROR",
-        details: Object.keys(details).length > 0 ? details : undefined,
+        details: Object.keys(details).length > 0
+            ? details
+            : typeof body.hint === "string"
+                ? { hint: body.hint }
+                : undefined,
     });
 }
 class Zindua {
@@ -115,6 +128,10 @@ class Zindua {
                 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,
             };
         }
         catch (err) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Zindua } from "./client";
-export type { ZinduaClientOptions, ZinduaSendOptions, ZinduaSendResult, SendChannel, } from "./client";
+export type { ZinduaClientOptions, ZinduaSendContext, ZinduaSendOptions, ZinduaSendResult, 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.2",
+  "version": "1.2.3",
   "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
   "author": "Zindua",
   "license": "MIT",