ad2app-lib 1.44.0 → 1.47.0

package/dist/types/agency.js

@@ -1,20 +1,16 @@
 "use strict";
-/**
- * Agency domain — organizations, memberships and creator access grants (spec 175).
- *
- * The shape behind "an agency sees its creators' numbers, because the creators
- * said yes". Two doors, one product: a creator account is unchanged by any of
- * this, and gains at most one grant.
- *
- * The one idea worth carrying into every consumer: a GRANT IS READ-ONLY AND
- * CREATOR-OWNED. The agency asks for scopes; only a creator's own act ever
- * writes `grantedScopes` (FR-008, SC-002). Nothing here can express a write on
- * a creator's account, and that is deliberate — the absence is the feature.
- *
- * See specs/175-agency-roster/contracts/lib-types.md.
- */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdminSetOrganizationStatusDto = exports.AgencyAccessRequestDto = exports.AgencyDiscoverQueryDto = exports.SponsorCreatorDto = exports.UpdateGrantScopesDto = exports.AcceptGrantDto = exports.AcceptAgencyMemberInviteDto = exports.RedeemAgencyInviteDto = exports.InviteAgencyMemberDto = exports.CreateAgencyOrganizationDto = exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = exports.AGENCY_ROSTER_ROW_STATES = exports.CREATOR_ACCESS_GRANT_STATES = exports.AGENCY_ORGANIZATION_STATUSES = exports.isAgencyGrantScope = exports.AGENCY_GRANT_SCOPES = exports.AGENCY_ROUTE_PATHS = void 0;
+exports.AdminSetOrganizationStatusDto = exports.UpdateAgencyDiscoverableDto = exports.AgencyAccessRequestDto = exports.AgencyDiscoverQueryDto = exports.SponsorCreatorDto = exports.UpdateGrantScopesDto = exports.AcceptGrantDto = exports.AcceptAgencyMemberInviteDto = exports.RedeemAgencyInviteDto = exports.InviteAgencyMemberDto = exports.CreateAgencyOrganizationDto = exports.AGENCY_ROSTER_METRICS_STATES = exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = exports.AGENCY_ROSTER_ROW_STATES = exports.AGENCY_REQUEST_CODES = exports.CREATOR_ACCESS_GRANT_STATES = exports.AGENCY_ORGANIZATION_STATUSES = exports.isAgencyGrantScope = exports.AGENCY_GRANT_SCOPES = exports.AGENCY_ROUTE_PATHS = void 0;
+const class_validator_1 = require("class-validator");
 // ── Cross-repo route constants ───────────────────────────────────────────────
 /**
  * Paths that BOTH repos have to agree on, with one home here.
@@ -93,6 +89,16 @@ exports.CREATOR_ACCESS_GRANT_STATES = [
     'expired',
     'revoked',
 ];
+/**
+ * Outcomes of discovery and requests that are not refusals of access, sent as
+ * codes so the screen composes the sentence in the reader's language (FR-019,
+ * review M4). A 429 carries `{ code, limit, windowMinutes }`.
+ */
+exports.AGENCY_REQUEST_CODES = {
+    RATE_LIMITED: 'agency-rate-limited',
+    REQUEST_EXPIRED: 'agency-request-expired',
+    REQUEST_ANSWERED: 'agency-request-answered',
+};
 // ── Roster ───────────────────────────────────────────────────────────────────
 /**
  * Roster row states, DECLARED IN PRECEDENCE ORDER (data-model §Derived).
@@ -108,6 +114,13 @@ exports.AGENCY_ROSTER_ROW_STATES = [
     'lapsed',
     /** the creator has no live platform connection */
     'disconnected',
+    /**
+     * shared within the last 24 hours and not synced yet: the first daily sync
+     * has not run. Not stale, and not something the agency can act on (T067,
+     * the 2026-09-26 UI run: a creator who agreed a minute ago read as
+     * "needs attention").
+     */
+    'syncing',
     /** no successful daily sync in 24 hours (FR-011, Jan 2026-09-21) */
     'stale',
     'active',
@@ -124,77 +137,213 @@ exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = [
     'disconnected',
     'stale',
 ];
+/**
+ * The rows that carry numbers — ONE home for "which creators' numbers may the
+ * agency see on the roster" (decided 2026-09-24, review M1/M2).
+ *
+ * Only a row whose card OPENS carries `metrics` and counts in the followers,
+ * followers-delta and comments totals: `active`, and `stale` (the card opens;
+ * the numbers are as old as `lastSyncAt` says). A `lapsed` creator's reads are
+ * refused on the card, so their numbers must not reach the agency through the
+ * roster instead; a `disconnected` creator has nothing live to count; a
+ * `requested` creator has shared nothing yet.
+ */
+exports.AGENCY_ROSTER_METRICS_STATES = [
+    'syncing',
+    'stale',
+    'active',
+];
 // ── DTOs ─────────────────────────────────────────────────────────────────────
+/**
+ * Every DTO below carries class-validator decorators and a constructor that
+ * survives being called with nothing.
+ *
+ * Both are load-bearing and were missing until 2026-09-22. The backend mounts
+ * a global `ValidationPipe`, which validates the decorated metadata of the
+ * class a handler's `@Body()` is typed with — an undecorated class, or a body
+ * typed as a plain interface, is simply passed through unchecked. And the pipe
+ * instantiates the class with NO arguments, so a constructor that reads
+ * `data.name` would throw a TypeError on every request rather than validate
+ * anything. The rest of this library's DTOs take `data?: Partial<T>` for that
+ * reason; these now do too.
+ */
 class CreateAgencyOrganizationDto {
     constructor(data) {
-        this.name = data.name;
-        this.website = data.website;
-        this.registryId = data.registryId;
-        this.registryCountry = data.registryCountry;
-        this.contactEmail = data.contactEmail;
+        this.name = data?.name ?? '';
+        this.website = data?.website;
+        this.registryId = data?.registryId ?? '';
+        this.registryCountry = data?.registryCountry ?? '';
+        this.contactEmail = data?.contactEmail ?? '';
     }
 }
 exports.CreateAgencyOrganizationDto = CreateAgencyOrganizationDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "name", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsUrl)({ protocols: ['http', 'https'], require_protocol: true }),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "website", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "registryId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Length)(2, 2),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "registryCountry", void 0);
+__decorate([
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "contactEmail", void 0);
 class InviteAgencyMemberDto {
     constructor(data) {
-        this.email = data.email;
+        this.email = data?.email ?? '';
     }
 }
 exports.InviteAgencyMemberDto = InviteAgencyMemberDto;
+__decorate([
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], InviteAgencyMemberDto.prototype, "email", void 0);
 class RedeemAgencyInviteDto {
     constructor(data) {
-        this.token = data.token;
+        this.token = data?.token ?? '';
     }
 }
 exports.RedeemAgencyInviteDto = RedeemAgencyInviteDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RedeemAgencyInviteDto.prototype, "token", void 0);
 class AcceptAgencyMemberInviteDto {
     constructor(data) {
-        this.token = data.token;
+        this.token = data?.token ?? '';
     }
 }
 exports.AcceptAgencyMemberInviteDto = AcceptAgencyMemberInviteDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AcceptAgencyMemberInviteDto.prototype, "token", void 0);
 /**
  * Accepting consent. Either arm identifies the grant being answered; `scopes`
  * is the creator's answer and defaults to the requested set when absent.
  */
 class AcceptGrantDto {
     constructor(data) {
-        this.token = data.token;
-        this.grantId = data.grantId;
-        this.scopes = data.scopes;
+        this.token = data?.token;
+        this.grantId = data?.grantId;
+        this.scopes = data?.scopes;
     }
 }
 exports.AcceptGrantDto = AcceptGrantDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AcceptGrantDto.prototype, "token", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsUUID)(),
+    __metadata("design:type", String)
+], AcceptGrantDto.prototype, "grantId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], AcceptGrantDto.prototype, "scopes", void 0);
 /** The creator narrowing or widening a live grant — the only other write path. */
 class UpdateGrantScopesDto {
     constructor(data) {
-        this.scopes = data.scopes;
+        this.scopes = data?.scopes ?? [];
     }
 }
 exports.UpdateGrantScopesDto = UpdateGrantScopesDto;
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], UpdateGrantScopesDto.prototype, "scopes", void 0);
 class SponsorCreatorDto {
     constructor(data) {
-        this.tier = data.tier;
+        this.tier = data?.tier ?? 'starter';
     }
 }
 exports.SponsorCreatorDto = SponsorCreatorDto;
+__decorate([
+    (0, class_validator_1.IsIn)(['starter', 'pro']),
+    __metadata("design:type", String)
+], SponsorCreatorDto.prototype, "tier", void 0);
 class AgencyDiscoverQueryDto {
     constructor(data) {
-        this.q = data.q;
+        this.q = data?.q ?? '';
     }
 }
 exports.AgencyDiscoverQueryDto = AgencyDiscoverQueryDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AgencyDiscoverQueryDto.prototype, "q", void 0);
 class AgencyAccessRequestDto {
     constructor(data) {
-        this.userId = data.userId;
-        this.scopes = data.scopes;
+        this.userId = data?.userId ?? '';
+        this.scopes = data?.scopes ?? [];
     }
 }
 exports.AgencyAccessRequestDto = AgencyAccessRequestDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/^[A-Za-z0-9-]{1,128}$/),
+    __metadata("design:type", String)
+], AgencyAccessRequestDto.prototype, "userId", void 0);
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], AgencyAccessRequestDto.prototype, "scopes", void 0);
+/** `PATCH /users/me/agency-discoverable` — "Let agencies find me" (FR-015). */
+class UpdateAgencyDiscoverableDto {
+    /**
+     * NO default: a required boolean that defaults to false lets an empty body
+     * through validation and reach the database as `undefined` (review M7).
+     */
+    constructor(data) {
+        if (data?.discoverable !== undefined)
+            this.discoverable = data.discoverable;
+    }
+}
+exports.UpdateAgencyDiscoverableDto = UpdateAgencyDiscoverableDto;
+__decorate([
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], UpdateAgencyDiscoverableDto.prototype, "discoverable", void 0);
 class AdminSetOrganizationStatusDto {
     constructor(data) {
-        this.status = data.status;
-        this.reason = data.reason;
+        this.status = data?.status ?? 'approved';
+        this.reason = data?.reason;
     }
 }
 exports.AdminSetOrganizationStatusDto = AdminSetOrganizationStatusDto;
+__decorate([
+    (0, class_validator_1.IsIn)(['approved', 'rejected']),
+    __metadata("design:type", Object)
+], AdminSetOrganizationStatusDto.prototype, "status", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], AdminSetOrganizationStatusDto.prototype, "reason", void 0);

package/dist/types/scheduling/I_SchedulingProUpgrade.d.ts

@@ -4,13 +4,14 @@
  * Covers subscription tier state, Stripe checkout flows,
  * and the customer portal redirect.
  */
+import type { I_SponsoredBy, I_SponsorshipEnded } from '../agency';
 export type SchedulingSubscriptionTier = 'free' | 'starter' | 'pro';
 export type SchedulingSubscriptionStatus = 'active' | 'canceled' | 'expired';
 /**
  * Constructor input. Takes `maxAccounts`, or the deprecated `maxPlatforms` so
  * code written against 1.40.0 keeps compiling; either way both fields are set.
  */
-export type SchedulingSubscriptionInfoInput = Pick<SchedulingSubscriptionInfoDTO, 'tier' | 'status' | 'expiresAt'> & ({
+export type SchedulingSubscriptionInfoInput = Pick<SchedulingSubscriptionInfoDTO, 'tier' | 'status' | 'expiresAt'> & Partial<Pick<SchedulingSubscriptionInfoDTO, 'sponsoredBy' | 'sponsorshipEnded'>> & ({
     maxAccounts: number;
     maxPlatforms?: number;
 } | {
@@ -32,6 +33,14 @@ export declare class SchedulingSubscriptionInfoDTO {
      * Read `maxAccounts`. Always equal to it; removed in a later release.
      */
     maxPlatforms: number;
+    /**
+     * Present only while an agency covers this creator's plan (spec 175 FR-014).
+     * `until` appears once the sponsorship is ending: the date the plan runs to.
+     * Absent — never null — for everyone else, so "not sponsored" has one shape.
+     */
+    sponsoredBy?: I_SponsoredBy;
+    /** Present only when a coverage ended recently and nothing replaced it. Absent otherwise. */
+    sponsorshipEnded?: I_SponsorshipEnded;
     constructor(data: SchedulingSubscriptionInfoInput);
 }
 /**

package/dist/types/scheduling/I_SchedulingProUpgrade.js

@@ -19,6 +19,10 @@ class SchedulingSubscriptionInfoDTO {
         this.expiresAt = data.expiresAt;
         this.maxAccounts = maxAccounts;
         this.maxPlatforms = maxAccounts;
+        if (data.sponsoredBy)
+            this.sponsoredBy = data.sponsoredBy;
+        if (data.sponsorshipEnded)
+            this.sponsorshipEnded = data.sponsorshipEnded;
     }
 }
 exports.SchedulingSubscriptionInfoDTO = SchedulingSubscriptionInfoDTO;

package/package.json

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

package/src/types/I_AccessDenial.ts

@@ -82,6 +82,25 @@ export const ACCESS_DENIAL_CODES = {
    * per person, FR-004). Names the case and NOTHING else about that account.
    */
   AGENCY_ALREADY_IN_ORGANIZATION: "agency-already-in-organization",
+  /**
+   * The owner invited an address that is ALREADY on this organization's team,
+   * themselves included (T063). A different case from the one above: the owner
+   * is told this person is already in, not that they belong elsewhere.
+   */
+  AGENCY_ALREADY_MEMBER: "agency-already-member",
+  /**
+   * The owner tried to cover a creator who pays for their own plan. Covering
+   * is for a creator without a paid plan (US4 scenario 3); covering a payer
+   * would leave them paying for what the agency also pays for (T066).
+   */
+  AGENCY_CREATOR_PAYS_OWN_PLAN: "agency-creator-pays-own-plan",
+  /**
+   * A creator whose plan an agency covers asked for the billing portal, and
+   * has no Stripe customer of their own to open it for (FR-014). The body
+   * names the covering agency; the client hides the portal button instead of
+   * showing a Stripe error.
+   */
+  SPONSORED_NO_PORTAL: "sponsored-no-portal",
 } as const;
 
 export type AccessDenialCode =

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

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

package/src/types/agency-billing.test.ts

@@ -0,0 +1,83 @@
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { ACCESS_DENIAL_CODES } from './I_AccessDenial';
+import type { I_AgencyBilling, I_SponsoredBy } from './agency';
+import { SchedulingSubscriptionInfoDTO } from './scheduling/I_SchedulingProUpgrade';
+
+/**
+ * Spec 175 US4 (T022/T024). The billing contract between backend and frontend:
+ * the settings screen, the creator's own subscription screen, and the one new
+ * refusal a sponsored creator can meet.
+ */
+
+test('a sponsored creator without a Stripe customer is refused the portal with its own code', () => {
+  assert.equal(ACCESS_DENIAL_CODES.SPONSORED_NO_PORTAL, 'sponsored-no-portal');
+});
+
+test('the subscription DTO carries sponsoredBy when the agency covers the plan', () => {
+  const sponsoredBy: I_SponsoredBy = { organizationName: 'Northlight', tier: 'pro', until: '2026-10-04T00:00:00.000Z' };
+  const dto = new SchedulingSubscriptionInfoDTO({
+    tier: 'pro',
+    status: 'active',
+    expiresAt: null,
+    maxAccounts: 10,
+    sponsoredBy,
+  });
+  assert.deepEqual(dto.sponsoredBy, sponsoredBy);
+});
+
+test('the subscription DTO leaves sponsoredBy ABSENT for everyone else, never null', () => {
+  const dto = new SchedulingSubscriptionInfoDTO({ tier: 'free', status: 'expired', expiresAt: null, maxAccounts: 0 });
+  assert.equal('sponsoredBy' in dto, false);
+});
+
+test('the billing overview names seats, price, invoices, who is covered and who left', () => {
+  const billing: I_AgencyBilling = {
+    subscriptionStatus: 'active',
+    seats: 3,
+    billedSeats: 3,
+    price: { amount: 2500, currency: 'USD', interval: 'month' },
+    currentPeriodEnd: '2026-10-04T00:00:00.000Z',
+    cancelAtPeriodEnd: false,
+    nextInvoice: { amount: 7500, currency: 'USD', date: '2026-10-04T00:00:00.000Z' },
+    discount: { name: 'First agency', percentOff: 100 },
+    paymentMethod: { brand: 'visa', last4: '4242', expMonth: 9, expYear: 2029 },
+    billingDetails: { name: 'Northlight Talent', email: 'kontakt@northlight.pl', country: 'PL' },
+    invoices: [
+      { id: 'in_1', number: 'AD2-0001', date: '2026-09-04T00:00:00.000Z', amount: 7500, currency: 'USD', status: 'paid' },
+    ],
+    covered: [
+      { grantId: 'g1', creator: { id: 'u1', handle: 'marta.moves' }, tier: 'pro', since: '2026-09-10T00:00:00.000Z' },
+      { grantId: 'g2', creator: { id: 'u2', handle: 'kubaplays' }, tier: null },
+    ],
+    pastCreators: [
+      {
+        grantId: 'g3',
+        creator: { id: null, handle: 'bartek.runs' },
+        endedAt: '2026-09-20T00:00:00.000Z',
+        endedBy: 'creator',
+        coveredUntil: '2026-10-04T00:00:00.000Z',
+      },
+    ],
+  };
+  assert.equal(billing.covered.filter((row) => row.tier !== null).length, 1);
+  assert.equal(billing.pastCreators[0].creator.id, null);
+});
+
+test('billedSeats is what Stripe bills: never below one, while seats is the creators with an active grant (review M1)', () => {
+  const billing: I_AgencyBilling = {
+    subscriptionStatus: 'none', seats: 0, billedSeats: 1, price: null, invoices: [], covered: [], pastCreators: [],
+  };
+  assert.equal(billing.billedSeats, 1);
+});
+
+test('the subscription DTO carries a RECENTLY ENDED coverage so the creator is told why the paywall is back (review M4, FR-014)', () => {
+  const dto = new SchedulingSubscriptionInfoDTO({
+    tier: 'free', status: 'expired', expiresAt: null, maxAccounts: 0,
+    sponsorshipEnded: { organizationName: 'Northlight', endedAt: '2026-10-04T00:00:00.000Z' },
+  });
+  assert.deepEqual(dto.sponsorshipEnded, { organizationName: 'Northlight', endedAt: '2026-10-04T00:00:00.000Z' });
+  const plain = new SchedulingSubscriptionInfoDTO({ tier: 'free', status: 'expired', expiresAt: null, maxAccounts: 0 });
+  assert.equal('sponsorshipEnded' in plain, false);
+});

package/src/types/agency-discover.test.ts

@@ -0,0 +1,79 @@
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { validateSync } from 'class-validator';
+
+import { AgencyAccessRequestDto, UpdateAgencyDiscoverableDto, type I_AgencyDiscoverResult, type I_AgencyRosterRow, type I_ConnectedPlatforms } from './agency';
+
+/**
+ * Spec 175 US5 (T026/T028): the discover and request contract.
+ */
+
+test('an access request accepts a Firebase uid, not only a UUID: most creators have one', () => {
+  const dto = new AgencyAccessRequestDto({ userId: 'fb59705bBaba4f2cA569B54ccbed', scopes: ['analytics'] });
+  assert.deepEqual(validateSync(dto), []);
+});
+
+test('an access request refuses an id that could not be a user id, and an empty scope set', () => {
+  assert.notDeepEqual(validateSync(new AgencyAccessRequestDto({ userId: 'nul\u0000byte', scopes: ['analytics'] })), []);
+  assert.notDeepEqual(validateSync(new AgencyAccessRequestDto({ userId: 'abc', scopes: [] })), []);
+  assert.notDeepEqual(validateSync(new AgencyAccessRequestDto({ userId: 'abc', scopes: ['dms' as never] })), []);
+});
+
+test('the discoverable switch is a boolean and nothing else', () => {
+  assert.deepEqual(validateSync(new UpdateAgencyDiscoverableDto({ discoverable: true })), []);
+  assert.notDeepEqual(validateSync(Object.assign(new UpdateAgencyDiscoverableDto(), { discoverable: 'yes' })), []);
+});
+
+test('a discover answer is ONE shape: hits carry handle, platforms and the platform matched only; a miss is an empty list (FR-015, T068)', () => {
+  // Two different creators can hold the same username on different platforms
+  // (@mark on YouTube, another @mark on Instagram): every match is returned,
+  // each naming where it matched, as separate people (Maciej, 2026-09-26).
+  const hits: I_AgencyDiscoverResult = {
+    results: [
+      { userId: 'u1', handle: 'mark', platforms: ['youtube'], matchedPlatform: 'youtube' },
+      { userId: 'u2', handle: 'mark', platforms: ['instagram', 'tiktok'], matchedPlatform: 'instagram' },
+    ],
+  };
+  const byEmail: I_AgencyDiscoverResult = { results: [{ userId: 'u3', handle: 'kasia.cooks', platforms: ['instagram'] }] };
+  const miss: I_AgencyDiscoverResult = { results: [] };
+  assert.deepEqual(Object.keys(hits.results[0]).sort(), ['handle', 'matchedPlatform', 'platforms', 'userId']);
+  assert.equal(byEmail.results[0].matchedPlatform, undefined);
+  assert.deepEqual(miss.results, []);
+});
+
+import { AGENCY_REQUEST_CODES, type I_CreatorAccessGrant } from './agency';
+
+test('the discoverable switch refuses a body with no value, rather than defaulting it (review M7)', () => {
+  const dto = Object.assign(new UpdateAgencyDiscoverableDto(), {});
+  assert.notDeepEqual(validateSync(dto), []);
+});
+
+test('request and discovery outcomes travel as codes, so the screen composes EN and PL itself (review M4)', () => {
+  assert.deepEqual(AGENCY_REQUEST_CODES, {
+    RATE_LIMITED: 'agency-rate-limited',
+    REQUEST_EXPIRED: 'agency-request-expired',
+    REQUEST_ANSWERED: 'agency-request-answered',
+  });
+});
+
+test('a grant carries the agency’s open second ask separately from what the creator granted (review H4, M3)', () => {
+  const grant: Pick<I_CreatorAccessGrant, 'grantedScopes' | 'reaskedScopes' | 'reaskExpiresAt'> = {
+    grantedScopes: ['analytics'],
+    reaskedScopes: ['comments'],
+    reaskExpiresAt: '2026-10-09T00:00:00.000Z',
+  };
+  assert.deepEqual(grant.reaskedScopes, ['comments']);
+});
+
+test('a roster row can carry the agency\'s last second ask and when another is possible, and nothing about the answer', () => {
+  const row: I_AgencyRosterRow = {
+    grantId: 'g1', creator: { id: 'c1', handle: 'h' }, platforms: ['instagram'], state: 'active', grantedScopes: ['analytics'],
+    reaskedAt: '2026-09-25T19:43:02.959Z', reaskAvailableAt: '2026-10-09T19:43:02.959Z',
+  };
+  assert.deepEqual(Object.keys(row).filter((k) => k.startsWith('reask')).sort(), ['reaskAvailableAt', 'reaskedAt']);
+});
+
+test('connected platforms are a plain list in the lib\'s spelling', () => {
+  const answer: I_ConnectedPlatforms = { platforms: ['instagram', 'tiktok'] };
+  assert.equal(answer.platforms.length, 2);
+});

package/src/types/agency.test.ts

@@ -7,9 +7,18 @@ import {
   CREATOR_ACCESS_GRANT_STATES,
   AGENCY_ROSTER_ROW_STATES,
   AGENCY_ROSTER_NEEDS_ATTENTION_STATES,
+  AGENCY_ROSTER_METRICS_STATES,
   isAgencyGrantScope,
   CreateAgencyOrganizationDto,
   AgencyAccessRequestDto,
+  InviteAgencyMemberDto,
+  RedeemAgencyInviteDto,
+  AcceptAgencyMemberInviteDto,
+  AcceptGrantDto,
+  UpdateGrantScopesDto,
+  SponsorCreatorDto,
+  AgencyDiscoverQueryDto,
+  AdminSetOrganizationStatusDto,
 } from "./agency";
 
 test("the grant scope set is exactly the three reads the spec allows", () => {
@@ -42,7 +51,7 @@ test("grant states are the five the data model pins, including declined and expi
 test("roster row states include `stale`, and `revoked` is NOT one of them", () => {
   assert.deepEqual(
     [...AGENCY_ROSTER_ROW_STATES],
-    ["requested", "lapsed", "disconnected", "stale", "active"],
+    ["requested", "lapsed", "disconnected", "syncing", "stale", "active"],
   );
   assert.equal(
     (AGENCY_ROSTER_ROW_STATES as readonly string[]).includes("revoked"),
@@ -58,6 +67,11 @@ test("needs-attention is disconnected + lapsed + stale, and never `requested` (F
     false,
     "a requested grant waits on the CREATOR, so it never lights the agency's badge",
   );
+  assert.equal(
+    (AGENCY_ROSTER_NEEDS_ATTENTION_STATES as readonly string[]).includes("syncing"),
+    false,
+    "a creator who joined within the day waits on the first sync, not on the agency (T067)",
+  );
   // Every needs-attention state must be a real roster state, or the tile counts a
   // state no row can ever hold.
   for (const state of AGENCY_ROSTER_NEEDS_ATTENTION_STATES) {
@@ -65,6 +79,20 @@ test("needs-attention is disconnected + lapsed + stale, and never `requested` (F
   }
 });
 
+test("only rows whose card opens carry numbers: active and stale (review M1/M2, 2026-09-24)", () => {
+  assert.deepEqual([...AGENCY_ROSTER_METRICS_STATES], ["syncing", "stale", "active"]);
+  for (const blocked of ["requested", "lapsed", "disconnected"]) {
+    assert.equal(
+      (AGENCY_ROSTER_METRICS_STATES as readonly string[]).includes(blocked),
+      false,
+      `a ${blocked} row must carry no metrics and count in no total`,
+    );
+  }
+  for (const state of AGENCY_ROSTER_METRICS_STATES) {
+    assert.ok((AGENCY_ROSTER_ROW_STATES as readonly string[]).includes(state));
+  }
+});
+
 test("DTOs construct from a plain object (the house `new I_DTO()` shape)", () => {
   const org = new CreateAgencyOrganizationDto({
     name: "Studio Kot",
@@ -78,3 +106,53 @@ test("DTOs construct from a plain object (the house `new I_DTO()` shape)", () =>
   const request = new AgencyAccessRequestDto({ userId: "u-1", scopes: ["analytics"] });
   assert.deepEqual(request.scopes, ["analytics"]);
 });
+
+test("every agency DTO survives being constructed with NOTHING", () => {
+  // What a validation pipe actually does. `plainToInstance` calls the
+  // constructor with no arguments before copying the body onto it, so a
+  // constructor that read `data.name` threw a TypeError on every request
+  // instead of validating anything (found 2026-09-22).
+  const DTOS = [
+    CreateAgencyOrganizationDto,
+    InviteAgencyMemberDto,
+    RedeemAgencyInviteDto,
+    AcceptAgencyMemberInviteDto,
+    AcceptGrantDto,
+    UpdateGrantScopesDto,
+    SponsorCreatorDto,
+    AgencyDiscoverQueryDto,
+    AgencyAccessRequestDto,
+    AdminSetOrganizationStatusDto,
+  ];
+
+  for (const Dto of DTOS) {
+    assert.doesNotThrow(() => new (Dto as new () => unknown)(), `${Dto.name} threw on an empty construct`);
+  }
+});
+
+test("every agency DTO carries validation metadata, not just a shape", () => {
+  // An undecorated class typed onto a handler's @Body() is passed through
+  // unchecked: the pipe validates DECORATORS, and there were none until
+  // 2026-09-22. Read from class-validator's own registry rather than by
+  // booting a pipe.
+  const { getMetadataStorage } = require("class-validator");
+  const storage = getMetadataStorage();
+
+  const DECORATED = [
+    CreateAgencyOrganizationDto,
+    InviteAgencyMemberDto,
+    RedeemAgencyInviteDto,
+    AcceptAgencyMemberInviteDto,
+    AcceptGrantDto,
+    UpdateGrantScopesDto,
+    SponsorCreatorDto,
+    AgencyDiscoverQueryDto,
+    AgencyAccessRequestDto,
+    AdminSetOrganizationStatusDto,
+  ];
+
+  for (const Dto of DECORATED) {
+    const rules = storage.getTargetValidationMetadatas(Dto, Dto.name, false, false);
+    assert.ok(rules.length > 0, `${Dto.name} has no validation rules`);
+  }
+});