ad2app-lib 1.44.0 → 1.47.0

package/src/types/agency.ts

@@ -1,3 +1,18 @@
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsBoolean,
+  IsEmail,
+  IsIn,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUrl,
+  IsUUID,
+  Length,
+  Matches,
+} from 'class-validator';
+
 /**
  * Agency domain — organizations, memberships and creator access grants (spec 175).
  *
@@ -132,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`. */
@@ -203,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 ───────────────────────────────────────────────────────────────────
 
 /**
@@ -221,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',
@@ -244,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;
@@ -276,45 +411,162 @@ 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 ─────────────────────────────────────────────────────────────────────
 
+/**
+ * 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.
+ */
+
 export class CreateAgencyOrganizationDto {
+  @IsString()
+  @IsNotEmpty()
   name: string;
+
+  /** Rendered as a link on the admin screen, so the protocol is checked here. */
+  @IsOptional()
+  @IsUrl({ protocols: ['http', 'https'], require_protocol: true })
   website?: string;
+
+  @IsString()
+  @IsNotEmpty()
   registryId: string;
+
+  /** ISO-3166 alpha-2: which register a reviewer should look in. */
+  @IsString()
+  @Length(2, 2)
   registryCountry: string;
+
+  @IsEmail()
   contactEmail: string;
 
-  constructor(data: CreateAgencyOrganizationDto) {
-    this.name = data.name;
-    this.website = data.website;
-    this.registryId = data.registryId;
-    this.registryCountry = data.registryCountry;
-    this.contactEmail = data.contactEmail;
+  constructor(data?: Partial<CreateAgencyOrganizationDto>) {
+    this.name = data?.name ?? '';
+    this.website = data?.website;
+    this.registryId = data?.registryId ?? '';
+    this.registryCountry = data?.registryCountry ?? '';
+    this.contactEmail = data?.contactEmail ?? '';
   }
 }
 
 export class InviteAgencyMemberDto {
+  @IsEmail()
   email: string;
 
-  constructor(data: InviteAgencyMemberDto) {
-    this.email = data.email;
+  constructor(data?: Partial<InviteAgencyMemberDto>) {
+    this.email = data?.email ?? '';
   }
 }
 
 export class RedeemAgencyInviteDto {
+  @IsString()
+  @IsNotEmpty()
   token: string;
 
-  constructor(data: RedeemAgencyInviteDto) {
-    this.token = data.token;
+  constructor(data?: Partial<RedeemAgencyInviteDto>) {
+    this.token = data?.token ?? '';
   }
 }
 
 export class AcceptAgencyMemberInviteDto {
+  @IsString()
+  @IsNotEmpty()
   token: string;
 
-  constructor(data: AcceptAgencyMemberInviteDto) {
-    this.token = data.token;
+  constructor(data?: Partial<AcceptAgencyMemberInviteDto>) {
+    this.token = data?.token ?? '';
   }
 }
 
@@ -323,60 +575,137 @@ export class AcceptAgencyMemberInviteDto {
  * is the creator's answer and defaults to the requested set when absent.
  */
 export class AcceptGrantDto {
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
   token?: string;
+
+  @IsOptional()
+  @IsUUID()
   grantId?: string;
+
+  /** A subset of the three reads. Never empty: sharing nothing is declining. */
+  @IsOptional()
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
   scopes?: I_AgencyGrantScope[];
 
-  constructor(data: AcceptGrantDto) {
-    this.token = data.token;
-    this.grantId = data.grantId;
-    this.scopes = data.scopes;
+  constructor(data?: Partial<AcceptGrantDto>) {
+    this.token = data?.token;
+    this.grantId = data?.grantId;
+    this.scopes = data?.scopes;
   }
 }
 
 /** The creator narrowing or widening a live grant — the only other write path. */
 export class UpdateGrantScopesDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
   scopes: I_AgencyGrantScope[];
 
-  constructor(data: UpdateGrantScopesDto) {
-    this.scopes = data.scopes;
+  constructor(data?: Partial<UpdateGrantScopesDto>) {
+    this.scopes = data?.scopes ?? [];
   }
 }
 
 export class SponsorCreatorDto {
+  @IsIn(['starter', 'pro'])
   tier: SponsoredTier;
 
-  constructor(data: SponsorCreatorDto) {
-    this.tier = data.tier;
+  constructor(data?: Partial<SponsorCreatorDto>) {
+    this.tier = data?.tier ?? 'starter';
   }
 }
 
 export class AgencyDiscoverQueryDto {
   /** An EXACT platform username or e-mail. Never recorded in analytics (FR-015). */
+  @IsString()
+  @IsNotEmpty()
   q: string;
 
-  constructor(data: AgencyDiscoverQueryDto) {
-    this.q = data.q;
+  constructor(data?: Partial<AgencyDiscoverQueryDto>) {
+    this.q = data?.q ?? '';
   }
 }
 
 export 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.
+   */
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,128}$/)
   userId: string;
+
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
   scopes: I_AgencyGrantScope[];
 
-  constructor(data: AgencyAccessRequestDto) {
-    this.userId = data.userId;
-    this.scopes = data.scopes;
+  constructor(data?: Partial<AgencyAccessRequestDto>) {
+    this.userId = data?.userId ?? '';
+    this.scopes = data?.scopes ?? [];
   }
 }
 
+/** `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'>;
-  /** Required on reject — a rejected applicant is shown this (FR-002). */
+
+  /** Required on reject — a rejected applicant is shown this (FR-002). The
+   *  "required when rejecting" half is a rule about the PAIR, so it stays in
+   *  the service where both fields are in hand. */
+  @IsOptional()
+  @IsString()
   reason?: string;
 
-  constructor(data: AdminSetOrganizationStatusDto) {
-    this.status = data.status;
-    this.reason = data.reason;
+  constructor(data?: Partial<AdminSetOrganizationStatusDto>) {
+    this.status = data?.status ?? 'approved';
+    this.reason = data?.reason;
   }
 }

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