ad2app-lib 1.50.0 → 1.59.0

package/src/types/agency-campaigns.ts

@@ -6,6 +6,7 @@ import {
   IsIn,
   IsInt,
   IsNotEmpty,
+  IsObject,
   IsOptional,
   IsString,
   Matches,
@@ -18,6 +19,7 @@ import { I_MediaStage } from './I_Media';
 import { I_OfferStatus } from './I_Offer';
 import { AGENCY_GRANT_SCOPES, type I_AgencyGrantScope } from './agency';
 import { PotFields, type I_AgencyPotView, type I_CampaignFile, type I_CreatorPotView, type I_DisclosureCheck } from './agency-pots';
+import { CAMPAIGN_VISIBILITIES, type CampaignVisibility, type I_CampaignListing, type I_TargetProfile } from './dealroom';
 
 /**
  * The campaign loop (spec 175 US7) — an organization runs a campaign with the
@@ -80,6 +82,10 @@ export type AgencyCampaignKind = (typeof AGENCY_CAMPAIGN_KINDS)[number];
 export const AGENCY_CAMPAIGN_MEMBER_STATES = ['invited', 'joined', 'declined', 'left', 'removed'] as const;
 export type AgencyCampaignMemberState = (typeof AGENCY_CAMPAIGN_MEMBER_STATES)[number];
 
+/** How a creator came onto a campaign: 175's invitation, or a Dealroom application to an open listing (spec 148). */
+export const AGENCY_CAMPAIGN_MEMBER_ORIGINS = ['invitation', 'application'] as const;
+export type AgencyCampaignMemberOrigin = (typeof AGENCY_CAMPAIGN_MEMBER_ORIGINS)[number];
+
 /** The offer statuses the agency loop writes. `draft`, `deleted` and `alternativeSuggested` are legacy-only. */
 export const AGENCY_OFFER_STATUSES = [
   I_OfferStatus.SENT,
@@ -99,9 +105,13 @@ export type CampaignSide = 'agency' | 'creator';
  * right now is the server's `availableActions`, never a client guess.
  *
  *   agency:  counter · confirm · reject
- *   creator: accept · counter · reject
+ *   creator: accept · counter · reject · apply
+ *
+ * `apply` (spec 148) is the creator's opening price on an open listing, with
+ * no offer yet: it lands in the existing negotiating status, the agency's
+ * turn. No offer status is added for it.
  */
-export const AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject'] as const;
+export const AGENCY_OFFER_ACTIONS = ['accept', 'counter', 'confirm', 'reject', 'apply'] as const;
 export type AgencyOfferAction = (typeof AGENCY_OFFER_ACTIONS)[number];
 
 /** The agency's acts on the latest material; the creator's only act is to upload. */
@@ -178,6 +188,20 @@ export const AGENCY_CAMPAIGN_EVENT_KINDS = [
   'caption_edited',
   'file_uploaded',
   'file_removed',
+  // Spec 148 money release (DORMANT): the contract, money and payout steps of a
+  // Dealroom deal are kinds in this one log (FR-008a). Mirrored by
+  // DEALROOM_MONEY_EVENT_KINDS in dealroom.ts.
+  '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 AgencyCampaignEventKind = (typeof AGENCY_CAMPAIGN_EVENT_KINDS)[number];
 
@@ -279,6 +303,21 @@ export interface I_AgencyCampaignEvent {
   /** A pot act's amount: a refill, a move, a reserved guarantee, an accrued bonus. */
   amount?: I_Money;
   note?: string;
+  /** Set when a delegate acted on the creator's side through a `deals` grant (spec 148 FR-017a). */
+  actingGrantId?: string;
+  /** With `actingGrantId`: the member who acted, shown as "<member> for <creator>". */
+  actingMemberName?: string;
+  /** The act came from the creator's Dealroom application (spec 148 US4), not an invitation. */
+  fromApplication?: true;
+}
+
+/** Spec 148 US8 AC3: one act a manager did in the creator's deal, for the creator's own view. */
+export interface I_CreatorDelegateAct {
+  kind: AgencyCampaignEventKind;
+  at: string;
+  /** The member of the managing agency who acted. */
+  memberName: string;
+  organizationName: string;
 }
 
 export interface I_CampaignCreatorIdentity {
@@ -293,6 +332,8 @@ export interface I_AgencyCampaignMemberRow {
   memberId: string;
   creator: I_CampaignCreatorIdentity;
   state: AgencyCampaignMemberState;
+  /** Invitation or Dealroom application (spec 148). Absent on older backends: read as 'invitation'. */
+  origin?: AgencyCampaignMemberOrigin;
   /** The board column, or the reason the row is off the board. */
   step: AgencyCampaignStep | AgencyCampaignOffBoard;
   /** When the row reached its current step. */
@@ -346,6 +387,8 @@ export interface I_AgencyCampaign {
   milestones: I_AgencyMilestone[];
   pipeline: I_AgencyCampaignPipeline;
   createdAt: string;
+  /** Spec 148: the Dealroom listing fields and their derived state. Absent on older backends. */
+  listing?: I_CampaignListing;
 }
 
 /** Opening one creator (FR-024): their course with dates, notes, files and milestones. */
@@ -355,6 +398,31 @@ export interface I_AgencyCampaignCreatorDetail {
   events: I_AgencyCampaignEvent[];
   materials: I_AgencyMaterial[];
   milestones: I_AgencyMilestone[];
+  /** Spec 148 T067: an offer deal's agreed publication time. Absent on a pot (its entry carries it) and on older backends. */
+  publication?: I_OfferPublication | null;
+}
+
+/**
+ * Spec 148 T067: an OFFER deal publishes through 175 US9's auto-publish path.
+ * The organization sets the agreed time on a confirmed offer with an approved
+ * material (`PATCH /agency/campaigns/:id/members/:memberId/publish-at`); the
+ * creator confirms that exact time once (`POST /agency/campaign-invitations/
+ * :memberId/publish-at/confirm`, the same route as a pot's); the post then goes
+ * out from the creator's own account, and publication is known by construction.
+ * `POST .../members/:memberId/published` stays for off-platform posting.
+ */
+export interface I_OfferPublication {
+  publishAt: string | null;
+  publishConfirmedAt: string | null;
+  /** The post is scheduled on the creator's account (the confirmed time is within the signed-link horizon). */
+  scheduled: boolean;
+  publishedAt: string | null;
+  /** The latest refusal at scheduling since the time was set or confirmed; the creator confirms again. */
+  publishRefusal: { at: string; reason: string } | null;
+  /** Organization side: the offer is confirmed, the latest material approved, and nothing is published yet. */
+  canSetPublishAt: boolean;
+  /** Creator side: a time is set and not confirmed, and the latest material's caption passes the disclosure check. */
+  canConfirmPublishAt: boolean;
 }
 
 /** `GET /agency/campaigns/attention` — what waits on the agency (FR-022, the rail). */
@@ -416,6 +484,10 @@ export interface I_CreatorCampaignView {
   canLeave: boolean;
   milestones: I_AgencyMilestone[];
   invitedAt: string;
+  /** Spec 148 T067: an offer deal's agreed publication time; null on a pot (see `pot.entry`) and before a confirmed offer. */
+  publication?: I_OfferPublication | null;
+  /** Spec 148 US8 AC3: what a manager did in this deal for the creator, oldest first. Absent on older backends. */
+  delegateActs?: I_CreatorDelegateAct[];
 }
 
 /** `GET /agency/campaign-invitations/mine` — pending invitations and live campaigns. */
@@ -484,8 +556,42 @@ class AgencyCampaignBriefFields extends PotFields {
   @Max(20)
   revisionRounds?: number | null;
 
+  // ── Spec 148: the open listing. Refused by the backend while DEALROOM_ENABLED is off. ──
+
+  /** `open` lists the campaign in the Dealroom feed; it needs a target profile and the organization's logo. */
+  @IsOptional()
+  @IsIn(CAMPAIGN_VISIBILITIES as unknown as string[])
+  visibility?: CampaignVisibility;
+
+  /** Checked field by field in the service (flat bodies, see above). Blank constraint = no filter. */
+  @IsOptional()
+  @IsObject()
+  targetProfile?: I_TargetProfile | null;
+
+  /** Null = unlimited. Once frozen, it may only grow. */
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(10000)
+  slots?: number | null;
+
+  /** Offer kind only (a pot keeps its own). Once frozen, it may only move later. */
+  @IsOptional()
+  @IsDateString()
+  applicationDeadline?: string | null;
+
+  /** Any date closes the listing NOW (server time): new applications stop, running deals do not. */
+  @IsOptional()
+  @IsDateString()
+  closedAt?: string | null;
+
   protected assignBrief(data?: Partial<AgencyCampaignBriefFields>): void {
     this.assignPot(data);
+    this.visibility = data?.visibility;
+    this.targetProfile = data?.targetProfile;
+    this.slots = data?.slots;
+    this.applicationDeadline = data?.applicationDeadline;
+    this.closedAt = data?.closedAt;
     this.text = data?.text;
     this.deliverables = data?.deliverables;
     this.draftDueAt = data?.draftDueAt;

package/src/types/agency-threads.ts

@@ -1,6 +1,7 @@
 import { IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
 
 import type { CampaignSide, I_CampaignCreatorIdentity } from './agency-campaigns';
+import type { AgencyOrganizationType } from './agency';
 
 /**
  * Agency ↔ creator threads (spec 175 US8, FR-023): one conversation per
@@ -36,15 +37,25 @@ 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. */
-  organization: { id: string; name: string };
-  lastMessage: { side: CampaignSide; body: string; at: string } | null;
+  /** 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/src/types/agency.ts

@@ -11,6 +11,7 @@ import {
   IsUUID,
   Length,
   Matches,
+  ValidateIf,
 } from 'class-validator';
 
 /**
@@ -87,10 +88,37 @@ export type I_AgencyGrantScope = (typeof AGENCY_GRANT_SCOPES)[number];
 export const isAgencyGrantScope = (value: string): value is I_AgencyGrantScope =>
   (AGENCY_GRANT_SCOPES as readonly string[]).includes(value);
 
+/**
+ * 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 const DELEGATION_SCOPES = ['deals'] as const;
+
+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 const isGrantScope = (value: string): value is I_GrantScope =>
+  isAgencyGrantScope(value) || (DELEGATION_SCOPES as readonly string[]).includes(value);
+
 // ── Organization ─────────────────────────────────────────────────────────────
 
-/** `'brand'` arrives with spec 148; one column, no enum table. */
-export type AgencyOrganizationType = 'agency';
+/**
+ * `'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 const AGENCY_ORGANIZATION_TYPES = ['agency', 'brand'] as const;
+
+export type AgencyOrganizationType = (typeof AGENCY_ORGANIZATION_TYPES)[number];
 
 /**
  * `closed` was added by the 2026-09-21 requirements review (FR-004b).
@@ -134,6 +162,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;
@@ -182,7 +215,14 @@ export const CREATOR_ACCESS_GRANT_STATES = [
 
 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 const CREATOR_ACCESS_GRANT_ORIGINS = ['invite_link', 'agency_request', 'dealroom_application'] as const;
+
+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 =
@@ -203,10 +243,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; displayName?: string };
   state: CreatorAccessGrantState;
@@ -357,6 +406,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;
 }
 
 /**
@@ -534,7 +589,24 @@ export class CreateAgencyOrganizationDto {
   @IsEmail()
   contactEmail: string;
 
+  /** Spec 148 US2: absent = `agency`. `brand` is refused while the backend's brand door is closed. */
+  @IsOptional()
+  @IsIn(AGENCY_ORGANIZATION_TYPES as unknown as string[])
+  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).
+   */
+  @IsOptional()
+  @IsString()
+  @Matches(/^pm_[A-Za-z0-9]{1,200}$/)
+  paymentMethodId?: string;
+
   constructor(data?: Partial<CreateAgencyOrganizationDto>) {
+    this.type = data?.type;
+    this.paymentMethodId = data?.paymentMethodId;
     this.name = data?.name ?? '';
     this.website = data?.website;
     this.registryId = data?.registryId ?? '';
@@ -600,18 +672,44 @@ export class 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 class UpdateGrantScopesDto {
+  @ValidateIf((dto: UpdateGrantScopesDto) => dto.deals === undefined || dto.scopes !== undefined)
   @IsArray()
   @ArrayNotEmpty()
   @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
-  scopes: I_AgencyGrantScope[];
+  scopes?: I_AgencyGrantScope[];
+
+  /** Let this organization run my deals (spec 148 US8). Creator-only; absent = unchanged. */
+  @IsOptional()
+  @IsBoolean()
+  deals?: boolean;
 
   constructor(data?: Partial<UpdateGrantScopesDto>) {
-    this.scopes = data?.scopes ?? [];
+    // Undefined when not given (never []): class-transformer builds the body
+    // with an empty construct, and a default would make `{ deals: true }` fail.
+    if (data?.scopes !== undefined) this.scopes = data.scopes;
+    if (data?.deals !== undefined) this.deals = data.deals;
   }
 }
 
+/**
+ * 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 const ACTING_FOR_HEADER = 'x-acting-for';
+
 export class SponsorCreatorDto {
   @IsIn(['starter', 'pro'])
   tier: SponsoredTier;
@@ -695,6 +793,21 @@ 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 class AdminSetOrganizationStatusDto {
   @IsIn(['approved', 'rejected'])
   status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;

package/src/types/consumer-compat.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Review #5 (H4): this minor must not break code written against 1.50.0. The
+ * fixture below is how the backend's and the frontend's master use the grant
+ * types (grant-view.ts, AgencyJoinPage, AgencyRequestPage, DataAccessSection);
+ * it type-checks against the current sources with the real compiler, so a
+ * widening that breaks a consumer fails here, not after the publish.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import ts from "typescript";
+
+const TYPES = resolve(__dirname, "index").replace(/\\/g, "/");
+
+const FIXTURE = `
+import {
+  AGENCY_GRANT_SCOPES,
+  type I_AgencyGrantScope,
+  type I_CreatorAccessGrant,
+  type I_AgencyRosterRow,
+  type CreatorAccessGrantOrigin,
+  type AgencyOrganizationType,
+  UpdateGrantScopesDto,
+} from "${TYPES}";
+
+declare const grant: I_CreatorAccessGrant;
+declare const row: I_AgencyRosterRow;
+declare const reask: { scopes: I_AgencyGrantScope[] } | null;
+const inCanonicalOrder = (scopes: readonly I_AgencyGrantScope[]): I_AgencyGrantScope[] =>
+  AGENCY_GRANT_SCOPES.filter((s) => scopes.includes(s));
+const word = (scope: I_AgencyGrantScope): string => scope;
+
+// frontend master: AgencyJoinPage:177, AgencyRequestPage:91/190, DataAccessSection:244
+(grant.grantedScopes ?? []).map((scope) => word(scope));
+inCanonicalOrder(grant.grantedScopes ?? []);
+const initial: I_AgencyGrantScope[] = grant.grantedScopes ?? [];
+const missing = AGENCY_GRANT_SCOPES.filter((s) => !row.grantedScopes.includes(s));
+
+// backend master: grant-view.ts builds the row from 175's columns
+declare const columns: { granted: I_AgencyGrantScope[]; requested: I_AgencyGrantScope[]; origin: 'invite_link' | 'agency_request' };
+const built: I_CreatorAccessGrant = {
+  id: "g", organizationId: "o", organizationName: "O",
+  requestedScopes: columns.requested,
+  grantedScopes: columns.granted,
+  creatorIdentity: { handle: "h" },
+  state: "active",
+  origin: columns.origin,
+  platformsReached: [],
+  ...(reask ? { reaskedScopes: reask.scopes, reaskExpiresAt: "x" } : {}),
+};
+
+// backend master: the scope update reads dto.scopes as the new reads
+declare const dto: UpdateGrantScopesDto;
+const next: I_AgencyGrantScope[] = dto?.scopes;
+
+const origin: CreatorAccessGrantOrigin = "agency_request";
+const type: AgencyOrganizationType = "agency";
+export { initial, missing, built, next, origin, type };
+`;
+
+test("1.50.0 consumer code type-checks against this version (no breaking widening)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "lib-compat-"));
+  const file = join(dir, "consumer.ts");
+  writeFileSync(file, FIXTURE);
+  const program = ts.createProgram([file], {
+    // Both consumers compile with strict off (backend: unset, frontend: false).
+    strict: false,
+    noEmit: true,
+    target: ts.ScriptTarget.ES2020,
+    module: ts.ModuleKind.CommonJS,
+    moduleResolution: ts.ModuleResolutionKind.Node10,
+    experimentalDecorators: true,
+    emitDecoratorMetadata: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+  });
+  const errors = ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file?.fileName === file)
+    .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n").split("\n")[0]);
+  assert.deepEqual(errors, []);
+});
+
+test("delegation rides in its own field, never in grantedScopes", () => {
+  const grant: Pick<import("./agency").I_CreatorAccessGrant, "grantedScopes" | "deals"> = { grantedScopes: ["analytics"], deals: true };
+  assert.equal(grant.deals, true);
+  assert.deepEqual(grant.grantedScopes, ["analytics"]);
+});

package/src/types/dealroom-audit1.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Spec 148 audit #1: the additive wire fields the fixes need. Pinned
+ * so a rename is a decision: the terms-version refusal code the frontend
+ * words, and the optional fields an older backend simply leaves out.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { ACCESS_DENIAL_CODES } from "./I_AccessDenial";
+import type { I_AgencyCampaignEvent, I_CreatorCampaignView, I_CreatorDelegateAct } from "./agency-campaigns";
+import type { I_DealContract, I_DealroomListing } from "./dealroom";
+import type { I_CreatorAccessGrant } from "./agency";
+
+test("an unset terms version is a coded refusal, never a 500", () => {
+  assert.equal(ACCESS_DENIAL_CODES.AGENCY_TERMS_VERSION_MISSING, "agency-terms-version-missing");
+});
+
+test("the listing names its campaign; an older backend may leave it out", () => {
+  const named: Pick<I_DealroomListing, "campaignName"> = { campaignName: "Poranna rutyna" };
+  const older: Pick<I_DealroomListing, "campaignName"> = {};
+  assert.equal(named.campaignName, "Poranna rutyna");
+  assert.equal(older.campaignName, undefined);
+});
+
+test("a contract carries the caller's own signing link, when there is one", () => {
+  const mine: Pick<I_DealContract, "signingUrl"> = { signingUrl: "https://sign.example.test/s/1" };
+  const none: Pick<I_DealContract, "signingUrl"> = { signingUrl: null };
+  assert.ok(mine.signingUrl);
+  assert.equal(none.signingUrl, null);
+});
+
+test("an application's events are marked as such, not as a note", () => {
+  const event: I_AgencyCampaignEvent = { kind: "joined", side: "creator", at: "2026-10-07T10:00:00.000Z", fromApplication: true };
+  assert.equal(event.fromApplication, true);
+  assert.equal(event.note, undefined);
+});
+
+test("the creator's own view lists what a manager did for them", () => {
+  const act: I_CreatorDelegateAct = { kind: "material_uploaded", at: "2026-10-07T10:00:00.000Z", memberName: "Ola", organizationName: "Demo Talent Studio" };
+  const view: Pick<I_CreatorCampaignView, "delegateActs"> = { delegateActs: [act] };
+  assert.equal(view.delegateActs?.[0].memberName, "Ola");
+});
+
+test("a grant names its organization's type, so a brand is never offered `deals`", () => {
+  const grant: Pick<I_CreatorAccessGrant, "organizationType"> = { organizationType: "brand" };
+  assert.equal(grant.organizationType, "brand");
+});
+
+test("review #14/#28: money-off, an unset value, a waiting template and a missing logo are four codes", async () => {
+  const { DEALROOM_CODES } = await import("./dealroom");
+  assert.equal(DEALROOM_CODES.MONEY_DISABLED, "dealroom-money-disabled");
+  assert.equal(DEALROOM_CODES.CONFIG_MISSING, "dealroom-config-missing");
+  assert.equal(DEALROOM_CODES.TEMPLATE_PENDING, "dealroom-template-pending");
+  assert.equal(DEALROOM_CODES.LOGO_REQUIRED, "dealroom-logo-required");
+  assert.equal(new Set(Object.values(DEALROOM_CODES)).size, Object.values(DEALROOM_CODES).length);
+});

package/src/types/dealroom-wave2.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Spec 148 wave 2 (T023-T027, T063): the wire shapes the listing, the brand
+ * door and the apply route read. Validated through class-validator, the way
+ * the backend's global ValidationPipe reads them.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { AdminSetOrganizationStatusDto, CreateAgencyOrganizationDto } from "./agency";
+import { CreateAgencyCampaignDto, UpdateAgencyCampaignDto } from "./agency-campaigns";
+import { ApplyToDealroomListingDto, DEALROOM_LISTING_STATES } from "./dealroom";
+
+const errorsOf = async (dto: object): Promise<string[]> => {
+  const { validate } = await import("class-validator");
+  return (await validate(dto)).map((e) => e.property);
+};
+
+const org = { name: "Marka", registryId: "1", registryCountry: "PL", contactEmail: "a@b.pl" };
+
+test("an organization's type is optional (agency) and only agency or brand", async () => {
+  assert.deepEqual(await errorsOf(new CreateAgencyOrganizationDto(org)), []);
+  assert.deepEqual(await errorsOf(new CreateAgencyOrganizationDto({ ...org, type: "brand" })), []);
+  assert.deepEqual(await errorsOf(new CreateAgencyOrganizationDto({ ...org, type: "school" as never })), ["type"]);
+  assert.ok(new AdminSetOrganizationStatusDto());
+});
+
+test("the listing fields ride on 175's campaign bodies, each optional and checked", async () => {
+  assert.deepEqual(await errorsOf(new CreateAgencyCampaignDto({ name: "X" })), []);
+  assert.deepEqual(
+    await errorsOf(
+      new UpdateAgencyCampaignDto({
+        visibility: "open",
+        targetProfile: { platforms: ["tiktok"], followerBand: {}, niches: ["beauty"] },
+        slots: 3,
+        applicationDeadline: "2026-12-01T00:00:00.000Z",
+        closedAt: "2026-11-01T00:00:00.000Z",
+      }),
+    ),
+    [],
+  );
+  assert.deepEqual(
+    (await errorsOf(new UpdateAgencyCampaignDto({ visibility: "public" as never, slots: 0, applicationDeadline: "soon" }))).sort(),
+    ["applicationDeadline", "slots", "visibility"],
+  );
+});
+
+test("an application names at least one scope, from the reads only", async () => {
+  assert.deepEqual(await errorsOf(new ApplyToDealroomListingDto({ scopes: ["analytics"], priceMinor: 100, currency: "PLN" })), []);
+  assert.deepEqual(await errorsOf(new ApplyToDealroomListingDto({ scopes: [] })), ["scopes"]);
+  assert.deepEqual(await errorsOf(new ApplyToDealroomListingDto({ scopes: ["deals" as never] })), ["scopes"]);
+  assert.deepEqual(await errorsOf(new ApplyToDealroomListingDto({ scopes: ["posts"], currency: "zł" })), ["currency"]);
+});
+
+test("the derived listing states, in order", () => {
+  assert.deepEqual([...DEALROOM_LISTING_STATES], ["draft", "live", "frozen", "closed"]);
+});
+
+test("a brand's first-charge card is optional and a Stripe payment method id only (dormant)", async () => {
+  assert.deepEqual(await errorsOf(new CreateAgencyOrganizationDto({ ...org, type: "brand", paymentMethodId: "pm_123abc" })), []);
+  assert.deepEqual(await errorsOf(new CreateAgencyOrganizationDto({ ...org, type: "brand", paymentMethodId: "4242424242424242" })), ["paymentMethodId"]);
+});