@growth-labs/cms 0.1.0

package/src/routes/shell.ts

@@ -0,0 +1,163 @@
+// src/routes/shell.ts — the /admin/api/* shell route factories. Built on the
+// same RouteContext/Authz/providers contracts as the content routes. The
+// integration's Astro endpoints adapt their APIContext onto a RouteContext and
+// call these.
+import type { D1Database } from '../engine/d1.js'
+import { nullProviders } from '../providers/null.js'
+import type { CmsProviders } from '../providers/types.js'
+import type { Authz, Capability, CmsUser, RouteContext } from './context.js'
+import { json } from './context.js'
+
+export interface ShellWorkspaceDescriptor {
+	id: string
+	name: string
+	meta: string
+	color: string
+}
+
+export interface ShellRouteConfig {
+	authz: Authz
+	workspaces: ShellWorkspaceDescriptor[]
+	activeWorkspaceId: string
+	providers?: Partial<CmsProviders>
+}
+
+export interface ShellRouteHandlers {
+	me(ctx: RouteContext): Promise<Response>
+	search(ctx: RouteContext): Promise<Response>
+	notifications(ctx: RouteContext): Promise<Response>
+	workspaceSettings(ctx: RouteContext): Promise<Response>
+}
+
+const SETTINGS_DEFAULTS = {
+	publication_name: null as string | null,
+	tagline: null as string | null,
+	language: 'en',
+	timezone: 'Europe/Paris',
+	require_review: 0,
+	auto_seo: 1,
+	scheduled_publish: 1,
+	premium_default: 0,
+	accent_color: 'Ink blue',
+	display_typeface: 'serif',
+}
+const SETTINGS_PATCHABLE = Object.keys(SETTINGS_DEFAULTS) as Array<keyof typeof SETTINGS_DEFAULTS>
+
+async function loadMembershipRole(
+	db: D1Database,
+	workspaceId: string,
+	subject: string,
+): Promise<string | null> {
+	const row = await db
+		.prepare('SELECT role FROM workspace_memberships WHERE workspace_id = ? AND user_id = ?')
+		.bind(workspaceId, subject)
+		.first<{ role: string }>()
+	return row?.role ?? null
+}
+
+export function createShellRoutes(config: ShellRouteConfig): ShellRouteHandlers {
+	const providers: CmsProviders = { ...nullProviders, ...(config.providers ?? {}) }
+
+	async function resolveUser(ctx: RouteContext): Promise<CmsUser | null> {
+		if (!config.authz.getUser) return null
+		return await config.authz.getUser(ctx)
+	}
+
+	return {
+		async me(ctx: RouteContext): Promise<Response> {
+			const user = await resolveUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			const workspace = config.workspaces.find((w) => w.id === config.activeWorkspaceId) ?? null
+			const membershipRole = await loadMembershipRole(
+				ctx.db,
+				config.activeWorkspaceId,
+				user.subject,
+			)
+			return json({ user, workspace, workspaces: config.workspaces, membershipRole })
+		},
+
+		async search(ctx: RouteContext): Promise<Response> {
+			const user = await resolveUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			const q = new URL(ctx.request.url).searchParams.get('q')?.trim() ?? ''
+			if (!q) return json({ status: 'empty', data: [] })
+			try {
+				const result = await providers.search.query(q)
+				if (result.status !== 'empty' && result.data.length > 0) return json(result)
+			} catch {
+				// provider unavailable — fall through to D1.
+			}
+			const like = `%${q.replace(/[%_]/g, (m) => `\\${m}`)}%`
+			const rows = await ctx.db
+				.prepare(
+					"SELECT id, title, type FROM content_items WHERE deleted_at IS NULL AND (title LIKE ?1 ESCAPE '\\' OR slug LIKE ?1 ESCAPE '\\') ORDER BY updated_at DESC LIMIT 10",
+				)
+				.bind(like)
+				.all<{ id: string; title: string; type: string }>()
+			return json({ status: 'partial', data: rows.results ?? [] })
+		},
+
+		async notifications(ctx: RouteContext): Promise<Response> {
+			const user = await resolveUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			if (ctx.request.method === 'POST') {
+				const body = (await ctx.request.json().catch(() => ({}))) as { ids?: unknown }
+				const ids = Array.isArray(body.ids)
+					? body.ids.filter((x): x is string => typeof x === 'string')
+					: []
+				if (ids.length === 0) return json({ updated: 0 })
+				const placeholders = ids.map(() => '?').join(',')
+				await ctx.db
+					.prepare(
+						`UPDATE cms_notifications SET read_at = unixepoch() WHERE workspace_id = ? AND user_id = ? AND read_at IS NULL AND id IN (${placeholders})`,
+					)
+					.bind(config.activeWorkspaceId, user.subject, ...ids)
+					.run()
+				return json({ updated: ids.length })
+			}
+			const rows = await ctx.db
+				.prepare(
+					'SELECT id, kind, body, read_at, created_at FROM cms_notifications WHERE workspace_id = ? AND user_id = ? ORDER BY (read_at IS NOT NULL), created_at DESC LIMIT 50',
+				)
+				.bind(config.activeWorkspaceId, user.subject)
+				.all()
+			return json({ data: rows.results ?? [] })
+		},
+
+		async workspaceSettings(ctx: RouteContext): Promise<Response> {
+			const user = await resolveUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			const wsId = config.activeWorkspaceId
+			if (ctx.request.method === 'PATCH') {
+				const gate = config.authz.requireRole
+					? await config.authz.requireRole('manage_settings' satisfies Capability, ctx)
+					: user.role === 'owner'
+						? null
+						: new Response('forbidden', { status: 403 })
+				if (gate) return gate
+				const body = (await ctx.request.json().catch(() => ({}))) as Record<string, unknown>
+				const updates = SETTINGS_PATCHABLE.filter((k) => k in body)
+				await ctx.db
+					.prepare(
+						'INSERT INTO workspace_settings (workspace_id) VALUES (?) ON CONFLICT(workspace_id) DO NOTHING',
+					)
+					.bind(wsId)
+					.run()
+				if (updates.length > 0) {
+					const setClause = updates.map((k) => `${k} = ?`).join(', ')
+					await ctx.db
+						.prepare(`UPDATE workspace_settings SET ${setClause} WHERE workspace_id = ?`)
+						.bind(...updates.map((k) => body[k] as string | number | null), wsId)
+						.run()
+				}
+				return json({ ok: true })
+			}
+			const row = await ctx.db
+				.prepare('SELECT * FROM workspace_settings WHERE workspace_id = ?')
+				.bind(wsId)
+				.first<Record<string, unknown>>()
+			if (!row) return json({ status: 'empty', data: { ...SETTINGS_DEFAULTS } })
+			return json({ status: 'live', data: { ...SETTINGS_DEFAULTS, ...row } })
+		},
+	}
+}

package/src/routes/subscriptions.ts

@@ -0,0 +1,167 @@
+// 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
+// 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 —
+// null KPI values (LTV/MRR/churn) are preserved, never zeroed.
+// No D1 subscription/member query; the provider owns those semantics.
+//
+// Authz: the read surfaces (members/kpis/planMix/gifts/duplicates) gate on
+// requirePublisher (any workspace member). exportMembers exposes subscriber PII
+// (member emails) → requireRole('export_subscribers') (owner + senior_editor,
+// 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.
+
+import { nullProviders } from '../providers/null.js'
+import type { CmsProviders } from '../providers/types.js'
+import type { Authz, Capability, RouteContext } from './context.js'
+import { json } from './context.js'
+
+export interface SubscriptionsRouteConfig {
+	authz: Authz
+	providers?: Partial<CmsProviders>
+}
+
+export interface SubscriptionsRouteHandlers {
+	members(ctx: RouteContext): Promise<Response>
+	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>
+	/** WRITE (privileged) — trigger the LemonSqueezy entitlement sync. */
+	importLsEntitlements(ctx: RouteContext): Promise<Response>
+}
+
+export function createSubscriptionsRoutes(
+	config: SubscriptionsRouteConfig,
+): SubscriptionsRouteHandlers {
+	const providers: CmsProviders = { ...nullProviders, ...(config.providers ?? {}) }
+
+	return {
+		async members(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const u = new URL(ctx.request.url)
+			// Forward all query params as the filter map (filter=paid, status=active, etc.)
+			const filter: Record<string, string | undefined> = {}
+			for (const [key, value] of u.searchParams.entries()) {
+				if (key !== 'page') filter[key] = value
+			}
+			const page = Number(u.searchParams.get('page') ?? '1') || 1
+
+			return json(await providers.subscriptions.listMembers(filter, page))
+		},
+
+		async kpis(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			// ProviderResult<Record<string, number | null>> passes straight through —
+			// null values (LTV/MRR/churn) are preserved for the screen to render honestly.
+			return json(await providers.subscriptions.getKpis())
+		},
+
+		async planMix(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			return json(await providers.subscriptions.getPlanMix())
+		},
+
+		async exportMembers(ctx: RouteContext): Promise<Response> {
+			// Subscriber-PII export → owner + senior_editor only (NOT editor) via
+			// requireRole('export_subscribers'); falls back to requirePublisher when
+			// the host has not wired the role seam (backwards compatible).
+			const denied = config.authz.requireRole
+				? await config.authz.requireRole('export_subscribers' satisfies Capability, ctx)
+				: await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const u = new URL(ctx.request.url)
+			const rawFmt = u.searchParams.get('fmt')
+			const fmt: 'csv' | 'json' = rawFmt === 'json' ? 'json' : 'csv'
+
+			// Return the ProviderResult envelope so the client can branch on status.
+			// The screen may choose to trigger a file download for the data string.
+			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.
+		async detectDuplicates(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			return json(await providers.subscriptions.detectDuplicates())
+		},
+
+		// READ — gift-order list. Forwards q/status/page/pageSize to the provider.
+		async listGifts(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const u = new URL(ctx.request.url)
+			const q = u.searchParams.get('q')?.trim() || undefined
+			const status = u.searchParams.get('status')?.trim() || undefined
+			const page = Number(u.searchParams.get('page') ?? '1') || 1
+			const rawPageSize = Number(u.searchParams.get('pageSize') ?? '25') || 25
+			// Clamp to a sane window; the provider may further bound this.
+			const pageSize = Math.min(Math.max(1, rawPageSize), 100)
+
+			return json(await providers.subscriptions.listGifts({ q, status, page, pageSize }))
+		},
+
+		// 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)
+		// when the host supplies the role seam, falling back to requireAdmin
+		// (owner-only) otherwise. Mirrors the workspaceSettings PATCH gate in shell.ts.
+		async importLsEntitlements(ctx: RouteContext): Promise<Response> {
+			const gate = config.authz.requireRole
+				? await config.authz.requireRole('manage_settings' satisfies Capability, ctx)
+				: await config.authz.requireAdmin(ctx)
+			if (gate) return gate
+
+			const u = new URL(ctx.request.url)
+			const dryRun = u.searchParams.get('dryRun') === 'true'
+			const includeTest = u.searchParams.get('includeTest') === 'true'
+			const storeId = u.searchParams.get('storeId')?.trim() || undefined
+
+			return json(
+				await providers.subscriptions.importLsEntitlements({ dryRun, storeId, includeTest }),
+			)
+		},
+	}
+}

package/src/routes/tags.ts

@@ -0,0 +1,93 @@
+// Tag route handlers (P3 Task 9). Backs the Organize tab tag management.
+// Delegates to the engine functions (list/search/create/rename/delete)
+// from engine/tags.ts. Guarded by requirePublisher.
+
+import { z } from 'zod'
+import { createTag, deleteTag, getTag, listTags, renameTag, searchTags } from '../engine/tags.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { json, type RouteContext } from './context.js'
+
+const TagWriteSchema = z.object({
+	label: z.string().min(1),
+})
+
+export interface TagRouteHandlers {
+	/**
+	 * GET /tags or GET /tags?q=<query>
+	 * Without q: lists all tags ordered by usage count desc, label asc.
+	 * With q: searches tags whose slug begins with the slugified query.
+	 * Returns { tags: TagSummary[] }.
+	 */
+	list(ctx: RouteContext): Promise<Response>
+	/** POST /tags — create a standalone tag. */
+	create(ctx: RouteContext): Promise<Response>
+	/** PATCH /tags/:id — rename a tag. */
+	update(ctx: RouteContext): Promise<Response>
+	/**
+	 * DELETE /tags/:id — removes the tag (and cascades its content_tag_links).
+	 * Returns { deleted: true } when the tag was found and removed,
+	 * { deleted: false } when the id was not found.
+	 */
+	delete(ctx: RouteContext): Promise<Response>
+}
+
+export function createTagRoutes(config: CmsRouteConfig): TagRouteHandlers {
+	const resolved = resolveConfig(config)
+
+	return {
+		async list(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const url = new URL(ctx.request.url)
+			const q = url.searchParams.get('q')
+
+			const tags = q ? await searchTags(ctx.db, q) : await listTags(ctx.db)
+			return json({ tags })
+		},
+
+		async create(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const parsed = TagWriteSchema.safeParse(await ctx.request.json().catch(() => null))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+			const tag = await createTag(ctx.db, parsed.data.label)
+			if (!tag) return json({ error: 'Tag already exists or label is invalid' }, 409)
+			return json({ tag }, 201)
+		},
+
+		async update(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const id = ctx.params.id
+			if (!id) return json({ error: 'id is required' }, 400)
+			const before = await getTag(ctx.db, id)
+			if (!before) return json({ error: 'Not found' }, 404)
+
+			const parsed = TagWriteSchema.safeParse(await ctx.request.json().catch(() => null))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+			const ok = await renameTag(ctx.db, id, parsed.data.label)
+			if (!ok) return json({ error: 'Tag slug already exists or label is invalid' }, 409)
+			const tag = await getTag(ctx.db, id)
+			return json({ tag })
+		},
+
+		async delete(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const id = ctx.params.id
+			if (!id) return json({ error: 'id is required' }, 400)
+
+			const deleted = await deleteTag(ctx.db, id)
+			return json({ deleted })
+		},
+	}
+}

package/src/routes/topics.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+import { createTopic, listTopics, renameTopic } from '../engine/topics.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { json, type RouteContext } from './context.js'
+
+const TopicWriteSchema = z.object({
+	label: z.string().min(1),
+})
+
+export interface TopicRouteHandlers {
+	/** GET /topics — list existing primary_topic values with usage counts. */
+	list(ctx: RouteContext): Promise<Response>
+	/** POST /topics — create a standalone topic row with zero content assignments. */
+	create(ctx: RouteContext): Promise<Response>
+	/** PATCH /topics/:id — rename an existing primary_topic value across content rows. */
+	update(ctx: RouteContext): Promise<Response>
+}
+
+export function createTopicRoutes(config: CmsRouteConfig): TopicRouteHandlers {
+	const resolved = resolveConfig(config)
+
+	return {
+		async list(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const topics = await listTopics(ctx.db)
+			return json({ topics })
+		},
+
+		async create(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const parsed = TopicWriteSchema.safeParse(await ctx.request.json().catch(() => null))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+			const topic = await createTopic(ctx.db, parsed.data.label)
+			if (!topic)
+				return json({ error: 'Topic already exists, invalid, or topics table is unavailable' }, 409)
+			return json({ topic }, 201)
+		},
+
+		async update(ctx) {
+			const denied = await resolved.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const id = ctx.params.id
+			if (!id) return json({ error: 'id is required' }, 400)
+			const parsed = TopicWriteSchema.safeParse(await ctx.request.json().catch(() => null))
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', details: parsed.error.flatten() }, 400)
+			}
+			const topic = await renameTopic(ctx.db, id, parsed.data.label)
+			if (!topic) return json({ error: 'Topic not found, invalid, or slug already exists' }, 409)
+			return json({ topic })
+		},
+	}
+}