@telepapo/sdk 0.1.0 → 0.2.0

package/README.md

@@ -27,8 +27,12 @@ if (evento.mensagem?.tipo === 'texto') await conta.enviarTexto(evento.mensagem.d
 
 API: `iniciarAutorizacao`, `concluirAutorizacao`, `conta(id)`,
 `processarWebhook`, `verificarAssinatura`; na conta: `receber`, `enviar`,
-`enviarTexto`, `marcarLida`, `reagir`, `garantirPreKeys`, `dados`,
-`desconectar`.
+`enviarTexto`, `enviarArquivo`, `subirAnexo`, `baixarAnexo`, `marcarLida`,
+`reagir`, `digitando`, `garantirPreKeys`, `dados`, `desconectar`.
+
+Mais de um processo usando as mesmas contas (API + worker, réplicas)? Passe
+`travar: (chave, f) => …` (ex.: um lock no Redis): o estado do Signal e o
+refresh token não aguentam dois escritores ao mesmo tempo.
 
 O Signal roda em WebAssembly (`signal/`, compilado do libsignal 0.105.4 —
 o mesmo do app, testado contra a biblioteca oficial).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telepapo/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK do TelePapo Developers: autorize contas comerciais e receba e responda mensagens com criptografia de ponta a ponta (Signal).",
   "type": "module",
   "main": "src/index.js",

package/src/anexos.js

@@ -0,0 +1,38 @@
+// Anexos no mesmo esquema do app e do TelePapo Web (o do Signal):
+// AES-256-CBC + HMAC-SHA256. A chave (64 bytes: 32 de AES, 32 de HMAC) e o
+// digest viajam só dentro da mensagem cifrada; o servidor guarda
+// `iv | cifrado | mac` e nada mais.
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+export function cifrarAnexo(dado, chave) {
+  const iv = randomBytes(16);
+  const c = createCipheriv('aes-256-cbc', chave.subarray(0, 32), iv);
+  const corpo = Buffer.concat([iv, c.update(dado), c.final()]);
+  const mac = createHmac('sha256', chave.subarray(32, 64)).update(corpo).digest();
+  return Buffer.concat([corpo, mac]);
+}
+
+export function decifrarAnexo(blob, chave) {
+  if (blob.length < 16 + 16 + 32) throw new Error('Anexo curto demais.');
+  const corpo = blob.subarray(0, blob.length - 32);
+  // MAC conferido ANTES de decifrar: CBC sem MAC aceita blob adulterado.
+  const mac = createHmac('sha256', chave.subarray(32, 64)).update(corpo).digest();
+  if (!timingSafeEqual(mac, blob.subarray(blob.length - 32))) throw new Error('Anexo adulterado (MAC).');
+  const d = createDecipheriv('aes-256-cbc', chave.subarray(0, 32), corpo.subarray(0, 16));
+  return Buffer.concat([d.update(corpo.subarray(16)), d.final()]);
+}
+
+/** Cifra e devolve o blob e o que vai na mensagem ({chave, digest} em base64). */
+export function prepararAnexo(dado) {
+  const chave = randomBytes(64);
+  const blob = cifrarAnexo(Buffer.from(dado), chave);
+  return { blob, chave: chave.toString('base64'), digest: createHash('sha256').update(blob).digest('base64') };
+}
+
+/** Confere o digest (vindo da mensagem cifrada) e decifra. */
+export function abrirAnexo(blob, anexo) {
+  const digest = createHash('sha256').update(blob).digest();
+  const esperado = Buffer.from(anexo.digest ?? '', 'base64');
+  if (digest.length !== esperado.length || !timingSafeEqual(digest, esperado)) throw new Error('Anexo adulterado (digest).');
+  return decifrarAnexo(blob, Buffer.from(anexo.chave, 'base64'));
+}

package/src/index.js

@@ -9,11 +9,13 @@ import { randomUUID } from 'node:crypto';
 import { ArmazenamentoArquivo, ArmazenamentoMemoria } from './armazenamento.js';
 import { verificarAssinatura } from './webhook.js';
 import { categoria, impressao } from './categoria.js';
+import { abrirAnexo, prepararAnexo } from './anexos.js';
 
 const require = createRequire(import.meta.url);
 const { Signal } = require('../signal/telepapo_signal.js');
 
 export { ArmazenamentoArquivo, ArmazenamentoMemoria, verificarAssinatura };
+export { cifrarAnexo, decifrarAnexo } from './anexos.js';
 
 export class ErroTelePapo extends Error {
   constructor(status, corpo) {
@@ -36,8 +38,12 @@ export class TelePapo {
    * @param {string} [o.chaveWebhook] chave de assinatura do webhook (portal)
    * @param {string} [o.apiUrl]      padrão https://api.telepapo.com.br
    * @param {object} [o.armazenamento] { ler, gravar, apagar } — padrão: memória
+   * @param {(chave: string, f: () => Promise<any>) => Promise<any>} [o.travar]
+   *   Trava ENTRE processos (ex.: Redis). Obrigatória se mais de um processo usa
+   *   a mesma conta: o estado do Signal e o refresh token não aguentam dois
+   *   escritores ao mesmo tempo. Sem ela, só a fila deste processo.
    */
-  constructor({ clientId, credencial, chaveWebhook, apiUrl = 'https://api.telepapo.com.br', armazenamento = new ArmazenamentoMemoria(), fetch = globalThis.fetch }) {
+  constructor({ clientId, credencial, chaveWebhook, apiUrl = 'https://api.telepapo.com.br', armazenamento = new ArmazenamentoMemoria(), fetch = globalThis.fetch, travar = null }) {
     if (!clientId || !credencial) throw new Error('clientId e credencial são obrigatórios.');
     this.clientId = clientId;
     this.credencial = credencial;
@@ -45,11 +51,12 @@ export class TelePapo {
     this.apiUrl = apiUrl.replace(/\/$/, '');
     this.armazenamento = armazenamento;
     this.fetch = fetch;
+    this.travar = travar;
     this.contas = new Map();
   }
 
   async http(metodo, caminho, { corpo, token, basic } = {}) {
-    const headers = { 'User-Agent': 'telepapo-sdk/0.1' };
+    const headers = { 'User-Agent': 'telepapo-sdk/0.2' };
     if (corpo !== undefined) headers['Content-Type'] = 'application/json';
     if (token) headers.Authorization = `Bearer ${token}`;
     if (basic) headers.Authorization = 'Basic ' + Buffer.from(`${this.clientId}:${this.credencial}`).toString('base64');
@@ -128,7 +135,8 @@ class Conta {
 
   /** Uma operação por vez por conta (o estado do Signal não pode ser usado por duas ao mesmo tempo). */
   trava(f) {
-    const vez = this.fila.then(f);
+    const externa = this.cliente.travar;
+    const vez = this.fila.then(() => (externa ? externa(`telepapo:conta:${this.id}`, f) : f()));
     this.fila = vez.catch(() => undefined);
     return vez;
   }
@@ -154,12 +162,20 @@ class Conta {
   }
 
   async token() {
+    const valido = (e) => new Date(e.tokens.acessoExpiraEm).getTime() - Date.now() > 60_000;
     const e = await this.estado();
-    if (new Date(e.tokens.acessoExpiraEm).getTime() - Date.now() > 60_000) return e.tokens.acesso;
-    const par = await this.cliente.http('POST', '/v1/auth/renovar', { corpo: { refresh: e.tokens.refresh } });
-    e.tokens = { acesso: par.acesso, refresh: par.refresh, acessoExpiraEm: par.acessoExpiraEm };
-    await this.gravar(e);
-    return par.acesso;
+    if (valido(e)) return e.tokens.acesso;
+    const renovar = async () => {
+      // Relê dentro da trava: outro processo pode ter acabado de renovar.
+      const atual = await this.estado();
+      if (valido(atual)) return atual.tokens.acesso;
+      const par = await this.cliente.http('POST', '/v1/auth/renovar', { corpo: { refresh: atual.tokens.refresh } });
+      atual.tokens = { acesso: par.acesso, refresh: par.refresh, acessoExpiraEm: par.acessoExpiraEm };
+      await this.gravar(atual);
+      return par.acesso;
+    };
+    const externa = this.cliente.travar;
+    return externa ? externa(`telepapo:token:${this.id}`, renovar) : renovar();
   }
 
   async api(metodo, caminho, corpo) {
@@ -260,7 +276,7 @@ class Conta {
     for (const n of [...(d.faltando ?? []), ...(d.desatualizados ?? [])]) await this.abrirSessoes(usuario, n);
   }
 
-  async enviar1a1(dest, c) {
+  async enviar1a1(dest, c, { efemero = false } = {}) {
     const claro = new TextEncoder().encode(JSON.stringify(c));
     const cat = categoria(c);
     const imp = await impressao(c);
@@ -269,7 +285,7 @@ class Conta {
       if (!comSessao.length) await this.abrirSessoes(dest);
       const envelopes = await this.cifrarPara(dest, claro);
       try {
-        await this.api('POST', `/v1/mensagens/${dest}`, { idCliente: c.id.replace(/-/g, ''), envelopes, categoria: cat, ...(imp ? { impressao: imp } : {}) });
+        await this.api('POST', `/v1/mensagens/${dest}`, { idCliente: c.id.replace(/-/g, ''), envelopes, categoria: cat, ...(imp ? { impressao: imp } : {}), ...(efemero ? { efemero: true } : {}) });
         return;
       } catch (e) {
         if (tentativa >= 3 || (e.status !== 409 && e.status !== 410)) throw e;
@@ -311,6 +327,67 @@ class Conta {
     return this.enviar(para, { tipo: 'reacao', alvo: mensagemId, emoji: emoji ?? '' });
   }
 
+  /** "Digitando…" (efêmero: só chega a quem estiver online; não vai para o celular do dono). */
+  digitando(para, ativo = true) {
+    return this.trava(async () => {
+      const c = { v: 1, id: randomUUID(), em: Date.now(), tipo: 'digitando', estado: ativo ? 'inicio' : 'fim' };
+      try {
+        await this.enviar1a1(para, c, { efemero: true });
+      } catch (e) {
+        if (!(e instanceof SemAparelho)) throw e;
+      }
+    });
+  }
+
+  // ------------------------------------------------------------ anexos
+
+  /**
+   * Cifra e sobe um arquivo; devolve o `anexo` para pôr numa mensagem `midia`.
+   * @param {Buffer|Uint8Array} dados
+   * @param {{mime: string, nome?: string, largura?: number, altura?: number, duracaoMs?: number, miniatura?: string}} info
+   */
+  async subirAnexo(dados, info = {}) {
+    if (!info.mime) throw new Error('Informe o mime do anexo.');
+    const { blob, chave, digest } = prepararAnexo(dados);
+    const { id } = await this.api('POST', '/v1/anexos', { tamanho: blob.length });
+    const token = await this.token();
+    const r = await this.cliente.fetch(`${this.cliente.apiUrl}/v1/anexos/${id}/conteudo`, {
+      method: 'PUT',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/octet-stream', 'User-Agent': 'telepapo-sdk/0.2' },
+      body: blob,
+    });
+    if (!r.ok) {
+      const texto = await r.text();
+      throw new ErroTelePapo(r.status, texto ? JSON.parse(texto) : null);
+    }
+    const extra = Object.fromEntries(['nome', 'largura', 'altura', 'duracaoMs', 'miniatura'].filter((k) => info[k] != null).map((k) => [k, info[k]]));
+    return { id, chave, digest, tamanho: Buffer.byteLength(Buffer.from(dados)), mime: info.mime, ...extra };
+  }
+
+  /** Baixa, confere e decifra o anexo de uma mensagem recebida (`mensagem.conteudo.anexo`). */
+  async baixarAnexo(anexo) {
+    const token = await this.token();
+    const r = await this.cliente.fetch(`${this.cliente.apiUrl}/v1/anexos/${encodeURIComponent(anexo.id)}`, {
+      headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'telepapo-sdk/0.2' },
+    });
+    if (!r.ok) {
+      const texto = await r.text();
+      throw new ErroTelePapo(r.status, texto ? JSON.parse(texto) : null);
+    }
+    return abrirAnexo(Buffer.from(await r.arrayBuffer()), anexo);
+  }
+
+  /**
+   * Envia um arquivo (foto, vídeo, áudio, documento). A mensagem de mídia do
+   * TelePapo não tem legenda: `legenda`, se houver, vai logo depois como texto.
+   */
+  async enviarArquivo(para, dados, { mime, nome, largura, altura, duracaoMs, miniatura, legenda, resposta } = {}) {
+    const anexo = await this.subirAnexo(dados, { mime, nome, largura, altura, duracaoMs, miniatura });
+    const r = await this.enviar(para, { tipo: 'midia', anexo, ...(resposta ? { resposta } : {}) });
+    if (legenda?.trim()) await this.enviarTexto(para, legenda);
+    return { ...r, anexo };
+  }
+
   /** Repõe as pré-chaves do aparelho quando o estoque no servidor baixa (rode de tempos em tempos). */
   async garantirPreKeys() {
     const c = await this.api('GET', '/v1/chaves/contagem');