@grapadigital/shared-schemas 1.0.228 → 1.0.231

package/dist/index.d.ts

@@ -38,5 +38,3 @@ export * from './schemas/snapshot.schema';
 export * from './schemas/lead.schema';
 export * from './utils/normalize-content-link.util';
 export * from './utils/merge-metrics-breakdown.util';
-export * from './utils/influencer-contract.util';
-export * from './utils/cost-per-impact.util';

package/dist/index.js

@@ -59,5 +59,3 @@ __exportStar(require("./schemas/snapshot.schema"), exports);
 __exportStar(require("./schemas/lead.schema"), exports);
 __exportStar(require("./utils/normalize-content-link.util"), exports);
 __exportStar(require("./utils/merge-metrics-breakdown.util"), exports);
-__exportStar(require("./utils/influencer-contract.util"), exports);
-__exportStar(require("./utils/cost-per-impact.util"), exports);

package/dist/schemas/client.schema.d.ts

@@ -40,7 +40,7 @@ export type ClientCustomization = (typeof CLIENT_CUSTOMIZATION_VALUES)[number];
  * `viralReachEngagementRate` é o limite de viral e só vale no Tier.
  * Ver GD-687.
  */
-export declare const CLIENT_GOAL_METRIC_VALUES: readonly ["potentialReach", "reachCount", "impressionCount", "engagementCount", "engagementRate", "reachEngagementRate", "qualifiedEngagementRate", "effectiveReach", "earnedMediaValue", "score", "costPerInfluency", "costPerImpact", "costPerEngagement", "savedCount", "shareCount", "videoCompletionRate", "viralReachEngagementRate"];
+export declare const CLIENT_GOAL_METRIC_VALUES: readonly ["potentialReach", "reachCount", "impressionCount", "engagementCount", "engagementRate", "reachEngagementRate", "followersEngagementRate", "qualifiedEngagementRate", "effectiveReach", "earnedMediaValue", "score", "costPerInfluency", "costPerImpact", "costPerEngagement", "savedCount", "shareCount", "videoCompletionRate", "viralReachEngagementRate"];
 export type ClientGoalMetric = (typeof CLIENT_GOAL_METRIC_VALUES)[number];
 export type ClientGoalMetricUnit = 'count' | 'rate' | 'currency';
 /** Unidade de cada métrica. `rate` é guardado como fração (0,10 = 10%). */

package/dist/schemas/client.schema.js

@@ -33,6 +33,7 @@ exports.CLIENT_GOAL_METRIC_VALUES = [
     'engagementCount',
     'engagementRate',
     'reachEngagementRate',
+    'followersEngagementRate',
     'qualifiedEngagementRate',
     'effectiveReach',
     'earnedMediaValue',
@@ -53,6 +54,7 @@ exports.CLIENT_GOAL_METRIC_UNITS = {
     engagementCount: 'count',
     engagementRate: 'rate',
     reachEngagementRate: 'rate',
+    followersEngagementRate: 'rate',
     qualifiedEngagementRate: 'rate',
     effectiveReach: 'count',
     earnedMediaValue: 'currency',

package/dist/schemas/content.schema.d.ts

@@ -126,6 +126,15 @@ export declare class Metrics {
     reachEngagementRate?: number | null;
     /** Tx. de Engaj. por Seguidores: engagementCount ÷ potentialReach (fração). Ver GD-703. */
     followersEngagementRate?: number | null;
+    /**
+     * Engajamento ponderado do Real E/R (pesos do genc): curtidas×1 + comentários
+     * curados×2 + compartilhamentos×3 + salvos×3 + respostas×2 + cliques×6 +
+     * toques×1. Comentário curado = alvo marca ou conteúdo, fora de spam. null em
+     * story, sem GenIA ou sem comentários classificados. Ver GD-720.
+     */
+    curatedEngagementCount?: number | null;
+    /** Real E/R: curatedEngagementCount ÷ potentialReach (fração). Ver GD-720. */
+    curatedEngagementRate?: number | null;
     /** Nome do Client.tiers pelo potentialReach do post; null sem Tiers ou fora das faixas. Ver GD-703. */
     tier?: string | null;
     /**

package/dist/schemas/content.schema.js

@@ -219,6 +219,14 @@ __decorate([
     (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
     __metadata("design:type", Object)
 ], Metrics.prototype, "followersEngagementRate", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
+    __metadata("design:type", Object)
+], Metrics.prototype, "curatedEngagementCount", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
+    __metadata("design:type", Object)
+], Metrics.prototype, "curatedEngagementRate", void 0);
 __decorate([
     (0, mongoose_1.Prop)({ type: String, required: false, default: null }),
     __metadata("design:type", Object)
@@ -393,22 +401,23 @@ ContentMetricsHistoryEntry = __decorate([
 exports.ContentMetricsHistoryEntry = ContentMetricsHistoryEntry;
 exports.ContentMetricsHistoryEntrySchema = mongoose_1.SchemaFactory.createForClass(ContentMetricsHistoryEntry);
 /** Métricas estimadas pelo porte do perfil, para quando a rede não informa. Ver GD-751. */
+// null é valor válido (sem estimativa): required recusaria null no create.
 let EstimatedMetrics = class EstimatedMetrics {
 };
 __decorate([
-    (0, mongoose_1.Prop)({ type: Number, required: true, default: null }),
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
     __metadata("design:type", Object)
 ], EstimatedMetrics.prototype, "impressionCount", void 0);
 __decorate([
-    (0, mongoose_1.Prop)({ type: Number, required: true, default: null }),
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
     __metadata("design:type", Object)
 ], EstimatedMetrics.prototype, "reachCount", void 0);
 __decorate([
-    (0, mongoose_1.Prop)({ type: Number, required: true, default: null }),
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
     __metadata("design:type", Object)
 ], EstimatedMetrics.prototype, "engagementCount", void 0);
 __decorate([
-    (0, mongoose_1.Prop)({ type: Number, required: true, default: null }),
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
     __metadata("design:type", Object)
 ], EstimatedMetrics.prototype, "engagementRate", void 0);
 EstimatedMetrics = __decorate([

package/dist/utils/influencer-contract.util.d.ts

@@ -4,14 +4,19 @@ type ContractLike = Pick<InfluencerContract, 'value' | 'productsValue' | 'startD
 };
 /**
  * Fim efetivo da vigência: o maior entre o fim do Contrato e o fim dos Aditivos
- * ativos (no genc o Aditivo estende a vigência). null = Contrato em aberto.
- * Ver GD-715.
+ * ativos (o Aditivo estende a vigência). null = Contrato em aberto, mesmo com
+ * Aditivo. Ver GD-715.
  */
 export declare const getContractEndDate: (contract: ContractLike) => Date | null;
+/**
+ * Início do dia seguinte ao fim da vigência em São Paulo (limite exclusivo):
+ * o último dia conta inteiro. null = Contrato em aberto.
+ */
+export declare const getContractEndExclusive: (contract: ContractLike) => Date | null;
 /**
  * Meses de vigência como no genc (`calcular_meses_vigencia`): anos × 12 + meses
  * e mais 1 se sobrar dia; mínimo 1. Sem fim, conta até `now`.
- * Ex.: 10/06/2025 a 11/02/2027 = 21.
+ * Ex.: 10/06/2025 a 11/02/2027 = 21; 15/03 a 14/09 = 6.
  */
 export declare const getContractMonths: (contract: ContractLike, now?: Date) => number;
 /** Cachê + produtos + Aditivos ativos. */
@@ -20,7 +25,7 @@ export declare const getContractTotalValue: (contract: ContractLike) => number;
 export declare const getContractMonthlyValue: (contract: ContractLike, now?: Date) => number;
 /** Ativo e assinado (status ausente conta como assinado). */
 export declare const isContractUsable: (contract: ContractLike) => boolean;
-/** Contrato usável do cliente vigente em `at` (sem fim = em aberto). */
+/** Contrato usável do cliente vigente em `at`, com o último dia inteiro (sem fim = em aberto). */
 export declare const getActiveContract: <T extends ContractLike>(influencer: {
     contracts?: T[] | null | undefined;
 } | null | undefined, clientId: unknown, at: Date) => T | null;

package/dist/utils/influencer-contract.util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getActiveContract = exports.isContractUsable = exports.getContractMonthlyValue = exports.getContractTotalValue = exports.getContractMonths = exports.getContractEndDate = void 0;
+exports.getActiveContract = exports.isContractUsable = exports.getContractMonthlyValue = exports.getContractTotalValue = exports.getContractMonths = exports.getContractEndExclusive = exports.getContractEndDate = void 0;
 const BRT_OFFSET_MS = 3 * 60 * 60 * 1000;
 /** Data no calendário de São Paulo (as datas do Flow são gravadas à meia-noite BRT = 03:00Z). */
 const brtParts = (date) => {
@@ -11,31 +11,41 @@ const round2 = (value) => Math.round(value * 100) / 100;
 const activeAmendments = (contract) => (contract.amendments ?? []).filter((amendment) => amendment.isActive !== false);
 /**
  * Fim efetivo da vigência: o maior entre o fim do Contrato e o fim dos Aditivos
- * ativos (no genc o Aditivo estende a vigência). null = Contrato em aberto.
- * Ver GD-715.
+ * ativos (o Aditivo estende a vigência). null = Contrato em aberto, mesmo com
+ * Aditivo. Ver GD-715.
  */
 const getContractEndDate = (contract) => {
+    if (!contract.endDate)
+        return null;
     const ends = [contract.endDate, ...activeAmendments(contract).map((a) => a.endDate)]
         .filter((date) => !!date)
         .map((date) => new Date(date).getTime());
-    return ends.length > 0 ? new Date(Math.max(...ends)) : null;
+    return new Date(Math.max(...ends));
 };
 exports.getContractEndDate = getContractEndDate;
+/**
+ * Início do dia seguinte ao fim da vigência em São Paulo (limite exclusivo):
+ * o último dia conta inteiro. null = Contrato em aberto.
+ */
+const getContractEndExclusive = (contract) => {
+    const end = (0, exports.getContractEndDate)(contract);
+    if (!end)
+        return null;
+    const { year, month, day } = brtParts(end);
+    return new Date(Date.UTC(year, month - 1, day + 1) + BRT_OFFSET_MS);
+};
+exports.getContractEndExclusive = getContractEndExclusive;
 /**
  * Meses de vigência como no genc (`calcular_meses_vigencia`): anos × 12 + meses
  * e mais 1 se sobrar dia; mínimo 1. Sem fim, conta até `now`.
- * Ex.: 10/06/2025 a 11/02/2027 = 21.
+ * Ex.: 10/06/2025 a 11/02/2027 = 21; 15/03 a 14/09 = 6.
  */
 const getContractMonths = (contract, now = new Date()) => {
     const start = brtParts(contract.startDate);
     const end = brtParts((0, exports.getContractEndDate)(contract) ?? now);
     let months = (end.year - start.year) * 12 + (end.month - start.month);
-    let days = end.day - start.day;
-    if (days < 0) {
-        months -= 1;
-        days += 1; // relativedelta: só importa se sobrou dia
-    }
-    if (days > 0)
+    // relativedelta: dia do fim menor tira um mês e sobra dia, que devolve o mês.
+    if (end.day > start.day)
         months += 1;
     return Math.max(1, months);
 };
@@ -51,7 +61,7 @@ exports.getContractMonthlyValue = getContractMonthlyValue;
 /** Ativo e assinado (status ausente conta como assinado). */
 const isContractUsable = (contract) => contract.isActive !== false && (contract.status ?? 'signed') === 'signed';
 exports.isContractUsable = isContractUsable;
-/** Contrato usável do cliente vigente em `at` (sem fim = em aberto). */
+/** Contrato usável do cliente vigente em `at`, com o último dia inteiro (sem fim = em aberto). */
 const getActiveContract = (influencer, clientId, at) => {
     const time = new Date(at).getTime();
     return ((influencer?.contracts ?? []).find((contract) => {
@@ -60,8 +70,8 @@ const getActiveContract = (influencer, clientId, at) => {
         const client = contract.client?._id ?? contract.client;
         if (String(client) !== String(clientId))
             return false;
-        const end = (0, exports.getContractEndDate)(contract);
-        return new Date(contract.startDate).getTime() <= time && (!end || time <= end.getTime());
+        const end = (0, exports.getContractEndExclusive)(contract);
+        return new Date(contract.startDate).getTime() <= time && (!end || time < end.getTime());
     }) ?? null);
 };
 exports.getActiveContract = getActiveContract;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grapadigital/shared-schemas",
-  "version": "1.0.228",
+  "version": "1.0.231",
   "description": "Shared Mongoose Schemas",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -38,5 +38,3 @@ export * from './schemas/snapshot.schema';
 export * from './schemas/lead.schema';
 export * from './utils/normalize-content-link.util';
 export * from './utils/merge-metrics-breakdown.util';
-export * from './utils/influencer-contract.util';
-export * from './utils/cost-per-impact.util';

package/src/schemas/client.schema.ts

@@ -32,6 +32,7 @@ export const CLIENT_GOAL_METRIC_VALUES = [
   'engagementCount',
   'engagementRate',
   'reachEngagementRate',
+  'followersEngagementRate',
   'qualifiedEngagementRate',
   'effectiveReach',
   'earnedMediaValue',
@@ -56,6 +57,7 @@ export const CLIENT_GOAL_METRIC_UNITS: Record<ClientGoalMetric, ClientGoalMetric
   engagementCount: 'count',
   engagementRate: 'rate',
   reachEngagementRate: 'rate',
+  followersEngagementRate: 'rate',
   qualifiedEngagementRate: 'rate',
   effectiveReach: 'count',
   earnedMediaValue: 'currency',

package/src/schemas/content.schema.ts

@@ -177,6 +177,19 @@ export class Metrics {
   @Prop({ type: Number, required: false, default: null })
   followersEngagementRate?: number | null;
 
+  /**
+   * Engajamento ponderado do Real E/R (pesos do genc): curtidas×1 + comentários
+   * curados×2 + compartilhamentos×3 + salvos×3 + respostas×2 + cliques×6 +
+   * toques×1. Comentário curado = alvo marca ou conteúdo, fora de spam. null em
+   * story, sem GenIA ou sem comentários classificados. Ver GD-720.
+   */
+  @Prop({ type: Number, required: false, default: null })
+  curatedEngagementCount?: number | null;
+
+  /** Real E/R: curatedEngagementCount ÷ potentialReach (fração). Ver GD-720. */
+  @Prop({ type: Number, required: false, default: null })
+  curatedEngagementRate?: number | null;
+
   /** Nome do Client.tiers pelo potentialReach do post; null sem Tiers ou fora das faixas. Ver GD-703. */
   @Prop({ type: String, required: false, default: null })
   tier?: string | null;
@@ -325,18 +338,19 @@ export class ContentMetricsHistoryEntry {
 export const ContentMetricsHistoryEntrySchema = SchemaFactory.createForClass(ContentMetricsHistoryEntry);
 
 /** Métricas estimadas pelo porte do perfil, para quando a rede não informa. Ver GD-751. */
+// null é valor válido (sem estimativa): required recusaria null no create.
 @Schema({ _id: false })
 export class EstimatedMetrics {
-  @Prop({ type: Number, required: true, default: null })
+  @Prop({ type: Number, required: false, default: null })
   impressionCount?: number | null;
 
-  @Prop({ type: Number, required: true, default: null })
+  @Prop({ type: Number, required: false, default: null })
   reachCount?: number | null;
 
-  @Prop({ type: Number, required: true, default: null })
+  @Prop({ type: Number, required: false, default: null })
   engagementCount?: number | null;
 
-  @Prop({ type: Number, required: true, default: null })
+  @Prop({ type: Number, required: false, default: null })
   engagementRate?: number | null;
 }
 

package/src/utils/cost-per-impact.util.ts

@@ -1,99 +0,0 @@
-import { getContractMonthlyValue } from './influencer-contract.util';
-import { InfluencerContract } from '../schemas/influencer.schema';
-
-/**
- * CPI (Custo por Impacto), como no genc (`TB_Contratos_Influencer_Cliente` e
- * `TB_CPI_Mensal_Contrato`). Ver GD-715.
- * CPI = valor ÷ ((E/R% ÷ 100) × impressões × posts), E/R% = engajamento ÷ alcance potencial × 100.
- */
-
-const round = (value: number, places: number) => Math.round(value * 10 ** places) / 10 ** places;
-
-export const getEngagementRatePercent = (totals: { engagement: number; potentialReach: number }): number | null =>
-  totals.potentialReach > 0 ? (totals.engagement / totals.potentialReach) * 100 : null;
-
-export const getCostPerImpact = (input: {
-  value: number;
-  engagementRatePercent: number | null;
-  impressions: number;
-  posts: number;
-}): number | null => {
-  const { value, engagementRatePercent, impressions, posts } = input;
-  if (!engagementRatePercent || engagementRatePercent <= 0 || value <= 0) return null;
-  const divisor = (engagementRatePercent / 100) * impressions * posts;
-  return divisor > 0 ? round(value / divisor, 6) : null;
-};
-
-export interface ContractMonthTotals {
-  year: number;
-  month: number;
-  posts: number;
-  impressions: number;
-  engagement: number;
-  potentialReach: number;
-}
-
-export interface MonthlyCostPerImpact extends ContractMonthTotals {
-  monthlyValue: number;
-  monthlyCostPerImpact: number | null;
-  engagementRatePercent: number | null;
-  elapsedMonths: number;
-  accumulatedSpend: number;
-}
-
-/**
- * Série mensal acumulada desde o mês de início até `untilMonth` (inclusive):
- * gasto acumulado = valor mensal × meses decorridos; métricas somadas desde o
- * início. `monthlyTotals` traz os totais de cada mês (não acumulados).
- */
-export const getMonthlyCostPerImpactSeries = (
-  contract: Pick<InfluencerContract, 'value' | 'productsValue' | 'startDate' | 'endDate' | 'amendments' | 'status' | 'isActive'>,
-  monthlyTotals: ContractMonthTotals[],
-  until: { year: number; month: number },
-): MonthlyCostPerImpact[] => {
-  const brt = new Date(new Date(contract.startDate).getTime() - 3 * 60 * 60 * 1000);
-  let year = brt.getUTCFullYear();
-  let month = brt.getUTCMonth() + 1;
-  const monthlyValue = getContractMonthlyValue(contract);
-  const byMonth = new Map(monthlyTotals.map((t) => [`${t.year}-${t.month}`, t]));
-  const acc = { posts: 0, impressions: 0, engagement: 0, potentialReach: 0 };
-  const series: MonthlyCostPerImpact[] = [];
-  let elapsedMonths = 0;
-  while (year < until.year || (year === until.year && month <= until.month)) {
-    elapsedMonths += 1;
-    const totals = byMonth.get(`${year}-${month}`);
-    if (totals) {
-      acc.posts += totals.posts;
-      acc.impressions += totals.impressions;
-      acc.engagement += totals.engagement;
-      acc.potentialReach += totals.potentialReach;
-    }
-    const accumulatedSpend = round(monthlyValue * elapsedMonths, 2);
-    const engagementRatePercent = acc.posts > 0 ? getEngagementRatePercent(acc) : null;
-    series.push({
-      year,
-      month,
-      ...acc,
-      monthlyValue,
-      elapsedMonths,
-      accumulatedSpend,
-      engagementRatePercent: engagementRatePercent == null ? null : round(engagementRatePercent, 4),
-      monthlyCostPerImpact:
-        acc.posts > 0 && acc.engagement > 0
-          ? getCostPerImpact({ value: accumulatedSpend, engagementRatePercent, impressions: acc.impressions, posts: acc.posts })
-          : null,
-    });
-    month += 1;
-    if (month > 12) {
-      month = 1;
-      year += 1;
-    }
-  }
-  return series;
-};
-
-/** Média dos CPIs mensais não nulos. */
-export const getAverageMonthlyCostPerImpact = (series: MonthlyCostPerImpact[]): number | null => {
-  const values = series.map((row) => row.monthlyCostPerImpact).filter((v): v is number => v != null);
-  return values.length > 0 ? round(values.reduce((a, b) => a + b, 0) / values.length, 6) : null;
-};

package/src/utils/influencer-contract.util.ts

@@ -1,83 +0,0 @@
-import { InfluencerContract } from '../schemas/influencer.schema';
-
-type ContractLike = Pick<
-  InfluencerContract,
-  'value' | 'productsValue' | 'startDate' | 'endDate' | 'amendments' | 'status' | 'isActive'
-> & { client?: unknown };
-
-const BRT_OFFSET_MS = 3 * 60 * 60 * 1000;
-
-/** Data no calendário de São Paulo (as datas do Flow são gravadas à meia-noite BRT = 03:00Z). */
-const brtParts = (date: Date) => {
-  const d = new Date(new Date(date).getTime() - BRT_OFFSET_MS);
-  return { year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate() };
-};
-
-const round2 = (value: number) => Math.round(value * 100) / 100;
-
-const activeAmendments = (contract: ContractLike) =>
-  (contract.amendments ?? []).filter((amendment) => amendment.isActive !== false);
-
-/**
- * Fim efetivo da vigência: o maior entre o fim do Contrato e o fim dos Aditivos
- * ativos (no genc o Aditivo estende a vigência). null = Contrato em aberto.
- * Ver GD-715.
- */
-export const getContractEndDate = (contract: ContractLike): Date | null => {
-  const ends = [contract.endDate, ...activeAmendments(contract).map((a) => a.endDate)]
-    .filter((date): date is Date => !!date)
-    .map((date) => new Date(date).getTime());
-  return ends.length > 0 ? new Date(Math.max(...ends)) : null;
-};
-
-/**
- * Meses de vigência como no genc (`calcular_meses_vigencia`): anos × 12 + meses
- * e mais 1 se sobrar dia; mínimo 1. Sem fim, conta até `now`.
- * Ex.: 10/06/2025 a 11/02/2027 = 21.
- */
-export const getContractMonths = (contract: ContractLike, now: Date = new Date()): number => {
-  const start = brtParts(contract.startDate);
-  const end = brtParts(getContractEndDate(contract) ?? now);
-  let months = (end.year - start.year) * 12 + (end.month - start.month);
-  let days = end.day - start.day;
-  if (days < 0) {
-    months -= 1;
-    days += 1; // relativedelta: só importa se sobrou dia
-  }
-  if (days > 0) months += 1;
-  return Math.max(1, months);
-};
-
-/** Cachê + produtos + Aditivos ativos. */
-export const getContractTotalValue = (contract: ContractLike): number =>
-  round2(
-    (contract.value ?? 0) +
-      (contract.productsValue ?? 0) +
-      activeAmendments(contract).reduce((sum, a) => sum + (a.value ?? 0), 0),
-  );
-
-/** Total ÷ meses de vigência, 2 casas (428.392,93 ÷ 21 = 20.399,66). */
-export const getContractMonthlyValue = (contract: ContractLike, now?: Date): number =>
-  round2(getContractTotalValue(contract) / getContractMonths(contract, now));
-
-/** Ativo e assinado (status ausente conta como assinado). */
-export const isContractUsable = (contract: ContractLike): boolean =>
-  contract.isActive !== false && (contract.status ?? 'signed') === 'signed';
-
-/** Contrato usável do cliente vigente em `at` (sem fim = em aberto). */
-export const getActiveContract = <T extends ContractLike>(
-  influencer: { contracts?: T[] | null } | null | undefined,
-  clientId: unknown,
-  at: Date,
-): T | null => {
-  const time = new Date(at).getTime();
-  return (
-    (influencer?.contracts ?? []).find((contract) => {
-      if (!isContractUsable(contract)) return false;
-      const client = (contract.client as { _id?: unknown })?._id ?? contract.client;
-      if (String(client) !== String(clientId)) return false;
-      const end = getContractEndDate(contract);
-      return new Date(contract.startDate).getTime() <= time && (!end || time <= end.getTime());
-    }) ?? null
-  );
-};