evo360-types 1.3.557 → 1.3.559

package/dist/apps/evo-finops/zod-schemas.d.ts

@@ -12993,3 +12993,88 @@ export declare const zNexVendasJourneyPaymentSchema: z.ZodObject<{
         payment_link_id?: string | null | undefined;
     }[] | null | undefined;
 }>;
+/**
+ * Franquia de uma métrica no contrato. `included` é número discreto e inteiro
+ * (não fração): 0 = nada incluso.
+ */
+export declare const zNexFinopsContractAllowanceSchema: z.ZodObject<{
+    included: z.ZodNumber;
+    /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+    unit_price_excess: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    included: number;
+    unit_price_excess?: number | null | undefined;
+}, {
+    included: number;
+    unit_price_excess?: number | null | undefined;
+}>;
+/**
+ * Mapa de franquias por métrica. A chave é `string` de propósito (ver
+ * `NexFinopsMetricCatalog`): métrica nova é linha de catálogo, não publish do
+ * evo-types. Métrica ausente = não contratada ⇒ não alerta.
+ */
+export declare const zNexFinopsContractAllowancesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    included: z.ZodNumber;
+    /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+    unit_price_excess: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    included: number;
+    unit_price_excess?: number | null | undefined;
+}, {
+    included: number;
+    unit_price_excess?: number | null | undefined;
+}>>;
+/**
+ * Gatilho de alerta: **fração** da franquia, não percentual — `0.8` é 80%.
+ * `0` é rejeitado porque dispararia em qualquer consumo.
+ */
+export declare const zNexFinopsAlertThresholdSchema: z.ZodNumber;
+/** Doc `platform/evo-billing/usage-alerts/config` — default herdado por todos os contratos. */
+export declare const zNexFinopsUsageAlertDefaultsSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    thresholds: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    thresholds: number[];
+}, {
+    enabled: boolean;
+    thresholds: number[];
+}>;
+/**
+ * Fragmento de escrita dos campos de franquia/alerta do contrato, para compor
+ * (`.merge()`) nos schemas de create/update/upsert de contrato do
+ * `@evo/nex-model`. Campo que não entra no schema de patch é aceito e
+ * descartado em silêncio.
+ *
+ * `alerts_enabled` e `alert_thresholds` ausentes significam **herda o default
+ * global** — nunca `false`/lista vazia.
+ */
+export declare const zNexFinopsContractAllowancesWriteSchema: z.ZodObject<{
+    allowances: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        included: z.ZodNumber;
+        /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+        unit_price_excess: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        included: number;
+        unit_price_excess?: number | null | undefined;
+    }, {
+        included: number;
+        unit_price_excess?: number | null | undefined;
+    }>>>>;
+    alerts_enabled: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    alert_thresholds: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    allowances?: Record<string, {
+        included: number;
+        unit_price_excess?: number | null | undefined;
+    }> | null | undefined;
+    alerts_enabled?: boolean | null | undefined;
+    alert_thresholds?: number[] | null | undefined;
+}, {
+    allowances?: Record<string, {
+        included: number;
+        unit_price_excess?: number | null | undefined;
+    }> | null | undefined;
+    alerts_enabled?: boolean | null | undefined;
+    alert_thresholds?: number[] | null | undefined;
+}>;

package/dist/apps/evo-finops/zod-schemas.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.zProviderInvoiceLinksSchema = exports.zServiceTaxInfoSchema = exports.zServiceLineItemSchema = exports.zServiceInvoiceStateSchema = exports.zProviderServiceInvoiceStatusSchema = exports.zExternalLinkSchema = exports.zExternalObjectTypeSchema = exports.zInvoiceSourceRefSchema = exports.zInvoiceSourceTypeSchema = exports.zInvoiceTakerRefSchema = exports.zInvoiceTakerSnapshotSchema = exports.zInvoiceTakerSnapshotAddressSchema = exports.zTakerDocumentSchema = exports.zTakerTaxProfileSchema = exports.zTakerProviderRefsSchema = exports.zTakerAddressSchema = exports.zInvoiceTakerTypeSchema = exports.zServiceSchema = exports.zCustomerServiceTaxInfoSchema = exports.zIssuerTaxProfileSchema = exports.zIssuerNfseConfigSchema = exports.zIssuerMunicipalCredentialsRefSchema = exports.zIssuerTaxRegimeSchema = exports.zIssuerCompanyIdentitySchema = exports.zIssuerCompanyAddressSchema = exports.zTaxProfileSyncStateSchema = exports.zAsaasProviderSchema = exports.zAsaasProviderAsaasBlockSchema = exports.zAsaasProviderCapabilitiesSchema = exports.zAsaasPaymentsCapabilitiesSchema = exports.zAsaasNfseCapabilitiesSchema = exports.zAsaasEnvAuthConfigSchema = exports.zAsaasSubaccountInputSchema = exports.zAsaasAccountScopeSchema = exports.zAsaasWebhookConfigSchema = exports.zRetryPolicySchema = exports.zAsaasWebhookEventSchema = exports.zAsaasAccountScopeModeSchema = exports.zProviderRemoteRefsSchema = exports.zProviderFiscalInfoPayloadSchema = exports.zProviderCredentialsInputSchema = exports.zProviderCredentialsSecretRefsSchema = exports.zProviderMunicipalOptionsSnapshotSchema = exports.zProviderOptionItemSchema = exports.zProviderMunicipalAuthTypeSchema = exports.zFinopsProviderBaseSchema = exports.zProviderStatusSchema = exports.zFinopsActionSchema = exports.zFinopsProviderTypeSchema = exports.zProviderEnvSchema = void 0;
-exports.zNexVendasJourneyPaymentSchema = exports.zNexVendasJourneyPaymentSupersededSchema = exports.zNexVendasJourneyPaymentWebhookEventSchema = exports.zNexVendasJourneyBoletoSchema = exports.zNexVendasJourneyPaymentChooseSchema = exports.zNexVendasJourneyPaymentStateSchema = exports.zNexVendasJourneyPaymentKindSchema = exports.zNexVendasJourneyPaymentMethodSchema = exports.zNexFinopsContractAsaasInfoSchema = exports.zNexFinopsAsaasSubscriptionStatusSchema = exports.zNexFinopsPaymentMethodSchema = exports.zNexFinopsProposalSchema = exports.zNexFinopsProposalWriteSchema = exports.zNexFinopsProposalPrefillSchema = exports.zNexFinopsProposalLoyaltyPeriodSchema = exports.zNexFinopsProposalPaymentMethodSchema = exports.zNexFinopsProposalStatusSchema = exports.zServiceInvoiceSchema = exports.zPaymentLinkSchema = exports.zPaymentLinkDocumentStateSchema = exports.zAsaasPaymentLinkSubscriptionCycleSchema = exports.zAsaasPaymentLinkChargeTypeSchema = exports.zAsaasPaymentLinkBillingTypeSchema = exports.zProviderPayloadSnapshotSchema = exports.zProviderTraceSchema = exports.zProviderInvoiceErrorSchema = exports.zProviderInvoiceIdentifiersSchema = void 0;
+exports.zNexFinopsContractAllowancesWriteSchema = exports.zNexFinopsUsageAlertDefaultsSchema = exports.zNexFinopsAlertThresholdSchema = exports.zNexFinopsContractAllowancesSchema = exports.zNexFinopsContractAllowanceSchema = exports.zNexVendasJourneyPaymentSchema = exports.zNexVendasJourneyPaymentSupersededSchema = exports.zNexVendasJourneyPaymentWebhookEventSchema = exports.zNexVendasJourneyBoletoSchema = exports.zNexVendasJourneyPaymentChooseSchema = exports.zNexVendasJourneyPaymentStateSchema = exports.zNexVendasJourneyPaymentKindSchema = exports.zNexVendasJourneyPaymentMethodSchema = exports.zNexFinopsContractAsaasInfoSchema = exports.zNexFinopsAsaasSubscriptionStatusSchema = exports.zNexFinopsPaymentMethodSchema = exports.zNexFinopsProposalSchema = exports.zNexFinopsProposalWriteSchema = exports.zNexFinopsProposalPrefillSchema = exports.zNexFinopsProposalLoyaltyPeriodSchema = exports.zNexFinopsProposalPaymentMethodSchema = exports.zNexFinopsProposalStatusSchema = exports.zServiceInvoiceSchema = exports.zPaymentLinkSchema = exports.zPaymentLinkDocumentStateSchema = exports.zAsaasPaymentLinkSubscriptionCycleSchema = exports.zAsaasPaymentLinkChargeTypeSchema = exports.zAsaasPaymentLinkBillingTypeSchema = exports.zProviderPayloadSnapshotSchema = exports.zProviderTraceSchema = exports.zProviderInvoiceErrorSchema = exports.zProviderInvoiceIdentifiersSchema = void 0;
 const zod_1 = require("zod");
 const zod_schemas_1 = require("../shared/zod-schemas");
 // ---- Provider enums and base ----
@@ -853,3 +853,52 @@ exports.zNexVendasJourneyPaymentSchema = zod_1.z
     last_error: zod_1.z.string().optional().nullable(),
 })
     .strip();
+// ---- Nexus FinOps / Franquias e alertas de consumo (feat-150 F0) ----
+/**
+ * Franquia de uma métrica no contrato. `included` é número discreto e inteiro
+ * (não fração): 0 = nada incluso.
+ */
+exports.zNexFinopsContractAllowanceSchema = zod_1.z
+    .object({
+    included: zod_1.z.number().int().nonnegative(),
+    /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+    unit_price_excess: zod_1.z.number().nonnegative().optional().nullable(),
+})
+    .strip();
+/**
+ * Mapa de franquias por métrica. A chave é `string` de propósito (ver
+ * `NexFinopsMetricCatalog`): métrica nova é linha de catálogo, não publish do
+ * evo-types. Métrica ausente = não contratada ⇒ não alerta.
+ */
+exports.zNexFinopsContractAllowancesSchema = zod_1.z.record(zod_1.z.string().min(1).max(64), exports.zNexFinopsContractAllowanceSchema);
+/**
+ * Gatilho de alerta: **fração** da franquia, não percentual — `0.8` é 80%.
+ * `0` é rejeitado porque dispararia em qualquer consumo.
+ */
+exports.zNexFinopsAlertThresholdSchema = zod_1.z
+    .number()
+    .gt(0, "threshold must be a fraction greater than 0 (0.8 = 80%)")
+    .lte(1, "threshold must be a fraction less than or equal to 1 (1 = 100%)");
+/** Doc `platform/evo-billing/usage-alerts/config` — default herdado por todos os contratos. */
+exports.zNexFinopsUsageAlertDefaultsSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean(),
+    thresholds: zod_1.z.array(exports.zNexFinopsAlertThresholdSchema),
+})
+    .strip();
+/**
+ * Fragmento de escrita dos campos de franquia/alerta do contrato, para compor
+ * (`.merge()`) nos schemas de create/update/upsert de contrato do
+ * `@evo/nex-model`. Campo que não entra no schema de patch é aceito e
+ * descartado em silêncio.
+ *
+ * `alerts_enabled` e `alert_thresholds` ausentes significam **herda o default
+ * global** — nunca `false`/lista vazia.
+ */
+exports.zNexFinopsContractAllowancesWriteSchema = zod_1.z
+    .object({
+    allowances: exports.zNexFinopsContractAllowancesSchema.optional().nullable(),
+    alerts_enabled: zod_1.z.boolean().optional().nullable(),
+    alert_thresholds: zod_1.z.array(exports.zNexFinopsAlertThresholdSchema).optional().nullable(),
+})
+    .strip();

package/dist/apps/evo-finops/zod-schemas.ts

@@ -932,3 +932,61 @@ export const zNexVendasJourneyPaymentSchema = z
     last_error: z.string().optional().nullable(),
   })
   .strip();
+
+// ---- Nexus FinOps / Franquias e alertas de consumo (feat-150 F0) ----
+
+/**
+ * Franquia de uma métrica no contrato. `included` é número discreto e inteiro
+ * (não fração): 0 = nada incluso.
+ */
+export const zNexFinopsContractAllowanceSchema = z
+  .object({
+    included: z.number().int().nonnegative(),
+    /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+    unit_price_excess: z.number().nonnegative().optional().nullable(),
+  })
+  .strip();
+
+/**
+ * Mapa de franquias por métrica. A chave é `string` de propósito (ver
+ * `NexFinopsMetricCatalog`): métrica nova é linha de catálogo, não publish do
+ * evo-types. Métrica ausente = não contratada ⇒ não alerta.
+ */
+export const zNexFinopsContractAllowancesSchema = z.record(
+  z.string().min(1).max(64),
+  zNexFinopsContractAllowanceSchema,
+);
+
+/**
+ * Gatilho de alerta: **fração** da franquia, não percentual — `0.8` é 80%.
+ * `0` é rejeitado porque dispararia em qualquer consumo.
+ */
+export const zNexFinopsAlertThresholdSchema = z
+  .number()
+  .gt(0, "threshold must be a fraction greater than 0 (0.8 = 80%)")
+  .lte(1, "threshold must be a fraction less than or equal to 1 (1 = 100%)");
+
+/** Doc `platform/evo-billing/usage-alerts/config` — default herdado por todos os contratos. */
+export const zNexFinopsUsageAlertDefaultsSchema = z
+  .object({
+    enabled: z.boolean(),
+    thresholds: z.array(zNexFinopsAlertThresholdSchema),
+  })
+  .strip();
+
+/**
+ * Fragmento de escrita dos campos de franquia/alerta do contrato, para compor
+ * (`.merge()`) nos schemas de create/update/upsert de contrato do
+ * `@evo/nex-model`. Campo que não entra no schema de patch é aceito e
+ * descartado em silêncio.
+ *
+ * `alerts_enabled` e `alert_thresholds` ausentes significam **herda o default
+ * global** — nunca `false`/lista vazia.
+ */
+export const zNexFinopsContractAllowancesWriteSchema = z
+  .object({
+    allowances: zNexFinopsContractAllowancesSchema.optional().nullable(),
+    alerts_enabled: z.boolean().optional().nullable(),
+    alert_thresholds: z.array(zNexFinopsAlertThresholdSchema).optional().nullable(),
+  })
+  .strip();

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

@@ -44,6 +44,66 @@ export interface INexFinopsContractServiceItem {
     /** Valor unitário (decimal, BRL). */
     amount: number;
 }
+/**
+ * Franquia de uma métrica dentro do contrato.
+ *
+ * Franquia é **número discreto** e **não tem default global**: é o que foi
+ * vendido àquele cliente. Só o gatilho (percentual) e o liga/desliga têm
+ * default de plataforma — ver `INexFinopsUsageAlertDefaults`.
+ */
+export interface INexFinopsContractAllowance {
+    /** Quantidade incluída no ciclo. 0 = nada incluso; ausente = não contratado. */
+    included: number;
+    /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+    unit_price_excess?: number | null;
+}
+/**
+ * Catálogo de métricas com franquia. É o que a tela do Nexus renderiza (`v-for`)
+ * e o que o motor de alerta itera.
+ *
+ * Métrica nova = **uma linha aqui**. Nenhuma migração, nenhum campo novo.
+ */
+export declare const NexFinopsMetricCatalog: {
+    readonly attendances: {
+        readonly label: "Atendimentos";
+        readonly unit: "contatos";
+    };
+    readonly sms: {
+        readonly label: "SMS enviados";
+        readonly unit: "mensagens";
+    };
+    readonly email: {
+        readonly label: "E-mails enviados";
+        readonly unit: "mensagens";
+    };
+};
+/**
+ * Chaves conhecidas do catálogo — para iterar e para tipar escolha de métrica
+ * na UI.
+ *
+ * ⚠️ NÃO usar para tipar a chave de `INexFinopsContract.allowances`: o mapa é
+ * deliberadamente aberto (`string`) para que uma métrica nova seja só uma linha
+ * de catálogo, sem publish do evo-types antes de o dado poder existir.
+ */
+export type NexFinopsMetricKey = keyof typeof NexFinopsMetricCatalog;
+/** Doc de config global dos alertas de consumo (convenção `/platform/<app>`). */
+export declare const EVO_BILLING_USAGE_ALERTS_CONFIG_PATH = "platform/evo-billing/usage-alerts/config";
+/**
+ * Default de plataforma dos alertas de consumo, herdado por todos os contratos.
+ * Vive em `EVO_BILLING_USAGE_ALERTS_CONFIG_PATH`.
+ *
+ * O contrato pode sobrescrever os dois campos (`alerts_enabled`,
+ * `alert_thresholds`); franquia nunca tem default aqui.
+ */
+export interface INexFinopsUsageAlertDefaults {
+    /** Alertas ligados para todos os contratos, salvo override. Nasce `true`. */
+    enabled: boolean;
+    /**
+     * Frações da franquia que disparam aviso — **frações, não percentuais**:
+     * `0.8` = 80%. Nasce `[0.8, 1.0]`.
+     */
+    thresholds: number[];
+}
 export interface INexFinopsContract extends IFireGlobalDoc {
     customer_id: string;
     customer_ref?: string | null;
@@ -71,6 +131,38 @@ export interface INexFinopsContract extends IFireGlobalDoc {
     /** Método com que o primeiro pagamento foi feito. `accepted_payment_methods` é a oferta; este é o fato. */
     payment_method?: NexFinopsPaymentMethod | null;
     asaas?: INexFinopsContractAsaasInfo | null;
+    /**
+     * Franquia incluída no ciclo, por métrica. A CHAVE é o id da métrica (ver
+     * `NexFinopsMetricCatalog`) e é deliberadamente `string`: métrica nova é um
+     * item de catálogo, não uma mudança de schema.
+     *
+     * Métrica ausente do mapa = **não contratada** ⇒ não gera alerta. Alertar em
+     * qualquer consumo sem franquia produziria alarme falso em massa.
+     *
+     * Vigência: a franquia herda `starts_at`/`ends_at` do contrato — mudar
+     * franquia é alterar o contrato.
+     *
+     * ⚠️ NÃO existe congelamento por competência ainda. Enquanto a feat-150 cheia
+     * não resolver isso, `allowances` **não pode** ser usado para recalcular
+     * competência fechada: reabrir junho leria a franquia de hoje, não a de junho.
+     */
+    allowances?: Record<string, INexFinopsContractAllowance> | null;
+    /**
+     * Override do liga/desliga global de alertas de consumo.
+     *
+     * ⚠️ **Ausente ≠ `false`.** Ausente = HERDA o default global
+     * (`INexFinopsUsageAlertDefaults.enabled`); `false` explícito é o kill-switch
+     * por cliente. Ler ausente como `false` desliga alerta de todo mundo.
+     */
+    alerts_enabled?: boolean | null;
+    /**
+     * Override dos gatilhos globais. Frações da franquia (`0.8` = 80%), válidas
+     * para todas as métricas do contrato.
+     *
+     * ⚠️ **Ausente ≠ lista vazia.** Ausente = HERDA
+     * `INexFinopsUsageAlertDefaults.thresholds`.
+     */
+    alert_thresholds?: number[] | null;
 }
 export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
 /**

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

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NEX_FINOPS_BILLABLE_CONTRACT_STATUSES = exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = void 0;
+exports.NEX_FINOPS_BILLABLE_CONTRACT_STATUSES = exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = exports.EVO_BILLING_USAGE_ALERTS_CONFIG_PATH = exports.NexFinopsMetricCatalog = void 0;
+/**
+ * Catálogo de métricas com franquia. É o que a tela do Nexus renderiza (`v-for`)
+ * e o que o motor de alerta itera.
+ *
+ * Métrica nova = **uma linha aqui**. Nenhuma migração, nenhum campo novo.
+ */
+exports.NexFinopsMetricCatalog = {
+    attendances: { label: 'Atendimentos', unit: 'contatos' },
+    sms: { label: 'SMS enviados', unit: 'mensagens' },
+    email: { label: 'E-mails enviados', unit: 'mensagens' },
+};
+/** Doc de config global dos alertas de consumo (convenção `/platform/<app>`). */
+exports.EVO_BILLING_USAGE_ALERTS_CONFIG_PATH = 'platform/evo-billing/usage-alerts/config';
 // ── Status transitions ──
 exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = {
     draft: ['active', 'canceled'],

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

@@ -54,6 +54,64 @@ export interface INexFinopsContractServiceItem {
   amount: number;
 }
 
+// ── Franquias e alertas de consumo (feat-150 F0) ──
+
+/**
+ * Franquia de uma métrica dentro do contrato.
+ *
+ * Franquia é **número discreto** e **não tem default global**: é o que foi
+ * vendido àquele cliente. Só o gatilho (percentual) e o liga/desliga têm
+ * default de plataforma — ver `INexFinopsUsageAlertDefaults`.
+ */
+export interface INexFinopsContractAllowance {
+  /** Quantidade incluída no ciclo. 0 = nada incluso; ausente = não contratado. */
+  included: number;
+  /** Reservado para a feat-150 cheia (preço do excedente). Não usar ainda. */
+  unit_price_excess?: number | null;
+}
+
+/**
+ * Catálogo de métricas com franquia. É o que a tela do Nexus renderiza (`v-for`)
+ * e o que o motor de alerta itera.
+ *
+ * Métrica nova = **uma linha aqui**. Nenhuma migração, nenhum campo novo.
+ */
+export const NexFinopsMetricCatalog = {
+  attendances: { label: 'Atendimentos', unit: 'contatos' },
+  sms: { label: 'SMS enviados', unit: 'mensagens' },
+  email: { label: 'E-mails enviados', unit: 'mensagens' },
+} as const;
+
+/**
+ * Chaves conhecidas do catálogo — para iterar e para tipar escolha de métrica
+ * na UI.
+ *
+ * ⚠️ NÃO usar para tipar a chave de `INexFinopsContract.allowances`: o mapa é
+ * deliberadamente aberto (`string`) para que uma métrica nova seja só uma linha
+ * de catálogo, sem publish do evo-types antes de o dado poder existir.
+ */
+export type NexFinopsMetricKey = keyof typeof NexFinopsMetricCatalog;
+
+/** Doc de config global dos alertas de consumo (convenção `/platform/<app>`). */
+export const EVO_BILLING_USAGE_ALERTS_CONFIG_PATH = 'platform/evo-billing/usage-alerts/config';
+
+/**
+ * Default de plataforma dos alertas de consumo, herdado por todos os contratos.
+ * Vive em `EVO_BILLING_USAGE_ALERTS_CONFIG_PATH`.
+ *
+ * O contrato pode sobrescrever os dois campos (`alerts_enabled`,
+ * `alert_thresholds`); franquia nunca tem default aqui.
+ */
+export interface INexFinopsUsageAlertDefaults {
+  /** Alertas ligados para todos os contratos, salvo override. Nasce `true`. */
+  enabled: boolean;
+  /**
+   * Frações da franquia que disparam aviso — **frações, não percentuais**:
+   * `0.8` = 80%. Nasce `[0.8, 1.0]`.
+   */
+  thresholds: number[];
+}
+
 // ── Main Document ──
 
 export interface INexFinopsContract extends IFireGlobalDoc {
@@ -106,6 +164,43 @@ export interface INexFinopsContract extends IFireGlobalDoc {
   /** Método com que o primeiro pagamento foi feito. `accepted_payment_methods` é a oferta; este é o fato. */
   payment_method?: NexFinopsPaymentMethod | null;
   asaas?: INexFinopsContractAsaasInfo | null;
+
+  // ── Franquias e alertas de consumo (feat-150 F0) ──
+
+  /**
+   * Franquia incluída no ciclo, por métrica. A CHAVE é o id da métrica (ver
+   * `NexFinopsMetricCatalog`) e é deliberadamente `string`: métrica nova é um
+   * item de catálogo, não uma mudança de schema.
+   *
+   * Métrica ausente do mapa = **não contratada** ⇒ não gera alerta. Alertar em
+   * qualquer consumo sem franquia produziria alarme falso em massa.
+   *
+   * Vigência: a franquia herda `starts_at`/`ends_at` do contrato — mudar
+   * franquia é alterar o contrato.
+   *
+   * ⚠️ NÃO existe congelamento por competência ainda. Enquanto a feat-150 cheia
+   * não resolver isso, `allowances` **não pode** ser usado para recalcular
+   * competência fechada: reabrir junho leria a franquia de hoje, não a de junho.
+   */
+  allowances?: Record<string, INexFinopsContractAllowance> | null;
+
+  /**
+   * Override do liga/desliga global de alertas de consumo.
+   *
+   * ⚠️ **Ausente ≠ `false`.** Ausente = HERDA o default global
+   * (`INexFinopsUsageAlertDefaults.enabled`); `false` explícito é o kill-switch
+   * por cliente. Ler ausente como `false` desliga alerta de todo mundo.
+   */
+  alerts_enabled?: boolean | null;
+
+  /**
+   * Override dos gatilhos globais. Frações da franquia (`0.8` = 80%), válidas
+   * para todas as métricas do contrato.
+   *
+   * ⚠️ **Ausente ≠ lista vazia.** Ausente = HERDA
+   * `INexFinopsUsageAlertDefaults.thresholds`.
+   */
+  alert_thresholds?: number[] | null;
 }
 
 // ── Status transitions ──

package/package.json

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