ad2app-lib 1.49.0 → 1.59.0

package/dist/types/agency-pots.js

@@ -0,0 +1,393 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PotFields = exports.PrepareCampaignFileUploadDto = exports.UpdateMaterialCaptionDto = exports.PotRemovalDecisionDto = exports.PotHoldActDto = exports.PotPublishAtDto = exports.MovePotDeadlineDto = exports.RefillPotDto = exports.ApplyToPotDto = exports.CAMPAIGN_FILE_MAX_BYTES = exports.CAMPAIGN_FILE_CONTENT_TYPE = exports.AGENCY_POT_CODES = exports.POT_REMOVAL_DECISIONS = exports.POT_HOLD_ACTIONS = exports.POT_HOLD_REASONS = exports.POT_AVAILABILITY = exports.POT_STEPS = exports.POT_ENTRY_STATES = exports.creatorPotForbiddenKeys = exports.CREATOR_POT_FORBIDDEN_KEY = exports.POT_CURRENCIES = exports.potCostPer1000Minor = exports.potViewsAtMax = exports.potEarnings = exports.potBonusMinor = exports.checkDisclosure = exports.DISCLOSURE_RESULTS = exports.DISCLOSURE_VISIBLE_CHARS = void 0;
+const class_validator_1 = require("class-validator");
+const agency_1 = require("./agency");
+/**
+ * Pot campaigns (spec 175 US9): the second way to pay creators on a campaign,
+ * beside the negotiated offer of US7.
+ *
+ * The agency funds ONE pot and sets a maximum per creator; each creator applies
+ * with their own guarantee and rate per 1,000 views; the agency accepts or
+ * declines, never counters (SC-018). Earnings are the guarantee plus the rate
+ * times the counted views, never above the maximum, and accrue only while the
+ * pot has unreserved money (FR-030, FR-032).
+ *
+ * Money is integer minor units plus an ISO-4217 code, everywhere. A creator
+ * never receives a pot-level figure: the only pot-level signal they get is the
+ * two-valued availability (SC-016), fenced by `creatorPotForbiddenKeys`.
+ *
+ * See specs/speckit/175-agency-roster/plan.md → US9 addendum.
+ */
+// ── The disclosure check (FR-040) ───────────────────────────────────────────
+/** A caption shows this many characters before "more"; the disclosure must sit inside them. */
+exports.DISCLOSURE_VISIBLE_CHARS = 125;
+/**
+ * UOKiK's recommended wordings, with or without "#", with or without Polish
+ * diacritics. The list is a counsel decision (spec 175 T030) and lives here
+ * only: the upload form, the approval, the publish gate and the report all
+ * call `checkDisclosure`.
+ */
+const STRONG_WORDINGS = [
+    'reklama',
+    'materia[łl]\\s*reklamowy',
+    'wsp[óo][łl]praca\\s*reklamowa',
+    'p[łl]atna\\s*wsp[óo][łl]praca',
+    'post\\s*sponsorowany',
+];
+/** Tags that say something but may not be enough: flagged, never accepted silently. */
+const WEAK_TAGS = ['wsp[óo][łl]praca', 'ad', 'spons', 'promo'];
+/**
+ * A wording is a whole word: nothing glued after it, and nothing glued before it
+ * unless it opens with `#` (a tag glued to the word before it still starts at its `#`).
+ */
+const word = (body) => new RegExp(`(?:#(?:${body})|(?<![\\p{L}\\p{N}_#])(?:${body}))(?![\\p{L}\\p{N}_])`, 'giu');
+const tag = (body) => new RegExp(`#(?:${body})(?![\\p{L}\\p{N}_])`, 'giu');
+const STRONG = word(STRONG_WORDINGS.join('|'));
+const WEAK = tag(WEAK_TAGS.join('|'));
+exports.DISCLOSURE_RESULTS = ['pass', 'weak', 'missing'];
+const checkDisclosure = (raw) => {
+    // Composed form, so a decomposed "ł"/"ó" (pasted from some keyboards) reads as one letter.
+    const caption = raw.normalize('NFC');
+    const strong = [...caption.matchAll(STRONG)][0];
+    if (strong && strong.index !== undefined) {
+        return {
+            result: strong.index < exports.DISCLOSURE_VISIBLE_CHARS ? 'pass' : 'weak',
+            found: strong[0],
+            at: strong.index,
+        };
+    }
+    const weak = [...caption.matchAll(WEAK)][0];
+    if (weak && weak.index !== undefined)
+        return { result: 'weak', found: weak[0], at: weak.index };
+    return { result: 'missing', found: null, at: null };
+};
+exports.checkDisclosure = checkDisclosure;
+// ── Earnings (FR-030, FR-032, FR-035) ───────────────────────────────────────
+/** The per-view part for `views`: rate × views / 1000, rounded DOWN to the minor unit. Exact for any size. */
+const potBonusMinor = (ratePer1000Minor, views) => Number((BigInt(wholeOrZero(ratePer1000Minor)) * BigInt(wholeOrZero(views))) / 1000n);
+exports.potBonusMinor = potBonusMinor;
+/** A non-negative whole number; anything else (NaN, Infinity, negative) is 0. */
+function wholeOrZero(n) {
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+/** What a creator's terms earn at `views` with an unlimited pot: never above the maximum. */
+const potEarnings = ({ guaranteeMinor, ratePer1000Minor, views, maxMinor }) => Math.min(maxMinor, guaranteeMinor + (0, exports.potBonusMinor)(ratePer1000Minor, views));
+exports.potEarnings = potEarnings;
+/** The exact view count at which the terms reach the maximum (rounded up), or null when they never do. */
+const potViewsAtMax = ({ guaranteeMinor, ratePer1000Minor, maxMinor }) => {
+    const left = maxMinor - guaranteeMinor;
+    if (left <= 0)
+        return 0;
+    const rate = BigInt(wholeOrZero(ratePer1000Minor));
+    if (rate === 0n)
+        return null;
+    const numerator = BigInt(Math.trunc(left)) * 1000n;
+    return Number((numerator + rate - 1n) / rate);
+};
+exports.potViewsAtMax = potViewsAtMax;
+/** Cost per 1,000 views in minor units, rounded half up; null without views. */
+const potCostPer1000Minor = (costMinor, views) => {
+    const v = wholeOrZero(views);
+    return v > 0 ? Number((BigInt(wholeOrZero(costMinor)) * 2000n + BigInt(v)) / (2n * BigInt(v))) : null;
+};
+exports.potCostPer1000Minor = potCostPer1000Minor;
+/**
+ * The currencies a pot may be kept in: every amount is in minor units of two
+ * decimals (grosz, cents), so a zero- or three-decimal currency (JPY, KWD) is
+ * refused rather than shown a hundred times off (review 2026-10-06 L14).
+ */
+exports.POT_CURRENCIES = ['PLN', 'EUR', 'USD', 'GBP', 'CHF', 'CZK', 'SEK', 'NOK', 'DKK'];
+// ── The creator's fence (SC-016) ────────────────────────────────────────────
+/** Any key carrying a pot-level figure. A creator-facing response must have none, at any depth. */
+exports.CREATOR_POT_FORBIDDEN_KEY = /budget|remainder|reserved|funded|goal|covered|commitment|acceptedCreators|earned|blended|resultViews|heldViews|countedViews/i;
+/** The paths of every forbidden key in `value`; empty when the response is clean. */
+const creatorPotForbiddenKeys = (value, path = '') => {
+    if (value === null || typeof value !== 'object')
+        return [];
+    return Object.entries(value).flatMap(([key, child]) => {
+        const at = path ? `${path}.${key}` : key;
+        return [...(exports.CREATOR_POT_FORBIDDEN_KEY.test(key) ? [at] : []), ...(0, exports.creatorPotForbiddenKeys)(child, at)];
+    });
+};
+exports.creatorPotForbiddenKeys = creatorPotForbiddenKeys;
+// ── States ───────────────────────────────────────────────────────────────────
+/**
+ * An entry is one creator's application on one pot.
+ *   applied → accepted | declined | withdrawn;  accepted → released (left or
+ *   removed before publication).
+ */
+exports.POT_ENTRY_STATES = ['applied', 'accepted', 'declined', 'withdrawn', 'released'];
+/**
+ * The pot board's columns, in order (design A2): invitation sent, application,
+ * in the campaign, material in, scheduled, bonus counting, bonus final, done
+ * (the keep-up period ended with the post still up).
+ */
+exports.POT_STEPS = ['invited', 'applied', 'accepted', 'material_in', 'scheduled', 'counting', 'final', 'done'];
+exports.POT_AVAILABILITY = ['full_max_available', 'filling_up'];
+/** Why a bonus is held (FR-037): the jump against the creator's own history, or paid delivery ad2app did not start. */
+exports.POT_HOLD_REASONS = ['jump', 'paid_delivery'];
+/** The agency's three acts on a held bonus. `message` records the act; the thread opens on the client. */
+exports.POT_HOLD_ACTIONS = ['approve', 'cap', 'message'];
+/**
+ * A post taken down after the bonus window but before the keep-up end: the
+ * agency is informed and decides whether the guarantee stays earned (FR-032).
+ * Before the window ends the guarantee is not earned, with no decision.
+ */
+exports.POT_REMOVAL_DECISIONS = ['keep_base', 'withhold_base'];
+/** Refusal codes the frontend owes its own copy for. */
+exports.AGENCY_POT_CODES = {
+    /** Accepting would reserve more than the pot has unreserved. */
+    POT_CANNOT_COVER: 'agency-pot-cannot-cover',
+    /** The guarantee must be below the maximum per creator. */
+    GUARANTEE_TOO_HIGH: 'agency-pot-guarantee-too-high',
+    /** Applications closed at the application deadline, or the pot was moved. */
+    APPLICATIONS_CLOSED: 'agency-pot-applications-closed',
+    /** The kind is fixed once a creator is invited; the terms once an entry is accepted. */
+    POT_LOCKED: 'agency-pot-locked',
+    /** A refill above the maximum budget. */
+    ABOVE_MAX_BUDGET: 'agency-pot-above-max-budget',
+    /** The caption fails the disclosure check (FR-040). */
+    DISCLOSURE_REQUIRED: 'agency-pot-disclosure-required',
+    /** The creator has not connected the platform the post goes to. */
+    NO_ACCOUNT: 'agency-pot-no-account',
+    /** The confirmed time is not the one on the row now (the agency moved it meanwhile). */
+    PUBLISH_TIME_CHANGED: 'agency-pot-publish-time-changed',
+};
+/** PDF, images, video, office documents and archives; no HTML or SVG (opened in the browser). */
+exports.CAMPAIGN_FILE_CONTENT_TYPE = /^(application\/pdf|image\/(png|jpeg|gif|webp|heic|heif|avif)|video\/[A-Za-z0-9.+-]+|application\/(msword|vnd\.openxmlformats-officedocument\.[a-z.]+|vnd\.ms-(excel|powerpoint)|vnd\.oasis\.opendocument\.[a-z.]+|rtf|zip|x-zip-compressed|x-7z-compressed|x-rar-compressed|vnd\.rar|gzip|x-tar)|text\/(plain|csv))$/;
+exports.CAMPAIGN_FILE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+// ── Bodies ───────────────────────────────────────────────────────────────────
+const MONEY_MAX = 100000000000;
+/**
+ * `POST /agency/campaign-invitations/:memberId/application` — the creator's own
+ * terms. Applying from an invitation also joins the campaign, answering any
+ * access request folded into it with `scopes` (absent = everything asked).
+ */
+class ApplyToPotDto {
+    constructor(data) {
+        this.guaranteeMinor = data?.guaranteeMinor ?? 0;
+        this.ratePer1000Minor = data?.ratePer1000Minor ?? 0;
+        this.scopes = data?.scopes;
+    }
+}
+exports.ApplyToPotDto = ApplyToPotDto;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], ApplyToPotDto.prototype, "guaranteeMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], ApplyToPotDto.prototype, "ratePer1000Minor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsIn)(agency_1.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], ApplyToPotDto.prototype, "scopes", void 0);
+/** `POST /agency/campaigns/:id/pot/refill` — up to the maximum budget. */
+class RefillPotDto {
+    constructor(data) {
+        this.amountMinor = data?.amountMinor ?? 0;
+    }
+}
+exports.RefillPotDto = RefillPotDto;
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], RefillPotDto.prototype, "amountMinor", void 0);
+/** `PATCH /agency/campaigns/:id/pot/application-deadline`. */
+class MovePotDeadlineDto {
+    constructor(data) {
+        this.applicationDeadlineAt = data?.applicationDeadlineAt ?? '';
+    }
+}
+exports.MovePotDeadlineDto = MovePotDeadlineDto;
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], MovePotDeadlineDto.prototype, "applicationDeadlineAt", void 0);
+/** The agency sets the time agreed with the brand; the creator confirms that same value. */
+class PotPublishAtDto {
+    constructor(data) {
+        this.publishAt = data?.publishAt ?? '';
+    }
+}
+exports.PotPublishAtDto = PotPublishAtDto;
+__decorate([
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], PotPublishAtDto.prototype, "publishAt", void 0);
+class PotHoldActDto {
+    constructor(data) {
+        this.action = data?.action ?? 'approve';
+    }
+}
+exports.PotHoldActDto = PotHoldActDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.POT_HOLD_ACTIONS),
+    __metadata("design:type", String)
+], PotHoldActDto.prototype, "action", void 0);
+/** `POST /agency/campaigns/:id/pot/entries/:entryId/removal` — the agency's decision on a late takedown (FR-032). */
+class PotRemovalDecisionDto {
+    constructor(data) {
+        this.decision = data?.decision ?? 'keep_base';
+    }
+}
+exports.PotRemovalDecisionDto = PotRemovalDecisionDto;
+__decorate([
+    (0, class_validator_1.IsIn)(exports.POT_REMOVAL_DECISIONS),
+    __metadata("design:type", String)
+], PotRemovalDecisionDto.prototype, "decision", void 0);
+/** The caption is the creator's until publication (FR-032). */
+class UpdateMaterialCaptionDto {
+    constructor(data) {
+        this.caption = data?.caption ?? '';
+    }
+}
+exports.UpdateMaterialCaptionDto = UpdateMaterialCaptionDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2200),
+    __metadata("design:type", String)
+], UpdateMaterialCaptionDto.prototype, "caption", void 0);
+class PrepareCampaignFileUploadDto {
+    constructor(data) {
+        this.fileName = data?.fileName ?? '';
+        this.contentType = data?.contentType ?? '';
+        this.sizeBytes = data?.sizeBytes ?? 0;
+    }
+}
+exports.PrepareCampaignFileUploadDto = PrepareCampaignFileUploadDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.MaxLength)(255),
+    __metadata("design:type", String)
+], PrepareCampaignFileUploadDto.prototype, "fileName", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(exports.CAMPAIGN_FILE_CONTENT_TYPE),
+    __metadata("design:type", String)
+], PrepareCampaignFileUploadDto.prototype, "contentType", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(exports.CAMPAIGN_FILE_MAX_BYTES),
+    __metadata("design:type", Number)
+], PrepareCampaignFileUploadDto.prototype, "sizeBytes", void 0);
+/** The pot's fields on campaign create (and on a move); flat for the reason given in agency-campaigns.ts. */
+class PotFields {
+    assignPot(data) {
+        this.potBudgetMinor = data?.potBudgetMinor;
+        this.potMaxBudgetMinor = data?.potMaxBudgetMinor;
+        this.potCapMinor = data?.potCapMinor;
+        this.potBonusWindowDays = data?.potBonusWindowDays;
+        this.potKeepUpMonths = data?.potKeepUpMonths;
+        this.potGoalViews = data?.potGoalViews;
+        this.potCurrency = data?.potCurrency;
+        this.potApplicationDeadlineAt = data?.potApplicationDeadlineAt;
+        this.potPaidPartnershipLabel = data?.potPaidPartnershipLabel;
+        this.potSponsorHandle = data?.potSponsorHandle;
+        this.potCollabHandle = data?.potCollabHandle;
+        this.potFirstComment = data?.potFirstComment;
+        this.potCommentsEnabled = data?.potCommentsEnabled;
+    }
+}
+exports.PotFields = PotFields;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potBudgetMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potMaxBudgetMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(MONEY_MAX),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potCapMinor", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(365),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potBonusWindowDays", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(60),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potKeepUpMonths", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(100000000000),
+    __metadata("design:type", Number)
+], PotFields.prototype, "potGoalViews", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.POT_CURRENCIES),
+    __metadata("design:type", String)
+], PotFields.prototype, "potCurrency", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", String)
+], PotFields.prototype, "potApplicationDeadlineAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PotFields.prototype, "potPaidPartnershipLabel", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^@?[A-Za-z0-9._]{1,64}$/),
+    __metadata("design:type", String)
+], PotFields.prototype, "potSponsorHandle", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^@?[A-Za-z0-9._]{1,64}$/),
+    __metadata("design:type", String)
+], PotFields.prototype, "potCollabHandle", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(2200),
+    __metadata("design:type", String)
+], PotFields.prototype, "potFirstComment", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PotFields.prototype, "potCommentsEnabled", void 0);

package/dist/types/agency-threads.d.ts

@@ -1,4 +1,5 @@
 import type { CampaignSide, I_CampaignCreatorIdentity } from './agency-campaigns';
+import type { AgencyOrganizationType } from './agency';
 /**
  * Agency ↔ creator threads (spec 175 US8, FR-023): one conversation per
  * organization and creator, inside ad2app.
@@ -31,21 +32,41 @@ export interface I_AgencyThreadMessage {
     side: CampaignSide;
     body: string;
     at: string;
+    /** A delegate wrote this for the creator through a `deals` grant (spec 148): which grant, and the member's name. */
+    actingFor?: {
+        grantId: string;
+        memberName: string;
+    };
 }
 export interface I_AgencyThreadSummary {
     id: string;
     /** Agency side: who the thread is with. */
     creator: I_CampaignCreatorIdentity;
-    /** Creator side: which organization. */
+    /** Creator side: which organization, and whether it is an agency or a brand (spec 148). */
     organization: {
         id: string;
         name: string;
+        type?: AgencyOrganizationType;
     };
+    /** `actingFor`: a delegate wrote the last message for the creator (spec 148 US8), under this member's name. */
     lastMessage: {
         side: CampaignSide;
         body: string;
         at: string;
+        actingFor?: {
+            memberName: string;
+        };
     } | null;
+    /**
+     * Spec 148 US8 (audit #2): the other organizations whose members read this
+     * conversation acting for the creator: a manager holding the creator's
+     * `deals` grant while this is a deal's thread, or one whose member already
+     * wrote in it. Empty when only the two parties see it.
+     */
+    delegates?: Array<{
+        id: string;
+        name: string;
+    }>;
     /** The other side wrote last, seen from the caller's side. */
     unanswered: boolean;
     /** No live relationship: read-only for whoever still exists. */

package/dist/types/agency.d.ts

@@ -54,8 +54,29 @@ export type I_AgencyGrantScope = (typeof AGENCY_GRANT_SCOPES)[number];
  * answer), so this is a trust boundary, not a convenience.
  */
 export declare const isAgencyGrantScope: (value: string) => value is I_AgencyGrantScope;
-/** `'brand'` arrives with spec 148; one column, no enum table. */
-export type AgencyOrganizationType = 'agency';
+/**
+ * Delegation (spec 148 FR-017a): the one scope that reaches WRITES, and only
+ * the creator-side deal acts (apply, offer acts, materials, the deal thread).
+ *
+ * Kept OUT of AGENCY_GRANT_SCOPES on purpose: that list is what an
+ * organization may ASK for, and no organization ever asks for this. Only the
+ * creator adds it to `grantedScopes`, which makes it the one exception to
+ * "granted is a subset of requested". Publishing, contract signature,
+ * payouts, the settlement form and platforms stay unreachable through it.
+ */
+export declare const DELEGATION_SCOPES: readonly ["deals"];
+export type I_DelegationScope = (typeof DELEGATION_SCOPES)[number];
+/** Everything a grant may carry once the creator has answered. */
+export type I_GrantScope = I_AgencyGrantScope | I_DelegationScope;
+/** Narrowing guard over both sets; an unrecognised scope fails closed. */
+export declare const isGrantScope: (value: string) => value is I_GrantScope;
+/**
+ * `'brand'` arrived with spec 148 (US2): one column, no enum table. A brand
+ * authors campaigns like an agency but has no roster; it is created only
+ * while the backend's brand door is open.
+ */
+export declare const AGENCY_ORGANIZATION_TYPES: readonly ["agency", "brand"];
+export type AgencyOrganizationType = (typeof AGENCY_ORGANIZATION_TYPES)[number];
 /**
  * `closed` was added by the 2026-09-21 requirements review (FR-004b).
  *
@@ -81,6 +102,11 @@ export interface I_AgencyOrganization {
     /** ISO-3166 alpha-2 of the register the identifier belongs to. */
     registryCountry: string;
     contactEmail: string;
+    /**
+     * The organization's logo, a storage path read through a signed URL (spec
+     * 148). Required before a campaign is listed open. Absent on older backends.
+     */
+    logoUrl?: string;
     status: AgencyOrganizationStatus;
     /** The reason an admin gave; shown to a rejected applicant (FR-002). */
     statusReason?: string;
@@ -117,7 +143,13 @@ export interface I_AgencyMember {
  */
 export declare const CREATOR_ACCESS_GRANT_STATES: readonly ["requested", "active", "declined", "expired", "revoked"];
 export type CreatorAccessGrantState = (typeof CREATOR_ACCESS_GRANT_STATES)[number];
-export type CreatorAccessGrantOrigin = 'invite_link' | 'agency_request';
+/**
+ * `dealroom_application` (spec 148): created or widened when the creator
+ * applies to an open listing. The system revokes a grant of this origin, and
+ * only of this origin, when that deal ends.
+ */
+export declare const CREATOR_ACCESS_GRANT_ORIGINS: readonly ["invite_link", "agency_request", "dealroom_application"];
+export type CreatorAccessGrantOrigin = (typeof CREATOR_ACCESS_GRANT_ORIGINS)[number];
 /** Who ended it. Shown in the agency's past-creators history (FR-013b). */
 export type CreatorAccessGrantRevokedBy = 'creator' | 'agency' | 'organization' | 'account-deleted' | 'purge' | 'system';
 export interface I_CreatorAccessGrant {
@@ -130,10 +162,19 @@ export interface I_CreatorAccessGrant {
     creatorUserId?: string;
     organizationId: string;
     organizationName: string;
+    /** Spec 148: `brand` cannot hold `deals` (it is the creator's counterparty), so the switch is not offered. Absent on older backends. */
+    organizationType?: AgencyOrganizationType;
     /** What the agency asked for. */
     requestedScopes: I_AgencyGrantScope[];
-    /** What the creator actually granted — a subset, possibly smaller, never larger. */
+    /** What the creator actually granted — a subset, possibly smaller, never larger. Reads only. */
     grantedScopes: I_AgencyGrantScope[];
+    /**
+     * Spec 148 FR-017a: the creator lets this organization run their Dealroom
+     * deals (the `deals` delegation scope, which no organization can ask for and
+     * only the creator adds). Kept out of `grantedScopes` so that list stays the
+     * reads 175 code is typed on. Absent on older backends: read absent as no.
+     */
+    deals?: boolean;
     /** Frozen at grant time; what the history shows after a purge. */
     creatorIdentity: {
         handle: string;
@@ -256,6 +297,12 @@ export interface I_AgencyRosterRow {
      */
     reaskedAt?: string;
     reaskAvailableAt?: string;
+    /**
+     * Spec 148 US8: the organization may act for this creator in the Dealroom
+     * (the active grant holds `deals`, the org is not a brand). Only
+     * sent while the Dealroom is on; absent while it is off (read absent as no).
+     */
+    canActForCreator?: boolean;
 }
 /**
  * The platforms a creator has connected, as the agency side sees them
@@ -428,6 +475,14 @@ export declare class CreateAgencyOrganizationDto {
     /** ISO-3166 alpha-2: which register a reviewer should look in. */
     registryCountry: string;
     contactEmail: string;
+    /** Spec 148 US2: absent = `agency`. `brand` is refused while the backend's brand door is closed. */
+    type?: AgencyOrganizationType;
+    /**
+     * Spec 148 US2, money release only (DORMANT): the card a brand pays its
+     * first subscription charge with, taken BEFORE the organization exists.
+     * Ignored while the backend's money switch is off (brands apply free).
+     */
+    paymentMethodId?: string;
     constructor(data?: Partial<CreateAgencyOrganizationDto>);
 }
 export declare class InviteAgencyMemberDto {
@@ -453,11 +508,29 @@ export declare class AcceptGrantDto {
     scopes?: I_AgencyGrantScope[];
     constructor(data?: Partial<AcceptGrantDto>);
 }
-/** The creator narrowing or widening a live grant — the only other write path. */
+/**
+ * The creator narrowing or widening a live grant — the only other write path.
+ *
+ * `scopes` are the READS only; `deals` is never one of them (it stays out of
+ * AGENCY_GRANT_SCOPES). Delegation (spec 148 FR-017a) is its own field, so the
+ * data-access screen, which saves reads, can never drop it by omission:
+ *
+ *  - `deals` absent ⇒ delegation unchanged (a reads-only save keeps `deals`);
+ *  - `deals: true` ⇒ added, `deals: false` ⇒ removed;
+ *  - `scopes` may be left out when `deals` is sent ⇒ the reads stay as they are.
+ */
 export declare class UpdateGrantScopesDto {
-    scopes: I_AgencyGrantScope[];
+    scopes?: I_AgencyGrantScope[];
+    /** Let this organization run my deals (spec 148 US8). Creator-only; absent = unchanged. */
+    deals?: boolean;
     constructor(data?: Partial<UpdateGrantScopesDto>);
 }
+/**
+ * Spec 148 US8: the header a delegate names the creator with on the
+ * creator-side deal routes (`X-Acting-For: <creatorUserId>`). Every other
+ * route refuses a request that carries it (`dealroom-delegate-forbidden`).
+ */
+export declare const ACTING_FOR_HEADER = "x-acting-for";
 export declare class SponsorCreatorDto {
     tier: SponsoredTier;
     constructor(data?: Partial<SponsorCreatorDto>);
@@ -512,6 +585,20 @@ export interface I_AgencyDiscoverHit {
 export interface I_AgencyDiscoverResult {
     results: I_AgencyDiscoverHit[];
 }
+/** `GET /admin/agency-organizations[?type=]`: one pending organization on the admin queue. */
+export interface I_AdminOrganizationRow {
+    id: string;
+    /** Spec 148: `agency` or `brand`; filter with `?type=`. */
+    type: AgencyOrganizationType;
+    name: string;
+    website: string | null;
+    registryId: string;
+    registryCountry: string;
+    contactEmail: string;
+    /** Derived, a SIGNAL only (FR-003). */
+    contactEmailDomain: string;
+    appliedAt: string;
+}
 export declare class AdminSetOrganizationStatusDto {
     status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
     /** Required on reject — a rejected applicant is shown this (FR-002). The