@telepapo/sdk 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telepapo/sdk",
-  "version": "0.2.0",
+  "version": "0.4.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/botoes.js

@@ -0,0 +1,111 @@
+/**
+ * Botões nas mensagens (só conta comercial; ver docs/MENSAGENS-RICAS.md no
+ * repositório do TelePapo). As mesmas regras valem no app Android e no web:
+ * quem recebe descarta o botão que não passa nelas.
+ *
+ *   { id, tipo: 'resposta' | 'link' | 'telefone', rotulo, url?, telefone? }
+ */
+
+export const MAX_BOTOES = 3;
+export const MAX_ROTULO = 25;
+export const MAX_LEGENDA = 1024;
+
+// Controles invisíveis (direção do texto e afins) disfarçam texto e links.
+const CONTROLES = /[\u0000-\u0008\u000B-\u001F\u007F‪-‮⁦-⁩]/g;
+
+/** Tira caracteres de controle e de direção (mantém \n e \t). */
+export function limparTexto(texto) {
+  return String(texto ?? '').replace(CONTROLES, '');
+}
+
+function erro(i, motivo) {
+  return new Error(`Botão ${i + 1}: ${motivo}`);
+}
+
+/**
+ * Confere e normaliza os botões de uma mensagem a enviar. Lança com o motivo
+ * (erro de quem chama: melhor saber agora do que o cliente não ver o botão).
+ * @returns {Array<{id: string, tipo: string, rotulo: string, url?: string, telefone?: string}>}
+ */
+export function validarBotoes(botoes) {
+  if (!Array.isArray(botoes) || !botoes.length) throw new Error('Informe de 1 a 3 botões.');
+  if (botoes.length > MAX_BOTOES) throw new Error(`No máximo ${MAX_BOTOES} botões por mensagem.`);
+  const ids = new Set();
+  return botoes.map((b, i) => {
+    const id = String(b?.id ?? '').trim();
+    if (!id || id.length > 64) throw erro(i, 'id de 1 a 64 caracteres.');
+    if (ids.has(id)) throw erro(i, `id "${id}" repetido.`);
+    ids.add(id);
+    const rotulo = limparTexto(b.rotulo).replace(/\s+/g, ' ').trim();
+    if (!rotulo || [...rotulo].length > MAX_ROTULO) throw erro(i, `rótulo de 1 a ${MAX_ROTULO} caracteres.`);
+    switch (b.tipo) {
+      case 'resposta':
+        return { id, tipo: 'resposta', rotulo };
+      case 'link': {
+        const url = String(b.url ?? '').trim();
+        let u;
+        try { u = new URL(url); } catch { throw erro(i, 'url inválida.'); }
+        if (!['https:', 'http:'].includes(u.protocol) || url.length > 2000) throw erro(i, 'url precisa ser http(s) e ter até 2000 caracteres.');
+        return { id, tipo: 'link', rotulo, url };
+      }
+      case 'telefone': {
+        const telefone = String(b.telefone ?? '').replace(/[^\d+]/g, '');
+        if (!/^\+\d{8,15}$/.test(telefone)) throw erro(i, 'telefone no formato +5511912345678.');
+        return { id, tipo: 'telefone', rotulo, telefone };
+      }
+      default:
+        throw erro(i, 'tipo deve ser resposta, link ou telefone.');
+    }
+  });
+}
+
+/**
+ * Botão escolhido numa mensagem recebida (`conteudo.botao`), quando o cliente
+ * tocou num botão de resposta: `{ id, msg }` (id do botão e da mensagem).
+ */
+export function botaoEscolhido(conteudo) {
+  const b = conteudo?.botao;
+  if (!b || typeof b.id !== 'string' || typeof b.msg !== 'string') return null;
+  return { id: b.id.slice(0, 64), msg: b.msg.slice(0, 64) };
+}
+
+export const MAX_ITENS_LISTA = 10;
+
+const umaLinha = (v) => limparTexto(v).replace(/\s+/g, ' ').trim();
+const tamanho = (s) => [...s].length;
+
+/**
+ * Confere e normaliza uma lista de opções (até 10 itens no total, em seções):
+ *   { botao: 'Escolher uma opção', secoes: [{ titulo?, itens: [{ id, titulo, descricao? }] }] }
+ * O cliente escolhe um item e a resposta chega como a de um botão
+ * (`botaoEscolhido(conteudo).id` é o id do item).
+ */
+export function validarLista(lista) {
+  const botao = umaLinha(lista?.botao);
+  if (!botao || tamanho(botao) > 20) throw new Error('Lista: botao de 1 a 20 caracteres.');
+  const secoes = lista.secoes;
+  if (!Array.isArray(secoes) || !secoes.length || secoes.length > 10) throw new Error('Lista: de 1 a 10 seções.');
+  const ids = new Set();
+  let total = 0;
+  const saida = secoes.map((s, si) => {
+    const titulo = s?.titulo == null ? '' : umaLinha(s.titulo);
+    if (tamanho(titulo) > 24) throw new Error(`Seção ${si + 1}: título até 24 caracteres.`);
+    if (!Array.isArray(s.itens) || !s.itens.length) throw new Error(`Seção ${si + 1}: pelo menos 1 item.`);
+    const itens = s.itens.map((it, ii) => {
+      const onde = `Seção ${si + 1}, item ${ii + 1}`;
+      const id = String(it?.id ?? '').trim();
+      if (!id || id.length > 64) throw new Error(`${onde}: id de 1 a 64 caracteres.`);
+      if (ids.has(id)) throw new Error(`${onde}: id "${id}" repetido.`);
+      ids.add(id);
+      const t = umaLinha(it.titulo);
+      if (!t || tamanho(t) > 24) throw new Error(`${onde}: título de 1 a 24 caracteres.`);
+      const d = it.descricao == null ? '' : umaLinha(it.descricao);
+      if (tamanho(d) > 72) throw new Error(`${onde}: descrição até 72 caracteres.`);
+      return { id, titulo: t, ...(d ? { descricao: d } : {}) };
+    });
+    total += itens.length;
+    return { ...(titulo ? { titulo } : {}), itens };
+  });
+  if (total > MAX_ITENS_LISTA) throw new Error(`Lista: no máximo ${MAX_ITENS_LISTA} itens no total.`);
+  return { botao, secoes: saida };
+}

package/src/index.js

@@ -10,12 +10,15 @@ import { ArmazenamentoArquivo, ArmazenamentoMemoria } from './armazenamento.js';
 import { verificarAssinatura } from './webhook.js';
 import { categoria, impressao } from './categoria.js';
 import { abrirAnexo, prepararAnexo } from './anexos.js';
+import { validarBotoes, validarLista, MAX_LEGENDA } from './botoes.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 { validarBotoes, validarLista, botaoEscolhido, limparTexto } from './botoes.js';
+export { pedidoDe } from './pedido.js';
 
 export class ErroTelePapo extends Error {
   constructor(status, corpo) {
@@ -56,7 +59,7 @@ export class TelePapo {
   }
 
   async http(metodo, caminho, { corpo, token, basic } = {}) {
-    const headers = { 'User-Agent': 'telepapo-sdk/0.2' };
+    const headers = { 'User-Agent': 'telepapo-sdk/0.4' };
     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');
@@ -187,6 +190,43 @@ class Conta {
     return { id: e.id, nome: e.nome, username: e.username, escopos: e.escopos };
   }
 
+  // ------------------------------------------------------------ catálogo
+  // Permissão `catalogo.gerenciar`. O sistema do comércio sincroniza os itens
+  // pelo CÓDIGO dele (SKU): salvar de novo o mesmo código atualiza, não duplica.
+
+  /** Itens do catálogo da conta (com `codigo` e `categoria`). */
+  listarCatalogo() {
+    return this.api('GET', '/v1/eu/catalogo');
+  }
+
+  /**
+   * Cria ou atualiza o item com este código.
+   * @param {string} codigo letras, números, ponto, hífen ou sublinhado (até 64)
+   * @param {{nome: string, descricao?: string, precoCentavos: number, precoPromoCentavos?: number|null, disponivel?: boolean, categoria?: string|null}} item
+   */
+  salvarItemDoCatalogo(codigo, item) {
+    return this.api('PUT', `/v1/eu/catalogo/codigo/${encodeURIComponent(codigo)}`, item);
+  }
+
+  removerItemDoCatalogo(codigo) {
+    return this.api('DELETE', `/v1/eu/catalogo/codigo/${encodeURIComponent(codigo)}`);
+  }
+
+  /** Foto do item (JPEG, PNG ou WebP, até 2 MB). */
+  async trocarFotoDoItem(codigo, imagem, mime) {
+    if (!['image/jpeg', 'image/png', 'image/webp'].includes(mime)) throw new Error('Foto: image/jpeg, image/png ou image/webp.');
+    const token = await this.token();
+    const r = await this.cliente.fetch(`${this.cliente.apiUrl}/v1/eu/catalogo/codigo/${encodeURIComponent(codigo)}/foto`, {
+      method: 'PUT',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': mime, 'User-Agent': 'telepapo-sdk/0.4' },
+      body: imagem,
+    });
+    if (!r.ok) {
+      const t = await r.text();
+      throw new ErroTelePapo(r.status, t ? JSON.parse(t) : null);
+    }
+  }
+
   // ------------------------------------------------------------ receber
 
   /** Busca o que está pendente (alternativa/complemento ao webhook), decifra e confirma. */
@@ -313,9 +353,21 @@ class Conta {
     });
   }
 
-  enviarTexto(para, texto, { resposta } = {}) {
+  /**
+   * Texto (com *negrito*, _itálico_, ~riscado~ e `código`, que o app mostra
+   * formatados). `botoes`: até 3 (só conta comercial; ver validarBotoes).
+   * `lista`: menu de até 10 opções atrás de um botão (ver validarLista).
+   */
+  enviarTexto(para, texto, { resposta, botoes, lista } = {}) {
     if (!texto?.trim()) throw new Error('Texto vazio.');
-    return this.enviar(para, { tipo: 'texto', texto: texto.slice(0, 65000), ...(resposta ? { resposta } : {}) });
+    if (botoes && lista) throw new Error('Use botoes ou lista, não os dois.');
+    return this.enviar(para, {
+      tipo: 'texto',
+      texto: texto.slice(0, 65000),
+      ...(resposta ? { resposta } : {}),
+      ...(botoes ? { botoes: validarBotoes(botoes) } : {}),
+      ...(lista ? { lista: validarLista(lista) } : {}),
+    });
   }
 
   /** Avisa quem escreveu que a conta leu (e o celular do dono também). */
@@ -344,7 +396,7 @@ class Conta {
   /**
    * 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
+   * @param {{mime: string, nome?: string, largura?: number, altura?: number, duracaoMs?: number, onda?: string, miniatura?: string}} info
    */
   async subirAnexo(dados, info = {}) {
     if (!info.mime) throw new Error('Informe o mime do anexo.');
@@ -353,14 +405,14 @@ class Conta {
     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' },
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/octet-stream', 'User-Agent': 'telepapo-sdk/0.4' },
       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]]));
+    const extra = Object.fromEntries(['nome', 'largura', 'altura', 'duracaoMs', 'onda', '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 };
   }
 
@@ -368,7 +420,7 @@ class Conta {
   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' },
+      headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'telepapo-sdk/0.4' },
     });
     if (!r.ok) {
       const texto = await r.text();
@@ -378,13 +430,20 @@ class Conta {
   }
 
   /**
-   * 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.
+   * Envia um arquivo (foto, vídeo, áudio, documento). `legenda` vai na própria
+   * mídia (até 1024 caracteres; o app mostra abaixo da imagem/vídeo/documento).
+   * Áudio: `duracaoMs` e `onda` (base64 de até 64 barras 0-255) desenham o player.
    */
-  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);
+  async enviarArquivo(para, dados, { mime, nome, largura, altura, duracaoMs, onda, miniatura, legenda, resposta, botoes } = {}) {
+    const anexo = await this.subirAnexo(dados, { mime, nome, largura, altura, duracaoMs, onda, miniatura });
+    const texto = legenda?.trim() ? legenda.trim().slice(0, MAX_LEGENDA) : null;
+    const r = await this.enviar(para, {
+      tipo: 'midia',
+      anexo,
+      ...(texto ? { texto } : {}),
+      ...(resposta ? { resposta } : {}),
+      ...(botoes ? { botoes: validarBotoes(botoes) } : {}),
+    });
     return { ...r, anexo };
   }
 

package/src/pedido.js

@@ -0,0 +1,41 @@
+/**
+ * Pedido do carrinho (docs/MENSAGENS-RICAS.md §6 do TelePapo): quem conversa
+ * com a conta comercial monta o carrinho com itens do catálogo e envia.
+ *
+ * O preço é o que o CLIENTE VIU, montado no aparelho dele: confira código,
+ * preço e disponibilidade no seu cadastro antes de confirmar o pedido.
+ */
+
+const inteiro = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
+const texto = (v, max) => (typeof v === 'string' && v.trim() ? v.trim().slice(0, max) : null);
+
+/**
+ * Lê o pedido de uma mensagem recebida (`mensagem.conteudo`). Itens
+ * malformados são descartados; sem nenhum item válido, devolve null.
+ * @returns {null | { loja: string|null, itens: Array<{produtoId: string|null, codigo: string|null, descricao: string, quantidade: number, precoCentavos: number, totalCentavos: number}>, totalCentavos: number, moeda: string, observacao: string|null }}
+ */
+export function pedidoDe(conteudo) {
+  const p = conteudo?.pedido;
+  if (!p || typeof p !== 'object' || !Array.isArray(p.itens)) return null;
+  const itens = p.itens.slice(0, 50).flatMap((i) => {
+    const descricao = texto(i?.descricao, 80);
+    if (!descricao || !inteiro(i.quantidade, 1, 999) || !inteiro(i.precoCentavos, 0, 100_000_000)) return [];
+    return [{
+      produtoId: texto(i.produtoId, 64),
+      codigo: texto(i.codigo, 64),
+      descricao,
+      quantidade: i.quantidade,
+      precoCentavos: i.precoCentavos,
+      // Recalculado aqui: não confie no total que veio.
+      totalCentavos: i.quantidade * i.precoCentavos,
+    }];
+  });
+  if (!itens.length) return null;
+  return {
+    loja: texto(p.loja, 64),
+    itens,
+    totalCentavos: itens.reduce((s, i) => s + i.totalCentavos, 0),
+    moeda: 'BRL',
+    observacao: texto(p.observacao, 500),
+  };
+}