ad2app-lib 1.47.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/agency-threads.d.ts

@@ -0,0 +1,87 @@
+import type { CampaignSide, I_CampaignCreatorIdentity } from './agency-campaigns';
+/**
+ * Agency ↔ creator threads (spec 175 US8, FR-023): one conversation per
+ * organization and creator, inside ad2app.
+ *
+ * Deliberately NOT the creator's platform inbox: nothing here reaches a social
+ * platform, and no grant scope opens a thread (SC-015). A thread is the two
+ * parties' own; a grant is a read of the creator's numbers, and the two never
+ * meet.
+ *
+ * "Unanswered" is derived: the other side wrote last. There is no read state
+ * and no mark-read step.
+ */
+export declare const AGENCY_THREAD_CODES: {
+    /** No live relationship any more: the history stays readable, nothing can be sent (FR-023). */
+    readonly CLOSED: "agency-thread-closed";
+    /** Too many messages from one person in the window (THREAD_POST_LIMIT). */
+    readonly RATE_LIMITED: "agency-thread-rate-limited";
+};
+/** Messages one person may post across all their threads per window: a conversation pace, never a script's. */
+export declare const THREAD_POST_LIMIT: {
+    readonly limit: 60;
+    readonly windowMinutes: 10;
+};
+/** Long enough for a real message, short enough to stay a message. */
+export declare const THREAD_MESSAGE_MAX = 4000;
+/** Messages per read: the newest page with the thread, earlier pages on request. */
+export declare const THREAD_PAGE_SIZE = 100;
+export interface I_AgencyThreadMessage {
+    id: string;
+    side: CampaignSide;
+    body: string;
+    at: string;
+}
+export interface I_AgencyThreadSummary {
+    id: string;
+    /** Agency side: who the thread is with. */
+    creator: I_CampaignCreatorIdentity;
+    /** Creator side: which organization. */
+    organization: {
+        id: string;
+        name: string;
+    };
+    lastMessage: {
+        side: CampaignSide;
+        body: string;
+        at: string;
+    } | null;
+    /** The other side wrote last, seen from the caller's side. */
+    unanswered: boolean;
+    /** No live relationship: read-only for whoever still exists. */
+    closed: boolean;
+}
+export interface I_AgencyThread {
+    summary: I_AgencyThreadSummary;
+    /** The newest page, oldest first. */
+    messages: I_AgencyThreadMessage[];
+    /** Older messages exist: read them with `…/messages?before=<oldest id>`. */
+    hasEarlier: boolean;
+}
+/** `GET …/threads/:id/messages?before=<message id>` — the page before a message. */
+export interface I_AgencyThreadPage {
+    /** Oldest first. */
+    messages: I_AgencyThreadMessage[];
+    hasEarlier: boolean;
+}
+/** `GET /agency/threads` — the agency's inbox. */
+export interface I_AgencyThreads {
+    items: I_AgencyThreadSummary[];
+    /** Creators on the roster the agency has no open thread with yet. */
+    startable: I_CampaignCreatorIdentity[];
+    /** The Inbox rail count. */
+    unanswered: number;
+}
+/** `GET /agency/creator-threads/mine` — the creator's threads, in the Agency tab. */
+export interface I_CreatorThreads {
+    items: I_AgencyThreadSummary[];
+    unanswered: number;
+}
+export declare class StartAgencyThreadDto {
+    creatorUserId: string;
+    constructor(data?: Partial<StartAgencyThreadDto>);
+}
+export declare class PostThreadMessageDto {
+    text: string;
+    constructor(data?: Partial<PostThreadMessageDto>);
+}

package/dist/types/agency-threads.js

@@ -0,0 +1,60 @@
+"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.PostThreadMessageDto = exports.StartAgencyThreadDto = exports.THREAD_PAGE_SIZE = exports.THREAD_MESSAGE_MAX = exports.THREAD_POST_LIMIT = exports.AGENCY_THREAD_CODES = void 0;
+const class_validator_1 = require("class-validator");
+/**
+ * Agency ↔ creator threads (spec 175 US8, FR-023): one conversation per
+ * organization and creator, inside ad2app.
+ *
+ * Deliberately NOT the creator's platform inbox: nothing here reaches a social
+ * platform, and no grant scope opens a thread (SC-015). A thread is the two
+ * parties' own; a grant is a read of the creator's numbers, and the two never
+ * meet.
+ *
+ * "Unanswered" is derived: the other side wrote last. There is no read state
+ * and no mark-read step.
+ */
+exports.AGENCY_THREAD_CODES = {
+    /** No live relationship any more: the history stays readable, nothing can be sent (FR-023). */
+    CLOSED: 'agency-thread-closed',
+    /** Too many messages from one person in the window (THREAD_POST_LIMIT). */
+    RATE_LIMITED: 'agency-thread-rate-limited',
+};
+/** Messages one person may post across all their threads per window: a conversation pace, never a script's. */
+exports.THREAD_POST_LIMIT = { limit: 60, windowMinutes: 10 };
+/** Long enough for a real message, short enough to stay a message. */
+exports.THREAD_MESSAGE_MAX = 4000;
+/** Messages per read: the newest page with the thread, earlier pages on request. */
+exports.THREAD_PAGE_SIZE = 100;
+class StartAgencyThreadDto {
+    constructor(data) {
+        this.creatorUserId = data?.creatorUserId ?? '';
+    }
+}
+exports.StartAgencyThreadDto = StartAgencyThreadDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Za-z0-9-]{1,128}$/),
+    __metadata("design:type", String)
+], StartAgencyThreadDto.prototype, "creatorUserId", void 0);
+class PostThreadMessageDto {
+    constructor(data) {
+        this.text = data?.text ?? '';
+    }
+}
+exports.PostThreadMessageDto = PostThreadMessageDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(exports.THREAD_MESSAGE_MAX),
+    __metadata("design:type", String)
+], PostThreadMessageDto.prototype, "text", void 0);

package/dist/types/agency.d.ts

@@ -33,6 +33,8 @@ export declare const AGENCY_ROUTE_PATHS: {
     readonly join: "/agency/join";
     /** A creator answering an access request (FR-016). */
     readonly requests: "/agency/requests";
+    /** A creator's campaign invitations and campaigns: the Agency tab of their Inbox (FR-023, FR-026). */
+    readonly creatorCampaigns: "/inbox/agency";
 };
 /**
  * The complete set of reads a grant may carry. A CEILING, not a starting point.

package/dist/types/agency.js

@@ -32,6 +32,8 @@ exports.AGENCY_ROUTE_PATHS = {
     join: '/agency/join',
     /** A creator answering an access request (FR-016). */
     requests: '/agency/requests',
+    /** A creator's campaign invitations and campaigns: the Agency tab of their Inbox (FR-023, FR-026). */
+    creatorCampaigns: '/inbox/agency',
 };
 // ── Scopes ───────────────────────────────────────────────────────────────────
 /**

package/dist/types/index.d.ts

@@ -38,4 +38,7 @@ export * from "./I_SM_Platform";
 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

@@ -57,5 +57,8 @@ __exportStar(require("./scheduling"), exports);
 __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.47.0",
+  "version": "1.50.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -196,11 +196,62 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
     actor_role: "member",
     origin: "agency_request",
   },
+  [EVENTS.AGENCY_CAMPAIGN_CREATED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_INVITED]: {
+    organization_id: "org-1",
+    actor_role: "member",
+    campaign_id: "c-1",
+    creator_user_id: "u-1",
+    with_access_request: true,
+  },
+  [EVENTS.AGENCY_CAMPAIGN_JOINED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_CAMPAIGN_DECLINED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_CAMPAIGN_LEFT]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_REMOVED]: {
+    organization_id: "org-1",
+    actor_role: "owner",
+    campaign_id: "c-1",
+    creator_user_id: "u-1",
+  },
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_SENT]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_ACTED]: {
+    organization_id: "org-1",
+    actor_role: "creator",
+    campaign_id: "c-1",
+    action: "counter",
+  },
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_UPLOADED]: {
+    organization_id: "org-1",
+    actor_role: "creator",
+    campaign_id: "c-1",
+    version: 2,
+  },
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_REVIEWED]: {
+    organization_id: "org-1",
+    actor_role: "member",
+    campaign_id: "c-1",
+    action: "request_changes",
+  },
+  [EVENTS.AGENCY_CAMPAIGN_PUBLISHED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [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, 15, "the 175 set is 15 events");
+  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)) {