@growth-labs/cms 0.5.2 → 0.5.3

package/src/routes/subscriptions.ts

@@ -1,6 +1,6 @@
 // src/routes/subscriptions.ts — Subscriptions route factory (P5 Task 6 + admin parity).
 // All handlers are SubscriptionsProvider passthrough: member list+filters,
-// KPI cards, plan-mix, CSV/JSON export, gift subscription, plus the three
+// KPI cards, plan-mix, CSV/JSON export, complimentary access admin, plus the three
 // admin-parity tools the legacy Fronts /admin had — duplicate-account detection,
 // gift-order tracking, and the LemonSqueezy entitlement sync (a privileged WRITE).
 // Each handler returns the ProviderResult {status, data} envelope unchanged —
@@ -13,9 +13,23 @@
 // NOT editor), falling back to requirePublisher when the role seam is absent.
 // importLsEntitlements is a privileged WRITE → requireRole('manage_settings')
 // (owner-only), falling back to requireAdmin when the role seam is absent.
+// complimentary access list/grant/revoke/retry → requireRole('manage_complimentary_access')
+// (owner + senior_editor + editor). Mutations derive the actor from authz.getUser;
+// actor-like fields in the browser body are rejected.
 
+import { z } from 'zod'
 import { nullProviders } from '../providers/null.js'
-import type { CmsProviders } from '../providers/types.js'
+import {
+	type CmsProviders,
+	type ComplimentaryAccessPage,
+	type ComplimentaryAccessQuery,
+	type ComplimentaryEmailRetryResult,
+	type ComplimentaryGrantResult,
+	type ComplimentaryRevokeResult,
+	MAX_COMPLIMENTARY_UNIX_SECONDS,
+	ProviderHttpError,
+	type ProviderResult,
+} from '../providers/types.js'
 import type { Authz, Capability, RouteContext } from './context.js'
 import { json } from './context.js'
 
@@ -29,15 +43,173 @@ export interface SubscriptionsRouteHandlers {
 	kpis(ctx: RouteContext): Promise<Response>
 	planMix(ctx: RouteContext): Promise<Response>
 	exportMembers(ctx: RouteContext): Promise<Response>
-	gift(ctx: RouteContext): Promise<Response>
 	/** READ — duplicate-account conflict groups (billing + canonical email). */
 	detectDuplicates(ctx: RouteContext): Promise<Response>
 	/** READ — paginated gift-order claim/delivery tracking. */
 	listGifts(ctx: RouteContext): Promise<Response>
+	/** READ — paginated current + historical complimentary access audit. */
+	listComplimentaryAccess(ctx: RouteContext): Promise<Response>
+	/** WRITE — grant complimentary access. */
+	grantComplimentaryAccess(ctx: RouteContext): Promise<Response>
+	/** WRITE — revoke complimentary access. */
+	revokeComplimentaryAccess(ctx: RouteContext): Promise<Response>
+	/** WRITE — retry the stored recipient's delivery email. */
+	retryComplimentaryAccessEmail(ctx: RouteContext): Promise<Response>
 	/** WRITE (privileged) — trigger the LemonSqueezy entitlement sync. */
 	importLsEntitlements(ctx: RouteContext): Promise<Response>
 }
 
+const providerStatusSchema = z.enum(['live', 'partial', 'empty'])
+const deliveryStatusSchema = z.enum(['pending', 'sending', 'sent', 'failed', 'unknown'])
+const emailStatusSchema = z.union([deliveryStatusSchema, z.literal('not_attempted')])
+const statusFilterSchema = z.enum(['active', 'revoked', 'all'])
+const unixSecondsSchema = z.number().int().nonnegative().max(MAX_COMPLIMENTARY_UNIX_SECONDS)
+
+const entitlementRowSchema = z
+	.object({
+		id: z.string().uuid(),
+		userId: z.string().min(1),
+		email: z.string().email(),
+		grantReason: z.string().min(1),
+		grantedAt: unixSecondsSchema,
+		grantedBySubject: z.string().min(1),
+		revokedAt: unixSecondsSchema.nullable(),
+		revokedBySubject: z.string().min(1).nullable(),
+		revokeReason: z.string().min(1).nullable(),
+		emailStatus: emailStatusSchema,
+		emailAttemptCount: z.number().int().nonnegative(),
+		emailRetryable: z.boolean(),
+		emailNextEligibleAt: unixSecondsSchema.nullable(),
+	})
+	.strict()
+
+const complimentaryPageSchema: z.ZodType<ComplimentaryAccessPage> = z
+	.object({
+		rows: z.array(entitlementRowSchema),
+		total: z.number().int().nonnegative(),
+		page: z.number().int().positive(),
+		pageSize: z.number().int().min(1).max(100),
+		totalPages: z.number().int().nonnegative(),
+		summary: z
+			.object({
+				active: z.number().int().nonnegative(),
+				revoked: z.number().int().nonnegative(),
+				failedEmail: z.number().int().nonnegative(),
+				unknownEmail: z.number().int().nonnegative(),
+				notAttempted: z.number().int().nonnegative(),
+			})
+			.strict(),
+	})
+	.strict()
+
+const emailResultSchema = z
+	.object({
+		status: emailStatusSchema,
+		retryable: z.boolean(),
+		nextEligibleAt: unixSecondsSchema.nullable(),
+	})
+	.strict()
+
+const complimentaryGrantResultSchema: z.ZodType<ComplimentaryGrantResult> = z
+	.object({
+		outcome: z.enum(['created', 'already_active']),
+		entitlement: entitlementRowSchema,
+		email: emailResultSchema,
+	})
+	.strict()
+
+const complimentaryRevokeResultSchema: z.ZodType<ComplimentaryRevokeResult> = z
+	.object({
+		outcome: z.enum(['revoked', 'already_revoked']),
+		entitlement: entitlementRowSchema,
+	})
+	.strict()
+
+const complimentaryRetryResultSchema: z.ZodType<ComplimentaryEmailRetryResult> = z
+	.object({
+		outcome: z.enum(['queued', 'sent', 'failed', 'unknown', 'throttled', 'conflict']),
+		entitlement: entitlementRowSchema,
+		email: emailResultSchema,
+	})
+	.strict()
+
+const emailInputSchema = z.string().trim().toLowerCase().email().max(254)
+const reasonSchema = z.string().trim().min(1).max(500)
+const complimentaryQuerySchema = z.string().trim().max(254)
+const entitlementIdSchema = z.string().trim().uuid()
+
+const grantSchema = z
+	.object({
+		email: emailInputSchema,
+		reason: reasonSchema,
+	})
+	.strict()
+
+const entitlementActionSchema = z
+	.object({
+		entitlementId: entitlementIdSchema,
+		reason: reasonSchema,
+	})
+	.strict()
+
+function providerResultSchema<T>(data: z.ZodType<T>): z.ZodType<ProviderResult<T>> {
+	return z.object({ status: providerStatusSchema, data }).strict() as z.ZodType<ProviderResult<T>>
+}
+
+function parsePositiveInteger(value: string | null, fallback: number): number {
+	if (value === null) return fallback
+	const parsed = Number(value)
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback
+}
+
+type StrictJsonResult<T> = { ok: true; data: T } | { ok: false; response: Response }
+
+async function readStrictJson<T>(
+	ctx: RouteContext,
+	schema: z.ZodType<T>,
+): Promise<StrictJsonResult<T>> {
+	let body: unknown
+	try {
+		body = await ctx.request.json()
+	} catch {
+		return { ok: false, response: json({ error: 'Invalid JSON body' }, 400) }
+	}
+	const parsed = schema.safeParse(body)
+	if (!parsed.success) return { ok: false, response: json({ error: 'Invalid request body' }, 400) }
+	return { ok: true, data: parsed.data }
+}
+
+async function requireComplimentaryAccess(
+	config: SubscriptionsRouteConfig,
+	ctx: RouteContext,
+): Promise<Response | null> {
+	if (!config.authz.requireRole) {
+		return json({ error: 'Role authorization is required' }, 500)
+	}
+	return config.authz.requireRole('manage_complimentary_access' satisfies Capability, ctx)
+}
+
+async function trustedActor(config: SubscriptionsRouteConfig, ctx: RouteContext) {
+	const user = config.authz.getUser ? await config.authz.getUser(ctx) : null
+	if (!user?.subject) return null
+	return { subject: user.subject }
+}
+
+async function providerJson<T>(
+	call: () => Promise<ProviderResult<T>>,
+	schema: z.ZodType<ProviderResult<T>>,
+): Promise<Response> {
+	try {
+		const result = await call()
+		const parsed = schema.safeParse(result)
+		if (!parsed.success) return json({ error: 'Invalid provider response' }, 502)
+		return json(parsed.data)
+	} catch (err) {
+		if (err instanceof ProviderHttpError) return json(err.toBody(), err.status)
+		throw err
+	}
+}
+
 export function createSubscriptionsRoutes(
 	config: SubscriptionsRouteConfig,
 ): SubscriptionsRouteHandlers {
@@ -93,30 +265,6 @@ export function createSubscriptionsRoutes(
 			return json(await providers.subscriptions.exportMembers(fmt))
 		},
 
-		async gift(ctx: RouteContext): Promise<Response> {
-			const denied = await config.authz.requirePublisher(ctx)
-			if (denied) return denied
-
-			let body: unknown
-			try {
-				body = await ctx.request.json()
-			} catch {
-				return json({ error: 'Invalid JSON body' }, 400)
-			}
-
-			const { email, planVariantId } =
-				typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
-
-			if (typeof email !== 'string' || !email) {
-				return json({ error: 'email is required' }, 400)
-			}
-			if (typeof planVariantId !== 'string' || !planVariantId) {
-				return json({ error: 'planVariantId is required' }, 400)
-			}
-
-			return json(await providers.subscriptions.createGift({ email, planVariantId }))
-		},
-
 		// READ — duplicate-account detection. Same publisher gate as the other
 		// read surfaces; the ProviderResult (conflict groups + summary) passes
 		// straight through, empty states preserved.
@@ -143,6 +291,80 @@ export function createSubscriptionsRoutes(
 			return json(await providers.subscriptions.listGifts({ q, status, page, pageSize }))
 		},
 
+		async listComplimentaryAccess(ctx: RouteContext): Promise<Response> {
+			const denied = await requireComplimentaryAccess(config, ctx)
+			if (denied) return denied
+
+			const u = new URL(ctx.request.url)
+			const qParsed = complimentaryQuerySchema.safeParse(u.searchParams.get('q') ?? '')
+			if (!qParsed.success) return json({ error: 'Invalid search query' }, 400)
+			const q = qParsed.data || undefined
+			const rawStatus = u.searchParams.get('status') ?? 'all'
+			const statusParsed = statusFilterSchema.safeParse(rawStatus)
+			if (!statusParsed.success) return json({ error: 'Invalid status filter' }, 400)
+			const page = parsePositiveInteger(u.searchParams.get('page'), 1)
+			const pageSize = Math.min(parsePositiveInteger(u.searchParams.get('pageSize'), 25), 100)
+			const query: ComplimentaryAccessQuery = {
+				q,
+				status: statusParsed.data,
+				page,
+				pageSize,
+			}
+
+			return providerJson(
+				() => providers.subscriptions.listComplimentaryAccess(query),
+				providerResultSchema(complimentaryPageSchema),
+			)
+		},
+
+		async grantComplimentaryAccess(ctx: RouteContext): Promise<Response> {
+			const denied = await requireComplimentaryAccess(config, ctx)
+			if (denied) return denied
+
+			const actor = await trustedActor(config, ctx)
+			if (!actor) return json({ error: 'Trusted actor context is required' }, 500)
+
+			const parsed = await readStrictJson(ctx, grantSchema)
+			if (!parsed.ok) return parsed.response
+
+			return providerJson(
+				() => providers.subscriptions.grantComplimentaryAccess(parsed.data, actor),
+				providerResultSchema(complimentaryGrantResultSchema),
+			)
+		},
+
+		async revokeComplimentaryAccess(ctx: RouteContext): Promise<Response> {
+			const denied = await requireComplimentaryAccess(config, ctx)
+			if (denied) return denied
+
+			const actor = await trustedActor(config, ctx)
+			if (!actor) return json({ error: 'Trusted actor context is required' }, 500)
+
+			const parsed = await readStrictJson(ctx, entitlementActionSchema)
+			if (!parsed.ok) return parsed.response
+
+			return providerJson(
+				() => providers.subscriptions.revokeComplimentaryAccess(parsed.data, actor),
+				providerResultSchema(complimentaryRevokeResultSchema),
+			)
+		},
+
+		async retryComplimentaryAccessEmail(ctx: RouteContext): Promise<Response> {
+			const denied = await requireComplimentaryAccess(config, ctx)
+			if (denied) return denied
+
+			const actor = await trustedActor(config, ctx)
+			if (!actor) return json({ error: 'Trusted actor context is required' }, 500)
+
+			const parsed = await readStrictJson(ctx, entitlementActionSchema)
+			if (!parsed.ok) return parsed.response
+
+			return providerJson(
+				() => providers.subscriptions.retryComplimentaryAccessEmail(parsed.data, actor),
+				providerResultSchema(complimentaryRetryResultSchema),
+			)
+		},
+
 		// WRITE (privileged) — trigger the LemonSqueezy entitlement sync. This
 		// mutates host state (creates/updates users + subscriptions), so it gates
 		// on requireRole('manage_settings') (owner-only per the capability matrix)

package/src/ui/api/subscriptions.ts

@@ -1,7 +1,7 @@
 // src/ui/api/subscriptions.ts — Astro endpoint adapter for /admin/api/subscriptions.
-// GET dispatches to members / kpis / planMix / exportMembers / duplicates / gifts
-// based on ?type=. POST routes to gift (default) or the LemonSqueezy import sync
-// (?type=import-ls) — a privileged WRITE gated on requireRole('manage_settings').
+// GET dispatches to members / kpis / planMix / exportMembers / duplicates / gifts /
+// complimentary based on ?type=. POST routes LemonSqueezy import sync
+// (?type=import-ls) or complimentary grant/revoke/retry actions.
 // Providers (SubscriptionsProvider) are read from c.locals.cmsProviders — the host
 // injects real impls at cutover (P8); null impl (empty states) is the default.
 
@@ -42,6 +42,8 @@ export const GET = (c: APIContext) => {
 			return routes.detectDuplicates(ctx)
 		case 'gifts':
 			return routes.listGifts(ctx)
+		case 'complimentary':
+			return routes.listComplimentaryAccess(ctx)
 		default:
 			return routes.members(ctx)
 	}
@@ -50,7 +52,27 @@ export const GET = (c: APIContext) => {
 export const POST = (c: APIContext) => {
 	const routes = createSubscriptionsRoutes(subscriptionsConfig(c))
 	const ctx = toCtx(c)
-	const type = new URL(c.request.url).searchParams.get('type')
+	const url = new URL(c.request.url)
+	const type = url.searchParams.get('type')
 	if (type === 'import-ls') return routes.importLsEntitlements(ctx)
-	return routes.gift(ctx)
+	if (type === 'complimentary') {
+		const action = url.searchParams.get('action')
+		switch (action) {
+			case 'grant':
+				return routes.grantComplimentaryAccess(ctx)
+			case 'revoke':
+				return routes.revokeComplimentaryAccess(ctx)
+			case 'retry-email':
+				return routes.retryComplimentaryAccessEmail(ctx)
+			default:
+				return new Response(JSON.stringify({ error: 'Invalid complimentary action' }), {
+					status: 400,
+					headers: { 'Content-Type': 'application/json' },
+				})
+		}
+	}
+	return new Response(JSON.stringify({ error: 'Invalid subscription action' }), {
+		status: 400,
+		headers: { 'Content-Type': 'application/json' },
+	})
 }