@growth-labs/cms 0.5.5 → 0.5.7

package/src/providers/types.ts

@@ -1,4 +1,5 @@
 import type { SeoScoreInput, SeoScoreResult } from '../engine/seo.js'
+import type { SurveyCsvResult, SurveyResults } from '../surveys/schema.js'
 
 export type ProviderStatus = 'live' | 'partial' | 'empty'
 export interface ProviderResult<T> {
@@ -402,6 +403,11 @@ export interface SettingsProvider {
 	getIntegrations(): Promise<ProviderResult<Record<string, CmsIntegrationStatus | null>>>
 }
 
+export interface SurveyProvider {
+	getResults(input: { surveyId: string }): Promise<SurveyResults>
+	getCsv(input: { surveyId: string }): Promise<SurveyCsvResult>
+}
+
 export interface CmsProviders {
 	analytics: AnalyticsProvider
 	subscriptions: SubscriptionsProvider
@@ -409,4 +415,5 @@ export interface CmsProviders {
 	seo: SeoProvider
 	search: SearchProvider
 	settings: SettingsProvider
+	surveys?: SurveyProvider
 }

package/src/routes/ai.ts

@@ -14,6 +14,7 @@
 //   apply the ai_locked_fields gate, persist when allowed, and return the result.
 // - OG-image generation lands in Task 5.
 
+import { generateContentDek } from '../engine/ai-dek.js'
 import {
 	headlinesPrompt,
 	metaDescriptionPrompt,
@@ -24,6 +25,7 @@ import { applyAiWrite, parseLockedFields } from '../engine/ai-writeback.js'
 import { buildOgCardSpec } from '../engine/og-render.js'
 import { type ContentItemRecord, getContentItem } from '../engine/publisher.js'
 import type { LlmDispatchResult } from '../providers/types.js'
+import { canPerformContentAction } from './authz-matrix.js'
 import type { CmsRouteConfig } from './config.js'
 import { resolveConfig } from './config.js'
 import { type Authz, type Capability, json, type RouteContext, requireId } from './context.js'
@@ -45,6 +47,8 @@ async function aiGuard(authz: Authz, ctx: RouteContext): Promise<Response | null
 }
 
 export interface AiRouteHandlers {
+	/** POST /content/:id/ai/dek — sync: generate + persist a display subheading. */
+	suggestDek(ctx: RouteContext): Promise<Response>
 	/** POST /content/:id/ai/proofread — SSE streaming proofread & tighten. */
 	proofreadAndTighten(ctx: RouteContext): Promise<Response>
 	/** POST /content/:id/ai/headlines — SSE streaming 5-headline suggestions. */
@@ -171,6 +175,45 @@ async function loadArticleBody(
 export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 	const resolved = resolveConfig(config)
 
+	async function suggestDek(ctx: RouteContext): Promise<Response> {
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const item = await getContentItem(ctx.db, idResult.id)
+		if (!item) return json({ error: 'Not found' }, 404)
+
+		if (resolved.authz.getUser) {
+			const user = await resolved.authz.getUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			const allowed = canPerformContentAction(
+				user.role,
+				{ actorSubject: user.subject, contentAuthorId: item.author_id },
+				item.status === 'published' ? 'write_published' : 'write',
+			)
+			if (!allowed) return json({ error: 'Forbidden', role: user.role }, 403)
+		} else {
+			const authGuard = await aiGuard(resolved.authz, ctx)
+			if (authGuard) return authGuard
+		}
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		const result = await generateContentDek({
+			db: ctx.db,
+			contentId: idResult.id,
+			llm: resolved.hooks.llm,
+		})
+		if (result.status === 'not_found') return json({ error: 'Not found' }, 404)
+		if (result.status === 'unavailable') {
+			return llmUnavailableResponse({ reason: result.reason }, { dek: null, written: false })
+		}
+		return json({
+			dek: result.dek,
+			written: result.written,
+			...(result.status === 'locked' ? { locked: true } : {}),
+		})
+	}
+
 	async function proofreadAndTighten(ctx: RouteContext): Promise<Response> {
 		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
 		const authGuard = await aiGuard(resolved.authz, ctx)
@@ -452,6 +495,7 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 	}
 
 	return {
+		suggestDek,
 		proofreadAndTighten,
 		suggestHeadlines,
 		generateKeyTakeaways,

package/src/routes/authz-matrix.ts

@@ -20,6 +20,7 @@
 
 import type { MembershipRecord } from '../engine/members.js'
 import type { CmsRole } from '../schema/types.js'
+import { SURVEY_RESPONSE_ROLES } from '../surveys/access.js'
 import type { Capability, CmsUser, RouteContext } from './context.js'
 import { json } from './context.js'
 
@@ -53,6 +54,7 @@ export const CAPABILITY_MATRIX: Record<Capability, ReadonlySet<CmsRole>> = {
 	publish_article: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	publish_video: new Set<CmsRole>(['owner', 'senior_editor', 'editor', 'producer']),
 	edit_own_draft: new Set<CmsRole>(['owner', 'senior_editor', 'editor', 'contributor', 'producer']),
+	edit_published: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	publish_others_draft: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	submit_for_review: new Set<CmsRole>([
 		'owner',
@@ -75,6 +77,7 @@ export const CAPABILITY_MATRIX: Record<Capability, ReadonlySet<CmsRole>> = {
 	// Complimentary access is an editorial admin action by explicit operator
 	// decision; it is not subscriber-PII export or owner-only settings.
 	manage_complimentary_access: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
+	view_survey_responses: SURVEY_RESPONSE_ROLES,
 }
 
 // ---------------------------------------------------------------------------
@@ -148,6 +151,7 @@ export function canActOnContent(
  *   - 'write'    — create / update / save a draft, set-status, snapshot,
  *                  contributors edit. Lowest bar: edit_own_draft (any member;
  *                  contributor/producer gated to OWN content by canActOnContent).
+ *   - 'write_published' — update published copy. Explicitly editorial-only.
  *   - 'publish'  — publish/unpublish/archive/unschedule an article. Requires
  *                  publish_others_draft (owner/senior_editor/editor); on OWN
  *                  content publish_article suffices (still excludes contributor).
@@ -156,7 +160,14 @@ export function canActOnContent(
  *   - 'trash'    — soft-delete / bulk-trash. Destructive → publish_others_draft.
  *   - 'media'    — dispatch-to-foundry / regenerate AI artefacts. media_pipeline.
  */
-export type ContentAction = 'write' | 'publish' | 'publish_video' | 'schedule' | 'trash' | 'media'
+export type ContentAction =
+	| 'write'
+	| 'write_published'
+	| 'publish'
+	| 'publish_video'
+	| 'schedule'
+	| 'trash'
+	| 'media'
 
 /**
  * Resolve whether `role` may perform a content `action` on an item authored by
@@ -178,6 +189,8 @@ export function canPerformContentAction(
 	switch (action) {
 		case 'write':
 			return canActOnContent(role, ownership, 'edit_own_draft')
+		case 'write_published':
+			return canActOnContent(role, ownership, 'edit_published')
 		case 'media':
 			return canActOnContent(role, ownership, 'media_pipeline')
 		case 'publish_video':

package/src/routes/content.ts

@@ -16,6 +16,8 @@
 
 import { z } from 'zod'
 import { logActivity } from '../engine/activity-log.js'
+import { generateContentDek } from '../engine/ai-dek.js'
+import { createDekFailureNotifications } from '../engine/ai-dek-notifications.js'
 import { listContributors, setContributors } from '../engine/contributors.js'
 import type { D1Database } from '../engine/d1.js'
 import {
@@ -1126,7 +1128,11 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (!existing) return json({ error: 'Not found' }, 404)
 
 			// Edit = write; contributor/producer gated to their own content.
-			const denied = await requireContentAction(ctx, 'write', existing.author_id)
+			const denied = await requireContentAction(
+				ctx,
+				existing.status === 'published' ? 'write_published' : 'write',
+				existing.author_id,
+			)
 			if (denied) return denied
 
 			const parsed = UpdateSchema.safeParse(await readJson(ctx))
@@ -1320,6 +1326,44 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 						422,
 					)
 				}
+
+				if (!existing.excerpt?.trim()) {
+					let failureReason: string | null = null
+					if (!resolved.hooks.llm) {
+						failureReason = 'AI generation is not configured'
+					} else {
+						try {
+							const generated = await generateContentDek({
+								db: ctx.db,
+								contentId: id,
+								llm: resolved.hooks.llm,
+							})
+							if (generated.status === 'unavailable' || generated.status === 'not_found') {
+								failureReason = generated.reason
+							}
+						} catch (error) {
+							failureReason = error instanceof Error ? error.message : String(error)
+						}
+					}
+					if (failureReason) {
+						console.error('[cms] dek generation failed; publishing without a subheading', {
+							contentId: id,
+							reason: failureReason,
+						})
+						try {
+							await createDekFailureNotifications({
+								db: ctx.db,
+								workspaceId: activeWorkspaceId,
+								contentId: id,
+								title: existing.title,
+								reason: failureReason,
+								userId: ctx.userId,
+							})
+						} catch (notificationError) {
+							console.error('[cms] failed to create dek generation notification', notificationError)
+						}
+					}
+				}
 				await publishContent(ctx.db, id, now)
 				await createRevision(ctx.db, id, ctx.userId || null)
 

package/src/routes/context.ts

@@ -25,6 +25,7 @@ export type Capability =
 	| 'publish_article'
 	| 'publish_video'
 	| 'edit_own_draft'
+	| 'edit_published'
 	| 'publish_others_draft'
 	| 'submit_for_review'
 	| 'media_pipeline'
@@ -38,6 +39,8 @@ export type Capability =
 	// Complimentary access administration. Explicit operator decision: owner,
 	// senior_editor, and editor may grant/revoke/retry; contributor/producer may not.
 	| 'manage_complimentary_access'
+	// Read-only survey reporting. No raw respondent identity is exposed in the screen contract.
+	| 'view_survey_responses'
 
 export interface CmsUser {
 	subject: string

package/src/routes/index.ts

@@ -163,6 +163,12 @@ export {
 	type SubscriptionsRouteConfig,
 	type SubscriptionsRouteHandlers,
 } from './subscriptions.js'
+// Survey reporting routes — optional storage-neutral provider, protected by role capability.
+export {
+	createSurveyRoutes,
+	type SurveyRouteConfig,
+	type SurveyRouteHandlers,
+} from './surveys.js'
 // Tag management routes — GET /tags, GET /tags?q=, DELETE /tags/:id (P3 Task 9).
 export { createTagRoutes, type TagRouteHandlers } from './tags.js'
 // Topic management over content_items.primary_topic.

package/src/routes/surveys.ts

@@ -0,0 +1,130 @@
+import { nullProviders } from '../providers/null.js'
+import { type CmsProviders, ProviderHttpError } from '../providers/types.js'
+import {
+	SURVEY_ERROR_CODE_HEADER,
+	SURVEY_ERROR_DEFINITIONS,
+	type SurveyErrorCode,
+	surveyErrorBody,
+} from '../surveys/errors.js'
+import { SurveyCsvResultSchema, SurveyIdSchema, SurveyResultsSchema } from '../surveys/schema.js'
+import type { Authz, Capability, RouteContext } from './context.js'
+
+export interface SurveyRouteConfig {
+	authz: Authz
+	providers?: Partial<CmsProviders>
+}
+
+export interface SurveyRouteHandlers {
+	results(ctx: RouteContext): Promise<Response>
+	csv(ctx: RouteContext): Promise<Response>
+}
+
+export function createSurveyRoutes(config: SurveyRouteConfig): SurveyRouteHandlers {
+	const providers: CmsProviders = { ...nullProviders, ...(config.providers ?? {}) }
+
+	return {
+		async results(ctx) {
+			const denied = await requireSurveyAccess(config.authz, ctx)
+			if (denied) return withNoStoreAuthFailure(denied)
+			const surveyId = parseSurveyId(ctx)
+			if (!surveyId) return surveyErrorResponse('survey_invalid_request')
+			try {
+				const parsed = SurveyResultsSchema.safeParse(
+					await providers.surveys?.getResults({ surveyId }),
+				)
+				if (!parsed.success || parsed.data.survey.id !== surveyId) {
+					return surveyErrorResponse('survey_provider_malformed')
+				}
+				return responseJson(parsed.data)
+			} catch (error) {
+				return providerFailure(error)
+			}
+		},
+
+		async csv(ctx) {
+			const denied = await requireSurveyAccess(config.authz, ctx)
+			if (denied) return withNoStoreAuthFailure(denied)
+			const surveyId = parseSurveyId(ctx)
+			if (!surveyId) return surveyErrorResponse('survey_invalid_request')
+			try {
+				const parsed = SurveyCsvResultSchema.safeParse(
+					await providers.surveys?.getCsv({ surveyId }),
+				)
+				if (!parsed.success) return surveyErrorResponse('survey_provider_malformed')
+				return new Response(parsed.data.content, {
+					headers: {
+						'Cache-Control': 'no-store',
+						'Content-Disposition': `attachment; filename="${safeCsvFilename(parsed.data.filename)}"`,
+						'Content-Type': 'text/csv; charset=utf-8',
+					},
+				})
+			} catch (error) {
+				return providerFailure(error)
+			}
+		},
+	}
+}
+
+async function requireSurveyAccess(authz: Authz, ctx: RouteContext): Promise<Response | null> {
+	if (!authz.requireRole) return surveyErrorResponse('survey_internal_failure')
+	return authz.requireRole('view_survey_responses' satisfies Capability, ctx)
+}
+
+function parseSurveyId(ctx: RouteContext): string | null {
+	const value = ctx.params.surveyId ?? ctx.params.id
+	const parsed = SurveyIdSchema.safeParse(value)
+	return parsed.success ? parsed.data : null
+}
+
+function safeCsvFilename(value: string): string {
+	const basename =
+		value
+			.split(/[\\/]/)
+			.at(-1)
+			?.replace(/[\r\n]/g, '') ?? ''
+	const safe = basename
+		.replace(/[^A-Za-z0-9._-]+/g, '-')
+		.replace(/^\.+/, '')
+		.replace(/-+/g, '-')
+		.slice(0, 180)
+	return safe.endsWith('.csv') ? safe : `${safe || 'survey-responses'}.csv`
+}
+
+function providerFailure(error: unknown): Response {
+	if (error instanceof ProviderHttpError) {
+		const mapped = ProviderFailureAllowlist.get(`${error.status}:${error.code}`)
+		if (mapped) return surveyErrorResponse(mapped)
+	}
+	return surveyErrorResponse('survey_upstream_failure')
+}
+
+const ProviderFailureAllowlist = new Map<string, SurveyErrorCode>([
+	['403:survey_forbidden', 'survey_forbidden'],
+	['404:survey_not_found', 'survey_not_found'],
+	['500:survey_internal_failure', 'survey_internal_failure'],
+	['502:survey_upstream_failure', 'survey_upstream_failure'],
+	['503:survey_provider_unavailable', 'survey_provider_unavailable'],
+	['503:survey_upstream_unavailable', 'survey_upstream_unavailable'],
+])
+
+function surveyErrorResponse(code: SurveyErrorCode): Response {
+	return responseJson(surveyErrorBody(code), SURVEY_ERROR_DEFINITIONS[code].status, code)
+}
+
+function withNoStoreAuthFailure(response: Response): Response {
+	const cloned = response.clone()
+	cloned.headers.set('Cache-Control', 'no-store')
+	if (cloned.status === 401 || cloned.status === 403) {
+		cloned.headers.set(SURVEY_ERROR_CODE_HEADER, 'survey_forbidden')
+	}
+	return cloned
+}
+
+function responseJson(body: unknown, status = 200, code?: SurveyErrorCode): Response {
+	const headers = new Headers({ 'Cache-Control': 'no-store', 'Content-Type': 'application/json' })
+	if (code) headers.set(SURVEY_ERROR_CODE_HEADER, code)
+	return new Response(JSON.stringify(body), {
+		status,
+		headers,
+	})
+}

package/src/surveys/access.ts

@@ -0,0 +1,11 @@
+import type { CmsRole } from '../schema/types.js'
+
+export const SURVEY_RESPONSE_ROLES: ReadonlySet<CmsRole> = new Set([
+	'owner',
+	'senior_editor',
+	'editor',
+])
+
+export function canViewSurveyResponses(role: CmsRole | null | undefined): boolean {
+	return role != null && SURVEY_RESPONSE_ROLES.has(role)
+}

package/src/surveys/errors.ts

@@ -0,0 +1,51 @@
+export const SURVEY_ERROR_CODE_HEADER = 'X-Growth-Labs-Survey-Error-Code'
+
+export const SURVEY_ERROR_DEFINITIONS = {
+	survey_invalid_request: {
+		status: 400,
+		error: 'Invalid survey request.',
+	},
+	survey_forbidden: {
+		status: 403,
+		error: 'You do not have permission to view survey responses.',
+	},
+	survey_not_found: {
+		status: 404,
+		error: 'Survey not found.',
+	},
+	survey_provider_unavailable: {
+		status: 503,
+		error: 'Survey reporting is not configured for this site.',
+	},
+	survey_provider_malformed: {
+		status: 502,
+		error: 'Survey provider returned invalid data.',
+	},
+	survey_upstream_unavailable: {
+		status: 503,
+		error: 'Survey reporting is temporarily unavailable.',
+	},
+	survey_upstream_failure: {
+		status: 502,
+		error: 'Survey reporting could not be loaded.',
+	},
+	survey_internal_failure: {
+		status: 500,
+		error: 'Survey reporting could not be loaded.',
+	},
+} as const
+
+export type SurveyErrorCode = keyof typeof SURVEY_ERROR_DEFINITIONS
+
+export interface SurveyErrorBody {
+	error: string
+	code: SurveyErrorCode
+}
+
+export function isSurveyErrorCode(value: unknown): value is SurveyErrorCode {
+	return typeof value === 'string' && Object.hasOwn(SURVEY_ERROR_DEFINITIONS, value)
+}
+
+export function surveyErrorBody(code: SurveyErrorCode): SurveyErrorBody {
+	return { error: SURVEY_ERROR_DEFINITIONS[code].error, code }
+}