ad2app-lib 1.43.0 → 1.44.1

package/dist/types/agency.js

@@ -0,0 +1,299 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+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;
+const class_validator_1 = require("class-validator");
+// ── 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 ─────────────────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+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;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "name", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsUrl)({ protocols: ['http', 'https'], require_protocol: true }),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "website", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "registryId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Length)(2, 2),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "registryCountry", void 0);
+__decorate([
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], CreateAgencyOrganizationDto.prototype, "contactEmail", void 0);
+class InviteAgencyMemberDto {
+    constructor(data) {
+        this.email = data?.email ?? '';
+    }
+}
+exports.InviteAgencyMemberDto = InviteAgencyMemberDto;
+__decorate([
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], InviteAgencyMemberDto.prototype, "email", void 0);
+class RedeemAgencyInviteDto {
+    constructor(data) {
+        this.token = data?.token ?? '';
+    }
+}
+exports.RedeemAgencyInviteDto = RedeemAgencyInviteDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RedeemAgencyInviteDto.prototype, "token", void 0);
+class AcceptAgencyMemberInviteDto {
+    constructor(data) {
+        this.token = data?.token ?? '';
+    }
+}
+exports.AcceptAgencyMemberInviteDto = AcceptAgencyMemberInviteDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AcceptAgencyMemberInviteDto.prototype, "token", void 0);
+/**
+ * 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;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AcceptGrantDto.prototype, "token", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsUUID)(),
+    __metadata("design:type", String)
+], AcceptGrantDto.prototype, "grantId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], AcceptGrantDto.prototype, "scopes", void 0);
+/** The creator narrowing or widening a live grant — the only other write path. */
+class UpdateGrantScopesDto {
+    constructor(data) {
+        this.scopes = data?.scopes ?? [];
+    }
+}
+exports.UpdateGrantScopesDto = UpdateGrantScopesDto;
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], UpdateGrantScopesDto.prototype, "scopes", void 0);
+class SponsorCreatorDto {
+    constructor(data) {
+        this.tier = data?.tier ?? 'starter';
+    }
+}
+exports.SponsorCreatorDto = SponsorCreatorDto;
+__decorate([
+    (0, class_validator_1.IsIn)(['starter', 'pro']),
+    __metadata("design:type", String)
+], SponsorCreatorDto.prototype, "tier", void 0);
+class AgencyDiscoverQueryDto {
+    constructor(data) {
+        this.q = data?.q ?? '';
+    }
+}
+exports.AgencyDiscoverQueryDto = AgencyDiscoverQueryDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], AgencyDiscoverQueryDto.prototype, "q", void 0);
+class AgencyAccessRequestDto {
+    constructor(data) {
+        this.userId = data?.userId ?? '';
+        this.scopes = data?.scopes ?? [];
+    }
+}
+exports.AgencyAccessRequestDto = AgencyAccessRequestDto;
+__decorate([
+    (0, class_validator_1.IsUUID)(),
+    __metadata("design:type", String)
+], AgencyAccessRequestDto.prototype, "userId", void 0);
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayNotEmpty)(),
+    (0, class_validator_1.IsIn)(exports.AGENCY_GRANT_SCOPES, { each: true }),
+    __metadata("design:type", Array)
+], AgencyAccessRequestDto.prototype, "scopes", void 0);
+class AdminSetOrganizationStatusDto {
+    constructor(data) {
+        this.status = data?.status ?? 'approved';
+        this.reason = data?.reason;
+    }
+}
+exports.AdminSetOrganizationStatusDto = AdminSetOrganizationStatusDto;
+__decorate([
+    (0, class_validator_1.IsIn)(['approved', 'rejected']),
+    __metadata("design:type", Object)
+], AdminSetOrganizationStatusDto.prototype, "status", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], AdminSetOrganizationStatusDto.prototype, "reason", void 0);

package/dist/types/index.d.ts

@@ -37,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

@@ -55,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.43.0",
+  "version": "1.44.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -51,7 +51,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej Górski@ad2.app",
+  "author": "Maciej G\u00f3rski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/analytics/index.test.ts

@@ -159,8 +159,57 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   // 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 = {
@@ -167,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];
@@ -380,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:
@@ -607,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/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}`);
+	}
 });