tokolaku-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tokolaku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# tokolaku-sdk
+
+Official TypeScript/JavaScript SDK for the Tokolaku Engine API — AI bot replies, omnichannel messaging (WhatsApp/Instagram/Messenger), and webhook verification.
+
+## Install
+
+```bash
+npm install tokolaku-sdk
+# or
+yarn add tokolaku-sdk
+```
+
+## Quickstart
+
+*Bahasa Indonesia ringkas: buat instance `Tokolaku` dengan API key, lalu panggil `botReply` untuk balasan AI atau `messages.send` untuk kirim pesan lewat channel resmi (WhatsApp/Instagram/Messenger) yang sudah terhubung.*
+
+```ts
+import { Tokolaku } from "tokolaku-sdk";
+// CommonJS: const { Tokolaku } = require("tokolaku-sdk");
+
+const tokolaku = new Tokolaku(process.env.TOKOLAKU_API_KEY!);
+// or with options: new Tokolaku({ apiKey, baseUrl, timeoutMs, maxRetries })
+
+// 1. AI bot reply for a single customer message
+const { reply, parts } = await tokolaku.botReply({
+  message: "Halo, apakah produk ini ready stock?",
+  session_id: "wa:628123456789", // keeps multi-turn context
+});
+console.log(reply);
+
+// 2. Send a text message through a connected channel
+const sent = await tokolaku.messages.send({
+  to: "628123456789",
+  text: "Terima kasih sudah menghubungi kami!",
+  channel_id: "ch_abc123",
+});
+console.log(sent.id, sent.status);
+```
+
+`messages.send` also accepts a business-initiated template message — pass `template` instead of `text` (exactly one of the two, never both):
+
+```ts
+await tokolaku.messages.send({
+  to: "628123456789",
+  template: { name: "order_update", language: "id", category: "utility" },
+  channel_id: "ch_abc123",
+});
+```
+
+## Error handling
+
+Every failed request rejects with an instance of `TokolakuAPIError` (or one of its subclasses). `status` is `null` when the request never got an HTTP response (network error, timeout); `code` is the backend's machine-readable error code when available.
+
+| Class | HTTP status | When it's thrown |
+|---|---|---|
+| `TokolakuValidationError` | 400, 422 | Invalid request params — also thrown client-side before any network call (e.g. `messages.send` with both `text` and `template`, or neither) |
+| `TokolakuAuthenticationError` | 401 | Missing or invalid API key |
+| `TokolakuInsufficientBalanceError` | 402 | Tenant balance too low to cover the charge |
+| `TokolakuPermissionError` | 403 | API key lacks permission for this action |
+| `TokolakuRateLimitError` | 429 | Rate limit exceeded |
+| `TokolakuAPIError` | any other status, or `null` | Base class — also covers network errors, timeouts, and malformed responses not mapped above |
+| `TokolakuWebhookSignatureError` | — | Webhook signature missing or invalid (does **not** extend `TokolakuAPIError`) |
+
+```ts
+import { Tokolaku, TokolakuAPIError, TokolakuInsufficientBalanceError, TokolakuRateLimitError } from "tokolaku-sdk";
+
+try {
+  await tokolaku.botReply({ message: "Halo" });
+} catch (err) {
+  if (err instanceof TokolakuInsufficientBalanceError) {
+    // top up balance, notify the tenant
+  } else if (err instanceof TokolakuRateLimitError) {
+    // back off and retry later
+  } else if (err instanceof TokolakuAPIError) {
+    console.error(err.status, err.code, err.message);
+  } else {
+    throw err; // not an SDK error
+  }
+}
+```
+
+## Retry policy
+
+The SDK retries automatically (`maxRetries`, default `2`) using exponential backoff with full jitter (base 250ms, capped at 1s; a `Retry-After` response header wins when present). The policy is **money-aware**: it only retries when a retry cannot cause a duplicate side effect.
+
+| Condition | `botReply` | `messages.send` |
+|---|---|---|
+| `429 Too Many Requests` | Retried | Retried |
+| Network error (`fetch` throws) | Retried | Retried |
+| `5xx` server error | Retried | **Not** retried |
+| Timeout (`code: "timeout"`) | **Not** retried | **Not** retried |
+| `2xx` with malformed JSON body (`code: "invalid_response"`) | **Not** retried | **Not** retried |
+
+- `botReply` has no side effect if it fails, so it retries on `429`, any `5xx`, and network errors.
+- **`messages.send` TIDAK di-retry pada timeout/5xx karena pesan mungkin sudah terkirim** — the message may already have been sent and charged even though the client never saw a successful response, and the API does not yet expose an idempotency key. It only retries on `429` and network errors (no HTTP response was ever received, so nothing could have been sent).
+- A timeout (`code: "timeout"`) is never retried on either endpoint, since it's ambiguous whether the server received/processed the request.
+- A `2xx` response with a body that fails to parse as JSON (`code: "invalid_response"`, `status: 200`) is never retried on either endpoint — the request already reached the server and had its side effect (reply generated / message sent and charged); retrying would risk a double-send or burning AI quota for nothing.
+
+## Webhooks
+
+Verify the `x-tokolaku-signature` header (`sha256=<hex>`, HMAC-SHA256 of the **raw** request body) before trusting a webhook payload. Always use the raw, unmodified request body — a re-serialized JSON string will not match the signature.
+
+```ts
+import { verifyWebhookSignature, constructEvent, TokolakuWebhookSignatureError } from "tokolaku-sdk/webhooks";
+```
+
+### Express
+
+```ts
+import express from "express";
+import { constructEvent, TokolakuWebhookSignatureError } from "tokolaku-sdk/webhooks";
+
+const app = express();
+
+app.post(
+  "/webhooks/tokolaku",
+  express.raw({ type: "application/json" }), // keep the raw Buffer — do NOT use express.json() on this route
+  (req, res) => {
+    const rawBody = req.body.toString("utf8");
+    try {
+      const { event } = constructEvent(rawBody, req.header("x-tokolaku-signature"), process.env.TOKOLAKU_WEBHOOK_SECRET!);
+      // ... handle event
+      res.json({ received: true });
+    } catch (err) {
+      if (err instanceof TokolakuWebhookSignatureError) {
+        return res.status(401).json({ error: "invalid signature" });
+      }
+      throw err;
+    }
+  },
+);
+```
+
+### Fastify
+
+```ts
+import Fastify from "fastify";
+import { constructEvent, TokolakuWebhookSignatureError } from "tokolaku-sdk/webhooks";
+
+const app = Fastify();
+
+// Capture the raw body before Fastify's default JSON parser touches it.
+app.addContentTypeParser("application/json", { parseAs: "string" }, (req, body, done) => {
+  (req as any).rawBody = body;
+  try {
+    done(null, JSON.parse(body as string));
+  } catch (err) {
+    done(err as Error);
+  }
+});
+
+app.post("/webhooks/tokolaku", async (req, reply) => {
+  try {
+    const { event } = constructEvent((req as any).rawBody, req.headers["x-tokolaku-signature"] as string, process.env.TOKOLAKU_WEBHOOK_SECRET!);
+    // ... handle event
+    return reply.send({ received: true });
+  } catch (err) {
+    if (err instanceof TokolakuWebhookSignatureError) {
+      return reply.code(401).send({ error: "invalid signature" });
+    }
+    throw err;
+  }
+});
+```
+
+## Requirements
+
+- Node.js ≥ 18
+
+## License
+
+MIT
+
+## Docs
+
+Full API reference: [https://tokolaku.id/api-docs](https://tokolaku.id/api-docs)

package/dist/chunk-6YQXWMOC.js

@@ -0,0 +1,61 @@
+// src/errors.ts
+var TokolakuAPIError = class extends Error {
+  status;
+  code;
+  constructor(message, opts) {
+    super(message);
+    this.name = new.target.name;
+    this.status = opts.status;
+    this.code = opts.code;
+  }
+};
+var TokolakuAuthenticationError = class extends TokolakuAPIError {
+};
+var TokolakuInsufficientBalanceError = class extends TokolakuAPIError {
+};
+var TokolakuPermissionError = class extends TokolakuAPIError {
+};
+var TokolakuRateLimitError = class extends TokolakuAPIError {
+};
+var TokolakuValidationError = class extends TokolakuAPIError {
+};
+var TokolakuWebhookSignatureError = class extends Error {
+  constructor(message = "Signature webhook tidak valid") {
+    super(message);
+    this.name = "TokolakuWebhookSignatureError";
+  }
+};
+var STATUS_CLASS = {
+  400: TokolakuValidationError,
+  401: TokolakuAuthenticationError,
+  402: TokolakuInsufficientBalanceError,
+  403: TokolakuPermissionError,
+  422: TokolakuValidationError,
+  429: TokolakuRateLimitError
+};
+function mapResponseError(status, bodyText) {
+  let code = null;
+  let message = bodyText ? bodyText.slice(0, 500) : `HTTP ${status}`;
+  try {
+    const parsed = JSON.parse(bodyText);
+    if (parsed?.error) {
+      code = parsed.error.code ?? null;
+      message = parsed.error.message ?? message;
+    }
+  } catch {
+  }
+  const Cls = STATUS_CLASS[status] ?? TokolakuAPIError;
+  return new Cls(message, { status, code });
+}
+
+export {
+  TokolakuAPIError,
+  TokolakuAuthenticationError,
+  TokolakuInsufficientBalanceError,
+  TokolakuPermissionError,
+  TokolakuRateLimitError,
+  TokolakuValidationError,
+  TokolakuWebhookSignatureError,
+  mapResponseError
+};
+//# sourceMappingURL=chunk-6YQXWMOC.js.map

package/dist/chunk-6YQXWMOC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/** Base error semua kegagalan API. `status` null = kegagalan sebelum ada\n *  respons HTTP (network/timeout). `code` = kode envelope BE, mis.\n *  \"insufficient_balance\"; null bila body bukan JSON envelope. */\nexport class TokolakuAPIError extends Error {\n  readonly status: number | null;\n  readonly code: string | null;\n  constructor(message: string, opts: { status: number | null; code: string | null }) {\n    super(message);\n    this.name = new.target.name;\n    this.status = opts.status;\n    this.code = opts.code;\n  }\n}\n\nexport class TokolakuAuthenticationError extends TokolakuAPIError {}      // 401\nexport class TokolakuInsufficientBalanceError extends TokolakuAPIError {} // 402\nexport class TokolakuPermissionError extends TokolakuAPIError {}          // 403\nexport class TokolakuRateLimitError extends TokolakuAPIError {}           // 429\nexport class TokolakuValidationError extends TokolakuAPIError {}          // 400/422 + validasi klien\n\nexport class TokolakuWebhookSignatureError extends Error {\n  constructor(message = \"Signature webhook tidak valid\") {\n    super(message);\n    this.name = \"TokolakuWebhookSignatureError\";\n  }\n}\n\nconst STATUS_CLASS: Record<number, new (m: string, o: { status: number | null; code: string | null }) => TokolakuAPIError> = {\n  400: TokolakuValidationError,\n  401: TokolakuAuthenticationError,\n  402: TokolakuInsufficientBalanceError,\n  403: TokolakuPermissionError,\n  422: TokolakuValidationError,\n  429: TokolakuRateLimitError,\n};\n\n/** Terjemahkan respons non-2xx jadi error class. Envelope BE:\n *  `{ error: { code, message } }`. Body non-JSON dipotong 500 char. */\nexport function mapResponseError(status: number, bodyText: string): TokolakuAPIError {\n  let code: string | null = null;\n  let message = bodyText ? bodyText.slice(0, 500) : `HTTP ${status}`;\n  try {\n    const parsed = JSON.parse(bodyText) as { error?: { code?: string; message?: string } };\n    if (parsed?.error) {\n      code = parsed.error.code ?? null;\n      message = parsed.error.message ?? message;\n    }\n  } catch {\n    /* non-JSON — pakai default */\n  }\n  const Cls = STATUS_CLASS[status] ?? TokolakuAPIError;\n  return new Cls(message, { status, code });\n}\n"],"mappings":";AAGO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EACjC;AAAA,EACA;AAAA,EACT,YAAY,SAAiB,MAAsD;AACjF,UAAM,OAAO;AACb,SAAK,OAAO,WAAW;AACvB,SAAK,SAAS,KAAK;AACnB,SAAK,OAAO,KAAK;AAAA,EACnB;AACF;AAEO,IAAM,8BAAN,cAA0C,iBAAiB;AAAC;AAC5D,IAAM,mCAAN,cAA+C,iBAAiB;AAAC;AACjE,IAAM,0BAAN,cAAsC,iBAAiB;AAAC;AACxD,IAAM,yBAAN,cAAqC,iBAAiB;AAAC;AACvD,IAAM,0BAAN,cAAsC,iBAAiB;AAAC;AAExD,IAAM,gCAAN,cAA4C,MAAM;AAAA,EACvD,YAAY,UAAU,iCAAiC;AACrD,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAM,eAAuH;AAAA,EAC3H,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AACP;AAIO,SAAS,iBAAiB,QAAgB,UAAoC;AACnF,MAAI,OAAsB;AAC1B,MAAI,UAAU,WAAW,SAAS,MAAM,GAAG,GAAG,IAAI,QAAQ,MAAM;AAChE,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,QAAQ;AAClC,QAAI,QAAQ,OAAO;AACjB,aAAO,OAAO,MAAM,QAAQ;AAC5B,gBAAU,OAAO,MAAM,WAAW;AAAA,IACpC;AAAA,EACF,QAAQ;AAAA,EAER;AACA,QAAM,MAAM,aAAa,MAAM,KAAK;AACpC,SAAO,IAAI,IAAI,SAAS,EAAE,QAAQ,KAAK,CAAC;AAC1C;","names":[]}

package/dist/errors-PooMi-0n.d.cts

@@ -0,0 +1,26 @@
+/** Base error semua kegagalan API. `status` null = kegagalan sebelum ada
+ *  respons HTTP (network/timeout). `code` = kode envelope BE, mis.
+ *  "insufficient_balance"; null bila body bukan JSON envelope. */
+declare class TokolakuAPIError extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    constructor(message: string, opts: {
+        status: number | null;
+        code: string | null;
+    });
+}
+declare class TokolakuAuthenticationError extends TokolakuAPIError {
+}
+declare class TokolakuInsufficientBalanceError extends TokolakuAPIError {
+}
+declare class TokolakuPermissionError extends TokolakuAPIError {
+}
+declare class TokolakuRateLimitError extends TokolakuAPIError {
+}
+declare class TokolakuValidationError extends TokolakuAPIError {
+}
+declare class TokolakuWebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+export { TokolakuAPIError as T, TokolakuAuthenticationError as a, TokolakuInsufficientBalanceError as b, TokolakuPermissionError as c, TokolakuRateLimitError as d, TokolakuValidationError as e, TokolakuWebhookSignatureError as f };

package/dist/errors-PooMi-0n.d.ts

@@ -0,0 +1,26 @@
+/** Base error semua kegagalan API. `status` null = kegagalan sebelum ada
+ *  respons HTTP (network/timeout). `code` = kode envelope BE, mis.
+ *  "insufficient_balance"; null bila body bukan JSON envelope. */
+declare class TokolakuAPIError extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    constructor(message: string, opts: {
+        status: number | null;
+        code: string | null;
+    });
+}
+declare class TokolakuAuthenticationError extends TokolakuAPIError {
+}
+declare class TokolakuInsufficientBalanceError extends TokolakuAPIError {
+}
+declare class TokolakuPermissionError extends TokolakuAPIError {
+}
+declare class TokolakuRateLimitError extends TokolakuAPIError {
+}
+declare class TokolakuValidationError extends TokolakuAPIError {
+}
+declare class TokolakuWebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+
+export { TokolakuAPIError as T, TokolakuAuthenticationError as a, TokolakuInsufficientBalanceError as b, TokolakuPermissionError as c, TokolakuRateLimitError as d, TokolakuValidationError as e, TokolakuWebhookSignatureError as f };

package/dist/index.cjs

@@ -0,0 +1,199 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Tokolaku: () => Tokolaku,
+  TokolakuAPIError: () => TokolakuAPIError,
+  TokolakuAuthenticationError: () => TokolakuAuthenticationError,
+  TokolakuInsufficientBalanceError: () => TokolakuInsufficientBalanceError,
+  TokolakuPermissionError: () => TokolakuPermissionError,
+  TokolakuRateLimitError: () => TokolakuRateLimitError,
+  TokolakuValidationError: () => TokolakuValidationError,
+  TokolakuWebhookSignatureError: () => TokolakuWebhookSignatureError,
+  default: () => Tokolaku
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+var TokolakuAPIError = class extends Error {
+  status;
+  code;
+  constructor(message, opts) {
+    super(message);
+    this.name = new.target.name;
+    this.status = opts.status;
+    this.code = opts.code;
+  }
+};
+var TokolakuAuthenticationError = class extends TokolakuAPIError {
+};
+var TokolakuInsufficientBalanceError = class extends TokolakuAPIError {
+};
+var TokolakuPermissionError = class extends TokolakuAPIError {
+};
+var TokolakuRateLimitError = class extends TokolakuAPIError {
+};
+var TokolakuValidationError = class extends TokolakuAPIError {
+};
+var TokolakuWebhookSignatureError = class extends Error {
+  constructor(message = "Signature webhook tidak valid") {
+    super(message);
+    this.name = "TokolakuWebhookSignatureError";
+  }
+};
+var STATUS_CLASS = {
+  400: TokolakuValidationError,
+  401: TokolakuAuthenticationError,
+  402: TokolakuInsufficientBalanceError,
+  403: TokolakuPermissionError,
+  422: TokolakuValidationError,
+  429: TokolakuRateLimitError
+};
+function mapResponseError(status, bodyText) {
+  let code = null;
+  let message = bodyText ? bodyText.slice(0, 500) : `HTTP ${status}`;
+  try {
+    const parsed = JSON.parse(bodyText);
+    if (parsed?.error) {
+      code = parsed.error.code ?? null;
+      message = parsed.error.message ?? message;
+    }
+  } catch {
+  }
+  const Cls = STATUS_CLASS[status] ?? TokolakuAPIError;
+  return new Cls(message, { status, code });
+}
+
+// src/retry.ts
+function shouldRetry(policy, error) {
+  if (error.code === "timeout") return false;
+  if (error.status === 429) return true;
+  if (error.code === "network_error") return true;
+  if (policy === "botReply" && error.status !== null && error.status >= 500) return true;
+  return false;
+}
+function retryDelayMs(attempt, retryAfterSec) {
+  if (retryAfterSec != null && Number.isFinite(retryAfterSec)) return Math.max(0, retryAfterSec * 1e3);
+  const cap = Math.min(1e3, 250 * 2 ** attempt);
+  return Math.round(cap * (0.5 + Math.random() * 0.5));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.tokolaku.id";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var Tokolaku = class {
+  #apiKey;
+  #baseUrl;
+  #timeoutMs;
+  #maxRetries;
+  #fetch;
+  constructor(apiKeyOrOptions) {
+    const o = typeof apiKeyOrOptions === "string" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions;
+    if (!o.apiKey) throw new TokolakuValidationError("apiKey wajib diisi", { status: null, code: "missing_api_key" });
+    this.#apiKey = o.apiKey;
+    this.#baseUrl = (o.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#maxRetries = o.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#fetch = o.fetchImpl ?? globalThis.fetch;
+  }
+  /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */
+  async botReply(params) {
+    return this.#request("/api/v1/bot/reply", params, "botReply");
+  }
+  messages = {
+    /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).
+     *  `type` diinferensi: field `text` → "text", field `template` → "template". */
+    send: async (params) => {
+      const hasText = "text" in params && params.text != null;
+      const hasTemplate = "template" in params && params.template != null;
+      if (hasText === hasTemplate) {
+        throw new TokolakuValidationError(
+          "Isi tepat satu: `text` (pesan sesi) ATAU `template` (business-initiated)",
+          { status: null, code: "invalid_params" }
+        );
+      }
+      const body = { ...params, type: hasText ? "text" : "template" };
+      return this.#request("/api/v1/messages", body, "messages");
+    }
+  };
+  async #request(path, body, policy) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+      let retryAfterSec = null;
+      try {
+        return await this.#once(path, body, (v) => {
+          retryAfterSec = v;
+        });
+      } catch (e) {
+        const err = e instanceof TokolakuAPIError ? e : new TokolakuAPIError(String(e), { status: null, code: "network_error" });
+        lastError = err;
+        if (attempt >= this.#maxRetries || !shouldRetry(policy, err)) throw err;
+        await new Promise((r) => setTimeout(r, retryDelayMs(attempt, retryAfterSec)));
+      }
+    }
+    throw lastError;
+  }
+  async #once(path, body, onRetryAfter) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+    try {
+      const res = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method: "POST",
+        headers: { "authorization": `Bearer ${this.#apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      const text = await res.text();
+      if (!res.ok) {
+        const ra = res.headers.get("retry-after");
+        onRetryAfter(ra != null && /^\d+$/.test(ra) ? Number(ra) : null);
+        throw mapResponseError(res.status, text);
+      }
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new TokolakuAPIError("Respons server bukan JSON valid", { status: res.status, code: "invalid_response" });
+      }
+    } catch (e) {
+      if (e instanceof TokolakuAPIError) throw e;
+      if (e instanceof Error && e.name === "AbortError") {
+        throw new TokolakuAPIError(`Timeout setelah ${this.#timeoutMs}ms`, { status: null, code: "timeout" });
+      }
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new TokolakuAPIError(`Network error: ${msg}`, { status: null, code: "network_error" });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tokolaku,
+  TokolakuAPIError,
+  TokolakuAuthenticationError,
+  TokolakuInsufficientBalanceError,
+  TokolakuPermissionError,
+  TokolakuRateLimitError,
+  TokolakuValidationError,
+  TokolakuWebhookSignatureError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/retry.ts","../src/client.ts"],"sourcesContent":["// src/index.ts\nexport { Tokolaku } from \"./client.js\";\nexport { Tokolaku as default } from \"./client.js\";\nexport {\n  TokolakuAPIError,\n  TokolakuAuthenticationError,\n  TokolakuInsufficientBalanceError,\n  TokolakuPermissionError,\n  TokolakuRateLimitError,\n  TokolakuValidationError,\n  TokolakuWebhookSignatureError,\n} from \"./errors.js\";\nexport type {\n  TokolakuOptions,\n  BotReplyParams, BotReplyResponse,\n  SendTextParams, SendTemplateParams, SendMessageParams, SendMessageResponse,\n} from \"./types.js\";\n","/** Base error semua kegagalan API. `status` null = kegagalan sebelum ada\n *  respons HTTP (network/timeout). `code` = kode envelope BE, mis.\n *  \"insufficient_balance\"; null bila body bukan JSON envelope. */\nexport class TokolakuAPIError extends Error {\n  readonly status: number | null;\n  readonly code: string | null;\n  constructor(message: string, opts: { status: number | null; code: string | null }) {\n    super(message);\n    this.name = new.target.name;\n    this.status = opts.status;\n    this.code = opts.code;\n  }\n}\n\nexport class TokolakuAuthenticationError extends TokolakuAPIError {}      // 401\nexport class TokolakuInsufficientBalanceError extends TokolakuAPIError {} // 402\nexport class TokolakuPermissionError extends TokolakuAPIError {}          // 403\nexport class TokolakuRateLimitError extends TokolakuAPIError {}           // 429\nexport class TokolakuValidationError extends TokolakuAPIError {}          // 400/422 + validasi klien\n\nexport class TokolakuWebhookSignatureError extends Error {\n  constructor(message = \"Signature webhook tidak valid\") {\n    super(message);\n    this.name = \"TokolakuWebhookSignatureError\";\n  }\n}\n\nconst STATUS_CLASS: Record<number, new (m: string, o: { status: number | null; code: string | null }) => TokolakuAPIError> = {\n  400: TokolakuValidationError,\n  401: TokolakuAuthenticationError,\n  402: TokolakuInsufficientBalanceError,\n  403: TokolakuPermissionError,\n  422: TokolakuValidationError,\n  429: TokolakuRateLimitError,\n};\n\n/** Terjemahkan respons non-2xx jadi error class. Envelope BE:\n *  `{ error: { code, message } }`. Body non-JSON dipotong 500 char. */\nexport function mapResponseError(status: number, bodyText: string): TokolakuAPIError {\n  let code: string | null = null;\n  let message = bodyText ? bodyText.slice(0, 500) : `HTTP ${status}`;\n  try {\n    const parsed = JSON.parse(bodyText) as { error?: { code?: string; message?: string } };\n    if (parsed?.error) {\n      code = parsed.error.code ?? null;\n      message = parsed.error.message ?? message;\n    }\n  } catch {\n    /* non-JSON — pakai default */\n  }\n  const Cls = STATUS_CLASS[status] ?? TokolakuAPIError;\n  return new Cls(message, { status, code });\n}\n","import { TokolakuAPIError } from \"./errors.js\";\n\nexport type RetryPolicy = \"botReply\" | \"messages\";\n\n/** Retry uang-sadar:\n *  - botReply: 429, 5xx, network error (tanpa efek samping bila gagal).\n *  - messages: HANYA 429 + network TypeError (pesan mungkin sudah terkirim\n *    & tercharge pada timeout/5xx — API belum punya idempotency key).\n *  - timeout (code \"timeout\") TIDAK pernah di-retry. */\nexport function shouldRetry(policy: RetryPolicy, error: TokolakuAPIError): boolean {\n  if (error.code === \"timeout\") return false;\n  if (error.status === 429) return true;\n  // \"invalid_response\" (200 OK tapi body JSON rusak) SENGAJA tidak match rule apa pun di\n  // bawah ini — efek samping server sudah terjadi, jadi non-retryable untuk kedua policy.\n  if (error.code === \"network_error\") return true;\n  if (policy === \"botReply\" && error.status !== null && error.status >= 500) return true;\n  return false;\n}\n\n/** Exponential backoff + full jitter, base 250ms cap 1s; Retry-After menang. */\nexport function retryDelayMs(attempt: number, retryAfterSec: number | null): number {\n  if (retryAfterSec != null && Number.isFinite(retryAfterSec)) return Math.max(0, retryAfterSec * 1000);\n  const cap = Math.min(1000, 250 * 2 ** attempt);\n  return Math.round(cap * (0.5 + Math.random() * 0.5));\n}\n","// src/client.ts\nimport { mapResponseError, TokolakuAPIError, TokolakuValidationError } from \"./errors.js\";\nimport { shouldRetry, retryDelayMs, type RetryPolicy } from \"./retry.js\";\nimport type {\n  BotReplyParams, BotReplyResponse, SendMessageParams, SendMessageResponse, TokolakuOptions,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.tokolaku.id\";\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_MAX_RETRIES = 2;\n\nexport class Tokolaku {\n  readonly #apiKey: string;\n  readonly #baseUrl: string;\n  readonly #timeoutMs: number;\n  readonly #maxRetries: number;\n  readonly #fetch: typeof fetch;\n\n  constructor(apiKeyOrOptions: string | TokolakuOptions) {\n    const o: TokolakuOptions =\n      typeof apiKeyOrOptions === \"string\" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions;\n    if (!o.apiKey) throw new TokolakuValidationError(\"apiKey wajib diisi\", { status: null, code: \"missing_api_key\" });\n    this.#apiKey = o.apiKey;\n    this.#baseUrl = (o.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.#timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.#maxRetries = o.maxRetries ?? DEFAULT_MAX_RETRIES;\n    this.#fetch = o.fetchImpl ?? globalThis.fetch;\n  }\n\n  /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */\n  async botReply(params: BotReplyParams): Promise<BotReplyResponse> {\n    return this.#request<BotReplyResponse>(\"/api/v1/bot/reply\", params, \"botReply\");\n  }\n\n  readonly messages = {\n    /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).\n     *  `type` diinferensi: field `text` → \"text\", field `template` → \"template\". */\n    send: async (params: SendMessageParams): Promise<SendMessageResponse> => {\n      const hasText = \"text\" in params && params.text != null;\n      const hasTemplate = \"template\" in params && (params as { template?: unknown }).template != null;\n      if (hasText === hasTemplate) {\n        throw new TokolakuValidationError(\n          \"Isi tepat satu: `text` (pesan sesi) ATAU `template` (business-initiated)\",\n          { status: null, code: \"invalid_params\" },\n        );\n      }\n      const body = { ...params, type: hasText ? \"text\" : \"template\" };\n      return this.#request<SendMessageResponse>(\"/api/v1/messages\", body, \"messages\");\n    },\n  };\n\n  async #request<T>(path: string, body: unknown, policy: RetryPolicy): Promise<T> {\n    let lastError: TokolakuAPIError | null = null;\n    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {\n      let retryAfterSec: number | null = null;\n      try {\n        return await this.#once<T>(path, body, (v) => { retryAfterSec = v; });\n      } catch (e) {\n        // defensif: #once selalu melempar TokolakuAPIError; cabang else = jaring pengaman\n        const err = e instanceof TokolakuAPIError\n          ? e\n          : new TokolakuAPIError(String(e), { status: null, code: \"network_error\" });\n        lastError = err;\n        if (attempt >= this.#maxRetries || !shouldRetry(policy, err)) throw err;\n        await new Promise((r) => setTimeout(r, retryDelayMs(attempt, retryAfterSec)));\n      }\n    }\n    throw lastError!;\n  }\n\n  async #once<T>(path: string, body: unknown, onRetryAfter: (sec: number | null) => void): Promise<T> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.#timeoutMs);\n    try {\n      const res = await this.#fetch(`${this.#baseUrl}${path}`, {\n        method: \"POST\",\n        headers: { \"authorization\": `Bearer ${this.#apiKey}`, \"content-type\": \"application/json\" },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n      const text = await res.text();\n      if (!res.ok) {\n        const ra = res.headers.get(\"retry-after\");\n        onRetryAfter(ra != null && /^\\d+$/.test(ra) ? Number(ra) : null);\n        throw mapResponseError(res.status, text);\n      }\n      try {\n        return JSON.parse(text) as T;\n      } catch {\n        // Respons HTTP sudah diterima (efek samping server, mis. pesan terkirim &\n        // tercharge, SUDAH terjadi) — parse gagal BUKAN network error & TIDAK boleh di-retry.\n        throw new TokolakuAPIError(\"Respons server bukan JSON valid\", { status: res.status, code: \"invalid_response\" });\n      }\n    } catch (e) {\n      if (e instanceof TokolakuAPIError) throw e;\n      if (e instanceof Error && e.name === \"AbortError\") {\n        throw new TokolakuAPIError(`Timeout setelah ${this.#timeoutMs}ms`, { status: null, code: \"timeout\" });\n      }\n      const msg = e instanceof Error ? e.message : String(e);\n      throw new TokolakuAPIError(`Network error: ${msg}`, { status: null, code: \"network_error\" });\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+export { T as TokolakuAPIError, a as TokolakuAuthenticationError, b as TokolakuInsufficientBalanceError, c as TokolakuPermissionError, d as TokolakuRateLimitError, e as TokolakuValidationError, f as TokolakuWebhookSignatureError } from './errors-PooMi-0n.cjs';
+
+type TokolakuOptions = {
+    apiKey: string;
+    /** Default "https://api.tokolaku.id" */
+    baseUrl?: string;
+    /** Default 30_000 ms */
+    timeoutMs?: number;
+    /** Default 2 — lihat kebijakan retry per endpoint di README */
+    maxRetries?: number;
+    /** Default globalThis.fetch — untuk testing/runtime custom */
+    fetchImpl?: typeof fetch;
+};
+type BotReplyParams = {
+    /** Pesan pelanggan, 1..4000 char */
+    message: string;
+    /** ID sesi percakapan (≤120 char) — jaga konteks multi-turn */
+    session_id?: string;
+    history?: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+};
+type BotReplyResponse = {
+    reply: string;
+    parts: string[];
+};
+type SendTextParams = {
+    to: string;
+    text: string;
+    channel_id?: string;
+};
+type SendTemplateParams = {
+    to: string;
+    template: {
+        name: string;
+        language: string;
+        category: "marketing" | "utility" | "authentication";
+        components?: unknown[];
+    };
+    channel_id?: string;
+    /** ISO-2, default "ID" di server */
+    country_code?: string;
+};
+type SendMessageParams = SendTextParams | SendTemplateParams;
+type SendMessageResponse = {
+    id: string;
+    channel_id: string;
+    to: string;
+    type: "text" | "template";
+    status: "sent";
+    provider_message_id: string | null;
+    charged_idr: number;
+};
+
+declare class Tokolaku {
+    #private;
+    constructor(apiKeyOrOptions: string | TokolakuOptions);
+    /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */
+    botReply(params: BotReplyParams): Promise<BotReplyResponse>;
+    readonly messages: {
+        /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).
+         *  `type` diinferensi: field `text` → "text", field `template` → "template". */
+        send: (params: SendMessageParams) => Promise<SendMessageResponse>;
+    };
+}
+
+export { type BotReplyParams, type BotReplyResponse, type SendMessageParams, type SendMessageResponse, type SendTemplateParams, type SendTextParams, Tokolaku, type TokolakuOptions, Tokolaku as default };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+export { T as TokolakuAPIError, a as TokolakuAuthenticationError, b as TokolakuInsufficientBalanceError, c as TokolakuPermissionError, d as TokolakuRateLimitError, e as TokolakuValidationError, f as TokolakuWebhookSignatureError } from './errors-PooMi-0n.js';
+
+type TokolakuOptions = {
+    apiKey: string;
+    /** Default "https://api.tokolaku.id" */
+    baseUrl?: string;
+    /** Default 30_000 ms */
+    timeoutMs?: number;
+    /** Default 2 — lihat kebijakan retry per endpoint di README */
+    maxRetries?: number;
+    /** Default globalThis.fetch — untuk testing/runtime custom */
+    fetchImpl?: typeof fetch;
+};
+type BotReplyParams = {
+    /** Pesan pelanggan, 1..4000 char */
+    message: string;
+    /** ID sesi percakapan (≤120 char) — jaga konteks multi-turn */
+    session_id?: string;
+    history?: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+};
+type BotReplyResponse = {
+    reply: string;
+    parts: string[];
+};
+type SendTextParams = {
+    to: string;
+    text: string;
+    channel_id?: string;
+};
+type SendTemplateParams = {
+    to: string;
+    template: {
+        name: string;
+        language: string;
+        category: "marketing" | "utility" | "authentication";
+        components?: unknown[];
+    };
+    channel_id?: string;
+    /** ISO-2, default "ID" di server */
+    country_code?: string;
+};
+type SendMessageParams = SendTextParams | SendTemplateParams;
+type SendMessageResponse = {
+    id: string;
+    channel_id: string;
+    to: string;
+    type: "text" | "template";
+    status: "sent";
+    provider_message_id: string | null;
+    charged_idr: number;
+};
+
+declare class Tokolaku {
+    #private;
+    constructor(apiKeyOrOptions: string | TokolakuOptions);
+    /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */
+    botReply(params: BotReplyParams): Promise<BotReplyResponse>;
+    readonly messages: {
+        /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).
+         *  `type` diinferensi: field `text` → "text", field `template` → "template". */
+        send: (params: SendMessageParams) => Promise<SendMessageResponse>;
+    };
+}
+
+export { type BotReplyParams, type BotReplyResponse, type SendMessageParams, type SendMessageResponse, type SendTemplateParams, type SendTextParams, Tokolaku, type TokolakuOptions, Tokolaku as default };

package/dist/index.js

@@ -0,0 +1,126 @@
+import {
+  TokolakuAPIError,
+  TokolakuAuthenticationError,
+  TokolakuInsufficientBalanceError,
+  TokolakuPermissionError,
+  TokolakuRateLimitError,
+  TokolakuValidationError,
+  TokolakuWebhookSignatureError,
+  mapResponseError
+} from "./chunk-6YQXWMOC.js";
+
+// src/retry.ts
+function shouldRetry(policy, error) {
+  if (error.code === "timeout") return false;
+  if (error.status === 429) return true;
+  if (error.code === "network_error") return true;
+  if (policy === "botReply" && error.status !== null && error.status >= 500) return true;
+  return false;
+}
+function retryDelayMs(attempt, retryAfterSec) {
+  if (retryAfterSec != null && Number.isFinite(retryAfterSec)) return Math.max(0, retryAfterSec * 1e3);
+  const cap = Math.min(1e3, 250 * 2 ** attempt);
+  return Math.round(cap * (0.5 + Math.random() * 0.5));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.tokolaku.id";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var Tokolaku = class {
+  #apiKey;
+  #baseUrl;
+  #timeoutMs;
+  #maxRetries;
+  #fetch;
+  constructor(apiKeyOrOptions) {
+    const o = typeof apiKeyOrOptions === "string" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions;
+    if (!o.apiKey) throw new TokolakuValidationError("apiKey wajib diisi", { status: null, code: "missing_api_key" });
+    this.#apiKey = o.apiKey;
+    this.#baseUrl = (o.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#maxRetries = o.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#fetch = o.fetchImpl ?? globalThis.fetch;
+  }
+  /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */
+  async botReply(params) {
+    return this.#request("/api/v1/bot/reply", params, "botReply");
+  }
+  messages = {
+    /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).
+     *  `type` diinferensi: field `text` → "text", field `template` → "template". */
+    send: async (params) => {
+      const hasText = "text" in params && params.text != null;
+      const hasTemplate = "template" in params && params.template != null;
+      if (hasText === hasTemplate) {
+        throw new TokolakuValidationError(
+          "Isi tepat satu: `text` (pesan sesi) ATAU `template` (business-initiated)",
+          { status: null, code: "invalid_params" }
+        );
+      }
+      const body = { ...params, type: hasText ? "text" : "template" };
+      return this.#request("/api/v1/messages", body, "messages");
+    }
+  };
+  async #request(path, body, policy) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+      let retryAfterSec = null;
+      try {
+        return await this.#once(path, body, (v) => {
+          retryAfterSec = v;
+        });
+      } catch (e) {
+        const err = e instanceof TokolakuAPIError ? e : new TokolakuAPIError(String(e), { status: null, code: "network_error" });
+        lastError = err;
+        if (attempt >= this.#maxRetries || !shouldRetry(policy, err)) throw err;
+        await new Promise((r) => setTimeout(r, retryDelayMs(attempt, retryAfterSec)));
+      }
+    }
+    throw lastError;
+  }
+  async #once(path, body, onRetryAfter) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+    try {
+      const res = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method: "POST",
+        headers: { "authorization": `Bearer ${this.#apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      const text = await res.text();
+      if (!res.ok) {
+        const ra = res.headers.get("retry-after");
+        onRetryAfter(ra != null && /^\d+$/.test(ra) ? Number(ra) : null);
+        throw mapResponseError(res.status, text);
+      }
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new TokolakuAPIError("Respons server bukan JSON valid", { status: res.status, code: "invalid_response" });
+      }
+    } catch (e) {
+      if (e instanceof TokolakuAPIError) throw e;
+      if (e instanceof Error && e.name === "AbortError") {
+        throw new TokolakuAPIError(`Timeout setelah ${this.#timeoutMs}ms`, { status: null, code: "timeout" });
+      }
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new TokolakuAPIError(`Network error: ${msg}`, { status: null, code: "network_error" });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  Tokolaku,
+  TokolakuAPIError,
+  TokolakuAuthenticationError,
+  TokolakuInsufficientBalanceError,
+  TokolakuPermissionError,
+  TokolakuRateLimitError,
+  TokolakuValidationError,
+  TokolakuWebhookSignatureError,
+  Tokolaku as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retry.ts","../src/client.ts"],"sourcesContent":["import { TokolakuAPIError } from \"./errors.js\";\n\nexport type RetryPolicy = \"botReply\" | \"messages\";\n\n/** Retry uang-sadar:\n *  - botReply: 429, 5xx, network error (tanpa efek samping bila gagal).\n *  - messages: HANYA 429 + network TypeError (pesan mungkin sudah terkirim\n *    & tercharge pada timeout/5xx — API belum punya idempotency key).\n *  - timeout (code \"timeout\") TIDAK pernah di-retry. */\nexport function shouldRetry(policy: RetryPolicy, error: TokolakuAPIError): boolean {\n  if (error.code === \"timeout\") return false;\n  if (error.status === 429) return true;\n  // \"invalid_response\" (200 OK tapi body JSON rusak) SENGAJA tidak match rule apa pun di\n  // bawah ini — efek samping server sudah terjadi, jadi non-retryable untuk kedua policy.\n  if (error.code === \"network_error\") return true;\n  if (policy === \"botReply\" && error.status !== null && error.status >= 500) return true;\n  return false;\n}\n\n/** Exponential backoff + full jitter, base 250ms cap 1s; Retry-After menang. */\nexport function retryDelayMs(attempt: number, retryAfterSec: number | null): number {\n  if (retryAfterSec != null && Number.isFinite(retryAfterSec)) return Math.max(0, retryAfterSec * 1000);\n  const cap = Math.min(1000, 250 * 2 ** attempt);\n  return Math.round(cap * (0.5 + Math.random() * 0.5));\n}\n","// src/client.ts\nimport { mapResponseError, TokolakuAPIError, TokolakuValidationError } from \"./errors.js\";\nimport { shouldRetry, retryDelayMs, type RetryPolicy } from \"./retry.js\";\nimport type {\n  BotReplyParams, BotReplyResponse, SendMessageParams, SendMessageResponse, TokolakuOptions,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.tokolaku.id\";\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_MAX_RETRIES = 2;\n\nexport class Tokolaku {\n  readonly #apiKey: string;\n  readonly #baseUrl: string;\n  readonly #timeoutMs: number;\n  readonly #maxRetries: number;\n  readonly #fetch: typeof fetch;\n\n  constructor(apiKeyOrOptions: string | TokolakuOptions) {\n    const o: TokolakuOptions =\n      typeof apiKeyOrOptions === \"string\" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions;\n    if (!o.apiKey) throw new TokolakuValidationError(\"apiKey wajib diisi\", { status: null, code: \"missing_api_key\" });\n    this.#apiKey = o.apiKey;\n    this.#baseUrl = (o.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.#timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.#maxRetries = o.maxRetries ?? DEFAULT_MAX_RETRIES;\n    this.#fetch = o.fetchImpl ?? globalThis.fetch;\n  }\n\n  /** Balasan AI bot tenant untuk satu pesan pelanggan (POST /api/v1/bot/reply). */\n  async botReply(params: BotReplyParams): Promise<BotReplyResponse> {\n    return this.#request<BotReplyResponse>(\"/api/v1/bot/reply\", params, \"botReply\");\n  }\n\n  readonly messages = {\n    /** Kirim pesan text/template via channel resmi (POST /api/v1/messages).\n     *  `type` diinferensi: field `text` → \"text\", field `template` → \"template\". */\n    send: async (params: SendMessageParams): Promise<SendMessageResponse> => {\n      const hasText = \"text\" in params && params.text != null;\n      const hasTemplate = \"template\" in params && (params as { template?: unknown }).template != null;\n      if (hasText === hasTemplate) {\n        throw new TokolakuValidationError(\n          \"Isi tepat satu: `text` (pesan sesi) ATAU `template` (business-initiated)\",\n          { status: null, code: \"invalid_params\" },\n        );\n      }\n      const body = { ...params, type: hasText ? \"text\" : \"template\" };\n      return this.#request<SendMessageResponse>(\"/api/v1/messages\", body, \"messages\");\n    },\n  };\n\n  async #request<T>(path: string, body: unknown, policy: RetryPolicy): Promise<T> {\n    let lastError: TokolakuAPIError | null = null;\n    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {\n      let retryAfterSec: number | null = null;\n      try {\n        return await this.#once<T>(path, body, (v) => { retryAfterSec = v; });\n      } catch (e) {\n        // defensif: #once selalu melempar TokolakuAPIError; cabang else = jaring pengaman\n        const err = e instanceof TokolakuAPIError\n          ? e\n          : new TokolakuAPIError(String(e), { status: null, code: \"network_error\" });\n        lastError = err;\n        if (attempt >= this.#maxRetries || !shouldRetry(policy, err)) throw err;\n        await new Promise((r) => setTimeout(r, retryDelayMs(attempt, retryAfterSec)));\n      }\n    }\n    throw lastError!;\n  }\n\n  async #once<T>(path: string, body: unknown, onRetryAfter: (sec: number | null) => void): Promise<T> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.#timeoutMs);\n    try {\n      const res = await this.#fetch(`${this.#baseUrl}${path}`, {\n        method: \"POST\",\n        headers: { \"authorization\": `Bearer ${this.#apiKey}`, \"content-type\": \"application/json\" },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n      const text = await res.text();\n      if (!res.ok) {\n        const ra = res.headers.get(\"retry-after\");\n        onRetryAfter(ra != null && /^\\d+$/.test(ra) ? Number(ra) : null);\n        throw mapResponseError(res.status, text);\n      }\n      try {\n        return JSON.parse(text) as T;\n      } catch {\n        // Respons HTTP sudah diterima (efek samping server, mis. pesan terkirim &\n        // tercharge, SUDAH terjadi) — parse gagal BUKAN network error & TIDAK boleh di-retry.\n        throw new TokolakuAPIError(\"Respons server bukan JSON valid\", { status: res.status, code: \"invalid_response\" });\n      }\n    } catch (e) {\n      if (e instanceof TokolakuAPIError) throw e;\n      if (e instanceof Error && e.name === \"AbortError\") {\n        throw new TokolakuAPIError(`Timeout setelah ${this.#timeoutMs}ms`, { status: null, code: \"timeout\" });\n      }\n      const msg = e instanceof Error ? e.message : String(e);\n      throw new TokolakuAPIError(`Network error: ${msg}`, { status: null, code: \"network_error\" });\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/webhooks.cjs

@@ -0,0 +1,59 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/webhooks.ts
+var webhooks_exports = {};
+__export(webhooks_exports, {
+  TokolakuWebhookSignatureError: () => TokolakuWebhookSignatureError,
+  constructEvent: () => constructEvent,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(webhooks_exports);
+var import_node_crypto = require("crypto");
+
+// src/errors.ts
+var TokolakuWebhookSignatureError = class extends Error {
+  constructor(message = "Signature webhook tidak valid") {
+    super(message);
+    this.name = "TokolakuWebhookSignatureError";
+  }
+};
+
+// src/webhooks.ts
+function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader?.startsWith("sha256=")) return false;
+  const hex = signatureHeader.slice("sha256=".length);
+  if (!/^[0-9a-f]{64}$/i.test(hex)) return false;
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(rawBody).digest();
+  const given = Buffer.from(hex, "hex");
+  return (0, import_node_crypto.timingSafeEqual)(given, expected);
+}
+function constructEvent(rawBody, signatureHeader, secret) {
+  if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {
+    throw new TokolakuWebhookSignatureError();
+  }
+  return { event: JSON.parse(rawBody) };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TokolakuWebhookSignatureError,
+  constructEvent,
+  verifyWebhookSignature
+});
+//# sourceMappingURL=webhooks.cjs.map

package/dist/webhooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhooks.ts","../src/errors.ts"],"sourcesContent":["import { createHmac, timingSafeEqual } from \"node:crypto\";\nimport { TokolakuWebhookSignatureError } from \"./errors.js\";\n\n/** Verifikasi header `x-tokolaku-signature` (format `sha256=<hex>`,\n *  HMAC-SHA256(secret, rawBody)) — compare timing-safe. rawBody HARUS\n *  string mentah persis seperti diterima (bukan hasil re-serialize).\n *  Hex format strict: exactly 64 hex chars, case-insensitive. */\nexport function verifyWebhookSignature(\n  rawBody: string,\n  signatureHeader: string | undefined,\n  secret: string,\n): boolean {\n  if (!signatureHeader?.startsWith(\"sha256=\")) return false;\n  const hex = signatureHeader.slice(\"sha256=\".length);\n  if (!/^[0-9a-f]{64}$/i.test(hex)) return false; // strict: exactly 64 hex chars, reject trailing garbage\n  const expected = createHmac(\"sha256\", secret).update(rawBody).digest();\n  const given = Buffer.from(hex, \"hex\");\n  return timingSafeEqual(given, expected);\n}\n\n/** Verify + parse. Signature invalid → throw TokolakuWebhookSignatureError.\n *  Signature VALID tapi rawBody bukan JSON valid → SyntaxError dari JSON.parse\n *  (sengaja tidak dibungkus — itu bug payload, bukan soal keamanan). */\nexport function constructEvent<T = unknown>(\n  rawBody: string,\n  signatureHeader: string | undefined,\n  secret: string,\n): { event: T } {\n  if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {\n    throw new TokolakuWebhookSignatureError();\n  }\n  return { event: JSON.parse(rawBody) as T };\n}\n\n// Re-export supaya konsumen bisa import class error dari subpath yang sama\n// dengan fungsi yang melemparnya (sesuai contoh README).\nexport { TokolakuWebhookSignatureError } from \"./errors.js\";\n","/** Base error semua kegagalan API. `status` null = kegagalan sebelum ada\n *  respons HTTP (network/timeout). `code` = kode envelope BE, mis.\n *  \"insufficient_balance\"; null bila body bukan JSON envelope. */\nexport class TokolakuAPIError extends Error {\n  readonly status: number | null;\n  readonly code: string | null;\n  constructor(message: string, opts: { status: number | null; code: string | null }) {\n    super(message);\n    this.name = new.target.name;\n    this.status = opts.status;\n    this.code = opts.code;\n  }\n}\n\nexport class TokolakuAuthenticationError extends TokolakuAPIError {}      // 401\nexport class TokolakuInsufficientBalanceError extends TokolakuAPIError {} // 402\nexport class TokolakuPermissionError extends TokolakuAPIError {}          // 403\nexport class TokolakuRateLimitError extends TokolakuAPIError {}           // 429\nexport class TokolakuValidationError extends TokolakuAPIError {}          // 400/422 + validasi klien\n\nexport class TokolakuWebhookSignatureError extends Error {\n  constructor(message = \"Signature webhook tidak valid\") {\n    super(message);\n    this.name = \"TokolakuWebhookSignatureError\";\n  }\n}\n\nconst STATUS_CLASS: Record<number, new (m: string, o: { status: number | null; code: string | null }) => TokolakuAPIError> = {\n  400: TokolakuValidationError,\n  401: TokolakuAuthenticationError,\n  402: TokolakuInsufficientBalanceError,\n  403: TokolakuPermissionError,\n  422: TokolakuValidationError,\n  429: TokolakuRateLimitError,\n};\n\n/** Terjemahkan respons non-2xx jadi error class. Envelope BE:\n *  `{ error: { code, message } }`. Body non-JSON dipotong 500 char. */\nexport function mapResponseError(status: number, bodyText: string): TokolakuAPIError {\n  let code: string | null = null;\n  let message = bodyText ? bodyText.slice(0, 500) : `HTTP ${status}`;\n  try {\n    const parsed = JSON.parse(bodyText) as { error?: { code?: string; message?: string } };\n    if (parsed?.error) {\n      code = parsed.error.code ?? null;\n      message = parsed.error.message ?? message;\n    }\n  } catch {\n    /* non-JSON — pakai default */\n  }\n  const Cls = STATUS_CLASS[status] ?? TokolakuAPIError;\n  return new Cls(message, { status, code });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA4C;;;ACoBrC,IAAM,gCAAN,cAA4C,MAAM;AAAA,EACvD,YAAY,UAAU,iCAAiC;AACrD,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;;;ADlBO,SAAS,uBACd,SACA,iBACA,QACS;AACT,MAAI,CAAC,iBAAiB,WAAW,SAAS,EAAG,QAAO;AACpD,QAAM,MAAM,gBAAgB,MAAM,UAAU,MAAM;AAClD,MAAI,CAAC,kBAAkB,KAAK,GAAG,EAAG,QAAO;AACzC,QAAM,eAAW,+BAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO;AACrE,QAAM,QAAQ,OAAO,KAAK,KAAK,KAAK;AACpC,aAAO,oCAAgB,OAAO,QAAQ;AACxC;AAKO,SAAS,eACd,SACA,iBACA,QACc;AACd,MAAI,CAAC,uBAAuB,SAAS,iBAAiB,MAAM,GAAG;AAC7D,UAAM,IAAI,8BAA8B;AAAA,EAC1C;AACA,SAAO,EAAE,OAAO,KAAK,MAAM,OAAO,EAAO;AAC3C;","names":[]}

package/dist/webhooks.d.cts

@@ -0,0 +1,15 @@
+export { f as TokolakuWebhookSignatureError } from './errors-PooMi-0n.cjs';
+
+/** Verifikasi header `x-tokolaku-signature` (format `sha256=<hex>`,
+ *  HMAC-SHA256(secret, rawBody)) — compare timing-safe. rawBody HARUS
+ *  string mentah persis seperti diterima (bukan hasil re-serialize).
+ *  Hex format strict: exactly 64 hex chars, case-insensitive. */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string | undefined, secret: string): boolean;
+/** Verify + parse. Signature invalid → throw TokolakuWebhookSignatureError.
+ *  Signature VALID tapi rawBody bukan JSON valid → SyntaxError dari JSON.parse
+ *  (sengaja tidak dibungkus — itu bug payload, bukan soal keamanan). */
+declare function constructEvent<T = unknown>(rawBody: string, signatureHeader: string | undefined, secret: string): {
+    event: T;
+};
+
+export { constructEvent, verifyWebhookSignature };

package/dist/webhooks.d.ts

@@ -0,0 +1,15 @@
+export { f as TokolakuWebhookSignatureError } from './errors-PooMi-0n.js';
+
+/** Verifikasi header `x-tokolaku-signature` (format `sha256=<hex>`,
+ *  HMAC-SHA256(secret, rawBody)) — compare timing-safe. rawBody HARUS
+ *  string mentah persis seperti diterima (bukan hasil re-serialize).
+ *  Hex format strict: exactly 64 hex chars, case-insensitive. */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string | undefined, secret: string): boolean;
+/** Verify + parse. Signature invalid → throw TokolakuWebhookSignatureError.
+ *  Signature VALID tapi rawBody bukan JSON valid → SyntaxError dari JSON.parse
+ *  (sengaja tidak dibungkus — itu bug payload, bukan soal keamanan). */
+declare function constructEvent<T = unknown>(rawBody: string, signatureHeader: string | undefined, secret: string): {
+    event: T;
+};
+
+export { constructEvent, verifyWebhookSignature };

package/dist/webhooks.js

@@ -0,0 +1,26 @@
+import {
+  TokolakuWebhookSignatureError
+} from "./chunk-6YQXWMOC.js";
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader?.startsWith("sha256=")) return false;
+  const hex = signatureHeader.slice("sha256=".length);
+  if (!/^[0-9a-f]{64}$/i.test(hex)) return false;
+  const expected = createHmac("sha256", secret).update(rawBody).digest();
+  const given = Buffer.from(hex, "hex");
+  return timingSafeEqual(given, expected);
+}
+function constructEvent(rawBody, signatureHeader, secret) {
+  if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {
+    throw new TokolakuWebhookSignatureError();
+  }
+  return { event: JSON.parse(rawBody) };
+}
+export {
+  TokolakuWebhookSignatureError,
+  constructEvent,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhooks.ts"],"sourcesContent":["import { createHmac, timingSafeEqual } from \"node:crypto\";\nimport { TokolakuWebhookSignatureError } from \"./errors.js\";\n\n/** Verifikasi header `x-tokolaku-signature` (format `sha256=<hex>`,\n *  HMAC-SHA256(secret, rawBody)) — compare timing-safe. rawBody HARUS\n *  string mentah persis seperti diterima (bukan hasil re-serialize).\n *  Hex format strict: exactly 64 hex chars, case-insensitive. */\nexport function verifyWebhookSignature(\n  rawBody: string,\n  signatureHeader: string | undefined,\n  secret: string,\n): boolean {\n  if (!signatureHeader?.startsWith(\"sha256=\")) return false;\n  const hex = signatureHeader.slice(\"sha256=\".length);\n  if (!/^[0-9a-f]{64}$/i.test(hex)) return false; // strict: exactly 64 hex chars, reject trailing garbage\n  const expected = createHmac(\"sha256\", secret).update(rawBody).digest();\n  const given = Buffer.from(hex, \"hex\");\n  return timingSafeEqual(given, expected);\n}\n\n/** Verify + parse. Signature invalid → throw TokolakuWebhookSignatureError.\n *  Signature VALID tapi rawBody bukan JSON valid → SyntaxError dari JSON.parse\n *  (sengaja tidak dibungkus — itu bug payload, bukan soal keamanan). */\nexport function constructEvent<T = unknown>(\n  rawBody: string,\n  signatureHeader: string | undefined,\n  secret: string,\n): { event: T } {\n  if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {\n    throw new TokolakuWebhookSignatureError();\n  }\n  return { event: JSON.parse(rawBody) as T };\n}\n\n// Re-export supaya konsumen bisa import class error dari subpath yang sama\n// dengan fungsi yang melemparnya (sesuai contoh README).\nexport { TokolakuWebhookSignatureError } from \"./errors.js\";\n"],"mappings":";;;;;AAAA,SAAS,YAAY,uBAAuB;AAOrC,SAAS,uBACd,SACA,iBACA,QACS;AACT,MAAI,CAAC,iBAAiB,WAAW,SAAS,EAAG,QAAO;AACpD,QAAM,MAAM,gBAAgB,MAAM,UAAU,MAAM;AAClD,MAAI,CAAC,kBAAkB,KAAK,GAAG,EAAG,QAAO;AACzC,QAAM,WAAW,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO;AACrE,QAAM,QAAQ,OAAO,KAAK,KAAK,KAAK;AACpC,SAAO,gBAAgB,OAAO,QAAQ;AACxC;AAKO,SAAS,eACd,SACA,iBACA,QACc;AACd,MAAI,CAAC,uBAAuB,SAAS,iBAAiB,MAAM,GAAG;AAC7D,UAAM,IAAI,8BAA8B;AAAA,EAC1C;AACA,SAAO,EAAE,OAAO,KAAK,MAAM,OAAO,EAAO;AAC3C;","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "tokolaku-sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for the Tokolaku Engine API — AI bot replies, omnichannel messaging (WhatsApp/Instagram/Messenger), and webhook verification.",
+  "keywords": ["tokolaku", "whatsapp", "chatbot", "sdk", "api", "messaging"],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" },
+    "./webhooks": { "types": "./dist/webhooks.d.ts", "import": "./dist/webhooks.js", "require": "./dist/webhooks.cjs" }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "repository": { "type": "git", "url": "git+https://github.com/Rustam335/tokolaku-sdk-js.git" },
+  "homepage": "https://tokolaku.id/developers",
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test --import tsx \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "yarn typecheck && yarn test && yarn build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}