ad2app-lib 1.43.0 → 1.44.0

package/src/types/agency.ts

@@ -0,0 +1,382 @@
+/**
+ * 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';
+
+// ── 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.
+ */
+export const 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',
+} as const;
+
+// ── 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.
+ */
+export const 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',
+] as const;
+
+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 const isAgencyGrantScope = (value: string): value is I_AgencyGrantScope =>
+  (AGENCY_GRANT_SCOPES as readonly string[]).includes(value);
+
+// ── Organization ─────────────────────────────────────────────────────────────
+
+/** `'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 const AGENCY_ORGANIZATION_STATUSES = [
+  'pending',
+  'approved',
+  'rejected',
+  'closed',
+] as const;
+
+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;
+}
+
+// ── 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.
+ */
+export const CREATOR_ACCESS_GRANT_STATES = [
+  'requested',
+  'active',
+  'declined',
+  'expired',
+  'revoked',
+] as const;
+
+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 ───────────────────────────────────────────────────────────────────
+
+/**
+ * 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 const 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',
+] as const;
+
+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 const AGENCY_ROSTER_NEEDS_ATTENTION_STATES = [
+  'lapsed',
+  'disconnected',
+  'stale',
+] as const satisfies readonly AgencyRosterRowState[];
+
+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;
+}
+
+// ── DTOs ─────────────────────────────────────────────────────────────────────
+
+export class CreateAgencyOrganizationDto {
+  name: string;
+  website?: string;
+  registryId: string;
+  registryCountry: string;
+  contactEmail: string;
+
+  constructor(data: CreateAgencyOrganizationDto) {
+    this.name = data.name;
+    this.website = data.website;
+    this.registryId = data.registryId;
+    this.registryCountry = data.registryCountry;
+    this.contactEmail = data.contactEmail;
+  }
+}
+
+export class InviteAgencyMemberDto {
+  email: string;
+
+  constructor(data: InviteAgencyMemberDto) {
+    this.email = data.email;
+  }
+}
+
+export class RedeemAgencyInviteDto {
+  token: string;
+
+  constructor(data: RedeemAgencyInviteDto) {
+    this.token = data.token;
+  }
+}
+
+export class AcceptAgencyMemberInviteDto {
+  token: string;
+
+  constructor(data: AcceptAgencyMemberInviteDto) {
+    this.token = data.token;
+  }
+}
+
+/**
+ * Accepting consent. Either arm identifies the grant being answered; `scopes`
+ * is the creator's answer and defaults to the requested set when absent.
+ */
+export class AcceptGrantDto {
+  token?: string;
+  grantId?: string;
+  scopes?: I_AgencyGrantScope[];
+
+  constructor(data: AcceptGrantDto) {
+    this.token = data.token;
+    this.grantId = data.grantId;
+    this.scopes = data.scopes;
+  }
+}
+
+/** The creator narrowing or widening a live grant — the only other write path. */
+export class UpdateGrantScopesDto {
+  scopes: I_AgencyGrantScope[];
+
+  constructor(data: UpdateGrantScopesDto) {
+    this.scopes = data.scopes;
+  }
+}
+
+export class SponsorCreatorDto {
+  tier: SponsoredTier;
+
+  constructor(data: SponsorCreatorDto) {
+    this.tier = data.tier;
+  }
+}
+
+export class AgencyDiscoverQueryDto {
+  /** An EXACT platform username or e-mail. Never recorded in analytics (FR-015). */
+  q: string;
+
+  constructor(data: AgencyDiscoverQueryDto) {
+    this.q = data.q;
+  }
+}
+
+export class AgencyAccessRequestDto {
+  userId: string;
+  scopes: I_AgencyGrantScope[];
+
+  constructor(data: AgencyAccessRequestDto) {
+    this.userId = data.userId;
+    this.scopes = data.scopes;
+  }
+}
+
+export class AdminSetOrganizationStatusDto {
+  status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
+  /** Required on reject — a rejected applicant is shown this (FR-002). */
+  reason?: string;
+
+  constructor(data: AdminSetOrganizationStatusDto) {
+    this.status = data.status;
+    this.reason = data.reason;
+  }
+}

package/src/types/index.ts

@@ -41,5 +41,8 @@ export * from "./scheduling";
 // ── Agent domain (delegated authority + direct media upload, spec 163) ───────
 export * from "./agent";
 
+// ── Agency domain (organizations, memberships, creator access grants, spec 175)
+export * from "./agency";
+
 // ── Access control ────────────────────────────────────────────────────────────
 export * from "./I_AccessDenial";