evo360-types 1.3.512 → 1.3.516

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-chat/search/index.d.ts

@@ -7,12 +7,35 @@ export interface SearchThreadsParams {
     department_ids?: string[];
     attendant_type?: SearchAttendantType;
     assigned_user_id?: string;
+    /** Atendente que ENCERROU algum ticket da conversa na janela. */
+    closed_by_user_id?: string;
+    close_codes?: string[];
     tag_ids?: string[];
     /** Free-text contains-match against contact_name (case-insensitive) OR contact_address (digits/email/etc). */
     search?: string;
     cursor?: string;
     limit?: number;
 }
+/**
+ * Janela de datas efetivamente usada na consulta.
+ *
+ * Existe porque o backend aplica um default quando o cliente nao manda datas —
+ * e ate a feat-127 nao contava isso a ninguem. O usuario procurava uma conversa
+ * fora da janela, recebia lista vazia e concluia que ela tinha sumido.
+ *
+ * `default_window_days` vem junto para o cliente rotular ("ultimos 30 dias") sem
+ * duplicar a constante: a regra tem UM dono, que e' o backend.
+ */
+export interface AppliedWindow {
+    /** ISO. Inicio da janela consultada. */
+    date_from: string;
+    /** ISO. Fim da janela consultada. */
+    date_to: string;
+    /** true = o cliente nao mandou datas e o backend aplicou o default. */
+    defaulted: boolean;
+    /** Tamanho do default, em dias. */
+    default_window_days: number;
+}
 export interface SearchThreadCursor {
     last_activity_ms: number;
     contact_id: string;
@@ -66,8 +89,58 @@ export interface SearchThreadsResponse {
     ok: true;
     threads: ThreadAggregate[];
     nextCursor?: string;
+    /** Janela realmente aplicada — mandada pelo cliente ou default do backend. */
+    applied_window: AppliedWindow;
+    /**
+     * Total de CONVERSAS (contatos distintos) que casam com os filtros na janela.
+     *
+     * Independente de paginacao: e' o mesmo valor em todas as paginas. Sai da
+     * propria query da lista (`COUNT(*) OVER ()`), sem query extra e sem bytes
+     * adicionais — o agregado por contato ja e' materializado inteiro antes do
+     * LIMIT.
+     */
+    total: number;
     stats: SearchThreadsStats;
 }
+/**
+ * Dimensoes com contagem na busca avancada.
+ *
+ * `tag_ids` NAO esta aqui de proposito: tags nao existem no BigQuery — o filtro
+ * por tag resolve os contatos no Firestore ANTES da query. Facetar exigiria
+ * varrer leads por tag a cada mudanca de filtro, no caminho quente da tela.
+ */
+export type SearchFacetDimension = 'status' | 'department_id' | 'attendant_type' | 'assigned_user_id' | 'closed_by_user_id' | 'close_code';
+export interface SearchFacetBucket {
+    value: string;
+    /** Contagem em CONVERSAS distintas (contatos), NAO em tickets. */
+    count: number;
+    /**
+     * So' preenchido em `closed_by_user_id`. Hub-omni e' cross-tenant: quem
+     * encerra um ticket do tenant X nem sempre consta em `tenants/X/users`, entao
+     * o cliente nao tem como resolver esse rotulo sozinho. Nas demais dimensoes o
+     * cliente ja carrega o dicionario correspondente.
+     */
+    label?: string;
+}
+export interface SearchFacetsStats {
+    bq_query_id?: string;
+    bq_bytes_processed?: number;
+    duration_ms: number;
+}
+export interface SearchFacetsResponse {
+    ok: true;
+    /**
+     * Contagem por dimensao. Cada dimensao aplica TODOS os filtros ativos MENOS o
+     * dela propria (faceting classico) — senao marcar uma opcao zeraria todas as
+     * outras da mesma lista.
+     *
+     * Valor ausente = zero. O cliente que renderiza a lista de opcoes a partir de
+     * um dicionario deve tratar ausencia como `(0)`.
+     */
+    facets: Record<SearchFacetDimension, SearchFacetBucket[]>;
+    applied_window: AppliedWindow;
+    stats: SearchFacetsStats;
+}
 export type SearchThreadsErrorCode = 'invalid_filter' | 'tag_filter_too_broad' | 'forbidden' | 'bq_error' | 'fs_error';
 export interface SearchThreadsErrorResponse {
     ok: false;
@@ -135,5 +208,7 @@ export interface TimelineResponse {
     ok: true;
     timeline: TimelineEntry[];
     nextCursor?: string;
+    /** Mesma janela default silenciosa da lista — ver `AppliedWindow`. */
+    applied_window: AppliedWindow;
     stats: TimelineStats;
 }

package/dist/types/evo-chat/search/index.ts

@@ -14,6 +14,9 @@ export interface SearchThreadsParams {
   department_ids?: string[];
   attendant_type?: SearchAttendantType;
   assigned_user_id?: string;
+  /** Atendente que ENCERROU algum ticket da conversa na janela. */
+  closed_by_user_id?: string;
+  close_codes?: string[];
   tag_ids?: string[];
   /** Free-text contains-match against contact_name (case-insensitive) OR contact_address (digits/email/etc). */
   search?: string;
@@ -21,6 +24,27 @@ export interface SearchThreadsParams {
   limit?: number;
 }
 
+/**
+ * Janela de datas efetivamente usada na consulta.
+ *
+ * Existe porque o backend aplica um default quando o cliente nao manda datas —
+ * e ate a feat-127 nao contava isso a ninguem. O usuario procurava uma conversa
+ * fora da janela, recebia lista vazia e concluia que ela tinha sumido.
+ *
+ * `default_window_days` vem junto para o cliente rotular ("ultimos 30 dias") sem
+ * duplicar a constante: a regra tem UM dono, que e' o backend.
+ */
+export interface AppliedWindow {
+  /** ISO. Inicio da janela consultada. */
+  date_from: string;
+  /** ISO. Fim da janela consultada. */
+  date_to: string;
+  /** true = o cliente nao mandou datas e o backend aplicou o default. */
+  defaulted: boolean;
+  /** Tamanho do default, em dias. */
+  default_window_days: number;
+}
+
 export interface SearchThreadCursor {
   last_activity_ms: number;
   contact_id: string;
@@ -80,9 +104,71 @@ export interface SearchThreadsResponse {
   ok: true;
   threads: ThreadAggregate[];
   nextCursor?: string;
+  /** Janela realmente aplicada — mandada pelo cliente ou default do backend. */
+  applied_window: AppliedWindow;
+  /**
+   * Total de CONVERSAS (contatos distintos) que casam com os filtros na janela.
+   *
+   * Independente de paginacao: e' o mesmo valor em todas as paginas. Sai da
+   * propria query da lista (`COUNT(*) OVER ()`), sem query extra e sem bytes
+   * adicionais — o agregado por contato ja e' materializado inteiro antes do
+   * LIMIT.
+   */
+  total: number;
   stats: SearchThreadsStats;
 }
 
+// ── Facets ──
+
+/**
+ * Dimensoes com contagem na busca avancada.
+ *
+ * `tag_ids` NAO esta aqui de proposito: tags nao existem no BigQuery — o filtro
+ * por tag resolve os contatos no Firestore ANTES da query. Facetar exigiria
+ * varrer leads por tag a cada mudanca de filtro, no caminho quente da tela.
+ */
+export type SearchFacetDimension =
+  | 'status'
+  | 'department_id'
+  | 'attendant_type'
+  | 'assigned_user_id'
+  | 'closed_by_user_id'
+  | 'close_code';
+
+export interface SearchFacetBucket {
+  value: string;
+  /** Contagem em CONVERSAS distintas (contatos), NAO em tickets. */
+  count: number;
+  /**
+   * So' preenchido em `closed_by_user_id`. Hub-omni e' cross-tenant: quem
+   * encerra um ticket do tenant X nem sempre consta em `tenants/X/users`, entao
+   * o cliente nao tem como resolver esse rotulo sozinho. Nas demais dimensoes o
+   * cliente ja carrega o dicionario correspondente.
+   */
+  label?: string;
+}
+
+export interface SearchFacetsStats {
+  bq_query_id?: string;
+  bq_bytes_processed?: number;
+  duration_ms: number;
+}
+
+export interface SearchFacetsResponse {
+  ok: true;
+  /**
+   * Contagem por dimensao. Cada dimensao aplica TODOS os filtros ativos MENOS o
+   * dela propria (faceting classico) — senao marcar uma opcao zeraria todas as
+   * outras da mesma lista.
+   *
+   * Valor ausente = zero. O cliente que renderiza a lista de opcoes a partir de
+   * um dicionario deve tratar ausencia como `(0)`.
+   */
+  facets: Record<SearchFacetDimension, SearchFacetBucket[]>;
+  applied_window: AppliedWindow;
+  stats: SearchFacetsStats;
+}
+
 export type SearchThreadsErrorCode =
   | 'invalid_filter'
   | 'tag_filter_too_broad'
@@ -178,5 +264,7 @@ export interface TimelineResponse {
   ok: true;
   timeline: TimelineEntry[];
   nextCursor?: string;
+  /** Mesma janela default silenciosa da lista — ver `AppliedWindow`. */
+  applied_window: AppliedWindow;
   stats: TimelineStats;
 }

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 ──