misterbot 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# misterbot
+
+SDK oficial de **Mister Bot** — el gateway HTTP que expone WhatsApp (vía Baileys) a tus apps.
+
+Envía mensajes de texto y multimedia que el servidor encola con jitter anti-ban, y trae un flujo listo para **validar números de celular por código (OTP)**.
+
+> Necesitás un token de API (`mbk_…`) que crea un admin desde el panel de Mister Bot, y la URL base de tu instancia.
+
+## Instalación
+
+```bash
+npm install misterbot
+```
+
+Requiere Node >= 18 (usa `fetch`, `FormData` y `Blob` globales). En el browser también funciona si pasás un token con CORS habilitado.
+
+## Uso rápido
+
+```ts
+import { MisterBotClient } from 'misterbot'
+
+const mb = new MisterBotClient({
+  baseUrl: 'https://wa.miempresa.com',
+  token: 'mbk_xxxxxxxxxxxxxxxx',
+  sessionId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee', // opcional si el token tiene sesión fija
+})
+
+const { id } = await mb.sendText({
+  to: '5491133334444',
+  text: '¡Hola! Probando la API.',
+})
+
+const estado = await mb.getStatus(id)
+console.log(estado.status) // 'sent' | 'delivered' | 'read' | ...
+```
+
+`sendText`/`sendMedia` resuelven cuando el servidor **despachó** el mensaje por la cola anti-ban; por eso un envío puede tardar (delays aleatorios entre mensajes). Ajustá `timeoutMs` si hace falta.
+
+## Enviar multimedia
+
+```ts
+// Desde datos binarios (Buffer, Uint8Array, ArrayBuffer o Blob)
+await mb.sendMedia({
+  to: '5491133334444',
+  data: miBuffer,
+  mimeType: 'image/jpeg',
+  filename: 'foto.jpg',
+  caption: 'Mirá esto',
+})
+
+// Conveniencia en Node: directo desde un archivo del disco
+await mb.sendMediaFile({
+  to: '5491133334444',
+  path: './facturas/0001.pdf',
+  caption: 'Tu factura',
+})
+```
+
+## Validación de número por código (OTP)
+
+```ts
+const otp = mb.otp({
+  ttlMs: 5 * 60 * 1000, // vigencia del código (default 5 min)
+  codeLength: 6,         // dígitos (default 6)
+  maxAttempts: 3,        // intentos antes de invalidar (default 3)
+})
+
+// 1. Mandar el código
+await otp.send('5491133334444')
+
+// 2. Verificar lo que ingresó el usuario
+const r = await otp.verify('5491133334444', '123456')
+if (r.ok) {
+  // número validado
+} else {
+  // r.reason: 'mismatch' | 'expired' | 'not_found' | 'too_many_attempts'
+}
+```
+
+### Store de códigos
+
+Por defecto el estado vive **en memoria** (`MemoryCodeStore`), suficiente para un solo proceso. Si corrés varias instancias o querés que sobreviva reinicios, inyectá tu propio store (Redis, DB, etc.):
+
+```ts
+import { MisterBotClient, type CodeStore } from 'misterbot'
+
+const redisStore: CodeStore = {
+  async get(key) {
+    const raw = await redis.get(`otp:${key}`)
+    return raw ? JSON.parse(raw) : undefined
+  },
+  async set(key, value) {
+    await redis.set(`otp:${key}`, JSON.stringify(value), 'PX', value.expiresAt - Date.now())
+  },
+  async delete(key) {
+    await redis.del(`otp:${key}`)
+  },
+}
+
+const otp = mb.otp({ store: redisStore })
+```
+
+### Mensaje personalizado
+
+```ts
+const otp = mb.otp({
+  template: (code, ttlMs) =>
+    `Tu código MiApp es ${code}. Vence en ${Math.round(ttlMs / 60000)} min.`,
+})
+```
+
+## Esperar confirmación de envío
+
+```ts
+const { id } = await mb.sendText({ to, text })
+const final = await mb.waitUntilSent(id, { minStatus: 'delivered', timeoutMs: 30_000 })
+console.log(final.status)
+```
+
+## Manejo de errores
+
+```ts
+import { MisterBotError } from 'misterbot'
+
+try {
+  await mb.sendText({ to, text })
+} catch (err) {
+  if (err instanceof MisterBotError) {
+    if (err.isQuotaError) {
+      // cuota agotada: NO reintentar en loop, esperá al día siguiente
+    } else if (err.isRetryable) {
+      // 5xx: reintentá con backoff
+    }
+    console.error(err.code, err.status) // ej: 'session_not_connected', 409
+  }
+}
+```
+
+Códigos comunes: `invalid_token` (401), `session_not_connected` (409), `session_not_found` (404), `daily_quota_exceeded` / `TOTAL_QUOTA_EXCEEDED` (429).
+
+## API
+
+| Método | Descripción |
+|--------|-------------|
+| `new MisterBotClient(opts)` | `baseUrl`, `token`, `sessionId?`, `timeoutMs?`, `fetch?` |
+| `sendText({ to, text, sessionId? })` | Envía texto. Devuelve `{ id }`. |
+| `sendMedia({ to, data, mimeType, filename?, caption?, sessionId? })` | Envía binario. |
+| `sendMediaFile({ to, path, mimeType?, caption?, sessionId? })` | Lee y envía un archivo (Node). |
+| `getStatus(id)` | Estado del mensaje. |
+| `listSessions()` | Sesiones que el token puede usar. |
+| `waitUntilSent(id, opts?)` | Pollea hasta estado terminal. |
+| `otp(opts?)` | Crea un `OtpManager` (`send` / `verify`). |
+
+## Desarrollo
+
+```bash
+npm install
+npm run build      # genera dist/ (ESM + CJS + tipos) con tsup
+npm run typecheck
+```

package/dist/index.cjs

@@ -0,0 +1,343 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryCodeStore: () => MemoryCodeStore,
+  MisterBotClient: () => MisterBotClient,
+  MisterBotError: () => MisterBotError,
+  OtpManager: () => OtpManager
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var QUOTA_CODES = /* @__PURE__ */ new Set([
+  "daily_quota_exceeded",
+  "monthly_quota_exceeded",
+  "UNKNOWN_QUOTA_EXCEEDED",
+  "TOTAL_QUOTA_EXCEEDED"
+]);
+var MisterBotError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message ?? code);
+    this.name = "MisterBotError";
+    this.status = status;
+    this.code = code;
+  }
+  /** true si el envío fue rechazado por cuota (token o anti-ban). No reintentar en loop. */
+  get isQuotaError() {
+    return QUOTA_CODES.has(this.code);
+  }
+  /** true si conviene reintentar con backoff (5xx). Los 4xx no se reintentan. */
+  get isRetryable() {
+    return this.status >= 500;
+  }
+};
+
+// src/store.ts
+var MemoryCodeStore = class {
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const v = this.map.get(key);
+    if (!v) return void 0;
+    if (v.expiresAt <= Date.now()) {
+      this.map.delete(key);
+      return void 0;
+    }
+    return v;
+  }
+  set(key, value) {
+    this.map.set(key, value);
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+
+// src/otp.ts
+function defaultTemplate(code, ttlMs) {
+  const mins = Math.max(1, Math.round(ttlMs / 6e4));
+  return `Tu c\xF3digo de verificaci\xF3n es: ${code}
+
+Vence en ${mins} minuto${mins === 1 ? "" : "s"}. No lo compartas con nadie.`;
+}
+function randomDigits(length) {
+  const g = globalThis;
+  let out = "";
+  if (g.crypto?.getRandomValues) {
+    const buf = new Uint32Array(length);
+    g.crypto.getRandomValues(buf);
+    for (let i = 0; i < length; i++) out += String((buf[i] ?? 0) % 10);
+  } else {
+    for (let i = 0; i < length; i++) out += String(Math.floor(Math.random() * 10));
+  }
+  return out;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function normalizePhone(phone) {
+  return phone.replace(/[^0-9]/g, "");
+}
+var OtpManager = class {
+  sender;
+  store;
+  codeLength;
+  ttlMs;
+  maxAttempts;
+  sessionId;
+  template;
+  generate;
+  constructor(sender, opts = {}) {
+    this.sender = sender;
+    this.store = opts.store ?? new MemoryCodeStore();
+    this.codeLength = opts.codeLength ?? 6;
+    this.ttlMs = opts.ttlMs ?? 5 * 60 * 1e3;
+    this.maxAttempts = opts.maxAttempts ?? 3;
+    this.sessionId = opts.sessionId;
+    this.template = opts.template ?? defaultTemplate;
+    this.generate = opts.generateCode ?? (() => randomDigits(this.codeLength));
+  }
+  /** Genera y envía un código a `phone`. Reemplaza cualquier código previo del mismo número. */
+  async send(phone) {
+    const key = normalizePhone(phone);
+    const code = this.generate();
+    const expiresAt = Date.now() + this.ttlMs;
+    await this.store.set(key, { code, expiresAt, attempts: 0 });
+    const result = await this.sender.sendText({
+      to: key,
+      text: this.template(code, this.ttlMs),
+      sessionId: this.sessionId
+    });
+    return { id: result.id, expiresAt };
+  }
+  /** Verifica el código ingresado por el usuario. Consume el código si es correcto. */
+  async verify(phone, code) {
+    const key = normalizePhone(phone);
+    const entry = await this.store.get(key);
+    if (!entry) return { ok: false, reason: "not_found" };
+    if (entry.expiresAt <= Date.now()) {
+      await this.store.delete(key);
+      return { ok: false, reason: "expired" };
+    }
+    if (entry.attempts >= this.maxAttempts) {
+      await this.store.delete(key);
+      return { ok: false, reason: "too_many_attempts" };
+    }
+    if (timingSafeEqual(entry.code, code.trim())) {
+      await this.store.delete(key);
+      return { ok: true };
+    }
+    const attempts = entry.attempts + 1;
+    if (attempts >= this.maxAttempts) {
+      await this.store.delete(key);
+      return { ok: false, reason: "too_many_attempts" };
+    }
+    await this.store.set(key, { ...entry, attempts });
+    return { ok: false, reason: "mismatch" };
+  }
+};
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 12e4;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["sent", "delivered", "read", "failed"]);
+var EXT_MIME = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+  gif: "image/gif",
+  mp4: "video/mp4",
+  "3gp": "video/3gpp",
+  webm: "video/webm",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  pdf: "application/pdf",
+  zip: "application/zip",
+  txt: "text/plain",
+  csv: "text/csv"
+};
+var MisterBotClient = class {
+  baseUrl;
+  token;
+  sessionId;
+  timeoutMs;
+  fetchImpl;
+  constructor(opts) {
+    if (!opts.baseUrl) throw new Error("baseUrl is required");
+    if (!opts.token) throw new Error("token is required");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = opts.token;
+    this.sessionId = opts.sessionId;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) throw new Error("No fetch available \u2014 pass options.fetch (Node <18 needs a polyfill)");
+    this.fetchImpl = f;
+  }
+  /** Envía un mensaje de texto. Resuelve cuando el servidor lo despachó por la cola anti-ban. */
+  async sendText(input) {
+    const body = {
+      to: input.to,
+      text: input.text,
+      sessionId: input.sessionId ?? this.sessionId
+    };
+    const res = await this.request("POST", "/api/v1/send/text", {
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    return { id: res.id };
+  }
+  /** Envía un archivo (imagen/video/audio/documento) a partir de datos binarios. */
+  async sendMedia(input) {
+    const blob = toBlob(input.data, input.mimeType);
+    const form = new FormData();
+    form.append("file", blob, input.filename ?? "file");
+    form.append("to", input.to);
+    if (input.caption) form.append("caption", input.caption);
+    const sessionId = input.sessionId ?? this.sessionId;
+    if (sessionId) form.append("sessionId", sessionId);
+    const res = await this.request("POST", "/api/v1/send/media", { body: form });
+    return { id: res.id };
+  }
+  /** Conveniencia para Node: lee un archivo del disco y lo envía. */
+  async sendMediaFile(input) {
+    const { readFile } = await import("fs/promises");
+    const data = await readFile(input.path);
+    const mimeType = input.mimeType ?? inferMime(input.path);
+    if (!mimeType) throw new Error(`No se pudo inferir el MIME de "${input.path}" \u2014 pas\xE1 mimeType.`);
+    const filename = input.path.split(/[\\/]/).pop() ?? "file";
+    return this.sendMedia({
+      to: input.to,
+      data: new Uint8Array(data),
+      mimeType,
+      filename,
+      caption: input.caption,
+      sessionId: input.sessionId
+    });
+  }
+  /** Estado actual de un mensaje (queued/sending/sent/delivered/read/failed). */
+  async getStatus(id) {
+    const res = await this.request("GET", `/api/v1/status/${encodeURIComponent(id)}`);
+    return res;
+  }
+  /** Sesiones que el token puede usar. */
+  async listSessions() {
+    const res = await this.request("GET", "/api/v1/sessions");
+    return res.sessions ?? [];
+  }
+  /**
+   * Pollea getStatus() hasta que el mensaje llegue a un estado terminal
+   * (sent/delivered/read/failed) o se agote el tiempo. Backoff: 1s,2s,3s,5s,8s...
+   */
+  async waitUntilSent(id, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 6e4);
+    const target = opts.minStatus ?? "sent";
+    const rank = { queued: 0, sending: 1, sent: 2, delivered: 3, read: 4 };
+    const delays = [1e3, 2e3, 3e3, 5e3, 8e3];
+    let attempt = 0;
+    for (; ; ) {
+      const s = await this.getStatus(id);
+      if (s.status === "failed") return s;
+      if ((rank[s.status] ?? 0) >= (rank[target] ?? 2)) return s;
+      if (!TERMINAL_STATUSES.has(s.status) && Date.now() >= deadline) return s;
+      const wait = delays[Math.min(attempt, delays.length - 1)] ?? 8e3;
+      if (Date.now() + wait > deadline) return s;
+      await sleep(wait);
+      attempt++;
+    }
+  }
+  /** Crea un manejador de OTP (validación de número por código) atado a este cliente. */
+  otp(opts = {}) {
+    return new OtpManager(this, { sessionId: this.sessionId, ...opts });
+  }
+  async request(method, path, init = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${this.token}`, ...init.headers },
+        body: init.body,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        throw new MisterBotError(408, "request_timeout", `La request super\xF3 ${this.timeoutMs}ms`);
+      }
+      throw new MisterBotError(0, "network_error", String(err?.message ?? err));
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json = {};
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = {};
+      }
+    }
+    if (!res.ok) {
+      const code = json.statusMessage || json.message || `http_${res.status}`;
+      throw new MisterBotError(res.status, code, json.message || code);
+    }
+    return json;
+  }
+};
+function toBlob(data, mimeType) {
+  if (typeof Blob !== "undefined" && data instanceof Blob) return data;
+  if (data instanceof ArrayBuffer) return new Blob([data], { type: mimeType });
+  if (ArrayBuffer.isView(data)) {
+    return new Blob([data], { type: mimeType });
+  }
+  throw new Error("data debe ser Blob, ArrayBuffer o ArrayBufferView (Buffer/Uint8Array)");
+}
+function inferMime(path) {
+  const ext = path.split(".").pop()?.toLowerCase() ?? "";
+  return EXT_MIME[ext];
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryCodeStore,
+  MisterBotClient,
+  MisterBotError,
+  OtpManager
+});

package/dist/index.d.cts

@@ -0,0 +1,190 @@
+interface MisterBotClientOptions {
+    /** Base URL del servidor Mister Bot, ej: "https://wa.miempresa.com". Sin "/" final. */
+    baseUrl: string;
+    /** Token de API (empieza con "mbk_"). Lo crea un admin desde el panel. */
+    token: string;
+    /** Sesión por defecto. Opcional si el token ya tiene una sesión fija. */
+    sessionId?: string;
+    /**
+     * Timeout por request en ms. El servidor encola el envío y responde recién
+     * cuando el mensaje salió, así que un envío puede tardar (jitter anti-ban).
+     * Default: 120000 (2 min).
+     */
+    timeoutMs?: number;
+    /** Implementación de fetch a usar. Default: el `fetch` global (Node >=18 / browser). */
+    fetch?: typeof fetch;
+}
+interface SendTextInput {
+    /** Número internacional sin "+" ni espacios. Ej: "5491133334444". */
+    to: string;
+    /** Texto del mensaje (1..4096 chars). */
+    text: string;
+    /** Override de la sesión para este envío. */
+    sessionId?: string;
+}
+type MediaData = Blob | ArrayBuffer | ArrayBufferView;
+interface SendMediaInput {
+    to: string;
+    /** Contenido binario del archivo (Blob, Buffer, Uint8Array, ArrayBuffer). */
+    data: MediaData;
+    /** MIME del archivo, ej: "image/jpeg", "application/pdf". */
+    mimeType: string;
+    /** Nombre de archivo (recomendado para documentos). */
+    filename?: string;
+    /** Leyenda (solo imagen/video/documento). */
+    caption?: string;
+    sessionId?: string;
+}
+interface SendMediaFileInput {
+    to: string;
+    /** Ruta en disco del archivo a enviar (solo Node). */
+    path: string;
+    /** MIME explícito. Si se omite se infiere de la extensión. */
+    mimeType?: string;
+    caption?: string;
+    sessionId?: string;
+}
+interface SendResult {
+    /** UUID del mensaje. Usalo con getStatus() / waitUntilSent(). */
+    id: string;
+}
+type MessageStatusValue = 'queued' | 'sending' | 'sent' | 'delivered' | 'read' | 'failed' | 'received';
+interface MessageStatus {
+    id: string;
+    status: MessageStatusValue;
+    type: string;
+    to: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    readAt: string | null;
+    failedAt: string | null;
+    error: string | null;
+}
+interface Session {
+    id: string;
+    name: string;
+    phoneNumber: string | null;
+    status: string;
+    isPaused: boolean;
+}
+
+interface StoredCode {
+    code: string;
+    expiresAt: number;
+    attempts: number;
+}
+/**
+ * Almacén de códigos OTP. Por defecto el SDK usa uno en memoria, pero podés
+ * inyectar el tuyo (Redis, DB, etc.) implementando esta interfaz para que la
+ * verificación funcione entre procesos o sobreviva reinicios.
+ */
+interface CodeStore {
+    get(key: string): Promise<StoredCode | undefined> | StoredCode | undefined;
+    set(key: string, value: StoredCode): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+/**
+ * Store en memoria con expiración. Suficiente para un solo proceso / pruebas.
+ * No sirve si corrés varias instancias: usá un store compartido en ese caso.
+ */
+declare class MemoryCodeStore implements CodeStore {
+    private map;
+    get(key: string): StoredCode | undefined;
+    set(key: string, value: StoredCode): void;
+    delete(key: string): void;
+}
+
+interface OtpSender {
+    sendText(input: SendTextInput): Promise<SendResult>;
+}
+interface OtpManagerOptions {
+    /** Store de códigos. Default: MemoryCodeStore (en memoria, un solo proceso). */
+    store?: CodeStore;
+    /** Cantidad de dígitos del código. Default: 6. */
+    codeLength?: number;
+    /** Vigencia del código en ms. Default: 300000 (5 min). */
+    ttlMs?: number;
+    /** Intentos de verificación permitidos antes de invalidar el código. Default: 3. */
+    maxAttempts?: number;
+    /** Sesión a usar para enviar el SMS/WhatsApp. Cae a la del cliente si se omite. */
+    sessionId?: string;
+    /** Genera el texto del mensaje. Recibe el código y los ms de vigencia. */
+    template?: (code: string, ttlMs: number) => string;
+    /** Generador de código propio (ej: alfanumérico). Default: numérico de `codeLength` dígitos. */
+    generateCode?: () => string;
+}
+type VerifyReason = 'not_found' | 'expired' | 'mismatch' | 'too_many_attempts';
+interface VerifyResult {
+    ok: boolean;
+    reason?: VerifyReason;
+}
+interface OtpSendResult extends SendResult {
+    /** Epoch ms en que vence el código. */
+    expiresAt: number;
+}
+/**
+ * Flujo de validación de número por código: genera un código, lo envía por
+ * WhatsApp (vía la cola anti-ban del servidor) y lo verifica contra un store.
+ * El estado vive del lado del cliente, así que es independiente del servidor.
+ */
+declare class OtpManager {
+    private sender;
+    private store;
+    private codeLength;
+    private ttlMs;
+    private maxAttempts;
+    private sessionId;
+    private template;
+    private generate;
+    constructor(sender: OtpSender, opts?: OtpManagerOptions);
+    /** Genera y envía un código a `phone`. Reemplaza cualquier código previo del mismo número. */
+    send(phone: string): Promise<OtpSendResult>;
+    /** Verifica el código ingresado por el usuario. Consume el código si es correcto. */
+    verify(phone: string, code: string): Promise<VerifyResult>;
+}
+
+declare class MisterBotClient {
+    private baseUrl;
+    private token;
+    private sessionId;
+    private timeoutMs;
+    private fetchImpl;
+    constructor(opts: MisterBotClientOptions);
+    /** Envía un mensaje de texto. Resuelve cuando el servidor lo despachó por la cola anti-ban. */
+    sendText(input: SendTextInput): Promise<SendResult>;
+    /** Envía un archivo (imagen/video/audio/documento) a partir de datos binarios. */
+    sendMedia(input: SendMediaInput): Promise<SendResult>;
+    /** Conveniencia para Node: lee un archivo del disco y lo envía. */
+    sendMediaFile(input: SendMediaFileInput): Promise<SendResult>;
+    /** Estado actual de un mensaje (queued/sending/sent/delivered/read/failed). */
+    getStatus(id: string): Promise<MessageStatus>;
+    /** Sesiones que el token puede usar. */
+    listSessions(): Promise<Session[]>;
+    /**
+     * Pollea getStatus() hasta que el mensaje llegue a un estado terminal
+     * (sent/delivered/read/failed) o se agote el tiempo. Backoff: 1s,2s,3s,5s,8s...
+     */
+    waitUntilSent(id: string, opts?: {
+        timeoutMs?: number;
+        minStatus?: 'sent' | 'delivered' | 'read';
+    }): Promise<MessageStatus>;
+    /** Crea un manejador de OTP (validación de número por código) atado a este cliente. */
+    otp(opts?: OtpManagerOptions): OtpManager;
+    private request;
+}
+
+/**
+ * Error de una llamada a la API de Mister Bot. `code` es el `statusMessage`
+ * que devuelve el servidor (ej: "session_not_connected", "invalid_token").
+ */
+declare class MisterBotError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message?: string);
+    /** true si el envío fue rechazado por cuota (token o anti-ban). No reintentar en loop. */
+    get isQuotaError(): boolean;
+    /** true si conviene reintentar con backoff (5xx). Los 4xx no se reintentan. */
+    get isRetryable(): boolean;
+}
+
+export { type CodeStore, type MediaData, MemoryCodeStore, type MessageStatus, type MessageStatusValue, MisterBotClient, type MisterBotClientOptions, MisterBotError, OtpManager, type OtpManagerOptions, type OtpSendResult, type SendMediaFileInput, type SendMediaInput, type SendResult, type SendTextInput, type Session, type StoredCode, type VerifyReason, type VerifyResult };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+interface MisterBotClientOptions {
+    /** Base URL del servidor Mister Bot, ej: "https://wa.miempresa.com". Sin "/" final. */
+    baseUrl: string;
+    /** Token de API (empieza con "mbk_"). Lo crea un admin desde el panel. */
+    token: string;
+    /** Sesión por defecto. Opcional si el token ya tiene una sesión fija. */
+    sessionId?: string;
+    /**
+     * Timeout por request en ms. El servidor encola el envío y responde recién
+     * cuando el mensaje salió, así que un envío puede tardar (jitter anti-ban).
+     * Default: 120000 (2 min).
+     */
+    timeoutMs?: number;
+    /** Implementación de fetch a usar. Default: el `fetch` global (Node >=18 / browser). */
+    fetch?: typeof fetch;
+}
+interface SendTextInput {
+    /** Número internacional sin "+" ni espacios. Ej: "5491133334444". */
+    to: string;
+    /** Texto del mensaje (1..4096 chars). */
+    text: string;
+    /** Override de la sesión para este envío. */
+    sessionId?: string;
+}
+type MediaData = Blob | ArrayBuffer | ArrayBufferView;
+interface SendMediaInput {
+    to: string;
+    /** Contenido binario del archivo (Blob, Buffer, Uint8Array, ArrayBuffer). */
+    data: MediaData;
+    /** MIME del archivo, ej: "image/jpeg", "application/pdf". */
+    mimeType: string;
+    /** Nombre de archivo (recomendado para documentos). */
+    filename?: string;
+    /** Leyenda (solo imagen/video/documento). */
+    caption?: string;
+    sessionId?: string;
+}
+interface SendMediaFileInput {
+    to: string;
+    /** Ruta en disco del archivo a enviar (solo Node). */
+    path: string;
+    /** MIME explícito. Si se omite se infiere de la extensión. */
+    mimeType?: string;
+    caption?: string;
+    sessionId?: string;
+}
+interface SendResult {
+    /** UUID del mensaje. Usalo con getStatus() / waitUntilSent(). */
+    id: string;
+}
+type MessageStatusValue = 'queued' | 'sending' | 'sent' | 'delivered' | 'read' | 'failed' | 'received';
+interface MessageStatus {
+    id: string;
+    status: MessageStatusValue;
+    type: string;
+    to: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    readAt: string | null;
+    failedAt: string | null;
+    error: string | null;
+}
+interface Session {
+    id: string;
+    name: string;
+    phoneNumber: string | null;
+    status: string;
+    isPaused: boolean;
+}
+
+interface StoredCode {
+    code: string;
+    expiresAt: number;
+    attempts: number;
+}
+/**
+ * Almacén de códigos OTP. Por defecto el SDK usa uno en memoria, pero podés
+ * inyectar el tuyo (Redis, DB, etc.) implementando esta interfaz para que la
+ * verificación funcione entre procesos o sobreviva reinicios.
+ */
+interface CodeStore {
+    get(key: string): Promise<StoredCode | undefined> | StoredCode | undefined;
+    set(key: string, value: StoredCode): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+/**
+ * Store en memoria con expiración. Suficiente para un solo proceso / pruebas.
+ * No sirve si corrés varias instancias: usá un store compartido en ese caso.
+ */
+declare class MemoryCodeStore implements CodeStore {
+    private map;
+    get(key: string): StoredCode | undefined;
+    set(key: string, value: StoredCode): void;
+    delete(key: string): void;
+}
+
+interface OtpSender {
+    sendText(input: SendTextInput): Promise<SendResult>;
+}
+interface OtpManagerOptions {
+    /** Store de códigos. Default: MemoryCodeStore (en memoria, un solo proceso). */
+    store?: CodeStore;
+    /** Cantidad de dígitos del código. Default: 6. */
+    codeLength?: number;
+    /** Vigencia del código en ms. Default: 300000 (5 min). */
+    ttlMs?: number;
+    /** Intentos de verificación permitidos antes de invalidar el código. Default: 3. */
+    maxAttempts?: number;
+    /** Sesión a usar para enviar el SMS/WhatsApp. Cae a la del cliente si se omite. */
+    sessionId?: string;
+    /** Genera el texto del mensaje. Recibe el código y los ms de vigencia. */
+    template?: (code: string, ttlMs: number) => string;
+    /** Generador de código propio (ej: alfanumérico). Default: numérico de `codeLength` dígitos. */
+    generateCode?: () => string;
+}
+type VerifyReason = 'not_found' | 'expired' | 'mismatch' | 'too_many_attempts';
+interface VerifyResult {
+    ok: boolean;
+    reason?: VerifyReason;
+}
+interface OtpSendResult extends SendResult {
+    /** Epoch ms en que vence el código. */
+    expiresAt: number;
+}
+/**
+ * Flujo de validación de número por código: genera un código, lo envía por
+ * WhatsApp (vía la cola anti-ban del servidor) y lo verifica contra un store.
+ * El estado vive del lado del cliente, así que es independiente del servidor.
+ */
+declare class OtpManager {
+    private sender;
+    private store;
+    private codeLength;
+    private ttlMs;
+    private maxAttempts;
+    private sessionId;
+    private template;
+    private generate;
+    constructor(sender: OtpSender, opts?: OtpManagerOptions);
+    /** Genera y envía un código a `phone`. Reemplaza cualquier código previo del mismo número. */
+    send(phone: string): Promise<OtpSendResult>;
+    /** Verifica el código ingresado por el usuario. Consume el código si es correcto. */
+    verify(phone: string, code: string): Promise<VerifyResult>;
+}
+
+declare class MisterBotClient {
+    private baseUrl;
+    private token;
+    private sessionId;
+    private timeoutMs;
+    private fetchImpl;
+    constructor(opts: MisterBotClientOptions);
+    /** Envía un mensaje de texto. Resuelve cuando el servidor lo despachó por la cola anti-ban. */
+    sendText(input: SendTextInput): Promise<SendResult>;
+    /** Envía un archivo (imagen/video/audio/documento) a partir de datos binarios. */
+    sendMedia(input: SendMediaInput): Promise<SendResult>;
+    /** Conveniencia para Node: lee un archivo del disco y lo envía. */
+    sendMediaFile(input: SendMediaFileInput): Promise<SendResult>;
+    /** Estado actual de un mensaje (queued/sending/sent/delivered/read/failed). */
+    getStatus(id: string): Promise<MessageStatus>;
+    /** Sesiones que el token puede usar. */
+    listSessions(): Promise<Session[]>;
+    /**
+     * Pollea getStatus() hasta que el mensaje llegue a un estado terminal
+     * (sent/delivered/read/failed) o se agote el tiempo. Backoff: 1s,2s,3s,5s,8s...
+     */
+    waitUntilSent(id: string, opts?: {
+        timeoutMs?: number;
+        minStatus?: 'sent' | 'delivered' | 'read';
+    }): Promise<MessageStatus>;
+    /** Crea un manejador de OTP (validación de número por código) atado a este cliente. */
+    otp(opts?: OtpManagerOptions): OtpManager;
+    private request;
+}
+
+/**
+ * Error de una llamada a la API de Mister Bot. `code` es el `statusMessage`
+ * que devuelve el servidor (ej: "session_not_connected", "invalid_token").
+ */
+declare class MisterBotError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message?: string);
+    /** true si el envío fue rechazado por cuota (token o anti-ban). No reintentar en loop. */
+    get isQuotaError(): boolean;
+    /** true si conviene reintentar con backoff (5xx). Los 4xx no se reintentan. */
+    get isRetryable(): boolean;
+}
+
+export { type CodeStore, type MediaData, MemoryCodeStore, type MessageStatus, type MessageStatusValue, MisterBotClient, type MisterBotClientOptions, MisterBotError, OtpManager, type OtpManagerOptions, type OtpSendResult, type SendMediaFileInput, type SendMediaInput, type SendResult, type SendTextInput, type Session, type StoredCode, type VerifyReason, type VerifyResult };

package/dist/index.js

@@ -0,0 +1,303 @@
+// src/errors.ts
+var QUOTA_CODES = /* @__PURE__ */ new Set([
+  "daily_quota_exceeded",
+  "monthly_quota_exceeded",
+  "UNKNOWN_QUOTA_EXCEEDED",
+  "TOTAL_QUOTA_EXCEEDED"
+]);
+var MisterBotError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message ?? code);
+    this.name = "MisterBotError";
+    this.status = status;
+    this.code = code;
+  }
+  /** true si el envío fue rechazado por cuota (token o anti-ban). No reintentar en loop. */
+  get isQuotaError() {
+    return QUOTA_CODES.has(this.code);
+  }
+  /** true si conviene reintentar con backoff (5xx). Los 4xx no se reintentan. */
+  get isRetryable() {
+    return this.status >= 500;
+  }
+};
+
+// src/store.ts
+var MemoryCodeStore = class {
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const v = this.map.get(key);
+    if (!v) return void 0;
+    if (v.expiresAt <= Date.now()) {
+      this.map.delete(key);
+      return void 0;
+    }
+    return v;
+  }
+  set(key, value) {
+    this.map.set(key, value);
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+
+// src/otp.ts
+function defaultTemplate(code, ttlMs) {
+  const mins = Math.max(1, Math.round(ttlMs / 6e4));
+  return `Tu c\xF3digo de verificaci\xF3n es: ${code}
+
+Vence en ${mins} minuto${mins === 1 ? "" : "s"}. No lo compartas con nadie.`;
+}
+function randomDigits(length) {
+  const g = globalThis;
+  let out = "";
+  if (g.crypto?.getRandomValues) {
+    const buf = new Uint32Array(length);
+    g.crypto.getRandomValues(buf);
+    for (let i = 0; i < length; i++) out += String((buf[i] ?? 0) % 10);
+  } else {
+    for (let i = 0; i < length; i++) out += String(Math.floor(Math.random() * 10));
+  }
+  return out;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function normalizePhone(phone) {
+  return phone.replace(/[^0-9]/g, "");
+}
+var OtpManager = class {
+  sender;
+  store;
+  codeLength;
+  ttlMs;
+  maxAttempts;
+  sessionId;
+  template;
+  generate;
+  constructor(sender, opts = {}) {
+    this.sender = sender;
+    this.store = opts.store ?? new MemoryCodeStore();
+    this.codeLength = opts.codeLength ?? 6;
+    this.ttlMs = opts.ttlMs ?? 5 * 60 * 1e3;
+    this.maxAttempts = opts.maxAttempts ?? 3;
+    this.sessionId = opts.sessionId;
+    this.template = opts.template ?? defaultTemplate;
+    this.generate = opts.generateCode ?? (() => randomDigits(this.codeLength));
+  }
+  /** Genera y envía un código a `phone`. Reemplaza cualquier código previo del mismo número. */
+  async send(phone) {
+    const key = normalizePhone(phone);
+    const code = this.generate();
+    const expiresAt = Date.now() + this.ttlMs;
+    await this.store.set(key, { code, expiresAt, attempts: 0 });
+    const result = await this.sender.sendText({
+      to: key,
+      text: this.template(code, this.ttlMs),
+      sessionId: this.sessionId
+    });
+    return { id: result.id, expiresAt };
+  }
+  /** Verifica el código ingresado por el usuario. Consume el código si es correcto. */
+  async verify(phone, code) {
+    const key = normalizePhone(phone);
+    const entry = await this.store.get(key);
+    if (!entry) return { ok: false, reason: "not_found" };
+    if (entry.expiresAt <= Date.now()) {
+      await this.store.delete(key);
+      return { ok: false, reason: "expired" };
+    }
+    if (entry.attempts >= this.maxAttempts) {
+      await this.store.delete(key);
+      return { ok: false, reason: "too_many_attempts" };
+    }
+    if (timingSafeEqual(entry.code, code.trim())) {
+      await this.store.delete(key);
+      return { ok: true };
+    }
+    const attempts = entry.attempts + 1;
+    if (attempts >= this.maxAttempts) {
+      await this.store.delete(key);
+      return { ok: false, reason: "too_many_attempts" };
+    }
+    await this.store.set(key, { ...entry, attempts });
+    return { ok: false, reason: "mismatch" };
+  }
+};
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 12e4;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["sent", "delivered", "read", "failed"]);
+var EXT_MIME = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+  gif: "image/gif",
+  mp4: "video/mp4",
+  "3gp": "video/3gpp",
+  webm: "video/webm",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  pdf: "application/pdf",
+  zip: "application/zip",
+  txt: "text/plain",
+  csv: "text/csv"
+};
+var MisterBotClient = class {
+  baseUrl;
+  token;
+  sessionId;
+  timeoutMs;
+  fetchImpl;
+  constructor(opts) {
+    if (!opts.baseUrl) throw new Error("baseUrl is required");
+    if (!opts.token) throw new Error("token is required");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = opts.token;
+    this.sessionId = opts.sessionId;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) throw new Error("No fetch available \u2014 pass options.fetch (Node <18 needs a polyfill)");
+    this.fetchImpl = f;
+  }
+  /** Envía un mensaje de texto. Resuelve cuando el servidor lo despachó por la cola anti-ban. */
+  async sendText(input) {
+    const body = {
+      to: input.to,
+      text: input.text,
+      sessionId: input.sessionId ?? this.sessionId
+    };
+    const res = await this.request("POST", "/api/v1/send/text", {
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    return { id: res.id };
+  }
+  /** Envía un archivo (imagen/video/audio/documento) a partir de datos binarios. */
+  async sendMedia(input) {
+    const blob = toBlob(input.data, input.mimeType);
+    const form = new FormData();
+    form.append("file", blob, input.filename ?? "file");
+    form.append("to", input.to);
+    if (input.caption) form.append("caption", input.caption);
+    const sessionId = input.sessionId ?? this.sessionId;
+    if (sessionId) form.append("sessionId", sessionId);
+    const res = await this.request("POST", "/api/v1/send/media", { body: form });
+    return { id: res.id };
+  }
+  /** Conveniencia para Node: lee un archivo del disco y lo envía. */
+  async sendMediaFile(input) {
+    const { readFile } = await import("fs/promises");
+    const data = await readFile(input.path);
+    const mimeType = input.mimeType ?? inferMime(input.path);
+    if (!mimeType) throw new Error(`No se pudo inferir el MIME de "${input.path}" \u2014 pas\xE1 mimeType.`);
+    const filename = input.path.split(/[\\/]/).pop() ?? "file";
+    return this.sendMedia({
+      to: input.to,
+      data: new Uint8Array(data),
+      mimeType,
+      filename,
+      caption: input.caption,
+      sessionId: input.sessionId
+    });
+  }
+  /** Estado actual de un mensaje (queued/sending/sent/delivered/read/failed). */
+  async getStatus(id) {
+    const res = await this.request("GET", `/api/v1/status/${encodeURIComponent(id)}`);
+    return res;
+  }
+  /** Sesiones que el token puede usar. */
+  async listSessions() {
+    const res = await this.request("GET", "/api/v1/sessions");
+    return res.sessions ?? [];
+  }
+  /**
+   * Pollea getStatus() hasta que el mensaje llegue a un estado terminal
+   * (sent/delivered/read/failed) o se agote el tiempo. Backoff: 1s,2s,3s,5s,8s...
+   */
+  async waitUntilSent(id, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 6e4);
+    const target = opts.minStatus ?? "sent";
+    const rank = { queued: 0, sending: 1, sent: 2, delivered: 3, read: 4 };
+    const delays = [1e3, 2e3, 3e3, 5e3, 8e3];
+    let attempt = 0;
+    for (; ; ) {
+      const s = await this.getStatus(id);
+      if (s.status === "failed") return s;
+      if ((rank[s.status] ?? 0) >= (rank[target] ?? 2)) return s;
+      if (!TERMINAL_STATUSES.has(s.status) && Date.now() >= deadline) return s;
+      const wait = delays[Math.min(attempt, delays.length - 1)] ?? 8e3;
+      if (Date.now() + wait > deadline) return s;
+      await sleep(wait);
+      attempt++;
+    }
+  }
+  /** Crea un manejador de OTP (validación de número por código) atado a este cliente. */
+  otp(opts = {}) {
+    return new OtpManager(this, { sessionId: this.sessionId, ...opts });
+  }
+  async request(method, path, init = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${this.token}`, ...init.headers },
+        body: init.body,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        throw new MisterBotError(408, "request_timeout", `La request super\xF3 ${this.timeoutMs}ms`);
+      }
+      throw new MisterBotError(0, "network_error", String(err?.message ?? err));
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json = {};
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = {};
+      }
+    }
+    if (!res.ok) {
+      const code = json.statusMessage || json.message || `http_${res.status}`;
+      throw new MisterBotError(res.status, code, json.message || code);
+    }
+    return json;
+  }
+};
+function toBlob(data, mimeType) {
+  if (typeof Blob !== "undefined" && data instanceof Blob) return data;
+  if (data instanceof ArrayBuffer) return new Blob([data], { type: mimeType });
+  if (ArrayBuffer.isView(data)) {
+    return new Blob([data], { type: mimeType });
+  }
+  throw new Error("data debe ser Blob, ArrayBuffer o ArrayBufferView (Buffer/Uint8Array)");
+}
+function inferMime(path) {
+  const ext = path.split(".").pop()?.toLowerCase() ?? "";
+  return EXT_MIME[ext];
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+export {
+  MemoryCodeStore,
+  MisterBotClient,
+  MisterBotError,
+  OtpManager
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "misterbot",
+  "version": "0.1.0",
+  "description": "SDK oficial de Mister Bot: envío de mensajes de WhatsApp con cola anti-ban y verificación de número por código (OTP).",
+  "keywords": [
+    "whatsapp",
+    "baileys",
+    "otp",
+    "verification",
+    "mister-bot",
+    "sdk"
+  ],
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target node18",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}