ad2app-lib 1.44.1 → 1.49.0

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-threads.ts

@@ -0,0 +1,103 @@
+import { IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
+
+import type { CampaignSide, I_CampaignCreatorIdentity } from './agency-campaigns';
+
+/**
+ * Agency ↔ creator threads (spec 175 US8, FR-023): one conversation per
+ * organization and creator, inside ad2app.
+ *
+ * Deliberately NOT the creator's platform inbox: nothing here reaches a social
+ * platform, and no grant scope opens a thread (SC-015). A thread is the two
+ * parties' own; a grant is a read of the creator's numbers, and the two never
+ * meet.
+ *
+ * "Unanswered" is derived: the other side wrote last. There is no read state
+ * and no mark-read step.
+ */
+
+export const AGENCY_THREAD_CODES = {
+  /** No live relationship any more: the history stays readable, nothing can be sent (FR-023). */
+  CLOSED: 'agency-thread-closed',
+  /** Too many messages from one person in the window (THREAD_POST_LIMIT). */
+  RATE_LIMITED: 'agency-thread-rate-limited',
+} as const;
+
+/** Messages one person may post across all their threads per window: a conversation pace, never a script's. */
+export const THREAD_POST_LIMIT = { limit: 60, windowMinutes: 10 } as const;
+
+/** Long enough for a real message, short enough to stay a message. */
+export const THREAD_MESSAGE_MAX = 4000;
+
+/** Messages per read: the newest page with the thread, earlier pages on request. */
+export const THREAD_PAGE_SIZE = 100;
+
+export interface I_AgencyThreadMessage {
+  id: string;
+  side: CampaignSide;
+  body: string;
+  at: 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;
+  /** The other side wrote last, seen from the caller's side. */
+  unanswered: boolean;
+  /** No live relationship: read-only for whoever still exists. */
+  closed: boolean;
+}
+
+export interface I_AgencyThread {
+  summary: I_AgencyThreadSummary;
+  /** The newest page, oldest first. */
+  messages: I_AgencyThreadMessage[];
+  /** Older messages exist: read them with `…/messages?before=<oldest id>`. */
+  hasEarlier: boolean;
+}
+
+/** `GET …/threads/:id/messages?before=<message id>` — the page before a message. */
+export interface I_AgencyThreadPage {
+  /** Oldest first. */
+  messages: I_AgencyThreadMessage[];
+  hasEarlier: boolean;
+}
+
+/** `GET /agency/threads` — the agency's inbox. */
+export interface I_AgencyThreads {
+  items: I_AgencyThreadSummary[];
+  /** Creators on the roster the agency has no open thread with yet. */
+  startable: I_CampaignCreatorIdentity[];
+  /** The Inbox rail count. */
+  unanswered: number;
+}
+
+/** `GET /agency/creator-threads/mine` — the creator's threads, in the Agency tab. */
+export interface I_CreatorThreads {
+  items: I_AgencyThreadSummary[];
+  unanswered: number;
+}
+
+export class StartAgencyThreadDto {
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,128}$/)
+  creatorUserId: string;
+
+  constructor(data?: Partial<StartAgencyThreadDto>) {
+    this.creatorUserId = data?.creatorUserId ?? '';
+  }
+}
+
+export class PostThreadMessageDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(THREAD_MESSAGE_MAX)
+  text: string;
+
+  constructor(data?: Partial<PostThreadMessageDto>) {
+    this.text = data?.text ?? '';
+  }
+}

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';
 
 /**
@@ -50,6 +52,8 @@ export const AGENCY_ROUTE_PATHS = {
 	join: '/agency/join',
 	/** A creator answering an access request (FR-016). */
 	requests: '/agency/requests',
+	/** A creator's campaign invitations and campaigns: the Agency tab of their Inbox (FR-023, FR-026). */
+	creatorCampaigns: '/inbox/agency',
 } as const;
 
 // ── Scopes ───────────────────────────────────────────────────────────────────
@@ -145,6 +149,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 +226,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 +266,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 +296,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 +413,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 +633,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 +653,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/index.ts

@@ -43,6 +43,8 @@ export * from "./agent";
 
 // ── Agency domain (organizations, memberships, creator access grants, spec 175)
 export * from "./agency";
+export * from "./agency-campaigns";
+export * from "./agency-threads";
 
 // ── Access control ────────────────────────────────────────────────────────────
 export * from "./I_AccessDenial";

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;
   }
 }