ad2app-lib 1.49.0 → 1.50.0

package/dist/types/agency-pots.js

@@ -0,0 +1,393 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.PotFields = exports.PrepareCampaignFileUploadDto = exports.UpdateMaterialCaptionDto = exports.PotRemovalDecisionDto = exports.PotHoldActDto = exports.PotPublishAtDto = exports.MovePotDeadlineDto = exports.RefillPotDto = exports.ApplyToPotDto = exports.CAMPAIGN_FILE_MAX_BYTES = exports.CAMPAIGN_FILE_CONTENT_TYPE = exports.AGENCY_POT_CODES = exports.POT_REMOVAL_DECISIONS = exports.POT_HOLD_ACTIONS = exports.POT_HOLD_REASONS = exports.POT_AVAILABILITY = exports.POT_STEPS = exports.POT_ENTRY_STATES = exports.creatorPotForbiddenKeys = exports.CREATOR_POT_FORBIDDEN_KEY = exports.POT_CURRENCIES = exports.potCostPer1000Minor = exports.potViewsAtMax = exports.potEarnings = exports.potBonusMinor = exports.checkDisclosure = exports.DISCLOSURE_RESULTS = exports.DISCLOSURE_VISIBLE_CHARS = void 0;
+const class_validator_1 = require("class-validator");
+const agency_1 = require("./agency");
+/**
+ * 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. */
+exports.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) => new RegExp(`(?:#(?:${body})|(?<![\\p{L}\\p{N}_#])(?:${body}))(?![\\p{L}\\p{N}_])`, 'giu');
+const tag = (body) => new RegExp(`#(?:${body})(?![\\p{L}\\p{N}_])`, 'giu');
+const STRONG = word(STRONG_WORDINGS.join('|'));
+const WEAK = tag(WEAK_TAGS.join('|'));
+exports.DISCLOSURE_RESULTS = ['pass', 'weak', 'missing'];
+const checkDisclosure = (raw) => {
+    // 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 < exports.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 };
+};
+exports.checkDisclosure = checkDisclosure;
+// ── 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. */
+const potBonusMinor = (ratePer1000Minor, views) => Number((BigInt(wholeOrZero(ratePer1000Minor)) * BigInt(wholeOrZero(views))) / 1000n);
+exports.potBonusMinor = potBonusMinor;
+/** A non-negative whole number; anything else (NaN, Infinity, negative) is 0. */
+function wholeOrZero(n) {
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+/** What a creator's terms earn at `views` with an unlimited pot: never above the maximum. */
+const potEarnings = ({ guaranteeMinor, ratePer1000Minor, views, maxMinor }) => Math.min(maxMinor, guaranteeMinor + (0, exports.potBonusMinor)(ratePer1000Minor, views));
+exports.potEarnings = potEarnings;
+/** The exact view count at which the terms reach the maximum (rounded up), or null when they never do. */
+const potViewsAtMax = ({ guaranteeMinor, ratePer1000Minor, maxMinor }) => {
+    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);
+};
+exports.potViewsAtMax = potViewsAtMax;
+/** Cost per 1,000 views in minor units, rounded half up; null without views. */
+const potCostPer1000Minor = (costMinor, views) => {
+    const v = wholeOrZero(views);
+    return v > 0 ? Number((BigInt(wholeOrZero(costMinor)) * 2000n + BigInt(v)) / (2n * BigInt(v))) : null;
+};
+exports.potCostPer1000Minor = potCostPer1000Minor;
+/**
+ * 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).
+ */
+exports.POT_CURRENCIES = ['PLN', 'EUR', 'USD', 'GBP', 'CHF', 'CZK', 'SEK', 'NOK', 'DKK'];
+// ── The creator's fence (SC-016) ────────────────────────────────────────────
+/** Any key carrying a pot-level figure. A creator-facing response must have none, at any depth. */
+exports.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. */
+const creatorPotForbiddenKeys = (value, path = '') => {
+    if (value === null || typeof value !== 'object')
+        return [];
+    return Object.entries(value).flatMap(([key, child]) => {
+        const at = path ? `${path}.${key}` : key;
+        return [...(exports.CREATOR_POT_FORBIDDEN_KEY.test(key) ? [at] : []), ...(0, exports.creatorPotForbiddenKeys)(child, at)];
+    });
+};
+exports.creatorPotForbiddenKeys = creatorPotForbiddenKeys;
+// ── States ───────────────────────────────────────────────────────────────────
+/**
+ * An entry is one creator's application on one pot.
+ *   applied → accepted | declined | withdrawn;  accepted → released (left or
+ *   removed before publication).
+ */
+exports.POT_ENTRY_STATES = ['applied', 'accepted', 'declined', 'withdrawn', 'released'];
+/**
+ * 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).
+ */
+exports.POT_STEPS = ['invited', 'applied', 'accepted', 'material_in', 'scheduled', 'counting', 'final', 'done'];
+exports.POT_AVAILABILITY = ['full_max_available', 'filling_up'];
+/** Why a bonus is held (FR-037): the jump against the creator's own history, or paid delivery ad2app did not start. */
+exports.POT_HOLD_REASONS = ['jump', 'paid_delivery'];
+/** The agency's three acts on a held bonus. `message` records the act; the thread opens on the client. */
+exports.POT_HOLD_ACTIONS = ['approve', 'cap', 'message'];
+/**
+ * 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.
+ */
+exports.POT_REMOVAL_DECISIONS = ['keep_base', 'withhold_base'];
+/** Refusal codes the frontend owes its own copy for. */
+exports.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',
+};
+/** PDF, images, video, office documents and archives; no HTML or SVG (opened in the browser). */
+exports.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))$/;
+exports.CAMPAIGN_FILE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+// ── Bodies ───────────────────────────────────────────────────────────────────
+const MONEY_MAX = 100000000000;
+/**
+ * `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).
+ */
+class ApplyToPotDto {
+    constructor(data) {
+        this.guaranteeMinor = data?.guaranteeMinor ?? 0;
+        this.ratePer1000Minor = data?.ratePer1000Minor ?? 0;
+        this.scopes = data?.scopes;
+    }
+}
+exports.ApplyToPotDto = ApplyToPotDto;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], ApplyToPotDto.prototype, "guaranteeMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], ApplyToPotDto.prototype, "ratePer1000Minor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsIn)(agency_1.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], ApplyToPotDto.prototype, "scopes", void 0);
+/** `POST /agency/campaigns/:id/pot/refill` — up to the maximum budget. */
+class RefillPotDto {
+    constructor(data) {
+        this.amountMinor = data?.amountMinor ?? 0;
+    }
+}
+exports.RefillPotDto = RefillPotDto;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], RefillPotDto.prototype, "amountMinor", void 0);
+/** `PATCH /agency/campaigns/:id/pot/application-deadline`. */
+class MovePotDeadlineDto {
+    constructor(data) {
+        this.applicationDeadlineAt = data?.applicationDeadlineAt ?? '';
+    }
+}
+exports.MovePotDeadlineDto = MovePotDeadlineDto;
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], MovePotDeadlineDto.prototype, "applicationDeadlineAt", void 0);
+/** The agency sets the time agreed with the brand; the creator confirms that same value. */
+class PotPublishAtDto {
+    constructor(data) {
+        this.publishAt = data?.publishAt ?? '';
+    }
+}
+exports.PotPublishAtDto = PotPublishAtDto;
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], PotPublishAtDto.prototype, "publishAt", void 0);
+class PotHoldActDto {
+    constructor(data) {
+        this.action = data?.action ?? 'approve';
+    }
+}
+exports.PotHoldActDto = PotHoldActDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.POT_HOLD_ACTIONS),
+    __metadata("design:type", String)
+], PotHoldActDto.prototype, "action", void 0);
+/** `POST /agency/campaigns/:id/pot/entries/:entryId/removal` — the agency's decision on a late takedown (FR-032). */
+class PotRemovalDecisionDto {
+    constructor(data) {
+        this.decision = data?.decision ?? 'keep_base';
+    }
+}
+exports.PotRemovalDecisionDto = PotRemovalDecisionDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.POT_REMOVAL_DECISIONS),
+    __metadata("design:type", String)
+], PotRemovalDecisionDto.prototype, "decision", void 0);
+/** The caption is the creator's until publication (FR-032). */
+class UpdateMaterialCaptionDto {
+    constructor(data) {
+        this.caption = data?.caption ?? '';
+    }
+}
+exports.UpdateMaterialCaptionDto = UpdateMaterialCaptionDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2200),
+    __metadata("design:type", String)
+], UpdateMaterialCaptionDto.prototype, "caption", void 0);
+class PrepareCampaignFileUploadDto {
+    constructor(data) {
+        this.fileName = data?.fileName ?? '';
+        this.contentType = data?.contentType ?? '';
+        this.sizeBytes = data?.sizeBytes ?? 0;
+    }
+}
+exports.PrepareCampaignFileUploadDto = PrepareCampaignFileUploadDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], PrepareCampaignFileUploadDto.prototype, "fileName", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(exports.CAMPAIGN_FILE_CONTENT_TYPE),
+    __metadata("design:type", String)
+], PrepareCampaignFileUploadDto.prototype, "contentType", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(exports.CAMPAIGN_FILE_MAX_BYTES),
+    __metadata("design:type", Number)
+], PrepareCampaignFileUploadDto.prototype, "sizeBytes", void 0);
+/** The pot's fields on campaign create (and on a move); flat for the reason given in agency-campaigns.ts. */
+class PotFields {
+    assignPot(data) {
+        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;
+    }
+}
+exports.PotFields = PotFields;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potBudgetMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potMaxBudgetMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potCapMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(365),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potBonusWindowDays", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(60),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potKeepUpMonths", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(100000000000),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potGoalViews", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.POT_CURRENCIES),
+    __metadata("design:type", String)
+], PotFields.prototype, "potCurrency", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], PotFields.prototype, "potApplicationDeadlineAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PotFields.prototype, "potPaidPartnershipLabel", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^@?[A-Za-z0-9._]{1,64}$/),
+    __metadata("design:type", String)
+], PotFields.prototype, "potSponsorHandle", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^@?[A-Za-z0-9._]{1,64}$/),
+    __metadata("design:type", String)
+], PotFields.prototype, "potCollabHandle", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2200),
+    __metadata("design:type", String)
+], PotFields.prototype, "potFirstComment", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PotFields.prototype, "potCommentsEnabled", void 0);

package/dist/types/index.d.ts

@@ -39,5 +39,6 @@ export * from "./scheduling";
 export * from "./agent";
 export * from "./agency";
 export * from "./agency-campaigns";
+export * from "./agency-pots";
 export * from "./agency-threads";
 export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -58,6 +58,7 @@ __exportStar(require("./agent"), exports);
 // ── Agency domain (organizations, memberships, creator access grants, spec 175)
 __exportStar(require("./agency"), exports);
 __exportStar(require("./agency-campaigns"), exports);
+__exportStar(require("./agency-pots"), exports);
 __exportStar(require("./agency-threads"), exports);
 // ── Access control ────────────────────────────────────────────────────────────
 __exportStar(require("./I_AccessDenial"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -236,11 +236,22 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.AGENCY_CAMPAIGN_MILESTONE_CONFIRMED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1" },
   [EVENTS.AGENCY_THREAD_STARTED]: { organization_id: "org-1", actor_role: "member", thread_id: "t-1" },
   [EVENTS.AGENCY_THREAD_MESSAGE_SENT]: { organization_id: "org-1", actor_role: "creator", thread_id: "t-1" },
+  [EVENTS.AGENCY_POT_APPLIED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_APPLICATION_DECIDED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", action: "accept" },
+  [EVENTS.AGENCY_POT_REFILLED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_MOVED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_PUBLISH_TIME_CONFIRMED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_PUBLISHED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_BONUS_HELD]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", reason: "jump" },
+  [EVENTS.AGENCY_POT_BONUS_DECIDED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1", action: "cap" },
+  [EVENTS.AGENCY_POT_REMOVAL_DECIDED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1", decision: "withhold_base" },
+  [EVENTS.AGENCY_POT_EXPORTED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", format: "xlsx" },
+  [EVENTS.AGENCY_POT_FILE_UPLOADED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
 };
 
 test("no agency event may carry the discover query — only whether it matched (FR-015)", () => {
   const agencyEvents = Object.values(EVENTS).filter((name) => name.startsWith("agency_"));
-  assert.equal(agencyEvents.length, 29, "the 175 set is 15 roster events, 12 campaign-loop events (US7) and 2 thread events (US8)");
+  assert.equal(agencyEvents.length, 40, "the 175 set is 15 roster events, 12 campaign-loop events (US7), 2 thread events (US8) and 11 pot events (US9)");
   for (const name of agencyEvents) {
     const props = EVENT_PROPERTY_WITNESS[name as keyof typeof EVENT_PROPERTY_WITNESS];
     for (const key of Object.keys(props)) {

package/src/analytics/index.ts

@@ -208,6 +208,18 @@ export const EVENTS = {
   // Threads (175 US8). Never the message body: a conversation is not analytics.
   AGENCY_THREAD_STARTED: 'agency_thread_started',
   AGENCY_THREAD_MESSAGE_SENT: 'agency_thread_message_sent',
+  // Pot campaigns (175 US9). Never an amount: the pot's economics are the agency's.
+  AGENCY_POT_APPLIED: 'agency_pot_applied',
+  AGENCY_POT_APPLICATION_DECIDED: 'agency_pot_application_decided',
+  AGENCY_POT_REFILLED: 'agency_pot_refilled',
+  AGENCY_POT_MOVED: 'agency_pot_moved',
+  AGENCY_POT_PUBLISH_TIME_CONFIRMED: 'agency_pot_publish_time_confirmed',
+  AGENCY_POT_PUBLISHED: 'agency_pot_published',
+  AGENCY_POT_BONUS_HELD: 'agency_pot_bonus_held',
+  AGENCY_POT_BONUS_DECIDED: 'agency_pot_bonus_decided',
+  AGENCY_POT_REMOVAL_DECIDED: 'agency_pot_removal_decided',
+  AGENCY_POT_EXPORTED: 'agency_pot_exported',
+  AGENCY_POT_FILE_UPLOADED: 'agency_pot_file_uploaded',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -714,6 +726,17 @@ export interface EventProperties {
   // Threads (175 US8): which thread, never its content.
   [EVENTS.AGENCY_THREAD_STARTED]: AgencyEventProperties & { thread_id: string };
   [EVENTS.AGENCY_THREAD_MESSAGE_SENT]: AgencyEventProperties & { thread_id: string };
+  [EVENTS.AGENCY_POT_APPLIED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_APPLICATION_DECIDED]: AgencyCampaignEventProperties & { action: 'accept' | 'decline' };
+  [EVENTS.AGENCY_POT_REFILLED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_MOVED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_PUBLISH_TIME_CONFIRMED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_PUBLISHED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_BONUS_HELD]: AgencyCampaignEventProperties & { reason: 'jump' | 'paid_delivery' };
+  [EVENTS.AGENCY_POT_BONUS_DECIDED]: AgencyCampaignEventProperties & { action: 'approve' | 'cap' | 'message' };
+  [EVENTS.AGENCY_POT_REMOVAL_DECIDED]: AgencyCampaignEventProperties & { decision: 'keep_base' | 'withhold_base' };
+  [EVENTS.AGENCY_POT_EXPORTED]: AgencyCampaignEventProperties & { format: 'csv' | 'xlsx' | 'report' };
+  [EVENTS.AGENCY_POT_FILE_UPLOADED]: AgencyCampaignEventProperties;
 }
 
 /** Canonical person property keys (set via identify / $set). */

package/src/types/agency-campaigns.ts

@@ -17,6 +17,7 @@ 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';
 
 /**
  * The campaign loop (spec 175 US7) — an organization runs a campaign with the
@@ -68,6 +69,14 @@ 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];
 
@@ -143,6 +152,32 @@ 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',
 ] as const;
 export type AgencyCampaignEventKind = (typeof AGENCY_CAMPAIGN_EVENT_KINDS)[number];
 
@@ -214,6 +249,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,8 +272,12 @@ 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;
 }
 
@@ -279,6 +322,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,6 +336,10 @@ 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[];
@@ -313,6 +362,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 +399,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[];
@@ -390,8 +446,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)
@@ -429,6 +485,7 @@ class AgencyCampaignBriefFields {
   revisionRounds?: number | null;
 
   protected assignBrief(data?: Partial<AgencyCampaignBriefFields>): void {
+    this.assignPot(data);
     this.text = data?.text;
     this.deliverables = data?.deliverables;
     this.draftDueAt = data?.draftDueAt;
@@ -445,9 +502,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 +527,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 +677,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;
   }
 }