evo360-types 1.3.639 → 1.3.644

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zProviderInvoiceLinksSchema = exports.zServiceTaxInfoSchema = exports.zServiceLineItemSchema = exports.zServiceInvoiceStateSchema = exports.zProviderServiceInvoiceStatusSchema = exports.zExternalLinkSchema = exports.zExternalObjectTypeSchema = exports.zInvoiceSourceRefSchema = exports.zInvoiceSourceTypeSchema = exports.zInvoiceTakerRefSchema = exports.zInvoiceTakerSnapshotSchema = exports.zInvoiceTakerSnapshotAddressSchema = exports.zTakerDocumentSchema = exports.zTakerTaxProfileSchema = exports.zTakerProviderRefsSchema = exports.zTakerAddressSchema = exports.zInvoiceTakerTypeSchema = exports.zServiceSchema = exports.zCustomerServiceTaxInfoSchema = exports.zIssuerTaxProfileSchema = exports.zIssuerNfseConfigSchema = exports.zIssuerMunicipalCredentialsRefSchema = exports.zIssuerTaxRegimeSchema = exports.zIssuerCompanyIdentitySchema = exports.zIssuerCompanyAddressSchema = exports.zTaxProfileSyncStateSchema = exports.zAsaasProviderSchema = exports.zAsaasProviderAsaasBlockSchema = exports.zAsaasProviderCapabilitiesSchema = exports.zAsaasPaymentsCapabilitiesSchema = exports.zAsaasNfseCapabilitiesSchema = exports.zAsaasEnvAuthConfigSchema = exports.zAsaasSubaccountInputSchema = exports.zAsaasAccountScopeSchema = exports.zAsaasWebhookConfigSchema = exports.zRetryPolicySchema = exports.zAsaasWebhookEventSchema = exports.zAsaasAccountScopeModeSchema = exports.zProviderRemoteRefsSchema = exports.zProviderFiscalInfoPayloadSchema = exports.zProviderCredentialsInputSchema = exports.zProviderCredentialsSecretRefsSchema = exports.zProviderMunicipalOptionsSnapshotSchema = exports.zProviderOptionItemSchema = exports.zProviderMunicipalAuthTypeSchema = exports.zFinopsProviderBaseSchema = exports.zProviderStatusSchema = exports.zFinopsActionSchema = exports.zFinopsProviderTypeSchema = exports.zProviderEnvSchema = void 0;
-exports.zNexFinopsContractAllowancesWriteSchema = exports.zNexFinopsUsageAlertDefaultsSchema = exports.zNexFinopsAlertThresholdSchema = exports.zNexFinopsContractAllowancesSchema = exports.zNexFinopsContractAllowanceSchema = exports.zNexVendasJourneyPaymentSchema = exports.zNexVendasJourneyPaymentSupersededSchema = exports.zNexVendasJourneyPaymentWebhookEventSchema = exports.zNexVendasJourneyBoletoSchema = exports.zNexVendasJourneyPaymentChooseSchema = exports.zNexVendasJourneyPaymentStateSchema = exports.zNexVendasJourneyPaymentKindSchema = exports.zNexVendasJourneyPaymentMethodSchema = exports.zNexFinopsContractAsaasInfoSchema = exports.zNexFinopsAsaasSubscriptionStatusSchema = exports.zNexFinopsPaymentMethodSchema = exports.zNexFinopsProposalSchema = exports.zNexFinopsProposalWriteSchema = exports.zNexFinopsProposalPrefillSchema = exports.zNexFinopsProposalLoyaltyPeriodSchema = exports.zNexFinopsProposalPaymentMethodSchema = exports.zNexFinopsProposalStatusSchema = exports.zServiceInvoiceSchema = exports.zPaymentLinkSchema = exports.zPaymentLinkDocumentStateSchema = exports.zAsaasPaymentLinkSubscriptionCycleSchema = exports.zAsaasPaymentLinkChargeTypeSchema = exports.zAsaasPaymentLinkBillingTypeSchema = exports.zProviderPayloadSnapshotSchema = exports.zProviderTraceSchema = exports.zProviderInvoiceErrorSchema = exports.zProviderInvoiceIdentifiersSchema = void 0;
+exports.zServiceTaxInfoSchema = exports.zServiceLineItemSchema = exports.zServiceInvoiceStateSchema = exports.zProviderServiceInvoiceStatusSchema = exports.zExternalLinkSchema = exports.zExternalObjectTypeSchema = exports.zInvoiceSourceRefSchema = exports.zInvoiceSourceTypeSchema = exports.zInvoiceTakerRefSchema = exports.zInvoiceTakerSnapshotSchema = exports.zInvoiceTakerSnapshotAddressSchema = exports.zTakerDocumentSchema = exports.zTakerTaxProfileSchema = exports.zTakerProviderRefsSchema = exports.zTakerAddressSchema = exports.zInvoiceTakerTypeSchema = exports.zServiceSchema = exports.zCustomerServiceTaxInfoSchema = exports.zIssuerTaxProfileSchema = exports.zIssuerNfseConfigSchema = exports.zIssuerMunicipalCredentialsRefSchema = exports.zIssuerTaxRegimeSchema = exports.zIssuerCompanyIdentitySchema = exports.zIssuerCompanyAddressSchema = exports.zTaxProfileSyncStateSchema = exports.zAsaasProviderSchema = exports.zAsaasProviderAsaasBlockSchema = exports.zAsaasProviderCapabilitiesSchema = exports.zAsaasPaymentsCapabilitiesSchema = exports.zAsaasEnvFlagSchema = exports.zAsaasNfseCapabilitiesSchema = exports.zAsaasEnvAuthConfigSchema = exports.zAsaasSubaccountInputSchema = exports.zAsaasAccountScopeSchema = exports.zAsaasWebhookConfigSchema = exports.zRetryPolicySchema = exports.zAsaasWebhookEventSchema = exports.zAsaasAccountScopeModeSchema = exports.zProviderRemoteRefsSchema = exports.zProviderFiscalInfoPayloadSchema = exports.zProviderCredentialsInputSchema = exports.zProviderCredentialsSecretRefsSchema = exports.zProviderMunicipalOptionsSnapshotSchema = exports.zProviderOptionItemSchema = exports.zProviderMunicipalAuthTypeSchema = exports.zFinopsProviderBaseSchema = exports.zProviderStatusSchema = exports.zFinopsActionSchema = exports.zFinopsProviderTypeSchema = exports.zProviderEnvSchema = void 0;
+exports.zNexFinopsPaymentMethodsDiscoverSchema = exports.zNexFinopsBillingCardChargeSchema = exports.zNexFinopsContractPaymentMethodsWriteSchema = exports.zNexFinopsPaymentMethodPatchSchema = exports.zNexFinopsPaymentMethodStatusSchema = exports.zNexFinopsPaymentMethodKindSchema = exports.zNexFinopsContractAllowancesWriteSchema = exports.zNexFinopsUsageAlertDefaultsSchema = exports.zNexFinopsAlertThresholdSchema = exports.zNexFinopsContractAllowancesSchema = exports.zNexFinopsContractAllowanceSchema = exports.zNexVendasJourneyPaymentSchema = exports.zNexVendasJourneyPaymentSupersededSchema = exports.zNexVendasJourneyPaymentWebhookEventSchema = exports.zNexVendasJourneyBoletoSchema = exports.zNexVendasJourneyPaymentChooseSchema = exports.zNexVendasJourneyPaymentStateSchema = exports.zNexVendasJourneyPaymentKindSchema = exports.zNexVendasJourneyPaymentMethodSchema = exports.zNexFinopsContractAsaasInfoSchema = exports.zNexFinopsAsaasSubscriptionStatusSchema = exports.zNexFinopsPaymentMethodSchema = exports.zNexFinopsProposalSchema = exports.zNexFinopsProposalWriteSchema = exports.zNexFinopsProposalPrefillSchema = exports.zNexFinopsProposalLoyaltyPeriodSchema = exports.zNexFinopsProposalPaymentMethodSchema = exports.zNexFinopsProposalStatusSchema = exports.zServiceInvoiceSchema = exports.zPaymentLinkSchema = exports.zPaymentLinkDocumentStateSchema = exports.zAsaasPaymentLinkSubscriptionCycleSchema = exports.zAsaasPaymentLinkChargeTypeSchema = exports.zAsaasPaymentLinkBillingTypeSchema = exports.zProviderPayloadSnapshotSchema = exports.zProviderTraceSchema = exports.zProviderInvoiceErrorSchema = exports.zProviderInvoiceIdentifiersSchema = exports.zProviderInvoiceLinksSchema = void 0;
 const zod_1 = require("zod");
 const zod_schemas_1 = require("../shared/zod-schemas");
 // ---- Provider enums and base ----
@@ -233,8 +233,18 @@ exports.zAsaasNfseCapabilitiesSchema = zod_1.z.object({
     allow_avulsa: zod_1.z.boolean(),
     allow_linked_to_payment: zod_1.z.boolean(),
 });
+exports.zAsaasEnvFlagSchema = zod_1.z
+    .object({
+    sandbox: zod_1.z.boolean().optional(),
+    production: zod_1.z.boolean().optional(),
+})
+    .strip();
 exports.zAsaasPaymentsCapabilitiesSchema = zod_1.z.object({
     enabled: zod_1.z.boolean(),
+    /** feat-253 — kill-switch do caminho A. */
+    card_subscription_adjust: exports.zAsaasEnvFlagSchema.optional(),
+    /** feat-253 — flag do caminho B (token). */
+    card_token: exports.zAsaasEnvFlagSchema.optional(),
 });
 exports.zAsaasProviderCapabilitiesSchema = zod_1.z.object({
     nfse: exports.zAsaasNfseCapabilitiesSchema,
@@ -913,3 +923,52 @@ exports.zNexFinopsContractAllowancesWriteSchema = zod_1.z
     alert_thresholds: zod_1.z.array(exports.zNexFinopsAlertThresholdSchema).optional().nullable(),
 })
     .strip();
+// ---- Nexus FinOps — métodos de pagamento do cliente (feat-253) ----
+//
+// PCI: todos `.strip()`. Nenhum schema aceita número de cartão, CCV, dados do
+// portador ou token — chave desconhecida é descartada antes de chegar ao use case.
+exports.zNexFinopsPaymentMethodKindSchema = zod_1.z.enum([
+    "asaas_subscription",
+    "asaas_card_token",
+]);
+exports.zNexFinopsPaymentMethodStatusSchema = zod_1.z.enum([
+    "active",
+    "failing",
+    "inactive",
+    "revoked",
+]);
+/** `PATCH /payment-methods/:id` — o operador só renomeia ou liga/desliga. */
+exports.zNexFinopsPaymentMethodPatchSchema = zod_1.z
+    .object({
+    label: zod_1.z.string().max(120).optional().nullable(),
+    status: zod_1.z.enum(["active", "inactive"]).optional(),
+})
+    .strip();
+/** `PUT /contracts/:id/payment-methods` — rota dedicada (o PUT genérico ignora estes campos). */
+exports.zNexFinopsContractPaymentMethodsWriteSchema = zod_1.z
+    .object({
+    payment_method_ids: zod_1.z.array(zod_1.z.string().min(1).max(128)).max(10),
+    default_payment_method_id: zod_1.z.string().min(1).max(128).optional().nullable(),
+})
+    .strip();
+/** `POST /billings/:id/card-charge` (F2/F3). */
+exports.zNexFinopsBillingCardChargeSchema = zod_1.z
+    .object({
+    action: zod_1.z.enum(["preview", "adjust", "revert", "charge_now"]),
+    expected_value: zod_1.z.number(),
+    asaas_payment_id: zod_1.z.string().min(1).max(128).optional(),
+    confirm: zod_1.z.boolean().optional(),
+})
+    .strip();
+/** `POST /payment-methods/discover` — sem `confirm` é dry-run. */
+exports.zNexFinopsPaymentMethodsDiscoverSchema = zod_1.z
+    .object({
+    customer_id: zod_1.z.string().min(1).max(128).optional(),
+    confirm: zod_1.z
+        .object({
+        payment_method_ids: zod_1.z.array(zod_1.z.string().min(1).max(128)).max(500),
+    })
+        .strip()
+        .optional(),
+})
+    .strip();

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

@@ -247,8 +247,19 @@ export const zAsaasNfseCapabilitiesSchema = z.object({
   allow_linked_to_payment: z.boolean(),
 });
 
+export const zAsaasEnvFlagSchema = z
+  .object({
+    sandbox: z.boolean().optional(),
+    production: z.boolean().optional(),
+  })
+  .strip();
+
 export const zAsaasPaymentsCapabilitiesSchema = z.object({
   enabled: z.boolean(),
+  /** feat-253 — kill-switch do caminho A. */
+  card_subscription_adjust: zAsaasEnvFlagSchema.optional(),
+  /** feat-253 — flag do caminho B (token). */
+  card_token: zAsaasEnvFlagSchema.optional(),
 });
 
 export const zAsaasProviderCapabilitiesSchema = z.object({
@@ -1001,3 +1012,59 @@ export const zNexFinopsContractAllowancesWriteSchema = z
     alert_thresholds: z.array(zNexFinopsAlertThresholdSchema).optional().nullable(),
   })
   .strip();
+
+// ---- Nexus FinOps — métodos de pagamento do cliente (feat-253) ----
+//
+// PCI: todos `.strip()`. Nenhum schema aceita número de cartão, CCV, dados do
+// portador ou token — chave desconhecida é descartada antes de chegar ao use case.
+
+export const zNexFinopsPaymentMethodKindSchema = z.enum([
+  "asaas_subscription",
+  "asaas_card_token",
+]);
+
+export const zNexFinopsPaymentMethodStatusSchema = z.enum([
+  "active",
+  "failing",
+  "inactive",
+  "revoked",
+]);
+
+/** `PATCH /payment-methods/:id` — o operador só renomeia ou liga/desliga. */
+export const zNexFinopsPaymentMethodPatchSchema = z
+  .object({
+    label: z.string().max(120).optional().nullable(),
+    status: z.enum(["active", "inactive"]).optional(),
+  })
+  .strip();
+
+/** `PUT /contracts/:id/payment-methods` — rota dedicada (o PUT genérico ignora estes campos). */
+export const zNexFinopsContractPaymentMethodsWriteSchema = z
+  .object({
+    payment_method_ids: z.array(z.string().min(1).max(128)).max(10),
+    default_payment_method_id: z.string().min(1).max(128).optional().nullable(),
+  })
+  .strip();
+
+/** `POST /billings/:id/card-charge` (F2/F3). */
+export const zNexFinopsBillingCardChargeSchema = z
+  .object({
+    action: z.enum(["preview", "adjust", "revert", "charge_now"]),
+    expected_value: z.number(),
+    asaas_payment_id: z.string().min(1).max(128).optional(),
+    confirm: z.boolean().optional(),
+  })
+  .strip();
+
+/** `POST /payment-methods/discover` — sem `confirm` é dry-run. */
+export const zNexFinopsPaymentMethodsDiscoverSchema = z
+  .object({
+    customer_id: z.string().min(1).max(128).optional(),
+    confirm: z
+      .object({
+        payment_method_ids: z.array(z.string().min(1).max(128)).max(500),
+      })
+      .strip()
+      .optional(),
+  })
+  .strip();

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

@@ -1,4 +1,5 @@
 import type { IFireGlobalDoc } from '../../shared';
+import type { NexFinopsPaymentMethodKind } from './payment-method';
 export type NexFinopsBillingStatus = 'draft' | 'issued' | 'paid' | 'overdue' | 'canceled';
 export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'other';
 export interface INexFinopsBillingServiceItem {
@@ -28,7 +29,7 @@ export interface INexFinopsBillingBoletoTerms {
     mora_taxa: number;
 }
 export interface INexFinopsBillingPaymentOption {
-    type: 'pix' | 'boleto' | 'payment_link';
+    type: 'pix' | 'boleto' | 'payment_link' | 'credit_card';
     provider_id?: string | null;
     external_id?: string | null;
     url?: string | null;
@@ -63,12 +64,61 @@ export interface INexFinopsBillingAttachment {
     category?: NexFinopsBillingAttachmentCategory;
 }
 export interface INexFinopsBillingPaidVia {
-    kind: 'payment_link' | 'manual' | 'pix' | 'boleto';
+    kind: 'payment_link' | 'manual' | 'pix' | 'boleto' | 'credit_card';
     payment_link_id?: string | null;
     asaas_payment_id?: string | null;
     event?: string | null;
     received_at?: string | null;
     raw_status?: string | null;
+    /** feat-253: método de pagamento (cartão) que liquidou a cobrança. */
+    payment_method_id?: string | null;
+    /** feat-253: degrau do roteamento do webhook de cartão que casou o pagamento. Interno (não vai ao portal). */
+    matched_by?: 'card_payment_id' | 'external_reference' | 'subscription_competency' | null;
+}
+/** Resumo do método herdado — só bandeira e últimos 4 (PCI). */
+export interface INexFinopsBillingPaymentMethodSnapshot {
+    kind: NexFinopsPaymentMethodKind;
+    brand: string | null;
+    last4: string | null;
+    subscription_id?: string | null;
+}
+export type NexFinopsBillingCardChargeMode = 'subscription_adjust'
+/** Contingência A′. */
+ | 'subscription_value_update' | 'token_charge';
+export type NexFinopsBillingCardChargeStatus = 'scheduled' | 'stale' | 'confirmed' | 'refused' | 'refunded' | 'chargeback' | 'canceled' | 'reverted';
+export interface INexFinopsBillingCardChargeHistoryEntry {
+    at: string;
+    by: string | null;
+    action: 'adjust' | 'readjust' | 'revert' | 'charge' | 'event';
+    value?: number | null;
+    event?: string | null;
+}
+export interface INexFinopsBillingCardCharge {
+    mode: NexFinopsBillingCardChargeMode;
+    payment_method_id: string;
+    asaas_payment_id: string;
+    subscription_id?: string | null;
+    /** `dueDate` do `pay_` no Asaas (YYYY-MM-DD). */
+    due_date: string;
+    /** Caminho A: valor antes do ajuste. */
+    value_before?: number | null;
+    /** = `billing.total` no momento do ajuste. */
+    value_after: number;
+    status: NexFinopsBillingCardChargeStatus;
+    raw_status?: string | null;
+    adjusted_at: string;
+    adjusted_by: {
+        kind: 'user' | 'system';
+        id: string | null;
+    };
+    last_event?: string | null;
+    last_event_at?: string | null;
+    failure?: {
+        event: string;
+        description?: string | null;
+    } | null;
+    /** Capado em 30 entradas. */
+    history: INexFinopsBillingCardChargeHistoryEntry[];
 }
 export interface INexFinopsBilling extends IFireGlobalDoc {
     customer_id: string;
@@ -95,6 +145,12 @@ export interface INexFinopsBilling extends IFireGlobalDoc {
     contract_snapshot?: Record<string, unknown> | null;
     customer_snapshot?: Record<string, unknown> | null;
     notes?: string | null;
+    /** Método herdado do `default_payment_method_id` do contrato na geração (ou escolhido depois). */
+    payment_method_id?: string | null;
+    payment_method_snapshot?: INexFinopsBillingPaymentMethodSnapshot | null;
+    /** Todos os `pay_` do Asaas já associados (A e B) — chave do roteamento do webhook. Interno. */
+    card_payment_ids?: string[];
+    card_charge?: INexFinopsBillingCardCharge | null;
 }
 /**
  * Transições permitidas de status de cobrança.

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

@@ -1,4 +1,5 @@
 import type { IFireGlobalDoc } from '../../shared';
+import type { NexFinopsPaymentMethodKind } from './payment-method';
 
 // ── Status ──
 
@@ -42,7 +43,7 @@ export interface INexFinopsBillingBoletoTerms {
 }
 
 export interface INexFinopsBillingPaymentOption {
-  type: 'pix' | 'boleto' | 'payment_link';
+  type: 'pix' | 'boleto' | 'payment_link' | 'credit_card';
   provider_id?: string | null;
   external_id?: string | null;
   url?: string | null;
@@ -80,12 +81,72 @@ export interface INexFinopsBillingAttachment {
 }
 
 export interface INexFinopsBillingPaidVia {
-  kind: 'payment_link' | 'manual' | 'pix' | 'boleto';
+  kind: 'payment_link' | 'manual' | 'pix' | 'boleto' | 'credit_card';
   payment_link_id?: string | null;
   asaas_payment_id?: string | null;
   event?: string | null;
   received_at?: string | null;
   raw_status?: string | null;
+  /** feat-253: método de pagamento (cartão) que liquidou a cobrança. */
+  payment_method_id?: string | null;
+  /** feat-253: degrau do roteamento do webhook de cartão que casou o pagamento. Interno (não vai ao portal). */
+  matched_by?: 'card_payment_id' | 'external_reference' | 'subscription_competency' | null;
+}
+
+// ── Cobrança no cartão (feat-253) ──
+
+/** Resumo do método herdado — só bandeira e últimos 4 (PCI). */
+export interface INexFinopsBillingPaymentMethodSnapshot {
+  kind: NexFinopsPaymentMethodKind;
+  brand: string | null;
+  last4: string | null;
+  subscription_id?: string | null;
+}
+
+export type NexFinopsBillingCardChargeMode =
+  | 'subscription_adjust'
+  /** Contingência A′. */
+  | 'subscription_value_update'
+  | 'token_charge';
+
+export type NexFinopsBillingCardChargeStatus =
+  | 'scheduled'
+  | 'stale'
+  | 'confirmed'
+  | 'refused'
+  | 'refunded'
+  | 'chargeback'
+  | 'canceled'
+  | 'reverted';
+
+export interface INexFinopsBillingCardChargeHistoryEntry {
+  at: string;
+  by: string | null;
+  action: 'adjust' | 'readjust' | 'revert' | 'charge' | 'event';
+  value?: number | null;
+  event?: string | null;
+}
+
+export interface INexFinopsBillingCardCharge {
+  mode: NexFinopsBillingCardChargeMode;
+  payment_method_id: string;
+  asaas_payment_id: string;
+  subscription_id?: string | null;
+  /** `dueDate` do `pay_` no Asaas (YYYY-MM-DD). */
+  due_date: string;
+  /** Caminho A: valor antes do ajuste. */
+  value_before?: number | null;
+  /** = `billing.total` no momento do ajuste. */
+  value_after: number;
+  status: NexFinopsBillingCardChargeStatus;
+  raw_status?: string | null;
+  adjusted_at: string;
+  adjusted_by: { kind: 'user' | 'system'; id: string | null };
+  last_event?: string | null;
+  last_event_at?: string | null;
+  failure?: { event: string; description?: string | null } | null;
+  /** Capado em 30 entradas. */
+  history: INexFinopsBillingCardChargeHistoryEntry[];
 }
 
 // ── Main Document ──
@@ -144,6 +205,15 @@ export interface INexFinopsBilling extends IFireGlobalDoc {
 
   // Observações
   notes?: string | null;
+
+  // ── Cartão (feat-253) ──
+
+  /** Método herdado do `default_payment_method_id` do contrato na geração (ou escolhido depois). */
+  payment_method_id?: string | null;
+  payment_method_snapshot?: INexFinopsBillingPaymentMethodSnapshot | null;
+  /** Todos os `pay_` do Asaas já associados (A e B) — chave do roteamento do webhook. Interno. */
+  card_payment_ids?: string[];
+  card_charge?: INexFinopsBillingCardCharge | null;
 }
 
 // ── Status transitions ──

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

@@ -139,6 +139,14 @@ export interface INexFinopsContract extends IFireGlobalDoc {
     /** Método com que o primeiro pagamento foi feito. `accepted_payment_methods` é a oferta; este é o fato. */
     payment_method?: NexFinopsPaymentMethod | null;
     asaas?: INexFinopsContractAsaasInfo | null;
+    /**
+     * Ids de `payment_methods` do MESMO customer habilitados neste contrato.
+     * Escrito só pela rota dedicada `PUT /contracts/:id/payment-methods`; o
+     * `PUT /contracts/:id` genérico ignora este campo.
+     */
+    payment_method_ids?: string[] | null;
+    /** Precisa estar em `payment_method_ids`. É o que a cobrança herda no `billingGenerate`. */
+    default_payment_method_id?: string | null;
     /**
      * Franquia incluída no ciclo, por métrica. A CHAVE é o id da métrica (ver
      * `NexFinopsMetricCatalog`) e é deliberadamente `string`: métrica nova é um

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

@@ -172,6 +172,17 @@ export interface INexFinopsContract extends IFireGlobalDoc {
   payment_method?: NexFinopsPaymentMethod | null;
   asaas?: INexFinopsContractAsaasInfo | null;
 
+  // ── Métodos de pagamento habilitados (feat-253) ──
+
+  /**
+   * Ids de `payment_methods` do MESMO customer habilitados neste contrato.
+   * Escrito só pela rota dedicada `PUT /contracts/:id/payment-methods`; o
+   * `PUT /contracts/:id` genérico ignora este campo.
+   */
+  payment_method_ids?: string[] | null;
+  /** Precisa estar em `payment_method_ids`. É o que a cobrança herda no `billingGenerate`. */
+  default_payment_method_id?: string | null;
+
   // ── Franquias e alertas de consumo (feat-150 F0) ──
 
   /**

package/dist/types/evo-finops/common/payment-method.d.ts

@@ -0,0 +1,77 @@
+import type { IFireGlobalDoc } from '../../shared';
+import type { NexFinopsAsaasSubscriptionStatus } from './contract';
+/**
+ * - `asaas_subscription` (caminho A): cartão capturado na página do Asaas, dentro
+ *   de uma assinatura. Id do doc: `asub_<subscription_id>`.
+ * - `asaas_card_token` (caminho B): token de cartão do Asaas. Id do doc: `atok_<shortid>`.
+ */
+export type NexFinopsPaymentMethodKind = 'asaas_subscription' | 'asaas_card_token';
+/**
+ * - `active`: assinatura `ACTIVE` sem `deleted`, ou token válido.
+ * - `failing`: última captura recusada/reprovada; volta a `active` no próximo `PAYMENT_CONFIRMED`.
+ * - `inactive`: assinatura `INACTIVE`/`EXPIRED`/`deleted`, ou desativado pelo operador.
+ * - `revoked`: token invalidado pelo Asaas. Terminal — o cliente cadastra o cartão de novo.
+ */
+export type NexFinopsPaymentMethodStatus = 'active' | 'failing' | 'inactive' | 'revoked';
+export type NexFinopsPaymentMethodSource = 'discovery_contract_asaas' | 'discovery_payment_link' | 'manual_link' | 'asaas_capture';
+export interface INexFinopsPaymentMethodProviderRef {
+    provider_id: string;
+    provider_type: 'asaas';
+    env: 'sandbox' | 'production';
+    /** `cus_` dono do cartão/assinatura (Q5) — pode ser ≠ `taker.provider_refs.remote_customer_id`. */
+    remote_customer_id: string;
+}
+export interface INexFinopsPaymentMethodSubscriptionInfo {
+    subscription_id: string;
+    /** Doc id do nosso payment_link (origem). */
+    payment_link_id?: string | null;
+    /** Checkout de vendas (`contract.asaas.checkout_id`). */
+    checkout_id?: string | null;
+    subscription_status?: NexFinopsAsaasSubscriptionStatus | null;
+    deleted?: boolean | null;
+    cycle?: string | null;
+    /** Valor BASE da assinatura. */
+    value?: number | null;
+    /** Data civil `YYYY-MM-DD`. */
+    next_due_date?: string | null;
+}
+/** PCI: só bandeira e últimos 4. */
+export interface INexFinopsPaymentMethodCard {
+    brand: string | null;
+    last4: string | null;
+}
+export interface INexFinopsPaymentMethodSourceInfo {
+    kind: NexFinopsPaymentMethodSource;
+    contract_id?: string | null;
+    payment_link_id?: string | null;
+    journey_ref?: string | null;
+    /** Pagamento que originou o método (caminho B). */
+    asaas_payment_id?: string | null;
+}
+export interface INexFinopsPaymentMethodLastCharge {
+    asaas_payment_id: string;
+    status: string;
+    at: string;
+    error?: string | null;
+}
+export interface INexFinopsCustomerPaymentMethod extends IFireGlobalDoc {
+    customer_id: string;
+    kind: NexFinopsPaymentMethodKind;
+    status: NexFinopsPaymentMethodStatus;
+    label?: string | null;
+    /** PCI: só isto. Nunca número completo, CCV ou token. */
+    card: INexFinopsPaymentMethodCard;
+    provider: INexFinopsPaymentMethodProviderRef;
+    /** Só no kind `asaas_subscription`. */
+    asaas_subscription?: INexFinopsPaymentMethodSubscriptionInfo | null;
+    /** Kind `asaas_card_token`: existe `private/credential`. Único reflexo do token. */
+    has_credential?: boolean | null;
+    source: INexFinopsPaymentMethodSourceInfo;
+    last_synced_at?: string | null;
+    last_used_at?: string | null;
+    last_charge?: INexFinopsPaymentMethodLastCharge | null;
+}
+/** Prefixos determinísticos dos ids (idempotência da descoberta). */
+export declare const NEX_FINOPS_PAYMENT_METHOD_ID_PREFIX: Record<NexFinopsPaymentMethodKind, string>;
+/** Status em que o método pode ser herdado por uma cobrança. */
+export declare const NEX_FINOPS_PAYMENT_METHOD_USABLE_STATUSES: readonly NexFinopsPaymentMethodStatus[];

package/dist/types/evo-finops/common/payment-method.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEX_FINOPS_PAYMENT_METHOD_USABLE_STATUSES = exports.NEX_FINOPS_PAYMENT_METHOD_ID_PREFIX = void 0;
+/** Prefixos determinísticos dos ids (idempotência da descoberta). */
+exports.NEX_FINOPS_PAYMENT_METHOD_ID_PREFIX = {
+    asaas_subscription: 'asub_',
+    asaas_card_token: 'atok_',
+};
+/** Status em que o método pode ser herdado por uma cobrança. */
+exports.NEX_FINOPS_PAYMENT_METHOD_USABLE_STATUSES = ['active', 'failing'];

package/dist/types/evo-finops/common/payment-method.ts

@@ -0,0 +1,106 @@
+import type { IFireGlobalDoc } from '../../shared';
+import type { NexFinopsAsaasSubscriptionStatus } from './contract';
+
+// ── Métodos de pagamento do cliente (feat-253) ──
+//
+// Coleção própria do nex-finops: `core/nexus/apps/nex-finops/payment_methods/{pmId}`.
+// Fica FORA do customer porque o portal devolve o customer inteiro e a regra de
+// `nex-customers/customers` não tem curinga de subcoleção.
+//
+// PCI: o doc só guarda bandeira + últimos 4. Número completo, CCV, dados do
+// portador ou token de cartão NÃO têm campo aqui e não devem ganhar um. O token
+// do caminho B mora em `payment_methods/{pmId}/private/credential`, sem leitura
+// pelo cliente e sem tipo exportado para o front.
+
+/**
+ * - `asaas_subscription` (caminho A): cartão capturado na página do Asaas, dentro
+ *   de uma assinatura. Id do doc: `asub_<subscription_id>`.
+ * - `asaas_card_token` (caminho B): token de cartão do Asaas. Id do doc: `atok_<shortid>`.
+ */
+export type NexFinopsPaymentMethodKind = 'asaas_subscription' | 'asaas_card_token';
+
+/**
+ * - `active`: assinatura `ACTIVE` sem `deleted`, ou token válido.
+ * - `failing`: última captura recusada/reprovada; volta a `active` no próximo `PAYMENT_CONFIRMED`.
+ * - `inactive`: assinatura `INACTIVE`/`EXPIRED`/`deleted`, ou desativado pelo operador.
+ * - `revoked`: token invalidado pelo Asaas. Terminal — o cliente cadastra o cartão de novo.
+ */
+export type NexFinopsPaymentMethodStatus = 'active' | 'failing' | 'inactive' | 'revoked';
+
+export type NexFinopsPaymentMethodSource =
+  | 'discovery_contract_asaas'
+  | 'discovery_payment_link'
+  | 'manual_link'
+  | 'asaas_capture';
+
+export interface INexFinopsPaymentMethodProviderRef {
+  provider_id: string;
+  provider_type: 'asaas';
+  env: 'sandbox' | 'production';
+  /** `cus_` dono do cartão/assinatura (Q5) — pode ser ≠ `taker.provider_refs.remote_customer_id`. */
+  remote_customer_id: string;
+}
+
+export interface INexFinopsPaymentMethodSubscriptionInfo {
+  subscription_id: string;
+  /** Doc id do nosso payment_link (origem). */
+  payment_link_id?: string | null;
+  /** Checkout de vendas (`contract.asaas.checkout_id`). */
+  checkout_id?: string | null;
+  subscription_status?: NexFinopsAsaasSubscriptionStatus | null;
+  deleted?: boolean | null;
+  cycle?: string | null;
+  /** Valor BASE da assinatura. */
+  value?: number | null;
+  /** Data civil `YYYY-MM-DD`. */
+  next_due_date?: string | null;
+}
+
+/** PCI: só bandeira e últimos 4. */
+export interface INexFinopsPaymentMethodCard {
+  brand: string | null;
+  last4: string | null;
+}
+
+export interface INexFinopsPaymentMethodSourceInfo {
+  kind: NexFinopsPaymentMethodSource;
+  contract_id?: string | null;
+  payment_link_id?: string | null;
+  journey_ref?: string | null;
+  /** Pagamento que originou o método (caminho B). */
+  asaas_payment_id?: string | null;
+}
+
+export interface INexFinopsPaymentMethodLastCharge {
+  asaas_payment_id: string;
+  status: string;
+  at: string;
+  error?: string | null;
+}
+
+export interface INexFinopsCustomerPaymentMethod extends IFireGlobalDoc {
+  customer_id: string;
+  kind: NexFinopsPaymentMethodKind;
+  status: NexFinopsPaymentMethodStatus;
+  label?: string | null;
+  /** PCI: só isto. Nunca número completo, CCV ou token. */
+  card: INexFinopsPaymentMethodCard;
+  provider: INexFinopsPaymentMethodProviderRef;
+  /** Só no kind `asaas_subscription`. */
+  asaas_subscription?: INexFinopsPaymentMethodSubscriptionInfo | null;
+  /** Kind `asaas_card_token`: existe `private/credential`. Único reflexo do token. */
+  has_credential?: boolean | null;
+  source: INexFinopsPaymentMethodSourceInfo;
+  last_synced_at?: string | null;
+  last_used_at?: string | null;
+  last_charge?: INexFinopsPaymentMethodLastCharge | null;
+}
+
+/** Prefixos determinísticos dos ids (idempotência da descoberta). */
+export const NEX_FINOPS_PAYMENT_METHOD_ID_PREFIX: Record<NexFinopsPaymentMethodKind, string> = {
+  asaas_subscription: 'asub_',
+  asaas_card_token: 'atok_',
+};
+
+/** Status em que o método pode ser herdado por uma cobrança. */
+export const NEX_FINOPS_PAYMENT_METHOD_USABLE_STATUSES: readonly NexFinopsPaymentMethodStatus[] = ['active', 'failing'];

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

@@ -12,3 +12,5 @@ export declare const FINOPS_SERVICES_COLLECTION = "services";
 export declare const FINOPS_TAKERS_COLLECTION = "takers";
 export declare const FINOPS_INVOICES_COLLECTION = "invoices";
 export declare const FINOPS_PAYMENT_LINKS_COLLECTION = "payment_links";
+/** feat-253 — métodos de pagamento do cliente (path: core/nexus/apps/nex-finops/payment_methods). */
+export declare const FINOPS_PAYMENT_METHODS_COLLECTION = "payment_methods";

package/dist/types/evo-finops/fb_collections.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FINOPS_PAYMENT_LINKS_COLLECTION = exports.FINOPS_INVOICES_COLLECTION = exports.FINOPS_TAKERS_COLLECTION = exports.FINOPS_SERVICES_COLLECTION = exports.FINOPS_DICS_SERVICES_ID = exports.FINOPS_ISSUER_PROFILES_COLLECTION = exports.FINOPS_DICS_ISSUERS_ID = exports.FINOPS_PROVIDERS_COLLECTION = exports.FINOPS_DICS_COLLECTION = exports.EVO_FINOPS_APP = void 0;
+exports.FINOPS_PAYMENT_METHODS_COLLECTION = exports.FINOPS_PAYMENT_LINKS_COLLECTION = exports.FINOPS_INVOICES_COLLECTION = exports.FINOPS_TAKERS_COLLECTION = exports.FINOPS_SERVICES_COLLECTION = exports.FINOPS_DICS_SERVICES_ID = exports.FINOPS_ISSUER_PROFILES_COLLECTION = exports.FINOPS_DICS_ISSUERS_ID = exports.FINOPS_PROVIDERS_COLLECTION = exports.FINOPS_DICS_COLLECTION = exports.EVO_FINOPS_APP = void 0;
 // evo-finops app identifier for Firestore paths
 exports.EVO_FINOPS_APP = "evo-finops";
 // Collection names for evo-finops
@@ -17,3 +17,5 @@ exports.FINOPS_SERVICES_COLLECTION = "services";
 exports.FINOPS_TAKERS_COLLECTION = "takers";
 exports.FINOPS_INVOICES_COLLECTION = "invoices";
 exports.FINOPS_PAYMENT_LINKS_COLLECTION = "payment_links";
+/** feat-253 — métodos de pagamento do cliente (path: core/nexus/apps/nex-finops/payment_methods). */
+exports.FINOPS_PAYMENT_METHODS_COLLECTION = "payment_methods";

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

@@ -16,3 +16,5 @@ export const FINOPS_TAKERS_COLLECTION = "takers";
 export const FINOPS_INVOICES_COLLECTION = "invoices";
 export const FINOPS_PAYMENT_LINKS_COLLECTION = "payment_links";
 
+/** feat-253 — métodos de pagamento do cliente (path: core/nexus/apps/nex-finops/payment_methods). */
+export const FINOPS_PAYMENT_METHODS_COLLECTION = "payment_methods";

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

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

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

@@ -21,6 +21,7 @@ __exportStar(require("./common/taker"), exports);
 __exportStar(require("./common/contract"), exports);
 __exportStar(require("./common/proposal"), exports);
 __exportStar(require("./common/billing"), exports);
+__exportStar(require("./common/payment-method"), exports);
 __exportStar(require("./providers"), exports);
 __exportStar(require("./providers/provider_fiscal_types"), exports);
 __exportStar(require("./providers/asaas/asaas_provider"), exports);

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

@@ -6,6 +6,7 @@ export * from "./common/taker";
 export * from "./common/contract";
 export * from "./common/proposal";
 export * from "./common/billing";
+export * from "./common/payment-method";
 export * from "./providers";
 export * from "./providers/provider_fiscal_types";
 export * from "./providers/asaas/asaas_provider";