ad2app-lib 1.44.1 → 1.47.0

package/dist/types/I_AccessDenial.d.ts

@@ -79,6 +79,25 @@ export declare const ACCESS_DENIAL_CODES: {
      * per person, FR-004). Names the case and NOTHING else about that account.
      */
     readonly 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.
+     */
+    readonly 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).
+     */
+    readonly 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.
+     */
+    readonly SPONSORED_NO_PORTAL: "sponsored-no-portal";
 };
 export type AccessDenialCode = (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
 /**

package/dist/types/I_AccessDenial.js

@@ -83,6 +83,25 @@ exports.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",
 };
 /**
  * WHICH precondition the entitlement wall refused on (backend#305, spec 170).

package/dist/types/agency.d.ts

@@ -93,6 +93,12 @@ export interface I_AgencyMember {
     /** Null while an e-mail invitation is outstanding — nobody has accepted yet. */
     userId?: string;
     invitedEmail: string;
+    /**
+     * The account's own e-mail once the invitation is accepted (and always for
+     * the owner, who applied rather than being invited). The Team panel names a
+     * person by this, never by the organization's contact address (T063).
+     */
+    accountEmail?: string;
     role: AgencyMemberRole;
     invitedAt: string;
     /** "Who is in" is exactly `acceptedAt != null`. */
@@ -152,7 +158,27 @@ export interface I_CreatorAccessGrant {
     };
     /** Which platforms the grant reaches right now — derived at read time, never stored. */
     platformsReached: PublishPlatform[];
+    /**
+     * The agency's OPEN second ask on an active grant, for scopes the creator
+     * did not grant (FR-008). Kept apart from `requestedScopes`, so the consent
+     * screen names exactly this ask and nothing refused earlier (review H4).
+     * Absent when there is no open ask.
+     */
+    reaskedScopes?: I_AgencyGrantScope[];
+    /** When that open ask expires unanswered. */
+    reaskExpiresAt?: string;
 }
+/**
+ * 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 }`.
+ */
+export declare const AGENCY_REQUEST_CODES: {
+    readonly RATE_LIMITED: "agency-rate-limited";
+    readonly REQUEST_EXPIRED: "agency-request-expired";
+    readonly REQUEST_ANSWERED: "agency-request-answered";
+};
+export type AgencyRequestCode = (typeof AGENCY_REQUEST_CODES)[keyof typeof AGENCY_REQUEST_CODES];
 /**
  * Roster row states, DECLARED IN PRECEDENCE ORDER (data-model §Derived).
  *
@@ -160,7 +186,7 @@ export interface I_CreatorAccessGrant {
  * first. `revoked` is deliberately absent — a revoked creator leaves the roster
  * entirely for the settings history (FR-011).
  */
-export declare const AGENCY_ROSTER_ROW_STATES: readonly ["requested", "lapsed", "disconnected", "stale", "active"];
+export declare const AGENCY_ROSTER_ROW_STATES: readonly ["requested", "lapsed", "disconnected", "syncing", "stale", "active"];
 export type AgencyRosterRowState = (typeof AGENCY_ROSTER_ROW_STATES)[number];
 /**
  * What "needs attention" means — ONE home for the KPI tile, the roster segment
@@ -171,6 +197,32 @@ export type AgencyRosterRowState = (typeof AGENCY_ROSTER_ROW_STATES)[number];
  */
 export declare const AGENCY_ROSTER_NEEDS_ATTENTION_STATES: readonly ["lapsed", "disconnected", "stale"];
 export type AgencyRosterNeedsAttentionState = (typeof AGENCY_ROSTER_NEEDS_ATTENTION_STATES)[number];
+/**
+ * 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.
+ */
+export declare const AGENCY_ROSTER_METRICS_STATES: readonly ["syncing", "stale", "active"];
+export type AgencyRosterMetricsState = (typeof AGENCY_ROSTER_METRICS_STATES)[number];
+/**
+ * One creator's numbers on the roster (FR-011a: sortable metric columns), read
+ * from the daily-synced tables, never a vendor call. `null` is a REASON, never
+ * a zero: the creator did not grant that scope, or nothing has been synced yet.
+ */
+export interface I_AgencyRosterRowMetrics {
+    /** Latest followers over the creator's CONNECTED platforms; null without `analytics` or before the first sync. */
+    followers: number | null;
+    /** Against the snapshot seven days earlier, per connected platform; null without `analytics` or without a week-old point. */
+    followersDelta7d: number | null;
+    /** The current Monday-to-Sunday week, organization timezone; null without `comments`. */
+    commentsThisWeek: number | null;
+}
 export interface I_AgencyRosterRow {
     grantId: string;
     creator: {
@@ -180,22 +232,72 @@ export interface I_AgencyRosterRow {
     platforms: PublishPlatform[];
     state: AgencyRosterRowState;
     grantedScopes: I_AgencyGrantScope[];
+    /**
+     * The newest successful daily sync. Absent on a `requested` row (nothing is
+     * shared yet, so there is nothing to have synced for the agency) and on a
+     * creator never synced. `platforms` stays on a requested row: it is what the
+     * consent screen names, a fact about the account rather than shared data.
+     */
     lastSyncAt?: string;
+    /**
+     * Present ONLY on rows in AGENCY_ROSTER_METRICS_STATES (`active`, `stale`):
+     * the rows whose card opens. Absent on `lapsed`, `disconnected` and
+     * `requested` rows — no numbers, not null numbers.
+     */
+    metrics?: I_AgencyRosterRowMetrics;
+    /**
+     * The agency's own last "Ask again" (FR-008), while its one-per-TTL clock
+     * runs (audit F19): when it was sent and when another is possible. It says
+     * nothing about the ANSWER, because the clock runs whatever the creator did.
+     * The roster uses it to say "asked on …, again after …" instead of offering
+     * an ask that would not be sent. Absent once the clock has run out.
+     */
+    reaskedAt?: string;
+    reaskAvailableAt?: string;
+}
+/**
+ * The platforms a creator has connected, as the agency side sees them
+ * (discovery, the grant's "reaches"). `GET users/me/connected-platforms`,
+ * answered to every creator, subscribed or not.
+ */
+export interface I_ConnectedPlatforms {
+    platforms: PublishPlatform[];
 }
 export interface I_AgencyRoster {
     totals: {
         creators: number;
         active: number;
-        /** Summed only over creators holding `analytics`; disconnected platforms excluded. */
-        followers: number;
-        followersDelta7d: number;
-        /** Calendar week, Mon-Sun, organization timezone, creators holding `comments`. */
-        commentsThisWeek: number;
+        /**
+         * Summed only over rows in AGENCY_ROSTER_METRICS_STATES whose creator holds
+         * `analytics`; disconnected platforms excluded. `null` when no counted
+         * creator has a synced number yet, never a zero standing in (T067).
+         */
+        followers: number | null;
+        /**
+         * Same rows as `followers`, against the snapshot seven days earlier. `null`
+         * when no counted creator has a week-old point — unknown, never a zero.
+         */
+        followersDelta7d: number | null;
+        /**
+         * Calendar week, Mon-Sun, organization timezone, over rows in
+         * AGENCY_ROSTER_METRICS_STATES whose creator holds `comments`. Like
+         * `followers`, `null` when no counted creator has a synced number yet:
+         * unknown, never a zero (SC-008, T067).
+         */
+        commentsThisWeek: number | null;
         /** Count of rows in AGENCY_ROSTER_NEEDS_ATTENTION_STATES. */
         needsAttention: number;
     };
     items: I_AgencyRosterRow[];
 }
+/**
+ * A coverage that ENDED recently, so the creator meeting the paywall again is
+ * told why (FR-014: "an honest message, never a silent loss of access").
+ */
+export interface I_SponsorshipEnded {
+    organizationName: string;
+    endedAt: string;
+}
 /** What a sponsored creator sees on their OWN subscription screen (FR-014). */
 export interface I_SponsoredBy {
     organizationName: string;
@@ -203,6 +305,106 @@ export interface I_SponsoredBy {
     /** Present once the sponsorship is ending: the date their plan runs to. */
     until?: string;
 }
+/** The card on file, as Stripe describes it. Never more than these four facts. */
+export interface I_AgencyPaymentMethod {
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+}
+/**
+ * One invoice. `amount` is Stripe's minor unit verbatim; the display edge
+ * formats it once, like every other price in the app.
+ */
+export interface I_AgencyInvoice {
+    id: string;
+    number: string | null;
+    date: string;
+    amount: number;
+    currency: string;
+    status: string;
+    pdfUrl?: string;
+    hostedUrl?: string;
+}
+/**
+ * One creator on an ACTIVE grant, with whether the agency covers their plan
+ * (FR-013b). `tier: null` is "not covered". `until` is set while a coverage is
+ * ending: it runs to the close of the period already paid for.
+ */
+export interface I_AgencyCoveredCreator {
+    grantId: string;
+    creator: {
+        id: string;
+        handle: string;
+    };
+    tier: SponsoredTier | null;
+    since?: string;
+    until?: string;
+}
+/**
+ * An ended relationship, for the past-creators history (FR-013b). `creator.id`
+ * is null once the creator's account was purged; the handle is the snapshot
+ * frozen at grant time.
+ */
+export interface I_AgencyPastCreator {
+    grantId: string;
+    creator: {
+        id: string | null;
+        handle: string;
+        displayName?: string;
+    };
+    endedAt: string;
+    endedBy: CreatorAccessGrantRevokedBy;
+    coveredUntil?: string;
+}
+/**
+ * Everything the owner's billing section and panel show (FR-013, FR-013b).
+ *
+ * `seats` is the ONE home of the billed quantity: the count of active grants.
+ * Covering a creator never changes it (clarify 2026-09-17), so nothing here
+ * derives a price from `covered`.
+ *
+ * `price` is null when the seat product is not configured in this deployment
+ * (T031, the money gate); the screen says so rather than inventing a number.
+ * `nextInvoice` is Stripe's own preview, so a coupon is already applied to it.
+ */
+export interface I_AgencyBilling {
+    subscriptionStatus: AgencySubscriptionStatus;
+    /** Creators with an active grant. */
+    seats: number;
+    /**
+     * What Stripe bills: `max(1, seats)`. An agency with no creators yet still
+     * pays for one seat, and the screen must say the number Stripe charges.
+     */
+    billedSeats: number;
+    price: {
+        amount: number;
+        currency: string;
+        interval: string;
+    } | null;
+    currentPeriodEnd?: string;
+    cancelAtPeriodEnd?: boolean;
+    nextInvoice?: {
+        amount: number;
+        currency: string;
+        date: string;
+    };
+    discount?: {
+        name?: string;
+        percentOff?: number;
+        amountOff?: number;
+    };
+    paymentMethod?: I_AgencyPaymentMethod;
+    billingDetails?: {
+        name?: string;
+        email?: string;
+        country?: string;
+        taxId?: string;
+    };
+    invoices: I_AgencyInvoice[];
+    covered: I_AgencyCoveredCreator[];
+    pastCreators: I_AgencyPastCreator[];
+}
 /**
  * Every DTO below carries class-validator decorators and a constructor that
  * survives being called with nothing.
@@ -264,10 +466,50 @@ export declare class AgencyDiscoverQueryDto {
     constructor(data?: Partial<AgencyDiscoverQueryDto>);
 }
 export declare class AgencyAccessRequestDto {
+    /**
+     * A user id: a UUID or a Firebase uid (letters, digits, hyphens). It was
+     * `@IsUUID()` until US5 was built, which refused most real creators — their
+     * ids are Firebase uids.
+     */
     userId: string;
     scopes: I_AgencyGrantScope[];
     constructor(data?: Partial<AgencyAccessRequestDto>);
 }
+/** `PATCH /users/me/agency-discoverable` — "Let agencies find me" (FR-015). */
+export declare class UpdateAgencyDiscoverableDto {
+    discoverable: boolean;
+    /**
+     * 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?: Partial<UpdateAgencyDiscoverableDto>);
+}
+/**
+ * One discover hit: the public handle and the platforms, NEVER a metric and
+ * never a grant flag, so the payload cannot tell a caller whether it already
+ * holds the creator (FR-015). `userId` is what the request is sent for.
+ */
+export interface I_AgencyDiscoverHit {
+    userId: string;
+    handle: string;
+    platforms: PublishPlatform[];
+    /**
+     * The platform whose username matched. Absent on an e-mail match. Two hits
+     * with the same handle are two different people (@mark on YouTube, another
+     * @mark on Instagram), and this is what tells them apart (T068).
+     */
+    matchedPlatform?: PublishPlatform;
+}
+/**
+ * `POST /agency/roster/discover` — the SAME shape and status for every case:
+ * discoverable exact matches, a non-discoverable account, a partial match and
+ * no account at all (SC-009). A miss is `{ results: [] }`, never a 404. An
+ * exact handle held by several findable creators returns each of them, one
+ * row per person (Maciej, 2026-09-26, T068); an e-mail matches one person.
+ */
+export interface I_AgencyDiscoverResult {
+    results: I_AgencyDiscoverHit[];
+}
 export declare class AdminSetOrganizationStatusDto {
     status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
     /** Required on reject — a rejected applicant is shown this (FR-002). The

package/dist/types/agency.js

@@ -9,7 +9,7 @@ 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 ───────────────────────────────────────────────
 /**
@@ -89,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).
@@ -104,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',
@@ -120,6 +137,22 @@ 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
@@ -272,7 +305,8 @@ class AgencyAccessRequestDto {
 }
 exports.AgencyAccessRequestDto = AgencyAccessRequestDto;
 __decorate([
-    (0, class_validator_1.IsUUID)(),
+    (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([
@@ -281,6 +315,22 @@ __decorate([
     (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 ?? 'approved';

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.1",
+  "version": "1.47.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -51,7 +51,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej G\u00f3rski@ad2.app",
+  "author": "Maciej Górski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

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,6 +7,7 @@ import {
   CREATOR_ACCESS_GRANT_STATES,
   AGENCY_ROSTER_ROW_STATES,
   AGENCY_ROSTER_NEEDS_ATTENTION_STATES,
+  AGENCY_ROSTER_METRICS_STATES,
   isAgencyGrantScope,
   CreateAgencyOrganizationDto,
   AgencyAccessRequestDto,
@@ -50,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"),
@@ -66,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) {
@@ -73,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",

package/src/types/agency.ts

@@ -1,6 +1,7 @@
 import {
   ArrayNotEmpty,
   IsArray,
+  IsBoolean,
   IsEmail,
   IsIn,
   IsNotEmpty,
@@ -9,6 +10,7 @@ import {
   IsUrl,
   IsUUID,
   Length,
+  Matches,
 } from 'class-validator';
 
 /**
@@ -145,6 +147,12 @@ export interface I_AgencyMember {
   /** Null while an e-mail invitation is outstanding — nobody has accepted yet. */
   userId?: string;
   invitedEmail: string;
+  /**
+   * The account's own e-mail once the invitation is accepted (and always for
+   * the owner, who applied rather than being invited). The Team panel names a
+   * person by this, never by the organization's contact address (T063).
+   */
+  accountEmail?: string;
   role: AgencyMemberRole;
   invitedAt: string;
   /** "Who is in" is exactly `acceptedAt != null`. */
@@ -216,8 +224,30 @@ export interface I_CreatorAccessGrant {
   sponsorship?: { tier: SponsoredTier; since: string; until?: string };
   /** Which platforms the grant reaches right now — derived at read time, never stored. */
   platformsReached: PublishPlatform[];
+  /**
+   * The agency's OPEN second ask on an active grant, for scopes the creator
+   * did not grant (FR-008). Kept apart from `requestedScopes`, so the consent
+   * screen names exactly this ask and nothing refused earlier (review H4).
+   * Absent when there is no open ask.
+   */
+  reaskedScopes?: I_AgencyGrantScope[];
+  /** When that open ask expires unanswered. */
+  reaskExpiresAt?: string;
 }
 
+/**
+ * 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 }`.
+ */
+export const AGENCY_REQUEST_CODES = {
+  RATE_LIMITED: 'agency-rate-limited',
+  REQUEST_EXPIRED: 'agency-request-expired',
+  REQUEST_ANSWERED: 'agency-request-answered',
+} as const;
+
+export type AgencyRequestCode = (typeof AGENCY_REQUEST_CODES)[keyof typeof AGENCY_REQUEST_CODES];
+
 // ── Roster ───────────────────────────────────────────────────────────────────
 
 /**
@@ -234,6 +264,13 @@ export const 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',
@@ -257,30 +294,115 @@ export const AGENCY_ROSTER_NEEDS_ATTENTION_STATES = [
 export type AgencyRosterNeedsAttentionState =
   (typeof AGENCY_ROSTER_NEEDS_ATTENTION_STATES)[number];
 
+/**
+ * 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.
+ */
+export const AGENCY_ROSTER_METRICS_STATES = [
+  'syncing',
+  'stale',
+  'active',
+] as const satisfies readonly AgencyRosterRowState[];
+
+export type AgencyRosterMetricsState = (typeof AGENCY_ROSTER_METRICS_STATES)[number];
+
+/**
+ * One creator's numbers on the roster (FR-011a: sortable metric columns), read
+ * from the daily-synced tables, never a vendor call. `null` is a REASON, never
+ * a zero: the creator did not grant that scope, or nothing has been synced yet.
+ */
+export interface I_AgencyRosterRowMetrics {
+  /** Latest followers over the creator's CONNECTED platforms; null without `analytics` or before the first sync. */
+  followers: number | null;
+  /** Against the snapshot seven days earlier, per connected platform; null without `analytics` or without a week-old point. */
+  followersDelta7d: number | null;
+  /** The current Monday-to-Sunday week, organization timezone; null without `comments`. */
+  commentsThisWeek: number | null;
+}
+
 export interface I_AgencyRosterRow {
   grantId: string;
   creator: { id: string; handle: string };
   platforms: PublishPlatform[];
   state: AgencyRosterRowState;
   grantedScopes: I_AgencyGrantScope[];
+  /**
+   * The newest successful daily sync. Absent on a `requested` row (nothing is
+   * shared yet, so there is nothing to have synced for the agency) and on a
+   * creator never synced. `platforms` stays on a requested row: it is what the
+   * consent screen names, a fact about the account rather than shared data.
+   */
   lastSyncAt?: string;
+  /**
+   * Present ONLY on rows in AGENCY_ROSTER_METRICS_STATES (`active`, `stale`):
+   * the rows whose card opens. Absent on `lapsed`, `disconnected` and
+   * `requested` rows — no numbers, not null numbers.
+   */
+  metrics?: I_AgencyRosterRowMetrics;
+  /**
+   * The agency's own last "Ask again" (FR-008), while its one-per-TTL clock
+   * runs (audit F19): when it was sent and when another is possible. It says
+   * nothing about the ANSWER, because the clock runs whatever the creator did.
+   * The roster uses it to say "asked on …, again after …" instead of offering
+   * an ask that would not be sent. Absent once the clock has run out.
+   */
+  reaskedAt?: string;
+  reaskAvailableAt?: string;
+}
+
+/**
+ * The platforms a creator has connected, as the agency side sees them
+ * (discovery, the grant's "reaches"). `GET users/me/connected-platforms`,
+ * answered to every creator, subscribed or not.
+ */
+export interface I_ConnectedPlatforms {
+  platforms: PublishPlatform[];
 }
 
 export interface I_AgencyRoster {
   totals: {
     creators: number;
     active: number;
-    /** Summed only over creators holding `analytics`; disconnected platforms excluded. */
-    followers: number;
-    followersDelta7d: number;
-    /** Calendar week, Mon-Sun, organization timezone, creators holding `comments`. */
-    commentsThisWeek: number;
+    /**
+     * Summed only over rows in AGENCY_ROSTER_METRICS_STATES whose creator holds
+     * `analytics`; disconnected platforms excluded. `null` when no counted
+     * creator has a synced number yet, never a zero standing in (T067).
+     */
+    followers: number | null;
+    /**
+     * Same rows as `followers`, against the snapshot seven days earlier. `null`
+     * when no counted creator has a week-old point — unknown, never a zero.
+     */
+    followersDelta7d: number | null;
+    /**
+     * Calendar week, Mon-Sun, organization timezone, over rows in
+     * AGENCY_ROSTER_METRICS_STATES whose creator holds `comments`. Like
+     * `followers`, `null` when no counted creator has a synced number yet:
+     * unknown, never a zero (SC-008, T067).
+     */
+    commentsThisWeek: number | null;
     /** Count of rows in AGENCY_ROSTER_NEEDS_ATTENTION_STATES. */
     needsAttention: number;
   };
   items: I_AgencyRosterRow[];
 }
 
+/**
+ * A coverage that ENDED recently, so the creator meeting the paywall again is
+ * told why (FR-014: "an honest message, never a silent loss of access").
+ */
+export interface I_SponsorshipEnded {
+  organizationName: string;
+  endedAt: string;
+}
+
 /** What a sponsored creator sees on their OWN subscription screen (FR-014). */
 export interface I_SponsoredBy {
   organizationName: string;
@@ -289,6 +411,89 @@ export interface I_SponsoredBy {
   until?: string;
 }
 
+// ── Billing (US4) ────────────────────────────────────────────────────────────
+
+/** The card on file, as Stripe describes it. Never more than these four facts. */
+export interface I_AgencyPaymentMethod {
+  brand: string;
+  last4: string;
+  expMonth: number;
+  expYear: number;
+}
+
+/**
+ * One invoice. `amount` is Stripe's minor unit verbatim; the display edge
+ * formats it once, like every other price in the app.
+ */
+export interface I_AgencyInvoice {
+  id: string;
+  number: string | null;
+  date: string;
+  amount: number;
+  currency: string;
+  status: string;
+  pdfUrl?: string;
+  hostedUrl?: string;
+}
+
+/**
+ * One creator on an ACTIVE grant, with whether the agency covers their plan
+ * (FR-013b). `tier: null` is "not covered". `until` is set while a coverage is
+ * ending: it runs to the close of the period already paid for.
+ */
+export interface I_AgencyCoveredCreator {
+  grantId: string;
+  creator: { id: string; handle: string };
+  tier: SponsoredTier | null;
+  since?: string;
+  until?: string;
+}
+
+/**
+ * An ended relationship, for the past-creators history (FR-013b). `creator.id`
+ * is null once the creator's account was purged; the handle is the snapshot
+ * frozen at grant time.
+ */
+export interface I_AgencyPastCreator {
+  grantId: string;
+  creator: { id: string | null; handle: string; displayName?: string };
+  endedAt: string;
+  endedBy: CreatorAccessGrantRevokedBy;
+  coveredUntil?: string;
+}
+
+/**
+ * Everything the owner's billing section and panel show (FR-013, FR-013b).
+ *
+ * `seats` is the ONE home of the billed quantity: the count of active grants.
+ * Covering a creator never changes it (clarify 2026-09-17), so nothing here
+ * derives a price from `covered`.
+ *
+ * `price` is null when the seat product is not configured in this deployment
+ * (T031, the money gate); the screen says so rather than inventing a number.
+ * `nextInvoice` is Stripe's own preview, so a coupon is already applied to it.
+ */
+export interface I_AgencyBilling {
+  subscriptionStatus: AgencySubscriptionStatus;
+  /** Creators with an active grant. */
+  seats: number;
+  /**
+   * What Stripe bills: `max(1, seats)`. An agency with no creators yet still
+   * pays for one seat, and the screen must say the number Stripe charges.
+   */
+  billedSeats: number;
+  price: { amount: number; currency: string; interval: string } | null;
+  currentPeriodEnd?: string;
+  cancelAtPeriodEnd?: boolean;
+  nextInvoice?: { amount: number; currency: string; date: string };
+  discount?: { name?: string; percentOff?: number; amountOff?: number };
+  paymentMethod?: I_AgencyPaymentMethod;
+  billingDetails?: { name?: string; email?: string; country?: string; taxId?: string };
+  invoices: I_AgencyInvoice[];
+  covered: I_AgencyCoveredCreator[];
+  pastCreators: I_AgencyPastCreator[];
+}
+
 // ── DTOs ─────────────────────────────────────────────────────────────────────
 
 /**
@@ -426,7 +631,13 @@ export class AgencyDiscoverQueryDto {
 }
 
 export class AgencyAccessRequestDto {
-  @IsUUID()
+  /**
+   * A user id: a UUID or a Firebase uid (letters, digits, hyphens). It was
+   * `@IsUUID()` until US5 was built, which refused most real creators — their
+   * ids are Firebase uids.
+   */
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,128}$/)
   userId: string;
 
   @IsArray()
@@ -440,6 +651,48 @@ export class AgencyAccessRequestDto {
   }
 }
 
+/** `PATCH /users/me/agency-discoverable` — "Let agencies find me" (FR-015). */
+export class UpdateAgencyDiscoverableDto {
+  @IsBoolean()
+  discoverable: boolean;
+
+  /**
+   * 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?: Partial<UpdateAgencyDiscoverableDto>) {
+    if (data?.discoverable !== undefined) this.discoverable = data.discoverable;
+  }
+}
+
+/**
+ * One discover hit: the public handle and the platforms, NEVER a metric and
+ * never a grant flag, so the payload cannot tell a caller whether it already
+ * holds the creator (FR-015). `userId` is what the request is sent for.
+ */
+export interface I_AgencyDiscoverHit {
+  userId: string;
+  handle: string;
+  platforms: PublishPlatform[];
+  /**
+   * The platform whose username matched. Absent on an e-mail match. Two hits
+   * with the same handle are two different people (@mark on YouTube, another
+   * @mark on Instagram), and this is what tells them apart (T068).
+   */
+  matchedPlatform?: PublishPlatform;
+}
+
+/**
+ * `POST /agency/roster/discover` — the SAME shape and status for every case:
+ * discoverable exact matches, a non-discoverable account, a partial match and
+ * no account at all (SC-009). A miss is `{ results: [] }`, never a 404. An
+ * exact handle held by several findable creators returns each of them, one
+ * row per person (Maciej, 2026-09-26, T068); an e-mail matches one person.
+ */
+export interface I_AgencyDiscoverResult {
+  results: I_AgencyDiscoverHit[];
+}
+
 export class AdminSetOrganizationStatusDto {
   @IsIn(['approved', 'rejected'])
   status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;

package/src/types/scheduling/I_SchedulingProUpgrade.ts

@@ -5,6 +5,8 @@
  * and the customer portal redirect.
  */
 
+import type { I_SponsoredBy, I_SponsorshipEnded } from '../agency';
+
 // ── SchedulingSubscriptionTier ────────────────────────────────────────────────
 
 export type SchedulingSubscriptionTier = 'free' | 'starter' | 'pro';
@@ -23,6 +25,7 @@ export type SchedulingSubscriptionInfoInput = Pick<
   SchedulingSubscriptionInfoDTO,
   'tier' | 'status' | 'expiresAt'
 > &
+  Partial<Pick<SchedulingSubscriptionInfoDTO, 'sponsoredBy' | 'sponsorshipEnded'>> &
   (
     | { maxAccounts: number; maxPlatforms?: number }
     | {
@@ -46,6 +49,14 @@ export 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) {
     const maxAccounts = 'maxAccounts' in data ? data.maxAccounts : data.maxPlatforms;
@@ -54,6 +65,8 @@ export 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;
   }
 }