@growth-labs/cms 0.5.2 → 0.5.4

package/src/ui/screens/SubscriptionsScreen.tsx

@@ -1,9 +1,8 @@
 // src/ui/screens/SubscriptionsScreen.tsx — Subscriptions screen (P5 Task 11).
 //
 // Renders the member list + filters, 4 KPI cards (Active/MRR/Churn/LTV),
-// the plan-mix bar, export, and gift subscription — backed entirely by
-// GET /admin/api/subscriptions?type=* (members / kpis / planMix / export)
-// and POST /admin/api/subscriptions (gift).
+// the plan-mix bar, export, paid gift-order tracking, and complimentary access
+// administration — backed entirely by GET/POST /admin/api/subscriptions?type=*.
 //
 // Honesty conventions (two-level per grounding fact 10):
 //   - result.status === 'empty'  → honest empty state, no mock numbers
@@ -16,10 +15,15 @@
 // Presentation: Broadsheet idiom — page-head/page-title, .grid-stats KPI cards
 // with serif .tnum numbers, .seg filter, the .tbl members table with .pill.pdot
 // plan/status chips, the .masthead-rule hairline under card titles, and the
-// gift dialog on a .scrim + .panel.panel-pad with .field-label/.input/.btn.
+// complimentary grant dialog on a .scrim + .panel.panel-pad with .field-label/.input/.btn.
 
 import { useCallback, useEffect, useReducer, useState } from 'react'
 import type {
+	ComplimentaryAccessPage,
+	ComplimentaryEmailRetryResult,
+	ComplimentaryEntitlementRow,
+	ComplimentaryGrantResult,
+	ComplimentaryRevokeResult,
 	DuplicateAccountsReport,
 	GiftOrdersPage,
 	LsImportSummary,
@@ -34,12 +38,31 @@ import {
 	planMixToBars,
 	selectKpiState,
 } from './render-state.js'
+import {
+	buildComplimentaryGrantPayload,
+	buildComplimentaryRetryPayload,
+	buildComplimentaryRevokePayload,
+	complimentaryGrantSubmitDisabled,
+	complimentaryPageLabel,
+	complimentaryRowActions,
+	describeComplimentaryGrantResult,
+	describeComplimentaryRetryResult,
+	describeComplimentaryRevokeResult,
+	formatTimestamp,
+	type ResultCopy,
+} from './subscriptions-data.js'
 
 // ---------------------------------------------------------------------------
 // Filter options
 // ---------------------------------------------------------------------------
 
 type FilterOption = 'all' | 'paid' | 'past_due' | 'canceled'
+export type ComplimentaryStatusFilter = 'active' | 'revoked' | 'all'
+
+export interface ComplimentaryQuery {
+	q: string
+	status: ComplimentaryStatusFilter
+}
 
 const FILTER_LABELS: Array<{ value: FilterOption; label: string }> = [
 	{ value: 'all', label: 'All' },
@@ -48,16 +71,32 @@ const FILTER_LABELS: Array<{ value: FilterOption; label: string }> = [
 	{ value: 'canceled', label: 'Canceled' },
 ]
 
+export function buildComplimentaryListUrl(query: ComplimentaryQuery, page: number): string {
+	const params = new URLSearchParams()
+	params.set('type', 'complimentary')
+	const trimmedQuery = query.q.trim()
+	if (trimmedQuery.length > 0) params.set('q', trimmedQuery)
+	params.set('status', query.status)
+	params.set('page', String(page))
+	return `/admin/api/subscriptions?${params.toString()}`
+}
+
 // ---------------------------------------------------------------------------
 // Data shapes
 // ---------------------------------------------------------------------------
 
-interface SubscriptionsData {
+export type ComplimentaryPanelState =
+	| { kind: 'available'; result: ProviderResult<ComplimentaryAccessPage> }
+	| { kind: 'unavailable'; reason: 'forbidden' }
+	| { kind: 'error'; reason: 'request_failed' }
+
+export interface SubscriptionsData {
 	members: ProviderResult<SubscriptionMember[]>
 	kpis: ProviderResult<Record<string, number | null>>
 	planMix: ProviderResult<PlanMixBucket[]>
 	duplicates: ProviderResult<DuplicateAccountsReport>
 	gifts: ProviderResult<GiftOrdersPage>
+	complimentary: ComplimentaryPanelState
 }
 
 // ---------------------------------------------------------------------------
@@ -69,6 +108,7 @@ interface SubscriptionsState {
 	error: string | null
 	data: SubscriptionsData | null
 	page: number
+	complimentaryPage: number
 }
 
 type SubscriptionsAction =
@@ -76,9 +116,10 @@ type SubscriptionsAction =
 	| { type: 'fetch-ok'; data: SubscriptionsData }
 	| { type: 'fetch-error'; error: string }
 	| { type: 'set-page'; page: number }
+	| { type: 'set-complimentary-page'; page: number }
 
 function init(): SubscriptionsState {
-	return { loading: true, error: null, data: null, page: 1 }
+	return { loading: true, error: null, data: null, page: 1, complimentaryPage: 1 }
 }
 
 function reducer(state: SubscriptionsState, action: SubscriptionsAction): SubscriptionsState {
@@ -91,21 +132,23 @@ function reducer(state: SubscriptionsState, action: SubscriptionsAction): Subscr
 			return { ...state, loading: false, error: action.error, data: null }
 		case 'set-page':
 			return { ...state, page: action.page }
+		case 'set-complimentary-page':
+			return { ...state, complimentaryPage: action.page }
 		default:
 			return state
 	}
 }
 
 // ---------------------------------------------------------------------------
-// Gift form state
+// Complimentary grant form state
 // ---------------------------------------------------------------------------
 
-interface GiftState {
+interface ComplimentaryGrantState {
 	open: boolean
 	email: string
-	planVariantId: string
+	reason: string
 	submitting: boolean
-	result: string | null
+	result: ResultCopy | null
 }
 
 // ---------------------------------------------------------------------------
@@ -115,50 +158,69 @@ interface GiftState {
 export function SubscriptionsScreen() {
 	const [filter, setFilter] = useState<FilterOption>('all')
 	const [s, dispatch] = useReducer(reducer, undefined, init)
-	const [gift, setGift] = useState<GiftState>({
+	const [complimentaryGrant, setComplimentaryGrant] = useState<ComplimentaryGrantState>({
 		open: false,
 		email: '',
-		planVariantId: '',
+		reason: '',
 		submitting: false,
 		result: null,
 	})
+	const [complimentaryNotice, setComplimentaryNotice] = useState<ResultCopy | null>(null)
+	const [complimentaryQuery, setComplimentaryQuery] = useState<ComplimentaryQuery>({
+		q: '',
+		status: 'all',
+	})
 	const [exporting, setExporting] = useState(false)
 
-	const fetchData = useCallback(async (f: FilterOption, page: number) => {
-		dispatch({ type: 'fetch-start' })
-		try {
-			const filterParam = f === 'all' ? '' : `&filter=${f}`
-			const [membersRes, kpisRes, planMixRes, duplicatesRes, giftsRes] = await Promise.all([
-				fetch(`/admin/api/subscriptions?type=members${filterParam}&page=${page}`),
-				fetch('/admin/api/subscriptions?type=kpis'),
-				fetch('/admin/api/subscriptions?type=planMix'),
-				fetch('/admin/api/subscriptions?type=duplicates'),
-				fetch('/admin/api/subscriptions?type=gifts'),
-			])
-
-			if (!membersRes.ok || !kpisRes.ok || !planMixRes.ok || !duplicatesRes.ok || !giftsRes.ok) {
-				const bad = [membersRes, kpisRes, planMixRes, duplicatesRes, giftsRes].find((r) => !r.ok)!
-				dispatch({ type: 'fetch-error', error: `${bad.status} ${bad.statusText}` })
-				return
+	const fetchData = useCallback(
+		async (f: FilterOption, page: number, query: ComplimentaryQuery, complimentaryPage: number) => {
+			dispatch({ type: 'fetch-start' })
+			try {
+				const filterParam = f === 'all' ? '' : `&filter=${f}`
+				const paidRequest = Promise.all([
+					fetch(`/admin/api/subscriptions?type=members${filterParam}&page=${page}`),
+					fetch('/admin/api/subscriptions?type=kpis'),
+					fetch('/admin/api/subscriptions?type=planMix'),
+					fetch('/admin/api/subscriptions?type=duplicates'),
+					fetch('/admin/api/subscriptions?type=gifts'),
+				])
+				const complimentaryRequest = fetchComplimentaryPanel(query, complimentaryPage)
+				const [[membersRes, kpisRes, planMixRes, duplicatesRes, giftsRes], complimentary] =
+					await Promise.all([paidRequest, complimentaryRequest])
+
+				if (!membersRes.ok || !kpisRes.ok || !planMixRes.ok || !duplicatesRes.ok || !giftsRes.ok) {
+					dispatch({
+						type: 'fetch-error',
+						error: 'Subscription data is temporarily unavailable. Please try again.',
+					})
+					return
+				}
+
+				const [members, kpis, planMix, duplicates, gifts] = await Promise.all([
+					membersRes.json() as Promise<ProviderResult<SubscriptionMember[]>>,
+					kpisRes.json() as Promise<ProviderResult<Record<string, number | null>>>,
+					planMixRes.json() as Promise<ProviderResult<PlanMixBucket[]>>,
+					duplicatesRes.json() as Promise<ProviderResult<DuplicateAccountsReport>>,
+					giftsRes.json() as Promise<ProviderResult<GiftOrdersPage>>,
+				])
+
+				dispatch({
+					type: 'fetch-ok',
+					data: { members, kpis, planMix, duplicates, gifts, complimentary },
+				})
+			} catch {
+				dispatch({
+					type: 'fetch-error',
+					error: 'Subscription data is temporarily unavailable. Please try again.',
+				})
 			}
-
-			const [members, kpis, planMix, duplicates, gifts] = await Promise.all([
-				membersRes.json() as Promise<ProviderResult<SubscriptionMember[]>>,
-				kpisRes.json() as Promise<ProviderResult<Record<string, number | null>>>,
-				planMixRes.json() as Promise<ProviderResult<PlanMixBucket[]>>,
-				duplicatesRes.json() as Promise<ProviderResult<DuplicateAccountsReport>>,
-				giftsRes.json() as Promise<ProviderResult<GiftOrdersPage>>,
-			])
-
-			dispatch({ type: 'fetch-ok', data: { members, kpis, planMix, duplicates, gifts } })
-		} catch (err) {
-			dispatch({ type: 'fetch-error', error: String(err) })
-		}
-	}, [])
+		},
+		[],
+	)
 
 	useEffect(() => {
-		void fetchData(filter, s.page)
-	}, [fetchData, filter, s.page])
+		void fetchData(filter, s.page, complimentaryQuery, s.complimentaryPage)
+	}, [fetchData, filter, s.page, complimentaryQuery, s.complimentaryPage])
 
 	const handleFilterChange = (f: FilterOption) => {
 		setFilter(f)
@@ -184,30 +246,92 @@ export function SubscriptionsScreen() {
 		}
 	}
 
-	const handleGiftSubmit = async () => {
-		if (!gift.email || !gift.planVariantId) return
-		setGift((g) => ({ ...g, submitting: true, result: null }))
+	const handleComplimentaryGrantSubmit = async () => {
+		if (complimentaryGrantSubmitDisabled(complimentaryGrant, false)) return
+		setComplimentaryGrant((g) => ({ ...g, submitting: true, result: null }))
 		try {
-			const res = await fetch('/admin/api/subscriptions', {
+			const res = await fetch('/admin/api/subscriptions?type=complimentary&action=grant', {
 				method: 'POST',
 				headers: { 'Content-Type': 'application/json' },
-				body: JSON.stringify({ email: gift.email, planVariantId: gift.planVariantId }),
+				body: JSON.stringify(buildComplimentaryGrantPayload(complimentaryGrant)),
 			})
-			const body = (await res.json()) as ProviderResult<{ id: string }>
-			if (body.status === 'empty' || !body.data.id) {
-				setGift((g) => ({ ...g, submitting: false, result: 'Provider not configured.' }))
-			} else {
-				setGift((g) => ({
+			if (!res.ok) {
+				const message = await readErrorMessage(res)
+				setComplimentaryGrant((g) => ({
 					...g,
 					submitting: false,
-					result: `Gift created: ${body.data.id}`,
-					email: '',
-					planVariantId: '',
+					result: { tone: 'error', message },
 				}))
-				void fetchData(filter, s.page)
+				return
+			}
+			const body = (await res.json()) as ProviderResult<ComplimentaryGrantResult>
+			const result = describeComplimentaryGrantResult(body)
+			setComplimentaryGrant((g) => ({
+				...g,
+				submitting: false,
+				result,
+				email: result.tone === 'error' ? g.email : '',
+				reason: result.tone === 'error' ? g.reason : '',
+			}))
+			setComplimentaryNotice(result)
+			void fetchData(filter, s.page, complimentaryQuery, s.complimentaryPage)
+		} catch {
+			setComplimentaryGrant((g) => ({
+				...g,
+				submitting: false,
+				result: {
+					tone: 'error',
+					message: 'Complimentary access could not be granted. Please try again.',
+				},
+			}))
+		}
+	}
+
+	const handleComplimentaryRevoke = async (entitlement: ComplimentaryEntitlementRow) => {
+		const reason = window.prompt('Reason for revoking complimentary access')
+		if (!reason?.trim()) return
+		try {
+			const res = await fetch('/admin/api/subscriptions?type=complimentary&action=revoke', {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(buildComplimentaryRevokePayload(entitlement, reason)),
+			})
+			if (!res.ok) {
+				setComplimentaryNotice({ tone: 'error', message: await readErrorMessage(res) })
+				return
 			}
-		} catch (err) {
-			setGift((g) => ({ ...g, submitting: false, result: String(err) }))
+			const body = (await res.json()) as ProviderResult<ComplimentaryRevokeResult>
+			setComplimentaryNotice(describeComplimentaryRevokeResult(body))
+			void fetchData(filter, s.page, complimentaryQuery, s.complimentaryPage)
+		} catch {
+			setComplimentaryNotice({
+				tone: 'error',
+				message: 'Complimentary access could not be revoked. Please try again.',
+			})
+		}
+	}
+
+	const handleComplimentaryRetry = async (entitlement: ComplimentaryEntitlementRow) => {
+		const reason = window.prompt('Reason for retrying the complimentary access email')
+		if (!reason?.trim()) return
+		try {
+			const res = await fetch('/admin/api/subscriptions?type=complimentary&action=retry-email', {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(buildComplimentaryRetryPayload(entitlement, reason)),
+			})
+			if (!res.ok) {
+				setComplimentaryNotice({ tone: 'error', message: await readErrorMessage(res) })
+				return
+			}
+			const body = (await res.json()) as ProviderResult<ComplimentaryEmailRetryResult>
+			setComplimentaryNotice(describeComplimentaryRetryResult(body))
+			void fetchData(filter, s.page, complimentaryQuery, s.complimentaryPage)
+		} catch {
+			setComplimentaryNotice({
+				tone: 'error',
+				message: 'The email could not be retried. Access was not changed.',
+			})
 		}
 	}
 
@@ -230,14 +354,16 @@ export function SubscriptionsScreen() {
 						<Icon name="download" size={16} />
 						{exporting ? 'Exporting…' : 'Export'}
 					</button>
-					<button
-						type="button"
-						className="btn primary"
-						onClick={() => setGift((g) => ({ ...g, open: true }))}
-					>
-						<Icon name="sparkle" size={16} />
-						Gift subscription
-					</button>
+					{s.data?.complimentary.kind === 'available' && (
+						<button
+							type="button"
+							className="btn primary"
+							onClick={() => setComplimentaryGrant((g) => ({ ...g, open: true, result: null }))}
+						>
+							<Icon name="sparkle" size={16} />
+							Grant complimentary access
+						</button>
+					)}
 				</div>
 			</div>
 
@@ -252,7 +378,7 @@ export function SubscriptionsScreen() {
 						type="button"
 						className="btn sm"
 						style={{ marginLeft: 12 }}
-						onClick={() => void fetchData(filter, s.page)}
+						onClick={() => void fetchData(filter, s.page, complimentaryQuery, s.complimentaryPage)}
 					>
 						Retry
 					</button>
@@ -267,16 +393,25 @@ export function SubscriptionsScreen() {
 					onFilterChange={handleFilterChange}
 					page={s.page}
 					onPageChange={(p) => dispatch({ type: 'set-page', page: p })}
+					complimentaryNotice={complimentaryNotice}
+					complimentaryQuery={complimentaryQuery}
+					onComplimentaryQueryChange={(query) => {
+						setComplimentaryQuery(query)
+						dispatch({ type: 'set-complimentary-page', page: 1 })
+					}}
+					complimentaryPage={s.complimentaryPage}
+					onComplimentaryPageChange={(p) => dispatch({ type: 'set-complimentary-page', page: p })}
+					onComplimentaryRevoke={(row) => void handleComplimentaryRevoke(row)}
+					onComplimentaryRetry={(row) => void handleComplimentaryRetry(row)}
 				/>
 			)}
 
-			{/* Gift modal */}
-			{gift.open && (
-				<GiftModal
-					gift={gift}
-					onChange={(field, value) => setGift((g) => ({ ...g, [field]: value }))}
-					onSubmit={() => void handleGiftSubmit()}
-					onClose={() => setGift((g) => ({ ...g, open: false, result: null }))}
+			{complimentaryGrant.open && (
+				<ComplimentaryGrantModal
+					grant={complimentaryGrant}
+					onChange={(field, value) => setComplimentaryGrant((g) => ({ ...g, [field]: value }))}
+					onSubmit={() => void handleComplimentaryGrantSubmit()}
+					onClose={() => setComplimentaryGrant((g) => ({ ...g, open: false, result: null }))}
 				/>
 			)}
 		</div>
@@ -287,13 +422,20 @@ export function SubscriptionsScreen() {
 // SubscriptionsBody
 // ---------------------------------------------------------------------------
 
-function SubscriptionsBody({
+export function SubscriptionsBody({
 	data,
 	isPartial,
 	filter,
 	onFilterChange,
 	page,
 	onPageChange,
+	complimentaryNotice,
+	complimentaryQuery,
+	onComplimentaryQueryChange,
+	complimentaryPage,
+	onComplimentaryPageChange,
+	onComplimentaryRevoke,
+	onComplimentaryRetry,
 }: {
 	data: SubscriptionsData
 	isPartial: boolean
@@ -301,6 +443,13 @@ function SubscriptionsBody({
 	onFilterChange: (f: FilterOption) => void
 	page: number
 	onPageChange: (p: number) => void
+	complimentaryNotice: ResultCopy | null
+	complimentaryQuery: ComplimentaryQuery
+	onComplimentaryQueryChange: (query: ComplimentaryQuery) => void
+	complimentaryPage: number
+	onComplimentaryPageChange: (p: number) => void
+	onComplimentaryRevoke: (row: ComplimentaryEntitlementRow) => void
+	onComplimentaryRetry: (row: ComplimentaryEntitlementRow) => void
 }) {
 	// resolvePlanName: null impl echoes the id — the screen receives plan-mix from the
 	// provider and resolves names via the plan-mix data directly (the provider already
@@ -357,7 +506,18 @@ function SubscriptionsBody({
 				)}
 			</div>
 
-			{/* Admin-parity panels: Duplicate Accounts, Gift Orders, LemonSqueezy Sync */}
+			<ComplimentaryAccessPanel
+				state={data.complimentary}
+				notice={complimentaryNotice}
+				query={complimentaryQuery}
+				onQueryChange={onComplimentaryQueryChange}
+				page={complimentaryPage}
+				onPageChange={onComplimentaryPageChange}
+				onRevoke={onComplimentaryRevoke}
+				onRetry={onComplimentaryRetry}
+			/>
+
+			{/* Admin-parity panels: Duplicate Accounts, paid Gift Orders, LemonSqueezy Sync */}
 			<DuplicateAccountsPanel result={data.duplicates} />
 			<GiftOrdersPanel result={data.gifts} />
 			<LemonSqueezySyncPanel />
@@ -365,6 +525,372 @@ function SubscriptionsBody({
 	)
 }
 
+// ---------------------------------------------------------------------------
+// ComplimentaryAccessPanel — current + historical manual access grants
+// ---------------------------------------------------------------------------
+
+function ComplimentaryAccessPanel({
+	state,
+	notice,
+	query,
+	onQueryChange,
+	page,
+	onPageChange,
+	onRevoke,
+	onRetry,
+}: {
+	state: ComplimentaryPanelState
+	notice: ResultCopy | null
+	query: ComplimentaryQuery
+	onQueryChange: (query: ComplimentaryQuery) => void
+	page: number
+	onPageChange: (p: number) => void
+	onRevoke: (row: ComplimentaryEntitlementRow) => void
+	onRetry: (row: ComplimentaryEntitlementRow) => void
+}) {
+	if (state.kind === 'unavailable') {
+		return (
+			<ComplimentaryPanelShell>
+				<EmptyPanel icon="users" message="Complimentary access is unavailable for your role." />
+			</ComplimentaryPanelShell>
+		)
+	}
+
+	if (state.kind === 'error') {
+		return (
+			<ComplimentaryPanelShell>
+				<ResultNotice
+					result={{
+						tone: 'error',
+						message:
+							'Complimentary access data is temporarily unavailable. Paid subscription data remains available.',
+					}}
+				/>
+			</ComplimentaryPanelShell>
+		)
+	}
+
+	const result = state.result
+	const data = result.data
+	const rows = data?.rows ?? []
+
+	return (
+		<ComplimentaryPanelShell>
+			{notice && <ResultNotice result={notice} />}
+
+			<div
+				style={{
+					display: 'flex',
+					flexWrap: 'wrap',
+					gap: 8,
+					alignItems: 'center',
+					marginBottom: 14,
+				}}
+			>
+				<input
+					type="search"
+					className="input"
+					placeholder="Search recipient email"
+					aria-label="Search recipient email"
+					maxLength={254}
+					value={query.q}
+					onChange={(event) => onQueryChange({ ...query, q: event.currentTarget.value })}
+					style={{ maxWidth: 320 }}
+				/>
+				<select
+					className="input"
+					aria-label="Complimentary access status"
+					value={query.status}
+					onChange={(event) =>
+						onQueryChange({
+							...query,
+							status: event.currentTarget.value as ComplimentaryStatusFilter,
+						})
+					}
+					style={{ maxWidth: 150 }}
+				>
+					<option value="all">All</option>
+					<option value="active">Active</option>
+					<option value="revoked">Revoked</option>
+				</select>
+			</div>
+
+			{data && (
+				<div
+					style={{
+						display: 'flex',
+						flexWrap: 'wrap',
+						gap: '6px 18px',
+						marginBottom: 14,
+						fontSize: 13,
+						color: 'var(--ink-soft)',
+					}}
+				>
+					<span>
+						<strong className="tnum">{data.summary.active}</strong> active
+					</span>
+					<span>
+						<strong className="tnum">{data.summary.revoked}</strong> revoked
+					</span>
+					<span>
+						<strong className="tnum">{data.summary.failedEmail}</strong> failed email
+					</span>
+					<span>
+						<strong className="tnum">{data.summary.unknownEmail}</strong> unknown email
+					</span>
+					<span>
+						<strong className="tnum">{data.summary.notAttempted}</strong> not attempted
+					</span>
+				</div>
+			)}
+
+			{result.status === 'partial' && (
+				<div className="kicker" style={{ color: 'var(--amber)', marginBottom: 12 }}>
+					Partial data
+				</div>
+			)}
+
+			{result.status === 'empty' || rows.length === 0 ? (
+				<EmptyPanel
+					icon="users"
+					message={
+						result.status === 'empty'
+							? 'Complimentary access appears once the provider is configured.'
+							: 'No complimentary access records found.'
+					}
+				/>
+			) : (
+				<>
+					<div style={{ overflowX: 'auto' }}>
+						<table className="tbl" style={{ minWidth: 980 }}>
+							<thead>
+								<tr>
+									<th>Recipient</th>
+									<th>Access</th>
+									<th>Granted</th>
+									<th>Grant reason</th>
+									<th>Revocation</th>
+									<th>Email</th>
+									<th>Actions</th>
+								</tr>
+							</thead>
+							<tbody>
+								{rows.map((row) => {
+									const actions = complimentaryRowActions(row)
+									return (
+										<tr key={row.id}>
+											<td>
+												<div style={{ fontSize: 13, fontWeight: 600, color: 'var(--ink)' }}>
+													{row.email}
+												</div>
+											</td>
+											<td>
+												<AccessStatusBadge revokedAt={row.revokedAt} />
+											</td>
+											<td>
+												<div className="tnum" style={{ fontSize: 12.5, color: 'var(--ink)' }}>
+													{formatTimestamp(row.grantedAt)}
+												</div>
+											</td>
+											<td style={{ fontSize: 12.5, color: 'var(--ink-muted)' }}>
+												{row.grantReason}
+											</td>
+											<td style={{ fontSize: 12.5, color: 'var(--ink-muted)' }}>
+												{row.revokedAt === null ? (
+													'—'
+												) : (
+													<>
+														<div>{formatTimestamp(row.revokedAt)}</div>
+														<div>{row.revokeReason}</div>
+													</>
+												)}
+											</td>
+											<td>
+												<EmailStatusBadge row={row} />
+											</td>
+											<td>
+												<div style={{ display: 'flex', gap: 8 }}>
+													<button
+														type="button"
+														className="btn sm"
+														disabled={!actions.canRevoke}
+														onClick={() => onRevoke(row)}
+														style={{ opacity: actions.canRevoke ? 1 : 0.45 }}
+													>
+														Revoke
+													</button>
+													<button
+														type="button"
+														className="btn sm"
+														disabled={!actions.canRetryEmail}
+														onClick={() => onRetry(row)}
+														title={actions.retryLabel}
+														style={{ opacity: actions.canRetryEmail ? 1 : 0.45 }}
+													>
+														{actions.retryLabel === 'Retry email' ? 'Retry' : 'Retry later'}
+													</button>
+												</div>
+											</td>
+										</tr>
+									)
+								})}
+							</tbody>
+						</table>
+					</div>
+					{data && (
+						<div
+							style={{
+								display: 'flex',
+								justifyContent: 'flex-end',
+								alignItems: 'center',
+								gap: 10,
+								paddingTop: 14,
+							}}
+						>
+							<button
+								type="button"
+								className="btn sm"
+								disabled={page <= 1}
+								onClick={() => onPageChange(page - 1)}
+								style={{ opacity: page <= 1 ? 0.4 : 1 }}
+							>
+								<Icon name="chevLeft" size={14} />
+								Prev
+							</button>
+							<span className="kicker">{complimentaryPageLabel(data)}</span>
+							<button
+								type="button"
+								className="btn sm"
+								disabled={data.totalPages <= page}
+								onClick={() => onPageChange(page + 1)}
+								style={{ opacity: data.totalPages <= page ? 0.4 : 1 }}
+							>
+								Next
+								<Icon name="chevRight" size={14} />
+							</button>
+						</div>
+					)}
+				</>
+			)}
+		</ComplimentaryPanelShell>
+	)
+}
+
+function ComplimentaryPanelShell({ children }: { children: React.ReactNode }) {
+	return (
+		<div className="panel panel-pad" style={{ marginBottom: 'var(--gap)' }}>
+			<div className="card-title">Complimentary access</div>
+			<div className="page-sub" style={{ margin: '4px 0 0' }}>
+				Manual access grants, revocations, and delivery history.
+			</div>
+			<hr className="masthead-rule" style={{ margin: '12px 0 16px' }} />
+			{children}
+		</div>
+	)
+}
+
+function AccessStatusBadge({ revokedAt }: { revokedAt: number | null }) {
+	const active = revokedAt === null
+	return (
+		<span className={`pill ${active ? 'published' : 'draft'}`}>
+			<span className="pdot" />
+			{active ? 'Active' : 'Revoked'}
+		</span>
+	)
+}
+
+function EmailStatusBadge({ row }: { row: ComplimentaryEntitlementRow }) {
+	const status = row.emailStatus
+	const cls =
+		status === 'sent'
+			? 'published'
+			: status === 'failed' || status === 'unknown'
+				? 'review'
+				: 'draft'
+	return (
+		<div>
+			<span className={`pill ${cls}`}>
+				<span className="pdot" />
+				{status.replace('_', ' ')}
+			</span>
+			<div style={{ marginTop: 4, fontSize: 12, color: 'var(--ink-muted)' }}>
+				{row.emailAttemptCount} attempts
+			</div>
+		</div>
+	)
+}
+
+function ResultNotice({ result }: { result: ResultCopy }) {
+	const color =
+		result.tone === 'success'
+			? 'var(--green)'
+			: result.tone === 'warning'
+				? 'var(--amber)'
+				: result.tone === 'info'
+					? 'var(--accent)'
+					: 'var(--red)'
+	return (
+		<div
+			style={{
+				fontSize: 12.5,
+				color,
+				padding: '7px 10px',
+				background: `color-mix(in srgb, ${color} 8%, transparent)`,
+				borderRadius: 'var(--radius-sm)',
+				marginBottom: 14,
+			}}
+		>
+			{result.message}
+		</div>
+	)
+}
+
+async function readErrorMessage(res: Response): Promise<string> {
+	let nextEligibleAt: number | null = null
+	try {
+		const body = (await res.json()) as { error?: unknown; code?: unknown; nextEligibleAt?: unknown }
+		nextEligibleAt = typeof body.nextEligibleAt === 'number' ? body.nextEligibleAt : null
+	} catch {
+		// The status code is still enough to return bounded public copy.
+	}
+	const base =
+		res.status === 400
+			? 'The request could not be processed.'
+			: res.status === 401 || res.status === 403
+				? 'You do not have permission to manage complimentary access.'
+				: res.status === 409
+					? 'The request conflicts with the current complimentary access state.'
+					: res.status === 429
+						? 'Please wait before retrying the email.'
+						: res.status >= 500
+							? 'The complimentary access service is temporarily unavailable.'
+							: 'The request failed. Please try again.'
+	if (nextEligibleAt !== null) {
+		const formatted = formatTimestamp(nextEligibleAt)
+		return formatted === 'Date unavailable' ? base : `${base} Try again after ${formatted}.`
+	}
+	return base
+}
+
+async function fetchComplimentaryPanel(
+	query: ComplimentaryQuery,
+	page: number,
+): Promise<ComplimentaryPanelState> {
+	try {
+		const response = await fetch(buildComplimentaryListUrl(query, page))
+		if (response.status === 401 || response.status === 403) {
+			return { kind: 'unavailable', reason: 'forbidden' }
+		}
+		if (!response.ok) return { kind: 'error', reason: 'request_failed' }
+		return {
+			kind: 'available',
+			result: (await response.json()) as ProviderResult<ComplimentaryAccessPage>,
+		}
+	} catch {
+		return { kind: 'error', reason: 'request_failed' }
+	}
+}
+
 // ---------------------------------------------------------------------------
 // DuplicateAccountsPanel — billing-email + canonical-email conflict groups
 // ---------------------------------------------------------------------------
@@ -594,8 +1120,12 @@ function LemonSqueezySyncPanel() {
 			}
 			const body = (await res.json()) as ProviderResult<LsImportSummary>
 			setS({ running: false, summary: body.data, error: null })
-		} catch (err) {
-			setS({ running: false, summary: null, error: String(err) })
+		} catch {
+			setS({
+				running: false,
+				summary: null,
+				error: 'LemonSqueezy sync could not be completed. Please try again.',
+			})
 		}
 	}, [])
 
@@ -1057,28 +1587,27 @@ function FilterSegment({
 }
 
 // ---------------------------------------------------------------------------
-// GiftModal — .scrim + .panel.panel-pad dialog
+// ComplimentaryGrantModal — .scrim + .panel.panel-pad dialog
 // ---------------------------------------------------------------------------
 
-function GiftModal({
-	gift,
+function ComplimentaryGrantModal({
+	grant,
 	onChange,
 	onSubmit,
 	onClose,
 }: {
-	gift: GiftState
-	onChange: (field: 'email' | 'planVariantId', value: string) => void
+	grant: ComplimentaryGrantState
+	onChange: (field: 'email' | 'reason', value: string) => void
 	onSubmit: () => void
 	onClose: () => void
 }) {
-	const ok = gift.result?.startsWith('Gift created')
 	return (
 		<div
 			className="scrim"
 			style={{ placeItems: 'center', zIndex: 100 }}
 			role="dialog"
 			aria-modal="true"
-			aria-label="Gift subscription"
+			aria-label="Grant complimentary access"
 			onClick={onClose}
 			onKeyUp={(e) => {
 				if (e.key === 'Escape') onClose()
@@ -1088,12 +1617,12 @@ function GiftModal({
 			<div
 				className="panel panel-pad fade-only"
 				role="document"
-				style={{ width: 420, boxShadow: 'var(--shadow-lg)' }}
+				style={{ width: 460, boxShadow: 'var(--shadow-lg)' }}
 				onClick={(e) => e.stopPropagation()}
 			>
 				<div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 4 }}>
 					<Icon name="sparkle" size={18} style={{ color: 'var(--accent)' }} />
-					<div className="card-title">Gift subscription</div>
+					<div className="card-title">Grant complimentary access</div>
 					<button
 						type="button"
 						className="icon-btn"
@@ -1110,39 +1639,25 @@ function GiftModal({
 					<input
 						className="input"
 						type="email"
-						value={gift.email}
+						value={grant.email}
 						onChange={(e) => onChange('email', e.target.value)}
-						placeholder="subscriber@example.com"
+						placeholder="recipient@example.com"
 					/>
 				</label>
 
 				<label style={{ display: 'block', marginBottom: 16 }}>
-					<span className="field-label">Plan variant ID</span>
-					<input
+					<span className="field-label">Grant reason</span>
+					<textarea
 						className="input"
-						type="text"
-						value={gift.planVariantId}
-						onChange={(e) => onChange('planVariantId', e.target.value)}
-						placeholder="e.g. variant_123"
+						value={grant.reason}
+						onChange={(e) => onChange('reason', e.target.value)}
+						placeholder="Required audit reason"
+						rows={4}
+						style={{ resize: 'vertical' }}
 					/>
 				</label>
 
-				{gift.result && (
-					<div
-						style={{
-							fontSize: 12,
-							color: ok ? 'var(--green)' : 'var(--red)',
-							padding: '6px 10px',
-							background: ok
-								? 'color-mix(in srgb, var(--green) 8%, transparent)'
-								: 'color-mix(in srgb, var(--red) 8%, transparent)',
-							borderRadius: 'var(--radius-sm)',
-							marginBottom: 16,
-						}}
-					>
-						{gift.result}
-					</div>
-				)}
+				{grant.result && <ResultNotice result={grant.result} />}
 
 				<div style={{ display: 'flex', justifyContent: 'flex-end', gap: 10 }}>
 					<button type="button" className="btn" onClick={onClose}>
@@ -1152,12 +1667,12 @@ function GiftModal({
 						type="button"
 						className="btn primary"
 						onClick={onSubmit}
-						disabled={gift.submitting || !gift.email || !gift.planVariantId}
+						disabled={complimentaryGrantSubmitDisabled(grant, grant.submitting)}
 						style={{
-							opacity: gift.submitting || !gift.email || !gift.planVariantId ? 0.5 : 1,
+							opacity: complimentaryGrantSubmitDisabled(grant, grant.submitting) ? 0.5 : 1,
 						}}
 					>
-						{gift.submitting ? 'Gifting…' : 'Send gift'}
+						{grant.submitting ? 'Granting…' : 'Grant access'}
 					</button>
 				</div>
 			</div>