@telepapo/sdk 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telepapo/sdk",
-  "version": "0.4.0",
+  "version": "0.5.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/index.js

@@ -18,7 +18,7 @@ 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 { pedidoDe, pedidoAcaoDe, enderecoDe, FORMAS_PAGAMENTO } from './pedido.js';
 
 export class ErroTelePapo extends Error {
   constructor(status, corpo) {
@@ -59,7 +59,7 @@ export class TelePapo {
   }
 
   async http(metodo, caminho, { corpo, token, basic } = {}) {
-    const headers = { 'User-Agent': 'telepapo-sdk/0.4' };
+    const headers = { 'User-Agent': 'telepapo-sdk/0.5' };
     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');
@@ -218,7 +218,7 @@ class Conta {
     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' },
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': mime, 'User-Agent': 'telepapo-sdk/0.5' },
       body: imagem,
     });
     if (!r.ok) {
@@ -227,6 +227,48 @@ class Conta {
     }
   }
 
+  // ------------------------------------------------------------ pedidos
+  // Permissão `pedidos.gerenciar` (docs/API.md, seção 6.7). O servidor guarda só
+  // o registro (de quem, quando, situação e andamento); itens, preços, entrega e
+  // pagamento vêm na própria mensagem, cifrados (`pedidoDe(mensagem.conteudo)`).
+
+  /**
+   * Pedidos recebidos, do mais novo para o mais antigo.
+   * @param {{situacao?: 'ABERTO'|'CONCLUIDO'|'CANCELADO', cliente?: string, antes?: string, limite?: number}} [filtro]
+   * @returns {Promise<{pedidos: Array<{mensagemId: string, cliente: {id: string, nome: string|null, username: string|null, telefone: string}, situacao: string, criadoEm: string, concluidoEm: string|null, acoes: Array<{codigo: string, descricao: string, em: string}>}>, proximo: string|null}>}
+   */
+  listarPedidos(filtro = {}) {
+    const q = new URLSearchParams(Object.entries(filtro).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+    return this.api('GET', `/v1/eu/pedidos${q.size ? `?${q}` : ''}`);
+  }
+
+  pedido(mensagemId) {
+    return this.api('GET', `/v1/eu/pedidos/${encodeURIComponent(mensagemId)}`);
+  }
+
+  /**
+   * Grava uma resposta no andamento do pedido **e** avisa o cliente na
+   * conversa (texto citando o pedido, com `pedidoAcao`). `CONCLUIDO` conclui.
+   * Sem `descricao`, vale a das respostas do pedido configuradas no perfil.
+   * @param {string} cliente id de quem fez o pedido (`mensagem.de`)
+   * @param {string} mensagemId id da mensagem do pedido (`mensagem.conteudo.id`)
+   */
+  async atualizarPedido(cliente, mensagemId, codigo, { descricao } = {}) {
+    const p = await this.api('POST', `/v1/eu/pedidos/${encodeURIComponent(mensagemId)}/acoes`, { codigo, ...(descricao ? { descricao } : {}) });
+    const feita = p.acoes[p.acoes.length - 1];
+    await this.enviar(cliente, {
+      tipo: 'texto',
+      texto: `${codigo === 'CONCLUIDO' ? '✅' : '📦'} ${feita.descricao}`,
+      resposta: { id: mensagemId, autorId: cliente, trecho: '🛒 Pedido' },
+      pedidoAcao: { pedido: mensagemId, codigo, descricao: feita.descricao },
+    });
+    return p;
+  }
+
+  concluirPedido(cliente, mensagemId) {
+    return this.atualizarPedido(cliente, mensagemId, 'CONCLUIDO');
+  }
+
   // ------------------------------------------------------------ receber
 
   /** Busca o que está pendente (alternativa/complemento ao webhook), decifra e confirma. */
@@ -405,7 +447,7 @@ 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.4' },
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/octet-stream', 'User-Agent': 'telepapo-sdk/0.5' },
       body: blob,
     });
     if (!r.ok) {
@@ -420,7 +462,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.4' },
+      headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'telepapo-sdk/0.5' },
     });
     if (!r.ok) {
       const texto = await r.text();

package/src/pedido.js

@@ -1,18 +1,71 @@
 /**
- * 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.
+ * Pedido do carrinho (docs/MENSAGENS-RICAS.md §6, §8, §9 e §10 do TelePapo):
+ * quem conversa com a conta comercial monta o carrinho com itens do catálogo,
+ * escolhe entrega e pagamento, 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);
+// Controles e direção do texto (disfarçam texto); tudo vira uma linha.
+const CONTROLES = /[\u0000-\u001F\u007F‪-‮⁦-⁩]/g;
+const texto = (v, max) => {
+  if (typeof v !== 'string') return null;
+  const t = v.replace(CONTROLES, ' ').replace(/\s+/g, ' ').trim();
+  return t ? t.slice(0, max) : null;
+};
+
+/** Formas de pagamento (§10): código → nome. */
+export const FORMAS_PAGAMENTO = {
+  PIX: 'Pix',
+  DINHEIRO: 'Dinheiro',
+  CREDITO: 'Cartão de crédito',
+  DEBITO: 'Cartão de débito',
+  VALE_REFEICAO: 'Vale-refeição',
+  VALE_ALIMENTACAO: 'Vale-alimentação',
+  BOLETO: 'Boleto',
+  TRANSFERENCIA: 'Transferência bancária',
+};
+
+const UFS = new Set('AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO'.split(' '));
+
+/**
+ * Endereço (§8) de uma mensagem (`conteudo.endereco`) ou de um pedido
+ * (`pedido.entrega`). Inválido: null.
+ * @returns {null | {rotulo: string|null, logradouro: string, numero: string, complemento: string|null, bairro: string|null, cidade: string, uf: string, cep: string|null, referencia: string|null}}
+ */
+export function enderecoDe(e) {
+  if (!e || typeof e !== 'object') return null;
+  const logradouro = texto(e.logradouro, 120);
+  const numero = texto(e.numero, 10);
+  const cidade = texto(e.cidade, 60);
+  const uf = typeof e.uf === 'string' && UFS.has(e.uf) ? e.uf : null;
+  const cep = typeof e.cep === 'string' && /^\d{5}-\d{3}$/.test(e.cep) ? e.cep : null;
+  if (!logradouro || !numero || !cidade || !uf) return null;
+  return {
+    rotulo: texto(e.rotulo, 30),
+    logradouro, numero,
+    complemento: texto(e.complemento, 60),
+    bairro: texto(e.bairro, 60),
+    cidade, uf, cep,
+    referencia: texto(e.referencia, 120),
+  };
+}
+
+/** Forma de pagamento escolhida no pedido (§10), ou null. */
+function pagamentoDe(p) {
+  if (!p || typeof p !== 'object' || typeof p.codigo !== 'string' || !/^[A-Z0-9_]{1,30}$/.test(p.codigo)) return null;
+  const descricao = FORMAS_PAGAMENTO[p.codigo] ?? texto(p.descricao, 40);
+  if (!descricao) return null;
+  const troco = p.codigo === 'DINHEIRO' && inteiro(p.trocoParaCentavos, 1, 100_000_000) ? p.trocoParaCentavos : null;
+  return { codigo: p.codigo, descricao, trocoParaCentavos: troco };
+}
 
 /**
  * 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 }}
+ * @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, entrega: ReturnType<typeof enderecoDe>, pagamento: null | {codigo: string, descricao: string, trocoParaCentavos: number|null} }}
  */
 export function pedidoDe(conteudo) {
   const p = conteudo?.pedido;
@@ -37,5 +90,22 @@ export function pedidoDe(conteudo) {
     totalCentavos: itens.reduce((s, i) => s + i.totalCentavos, 0),
     moeda: 'BRL',
     observacao: texto(p.observacao, 500),
+    entrega: enderecoDe(p.entrega),
+    pagamento: pagamentoDe(p.pagamento),
   };
 }
+
+/**
+ * Andamento de pedido numa mensagem (§9): a resposta da loja ou o
+ * cancelamento do cliente. Confira quem mandou: `CANCELADO` só vale do cliente
+ * do pedido; os outros códigos, só da loja.
+ * @returns {null | {pedido: string, codigo: string, descricao: string}}
+ */
+export function pedidoAcaoDe(conteudo) {
+  const a = conteudo?.pedidoAcao;
+  if (!a || typeof a !== 'object') return null;
+  const pedido = typeof a.pedido === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(a.pedido) ? a.pedido : null;
+  const codigo = typeof a.codigo === 'string' && /^[A-Z0-9_]{1,30}$/.test(a.codigo) ? a.codigo : null;
+  const descricao = texto(a.descricao, 40);
+  return pedido && codigo && descricao ? { pedido, codigo, descricao } : null;
+}