evo360-types 1.3.787 → 1.3.791

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16190,8 +16190,8 @@ export declare const zNexFinopsContractAsaasInfoSchema: z.ZodObject<{
16190
16190
  env: z.ZodNullable<z.ZodOptional<z.ZodEnum<["sandbox", "production"]>>>;
16191
16191
  }, "strip", z.ZodTypeAny, {
16192
16192
  value?: number | null | undefined;
16193
- customer_id?: string | null | undefined;
16194
16193
  cycle?: string | null | undefined;
16194
+ customer_id?: string | null | undefined;
16195
16195
  subscription_id?: string | null | undefined;
16196
16196
  subscription_status?: "ACTIVE" | "EXPIRED" | "INACTIVE" | null | undefined;
16197
16197
  next_due_date?: string | null | undefined;
@@ -16201,8 +16201,8 @@ export declare const zNexFinopsContractAsaasInfoSchema: z.ZodObject<{
16201
16201
  env?: "sandbox" | "production" | null | undefined;
16202
16202
  }, {
16203
16203
  value?: number | null | undefined;
16204
- customer_id?: string | null | undefined;
16205
16204
  cycle?: string | null | undefined;
16205
+ customer_id?: string | null | undefined;
16206
16206
  subscription_id?: string | null | undefined;
16207
16207
  subscription_status?: "ACTIVE" | "EXPIRED" | "INACTIVE" | null | undefined;
16208
16208
  next_due_date?: string | null | undefined;
@@ -0,0 +1,97 @@
1
+ /**
2
+ * feat-328 F2 — extrato do Billing de uma competência e o snapshot de preço.
3
+ *
4
+ * O extrato é o "racional" linha a linha do valor de um tenant num mês. É calculado
5
+ * pelo motor do backend (`@evo/nex-model`, `computeBillingStatement`) e congelado
6
+ * na cobrança em `usage_snapshot`, junto com `pricing_snapshot` (a tabela resolvida
7
+ * que o produziu). Com os dois, a cobrança se explica sozinha, mesmo que o consumo,
8
+ * o contrato ou a tabela mudem depois.
9
+ *
10
+ * Schema 1 (`ssr_excess_or_table_v1`) = extratos congelados pelo front do Nexus até
11
+ * out/2026, com preço fixo no código. Schema 2 (`price_table_v1`) = motor do
12
+ * backend lendo a tabela de preço. Os campos comuns têm o MESMO nome e significado
13
+ * nos dois — o front lê os dois sem migração.
14
+ */
15
+ import type { ResolvedPriceLine } from './price-table';
16
+ /** Modo de cobrança do contrato (Q13/Q17). Ausente = `standard`. */
17
+ export type NexFinopsBillingMode = 'standard' | 'trial';
18
+ export declare const BILLING_STATEMENT_SCHEMA = 2;
19
+ export declare const BILLING_STATEMENT_FORMULA = "price_table_v1";
20
+ export interface IBillingStatementLine {
21
+ /**
22
+ * Chave aberta: métrica do catálogo (`attendances`, `sms`…), módulo (`recurring`)
23
+ * ou `extra:<CAT>` para serviço fixo do contrato.
24
+ */
25
+ key: string;
26
+ label: string;
27
+ /** `usage` = consumo × franquia; `fixed` = serviço fixo do contrato; `recurring` = módulo ativo. */
28
+ kind: 'usage' | 'fixed' | 'recurring';
29
+ /** Categoria do item na cobrança (`services[].category`) que este valor compõe. */
30
+ billing_category: string;
31
+ /** Descrição sugerida para o item na cobrança. */
32
+ billing_description: string;
33
+ /** `null` = série indisponível no mês (≠ zero). */
34
+ used?: number | null;
35
+ /** `null` = métrica sem franquia nos contratos (não cobrada). */
36
+ included?: number | null;
37
+ excess?: number;
38
+ unit_price?: number | null;
39
+ amount: number;
40
+ /** Tabela da cadeia que declarou o preço da linha (schema 2). `null` em `fixed`. */
41
+ source?: {
42
+ table_id: string;
43
+ } | null;
44
+ /** Contrato de origem da linha `fixed` (schema 2). */
45
+ contract_id?: string | null;
46
+ }
47
+ export interface IBillingStatement {
48
+ schema: number;
49
+ formula: string;
50
+ /** `YYYY-MM`. */
51
+ competency: string;
52
+ currency: 'BRL';
53
+ tenant: string | null;
54
+ /** Contratos vigentes que compõem o extrato (schema 2). */
55
+ contract_ids?: string[];
56
+ /** Schema 2. Ausente (schema 1) = `standard`. */
57
+ billing_mode?: NexFinopsBillingMode;
58
+ /** Base dos atendimentos: soma do SSR dos contratos. */
59
+ ssr_base: number;
60
+ /** Por que o valor de atendimentos é o que é. */
61
+ attendances: {
62
+ rule: 'base' | 'excess' | 'table';
63
+ with_excess: number | null;
64
+ table_value: number | null;
65
+ table_tier: number | null;
66
+ };
67
+ lines: IBillingStatementLine[];
68
+ /** Valor calculado. Em `trial` é 0 (o extrato mostra o que seria cobrado nas linhas). */
69
+ total: number;
70
+ /** Schema 2. `false` em `trial`: o extrato existe, a cobrança não. */
71
+ charged?: boolean;
72
+ /** Origem dos números de consumo. */
73
+ usage_source: string;
74
+ /**
75
+ * Schema 2. `false` = o mês está fora da janela da série de consumo (12 meses).
76
+ * ⚠️ NÃO detecta ingestão falha: a série preenche com zero todo mês da janela, então
77
+ * mês com ingestão incompleta sai `true` com consumo baixo. O gate de ingestão é da feat-252.
78
+ */
79
+ usage_available?: boolean;
80
+ /** Schema 2. Métricas com consumo e sem franquia: não cobradas, só sinalizadas. */
81
+ used_without_allowance?: string[];
82
+ /** Schema 2. Métricas com franquia e excedente mas sem linha de preço (ou `disabled`). */
83
+ used_without_price?: string[];
84
+ /** Preenchidos só no congelamento. */
85
+ captured_at?: string;
86
+ captured_by?: string | null;
87
+ }
88
+ /** Tabela de preço resolvida que produziu o extrato, congelada na cobrança. */
89
+ export interface INexFinopsBillingPricingSnapshot {
90
+ /** Da tabela do contrato até a padrão, inclusive. */
91
+ table_chain: string[];
92
+ lines: Record<string, ResolvedPriceLine>;
93
+ /** Módulos considerados para linhas `recurring` (ativos no fechamento, `trial` fora — Q5). */
94
+ modules_active: string[];
95
+ billing_mode: NexFinopsBillingMode;
96
+ resolved_at: string;
97
+ }
@@ -0,0 +1,19 @@
1
+ "use strict";
2
+ /**
3
+ * feat-328 F2 — extrato do Billing de uma competência e o snapshot de preço.
4
+ *
5
+ * O extrato é o "racional" linha a linha do valor de um tenant num mês. É calculado
6
+ * pelo motor do backend (`@evo/nex-model`, `computeBillingStatement`) e congelado
7
+ * na cobrança em `usage_snapshot`, junto com `pricing_snapshot` (a tabela resolvida
8
+ * que o produziu). Com os dois, a cobrança se explica sozinha, mesmo que o consumo,
9
+ * o contrato ou a tabela mudem depois.
10
+ *
11
+ * Schema 1 (`ssr_excess_or_table_v1`) = extratos congelados pelo front do Nexus até
12
+ * out/2026, com preço fixo no código. Schema 2 (`price_table_v1`) = motor do
13
+ * backend lendo a tabela de preço. Os campos comuns têm o MESMO nome e significado
14
+ * nos dois — o front lê os dois sem migração.
15
+ */
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.BILLING_STATEMENT_FORMULA = exports.BILLING_STATEMENT_SCHEMA = void 0;
18
+ exports.BILLING_STATEMENT_SCHEMA = 2;
19
+ exports.BILLING_STATEMENT_FORMULA = 'price_table_v1';
@@ -0,0 +1,101 @@
1
+ /**
2
+ * feat-328 F2 — extrato do Billing de uma competência e o snapshot de preço.
3
+ *
4
+ * O extrato é o "racional" linha a linha do valor de um tenant num mês. É calculado
5
+ * pelo motor do backend (`@evo/nex-model`, `computeBillingStatement`) e congelado
6
+ * na cobrança em `usage_snapshot`, junto com `pricing_snapshot` (a tabela resolvida
7
+ * que o produziu). Com os dois, a cobrança se explica sozinha, mesmo que o consumo,
8
+ * o contrato ou a tabela mudem depois.
9
+ *
10
+ * Schema 1 (`ssr_excess_or_table_v1`) = extratos congelados pelo front do Nexus até
11
+ * out/2026, com preço fixo no código. Schema 2 (`price_table_v1`) = motor do
12
+ * backend lendo a tabela de preço. Os campos comuns têm o MESMO nome e significado
13
+ * nos dois — o front lê os dois sem migração.
14
+ */
15
+
16
+ import type { ResolvedPriceLine } from './price-table';
17
+
18
+ /** Modo de cobrança do contrato (Q13/Q17). Ausente = `standard`. */
19
+ export type NexFinopsBillingMode = 'standard' | 'trial';
20
+
21
+ export const BILLING_STATEMENT_SCHEMA = 2;
22
+ export const BILLING_STATEMENT_FORMULA = 'price_table_v1';
23
+
24
+ export interface IBillingStatementLine {
25
+ /**
26
+ * Chave aberta: métrica do catálogo (`attendances`, `sms`…), módulo (`recurring`)
27
+ * ou `extra:<CAT>` para serviço fixo do contrato.
28
+ */
29
+ key: string;
30
+ label: string;
31
+ /** `usage` = consumo × franquia; `fixed` = serviço fixo do contrato; `recurring` = módulo ativo. */
32
+ kind: 'usage' | 'fixed' | 'recurring';
33
+ /** Categoria do item na cobrança (`services[].category`) que este valor compõe. */
34
+ billing_category: string;
35
+ /** Descrição sugerida para o item na cobrança. */
36
+ billing_description: string;
37
+ /** `null` = série indisponível no mês (≠ zero). */
38
+ used?: number | null;
39
+ /** `null` = métrica sem franquia nos contratos (não cobrada). */
40
+ included?: number | null;
41
+ excess?: number;
42
+ unit_price?: number | null;
43
+ amount: number;
44
+ /** Tabela da cadeia que declarou o preço da linha (schema 2). `null` em `fixed`. */
45
+ source?: { table_id: string } | null;
46
+ /** Contrato de origem da linha `fixed` (schema 2). */
47
+ contract_id?: string | null;
48
+ }
49
+
50
+ export interface IBillingStatement {
51
+ schema: number;
52
+ formula: string;
53
+ /** `YYYY-MM`. */
54
+ competency: string;
55
+ currency: 'BRL';
56
+ tenant: string | null;
57
+ /** Contratos vigentes que compõem o extrato (schema 2). */
58
+ contract_ids?: string[];
59
+ /** Schema 2. Ausente (schema 1) = `standard`. */
60
+ billing_mode?: NexFinopsBillingMode;
61
+ /** Base dos atendimentos: soma do SSR dos contratos. */
62
+ ssr_base: number;
63
+ /** Por que o valor de atendimentos é o que é. */
64
+ attendances: {
65
+ rule: 'base' | 'excess' | 'table';
66
+ with_excess: number | null;
67
+ table_value: number | null;
68
+ table_tier: number | null;
69
+ };
70
+ lines: IBillingStatementLine[];
71
+ /** Valor calculado. Em `trial` é 0 (o extrato mostra o que seria cobrado nas linhas). */
72
+ total: number;
73
+ /** Schema 2. `false` em `trial`: o extrato existe, a cobrança não. */
74
+ charged?: boolean;
75
+ /** Origem dos números de consumo. */
76
+ usage_source: string;
77
+ /**
78
+ * Schema 2. `false` = o mês está fora da janela da série de consumo (12 meses).
79
+ * ⚠️ NÃO detecta ingestão falha: a série preenche com zero todo mês da janela, então
80
+ * mês com ingestão incompleta sai `true` com consumo baixo. O gate de ingestão é da feat-252.
81
+ */
82
+ usage_available?: boolean;
83
+ /** Schema 2. Métricas com consumo e sem franquia: não cobradas, só sinalizadas. */
84
+ used_without_allowance?: string[];
85
+ /** Schema 2. Métricas com franquia e excedente mas sem linha de preço (ou `disabled`). */
86
+ used_without_price?: string[];
87
+ /** Preenchidos só no congelamento. */
88
+ captured_at?: string;
89
+ captured_by?: string | null;
90
+ }
91
+
92
+ /** Tabela de preço resolvida que produziu o extrato, congelada na cobrança. */
93
+ export interface INexFinopsBillingPricingSnapshot {
94
+ /** Da tabela do contrato até a padrão, inclusive. */
95
+ table_chain: string[];
96
+ lines: Record<string, ResolvedPriceLine>;
97
+ /** Módulos considerados para linhas `recurring` (ativos no fechamento, `trial` fora — Q5). */
98
+ modules_active: string[];
99
+ billing_mode: NexFinopsBillingMode;
100
+ resolved_at: string;
101
+ }
@@ -1,5 +1,6 @@
1
1
  import type { IFireGlobalDoc } from '../../shared';
2
2
  import type { NexFinopsPaymentMethodKind } from './payment-method';
3
+ import type { IBillingStatement, INexFinopsBillingPricingSnapshot } from './billing-statement';
3
4
  export type NexFinopsBillingStatus = 'draft' | 'issued' | 'paid' | 'overdue' | 'canceled';
4
5
  export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'other';
5
6
  export interface INexFinopsBillingServiceItem {
@@ -201,6 +202,14 @@ export interface INexFinopsBilling extends IFireGlobalDoc {
201
202
  competency?: INexFinopsBillingCompetency | null;
202
203
  contract_snapshot?: Record<string, unknown> | null;
203
204
  customer_snapshot?: Record<string, unknown> | null;
205
+ /**
206
+ * Extrato da competência congelado na cobrança. Schema 1 = gravado pelo front do
207
+ * Nexus até out/2026 (lido como está); schema 2 = motor do backend. Só o backend
208
+ * grava schema 2 (`POST /billings/:id/freeze-statement` ou `generate` com `from_statement`).
209
+ */
210
+ usage_snapshot?: IBillingStatement | null;
211
+ /** Tabela de preço resolvida que produziu o `usage_snapshot` schema 2. */
212
+ pricing_snapshot?: INexFinopsBillingPricingSnapshot | null;
204
213
  notes?: string | null;
205
214
  /** Método herdado do `default_payment_method_id` do contrato na geração (ou escolhido depois). */
206
215
  payment_method_id?: string | null;
@@ -1,5 +1,6 @@
1
1
  import type { IFireGlobalDoc } from '../../shared';
2
2
  import type { NexFinopsPaymentMethodKind } from './payment-method';
3
+ import type { IBillingStatement, INexFinopsBillingPricingSnapshot } from './billing-statement';
3
4
 
4
5
  // ── Status ──
5
6
 
@@ -263,6 +264,17 @@ export interface INexFinopsBilling extends IFireGlobalDoc {
263
264
  // Snapshot do cliente no momento da geração (dados para NF)
264
265
  customer_snapshot?: Record<string, unknown> | null;
265
266
 
267
+ // ── Extrato congelado (feat-252 D2 / feat-328 F2) ──
268
+
269
+ /**
270
+ * Extrato da competência congelado na cobrança. Schema 1 = gravado pelo front do
271
+ * Nexus até out/2026 (lido como está); schema 2 = motor do backend. Só o backend
272
+ * grava schema 2 (`POST /billings/:id/freeze-statement` ou `generate` com `from_statement`).
273
+ */
274
+ usage_snapshot?: IBillingStatement | null;
275
+ /** Tabela de preço resolvida que produziu o `usage_snapshot` schema 2. */
276
+ pricing_snapshot?: INexFinopsBillingPricingSnapshot | null;
277
+
266
278
  // Observações
267
279
  notes?: string | null;
268
280
 
@@ -1,3 +1,4 @@
1
+ import type { NexFinopsBillingMode } from './billing-statement';
1
2
  import type { IFireGlobalDoc } from '../../shared';
2
3
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
3
4
  /**
@@ -209,6 +210,12 @@ export interface INexFinopsContract extends IFireGlobalDoc {
209
210
  * tabela (efetiva) — validado pelo backend ao ativar o contrato.
210
211
  */
211
212
  price_table_id?: string | null;
213
+ /**
214
+ * feat-328 Q13/Q17 — modo de cobrança. ⚠️ Ausente = `standard`.
215
+ * `trial`: o fechamento calcula o extrato e NÃO gera cobrança. Exige `ends_at`
216
+ * (validação de escrita entra na F5; até lá o campo só é lido).
217
+ */
218
+ billing_mode?: NexFinopsBillingMode;
212
219
  }
213
220
  export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
214
221
  /**
@@ -1,3 +1,4 @@
1
+ import type { NexFinopsBillingMode } from './billing-statement';
1
2
  import type { IFireGlobalDoc } from '../../shared';
2
3
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
3
4
 
@@ -252,6 +253,13 @@ export interface INexFinopsContract extends IFireGlobalDoc {
252
253
  * tabela (efetiva) — validado pelo backend ao ativar o contrato.
253
254
  */
254
255
  price_table_id?: string | null;
256
+
257
+ /**
258
+ * feat-328 Q13/Q17 — modo de cobrança. ⚠️ Ausente = `standard`.
259
+ * `trial`: o fechamento calcula o extrato e NÃO gera cobrança. Exige `ends_at`
260
+ * (validação de escrita entra na F5; até lá o campo só é lido).
261
+ */
262
+ billing_mode?: NexFinopsBillingMode;
255
263
  }
256
264
 
257
265
  // ── Status transitions ──
@@ -3,6 +3,7 @@ export * from "./common";
3
3
  export * from "./common/taker";
4
4
  export * from "./common/contract";
5
5
  export * from "./common/price-table";
6
+ export * from "./common/billing-statement";
6
7
  export * from "./common/proposal";
7
8
  export * from "./common/billing";
8
9
  export * from "./common/payment-method";
@@ -20,6 +20,7 @@ __exportStar(require("./common"), exports);
20
20
  __exportStar(require("./common/taker"), exports);
21
21
  __exportStar(require("./common/contract"), exports);
22
22
  __exportStar(require("./common/price-table"), exports);
23
+ __exportStar(require("./common/billing-statement"), exports);
23
24
  __exportStar(require("./common/proposal"), exports);
24
25
  __exportStar(require("./common/billing"), exports);
25
26
  __exportStar(require("./common/payment-method"), exports);
@@ -5,6 +5,7 @@ export * from "./common";
5
5
  export * from "./common/taker";
6
6
  export * from "./common/contract";
7
7
  export * from "./common/price-table";
8
+ export * from "./common/billing-statement";
8
9
  export * from "./common/proposal";
9
10
  export * from "./common/billing";
10
11
  export * from "./common/payment-method";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "evo360-types",
3
- "version": "1.3.787",
3
+ "version": "1.3.791",
4
4
  "description": "HREVO360 Shared Types",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",