evo360-types 1.3.639 → 1.3.647

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

@@ -0,0 +1,108 @@
+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;
+  /** 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 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";

package/dist/types/evo-finops/providers/asaas/asaas_provider.d.ts

@@ -156,6 +156,13 @@ export interface IAsaasEnvAuthConfig {
     operational?: {
         rate_limit_max_per_minute?: number;
     };
+    /**
+     * feat-253 (caminho B) — cobrança com `creditCardToken`. `remote_ip` é o IP enviado ao Asaas
+     * quando a credencial não guardou o IP do pagador. Ausente nos dois → a cobrança falha fechada.
+     */
+    card_token?: {
+        remote_ip?: string | null;
+    };
 }
 export interface IAsaasNfseCapabilities {
     enabled: boolean;
@@ -163,8 +170,24 @@ export interface IAsaasNfseCapabilities {
     allow_avulsa: boolean;
     allow_linked_to_payment: boolean;
 }
+/** Liga/desliga por ambiente. Ausente = desligado. */
+export interface IAsaasEnvFlag {
+    sandbox?: boolean;
+    production?: boolean;
+}
 export interface IAsaasPaymentsCapabilities {
     enabled: boolean;
+    /**
+     * feat-253 — kill-switch do caminho A (ajuste do valor da cobrança pendente da assinatura).
+     * @deprecated O caminho A saiu do modelo (o Asaas trava valor/vencimento após a 1ª fatura paga). Não usar.
+     */
+    card_subscription_adjust?: IAsaasEnvFlag;
+    /** feat-253 — flag do caminho B (captura do token + cobrança com `creditCardToken`). Desligado até o Asaas habilitar. */
+    card_token?: IAsaasEnvFlag;
+    /** feat-253 — fatura hospedada do Asaas gerada pelo Nexus para a cobrança (contingência C e entrada da captura). */
+    hosted_invoice?: IAsaasEnvFlag;
+    /** feat-253 — job diário que cobra no cartão salvo no vencimento (fatia 8). */
+    card_token_auto?: IAsaasEnvFlag;
 }
 export interface IAsaasProviderCapabilities {
     nfse: IAsaasNfseCapabilities;

package/dist/types/evo-finops/providers/asaas/asaas_provider.ts

@@ -225,6 +225,14 @@ export interface IAsaasEnvAuthConfig {
   operational?: {
     rate_limit_max_per_minute?: number;
   };
+
+  /**
+   * feat-253 (caminho B) — cobrança com `creditCardToken`. `remote_ip` é o IP enviado ao Asaas
+   * quando a credencial não guardou o IP do pagador. Ausente nos dois → a cobrança falha fechada.
+   */
+  card_token?: {
+    remote_ip?: string | null;
+  };
 }
 
 export interface IAsaasNfseCapabilities {
@@ -237,8 +245,25 @@ export interface IAsaasNfseCapabilities {
   allow_linked_to_payment: boolean; // future
 }
 
+/** Liga/desliga por ambiente. Ausente = desligado. */
+export interface IAsaasEnvFlag {
+  sandbox?: boolean;
+  production?: boolean;
+}
+
 export interface IAsaasPaymentsCapabilities {
   enabled: boolean; // false for now, future for payment links/subscriptions
+  /**
+   * feat-253 — kill-switch do caminho A (ajuste do valor da cobrança pendente da assinatura).
+   * @deprecated O caminho A saiu do modelo (o Asaas trava valor/vencimento após a 1ª fatura paga). Não usar.
+   */
+  card_subscription_adjust?: IAsaasEnvFlag;
+  /** feat-253 — flag do caminho B (captura do token + cobrança com `creditCardToken`). Desligado até o Asaas habilitar. */
+  card_token?: IAsaasEnvFlag;
+  /** feat-253 — fatura hospedada do Asaas gerada pelo Nexus para a cobrança (contingência C e entrada da captura). */
+  hosted_invoice?: IAsaasEnvFlag;
+  /** feat-253 — job diário que cobra no cartão salvo no vencimento (fatia 8). */
+  card_token_auto?: IAsaasEnvFlag;
 }
 
 export interface IAsaasProviderCapabilities {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.639",
+  "version": "1.3.647",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",