@zindua/sdk 1.2.1 → 1.2.3

package/README.md

@@ -2,17 +2,50 @@
 
 Official **server-side** SDK for [Zindua](https://zindua.run): one API for transactional **email** and **WhatsApp** (`POST /api/v1/send`).
 
-**npm:** [https://www.npmjs.com/package/@zindua/sdk](https://www.npmjs.com/package/@zindua/sdk) (this URL does not change when we ship new versions)
-
 | Resource | Link |
 |----------|------|
-| npm package | [npmjs.com/package/@zindua/sdk](https://www.npmjs.com/package/@zindua/sdk) |
-| Website | [zindua.run](https://zindua.run) |
-| Developer documentation | [zindua.run/developers](https://zindua.run/developers) |
+| Website & docs | [zindua.run/developers](https://zindua.run/developers) |
 | HTTP / cURL (no SDK) | [zindua.run/developers#http](https://zindua.run/developers#http) |
-| Domain & custom sender | [zindua.run/developers#domain](https://zindua.run/developers#domain) |
+| Pricing & plans | [zindua.run/pricing](https://zindua.run/pricing) |
 | Dashboard | [zindua.run/login](https://zindua.run/login) |
 
+Install: `npm install @zindua/sdk`
+
+---
+
+## Templates and languages
+
+Create templates in the **dashboard** (one **slug** per template, e.g. `welcome`, `otp-verification`). Each template can include **email HTML** and **WhatsApp text** for the same slug.
+
+Send in a locale with the `lang` field (ISO code: `fr`, `en`, `sw`, …). If you omit `lang`, Zindua uses your project default.
+
+| Plan | Templates per project | Languages per template (email + WhatsApp) |
+|------|----------------------|-------------------------------------------|
+| **Free** | 5 | 3 |
+| **Pro** | 50 | 10 |
+| **Team** | 1000 | 100 |
+
+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
+await zindua.send({
+  to: "user@example.com",
+  template: "welcome",
+  lang: "fr",
+  variables: { name: "Alex" },
+});
+
+// WhatsApp: same slug, different channel + E.164 phone
+await zindua.send({
+  to: "+243812345678",
+  channel: "whatsapp",
+  template: "otp-verification",
+  lang: "fr",
+  variables: { code: "4592", app: "MonApp" },
+});
+```
+
 ---
 
 ## Requirements
@@ -26,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**
 
@@ -133,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
@@ -161,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).
 
 ---
 
@@ -202,13 +279,6 @@ Full reference: [HTTP / cURL](https://zindua.run/developers#http).
 
 ---
 
-## Releases and versioning
-
-- The registry page [npmjs.com/package/@zindua/sdk](https://www.npmjs.com/package/@zindua/sdk) is **permanent**.
-- Each release only updates the **version** (`1.2.0`, `1.2.1`, `1.3.0`, …) using [semver](https://semver.org/).
-- Consumers pin in `package.json`: `"@zindua/sdk": "^1.2.0"`, or run `npm update @zindua/sdk` for the latest compatible version.
-- Maintainers: bump `version` in `package.json`, sync `SDK_VERSION` in `src/client.ts`, then `npm publish --access public` from this folder (see `PUBLISHING.md`).
-
 ## Local development (monorepo)
 
 ```bash

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.1";
+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.1",
+  "version": "1.2.3",
   "description": "Official Zindua SDK for Node.js — transactional email and WhatsApp via POST /api/v1/send.",
   "author": "Zindua",
   "license": "MIT",