ad2app-lib 1.49.0 → 1.59.0

package/dist/types/dealroom.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * Dealroom (spec 148): only what spec 175 has no concept of.
+ *
+ * The organization, membership, grant, campaign, offer loop, materials,
+ * threads and pots are 175's (`agency*.ts`); 148 adds unions there and keeps
+ * this file for the open listing, matching, the coarse creator row, its codes,
+ * the dormant money layer and the commission lane.
+ *
+ * The money types below are DORMANT: the backend refuses every money act with
+ * `dealroom-money-disabled` until the money release (FR-027). Their state
+ * lists mirror data-model.md's state machine exactly.
+ *
+ * See specs/148-dealroom/contracts/lib-types.md.
+ */
+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.DealroomCalendarQueryDto = exports.DEALROOM_CALENDAR_MAX_DAYS = exports.DEALROOM_CALENDAR_KINDS = exports.ReviewCommissionAdSpaceDto = exports.COMMISSION_AD_SPACE_DECISIONS = exports.COMMISSION_AD_SPACE_STATES = exports.COMMISSION_JOIN_STATES = exports.COMMISSION_MATERIAL_KINDS = exports.COMMISSION_LINK_MODES = exports.COMMISSION_LINK_STATES = exports.COMMISSION_OFFER_STATES = exports.COMMISSION_NETWORKS = exports.UpsertPayoutProfileDto = exports.PAYOUT_PROFILE_FIELDS = exports.DEAL_MONEY_ACTIONS = exports.StartDealPaymentDto = exports.DEAL_PAYMENT_METHODS = exports.CreateDealContractDto = exports.DEAL_SIGNATURE_LEVELS = exports.DEAL_CONTRACT_STATES = exports.DEAL_CONTRACT_SOURCES = exports.DEALROOM_MONEY_EVENT_KINDS = exports.PAYOUT_LEDGER_STATES = exports.PAYOUT_LEDGER_SOURCES = exports.PAYOUT_BILLING_VARIANTS = exports.DEAL_PAYOUT_STATES = exports.DEAL_MONEY_STATES = exports.DEALROOM_CODES = exports.ApplyToDealroomListingDto = exports.DEALROOM_LISTING_STATES = exports.DEALROOM_PROFILE_FIELDS = exports.isCampaignVisibility = exports.CAMPAIGN_VISIBILITIES = void 0;
+const class_validator_1 = require("class-validator");
+const agency_1 = require("./agency");
+// ── Open listing ─────────────────────────────────────────────────────────────
+/** `private` is every 175 campaign today (members only); `open` is listed in the feed to matching creators. */
+exports.CAMPAIGN_VISIBILITIES = ['private', 'open'];
+const isCampaignVisibility = (value) => exports.CAMPAIGN_VISIBILITIES.includes(value);
+exports.isCampaignVisibility = isCampaignVisibility;
+/** The profile fields whose absence makes the feed `profile_incomplete` (FR-026). */
+exports.DEALROOM_PROFILE_FIELDS = ['country', 'niches'];
+// ── The organization's side of a listing (US3) ──────────────────────────────
+/**
+ * Derived, never stored: `draft` (175 isDraft) → `live` (open, not closed,
+ * before its deadline, a slot free) → `frozen` (live, and a creator has been
+ * invited or applied: only the deadline, the slots and closing may change) →
+ * `closed` (closed by the organization, past its deadline, or full).
+ */
+exports.DEALROOM_LISTING_STATES = ['draft', 'live', 'frozen', 'closed'];
+// ── Applying (US4) ───────────────────────────────────────────────────────────
+/**
+ * `POST /dealroom/listings/:campaignId/apply`. `scopes`: what the creator
+ * shares, a non-empty subset of the listing's `askedScopes`. An offer
+ * listing takes the opening price (`priceMinor` + `currency`); a pot listing
+ * takes the creator's own terms (`guaranteeMinor` + `ratePer1000Minor`).
+ */
+class ApplyToDealroomListingDto {
+    constructor(data) {
+        this.scopes = data?.scopes ?? [];
+        this.priceMinor = data?.priceMinor;
+        this.currency = data?.currency;
+        this.guaranteeMinor = data?.guaranteeMinor;
+        this.ratePer1000Minor = data?.ratePer1000Minor;
+    }
+}
+exports.ApplyToDealroomListingDto = ApplyToDealroomListingDto;
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(agency_1.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], ApplyToDealroomListingDto.prototype, "scopes", 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)
+], ApplyToDealroomListingDto.prototype, "priceMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Z]{3}$/),
+    __metadata("design:type", String)
+], ApplyToDealroomListingDto.prototype, "currency", 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)
+], ApplyToDealroomListingDto.prototype, "guaranteeMinor", 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)
+], ApplyToDealroomListingDto.prototype, "ratePer1000Minor", void 0);
+// ── Codes ────────────────────────────────────────────────────────────────────
+/** Refusal codes the frontend owes its own copy for (contracts/dealroom-api.md). */
+exports.DEALROOM_CODES = {
+    OFFER_FILLED: 'dealroom-offer-filled',
+    LISTING_FROZEN: 'dealroom-listing-frozen',
+    NEAR_MATCH_NOT_APPLIABLE: 'dealroom-near-match-not-appliable',
+    PROFILE_INCOMPLETE: 'dealroom-profile-incomplete',
+    BRAND_DOOR_CLOSED: 'dealroom-brand-door-closed',
+    BRAND_NO_ROSTER: 'dealroom-brand-no-roster',
+    DELEGATE_FORBIDDEN: 'dealroom-delegate-forbidden',
+    DELEGATE_OWN_DEAL: 'dealroom-delegate-own-deal',
+    /** A delegate never writes the creator's grant consent: joining with an access request, or an apply that would create or widen the grant's reads. */
+    DELEGATE_CONSENT_FORBIDDEN: 'dealroom-delegate-consent-forbidden',
+    /** The money switch is off: every money route and act answers 404 with this code (FR-027). Means nothing else. */
+    MONEY_DISABLED: 'dealroom-money-disabled',
+    /** Money on, but a value the act needs is not configured yet (e.g. the deal's deposit %). 422. */
+    CONFIG_MISSING: 'dealroom-config-missing',
+    /** Money on, but the platform contract template is still waiting for counsel: upload your own. 422. */
+    TEMPLATE_PENDING: 'dealroom-template-pending',
+    /** An open listing needs the organization's logo first (US2). 400. */
+    LOGO_REQUIRED: 'dealroom-logo-required',
+    CONTRACT_UNSIGNED: 'dealroom-contract-unsigned',
+    DEPOSIT_REQUIRED: 'dealroom-deposit-required',
+    NOT_FUNDED: 'dealroom-not-funded',
+    /** Money release: the agreed amount is under the fee config's minimum deal. */
+    DEAL_BELOW_MINIMUM: 'dealroom-deal-below-minimum',
+    /** Money release: that money act is not open at the deal's current step. */
+    MONEY_WRONG_STEP: 'dealroom-money-wrong-step',
+    /** Money release: the deal already has a contract out for signature or signed. */
+    CONTRACT_EXISTS: 'dealroom-contract-exists',
+    /** Money release: no guarantee is configured, or the claim is not open yet. */
+    GUARANTEE_UNAVAILABLE: 'dealroom-guarantee-unavailable',
+    /** Commission lane (2026-10-07): the creator's Admitad Ad Space is still under admin review; no link yet. */
+    COMMISSION_AD_SPACE_PENDING: 'commission-ad-space-pending',
+    /** Commission lane (2026-10-07): the creator's Admitad Ad Space was rejected or suspended; no Admitad link. */
+    COMMISSION_AD_SPACE_UNAVAILABLE: 'commission-ad-space-unavailable',
+    /** Admin: that decision is not open from the Ad Space's state (a suspended or rejected Ad Space is never re-registered under a new id). */
+    COMMISSION_AD_SPACE_DECISION_CLOSED: 'commission-ad-space-decision-closed',
+    /** The network did not answer a join or a registration; nothing was written. */
+    COMMISSION_NETWORK_UNAVAILABLE: 'commission-network-unavailable',
+};
+// ── Money (DORMANT until the money release) ──────────────────────────────────
+/**
+ * The deal's money state (FR-010), exactly data-model.md's machine:
+ *
+ *   awaiting_material → material_submitted → deposit_paid → funded → approved → published
+ *   deposit declined                → closed_unviewed
+ *   funded/approved, never published → refund_pending → refunded
+ *   delivered, never funded          → guarantee_claimed
+ *
+ * The payout after publication is its own column (DEAL_PAYOUT_STATES).
+ */
+exports.DEAL_MONEY_STATES = [
+    'awaiting_material',
+    'material_submitted',
+    'deposit_paid',
+    'funded',
+    'approved',
+    'published',
+    'closed_unviewed',
+    'refund_pending',
+    'refunded',
+    'guarantee_claimed',
+];
+exports.DEAL_PAYOUT_STATES = ['none', 'initiated', 'paid'];
+/** Derived from 175's settlement form (`invoice` → faktura_vat, `contract` → umowa_o_dzielo); `international` is 148's. */
+exports.PAYOUT_BILLING_VARIANTS = ['faktura_vat', 'umowa_o_dzielo', 'international'];
+exports.PAYOUT_LEDGER_SOURCES = ['deal', 'pot', 'commission'];
+/** Commission entries are `validated` only after the network pays us. */
+exports.PAYOUT_LEDGER_STATES = ['earned', 'validated', 'paid'];
+// ── Money release, wave 4 (DORMANT): contract step, deal money, payouts ──────
+/** The contract, money and payout kinds this release writes into 175's event log (FR-008a). */
+exports.DEALROOM_MONEY_EVENT_KINDS = [
+    'contract_sent',
+    'contract_signed',
+    'contract_declined',
+    'deposit_paid',
+    'deal_funded',
+    'deal_closed_unviewed',
+    'deal_refund_requested',
+    'deal_refunded',
+    'guarantee_claimed',
+    'payout_initiated',
+    'payout_paid',
+];
+exports.DEAL_CONTRACT_SOURCES = ['template', 'uploaded'];
+/** `draft` again after a signer declines; `signed` once every party signed (the e-sign provider's word). */
+exports.DEAL_CONTRACT_STATES = ['draft', 'sent', 'signed'];
+/** SES by default, QES as an option (research R2; counsel point 3 may require QES for some documents). */
+exports.DEAL_SIGNATURE_LEVELS = ['SES', 'QES'];
+/**
+ * `POST /agency/campaigns/:id/members/:memberId/contract` (organization side).
+ * `template`: the form fields (deliverables default to the brief's, the rate is
+ * the agreed price). `uploaded`: the organization's own file, base64.
+ */
+class CreateDealContractDto {
+    constructor(data) {
+        this.source = data?.source ?? 'template';
+        this.signatureLevel = data?.signatureLevel;
+        this.deliverables = data?.deliverables;
+        this.draftDueAt = data?.draftDueAt;
+        this.liveByAt = data?.liveByAt;
+        this.licenceMonths = data?.licenceMonths;
+        this.paidPromoMonths = data?.paidPromoMonths;
+        this.fileName = data?.fileName;
+        this.fileBase64 = data?.fileBase64;
+    }
+}
+exports.CreateDealContractDto = CreateDealContractDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.DEAL_CONTRACT_SOURCES),
+    __metadata("design:type", String)
+], CreateDealContractDto.prototype, "source", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.DEAL_SIGNATURE_LEVELS),
+    __metadata("design:type", String)
+], CreateDealContractDto.prototype, "signatureLevel", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMaxSize)(20),
+    (0, class_validator_1.IsString)({ each: true }),
+    (0, class_validator_1.MaxLength)(500, { each: true }),
+    __metadata("design:type", Array)
+], CreateDealContractDto.prototype, "deliverables", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], CreateDealContractDto.prototype, "draftDueAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], CreateDealContractDto.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)
+], CreateDealContractDto.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)
+], CreateDealContractDto.prototype, "paidPromoMonths", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], CreateDealContractDto.prototype, "fileName", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], CreateDealContractDto.prototype, "fileBase64", void 0);
+/** Card (PaymentIntent, confirmed in the browser) or invoice (a Stripe invoice the organization pays by transfer). */
+exports.DEAL_PAYMENT_METHODS = ['card', 'invoice'];
+/** `POST /agency/campaigns/:id/members/:memberId/deal/deposit|fund`. Big sums go by invoice whatever is asked. */
+class StartDealPaymentDto {
+    constructor(data) {
+        this.method = data?.method;
+    }
+}
+exports.StartDealPaymentDto = StartDealPaymentDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.DEAL_PAYMENT_METHODS),
+    __metadata("design:type", String)
+], StartDealPaymentDto.prototype, "method", void 0);
+/** The money acts a deal view may offer; the server decides which, per side and step. */
+exports.DEAL_MONEY_ACTIONS = ['send_contract', 'pay_deposit', 'decline_deposit', 'fund', 'refund', 'claim_guarantee'];
+/** What the first payout needs and is missing; the provider's KYC runs behind the form and is never a field. */
+exports.PAYOUT_PROFILE_FIELDS = ['settlement_form', 'nip', 'tax_statement', 'intl_billing_data', 'iban', 'payout_currency'];
+/**
+ * `PUT /dealroom/payouts/profile`. The track is NOT here: it is read from the
+ * 175 settlement form. `international` picks the international variant.
+ */
+class UpsertPayoutProfileDto {
+    constructor(data) {
+        this.international = data?.international;
+        this.nip = data?.nip;
+        this.taxStatement = data?.taxStatement;
+        this.intlBillingData = data?.intlBillingData;
+        this.iban = data?.iban ?? '';
+        this.payoutCurrency = data?.payoutCurrency ?? '';
+    }
+}
+exports.UpsertPayoutProfileDto = UpsertPayoutProfileDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], UpsertPayoutProfileDto.prototype, "international", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[0-9]{10}$/),
+    __metadata("design:type", String)
+], UpsertPayoutProfileDto.prototype, "nip", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2000),
+    __metadata("design:type", String)
+], UpsertPayoutProfileDto.prototype, "taxStatement", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsObject)(),
+    __metadata("design:type", Object)
+], UpsertPayoutProfileDto.prototype, "intlBillingData", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Z]{2}[0-9]{2}(?:\s?[A-Z0-9]){11,30}$/),
+    __metadata("design:type", String)
+], UpsertPayoutProfileDto.prototype, "iban", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Z]{3}$/),
+    __metadata("design:type", String)
+], UpsertPayoutProfileDto.prototype, "payoutCurrency", void 0);
+// ── Commission lane ──────────────────────────────────────────────────────────
+exports.COMMISSION_NETWORKS = ['awin', 'admitad'];
+exports.COMMISSION_OFFER_STATES = ['live', 'paused', 'gone'];
+exports.COMMISSION_LINK_STATES = ['active', 'suspended'];
+/**
+ * `subnetwork`: minted from OUR publisher account with the creator's own
+ * attribution (Awin `clickref` = creator id; Admitad = the creator's registered
+ * Ad Space). `deeplink`: the fallback while a network's subnetwork mode is off,
+ * a plain link to the programme on the network, carrying no attribution of ours.
+ */
+exports.COMMISSION_LINK_MODES = ['subnetwork', 'deeplink'];
+/** An advertiser creative as the network feed carries it (2026-10-07). */
+exports.COMMISSION_MATERIAL_KINDS = ['logo', 'banner', 'landing_preview', 'coupon'];
+/** `POST /dealroom/commission/offers/:id/join`: what the join produced. */
+exports.COMMISSION_JOIN_STATES = ['link', 'deeplink', 'ad_space_pending'];
+// ── Commission lane: the Admitad Ad Space per creator (2026-10-07) ───────────
+/**
+ * One static Ad Space per creator (Admitad Subnetwork Code of Conduct §3.1/§5):
+ * created `pending_review` on the first Admitad join, `registered` through the
+ * Partner networks API after an admin approves, or `rejected` / `suspended`.
+ * Its id is never rotated, deleted or reassigned.
+ */
+exports.COMMISSION_AD_SPACE_STATES = ['pending_review', 'registered', 'rejected', 'suspended'];
+exports.COMMISSION_AD_SPACE_DECISIONS = ['approve', 'reject', 'suspend'];
+/** `PATCH /admin/dealroom/commission/ad-spaces/:id`. */
+class ReviewCommissionAdSpaceDto {
+    constructor(data) {
+        this.decision = data?.decision;
+    }
+}
+exports.ReviewCommissionAdSpaceDto = ReviewCommissionAdSpaceDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.COMMISSION_AD_SPACE_DECISIONS),
+    __metadata("design:type", String)
+], ReviewCommissionAdSpaceDto.prototype, "decision", void 0);
+// ── The calendar (US9, T041) ─────────────────────────────────────────────────
+/**
+ * What a deal date on the creator's calendar is. No second deadline store:
+ * `milestone` is a 175 milestone (`campaign-deadlines`, the creator's own or
+ * campaign-wide); the pot dates are the US9 schedule; `publish_at` is the
+ * agreed publication time (a pot entry's, or an offer deal's, T067).
+ */
+exports.DEALROOM_CALENDAR_KINDS = [
+    'milestone',
+    'application_deadline',
+    'materials_due',
+    'publication_due',
+    'publish_at',
+    'bonus_ends',
+    'keep_up_ends',
+];
+/** The calendar window: both ends required, at most DEALROOM_CALENDAR_MAX_DAYS apart. */
+exports.DEALROOM_CALENDAR_MAX_DAYS = 400;
+class DealroomCalendarQueryDto {
+    constructor(data) {
+        this.from = data?.from ?? '';
+        this.to = data?.to ?? '';
+    }
+}
+exports.DealroomCalendarQueryDto = DealroomCalendarQueryDto;
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], DealroomCalendarQueryDto.prototype, "from", void 0);
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], DealroomCalendarQueryDto.prototype, "to", void 0);

package/dist/types/index.d.ts

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

package/dist/types/index.js

@@ -58,6 +58,9 @@ __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);
+// ── Dealroom (spec 148): what 175 has no concept of ──────────────────────────
+__exportStar(require("./dealroom"), exports);
 // ── Access control ────────────────────────────────────────────────────────────
 __exportStar(require("./I_AccessDenial"), exports);

package/package.json

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

package/src/analytics/index.test.ts

@@ -236,11 +236,33 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.AGENCY_CAMPAIGN_MILESTONE_CONFIRMED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1" },
   [EVENTS.AGENCY_THREAD_STARTED]: { organization_id: "org-1", actor_role: "member", thread_id: "t-1" },
   [EVENTS.AGENCY_THREAD_MESSAGE_SENT]: { organization_id: "org-1", actor_role: "creator", thread_id: "t-1" },
+  [EVENTS.AGENCY_POT_APPLIED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_APPLICATION_DECIDED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", action: "accept" },
+  [EVENTS.AGENCY_POT_REFILLED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_MOVED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_PUBLISH_TIME_CONFIRMED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_PUBLISHED]: { organization_id: "org-1", actor_role: "creator", campaign_id: "c-1" },
+  [EVENTS.AGENCY_POT_BONUS_HELD]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", reason: "jump" },
+  [EVENTS.AGENCY_POT_BONUS_DECIDED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1", action: "cap" },
+  [EVENTS.AGENCY_POT_REMOVAL_DECIDED]: { organization_id: "org-1", actor_role: "owner", campaign_id: "c-1", decision: "withhold_base" },
+  [EVENTS.AGENCY_POT_EXPORTED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1", format: "xlsx" },
+  [EVENTS.AGENCY_POT_FILE_UPLOADED]: { organization_id: "org-1", actor_role: "member", campaign_id: "c-1" },
+  // Dealroom (148)
+  [EVENTS.DEALROOM_FEED_VIEWED]: { state: "ok", listing_count: 3, broadened: true, near_match_count: 1 },
+  [EVENTS.DEALROOM_LISTING_OPENED]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer" },
+  [EVENTS.DEALROOM_APPLIED]: { campaign_id: "c-1", organization_id: "org-1", kind: "pot", acting_grant_id: "g-1" },
+  [EVENTS.DEALROOM_BROADEN_TOGGLED]: { broadened: false },
+  [EVENTS.DEALROOM_NEAR_MATCH_SHOWN]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer", gap: "followers" },
+  [EVENTS.DEALROOM_NEAR_MATCH_PROMOTED]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer" },
+  [EVENTS.DEALROOM_CONNECT_FROM_NEAR_MATCH_CLICKED]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer", platform: "tiktok" },
+  [EVENTS.DEALROOM_DELEGATION_CHANGED]: { organization_id: "org-1", actor_role: "creator", grant_id: "g-1", action: "granted" },
+  [EVENTS.DEALROOM_DEAL_MONEY_STATE_CHANGED]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer", money_state: "deposit_paid" },
+  [EVENTS.DEALROOM_DEAL_PAYOUT_STATE_CHANGED]: { campaign_id: "c-1", organization_id: "org-1", kind: "offer", payout_state: "initiated" },
 };
 
 test("no agency event may carry the discover query — only whether it matched (FR-015)", () => {
   const agencyEvents = Object.values(EVENTS).filter((name) => name.startsWith("agency_"));
-  assert.equal(agencyEvents.length, 29, "the 175 set is 15 roster events, 12 campaign-loop events (US7) and 2 thread events (US8)");
+  assert.equal(agencyEvents.length, 40, "the 175 set is 15 roster events, 12 campaign-loop events (US7), 2 thread events (US8) and 11 pot events (US9)");
   for (const name of agencyEvents) {
     const props = EVENT_PROPERTY_WITNESS[name as keyof typeof EVENT_PROPERTY_WITNESS];
     for (const key of Object.keys(props)) {

package/src/analytics/index.ts

@@ -10,7 +10,9 @@
  */
 
 import type { AccessDenialCode } from "../types/I_AccessDenial";
-import type { SponsoredTier } from "../types/agency";
+import type { CreatorAccessGrantOrigin, SponsoredTier } from "../types/agency";
+import type { AgencyCampaignKind, CampaignPlatform } from "../types/agency-campaigns";
+import type { DealMoneyState, DealPayoutState } from "../types/dealroom";
 
 /** Canonical PostHog event names. */
 export const EVENTS = {
@@ -208,6 +210,32 @@ export const EVENTS = {
   // Threads (175 US8). Never the message body: a conversation is not analytics.
   AGENCY_THREAD_STARTED: 'agency_thread_started',
   AGENCY_THREAD_MESSAGE_SENT: 'agency_thread_message_sent',
+  // Pot campaigns (175 US9). Never an amount: the pot's economics are the agency's.
+  AGENCY_POT_APPLIED: 'agency_pot_applied',
+  AGENCY_POT_APPLICATION_DECIDED: 'agency_pot_application_decided',
+  AGENCY_POT_REFILLED: 'agency_pot_refilled',
+  AGENCY_POT_MOVED: 'agency_pot_moved',
+  AGENCY_POT_PUBLISH_TIME_CONFIRMED: 'agency_pot_publish_time_confirmed',
+  AGENCY_POT_PUBLISHED: 'agency_pot_published',
+  AGENCY_POT_BONUS_HELD: 'agency_pot_bonus_held',
+  AGENCY_POT_BONUS_DECIDED: 'agency_pot_bonus_decided',
+  AGENCY_POT_REMOVAL_DECIDED: 'agency_pot_removal_decided',
+  AGENCY_POT_EXPORTED: 'agency_pot_exported',
+  AGENCY_POT_FILE_UPLOADED: 'agency_pot_file_uploaded',
+  // Dealroom (148): only what 175 has no event for. Offer, material and thread
+  // acts on a Dealroom deal reuse the AGENCY_CAMPAIGN_* / AGENCY_THREAD_* events.
+  DEALROOM_FEED_VIEWED: 'dealroom_feed_viewed',
+  DEALROOM_LISTING_OPENED: 'dealroom_listing_opened',
+  DEALROOM_APPLIED: 'dealroom_applied',
+  DEALROOM_BROADEN_TOGGLED: 'dealroom_broaden_toggled',
+  DEALROOM_NEAR_MATCH_SHOWN: 'dealroom_near_match_shown',
+  DEALROOM_NEAR_MATCH_PROMOTED: 'dealroom_near_match_promoted',
+  // The near-match's missing-platform nudge, clicked through to Connect (US11).
+  DEALROOM_CONNECT_FROM_NEAR_MATCH_CLICKED: 'dealroom_connect_from_near_match_clicked',
+  DEALROOM_DELEGATION_CHANGED: 'dealroom_delegation_changed',
+  // Money release (dormant until then): state moves, never an amount.
+  DEALROOM_DEAL_MONEY_STATE_CHANGED: 'dealroom_deal_money_state_changed',
+  DEALROOM_DEAL_PAYOUT_STATE_CHANGED: 'dealroom_deal_payout_state_changed',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -433,7 +461,7 @@ export interface AgencyEventProperties {
   /** Present once a specific consent is the subject of the act. */
   grant_id?: string;
   actor_role: 'owner' | 'member' | 'creator' | 'admin' | 'system';
-  origin?: 'invite_link' | 'agency_request';
+  origin?: CreatorAccessGrantOrigin;
   terms_version?: string;
   tier?: SponsoredTier;
   /**
@@ -449,6 +477,17 @@ export interface AgencyCampaignEventProperties extends AgencyEventProperties {
   campaign_id: string;
 }
 
+/**
+ * A Dealroom listing event (148): which listing, of which organization and
+ * kind. Never a price and never a follower count: what a creator saw and
+ * applied to, not what they earn.
+ */
+export interface DealroomListingEventProperties {
+  campaign_id: string;
+  organization_id: string;
+  kind: AgencyCampaignKind;
+}
+
 export interface EventProperties {
   [EVENTS.LANDING_CTA_CLICKED]: {
     location:
@@ -714,6 +753,34 @@ export interface EventProperties {
   // Threads (175 US8): which thread, never its content.
   [EVENTS.AGENCY_THREAD_STARTED]: AgencyEventProperties & { thread_id: string };
   [EVENTS.AGENCY_THREAD_MESSAGE_SENT]: AgencyEventProperties & { thread_id: string };
+  [EVENTS.AGENCY_POT_APPLIED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_APPLICATION_DECIDED]: AgencyCampaignEventProperties & { action: 'accept' | 'decline' };
+  [EVENTS.AGENCY_POT_REFILLED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_MOVED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_PUBLISH_TIME_CONFIRMED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_PUBLISHED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_POT_BONUS_HELD]: AgencyCampaignEventProperties & { reason: 'jump' | 'paid_delivery' };
+  [EVENTS.AGENCY_POT_BONUS_DECIDED]: AgencyCampaignEventProperties & { action: 'approve' | 'cap' | 'message' };
+  [EVENTS.AGENCY_POT_REMOVAL_DECIDED]: AgencyCampaignEventProperties & { decision: 'keep_base' | 'withhold_base' };
+  [EVENTS.AGENCY_POT_EXPORTED]: AgencyCampaignEventProperties & { format: 'csv' | 'xlsx' | 'report' };
+  [EVENTS.AGENCY_POT_FILE_UPLOADED]: AgencyCampaignEventProperties;
+  // Dealroom (148).
+  [EVENTS.DEALROOM_FEED_VIEWED]: {
+    state: 'ok' | 'profile_incomplete';
+    listing_count: number;
+    broadened: boolean;
+    near_match_count?: number;
+  };
+  [EVENTS.DEALROOM_LISTING_OPENED]: DealroomListingEventProperties;
+  // `acting_grant_id` when a delegate applied for the creator.
+  [EVENTS.DEALROOM_APPLIED]: DealroomListingEventProperties & { acting_grant_id?: string };
+  [EVENTS.DEALROOM_BROADEN_TOGGLED]: { broadened: boolean };
+  [EVENTS.DEALROOM_NEAR_MATCH_SHOWN]: DealroomListingEventProperties & { gap: 'followers' | 'missing_platform' };
+  [EVENTS.DEALROOM_NEAR_MATCH_PROMOTED]: DealroomListingEventProperties;
+  [EVENTS.DEALROOM_CONNECT_FROM_NEAR_MATCH_CLICKED]: DealroomListingEventProperties & { platform: CampaignPlatform };
+  [EVENTS.DEALROOM_DELEGATION_CHANGED]: AgencyEventProperties & { action: 'granted' | 'revoked' };
+  [EVENTS.DEALROOM_DEAL_MONEY_STATE_CHANGED]: DealroomListingEventProperties & { money_state: DealMoneyState };
+  [EVENTS.DEALROOM_DEAL_PAYOUT_STATE_CHANGED]: DealroomListingEventProperties & { payout_state: DealPayoutState };
 }
 
 /** Canonical person property keys (set via identify / $set). */

package/src/types/I_AccessDenial.ts

@@ -64,6 +64,13 @@ export const ACCESS_DENIAL_CODES = {
   AGENCY_SCOPE_NOT_GRANTED: "agency-scope-not-granted",
   /** The consent screen is off in this environment (FR-020, the legal gate). */
   AGENCY_CONSENT_DISABLED: "agency-consent-disabled",
+  /**
+   * The consent screen is on but this environment names no terms version, so
+   * no grant can be minted (FR-020). A deployment fault, said as a refusal
+   * rather than a 500 (spec 148 audit #1); the env gate requires the version
+   * wherever consent is switched on.
+   */
+  AGENCY_TERMS_VERSION_MISSING: "agency-terms-version-missing",
   /** The roster invite link expired, was rotated, or its organization is not approved. */
   AGENCY_LINK_INVALID: "agency-link-invalid",
   /** An admin may not decide on an organization they belong to (FR-017). */

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

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