ad2app-lib 1.44.0 → 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,25 +305,140 @@ 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.
+ *
+ * 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 declare class CreateAgencyOrganizationDto {
     name: string;
+    /** Rendered as a link on the admin screen, so the protocol is checked here. */
     website?: string;
     registryId: string;
+    /** ISO-3166 alpha-2: which register a reviewer should look in. */
     registryCountry: string;
     contactEmail: string;
-    constructor(data: CreateAgencyOrganizationDto);
+    constructor(data?: Partial<CreateAgencyOrganizationDto>);
 }
 export declare class InviteAgencyMemberDto {
     email: string;
-    constructor(data: InviteAgencyMemberDto);
+    constructor(data?: Partial<InviteAgencyMemberDto>);
 }
 export declare class RedeemAgencyInviteDto {
     token: string;
-    constructor(data: RedeemAgencyInviteDto);
+    constructor(data?: Partial<RedeemAgencyInviteDto>);
 }
 export declare class AcceptAgencyMemberInviteDto {
     token: string;
-    constructor(data: AcceptAgencyMemberInviteDto);
+    constructor(data?: Partial<AcceptAgencyMemberInviteDto>);
 }
 /**
  * Accepting consent. Either arm identifies the grant being answered; `scopes`
@@ -230,31 +447,74 @@ export declare class AcceptAgencyMemberInviteDto {
 export declare class AcceptGrantDto {
     token?: string;
     grantId?: string;
+    /** A subset of the three reads. Never empty: sharing nothing is declining. */
     scopes?: I_AgencyGrantScope[];
-    constructor(data: AcceptGrantDto);
+    constructor(data?: Partial<AcceptGrantDto>);
 }
 /** The creator narrowing or widening a live grant — the only other write path. */
 export declare class UpdateGrantScopesDto {
     scopes: I_AgencyGrantScope[];
-    constructor(data: UpdateGrantScopesDto);
+    constructor(data?: Partial<UpdateGrantScopesDto>);
 }
 export declare class SponsorCreatorDto {
     tier: SponsoredTier;
-    constructor(data: SponsorCreatorDto);
+    constructor(data?: Partial<SponsorCreatorDto>);
 }
 export declare class AgencyDiscoverQueryDto {
     /** An EXACT platform username or e-mail. Never recorded in analytics (FR-015). */
     q: string;
-    constructor(data: 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: AgencyAccessRequestDto);
+    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). */
+    /** 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. */
     reason?: string;
-    constructor(data: AdminSetOrganizationStatusDto);
+    constructor(data?: Partial<AdminSetOrganizationStatusDto>);
 }