ad2app-lib 1.42.0 → 1.44.0

package/dist/types/agency.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminSetOrganizationStatusDto = exports.AgencyAccessRequestDto = exports.AgencyDiscoverQueryDto = exports.SponsorCreatorDto = exports.UpdateGrantScopesDto = exports.AcceptGrantDto = exports.AcceptAgencyMemberInviteDto = exports.RedeemAgencyInviteDto = exports.InviteAgencyMemberDto = exports.CreateAgencyOrganizationDto = exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = exports.AGENCY_ROSTER_ROW_STATES = exports.CREATOR_ACCESS_GRANT_STATES = exports.AGENCY_ORGANIZATION_STATUSES = exports.isAgencyGrantScope = exports.AGENCY_GRANT_SCOPES = exports.AGENCY_ROUTE_PATHS = void 0;
+// ── Cross-repo route constants ───────────────────────────────────────────────
+/**
+ * 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.
+ */
+exports.AGENCY_ROUTE_PATHS = {
+    /** A colleague accepting a team invitation (FR-005). */
+    joinTeam: '/agency/join-team',
+    /** A creator consenting to an agency's access (FR-007). */
+    join: '/agency/join',
+    /** A creator answering an access request (FR-016). */
+    requests: '/agency/requests',
+};
+// ── Scopes ───────────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+exports.AGENCY_GRANT_SCOPES = [
+    /** the creator's own five analytics reads, full history, no date filtering */
+    'analytics',
+    /** comments under the creator's posts, READ only — the one inbox read a grant reaches */
+    'comments',
+    /** the creator's published posts with their own numbers — never drafts or the queue */
+    'posts',
+];
+/**
+ * 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.
+ */
+const isAgencyGrantScope = (value) => exports.AGENCY_GRANT_SCOPES.includes(value);
+exports.isAgencyGrantScope = isAgencyGrantScope;
+/**
+ * `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.
+ */
+exports.AGENCY_ORGANIZATION_STATUSES = [
+    'pending',
+    'approved',
+    'rejected',
+    'closed',
+];
+// ── Grant ────────────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+exports.CREATOR_ACCESS_GRANT_STATES = [
+    'requested',
+    'active',
+    'declined',
+    'expired',
+    'revoked',
+];
+// ── Roster ───────────────────────────────────────────────────────────────────
+/**
+ * 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).
+ */
+exports.AGENCY_ROSTER_ROW_STATES = [
+    /** the agency asked, the creator has not answered */
+    'requested',
+    /** the creator's own plan has lapsed */
+    'lapsed',
+    /** the creator has no live platform connection */
+    'disconnected',
+    /** no successful daily sync in 24 hours (FR-011, Jan 2026-09-21) */
+    'stale',
+    'active',
+];
+/**
+ * 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.
+ */
+exports.AGENCY_ROSTER_NEEDS_ATTENTION_STATES = [
+    'lapsed',
+    'disconnected',
+    'stale',
+];
+// ── DTOs ─────────────────────────────────────────────────────────────────────
+class CreateAgencyOrganizationDto {
+    constructor(data) {
+        this.name = data.name;
+        this.website = data.website;
+        this.registryId = data.registryId;
+        this.registryCountry = data.registryCountry;
+        this.contactEmail = data.contactEmail;
+    }
+}
+exports.CreateAgencyOrganizationDto = CreateAgencyOrganizationDto;
+class InviteAgencyMemberDto {
+    constructor(data) {
+        this.email = data.email;
+    }
+}
+exports.InviteAgencyMemberDto = InviteAgencyMemberDto;
+class RedeemAgencyInviteDto {
+    constructor(data) {
+        this.token = data.token;
+    }
+}
+exports.RedeemAgencyInviteDto = RedeemAgencyInviteDto;
+class AcceptAgencyMemberInviteDto {
+    constructor(data) {
+        this.token = data.token;
+    }
+}
+exports.AcceptAgencyMemberInviteDto = AcceptAgencyMemberInviteDto;
+/**
+ * Accepting consent. Either arm identifies the grant being answered; `scopes`
+ * is the creator's answer and defaults to the requested set when absent.
+ */
+class AcceptGrantDto {
+    constructor(data) {
+        this.token = data.token;
+        this.grantId = data.grantId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AcceptGrantDto = AcceptGrantDto;
+/** The creator narrowing or widening a live grant — the only other write path. */
+class UpdateGrantScopesDto {
+    constructor(data) {
+        this.scopes = data.scopes;
+    }
+}
+exports.UpdateGrantScopesDto = UpdateGrantScopesDto;
+class SponsorCreatorDto {
+    constructor(data) {
+        this.tier = data.tier;
+    }
+}
+exports.SponsorCreatorDto = SponsorCreatorDto;
+class AgencyDiscoverQueryDto {
+    constructor(data) {
+        this.q = data.q;
+    }
+}
+exports.AgencyDiscoverQueryDto = AgencyDiscoverQueryDto;
+class AgencyAccessRequestDto {
+    constructor(data) {
+        this.userId = data.userId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AgencyAccessRequestDto = AgencyAccessRequestDto;
+class AdminSetOrganizationStatusDto {
+    constructor(data) {
+        this.status = data.status;
+        this.reason = data.reason;
+    }
+}
+exports.AdminSetOrganizationStatusDto = AdminSetOrganizationStatusDto;

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export * from "./I_Influencer";
 export * from "./I_InfluencersLists";
 export * from "./I_InfluencersCategories";
 export * from "./I_InfluencersProperties";
+export * from "./I_AnalyticsConsent";
 export * from "./I_Item";
 export * from "./I_List";
 export * from "./I_PaginatedList";
@@ -36,4 +37,5 @@ export * from "./I_Publish";
 export * from "./I_SM_Platform";
 export * from "./scheduling";
 export * from "./agent";
+export * from "./agency";
 export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./I_Influencer"), exports);
 __exportStar(require("./I_InfluencersLists"), exports);
 __exportStar(require("./I_InfluencersCategories"), exports);
 __exportStar(require("./I_InfluencersProperties"), exports);
+__exportStar(require("./I_AnalyticsConsent"), exports);
 __exportStar(require("./I_Item"), exports);
 __exportStar(require("./I_List"), exports);
 __exportStar(require("./I_PaginatedList"), exports);
@@ -54,5 +55,7 @@ __exportStar(require("./I_SM_Platform"), exports);
 __exportStar(require("./scheduling"), exports);
 // ── Agent domain (delegated authority + direct media upload, spec 163) ───────
 __exportStar(require("./agent"), exports);
+// ── Agency domain (organizations, memberships, creator access grants, spec 175)
+__exportStar(require("./agency"), exports);
 // ── Access control ────────────────────────────────────────────────────────────
 __exportStar(require("./I_AccessDenial"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.42.0",
+  "version": "1.44.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -154,8 +154,62 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   // 164 G012 — both behind default-OFF flags, fixed for completeness
   [EVENTS.COMMENT_GUARD_MODE_CHANGED]: { mode: "flag-only" },
   [EVENTS.AI_TOOLS_REVOKE_REQUESTED]: {},
+  // 171 (backend#307) — both server-owned, both emitted by the backend so they
+  // arrive for the people who declined analytics. A decline recorded only by
+  // the browser that declined is a fact nobody can read.
+  [EVENTS.ANALYTICS_CONSENT_RECORDED]: { state: "declined" },
+  [EVENTS.FIRST_AUTHENTICATED]: {},
+  // 175 — the agency set. Every witness carries organization_id + actor_role,
+  // because those are the two mandatory fields of AgencyEventProperties.
+  [EVENTS.AGENCY_SIGNUP_SUBMITTED]: { organization_id: "org-1", actor_role: "owner" },
+  [EVENTS.AGENCY_APPROVED]: { organization_id: "org-1", actor_role: "admin" },
+  [EVENTS.AGENCY_REJECTED]: { organization_id: "org-1", actor_role: "admin" },
+  [EVENTS.AGENCY_MEMBER_INVITED]: { organization_id: "org-1", actor_role: "owner" },
+  [EVENTS.AGENCY_INVITE_LINK_ROTATED]: { organization_id: "org-1", actor_role: "owner" },
+  [EVENTS.AGENCY_INVITE_OPENED]: { organization_id: "org-1", actor_role: "creator", origin: "invite_link" },
+  [EVENTS.AGENCY_CONSENT_ACCEPTED]: {
+    organization_id: "org-1",
+    grant_id: "g-1",
+    actor_role: "creator",
+    terms_version: "draft-2026-09-21",
+  },
+  [EVENTS.AGENCY_CONSENT_DECLINED]: { organization_id: "org-1", grant_id: "g-1", actor_role: "creator" },
+  [EVENTS.AGENCY_GRANT_REVOKED]: { organization_id: "org-1", grant_id: "g-1", actor_role: "creator" },
+  [EVENTS.AGENCY_ROSTER_VIEWED]: { organization_id: "org-1", actor_role: "member" },
+  [EVENTS.AGENCY_CREATOR_VIEWED]: {
+    organization_id: "org-1",
+    grant_id: "g-1",
+    actor_role: "member",
+    creator_user_id: "u-1",
+  },
+  [EVENTS.AGENCY_SPONSORSHIP_STARTED]: {
+    organization_id: "org-1",
+    grant_id: "g-1",
+    actor_role: "owner",
+    tier: "pro",
+  },
+  [EVENTS.AGENCY_SPONSORSHIP_ENDED]: { organization_id: "org-1", grant_id: "g-1", actor_role: "system" },
+  [EVENTS.AGENCY_DISCOVER_SEARCHED]: { organization_id: "org-1", actor_role: "member", matched: false },
+  [EVENTS.AGENCY_ACCESS_REQUESTED]: {
+    organization_id: "org-1",
+    grant_id: "g-1",
+    actor_role: "member",
+    origin: "agency_request",
+  },
 };
 
+test("no agency event may carry the discover query — only whether it matched (FR-015)", () => {
+  const agencyEvents = Object.values(EVENTS).filter((name) => name.startsWith("agency_"));
+  assert.equal(agencyEvents.length, 15, "the 175 set is 15 events");
+  for (const name of agencyEvents) {
+    const props = EVENT_PROPERTY_WITNESS[name as keyof typeof EVENT_PROPERTY_WITNESS];
+    for (const key of Object.keys(props)) {
+      assert.notEqual(key, "q", `${name} must never carry the search term`);
+      assert.notEqual(key, "query", `${name} must never carry the search term`);
+    }
+  }
+});
+
 test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {
   const eventValues = Object.values(EVENTS).sort();
   const propertyKeys = Object.keys(EVENT_PROPERTY_WITNESS).sort();

package/src/analytics/index.ts

@@ -10,6 +10,7 @@
  */
 
 import type { AccessDenialCode } from "../types/I_AccessDenial";
+import type { SponsoredTier } from "../types/agency";
 
 /** Canonical PostHog event names. */
 export const EVENTS = {
@@ -43,6 +44,15 @@ export const EVENTS = {
 
   // 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',
@@ -158,6 +168,29 @@ export const 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',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -371,6 +404,29 @@ export type PublishFailureReason =
   | 'unknown'; // no error detail or unclassifiable
 
 /** 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:
@@ -405,6 +461,8 @@ export interface EventProperties {
   [EVENTS.PLAYBOOK_OPENED]: { edition_version?: string };
   [EVENTS.PLAYBOOK_DOWNLOADED]: { edition_version?: string; format?: string };
   [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
+  [EVENTS.ANALYTICS_CONSENT_RECORDED]: { state: 'granted' | 'declined' | 'unset' };
+  [EVENTS.FIRST_AUTHENTICATED]: Record<string, never>;
   [EVENTS.PROFILE_COMPLETED]: { role: string };
   // Spec 161: widened to include 'apple' — the value was already missing from
   // this union (Google/email only) even though native Apple sign-in has
@@ -596,6 +654,27 @@ export interface EventProperties {
   [EVENTS.NATIVE_SESSION_LAUNCHED]: { outcome: 'restored' | 'none' | 'degraded' };
   [EVENTS.NATIVE_SESSION_RENEWED]: Record<string, never>;
   [EVENTS.NATIVE_SESSION_ENDED]: { cause: 'rejected' | 'sign_out' };
+
+  // Agency domain (175, contract lib-types.md). One shared shape: who acted
+  // (`actor_role`), on whose behalf (`organization_id`) and against which
+  // consent (`grant_id`). `creator_user_id` is a PROPERTY of an agency-side
+  // event, never the distinct id it is captured under (audit F17).
+  [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;
+  // `matched` only. The query itself is never sent (FR-015).
+  [EVENTS.AGENCY_DISCOVER_SEARCHED]: AgencyEventProperties & { matched: boolean };
+  [EVENTS.AGENCY_ACCESS_REQUESTED]: AgencyEventProperties;
 }
 
 /** Canonical person property keys (set via identify / $set). */

package/src/types/I_AccessDenial.ts

@@ -24,6 +24,64 @@ export const 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",
 } as const;
 
 export type AccessDenialCode =

package/src/types/I_AnalyticsConsent.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 const 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",
+} as const;
+
+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/src/types/access-denial.test.ts

@@ -60,11 +60,35 @@ test('precondition is optional, so an older backend still sends a valid body', (
 	assert.equal(withIt.precondition, 'no-connection');
 });
 
-test('the denial codes are untouched', () => {
-	// FR-003: this feature adds a field, it does not renegotiate `code`.
-	assert.deepEqual(ACCESS_DENIAL_CODES, {
-		BETA_REQUIRED: 'beta-required',
-		SUBSCRIPTION_REQUIRED: 'subscription-required',
-		ENTITLEMENT_PRECONDITION: 'entitlement-precondition',
-	});
+test('the three original denial codes keep their exact values', () => {
+	// Spec 170 FR-003 locked these because that feature added a FIELD and must
+	// not renegotiate `code`. The lock is on the VALUES, not on the set ever
+	// growing: these three strings are what shipped clients branch on, so a
+	// rename is a breaking change however harmless it looks in a diff.
+	assert.equal(ACCESS_DENIAL_CODES.BETA_REQUIRED, 'beta-required');
+	assert.equal(ACCESS_DENIAL_CODES.SUBSCRIPTION_REQUIRED, 'subscription-required');
+	assert.equal(ACCESS_DENIAL_CODES.ENTITLEMENT_PRECONDITION, 'entitlement-precondition');
+});
+
+test('every code is a unique kebab-case string', () => {
+	const values = Object.values(ACCESS_DENIAL_CODES);
+
+	assert.equal(new Set(values).size, values.length, 'duplicate denial code');
+	for (const value of values) assert.match(value, /^[a-z]+(-[a-z]+)*$/, `not kebab-case: ${value}`);
+});
+
+test('every AGENCY code is namespaced, so a new domain cannot shadow an old wall', () => {
+	// Spec 175 added twelve. A prefix per domain is what keeps "cannot see this
+	// creator" from ever colliding with an entitlement wall a client already
+	// handles correctly — the two want completely different behaviour.
+	// `admin-required` is deliberately NOT agency-prefixed: RoleGuard is generic
+	// and guards the legacy marketplace controllers too.
+	const agencyCodes = Object.entries(ACCESS_DENIAL_CODES).filter(([key]) =>
+		key.startsWith('AGENCY_'),
+	);
+
+	assert.equal(agencyCodes.length, 12);
+	for (const [, value] of agencyCodes) {
+		assert.match(value, /^agency-/, `un-namespaced agency code: ${value}`);
+	}
 });

package/src/types/agency.test.ts

@@ -0,0 +1,80 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  AGENCY_GRANT_SCOPES,
+  AGENCY_ORGANIZATION_STATUSES,
+  CREATOR_ACCESS_GRANT_STATES,
+  AGENCY_ROSTER_ROW_STATES,
+  AGENCY_ROSTER_NEEDS_ATTENTION_STATES,
+  isAgencyGrantScope,
+  CreateAgencyOrganizationDto,
+  AgencyAccessRequestDto,
+} from "./agency";
+
+test("the grant scope set is exactly the three reads the spec allows", () => {
+  assert.deepEqual([...AGENCY_GRANT_SCOPES], ["analytics", "comments", "posts"]);
+});
+
+test("isAgencyGrantScope fails closed on anything outside the set", () => {
+  for (const scope of AGENCY_GRANT_SCOPES) assert.equal(isAgencyGrantScope(scope), true);
+  // The refusals that matter: every one of these is a WRITE the grant must never reach
+  // (FR-010), and a scope string arriving from a request body is untrusted input.
+  for (const notAScope of ["messages", "dms", "publish", "reply", "moderate", "accounts", ""]) {
+    assert.equal(isAgencyGrantScope(notAScope), false, `must refuse: ${notAScope}`);
+  }
+});
+
+test("organization statuses carry `closed` — a closed organization's row is retained, never deleted", () => {
+  assert.deepEqual(
+    [...AGENCY_ORGANIZATION_STATUSES],
+    ["pending", "approved", "rejected", "closed"],
+  );
+});
+
+test("grant states are the five the data model pins, including declined and expired", () => {
+  assert.deepEqual(
+    [...CREATOR_ACCESS_GRANT_STATES],
+    ["requested", "active", "declined", "expired", "revoked"],
+  );
+});
+
+test("roster row states include `stale`, and `revoked` is NOT one of them", () => {
+  assert.deepEqual(
+    [...AGENCY_ROSTER_ROW_STATES],
+    ["requested", "lapsed", "disconnected", "stale", "active"],
+  );
+  assert.equal(
+    (AGENCY_ROSTER_ROW_STATES as readonly string[]).includes("revoked"),
+    false,
+    "a revoked creator leaves the roster for the settings history (FR-011)",
+  );
+});
+
+test("needs-attention is disconnected + lapsed + stale, and never `requested` (FR-011)", () => {
+  assert.deepEqual([...AGENCY_ROSTER_NEEDS_ATTENTION_STATES], ["lapsed", "disconnected", "stale"]);
+  assert.equal(
+    (AGENCY_ROSTER_NEEDS_ATTENTION_STATES as readonly string[]).includes("requested"),
+    false,
+    "a requested grant waits on the CREATOR, so it never lights the agency's badge",
+  );
+  // 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) {
+    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",
+    registryId: "5252445767",
+    registryCountry: "PL",
+    contactEmail: "biuro@studiokot.pl",
+  });
+  assert.equal(org.name, "Studio Kot");
+  assert.equal(org.website, undefined);
+
+  const request = new AgencyAccessRequestDto({ userId: "u-1", scopes: ["analytics"] });
+  assert.deepEqual(request.scopes, ["analytics"]);
+});