evo360-types 1.3.818 → 1.3.822

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.
@@ -15880,6 +15880,8 @@ export declare const zNexFinopsProposalWriteSchema: z.ZodObject<{
15880
15880
  notes?: string | null | undefined;
15881
15881
  terms?: string | null | undefined;
15882
15882
  base_amount?: number | undefined;
15883
+ valid_until?: string | undefined;
15884
+ offer_slug?: string | null | undefined;
15883
15885
  html_content?: string | undefined;
15884
15886
  due_day?: number | undefined;
15885
15887
  accepted_payment_methods?: ("payment_link" | "boleto" | "card_subscription")[] | undefined;
@@ -15906,8 +15908,6 @@ export declare const zNexFinopsProposalWriteSchema: z.ZodObject<{
15906
15908
  city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
15907
15909
  state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
15908
15910
  }, z.ZodTypeAny, "passthrough"> | null | undefined;
15909
- valid_until?: string | undefined;
15910
- offer_slug?: string | null | undefined;
15911
15911
  attribution?: {
15912
15912
  site?: string | null | undefined;
15913
15913
  utm_source?: string | null | undefined;
@@ -15926,6 +15926,8 @@ export declare const zNexFinopsProposalWriteSchema: z.ZodObject<{
15926
15926
  notes?: string | null | undefined;
15927
15927
  terms?: string | null | undefined;
15928
15928
  base_amount?: number | undefined;
15929
+ valid_until?: string | undefined;
15930
+ offer_slug?: string | null | undefined;
15929
15931
  html_content?: string | undefined;
15930
15932
  due_day?: number | undefined;
15931
15933
  accepted_payment_methods?: ("payment_link" | "boleto" | "card_subscription")[] | undefined;
@@ -15952,8 +15954,6 @@ export declare const zNexFinopsProposalWriteSchema: z.ZodObject<{
15952
15954
  city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
15953
15955
  state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
15954
15956
  }, z.ZodTypeAny, "passthrough"> | null | undefined;
15955
- valid_until?: string | undefined;
15956
- offer_slug?: string | null | undefined;
15957
15957
  attribution?: {
15958
15958
  site?: string | null | undefined;
15959
15959
  utm_source?: string | null | undefined;
@@ -16089,6 +16089,8 @@ export declare const zNexFinopsProposalSchema: z.ZodObject<{
16089
16089
  notes?: string | null | undefined;
16090
16090
  terms?: string | null | undefined;
16091
16091
  base_amount?: number | undefined;
16092
+ valid_until?: string | undefined;
16093
+ offer_slug?: string | null | undefined;
16092
16094
  html_content?: string | undefined;
16093
16095
  due_day?: number | undefined;
16094
16096
  accepted_payment_methods?: ("payment_link" | "boleto" | "card_subscription")[] | undefined;
@@ -16115,8 +16117,6 @@ export declare const zNexFinopsProposalSchema: z.ZodObject<{
16115
16117
  city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16116
16118
  state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16117
16119
  }, z.ZodTypeAny, "passthrough"> | null | undefined;
16118
- valid_until?: string | undefined;
16119
- offer_slug?: string | null | undefined;
16120
16120
  attribution?: {
16121
16121
  site?: string | null | undefined;
16122
16122
  utm_source?: string | null | undefined;
@@ -16138,6 +16138,8 @@ export declare const zNexFinopsProposalSchema: z.ZodObject<{
16138
16138
  notes?: string | null | undefined;
16139
16139
  terms?: string | null | undefined;
16140
16140
  base_amount?: number | undefined;
16141
+ valid_until?: string | undefined;
16142
+ offer_slug?: string | null | undefined;
16141
16143
  html_content?: string | undefined;
16142
16144
  due_day?: number | undefined;
16143
16145
  accepted_payment_methods?: ("payment_link" | "boleto" | "card_subscription")[] | undefined;
@@ -16164,8 +16166,6 @@ export declare const zNexFinopsProposalSchema: z.ZodObject<{
16164
16166
  city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16165
16167
  state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16166
16168
  }, z.ZodTypeAny, "passthrough"> | null | undefined;
16167
- valid_until?: string | undefined;
16168
- offer_slug?: string | null | undefined;
16169
16169
  attribution?: {
16170
16170
  site?: string | null | undefined;
16171
16171
  utm_source?: string | null | undefined;
@@ -16660,11 +16660,11 @@ export declare const zNexFinopsContractAllowancesWriteSchema: z.ZodObject<{
16660
16660
  /** feat-353 — slug da oferta de origem. */
16661
16661
  offer_slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
16662
16662
  }, "strip", z.ZodTypeAny, {
16663
+ offer_slug?: string | null | undefined;
16663
16664
  allowances?: Record<string, {
16664
16665
  included: number;
16665
16666
  unit_price_excess?: number | null | undefined;
16666
16667
  }> | null | undefined;
16667
- offer_slug?: string | null | undefined;
16668
16668
  alerts_enabled?: boolean | null | undefined;
16669
16669
  alert_thresholds?: number[] | null | undefined;
16670
16670
  nfse_fee_reimbursement?: boolean | null | undefined;
@@ -16674,11 +16674,11 @@ export declare const zNexFinopsContractAllowancesWriteSchema: z.ZodObject<{
16674
16674
  capabilities?: Record<string, string | number | boolean> | null | undefined;
16675
16675
  }> | null | undefined;
16676
16676
  }, {
16677
+ offer_slug?: string | null | undefined;
16677
16678
  allowances?: Record<string, {
16678
16679
  included: number;
16679
16680
  unit_price_excess?: number | null | undefined;
16680
16681
  }> | null | undefined;
16681
- offer_slug?: string | null | undefined;
16682
16682
  alerts_enabled?: boolean | null | undefined;
16683
16683
  alert_thresholds?: number[] | null | undefined;
16684
16684
  nfse_fee_reimbursement?: boolean | null | undefined;
@@ -17539,6 +17539,11 @@ export declare const zNexVendasOfferStartRequestSchema: z.ZodObject<{
17539
17539
  landing_path?: string | null | undefined;
17540
17540
  }>>>;
17541
17541
  privacy_accepted: z.ZodLiteral<true>;
17542
+ /**
17543
+ * feat-367 — como o cliente digitou. SEM checar formato aqui: código inválido
17544
+ * não pode derrubar o `start` (D4); o backend normaliza e segue sem cupom.
17545
+ */
17546
+ coupon_code: z.ZodNullable<z.ZodOptional<z.ZodString>>;
17542
17547
  }, "strip", z.ZodTypeAny, {
17543
17548
  name: string;
17544
17549
  email: string;
@@ -17557,6 +17562,7 @@ export declare const zNexVendasOfferStartRequestSchema: z.ZodObject<{
17557
17562
  referrer?: string | null | undefined;
17558
17563
  landing_path?: string | null | undefined;
17559
17564
  } | null | undefined;
17565
+ coupon_code?: string | null | undefined;
17560
17566
  }, {
17561
17567
  name: string;
17562
17568
  email: string;
@@ -17575,4 +17581,5 @@ export declare const zNexVendasOfferStartRequestSchema: z.ZodObject<{
17575
17581
  referrer?: string | null | undefined;
17576
17582
  landing_path?: string | null | undefined;
17577
17583
  } | null | undefined;
17584
+ coupon_code?: string | null | undefined;
17578
17585
  }>;
@@ -1398,5 +1398,10 @@ exports.zNexVendasOfferStartRequestSchema = zod_1.z
1398
1398
  turnstile_token: zod_1.z.string().min(1).max(4096),
1399
1399
  attribution: exports.zNexVendasAttributionSchema.optional().nullable(),
1400
1400
  privacy_accepted: zod_1.z.literal(true),
1401
+ /**
1402
+ * feat-367 — como o cliente digitou. SEM checar formato aqui: código inválido
1403
+ * não pode derrubar o `start` (D4); o backend normaliza e segue sem cupom.
1404
+ */
1405
+ coupon_code: zod_1.z.string().max(64).optional().nullable(),
1401
1406
  })
1402
1407
  .strip();
@@ -1536,5 +1536,10 @@ export const zNexVendasOfferStartRequestSchema = z
1536
1536
  turnstile_token: z.string().min(1).max(4096),
1537
1537
  attribution: zNexVendasAttributionSchema.optional().nullable(),
1538
1538
  privacy_accepted: z.literal(true),
1539
+ /**
1540
+ * feat-367 — como o cliente digitou. SEM checar formato aqui: código inválido
1541
+ * não pode derrubar o `start` (D4); o backend normaliza e segue sem cupom.
1542
+ */
1543
+ coupon_code: z.string().max(64).optional().nullable(),
1539
1544
  })
1540
1545
  .strip();
@@ -2,7 +2,8 @@ import type { IFireGlobalDoc } from '../../shared';
2
2
  import type { NexFinopsPaymentMethodKind } from './payment-method';
3
3
  import type { IBillingStatement, INexFinopsBillingPricingSnapshot } from './billing-statement';
4
4
  export type NexFinopsBillingStatus = 'draft' | 'issued' | 'paid' | 'overdue' | 'canceled';
5
- export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'other';
5
+ /** feat-360 F2: `statement` = extrato da cobrança em PDF, gerado pelo servidor (versionado). */
6
+ export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'statement' | 'other';
6
7
  export interface INexFinopsBillingServiceItem {
7
8
  category: string;
8
9
  description: string;
@@ -13,7 +13,8 @@ export type NexFinopsBillingStatus =
13
13
 
14
14
  // ── Sub-interfaces ──
15
15
 
16
- export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'other';
16
+ /** feat-360 F2: `statement` = extrato da cobrança em PDF, gerado pelo servidor (versionado). */
17
+ export type NexFinopsBillingAttachmentCategory = 'boleto' | 'invoice' | 'statement' | 'other';
17
18
 
18
19
  export interface INexFinopsBillingServiceItem {
19
20
  category: string;
@@ -2,6 +2,7 @@ import type { NexFinopsBillingMode } from './billing-statement';
2
2
  import type { IFireGlobalDoc } from '../../shared';
3
3
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
4
4
  import type { INexVendasPackageModule } from '../../nex-vendas/offer-package';
5
+ import type { INexVendasCouponSnapshot } from '../../nex-vendas/coupon';
5
6
  /**
6
7
  * `cancellation_requested`: o cliente pediu o cancelamento e o contrato está em
7
8
  * processo de encerramento — mas **continua em vigência** e continua faturando
@@ -249,6 +250,11 @@ export interface INexFinopsContract extends IFireGlobalDoc {
249
250
  package_modules?: Record<string, INexVendasPackageModule> | null;
250
251
  /** Slug da oferta de origem (auditoria/relatório). Ausente = contrato sem oferta. */
251
252
  offer_slug?: string | null;
253
+ /**
254
+ * Cópia do snapshot `proposal.coupon` (gravada pelo `ensureContract`), somente
255
+ * leitura. Ausente/null = contrato sem cupom.
256
+ */
257
+ coupon?: INexVendasCouponSnapshot | null;
252
258
  }
253
259
  export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
254
260
  /**
@@ -2,6 +2,7 @@ import type { NexFinopsBillingMode } from './billing-statement';
2
2
  import type { IFireGlobalDoc } from '../../shared';
3
3
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
4
4
  import type { INexVendasPackageModule } from '../../nex-vendas/offer-package';
5
+ import type { INexVendasCouponSnapshot } from '../../nex-vendas/coupon';
5
6
 
6
7
  // ── Status & Recurrence ──
7
8
 
@@ -295,6 +296,14 @@ export interface INexFinopsContract extends IFireGlobalDoc {
295
296
  package_modules?: Record<string, INexVendasPackageModule> | null;
296
297
  /** Slug da oferta de origem (auditoria/relatório). Ausente = contrato sem oferta. */
297
298
  offer_slug?: string | null;
299
+
300
+ // ── Cupom (feat-367) ──
301
+
302
+ /**
303
+ * Cópia do snapshot `proposal.coupon` (gravada pelo `ensureContract`), somente
304
+ * leitura. Ausente/null = contrato sem cupom.
305
+ */
306
+ coupon?: INexVendasCouponSnapshot | null;
298
307
  }
299
308
 
300
309
  // ── Status transitions ──
@@ -2,6 +2,7 @@ import type { IFireGlobalDoc } from '../../shared';
2
2
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
3
3
  import type { INexVendasAttribution } from '../../nex-vendas/offer';
4
4
  import type { INexVendasOfferPackage, INexVendasPackageDisplay } from '../../nex-vendas/offer-package';
5
+ import type { INexVendasCouponSnapshot, INexVendasCouponSnapshotPublic } from '../../nex-vendas/coupon';
5
6
  /**
6
7
  * `viewed` é carimbado pelo endpoint público no primeiro acesso ao `short_code`.
7
8
  * `expired` é **derivado** de `valid_until` na leitura (não há cron): o documento
@@ -118,6 +119,12 @@ export interface INexFinopsProposal extends IFireGlobalDoc {
118
119
  * proposta sem pacote (vendedor ou oferta v1).
119
120
  */
120
121
  package?: INexVendasOfferPackage | null;
122
+ /**
123
+ * Snapshot CONGELADO do cupom aplicado no `start`. Só o backend grava (não entra
124
+ * no `zNexFinopsProposalWriteSchema`). `base_amount` continua CHEIO; a
125
+ * mensalidade cobrada é `effectiveMonthlyAmount(proposal)`. Ausente/null = sem cupom.
126
+ */
127
+ coupon?: INexVendasCouponSnapshot | null;
121
128
  }
122
129
  /** O que o endpoint sem auth expõe. Sem ids internos, sem dado sensível. */
123
130
  export interface INexFinopsProposalPublic {
@@ -173,6 +180,12 @@ export interface INexFinopsProposalPublic {
173
180
  * proposta sem pacote ou backend anterior à feat-353.
174
181
  */
175
182
  package_display?: INexVendasPackageDisplay | null;
183
+ /**
184
+ * feat-367 — cupom aplicado, sem campos internos (`toCouponSnapshotPublic`).
185
+ * `base_amount` continua CHEIO; o preço "por" é `effectiveMonthlyAmount(proposal)`.
186
+ * Ausente/null = sem cupom ou backend anterior à feat-367.
187
+ */
188
+ coupon?: INexVendasCouponSnapshotPublic | null;
176
189
  }
177
190
  /** Mesmos campos de `INexFinopsProposalPrefill`, cada um `null` quando ausente. */
178
191
  export interface INexFinopsProposalPublicPrefill {
@@ -2,6 +2,7 @@ import type { IFireGlobalDoc } from '../../shared';
2
2
  import type { NexVendasContractType } from '../../nex-vendas/adhesion';
3
3
  import type { INexVendasAttribution } from '../../nex-vendas/offer';
4
4
  import type { INexVendasOfferPackage, INexVendasPackageDisplay } from '../../nex-vendas/offer-package';
5
+ import type { INexVendasCouponSnapshot, INexVendasCouponSnapshotPublic } from '../../nex-vendas/coupon';
5
6
 
6
7
  // ── Status, origem e formas de pagamento ──
7
8
 
@@ -157,6 +158,15 @@ export interface INexFinopsProposal extends IFireGlobalDoc {
157
158
  * proposta sem pacote (vendedor ou oferta v1).
158
159
  */
159
160
  package?: INexVendasOfferPackage | null;
161
+
162
+ // ── Cupom (feat-367) ──
163
+
164
+ /**
165
+ * Snapshot CONGELADO do cupom aplicado no `start`. Só o backend grava (não entra
166
+ * no `zNexFinopsProposalWriteSchema`). `base_amount` continua CHEIO; a
167
+ * mensalidade cobrada é `effectiveMonthlyAmount(proposal)`. Ausente/null = sem cupom.
168
+ */
169
+ coupon?: INexVendasCouponSnapshot | null;
160
170
  }
161
171
 
162
172
  // ── Projeção pública ──
@@ -213,6 +223,12 @@ export interface INexFinopsProposalPublic {
213
223
  * proposta sem pacote ou backend anterior à feat-353.
214
224
  */
215
225
  package_display?: INexVendasPackageDisplay | null;
226
+ /**
227
+ * feat-367 — cupom aplicado, sem campos internos (`toCouponSnapshotPublic`).
228
+ * `base_amount` continua CHEIO; o preço "por" é `effectiveMonthlyAmount(proposal)`.
229
+ * Ausente/null = sem cupom ou backend anterior à feat-367.
230
+ */
231
+ coupon?: INexVendasCouponSnapshotPublic | null;
216
232
  }
217
233
 
218
234
  /** Mesmos campos de `INexFinopsProposalPrefill`, cada um `null` quando ausente. */
@@ -0,0 +1,231 @@
1
+ import type { IFireGlobalDoc } from '../shared';
2
+ /** Collection `core/nexus/apps/nex-vendas/coupons/{CODE}` (doc id = código). */
3
+ export declare const NEX_VENDAS_COUPONS_COLLECTION = "coupons";
4
+ /** Subcollection `coupons/{CODE}/redemptions/{short_code}` (um uso por jornada). */
5
+ export declare const NEX_VENDAS_COUPON_REDEMPTIONS_COLLECTION = "redemptions";
6
+ /** Doc de configuração dos cupons (`INexVendasCouponsConfig`). */
7
+ export declare const NEX_VENDAS_COUPONS_CONFIG_PATH = "platform/nex-vendas/coupons/config";
8
+ /**
9
+ * Piso padrão da mensalidade com desconto, em reais, quando a config não informa
10
+ * `min_monthly_amount` (D9 — R$ 5 já é cobrado em produção pelo Asaas).
11
+ */
12
+ export declare const NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT = 5;
13
+ /** D8 — tamanho exato do código. */
14
+ export declare const NEX_VENDAS_COUPON_CODE_LENGTH = 6;
15
+ /** D8 — formato do código já normalizado: exatamente 6 letras maiúsculas e números. */
16
+ export declare const NEX_VENDAS_COUPON_CODE_REGEX: RegExp;
17
+ /** Faixa do desconto percentual (inteiro). 100% é "período grátis", fora do escopo. */
18
+ export declare const NEX_VENDAS_COUPON_PERCENT_MIN = 1;
19
+ export declare const NEX_VENDAS_COUPON_PERCENT_MAX = 99;
20
+ /** Teto de `duration_months` (F5). Na F1 o cadastro só aceita `null`. */
21
+ export declare const NEX_VENDAS_COUPON_MAX_DURATION_MONTHS = 24;
22
+ export type NexVendasCouponDiscountType = 'percent' | 'fixed';
23
+ /** `inactive` = invalidado no Nexus (com motivo). */
24
+ export type NexVendasCouponStatus = 'active' | 'inactive';
25
+ /**
26
+ * Cupom (BA §4.1). Doc id = `code`, imutável depois de criado.
27
+ * Regras de escrita (formato, faixas, ofertas existentes) ficam no backend.
28
+ */
29
+ export interface INexVendasCoupon extends IFireGlobalDoc {
30
+ /** `^[A-Z0-9]{6}$` (D8). Igual ao doc id. */
31
+ code: string;
32
+ /** Nome INTERNO ("Black Friday 2026"). Não vai para o shop. */
33
+ name: string;
34
+ discount_type: NexVendasCouponDiscountType;
35
+ /** `percent`: inteiro 1–99. `fixed`: reais (> 0, centavos inteiros). */
36
+ discount_value: number;
37
+ /**
38
+ * Quantas mensalidades têm desconto. `null` = enquanto durar o contrato.
39
+ * 1..24 só a partir da F5 (reversão por webhook).
40
+ */
41
+ duration_months: number | null;
42
+ /** Inteiro ≥ 1, ou `null` = sem limite. */
43
+ max_redemptions: number | null;
44
+ /** Data civil `YYYY-MM-DD` (São Paulo), inclusiva. Ausente/null = já vale. */
45
+ valid_from?: string | null;
46
+ /** Data civil `YYYY-MM-DD` (São Paulo), inclusiva. Ausente/null = sem fim. */
47
+ valid_until?: string | null;
48
+ /** Ofertas onde vale. Vazia = NÃO vale em nenhuma (D6, seguro por padrão). */
49
+ offer_slugs: string[];
50
+ status: NexVendasCouponStatus;
51
+ /** Usos resgatados (pagos). Mantido pelo backend em transação. */
52
+ redemption_count: number;
53
+ created_by: string;
54
+ inactivated_by?: string | null;
55
+ inactivated_at?: Date | null;
56
+ inactivation_reason?: string | null;
57
+ }
58
+ /**
59
+ * - `reserved`: `start` com cupom; conta enquanto `reserved_until ≥ agora` (D3).
60
+ * - `redeemed`: pagamento confirmado; conta sempre.
61
+ * - `released`: reserva liberada (cliente tirou o cupom, jornada abandonada…).
62
+ */
63
+ export type NexVendasCouponRedemptionStatus = 'reserved' | 'redeemed' | 'released';
64
+ /** Uso do cupom (BA §4.2): `coupons/{CODE}/redemptions/{short_code}`, um por jornada. */
65
+ export interface INexVendasCouponRedemption extends IFireGlobalDoc {
66
+ /** Código do cupom (redundante com o path; facilita collection group). */
67
+ code: string;
68
+ /** `short_code` da jornada/proposta. Igual ao doc id. */
69
+ short_code: string;
70
+ offer_slug: string;
71
+ proposal_id: string;
72
+ /** Preenchido quando o contrato existir. */
73
+ contract_id?: string | null;
74
+ /** CPF/CNPJ só com dígitos, gravado no `/dados` (D5: um uso por documento). */
75
+ document_number?: string | null;
76
+ status: NexVendasCouponRedemptionStatus;
77
+ /** Fim do `valid_until` da proposta (SP). Reserva vencida não conta. */
78
+ reserved_until: Date;
79
+ /** Desconto mensal aplicado, em reais (cópia do snapshot). */
80
+ discount_amount: number;
81
+ reserved_at: Date;
82
+ redeemed_at?: Date | null;
83
+ released_at?: Date | null;
84
+ /** Motivo curto da liberação (`customer_removed`, `expired`…). Texto livre do backend. */
85
+ release_reason?: string | null;
86
+ }
87
+ /**
88
+ * Snapshot congelado (BA §4.3), igual na proposta e no contrato. Gravado uma vez
89
+ * no `start` e nunca recalculado: editar ou invalidar o cupom não muda o snapshot.
90
+ */
91
+ export interface INexVendasCouponSnapshot {
92
+ code: string;
93
+ /** Nome interno do cupom no momento do uso. Não sai na projeção pública. */
94
+ coupon_name: string;
95
+ discount_type: NexVendasCouponDiscountType;
96
+ discount_value: number;
97
+ /** `null` = enquanto durar o contrato. */
98
+ duration_months: number | null;
99
+ /** Mensalidade cheia da oferta (`base_amount`), em reais. */
100
+ list_amount: number;
101
+ /** Desconto por mês, em reais. */
102
+ discount_amount: number;
103
+ /** Mensalidade com desconto, em reais. */
104
+ discounted_amount: number;
105
+ applied_at: Date;
106
+ /** F5 — quando o desconto acabou (assinatura voltou ao preço cheio). */
107
+ ended_at?: Date | null;
108
+ }
109
+ /**
110
+ * Snapshot para o shop (proposta pública e `coupon-check`): sem nome interno nem
111
+ * auditoria. `duration_label` vem pronto (`couponDurationLabel`).
112
+ */
113
+ export interface INexVendasCouponSnapshotPublic {
114
+ code: string;
115
+ discount_type: NexVendasCouponDiscountType;
116
+ discount_value: number;
117
+ duration_months: number | null;
118
+ /** "enquanto durar o contrato" / "nas 3 primeiras mensalidades". */
119
+ duration_label: string;
120
+ list_amount: number;
121
+ discount_amount: number;
122
+ discounted_amount: number;
123
+ }
124
+ /** Doc `NEX_VENDAS_COUPONS_CONFIG_PATH`. */
125
+ export interface INexVendasCouponsConfig {
126
+ /** Piso da mensalidade com desconto, em reais. Ausente = `NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT`. */
127
+ min_monthly_amount?: number | null;
128
+ }
129
+ /**
130
+ * Motivo INTERNO da recusa (BA §5.3, na ordem de validação). Fica no backend e
131
+ * em log; para o shop vai só `toCouponPublicReason(...)`.
132
+ */
133
+ export type NexVendasCouponInvalidReason = 'invalid_format' | 'not_found' | 'inactive' | 'not_started' | 'expired' | 'offer_not_allowed' | 'exhausted' | 'invalid_discount' | 'below_minimum';
134
+ /**
135
+ * Motivo GENÉRICO devolvido ao shop. Não distingue "não existe" de "inativo"
136
+ * (BA §5.2, contra adivinhação de código).
137
+ * - `not_found`: "Cupom não encontrado".
138
+ * - `expired`: "Este cupom expirou".
139
+ * - `not_for_offer`: "Este cupom não vale para este plano".
140
+ * - `unavailable`: esgotado ou sem condição de aplicar neste plano.
141
+ */
142
+ export type NexVendasCouponPublicReason = 'not_found' | 'expired' | 'not_for_offer' | 'unavailable';
143
+ /** Corpo de `POST /offers/:slug/coupon-check` (público). */
144
+ export interface INexVendasCouponCheckRequest {
145
+ /** Como o cliente digitou; o backend normaliza (`normalizeCouponCode`). */
146
+ code: string;
147
+ }
148
+ /** Resposta de `coupon-check`: só valida e calcula, não reserva. */
149
+ export interface INexVendasCouponCheckResponse {
150
+ valid: boolean;
151
+ /** Só com `valid: false`. */
152
+ reason?: NexVendasCouponPublicReason | null;
153
+ /** Só com `valid: true`: preço calculado para a oferta. */
154
+ snapshot?: INexVendasCouponSnapshotPublic | null;
155
+ }
156
+ /**
157
+ * Resposta do `start` sobre o cupom pedido (D4: cupom inválido não bloqueia, a
158
+ * jornada segue sem cupom e o shop avisa).
159
+ */
160
+ export type NexVendasOfferStartCouponStatus = 'applied' | 'not_applied';
161
+ /**
162
+ * Normaliza o código digitado: `trim` + maiúsculo. Fora do formato (D8: exatamente
163
+ * 6 letras e números) ⇒ `null`. Aceita `unknown` (query string pode vir como lista).
164
+ */
165
+ export declare function normalizeCouponCode(raw: unknown): string | null;
166
+ export interface INexVendasCouponDiscountInput {
167
+ /** Mensalidade cheia, em reais. */
168
+ base_amount: number;
169
+ discount_type: NexVendasCouponDiscountType;
170
+ discount_value: number;
171
+ /** Piso da mensalidade com desconto, em reais (igual ao piso passa). */
172
+ min_amount: number;
173
+ }
174
+ export interface INexVendasCouponDiscountResult {
175
+ discount_amount: number;
176
+ discounted_amount: number;
177
+ }
178
+ export interface INexVendasCouponDiscountError {
179
+ /**
180
+ * - `invalid`: entrada inválida (tipo, percentual fora de 1–99, fixo ≤ 0 ou com
181
+ * fração de centavo, fixo ≥ mensalidade, desconto que arredonda para zero).
182
+ * - `below_minimum`: mensalidade com desconto abaixo do piso.
183
+ */
184
+ error: 'below_minimum' | 'invalid';
185
+ }
186
+ /**
187
+ * Calcula o desconto do cupom sobre a mensalidade. ÚNICA fonte do preço com
188
+ * desconto (backend e shop).
189
+ *
190
+ * - Tudo em CENTAVOS inteiros; o resultado é `centavos / 100` (sem float sujo).
191
+ * - Percentual: desconto arredondado para BAIXO (o cliente paga no máximo o
192
+ * anunciado, nunca centavo a menos). Ex.: 19,90 × 15% = 2,985 ⇒ desconto 2,98.
193
+ * - Fixo: em reais, com no máximo 2 casas, e menor que a mensalidade.
194
+ * - Mensalidade com desconto < `min_amount` ⇒ `below_minimum` (igual passa).
195
+ */
196
+ export declare function applyCouponDiscount(input: INexVendasCouponDiscountInput): INexVendasCouponDiscountResult | INexVendasCouponDiscountError;
197
+ /**
198
+ * Mensalidade que de fato se cobra/exibe: `coupon.discounted_amount` quando houver
199
+ * cupom, senão `base_amount`. Serve para proposta, proposta pública e contrato.
200
+ */
201
+ export declare function effectiveMonthlyAmount(input: {
202
+ base_amount: number;
203
+ coupon?: {
204
+ discounted_amount: number;
205
+ } | null;
206
+ }): number;
207
+ /**
208
+ * Duração do desconto em texto de cliente (pt-BR, curto):
209
+ * - `null`/ausente ⇒ "enquanto durar o contrato";
210
+ * - 1 ⇒ "na primeira mensalidade";
211
+ * - N ⇒ "nas N primeiras mensalidades".
212
+ * Valor fora de inteiro ≥ 1 (não deveria existir; o backend valida) ⇒ "por tempo
213
+ * limitado" — nunca promete desconto permanente por engano.
214
+ */
215
+ export declare function couponDurationLabel(duration_months: number | null | undefined): string;
216
+ /**
217
+ * Hoje (data civil `YYYY-MM-DD` em São Paulo) está na janela do cupom? Bordas
218
+ * inclusivas. `valid_from` ausente = já vale; `valid_until` ausente = sem fim.
219
+ * `todayIsoSp` fora do formato ⇒ `false` (fecha por segurança).
220
+ */
221
+ export declare function isCouponWindowOpen(coupon: {
222
+ valid_from?: string | null;
223
+ valid_until?: string | null;
224
+ }, todayIsoSp: string): boolean;
225
+ /**
226
+ * Motivo interno ⇒ motivo genérico do shop. Formato inválido, inexistente e
227
+ * inativo viram o mesmo `not_found` (BA §5.2).
228
+ */
229
+ export declare function toCouponPublicReason(reason: NexVendasCouponInvalidReason): NexVendasCouponPublicReason;
230
+ /** Snapshot ⇒ projeção pública (sem `coupon_name`/datas; com `duration_label`). */
231
+ export declare function toCouponSnapshotPublic(snapshot: INexVendasCouponSnapshot): INexVendasCouponSnapshotPublic;
@@ -0,0 +1,180 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.NEX_VENDAS_COUPON_MAX_DURATION_MONTHS = exports.NEX_VENDAS_COUPON_PERCENT_MAX = exports.NEX_VENDAS_COUPON_PERCENT_MIN = exports.NEX_VENDAS_COUPON_CODE_REGEX = exports.NEX_VENDAS_COUPON_CODE_LENGTH = exports.NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT = exports.NEX_VENDAS_COUPONS_CONFIG_PATH = exports.NEX_VENDAS_COUPON_REDEMPTIONS_COLLECTION = exports.NEX_VENDAS_COUPONS_COLLECTION = void 0;
4
+ exports.normalizeCouponCode = normalizeCouponCode;
5
+ exports.applyCouponDiscount = applyCouponDiscount;
6
+ exports.effectiveMonthlyAmount = effectiveMonthlyAmount;
7
+ exports.couponDurationLabel = couponDurationLabel;
8
+ exports.isCouponWindowOpen = isCouponWindowOpen;
9
+ exports.toCouponPublicReason = toCouponPublicReason;
10
+ exports.toCouponSnapshotPublic = toCouponSnapshotPublic;
11
+ // ── Cupom de desconto no checkout do shop (feat-367) ──
12
+ //
13
+ // Caminho do dado:
14
+ // cupom (Nexus) ──start──▶ proposal.coupon (snapshot CONGELADO, + redemption `reserved`)
15
+ // ──ensureContract──▶ contract.coupon (mesmo snapshot)
16
+ // ──mark-paid──▶ redemption `redeemed`
17
+ //
18
+ // `proposal.base_amount` continua com a mensalidade CHEIA. Quem cobra/exibe a
19
+ // mensalidade lê `effectiveMonthlyAmount(...)` (= `coupon.discounted_amount` quando
20
+ // houver cupom). O preço com desconto sai SÓ de `applyCouponDiscount` — ninguém
21
+ // recalcula desconto em outro lugar.
22
+ //
23
+ // As funções deste arquivo são PURAS e sem dependência (nem firebase, nem zod):
24
+ // backend e shop importam em runtime.
25
+ // ── Constantes ──
26
+ /** Collection `core/nexus/apps/nex-vendas/coupons/{CODE}` (doc id = código). */
27
+ exports.NEX_VENDAS_COUPONS_COLLECTION = 'coupons';
28
+ /** Subcollection `coupons/{CODE}/redemptions/{short_code}` (um uso por jornada). */
29
+ exports.NEX_VENDAS_COUPON_REDEMPTIONS_COLLECTION = 'redemptions';
30
+ /** Doc de configuração dos cupons (`INexVendasCouponsConfig`). */
31
+ exports.NEX_VENDAS_COUPONS_CONFIG_PATH = 'platform/nex-vendas/coupons/config';
32
+ /**
33
+ * Piso padrão da mensalidade com desconto, em reais, quando a config não informa
34
+ * `min_monthly_amount` (D9 — R$ 5 já é cobrado em produção pelo Asaas).
35
+ */
36
+ exports.NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT = 5;
37
+ /** D8 — tamanho exato do código. */
38
+ exports.NEX_VENDAS_COUPON_CODE_LENGTH = 6;
39
+ /** D8 — formato do código já normalizado: exatamente 6 letras maiúsculas e números. */
40
+ exports.NEX_VENDAS_COUPON_CODE_REGEX = /^[A-Z0-9]{6}$/;
41
+ /** Faixa do desconto percentual (inteiro). 100% é "período grátis", fora do escopo. */
42
+ exports.NEX_VENDAS_COUPON_PERCENT_MIN = 1;
43
+ exports.NEX_VENDAS_COUPON_PERCENT_MAX = 99;
44
+ /** Teto de `duration_months` (F5). Na F1 o cadastro só aceita `null`. */
45
+ exports.NEX_VENDAS_COUPON_MAX_DURATION_MONTHS = 24;
46
+ // ── Funções puras ──
47
+ /**
48
+ * Normaliza o código digitado: `trim` + maiúsculo. Fora do formato (D8: exatamente
49
+ * 6 letras e números) ⇒ `null`. Aceita `unknown` (query string pode vir como lista).
50
+ */
51
+ function normalizeCouponCode(raw) {
52
+ if (typeof raw !== 'string')
53
+ return null;
54
+ const code = raw.trim().toUpperCase();
55
+ return exports.NEX_VENDAS_COUPON_CODE_REGEX.test(code) ? code : null;
56
+ }
57
+ const isFiniteNumber = (n) => typeof n === 'number' && isFinite(n);
58
+ /** Reais → centavos inteiros (representação, não cálculo: corrige 0,29 × 100 = 28,999…). */
59
+ const toCents = (amount) => Math.round(amount * 100);
60
+ /** `amount` tem no máximo 2 casas (sem fração de centavo)? */
61
+ const hasWholeCents = (amount) => Math.abs(amount * 100 - toCents(amount)) < 1e-6;
62
+ /**
63
+ * Calcula o desconto do cupom sobre a mensalidade. ÚNICA fonte do preço com
64
+ * desconto (backend e shop).
65
+ *
66
+ * - Tudo em CENTAVOS inteiros; o resultado é `centavos / 100` (sem float sujo).
67
+ * - Percentual: desconto arredondado para BAIXO (o cliente paga no máximo o
68
+ * anunciado, nunca centavo a menos). Ex.: 19,90 × 15% = 2,985 ⇒ desconto 2,98.
69
+ * - Fixo: em reais, com no máximo 2 casas, e menor que a mensalidade.
70
+ * - Mensalidade com desconto < `min_amount` ⇒ `below_minimum` (igual passa).
71
+ */
72
+ function applyCouponDiscount(input) {
73
+ const { base_amount, discount_type, discount_value, min_amount } = input;
74
+ if (!isFiniteNumber(base_amount) || base_amount <= 0)
75
+ return { error: 'invalid' };
76
+ if (!isFiniteNumber(min_amount) || min_amount < 0)
77
+ return { error: 'invalid' };
78
+ if (!isFiniteNumber(discount_value))
79
+ return { error: 'invalid' };
80
+ const baseCents = toCents(base_amount);
81
+ let discountCents;
82
+ if (discount_type === 'percent') {
83
+ if (Math.floor(discount_value) !== discount_value ||
84
+ discount_value < exports.NEX_VENDAS_COUPON_PERCENT_MIN ||
85
+ discount_value > exports.NEX_VENDAS_COUPON_PERCENT_MAX) {
86
+ return { error: 'invalid' };
87
+ }
88
+ // Inteiro × inteiro: a divisão é a única fonte de fração, e o floor é exato.
89
+ discountCents = Math.floor((baseCents * discount_value) / 100);
90
+ }
91
+ else if (discount_type === 'fixed') {
92
+ if (discount_value <= 0 || !hasWholeCents(discount_value))
93
+ return { error: 'invalid' };
94
+ discountCents = toCents(discount_value);
95
+ if (discountCents >= baseCents)
96
+ return { error: 'invalid' };
97
+ }
98
+ else {
99
+ return { error: 'invalid' };
100
+ }
101
+ if (discountCents <= 0)
102
+ return { error: 'invalid' };
103
+ const discountedCents = baseCents - discountCents;
104
+ if (discountedCents < toCents(min_amount))
105
+ return { error: 'below_minimum' };
106
+ return { discount_amount: discountCents / 100, discounted_amount: discountedCents / 100 };
107
+ }
108
+ /**
109
+ * Mensalidade que de fato se cobra/exibe: `coupon.discounted_amount` quando houver
110
+ * cupom, senão `base_amount`. Serve para proposta, proposta pública e contrato.
111
+ */
112
+ function effectiveMonthlyAmount(input) {
113
+ return input.coupon?.discounted_amount ?? input.base_amount;
114
+ }
115
+ /**
116
+ * Duração do desconto em texto de cliente (pt-BR, curto):
117
+ * - `null`/ausente ⇒ "enquanto durar o contrato";
118
+ * - 1 ⇒ "na primeira mensalidade";
119
+ * - N ⇒ "nas N primeiras mensalidades".
120
+ * Valor fora de inteiro ≥ 1 (não deveria existir; o backend valida) ⇒ "por tempo
121
+ * limitado" — nunca promete desconto permanente por engano.
122
+ */
123
+ function couponDurationLabel(duration_months) {
124
+ if (duration_months === null || duration_months === undefined)
125
+ return 'enquanto durar o contrato';
126
+ if (!isFiniteNumber(duration_months) || Math.floor(duration_months) !== duration_months || duration_months < 1) {
127
+ return 'por tempo limitado';
128
+ }
129
+ if (duration_months === 1)
130
+ return 'na primeira mensalidade';
131
+ return `nas ${duration_months} primeiras mensalidades`;
132
+ }
133
+ const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
134
+ /**
135
+ * Hoje (data civil `YYYY-MM-DD` em São Paulo) está na janela do cupom? Bordas
136
+ * inclusivas. `valid_from` ausente = já vale; `valid_until` ausente = sem fim.
137
+ * `todayIsoSp` fora do formato ⇒ `false` (fecha por segurança).
138
+ */
139
+ function isCouponWindowOpen(coupon, todayIsoSp) {
140
+ if (typeof todayIsoSp !== 'string' || !ISO_DATE_REGEX.test(todayIsoSp))
141
+ return false;
142
+ // `YYYY-MM-DD` compara certo como string.
143
+ if (coupon.valid_from && todayIsoSp < coupon.valid_from)
144
+ return false;
145
+ if (coupon.valid_until && todayIsoSp > coupon.valid_until)
146
+ return false;
147
+ return true;
148
+ }
149
+ /**
150
+ * Motivo interno ⇒ motivo genérico do shop. Formato inválido, inexistente e
151
+ * inativo viram o mesmo `not_found` (BA §5.2).
152
+ */
153
+ function toCouponPublicReason(reason) {
154
+ switch (reason) {
155
+ case 'invalid_format':
156
+ case 'not_found':
157
+ case 'inactive':
158
+ case 'not_started':
159
+ return 'not_found';
160
+ case 'expired':
161
+ return 'expired';
162
+ case 'offer_not_allowed':
163
+ return 'not_for_offer';
164
+ default:
165
+ return 'unavailable';
166
+ }
167
+ }
168
+ /** Snapshot ⇒ projeção pública (sem `coupon_name`/datas; com `duration_label`). */
169
+ function toCouponSnapshotPublic(snapshot) {
170
+ return {
171
+ code: snapshot.code,
172
+ discount_type: snapshot.discount_type,
173
+ discount_value: snapshot.discount_value,
174
+ duration_months: snapshot.duration_months,
175
+ duration_label: couponDurationLabel(snapshot.duration_months),
176
+ list_amount: snapshot.list_amount,
177
+ discount_amount: snapshot.discount_amount,
178
+ discounted_amount: snapshot.discounted_amount,
179
+ };
180
+ }
@@ -0,0 +1,381 @@
1
+ import type { IFireGlobalDoc } from '../shared';
2
+
3
+ // ── Cupom de desconto no checkout do shop (feat-367) ──
4
+ //
5
+ // Caminho do dado:
6
+ // cupom (Nexus) ──start──▶ proposal.coupon (snapshot CONGELADO, + redemption `reserved`)
7
+ // ──ensureContract──▶ contract.coupon (mesmo snapshot)
8
+ // ──mark-paid──▶ redemption `redeemed`
9
+ //
10
+ // `proposal.base_amount` continua com a mensalidade CHEIA. Quem cobra/exibe a
11
+ // mensalidade lê `effectiveMonthlyAmount(...)` (= `coupon.discounted_amount` quando
12
+ // houver cupom). O preço com desconto sai SÓ de `applyCouponDiscount` — ninguém
13
+ // recalcula desconto em outro lugar.
14
+ //
15
+ // As funções deste arquivo são PURAS e sem dependência (nem firebase, nem zod):
16
+ // backend e shop importam em runtime.
17
+
18
+ // ── Constantes ──
19
+
20
+ /** Collection `core/nexus/apps/nex-vendas/coupons/{CODE}` (doc id = código). */
21
+ export const NEX_VENDAS_COUPONS_COLLECTION = 'coupons';
22
+
23
+ /** Subcollection `coupons/{CODE}/redemptions/{short_code}` (um uso por jornada). */
24
+ export const NEX_VENDAS_COUPON_REDEMPTIONS_COLLECTION = 'redemptions';
25
+
26
+ /** Doc de configuração dos cupons (`INexVendasCouponsConfig`). */
27
+ export const NEX_VENDAS_COUPONS_CONFIG_PATH = 'platform/nex-vendas/coupons/config';
28
+
29
+ /**
30
+ * Piso padrão da mensalidade com desconto, em reais, quando a config não informa
31
+ * `min_monthly_amount` (D9 — R$ 5 já é cobrado em produção pelo Asaas).
32
+ */
33
+ export const NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT = 5;
34
+
35
+ /** D8 — tamanho exato do código. */
36
+ export const NEX_VENDAS_COUPON_CODE_LENGTH = 6;
37
+
38
+ /** D8 — formato do código já normalizado: exatamente 6 letras maiúsculas e números. */
39
+ export const NEX_VENDAS_COUPON_CODE_REGEX = /^[A-Z0-9]{6}$/;
40
+
41
+ /** Faixa do desconto percentual (inteiro). 100% é "período grátis", fora do escopo. */
42
+ export const NEX_VENDAS_COUPON_PERCENT_MIN = 1;
43
+ export const NEX_VENDAS_COUPON_PERCENT_MAX = 99;
44
+
45
+ /** Teto de `duration_months` (F5). Na F1 o cadastro só aceita `null`. */
46
+ export const NEX_VENDAS_COUPON_MAX_DURATION_MONTHS = 24;
47
+
48
+ // ── Tipos de domínio ──
49
+
50
+ export type NexVendasCouponDiscountType = 'percent' | 'fixed';
51
+
52
+ /** `inactive` = invalidado no Nexus (com motivo). */
53
+ export type NexVendasCouponStatus = 'active' | 'inactive';
54
+
55
+ /**
56
+ * Cupom (BA §4.1). Doc id = `code`, imutável depois de criado.
57
+ * Regras de escrita (formato, faixas, ofertas existentes) ficam no backend.
58
+ */
59
+ export interface INexVendasCoupon extends IFireGlobalDoc {
60
+ /** `^[A-Z0-9]{6}$` (D8). Igual ao doc id. */
61
+ code: string;
62
+ /** Nome INTERNO ("Black Friday 2026"). Não vai para o shop. */
63
+ name: string;
64
+ discount_type: NexVendasCouponDiscountType;
65
+ /** `percent`: inteiro 1–99. `fixed`: reais (> 0, centavos inteiros). */
66
+ discount_value: number;
67
+ /**
68
+ * Quantas mensalidades têm desconto. `null` = enquanto durar o contrato.
69
+ * 1..24 só a partir da F5 (reversão por webhook).
70
+ */
71
+ duration_months: number | null;
72
+ /** Inteiro ≥ 1, ou `null` = sem limite. */
73
+ max_redemptions: number | null;
74
+ /** Data civil `YYYY-MM-DD` (São Paulo), inclusiva. Ausente/null = já vale. */
75
+ valid_from?: string | null;
76
+ /** Data civil `YYYY-MM-DD` (São Paulo), inclusiva. Ausente/null = sem fim. */
77
+ valid_until?: string | null;
78
+ /** Ofertas onde vale. Vazia = NÃO vale em nenhuma (D6, seguro por padrão). */
79
+ offer_slugs: string[];
80
+ status: NexVendasCouponStatus;
81
+ /** Usos resgatados (pagos). Mantido pelo backend em transação. */
82
+ redemption_count: number;
83
+
84
+ // Auditoria
85
+ created_by: string;
86
+ inactivated_by?: string | null;
87
+ inactivated_at?: Date | null;
88
+ inactivation_reason?: string | null;
89
+ }
90
+
91
+ /**
92
+ * - `reserved`: `start` com cupom; conta enquanto `reserved_until ≥ agora` (D3).
93
+ * - `redeemed`: pagamento confirmado; conta sempre.
94
+ * - `released`: reserva liberada (cliente tirou o cupom, jornada abandonada…).
95
+ */
96
+ export type NexVendasCouponRedemptionStatus = 'reserved' | 'redeemed' | 'released';
97
+
98
+ /** Uso do cupom (BA §4.2): `coupons/{CODE}/redemptions/{short_code}`, um por jornada. */
99
+ export interface INexVendasCouponRedemption extends IFireGlobalDoc {
100
+ /** Código do cupom (redundante com o path; facilita collection group). */
101
+ code: string;
102
+ /** `short_code` da jornada/proposta. Igual ao doc id. */
103
+ short_code: string;
104
+ offer_slug: string;
105
+ proposal_id: string;
106
+ /** Preenchido quando o contrato existir. */
107
+ contract_id?: string | null;
108
+ /** CPF/CNPJ só com dígitos, gravado no `/dados` (D5: um uso por documento). */
109
+ document_number?: string | null;
110
+ status: NexVendasCouponRedemptionStatus;
111
+ /** Fim do `valid_until` da proposta (SP). Reserva vencida não conta. */
112
+ reserved_until: Date;
113
+ /** Desconto mensal aplicado, em reais (cópia do snapshot). */
114
+ discount_amount: number;
115
+ reserved_at: Date;
116
+ redeemed_at?: Date | null;
117
+ released_at?: Date | null;
118
+ /** Motivo curto da liberação (`customer_removed`, `expired`…). Texto livre do backend. */
119
+ release_reason?: string | null;
120
+ }
121
+
122
+ /**
123
+ * Snapshot congelado (BA §4.3), igual na proposta e no contrato. Gravado uma vez
124
+ * no `start` e nunca recalculado: editar ou invalidar o cupom não muda o snapshot.
125
+ */
126
+ export interface INexVendasCouponSnapshot {
127
+ code: string;
128
+ /** Nome interno do cupom no momento do uso. Não sai na projeção pública. */
129
+ coupon_name: string;
130
+ discount_type: NexVendasCouponDiscountType;
131
+ discount_value: number;
132
+ /** `null` = enquanto durar o contrato. */
133
+ duration_months: number | null;
134
+ /** Mensalidade cheia da oferta (`base_amount`), em reais. */
135
+ list_amount: number;
136
+ /** Desconto por mês, em reais. */
137
+ discount_amount: number;
138
+ /** Mensalidade com desconto, em reais. */
139
+ discounted_amount: number;
140
+ applied_at: Date;
141
+ /** F5 — quando o desconto acabou (assinatura voltou ao preço cheio). */
142
+ ended_at?: Date | null;
143
+ }
144
+
145
+ /**
146
+ * Snapshot para o shop (proposta pública e `coupon-check`): sem nome interno nem
147
+ * auditoria. `duration_label` vem pronto (`couponDurationLabel`).
148
+ */
149
+ export interface INexVendasCouponSnapshotPublic {
150
+ code: string;
151
+ discount_type: NexVendasCouponDiscountType;
152
+ discount_value: number;
153
+ duration_months: number | null;
154
+ /** "enquanto durar o contrato" / "nas 3 primeiras mensalidades". */
155
+ duration_label: string;
156
+ list_amount: number;
157
+ discount_amount: number;
158
+ discounted_amount: number;
159
+ }
160
+
161
+ /** Doc `NEX_VENDAS_COUPONS_CONFIG_PATH`. */
162
+ export interface INexVendasCouponsConfig {
163
+ /** Piso da mensalidade com desconto, em reais. Ausente = `NEX_VENDAS_COUPON_DEFAULT_MIN_MONTHLY_AMOUNT`. */
164
+ min_monthly_amount?: number | null;
165
+ }
166
+
167
+ // ── Contrato HTTP público ──
168
+
169
+ /**
170
+ * Motivo INTERNO da recusa (BA §5.3, na ordem de validação). Fica no backend e
171
+ * em log; para o shop vai só `toCouponPublicReason(...)`.
172
+ */
173
+ export type NexVendasCouponInvalidReason =
174
+ | 'invalid_format'
175
+ | 'not_found'
176
+ | 'inactive'
177
+ | 'not_started'
178
+ | 'expired'
179
+ | 'offer_not_allowed'
180
+ | 'exhausted'
181
+ | 'invalid_discount'
182
+ | 'below_minimum';
183
+
184
+ /**
185
+ * Motivo GENÉRICO devolvido ao shop. Não distingue "não existe" de "inativo"
186
+ * (BA §5.2, contra adivinhação de código).
187
+ * - `not_found`: "Cupom não encontrado".
188
+ * - `expired`: "Este cupom expirou".
189
+ * - `not_for_offer`: "Este cupom não vale para este plano".
190
+ * - `unavailable`: esgotado ou sem condição de aplicar neste plano.
191
+ */
192
+ export type NexVendasCouponPublicReason = 'not_found' | 'expired' | 'not_for_offer' | 'unavailable';
193
+
194
+ /** Corpo de `POST /offers/:slug/coupon-check` (público). */
195
+ export interface INexVendasCouponCheckRequest {
196
+ /** Como o cliente digitou; o backend normaliza (`normalizeCouponCode`). */
197
+ code: string;
198
+ }
199
+
200
+ /** Resposta de `coupon-check`: só valida e calcula, não reserva. */
201
+ export interface INexVendasCouponCheckResponse {
202
+ valid: boolean;
203
+ /** Só com `valid: false`. */
204
+ reason?: NexVendasCouponPublicReason | null;
205
+ /** Só com `valid: true`: preço calculado para a oferta. */
206
+ snapshot?: INexVendasCouponSnapshotPublic | null;
207
+ }
208
+
209
+ /**
210
+ * Resposta do `start` sobre o cupom pedido (D4: cupom inválido não bloqueia, a
211
+ * jornada segue sem cupom e o shop avisa).
212
+ */
213
+ export type NexVendasOfferStartCouponStatus = 'applied' | 'not_applied';
214
+
215
+ // ── Funções puras ──
216
+
217
+ /**
218
+ * Normaliza o código digitado: `trim` + maiúsculo. Fora do formato (D8: exatamente
219
+ * 6 letras e números) ⇒ `null`. Aceita `unknown` (query string pode vir como lista).
220
+ */
221
+ export function normalizeCouponCode(raw: unknown): string | null {
222
+ if (typeof raw !== 'string') return null;
223
+ const code = raw.trim().toUpperCase();
224
+ return NEX_VENDAS_COUPON_CODE_REGEX.test(code) ? code : null;
225
+ }
226
+
227
+ export interface INexVendasCouponDiscountInput {
228
+ /** Mensalidade cheia, em reais. */
229
+ base_amount: number;
230
+ discount_type: NexVendasCouponDiscountType;
231
+ discount_value: number;
232
+ /** Piso da mensalidade com desconto, em reais (igual ao piso passa). */
233
+ min_amount: number;
234
+ }
235
+
236
+ export interface INexVendasCouponDiscountResult {
237
+ discount_amount: number;
238
+ discounted_amount: number;
239
+ }
240
+
241
+ export interface INexVendasCouponDiscountError {
242
+ /**
243
+ * - `invalid`: entrada inválida (tipo, percentual fora de 1–99, fixo ≤ 0 ou com
244
+ * fração de centavo, fixo ≥ mensalidade, desconto que arredonda para zero).
245
+ * - `below_minimum`: mensalidade com desconto abaixo do piso.
246
+ */
247
+ error: 'below_minimum' | 'invalid';
248
+ }
249
+
250
+ const isFiniteNumber = (n: unknown): n is number => typeof n === 'number' && isFinite(n);
251
+
252
+ /** Reais → centavos inteiros (representação, não cálculo: corrige 0,29 × 100 = 28,999…). */
253
+ const toCents = (amount: number): number => Math.round(amount * 100);
254
+
255
+ /** `amount` tem no máximo 2 casas (sem fração de centavo)? */
256
+ const hasWholeCents = (amount: number): boolean => Math.abs(amount * 100 - toCents(amount)) < 1e-6;
257
+
258
+ /**
259
+ * Calcula o desconto do cupom sobre a mensalidade. ÚNICA fonte do preço com
260
+ * desconto (backend e shop).
261
+ *
262
+ * - Tudo em CENTAVOS inteiros; o resultado é `centavos / 100` (sem float sujo).
263
+ * - Percentual: desconto arredondado para BAIXO (o cliente paga no máximo o
264
+ * anunciado, nunca centavo a menos). Ex.: 19,90 × 15% = 2,985 ⇒ desconto 2,98.
265
+ * - Fixo: em reais, com no máximo 2 casas, e menor que a mensalidade.
266
+ * - Mensalidade com desconto < `min_amount` ⇒ `below_minimum` (igual passa).
267
+ */
268
+ export function applyCouponDiscount(
269
+ input: INexVendasCouponDiscountInput,
270
+ ): INexVendasCouponDiscountResult | INexVendasCouponDiscountError {
271
+ const { base_amount, discount_type, discount_value, min_amount } = input;
272
+ if (!isFiniteNumber(base_amount) || base_amount <= 0) return { error: 'invalid' };
273
+ if (!isFiniteNumber(min_amount) || min_amount < 0) return { error: 'invalid' };
274
+ if (!isFiniteNumber(discount_value)) return { error: 'invalid' };
275
+
276
+ const baseCents = toCents(base_amount);
277
+ let discountCents: number;
278
+ if (discount_type === 'percent') {
279
+ if (
280
+ Math.floor(discount_value) !== discount_value ||
281
+ discount_value < NEX_VENDAS_COUPON_PERCENT_MIN ||
282
+ discount_value > NEX_VENDAS_COUPON_PERCENT_MAX
283
+ ) {
284
+ return { error: 'invalid' };
285
+ }
286
+ // Inteiro × inteiro: a divisão é a única fonte de fração, e o floor é exato.
287
+ discountCents = Math.floor((baseCents * discount_value) / 100);
288
+ } else if (discount_type === 'fixed') {
289
+ if (discount_value <= 0 || !hasWholeCents(discount_value)) return { error: 'invalid' };
290
+ discountCents = toCents(discount_value);
291
+ if (discountCents >= baseCents) return { error: 'invalid' };
292
+ } else {
293
+ return { error: 'invalid' };
294
+ }
295
+
296
+ if (discountCents <= 0) return { error: 'invalid' };
297
+ const discountedCents = baseCents - discountCents;
298
+ if (discountedCents < toCents(min_amount)) return { error: 'below_minimum' };
299
+
300
+ return { discount_amount: discountCents / 100, discounted_amount: discountedCents / 100 };
301
+ }
302
+
303
+ /**
304
+ * Mensalidade que de fato se cobra/exibe: `coupon.discounted_amount` quando houver
305
+ * cupom, senão `base_amount`. Serve para proposta, proposta pública e contrato.
306
+ */
307
+ export function effectiveMonthlyAmount(input: {
308
+ base_amount: number;
309
+ coupon?: { discounted_amount: number } | null;
310
+ }): number {
311
+ return input.coupon?.discounted_amount ?? input.base_amount;
312
+ }
313
+
314
+ /**
315
+ * Duração do desconto em texto de cliente (pt-BR, curto):
316
+ * - `null`/ausente ⇒ "enquanto durar o contrato";
317
+ * - 1 ⇒ "na primeira mensalidade";
318
+ * - N ⇒ "nas N primeiras mensalidades".
319
+ * Valor fora de inteiro ≥ 1 (não deveria existir; o backend valida) ⇒ "por tempo
320
+ * limitado" — nunca promete desconto permanente por engano.
321
+ */
322
+ export function couponDurationLabel(duration_months: number | null | undefined): string {
323
+ if (duration_months === null || duration_months === undefined) return 'enquanto durar o contrato';
324
+ if (!isFiniteNumber(duration_months) || Math.floor(duration_months) !== duration_months || duration_months < 1) {
325
+ return 'por tempo limitado';
326
+ }
327
+ if (duration_months === 1) return 'na primeira mensalidade';
328
+ return `nas ${duration_months} primeiras mensalidades`;
329
+ }
330
+
331
+ const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
332
+
333
+ /**
334
+ * Hoje (data civil `YYYY-MM-DD` em São Paulo) está na janela do cupom? Bordas
335
+ * inclusivas. `valid_from` ausente = já vale; `valid_until` ausente = sem fim.
336
+ * `todayIsoSp` fora do formato ⇒ `false` (fecha por segurança).
337
+ */
338
+ export function isCouponWindowOpen(
339
+ coupon: { valid_from?: string | null; valid_until?: string | null },
340
+ todayIsoSp: string,
341
+ ): boolean {
342
+ if (typeof todayIsoSp !== 'string' || !ISO_DATE_REGEX.test(todayIsoSp)) return false;
343
+ // `YYYY-MM-DD` compara certo como string.
344
+ if (coupon.valid_from && todayIsoSp < coupon.valid_from) return false;
345
+ if (coupon.valid_until && todayIsoSp > coupon.valid_until) return false;
346
+ return true;
347
+ }
348
+
349
+ /**
350
+ * Motivo interno ⇒ motivo genérico do shop. Formato inválido, inexistente e
351
+ * inativo viram o mesmo `not_found` (BA §5.2).
352
+ */
353
+ export function toCouponPublicReason(reason: NexVendasCouponInvalidReason): NexVendasCouponPublicReason {
354
+ switch (reason) {
355
+ case 'invalid_format':
356
+ case 'not_found':
357
+ case 'inactive':
358
+ case 'not_started':
359
+ return 'not_found';
360
+ case 'expired':
361
+ return 'expired';
362
+ case 'offer_not_allowed':
363
+ return 'not_for_offer';
364
+ default:
365
+ return 'unavailable';
366
+ }
367
+ }
368
+
369
+ /** Snapshot ⇒ projeção pública (sem `coupon_name`/datas; com `duration_label`). */
370
+ export function toCouponSnapshotPublic(snapshot: INexVendasCouponSnapshot): INexVendasCouponSnapshotPublic {
371
+ return {
372
+ code: snapshot.code,
373
+ discount_type: snapshot.discount_type,
374
+ discount_value: snapshot.discount_value,
375
+ duration_months: snapshot.duration_months,
376
+ duration_label: couponDurationLabel(snapshot.duration_months),
377
+ list_amount: snapshot.list_amount,
378
+ discount_amount: snapshot.discount_amount,
379
+ discounted_amount: snapshot.discounted_amount,
380
+ };
381
+ }
@@ -3,3 +3,4 @@ export * from './adhesion';
3
3
  export * from './notifications';
4
4
  export * from './offer';
5
5
  export * from './offer-package';
6
+ export * from './coupon';
@@ -19,3 +19,4 @@ __exportStar(require("./adhesion"), exports);
19
19
  __exportStar(require("./notifications"), exports);
20
20
  __exportStar(require("./offer"), exports);
21
21
  __exportStar(require("./offer-package"), exports);
22
+ __exportStar(require("./coupon"), exports);
@@ -3,3 +3,4 @@ export * from './adhesion';
3
3
  export * from './notifications';
4
4
  export * from './offer';
5
5
  export * from './offer-package';
6
+ export * from './coupon';
@@ -3,6 +3,7 @@ import type { NexFinopsProposalLoyaltyPeriod, NexFinopsProposalOrigem, NexFinops
3
3
  import type { INexFinopsContractAllowance } from '../evo-finops/common/contract';
4
4
  import type { NexVendasContractType } from './adhesion';
5
5
  import type { INexVendasOfferPackage, INexVendasPackageDisplay } from './offer-package';
6
+ import type { NexVendasOfferStartCouponStatus } from './coupon';
6
7
  /**
7
8
  * Origem de marketing do `start`, capturada pelo shop (query string + `document.referrer`)
8
9
  * e gravada server-side, sem cookie, na proposta e na jornada. Cada campo é `null`
@@ -135,9 +136,21 @@ export interface INexVendasOfferStartRequest {
135
136
  turnstile_token: string;
136
137
  attribution?: INexVendasAttribution | null;
137
138
  privacy_accepted: true;
139
+ /**
140
+ * feat-367 — cupom como o cliente digitou (ou `?cupom=`). O backend normaliza
141
+ * (`normalizeCouponCode`) e revalida; inválido NÃO falha o `start` (D4): a
142
+ * jornada segue sem cupom e a resposta traz `coupon_status: 'not_applied'`.
143
+ */
144
+ coupon_code?: string | null;
138
145
  }
139
146
  /** Resposta do `start`: o shop grava o cookie de retomada e navega para `/:site/j/:short_code/dados`. */
140
147
  export interface INexVendasOfferStartResponse {
141
148
  ok: true;
142
149
  short_code: string;
150
+ /**
151
+ * feat-367 — só quando o corpo trouxe `coupon_code`: `applied` (snapshot gravado
152
+ * na proposta) ou `not_applied` (seguiu sem cupom; o shop avisa). Ausente =
153
+ * `start` sem cupom ou backend anterior à feat-367.
154
+ */
155
+ coupon_status?: NexVendasOfferStartCouponStatus | null;
143
156
  }
@@ -7,6 +7,7 @@ import type {
7
7
  import type { INexFinopsContractAllowance } from '../evo-finops/common/contract';
8
8
  import type { NexVendasContractType } from './adhesion';
9
9
  import type { INexVendasOfferPackage, INexVendasPackageDisplay } from './offer-package';
10
+ import type { NexVendasOfferStartCouponStatus } from './coupon';
10
11
 
11
12
  // ── Atribuição (feat-326 D14) ──
12
13
 
@@ -159,10 +160,22 @@ export interface INexVendasOfferStartRequest {
159
160
  turnstile_token: string;
160
161
  attribution?: INexVendasAttribution | null;
161
162
  privacy_accepted: true;
163
+ /**
164
+ * feat-367 — cupom como o cliente digitou (ou `?cupom=`). O backend normaliza
165
+ * (`normalizeCouponCode`) e revalida; inválido NÃO falha o `start` (D4): a
166
+ * jornada segue sem cupom e a resposta traz `coupon_status: 'not_applied'`.
167
+ */
168
+ coupon_code?: string | null;
162
169
  }
163
170
 
164
171
  /** Resposta do `start`: o shop grava o cookie de retomada e navega para `/:site/j/:short_code/dados`. */
165
172
  export interface INexVendasOfferStartResponse {
166
173
  ok: true;
167
174
  short_code: string;
175
+ /**
176
+ * feat-367 — só quando o corpo trouxe `coupon_code`: `applied` (snapshot gravado
177
+ * na proposta) ou `not_applied` (seguiu sem cupom; o shop avisa). Ausente =
178
+ * `start` sem cupom ou backend anterior à feat-367.
179
+ */
180
+ coupon_status?: NexVendasOfferStartCouponStatus | null;
168
181
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "evo360-types",
3
- "version": "1.3.818",
3
+ "version": "1.3.822",
4
4
  "description": "HREVO360 Shared Types",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",