ad2app-lib 1.49.0 → 1.59.0

package/src/types/agency-campaigns.ts

@@ -6,6 +6,7 @@ import {
   IsIn,
   IsInt,
   IsNotEmpty,
+  IsObject,
   IsOptional,
   IsString,
   Matches,
@@ -17,6 +18,8 @@ import {
 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';
+import { CAMPAIGN_VISIBILITIES, type CampaignVisibility, type I_CampaignListing, type I_TargetProfile } from './dealroom';
 
 /**
  * The campaign loop (spec 175 US7) — an organization runs a campaign with the
@@ -68,9 +71,21 @@ 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];
 
+/** How a creator came onto a campaign: 175's invitation, or a Dealroom application to an open listing (spec 148). */
+export const AGENCY_CAMPAIGN_MEMBER_ORIGINS = ['invitation', 'application'] as const;
+export type AgencyCampaignMemberOrigin = (typeof AGENCY_CAMPAIGN_MEMBER_ORIGINS)[number];
+
 /** The offer statuses the agency loop writes. `draft`, `deleted` and `alternativeSuggested` are legacy-only. */
 export const AGENCY_OFFER_STATUSES = [
   I_OfferStatus.SENT,
@@ -90,9 +105,13 @@ export type CampaignSide = 'agency' | 'creator';
  * right now is the server's `availableActions`, never a client guess.
  *
  *   agency:  counter · confirm · reject
- *   creator: accept · counter · reject
+ *   creator: accept · counter · reject · apply
+ *
+ * `apply` (spec 148) is the creator's opening price on an open listing, with
+ * no offer yet: it lands in the existing negotiating status, the agency's
+ * turn. No offer status is added for it.
  */
-export const AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject'] as const;
+export const AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject', 'apply'] 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. */
@@ -143,6 +162,46 @@ export const AGENCY_CAMPAIGN_EVENT_KINDS = [
   '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',
+  // Spec 148 money release (DORMANT): the contract, money and payout steps of a
+  // Dealroom deal are kinds in this one log (FR-008a). Mirrored by
+  // DEALROOM_MONEY_EVENT_KINDS in dealroom.ts.
+  'contract_sent',
+  'contract_signed',
+  'contract_declined',
+  'deposit_paid',
+  'deal_funded',
+  'deal_closed_unviewed',
+  'deal_refund_requested',
+  'deal_refunded',
+  'guarantee_claimed',
+  'payout_initiated',
+  'payout_paid',
 ] as const;
 export type AgencyCampaignEventKind = (typeof AGENCY_CAMPAIGN_EVENT_KINDS)[number];
 
@@ -214,6 +273,10 @@ export interface I_AgencyMaterial {
   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 {
@@ -233,9 +296,28 @@ export interface I_AgencyMilestone {
 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;
+  /** Set when a delegate acted on the creator's side through a `deals` grant (spec 148 FR-017a). */
+  actingGrantId?: string;
+  /** With `actingGrantId`: the member who acted, shown as "<member> for <creator>". */
+  actingMemberName?: string;
+  /** The act came from the creator's Dealroom application (spec 148 US4), not an invitation. */
+  fromApplication?: true;
+}
+
+/** Spec 148 US8 AC3: one act a manager did in the creator's deal, for the creator's own view. */
+export interface I_CreatorDelegateAct {
+  kind: AgencyCampaignEventKind;
+  at: string;
+  /** The member of the managing agency who acted. */
+  memberName: string;
+  organizationName: string;
 }
 
 export interface I_CampaignCreatorIdentity {
@@ -250,6 +332,8 @@ export interface I_AgencyCampaignMemberRow {
   memberId: string;
   creator: I_CampaignCreatorIdentity;
   state: AgencyCampaignMemberState;
+  /** Invitation or Dealroom application (spec 148). Absent on older backends: read as 'invitation'. */
+  origin?: AgencyCampaignMemberOrigin;
   /** The board column, or the reason the row is off the board. */
   step: AgencyCampaignStep | AgencyCampaignOffBoard;
   /** When the row reached its current step. */
@@ -279,6 +363,8 @@ export interface I_AgencyCampaignPipeline {
 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;
@@ -291,12 +377,18 @@ export interface I_AgencyCampaignCard {
 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;
+  /** Spec 148: the Dealroom listing fields and their derived state. Absent on older backends. */
+  listing?: I_CampaignListing;
 }
 
 /** Opening one creator (FR-024): their course with dates, notes, files and milestones. */
@@ -306,6 +398,31 @@ export interface I_AgencyCampaignCreatorDetail {
   events: I_AgencyCampaignEvent[];
   materials: I_AgencyMaterial[];
   milestones: I_AgencyMilestone[];
+  /** Spec 148 T067: an offer deal's agreed publication time. Absent on a pot (its entry carries it) and on older backends. */
+  publication?: I_OfferPublication | null;
+}
+
+/**
+ * Spec 148 T067: an OFFER deal publishes through 175 US9's auto-publish path.
+ * The organization sets the agreed time on a confirmed offer with an approved
+ * material (`PATCH /agency/campaigns/:id/members/:memberId/publish-at`); the
+ * creator confirms that exact time once (`POST /agency/campaign-invitations/
+ * :memberId/publish-at/confirm`, the same route as a pot's); the post then goes
+ * out from the creator's own account, and publication is known by construction.
+ * `POST .../members/:memberId/published` stays for off-platform posting.
+ */
+export interface I_OfferPublication {
+  publishAt: string | null;
+  publishConfirmedAt: string | null;
+  /** The post is scheduled on the creator's account (the confirmed time is within the signed-link horizon). */
+  scheduled: boolean;
+  publishedAt: string | null;
+  /** The latest refusal at scheduling since the time was set or confirmed; the creator confirms again. */
+  publishRefusal: { at: string; reason: string } | null;
+  /** Organization side: the offer is confirmed, the latest material approved, and nothing is published yet. */
+  canSetPublishAt: boolean;
+  /** Creator side: a time is set and not confirmed, and the latest material's caption passes the disclosure check. */
+  canConfirmPublishAt: boolean;
 }
 
 /** `GET /agency/campaigns/attention` — what waits on the agency (FR-022, the rail). */
@@ -313,6 +430,8 @@ 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;
 }
 
@@ -348,7 +467,12 @@ export interface I_CreatorCampaignView {
   memberId: string;
   state: AgencyCampaignMemberState;
   organization: { id: string; name: string };
-  campaign: { id: string; name: string; brief: I_AgencyCampaignBrief };
+  /** `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[];
@@ -360,6 +484,10 @@ export interface I_CreatorCampaignView {
   canLeave: boolean;
   milestones: I_AgencyMilestone[];
   invitedAt: string;
+  /** Spec 148 T067: an offer deal's agreed publication time; null on a pot (see `pot.entry`) and before a confirmed offer. */
+  publication?: I_OfferPublication | null;
+  /** Spec 148 US8 AC3: what a manager did in this deal for the creator, oldest first. Absent on older backends. */
+  delegateActs?: I_CreatorDelegateAct[];
 }
 
 /** `GET /agency/campaign-invitations/mine` — pending invitations and live campaigns. */
@@ -390,8 +518,8 @@ export interface I_SignedRead {
 // 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. */
-class AgencyCampaignBriefFields {
+/** 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)
@@ -428,7 +556,42 @@ class AgencyCampaignBriefFields {
   @Max(20)
   revisionRounds?: number | null;
 
+  // ── Spec 148: the open listing. Refused by the backend while DEALROOM_ENABLED is off. ──
+
+  /** `open` lists the campaign in the Dealroom feed; it needs a target profile and the organization's logo. */
+  @IsOptional()
+  @IsIn(CAMPAIGN_VISIBILITIES as unknown as string[])
+  visibility?: CampaignVisibility;
+
+  /** Checked field by field in the service (flat bodies, see above). Blank constraint = no filter. */
+  @IsOptional()
+  @IsObject()
+  targetProfile?: I_TargetProfile | null;
+
+  /** Null = unlimited. Once frozen, it may only grow. */
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(10000)
+  slots?: number | null;
+
+  /** Offer kind only (a pot keeps its own). Once frozen, it may only move later. */
+  @IsOptional()
+  @IsDateString()
+  applicationDeadline?: string | null;
+
+  /** Any date closes the listing NOW (server time): new applications stop, running deals do not. */
+  @IsOptional()
+  @IsDateString()
+  closedAt?: string | null;
+
   protected assignBrief(data?: Partial<AgencyCampaignBriefFields>): void {
+    this.assignPot(data);
+    this.visibility = data?.visibility;
+    this.targetProfile = data?.targetProfile;
+    this.slots = data?.slots;
+    this.applicationDeadline = data?.applicationDeadline;
+    this.closedAt = data?.closedAt;
     this.text = data?.text;
     this.deliverables = data?.deliverables;
     this.draftDueAt = data?.draftDueAt;
@@ -445,9 +608,15 @@ export class CreateAgencyCampaignDto extends AgencyCampaignBriefFields {
   @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);
   }
 }
@@ -464,10 +633,16 @@ export class UpdateAgencyCampaignDto extends AgencyCampaignBriefFields {
   @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);
   }
 }
@@ -608,8 +783,15 @@ export class ConfirmMaterialUploadDto {
   @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;
   }
 }
 

package/src/types/agency-pots.test.ts

@@ -0,0 +1,255 @@
+import { test } from "node:test";
+import { validateSync } from "class-validator";
+import assert from "node:assert/strict";
+
+import {
+  ApplyToPotDto,
+  POT_CURRENCIES,
+  CREATOR_POT_FORBIDDEN_KEY,
+  DISCLOSURE_VISIBLE_CHARS,
+  POT_STEPS,
+  checkDisclosure,
+  creatorPotForbiddenKeys,
+  POT_REMOVAL_DECISIONS,
+  potBonusMinor,
+  potEarnings,
+  potViewsAtMax,
+  potCostPer1000Minor,
+  type I_CreatorPotView,
+} from "./agency-pots";
+import { AGENCY_CAMPAIGN_EVENT_KINDS, CreateAgencyCampaignDto } from "./agency-campaigns";
+import { EVENTS } from "../analytics";
+
+// ── checkDisclosure (FR-040) ────────────────────────────────────────────────
+
+test("every UOKiK wording passes, with or without #, in any case", () => {
+  const passing = [
+    "reklama",
+    "#reklama Poranny bieg",
+    "REKLAMA: nowa kolekcja",
+    "materiał reklamowy",
+    "#materiałreklamowy",
+    "Materiał reklamowy marki X",
+    "współpraca reklamowa z @northlight",
+    "#współpracareklamowa",
+    "płatna współpraca",
+    "#płatnawspółpraca",
+    "post sponsorowany",
+    "#postsponsorowany",
+    // Without Polish diacritics, as people type on a phone.
+    "material reklamowy",
+    "wspolpraca reklamowa",
+    "platna wspolpraca",
+  ];
+  for (const caption of passing) {
+    assert.equal(checkDisclosure(caption).result, "pass", caption);
+  }
+});
+
+test("the four bare tags are weak, never accepted silently", () => {
+  for (const tag of ["#współpraca", "#ad", "#spons", "#promo", "#wspolpraca", "#AD"]) {
+    const check = checkDisclosure(`Nowa kolekcja jest super ${tag}`);
+    assert.equal(check.result, "weak", tag);
+    assert.equal(check.found, tag);
+  }
+});
+
+test("a caption with no disclosure at all is missing", () => {
+  assert.deepEqual(checkDisclosure("Poranny bieg w nowej kurtce"), { result: "missing", found: null, at: null });
+  assert.equal(checkDisclosure("").result, "missing");
+});
+
+test("a wording past the first 125 characters is not visible and does not pass", () => {
+  assert.equal(DISCLOSURE_VISIBLE_CHARS, 125, "FR-040: visible without expanding the caption");
+  const filler = "x".repeat(DISCLOSURE_VISIBLE_CHARS);
+  const check = checkDisclosure(`${filler} #reklama`);
+  assert.equal(check.result, "weak");
+  assert.equal(check.found, "#reklama");
+  assert.equal(check.at, DISCLOSURE_VISIBLE_CHARS + 1);
+  // The last visible position still passes.
+  const edge = `${"x".repeat(DISCLOSURE_VISIBLE_CHARS - "reklama".length)}reklama`;
+  assert.equal(edge.length, DISCLOSURE_VISIBLE_CHARS);
+  assert.equal(checkDisclosure(edge).result, "missing", "glued to a word is not the word");
+  assert.equal(checkDisclosure(`${"x ".repeat(59)}reklama`).result, "pass");
+});
+
+test("a wording inside another word is not a disclosure", () => {
+  for (const caption of ["reklamacja przyjęta", "antyreklama", "#reklamacja", "#adidas", "#promocja", "#sponsor"]) {
+    assert.notEqual(checkDisclosure(caption).result, "pass", caption);
+  }
+  assert.equal(checkDisclosure("#adidas").result, "missing");
+});
+
+test("a strong wording wins over a weak tag anywhere in the caption", () => {
+  assert.equal(checkDisclosure("#współpraca #reklama nowa kurtka").result, "pass");
+});
+
+// ── potEarnings (FR-030, FR-032, FR-035) ───────────────────────────────────
+
+test("earnings are the guarantee plus the rate times views, exact to the minor unit", () => {
+  // 15 000,00 zł + 70,00 zł per 1000 × 1 000 views = 15 070,00 zł
+  assert.equal(potEarnings({ guaranteeMinor: 1_500_000, ratePer1000Minor: 7_000, views: 1_000, maxMinor: 9_000_000 }), 1_507_000);
+  // 55,00 zł per 1000 × 845 300 views = 46 491,50 zł; plus 20 000,00 zł
+  assert.equal(potEarnings({ guaranteeMinor: 2_000_000, ratePer1000Minor: 5_500, views: 845_300, maxMinor: 9_000_000 }), 6_649_150);
+  // A fraction of a grosz is never paid: rounded down.
+  assert.equal(potBonusMinor(3_333, 1), 3);
+  assert.equal(potBonusMinor(1, 999), 0);
+});
+
+test("earnings never exceed the maximum", () => {
+  assert.equal(potEarnings({ guaranteeMinor: 1_500_000, ratePer1000Minor: 7_000, views: 1_420_000, maxMinor: 9_000_000 }), 9_000_000);
+  for (let i = 0; i < 2_000; i++) {
+    const maxMinor = 1 + Math.floor(Math.random() * 20_000_000);
+    const guaranteeMinor = Math.floor(Math.random() * maxMinor);
+    const ratePer1000Minor = Math.floor(Math.random() * 100_000);
+    const views = Math.floor(Math.random() * 50_000_000);
+    const earned = potEarnings({ guaranteeMinor, ratePer1000Minor, views, maxMinor });
+    assert.ok(Number.isInteger(earned));
+    assert.ok(earned <= maxMinor, `${earned} > ${maxMinor}`);
+    assert.ok(earned >= guaranteeMinor);
+  }
+});
+
+test("views at the maximum are the exact count, rounded up", () => {
+  // (90 000 − 15 000) / 70 × 1000 = 1 071 428.57… → 1 071 429
+  const terms = { guaranteeMinor: 1_500_000, ratePer1000Minor: 7_000, maxMinor: 9_000_000 };
+  const atMax = potViewsAtMax(terms);
+  assert.equal(atMax, 1_071_429);
+  assert.equal(potEarnings({ ...terms, views: atMax }), 9_000_000);
+  assert.ok(potEarnings({ ...terms, views: atMax - 1 }) < 9_000_000);
+  assert.equal(potViewsAtMax({ ...terms, ratePer1000Minor: 0 }), null, "a zero rate never reaches the maximum");
+});
+
+// ── The creator's view carries nothing pot-level (SC-016) ───────────────────
+
+test("I_CreatorPotView has no key matching a pot-level word", () => {
+  // A full sample of the type: every key the creator receives. Adding a key to
+  // the interface without adding it here fails to compile (the satisfies check).
+  const sample = {
+    campaignId: "c",
+    currency: "PLN",
+    maxPerCreatorMinor: 1,
+    bonusWindowDays: 30,
+    keepUpMonths: 12,
+    coverUrl: null,
+    applicationDeadlineAt: null,
+    availability: "full_max_available",
+    approx: { currency: "EUR", maxPerCreatorMinor: 1, rateDate: "2026-09-30" },
+    schedule: { materialsDueAt: null, publicationDueAt: null, bonusEndsAt: null, keepUpEndsAt: null },
+    publishing: { paidPartnershipLabel: true, sponsorHandle: null, collabHandle: null, firstComment: null, commentsEnabled: true },
+    entry: {
+      state: "accepted",
+      terms: { guaranteeMinor: 1, ratePer1000Minor: 1 },
+      appliedAt: "x",
+      decidedAt: null,
+      publishAt: null,
+      publishConfirmedAt: null,
+      publishedAt: null,
+      postUrl: null,
+      bonusEndsAt: null,
+      keepUpEndsAt: null,
+      outcome: null,
+      mayTakeDown: false,
+      earnings: { guaranteeMinor: 1, bonusMinor: 0, heldBonusMinor: 0, totalMinor: 1, views: 0, lastCountAt: null, frozen: false },
+    },
+    canApply: false,
+    canWithdraw: false,
+    canConfirmPublishAt: false,
+    medianViews: null,
+  } satisfies Required<I_CreatorPotView>;
+  assert.deepEqual(creatorPotForbiddenKeys(sample), []);
+});
+
+test("the fence catches a pot-level key at any depth", () => {
+  assert.deepEqual(creatorPotForbiddenKeys({ a: { b: [{ potBudgetMinor: 1 }] } }), ["a.b.0.potBudgetMinor"]);
+  for (const key of ["budgetMinor", "remainderMinor", "reservedMinor", "fundedMinor", "max_budget", "maxBudgetMinor", "goalViews", "unreserved", "creatorsCoveredAtFullMax", "maxCommitmentMinor", "acceptedCreators"]) {
+    assert.ok(CREATOR_POT_FORBIDDEN_KEY.test(key), key);
+  }
+  // SC-016 names the earned amount; views and the blended cost are pot-level too (review 2026-10-06 M9).
+  for (const key of ["earnedMinor", "blendedCostPer1000Minor", "resultViews", "heldViews", "countedViews"]) {
+    assert.ok(CREATOR_POT_FORBIDDEN_KEY.test(key), key);
+  }
+  for (const key of ["maxPerCreatorMinor", "guaranteeMinor", "keepUpMonths", "availability", "acceptedAt", "decidedAt", "earnings", "bonusMinor", "totalMinor", "views", "medianViews"]) {
+    assert.ok(!CREATOR_POT_FORBIDDEN_KEY.test(key), key);
+  }
+});
+
+test("a decomposed Polish letter, a double space or a no-break space still pass (review 2026-10-06 L9)", () => {
+  assert.equal(checkDisclosure("współpraca reklamowa".normalize("NFD")).result, "pass");
+  assert.equal(checkDisclosure("materiał  reklamowy").result, "pass");
+  assert.equal(checkDisclosure("płatna\u00a0współpraca").result, "pass");
+});
+
+test("a tag glued to the word before it starts at its #, so the fold is judged from there", () => {
+  const caption = "x".repeat(DISCLOSURE_VISIBLE_CHARS - 2) + "x#reklama";
+  const check = checkDisclosure(caption);
+  assert.equal(check.at, DISCLOSURE_VISIBLE_CHARS - 1);
+  assert.equal(check.result, "pass");
+  assert.equal(check.found, "#reklama");
+});
+
+test("the money helpers never throw on a non-whole input", () => {
+  assert.equal(potBonusMinor(Number.NaN, 1000), 0);
+  assert.equal(potBonusMinor(100, Number.POSITIVE_INFINITY), 0);
+  assert.equal(potViewsAtMax({ guaranteeMinor: 0, ratePer1000Minor: 0.5, maxMinor: 100 }), null);
+  assert.equal(potCostPer1000Minor(10.5, 1000), 10);
+  assert.equal(potCostPer1000Minor(100, Number.NaN), null);
+});
+
+// ── States, events, DTOs ─────────────────────────────────────────────────────
+
+test("the pot board columns are the approved design's, in order", () => {
+  assert.deepEqual([...POT_STEPS], ["invited", "applied", "accepted", "material_in", "scheduled", "counting", "final", "done"]);
+});
+
+test("every pot act is an event kind, recorded with actor and amount (FR-021, FR-033)", () => {
+  for (const kind of [
+    "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",
+    "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",
+    "caption_edited",
+    "file_uploaded",
+    "file_removed",
+  ]) {
+    assert.ok((AGENCY_CAMPAIGN_EVENT_KINDS as readonly string[]).includes(kind), kind);
+  }
+});
+
+test("the pot analytics events are snake_case and carry the agency prefix", () => {
+  const pot = Object.entries(EVENTS).filter(([name]) => name.startsWith("AGENCY_POT_"));
+  assert.ok(pot.length >= 6);
+  for (const [, value] of pot) assert.match(value, /^agency_pot_[a-z_]+$/);
+});
+
+test("an application constructs empty, as the validation pipe does", () => {
+  assert.doesNotThrow(() => new ApplyToPotDto());
+  assert.equal(new ApplyToPotDto({ guaranteeMinor: 5, ratePer1000Minor: 7 }).ratePer1000Minor, 7);
+});
+
+test("the agency's decision on a removal after the bonus window is keep or withhold, nothing else", () => {
+  assert.deepEqual([...POT_REMOVAL_DECISIONS], ["keep_base", "withhold_base"]);
+});
+
+test("a pot is kept in a two-decimal currency only", () => {
+  const errors = (potCurrency: string) =>
+    validateSync(new CreateAgencyCampaignDto({ name: "x", kind: "pot", potCurrency })).filter((e) => e.property === "potCurrency");
+  for (const c of POT_CURRENCIES) assert.deepEqual(errors(c), [], c);
+  for (const c of ["JPY", "KWD", "pln", "XXX"]) assert.equal(errors(c).length, 1, c);
+});