@zindua/sdk 1.2.2 → 1.2.4

package/README.md

@@ -1,217 +1,350 @@
 # @zindua/sdk
 
-Official **server-side** SDK for [Zindua](https://zindua.run): one API for transactional **email** and **WhatsApp** (`POST /api/v1/send`).
+Official **server-side** SDK for [Zindua](https://zindua.run): send transactional **email** and **WhatsApp** messages with one API.
 
-| Resource | Link |
-|----------|------|
-| Website & docs | [zindua.run/developers](https://zindua.run/developers) |
-| HTTP / cURL (no SDK) | [zindua.run/developers#http](https://zindua.run/developers#http) |
-| Pricing & plans | [zindua.run/pricing](https://zindua.run/pricing) |
-| Dashboard | [zindua.run/login](https://zindua.run/login) |
+| | |
+|---|---|
+| Full API reference | [zindua.run/developers](https://zindua.run/developers) |
+| Dashboard (keys, templates, services) | [zindua.run/login](https://zindua.run/login) |
+| Pricing | [zindua.run/pricing](https://zindua.run/pricing) |
 
-Install: `npm install @zindua/sdk`
+```bash
+npm install @zindua/sdk
+```
+
+**Requirements:** Node.js 18+, run only on your **backend** (not in the browser).
 
 ---
 
-## Templates and languages
+## Quick start
+
+### 1. Create a Zindua project
+
+1. Sign in at [zindua.run/login](https://zindua.run/login).
+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`).
 
-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.
+### 2. Install and configure
+
+```bash
+npm install @zindua/sdk
+```
+
+```bash
+# .env — never commit real keys; never expose in frontend code
+ZINDUA_API_KEY=znd_live_xxxxxxxxxxxxxxxxxxxxxxxx
+```
 
-Send in a locale with the `lang` field (ISO code: `fr`, `en`, `sw`, …). If you omit `lang`, Zindua uses your project default.
+```typescript
+import { Zindua } from "@zindua/sdk";
 
-| Plan | Templates per project | Languages per template (email + WhatsApp) |
-|------|----------------------|-------------------------------------------|
-| **Free** | 5 | 3 |
-| **Pro** | 50 | 10 |
-| **Team** | 1000 | 100 |
+export const zindua = new Zindua({
+  apiKey: process.env.ZINDUA_API_KEY!,
+});
+```
 
-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.
+### 3. Send a message
 
 ```typescript
-// French version of the same template slug
+// Email (default channel)
 await zindua.send({
   to: "user@example.com",
   template: "welcome",
-  lang: "fr",
   variables: { name: "Alex" },
 });
 
-// WhatsApp: same slug, different channel + E.164 phone
+// WhatsApp — phone in E.164 with +
 await zindua.send({
   to: "+243812345678",
   channel: "whatsapp",
-  template: "otp-verification",
-  lang: "fr",
-  variables: { code: "4592", app: "MonApp" },
+  template: "otp",
+  variables: { code: "482910" },
 });
 ```
 
 ---
 
-## Requirements
+## Plans and channels
 
-Before using the SDK, set up your Zindua project in the dashboard:
+| Plan | Email API | WhatsApp | Email / month | WhatsApp OTP / month |
+|------|-----------|----------|---------------|----------------------|
+| **Free** | Yes, if a **Service** is connected on the project | Yes | 25,000 | 200 |
+| **Pro** | Yes | Yes | 160,000 | 20,000 |
+| **Team** | Yes | Yes | High volume | Unlimited |
 
-| Requirement | Required for | Where |
-|-------------|--------------|--------|
-| Zindua account | All | [Sign up / login](https://zindua.run/login) |
-| Project + API key (`znd_live_…` or `znd_test_…`) | All | Dashboard → **Projects** → your project |
-| 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** |
+On **Free**, email works through **your** connected provider (Gmail, SMTP, etc.). **Pro** and **Team** raise template counts and monthly limits. Details: [pricing](https://zindua.run/pricing).
 
-**Runtime**
+| | Free | Pro / Team |
+|---|------|------------|
+| Templates per project | 5 | 50+ |
+| Languages per template | 3 | 10+ |
 
-- **Node.js 18+** (uses native `fetch`)
-- **Server only** — do not bundle this package for the browser (see [Mobile & SPA](#mobile--spa))
+Use `znd_test_…` keys to try the API without consuming live quota (sandbox behaviour).
 
 ---
 
-## Install
+## One project or several?
 
-```bash
-npm install @zindua/sdk
-```
+| Setup | When it fits |
+|-------|----------------|
+| **One Zindua project, one API key** | One product, one sender, shared templates and quota. |
+| **Several Zindua projects, one key each** | Several clients or brands: separate templates, Gmail accounts, logs, and quotas. |
 
-```bash
-yarn add @zindua/sdk
-```
+### Several keys in one backend
 
 ```bash
-pnpm add @zindua/sdk
+ZINDUA_KEY_CLIENT_A=znd_live_aaaaaaaaaaaaaaaaaaaaaaaa
+ZINDUA_KEY_CLIENT_B=znd_live_bbbbbbbbbbbbbbbbbbbbbbbb
 ```
 
----
+```typescript
+import { Zindua } from "@zindua/sdk";
+
+const clients = {
+  clientA: new Zindua({ apiKey: process.env.ZINDUA_KEY_CLIENT_A! }),
+  clientB: new Zindua({ apiKey: process.env.ZINDUA_KEY_CLIENT_B! }),
+};
 
-## Configure
+await clients.clientA.send({
+  to: "user@example.com",
+  template: "otp",
+  variables: { code: "123456" },
+});
+```
 
-### 1. API key
+Each key only accesses **its** Zindua project (templates, service, usage).
 
-Copy your project key from the dashboard. Format: `znd_live_` + 24 characters, or `znd_test_` for test mode.
+---
 
-```bash
-# .env (example — load with dotenv or your framework)
-ZINDUA_API_KEY=znd_live_xxxxxxxxxxxxxxxxxxxxxxxx
-```
+## Framework examples
 
-The SDK does **not** read `ZINDUA_API_KEY` automatically. Pass it to the constructor explicitly.
+Use the same pattern everywhere: **your server** holds the API key; the client app calls **your** API.
 
-### 2. Base URL (optional)
+### Next.js (App Router)
 
-| Variable | Default | Notes |
-|----------|---------|--------|
-| `ZINDUA_API_BASE_URL` | `https://zindua.run/api/v1` | Used when `baseUrl` is omitted in constructor |
-| Constructor `baseUrl` | env or default | Overrides env; must be **HTTPS** in production (`http://localhost` allowed for local dev) |
+```typescript
+// lib/zindua.ts
+import { Zindua } from "@zindua/sdk";
 
-### 3. Timeout (optional)
+export const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
+```
 
-| Option | Default | Max |
-|--------|---------|-----|
-| `timeoutMs` | `30000` | `120000` |
+```typescript
+// app/api/notify/route.ts
+import { zindua } from "@/lib/zindua";
+import { NextResponse } from "next/server";
+
+export async function POST(req: Request) {
+  const { email, code } = await req.json();
+  const result = await zindua.send({
+    to: email,
+    template: "otp",
+    variables: { code },
+  });
+  return NextResponse.json(result, { status: 202 });
+}
+```
 
-### Minimal setup
+### Express
 
 ```typescript
+import express from "express";
 import { Zindua } from "@zindua/sdk";
 
-export const zindua = new Zindua({
-  apiKey: process.env.ZINDUA_API_KEY!,
-  // baseUrl: process.env.ZINDUA_API_BASE_URL, // optional
-  // timeoutMs: 30_000,
+const app = express();
+app.use(express.json());
+
+const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
+
+app.post("/api/notify", async (req, res) => {
+  try {
+    const result = await zindua.send({
+      to: req.body.email,
+      template: req.body.template ?? "otp",
+      variables: req.body.variables ?? {},
+    });
+    res.status(202).json(result);
+  } catch (err) {
+    res.status(500).json({ error: "Send failed" });
+  }
 });
 ```
 
----
+### Fastify
 
-## Usage
+```typescript
+import Fastify from "fastify";
+import { Zindua } from "@zindua/sdk";
 
-### Send email
+const zindua = new Zindua({ apiKey: process.env.ZINDUA_API_KEY! });
+const app = Fastify();
 
-```typescript
-await zindua.send({
-  to: "user@example.com",
-  template: "welcome",
-  variables: { name: "Alex" },
+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);
 });
 ```
 
-### Send WhatsApp OTP
-
-Phone numbers must be **E.164** with a leading `+` (e.g. `+243812345678`).
+### Hono
 
 ```typescript
-await zindua.send({
-  to: "+243812345678",
-  channel: "whatsapp",
-  template: "otp-verification",
-  variables: { code: "4592", app: "MyApp" },
+import { Hono } from "hono";
+import { Zindua } from "@zindua/sdk";
+
+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 result = await zindua.send({
+    to: email,
+    template: "otp",
+    variables: { code },
+  });
+  return c.json(result, 202);
 });
 ```
 
-### Optional fields (email only)
+### Mobile apps (React Native, Flutter)
+
+Do **not** embed `@zindua/sdk` or `znd_live_…` in the app. Call your backend route above from the device.
+
+---
+
+## Configuration options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `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`). |
 
 ```typescript
-await zindua.send({
-  to: "user@example.com",
-  template: "invoice",
-  lang: "fr",
-  cc: "billing@example.com",
-  replyTo: "support@example.com",
-  variables: { amount: "99" },
+const zindua = new Zindua({
+  apiKey: process.env.ZINDUA_API_KEY!,
+  baseUrl: process.env.ZINDUA_API_BASE_URL, // optional
+  timeoutMs: 45_000,
 });
 ```
 
-### Response
+---
+
+## Send options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `to` | Yes | Email address, or E.164 phone (`+243…`) for WhatsApp. |
+| `template` | Yes | Template slug from your dashboard. |
+| `channel` | No | `"email"` (default) or `"whatsapp"`. |
+| `lang` | No | `fr`, `en`, … — falls back to project default. |
+| `variables` | No | `{{placeholders}}` in the template. |
+| `cc`, `bcc`, `replyTo` | No | Email only. |
+
+---
+
+## Successful response
 
 ```typescript
 const result = await zindua.send({ /* … */ });
-// { success: true, status: "queued", logId: "…", channel: "email" | "whatsapp", … }
 ```
 
+| Field | Meaning |
+|-------|---------|
+| `success` | `true` |
+| `status` | `queued`, `processing`, or `sent` (test keys often return `sent` immediately). |
+| `logId` | Id for support / logs in the dashboard. |
+| `channel` | `email` or `whatsapp` |
+| `context` | Workspace snapshot (see below). |
+
+### `context` object
+
+The API returns metadata so you can log or debug without exposing secrets:
+
+```json
+{
+  "context": {
+    "project": { "name": "My App", "slug": "my-app" },
+    "apiKey": { "mode": "live", "suffix": "ejho" },
+    "plan": { "slug": "free", "name": "Free", "emailQuota": 25000, "emailsUsed": 12 },
+    "channels": { "email": true, "whatsapp": false }
+  }
+}
+```
+
+- **`context.apiKey.suffix`** — last 4 characters of the key (match in the dashboard).
+- **`context.plan`** — current plan and usage for the workspace linked to this key.
+- **`context.channels`** — whether email / WhatsApp is ready for this project.
+
+The full API key is **never** returned in responses.
+
 ---
 
 ## Errors
 
+Wrap sends in `try/catch` and handle `ZinduaError`:
+
 ```typescript
 import { Zindua, ZinduaError } from "@zindua/sdk";
 
 try {
-  await zindua.send({ to: "+243…", channel: "whatsapp", template: "otp-verification" });
+  await zindua.send({ to: "user@example.com", template: "otp", variables: { code: "1" } });
 } catch (e) {
   if (e instanceof ZinduaError) {
-    console.error(e.status, e.code, e.message);
-    // Platform codes may include: WHATSAPP_NOT_CONNECTED, RATE_LIMIT_EXCEEDED, …
+    console.log(e.status);  // HTTP status
+    console.log(e.code);    // machine-readable code
+    console.log(e.message); // human-readable
+    console.log(e.details); // optional: hint, context, retryAfterSec, …
   }
-  throw e;
 }
 ```
 
-`ZinduaError` never includes your API key in the message.
-
----
-
-## Security
-
-- **Server only** — throws in browser environments (`BROWSER_FORBIDDEN`).
-- **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"`.
+### Error codes
+
+| Code | HTTP | What it means | What to do |
+|------|------|---------------|------------|
+| `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`. |
+| `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**. |
+| `QUOTA_EXCEEDED` | 429 | Monthly email limit reached. | Upgrade plan or wait for reset. |
+| `WHATSAPP_NOT_AVAILABLE` | 403 | WhatsApp not on plan. | Check [pricing](https://zindua.run/pricing). |
+| `WHATSAPP_NOT_CONNECTED` | 422 | WhatsApp not linked. | Dashboard → project → **WhatsApp** → scan QR. |
+| `WHATSAPP_PAUSED` | 422 | WhatsApp session paused. | Resume in the dashboard. |
+| `WHATSAPP_QUOTA_EXCEEDED` | 429 | Monthly WhatsApp limit reached. | Upgrade or wait. |
+| `RATE_LIMIT_EXCEEDED` | 429 | Sending too fast (WhatsApp). | Wait `retryAfterSec` from `e.details`, then retry. |
+| `TEMPLATE_NOT_FOUND` | 404 | Unknown template slug. | Create template or fix slug; check `availableTemplateSlugs` in details. |
+| `TEMPLATE_NO_CONTENT` | 404 | Template has no language version. | Add content in Dashboard → Templates. |
+| `TEMPLATE_NO_WHATSAPP_BODY` | 422 | No plain text for WhatsApp. | Add a text body for that language. |
+| `QUEUE_UNAVAILABLE` | 503 | Temporary delivery queue issue. | Retry shortly; contact support if it persists. |
+| `BROWSER_FORBIDDEN` | — | SDK used in browser. | Move the call to your backend. |
+| `REQUEST_TIMEOUT` | — | Request exceeded `timeoutMs`. | Increase timeout or retry. |
+
+Many errors include a **`context`** field (same shape as success) with `plan` and `project` to help you debug.
 
 ---
 
-## Mobile & SPA
+## Best practices
 
-Never put `znd_live_` keys in React Native, Flutter, or browser code. Call your own backend; your backend uses this SDK.
-
-See [Developer docs → Quickstart](https://zindua.run/developers#setup).
+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"`.
+5. One Zindua project per client when quotas, senders, or templates must stay isolated.
 
 ---
 
-## HTTP without the SDK
-
-Any language can call the same endpoint:
+## Without the SDK (HTTP)
 
 ```bash
 curl -X POST https://zindua.run/api/v1/send \
@@ -220,34 +353,20 @@ curl -X POST https://zindua.run/api/v1/send \
   -d '{"to":"user@example.com","template":"welcome","variables":{"name":"Alex"}}'
 ```
 
-Full reference: [HTTP / cURL](https://zindua.run/developers#http).
+See [HTTP / cURL](https://zindua.run/developers#http).
 
 ---
 
-## API surface
+## API reference
 
 | Export | Description |
 |--------|-------------|
 | `Zindua` | Client class |
-| `ZinduaError` | Typed error |
+| `ZinduaError` | Error type (`status`, `code`, `message`, `details`) |
+| `ZinduaSendResult` | Success payload type |
+| `ZinduaSendContext` | Type of `result.context` |
 | `DEFAULT_API_BASE` | `https://zindua.run/api/v1` |
-| `LIMITS` | Validation limits (documented constants) |
-
----
-
-## Local development (monorepo)
-
-```bash
-cd packages/zindua-js
-npm run build
-npm test
-```
-
-From the app repo root:
-
-```bash
-npm install file:./packages/zindua-js
-```
+| `LIMITS` | Client-side validation limits |
 
 ---
 

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