ad2app-lib 1.49.0 → 1.59.0

package/src/types/dealroom.ts

@@ -0,0 +1,868 @@
+/**
+ * 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.
+ */
+
+import { ArrayMaxSize, ArrayNotEmpty, IsArray, IsBoolean, IsDateString, IsIn, IsInt, IsObject, IsOptional, IsString, Matches, Max, MaxLength, Min } from 'class-validator';
+
+import { AGENCY_GRANT_SCOPES, type AgencyOrganizationType, type I_AgencyGrantScope } from './agency';
+import type {
+  AgencyCampaignKind,
+  AgencyMilestoneKind,
+  CampaignPlatform,
+  I_CampaignDeliverable,
+  I_CreatorCampaignView,
+  I_Money,
+  SettlementForm,
+} from './agency-campaigns';
+
+// ── Open listing ─────────────────────────────────────────────────────────────
+
+/** `private` is every 175 campaign today (members only); `open` is listed in the feed to matching creators. */
+export const CAMPAIGN_VISIBILITIES = ['private', 'open'] as const;
+export type CampaignVisibility = (typeof CAMPAIGN_VISIBILITIES)[number];
+
+export const isCampaignVisibility = (value: string): value is CampaignVisibility =>
+  (CAMPAIGN_VISIBILITIES as readonly string[]).includes(value);
+
+/** A follower band on one platform; no `max` means no upper bound. */
+export interface I_FollowerBand {
+  min: number;
+  max?: number;
+}
+
+/**
+ * Who a listing is for. A BLANK constraint means "no filter" — which is a
+ * listing's meaning only. A creator's missing country or niches never reads
+ * that way: it is an incomplete profile (FR-026).
+ */
+export interface I_TargetProfile {
+  platforms: CampaignPlatform[];
+  followerBand: Partial<Record<CampaignPlatform, I_FollowerBand>>;
+  niches: string[];
+  /** ISO-3166 alpha-2. */
+  country?: string;
+  language?: string;
+}
+
+// ── Matching ─────────────────────────────────────────────────────────────────
+
+/**
+ * The verifiable parts of "why you see this", built from the same row the
+ * match query returned — never composed separately. The screen writes the
+ * sentence in the reader's language.
+ */
+export interface I_MatchExplanation {
+  platform: CampaignPlatform;
+  followers: number;
+  /** The niches the creator and the listing share. */
+  niches: string[];
+  country?: string;
+  language?: string;
+}
+
+/** The one dimension a near match misses (US11): followers within ±20%, or one platform not connected. */
+export type I_NearMatchGap =
+  | {
+      kind: 'followers';
+      /**
+       * The platform whose followers miss the band, so the sentence names it on
+       * a multi-platform listing. Always sent by the current backend;
+       * optional only so older fixtures still type.
+       */
+      platform?: CampaignPlatform;
+      followers: number;
+      band: I_FollowerBand;
+      percent: number;
+      direction: 'under' | 'over';
+    }
+  | { kind: 'missing_platform'; platform: CampaignPlatform };
+
+export interface I_DealroomListingOrganization {
+  id: string;
+  name: string;
+  logoUrl: string | null;
+  type: AgencyOrganizationType;
+}
+
+/** One open listing in a creator's feed: coarse campaign data, never another creator. */
+export interface I_DealroomListing {
+  campaignId: string;
+  /** The campaign's own name, the one the deal carries once joined (audit #1). Absent on older backends: read the brief. */
+  campaignName?: string;
+  kind: AgencyCampaignKind;
+  organization: I_DealroomListingOrganization;
+  briefSummary: string;
+  /** Filtered to the creator's platforms (175 rule). */
+  deliverables: I_CampaignDeliverable[];
+  currency: string;
+  /** Null = unlimited. */
+  slots: number | null;
+  /** Confirmed offers (offer kind) or accepted entries (pot kind) — a count, never who. */
+  acceptedCount: number;
+  applicationDeadline: string | null;
+  explanation: I_MatchExplanation;
+  /**
+   * What joining shares: the scopes the pre-join (175 consent) screen names.
+   * An open listing asks for every read an organization may ask for; the
+   * creator ticks a subset when applying. ABSENT = all of AGENCY_GRANT_SCOPES
+   * (the backend does not send it today).
+   */
+  askedScopes?: I_AgencyGrantScope[];
+  /** Money release only; absent while money is off (interpretation 8). */
+  guaranteedAmount?: I_Money;
+  /** Money release only; absent while money is off. */
+  depositPct?: number;
+}
+
+/** A listing the creator would match but for one gap. Never appliable, by construction. */
+export interface I_NearMatch {
+  listing: Omit<I_DealroomListing, 'explanation'>;
+  explanation: I_MatchExplanation;
+  gap: I_NearMatchGap;
+  applicationAllowed: false;
+}
+
+/** The profile fields whose absence makes the feed `profile_incomplete` (FR-026). */
+export const DEALROOM_PROFILE_FIELDS = ['country', 'niches'] as const;
+export type DealroomProfileField = (typeof DEALROOM_PROFILE_FIELDS)[number];
+
+/** `GET /dealroom/feed[?broaden=true]`. */
+export interface I_DealroomFeed {
+  state: 'ok' | 'profile_incomplete';
+  listings: I_DealroomListing[];
+  /** Present only when the creator broadened the view. */
+  nearMatches?: I_NearMatch[];
+  /** Distinct organizations in `listings`; empty when there are none, never filler. */
+  logoStrip: I_DealroomListingOrganization[];
+  /** With `profile_incomplete`: which fields to complete. */
+  missingProfileFields?: DealroomProfileField[];
+}
+
+/**
+ * A creator as an organization sees them on a match list, before any grant:
+ * handle, platforms, follower BAND per platform, niches, country. Never a
+ * rate, never an exact or rich metric (FR-007).
+ */
+export interface I_CoarseCreatorProfile {
+  userId: string;
+  handle: string;
+  platforms: CampaignPlatform[];
+  followerBand: Partial<Record<CampaignPlatform, I_FollowerBand>>;
+  niches: string[];
+  country: string | null;
+}
+
+// ── 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).
+ */
+export const DEALROOM_LISTING_STATES = ['draft', 'live', 'frozen', 'closed'] as const;
+export type DealroomListingState = (typeof DEALROOM_LISTING_STATES)[number];
+
+/** `I_AgencyCampaign.listing`: the listing fields and where the listing stands. */
+export interface I_CampaignListing {
+  visibility: CampaignVisibility;
+  targetProfile: I_TargetProfile | null;
+  /** Null = unlimited. */
+  slots: number | null;
+  /** Confirmed offers (offer kind) or accepted entries (pot kind): a count, never who. */
+  acceptedCount: number;
+  /** The offer's own deadline, or the pot's application deadline. */
+  applicationDeadline: string | null;
+  closedAt: string | null;
+  state: DealroomListingState;
+  /** True once a creator was invited or applied: terms are fixed (FR-004). */
+  frozen: boolean;
+}
+
+/** `GET /agency/campaigns/:id/matches`: coarse rows only, each invitable through 175's invitation route. */
+export interface I_CampaignMatches {
+  matches: I_CoarseCreatorProfile[];
+}
+
+// ── 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`).
+ */
+export class ApplyToDealroomListingDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes: I_AgencyGrantScope[];
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(1_000_000_000)
+  priceMinor?: number;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^[A-Z]{3}$/)
+  currency?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(1_000_000_000)
+  guaranteeMinor?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(1_000_000_000)
+  ratePer1000Minor?: number;
+
+  constructor(data?: Partial<ApplyToDealroomListingDto>) {
+    this.scopes = data?.scopes ?? [];
+    this.priceMinor = data?.priceMinor;
+    this.currency = data?.currency;
+    this.guaranteeMinor = data?.guaranteeMinor;
+    this.ratePer1000Minor = data?.ratePer1000Minor;
+  }
+}
+
+/** The apply answer: the creator's campaign as 175 shows it; `alreadyMember` when they were on it before. */
+export interface I_DealroomApplication {
+  alreadyMember: boolean;
+  campaign: I_CreatorCampaignView;
+}
+
+// ── Codes ────────────────────────────────────────────────────────────────────
+
+/** Refusal codes the frontend owes its own copy for (contracts/dealroom-api.md). */
+export const 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',
+} as const;
+export type DealroomCode = (typeof DEALROOM_CODES)[keyof typeof DEALROOM_CODES];
+
+// ── 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).
+ */
+export const DEAL_MONEY_STATES = [
+  'awaiting_material',
+  'material_submitted',
+  'deposit_paid',
+  'funded',
+  'approved',
+  'published',
+  'closed_unviewed',
+  'refund_pending',
+  'refunded',
+  'guarantee_claimed',
+] as const;
+export type DealMoneyState = (typeof DEAL_MONEY_STATES)[number];
+
+export const DEAL_PAYOUT_STATES = ['none', 'initiated', 'paid'] as const;
+export type DealPayoutState = (typeof DEAL_PAYOUT_STATES)[number];
+
+/** One payment-rail cost, passed through at cost and shown, never part of our fee. */
+export interface I_RailCostItem {
+  kind: 'processing' | 'payout' | 'account' | 'fx' | 'other';
+  amount: I_Money;
+  note?: string;
+}
+
+/** The FX conversion a snapshot used (175 `fx_rates`, ECB daily). */
+export interface I_FxSnapshot {
+  from: string;
+  to: string;
+  rate: number;
+  rateDate: string;
+}
+
+/** Frozen at signing: what the fees were, which cap bound, and whether the floor guard did. */
+export interface I_DealFeeSnapshot {
+  agencyFee: I_Money;
+  creatorFee: I_Money;
+  capsApplied: { agency: boolean; creator: boolean };
+  railCosts: I_RailCostItem[];
+  floorGuardApplied: boolean;
+  fx?: I_FxSnapshot;
+}
+
+export interface I_DealroomDeal {
+  id: string;
+  /** Offer deals; null for a pot deal. */
+  collaborationId: string | null;
+  /** Pot deals; null for an offer deal. */
+  potEntryId: string | null;
+  campaignId: string;
+  organizationId: string;
+  creatorUserId: string | null;
+  agreed: I_Money;
+  feeSnapshot: I_DealFeeSnapshot;
+  moneyState: DealMoneyState;
+  payoutState: DealPayoutState;
+  /** The cap the guarantee covers, never more (US7 scenario 4); zero when no guarantee is configured. */
+  guaranteeCap: I_Money;
+  /** Snapshotted from the settlement form when the contract is signed; null before, or for barter / international. */
+  payoutTrack: 1 | 2 | null;
+  createdAt: string;
+  /** The 175 membership the deal belongs to (wave 4). */
+  memberId?: string;
+  /** When the fee snapshot was frozen (contract signed); null while it is still a quote. */
+  feeFrozenAt?: string | null;
+  /** The zadatek %, snapshotted at confirmation; null while counsel has not set it. */
+  depositPct?: number | null;
+}
+
+export interface I_DealContract {
+  collaborationId: string;
+  source: 'template' | 'uploaded';
+  documentUrl: string | null;
+  signatureLevel: 'SES' | 'QES';
+  provider: string;
+  state: 'draft' | 'sent' | 'signed';
+  signedAt: string | null;
+  /** Wave 4 (additive). */
+  id?: string;
+  /** The template's form fields as sent (template contracts). */
+  terms?: I_DealContractTerms | null;
+  /** The uploaded file's name (uploaded contracts). */
+  fileName?: string | null;
+  sentAt?: string | null;
+  createdAt?: string;
+  /**
+   * The e-sign provider's signing link for the CALLER's own party (the
+   * organization's signer or the creator), while the contract is `sent` and
+   * that party has not signed; null otherwise. Never the other party's link.
+   */
+  signingUrl?: string | null;
+}
+
+export interface I_DealPayment {
+  id: string;
+  collaborationId: string;
+  type: 'deposit' | 'funding' | 'refund' | 'payout';
+  amount: I_Money;
+  railCostsItemized: I_RailCostItem[];
+  state: 'pending' | 'succeeded' | 'failed';
+  fxSnapshot?: I_FxSnapshot;
+  createdAt: string;
+  /** Wave 4 (additive): the deal it belongs to. */
+  dealroomDealId?: string;
+  /** Wave 4: what the payer is charged in all: the amount, the organization's fee when it is due, and the rail costs. */
+  total?: I_Money;
+  /** Wave 4: the organization's fee carried by this payment (funding only). */
+  agencyFee?: I_Money | null;
+  method?: DealPaymentMethod;
+}
+
+/** Derived from 175's settlement form (`invoice` → faktura_vat, `contract` → umowa_o_dzielo); `international` is 148's. */
+export const PAYOUT_BILLING_VARIANTS = ['faktura_vat', 'umowa_o_dzielo', 'international'] as const;
+export type PayoutBillingVariant = (typeof PAYOUT_BILLING_VARIANTS)[number];
+
+/** Settings → Payouts. The payment provider's account id is never surfaced. */
+export interface I_PayoutProfile {
+  /** Wave 4 (additive): the 175 settlement form the track is read from (one setting, not two). */
+  settlementForm?: SettlementForm | null;
+  /** Wave 4: everything a payout needs is on file. Joining and working never wait for it; the first payout does. */
+  complete?: boolean;
+  /** Wave 4: what is still missing for the first payout. */
+  missing?: PayoutProfileField[];
+  /** Null while the settlement form is unset or barter (no payout) and the international variant is not chosen. */
+  billingVariant: PayoutBillingVariant | null;
+  /** 1 = invoice, 2 = umowa o dzieło (withholding); null for barter or international. */
+  track: 1 | 2 | null;
+  nip?: string;
+  taxStatement?: string;
+  intlBillingData?: Record<string, string>;
+  iban?: string;
+  payoutCurrency: string;
+  kycState: 'none' | 'pending' | 'verified' | 'rejected';
+}
+
+export const PAYOUT_LEDGER_SOURCES = ['deal', 'pot', 'commission'] as const;
+export type PayoutLedgerSource = (typeof PAYOUT_LEDGER_SOURCES)[number];
+
+/** Commission entries are `validated` only after the network pays us. */
+export const PAYOUT_LEDGER_STATES = ['earned', 'validated', 'paid'] as const;
+export type PayoutLedgerState = (typeof PAYOUT_LEDGER_STATES)[number];
+
+export interface I_PayoutLedgerEntry {
+  id: string;
+  source: PayoutLedgerSource;
+  dealroomDealId?: string;
+  potEntryId?: string;
+  network?: CommissionNetwork;
+  amount: I_Money;
+  feesItemized: I_RailCostItem[];
+  state: PayoutLedgerState;
+  availableAt?: string;
+  createdAt: string;
+  /** Wave 4 (additive): track 2's withheld PIT, itemized; absent when nothing is withheld. */
+  withheld?: I_Money | null;
+  /** Wave 4: why the entry exists. */
+  reason?: 'publication' | 'guarantee' | 'deposit_forfeit' | 'pot' | 'commission';
+  /** Wave 4: why a due payout waits (`profile_incomplete`, `below_threshold`, …); null when it does not. */
+  holdReason?: string | null;
+  paidAt?: string | null;
+}
+
+// ── 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). */
+export const 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',
+] as const;
+export type DealroomMoneyEventKind = (typeof DEALROOM_MONEY_EVENT_KINDS)[number];
+
+export const DEAL_CONTRACT_SOURCES = ['template', 'uploaded'] as const;
+export type DealContractSource = (typeof DEAL_CONTRACT_SOURCES)[number];
+
+/** `draft` again after a signer declines; `signed` once every party signed (the e-sign provider's word). */
+export const DEAL_CONTRACT_STATES = ['draft', 'sent', 'signed'] as const;
+export type DealContractState = (typeof DEAL_CONTRACT_STATES)[number];
+
+/** SES by default, QES as an option (research R2; counsel point 3 may require QES for some documents). */
+export const DEAL_SIGNATURE_LEVELS = ['SES', 'QES'] as const;
+export type DealSignatureLevel = (typeof DEAL_SIGNATURE_LEVELS)[number];
+
+/** What a template contract carries (the organization's form-fill). Parties and rate come from the deal, never the form. */
+export interface I_DealContractTerms {
+  parties: { organization: string; creator: string };
+  deliverables: string[];
+  rate: I_Money;
+  draftDueAt: string | null;
+  liveByAt: string | null;
+  licenceMonths: number | null;
+  paidPromoMonths: number | null;
+}
+
+/**
+ * `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.
+ */
+export class CreateDealContractDto {
+  @IsIn(DEAL_CONTRACT_SOURCES as unknown as string[])
+  source: DealContractSource;
+
+  @IsOptional()
+  @IsIn(DEAL_SIGNATURE_LEVELS as unknown as string[])
+  signatureLevel?: DealSignatureLevel;
+
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(20)
+  @IsString({ each: true })
+  @MaxLength(500, { each: true })
+  deliverables?: string[];
+
+  @IsOptional()
+  @IsDateString()
+  draftDueAt?: string;
+
+  @IsOptional()
+  @IsDateString()
+  liveByAt?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(120)
+  licenceMonths?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(120)
+  paidPromoMonths?: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  fileName?: string;
+
+  /** The uploaded file, base64; the backend checks the type and the size. */
+  @IsOptional()
+  @IsString()
+  fileBase64?: string;
+
+  constructor(data?: Partial<CreateDealContractDto>) {
+    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;
+  }
+}
+
+/** Card (PaymentIntent, confirmed in the browser) or invoice (a Stripe invoice the organization pays by transfer). */
+export const DEAL_PAYMENT_METHODS = ['card', 'invoice'] as const;
+export type DealPaymentMethod = (typeof DEAL_PAYMENT_METHODS)[number];
+
+/** `POST /agency/campaigns/:id/members/:memberId/deal/deposit|fund`. Big sums go by invoice whatever is asked. */
+export class StartDealPaymentDto {
+  @IsOptional()
+  @IsIn(DEAL_PAYMENT_METHODS as unknown as string[])
+  method?: DealPaymentMethod;
+
+  constructor(data?: Partial<StartDealPaymentDto>) {
+    this.method = data?.method;
+  }
+}
+
+/** A started payment: confirm `clientSecret` with Stripe.js (card), or send the payer to `invoiceUrl` (invoice). */
+export interface I_DealPaymentStart {
+  payment: I_DealPayment;
+  clientSecret: string | null;
+  invoiceUrl: string | null;
+}
+
+/** The money acts a deal view may offer; the server decides which, per side and step. */
+export const DEAL_MONEY_ACTIONS = ['send_contract', 'pay_deposit', 'decline_deposit', 'fund', 'refund', 'claim_guarantee'] as const;
+export type DealMoneyAction = (typeof DEAL_MONEY_ACTIONS)[number];
+
+/**
+ * One deal's money, as one side reads it:
+ * `GET /agency/campaigns/:id/members/:memberId/deal` (organization) and
+ * `GET /dealroom/my-deals/:memberId` (creator). Null `deal` ⇒ no money row
+ * (money was off at confirmation, or a pot entry with no guarantee).
+ */
+export interface I_DealroomDealView {
+  deal: I_DealroomDeal;
+  contract: I_DealContract | null;
+  /** The zadatek and the rest; null while counsel has not set the deposit %. */
+  deposit: I_Money | null;
+  remaining: I_Money | null;
+  payments: I_DealPayment[];
+  /** The organization may open the submitted material (deposit paid). */
+  materialViewable: boolean;
+  /** The organization may approve it (fully funded). */
+  approvable: boolean;
+  actions: DealMoneyAction[];
+}
+
+/** What the first payout needs and is missing; the provider's KYC runs behind the form and is never a field. */
+export const PAYOUT_PROFILE_FIELDS = ['settlement_form', 'nip', 'tax_statement', 'intl_billing_data', 'iban', 'payout_currency'] as const;
+export type PayoutProfileField = (typeof PAYOUT_PROFILE_FIELDS)[number];
+
+/**
+ * `PUT /dealroom/payouts/profile`. The track is NOT here: it is read from the
+ * 175 settlement form. `international` picks the international variant.
+ */
+export class UpsertPayoutProfileDto {
+  @IsOptional()
+  @IsBoolean()
+  international?: boolean;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^[0-9]{10}$/)
+  nip?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  taxStatement?: string;
+
+  @IsOptional()
+  @IsObject()
+  intlBillingData?: Record<string, string>;
+
+  /** IBAN: country code, check digits, 11-30 alphanumerics, spaces allowed. */
+  @IsString()
+  @Matches(/^[A-Z]{2}[0-9]{2}(?:\s?[A-Z0-9]){11,30}$/)
+  iban: string;
+
+  @IsString()
+  @Matches(/^[A-Z]{3}$/)
+  payoutCurrency: string;
+
+  constructor(data?: Partial<UpsertPayoutProfileDto>) {
+    this.international = data?.international;
+    this.nip = data?.nip;
+    this.taxStatement = data?.taxStatement;
+    this.intlBillingData = data?.intlBillingData;
+    this.iban = data?.iban ?? '';
+    this.payoutCurrency = data?.payoutCurrency ?? '';
+  }
+}
+
+/** `GET /dealroom/payouts/ledger`: every entry and the totals per currency, honestly per state. */
+export interface I_PayoutLedger {
+  entries: I_PayoutLedgerEntry[];
+  totals: Array<{ currency: string; earned: number; validated: number; paid: number }>;
+  /** Commission payouts batch monthly from this amount up; below it they accrue. */
+  commissionThreshold: I_Money;
+  profileComplete: boolean;
+}
+
+// ── Commission lane ──────────────────────────────────────────────────────────
+
+export const COMMISSION_NETWORKS = ['awin', 'admitad'] as const;
+export type CommissionNetwork = (typeof COMMISSION_NETWORKS)[number];
+
+export const COMMISSION_OFFER_STATES = ['live', 'paused', 'gone'] as const;
+export type CommissionOfferState = (typeof COMMISSION_OFFER_STATES)[number];
+
+export const COMMISSION_LINK_STATES = ['active', 'suspended'] as const;
+export type CommissionLinkState = (typeof COMMISSION_LINK_STATES)[number];
+
+/**
+ * `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.
+ */
+export const COMMISSION_LINK_MODES = ['subnetwork', 'deeplink'] as const;
+export type CommissionLinkMode = (typeof COMMISSION_LINK_MODES)[number];
+
+/** An advertiser creative as the network feed carries it (2026-10-07). */
+export const COMMISSION_MATERIAL_KINDS = ['logo', 'banner', 'landing_preview', 'coupon'] as const;
+export type CommissionMaterialKind = (typeof COMMISSION_MATERIAL_KINDS)[number];
+
+export interface I_CommissionMaterial {
+  kind: CommissionMaterialKind;
+  /** Image or landing page; absent on a text-only coupon. */
+  url?: string;
+  /** Coupon code or creative text. */
+  text?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface I_CommissionOffer {
+  id: string;
+  /** Always 'commission': a row of this lane is never an agency listing. */
+  kind: 'commission';
+  network: CommissionNetwork;
+  /** The advertiser (programme) name, as the network names it. */
+  title: string;
+  /** The commercial terms, as the network states them (e.g. "5% od sprzedaży", "12,00 PLN za lead"). */
+  terms: string;
+  commissionType: 'CPS' | 'CPL' | 'CPC' | 'CPI';
+  plEligible: boolean;
+  /** country is always PL; niches from the programme's categories when mappable, else blank (all). */
+  derivedTargetProfile: I_TargetProfile;
+  state: CommissionOfferState;
+  lastSyncAt: string;
+  /**
+   * Advertiser materials (2026-10-07). PRESENT ONLY when that network's
+   * written-consent flag is on (Awin: DEALROOM_COMMISSION_AWIN_MATERIALS_CONSENT;
+   * Admitad: never in v1). The server strips them; the client never decides.
+   */
+  materials?: I_CommissionMaterial[];
+  /** The caller's own link to this offer, when they joined it. */
+  myLink?: I_CommissionLink;
+}
+
+export interface I_CommissionLink {
+  id: string;
+  commissionOfferId: string;
+  mode: CommissionLinkMode;
+  url: string;
+  state: CommissionLinkState;
+  /** Admitad in subnetwork mode: the creator's registered Ad Space id. */
+  adSpaceId?: string;
+}
+
+/**
+ * `GET /dealroom/commission/offers`. The lane, never mixed with agency offers.
+ * A network that failed its last sync contributes NO rows (never a stale
+ * cache shown as live) and is named in `unavailableNetworks`.
+ */
+export interface I_CommissionLane {
+  state: 'ok' | 'profile_incomplete';
+  offers: I_CommissionOffer[];
+  unavailableNetworks: CommissionNetwork[];
+  /** With `profile_incomplete`: which fields to complete (the feed's rule, FR-026). */
+  missingProfileFields?: DealroomProfileField[];
+}
+
+/** `POST /dealroom/commission/offers/:id/join`: what the join produced. */
+export const COMMISSION_JOIN_STATES = ['link', 'deeplink', 'ad_space_pending'] as const;
+export type CommissionJoinState = (typeof COMMISSION_JOIN_STATES)[number];
+
+/**
+ * `link` (200): a subnetwork link from our account, attributed to the creator.
+ * `deeplink` (200): the network's own programme page (subnetwork mode off).
+ * `ad_space_pending` (202): the creator's first Admitad join created their Ad
+ * Space for admin review; no link until it is registered.
+ */
+export interface I_CommissionJoinResult {
+  state: CommissionJoinState;
+  url?: string;
+  link?: I_CommissionLink;
+}
+
+// ── 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.
+ */
+export const COMMISSION_AD_SPACE_STATES = ['pending_review', 'registered', 'rejected', 'suspended'] as const;
+export type CommissionAdSpaceState = (typeof COMMISSION_AD_SPACE_STATES)[number];
+
+export const COMMISSION_AD_SPACE_DECISIONS = ['approve', 'reject', 'suspend'] as const;
+export type CommissionAdSpaceDecision = (typeof COMMISSION_AD_SPACE_DECISIONS)[number];
+
+/** A row of `GET /admin/dealroom/commission/ad-spaces` (admin only). */
+export interface I_CommissionAdSpace {
+  id: string;
+  network: 'admitad';
+  state: CommissionAdSpaceState;
+  creator: { userId: string; email: string | null; displayName: string | null };
+  /** The creator's connected profile URL, sent with the registration. */
+  sourceUrl: string;
+  /** Set at registration; static from then on. */
+  adSpaceId: string | null;
+  reviewedAt: string | null;
+  registeredAt: string | null;
+  createdAt: string;
+  /** How many of the creator's Admitad links are active. */
+  activeLinks: number;
+}
+
+/** `PATCH /admin/dealroom/commission/ad-spaces/:id`. */
+export class ReviewCommissionAdSpaceDto {
+  @IsIn(COMMISSION_AD_SPACE_DECISIONS as unknown as string[])
+  decision: CommissionAdSpaceDecision;
+
+  constructor(data?: Partial<ReviewCommissionAdSpaceDto>) {
+    this.decision = data?.decision as CommissionAdSpaceDecision;
+  }
+}
+
+// ── 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).
+ */
+export const DEALROOM_CALENDAR_KINDS = [
+  'milestone',
+  'application_deadline',
+  'materials_due',
+  'publication_due',
+  'publish_at',
+  'bonus_ends',
+  'keep_up_ends',
+] as const;
+export type DealroomCalendarKind = (typeof DEALROOM_CALENDAR_KINDS)[number];
+
+/** One marker on the Dashboard calendar; the marker IS the tap target. */
+export interface I_DealroomCalendarItem {
+  /** Stable per marker: `<kind>:<memberId>[:<milestoneId>]`. */
+  id: string;
+  kind: DealroomCalendarKind;
+  /** ISO timestamp of the deadline. */
+  at: string;
+  /** `milestone` only: draft_due | live_by | custom; `label` is set for custom. */
+  milestoneKind?: AgencyMilestoneKind;
+  label?: string | null;
+  /** `milestone` only: the milestone is confirmed. */
+  done?: boolean;
+  organization: { id: string; name: string };
+  campaign: { id: string; name: string; kind: AgencyCampaignKind };
+  /** The deep link into the deal: the creator's campaign + their membership + the step the date is about. */
+  target: { campaignId: string; memberId: string; step: string | null };
+}
+
+/** `GET /dealroom/calendar?from&to` — the creator's own deal dates in the window, oldest first. */
+export interface I_DealroomCalendar {
+  from: string;
+  to: string;
+  items: I_DealroomCalendarItem[];
+}
+
+/** The calendar window: both ends required, at most DEALROOM_CALENDAR_MAX_DAYS apart. */
+export const DEALROOM_CALENDAR_MAX_DAYS = 400;
+
+export class DealroomCalendarQueryDto {
+  @IsDateString()
+  from: string;
+
+  @IsDateString()
+  to: string;
+
+  constructor(data?: Partial<DealroomCalendarQueryDto>) {
+    this.from = data?.from ?? '';
+    this.to = data?.to ?? '';
+  }
+}