evo360-types 1.3.514 → 1.3.518

package/dist/apps/evo-finops/zod-schemas.ts

@@ -739,3 +739,185 @@ export const zServiceInvoiceSchema = zFireDocSchema
     snapshots: z.array(zProviderPayloadSnapshotSchema).optional(),
   })
   .passthrough();
+
+// ---- Nexus FinOps Proposal (feat-128) ----
+
+export const zNexFinopsProposalStatusSchema = z.enum([
+  "draft",
+  "sent",
+  "viewed",
+  "accepted",
+  "expired",
+  "canceled",
+]);
+
+export const zNexFinopsProposalPaymentMethodSchema = z.enum([
+  "boleto",
+  "card_subscription",
+  "payment_link",
+]);
+
+export const zNexFinopsProposalPrefillSchema = z
+  .object({
+    name: z.string().max(255).nullable().optional(),
+    email: z.string().max(255).nullable().optional(),
+    phone: z.string().max(50).nullable().optional(),
+    company: z.string().max(255).nullable().optional(),
+  })
+  .passthrough();
+
+/**
+ * Payload de escrita da proposta (fronteira HTTP). Campos opcionais usam
+ * `.nullable()` além de `.optional()` porque o cliente pode mandar `null`
+ * explícito (Vuetify `clearable` grava null; callable converte undefined em null).
+ *
+ * `short_code`, `status` e `currency` NÃO entram aqui: são resolvidos no servidor.
+ */
+export const zNexFinopsProposalWriteSchema = z
+  .object({
+    origem: z.string().min(1).max(64).optional(),
+    customer_id: z.string().max(128).nullable().optional(),
+    customer_ref: z.string().max(512).nullable().optional(),
+    prefill: zNexFinopsProposalPrefillSchema.nullable().optional(),
+    name: z.string().max(255).nullable().optional(),
+    html_content: z.string().optional(),
+    base_amount: z.number().nonnegative().optional(),
+    due_day: z.number().int().min(1).max(31).optional(),
+    accepted_payment_methods: z.array(zNexFinopsProposalPaymentMethodSchema).optional(),
+    terms: z.string().nullable().optional(),
+    valid_until: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, "valid_until must be an ISO date (YYYY-MM-DD)")
+      .optional(),
+    notes: z.string().nullable().optional(),
+  })
+  .strip();
+
+export const zNexFinopsProposalSchema = zNexFinopsProposalWriteSchema.extend({
+  short_code: z.string().min(1),
+  status: zNexFinopsProposalStatusSchema,
+  currency: z.literal("BRL"),
+});
+
+// ---- Nexus FinOps / Vendas Payment (feat-131) ----
+
+export const zNexFinopsPaymentMethodSchema = z.enum([
+  "pix",
+  "boleto",
+  "payment_link",
+  "card_subscription",
+]);
+
+export const zNexFinopsAsaasSubscriptionStatusSchema = z.enum([
+  "ACTIVE",
+  "EXPIRED",
+  "INACTIVE",
+]);
+
+/**
+ * Vínculo contrato ↔ assinatura Asaas. O checkout é hospedado (SAQ-A): nunca
+ * existe campo de número completo, CCV ou token de cartão neste schema.
+ */
+export const zNexFinopsContractAsaasInfoSchema = z
+  .object({
+    customer_id: z.string().max(128).optional().nullable(),
+    subscription_id: z.string().max(128).optional().nullable(),
+    subscription_status: zNexFinopsAsaasSubscriptionStatusSchema.optional().nullable(),
+    cycle: z.string().max(32).optional().nullable(),
+    value: z.number().nonnegative().optional().nullable(),
+    next_due_date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, "next_due_date must be an ISO date (YYYY-MM-DD)")
+      .optional()
+      .nullable(),
+    card_last4: z.string().max(4).optional().nullable(),
+    card_brand: z.string().max(32).optional().nullable(),
+    checkout_id: z.string().max(128).optional().nullable(),
+    env: z.enum(["sandbox", "production"]).optional().nullable(),
+  })
+  .strip();
+
+export const zNexVendasJourneyPaymentMethodSchema = z.enum([
+  "card_subscription",
+  "boleto",
+  "payment_link",
+]);
+
+export const zNexVendasJourneyPaymentKindSchema = z.enum([
+  "asaas_checkout",
+  "boleto",
+  "payment_link",
+]);
+
+export const zNexVendasJourneyPaymentStateSchema = z.enum([
+  "none",
+  "awaiting_payment",
+  "compensating",
+  "paid",
+]);
+
+/** Body de `POST /journeys/:short_code/payment`. */
+export const zNexVendasJourneyPaymentChooseSchema = z
+  .object({
+    method: zNexVendasJourneyPaymentMethodSchema,
+  })
+  .strip();
+
+export const zNexVendasJourneyBoletoSchema = z
+  .object({
+    payment_id: z.string().max(128).optional().nullable(),
+    invoice_url: z.string().max(2048).optional().nullable(),
+    bank_slip_url: z.string().max(2048).optional().nullable(),
+    pix_qr_code: z.string().optional().nullable(),
+    pix_copy_paste: z.string().optional().nullable(),
+    due_date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, "due_date must be an ISO date (YYYY-MM-DD)")
+      .optional()
+      .nullable(),
+    value: z.number().nonnegative().optional().nullable(),
+  })
+  .strip();
+
+export const zNexVendasJourneyPaymentWebhookEventSchema = z
+  .object({
+    event: z.string().min(1).max(64),
+    payment_id: z.string().max(128).optional().nullable(),
+    payment_status: z.string().max(64).optional().nullable(),
+    subscription_id: z.string().max(128).optional().nullable(),
+    at: zFirestoreDateSchema,
+  })
+  .strip();
+
+export const zNexVendasJourneyPaymentSupersededSchema = z
+  .object({
+    method: zNexVendasJourneyPaymentMethodSchema,
+    kind: zNexVendasJourneyPaymentKindSchema,
+    checkout_id: z.string().max(128).optional().nullable(),
+    payment_id: z.string().max(128).optional().nullable(),
+    payment_link_id: z.string().max(128).optional().nullable(),
+    at: zFirestoreDateSchema,
+    revoked: z.boolean().optional().nullable(),
+  })
+  .strip();
+
+export const zNexVendasJourneyPaymentSchema = z
+  .object({
+    state: zNexVendasJourneyPaymentStateSchema,
+    method: zNexVendasJourneyPaymentMethodSchema.optional().nullable(),
+    kind: zNexVendasJourneyPaymentKindSchema.optional().nullable(),
+    checkout_id: z.string().max(128).optional().nullable(),
+    redirect_url: z.string().max(2048).optional().nullable(),
+    expires_at: zFirestoreDateSchema.optional().nullable(),
+    boleto: zNexVendasJourneyBoletoSchema.optional().nullable(),
+    payment_link_id: z.string().max(128).optional().nullable(),
+    link: z.string().max(2048).optional().nullable(),
+    first_payment_id: z.string().max(128).optional().nullable(),
+    subscription_id: z.string().max(128).optional().nullable(),
+    paid_at: zFirestoreDateSchema.optional().nullable(),
+    created_at: zFirestoreDateSchema.optional().nullable(),
+    webhook_events: z.array(zNexVendasJourneyPaymentWebhookEventSchema).optional().nullable(),
+    superseded: z.array(zNexVendasJourneyPaymentSupersededSchema).optional().nullable(),
+    last_error: z.string().optional().nullable(),
+  })
+  .strip();

package/dist/apps/evo-med/insurance/zod-schemas.d.ts

@@ -44,7 +44,6 @@ export declare const zTissConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: string;
     active: boolean;
-    current_batch: number;
     contract: {
         name: string;
         type: "PJ" | "PF";
@@ -52,10 +51,10 @@ export declare const zTissConfigSchema: z.ZodObject<{
         taxId: string;
         cnes: string;
     };
+    current_batch: number;
 }, {
     version: string;
     active: boolean;
-    current_batch: number;
     contract: {
         name: string;
         type: "PJ" | "PF";
@@ -63,6 +62,7 @@ export declare const zTissConfigSchema: z.ZodObject<{
         taxId: string;
         cnes: string;
     };
+    current_batch: number;
 }>;
 export declare const zInsuranceCompanySchema: z.ZodObject<{
     id: z.ZodString;
@@ -105,7 +105,6 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -113,10 +112,10 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -124,6 +123,7 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }>>;
     address: z.ZodOptional<z.ZodObject<{
         name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -241,7 +241,6 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -249,10 +248,10 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -260,6 +259,7 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }>>;
     address: z.ZodOptional<z.ZodObject<{
         name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -377,7 +377,6 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -385,10 +384,10 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }, {
         version: string;
         active: boolean;
-        current_batch: number;
         contract: {
             name: string;
             type: "PJ" | "PF";
@@ -396,6 +395,7 @@ export declare const zInsuranceCompanySchema: z.ZodObject<{
             taxId: string;
             cnes: string;
         };
+        current_batch: number;
     }>>;
     address: z.ZodOptional<z.ZodObject<{
         name: z.ZodDefault<z.ZodOptional<z.ZodString>>;

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from "./types/domain-events";
 export * from "./types/evo-integrations";
 export * from "./types/nex-customers";
 export * from "./types/nex-tenants";
+export * from "./types/nex-vendas";
 export * from "./types/nexus-webhooks";
 export * from "./types/evo-hub-ia";
 export * from "./types/evo-mcp";

package/dist/index.js

@@ -46,6 +46,7 @@ __exportStar(require("./types/domain-events"), exports);
 __exportStar(require("./types/evo-integrations"), exports);
 __exportStar(require("./types/nex-customers"), exports);
 __exportStar(require("./types/nex-tenants"), exports);
+__exportStar(require("./types/nex-vendas"), exports);
 __exportStar(require("./types/nexus-webhooks"), exports);
 __exportStar(require("./types/evo-hub-ia"), exports);
 __exportStar(require("./types/evo-mcp"), exports);

package/dist/index.ts

@@ -30,6 +30,7 @@ export * from "./types/domain-events";
 export * from "./types/evo-integrations";
 export * from "./types/nex-customers";
 export * from "./types/nex-tenants";
+export * from "./types/nex-vendas";
 export * from "./types/nexus-webhooks";
 export * from "./types/evo-hub-ia";
 export * from "./types/evo-mcp";

package/dist/types/evo-finops/common/contract.d.ts

@@ -7,7 +7,37 @@ import type { IFireGlobalDoc } from '../../shared';
  */
 export type NexFinopsContractStatus = 'draft' | 'active' | 'cancellation_requested' | 'inactive' | 'ended' | 'canceled';
 export type NexFinopsContractRecurrence = 'one_time' | 'monthly';
-export type NexFinopsPaymentMethod = 'pix' | 'boleto' | 'payment_link';
+/**
+ * `card_subscription` entra na feat-131 para convergir com
+ * `NexFinopsProposalPaymentMethod`: o que a proposta aceita é o que o contrato
+ * registra. `pix` continua porque o operador ainda lança cobrança avulsa por pix.
+ */
+export type NexFinopsPaymentMethod = 'pix' | 'boleto' | 'payment_link' | 'card_subscription';
+/** Status da assinatura no Asaas. */
+export type NexFinopsAsaasSubscriptionStatus = 'ACTIVE' | 'EXPIRED' | 'INACTIVE';
+/**
+ * Vínculo contrato ↔ assinatura Asaas (D2). Escrito uma vez, na confirmação do
+ * primeiro pagamento, a partir de `GET /v3/subscriptions/{id}`.
+ *
+ * PCI: o checkout é hospedado pelo Asaas (SAQ-A) e o cartão nunca toca este
+ * backend. Por isso aqui só cabem os 4 últimos dígitos e a bandeira — número
+ * completo, CCV, trilha ou token de cartão NÃO têm campo neste tipo e não devem
+ * ganhar um.
+ */
+export interface INexFinopsContractAsaasInfo {
+    customer_id?: string | null;
+    subscription_id?: string | null;
+    subscription_status?: NexFinopsAsaasSubscriptionStatus | null;
+    cycle?: string | null;
+    value?: number | null;
+    /** Data civil `YYYY-MM-DD`, igual ao resto do finops. */
+    next_due_date?: string | null;
+    card_last4?: string | null;
+    card_brand?: string | null;
+    /** Sessão de checkout hospedado que originou a assinatura. */
+    checkout_id?: string | null;
+    env?: 'sandbox' | 'production' | null;
+}
 export interface INexFinopsContractServiceItem {
     category: string;
     description: string;
@@ -29,6 +59,18 @@ export interface INexFinopsContract extends IFireGlobalDoc {
     total_amount: number;
     currency: 'BRL';
     notes?: string | null;
+    /** Doc id (= `short_code`) da jornada que originou este contrato. */
+    journey_ref?: string | null;
+    /** Path Firestore da proposta que originou este contrato. */
+    proposal_ref?: string | null;
+    /**
+     * D5 — contrato fechado pelo próprio cliente no site (`origem === 'site-hm'`)
+     * nasce com direito a estorno; venda assistida, não. Default `false`.
+     */
+    refund_eligible?: boolean | null;
+    /** Método com que o primeiro pagamento foi feito. `accepted_payment_methods` é a oferta; este é o fato. */
+    payment_method?: NexFinopsPaymentMethod | null;
+    asaas?: INexFinopsContractAsaasInfo | null;
 }
 export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
 /**

package/dist/types/evo-finops/common/contract.ts

@@ -10,7 +10,40 @@ import type { IFireGlobalDoc } from '../../shared';
  */
 export type NexFinopsContractStatus = 'draft' | 'active' | 'cancellation_requested' | 'inactive' | 'ended' | 'canceled';
 export type NexFinopsContractRecurrence = 'one_time' | 'monthly';
-export type NexFinopsPaymentMethod = 'pix' | 'boleto' | 'payment_link';
+
+/**
+ * `card_subscription` entra na feat-131 para convergir com
+ * `NexFinopsProposalPaymentMethod`: o que a proposta aceita é o que o contrato
+ * registra. `pix` continua porque o operador ainda lança cobrança avulsa por pix.
+ */
+export type NexFinopsPaymentMethod = 'pix' | 'boleto' | 'payment_link' | 'card_subscription';
+
+/** Status da assinatura no Asaas. */
+export type NexFinopsAsaasSubscriptionStatus = 'ACTIVE' | 'EXPIRED' | 'INACTIVE';
+
+/**
+ * Vínculo contrato ↔ assinatura Asaas (D2). Escrito uma vez, na confirmação do
+ * primeiro pagamento, a partir de `GET /v3/subscriptions/{id}`.
+ *
+ * PCI: o checkout é hospedado pelo Asaas (SAQ-A) e o cartão nunca toca este
+ * backend. Por isso aqui só cabem os 4 últimos dígitos e a bandeira — número
+ * completo, CCV, trilha ou token de cartão NÃO têm campo neste tipo e não devem
+ * ganhar um.
+ */
+export interface INexFinopsContractAsaasInfo {
+  customer_id?: string | null;
+  subscription_id?: string | null;
+  subscription_status?: NexFinopsAsaasSubscriptionStatus | null;
+  cycle?: string | null;
+  value?: number | null;
+  /** Data civil `YYYY-MM-DD`, igual ao resto do finops. */
+  next_due_date?: string | null;
+  card_last4?: string | null;
+  card_brand?: string | null;
+  /** Sessão de checkout hospedado que originou a assinatura. */
+  checkout_id?: string | null;
+  env?: 'sandbox' | 'production' | null;
+}
 
 // ── Service Item ──
 
@@ -55,6 +88,24 @@ export interface INexFinopsContract extends IFireGlobalDoc {
 
   // Observações
   notes?: string | null;
+
+  // ── Origem na jornada de contratação (feat-130) ──
+
+  /** Doc id (= `short_code`) da jornada que originou este contrato. */
+  journey_ref?: string | null;
+  /** Path Firestore da proposta que originou este contrato. */
+  proposal_ref?: string | null;
+  /**
+   * D5 — contrato fechado pelo próprio cliente no site (`origem === 'site-hm'`)
+   * nasce com direito a estorno; venda assistida, não. Default `false`.
+   */
+  refund_eligible?: boolean | null;
+
+  // ── Pagamento efetivo (feat-131) ──
+
+  /** Método com que o primeiro pagamento foi feito. `accepted_payment_methods` é a oferta; este é o fato. */
+  payment_method?: NexFinopsPaymentMethod | null;
+  asaas?: INexFinopsContractAsaasInfo | null;
 }
 
 // ── Status transitions ──

package/dist/types/evo-finops/common/proposal.d.ts

@@ -0,0 +1,71 @@
+import type { IFireGlobalDoc } from '../../shared';
+/**
+ * `viewed` é carimbado pelo endpoint público no primeiro acesso ao `short_code`.
+ * `expired` é **derivado** de `valid_until` na leitura (não há cron): o documento
+ * pode continuar gravado como `sent` depois da data — quem lê é que resolve.
+ */
+export type NexFinopsProposalStatus = 'draft' | 'sent' | 'viewed' | 'accepted' | 'expired' | 'canceled';
+/**
+ * Aberto para extensão de propósito: novos canais de originação entram sem
+ * mudança de tipo. Os valores em uso hoje são `vendas` e `site-hm`.
+ */
+export type NexFinopsProposalOrigem = 'vendas' | 'site-hm' | (string & {});
+/**
+ * Não confundir com `NexFinopsPaymentMethod` (contratos), que é
+ * `'pix' | 'boleto' | 'payment_link'`. A proposta aceita assinatura em cartão e
+ * não oferece pix avulso; os dois conjuntos divergem de propósito.
+ */
+export type NexFinopsProposalPaymentMethod = 'boleto' | 'card_subscription' | 'payment_link';
+/** Dados que o vendedor já conhece e a página pública usa para pré-preencher. */
+export interface INexFinopsProposalPrefill {
+    name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    company?: string | null;
+}
+export interface INexFinopsProposal extends IFireGlobalDoc {
+    origem: NexFinopsProposalOrigem;
+    customer_id?: string | null;
+    customer_ref?: string | null;
+    prefill?: INexFinopsProposalPrefill | null;
+    /** Gerado no servidor, único, sem caracteres ambíguos. Nunca vem do cliente. */
+    short_code: string;
+    name?: string | null;
+    status: NexFinopsProposalStatus;
+    /** HTML descritivo escrito pelo vendedor. Sanitizar na renderização. */
+    html_content: string;
+    /** Mensalidade base em reais (decimal), mesma convenção do contrato. */
+    base_amount: number;
+    due_day: number;
+    accepted_payment_methods: NexFinopsProposalPaymentMethod[];
+    terms?: string | null;
+    currency: 'BRL';
+    valid_until: string;
+    sent_at?: Date | null;
+    viewed_at?: Date | null;
+    accepted_at?: Date | null;
+    notes?: string | null;
+}
+/** O que o endpoint sem auth expõe. Sem ids internos, sem dado sensível. */
+export interface INexFinopsProposalPublic {
+    short_code: string;
+    status: NexFinopsProposalStatus;
+    html_content: string;
+    base_amount: number;
+    due_day: number;
+    accepted_payment_methods: NexFinopsProposalPaymentMethod[];
+    terms: string | null;
+    valid_until: string;
+    /** Só nome de exibição — nunca e-mail, telefone ou documento completos. */
+    prefill_masked: {
+        name: string | null;
+    };
+}
+export declare const NEX_FINOPS_PROPOSAL_STATUS_TRANSITIONS: Record<NexFinopsProposalStatus, NexFinopsProposalStatus[]>;
+/**
+ * Status em que `valid_until` no passado deve ser lido como `expired`.
+ * `readonly string[]` para que `.includes(x)` aceite qualquer string sem cast.
+ */
+export declare const NEX_FINOPS_PROPOSAL_EXPIRABLE_STATUSES: readonly string[];
+/** Status em que a página pública deve mostrar a proposta. Os demais são 410. */
+export declare const NEX_FINOPS_PROPOSAL_PUBLIC_VISIBLE_STATUSES: readonly string[];

package/dist/types/evo-finops/common/proposal.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEX_FINOPS_PROPOSAL_PUBLIC_VISIBLE_STATUSES = exports.NEX_FINOPS_PROPOSAL_EXPIRABLE_STATUSES = exports.NEX_FINOPS_PROPOSAL_STATUS_TRANSITIONS = void 0;
+// ── Transições de status ──
+exports.NEX_FINOPS_PROPOSAL_STATUS_TRANSITIONS = {
+    draft: ['sent', 'canceled'],
+    sent: ['viewed', 'accepted', 'expired', 'canceled'],
+    viewed: ['accepted', 'expired', 'canceled'],
+    accepted: [],
+    expired: [],
+    canceled: [],
+};
+/**
+ * Status em que `valid_until` no passado deve ser lido como `expired`.
+ * `readonly string[]` para que `.includes(x)` aceite qualquer string sem cast.
+ */
+exports.NEX_FINOPS_PROPOSAL_EXPIRABLE_STATUSES = ['draft', 'sent', 'viewed'];
+/** Status em que a página pública deve mostrar a proposta. Os demais são 410. */
+exports.NEX_FINOPS_PROPOSAL_PUBLIC_VISIBLE_STATUSES = [
+    'sent',
+    'viewed',
+    'accepted',
+];

package/dist/types/evo-finops/common/proposal.ts

@@ -0,0 +1,122 @@
+import type { IFireGlobalDoc } from '../../shared';
+
+// ── Status, origem e formas de pagamento ──
+
+/**
+ * `viewed` é carimbado pelo endpoint público no primeiro acesso ao `short_code`.
+ * `expired` é **derivado** de `valid_until` na leitura (não há cron): o documento
+ * pode continuar gravado como `sent` depois da data — quem lê é que resolve.
+ */
+export type NexFinopsProposalStatus =
+  | 'draft'
+  | 'sent'
+  | 'viewed'
+  | 'accepted'
+  | 'expired'
+  | 'canceled';
+
+/**
+ * Aberto para extensão de propósito: novos canais de originação entram sem
+ * mudança de tipo. Os valores em uso hoje são `vendas` e `site-hm`.
+ */
+export type NexFinopsProposalOrigem = 'vendas' | 'site-hm' | (string & {});
+
+/**
+ * Não confundir com `NexFinopsPaymentMethod` (contratos), que é
+ * `'pix' | 'boleto' | 'payment_link'`. A proposta aceita assinatura em cartão e
+ * não oferece pix avulso; os dois conjuntos divergem de propósito.
+ */
+export type NexFinopsProposalPaymentMethod = 'boleto' | 'card_subscription' | 'payment_link';
+
+// ── Prefill do cliente ──
+
+/** Dados que o vendedor já conhece e a página pública usa para pré-preencher. */
+export interface INexFinopsProposalPrefill {
+  name?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  company?: string | null;
+}
+
+// ── Documento principal ──
+
+export interface INexFinopsProposal extends IFireGlobalDoc {
+  // Originação
+  origem: NexFinopsProposalOrigem;
+
+  // Vínculos (opcionais — a proposta pode nascer antes do cadastro do cliente)
+  customer_id?: string | null;
+  customer_ref?: string | null;
+  prefill?: INexFinopsProposalPrefill | null;
+
+  // Identificação
+  /** Gerado no servidor, único, sem caracteres ambíguos. Nunca vem do cliente. */
+  short_code: string;
+  name?: string | null;
+  status: NexFinopsProposalStatus;
+
+  // Conteúdo
+  /** HTML descritivo escrito pelo vendedor. Sanitizar na renderização. */
+  html_content: string;
+
+  // Valores efetivos
+  /** Mensalidade base em reais (decimal), mesma convenção do contrato. */
+  base_amount: number;
+  due_day: number;
+  accepted_payment_methods: NexFinopsProposalPaymentMethod[];
+  terms?: string | null;
+  currency: 'BRL';
+
+  // Validade — data ISO `YYYY-MM-DD`, igual a `starts_at`/`ends_at` do contrato
+  valid_until: string;
+
+  // Rastreio
+  sent_at?: Date | null;
+  viewed_at?: Date | null;
+  accepted_at?: Date | null;
+
+  notes?: string | null;
+}
+
+// ── Projeção pública ──
+
+/** O que o endpoint sem auth expõe. Sem ids internos, sem dado sensível. */
+export interface INexFinopsProposalPublic {
+  short_code: string;
+  status: NexFinopsProposalStatus;
+  html_content: string;
+  base_amount: number;
+  due_day: number;
+  accepted_payment_methods: NexFinopsProposalPaymentMethod[];
+  terms: string | null;
+  valid_until: string;
+  /** Só nome de exibição — nunca e-mail, telefone ou documento completos. */
+  prefill_masked: { name: string | null };
+}
+
+// ── Transições de status ──
+
+export const NEX_FINOPS_PROPOSAL_STATUS_TRANSITIONS: Record<
+  NexFinopsProposalStatus,
+  NexFinopsProposalStatus[]
+> = {
+  draft: ['sent', 'canceled'],
+  sent: ['viewed', 'accepted', 'expired', 'canceled'],
+  viewed: ['accepted', 'expired', 'canceled'],
+  accepted: [],
+  expired: [],
+  canceled: [],
+};
+
+/**
+ * Status em que `valid_until` no passado deve ser lido como `expired`.
+ * `readonly string[]` para que `.includes(x)` aceite qualquer string sem cast.
+ */
+export const NEX_FINOPS_PROPOSAL_EXPIRABLE_STATUSES: readonly string[] = ['draft', 'sent', 'viewed'];
+
+/** Status em que a página pública deve mostrar a proposta. Os demais são 410. */
+export const NEX_FINOPS_PROPOSAL_PUBLIC_VISIBLE_STATUSES: readonly string[] = [
+  'sent',
+  'viewed',
+  'accepted',
+];

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

@@ -2,6 +2,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/evo-finops/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./fb_collections"), exports);
 __exportStar(require("./common"), exports);
 __exportStar(require("./common/taker"), exports);
 __exportStar(require("./common/contract"), exports);
+__exportStar(require("./common/proposal"), exports);
 __exportStar(require("./common/billing"), exports);
 __exportStar(require("./providers"), exports);
 __exportStar(require("./providers/provider_fiscal_types"), exports);