@hed-hog/core 0.0.399 → 0.0.400

package/src/whatsapp-sender/whatsapp-sender.service.ts

@@ -35,11 +35,27 @@ export type WhatsappSendInput = {
 };
 
 type ResolvedProfile = {
+  id: number;
   slug: string;
   providerSlug: string;
   config: Record<string, unknown>;
 };
 
+/**
+ * Erro de envio classificado: `retryable` diz se tentar de novo pode dar
+ * resultado diferente. Um HTTP 4xx da Graph API (id inexistente, sem
+ * permissão, token ruim) não muda em cinco minutos; um 5xx ou falha de rede
+ * pode ser uma instabilidade passageira do provedor.
+ */
+export class WhatsappSendError extends BadRequestException {
+  constructor(
+    message: string,
+    public readonly retryable: boolean,
+  ) {
+    super(message);
+  }
+}
+
 /**
  * Envio de WhatsApp usando um perfil de integração escolhido pelo usuário.
  *
@@ -92,6 +108,22 @@ export class WhatsappSenderService {
     }
   }
 
+  /**
+   * Identidade do perfil que o `send` usaria, sem o `config`.
+   *
+   * Quem envia pelo provider oficial precisa dizer por qual número a mensagem
+   * sai, e cada módulo guarda esse id no próprio cadastro. Para achar o cadastro
+   * certo é preciso saber qual perfil foi resolvido — inclusive quando o slug
+   * veio vazio e a escolha coube a este serviço. O `config` fica de fora de
+   * propósito: é onde moram `access_token` e `app_secret`.
+   */
+  async describeProfile(
+    profileSlug?: string,
+  ): Promise<{ id: number; slug: string; providerSlug: string }> {
+    const { id, slug, providerSlug } = await this.resolveProfile(profileSlug);
+    return { id, slug, providerSlug };
+  }
+
   /**
    * Normaliza o destino: número vira só dígitos, id de grupo passa intacto
    * (grupos do WhatsApp têm sufixo `@g.us`, que seria destruído por um strip).
@@ -153,6 +185,7 @@ export class WhatsappSenderService {
     }
 
     return {
+      id: profile.id,
       slug: profile.slug,
       providerSlug: String((profile as any).integration_provider?.slug ?? ''),
       config: ((profile.config ?? {}) as Record<string, unknown>),
@@ -226,6 +259,19 @@ export class WhatsappSenderService {
   ): Promise<void> {
     const cfg = buildWhatsappOfficialConfigFromIntegration(profile.config);
 
+    // A Cloud API da Meta não envia para grupo — não há endpoint para isso. Sem
+    // esta guarda o `normalizeTarget(..., 'phone')` logo abaixo arrancaria o
+    // sufixo `@g.us` e a Graph API receberia o id do grupo como se fosse um
+    // telefone: ou erro genérico de número inválido, ou (pior) entrega a um
+    // número que por acaso exista. `retryable: false` porque trocar de provider
+    // é decisão de configuração, não instabilidade.
+    if (input.targetType === 'group') {
+      throw new WhatsappSendError(
+        `Perfil de integração "${profile.slug}" usa a Cloud API oficial da Meta, que não envia mensagem para grupo. Use um perfil evolution-api para esse destino.`,
+        false,
+      );
+    }
+
     if (!cfg.accessToken) {
       throw new BadRequestException(
         `Perfil de WhatsApp "${profile.slug}" está sem access_token.`,
@@ -290,17 +336,24 @@ export class WhatsappSenderService {
 
     if (!response.ok) {
       const payload = (await response.json().catch(() => ({}))) as {
-        error?: { message?: string };
+        error?: { message?: string; code?: number };
       };
 
-      throw new BadRequestException(
+      // Código documentado pela Meta para "business-initiated message fora da
+      // janela de 24h sem template" (re-engagement). Outros 4xx (id inválido,
+      // sem permissão, token ruim) não têm nada a ver com template e não
+      // devem exibir essa dica.
+      const isReengagementWindowError = payload?.error?.code === 131047;
+
+      throw new WhatsappSendError(
         `WhatsApp recusou o envio (HTTP ${response.status}): ${
           payload?.error?.message ?? 'sem detalhe'
         }${
-          input.template?.name
-            ? ''
-            : ' — sem template configurado, a entrega só funciona na janela de 24h'
+          !input.template?.name && isReengagementWindowError
+            ? ' — sem template configurado, a entrega só funciona na janela de 24h'
+            : ''
         }`,
+        response.status >= 500,
       );
     }
   }

package/hedhog/query/device_pairing_request.sql

@@ -1,46 +0,0 @@
--- Pareamento de dispositivo (QR entre celular e navegador).
---
--- Tabela de infra de auth: vive so aqui, sem YAML em hedhog/table (ver
--- oauth_mobile_state_token.sql).
---
--- Usada por libraries/core/src/pairing/pairing.service.ts. A FK para "user"
--- resolve porque os arquivos de hedhog/query sao anexados DEPOIS de todos os
--- CREATE TABLE (ver docs/YAML-SPEC.md secao 7).
-CREATE TABLE IF NOT EXISTS device_pairing_request (
-  id                BIGSERIAL    PRIMARY KEY,
-  direction         VARCHAR(20)  NOT NULL,
-  -- Só o hash do token de resgate/poll: um dump do banco não permite reivindicar
-  -- nem consumir pareamento nenhum.
-  auth_hash         VARCHAR(255) NOT NULL UNIQUE,
-  -- NULL em 'device-to-browser' até a aprovação: o navegador que pede ainda não
-  -- é ninguém. Preenchido pelo aparelho que aprova.
-  user_id           INTEGER      NULL REFERENCES "user"(id) ON DELETE CASCADE,
-  client_id         VARCHAR(100) NOT NULL,
-  purpose           VARCHAR(50)  NOT NULL DEFAULT 'vaults',
-  -- 'device-to-browser': ponto EC não comprimido (65 bytes) em base64. É a chave
-  -- para a qual o celular cifra; a privada correspondente nunca sai da aba.
-  eph_public_key    TEXT         NULL,
-  -- 'device-to-browser': o navegador também precisa de sessão (computador novo,
-  -- ninguém logado) ou só das chaves do cofre (sessão já existe, cofre travado).
-  want_session      BOOLEAN      NOT NULL DEFAULT TRUE,
-  -- OPACO para o servidor: AES-256-GCM feito no cliente com uma chave que nunca
-  -- chega aqui (fragmento do QR ou par efêmero da aba). Fica NULL até a
-  -- aprovação, então um pareamento não aprovado nunca guarda material de chave.
-  payload_enc       TEXT         NULL,
-  issued_ip         VARCHAR(64)  NULL,
-  issued_user_agent TEXT         NULL,
-  claimed_at        TIMESTAMPTZ  NULL,
-  claim_ip          VARCHAR(64)  NULL,
-  claim_user_agent  TEXT         NULL,
-  confirmed_at      TIMESTAMPTZ  NULL,
-  cancelled_at      TIMESTAMPTZ  NULL,
-  consumed_at       TIMESTAMPTZ  NULL,
-  expires_at        TIMESTAMPTZ  NOT NULL,
-  created_at        TIMESTAMPTZ  NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_device_pairing_request_expires_at
-  ON device_pairing_request (expires_at);
-
-CREATE INDEX IF NOT EXISTS idx_device_pairing_request_user
-  ON device_pairing_request (user_id, created_at DESC);

package/hedhog/query/impersonation_grant.sql

@@ -1,71 +0,0 @@
--- Simulacao de acesso ("simular login"): um operador abre uma sessao curta,
--- auditada e nao renovavel como outro usuario.
---
--- Tabela de infra de auth: vive so aqui, sem YAML em hedhog/table (ver
--- oauth_mobile_state_token.sql).
---
--- Usada por libraries/core/src/impersonation/impersonation.service.ts.
---
--- POR QUE impersonator_user_id E target_user_id SAO INTEGER SEM FOREIGN KEY:
--- as tabelas marcadas mais abaixo ja tem uma FK para "user". Uma segunda FK faz
--- o `prisma db pull` desambiguar os nomes das relacoes NOS DOIS LADOS, o que
--- renomearia `user.user_session`, `user.access_log` e `user.user_activity` e
--- quebraria UserService, packages/api-types e a tela de sessoes do admin. O nome
--- do operador e resolvido por uma segunda consulta.
-CREATE TABLE IF NOT EXISTS impersonation_grant (
-  id                   SERIAL       PRIMARY KEY,
-  code_hash            VARCHAR(255) NOT NULL UNIQUE,
-  -- Sem FK de proposito — ver a nota no topo do arquivo.
-  impersonator_user_id INTEGER      NOT NULL,
-  target_user_id       INTEGER      NOT NULL,
-  -- Chave do app de destino ('admin', 'class', 'partners'), resolvida contra a
-  -- setting app-urls.
-  app                  VARCHAR(50)  NOT NULL,
-  reason               VARCHAR(255) NULL,
-  -- Preenchido no resgate: aponta para a user_session simulada que nasceu daqui.
-  session_id           INTEGER      NULL,
-  issued_ip            VARCHAR(64)  NULL,
-  issued_user_agent    TEXT         NULL,
-  redeemed_ip          VARCHAR(64)  NULL,
-  redeemed_user_agent  TEXT         NULL,
-  consumed_at          TIMESTAMPTZ  NULL,
-  ended_at             TIMESTAMPTZ  NULL,
-  expires_at           TIMESTAMPTZ  NOT NULL,
-  created_at           TIMESTAMPTZ  NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_impersonation_grant_impersonator
-  ON impersonation_grant (impersonator_user_id, created_at DESC);
-
-CREATE INDEX IF NOT EXISTS idx_impersonation_grant_target
-  ON impersonation_grant (target_user_id, created_at DESC);
-
-CREATE INDEX IF NOT EXISTS idx_impersonation_grant_expires
-  ON impersonation_grant (expires_at);
-
-CREATE INDEX IF NOT EXISTS idx_impersonation_grant_session
-  ON impersonation_grant (session_id)
-  WHERE session_id IS NOT NULL;
-
--- ---------------------------------------------------------------------------
--- Indices das colunas de simulacao nas tabelas que TEM YAML.
---
--- As colunas em si vem de hedhog/table/{user_session,access_log,user_activity}.yaml
--- e o CLI as cria; os indices NAO — o gerador nao emite indice para elas, e a
--- semantica parcial (WHERE ... IS NOT NULL) nao e exprimivel em YAML.
---
--- Parciais de proposito: a esmagadora maioria das linhas nao tem simulacao
--- nenhuma, entao um indice cheio numa coluna quase toda NULL seria bem maior sem
--- servir a nenhuma consulta.
--- ---------------------------------------------------------------------------
-CREATE INDEX IF NOT EXISTS "user_session_impersonator_user_id_idx"
-  ON "user_session" ("impersonator_user_id")
-  WHERE "impersonator_user_id" IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS "access_log_impersonator_user_id_idx"
-  ON "access_log" ("impersonator_user_id")
-  WHERE "impersonator_user_id" IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS "user_activity_actor_user_id_idx"
-  ON "user_activity" ("actor_user_id")
-  WHERE "actor_user_id" IS NOT NULL;

package/hedhog/query/oauth_authorize_pkce.sql

@@ -1,58 +0,0 @@
--- OAuth authorization code + PKCE: a API como PROVEDORA de identidade.
---
--- Tabelas de infra de auth: vivem so aqui, sem YAML em hedhog/table (ver
--- oauth_mobile_state_token.sql).
---
--- Usadas por libraries/core/src/authorize/authorize.service.ts e
--- libraries/core/src/pairing/pairing.service.ts.
---
--- A ordem interna importa: oauth_authorization_code.client_id aponta para
--- oauth_app_client.client_id. A FK para "user" resolve porque os arquivos de
--- hedhog/query sao anexados DEPOIS de todos os CREATE TABLE (ver docs/YAML-SPEC.md
--- secao 7).
-CREATE TABLE IF NOT EXISTS oauth_app_client (
-  id             SERIAL PRIMARY KEY,
-  client_id      VARCHAR(100) NOT NULL UNIQUE,
-  name           VARCHAR(255) NOT NULL,
-  -- 'public' = sem client_secret, PKCE obrigatorio (o caso de uma extensao, que
-  -- nao consegue guardar segredo).
-  client_type    VARCHAR(20)  NOT NULL DEFAULT 'public',
-  -- Allowlist de URIs exatas, uma por linha. A comparacao e igualdade de string:
-  -- parsing de origin quebraria para esquemas nao-http.
-  redirect_uris  TEXT         NOT NULL,
-  scopes         TEXT         NOT NULL DEFAULT 'vaults',
-  -- Reservado: hoje NAO pula a tela de consent. Pular economizaria um clique e
-  -- custaria um authorize silencioso disparavel por qualquer pagina.
-  is_first_party BOOLEAN      NOT NULL DEFAULT TRUE,
-  enabled        BOOLEAN      NOT NULL DEFAULT TRUE,
-  created_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
-  updated_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW()
-);
-
--- Authorization codes de vida curta (60s), consumidos atomicamente uma unica vez.
-CREATE TABLE IF NOT EXISTS oauth_authorization_code (
-  id                    BIGSERIAL PRIMARY KEY,
-  -- Guardamos so o hash: um dump do banco nao permite trocar codes por tokens.
-  code_hash             VARCHAR(255) NOT NULL UNIQUE,
-  client_id             VARCHAR(100) NOT NULL,
-  user_id               INTEGER      NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
-  redirect_uri          TEXT         NOT NULL,
-  scope                 TEXT         NOT NULL,
-  code_challenge        VARCHAR(255) NOT NULL,
-  code_challenge_method VARCHAR(10)  NOT NULL DEFAULT 'S256',
-  expires_at            TIMESTAMPTZ  NOT NULL,
-  consumed_at           TIMESTAMPTZ  NULL,
-  created_at            TIMESTAMPTZ  NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_oauth_authorization_code_expires_at
-  ON oauth_authorization_code (expires_at);
-
-CREATE INDEX IF NOT EXISTS idx_oauth_authorization_code_client
-  ON oauth_authorization_code (client_id);
-
--- NOTA: o repositorio de referencia semeia aqui um oauth_app_client para a
--- extensao "HedHog Vaults" (client_id 'hedhog-extension', scope 'vaults'). Esse
--- seed NAO foi trazido de proposito: e dado de aplicacao, nao estrutura; depende
--- da library `vaults`; e o proprio redirect_uri de la ja mudou depois daquela
--- migration. Cada instalacao cadastra os proprios clients.

package/hedhog/query/oauth_mobile_state_token.sql

@@ -1,30 +0,0 @@
--- Estado do fluxo OAuth mobile, duravel entre replicas da API.
---
--- Tabela de infra de auth: vive so aqui, sem YAML em hedhog/table, porque nao e
--- entidade de negocio e nao tem CRUD administravel. hedhog/table e para o que
--- ganha scaffolding.
---
--- O `state` opaco nao pode viver em memoria de processo: com mais de uma replica,
--- o callback do provedor cai em qualquer pod. O token e gravado com hash, amarrado
--- a provider + redirect_uri + flow_type, e consumido uma unica vez (consumed_at)
--- antes de expirar (expires_at).
---
--- Usada por libraries/core/src/oauth/oauth.service.ts.
-CREATE TABLE IF NOT EXISTS oauth_mobile_state_token (
-  id BIGSERIAL PRIMARY KEY,
-  token_hash VARCHAR(255) NOT NULL UNIQUE,
-  provider VARCHAR(100) NOT NULL,
-  redirect_uri TEXT NOT NULL,
-  flow_type VARCHAR(20) NOT NULL,
-  expires_at TIMESTAMPTZ NOT NULL,
-  consumed_at TIMESTAMPTZ NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
--- Lookup do callback: casa o state com o par provider + redirect_uri.
-CREATE INDEX IF NOT EXISTS idx_oauth_mobile_state_token_provider_redirect
-  ON oauth_mobile_state_token (provider, redirect_uri);
-
--- Varredura de expirados.
-CREATE INDEX IF NOT EXISTS idx_oauth_mobile_state_token_expires_at
-  ON oauth_mobile_state_token (expires_at);

package/hedhog/query/oauth_web_ref_token.sql

@@ -1,25 +0,0 @@
--- Referencia curta de uso unico para o retorno do OAuth web (Microsoft Entra ID).
---
--- Tabela de infra de auth: vive so aqui, sem YAML em hedhog/table (ver
--- oauth_mobile_state_token.sql).
---
--- A API troca o authorization code (~2KB) do provedor no servidor, guarda o perfil
--- resultante cifrado sob um id curto e opaco, e devolve so esse id ao front-end,
--- que o resgata. Modelada a partir de oauth_mobile_state_token, pelo mesmo motivo:
--- ser duravel entre replicas.
---
--- Usada por libraries/core/src/oauth/oauth.service.ts.
-CREATE TABLE IF NOT EXISTS oauth_web_ref_token (
-  id BIGSERIAL PRIMARY KEY,
-  token_hash VARCHAR(255) NOT NULL UNIQUE,
-  provider VARCHAR(100) NOT NULL,
-  flow_type VARCHAR(20) NOT NULL,
-  app_origin TEXT NULL,
-  profile_enc TEXT NOT NULL,
-  expires_at TIMESTAMPTZ NOT NULL,
-  consumed_at TIMESTAMPTZ NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_oauth_web_ref_token_expires_at
-  ON oauth_web_ref_token (expires_at);