evo360-types 1.3.639 → 1.3.647

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 ----
@@ -225,6 +225,13 @@ exports.zAsaasEnvAuthConfigSchema = zod_1.z
         rate_limit_max_per_minute: zod_1.z.number().optional(),
     })
         .optional(),
+    /** feat-253 — IP enviado na cobrança com token quando a credencial não tem o do pagador. */
+    card_token: zod_1.z
+        .object({
+        remote_ip: zod_1.z.string().max(64).optional().nullable(),
+    })
+        .strip()
+        .optional(),
 })
     .passthrough();
 exports.zAsaasNfseCapabilitiesSchema = zod_1.z.object({
@@ -233,8 +240,22 @@ 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. @deprecated (caminho A saiu do modelo). */
+    card_subscription_adjust: exports.zAsaasEnvFlagSchema.optional(),
+    /** feat-253 — flag do caminho B (captura + cobrança com token). */
+    card_token: exports.zAsaasEnvFlagSchema.optional(),
+    /** feat-253 — fatura hospedada (contingência C + entrada da captura). */
+    hosted_invoice: exports.zAsaasEnvFlagSchema.optional(),
+    /** feat-253 — job de cobrança automática no vencimento (fatia 8). */
+    card_token_auto: exports.zAsaasEnvFlagSchema.optional(),
 });
 exports.zAsaasProviderCapabilitiesSchema = zod_1.z.object({
     nfse: exports.zAsaasNfseCapabilitiesSchema,
@@ -913,3 +934,65 @@ 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` (feat-253 F2b).
+ * - `preview`: prévia da cobrança no cartão salvo (não escreve).
+ * - `charge_now`: cobra no cartão salvo (`confirm` + `expected_value`).
+ * - `send_invoice`: fatura hospedada do Asaas (`billing_type` CREDIT_CARD captura o cartão; UNDEFINED = cliente escolhe).
+ * - `cancel_invoice`: cancela a fatura aberta (`asaas_payment_id`).
+ * `.strip()`: dados de cartão/token nunca entram por aqui.
+ */
+exports.zNexFinopsBillingCardChargeSchema = zod_1.z
+    .object({
+    action: zod_1.z.enum(["preview", "charge_now", "send_invoice", "cancel_invoice"]),
+    expected_value: zod_1.z.number().optional(),
+    asaas_payment_id: zod_1.z.string().min(1).max(128).optional(),
+    confirm: zod_1.z.boolean().optional(),
+    capture_card: zod_1.z.boolean().optional(),
+    billing_type: zod_1.z.enum(["CREDIT_CARD", "UNDEFINED"]).optional(),
+    provider_id: zod_1.z.string().min(1).max(128).optional(),
+    env: zod_1.z.enum(["sandbox", "production"]).optional(),
+    taker_id: zod_1.z.string().min(1).max(128).optional(),
+    allow_early: 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

@@ -237,6 +237,13 @@ export const zAsaasEnvAuthConfigSchema = z
         rate_limit_max_per_minute: z.number().optional(),
       })
       .optional(),
+    /** feat-253 — IP enviado na cobrança com token quando a credencial não tem o do pagador. */
+    card_token: z
+      .object({
+        remote_ip: z.string().max(64).optional().nullable(),
+      })
+      .strip()
+      .optional(),
   })
   .passthrough();
 
@@ -247,8 +254,23 @@ 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. @deprecated (caminho A saiu do modelo). */
+  card_subscription_adjust: zAsaasEnvFlagSchema.optional(),
+  /** feat-253 — flag do caminho B (captura + cobrança com token). */
+  card_token: zAsaasEnvFlagSchema.optional(),
+  /** feat-253 — fatura hospedada (contingência C + entrada da captura). */
+  hosted_invoice: zAsaasEnvFlagSchema.optional(),
+  /** feat-253 — job de cobrança automática no vencimento (fatia 8). */
+  card_token_auto: zAsaasEnvFlagSchema.optional(),
 });
 
 export const zAsaasProviderCapabilitiesSchema = z.object({
@@ -1001,3 +1023,72 @@ 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` (feat-253 F2b).
+ * - `preview`: prévia da cobrança no cartão salvo (não escreve).
+ * - `charge_now`: cobra no cartão salvo (`confirm` + `expected_value`).
+ * - `send_invoice`: fatura hospedada do Asaas (`billing_type` CREDIT_CARD captura o cartão; UNDEFINED = cliente escolhe).
+ * - `cancel_invoice`: cancela a fatura aberta (`asaas_payment_id`).
+ * `.strip()`: dados de cartão/token nunca entram por aqui.
+ */
+export const zNexFinopsBillingCardChargeSchema = z
+  .object({
+    action: z.enum(["preview", "charge_now", "send_invoice", "cancel_invoice"]),
+    expected_value: z.number().optional(),
+    asaas_payment_id: z.string().min(1).max(128).optional(),
+    confirm: z.boolean().optional(),
+    capture_card: z.boolean().optional(),
+    billing_type: z.enum(["CREDIT_CARD", "UNDEFINED"]).optional(),
+    provider_id: z.string().min(1).max(128).optional(),
+    env: z.enum(["sandbox", "production"]).optional(),
+    taker_id: z.string().min(1).max(128).optional(),
+    allow_early: 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,13 +64,81 @@ 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'
+/** feat-253 F2b: fatura avulsa hospedada no Asaas (cartão com captura, ou cliente escolhe). */
+ | 'hosted_invoice';
+export type NexFinopsBillingCardChargeStatus = 'scheduled'
+/** Fatura enviada aguardando pagamento, ou cobrança com token em análise. */
+ | 'pending' | 'stale' | 'confirmed' | 'refused' | 'refunded' | 'chargeback' | 'canceled' | 'reverted';
+export interface INexFinopsBillingCardChargeHistoryEntry {
+    at: string;
+    by: string | null;
+    action: 'adjust' | 'readjust' | 'revert' | 'charge' | 'event' | 'send_invoice' | 'cancel_invoice' | 'capture';
+    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;
+    /** Mantido por compatibilidade: na F2b é o momento/autor da criação do `pay_`. */
+    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[];
+    /** Fatura hospedada que, paga no cartão, captura o token (`billing_type: 'CREDIT_CARD'`). */
+    capture_card?: boolean | null;
+    /** `invoiceUrl` da fatura hospedada (pagável pelo cliente). */
+    invoice_url?: string | null;
+    /** `billingType` pedido ao Asaas. */
+    billing_type?: 'CREDIT_CARD' | 'UNDEFINED' | null;
+    /** Resultado da captura do token após o pagamento. */
+    capture_status?: NexFinopsBillingCardCaptureStatus | null;
+    /** Método `atok_` capturado por esta cobrança (a tela oferece usar como padrão). Interno (fora do portal). */
+    captured_payment_method_id?: string | null;
+    /** Provider/ambiente onde o `pay_` foi criado. */
+    provider_id?: string | null;
+    env?: 'sandbox' | 'production' | null;
+}
+export type NexFinopsBillingCardCaptureStatus = 'captured' | 'no_token' | 'skipped';
 export interface INexFinopsBilling extends IFireGlobalDoc {
     customer_id: string;
     customer_ref?: string | null;
@@ -95,6 +164,17 @@ 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;
+    /** Trava curta da cobrança no cartão (`charge_now`). Interno (fora das projeções). */
+    card_charge_lock?: {
+        by: string | null;
+        until: string;
+    } | 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,14 +81,97 @@ 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'
+  /** feat-253 F2b: fatura avulsa hospedada no Asaas (cartão com captura, ou cliente escolhe). */
+  | 'hosted_invoice';
+
+export type NexFinopsBillingCardChargeStatus =
+  | 'scheduled'
+  /** Fatura enviada aguardando pagamento, ou cobrança com token em análise. */
+  | 'pending'
+  | 'stale'
+  | 'confirmed'
+  | 'refused'
+  | 'refunded'
+  | 'chargeback'
+  | 'canceled'
+  | 'reverted';
+
+export interface INexFinopsBillingCardChargeHistoryEntry {
+  at: string;
+  by: string | null;
+  action: 'adjust' | 'readjust' | 'revert' | 'charge' | 'event' | 'send_invoice' | 'cancel_invoice' | 'capture';
+  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;
+  /** Mantido por compatibilidade: na F2b é o momento/autor da criação do `pay_`. */
+  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[];
+
+  // ── F2b (fatura hospedada / token) ──
+
+  /** Fatura hospedada que, paga no cartão, captura o token (`billing_type: 'CREDIT_CARD'`). */
+  capture_card?: boolean | null;
+  /** `invoiceUrl` da fatura hospedada (pagável pelo cliente). */
+  invoice_url?: string | null;
+  /** `billingType` pedido ao Asaas. */
+  billing_type?: 'CREDIT_CARD' | 'UNDEFINED' | null;
+  /** Resultado da captura do token após o pagamento. */
+  capture_status?: NexFinopsBillingCardCaptureStatus | null;
+  /** Método `atok_` capturado por esta cobrança (a tela oferece usar como padrão). Interno (fora do portal). */
+  captured_payment_method_id?: string | null;
+  /** Provider/ambiente onde o `pay_` foi criado. */
+  provider_id?: string | null;
+  env?: 'sandbox' | 'production' | null;
+}
+
+export type NexFinopsBillingCardCaptureStatus = 'captured' | 'no_token' | 'skipped';
+
 // ── Main Document ──
 
 export interface INexFinopsBilling extends IFireGlobalDoc {
@@ -144,6 +228,17 @@ 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;
+  /** Trava curta da cobrança no cartão (`charge_now`). Interno (fora das projeções). */
+  card_charge_lock?: { by: string | null; until: string } | 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,79 @@
+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;
+    /** feat-253 F2b: `asub_` migrado aponta para o `atok_` que o substituiu. */
+    replaced_by_payment_method_id?: string | 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'];