@growth-labs/cms 0.5.5 → 0.5.6

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 }
+}

package/src/surveys/schema.ts

@@ -0,0 +1,435 @@
+import { z } from 'zod'
+
+export const SURVEY_ID_MAX_LENGTH = 200
+const MAX_TITLE_LENGTH = 300
+const MAX_PROMPT_LENGTH = 1_000
+const MAX_QUESTIONS = 100
+const MAX_RESPONSES = 500
+const MAX_FREE_TEXT_ENTRIES = 500
+const MAX_FREE_TEXT_LENGTH = 20_000
+const MAX_CHOICE_OPTIONS = 100
+const MAX_OPTION_LENGTH = 256
+const MAX_SCALE_POINTS = 100
+const MAX_COUNT = 1_000_000_000
+const MAX_CSV_FILENAME_LENGTH = 200
+const MAX_CSV_CONTENT_LENGTH = 10_000_000
+const MAX_CSV_COLUMNS = 256
+const MAX_CSV_HEADER_LENGTH = 256
+
+export const SurveyIdSchema = z
+	.string()
+	.min(1)
+	.max(SURVEY_ID_MAX_LENGTH)
+	.regex(/^[A-Za-z0-9_-]+$/)
+export const SurveyQuestionIdSchema = SurveyIdSchema
+const BoundedRecordIdSchema = z
+	.string()
+	.min(1)
+	.max(SURVEY_ID_MAX_LENGTH)
+	.regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/)
+const IsoTimestampSchema = z.string().datetime({ offset: true })
+const CountSchema = z.number().int().nonnegative().max(MAX_COUNT)
+const NonemptyBoundedStringSchema = z
+	.string()
+	.min(1)
+	.max(MAX_OPTION_LENGTH)
+	.refine((value) => value.trim().length > 0)
+
+export const SurveyAudienceSchema = z.enum(['all', 'member', 'non_member'])
+export const SurveyRespondentSegmentSchema = z.enum(['member', 'non_member', 'unknown'])
+
+const ChoiceOptionsSchema = z
+	.array(NonemptyBoundedStringSchema)
+	.min(1)
+	.max(MAX_CHOICE_OPTIONS)
+	.refine((options) => new Set(options).size === options.length)
+
+const CountsSchema = z
+	.record(CountSchema)
+	.refine((counts) => Object.keys(counts).length <= MAX_CHOICE_OPTIONS)
+
+const QuestionBase = {
+	id: SurveyQuestionIdSchema,
+	position: z
+		.number()
+		.int()
+		.nonnegative()
+		.max(MAX_QUESTIONS - 1),
+	prompt: z
+		.string()
+		.min(1)
+		.max(MAX_PROMPT_LENGTH)
+		.refine((value) => value.trim().length > 0),
+	audience: SurveyAudienceSchema,
+	answerCount: CountSchema,
+}
+
+const SingleChoiceQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('single_choice'),
+		options: ChoiceOptionsSchema,
+		counts: CountsSchema,
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const MultiChoiceQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('multi_choice'),
+		options: ChoiceOptionsSchema,
+		counts: CountsSchema,
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const ScaleOptionsSchema = z
+	.object({
+		min: z.number().int(),
+		max: z.number().int(),
+	})
+	.strict()
+	.refine(
+		(options) => options.max >= options.min && options.max - options.min + 1 <= MAX_SCALE_POINTS,
+	)
+
+const ScaleQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('scale'),
+		options: ScaleOptionsSchema,
+		counts: z.null(),
+		average: z.number().finite().nullable(),
+		distribution: z.record(CountSchema),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const TextQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('text'),
+		options: z
+			.object({ max_length: z.number().int().positive().max(MAX_FREE_TEXT_LENGTH) })
+			.strict(),
+		counts: z.null(),
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: CountSchema,
+	})
+	.strict()
+
+export const SurveyQuestionSchema = z
+	.discriminatedUnion('kind', [
+		SingleChoiceQuestionSchema,
+		MultiChoiceQuestionSchema,
+		ScaleQuestionSchema,
+		TextQuestionSchema,
+	])
+	.superRefine((question, ctx) => {
+		if (question.kind === 'single_choice' || question.kind === 'multi_choice') {
+			if (!hasExactKeys(question.counts, question.options)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'Counts must match configured options',
+				})
+			}
+			const total = Object.values(question.counts).reduce((sum, count) => sum + count, 0)
+			if (question.kind === 'single_choice' && total !== question.answerCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Choice total is incoherent' })
+			}
+			if (
+				question.kind === 'multi_choice' &&
+				Object.values(question.counts).some((count) => count > question.answerCount)
+			) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Multi-choice total is incoherent' })
+			}
+			return
+		}
+
+		if (question.kind === 'scale') {
+			const keys = Array.from(
+				{ length: question.options.max - question.options.min + 1 },
+				(_, index) => String(question.options.min + index),
+			)
+			if (!hasExactKeys(question.distribution, keys)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'Scale distribution must include every configured value',
+				})
+			}
+			const total = Object.values(question.distribution).reduce((sum, count) => sum + count, 0)
+			if (total !== question.answerCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Scale total is incoherent' })
+			}
+			if (
+				(question.answerCount === 0 && question.average !== null) ||
+				(question.answerCount > 0 &&
+					(question.average === null ||
+						question.average < question.options.min ||
+						question.average > question.options.max))
+			) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Scale average is incoherent' })
+			}
+			return
+		}
+
+		if (question.responseCount !== question.answerCount) {
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Text response total is incoherent' })
+		}
+	})
+
+export const SurveyResultsSchema = z
+	.object({
+		survey: z
+			.object({
+				id: SurveyIdSchema,
+				title: z
+					.string()
+					.min(1)
+					.max(MAX_TITLE_LENGTH)
+					.refine((value) => value.trim().length > 0),
+				status: z.enum(['draft', 'active', 'closed']),
+				responseCount: CountSchema,
+			})
+			.strict(),
+		questions: z.array(SurveyQuestionSchema).max(MAX_QUESTIONS),
+		responses: z
+			.array(
+				z
+					.object({
+						id: BoundedRecordIdSchema,
+						channel: z.enum(['email', 'site', 'direct']),
+						submittedAt: IsoTimestampSchema,
+						respondentSegment: SurveyRespondentSegmentSchema,
+						anonymous: z.boolean(),
+					})
+					.strict(),
+			)
+			.max(MAX_RESPONSES),
+		freeText: z
+			.array(
+				z
+					.object({
+						questionId: SurveyQuestionIdSchema,
+						responseId: BoundedRecordIdSchema,
+						submittedAt: IsoTimestampSchema,
+						value: z.string().min(1).max(MAX_FREE_TEXT_LENGTH),
+					})
+					.strict(),
+			)
+			.max(MAX_FREE_TEXT_ENTRIES),
+	})
+	.strict()
+	.superRefine((results, ctx) => {
+		const questionIds = new Set<string>()
+		for (const [index, question] of results.questions.entries()) {
+			if (question.position !== index) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'position'],
+					message: 'Question positions must be ordered',
+				})
+			}
+			if (questionIds.has(question.id)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'id'],
+					message: 'Question IDs must be unique',
+				})
+			}
+			questionIds.add(question.id)
+			if (question.answerCount > results.survey.responseCount) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'answerCount'],
+					message: 'Question total exceeds survey total',
+				})
+			}
+		}
+
+		if (results.responses.length > results.survey.responseCount) {
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Response rows exceed survey total' })
+		}
+		const responses = new Map<string, (typeof results.responses)[number]>()
+		for (const [index, response] of results.responses.entries()) {
+			if (responses.has(response.id)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['responses', index, 'id'],
+					message: 'Response IDs must be unique',
+				})
+			}
+			responses.set(response.id, response)
+		}
+
+		const textQuestions = new Map(
+			results.questions
+				.filter(
+					(question): question is z.infer<typeof TextQuestionSchema> => question.kind === 'text',
+				)
+				.map((question) => [question.id, question]),
+		)
+		const freeTextCounts = new Map<string, number>()
+		for (const [index, entry] of results.freeText.entries()) {
+			const question = textQuestions.get(entry.questionId)
+			const response = responses.get(entry.responseId)
+			if (!question || (response && response.submittedAt !== entry.submittedAt)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['freeText', index],
+					message: 'Free-text references must be coherent',
+				})
+				continue
+			}
+			if (entry.value.length > question.options.max_length) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['freeText', index, 'value'],
+					message: 'Free-text value exceeds its question limit',
+				})
+			}
+			freeTextCounts.set(entry.questionId, (freeTextCounts.get(entry.questionId) ?? 0) + 1)
+		}
+		for (const question of textQuestions.values()) {
+			if ((freeTextCounts.get(question.id) ?? 0) > question.responseCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Free-text entries exceed total' })
+			}
+		}
+	})
+
+export const SurveyCsvResultSchema = z
+	.object({
+		filename: z.string().min(1).max(MAX_CSV_FILENAME_LENGTH),
+		content: z.string().min(1).max(MAX_CSV_CONTENT_LENGTH),
+	})
+	.strict()
+	.superRefine((result, ctx) => {
+		const header = parseCsvHeader(result.content)
+		if (!header) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'Invalid CSV header',
+			})
+			return
+		}
+		if (
+			header.length > MAX_CSV_COLUMNS ||
+			header.some(
+				(column) =>
+					column.length === 0 ||
+					column.length > MAX_CSV_HEADER_LENGTH ||
+					column.trim().length === 0,
+			)
+		) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'CSV header is too large',
+			})
+			return
+		}
+		if (header.some((column) => !isSafeCsvColumn(column))) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'CSV header contains a non-allowlisted column',
+			})
+		}
+	})
+
+const SafeCsvMetadataColumns = new Set([
+	'response_id',
+	'submitted_at',
+	'channel',
+	'respondent_segment',
+	'anonymous',
+])
+
+function isSafeCsvColumn(value: string): boolean {
+	if (SafeCsvMetadataColumns.has(value)) return true
+	const prefix = 'answer:'
+	return (
+		value.startsWith(prefix) && SurveyQuestionIdSchema.safeParse(value.slice(prefix.length)).success
+	)
+}
+
+function parseCsvHeader(content: string): string[] | null {
+	const fields: string[] = []
+	let field = ''
+	let inQuotes = false
+	let closedQuote = false
+	let atFieldStart = true
+	const source = content.startsWith('\uFEFF') ? content.slice(1) : content
+
+	for (let index = 0; index < source.length; index += 1) {
+		const char = source[index]
+		if (inQuotes) {
+			if (char !== '"') {
+				field += char
+				continue
+			}
+			if (source[index + 1] === '"') {
+				field += '"'
+				index += 1
+				continue
+			}
+			inQuotes = false
+			closedQuote = true
+			continue
+		}
+
+		if (closedQuote) {
+			if (char === ',') {
+				fields.push(field)
+				field = ''
+				closedQuote = false
+				atFieldStart = true
+				continue
+			}
+			if (char === '\r' || char === '\n') {
+				fields.push(field)
+				return fields
+			}
+			return null
+		}
+
+		if (atFieldStart && char === '"') {
+			inQuotes = true
+			atFieldStart = false
+			continue
+		}
+		if (char === '"') return null
+		if (char === ',') {
+			fields.push(field)
+			field = ''
+			atFieldStart = true
+			continue
+		}
+		if (char === '\r' || char === '\n') {
+			fields.push(field)
+			return fields
+		}
+		field += char
+		atFieldStart = false
+	}
+
+	if (inQuotes) return null
+	fields.push(field)
+	return fields
+}
+
+function hasExactKeys(record: Record<string, number>, expected: readonly string[]): boolean {
+	const actual = Object.keys(record)
+	return actual.length === expected.length && expected.every((key) => Object.hasOwn(record, key))
+}
+
+export type SurveyQuestion = z.infer<typeof SurveyQuestionSchema>
+export type SurveyResults = z.infer<typeof SurveyResultsSchema>
+export type SurveyCsvResult = z.infer<typeof SurveyCsvResultSchema>

package/src/ui/api/surveys/[surveyId]/responses.csv.ts

@@ -0,0 +1,23 @@
+import type { APIContext } from 'astro'
+import type { CmsProviders } from '../../../../providers/types.js'
+import type { RouteContext } from '../../../../routes/context.js'
+import { createSurveyRoutes, type SurveyRouteConfig } from '../../../../routes/surveys.js'
+import { buildSiteAuthz } from '../../_authz.js'
+
+function toCtx(context: APIContext): RouteContext {
+	const env = (context.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return {
+		request: context.request,
+		params: { surveyId: context.params.surveyId },
+		db: env.SITE_DB as RouteContext['db'],
+		env,
+	}
+}
+
+function routeConfig(context: APIContext): SurveyRouteConfig {
+	const locals = context.locals as { cmsProviders?: Partial<CmsProviders> }
+	return { authz: buildSiteAuthz(context), providers: locals.cmsProviders }
+}
+
+export const GET = (context: APIContext) =>
+	createSurveyRoutes(routeConfig(context)).csv(toCtx(context))

package/src/ui/api/surveys/[surveyId].ts

@@ -0,0 +1,23 @@
+import type { APIContext } from 'astro'
+import type { CmsProviders } from '../../../providers/types.js'
+import type { RouteContext } from '../../../routes/context.js'
+import { createSurveyRoutes, type SurveyRouteConfig } from '../../../routes/surveys.js'
+import { buildSiteAuthz } from '../_authz.js'
+
+function toCtx(context: APIContext): RouteContext {
+	const env = (context.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return {
+		request: context.request,
+		params: { surveyId: context.params.surveyId },
+		db: env.SITE_DB as RouteContext['db'],
+		env,
+	}
+}
+
+function routeConfig(context: APIContext): SurveyRouteConfig {
+	const locals = context.locals as { cmsProviders?: Partial<CmsProviders> }
+	return { authz: buildSiteAuthz(context), providers: locals.cmsProviders }
+}
+
+export const GET = (context: APIContext) =>
+	createSurveyRoutes(routeConfig(context)).results(toCtx(context))

package/src/ui/client/mount.tsx

@@ -37,6 +37,7 @@ export async function mount(elementId = 'masthead-root') {
 	const initial = initialWorkspaceState(config.workspaces, config.activeWorkspaceId, user)
 	const screens = createCmsScreens({
 		allowInlineAuthorCreation: config.socialSharing.allowInlineAuthorCreation,
+		surveyId: config.surveyResults?.surveyId,
 	})
 	createRoot(el).render(<CmsApp initial={initial} screens={screens} boot={boot} />)
 }