@open-apime/sdk 0.3.1 → 0.4.1

package/README.md

@@ -32,8 +32,8 @@ await conexao.messages.sendText(
 
 | | |
 |---|---|
-| [Guia de uso](https://github.com/open-apime/sdk/blob/main/docs/guia.md) | clientes, envio, erros, retry, observabilidade e webhook |
-| [Segurança](https://github.com/open-apime/sdk/blob/main/docs/seguranca.md) | o que o SDK protege, e como |
+| [Guia de uso](docs/guia.md) | clientes, envio, erros, retry, observabilidade e webhook |
+| [Segurança](docs/seguranca.md) | o que o SDK protege, e como |
 | [openapi.yaml](https://github.com/open-apime/apime/blob/main/openapi.yaml) | contrato da API |
 | [webhook-payloads.md](https://github.com/open-apime/apime/blob/main/docs/webhook-payloads.md) | os 12 eventos |
 

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   ConfigurationError: () => ConfigurationError,
   ConflictError: () => ConflictError,
   ConnectionError: () => ConnectionError,
+  DEFAULT_HEALTH_TIMEOUT_MS: () => DEFAULT_HEALTH_TIMEOUT_MS,
   InvalidRequestError: () => InvalidRequestError,
   InvalidSignatureError: () => InvalidSignatureError,
   NotFoundError: () => NotFoundError,
@@ -37,6 +38,7 @@ __export(index_exports, {
   SessionUnavailableError: () => SessionUnavailableError,
   TimeoutError: () => TimeoutError,
   UnprocessableError: () => UnprocessableError,
+  checkHealth: () => checkHealth,
   constructEvent: () => constructEvent,
   hasSentry: () => hasSentry,
   verifyWebhookSignature: () => verifyWebhookSignature
@@ -785,6 +787,31 @@ var Apime = {
   }
 };
 
+// src/health.ts
+var DEFAULT_HEALTH_TIMEOUT_MS = 1e4;
+async function checkHealth(baseUrl, options = {}) {
+  const url = buildUrl(assertUsableBaseUrl(baseUrl), "/healthz");
+  const impl = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await impl(url, { method: "GET", signal: controller.signal });
+    if (!response.ok) {
+      throw new ApimeError(`apime respondeu ${response.status} no healthz`, { status: response.status });
+    }
+    return await response.json();
+  } catch (cause) {
+    if (cause instanceof ApimeError) throw cause;
+    if (controller.signal.aborted) {
+      throw new TimeoutError(`o healthz passou de ${timeoutMs}ms`, { cause });
+    }
+    throw new ConnectionError("falha de rede ao falar com o apime", { cause });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/webhook/index.ts
 var import_node_crypto = require("crypto");
 var InvalidSignatureError = class extends ApimeError {
@@ -822,6 +849,7 @@ function constructEvent(rawBody, signature, secret) {
   ConfigurationError,
   ConflictError,
   ConnectionError,
+  DEFAULT_HEALTH_TIMEOUT_MS,
   InvalidRequestError,
   InvalidSignatureError,
   NotFoundError,
@@ -830,6 +858,7 @@ function constructEvent(rawBody, signature, secret) {
   SessionUnavailableError,
   TimeoutError,
   UnprocessableError,
+  checkHealth,
   constructEvent,
   hasSentry,
   verifyWebhookSignature

package/dist/index.d.cts

@@ -523,4 +523,16 @@ declare const Apime: {
     }, options: ClientOptions): ApimeInstanceClient;
 };
 
-export { type ApiToken, type ApiTokenAuth, Apime, ApimeError, ApimeInstanceClient, ApimeUserClient, type Auth, type AuthKind, type CheckNumberResult, type ClientOptions, type ContactEntry, type CreateInstanceInput, EventLogEntry, type FailureInfo, type GroupInfo, type GroupParticipant, Instance, InstanceInfo, type InstanceTokenAuth, type IpFamily, type JoinRequestAction, type MarkReadInput, type Observer, type ParticipantAction, type PresenceState, Profile, QrCode, type QuoteInput, type RequestInfo, type RequestOptions, type SendAudioInput, type SendContactInput, type SendDocumentInput, type SendLocationInput, type SendMediaInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, hasSentry };
+interface HealthOptions {
+    /** Kept short on purpose: a health check that hangs is worse than one that fails. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+interface HealthResult {
+    status?: string;
+    [key: string]: unknown;
+}
+declare const DEFAULT_HEALTH_TIMEOUT_MS = 10000;
+declare function checkHealth(baseUrl: string, options?: HealthOptions): Promise<HealthResult>;
+
+export { type ApiToken, type ApiTokenAuth, Apime, ApimeError, ApimeInstanceClient, ApimeUserClient, type Auth, type AuthKind, type CheckNumberResult, type ClientOptions, type ContactEntry, type CreateInstanceInput, DEFAULT_HEALTH_TIMEOUT_MS, EventLogEntry, type FailureInfo, type GroupInfo, type GroupParticipant, type HealthOptions, type HealthResult, Instance, InstanceInfo, type InstanceTokenAuth, type IpFamily, type JoinRequestAction, type MarkReadInput, type Observer, type ParticipantAction, type PresenceState, Profile, QrCode, type QuoteInput, type RequestInfo, type RequestOptions, type SendAudioInput, type SendContactInput, type SendDocumentInput, type SendLocationInput, type SendMediaInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, checkHealth, hasSentry };

package/dist/index.d.ts

@@ -523,4 +523,16 @@ declare const Apime: {
     }, options: ClientOptions): ApimeInstanceClient;
 };
 
-export { type ApiToken, type ApiTokenAuth, Apime, ApimeError, ApimeInstanceClient, ApimeUserClient, type Auth, type AuthKind, type CheckNumberResult, type ClientOptions, type ContactEntry, type CreateInstanceInput, EventLogEntry, type FailureInfo, type GroupInfo, type GroupParticipant, Instance, InstanceInfo, type InstanceTokenAuth, type IpFamily, type JoinRequestAction, type MarkReadInput, type Observer, type ParticipantAction, type PresenceState, Profile, QrCode, type QuoteInput, type RequestInfo, type RequestOptions, type SendAudioInput, type SendContactInput, type SendDocumentInput, type SendLocationInput, type SendMediaInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, hasSentry };
+interface HealthOptions {
+    /** Kept short on purpose: a health check that hangs is worse than one that fails. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+interface HealthResult {
+    status?: string;
+    [key: string]: unknown;
+}
+declare const DEFAULT_HEALTH_TIMEOUT_MS = 10000;
+declare function checkHealth(baseUrl: string, options?: HealthOptions): Promise<HealthResult>;
+
+export { type ApiToken, type ApiTokenAuth, Apime, ApimeError, ApimeInstanceClient, ApimeUserClient, type Auth, type AuthKind, type CheckNumberResult, type ClientOptions, type ContactEntry, type CreateInstanceInput, DEFAULT_HEALTH_TIMEOUT_MS, EventLogEntry, type FailureInfo, type GroupInfo, type GroupParticipant, type HealthOptions, type HealthResult, Instance, InstanceInfo, type InstanceTokenAuth, type IpFamily, type JoinRequestAction, type MarkReadInput, type Observer, type ParticipantAction, type PresenceState, Profile, QrCode, type QuoteInput, type RequestInfo, type RequestOptions, type SendAudioInput, type SendContactInput, type SendDocumentInput, type SendLocationInput, type SendMediaInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, checkHealth, hasSentry };

package/dist/index.js

@@ -715,6 +715,31 @@ var Apime = {
     );
   }
 };
+
+// src/health.ts
+var DEFAULT_HEALTH_TIMEOUT_MS = 1e4;
+async function checkHealth(baseUrl, options = {}) {
+  const url = buildUrl(assertUsableBaseUrl(baseUrl), "/healthz");
+  const impl = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await impl(url, { method: "GET", signal: controller.signal });
+    if (!response.ok) {
+      throw new ApimeError(`apime respondeu ${response.status} no healthz`, { status: response.status });
+    }
+    return await response.json();
+  } catch (cause) {
+    if (cause instanceof ApimeError) throw cause;
+    if (controller.signal.aborted) {
+      throw new TimeoutError(`o healthz passou de ${timeoutMs}ms`, { cause });
+    }
+    throw new ConnectionError("falha de rede ao falar com o apime", { cause });
+  } finally {
+    clearTimeout(timer);
+  }
+}
 export {
   ApiError,
   Apime,
@@ -725,6 +750,7 @@ export {
   ConfigurationError,
   ConflictError,
   ConnectionError,
+  DEFAULT_HEALTH_TIMEOUT_MS,
   InvalidRequestError,
   InvalidSignatureError,
   NotFoundError,
@@ -733,6 +759,7 @@ export {
   SessionUnavailableError,
   TimeoutError,
   UnprocessableError,
+  checkHealth,
   constructEvent,
   hasSentry,
   verifyWebhookSignature

package/docs/guia.md

@@ -0,0 +1,211 @@
+# Guia do `@open-apime/sdk`
+
+Referência de uso. O [README](../README.md) tem o resumo e a instalação.
+
+## Os três tokens decidem o que você pode chamar
+
+A API do apime não é uniforme: 46 rotas só aceitam token de instância, 13 só aceitam token de
+usuário. Por isso o SDK tem **dois clientes**, e o que você constrói define o que o compilador
+deixa chamar. Sem isso, o erro só apareceria como `403` em produção.
+
+```ts
+import { Apime } from "@open-apime/sdk";
+
+// token de usuário: administra instâncias
+const admin = Apime.withApiToken(process.env.APIME_TOKEN!, {
+  baseUrl: "https://apime.example.com",
+});
+await admin.instances.list();
+
+// token de instância: opera UMA instância, e o id vem da credencial
+const conexao = Apime.withInstanceToken(
+  { token: process.env.INSTANCE_TOKEN!, instanceId: "abc-123" },
+  { baseUrl: "https://apime.example.com" },
+);
+await conexao.instance.info();
+```
+
+`admin.instance` não existe, e `conexao.instances.create()` também não. É erro de compilação, não
+de runtime.
+
+### O que cada cliente tem
+
+| Cliente | Recursos |
+|---|---|
+| `withApiToken` / `withUserJwt` | `instances`, `users` (exige admin), `tokens` |
+| `withInstanceToken` | `instance`, `messages`, `whatsapp` (com `.groups` e `.newsletters`) |
+
+## Enviando mensagem
+
+```ts
+await conexao.messages.sendText(
+  { to: "5511999999999", text: "Olá" },
+  { idempotencyKey: mensagem.id },
+);
+
+await conexao.messages.sendMedia(
+  { to: "5511999999999", type: "image", file: blob, caption: "Segue" },
+  { idempotencyKey: mensagem.id },
+);
+
+await conexao.whatsapp.groups.updateParticipants(grupoJid, {
+  action: "add",
+  participants: ["5511999999999@s.whatsapp.net"],
+});
+```
+
+## Erros
+
+Uma classe por condição, então dá para ramificar sem ler status code:
+
+```ts
+import { PermissionError, RateLimitError, SessionUnavailableError } from "@open-apime/sdk";
+
+try {
+  await conexao.instance.info();
+} catch (erro) {
+  if (erro instanceof SessionUnavailableError) {/* sessão não pronta, pode repetir */}
+  if (erro instanceof RateLimitError) {/* erro.retryAfterMs */}
+  if (erro instanceof PermissionError) {/* token errado para esta rota */}
+}
+```
+
+## Retry: por que o envio não retenta sozinho
+
+Leitura retenta com backoff exponencial e jitter. **Escrita não**, a menos que você passe uma
+`Idempotency-Key`, porque retentar um envio sem chave entrega a mesma mensagem duas vezes ao
+cliente final.
+
+```ts
+await conexao.request({
+  method: "POST",
+  path: `/instances/${conexao.instanceId}/messages/text`,
+  body: { to: "5511999999999", text: "Olá" },
+  // a MESMA chave na retentativa. Um id estável da sua mensagem serve melhor que um uuid novo.
+  options: { idempotencyKey: mensagem.id },
+});
+```
+
+A exceção é `503`: o apime devolve isso quando a sessão não está pronta, antes de tocar o WhatsApp,
+então nada saiu e o SDK repete mesmo sem chave.
+
+`4xx` (fora `408` e `429`) nunca retenta, porque tentar de novo não muda o resultado.
+
+## Observabilidade: vigiando o próprio SDK
+
+O SDK **não importa Sentry, nem OpenTelemetry, nem nada**, e mantém zero dependência de runtime.
+
+**Rodando com Sentry já iniciado no projeto, a falha definitiva é reportada sozinha.** O SDK acha o
+cliente global do `@sentry/node` sem importar o pacote, então não pina versão nem obriga ninguém.
+**Sem Sentry, não faz nada e não quebra.** Para calar, `autoReport: false`.
+
+Querendo controlar o que é reportado, o `observer` tem prioridade sobre o automático:
+
+```ts
+import * as Sentry from "@sentry/node";
+
+const conexao = Apime.withInstanceToken(credenciais, {
+  baseUrl,
+  appName: "meu-app",
+  observer: {
+    // Dispara em toda tentativa falha, inclusive as que serão repetidas.
+    onError: ({ error, route, method, status, instanceId, attempt, willRetry, idempotencyKey }) => {
+      if (willRetry) return;   // ainda vai tentar de novo, não é falha definitiva
+      Sentry.captureException(error, {
+        tags: { sdk: "open-apime", route, method, status: String(status) },
+        extra: { instanceId, attempt, idempotencyKey },
+      });
+    },
+  },
+});
+```
+
+A `route` vem **normalizada** (`/instances/{id}/profile/{jid}`), e não com os ids reais. Sem isso o
+error tracker criaria uma issue por instância e por contato, e o volume esconderia o problema.
+
+Os quatro ganchos: `onRequest`, `onSuccess`, `onError` e `onRetry`. Um observer que lança exceção
+**não derruba a requisição**: observabilidade nunca é motivo para perder um envio.
+
+## Health
+
+`/healthz` não pede credencial, então é função avulsa, e não método de cliente: exigir token para
+perguntar se o servidor está de pé seria ao contrário.
+
+```ts
+import { checkHealth } from "@open-apime/sdk";
+
+const health = await checkHealth("https://apime.example.com");  // { status: "ok", version, name }
+```
+
+Passa pelo mesmo guard anti-SSRF do resto, e o timeout é curto (10s), porque health que pendura é
+pior que health que falha.
+
+## Rede: forçar IPv4
+
+Host atrás de Cloudflare responde A e AAAA. Onde a rede não tem rota IPv6, o Node tenta os
+endereços v6 primeiro e colhe `ENETUNREACH` em cada um antes de chegar ao v4. Nada falha, mas o
+ruído acaba gravado no erro da mensagem que estava sendo enviada.
+
+```ts
+const conexao = Apime.withInstanceToken(credenciais, { baseUrl, ipFamily: 4 });
+```
+
+**Vale para o processo inteiro**, porque o Node não oferece esse ajuste por requisição: é o
+`dns.setDefaultResultOrder`. Por isso o SDK aplica **uma vez só**, na primeira vez que alguém pede,
+e ignora pedido conflitante depois. Sem `ipFamily`, o SDK não mexe na resolução do processo.
+
+## Webhook
+
+```ts
+import { constructEvent } from "@open-apime/sdk/webhook";
+
+app.post("/webhooks/apime", express.raw({ type: "application/json" }), (req, res) => {
+  let evento;
+  try {
+    // corpo CRU. JSON já parseado e reserializado quebra a assinatura.
+    evento = constructEvent(req.body, req.get("X-ApiMe-Signature"), process.env.WEBHOOK_SECRET!);
+  } catch {
+    return res.sendStatus(401);
+  }
+
+  switch (evento.type) {
+    case "message":
+      console.log(evento.payload.text);  // tipado, estreitado pelo `type`
+      break;
+    case "temporary_ban":
+      console.log(evento.payload.restrictedUntil);
+      break;
+  }
+  res.sendStatus(200);
+});
+```
+
+São **12 tipos de evento**. `reply`, `url`, `copy` e `call` **não** são eventos, são tipos de botão
+dentro de `payload.buttons[].type`.
+
+## Cobertura
+
+Cobre **as 66 operações** do contrato do apime. Ficam de fora `/auth/login`, que é como se obtém a
+credencial, e `/media/{instanceId}/{mediaId}`, que serve arquivo direto ao navegador.
+
+Para qualquer rota que o SDK ainda não tenha, `client.request()` fala com a API mantendo auth,
+retry e observabilidade.
+
+A API completa está no [openapi.yaml](https://github.com/open-apime/apime/blob/main/openapi.yaml)
+do apime, e os eventos em [webhook-payloads.md](https://github.com/open-apime/apime/blob/main/docs/webhook-payloads.md).
+
+Enquanto está em `0.x`, minor pode trazer mudança incompatível.
+
+## Segurança
+
+- **Sem sourcemap no pacote.** O `.map` embute o código-fonte inteiro em `sourcesContent`, então
+  publicá-lo entregaria a fonte junto do build. O fonte vive no GitHub, que é onde se lê.
+- **Segmento de path é escapado.** Id vindo do banco ou de entrada de usuário não escapa da rota:
+  sem isso, um id com `../` faria `/instances/{id}` cair em `/users/admin`.
+- **Guard anti-SSRF na `baseUrl`.** IP privado, loopback, link-local e endpoint de metadados de
+  nuvem são recusados antes de qualquer requisição.
+- **O token não aparece em erro.** Nem na mensagem, nem no corpo, nem no stack.
+- **O relato ao Sentry não leva telefone.** Vai a rota normalizada (`/instances/{id}/profile/{jid}`),
+  nunca o path real com o jid do contato.
+- **Verificação de webhook em tempo constante**, sobre o corpo cru.
+

package/docs/seguranca.md

@@ -0,0 +1,13 @@
+# Segurança do `@open-apime/sdk`
+
+- **Sem sourcemap no pacote.** O `.map` embute o código-fonte inteiro em `sourcesContent`, então
+  publicá-lo entregaria a fonte junto do build. O fonte vive no GitHub, que é onde se lê.
+- **Segmento de path é escapado.** Id vindo do banco ou de entrada de usuário não escapa da rota:
+  sem isso, um id com `../` faria `/instances/{id}` cair em `/users/admin`.
+- **Guard anti-SSRF na `baseUrl`.** IP privado, loopback, link-local e endpoint de metadados de
+  nuvem são recusados antes de qualquer requisição.
+- **O token não aparece em erro.** Nem na mensagem, nem no corpo, nem no stack.
+- **O relato ao Sentry não leva telefone.** Vai a rota normalizada (`/instances/{id}/profile/{jid}`),
+  nunca o path real com o jid do contato.
+- **Verificação de webhook em tempo constante**, sobre o corpo cru.
+

package/package.json

@@ -1,16 +1,8 @@
 {
   "name": "@open-apime/sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Cliente TypeScript da API do apime: WhatsApp, instâncias e webhooks",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/open-apime/sdk.git"
-  },
-  "homepage": "https://github.com/open-apime/sdk#readme",
-  "bugs": {
-    "url": "https://github.com/open-apime/sdk/issues"
-  },
   "keywords": [
     "apime",
     "whatsapp",
@@ -31,6 +23,7 @@
     "dist/**/*.cjs",
     "dist/**/*.d.ts",
     "dist/**/*.d.cts",
+    "docs/*.md",
     "README.md",
     "LICENSE"
   ],