ad2app-lib 1.49.0 → 1.59.0

package/src/types/agency-pots.ts

@@ -0,0 +1,751 @@
+import { IsArray, IsBoolean, IsDateString, IsIn, IsInt, IsNotEmpty, IsOptional, IsString, Matches, Max, MaxLength, Min } from 'class-validator';
+
+import { AGENCY_GRANT_SCOPES, type I_AgencyGrantScope } from './agency';
+
+import type { I_CampaignCreatorIdentity, SettlementForm } from './agency-campaigns';
+
+/**
+ * Pot campaigns (spec 175 US9): the second way to pay creators on a campaign,
+ * beside the negotiated offer of US7.
+ *
+ * The agency funds ONE pot and sets a maximum per creator; each creator applies
+ * with their own guarantee and rate per 1,000 views; the agency accepts or
+ * declines, never counters (SC-018). Earnings are the guarantee plus the rate
+ * times the counted views, never above the maximum, and accrue only while the
+ * pot has unreserved money (FR-030, FR-032).
+ *
+ * Money is integer minor units plus an ISO-4217 code, everywhere. A creator
+ * never receives a pot-level figure: the only pot-level signal they get is the
+ * two-valued availability (SC-016), fenced by `creatorPotForbiddenKeys`.
+ *
+ * See specs/speckit/175-agency-roster/plan.md → US9 addendum.
+ */
+
+// ── The disclosure check (FR-040) ───────────────────────────────────────────
+
+/** A caption shows this many characters before "more"; the disclosure must sit inside them. */
+export const DISCLOSURE_VISIBLE_CHARS = 125;
+
+/**
+ * UOKiK's recommended wordings, with or without "#", with or without Polish
+ * diacritics. The list is a counsel decision (spec 175 T030) and lives here
+ * only: the upload form, the approval, the publish gate and the report all
+ * call `checkDisclosure`.
+ */
+const STRONG_WORDINGS = [
+  'reklama',
+  'materia[łl]\\s*reklamowy',
+  'wsp[óo][łl]praca\\s*reklamowa',
+  'p[łl]atna\\s*wsp[óo][łl]praca',
+  'post\\s*sponsorowany',
+];
+
+/** Tags that say something but may not be enough: flagged, never accepted silently. */
+const WEAK_TAGS = ['wsp[óo][łl]praca', 'ad', 'spons', 'promo'];
+
+/**
+ * A wording is a whole word: nothing glued after it, and nothing glued before it
+ * unless it opens with `#` (a tag glued to the word before it still starts at its `#`).
+ */
+const word = (body: string): RegExp =>
+  new RegExp(`(?:#(?:${body})|(?<![\\p{L}\\p{N}_#])(?:${body}))(?![\\p{L}\\p{N}_])`, 'giu');
+const tag = (body: string): RegExp => new RegExp(`#(?:${body})(?![\\p{L}\\p{N}_])`, 'giu');
+
+const STRONG = word(STRONG_WORDINGS.join('|'));
+const WEAK = tag(WEAK_TAGS.join('|'));
+
+export const DISCLOSURE_RESULTS = ['pass', 'weak', 'missing'] as const;
+export type DisclosureResult = (typeof DISCLOSURE_RESULTS)[number];
+
+export interface I_DisclosureCheck {
+  /**
+   * `pass`: a recommended wording within the first 125 characters.
+   * `weak`: only a bare tag, or a recommended wording placed past the fold.
+   * `missing`: nothing.
+   */
+  result: DisclosureResult;
+  /** The text that was found, as written. */
+  found: string | null;
+  /** Its character index in the caption. */
+  at: number | null;
+}
+
+export const checkDisclosure = (raw: string): I_DisclosureCheck => {
+  // Composed form, so a decomposed "ł"/"ó" (pasted from some keyboards) reads as one letter.
+  const caption = raw.normalize('NFC');
+  const strong = [...caption.matchAll(STRONG)][0];
+  if (strong && strong.index !== undefined) {
+    return {
+      result: strong.index < DISCLOSURE_VISIBLE_CHARS ? 'pass' : 'weak',
+      found: strong[0],
+      at: strong.index,
+    };
+  }
+  const weak = [...caption.matchAll(WEAK)][0];
+  if (weak && weak.index !== undefined) return { result: 'weak', found: weak[0], at: weak.index };
+  return { result: 'missing', found: null, at: null };
+};
+
+// ── Earnings (FR-030, FR-032, FR-035) ───────────────────────────────────────
+
+/** The per-view part for `views`: rate × views / 1000, rounded DOWN to the minor unit. Exact for any size. */
+export const potBonusMinor = (ratePer1000Minor: number, views: number): number =>
+  Number((BigInt(wholeOrZero(ratePer1000Minor)) * BigInt(wholeOrZero(views))) / 1000n);
+
+/** A non-negative whole number; anything else (NaN, Infinity, negative) is 0. */
+function wholeOrZero(n: number): number {
+  return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+
+export interface I_PotEarningsInput {
+  guaranteeMinor: number;
+  ratePer1000Minor: number;
+  views: number;
+  maxMinor: number;
+}
+
+/** What a creator's terms earn at `views` with an unlimited pot: never above the maximum. */
+export const potEarnings = ({ guaranteeMinor, ratePer1000Minor, views, maxMinor }: I_PotEarningsInput): number =>
+  Math.min(maxMinor, guaranteeMinor + potBonusMinor(ratePer1000Minor, views));
+
+/** The exact view count at which the terms reach the maximum (rounded up), or null when they never do. */
+export const potViewsAtMax = ({ guaranteeMinor, ratePer1000Minor, maxMinor }: Omit<I_PotEarningsInput, 'views'>): number | null => {
+  const left = maxMinor - guaranteeMinor;
+  if (left <= 0) return 0;
+  const rate = BigInt(wholeOrZero(ratePer1000Minor));
+  if (rate === 0n) return null;
+  const numerator = BigInt(Math.trunc(left)) * 1000n;
+  return Number((numerator + rate - 1n) / rate);
+};
+
+/** Cost per 1,000 views in minor units, rounded half up; null without views. */
+export const potCostPer1000Minor = (costMinor: number, views: number): number | null => {
+  const v = wholeOrZero(views);
+  return v > 0 ? Number((BigInt(wholeOrZero(costMinor)) * 2000n + BigInt(v)) / (2n * BigInt(v))) : null;
+};
+
+/**
+ * The currencies a pot may be kept in: every amount is in minor units of two
+ * decimals (grosz, cents), so a zero- or three-decimal currency (JPY, KWD) is
+ * refused rather than shown a hundred times off (review 2026-10-06 L14).
+ */
+export const POT_CURRENCIES = ['PLN', 'EUR', 'USD', 'GBP', 'CHF', 'CZK', 'SEK', 'NOK', 'DKK'] as const;
+export type PotCurrency = (typeof POT_CURRENCIES)[number];
+
+// ── The creator's fence (SC-016) ────────────────────────────────────────────
+
+/** Any key carrying a pot-level figure. A creator-facing response must have none, at any depth. */
+export const CREATOR_POT_FORBIDDEN_KEY = /budget|remainder|reserved|funded|goal|covered|commitment|acceptedCreators|earned|blended|resultViews|heldViews|countedViews/i;
+
+/** The paths of every forbidden key in `value`; empty when the response is clean. */
+export const creatorPotForbiddenKeys = (value: unknown, path = ''): string[] => {
+  if (value === null || typeof value !== 'object') return [];
+  return Object.entries(value as Record<string, unknown>).flatMap(([key, child]) => {
+    const at = path ? `${path}.${key}` : key;
+    return [...(CREATOR_POT_FORBIDDEN_KEY.test(key) ? [at] : []), ...creatorPotForbiddenKeys(child, at)];
+  });
+};
+
+// ── States ───────────────────────────────────────────────────────────────────
+
+/**
+ * An entry is one creator's application on one pot.
+ *   applied → accepted | declined | withdrawn;  accepted → released (left or
+ *   removed before publication).
+ */
+export const POT_ENTRY_STATES = ['applied', 'accepted', 'declined', 'withdrawn', 'released'] as const;
+export type PotEntryState = (typeof POT_ENTRY_STATES)[number];
+
+/**
+ * The pot board's columns, in order (design A2): invitation sent, application,
+ * in the campaign, material in, scheduled, bonus counting, bonus final, done
+ * (the keep-up period ended with the post still up).
+ */
+export const POT_STEPS = ['invited', 'applied', 'accepted', 'material_in', 'scheduled', 'counting', 'final', 'done'] as const;
+export type PotStep = (typeof POT_STEPS)[number];
+
+/** Rows off the board, kept in the table with their date. */
+export type PotOffBoard = 'declined' | 'withdrawn' | 'released' | 'left' | 'removed' | 'broken';
+
+export const POT_AVAILABILITY = ['full_max_available', 'filling_up'] as const;
+export type PotAvailability = (typeof POT_AVAILABILITY)[number];
+
+/** Why a bonus is held (FR-037): the jump against the creator's own history, or paid delivery ad2app did not start. */
+export const POT_HOLD_REASONS = ['jump', 'paid_delivery'] as const;
+export type PotHoldReason = (typeof POT_HOLD_REASONS)[number];
+
+/** The agency's three acts on a held bonus. `message` records the act; the thread opens on the client. */
+export const POT_HOLD_ACTIONS = ['approve', 'cap', 'message'] as const;
+export type PotHoldAction = (typeof POT_HOLD_ACTIONS)[number];
+
+/** The keep-up check's outcome (FR-032): still up, or taken down before the end. */
+export type PotKeepUpOutcome = 'kept' | 'broken';
+
+/**
+ * A post taken down after the bonus window but before the keep-up end: the
+ * agency is informed and decides whether the guarantee stays earned (FR-032).
+ * Before the window ends the guarantee is not earned, with no decision.
+ */
+export const POT_REMOVAL_DECISIONS = ['keep_base', 'withhold_base'] as const;
+export type PotRemovalDecision = (typeof POT_REMOVAL_DECISIONS)[number];
+
+/** Refusal codes the frontend owes its own copy for. */
+export const AGENCY_POT_CODES = {
+  /** Accepting would reserve more than the pot has unreserved. */
+  POT_CANNOT_COVER: 'agency-pot-cannot-cover',
+  /** The guarantee must be below the maximum per creator. */
+  GUARANTEE_TOO_HIGH: 'agency-pot-guarantee-too-high',
+  /** Applications closed at the application deadline, or the pot was moved. */
+  APPLICATIONS_CLOSED: 'agency-pot-applications-closed',
+  /** The kind is fixed once a creator is invited; the terms once an entry is accepted. */
+  POT_LOCKED: 'agency-pot-locked',
+  /** A refill above the maximum budget. */
+  ABOVE_MAX_BUDGET: 'agency-pot-above-max-budget',
+  /** The caption fails the disclosure check (FR-040). */
+  DISCLOSURE_REQUIRED: 'agency-pot-disclosure-required',
+  /** The creator has not connected the platform the post goes to. */
+  NO_ACCOUNT: 'agency-pot-no-account',
+  /** The confirmed time is not the one on the row now (the agency moved it meanwhile). */
+  PUBLISH_TIME_CHANGED: 'agency-pot-publish-time-changed',
+} as const;
+export type AgencyPotCode = (typeof AGENCY_POT_CODES)[keyof typeof AGENCY_POT_CODES];
+
+// ── Shared shapes ───────────────────────────────────────────────────────────
+
+export interface I_PotTerms {
+  guaranteeMinor: number;
+  ratePer1000Minor: number;
+}
+
+/**
+ * Set once by the agency, pre-filled for the creator (FR-040). A field the
+ * platform does not support is dropped at publish (research/us9/publishing-fields.md).
+ */
+export interface I_PotPublishingSettings {
+  /** Instagram "Paid partnership", TikTok "Branded content", X "Paid partnership". */
+  paidPartnershipLabel: boolean;
+  /** The brand tagged as sponsor on Instagram. */
+  sponsorHandle: string | null;
+  /** A Collab invite to the brand's Instagram account. */
+  collabHandle: string | null;
+  /** A link or a discount code, posted as the first comment. */
+  firstComment: string | null;
+  commentsEnabled: boolean;
+}
+
+/** The dates on the timeline (FR-036). Bonus and keep-up ends derive from publication due; never set by hand. */
+export interface I_PotSchedule {
+  materialsDueAt: string | null;
+  publicationDueAt: string | null;
+  bonusEndsAt: string | null;
+  keepUpEndsAt: string | null;
+}
+
+// ── The agency's side ───────────────────────────────────────────────────────
+
+/** The pot's parts. approvedBonus + heldBonus + reservedGuarantees + unreserved = funded, always. */
+export interface I_AgencyPotParts {
+  fundedMinor: number;
+  /** Accepted creators' guarantees, published or not. */
+  reservedGuaranteesMinor: number;
+  /** Per-view bonus accrued and payable. */
+  approvedBonusMinor: number;
+  /** Per-view bonus accrued and held under FR-037: committed, not payable, out of the cost figures. */
+  heldBonusMinor: number;
+  unreservedMinor: number;
+}
+
+export interface I_AgencyPotView {
+  currency: string;
+  maxBudgetMinor: number;
+  maxPerCreatorMinor: number;
+  bonusWindowDays: number;
+  keepUpMonths: number;
+  goalViews: number | null;
+  coverUrl: string | null;
+  applicationDeadlineAt: string | null;
+  /** Set when the remainder was moved into another campaign: closed to new applications. */
+  movedTo: { campaignId: string; name: string } | null;
+  publishing: I_PotPublishingSettings;
+  schedule: I_PotSchedule;
+  parts: I_AgencyPotParts;
+  /** floor(funded / max per creator). */
+  creatorsCoveredAtFullMax: number;
+  /** Accepted creators × the maximum: what the pot could owe if every one reached it. */
+  maxCommitmentMinor: number;
+  /** Published creators' guarantees plus approved bonus. */
+  earnedMinor: number;
+  /** Raw readings summed over every row: the totals row. */
+  views: number;
+  /** The goal's progress: raw readings of posts whose bonus is not under review, as the client report counts them (FR-037). */
+  resultViews: number;
+  /** Raw readings of posts whose bonus is under review, named beside the goal and left out of it. */
+  heldViews: number;
+  /** Views the bonus counts toward (capped under FR-037): the cost basis. */
+  countedViews: number;
+  /** Blended cost per 1,000 views over published, unheld rows; null with no views. */
+  blendedCostPer1000Minor: number | null;
+  /** The latest count across the pot; every export is stamped with it. */
+  lastCountAt: string | null;
+}
+
+/** The FR-037 evidence, in numbers. */
+export interface I_PotHoldEvidence {
+  reason: PotHoldReason;
+  medianViews: number | null;
+  /** views / median, two decimals. */
+  viewsVsMedian: number | null;
+  /** Engagement per view now and usually, as fractions. */
+  engagementNow: number | null;
+  engagementUsual: number | null;
+  jumpViews: number | null;
+  jumpDays: number | null;
+}
+
+export interface I_PotHold {
+  heldAt: string;
+  evidence: I_PotHoldEvidence;
+  /** null while it waits on the agency. */
+  decision: 'approved' | 'capped' | null;
+  decidedAt: string | null;
+  /** With `capped`: the views the bonus counts to (2 × median). */
+  capViews: number | null;
+  /** What `cap` would leave as bonus, for the button. */
+  cappedBonusMinor: number | null;
+}
+
+/** Zernio refused the post when ad2app scheduled it: the confirmation is cleared and the creator confirms again. */
+export interface I_PotPublishRefusal {
+  at: string;
+  /** The provider's words, per platform (`tiktok: …; instagram: …`). */
+  reason: string;
+}
+
+/** One creator's row in the pot table (FR-035). Every total equals the sum of its rows. */
+export interface I_AgencyPotRow {
+  memberId: string;
+  entryId: string | null;
+  creator: I_CampaignCreatorIdentity;
+  step: PotStep | PotOffBoard;
+  stepAt: string;
+  terms: I_PotTerms | null;
+  /** The latest reading; null before publication. */
+  views: number | null;
+  /** Views the bonus counts toward: `views`, stopped at the FR-037 cap when the agency set one. */
+  countedViews: number | null;
+  guaranteeReservedMinor: number;
+  /** Earned so far: the guarantee once published plus approved bonus. */
+  earnedMinor: number;
+  heldBonusMinor: number;
+  /** earned / max, as a fraction; null before publication. */
+  shareOfMax: number | null;
+  costPer1000Minor: number | null;
+  settlementForm: SettlementForm | null;
+  publishAt: string | null;
+  publishConfirmedAt: string | null;
+  publishedAt: string | null;
+  postUrl: string | null;
+  bonusEndsAt: string | null;
+  keepUpEndsAt: string | null;
+  frozen: boolean;
+  /** `needsDecision`: taken down after the bonus window, waiting on the agency's keep-or-withhold (FR-032). */
+  outcome: { kind: PotKeepUpOutcome; lastFoundAt: string | null; decision: PotRemovalDecision | null; needsDecision: boolean } | null;
+  hold: I_PotHold | null;
+  lastCountAt: string | null;
+  /** The provider refused the post at scheduling, since the time was last set or confirmed; null otherwise. */
+  publishRefusal?: I_PotPublishRefusal | null;
+}
+
+export interface I_AgencyPotTotals {
+  acceptedCreators: number;
+  reservedGuaranteesMinor: number;
+  views: number;
+  countedViews: number;
+  earnedMinor: number;
+  blendedCostPer1000Minor: number | null;
+}
+
+/** `GET /agency/campaigns/:id/pot/board` (FR-035). */
+export interface I_AgencyPotBoard {
+  pot: I_AgencyPotView;
+  rows: I_AgencyPotRow[];
+  totals: I_AgencyPotTotals;
+  /** Creators per board column. */
+  steps: Record<PotStep, number>;
+}
+
+/** The creator's statistics an application shows, from what they shared (FR-035). */
+export interface I_PotCreatorProfile {
+  platforms: Array<{ platform: string; followers: number | null }>;
+  medianViews: number | null;
+  meanViews: number | null;
+  p25Views: number | null;
+  p75Views: number | null;
+  /** Interactions per view over 90 days, as a fraction. */
+  engagement: number | null;
+  posts90: number;
+  recent: Array<{ postedAt: string; views: number | null; url: string | null; thumbnailUrl: string | null }>;
+}
+
+export type PotScenario = 'none' | 'p25' | 'median' | 'p75' | 'max';
+
+/** `GET /agency/campaigns/:id/pot/entries/:entryId` while it is an application. */
+export interface I_PotApplicationView {
+  entryId: string;
+  memberId: string;
+  creator: I_CampaignCreatorIdentity;
+  terms: I_PotTerms;
+  appliedAt: string;
+  /**
+   * `shared`: the profile is filled. `not_shared`: no active grant with the
+   * analytics scope, said in words. `unavailable`: the read failed just now;
+   * never shown as zeros.
+   */
+  profileState: 'shared' | 'not_shared' | 'unavailable';
+  /** Set only when `profileState` is `shared`. */
+  profile: I_PotCreatorProfile | null;
+  viewsAtMax: number | null;
+  scenarios: Array<{ scenario: PotScenario; views: number | null; costMinor: number | null; costPer1000Minor: number | null }>;
+  blendedCostPer1000Minor: number | null;
+  unreservedBeforeMinor: number;
+  unreservedAfterMinor: number;
+  /** False when the pot cannot cover the guarantee: accept is refused with POT_CANNOT_COVER. */
+  canAccept: boolean;
+}
+
+// ── The creator's side (SC-016: nothing pot-level) ──────────────────────────
+
+export interface I_CreatorPotEarnings {
+  guaranteeMinor: number;
+  /** Payable per-view bonus. */
+  bonusMinor: number;
+  /** Bonus under review (FR-037): shown with the amount, never as an accusation. */
+  heldBonusMinor: number;
+  totalMinor: number;
+  views: number;
+  lastCountAt: string | null;
+  frozen: boolean;
+}
+
+export interface I_CreatorPotEntry {
+  state: PotEntryState;
+  terms: I_PotTerms;
+  appliedAt: string;
+  decidedAt: string | null;
+  publishAt: string | null;
+  publishConfirmedAt: string | null;
+  publishedAt: string | null;
+  postUrl: string | null;
+  bonusEndsAt: string | null;
+  keepUpEndsAt: string | null;
+  outcome: PotKeepUpOutcome | null;
+  /** True once the keep-up period ended with the post still up. */
+  mayTakeDown: boolean;
+  /**
+   * A post taken down before the keep-up end (FR-032): inside the bonus window
+   * the guarantee is lost; after it the agency decides, then keeps or returns it.
+   */
+  removal: 'guarantee_lost' | 'agency_deciding' | 'guarantee_kept' | 'guarantee_returned' | null;
+  /** null before publication. */
+  earnings: I_CreatorPotEarnings | null;
+  /** The provider refused the post at scheduling, since the time was last set or confirmed; null otherwise. */
+  publishRefusal?: I_PotPublishRefusal | null;
+}
+
+/** Attached to `I_CreatorCampaignView.pot` on a pot campaign. */
+export interface I_CreatorPotView {
+  campaignId: string;
+  currency: string;
+  maxPerCreatorMinor: number;
+  bonusWindowDays: number;
+  keepUpMonths: number;
+  coverUrl: string | null;
+  applicationDeadlineAt: string | null;
+  availability: PotAvailability;
+  /** The maximum in the creator's preferred currency, approximate; null with no rate for the day. */
+  approx: { currency: string; maxPerCreatorMinor: number; rateDate: string } | null;
+  schedule: I_PotSchedule;
+  publishing: I_PotPublishingSettings;
+  entry: I_CreatorPotEntry | null;
+  canApply: boolean;
+  canWithdraw: boolean;
+  canConfirmPublishAt: boolean;
+  /** The creator's own 90-day median views from their shared statistics, for the application estimate; null when unknown. */
+  medianViews: number | null;
+}
+
+// ── The client report (FR-038) ──────────────────────────────────────────────
+
+/** One published post in the brand's report. Costs ride along; the page shows them only when the agency ticks them. */
+export interface I_PotReportPost {
+  memberId: string;
+  creator: I_CampaignCreatorIdentity;
+  platform: string | null;
+  publishedAt: string;
+  postUrl: string | null;
+  thumbnailUrl: string | null;
+  caption: string | null;
+  disclosure: I_DisclosureCheck | null;
+  /** Whether the platform's paid-partnership label went out (null: not asked for). */
+  labelApplied: boolean | null;
+  /** A durable ad2app link that opens a fresh signed read of the approved material on every open; null when none. */
+  materialLink: string | null;
+  views: number;
+  likes: number | null;
+  comments: number | null;
+  shares: number | null;
+  saves: number | null;
+  followers: number | null;
+  /** The creator's own 90-day median, when known: each post is judged against its creator. */
+  medianViews: number | null;
+  /** Views by day since publication, as counted (the latest reading of each day). */
+  daily: Array<{ day: string; views: number }>;
+  /** A bonus under review (FR-037): left out of the sums and named as such. */
+  held: boolean;
+  publishedOnTime: boolean | null;
+  keepUpEndsAt: string | null;
+  versions: number;
+  revisionRounds: number;
+  /** The most-liked comments, text and likes only; null when the creator does not share comments. */
+  topComments: Array<{ text: string; likes: number }> | null;
+  earnedMinor: number;
+}
+
+/** `GET /agency/campaigns/:id/pot/report`. */
+export interface I_PotClientReport {
+  campaign: { id: string; name: string; organizationName: string; brief: string };
+  currency: string;
+  goalViews: number | null;
+  publicationDueAt: string | null;
+  /** When the bonus window of the campaign closes (publication due + the window): the pacing projection runs to it. */
+  campaignEndsAt: string | null;
+  keepUpMonths: number;
+  generatedAt: string;
+  lastCountAt: string | null;
+  posts: I_PotReportPost[];
+  /** What the published, unheld posts cost: shown only when the agency includes costs. */
+  totalCostMinor: number;
+}
+
+// ── Files (FR-039) ──────────────────────────────────────────────────────────
+
+export interface I_CampaignFile {
+  id: string;
+  fileName: string;
+  contentType: string;
+  sizeBytes: number;
+  uploadedAt: string;
+  uploadedBy: string;
+}
+
+/** PDF, images, video, office documents and archives; no HTML or SVG (opened in the browser). */
+export const CAMPAIGN_FILE_CONTENT_TYPE =
+  /^(application\/pdf|image\/(png|jpeg|gif|webp|heic|heif|avif)|video\/[A-Za-z0-9.+-]+|application\/(msword|vnd\.openxmlformats-officedocument\.[a-z.]+|vnd\.ms-(excel|powerpoint)|vnd\.oasis\.opendocument\.[a-z.]+|rtf|zip|x-zip-compressed|x-7z-compressed|x-rar-compressed|vnd\.rar|gzip|x-tar)|text\/(plain|csv))$/;
+export const CAMPAIGN_FILE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+
+// ── Bodies ───────────────────────────────────────────────────────────────────
+
+const MONEY_MAX = 100_000_000_000;
+
+/**
+ * `POST /agency/campaign-invitations/:memberId/application` — the creator's own
+ * terms. Applying from an invitation also joins the campaign, answering any
+ * access request folded into it with `scopes` (absent = everything asked).
+ */
+export class ApplyToPotDto {
+  @IsInt()
+  @Min(0)
+  @Max(MONEY_MAX)
+  guaranteeMinor: number;
+
+  @IsInt()
+  @Min(0)
+  @Max(MONEY_MAX)
+  ratePer1000Minor: number;
+
+  @IsOptional()
+  @IsArray()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes?: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<ApplyToPotDto>) {
+    this.guaranteeMinor = data?.guaranteeMinor ?? 0;
+    this.ratePer1000Minor = data?.ratePer1000Minor ?? 0;
+    this.scopes = data?.scopes;
+  }
+}
+
+/** `POST /agency/campaigns/:id/pot/refill` — up to the maximum budget. */
+export class RefillPotDto {
+  @IsInt()
+  @Min(1)
+  @Max(MONEY_MAX)
+  amountMinor: number;
+
+  constructor(data?: Partial<RefillPotDto>) {
+    this.amountMinor = data?.amountMinor ?? 0;
+  }
+}
+
+/** `PATCH /agency/campaigns/:id/pot/application-deadline`. */
+export class MovePotDeadlineDto {
+  @IsDateString()
+  applicationDeadlineAt: string;
+
+  constructor(data?: Partial<MovePotDeadlineDto>) {
+    this.applicationDeadlineAt = data?.applicationDeadlineAt ?? '';
+  }
+}
+
+/** The agency sets the time agreed with the brand; the creator confirms that same value. */
+export class PotPublishAtDto {
+  @IsDateString()
+  publishAt: string;
+
+  constructor(data?: Partial<PotPublishAtDto>) {
+    this.publishAt = data?.publishAt ?? '';
+  }
+}
+
+export class PotHoldActDto {
+  @IsIn(POT_HOLD_ACTIONS as unknown as string[])
+  action: PotHoldAction;
+
+  constructor(data?: Partial<PotHoldActDto>) {
+    this.action = data?.action ?? 'approve';
+  }
+}
+
+/** `POST /agency/campaigns/:id/pot/entries/:entryId/removal` — the agency's decision on a late takedown (FR-032). */
+export class PotRemovalDecisionDto {
+  @IsIn(POT_REMOVAL_DECISIONS as unknown as string[])
+  decision: PotRemovalDecision;
+
+  constructor(data?: Partial<PotRemovalDecisionDto>) {
+    this.decision = data?.decision ?? 'keep_base';
+  }
+}
+
+/** The caption is the creator's until publication (FR-032). */
+export class UpdateMaterialCaptionDto {
+  @IsString()
+  @MaxLength(2200)
+  caption: string;
+
+  constructor(data?: Partial<UpdateMaterialCaptionDto>) {
+    this.caption = data?.caption ?? '';
+  }
+}
+
+export class PrepareCampaignFileUploadDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  fileName: string;
+
+  @IsString()
+  @Matches(CAMPAIGN_FILE_CONTENT_TYPE)
+  contentType: string;
+
+  @IsInt()
+  @Min(1)
+  @Max(CAMPAIGN_FILE_MAX_BYTES)
+  sizeBytes: number;
+
+  constructor(data?: Partial<PrepareCampaignFileUploadDto>) {
+    this.fileName = data?.fileName ?? '';
+    this.contentType = data?.contentType ?? '';
+    this.sizeBytes = data?.sizeBytes ?? 0;
+  }
+}
+
+/** The pot's fields on campaign create (and on a move); flat for the reason given in agency-campaigns.ts. */
+export class PotFields {
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(MONEY_MAX)
+  potBudgetMinor?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(MONEY_MAX)
+  potMaxBudgetMinor?: number;
+
+  /**
+   * The maximum one creator can earn, guarantee included. Named "cap" on the
+   * wire: a body field matching /creator|user/ reads as a person id to the
+   * agency boundary scan (backend agency-grant-never-opens-inbox.spec.ts).
+   */
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(MONEY_MAX)
+  potCapMinor?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(365)
+  potBonusWindowDays?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(60)
+  potKeepUpMonths?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(100_000_000_000)
+  potGoalViews?: number | null;
+
+  @IsOptional()
+  @IsIn(POT_CURRENCIES as unknown as string[])
+  potCurrency?: string;
+
+  @IsOptional()
+  @IsDateString()
+  potApplicationDeadlineAt?: string | null;
+
+  @IsOptional()
+  @IsBoolean()
+  potPaidPartnershipLabel?: boolean;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^@?[A-Za-z0-9._]{1,64}$/)
+  potSponsorHandle?: string | null;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^@?[A-Za-z0-9._]{1,64}$/)
+  potCollabHandle?: string | null;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2200)
+  potFirstComment?: string | null;
+
+  @IsOptional()
+  @IsBoolean()
+  potCommentsEnabled?: boolean;
+
+  protected assignPot(data?: Partial<PotFields>): void {
+    this.potBudgetMinor = data?.potBudgetMinor;
+    this.potMaxBudgetMinor = data?.potMaxBudgetMinor;
+    this.potCapMinor = data?.potCapMinor;
+    this.potBonusWindowDays = data?.potBonusWindowDays;
+    this.potKeepUpMonths = data?.potKeepUpMonths;
+    this.potGoalViews = data?.potGoalViews;
+    this.potCurrency = data?.potCurrency;
+    this.potApplicationDeadlineAt = data?.potApplicationDeadlineAt;
+    this.potPaidPartnershipLabel = data?.potPaidPartnershipLabel;
+    this.potSponsorHandle = data?.potSponsorHandle;
+    this.potCollabHandle = data?.potCollabHandle;
+    this.potFirstComment = data?.potFirstComment;
+    this.potCommentsEnabled = data?.potCommentsEnabled;
+  }
+}