evo360-types 1.3.662 → 1.3.667

package/dist/types/evo-finops/common/nfse-fee-reimbursement.js

@@ -0,0 +1,34 @@
+"use strict";
+// ── Nexus FinOps — reembolso da taxa de NFS-e (feat-264) ──
+//
+// A Asaas debita da subconta do cliente a taxa de cada NFS-e autorizada. O
+// Nexus apura, por competência, quantas notas nossas foram autorizadas e
+// devolve `count × fee` por transferência interna (walletId) a partir da conta
+// master. Cada apuração vira um registro de controle do backend.
+//
+// Runtime `lib: es6`: as constantes abaixo são só dados.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NFSE_FEE_REIMBURSEMENT_IN_FLIGHT_STATES = exports.NFSE_FEE_REIMBURSEMENT_CONSUMING_STATES = exports.NFSE_FEE_REIMBURSEMENT_TRANSITIONS = exports.NFSE_FEE_REIMBURSEMENT_EXTERNAL_REF_PREFIX = exports.NEX_FINOPS_NFSE_FEE_REIMBURSEMENTS_COLLECTION = void 0;
+/** Coleção dos registros de reembolso. */
+exports.NEX_FINOPS_NFSE_FEE_REIMBURSEMENTS_COLLECTION = 'nfse_fee_reimbursements';
+// path: core/nexus/apps/nex-finops/nfse_fee_reimbursements/{id}
+/** `externalReference` da transferência Asaas = `"nexnfr:{id}"`. */
+exports.NFSE_FEE_REIMBURSEMENT_EXTERNAL_REF_PREFIX = 'nexnfr:';
+/**
+ * `failed`/`canceled`/`refused` -> `done` existe só para a REALIDADE do Asaas: um
+ * `TRANSFER_DONE` do `transfer_id` vinculado significa que o dinheiro saiu; o
+ * registro vira `done` (as notas passam a ser consumidas e nunca são pagas duas
+ * vezes) e gera alerta CRITICAL. Nenhum fluxo nosso faz essa transição.
+ */
+exports.NFSE_FEE_REIMBURSEMENT_TRANSITIONS = {
+    awaiting_authorization: ['pending', 'failed', 'refused', 'canceled', 'done'],
+    pending: ['done', 'failed', 'canceled'],
+    done: [],
+    failed: ['done'],
+    canceled: ['done'],
+    refused: ['done'],
+};
+/** Estados que consomem as notas do snapshot (não podem ser reembolsadas de novo). */
+exports.NFSE_FEE_REIMBURSEMENT_CONSUMING_STATES = ['awaiting_authorization', 'pending', 'done'];
+/** Estados em voo: bloqueiam nova execução para o mesmo tenant/competência. */
+exports.NFSE_FEE_REIMBURSEMENT_IN_FLIGHT_STATES = ['awaiting_authorization', 'pending'];

package/dist/types/evo-finops/common/nfse-fee-reimbursement.ts

@@ -0,0 +1,143 @@
+// ── Nexus FinOps — reembolso da taxa de NFS-e (feat-264) ──
+//
+// A Asaas debita da subconta do cliente a taxa de cada NFS-e autorizada. O
+// Nexus apura, por competência, quantas notas nossas foram autorizadas e
+// devolve `count × fee` por transferência interna (walletId) a partir da conta
+// master. Cada apuração vira um registro de controle do backend.
+//
+// Runtime `lib: es6`: as constantes abaixo são só dados.
+
+/** Coleção dos registros de reembolso. */
+export const NEX_FINOPS_NFSE_FEE_REIMBURSEMENTS_COLLECTION = 'nfse_fee_reimbursements';
+// path: core/nexus/apps/nex-finops/nfse_fee_reimbursements/{id}
+
+/** `externalReference` da transferência Asaas = `"nexnfr:{id}"`. */
+export const NFSE_FEE_REIMBURSEMENT_EXTERNAL_REF_PREFIX = 'nexnfr:';
+
+export type NfseFeeReimbursementState =
+  | 'awaiting_authorization' // intenção gravada; POST /v3/transfers chamado ou a chamar; aguarda validação
+  | 'pending' // validação APROVADA por nós (ou Asaas confirmou PENDING com id vinculado)
+  | 'done' // TRANSFER_DONE
+  | 'failed' // POST rejeitado/erro de rede, ou TRANSFER_FAILED
+  | 'canceled' // TRANSFER_CANCELLED (inclui 3 falhas da validação)
+  | 'refused'; // nosso webhook recusou (divergência) — terminal
+
+/**
+ * `failed`/`canceled`/`refused` -> `done` existe só para a REALIDADE do Asaas: um
+ * `TRANSFER_DONE` do `transfer_id` vinculado significa que o dinheiro saiu; o
+ * registro vira `done` (as notas passam a ser consumidas e nunca são pagas duas
+ * vezes) e gera alerta CRITICAL. Nenhum fluxo nosso faz essa transição.
+ */
+export const NFSE_FEE_REIMBURSEMENT_TRANSITIONS: Record<NfseFeeReimbursementState, NfseFeeReimbursementState[]> = {
+  awaiting_authorization: ['pending', 'failed', 'refused', 'canceled', 'done'],
+  pending: ['done', 'failed', 'canceled'],
+  done: [],
+  failed: ['done'],
+  canceled: ['done'],
+  refused: ['done'],
+};
+
+/** Estados que consomem as notas do snapshot (não podem ser reembolsadas de novo). */
+export const NFSE_FEE_REIMBURSEMENT_CONSUMING_STATES: readonly string[] = ['awaiting_authorization', 'pending', 'done'];
+
+/** Estados em voo: bloqueiam nova execução para o mesmo tenant/competência. */
+export const NFSE_FEE_REIMBURSEMENT_IN_FLIGHT_STATES: readonly string[] = ['awaiting_authorization', 'pending'];
+
+/** De onde veio o `wallet_id` do destino (Adendo D1). */
+export type NfseFeeReimbursementWalletSource = 'account_scope' | 'asaas_wallets_api';
+
+/** D1: plugável. Só `asaas_internal_transfer` é implementado; `pix` fica para depois. */
+export type NfseFeeReimbursementPayoutMethod = 'asaas_internal_transfer';
+
+export interface INfseFeeReimbursement {
+  /** `{tenant}_{YYYY-MM}[_{seq}]` */
+  id: string;
+  tenant: string;
+  /** `"YYYY-MM"` (mês de `authorized_at` em America/Sao_Paulo). */
+  competencia: string;
+  /** 1, 2, … */
+  seq: number;
+  state: NfseFeeReimbursementState;
+  state_reason?: string | null;
+  provider: {
+    id: string;
+    /** Adendo D1: `asaas` = conta própria do tenant; `asaas_subaccount` = subconta da master. */
+    type: 'asaas' | 'asaas_subaccount';
+    env: 'production';
+    /** Só a subconta tem; conta própria => `null`. */
+    asaas_account_id?: string | null;
+    wallet_id: string;
+    /** `account_scope` (subconta, persistido) | `asaas_wallets_api` (conta própria, `GET /v3/wallets/` com a chave do tenant; só snapshot). */
+    wallet_source: NfseFeeReimbursementWalletSource;
+  };
+  /** Snapshot do que foi reembolsado. */
+  invoices: { count: number; ids: string[] };
+  fee: { value: number; source: 'asaas_myaccount_fees'; fetched_at: string };
+  /** `round2(count * fee.value)` */
+  amount: number;
+  currency: 'BRL';
+  contract: { customer_id: string | null; contract_ids: string[] };
+  payout: {
+    method: NfseFeeReimbursementPayoutMethod;
+    /** `"nexnfr:{id}"` */
+    external_reference: string;
+    /** Ex.: `"Reembolso taxa NFS-e 09/2026 - 10 notas"` */
+    description: string;
+    /** Id Asaas — vinculado SÓ pela resposta do nosso POST /v3/transfers/ (validação e eventos nunca vinculam). */
+    transfer_id?: string | null;
+    /** PENDING | BANK_PROCESSING | DONE | CANCELLED | FAILED | BLOCKED */
+    asaas_status?: string | null;
+    transfer_fee?: number | null;
+    effective_date?: string | null;
+    fail_reason?: string | null;
+  };
+  validation: {
+    decision: 'APPROVED' | 'REFUSED' | null;
+    decided_at?: string | null;
+    attempts: number;
+    last_reason?: string | null;
+  };
+  last_event?: string | null;
+  last_event_at?: string | null;
+  requested_by: {
+    login_id: string;
+    email?: string | null;
+    second_factor: 'totp';
+    auth_time: string;
+  };
+  created_at: string;
+  updated_at: string;
+  done_at?: string | null;
+}
+
+export type NfseFeeReimbursementEligibility =
+  | 'eligible'
+  | 'nothing_to_reimburse'
+  | 'in_flight'
+  | 'open_competencia'
+  | 'not_eligible_contract_flag'
+  | 'no_contract'
+  | 'subaccount_not_ready' // subconta ativa sem account_scope.wallet_id
+  | 'wallet_unavailable' // conta própria: GET /v3/wallets/ com 0, >1 wallets ou erro
+  | 'ambiguous_provider' // mais de 1 provider Asaas ativo (asaas/asaas_subaccount) em production
+  | 'fee_unavailable'; // GET /v3/myAccount/fees falhou ou sem invoice.feeValue
+
+export interface INfseFeeReimbursementPreviewRow {
+  tenant: string;
+  tenant_name?: string | null;
+  competencia: string;
+  eligibility: NfseFeeReimbursementEligibility;
+  reason?: string | null;
+  provider_id?: string | null;
+  provider_type?: string | null;
+  wallet_id?: string | null;
+  wallet_source?: NfseFeeReimbursementWalletSource | null;
+  /** Autorizadas na competência, do provider. */
+  invoice_count_total: number;
+  invoice_count_already_reimbursed: number;
+  invoice_count_to_reimburse: number;
+  fee_value: number | null;
+  amount: number | null;
+  next_record_id?: string | null;
+  records: Array<Pick<INfseFeeReimbursement, 'id' | 'state' | 'amount' | 'seq'> & { invoice_count: number }>;
+}

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

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

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

@@ -22,6 +22,7 @@ __exportStar(require("./common/contract"), exports);
 __exportStar(require("./common/proposal"), exports);
 __exportStar(require("./common/billing"), exports);
 __exportStar(require("./common/payment-method"), exports);
+__exportStar(require("./common/nfse-fee-reimbursement"), 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

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

package/dist/types/shared/index.d.ts

@@ -39,6 +39,8 @@ export interface IAddress {
     name?: string;
     kind?: string;
     line1?: string;
+    /** Número do logradouro. */
+    number?: string;
     line2?: string;
     neighborhood?: string;
     city?: string;

package/dist/types/shared/index.ts

@@ -51,6 +51,8 @@ export interface IAddress {
   name?: string;
   kind?: string;
   line1?: string;
+  /** Número do logradouro. */
+  number?: string;
   line2?: string;
   neighborhood?: string;
   city?: string;

package/package.json

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