@grapadigital/shared-schemas 1.0.227 → 1.0.228

package/dist/index.d.ts

@@ -38,3 +38,5 @@ 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,3 +59,5 @@ __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/influencer.schema.d.ts

@@ -62,15 +62,60 @@ export declare const NoteSchema: MongooseSchema<Note, import("mongoose").Model<N
 } & {
     __v: number;
 }>;
+/** Status do Contrato do Influenciador. Ver GD-715. */
+export declare const CONTRACT_STATUS_VALUES: readonly ["draft", "proposed", "signed", "rejected"];
+export type ContractStatus = (typeof CONTRACT_STATUS_VALUES)[number];
+/**
+ * Aditivo do Contrato: soma no valor total quando ativo e pode estender a
+ * vigência (o fim do Contrato vai até o fim do último Aditivo ativo). Não tem
+ * ligação com Ações. Ver GD-715.
+ */
+export declare class ContractAmendment {
+    _id?: Types.ObjectId;
+    value: number;
+    isActive?: boolean;
+    startDate: Date;
+    endDate: Date;
+    description?: string | null;
+}
+export declare const ContractAmendmentSchema: MongooseSchema<ContractAmendment, import("mongoose").Model<ContractAmendment, any, any, any, import("mongoose").Document<unknown, any, ContractAmendment, any, {}> & ContractAmendment & Required<{
+    _id: Types.ObjectId;
+}> & {
+    __v: number;
+}, any>, {}, {}, {}, {}, import("mongoose").DefaultSchemaOptions, ContractAmendment, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<ContractAmendment>, {}, import("mongoose").ResolveSchemaOptions<import("mongoose").DefaultSchemaOptions>> & import("mongoose").FlatRecord<ContractAmendment> & Required<{
+    _id: Types.ObjectId;
+}> & {
+    __v: number;
+}>;
 export declare class InfluencerContract {
     _id?: Types.ObjectId;
     client: Types.ObjectId | Client;
+    /** Cachê total do Contrato (o `valor_cache` do genc). Ver GD-715. */
     value: number;
+    /** Valor em produtos; entra no total. Ver GD-715. */
+    productsValue?: number;
+    status?: ContractStatus;
+    /** Desligado = Contrato encerrado. */
+    isActive?: boolean;
+    /**
+     * Rateio do custo: monthly = valor mensal (total ÷ meses) por mês-calendário;
+     * annual = valor total no período.
+     */
     periodType: 'monthly' | 'annual';
     startDate: Date;
     endDate?: Date;
     deliveryScope?: Delivery;
     documentUrl?: string;
+    /** CPI (Custo por Impacto) contratual, digitado no planejamento. Ver GD-715. */
+    contractedCostPerImpact?: number | null;
+    /** E/R contratual, em fração (0,02 = 2%). */
+    contractedEngagementRate?: number | null;
+    /** Ex.: "Team Galaxy", "Content Creator", "Tech". */
+    squad?: string | null;
+    /** Ex.: "Technology", "Camera", "Fashion". */
+    passionPoint?: string | null;
+    description?: string | null;
+    amendments?: ContractAmendment[];
 }
 export declare const InfluencerContractSchema: MongooseSchema<InfluencerContract, import("mongoose").Model<InfluencerContract, any, any, any, import("mongoose").Document<unknown, any, InfluencerContract, any, {}> & InfluencerContract & Required<{
     _id: Types.ObjectId;

package/dist/schemas/influencer.schema.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InfluencerModel = exports.InfluencerSchema = exports.Influencer = exports.InfluencerContractSchema = exports.InfluencerContract = exports.NoteSchema = exports.Note = exports.AdvisorSchema = exports.Advisor = void 0;
+exports.InfluencerModel = exports.InfluencerSchema = exports.Influencer = exports.InfluencerContractSchema = exports.InfluencerContract = exports.ContractAmendmentSchema = exports.ContractAmendment = exports.CONTRACT_STATUS_VALUES = exports.NoteSchema = exports.Note = exports.AdvisorSchema = exports.Advisor = void 0;
 const mongoose_1 = require("@nestjs/mongoose");
 const mongoose_2 = require("mongoose");
 const party_schema_1 = require("./party.schema");
@@ -72,6 +72,44 @@ Note = __decorate([
 ], Note);
 exports.Note = Note;
 exports.NoteSchema = mongoose_1.SchemaFactory.createForClass(Note);
+/** Status do Contrato do Influenciador. Ver GD-715. */
+exports.CONTRACT_STATUS_VALUES = ['draft', 'proposed', 'signed', 'rejected'];
+/**
+ * Aditivo do Contrato: soma no valor total quando ativo e pode estender a
+ * vigência (o fim do Contrato vai até o fim do último Aditivo ativo). Não tem
+ * ligação com Ações. Ver GD-715.
+ */
+let ContractAmendment = class ContractAmendment {
+};
+__decorate([
+    (0, mongoose_1.Prop)({ type: mongoose_2.Schema.Types.ObjectId, auto: true, required: false }),
+    __metadata("design:type", mongoose_2.Types.ObjectId)
+], ContractAmendment.prototype, "_id", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: true }),
+    __metadata("design:type", Number)
+], ContractAmendment.prototype, "value", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Boolean, required: false, default: true }),
+    __metadata("design:type", Boolean)
+], ContractAmendment.prototype, "isActive", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Date, required: true }),
+    __metadata("design:type", Date)
+], ContractAmendment.prototype, "startDate", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Date, required: true }),
+    __metadata("design:type", Date)
+], ContractAmendment.prototype, "endDate", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: String, required: false, default: null }),
+    __metadata("design:type", Object)
+], ContractAmendment.prototype, "description", void 0);
+ContractAmendment = __decorate([
+    (0, mongoose_1.Schema)({ timestamps: true })
+], ContractAmendment);
+exports.ContractAmendment = ContractAmendment;
+exports.ContractAmendmentSchema = mongoose_1.SchemaFactory.createForClass(ContractAmendment);
 // Contrato de valor fixo recorrente (influenciador embaixador de marca) —
 // alternativa ao pagamento avulso por Recruitment (scope.payment/advisorPayment).
 // Escopo de entregas reaproveita a mesma classe Delivery do termo de aceite
@@ -90,6 +128,18 @@ __decorate([
     (0, mongoose_1.Prop)({ type: Number, required: true }),
     __metadata("design:type", Number)
 ], InfluencerContract.prototype, "value", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: 0 }),
+    __metadata("design:type", Number)
+], InfluencerContract.prototype, "productsValue", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: String, enum: exports.CONTRACT_STATUS_VALUES, required: false, default: 'signed' }),
+    __metadata("design:type", String)
+], InfluencerContract.prototype, "status", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Boolean, required: false, default: true }),
+    __metadata("design:type", Boolean)
+], InfluencerContract.prototype, "isActive", void 0);
 __decorate([
     (0, mongoose_1.Prop)({ type: String, enum: ['monthly', 'annual'], required: true }),
     __metadata("design:type", String)
@@ -110,6 +160,30 @@ __decorate([
     (0, mongoose_1.Prop)({ type: String, required: false }),
     __metadata("design:type", String)
 ], InfluencerContract.prototype, "documentUrl", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
+    __metadata("design:type", Object)
+], InfluencerContract.prototype, "contractedCostPerImpact", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: Number, required: false, default: null }),
+    __metadata("design:type", Object)
+], InfluencerContract.prototype, "contractedEngagementRate", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: String, required: false, default: null }),
+    __metadata("design:type", Object)
+], InfluencerContract.prototype, "squad", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: String, required: false, default: null }),
+    __metadata("design:type", Object)
+], InfluencerContract.prototype, "passionPoint", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: String, required: false, default: null }),
+    __metadata("design:type", Object)
+], InfluencerContract.prototype, "description", void 0);
+__decorate([
+    (0, mongoose_1.Prop)({ type: [exports.ContractAmendmentSchema], required: false, default: [] }),
+    __metadata("design:type", Array)
+], InfluencerContract.prototype, "amendments", void 0);
 InfluencerContract = __decorate([
     (0, mongoose_1.Schema)({ timestamps: true })
 ], InfluencerContract);

package/dist/utils/cost-per-impact.util.d.ts

@@ -0,0 +1,37 @@
+import { InfluencerContract } from '../schemas/influencer.schema';
+export declare const getEngagementRatePercent: (totals: {
+    engagement: number;
+    potentialReach: number;
+}) => number | null;
+export declare const getCostPerImpact: (input: {
+    value: number;
+    engagementRatePercent: number | null;
+    impressions: number;
+    posts: number;
+}) => number | 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 declare const getMonthlyCostPerImpactSeries: (contract: Pick<InfluencerContract, 'value' | 'productsValue' | 'startDate' | 'endDate' | 'amendments' | 'status' | 'isActive'>, monthlyTotals: ContractMonthTotals[], until: {
+    year: number;
+    month: number;
+}) => MonthlyCostPerImpact[];
+/** Média dos CPIs mensais não nulos. */
+export declare const getAverageMonthlyCostPerImpact: (series: MonthlyCostPerImpact[]) => number | null;

package/dist/utils/cost-per-impact.util.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAverageMonthlyCostPerImpact = exports.getMonthlyCostPerImpactSeries = exports.getCostPerImpact = exports.getEngagementRatePercent = void 0;
+const influencer_contract_util_1 = require("./influencer-contract.util");
+/**
+ * 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, places) => Math.round(value * 10 ** places) / 10 ** places;
+const getEngagementRatePercent = (totals) => totals.potentialReach > 0 ? (totals.engagement / totals.potentialReach) * 100 : null;
+exports.getEngagementRatePercent = getEngagementRatePercent;
+const getCostPerImpact = (input) => {
+    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;
+};
+exports.getCostPerImpact = getCostPerImpact;
+/**
+ * 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).
+ */
+const getMonthlyCostPerImpactSeries = (contract, monthlyTotals, until) => {
+    const brt = new Date(new Date(contract.startDate).getTime() - 3 * 60 * 60 * 1000);
+    let year = brt.getUTCFullYear();
+    let month = brt.getUTCMonth() + 1;
+    const monthlyValue = (0, influencer_contract_util_1.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 = [];
+    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 ? (0, exports.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
+                ? (0, exports.getCostPerImpact)({ value: accumulatedSpend, engagementRatePercent, impressions: acc.impressions, posts: acc.posts })
+                : null,
+        });
+        month += 1;
+        if (month > 12) {
+            month = 1;
+            year += 1;
+        }
+    }
+    return series;
+};
+exports.getMonthlyCostPerImpactSeries = getMonthlyCostPerImpactSeries;
+/** Média dos CPIs mensais não nulos. */
+const getAverageMonthlyCostPerImpact = (series) => {
+    const values = series.map((row) => row.monthlyCostPerImpact).filter((v) => v != null);
+    return values.length > 0 ? round(values.reduce((a, b) => a + b, 0) / values.length, 6) : null;
+};
+exports.getAverageMonthlyCostPerImpact = getAverageMonthlyCostPerImpact;

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

@@ -0,0 +1,27 @@
+import { InfluencerContract } from '../schemas/influencer.schema';
+type ContractLike = Pick<InfluencerContract, 'value' | 'productsValue' | 'startDate' | 'endDate' | 'amendments' | 'status' | 'isActive'> & {
+    client?: unknown;
+};
+/**
+ * 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 declare const getContractEndDate: (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.
+ */
+export declare const getContractMonths: (contract: ContractLike, now?: Date) => number;
+/** Cachê + produtos + Aditivos ativos. */
+export declare const getContractTotalValue: (contract: ContractLike) => number;
+/** Total ÷ meses de vigência, 2 casas (428.392,93 ÷ 21 = 20.399,66). */
+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). */
+export declare const getActiveContract: <T extends ContractLike>(influencer: {
+    contracts?: T[] | null | undefined;
+} | null | undefined, clientId: unknown, at: Date) => T | null;
+export {};

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActiveContract = exports.isContractUsable = exports.getContractMonthlyValue = exports.getContractTotalValue = exports.getContractMonths = 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) => {
+    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) => 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.
+ */
+const getContractEndDate = (contract) => {
+    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;
+};
+exports.getContractEndDate = getContractEndDate;
+/**
+ * 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.
+ */
+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)
+        months += 1;
+    return Math.max(1, months);
+};
+exports.getContractMonths = getContractMonths;
+/** Cachê + produtos + Aditivos ativos. */
+const getContractTotalValue = (contract) => round2((contract.value ?? 0) +
+    (contract.productsValue ?? 0) +
+    activeAmendments(contract).reduce((sum, a) => sum + (a.value ?? 0), 0));
+exports.getContractTotalValue = getContractTotalValue;
+/** Total ÷ meses de vigência, 2 casas (428.392,93 ÷ 21 = 20.399,66). */
+const getContractMonthlyValue = (contract, now) => round2((0, exports.getContractTotalValue)(contract) / (0, exports.getContractMonths)(contract, now));
+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). */
+const getActiveContract = (influencer, clientId, at) => {
+    const time = new Date(at).getTime();
+    return ((influencer?.contracts ?? []).find((contract) => {
+        if (!(0, exports.isContractUsable)(contract))
+            return false;
+        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());
+    }) ?? null);
+};
+exports.getActiveContract = getActiveContract;

package/package.json

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

package/src/index.ts

@@ -38,3 +38,5 @@ 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/influencer.schema.ts

@@ -47,6 +47,38 @@ export class Note {
 
 export const NoteSchema = SchemaFactory.createForClass(Note);
 
+/** Status do Contrato do Influenciador. Ver GD-715. */
+export const CONTRACT_STATUS_VALUES = ['draft', 'proposed', 'signed', 'rejected'] as const;
+export type ContractStatus = (typeof CONTRACT_STATUS_VALUES)[number];
+
+/**
+ * Aditivo do Contrato: soma no valor total quando ativo e pode estender a
+ * vigência (o fim do Contrato vai até o fim do último Aditivo ativo). Não tem
+ * ligação com Ações. Ver GD-715.
+ */
+@Schema({ timestamps: true })
+export class ContractAmendment {
+  @Prop({ type: MongooseSchema.Types.ObjectId, auto: true, required: false })
+  _id?: Types.ObjectId;
+
+  @Prop({ type: Number, required: true })
+  value: number;
+
+  @Prop({ type: Boolean, required: false, default: true })
+  isActive?: boolean;
+
+  @Prop({ type: Date, required: true })
+  startDate: Date;
+
+  @Prop({ type: Date, required: true })
+  endDate: Date;
+
+  @Prop({ type: String, required: false, default: null })
+  description?: string | null;
+}
+
+export const ContractAmendmentSchema = SchemaFactory.createForClass(ContractAmendment);
+
 // Contrato de valor fixo recorrente (influenciador embaixador de marca) —
 // alternativa ao pagamento avulso por Recruitment (scope.payment/advisorPayment).
 // Escopo de entregas reaproveita a mesma classe Delivery do termo de aceite
@@ -59,9 +91,25 @@ export class InfluencerContract {
   @Prop({ type: MongooseSchema.Types.ObjectId, ref: 'Client', required: true })
   client: Types.ObjectId | Client;
 
+  /** Cachê total do Contrato (o `valor_cache` do genc). Ver GD-715. */
   @Prop({ type: Number, required: true })
   value: number;
 
+  /** Valor em produtos; entra no total. Ver GD-715. */
+  @Prop({ type: Number, required: false, default: 0 })
+  productsValue?: number;
+
+  @Prop({ type: String, enum: CONTRACT_STATUS_VALUES, required: false, default: 'signed' })
+  status?: ContractStatus;
+
+  /** Desligado = Contrato encerrado. */
+  @Prop({ type: Boolean, required: false, default: true })
+  isActive?: boolean;
+
+  /**
+   * Rateio do custo: monthly = valor mensal (total ÷ meses) por mês-calendário;
+   * annual = valor total no período.
+   */
   @Prop({ type: String, enum: ['monthly', 'annual'], required: true })
   periodType: 'monthly' | 'annual';
 
@@ -83,6 +131,28 @@ export class InfluencerContract {
   // fica salva no Mongo.
   @Prop({ type: String, required: false })
   documentUrl?: string;
+
+  /** CPI (Custo por Impacto) contratual, digitado no planejamento. Ver GD-715. */
+  @Prop({ type: Number, required: false, default: null })
+  contractedCostPerImpact?: number | null;
+
+  /** E/R contratual, em fração (0,02 = 2%). */
+  @Prop({ type: Number, required: false, default: null })
+  contractedEngagementRate?: number | null;
+
+  /** Ex.: "Team Galaxy", "Content Creator", "Tech". */
+  @Prop({ type: String, required: false, default: null })
+  squad?: string | null;
+
+  /** Ex.: "Technology", "Camera", "Fashion". */
+  @Prop({ type: String, required: false, default: null })
+  passionPoint?: string | null;
+
+  @Prop({ type: String, required: false, default: null })
+  description?: string | null;
+
+  @Prop({ type: [ContractAmendmentSchema], required: false, default: [] })
+  amendments?: ContractAmendment[];
 }
 
 export const InfluencerContractSchema = SchemaFactory.createForClass(InfluencerContract);

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

@@ -0,0 +1,99 @@
+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

@@ -0,0 +1,83 @@
+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
+  );
+};