@open-apime/sdk 0.4.0 → 0.5.0

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

@@ -490,6 +490,18 @@ var MessagesResource = class {
     form.set("file", input.file, input.filename ?? fileName(input.file, "media"));
     return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
   }
+  sendGif(input, options) {
+    const form = toForm(input, ["file", "filename"]);
+    form.set("type", "gif");
+    form.set("file", input.file, input.filename ?? fileName(input.file, "animation.mp4"));
+    return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
+  }
+  sendSticker(input, options) {
+    const form = toForm(input, ["file", "filename"]);
+    form.set("type", "sticker");
+    form.set("file", input.file, input.filename ?? fileName(input.file, "sticker.webp"));
+    return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
+  }
   sendAudio(input, options) {
     const form = toForm(input, ["file", "filename"]);
     form.set("file", input.file, input.filename ?? fileName(input.file, "audio.ogg"));

package/dist/index.d.cts

@@ -230,6 +230,32 @@ interface SendMediaInput extends QuoteInput, MarkReadInput {
     filename?: string;
     caption?: string;
 }
+/**
+ * A GIF on WhatsApp is an MP4 VIDEO carrying the gif-playback flag, which is what makes the client
+ * loop it with no controls. Sending a real `.gif` file arrives as a still image, so it gets a method
+ * of its own rather than a `type` on sendMedia: the name is what warns the caller at the call site.
+ */
+interface SendGifInput extends QuoteInput, MarkReadInput {
+    to: string;
+    /** MP4 bytes. A `.gif` file is NOT what WhatsApp expects here. */
+    file: Blob | File;
+    filename?: string;
+    caption?: string;
+}
+/**
+ * WhatsApp takes stickers as WebP 512x512, up to 500 KB, transparent background; animated ones are
+ * animated WebP. The server validates and refuses outside that, because a sticker off-spec is
+ * accepted by the wire and then fails to render, with nothing reporting it.
+ *
+ * There is no caption: the protocol has no such field on a sticker, so one would be dropped in
+ * silence. That is why this does not reuse `SendMediaInput`.
+ */
+interface SendStickerInput extends QuoteInput, MarkReadInput {
+    to: string;
+    /** WebP bytes, 512x512, up to 500 KB. */
+    file: Blob | File;
+    filename?: string;
+}
 interface SendAudioInput extends QuoteInput, MarkReadInput {
     to: string;
     file: Blob | File;
@@ -275,6 +301,8 @@ declare class MessagesResource {
     private get base();
     sendText(input: SendTextInput, options?: RequestOptions): Promise<SentMessage>;
     sendMedia(input: SendMediaInput, options?: RequestOptions): Promise<SentMessage>;
+    sendGif(input: SendGifInput, options?: RequestOptions): Promise<SentMessage>;
+    sendSticker(input: SendStickerInput, options?: RequestOptions): Promise<SentMessage>;
     sendAudio(input: SendAudioInput, options?: RequestOptions): Promise<SentMessage>;
     sendDocument(input: SendDocumentInput, options?: RequestOptions): Promise<SentMessage>;
     sendContact(input: SendContactInput, options?: RequestOptions): Promise<SentMessage>;
@@ -535,4 +563,4 @@ interface HealthResult {
 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 };
+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 SendGifInput, type SendLocationInput, type SendMediaInput, type SendStickerInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, checkHealth, hasSentry };

package/dist/index.d.ts

@@ -230,6 +230,32 @@ interface SendMediaInput extends QuoteInput, MarkReadInput {
     filename?: string;
     caption?: string;
 }
+/**
+ * A GIF on WhatsApp is an MP4 VIDEO carrying the gif-playback flag, which is what makes the client
+ * loop it with no controls. Sending a real `.gif` file arrives as a still image, so it gets a method
+ * of its own rather than a `type` on sendMedia: the name is what warns the caller at the call site.
+ */
+interface SendGifInput extends QuoteInput, MarkReadInput {
+    to: string;
+    /** MP4 bytes. A `.gif` file is NOT what WhatsApp expects here. */
+    file: Blob | File;
+    filename?: string;
+    caption?: string;
+}
+/**
+ * WhatsApp takes stickers as WebP 512x512, up to 500 KB, transparent background; animated ones are
+ * animated WebP. The server validates and refuses outside that, because a sticker off-spec is
+ * accepted by the wire and then fails to render, with nothing reporting it.
+ *
+ * There is no caption: the protocol has no such field on a sticker, so one would be dropped in
+ * silence. That is why this does not reuse `SendMediaInput`.
+ */
+interface SendStickerInput extends QuoteInput, MarkReadInput {
+    to: string;
+    /** WebP bytes, 512x512, up to 500 KB. */
+    file: Blob | File;
+    filename?: string;
+}
 interface SendAudioInput extends QuoteInput, MarkReadInput {
     to: string;
     file: Blob | File;
@@ -275,6 +301,8 @@ declare class MessagesResource {
     private get base();
     sendText(input: SendTextInput, options?: RequestOptions): Promise<SentMessage>;
     sendMedia(input: SendMediaInput, options?: RequestOptions): Promise<SentMessage>;
+    sendGif(input: SendGifInput, options?: RequestOptions): Promise<SentMessage>;
+    sendSticker(input: SendStickerInput, options?: RequestOptions): Promise<SentMessage>;
     sendAudio(input: SendAudioInput, options?: RequestOptions): Promise<SentMessage>;
     sendDocument(input: SendDocumentInput, options?: RequestOptions): Promise<SentMessage>;
     sendContact(input: SendContactInput, options?: RequestOptions): Promise<SentMessage>;
@@ -535,4 +563,4 @@ interface HealthResult {
 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 };
+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 SendGifInput, type SendLocationInput, type SendMediaInput, type SendStickerInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, checkHealth, hasSentry };

package/dist/index.js

@@ -419,6 +419,18 @@ var MessagesResource = class {
     form.set("file", input.file, input.filename ?? fileName(input.file, "media"));
     return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
   }
+  sendGif(input, options) {
+    const form = toForm(input, ["file", "filename"]);
+    form.set("type", "gif");
+    form.set("file", input.file, input.filename ?? fileName(input.file, "animation.mp4"));
+    return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
+  }
+  sendSticker(input, options) {
+    const form = toForm(input, ["file", "filename"]);
+    form.set("type", "sticker");
+    form.set("file", input.file, input.filename ?? fileName(input.file, "sticker.webp"));
+    return this.http.request({ method: "POST", path: `${this.base}/media`, body: form, ...options ? { options } : {} });
+  }
   sendAudio(input, options) {
     const form = toForm(input, ["file", "filename"]);
     form.set("file", input.file, input.filename ?? fileName(input.file, "audio.ogg"));

package/docs/guia.md

@@ -0,0 +1,225 @@
+# 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 },
+);
+
+// GIF é MP4 com reprodução em laço, não arquivo .gif: mandar um .gif de verdade
+// faz a mensagem chegar como imagem parada.
+await conexao.messages.sendGif(
+  { to: "5511999999999", file: mp4Blob },
+  { idempotencyKey: mensagem.id },
+);
+
+// Figurinha exige WebP 512x512 até 500 KB (animada ou não), e não tem legenda:
+// o protocolo não traz esse campo. Fora da especificação, o apime recusa com 400.
+await conexao.messages.sendSticker(
+  { to: "5511999999999", file: webpBlob },
+  { 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.5.0",
   "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"
   ],