ad2app-lib 1.47.0 → 1.49.0

package/dist/types/agency-campaigns.js

@@ -0,0 +1,426 @@
+"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.UpdateSettlementFormDto = exports.CreateAgencyMilestoneDto = exports.ConfirmMaterialUploadDto = exports.PrepareMaterialUploadDto = exports.MATERIAL_CONTENT_TYPE = exports.MATERIAL_IMAGE_TYPES = exports.MATERIAL_MAX_BYTES = exports.JoinCampaignDto = exports.CampaignMaterialActDto = exports.CampaignOfferActDto = exports.SendCampaignOfferDto = exports.InviteCampaignCreatorDto = exports.UpdateAgencyCampaignDto = exports.CreateAgencyCampaignDto = exports.AGENCY_CAMPAIGN_CODES = exports.AGENCY_CAMPAIGN_EVENT_KINDS = exports.AGENCY_MILESTONE_MEDIA_RULES = exports.AGENCY_MILESTONE_OFFER_RULES = exports.AGENCY_MILESTONE_KINDS = exports.AGENCY_CAMPAIGN_STEPS = exports.AGENCY_MATERIAL_ACTIONS = exports.AGENCY_OFFER_ACTIONS = exports.AGENCY_OFFER_STATUSES = exports.AGENCY_CAMPAIGN_MEMBER_STATES = exports.SETTLEMENT_FORMS = exports.isCampaignPlacement = exports.CAMPAIGN_PLATFORMS = exports.CAMPAIGN_PLACEMENTS = void 0;
+const class_validator_1 = require("class-validator");
+const I_Media_1 = require("./I_Media");
+const I_Offer_1 = require("./I_Offer");
+const agency_1 = require("./agency");
+/**
+ * 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.
+ */
+exports.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'],
+};
+exports.CAMPAIGN_PLATFORMS = Object.keys(exports.CAMPAIGN_PLACEMENTS);
+const isCampaignPlacement = (platform, placement) => Object.prototype.hasOwnProperty.call(exports.CAMPAIGN_PLACEMENTS, platform) &&
+    exports.CAMPAIGN_PLACEMENTS[platform].includes(placement);
+exports.isCampaignPlacement = isCampaignPlacement;
+// ── The settlement form (FR-027) ─────────────────────────────────────────────
+/** The creator's own setting. The agency reads it and can never set it. */
+exports.SETTLEMENT_FORMS = ['invoice', 'contract', 'barter'];
+// ── States ───────────────────────────────────────────────────────────────────
+exports.AGENCY_CAMPAIGN_MEMBER_STATES = ['invited', 'joined', 'declined', 'left', 'removed'];
+/** The offer statuses the agency loop writes. `draft`, `deleted` and `alternativeSuggested` are legacy-only. */
+exports.AGENCY_OFFER_STATUSES = [
+    I_Offer_1.I_OfferStatus.SENT,
+    I_Offer_1.I_OfferStatus.INFLUENCER_NEGOTIATED,
+    I_Offer_1.I_OfferStatus.AGENCY_NEGOTIATED,
+    I_Offer_1.I_OfferStatus.ACCEPTED,
+    I_Offer_1.I_OfferStatus.CONFIRMED,
+    I_Offer_1.I_OfferStatus.REJECTED,
+    I_Offer_1.I_OfferStatus.WITHDRAWN,
+];
+/**
+ * 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
+ */
+exports.AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject'];
+/** The agency's acts on the latest material; the creator's only act is to upload. */
+exports.AGENCY_MATERIAL_ACTIONS = ['approve', 'request_changes', 'reject'];
+/**
+ * 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.
+ */
+exports.AGENCY_CAMPAIGN_STEPS = [
+    'invited',
+    'joined',
+    'offer_sent',
+    'negotiating',
+    'confirmed',
+    'material_in',
+    'approved',
+    'published',
+];
+exports.AGENCY_MILESTONE_KINDS = ['draft_due', 'live_by', 'custom'];
+/** A milestone may wait on one rule: every ACTIVE offer at a status, or every active creator's latest material at a stage. */
+exports.AGENCY_MILESTONE_OFFER_RULES = [I_Offer_1.I_OfferStatus.CONFIRMED];
+exports.AGENCY_MILESTONE_MEDIA_RULES = [I_Media_1.I_MediaStage.UPLOADED, I_Media_1.I_MediaStage.ACCEPTED];
+exports.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',
+];
+/** Refusal codes the frontend owes its own copy for. */
+exports.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',
+};
+// ── 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. */
+class AgencyCampaignBriefFields {
+    assignBrief(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;
+    }
+}
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(10000),
+    __metadata("design:type", String)
+], AgencyCampaignBriefFields.prototype, "text", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(30),
+    __metadata("design:type", Array)
+], AgencyCampaignBriefFields.prototype, "deliverables", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], AgencyCampaignBriefFields.prototype, "draftDueAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], AgencyCampaignBriefFields.prototype, "liveByAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(120),
+    __metadata("design:type", Number)
+], AgencyCampaignBriefFields.prototype, "licenceMonths", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(120),
+    __metadata("design:type", Number)
+], AgencyCampaignBriefFields.prototype, "paidPromoMonths", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(20),
+    __metadata("design:type", Number)
+], AgencyCampaignBriefFields.prototype, "revisionRounds", void 0);
+class CreateAgencyCampaignDto extends AgencyCampaignBriefFields {
+    constructor(data) {
+        super();
+        this.name = data?.name ?? '';
+        this.assignBrief(data);
+    }
+}
+exports.CreateAgencyCampaignDto = CreateAgencyCampaignDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(128),
+    __metadata("design:type", String)
+], CreateAgencyCampaignDto.prototype, "name", void 0);
+class UpdateAgencyCampaignDto extends AgencyCampaignBriefFields {
+    constructor(data) {
+        super();
+        this.name = data?.name;
+        this.isDraft = data?.isDraft;
+        this.assignBrief(data);
+    }
+}
+exports.UpdateAgencyCampaignDto = UpdateAgencyCampaignDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(128),
+    __metadata("design:type", String)
+], UpdateAgencyCampaignDto.prototype, "name", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], UpdateAgencyCampaignDto.prototype, "isDraft", void 0);
+class InviteCampaignCreatorDto {
+    constructor(data) {
+        this.creatorUserId = data?.creatorUserId ?? '';
+        this.creatorBrief = data?.creatorBrief;
+        this.scopes = data?.scopes;
+    }
+}
+exports.InviteCampaignCreatorDto = InviteCampaignCreatorDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Za-z0-9-]{1,128}$/),
+    __metadata("design:type", String)
+], InviteCampaignCreatorDto.prototype, "creatorUserId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(5000),
+    __metadata("design:type", String)
+], InviteCampaignCreatorDto.prototype, "creatorBrief", 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)
+], InviteCampaignCreatorDto.prototype, "scopes", void 0);
+class SendCampaignOfferDto {
+    constructor(data) {
+        this.priceMinor = data?.priceMinor ?? 0;
+        this.currency = data?.currency ?? 'PLN';
+    }
+}
+exports.SendCampaignOfferDto = SendCampaignOfferDto;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(1000000000),
+    __metadata("design:type", Number)
+], SendCampaignOfferDto.prototype, "priceMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Z]{3}$/),
+    __metadata("design:type", String)
+], SendCampaignOfferDto.prototype, "currency", void 0);
+/** One act on an offer. `counter` needs `priceMinor`; any act may carry a note. */
+class CampaignOfferActDto {
+    constructor(data) {
+        this.action = data?.action ?? 'accept';
+        this.priceMinor = data?.priceMinor;
+        this.note = data?.note;
+    }
+}
+exports.CampaignOfferActDto = CampaignOfferActDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.AGENCY_OFFER_ACTIONS),
+    __metadata("design:type", String)
+], CampaignOfferActDto.prototype, "action", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(1000000000),
+    __metadata("design:type", Number)
+], CampaignOfferActDto.prototype, "priceMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2000),
+    __metadata("design:type", String)
+], CampaignOfferActDto.prototype, "note", void 0);
+/** One agency act on a material. `request_changes` requires the note. */
+class CampaignMaterialActDto {
+    constructor(data) {
+        this.action = data?.action ?? 'approve';
+        this.note = data?.note;
+    }
+}
+exports.CampaignMaterialActDto = CampaignMaterialActDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.AGENCY_MATERIAL_ACTIONS),
+    __metadata("design:type", String)
+], CampaignMaterialActDto.prototype, "action", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2000),
+    __metadata("design:type", String)
+], CampaignMaterialActDto.prototype, "note", void 0);
+class JoinCampaignDto {
+    constructor(data) {
+        this.scopes = data?.scopes;
+    }
+}
+exports.JoinCampaignDto = JoinCampaignDto;
+__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)
+], JoinCampaignDto.prototype, "scopes", void 0);
+/** Material files: images and video only, at most 2 GB. */
+exports.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.
+ */
+exports.MATERIAL_IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/heic', 'image/heif', 'image/avif'];
+/** A material's content type: one of MATERIAL_IMAGE_TYPES, or any video. */
+exports.MATERIAL_CONTENT_TYPE = new RegExp(`^(${exports.MATERIAL_IMAGE_TYPES.map((type) => type.replace(/[/+.]/g, (c) => `\\${c}`)).join('|')}|video\\/[A-Za-z0-9.+-]+)$`);
+class PrepareMaterialUploadDto {
+    constructor(data) {
+        this.fileName = data?.fileName ?? '';
+        this.contentType = data?.contentType ?? '';
+        this.sizeBytes = data?.sizeBytes ?? 0;
+    }
+}
+exports.PrepareMaterialUploadDto = PrepareMaterialUploadDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], PrepareMaterialUploadDto.prototype, "fileName", void 0);
+__decorate([
+    (0, class_validator_1.IsString)()
+    /** Raster images and video (MATERIAL_CONTENT_TYPE). */
+    ,
+    (0, class_validator_1.Matches)(exports.MATERIAL_CONTENT_TYPE),
+    __metadata("design:type", String)
+], PrepareMaterialUploadDto.prototype, "contentType", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(exports.MATERIAL_MAX_BYTES),
+    __metadata("design:type", Number)
+], PrepareMaterialUploadDto.prototype, "sizeBytes", void 0);
+class ConfirmMaterialUploadDto {
+    constructor(data) {
+        this.uploadId = data?.uploadId ?? '';
+    }
+}
+exports.ConfirmMaterialUploadDto = ConfirmMaterialUploadDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(512),
+    __metadata("design:type", String)
+], ConfirmMaterialUploadDto.prototype, "uploadId", void 0);
+class CreateAgencyMilestoneDto {
+    constructor(data) {
+        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;
+    }
+}
+exports.CreateAgencyMilestoneDto = CreateAgencyMilestoneDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.AGENCY_MILESTONE_KINDS),
+    __metadata("design:type", String)
+], CreateAgencyMilestoneDto.prototype, "kind", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(256),
+    __metadata("design:type", String)
+], CreateAgencyMilestoneDto.prototype, "label", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], CreateAgencyMilestoneDto.prototype, "dueAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Za-z0-9-]{1,128}$/),
+    __metadata("design:type", String)
+], CreateAgencyMilestoneDto.prototype, "creatorUserId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_MILESTONE_OFFER_RULES),
+    __metadata("design:type", Object)
+], CreateAgencyMilestoneDto.prototype, "offerRule", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_MILESTONE_MEDIA_RULES),
+    __metadata("design:type", Object)
+], CreateAgencyMilestoneDto.prototype, "mediaRule", void 0);
+/** `PATCH /users/me/settlement-form` — the creator's own setting (FR-027). */
+class UpdateSettlementFormDto {
+    constructor(data) {
+        this.settlementForm = data?.settlementForm ?? null;
+    }
+}
+exports.UpdateSettlementFormDto = UpdateSettlementFormDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.SETTLEMENT_FORMS),
+    __metadata("design:type", String)
+], UpdateSettlementFormDto.prototype, "settlementForm", 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,6 @@ export * from "./I_SM_Platform";
 export * from "./scheduling";
 export * from "./agent";
 export * from "./agency";
+export * from "./agency-campaigns";
+export * from "./agency-threads";
 export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -57,5 +57,7 @@ __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-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.49.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -196,11 +196,51 @@ 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" },
 };
 
 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, 29, "the 175 set is 15 roster events, 12 campaign-loop events (US7) and 2 thread events (US8)");
   for (const name of agencyEvents) {
     const props = EVENT_PROPERTY_WITNESS[name as keyof typeof EVENT_PROPERTY_WITNESS];
     for (const key of Object.keys(props)) {