wppapi-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IPRoute Tecnologia
+
+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,103 @@
+# WPPAPI — SDK JavaScript
+
+SDK oficial da [WPPAPI](https://wpp-api.com?utm_source=github&utm_medium=sdk) — API WhatsApp multi-tenant, gerenciada e dev-friendly. Envie e receba mensagens de WhatsApp via REST, com webhooks assinados (HMAC), integração nativa com Chatwoot e painel self-service.
+
+- **Zero dependências** — usa `fetch` nativo (browser e Node 18+)
+- **Trial de 3 dias grátis, sem cartão** → [criar conta](https://app.wpp-api.com/signup?utm_source=github&utm_medium=sdk)
+- Base da API: `https://api.wpp-api.com`
+
+## Instalação
+
+```bash
+npm install github:iproute-tecnologia/wppapi-sdk-js
+```
+
+Ou copie o `index.js` — é um arquivo único, sem dependências.
+
+## Uso
+
+```js
+import { WppApiClient } from "wppapi-sdk";
+
+const client = new WppApiClient({
+  baseUrl: "https://api.wpp-api.com",
+  instanceId: "sua-instancia",
+  token: "seu-token",
+});
+
+// Texto
+await client.sendText("5511999999999", "Olá! 👋");
+
+// Imagem por URL, com legenda
+await client.sendImage("5511999999999", "https://exemplo.com/foto.jpg", "Olha isso");
+
+// Documento em base64
+await client.sendFile("5511999999999", {
+  data: "<base64 sem prefixo data:>",
+  mimetype: "application/pdf",
+  filename: "proposta.pdf",
+});
+
+// Validar número antes de enviar
+const { exists } = await client.checkNumber("5511999999999");
+
+// Sessão
+await client.status();   // conectada? pareando?
+await client.qrCode();   // QR para parear
+await client.me();       // perfil conectado
+```
+
+### Token no header (em vez da URL)
+
+Para ambientes onde URLs vão para logs, envie o token via header `Client-Token`:
+
+```js
+const client = new WppApiClient({
+  baseUrl: "https://api.wpp-api.com",
+  instanceId: "sua-instancia",
+  token: "seu-token",
+  clientTokenHeader: true,
+});
+```
+
+## Métodos
+
+| Método | Endpoint |
+|--------|----------|
+| `status()` | `GET /status` |
+| `qrCode()` | `GET /qr-code` |
+| `me()` | `GET /me` |
+| `sendText(phone, message)` | `POST /send-text` |
+| `sendImage(phone, image, caption?)` | `POST /send-image` |
+| `sendFile(phone, file, caption?)` | `POST /send-file` |
+| `sendVoice(phone, audio)` | `POST /send-voice` |
+| `sendVideo(phone, video, caption?)` | `POST /send-video` |
+| `checkNumber(phone)` | `GET /check-number` |
+| `chats(limit?)` | `GET /chats` |
+| `groups()` | `GET /groups` |
+
+A API completa (location, contact, reply, reaction, typing, seen, sticker, poll, list, status/stories, edit, pin) está documentada em [wpp-api.com/docs](https://wpp-api.com/docs?utm_source=github&utm_medium=sdk) e no Swagger do painel.
+
+## Recebendo mensagens (webhooks)
+
+Cadastre uma URL de webhook no painel e receba eventos assinados com HMAC-SHA256 (`X-WPPAPI-Signature`). Exemplo completo de receptor em Node.js com validação de assinatura: [guia de webhooks](https://wpp-api.com/guias/webhooks-whatsapp-nodejs?utm_source=github&utm_medium=sdk).
+
+```js
+// Payload de mensagem recebida
+{
+  "event": "received",
+  "instanceId": "sua-instancia",
+  "timestamp": "2026-07-23T15:00:00.000Z",
+  "data": { "from": "5511999999999", "body": "oi", "type": "chat", "fromMe": false }
+}
+```
+
+## Guias
+
+- [WhatsApp no n8n](https://wpp-api.com/guias/whatsapp-n8n?utm_source=github&utm_medium=sdk)
+- [Chatwoot + WhatsApp (integração nativa)](https://wpp-api.com/guias/whatsapp-chatwoot?utm_source=github&utm_medium=sdk)
+- [Webhooks com HMAC em Node.js](https://wpp-api.com/guias/webhooks-whatsapp-nodejs?utm_source=github&utm_medium=sdk)
+
+## Licença
+
+[MIT](./LICENSE) © IPRoute Tecnologia

package/index.d.ts

@@ -0,0 +1,60 @@
+export interface WppApiClientOptions {
+  /** Base da API, ex.: https://api.wpp-api.com */
+  baseUrl: string;
+  /** ID público da instância */
+  instanceId: string;
+  /** Token da instância */
+  token: string;
+  /** Envia o token no header `Client-Token` em vez da URL */
+  clientTokenHeader?: boolean;
+}
+
+export interface MediaFile {
+  /** URL pública do arquivo */
+  url?: string;
+  /** Conteúdo em base64 (sem prefixo data:) */
+  data?: string;
+  mimetype?: string;
+  filename?: string;
+}
+
+export type MediaInput = string | MediaFile;
+
+export declare class WppApiClient {
+  constructor(options: WppApiClientOptions);
+
+  /** Status da sessão (conectada, pareando, desconectada). */
+  status(): Promise<Record<string, unknown>>;
+
+  /** QR Code para parear o número. */
+  qrCode(): Promise<Record<string, unknown>>;
+
+  /** Perfil do número conectado. */
+  me(): Promise<Record<string, unknown>>;
+
+  /** Envia mensagem de texto. */
+  sendText(phone: string, message: string): Promise<Record<string, unknown>>;
+
+  /** Envia imagem com legenda opcional. */
+  sendImage(phone: string, image: MediaInput, caption?: string): Promise<Record<string, unknown>>;
+
+  /** Envia arquivo/documento. */
+  sendFile(phone: string, file: MediaInput, caption?: string): Promise<Record<string, unknown>>;
+
+  /** Envia áudio/voz. */
+  sendVoice(phone: string, audio: MediaInput): Promise<Record<string, unknown>>;
+
+  /** Envia vídeo com legenda opcional. */
+  sendVideo(phone: string, video: MediaInput, caption?: string): Promise<Record<string, unknown>>;
+
+  /** Verifica se o número tem WhatsApp antes de enviar. */
+  checkNumber(phone: string): Promise<Record<string, unknown>>;
+
+  /** Lista os chats da instância. */
+  chats(limit?: number): Promise<Record<string, unknown>[]>;
+
+  /** Lista os grupos da instância. */
+  groups(): Promise<Record<string, unknown>[]>;
+}
+
+export default WppApiClient;

package/index.js

@@ -0,0 +1,138 @@
+/**
+ * WPPAPI JS SDK — cliente mínimo para o gateway público da WPPAPI.
+ * https://wpp-api.com
+ *
+ * Zero dependências: usa fetch nativo (browser / Node 18+).
+ *
+ * @example
+ *   import { WppApiClient } from "wppapi-sdk";
+ *
+ *   const client = new WppApiClient({
+ *     baseUrl: "https://api.wpp-api.com",
+ *     instanceId: "sua-instancia",
+ *     token: "seu-token",
+ *   });
+ *
+ *   await client.sendText("5511999999999", "Olá! 👋");
+ */
+export class WppApiClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl - Base da API, ex.: https://api.wpp-api.com
+   * @param {string} opts.instanceId - ID público da instância
+   * @param {string} opts.token - Token da instância
+   * @param {boolean} [opts.clientTokenHeader=false] - Envia o token no header
+   *   `Client-Token` em vez da URL (recomendado em ambientes com logs de URL)
+   */
+  constructor({ baseUrl, instanceId, token, clientTokenHeader = false }) {
+    if (!baseUrl || !instanceId || !token) {
+      throw new Error("baseUrl, instanceId e token são obrigatórios");
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.instanceId = instanceId;
+    this.token = token;
+    this.clientTokenHeader = clientTokenHeader;
+  }
+
+  path(suffix) {
+    const t = this.clientTokenHeader ? "_" : this.token;
+    return `${this.baseUrl}/instances/${this.instanceId}/token/${t}${suffix}`;
+  }
+
+  headers(json = true) {
+    const h = {};
+    if (json) h["Content-Type"] = "application/json";
+    if (this.clientTokenHeader) h["Client-Token"] = this.token;
+    return h;
+  }
+
+  async request(method, suffix, body) {
+    const res = await fetch(this.path(suffix), {
+      method,
+      headers: this.headers(body !== undefined),
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(err || res.statusText);
+    }
+    return res.json();
+  }
+
+  /** Status da sessão (conectada, pareando, desconectada). */
+  status() {
+    return this.request("GET", "/status");
+  }
+
+  /** QR Code para parear o número. */
+  qrCode() {
+    return this.request("GET", "/qr-code");
+  }
+
+  /** Perfil do número conectado. */
+  me() {
+    return this.request("GET", "/me");
+  }
+
+  /** Envia mensagem de texto. */
+  sendText(phone, message) {
+    return this.request("POST", "/send-text", { phone, message });
+  }
+
+  /**
+   * Envia imagem com legenda opcional.
+   * @param {string|{url?: string, data?: string, mimetype?: string, filename?: string}} image
+   *   URL da imagem, ou objeto file com `data` em base64 (sem prefixo data:)
+   */
+  sendImage(phone, image, caption) {
+    const body =
+      typeof image === "string" ? { phone, image, caption } : { phone, file: image, caption };
+    return this.request("POST", "/send-image", body);
+  }
+
+  /**
+   * Envia arquivo/documento.
+   * @param {string|{url?: string, data?: string, mimetype?: string, filename?: string}} file
+   */
+  sendFile(phone, file, caption) {
+    const body =
+      typeof file === "string" ? { phone, document: file, caption } : { phone, file, caption };
+    return this.request("POST", "/send-file", body);
+  }
+
+  /**
+   * Envia áudio/voz.
+   * @param {string|{url?: string, data?: string, mimetype?: string, filename?: string}} audio
+   */
+  sendVoice(phone, audio) {
+    const body = typeof audio === "string" ? { phone, audio } : { phone, file: audio };
+    return this.request("POST", "/send-voice", body);
+  }
+
+  /**
+   * Envia vídeo com legenda opcional.
+   * @param {string|{url?: string, data?: string, mimetype?: string, filename?: string}} video
+   */
+  sendVideo(phone, video, caption) {
+    const body =
+      typeof video === "string" ? { phone, video, caption } : { phone, file: video, caption };
+    return this.request("POST", "/send-video", body);
+  }
+
+  /** Verifica se o número tem WhatsApp antes de enviar. */
+  checkNumber(phone) {
+    return this.request("GET", `/check-number?phone=${encodeURIComponent(phone)}`);
+  }
+
+  /** Lista os chats da instância. */
+  chats(limit = 50) {
+    return this.request("GET", `/chats?limit=${limit}`);
+  }
+
+  /** Lista os grupos da instância. */
+  groups() {
+    return this.request("GET", "/groups");
+  }
+}
+
+export default WppApiClient;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "wppapi-sdk",
+  "version": "0.2.0",
+  "description": "SDK JavaScript oficial da WPPAPI — API WhatsApp multi-tenant (envio de texto e mídia, status, webhooks). Zero dependências, browser e Node 18+.",
+  "keywords": [
+    "whatsapp",
+    "whatsapp-api",
+    "api-whatsapp",
+    "wppapi",
+    "chatbot",
+    "automacao",
+    "n8n",
+    "chatwoot"
+  ],
+  "homepage": "https://wpp-api.com?utm_source=npm&utm_medium=sdk",
+  "bugs": {
+    "url": "https://github.com/iproute-tecnologia/wppapi-sdk-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iproute-tecnologia/wppapi-sdk-js.git"
+  },
+  "license": "MIT",
+  "author": "IPRoute Tecnologia <contato@wpp-api.com>",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}