@open-apime/sdk 0.4.0 → 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/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.4.0",
+  "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"
   ],