ad2app-lib 1.49.0 → 1.59.0

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"]);
+});

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

@@ -0,0 +1,68 @@
+/**
+ * Spec 148 wave 3 (T068/T069 US8, T067 US6, T041 US9): the wire shapes the
+ * delegation, the offer-deal publication and the calendar read. Validated
+ * through class-validator, the way the backend's global ValidationPipe reads
+ * them (an empty construct, then the body's properties assigned).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { ACTING_FOR_HEADER, UpdateGrantScopesDto } from "./agency";
+import { DEALROOM_CALENDAR_KINDS, DealroomCalendarQueryDto } from "./dealroom";
+
+const errorsOf = async (dto: object): Promise<string[]> => {
+  const { validate } = await import("class-validator");
+  return (await validate(dto)).map((e) => e.property).sort();
+};
+
+/** What the ValidationPipe does: `new Dto()`, then the body's own keys. */
+const piped = (body: Record<string, unknown>) => Object.assign(new UpdateGrantScopesDto(), body);
+
+test("the data-access screen's reads-only save is unchanged and never names deals", async () => {
+  assert.deepEqual(await errorsOf(piped({ scopes: ["analytics"] })), []);
+  assert.equal(piped({ scopes: ["analytics"] }).deals, undefined);
+  assert.deepEqual(await errorsOf(piped({ scopes: [] })), ["scopes"]);
+  assert.deepEqual(await errorsOf(piped({})), ["scopes"]);
+});
+
+test("`deals` is never a read scope: it cannot ride in `scopes`", async () => {
+  assert.deepEqual(await errorsOf(piped({ scopes: ["analytics", "deals"] })), ["scopes"]);
+});
+
+test("delegation is its own boolean, with or without the reads", async () => {
+  assert.deepEqual(await errorsOf(piped({ deals: true })), []);
+  assert.deepEqual(await errorsOf(piped({ deals: false })), []);
+  assert.deepEqual(await errorsOf(piped({ scopes: ["posts"], deals: true })), []);
+  assert.deepEqual(await errorsOf(piped({ deals: "yes" })), ["deals"]);
+  assert.deepEqual(await errorsOf(piped({ scopes: [], deals: true })), ["scopes"]);
+});
+
+test("the delegate names the creator in one header, lower-case as Node reads it", () => {
+  assert.equal(ACTING_FOR_HEADER, "x-acting-for");
+});
+
+test("the calendar window needs both ends as dates", async () => {
+  assert.deepEqual(await errorsOf(new DealroomCalendarQueryDto({ from: "2026-10-01", to: "2026-11-01" })), []);
+  assert.deepEqual(await errorsOf(new DealroomCalendarQueryDto({ from: "soon" })), ["from", "to"]);
+});
+
+test("the calendar's marker kinds, in order", () => {
+  assert.deepEqual([...DEALROOM_CALENDAR_KINDS], [
+    "milestone",
+    "application_deadline",
+    "materials_due",
+    "publication_due",
+    "publish_at",
+    "bonus_ends",
+    "keep_up_ends",
+  ]);
+});
+
+test("wave 3b: the delegate-consent code, the roster's act-for flag and the followers gap's platform", async () => {
+  const { DEALROOM_CODES } = await import("./dealroom");
+  assert.equal(DEALROOM_CODES.DELEGATE_CONSENT_FORBIDDEN, "dealroom-delegate-consent-forbidden");
+  const gap: import("./dealroom").I_NearMatchGap = { kind: "followers", platform: "tiktok", followers: 8_800, band: { min: 10_000 }, percent: 12, direction: "under" };
+  assert.equal(gap.kind === "followers" && gap.platform, "tiktok");
+  const row: import("./agency").I_AgencyRosterRow = { grantId: "g", creator: { id: "c", handle: "@a" }, platforms: [], state: "active", grantedScopes: ["analytics"], canActForCreator: true };
+  assert.equal(row.canActForCreator, true);
+});

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

@@ -0,0 +1,103 @@
+/**
+ * Spec 148 wave 4 (US5 T029/T030, US6 T032/T033, US7 T036/T037), DORMANT:
+ * the wire shapes of the contract step, the deal money and the payouts.
+ * Validated through class-validator, the way the backend's global
+ * ValidationPipe reads them (an empty construct, then the body's keys).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { AGENCY_CAMPAIGN_EVENT_KINDS } from "./agency-campaigns";
+import {
+  CreateDealContractDto,
+  DEAL_CONTRACT_SOURCES,
+  DEAL_CONTRACT_STATES,
+  DEAL_MONEY_ACTIONS,
+  DEAL_PAYMENT_METHODS,
+  DEAL_SIGNATURE_LEVELS,
+  DEALROOM_CODES,
+  DEALROOM_MONEY_EVENT_KINDS,
+  PAYOUT_PROFILE_FIELDS,
+  StartDealPaymentDto,
+  UpsertPayoutProfileDto,
+} from "./dealroom";
+
+const errorsOf = async (dto: object): Promise<string[]> => {
+  const { validate } = await import("class-validator");
+  return (await validate(dto)).map((e) => e.property).sort();
+};
+
+test("the contract step's vocabulary (data-model §dealroom_contracts)", () => {
+  assert.deepEqual([...DEAL_CONTRACT_SOURCES], ["template", "uploaded"]);
+  assert.deepEqual([...DEAL_CONTRACT_STATES], ["draft", "sent", "signed"]);
+  assert.deepEqual([...DEAL_SIGNATURE_LEVELS], ["SES", "QES"]);
+});
+
+test("a template contract takes the form fields; an upload takes the file", async () => {
+  const template = Object.assign(new CreateDealContractDto(), {
+    source: "template",
+    deliverables: ["1 reel on Instagram"],
+    liveByAt: "2026-11-01T10:00:00.000Z",
+    licenceMonths: 6,
+  });
+  assert.deepEqual(await errorsOf(template), []);
+
+  const upload = Object.assign(new CreateDealContractDto(), { source: "uploaded", fileName: "umowa.pdf", fileBase64: "JVBERi0=" });
+  assert.deepEqual(await errorsOf(upload), []);
+
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "fax" })), ["source"]);
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "template", signatureLevel: "AES" })), ["signatureLevel"]);
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "template", licenceMonths: -1 })), ["licenceMonths"]);
+});
+
+test("a payment names its method or none (card by default; invoice for big sums)", async () => {
+  assert.deepEqual([...DEAL_PAYMENT_METHODS], ["card", "invoice"]);
+  assert.deepEqual(await errorsOf(new StartDealPaymentDto()), []);
+  assert.deepEqual(await errorsOf(Object.assign(new StartDealPaymentDto(), { method: "invoice" })), []);
+  assert.deepEqual(await errorsOf(Object.assign(new StartDealPaymentDto(), { method: "cash" })), ["method"]);
+});
+
+test("the payout profile: IBAN and payout currency, nothing about a provider", async () => {
+  const ok = Object.assign(new UpsertPayoutProfileDto(), { iban: "PL61109010140000071219812874", payoutCurrency: "PLN", nip: "5260250274" });
+  assert.deepEqual(await errorsOf(ok), []);
+  assert.deepEqual(await errorsOf(Object.assign(new UpsertPayoutProfileDto(), { iban: "not an iban", payoutCurrency: "PLN" })), ["iban"]);
+  assert.deepEqual(await errorsOf(Object.assign(new UpsertPayoutProfileDto(), { iban: "PL61109010140000071219812874", payoutCurrency: "zł" })), ["payoutCurrency"]);
+  assert.equal("stripeAccountId" in ok, false);
+  assert.deepEqual([...PAYOUT_PROFILE_FIELDS], ["settlement_form", "nip", "tax_statement", "intl_billing_data", "iban", "payout_currency"]);
+});
+
+test("the money acts a deal view offers its reader", () => {
+  assert.deepEqual([...DEAL_MONEY_ACTIONS], ["send_contract", "pay_deposit", "decline_deposit", "fund", "refund", "claim_guarantee"]);
+});
+
+test("the four wave-4 codes are added, never renamed", () => {
+  assert.equal(DEALROOM_CODES.DEAL_BELOW_MINIMUM, "dealroom-deal-below-minimum");
+  assert.equal(DEALROOM_CODES.MONEY_WRONG_STEP, "dealroom-money-wrong-step");
+  assert.equal(DEALROOM_CODES.CONTRACT_EXISTS, "dealroom-contract-exists");
+  assert.equal(DEALROOM_CODES.GUARANTEE_UNAVAILABLE, "dealroom-guarantee-unavailable");
+});
+
+test("contract, money and payout steps are kinds in 175's one event log (FR-008a)", () => {
+  for (const kind of DEALROOM_MONEY_EVENT_KINDS) {
+    assert.ok((AGENCY_CAMPAIGN_EVENT_KINDS as readonly string[]).includes(kind), kind);
+    assert.ok(kind.length <= 32, kind);
+  }
+  assert.deepEqual([...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",
+  ]);
+});
+
+test("a payout profile with no payable settlement form names no billing variant", () => {
+  const profile: import("./dealroom").I_PayoutProfile = { billingVariant: null, track: null, payoutCurrency: "PLN", kycState: "none" };
+  assert.equal(profile.billingVariant, null);
+});