ad2app-lib 1.42.0 → 1.44.0

package/dist/analytics/index.d.ts

@@ -9,6 +9,7 @@
  * Do NOT rename events after they ship — historical data does not migrate.
  */
 import type { AccessDenialCode } from "../types/I_AccessDenial";
+import type { SponsoredTier } from "../types/agency";
 /** Canonical PostHog event names. */
 export declare const EVENTS: {
     readonly LANDING_CTA_CLICKED: "landing_cta_clicked";
@@ -29,6 +30,8 @@ export declare const EVENTS: {
     readonly PLAYBOOK_OPENED: "playbook_opened";
     readonly PLAYBOOK_DOWNLOADED: "playbook_downloaded";
     readonly SIGNED_UP: "signed_up";
+    readonly ANALYTICS_CONSENT_RECORDED: "analytics_consent_recorded";
+    readonly FIRST_AUTHENTICATED: "first_authenticated";
     readonly PROFILE_COMPLETED: "profile_completed";
     readonly LOGGED_IN: "logged_in";
     readonly SOCIAL_ACCOUNT_CONNECTED: "social_account_connected";
@@ -88,6 +91,21 @@ export declare const EVENTS: {
     readonly NATIVE_SESSION_LAUNCHED: "native_session_launched";
     readonly NATIVE_SESSION_RENEWED: "native_session_renewed";
     readonly NATIVE_SESSION_ENDED: "native_session_ended";
+    readonly AGENCY_SIGNUP_SUBMITTED: "agency_signup_submitted";
+    readonly AGENCY_APPROVED: "agency_approved";
+    readonly AGENCY_REJECTED: "agency_rejected";
+    readonly AGENCY_MEMBER_INVITED: "agency_member_invited";
+    readonly AGENCY_INVITE_LINK_ROTATED: "agency_invite_link_rotated";
+    readonly AGENCY_INVITE_OPENED: "agency_invite_opened";
+    readonly AGENCY_CONSENT_ACCEPTED: "agency_consent_accepted";
+    readonly AGENCY_CONSENT_DECLINED: "agency_consent_declined";
+    readonly AGENCY_GRANT_REVOKED: "agency_grant_revoked";
+    readonly AGENCY_ROSTER_VIEWED: "agency_roster_viewed";
+    readonly AGENCY_CREATOR_VIEWED: "agency_creator_viewed";
+    readonly AGENCY_SPONSORSHIP_STARTED: "agency_sponsorship_started";
+    readonly AGENCY_SPONSORSHIP_ENDED: "agency_sponsorship_ended";
+    readonly AGENCY_DISCOVER_SEARCHED: "agency_discover_searched";
+    readonly AGENCY_ACCESS_REQUESTED: "agency_access_requested";
 };
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** Which email program a send belongs to (spec 120). Wire values — do not rename. */
@@ -213,6 +231,28 @@ export type SignInFailureReason = 'canceled' | 'missing_code' | 'invalid_provide
 export declare const SIGN_IN_FAILURE_REASONS: readonly ["canceled", "missing_code", "invalid_provider", "no_email", "api_failed", "exception"];
 export type PublishFailureReason = 'auth' | 'rate_limit' | 'media' | 'content' | 'network' | 'platform' | 'unknown';
 /** Property shape per event. Keeps emitters honest across repos. */
+/**
+ * The shared shape every agency event carries (spec 175, contract lib-types.md).
+ *
+ * `organization_id` is mandatory because every agency event is an act BY an
+ * organization — an agency event without one cannot be attributed, and the
+ * whole point of the set is reading adoption per agency after launch (FR-018).
+ */
+export interface AgencyEventProperties {
+    organization_id: string;
+    /** Present once a specific consent is the subject of the act. */
+    grant_id?: string;
+    actor_role: 'owner' | 'member' | 'creator' | 'admin' | 'system';
+    origin?: 'invite_link' | 'agency_request';
+    terms_version?: string;
+    tier?: SponsoredTier;
+    /**
+     * The creator the act concerns, as a PROPERTY. Never the distinct id an
+     * agency-side event is captured under (audit F17): an agency browsing its
+     * roster must not write events into its creators' own timelines.
+     */
+    creator_user_id?: string;
+}
 export interface EventProperties {
     [EVENTS.LANDING_CTA_CLICKED]: {
         location: 'hero' | 'pricing' | 'final_cta' | 'nav' | 'ai_connector' | 'free_skills';
@@ -262,6 +302,10 @@ export interface EventProperties {
         method: 'email' | 'google';
         role: string;
     };
+    [EVENTS.ANALYTICS_CONSENT_RECORDED]: {
+        state: 'granted' | 'declined' | 'unset';
+    };
+    [EVENTS.FIRST_AUTHENTICATED]: Record<string, never>;
     [EVENTS.PROFILE_COMPLETED]: {
         role: string;
     };
@@ -523,6 +567,23 @@ export interface EventProperties {
     [EVENTS.NATIVE_SESSION_ENDED]: {
         cause: 'rejected' | 'sign_out';
     };
+    [EVENTS.AGENCY_SIGNUP_SUBMITTED]: AgencyEventProperties;
+    [EVENTS.AGENCY_APPROVED]: AgencyEventProperties;
+    [EVENTS.AGENCY_REJECTED]: AgencyEventProperties;
+    [EVENTS.AGENCY_MEMBER_INVITED]: AgencyEventProperties;
+    [EVENTS.AGENCY_INVITE_LINK_ROTATED]: AgencyEventProperties;
+    [EVENTS.AGENCY_INVITE_OPENED]: AgencyEventProperties;
+    [EVENTS.AGENCY_CONSENT_ACCEPTED]: AgencyEventProperties;
+    [EVENTS.AGENCY_CONSENT_DECLINED]: AgencyEventProperties;
+    [EVENTS.AGENCY_GRANT_REVOKED]: AgencyEventProperties;
+    [EVENTS.AGENCY_ROSTER_VIEWED]: AgencyEventProperties;
+    [EVENTS.AGENCY_CREATOR_VIEWED]: AgencyEventProperties;
+    [EVENTS.AGENCY_SPONSORSHIP_STARTED]: AgencyEventProperties;
+    [EVENTS.AGENCY_SPONSORSHIP_ENDED]: AgencyEventProperties;
+    [EVENTS.AGENCY_DISCOVER_SEARCHED]: AgencyEventProperties & {
+        matched: boolean;
+    };
+    [EVENTS.AGENCY_ACCESS_REQUESTED]: AgencyEventProperties;
 }
 /** Canonical person property keys (set via identify / $set). */
 export declare const PERSON_PROPS: {

package/dist/analytics/index.js

@@ -39,6 +39,15 @@ exports.EVENTS = {
     PLAYBOOK_DOWNLOADED: 'playbook_downloaded',
     // Activation (web app)
     SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
+    // 171 (backend#307): the analytics answer itself, emitted by the BACKEND so
+    // it arrives for the people who declined — a decline recorded only by the
+    // browser that declined is a fact nobody can read. Carries the answer and
+    // nothing else.
+    ANALYTICS_CONSENT_RECORDED: 'analytics_consent_recorded', // server-owned (backend)
+    // 171: the first authenticated request after signup. Server-owned and
+    // consent-independent, in the same spirit as T046/T054 — it is what tells
+    // "used the product, refused tracking" apart from "never came back".
+    FIRST_AUTHENTICATED: 'first_authenticated', // server-owned (backend)
     PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
     LOGGED_IN: 'logged_in',
     SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
@@ -146,6 +155,28 @@ exports.EVENTS = {
     NATIVE_SESSION_LAUNCHED: 'native_session_launched',
     NATIVE_SESSION_RENEWED: 'native_session_renewed',
     NATIVE_SESSION_ENDED: 'native_session_ended',
+    // Agency domain (175). Every one of these is captured under the acting
+    // person's own distinct id: agency-side events under the MEMBER's, with
+    // creator_user_id as a property, never under the creator's (audit F17) --
+    // otherwise an agency's activity would rewrite the creator's own timeline.
+    AGENCY_SIGNUP_SUBMITTED: 'agency_signup_submitted',
+    AGENCY_APPROVED: 'agency_approved', // server-owned (backend)
+    AGENCY_REJECTED: 'agency_rejected', // server-owned (backend)
+    AGENCY_MEMBER_INVITED: 'agency_member_invited',
+    AGENCY_INVITE_LINK_ROTATED: 'agency_invite_link_rotated',
+    AGENCY_INVITE_OPENED: 'agency_invite_opened',
+    AGENCY_CONSENT_ACCEPTED: 'agency_consent_accepted',
+    AGENCY_CONSENT_DECLINED: 'agency_consent_declined',
+    AGENCY_GRANT_REVOKED: 'agency_grant_revoked',
+    AGENCY_ROSTER_VIEWED: 'agency_roster_viewed',
+    AGENCY_CREATOR_VIEWED: 'agency_creator_viewed',
+    AGENCY_SPONSORSHIP_STARTED: 'agency_sponsorship_started',
+    AGENCY_SPONSORSHIP_ENDED: 'agency_sponsorship_ended',
+    // Carries `matched` and NEVER the query (FR-015, audit F17): the search term
+    // is the one field that would turn product analytics into a record of which
+    // creators an agency went looking for.
+    AGENCY_DISCOVER_SEARCHED: 'agency_discover_searched',
+    AGENCY_ACCESS_REQUESTED: 'agency_access_requested',
 };
 /**
  * Canonical email event property KEYS (spec 120 T001). Emitters and tests

package/dist/types/I_AccessDenial.d.ts

@@ -24,6 +24,61 @@ export declare const ACCESS_DENIAL_CODES: {
      * for this one and do NOT redirect.
      */
     readonly ENTITLEMENT_PRECONDITION: "entitlement-precondition";
+    /**
+     * The caller is not an admin.
+     *
+     * `RoleGuard` answered a 401 with Polish prose until 2026-09-21, which the
+     * frontend's session handling reads as an expired session — so a non-admin
+     * who opened an admin screen could be signed out rather than refused. A 403
+     * with a code says "you may not", which is the true statement.
+     */
+    readonly ADMIN_REQUIRED: "admin-required";
+    /** The caller holds no accepted membership in any organization. */
+    readonly AGENCY_NOT_MEMBER: "agency-not-member";
+    /** Their organization is still awaiting a human decision (FR-002). */
+    readonly AGENCY_PENDING: "agency-pending";
+    /** Their organization was rejected; the reason travels in the body. */
+    readonly AGENCY_REJECTED: "agency-rejected";
+    /** No live subscription: the roster is dark until the plan is paid (FR-013a). */
+    readonly AGENCY_UNPAID: "agency-unpaid";
+    /**
+     * ONE code for EVERY "cannot see this creator" case — no grant, another
+     * organization's creator, a non-existent id, a non-discoverable account.
+     *
+     * The single code IS the privacy control (FR-011, SC-005, audit F6). Distinct
+     * codes would let an agency learn that an account exists by the shape of its
+     * refusal, which is the same existence oracle the discover query is
+     * structurally built to avoid.
+     */
+    readonly AGENCY_NO_ACCESS: "agency-no-access";
+    /**
+     * The grant exists but does not carry the scope this read needs.
+     *
+     * Returned ONLY for a creator the caller already holds on the roster — for
+     * anyone else it would prove a grant exists, so they get AGENCY_NO_ACCESS
+     * instead (SC-012).
+     */
+    readonly AGENCY_SCOPE_NOT_GRANTED: "agency-scope-not-granted";
+    /** The consent screen is off in this environment (FR-020, the legal gate). */
+    readonly AGENCY_CONSENT_DISABLED: "agency-consent-disabled";
+    /** The roster invite link expired, was rotated, or its organization is not approved. */
+    readonly AGENCY_LINK_INVALID: "agency-link-invalid";
+    /** An admin may not decide on an organization they belong to (FR-017). */
+    readonly AGENCY_ADMIN_SELF_APPROVAL: "agency-admin-self-approval";
+    /**
+     * A sole owner tried to leave or delete their account. Refused until they
+     * hand ownership over or close the organization explicitly (FR-004): closing
+     * carries a fan-out that cancels a subscription and ends sponsorships, and
+     * that must be a decision rather than a side effect.
+     */
+    readonly AGENCY_SOLE_OWNER_BLOCKED: "agency-sole-owner-blocked";
+    /** A member invitation token that is expired, already used, or revoked (FR-005). */
+    readonly AGENCY_MEMBER_INVITE_INVALID: "agency-member-invite-invalid";
+    /**
+     * The invited or accepting person already belongs to an organization (one
+     * per person, FR-004). Names the case and NOTHING else about that account.
+     */
+    readonly AGENCY_ALREADY_IN_ORGANIZATION: "agency-already-in-organization";
 };
 export type AccessDenialCode = (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
 /**

package/dist/types/I_AccessDenial.js

@@ -27,6 +27,62 @@ exports.ACCESS_DENIAL_CODES = {
      * for this one and do NOT redirect.
      */
     ENTITLEMENT_PRECONDITION: "entitlement-precondition",
+    /**
+     * The caller is not an admin.
+     *
+     * `RoleGuard` answered a 401 with Polish prose until 2026-09-21, which the
+     * frontend's session handling reads as an expired session — so a non-admin
+     * who opened an admin screen could be signed out rather than refused. A 403
+     * with a code says "you may not", which is the true statement.
+     */
+    ADMIN_REQUIRED: "admin-required",
+    // ── Agency domain (spec 175) ──────────────────────────────────────────────
+    /** The caller holds no accepted membership in any organization. */
+    AGENCY_NOT_MEMBER: "agency-not-member",
+    /** Their organization is still awaiting a human decision (FR-002). */
+    AGENCY_PENDING: "agency-pending",
+    /** Their organization was rejected; the reason travels in the body. */
+    AGENCY_REJECTED: "agency-rejected",
+    /** No live subscription: the roster is dark until the plan is paid (FR-013a). */
+    AGENCY_UNPAID: "agency-unpaid",
+    /**
+     * ONE code for EVERY "cannot see this creator" case — no grant, another
+     * organization's creator, a non-existent id, a non-discoverable account.
+     *
+     * The single code IS the privacy control (FR-011, SC-005, audit F6). Distinct
+     * codes would let an agency learn that an account exists by the shape of its
+     * refusal, which is the same existence oracle the discover query is
+     * structurally built to avoid.
+     */
+    AGENCY_NO_ACCESS: "agency-no-access",
+    /**
+     * The grant exists but does not carry the scope this read needs.
+     *
+     * Returned ONLY for a creator the caller already holds on the roster — for
+     * anyone else it would prove a grant exists, so they get AGENCY_NO_ACCESS
+     * instead (SC-012).
+     */
+    AGENCY_SCOPE_NOT_GRANTED: "agency-scope-not-granted",
+    /** The consent screen is off in this environment (FR-020, the legal gate). */
+    AGENCY_CONSENT_DISABLED: "agency-consent-disabled",
+    /** The roster invite link expired, was rotated, or its organization is not approved. */
+    AGENCY_LINK_INVALID: "agency-link-invalid",
+    /** An admin may not decide on an organization they belong to (FR-017). */
+    AGENCY_ADMIN_SELF_APPROVAL: "agency-admin-self-approval",
+    /**
+     * A sole owner tried to leave or delete their account. Refused until they
+     * hand ownership over or close the organization explicitly (FR-004): closing
+     * carries a fan-out that cancels a subscription and ends sponsorships, and
+     * that must be a decision rather than a side effect.
+     */
+    AGENCY_SOLE_OWNER_BLOCKED: "agency-sole-owner-blocked",
+    /** A member invitation token that is expired, already used, or revoked (FR-005). */
+    AGENCY_MEMBER_INVITE_INVALID: "agency-member-invite-invalid",
+    /**
+     * The invited or accepting person already belongs to an organization (one
+     * per person, FR-004). Names the case and NOTHING else about that account.
+     */
+    AGENCY_ALREADY_IN_ORGANIZATION: "agency-already-in-organization",
 };
 /**
  * WHICH precondition the entitlement wall refused on (backend#305, spec 170).

package/dist/types/I_AnalyticsConsent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A person's stated answer about analytics, as an ACCOUNT FACT (spec 171,
+ * backend#307).
+ *
+ * WHY THIS EXISTS. `posthog-js` runs `opt_out_capturing_by_default: true`, and
+ * a decline calls `opt_out_capturing()`. That is correct and it is the point:
+ * a decline collects nothing. It also means the fact of the decline is known
+ * only to that browser — so from the product's side, someone using the app
+ * every day with analytics off is indistinguishable from someone who signed up
+ * and never came back. Five of nineteen beta testers were in that state on
+ * 2026-09-14, and every percentage on the beta dashboard was silently computed
+ * over fourteen people while claiming nineteen.
+ *
+ * RECORDING A DECLINE IS NOT THE TRACKING THAT WAS DECLINED. This carries the
+ * answer and nothing else — no page, no behaviour, no session. It is the same
+ * instrument as `push_consent_state`, which has recorded "declined" as a
+ * separate legal control since spec 162 without anyone calling it surveillance,
+ * and it is precisely what lets the product HONOUR a decline while still
+ * counting that person as a user rather than as an absence.
+ */
+export declare const ANALYTICS_CONSENT_STATES: {
+    /** Never answered the banner. The default, and distinguishable from both
+     *  answers — an unanswered question is not a "no". */
+    readonly UNSET: "unset";
+    /** Accepted analytics. Recorded the same way as a decline, so neither answer
+     *  is ever inferred from the absence of the other. */
+    readonly GRANTED: "granted";
+    /** Declined analytics. The person is still using the product; they are
+     *  invisible by choice, which is a different thing from inactive. */
+    readonly DECLINED: "declined";
+};
+export type AnalyticsConsentState = (typeof ANALYTICS_CONSENT_STATES)[keyof typeof ANALYTICS_CONSENT_STATES];
+/**
+ * The body of `POST /users/analytics-consent`.
+ *
+ * `unset` IS sendable, and only from one place: the "Cookie settings" link
+ * that reopens the choice (review 2026-09-17 M2). The first draft forbade it
+ * on the reasoning that the absence of an answer is not an answer anyone
+ * gives — true of the banner, false of a RESET, which is a person actively
+ * withdrawing their previous answer. Without it the browser went back to
+ * `pending` while the column still said `declined`, so the dashboard counted
+ * someone as opted out while they were being asked again. A stale record is
+ * worse than an absent one.
+ */
+export interface I_AnalyticsConsentBody {
+    state: AnalyticsConsentState;
+}

package/dist/types/I_AnalyticsConsent.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYTICS_CONSENT_STATES = void 0;
+/**
+ * A person's stated answer about analytics, as an ACCOUNT FACT (spec 171,
+ * backend#307).
+ *
+ * WHY THIS EXISTS. `posthog-js` runs `opt_out_capturing_by_default: true`, and
+ * a decline calls `opt_out_capturing()`. That is correct and it is the point:
+ * a decline collects nothing. It also means the fact of the decline is known
+ * only to that browser — so from the product's side, someone using the app
+ * every day with analytics off is indistinguishable from someone who signed up
+ * and never came back. Five of nineteen beta testers were in that state on
+ * 2026-09-14, and every percentage on the beta dashboard was silently computed
+ * over fourteen people while claiming nineteen.
+ *
+ * RECORDING A DECLINE IS NOT THE TRACKING THAT WAS DECLINED. This carries the
+ * answer and nothing else — no page, no behaviour, no session. It is the same
+ * instrument as `push_consent_state`, which has recorded "declined" as a
+ * separate legal control since spec 162 without anyone calling it surveillance,
+ * and it is precisely what lets the product HONOUR a decline while still
+ * counting that person as a user rather than as an absence.
+ */
+exports.ANALYTICS_CONSENT_STATES = {
+    /** Never answered the banner. The default, and distinguishable from both
+     *  answers — an unanswered question is not a "no". */
+    UNSET: "unset",
+    /** Accepted analytics. Recorded the same way as a decline, so neither answer
+     *  is ever inferred from the absence of the other. */
+    GRANTED: "granted",
+    /** Declined analytics. The person is still using the product; they are
+     *  invisible by choice, which is a different thing from inactive. */
+    DECLINED: "declined",
+};

package/dist/types/agency.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Agency domain — organizations, memberships and creator access grants (spec 175).
+ *
+ * The shape behind "an agency sees its creators' numbers, because the creators
+ * said yes". Two doors, one product: a creator account is unchanged by any of
+ * this, and gains at most one grant.
+ *
+ * The one idea worth carrying into every consumer: a GRANT IS READ-ONLY AND
+ * CREATOR-OWNED. The agency asks for scopes; only a creator's own act ever
+ * writes `grantedScopes` (FR-008, SC-002). Nothing here can express a write on
+ * a creator's account, and that is deliberate — the absence is the feature.
+ *
+ * See specs/175-agency-roster/contracts/lib-types.md.
+ */
+import type { PublishPlatform } from '../publish-limits/types';
+/**
+ * Paths that BOTH repos have to agree on, with one home here.
+ *
+ * The backend mails this path; the frontend registers it. They deploy
+ * separately, so nothing else notices them drifting — and the first version of
+ * that link pointed at a route no repo served, which is how an entire user
+ * story shipped with its headline capability unreachable.
+ *
+ * A test in each repo asserts its own side against these constants. The first
+ * attempt at that guard read across the filesystem into a sibling checkout,
+ * which worked on one laptop and threw ENOENT in CI; a shared constant is the
+ * version that actually runs.
+ */
+export declare const AGENCY_ROUTE_PATHS: {
+    /** A colleague accepting a team invitation (FR-005). */
+    readonly joinTeam: "/agency/join-team";
+    /** A creator consenting to an agency's access (FR-007). */
+    readonly join: "/agency/join";
+    /** A creator answering an access request (FR-016). */
+    readonly requests: "/agency/requests";
+};
+/**
+ * The complete set of reads a grant may carry. A CEILING, not a starting point.
+ *
+ * All three are reads of what the creator already sees on their own screens.
+ * Private messages, comment replies and moderation, publishing, connection
+ * changes and settings are absent by construction (FR-010) — there is no scope
+ * string that could name them, so a widened grant is a spec change rather than
+ * a config change.
+ */
+export declare const AGENCY_GRANT_SCOPES: readonly ["analytics", "comments", "posts"];
+export type I_AgencyGrantScope = (typeof AGENCY_GRANT_SCOPES)[number];
+/**
+ * Narrowing guard — an unrecognised scope must fail closed.
+ *
+ * Scope strings arrive from request bodies (the agency's ask, the creator's
+ * answer), so this is a trust boundary, not a convenience.
+ */
+export declare const isAgencyGrantScope: (value: string) => value is I_AgencyGrantScope;
+/** `'brand'` arrives with spec 148; one column, no enum table. */
+export type AgencyOrganizationType = 'agency';
+/**
+ * `closed` was added by the 2026-09-21 requirements review (FR-004b).
+ *
+ * It exists so closure has an end state that is NOT a deleted row: grants are
+ * `on delete cascade` from the organization, so hard-deleting one would destroy
+ * the consent records FR-009 says are never deleted — and which are also the
+ * invoice basis.
+ */
+export declare const AGENCY_ORGANIZATION_STATUSES: readonly ["pending", "approved", "rejected", "closed"];
+export type AgencyOrganizationStatus = (typeof AGENCY_ORGANIZATION_STATUSES)[number];
+/** Mirrored from Stripe. `comped` is a 100% coupon and is treated as active. */
+export type AgencySubscriptionStatus = 'none' | 'active' | 'trialing' | 'past_due' | 'unpaid' | 'canceled' | 'comped';
+/** Two roles, no more (FR-004). Only the owner reaches billing, members and the link. */
+export type AgencyMemberRole = 'owner' | 'member';
+export type SponsoredTier = 'starter' | 'pro';
+export interface I_AgencyOrganization {
+    id: string;
+    type: AgencyOrganizationType;
+    name: string;
+    website?: string;
+    /** NIP/KRS or a foreign equivalent — free text, verified by a human, never by code. */
+    registryId: string;
+    /** ISO-3166 alpha-2 of the register the identifier belongs to. */
+    registryCountry: string;
+    contactEmail: string;
+    status: AgencyOrganizationStatus;
+    /** The reason an admin gave; shown to a rejected applicant (FR-002). */
+    statusReason?: string;
+    subscriptionStatus: AgencySubscriptionStatus;
+    /** The date sponsorships run to when a grant is revoked or the plan lapses. */
+    currentPeriodEnd?: string;
+    createdAt: string;
+}
+export interface I_AgencyMember {
+    id: string;
+    organizationId: string;
+    /** Null while an e-mail invitation is outstanding — nobody has accepted yet. */
+    userId?: string;
+    invitedEmail: string;
+    role: AgencyMemberRole;
+    invitedAt: string;
+    /** "Who is in" is exactly `acceptedAt != null`. */
+    acceptedAt?: string;
+    revokedAt?: string;
+}
+/**
+ * The five states the data model pins.
+ *
+ * `declined` and `expired` belong to the US5 request path (FR-016) and were
+ * missing from the spec's own Key Entities until the 2026-09-21 review. There
+ * is no transition OUT of `revoked`, `declined` or `expired`: a new consent is
+ * a new row, so the record of what was agreed is never overwritten.
+ */
+export declare const CREATOR_ACCESS_GRANT_STATES: readonly ["requested", "active", "declined", "expired", "revoked"];
+export type CreatorAccessGrantState = (typeof CREATOR_ACCESS_GRANT_STATES)[number];
+export type CreatorAccessGrantOrigin = 'invite_link' | 'agency_request';
+/** Who ended it. Shown in the agency's past-creators history (FR-013b). */
+export type CreatorAccessGrantRevokedBy = 'creator' | 'agency' | 'organization' | 'account-deleted' | 'purge' | 'system';
+export interface I_CreatorAccessGrant {
+    id: string;
+    /**
+     * Null once the creator's user row is hard-purged (audit D-D): the grant
+     * survives as the consent record, with `creatorIdentity` standing in for the
+     * person who is no longer there.
+     */
+    creatorUserId?: string;
+    organizationId: string;
+    organizationName: string;
+    /** What the agency asked for. */
+    requestedScopes: I_AgencyGrantScope[];
+    /** What the creator actually granted — a subset, possibly smaller, never larger. */
+    grantedScopes: I_AgencyGrantScope[];
+    /** Frozen at grant time; what the history shows after a purge. */
+    creatorIdentity: {
+        handle: string;
+        displayName?: string;
+    };
+    state: CreatorAccessGrantState;
+    origin: CreatorAccessGrantOrigin;
+    requestedAt?: string;
+    expiresAt?: string;
+    grantedAt?: string;
+    /** Which terms the creator accepted. A `draft-` prefix means pre-addendum (FR-020). */
+    termsVersion?: string;
+    revokedAt?: string;
+    revokedBy?: CreatorAccessGrantRevokedBy;
+    /**
+     * The agency covering this creator's plan. `until` is set when the
+     * sponsorship is ending — it runs to the close of the period already paid
+     * for, so a revoke never silently drops the creator's plan (FR-014).
+     */
+    sponsorship?: {
+        tier: SponsoredTier;
+        since: string;
+        until?: string;
+    };
+    /** Which platforms the grant reaches right now — derived at read time, never stored. */
+    platformsReached: PublishPlatform[];
+}
+/**
+ * Roster row states, DECLARED IN PRECEDENCE ORDER (data-model §Derived).
+ *
+ * A row holds exactly one state: the first of these that applies, most-blocking
+ * 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 type AgencyRosterRowState = (typeof AGENCY_ROSTER_ROW_STATES)[number];
+/**
+ * What "needs attention" means — ONE home for the KPI tile, the roster segment
+ * and the rail badge, so the three can never drift apart (FR-011).
+ *
+ * `requested` is excluded on purpose: it waits on the CREATOR, and FR-004a says
+ * the badge means something waits on the agency.
+ */
+export declare const AGENCY_ROSTER_NEEDS_ATTENTION_STATES: readonly ["lapsed", "disconnected", "stale"];
+export type AgencyRosterNeedsAttentionState = (typeof AGENCY_ROSTER_NEEDS_ATTENTION_STATES)[number];
+export interface I_AgencyRosterRow {
+    grantId: string;
+    creator: {
+        id: string;
+        handle: string;
+    };
+    platforms: PublishPlatform[];
+    state: AgencyRosterRowState;
+    grantedScopes: I_AgencyGrantScope[];
+    lastSyncAt?: string;
+}
+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;
+        /** Count of rows in AGENCY_ROSTER_NEEDS_ATTENTION_STATES. */
+        needsAttention: number;
+    };
+    items: I_AgencyRosterRow[];
+}
+/** What a sponsored creator sees on their OWN subscription screen (FR-014). */
+export interface I_SponsoredBy {
+    organizationName: string;
+    tier: SponsoredTier;
+    /** Present once the sponsorship is ending: the date their plan runs to. */
+    until?: string;
+}
+export declare class CreateAgencyOrganizationDto {
+    name: string;
+    website?: string;
+    registryId: string;
+    registryCountry: string;
+    contactEmail: string;
+    constructor(data: CreateAgencyOrganizationDto);
+}
+export declare class InviteAgencyMemberDto {
+    email: string;
+    constructor(data: InviteAgencyMemberDto);
+}
+export declare class RedeemAgencyInviteDto {
+    token: string;
+    constructor(data: RedeemAgencyInviteDto);
+}
+export declare class AcceptAgencyMemberInviteDto {
+    token: string;
+    constructor(data: AcceptAgencyMemberInviteDto);
+}
+/**
+ * Accepting consent. Either arm identifies the grant being answered; `scopes`
+ * is the creator's answer and defaults to the requested set when absent.
+ */
+export declare class AcceptGrantDto {
+    token?: string;
+    grantId?: string;
+    scopes?: I_AgencyGrantScope[];
+    constructor(data: AcceptGrantDto);
+}
+/** The creator narrowing or widening a live grant — the only other write path. */
+export declare class UpdateGrantScopesDto {
+    scopes: I_AgencyGrantScope[];
+    constructor(data: UpdateGrantScopesDto);
+}
+export declare class SponsorCreatorDto {
+    tier: SponsoredTier;
+    constructor(data: SponsorCreatorDto);
+}
+export declare class AgencyDiscoverQueryDto {
+    /** An EXACT platform username or e-mail. Never recorded in analytics (FR-015). */
+    q: string;
+    constructor(data: AgencyDiscoverQueryDto);
+}
+export declare class AgencyAccessRequestDto {
+    userId: string;
+    scopes: I_AgencyGrantScope[];
+    constructor(data: AgencyAccessRequestDto);
+}
+export declare class AdminSetOrganizationStatusDto {
+    status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
+    /** Required on reject — a rejected applicant is shown this (FR-002). */
+    reason?: string;
+    constructor(data: AdminSetOrganizationStatusDto);
+}