ad2app-lib 1.47.0 → 1.50.0

package/src/types/agency-campaigns.ts

@@ -0,0 +1,739 @@
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsBoolean,
+  IsDateString,
+  IsIn,
+  IsInt,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Matches,
+  Max,
+  MaxLength,
+  Min,
+} from 'class-validator';
+
+import { I_MediaStage } from './I_Media';
+import { I_OfferStatus } from './I_Offer';
+import { AGENCY_GRANT_SCOPES, type I_AgencyGrantScope } from './agency';
+import { PotFields, type I_AgencyPotView, type I_CampaignFile, type I_CreatorPotView, type I_DisclosureCheck } from './agency-pots';
+
+/**
+ * The campaign loop (spec 175 US7) — an organization runs a campaign with the
+ * creators on its roster or in the directory.
+ *
+ * Two steps, never one (Jan, 2026-09-28):
+ *
+ *   1. MEMBERSHIP — the agency invites a creator; the creator joins or
+ *      declines. Joining answers any access request folded into the
+ *      invitation. No money is named here.
+ *   2. OFFER — once joined, the agency sends a rate. It is countered, accepted,
+ *      confirmed or rejected; a creator who leaves withdraws it.
+ *
+ * The server owns every transition. Each view carries `availableActions`, and
+ * a screen renders exactly those acts — it never derives them from a status,
+ * so the two can never disagree.
+ *
+ * See specs/speckit/175-agency-roster/contracts/agency-api.md → US7.
+ */
+
+// ── The ONE placements list (FR-025) ────────────────────────────────────────
+
+/**
+ * What a deliverable may be, per platform. A named list in one place, so a
+ * "placement" can never be free text that drifts per campaign.
+ */
+export const CAMPAIGN_PLACEMENTS = {
+  instagram: ['reel', 'post', 'carousel', 'stories', 'collab_post'],
+  tiktok: ['video', 'repost', 'duet', 'stories'],
+  youtube: ['video', 'short', 'integration', 'community_post'],
+  facebook: ['post', 'reel', 'stories'],
+  linkedin: ['post', 'article'],
+} as const;
+
+export type CampaignPlatform = keyof typeof CAMPAIGN_PLACEMENTS;
+export type CampaignPlacement = (typeof CAMPAIGN_PLACEMENTS)[CampaignPlatform][number];
+
+export const CAMPAIGN_PLATFORMS = Object.keys(CAMPAIGN_PLACEMENTS) as CampaignPlatform[];
+
+export const isCampaignPlacement = (platform: string, placement: string): boolean =>
+  Object.prototype.hasOwnProperty.call(CAMPAIGN_PLACEMENTS, platform) &&
+  (CAMPAIGN_PLACEMENTS[platform as CampaignPlatform] as readonly string[]).includes(placement);
+
+// ── The settlement form (FR-027) ─────────────────────────────────────────────
+
+/** The creator's own setting. The agency reads it and can never set it. */
+export const SETTLEMENT_FORMS = ['invoice', 'contract', 'barter'] as const;
+export type SettlementForm = (typeof SETTLEMENT_FORMS)[number];
+
+// ── States ───────────────────────────────────────────────────────────────────
+
+/**
+ * An offer campaign negotiates one price per creator (US7); a pot campaign pays
+ * from one pot on each creator's own terms (US9). Chosen at creation, fixed once
+ * the first creator is invited (FR-030).
+ */
+export const AGENCY_CAMPAIGN_KINDS = ['offer', 'pot'] as const;
+export type AgencyCampaignKind = (typeof AGENCY_CAMPAIGN_KINDS)[number];
+
+export const AGENCY_CAMPAIGN_MEMBER_STATES = ['invited', 'joined', 'declined', 'left', 'removed'] as const;
+export type AgencyCampaignMemberState = (typeof AGENCY_CAMPAIGN_MEMBER_STATES)[number];
+
+/** The offer statuses the agency loop writes. `draft`, `deleted` and `alternativeSuggested` are legacy-only. */
+export const AGENCY_OFFER_STATUSES = [
+  I_OfferStatus.SENT,
+  I_OfferStatus.INFLUENCER_NEGOTIATED,
+  I_OfferStatus.AGENCY_NEGOTIATED,
+  I_OfferStatus.ACCEPTED,
+  I_OfferStatus.CONFIRMED,
+  I_OfferStatus.REJECTED,
+  I_OfferStatus.WITHDRAWN,
+] as const;
+export type AgencyOfferStatus = (typeof AGENCY_OFFER_STATUSES)[number];
+
+export type CampaignSide = 'agency' | 'creator';
+
+/**
+ * Every act on an offer, by either side. Which of them a given caller may take
+ * right now is the server's `availableActions`, never a client guess.
+ *
+ *   agency:  counter · confirm · reject
+ *   creator: accept · counter · reject
+ */
+export const AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject'] as const;
+export type AgencyOfferAction = (typeof AGENCY_OFFER_ACTIONS)[number];
+
+/** The agency's acts on the latest material; the creator's only act is to upload. */
+export const AGENCY_MATERIAL_ACTIONS = ['approve', 'request_changes', 'reject'] as const;
+export type AgencyMaterialAction = (typeof AGENCY_MATERIAL_ACTIONS)[number];
+
+/**
+ * The board's columns, in order (FR-024). A creator stands in exactly one.
+ * `declined`, `left`, `removed` and `rejected` are OFF the board: those rows
+ * stay in the list with their date (US7 scenario 9), never in a column.
+ */
+export const AGENCY_CAMPAIGN_STEPS = [
+  'invited',
+  'joined',
+  'offer_sent',
+  'negotiating',
+  'confirmed',
+  'material_in',
+  'approved',
+  'published',
+] as const;
+export type AgencyCampaignStep = (typeof AGENCY_CAMPAIGN_STEPS)[number];
+
+export type AgencyCampaignOffBoard = 'declined' | 'left' | 'removed' | 'rejected';
+
+export const AGENCY_MILESTONE_KINDS = ['draft_due', 'live_by', 'custom'] as const;
+export type AgencyMilestoneKind = (typeof AGENCY_MILESTONE_KINDS)[number];
+
+/** A milestone may wait on one rule: every ACTIVE offer at a status, or every active creator's latest material at a stage. */
+export const AGENCY_MILESTONE_OFFER_RULES = [I_OfferStatus.CONFIRMED] as const;
+export const AGENCY_MILESTONE_MEDIA_RULES = [I_MediaStage.UPLOADED, I_MediaStage.ACCEPTED] as const;
+
+export const AGENCY_CAMPAIGN_EVENT_KINDS = [
+  'invited',
+  'joined',
+  'declined',
+  'left',
+  'removed',
+  'offer_sent',
+  'offer_countered',
+  'offer_accepted',
+  'offer_confirmed',
+  'offer_rejected',
+  'offer_withdrawn',
+  'material_uploaded',
+  'material_approved',
+  'material_changes_asked',
+  'material_rejected',
+  'published',
+  'milestone_confirmed',
+  // US9: the pot. Every money act carries its amount (FR-021, FR-033).
+  'pot_applied',
+  'pot_application_withdrawn',
+  'pot_accepted',
+  'pot_declined',
+  'pot_released',
+  'pot_refilled',
+  'pot_moved',
+  'pot_deadline_moved',
+  'pot_publish_time_set',
+  'pot_publish_time_confirmed',
+  /** Zernio refused the post at scheduling; `note` carries its reason. */
+  'pot_publish_refused',
+  'pot_published',
+  'pot_counted',
+  'pot_frozen',
+  'pot_bonus_held',
+  'pot_bonus_approved',
+  'pot_bonus_capped',
+  'pot_bonus_message',
+  'pot_kept',
+  'pot_broken',
+  'pot_removal_decided',
+  'caption_edited',
+  'file_uploaded',
+  'file_removed',
+] as const;
+export type AgencyCampaignEventKind = (typeof AGENCY_CAMPAIGN_EVENT_KINDS)[number];
+
+/** Refusal codes the frontend owes its own copy for. */
+export const AGENCY_CAMPAIGN_CODES = {
+  /** The transition is not open at this state, or not for this side. */
+  TRANSITION_REFUSED: 'agency-campaign-transition-refused',
+  /** A campaign sent to a creator must carry its brief text (FR-025). */
+  BRIEF_REQUIRED: 'agency-campaign-brief-required',
+  /** A deliverable on a platform the creator has not connected (FR-025). */
+  PLATFORM_NOT_CONNECTED: 'agency-campaign-platform-not-connected',
+  /** The creator is already on this campaign. */
+  ALREADY_MEMBER: 'agency-campaign-already-member',
+  /** The upload was confirmed but no stored file exists at its path (FR-029). */
+  MATERIAL_NOT_STORED: 'agency-campaign-material-not-stored',
+  /** A demo creator cannot be invited or mailed (spec 179). */
+  DEMO_CREATOR: 'agency-campaign-demo-creator',
+} as const;
+export type AgencyCampaignCode = (typeof AGENCY_CAMPAIGN_CODES)[keyof typeof AGENCY_CAMPAIGN_CODES];
+
+// ── Views ────────────────────────────────────────────────────────────────────
+
+export interface I_CampaignDeliverable {
+  platform: CampaignPlatform;
+  placement: CampaignPlacement;
+  qty: number;
+  note?: string;
+}
+
+export interface I_AgencyCampaignBrief {
+  /** The concept, in prose. May be empty only while the campaign is a draft. */
+  text: string;
+  deliverables: I_CampaignDeliverable[];
+  /** ISO dates, or null when not set. */
+  draftDueAt: string | null;
+  liveByAt: string | null;
+  /** Usage rights on the brand's profiles, in months. */
+  licenceMonths: number | null;
+  /** Paid promotion (whitelisting), in months. */
+  paidPromoMonths: number | null;
+  revisionRounds: number | null;
+}
+
+/** Money is integer minor units plus an ISO-4217 code; the legacy float `price` is never written. */
+export interface I_Money {
+  minor: number;
+  currency: string;
+}
+
+export interface I_AgencyOfferView {
+  id: string;
+  status: AgencyOfferStatus;
+  /** The price on the table now: the latest one either side named. */
+  price: I_Money;
+  /** Whose move it is; null once the offer is settled. */
+  turn: CampaignSide | null;
+  /** The acts open to the CALLER'S side, right now. */
+  availableActions: AgencyOfferAction[];
+  sentAt: string;
+  updatedAt: string;
+}
+
+export interface I_AgencyMaterial {
+  id: string;
+  fileName: string;
+  contentType: string;
+  sizeBytes: number | null;
+  stage: I_MediaStage;
+  uploadedAt: string;
+  /** The note sent with a change request or a rejection of THIS version. */
+  note: string | null;
+  /** The post's caption, uploaded with the material (US9, FR-032); the creator may edit it until publication. Optional: 1.49 backends omit it. */
+  caption?: string | null;
+  /** `checkDisclosure(caption)`, returned with every read (FR-040); null without a caption. Optional: 1.49 backends omit it. */
+  disclosure?: I_DisclosureCheck | null;
+}
+
+export interface I_AgencyMilestone {
+  id: string;
+  kind: AgencyMilestoneKind;
+  /** Only for `custom`; the others are named by i18n from `kind`. */
+  label: string | null;
+  dueAt: string | null;
+  /** Null = campaign-wide. */
+  creatorUserId: string | null;
+  offerRule: (typeof AGENCY_MILESTONE_OFFER_RULES)[number] | null;
+  mediaRule: (typeof AGENCY_MILESTONE_MEDIA_RULES)[number] | null;
+  readyToConfirm: boolean;
+  confirmedAt: string | null;
+}
+
+export interface I_AgencyCampaignEvent {
+  kind: AgencyCampaignEventKind;
+  side: CampaignSide;
+  /** Done by ad2app itself (the daily pot job), not by a person on that side. */
+  byAd2app?: true;
+  at: string;
+  price?: I_Money;
+  /** A pot act's amount: a refill, a move, a reserved guarantee, an accrued bonus. */
+  amount?: I_Money;
+  note?: string;
+}
+
+export interface I_CampaignCreatorIdentity {
+  userId: string | null;
+  handle: string;
+  displayName?: string;
+  avatarUrl?: string;
+}
+
+/** One creator's row on the campaign screen (the list twin of the board). */
+export interface I_AgencyCampaignMemberRow {
+  memberId: string;
+  creator: I_CampaignCreatorIdentity;
+  state: AgencyCampaignMemberState;
+  /** The board column, or the reason the row is off the board. */
+  step: AgencyCampaignStep | AgencyCampaignOffBoard;
+  /** When the row reached its current step. */
+  stepAt: string;
+  offer: I_AgencyOfferView | null;
+  latestMaterial: I_AgencyMaterial | null;
+  /** The agency's acts on `latestMaterial`. */
+  materialActions: AgencyMaterialAction[];
+  /** Read from the creator's own setting (FR-027); null when they have not set it. */
+  settlementForm: SettlementForm | null;
+  nextDeadline: { at: string; kind: AgencyMilestoneKind; label: string | null } | null;
+  /** True when the agency may still remove them (no confirmed offer). */
+  removable: boolean;
+  /** True when the agency may send an offer now (joined, none sent yet). */
+  canSendOffer: boolean;
+  canMarkPublished: boolean;
+  /** Scopes a folded access request asked for, while the invitation is open. */
+  requestedScopes: I_AgencyGrantScope[];
+}
+
+export interface I_AgencyCampaignPipeline {
+  /** Creators per board column; off-board rows are not counted. */
+  steps: Record<AgencyCampaignStep, number>;
+  total: number;
+}
+
+export interface I_AgencyCampaignCard {
+  id: string;
+  name: string;
+  /** Absent from 1.49 backends: read as 'offer'. */
+  kind?: AgencyCampaignKind;
+  isDraft: boolean;
+  liveByAt: string | null;
+  draftDueAt: string | null;
+  pipeline: I_AgencyCampaignPipeline;
+  /** How many things on this campaign wait on the agency (the rail's definition). */
+  attention: number;
+  createdAt: string;
+}
+
+export interface I_AgencyCampaign {
+  id: string;
+  name: string;
+  /** Absent from 1.49 backends: read as 'offer'. */
+  kind?: AgencyCampaignKind;
+  /** Set on a pot campaign; the pot board itself is `GET /agency/campaigns/:id/pot/board`. */
+  pot?: I_AgencyPotView | null;
+  isDraft: boolean;
+  brief: I_AgencyCampaignBrief;
+  members: I_AgencyCampaignMemberRow[];
+  milestones: I_AgencyMilestone[];
+  pipeline: I_AgencyCampaignPipeline;
+  createdAt: string;
+}
+
+/** Opening one creator (FR-024): their course with dates, notes, files and milestones. */
+export interface I_AgencyCampaignCreatorDetail {
+  row: I_AgencyCampaignMemberRow;
+  creatorBrief: string | null;
+  events: I_AgencyCampaignEvent[];
+  materials: I_AgencyMaterial[];
+  milestones: I_AgencyMilestone[];
+}
+
+/** `GET /agency/campaigns/attention` — what waits on the agency (FR-022, the rail). */
+export interface I_AgencyCampaignAttention {
+  counterOffers: number;
+  materialsToReview: number;
+  milestonesReady: number;
+  /** US9: applications to answer, held bonuses to decide, and posts taken down after the bonus window. */
+  potDecisions?: number;
+  total: number;
+}
+
+/** `GET /agency/panel` (FR-022). */
+export interface I_AgencyPanel {
+  /** Open milestones of running (non-draft) campaigns due today. */
+  dueToday: number;
+  /** Open milestones of running (non-draft) campaigns past their date. */
+  overdue: number;
+  /** The roster's own "needs attention" count, or null when it could not be read: shown as a dash, never 0. */
+  needsAttention: number | null;
+  deadlines: Array<{
+    campaignId: string;
+    campaignName: string;
+    milestoneId: string;
+    kind: AgencyMilestoneKind;
+    label: string | null;
+    dueAt: string;
+    creatorHandle: string | null;
+    confirmed: boolean;
+  }>;
+  campaigns: Array<{ id: string; name: string; pipeline: I_AgencyCampaignPipeline; liveByAt: string | null }>;
+}
+
+// ── The creator's side ───────────────────────────────────────────────────────
+
+/**
+ * What a creator reads about ONE campaign they are on. Deliberately narrow
+ * (SC-014): their own membership, offer, brief, materials and deadlines — no
+ * other creator, no total, no average, no count of others.
+ */
+export interface I_CreatorCampaignView {
+  memberId: string;
+  state: AgencyCampaignMemberState;
+  organization: { id: string; name: string };
+  /** `kind` is absent from 1.49 backends: read as 'offer'. */
+  campaign: { id: string; name: string; brief: I_AgencyCampaignBrief; kind?: AgencyCampaignKind };
+  /** Set on a pot campaign: the creator's own terms, earnings and the two-valued availability, nothing pot-level (SC-016). */
+  pot?: I_CreatorPotView | null;
+  /** The agency's files for the campaign (FR-039): every one is for its creators; opened through a signed read. */
+  files?: I_CampaignFile[];
+  creatorBrief: string | null;
+  /** The access request folded into the invitation, while it is open. */
+  requestedScopes: I_AgencyGrantScope[];
+  offer: I_AgencyOfferView | null;
+  materials: I_AgencyMaterial[];
+  /** True when the creator may upload now (confirmed, and no version awaits review). */
+  canUpload: boolean;
+  /** True when the creator may leave (no confirmed offer). */
+  canLeave: boolean;
+  milestones: I_AgencyMilestone[];
+  invitedAt: string;
+}
+
+/** `GET /agency/campaign-invitations/mine` — pending invitations and live campaigns. */
+export interface I_CreatorCampaigns {
+  items: I_CreatorCampaignView[];
+  /** The creator's turn, the creator's badge: invitations to answer, offers to answer, and materials to upload (a first version, or a new one after changes were asked or a version was rejected). */
+  waitingOnYou: number;
+}
+
+export interface I_MaterialUploadTicket {
+  /** Opaque; sent back on confirm. */
+  uploadId: string;
+  /** PUT the file's bytes here with `headers`. */
+  uploadUrl: string;
+  headers: Record<string, string>;
+  expiresAt: string;
+}
+
+export interface I_SignedRead {
+  url: string;
+  expiresAt: string;
+}
+
+// ── Bodies ───────────────────────────────────────────────────────────────────
+//
+// Flat on purpose: nested bodies need class-transformer's `@Type`, and a
+// linked lib carries its own copy whose metadata the backend's ValidationPipe
+// never reads. `deliverables` is an array of plain objects checked item by
+// item in the service against CAMPAIGN_PLACEMENTS — the pair is the rule.
+
+/** The brief's fields, shared by create and update. All optional on the wire. The pot's fields ride along (US9). */
+class AgencyCampaignBriefFields extends PotFields {
+  @IsOptional()
+  @IsString()
+  @MaxLength(10000)
+  text?: string;
+
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(30)
+  deliverables?: I_CampaignDeliverable[];
+
+  @IsOptional()
+  @IsDateString()
+  draftDueAt?: string | null;
+
+  @IsOptional()
+  @IsDateString()
+  liveByAt?: string | null;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(120)
+  licenceMonths?: number | null;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(120)
+  paidPromoMonths?: number | null;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(20)
+  revisionRounds?: number | null;
+
+  protected assignBrief(data?: Partial<AgencyCampaignBriefFields>): void {
+    this.assignPot(data);
+    this.text = data?.text;
+    this.deliverables = data?.deliverables;
+    this.draftDueAt = data?.draftDueAt;
+    this.liveByAt = data?.liveByAt;
+    this.licenceMonths = data?.licenceMonths;
+    this.paidPromoMonths = data?.paidPromoMonths;
+    this.revisionRounds = data?.revisionRounds;
+  }
+}
+
+export class CreateAgencyCampaignDto extends AgencyCampaignBriefFields {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  name: string;
+
+  /** Absent = an offer campaign (US7). */
+  @IsOptional()
+  @IsIn(AGENCY_CAMPAIGN_KINDS as unknown as string[])
+  kind?: AgencyCampaignKind;
+
+  constructor(data?: Partial<CreateAgencyCampaignDto>) {
+    super();
+    this.name = data?.name ?? '';
+    this.kind = data?.kind;
+    this.assignBrief(data);
+  }
+}
+
+export class UpdateAgencyCampaignDto extends AgencyCampaignBriefFields {
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(128)
+  name?: string;
+
+  /** Setting false publishes the draft; the brief text must then be present (FR-025). */
+  @IsOptional()
+  @IsBoolean()
+  isDraft?: boolean;
+
+  /** Switch offer ↔ pot; refused once the first creator is invited (FR-030). */
+  @IsOptional()
+  @IsIn(AGENCY_CAMPAIGN_KINDS as unknown as string[])
+  kind?: AgencyCampaignKind;
+
+  constructor(data?: Partial<UpdateAgencyCampaignDto>) {
+    super();
+    this.name = data?.name;
+    this.isDraft = data?.isDraft;
+    this.kind = data?.kind;
+    this.assignBrief(data);
+  }
+}
+
+export class InviteCampaignCreatorDto {
+  /** A user id: a UUID or a Firebase uid. */
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,128}$/)
+  creatorUserId: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(5000)
+  creatorBrief?: string;
+
+  /** The access request folded into the invitation when no grant covers them (FR-026). */
+  @IsOptional()
+  @IsArray()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes?: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<InviteCampaignCreatorDto>) {
+    this.creatorUserId = data?.creatorUserId ?? '';
+    this.creatorBrief = data?.creatorBrief;
+    this.scopes = data?.scopes;
+  }
+}
+
+export class SendCampaignOfferDto {
+  @IsInt()
+  @Min(0)
+  @Max(1_000_000_000)
+  priceMinor: number;
+
+  @IsString()
+  @Matches(/^[A-Z]{3}$/)
+  currency: string;
+
+  constructor(data?: Partial<SendCampaignOfferDto>) {
+    this.priceMinor = data?.priceMinor ?? 0;
+    this.currency = data?.currency ?? 'PLN';
+  }
+}
+
+/** One act on an offer. `counter` needs `priceMinor`; any act may carry a note. */
+export class CampaignOfferActDto {
+  @IsIn(AGENCY_OFFER_ACTIONS as unknown as string[])
+  action: AgencyOfferAction;
+
+  /** A counter keeps the offer's currency; only the amount moves. */
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(1_000_000_000)
+  priceMinor?: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  note?: string;
+
+  constructor(data?: Partial<CampaignOfferActDto>) {
+    this.action = data?.action ?? 'accept';
+    this.priceMinor = data?.priceMinor;
+    this.note = data?.note;
+  }
+}
+
+/** One agency act on a material. `request_changes` requires the note. */
+export class CampaignMaterialActDto {
+  @IsIn(AGENCY_MATERIAL_ACTIONS as unknown as string[])
+  action: AgencyMaterialAction;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  note?: string;
+
+  constructor(data?: Partial<CampaignMaterialActDto>) {
+    this.action = data?.action ?? 'approve';
+    this.note = data?.note;
+  }
+}
+
+export class JoinCampaignDto {
+  /** A subset of what was asked; absent = everything asked. */
+  @IsOptional()
+  @IsArray()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes?: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<JoinCampaignDto>) {
+    this.scopes = data?.scopes;
+  }
+}
+
+/** Material files: images and video only, at most 2 GB. */
+export const MATERIAL_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+
+/**
+ * The photo formats a material may be. Raster only: no SVG or HTML, because a
+ * material is opened in the browser. Shared so the upload picker, the
+ * creator's own check and the API refuse exactly the same files.
+ */
+export const MATERIAL_IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/heic', 'image/heif', 'image/avif'] as const;
+
+/** A material's content type: one of MATERIAL_IMAGE_TYPES, or any video. */
+export const MATERIAL_CONTENT_TYPE = new RegExp(
+  `^(${MATERIAL_IMAGE_TYPES.map((type) => type.replace(/[/+.]/g, (c) => `\\${c}`)).join('|')}|video\\/[A-Za-z0-9.+-]+)$`,
+);
+
+export class PrepareMaterialUploadDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  fileName: string;
+
+  @IsString()
+  /** Raster images and video (MATERIAL_CONTENT_TYPE). */
+  @Matches(MATERIAL_CONTENT_TYPE)
+  contentType: string;
+
+  @IsInt()
+  @Min(1)
+  @Max(MATERIAL_MAX_BYTES)
+  sizeBytes: number;
+
+  constructor(data?: Partial<PrepareMaterialUploadDto>) {
+    this.fileName = data?.fileName ?? '';
+    this.contentType = data?.contentType ?? '';
+    this.sizeBytes = data?.sizeBytes ?? 0;
+  }
+}
+
+export class ConfirmMaterialUploadDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(512)
+  uploadId: string;
+
+  /** The post's caption, sent with the material on a pot campaign (FR-032). */
+  @IsOptional()
+  @IsString()
+  @MaxLength(2200)
+  caption?: string;
+
+  constructor(data?: Partial<ConfirmMaterialUploadDto>) {
+    this.uploadId = data?.uploadId ?? '';
+    this.caption = data?.caption;
+  }
+}
+
+export class CreateAgencyMilestoneDto {
+  @IsIn(AGENCY_MILESTONE_KINDS as unknown as string[])
+  kind: AgencyMilestoneKind;
+
+  /** Required for `custom`, ignored otherwise. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(256)
+  label?: string;
+
+  @IsOptional()
+  @IsDateString()
+  dueAt?: string | null;
+
+  /** Absent = campaign-wide. */
+  @IsOptional()
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,128}$/)
+  creatorUserId?: string | null;
+
+  @IsOptional()
+  @IsIn(AGENCY_MILESTONE_OFFER_RULES as unknown as string[])
+  offerRule?: (typeof AGENCY_MILESTONE_OFFER_RULES)[number] | null;
+
+  @IsOptional()
+  @IsIn(AGENCY_MILESTONE_MEDIA_RULES as unknown as string[])
+  mediaRule?: (typeof AGENCY_MILESTONE_MEDIA_RULES)[number] | null;
+
+  constructor(data?: Partial<CreateAgencyMilestoneDto>) {
+    this.kind = data?.kind ?? 'custom';
+    this.label = data?.label;
+    this.dueAt = data?.dueAt;
+    this.creatorUserId = data?.creatorUserId;
+    this.offerRule = data?.offerRule;
+    this.mediaRule = data?.mediaRule;
+  }
+}
+
+/** `PATCH /users/me/settlement-form` — the creator's own setting (FR-027). */
+export class UpdateSettlementFormDto {
+  @IsOptional()
+  @IsIn(SETTLEMENT_FORMS as unknown as string[])
+  settlementForm: SettlementForm | null;
+
+  constructor(data?: Partial<UpdateSettlementFormDto>) {
+    this.settlementForm = data?.settlementForm ?? null;
+  }
+}