ad2app-lib 1.43.0 → 1.44.1

package/src/types/agency.test.ts

@@ -0,0 +1,138 @@
+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,
+  InviteAgencyMemberDto,
+  RedeemAgencyInviteDto,
+  AcceptAgencyMemberInviteDto,
+  AcceptGrantDto,
+  UpdateGrantScopesDto,
+  SponsorCreatorDto,
+  AgencyDiscoverQueryDto,
+  AdminSetOrganizationStatusDto,
+} 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"]);
+});
+
+test("every agency DTO survives being constructed with NOTHING", () => {
+  // What a validation pipe actually does. `plainToInstance` calls the
+  // constructor with no arguments before copying the body onto it, so a
+  // constructor that read `data.name` threw a TypeError on every request
+  // instead of validating anything (found 2026-09-22).
+  const DTOS = [
+    CreateAgencyOrganizationDto,
+    InviteAgencyMemberDto,
+    RedeemAgencyInviteDto,
+    AcceptAgencyMemberInviteDto,
+    AcceptGrantDto,
+    UpdateGrantScopesDto,
+    SponsorCreatorDto,
+    AgencyDiscoverQueryDto,
+    AgencyAccessRequestDto,
+    AdminSetOrganizationStatusDto,
+  ];
+
+  for (const Dto of DTOS) {
+    assert.doesNotThrow(() => new (Dto as new () => unknown)(), `${Dto.name} threw on an empty construct`);
+  }
+});
+
+test("every agency DTO carries validation metadata, not just a shape", () => {
+  // An undecorated class typed onto a handler's @Body() is passed through
+  // unchecked: the pipe validates DECORATORS, and there were none until
+  // 2026-09-22. Read from class-validator's own registry rather than by
+  // booting a pipe.
+  const { getMetadataStorage } = require("class-validator");
+  const storage = getMetadataStorage();
+
+  const DECORATED = [
+    CreateAgencyOrganizationDto,
+    InviteAgencyMemberDto,
+    RedeemAgencyInviteDto,
+    AcceptAgencyMemberInviteDto,
+    AcceptGrantDto,
+    UpdateGrantScopesDto,
+    SponsorCreatorDto,
+    AgencyDiscoverQueryDto,
+    AgencyAccessRequestDto,
+    AdminSetOrganizationStatusDto,
+  ];
+
+  for (const Dto of DECORATED) {
+    const rules = storage.getTargetValidationMetadatas(Dto, Dto.name, false, false);
+    assert.ok(rules.length > 0, `${Dto.name} has no validation rules`);
+  }
+});

package/src/types/agency.ts

@@ -0,0 +1,458 @@
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsEmail,
+  IsIn,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUrl,
+  IsUUID,
+  Length,
+} from 'class-validator';
+
+/**
+ * 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 ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Every DTO below carries class-validator decorators and a constructor that
+ * survives being called with nothing.
+ *
+ * Both are load-bearing and were missing until 2026-09-22. The backend mounts
+ * a global `ValidationPipe`, which validates the decorated metadata of the
+ * class a handler's `@Body()` is typed with — an undecorated class, or a body
+ * typed as a plain interface, is simply passed through unchecked. And the pipe
+ * instantiates the class with NO arguments, so a constructor that reads
+ * `data.name` would throw a TypeError on every request rather than validate
+ * anything. The rest of this library's DTOs take `data?: Partial<T>` for that
+ * reason; these now do too.
+ */
+
+export class CreateAgencyOrganizationDto {
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  /** Rendered as a link on the admin screen, so the protocol is checked here. */
+  @IsOptional()
+  @IsUrl({ protocols: ['http', 'https'], require_protocol: true })
+  website?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  registryId: string;
+
+  /** ISO-3166 alpha-2: which register a reviewer should look in. */
+  @IsString()
+  @Length(2, 2)
+  registryCountry: string;
+
+  @IsEmail()
+  contactEmail: string;
+
+  constructor(data?: Partial<CreateAgencyOrganizationDto>) {
+    this.name = data?.name ?? '';
+    this.website = data?.website;
+    this.registryId = data?.registryId ?? '';
+    this.registryCountry = data?.registryCountry ?? '';
+    this.contactEmail = data?.contactEmail ?? '';
+  }
+}
+
+export class InviteAgencyMemberDto {
+  @IsEmail()
+  email: string;
+
+  constructor(data?: Partial<InviteAgencyMemberDto>) {
+    this.email = data?.email ?? '';
+  }
+}
+
+export class RedeemAgencyInviteDto {
+  @IsString()
+  @IsNotEmpty()
+  token: string;
+
+  constructor(data?: Partial<RedeemAgencyInviteDto>) {
+    this.token = data?.token ?? '';
+  }
+}
+
+export class AcceptAgencyMemberInviteDto {
+  @IsString()
+  @IsNotEmpty()
+  token: string;
+
+  constructor(data?: Partial<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 {
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  token?: string;
+
+  @IsOptional()
+  @IsUUID()
+  grantId?: string;
+
+  /** A subset of the three reads. Never empty: sharing nothing is declining. */
+  @IsOptional()
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes?: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<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 {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<UpdateGrantScopesDto>) {
+    this.scopes = data?.scopes ?? [];
+  }
+}
+
+export class SponsorCreatorDto {
+  @IsIn(['starter', 'pro'])
+  tier: SponsoredTier;
+
+  constructor(data?: Partial<SponsorCreatorDto>) {
+    this.tier = data?.tier ?? 'starter';
+  }
+}
+
+export class AgencyDiscoverQueryDto {
+  /** An EXACT platform username or e-mail. Never recorded in analytics (FR-015). */
+  @IsString()
+  @IsNotEmpty()
+  q: string;
+
+  constructor(data?: Partial<AgencyDiscoverQueryDto>) {
+    this.q = data?.q ?? '';
+  }
+}
+
+export class AgencyAccessRequestDto {
+  @IsUUID()
+  userId: string;
+
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsIn(AGENCY_GRANT_SCOPES as unknown as string[], { each: true })
+  scopes: I_AgencyGrantScope[];
+
+  constructor(data?: Partial<AgencyAccessRequestDto>) {
+    this.userId = data?.userId ?? '';
+    this.scopes = data?.scopes ?? [];
+  }
+}
+
+export class AdminSetOrganizationStatusDto {
+  @IsIn(['approved', 'rejected'])
+  status: Extract<AgencyOrganizationStatus, 'approved' | 'rejected'>;
+
+  /** Required on reject — a rejected applicant is shown this (FR-002). The
+   *  "required when rejecting" half is a rule about the PAIR, so it stays in
+   *  the service where both fields are in hand. */
+  @IsOptional()
+  @IsString()
+  reason?: string;
+
+  constructor(data?: Partial<AdminSetOrganizationStatusDto>) {
+    this.status = data?.status ?? 'approved';
+    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";