evo360-types 1.3.514 → 1.3.518

package/dist/types/nex-vendas/journey.ts

@@ -0,0 +1,387 @@
+import type { IFireGlobalDoc } from '../shared';
+import type {
+  INexFinopsProposalPublic,
+  NexFinopsProposalOrigem,
+} from '../evo-finops/common/proposal';
+import type { NexFinopsContractStatus } from '../evo-finops/common/contract';
+
+// ── Status ──
+
+/**
+ * União completa dos estados da jornada de contratação (visão §5.2). A feat-130
+ * implementa até `contrato_assinado`; `aguardando_pagamento`/`pago` são da
+ * feat-131 e os estados de provisionamento da F2 — declarados aqui de uma vez
+ * para que as features seguintes não mexam na máquina.
+ *
+ * `expirada` NÃO é gravada por job: quando não existe doc de jornada, quem lê
+ * deriva de `valid_until` da proposta. Depois que a jornada nasce, o status
+ * gravado é a verdade. `abandonada` é ação de backoffice.
+ */
+export type NexVendasJourneyStatus =
+  | 'proposta_enviada'
+  | 'proposta_aceita'
+  | 'dados_coletados'
+  | 'contrato_assinado'
+  | 'aguardando_pagamento'
+  | 'pago'
+  | 'tenant_criado'
+  | 'onboarding_em_curso'
+  | 'concluida'
+  | 'expirada'
+  | 'abandonada';
+
+export const NEX_VENDAS_JOURNEY_STATUS_TRANSITIONS: Record<
+  NexVendasJourneyStatus,
+  NexVendasJourneyStatus[]
+> = {
+  proposta_enviada: ['proposta_aceita', 'expirada', 'abandonada'],
+  proposta_aceita: ['dados_coletados', 'expirada', 'abandonada'],
+  dados_coletados: ['contrato_assinado', 'abandonada'],
+  contrato_assinado: ['aguardando_pagamento', 'abandonada'],
+  aguardando_pagamento: ['pago', 'abandonada'],
+  pago: ['tenant_criado', 'abandonada'],
+  tenant_criado: ['onboarding_em_curso', 'abandonada'],
+  onboarding_em_curso: ['concluida', 'abandonada'],
+  concluida: [],
+  expirada: [],
+  abandonada: [],
+};
+
+/** Status em que a jornada ainda aceita ação do cliente na página pública. */
+export const NEX_VENDAS_JOURNEY_OPEN_STATUSES: readonly string[] = [
+  'proposta_enviada',
+  'proposta_aceita',
+  'dados_coletados',
+];
+
+/**
+ * Próximo passo que a página pública deve mostrar. Derivado do status — o shop
+ * não reimplementa a máquina, só obedece.
+ */
+export type NexVendasJourneyNextStep =
+  | 'accept'
+  | 'data'
+  | 'sign'
+  | 'payment'
+  | 'wait'
+  | 'done';
+
+// ── Assinatura ──
+
+/**
+ * `unavailable`: não há provider de assinatura configurado. A jornada avança
+ * mesmo assim (o dado foi coletado); a página pública mostra "link de assinatura
+ * em instantes" e o polling resolve quando o provider entrar.
+ */
+export type NexVendasJourneySignatureStatus =
+  | 'none'
+  | 'pending'
+  | 'signed'
+  | 'unavailable';
+
+export interface INexVendasJourneySignature {
+  status: NexVendasJourneySignatureStatus;
+  /** Nome do provider que emitiu o envelope (ex.: `d4sign`). */
+  provider?: string | null;
+  /** Id do documento/envelope no provider — chave de busca do webhook. */
+  envelope_id?: string | null;
+  sign_url?: string | null;
+  /** Identificador do signatário no provider (D4Sign: `key_signer` decodificado). */
+  signer_key?: string | null;
+  requested_at?: Date | null;
+  signed_at?: Date | null;
+  last_error?: string | null;
+}
+
+// ── Dados de identificação coletados ──
+
+export interface INexVendasJourneyCompany {
+  legal_name?: string | null;
+  trade_name?: string | null;
+  document_type?: 'cpf' | 'cnpj' | null;
+  document_number?: string | null;
+  zip?: string | null;
+  street?: string | null;
+  number?: string | null;
+  complement?: string | null;
+  district?: string | null;
+  city?: string | null;
+  state?: string | null;
+}
+
+export interface INexVendasJourneyCustomerData {
+  name: string;
+  email: string;
+  phone: string;
+  company?: INexVendasJourneyCompany | null;
+  /**
+   * CPF de quem assina o contrato (variável `RESPONSAVEL_CPF`), só dígitos.
+   *
+   * Existe separado de `company.document_number` porque no cadastro PJ aquele
+   * campo é o CNPJ e o contrato imprime o CPF do representante legal abaixo do
+   * nome, na região da assinatura. No cadastro PF os dois coincidem — o form
+   * replica o documento aqui em vez de perguntar duas vezes.
+   */
+  responsible_cpf?: string | null;
+}
+
+// ── Pagamento (feat-131) ──
+
+/**
+ * Métodos que o passo `g` oferece. Espelha `NexFinopsProposalPaymentMethod`: a
+ * proposta declara o que aceita, a jornada escolhe um deles.
+ */
+export type NexVendasJourneyPaymentMethod = 'card_subscription' | 'boleto' | 'payment_link';
+
+/** Artefato criado para o método escolhido. */
+export type NexVendasJourneyPaymentKind = 'asaas_checkout' | 'boleto' | 'payment_link';
+
+/**
+ * `compensating` é boleto emitido em janela D+1..D+3 — a tela precisa dizer
+ * "recebemos, aguardando compensação" em vez de "pague agora".
+ */
+export type NexVendasJourneyPaymentState =
+  | 'none'
+  | 'awaiting_payment'
+  | 'compensating'
+  | 'paid';
+
+/**
+ * Dados do boleto avulso Asaas (Q3/Q8: boleto com pix embutido, não assinatura
+ * BOLETO). Nunca há dado de cartão aqui — o cartão é sempre checkout hospedado.
+ */
+export interface INexVendasJourneyBoleto {
+  payment_id?: string | null;
+  invoice_url?: string | null;
+  bank_slip_url?: string | null;
+  pix_qr_code?: string | null;
+  pix_copy_paste?: string | null;
+  /** Data civil `YYYY-MM-DD`. */
+  due_date?: string | null;
+  value?: number | null;
+}
+
+/**
+ * Trilha de webhooks do pagamento. A chave de dedupe é `(event, payment_id)`:
+ * o Asaas entrega at-least-once e o mesmo evento reentra.
+ */
+export interface INexVendasJourneyPaymentWebhookEvent {
+  event: string;
+  payment_id?: string | null;
+  payment_status?: string | null;
+  subscription_id?: string | null;
+  at: Date;
+}
+
+/**
+ * Artefato descartado quando o cliente troca de método. Fica registrado porque
+ * um checkout expirado ou um boleto cancelado ainda pode receber webhook.
+ */
+export interface INexVendasJourneyPaymentSuperseded {
+  method: NexVendasJourneyPaymentMethod;
+  kind: NexVendasJourneyPaymentKind;
+  checkout_id?: string | null;
+  payment_id?: string | null;
+  payment_link_id?: string | null;
+  at: Date;
+  /** `false` quando a API do provider recusou expirar/cancelar o artefato. */
+  revoked?: boolean | null;
+}
+
+/**
+ * Bloco `payment` da jornada. Um artefato por vez; trocar de método marca o
+ * anterior em `superseded` e cria outro.
+ */
+export interface INexVendasJourneyPayment {
+  state: NexVendasJourneyPaymentState;
+  method?: NexVendasJourneyPaymentMethod | null;
+  kind?: NexVendasJourneyPaymentKind | null;
+
+  // Checkout hospedado (cartão / assinatura)
+  checkout_id?: string | null;
+  redirect_url?: string | null;
+  expires_at?: Date | null;
+
+  // Boleto avulso
+  boleto?: INexVendasJourneyBoleto | null;
+
+  // Link de pagamento (trilho existente)
+  payment_link_id?: string | null;
+  link?: string | null;
+
+  // Resultado
+  /** Id da 1ª cobrança — a assinatura não devolve isso na criação. */
+  first_payment_id?: string | null;
+  subscription_id?: string | null;
+  paid_at?: Date | null;
+
+  created_at?: Date | null;
+  webhook_events?: INexVendasJourneyPaymentWebhookEvent[] | null;
+  superseded?: INexVendasJourneyPaymentSuperseded[] | null;
+  last_error?: string | null;
+}
+
+/**
+ * Boleto na projeção pública: sem `payment_id`. O id da cobrança no Asaas é
+ * chave de roteamento interna, e o artefato do POST já o omite — a projeção
+ * pública não pode ser mais generosa que ele.
+ */
+export interface INexVendasJourneyBoletoPublic {
+  invoice_url: string | null;
+  bank_slip_url: string | null;
+  pix_qr_code: string | null;
+  pix_copy_paste: string | null;
+  due_date: string | null;
+  value: number | null;
+}
+
+/** Projeção pública do bloco: sem ids internos de assinatura nem trilha de webhook. */
+export interface INexVendasJourneyPaymentPublic {
+  state: NexVendasJourneyPaymentState;
+  method: NexVendasJourneyPaymentMethod | null;
+  kind: NexVendasJourneyPaymentKind | null;
+  redirect_url: string | null;
+  expires_at: Date | null;
+  boleto: INexVendasJourneyBoletoPublic | null;
+  link: string | null;
+  paid_at: Date | null;
+}
+
+// ── Trilha ──
+
+/**
+ * Trilha SEMÂNTICA da jornada. Não substitui a subcollection `actions` que o
+ * DAL grava: aquela é auditoria campo-a-campo, esta é a narrativa do funil.
+ */
+export interface INexVendasJourneyEvent {
+  type: string;
+  at: Date;
+  /** `system`, `customer` ou o id do usuário de backoffice. */
+  actor?: string | null;
+  data?: Record<string, unknown> | null;
+}
+
+export interface INexVendasJourneyNotification {
+  channel: 'whatsapp' | 'email' | (string & {});
+  /** Passo do funil que originou o envio (ex.: `signed`). */
+  step: string;
+  dedup_key: string;
+  task_id?: string | null;
+  sent_at: Date;
+  error?: string | null;
+}
+
+// ── Reserva de efeito externo ──
+
+/**
+ * Slots que disparam efeito externo NÃO-idempotente e por isso precisam de
+ * reserva transacional: criar o contrato, criar o envelope de assinatura e
+ * (feat-131) criar o artefato de pagamento.
+ *
+ * `payment` difere dos outros dois num ponto: contrato e envelope são efeito
+ * ÚNICO por jornada, enquanto o artefato de pagamento pode legitimamente ser
+ * recriado quando o cliente troca de método. Por isso o slot de pagamento é um
+ * mutex puro — não tem valor "definitivo" que o torne `already_done`.
+ */
+export type NexVendasJourneySlot = 'contract' | 'signature' | 'payment';
+
+/**
+ * Marca de reserva de um slot, gravada e liberada dentro de transaction.
+ *
+ * Existe porque um guard por leitura não segura corrida: dois POSTs em voo liam
+ * o `contract_ref` vazio ao mesmo tempo e criavam dois contratos, um órfão.
+ *
+ * `expires_at` é gravado (em vez de derivado na leitura) para que a reserva seja
+ * legível por quem abrir o documento: dá para ver que há um efeito externo em
+ * curso e até quando ele bloqueia uma nova tentativa. Passado o prazo, outro
+ * processo reassume — é o que impede que um crash trave o slot para sempre.
+ */
+export interface INexVendasJourneySlotClaim {
+  claimed_at: Date;
+  expires_at: Date;
+}
+
+// ── Documento principal ──
+
+/**
+ * Doc ID = `short_code` da proposta. É o aglutinador da retomada (D11) e a
+ * idempotência estrutural do aceite: aceitar duas vezes é um create que colide,
+ * não um segundo documento.
+ */
+export interface INexVendasJourney extends IFireGlobalDoc {
+  short_code: string;
+  status: NexVendasJourneyStatus;
+  origem: NexFinopsProposalOrigem;
+
+  // Vínculos (paths Firestore, não DocumentReference — o doc é lido por HTTP)
+  proposal_ref: string;
+  contract_ref?: string | null;
+  tenant_ref?: string | null;
+  customer_id?: string | null;
+
+  customer_data?: INexVendasJourneyCustomerData | null;
+  signature?: INexVendasJourneySignature | null;
+  payment?: INexVendasJourneyPayment | null;
+
+  /**
+   * Espelho PLANO de todo id externo de pagamento que a jornada já produziu —
+   * checkout, cobrança, assinatura e link, **inclusive os superseded**.
+   *
+   * É o índice de roteamento do webhook: `array-contains` sobre um array usa
+   * índice single-field automático, então uma consulta só acha a jornada por
+   * qualquer das chaves, sem índice composto. Sem este campo o roteamento
+   * dependeria de o `externalReference` propagar do checkout para a cobrança
+   * (INCERTO, não validado em sandbox) e um pagamento de artefato trocado ficaria
+   * órfão, com a assinatura cobrando e a jornada parada.
+   */
+  payment_refs?: string[] | null;
+
+  /** Cliente Asaas da conta MASTER, reusado entre tentativas de pagamento. */
+  asaas_customer_id?: string | null;
+
+  events: INexVendasJourneyEvent[];
+  notifications: INexVendasJourneyNotification[];
+
+  /**
+   * Reservas em curso, por slot. Bookkeeping do mecanismo de idempotência, não
+   * dado de negócio: nasce e morre dentro das transactions que criam contrato e
+   * envelope. Slot ausente = nada em curso.
+   */
+  claims?: Partial<Record<NexVendasJourneySlot, INexVendasJourneySlotClaim>> | null;
+
+  abandon_reason?: string | null;
+}
+
+// ── Projeção pública ──
+
+/** Nunca e-mail, telefone ou documento completos — só o suficiente para o cliente se reconhecer. */
+export interface INexVendasJourneyCustomerMasked {
+  name: string | null;
+  email_masked: string | null;
+  phone_masked: string | null;
+  document_masked: string | null;
+}
+
+/** O que o endpoint sem auth expõe. Sem ids internos de customer/tenant/contrato. */
+export interface INexVendasJourneyPublic {
+  short_code: string;
+  status: NexVendasJourneyStatus;
+  next_step: NexVendasJourneyNextStep;
+  proposal: INexFinopsProposalPublic;
+  data_submitted: boolean;
+  customer_masked: INexVendasJourneyCustomerMasked | null;
+  signature: {
+    status: NexVendasJourneySignatureStatus;
+    sign_url: string | null;
+  };
+  payment: INexVendasJourneyPaymentPublic;
+  contract: { status: NexFinopsContractStatus } | null;
+}
+
+// ── Verificações plugáveis (D1) ──
+
+/** Falha de verificação devolvida no 422 de `POST /journeys/:short_code/data`. */
+export interface INexVendasJourneyVerificationFailure {
+  id: string;
+  message: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.514",
+  "version": "1.3.518",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",