evo360-types 1.3.514 → 1.3.516

package/dist/types/evo-finops/index.ts

@@ -4,6 +4,7 @@ export * from "./fb_collections";
 export * from "./common";
 export * from "./common/taker";
 export * from "./common/contract";
+export * from "./common/proposal";
 export * from "./common/billing";
 export * from "./providers";
 export * from "./providers/provider_fiscal_types";

package/dist/types/nex-vendas/index.d.ts

@@ -0,0 +1 @@
+export * from './journey';

package/dist/types/nex-vendas/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./journey"), exports);

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

@@ -0,0 +1 @@
+export * from './journey';

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

@@ -0,0 +1,273 @@
+import type { IFireGlobalDoc } from '../shared';
+import type { INexFinopsProposalPublic, NexFinopsProposalOrigem } from '../evo-finops/common/proposal';
+import type { NexFinopsContractStatus } from '../evo-finops/common/contract';
+/**
+ * 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 declare const NEX_VENDAS_JOURNEY_STATUS_TRANSITIONS: Record<NexVendasJourneyStatus, NexVendasJourneyStatus[]>;
+/** Status em que a jornada ainda aceita ação do cliente na página pública. */
+export declare const NEX_VENDAS_JOURNEY_OPEN_STATUSES: readonly string[];
+/**
+ * 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';
+/**
+ * `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;
+}
+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;
+}
+/**
+ * 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_id?: string | null;
+    redirect_url?: string | null;
+    expires_at?: Date | null;
+    boleto?: INexVendasJourneyBoleto | null;
+    payment_link_id?: string | null;
+    link?: string | null;
+    /** 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 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    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;
+}
+/** 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;
+}
+/** Falha de verificação devolvida no 422 de `POST /journeys/:short_code/data`. */
+export interface INexVendasJourneyVerificationFailure {
+    id: string;
+    message: string;
+}

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

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEX_VENDAS_JOURNEY_OPEN_STATUSES = exports.NEX_VENDAS_JOURNEY_STATUS_TRANSITIONS = void 0;
+exports.NEX_VENDAS_JOURNEY_STATUS_TRANSITIONS = {
+    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. */
+exports.NEX_VENDAS_JOURNEY_OPEN_STATUSES = [
+    'proposta_enviada',
+    'proposta_aceita',
+    'dados_coletados',
+];