evo360-types 1.3.659 → 1.3.664

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

@@ -54,14 +54,26 @@ export interface INexusModuleChatPermissions {
 }
 export interface INexusReports {
 }
+/**
+ * Sub-claims do módulo financeiro do Nexus. `finance === true` é o formato
+ * legado; não herda `reimbursements` (feat-264: movimenta dinheiro, exige TOTP).
+ */
+export interface INexusModuleFinancePermissions {
+    customers?: boolean;
+    contracts?: boolean;
+    billing?: boolean;
+    reports?: boolean;
+    /** feat-264 — reembolso da taxa de NFS-e. Sem bypass de admin. */
+    reimbursements?: boolean;
+}
 export interface INexusModules {
     chat?: INexusModuleChatPermissions | boolean;
     tenants?: boolean;
-    finance?: boolean;
+    finance?: INexusModuleFinancePermissions | boolean;
     notifications?: boolean;
     waba?: boolean;
     reports?: INexusReports | boolean;
-    [key: string]: INexusModuleChatPermissions | INexusReports | boolean | undefined;
+    [key: string]: INexusModuleChatPermissions | INexusModuleFinancePermissions | INexusReports | boolean | undefined;
 }
 export interface INexusClaims {
     nexus_access: boolean;

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

@@ -66,14 +66,32 @@ export interface INexusModuleChatPermissions {
 
 export interface INexusReports {}
 
+/**
+ * Sub-claims do módulo financeiro do Nexus. `finance === true` é o formato
+ * legado; não herda `reimbursements` (feat-264: movimenta dinheiro, exige TOTP).
+ */
+export interface INexusModuleFinancePermissions {
+  customers?: boolean;
+  contracts?: boolean;
+  billing?: boolean;
+  reports?: boolean;
+  /** feat-264 — reembolso da taxa de NFS-e. Sem bypass de admin. */
+  reimbursements?: boolean;
+}
+
 export interface INexusModules {
   chat?: INexusModuleChatPermissions | boolean;
   tenants?: boolean;
-  finance?: boolean;
+  finance?: INexusModuleFinancePermissions | boolean;
   notifications?: boolean;
   waba?: boolean;
   reports?: INexusReports | boolean;
-  [key: string]: INexusModuleChatPermissions | INexusReports | boolean | undefined;
+  [key: string]:
+    | INexusModuleChatPermissions
+    | INexusModuleFinancePermissions
+    | INexusReports
+    | boolean
+    | undefined;
 }
 
 export interface INexusClaims {

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

@@ -179,6 +179,8 @@ export interface INexFinopsContract extends IFireGlobalDoc {
      * `INexFinopsUsageAlertDefaults.thresholds`.
      */
     alert_thresholds?: number[] | null;
+    /** feat-264 D4 — reembolsar a taxa de NFS-e ao cliente. ⚠️ Ausente/null = TRUE (reembolsa). */
+    nfse_fee_reimbursement?: boolean | null;
 }
 export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
 /**

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

@@ -219,6 +219,9 @@ export interface INexFinopsContract extends IFireGlobalDoc {
    * `INexFinopsUsageAlertDefaults.thresholds`.
    */
   alert_thresholds?: number[] | null;
+
+  /** feat-264 D4 — reembolsar a taxa de NFS-e ao cliente. ⚠️ Ausente/null = TRUE (reembolsa). */
+  nfse_fee_reimbursement?: boolean | null;
 }
 
 // ── Status transitions ──

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

@@ -0,0 +1,105 @@
+/** Coleção dos registros de reembolso. */
+export declare const NEX_FINOPS_NFSE_FEE_REIMBURSEMENTS_COLLECTION = "nfse_fee_reimbursements";
+/** `externalReference` da transferência Asaas = `"nexnfr:{id}"`. */
+export declare const NFSE_FEE_REIMBURSEMENT_EXTERNAL_REF_PREFIX = "nexnfr:";
+export type NfseFeeReimbursementState = 'awaiting_authorization' | 'pending' | 'done' | 'failed' | 'canceled' | 'refused';
+/**
+ * `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 declare const NFSE_FEE_REIMBURSEMENT_TRANSITIONS: Record<NfseFeeReimbursementState, NfseFeeReimbursementState[]>;
+/** Estados que consomem as notas do snapshot (não podem ser reembolsadas de novo). */
+export declare const NFSE_FEE_REIMBURSEMENT_CONSUMING_STATES: readonly string[];
+/** Estados em voo: bloqueiam nova execução para o mesmo tenant/competência. */
+export declare const NFSE_FEE_REIMBURSEMENT_IN_FLIGHT_STATES: readonly string[];
+/** 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;
+        type: 'asaas_subaccount';
+        env: 'production';
+        asaas_account_id: string;
+        wallet_id: string;
+    };
+    /** 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_own_account' | 'not_eligible_contract_flag' | 'no_contract' | 'subaccount_not_ready' | 'fee_unavailable';
+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;
+    /** 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/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,134 @@
+// ── 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'];
+
+/** 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;
+    type: 'asaas_subaccount';
+    env: 'production';
+    asaas_account_id: string;
+    wallet_id: string;
+  };
+  /** 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_own_account' // provider type 'asaas' (conta própria) — D1
+  | 'not_eligible_contract_flag'
+  | 'no_contract'
+  | 'subaccount_not_ready' // subconta inativa/sem wallet_id/sem env 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;
+  /** 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/evo-task/index.d.ts

@@ -191,6 +191,7 @@ export interface IAutoTask extends ITaskBase {
     retry?: ITaskRetryPolicy;
     on_failure?: ITaskOnFailure;
     runner_state?: ITaskRunnerState;
+    outcome?: ITaskOutcome | null;
     auto: ITaskAutoSpec;
 }
 export type ITask = IHumanTask | IAutoTask;
@@ -198,8 +199,20 @@ export declare const TaskExecutionStatusEnum: {
     readonly Success: "success";
     readonly Error: "error";
     readonly Retry: "retry";
+    readonly Suppressed: "suppressed";
 };
 export type TaskExecutionStatus = (typeof TaskExecutionStatusEnum)[keyof typeof TaskExecutionStatusEnum];
+export type TaskOutcomeClass = "legitimate" | "defect";
+export interface ITaskOutcome {
+    class: TaskOutcomeClass;
+    reason: string;
+    label: string;
+    message: string;
+    action_hint?: string;
+    scope?: string;
+    details?: Record<string, unknown>;
+    at: Date;
+}
 export interface ITaskExecution extends IFireDoc {
     taskId: string;
     handler: TaskAutoHandler;
@@ -214,6 +227,7 @@ export interface ITaskExecution extends IFireDoc {
         code?: string | number;
         details?: Record<string, unknown>;
     };
+    outcome?: ITaskOutcome;
     provider?: {
         name?: string;
         message_id?: string;

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

@@ -167,4 +167,7 @@ exports.TaskExecutionStatusEnum = {
     Success: "success",
     Error: "error",
     Retry: "retry",
+    // Handler ran and decided not to deliver; `outcome` says why. The runner
+    // finalizes the task directly (no retry, fallback or handoff).
+    Suppressed: "suppressed",
 };

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

@@ -357,6 +357,10 @@ export interface IAutoTask extends ITaskBase {
   // Runtime state populated by the Task Runner
   runner_state?: ITaskRunnerState;
 
+  // Why the handler decided not to deliver (suppressed | failed by defect).
+  // Reset to null when the task completes or is retried manually.
+  outcome?: ITaskOutcome | null;
+
   // What to execute
   auto: ITaskAutoSpec;
 }
@@ -369,11 +373,29 @@ export const TaskExecutionStatusEnum = {
   Success: "success",
   Error: "error",
   Retry: "retry",
+  // Handler ran and decided not to deliver; `outcome` says why. The runner
+  // finalizes the task directly (no retry, fallback or handoff).
+  Suppressed: "suppressed",
 } as const;
 
 export type TaskExecutionStatus =
   (typeof TaskExecutionStatusEnum)[keyof typeof TaskExecutionStatusEnum];
 
+export type TaskOutcomeClass = "legitimate" | "defect";
+
+// Outcome of an execution that did not deliver. `legitimate` ends the task as
+// `suppressed`; `defect` ends it as `failed` (actionable problem).
+export interface ITaskOutcome {
+  class: TaskOutcomeClass;
+  reason: string;
+  label: string;
+  message: string;
+  action_hint?: string;
+  scope?: string;
+  details?: Record<string, unknown>;
+  at: Date;
+}
+
 export interface ITaskExecution extends IFireDoc {
   taskId: string;
   handler: TaskAutoHandler;
@@ -391,6 +413,9 @@ export interface ITaskExecution extends IFireDoc {
     details?: Record<string, unknown>;
   };
 
+  // Present when status is suppressed
+  outcome?: ITaskOutcome;
+
   // Optional provider metadata (e.g. WhatsApp provider message id)
   provider?: {
     name?: string;

package/dist/types/evo-task-runner/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./fb_collections";
 import type { IFireDoc } from "../shared";
-import type { TaskAutoHandler, TaskExecutionStatus, TaskRetryStrategy } from "../evo-task";
+import type { TaskAutoHandler, ITaskOutcome, TaskExecutionStatus, TaskRetryStrategy } from "../evo-task";
 export declare const EvoTaskRunnerPermissions: {
     readonly List: "evo_task_runner_read";
     readonly Get: "evo_task_runner_read";
@@ -55,6 +55,7 @@ export interface ITaskExecutionReport {
     attempt: number;
     correlation_id?: string;
     status: TaskExecutionStatus;
+    outcome?: ITaskOutcome;
     started_at: Date;
     completed_at: Date;
     suggested_retry?: {

package/dist/types/evo-task-runner/index.ts

@@ -2,6 +2,7 @@ export * from "./fb_collections";
 import type { IFireDoc } from "../shared";
 import type {
   TaskAutoHandler,
+  ITaskOutcome,
   TaskExecutionStatus,
   TaskRetryStrategy,
 } from "../evo-task";
@@ -115,7 +116,10 @@ export interface ITaskExecutionReport {
   correlation_id?: string;
 
   // Status/result
-  status: TaskExecutionStatus; // success | error | retry
+  status: TaskExecutionStatus; // success | error | retry | suppressed
+
+  // Required when status is suppressed: why nothing was delivered
+  outcome?: ITaskOutcome;
 
   started_at: Date;
   completed_at: Date;

package/package.json

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