ad2app-lib 1.44.1 → 1.49.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.
@@ -93,6 +95,12 @@ export interface I_AgencyMember {
     /** Null while an e-mail invitation is outstanding — nobody has accepted yet. */
     userId?: string;
     invitedEmail: string;
+    /**
+     * The account's own e-mail once the invitation is accepted (and always for
+     * the owner, who applied rather than being invited). The Team panel names a
+     * person by this, never by the organization's contact address (T063).
+     */
+    accountEmail?: string;
     role: AgencyMemberRole;
     invitedAt: string;
     /** "Who is in" is exactly `acceptedAt != null`. */
@@ -152,7 +160,27 @@ export interface I_CreatorAccessGrant {
     };
     /** Which platforms the grant reaches right now — derived at read time, never stored. */
     platformsReached: PublishPlatform[];
+    /**
+     * The agency's OPEN second ask on an active grant, for scopes the creator
+     * did not grant (FR-008). Kept apart from `requestedScopes`, so the consent
+     * screen names exactly this ask and nothing refused earlier (review H4).
+     * Absent when there is no open ask.
+     */
+    reaskedScopes?: I_AgencyGrantScope[];
+    /** When that open ask expires unanswered. */
+    reaskExpiresAt?: string;
 }
+/**
+ * Outcomes of discovery and requests that are not refusals of access, sent as
+ * codes so the screen composes the sentence in the reader's language (FR-019,
+ * review M4). A 429 carries `{ code, limit, windowMinutes }`.
+ */
+export declare const AGENCY_REQUEST_CODES: {
+    readonly RATE_LIMITED: "agency-rate-limited";
+    readonly REQUEST_EXPIRED: "agency-request-expired";
+    readonly REQUEST_ANSWERED: "agency-request-answered";
+};
+export type AgencyRequestCode = (typeof AGENCY_REQUEST_CODES)[keyof typeof AGENCY_REQUEST_CODES];
 /**
  * Roster row states, DECLARED IN PRECEDENCE ORDER (data-model §Derived).
  *
@@ -160,7 +188,7 @@ export interface I_CreatorAccessGrant {
  * first. `revoked` is deliberately absent — a revoked creator leaves the roster
  * entirely for the settings history (FR-011).
  */
-export declare const AGENCY_ROSTER_ROW_STATES: readonly ["requested", "lapsed", "disconnected", "stale", "active"];
+export declare const AGENCY_ROSTER_ROW_STATES: readonly ["requested", "lapsed", "disconnected", "syncing", "stale", "active"];
 export type AgencyRosterRowState = (typeof AGENCY_ROSTER_ROW_STATES)[number];
 /**
  * What "needs attention" means — ONE home for the KPI tile, the roster segment
@@ -171,6 +199,32 @@ export type AgencyRosterRowState = (typeof AGENCY_ROSTER_ROW_STATES)[number];
  */
 export declare const AGENCY_ROSTER_NEEDS_ATTENTION_STATES: readonly ["lapsed", "disconnected", "stale"];
 export type AgencyRosterNeedsAttentionState = (typeof AGENCY_ROSTER_NEEDS_ATTENTION_STATES)[number];
+/**
+ * The rows that carry numbers — ONE home for "which creators' numbers may the
+ * agency see on the roster" (decided 2026-09-24, review M1/M2).
+ *
+ * Only a row whose card OPENS carries `metrics` and counts in the followers,
+ * followers-delta and comments totals: `active`, and `stale` (the card opens;
+ * the numbers are as old as `lastSyncAt` says). A `lapsed` creator's reads are
+ * refused on the card, so their numbers must not reach the agency through the
+ * roster instead; a `disconnected` creator has nothing live to count; a
+ * `requested` creator has shared nothing yet.
+ */
+export declare const AGENCY_ROSTER_METRICS_STATES: readonly ["syncing", "stale", "active"];
+export type AgencyRosterMetricsState = (typeof AGENCY_ROSTER_METRICS_STATES)[number];
+/**
+ * One creator's numbers on the roster (FR-011a: sortable metric columns), read
+ * from the daily-synced tables, never a vendor call. `null` is a REASON, never
+ * a zero: the creator did not grant that scope, or nothing has been synced yet.
+ */
+export interface I_AgencyRosterRowMetrics {
+    /** Latest followers over the creator's CONNECTED platforms; null without `analytics` or before the first sync. */
+    followers: number | null;
+    /** Against the snapshot seven days earlier, per connected platform; null without `analytics` or without a week-old point. */
+    followersDelta7d: number | null;
+    /** The current Monday-to-Sunday week, organization timezone; null without `comments`. */
+    commentsThisWeek: number | null;
+}
 export interface I_AgencyRosterRow {
     grantId: string;
     creator: {
@@ -180,22 +234,72 @@ export interface I_AgencyRosterRow {
     platforms: PublishPlatform[];
     state: AgencyRosterRowState;
     grantedScopes: I_AgencyGrantScope[];
+    /**
+     * The newest successful daily sync. Absent on a `requested` row (nothing is
+     * shared yet, so there is nothing to have synced for the agency) and on a
+     * creator never synced. `platforms` stays on a requested row: it is what the
+     * consent screen names, a fact about the account rather than shared data.
+     */
     lastSyncAt?: string;
+    /**
+     * Present ONLY on rows in AGENCY_ROSTER_METRICS_STATES (`active`, `stale`):
+     * the rows whose card opens. Absent on `lapsed`, `disconnected` and
+     * `requested` rows — no numbers, not null numbers.
+     */
+    metrics?: I_AgencyRosterRowMetrics;
+    /**
+     * The agency's own last "Ask again" (FR-008), while its one-per-TTL clock
+     * runs (audit F19): when it was sent and when another is possible. It says
+     * nothing about the ANSWER, because the clock runs whatever the creator did.
+     * The roster uses it to say "asked on …, again after …" instead of offering
+     * an ask that would not be sent. Absent once the clock has run out.
+     */
+    reaskedAt?: string;
+    reaskAvailableAt?: string;
+}
+/**
+ * The platforms a creator has connected, as the agency side sees them
+ * (discovery, the grant's "reaches"). `GET users/me/connected-platforms`,
+ * answered to every creator, subscribed or not.
+ */
+export interface I_ConnectedPlatforms {
+    platforms: PublishPlatform[];
 }
 export interface I_AgencyRoster {
     totals: {
         creators: number;
         active: number;
-        /** Summed only over creators holding `analytics`; disconnected platforms excluded. */
-        followers: number;
-        followersDelta7d: number;
-        /** Calendar week, Mon-Sun, organization timezone, creators holding `comments`. */
-        commentsThisWeek: number;
+        /**
+         * Summed only over rows in AGENCY_ROSTER_METRICS_STATES whose creator holds
+         * `analytics`; disconnected platforms excluded. `null` when no counted
+         * creator has a synced number yet, never a zero standing in (T067).
+         */
+        followers: number | null;
+        /**
+         * Same rows as `followers`, against the snapshot seven days earlier. `null`
+         * when no counted creator has a week-old point — unknown, never a zero.
+         */
+        followersDelta7d: number | null;
+        /**
+         * Calendar week, Mon-Sun, organization timezone, over rows in
+         * AGENCY_ROSTER_METRICS_STATES whose creator holds `comments`. Like
+         * `followers`, `null` when no counted creator has a synced number yet:
+         * unknown, never a zero (SC-008, T067).
+         */
+        commentsThisWeek: number | null;
         /** Count of rows in AGENCY_ROSTER_NEEDS_ATTENTION_STATES. */
         needsAttention: number;
     };
     items: I_AgencyRosterRow[];
 }
+/**
+ * A coverage that ENDED recently, so the creator meeting the paywall again is
+ * told why (FR-014: "an honest message, never a silent loss of access").
+ */
+export interface I_SponsorshipEnded {
+    organizationName: string;
+    endedAt: string;
+}
 /** What a sponsored creator sees on their OWN subscription screen (FR-014). */
 export interface I_SponsoredBy {
     organizationName: string;
@@ -203,6 +307,106 @@ export interface I_SponsoredBy {
     /** Present once the sponsorship is ending: the date their plan runs to. */
     until?: string;
 }
+/** The card on file, as Stripe describes it. Never more than these four facts. */
+export interface I_AgencyPaymentMethod {
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+}
+/**
+ * One invoice. `amount` is Stripe's minor unit verbatim; the display edge
+ * formats it once, like every other price in the app.
+ */
+export interface I_AgencyInvoice {
+    id: string;
+    number: string | null;
+    date: string;
+    amount: number;
+    currency: string;
+    status: string;
+    pdfUrl?: string;
+    hostedUrl?: string;
+}
+/**
+ * One creator on an ACTIVE grant, with whether the agency covers their plan
+ * (FR-013b). `tier: null` is "not covered". `until` is set while a coverage is
+ * ending: it runs to the close of the period already paid for.
+ */
+export interface I_AgencyCoveredCreator {
+    grantId: string;
+    creator: {
+        id: string;
+        handle: string;
+    };
+    tier: SponsoredTier | null;
+    since?: string;
+    until?: string;
+}
+/**
+ * An ended relationship, for the past-creators history (FR-013b). `creator.id`
+ * is null once the creator's account was purged; the handle is the snapshot
+ * frozen at grant time.
+ */
+export interface I_AgencyPastCreator {
+    grantId: string;
+    creator: {
+        id: string | null;
+        handle: string;
+        displayName?: string;
+    };
+    endedAt: string;
+    endedBy: CreatorAccessGrantRevokedBy;
+    coveredUntil?: string;
+}
+/**
+ * Everything the owner's billing section and panel show (FR-013, FR-013b).
+ *
+ * `seats` is the ONE home of the billed quantity: the count of active grants.
+ * Covering a creator never changes it (clarify 2026-09-17), so nothing here
+ * derives a price from `covered`.
+ *
+ * `price` is null when the seat product is not configured in this deployment
+ * (T031, the money gate); the screen says so rather than inventing a number.
+ * `nextInvoice` is Stripe's own preview, so a coupon is already applied to it.
+ */
+export interface I_AgencyBilling {
+    subscriptionStatus: AgencySubscriptionStatus;
+    /** Creators with an active grant. */
+    seats: number;
+    /**
+     * What Stripe bills: `max(1, seats)`. An agency with no creators yet still
+     * pays for one seat, and the screen must say the number Stripe charges.
+     */
+    billedSeats: number;
+    price: {
+        amount: number;
+        currency: string;
+        interval: string;
+    } | null;
+    currentPeriodEnd?: string;
+    cancelAtPeriodEnd?: boolean;
+    nextInvoice?: {
+        amount: number;
+        currency: string;
+        date: string;
+    };
+    discount?: {
+        name?: string;
+        percentOff?: number;
+        amountOff?: number;
+    };
+    paymentMethod?: I_AgencyPaymentMethod;
+    billingDetails?: {
+        name?: string;
+        email?: string;
+        country?: string;
+        taxId?: string;
+    };
+    invoices: I_AgencyInvoice[];
+    covered: I_AgencyCoveredCreator[];
+    pastCreators: I_AgencyPastCreator[];
+}
 /**
  * Every DTO below carries class-validator decorators and a constructor that
  * survives being called with nothing.
@@ -264,10 +468,50 @@ export declare class AgencyDiscoverQueryDto {
     constructor(data?: Partial<AgencyDiscoverQueryDto>);
 }
 export declare class AgencyAccessRequestDto {
+    /**
+     * A user id: a UUID or a Firebase uid (letters, digits, hyphens). It was
+     * `@IsUUID()` until US5 was built, which refused most real creators — their
+     * ids are Firebase uids.
+     */
     userId: string;
     scopes: I_AgencyGrantScope[];
     constructor(data?: Partial<AgencyAccessRequestDto>);
 }
+/** `PATCH /users/me/agency-discoverable` — "Let agencies find me" (FR-015). */
+export declare class UpdateAgencyDiscoverableDto {
+    discoverable: boolean;
+    /**
+     * NO default: a required boolean that defaults to false lets an empty body
+     * through validation and reach the database as `undefined` (review M7).
+     */
+    constructor(data?: Partial<UpdateAgencyDiscoverableDto>);
+}
+/**
+ * One discover hit: the public handle and the platforms, NEVER a metric and
+ * never a grant flag, so the payload cannot tell a caller whether it already
+ * holds the creator (FR-015). `userId` is what the request is sent for.
+ */
+export interface I_AgencyDiscoverHit {
+    userId: string;
+    handle: string;
+    platforms: PublishPlatform[];
+    /**
+     * The platform whose username matched. Absent on an e-mail match. Two hits
+     * with the same handle are two different people (@mark on YouTube, another
+     * @mark on Instagram), and this is what tells them apart (T068).
+     */
+    matchedPlatform?: PublishPlatform;
+}
+/**
+ * `POST /agency/roster/discover` — the SAME shape and status for every case:
+ * discoverable exact matches, a non-discoverable account, a partial match and
+ * no account at all (SC-009). A miss is `{ results: [] }`, never a 404. An
+ * exact handle held by several findable creators returns each of them, one
+ * row per person (Maciej, 2026-09-26, T068); an e-mail matches one person.
+ */
+export interface I_AgencyDiscoverResult {
+    results: I_AgencyDiscoverHit[];
+}
 export declare class AdminSetOrganizationStatusDto {
     status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
     /** Required on reject — a rejected applicant is shown this (FR-002). The

package/dist/types/agency.js

@@ -9,7 +9,7 @@ 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.AdminSetOrganizationStatusDto = exports.AgencyAccessRequestDto = exports.AgencyDiscoverQueryDto = exports.SponsorCreatorDto = exports.UpdateGrantScopesDto = exports.AcceptGrantDto = exports.AcceptAgencyMemberInviteDto = exports.RedeemAgencyInviteDto = exports.InviteAgencyMemberDto = exports.CreateAgencyOrganizationDto = exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = exports.AGENCY_ROSTER_ROW_STATES = exports.CREATOR_ACCESS_GRANT_STATES = exports.AGENCY_ORGANIZATION_STATUSES = exports.isAgencyGrantScope = exports.AGENCY_GRANT_SCOPES = exports.AGENCY_ROUTE_PATHS = void 0;
+exports.AdminSetOrganizationStatusDto = exports.UpdateAgencyDiscoverableDto = exports.AgencyAccessRequestDto = exports.AgencyDiscoverQueryDto = exports.SponsorCreatorDto = exports.UpdateGrantScopesDto = exports.AcceptGrantDto = exports.AcceptAgencyMemberInviteDto = exports.RedeemAgencyInviteDto = exports.InviteAgencyMemberDto = exports.CreateAgencyOrganizationDto = exports.AGENCY_ROSTER_METRICS_STATES = exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = exports.AGENCY_ROSTER_ROW_STATES = exports.AGENCY_REQUEST_CODES = exports.CREATOR_ACCESS_GRANT_STATES = exports.AGENCY_ORGANIZATION_STATUSES = exports.isAgencyGrantScope = exports.AGENCY_GRANT_SCOPES = exports.AGENCY_ROUTE_PATHS = void 0;
 const class_validator_1 = require("class-validator");
 // ── Cross-repo route constants ───────────────────────────────────────────────
 /**
@@ -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 ───────────────────────────────────────────────────────────────────
 /**
@@ -89,6 +91,16 @@ exports.CREATOR_ACCESS_GRANT_STATES = [
     'expired',
     'revoked',
 ];
+/**
+ * Outcomes of discovery and requests that are not refusals of access, sent as
+ * codes so the screen composes the sentence in the reader's language (FR-019,
+ * review M4). A 429 carries `{ code, limit, windowMinutes }`.
+ */
+exports.AGENCY_REQUEST_CODES = {
+    RATE_LIMITED: 'agency-rate-limited',
+    REQUEST_EXPIRED: 'agency-request-expired',
+    REQUEST_ANSWERED: 'agency-request-answered',
+};
 // ── Roster ───────────────────────────────────────────────────────────────────
 /**
  * Roster row states, DECLARED IN PRECEDENCE ORDER (data-model §Derived).
@@ -104,6 +116,13 @@ exports.AGENCY_ROSTER_ROW_STATES = [
     'lapsed',
     /** the creator has no live platform connection */
     'disconnected',
+    /**
+     * shared within the last 24 hours and not synced yet: the first daily sync
+     * has not run. Not stale, and not something the agency can act on (T067,
+     * the 2026-09-26 UI run: a creator who agreed a minute ago read as
+     * "needs attention").
+     */
+    'syncing',
     /** no successful daily sync in 24 hours (FR-011, Jan 2026-09-21) */
     'stale',
     'active',
@@ -120,6 +139,22 @@ exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = [
     'disconnected',
     'stale',
 ];
+/**
+ * The rows that carry numbers — ONE home for "which creators' numbers may the
+ * agency see on the roster" (decided 2026-09-24, review M1/M2).
+ *
+ * Only a row whose card OPENS carries `metrics` and counts in the followers,
+ * followers-delta and comments totals: `active`, and `stale` (the card opens;
+ * the numbers are as old as `lastSyncAt` says). A `lapsed` creator's reads are
+ * refused on the card, so their numbers must not reach the agency through the
+ * roster instead; a `disconnected` creator has nothing live to count; a
+ * `requested` creator has shared nothing yet.
+ */
+exports.AGENCY_ROSTER_METRICS_STATES = [
+    'syncing',
+    'stale',
+    'active',
+];
 // ── DTOs ─────────────────────────────────────────────────────────────────────
 /**
  * Every DTO below carries class-validator decorators and a constructor that
@@ -272,7 +307,8 @@ class AgencyAccessRequestDto {
 }
 exports.AgencyAccessRequestDto = AgencyAccessRequestDto;
 __decorate([
-    (0, class_validator_1.IsUUID)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Za-z0-9-]{1,128}$/),
     __metadata("design:type", String)
 ], AgencyAccessRequestDto.prototype, "userId", void 0);
 __decorate([
@@ -281,6 +317,22 @@ __decorate([
     (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
     __metadata("design:type", Array)
 ], AgencyAccessRequestDto.prototype, "scopes", void 0);
+/** `PATCH /users/me/agency-discoverable` — "Let agencies find me" (FR-015). */
+class UpdateAgencyDiscoverableDto {
+    /**
+     * NO default: a required boolean that defaults to false lets an empty body
+     * through validation and reach the database as `undefined` (review M7).
+     */
+    constructor(data) {
+        if (data?.discoverable !== undefined)
+            this.discoverable = data.discoverable;
+    }
+}
+exports.UpdateAgencyDiscoverableDto = UpdateAgencyDiscoverableDto;
+__decorate([
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], UpdateAgencyDiscoverableDto.prototype, "discoverable", void 0);
 class AdminSetOrganizationStatusDto {
     constructor(data) {
         this.status = data?.status ?? 'approved';

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/dist/types/scheduling/I_SchedulingProUpgrade.d.ts

@@ -4,13 +4,14 @@
  * Covers subscription tier state, Stripe checkout flows,
  * and the customer portal redirect.
  */
+import type { I_SponsoredBy, I_SponsorshipEnded } from '../agency';
 export type SchedulingSubscriptionTier = 'free' | 'starter' | 'pro';
 export type SchedulingSubscriptionStatus = 'active' | 'canceled' | 'expired';
 /**
  * Constructor input. Takes `maxAccounts`, or the deprecated `maxPlatforms` so
  * code written against 1.40.0 keeps compiling; either way both fields are set.
  */
-export type SchedulingSubscriptionInfoInput = Pick<SchedulingSubscriptionInfoDTO, 'tier' | 'status' | 'expiresAt'> & ({
+export type SchedulingSubscriptionInfoInput = Pick<SchedulingSubscriptionInfoDTO, 'tier' | 'status' | 'expiresAt'> & Partial<Pick<SchedulingSubscriptionInfoDTO, 'sponsoredBy' | 'sponsorshipEnded'>> & ({
     maxAccounts: number;
     maxPlatforms?: number;
 } | {
@@ -32,6 +33,14 @@ export declare class SchedulingSubscriptionInfoDTO {
      * Read `maxAccounts`. Always equal to it; removed in a later release.
      */
     maxPlatforms: number;
+    /**
+     * Present only while an agency covers this creator's plan (spec 175 FR-014).
+     * `until` appears once the sponsorship is ending: the date the plan runs to.
+     * Absent — never null — for everyone else, so "not sponsored" has one shape.
+     */
+    sponsoredBy?: I_SponsoredBy;
+    /** Present only when a coverage ended recently and nothing replaced it. Absent otherwise. */
+    sponsorshipEnded?: I_SponsorshipEnded;
     constructor(data: SchedulingSubscriptionInfoInput);
 }
 /**

package/dist/types/scheduling/I_SchedulingProUpgrade.js

@@ -19,6 +19,10 @@ class SchedulingSubscriptionInfoDTO {
         this.expiresAt = data.expiresAt;
         this.maxAccounts = maxAccounts;
         this.maxPlatforms = maxAccounts;
+        if (data.sponsoredBy)
+            this.sponsoredBy = data.sponsoredBy;
+        if (data.sponsorshipEnded)
+            this.sponsorshipEnded = data.sponsorshipEnded;
     }
 }
 exports.SchedulingSubscriptionInfoDTO = SchedulingSubscriptionInfoDTO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.44.1",
+  "version": "1.49.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -51,7 +51,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej G\u00f3rski@ad2.app",
+  "author": "Maciej Górski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

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)) {

package/src/analytics/index.ts

@@ -191,6 +191,23 @@ export const EVENTS = {
   // creators an agency went looking for.
   AGENCY_DISCOVER_SEARCHED: 'agency_discover_searched',
   AGENCY_ACCESS_REQUESTED: 'agency_access_requested',
+  // The campaign loop (175 US7). Server-owned: each is captured in the act's
+  // own transaction path, under the ACTOR's distinct id.
+  AGENCY_CAMPAIGN_CREATED: 'agency_campaign_created',
+  AGENCY_CAMPAIGN_CREATOR_INVITED: 'agency_campaign_creator_invited',
+  AGENCY_CAMPAIGN_JOINED: 'agency_campaign_joined',
+  AGENCY_CAMPAIGN_DECLINED: 'agency_campaign_declined',
+  AGENCY_CAMPAIGN_LEFT: 'agency_campaign_left',
+  AGENCY_CAMPAIGN_CREATOR_REMOVED: 'agency_campaign_creator_removed',
+  AGENCY_CAMPAIGN_OFFER_SENT: 'agency_campaign_offer_sent',
+  AGENCY_CAMPAIGN_OFFER_ACTED: 'agency_campaign_offer_acted',
+  AGENCY_CAMPAIGN_MATERIAL_UPLOADED: 'agency_campaign_material_uploaded',
+  AGENCY_CAMPAIGN_MATERIAL_REVIEWED: 'agency_campaign_material_reviewed',
+  AGENCY_CAMPAIGN_PUBLISHED: 'agency_campaign_published',
+  AGENCY_CAMPAIGN_MILESTONE_CONFIRMED: 'agency_campaign_milestone_confirmed',
+  // 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',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -427,6 +444,11 @@ export interface AgencyEventProperties {
   creator_user_id?: string;
 }
 
+/** A campaign-loop event: the agency event plus the campaign it concerns. */
+export interface AgencyCampaignEventProperties extends AgencyEventProperties {
+  campaign_id: string;
+}
+
 export interface EventProperties {
   [EVENTS.LANDING_CTA_CLICKED]: {
     location:
@@ -675,6 +697,23 @@ export interface EventProperties {
   // `matched` only. The query itself is never sent (FR-015).
   [EVENTS.AGENCY_DISCOVER_SEARCHED]: AgencyEventProperties & { matched: boolean };
   [EVENTS.AGENCY_ACCESS_REQUESTED]: AgencyEventProperties;
+  // The campaign loop (175 US7): which campaign, and for an act, which one.
+  // Never a price: an amount in analytics is a creator's rate in a dashboard.
+  [EVENTS.AGENCY_CAMPAIGN_CREATED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_INVITED]: AgencyCampaignEventProperties & { with_access_request: boolean };
+  [EVENTS.AGENCY_CAMPAIGN_JOINED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_DECLINED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_LEFT]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_REMOVED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_SENT]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_ACTED]: AgencyCampaignEventProperties & { action: 'accept' | 'counter' | 'confirm' | 'reject' };
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_UPLOADED]: AgencyCampaignEventProperties & { version: number };
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_REVIEWED]: AgencyCampaignEventProperties & { action: 'approve' | 'request_changes' | 'reject' };
+  [EVENTS.AGENCY_CAMPAIGN_PUBLISHED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_MILESTONE_CONFIRMED]: AgencyCampaignEventProperties;
+  // 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 };
 }
 
 /** Canonical person property keys (set via identify / $set). */

package/src/types/I_AccessDenial.ts

@@ -82,6 +82,25 @@ export const ACCESS_DENIAL_CODES = {
    * per person, FR-004). Names the case and NOTHING else about that account.
    */
   AGENCY_ALREADY_IN_ORGANIZATION: "agency-already-in-organization",
+  /**
+   * The owner invited an address that is ALREADY on this organization's team,
+   * themselves included (T063). A different case from the one above: the owner
+   * is told this person is already in, not that they belong elsewhere.
+   */
+  AGENCY_ALREADY_MEMBER: "agency-already-member",
+  /**
+   * The owner tried to cover a creator who pays for their own plan. Covering
+   * is for a creator without a paid plan (US4 scenario 3); covering a payer
+   * would leave them paying for what the agency also pays for (T066).
+   */
+  AGENCY_CREATOR_PAYS_OWN_PLAN: "agency-creator-pays-own-plan",
+  /**
+   * A creator whose plan an agency covers asked for the billing portal, and
+   * has no Stripe customer of their own to open it for (FR-014). The body
+   * names the covering agency; the client hides the portal button instead of
+   * showing a Stripe error.
+   */
+  SPONSORED_NO_PORTAL: "sponsored-no-portal",
 } as const;
 
 export type AccessDenialCode =

package/src/types/I_Offer.ts

@@ -41,6 +41,8 @@ export enum I_OfferStatus {
   AGENCY_NEGOTIATED = 'agencyNegotiated',
   CONFIRMED = 'confirmed',
   ALTERNATIVE_SUGGESTED = 'alternativeSuggested',
+  /** The creator left the campaign before the offer was confirmed (spec 175 US7). Added, never renamed: Postgres enums only grow. */
+  WITHDRAWN = 'withdrawn',
 }
 
 export declare class I_OfferGetDTO {

package/src/types/access-denial.test.ts

@@ -87,7 +87,7 @@ test('every AGENCY code is namespaced, so a new domain cannot shadow an old wall
 		key.startsWith('AGENCY_'),
 	);
 
-	assert.equal(agencyCodes.length, 12);
+	assert.equal(agencyCodes.length, 14);
 	for (const [, value] of agencyCodes) {
 		assert.match(value, /^agency-/, `un-namespaced agency code: ${value}`);
 	}