@growth-labs/video 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/video",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "exports": {
     ".": {
@@ -31,14 +31,18 @@
   },
   "files": [
     "dist",
-    "src/components"
+    "src/**/*.ts",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/**/*.md",
+    "src/**/*.sql"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
-    "astro": "^6.0.0",
+    "astro": "^6.1.10",
     "vidstack": "^1.12.0"
   },
   "peerDependenciesMeta": {
@@ -51,9 +55,9 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260402.1",
-    "astro": "^6.0.0",
+    "astro": "^6.1.10",
     "typescript": "^5.7.0",
-    "vite": "^7.0.0",
+    "vite": "^7.3.2",
     "vitest": "^3.0.0",
     "vidstack": "^1.12.0"
   },

package/src/cloudflare-workers.d.ts

@@ -0,0 +1,3 @@
+declare module 'cloudflare:workers' {
+	export const env: Record<string, unknown>
+}

package/src/components/Video.astro

@@ -72,6 +72,7 @@ const playerBoolAttrs = buildPlayerBooleanAttrs({
 	src={premium ? undefined : src}
 	poster={poster}
 	preload={config.player.preload}
+	crossorigin="anonymous"
 	class={`gl-video ${className ?? ''}`.trim()}
 	{...playerBoolAttrs}
 >

package/src/index.ts

@@ -0,0 +1,129 @@
+import type { AstroIntegration } from 'astro'
+import { type VideoOptions, videoOptionsSchema } from './options.js'
+import type { AccessCheck } from './types.js'
+import { growthLabsVideoPlugin } from './vite-plugin.js'
+
+/**
+ * Integration input. Mirrors `VideoOptions` (the Zod-validated shape). The
+ * legacy `accessCheck` inline function is accepted only to throw a clear
+ * migration error at integration init — it never worked in Cloudflare
+ * Workers production (build-time registration didn't survive to the
+ * runtime process). See MIGRATION.md.
+ */
+export interface VideoIntegrationInput extends VideoOptions {
+	/**
+	 * @deprecated since 0.3.3 — removed. Wire your access check through
+	 *   `premium.accessCheckModule: { module, export }` instead. The inline
+	 *   form never worked in Cloudflare Workers production.
+	 */
+	accessCheck?: AccessCheck
+}
+
+export default function video(userOptions: VideoIntegrationInput): AstroIntegration {
+	const { accessCheck: inlineAccessCheck, ...optionsInput } = userOptions
+	const options = videoOptionsSchema.parse(optionsInput)
+
+	if (options.premium?.enabled) {
+		if (inlineAccessCheck !== undefined && !options.premium.accessCheckModule) {
+			throw new Error(
+				'@growth-labs/video: inline `accessCheck` function is no longer supported since 0.3.3. ' +
+					'The inline form never worked in Cloudflare Workers production — build-time ' +
+					'registration of the function did not survive to the runtime process, so ' +
+					'`/api/video/session` returned `500 access_check_not_registered` on every request. ' +
+					'Move the function into its own module and reference it via ' +
+					"`premium.accessCheckModule: { module: '/src/lib/video-access-check', export: 'check' }`. " +
+					'See MIGRATION.md for the migration.',
+			)
+		}
+		if (!options.premium.accessCheckModule) {
+			throw new Error(
+				'@growth-labs/video: premium.enabled=true but no `premium.accessCheckModule` was provided. ' +
+					'Premium video must not be served without an entitlement check. Wire one as ' +
+					"`premium.accessCheckModule: { module: '/src/lib/video-access-check', export: 'check' }` " +
+					'(the module path is project-root absolute; the export must implement the `AccessCheck` type). ' +
+					'See README + MIGRATION.md for the module shape, or set `premium.enabled=false`.',
+			)
+		}
+	}
+
+	return {
+		name: '@growth-labs/video',
+		hooks: {
+			'astro:config:setup': ({ injectRoute, updateConfig }) => {
+				updateConfig({
+					vite: { plugins: [growthLabsVideoPlugin(options)] },
+				})
+
+				if (options.premium?.enabled) {
+					injectRoute({
+						pattern: options.premium.sessionRoute,
+						entrypoint: '@growth-labs/video/routes/session',
+					})
+					injectRoute({
+						pattern: `${options.premium.playbackRoute}/[...path]`,
+						entrypoint: '@growth-labs/video/routes/playback',
+					})
+				}
+
+				if (options.admin.importRoute.enabled) {
+					injectRoute({
+						pattern: options.admin.importRoute.path,
+						entrypoint: '@growth-labs/video/routes/import',
+					})
+				}
+			},
+		},
+	}
+}
+
+export type { ResolvedVideoOptions, VideoOptions } from './options.js'
+export { videoOptionsSchema } from './options.js'
+export type {
+	AccessCheck,
+	AccessCheckParams,
+	AccessResult,
+	Chapter,
+	ChaptersFile,
+	VideoObjectInput,
+	VttCue,
+} from './types.js'
+export { loadCaptions, parseVtt } from './utils/captions.js'
+export { loadChapters, parseChaptersJson, parseChaptersVtt } from './utils/chapters.js'
+export {
+	type HlsBundleFile,
+	type HlsBundleIngestResult,
+	ingestHlsBundle,
+	type ValidatedHlsBundle,
+	type ValidatedHlsBundleFile,
+	type VideoR2Bucket,
+	validateHlsBundle,
+} from './utils/ingest.js'
+export { generateVideoObjectJsonLd } from './utils/jsonld.js'
+export {
+	captionsKey,
+	chaptersJsonKey,
+	chaptersKey,
+	hlsBundlePrefix,
+	posterKey,
+	videoManifestKey,
+} from './utils/keys.js'
+export { issueSession, verifySession } from './utils/session.js'
+export {
+	readCaptionsVtt,
+	readChaptersVtt,
+	type VideoTextTrackBucket,
+	type VideoTextTrackReadResult,
+	type VideoTextTrackWriteResult,
+	writeCaptionsVtt,
+	writeChaptersVtt,
+} from './utils/text-tracks.js'
+export {
+	captionsUrl,
+	chaptersJsonUrl,
+	chaptersUrl,
+	manifestUrl,
+	posterUrl,
+	premiumManifestUrl,
+	premiumPlaybackUrl,
+} from './utils/url.js'
+export { youtubeEmbedUrl, youtubeThumbnailUrl } from './utils/youtube.js'

package/src/options.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod'
+
+const SESSION_TTL_MIN_SECONDS = 60
+const SESSION_TTL_MAX_SECONDS = 86_400
+
+function parseDurationToSeconds(input: string): number | null {
+	if (typeof input !== 'string' || input.length === 0) return null
+	const match = input.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/)
+	if (!match) return null
+	const [, h, m, s] = match
+	if (h === undefined && m === undefined && s === undefined) return null
+	const hours = h ? Number.parseInt(h, 10) : 0
+	const minutes = m ? Number.parseInt(m, 10) : 0
+	const seconds = s ? Number.parseInt(s, 10) : 0
+	return hours * 3600 + minutes * 60 + seconds
+}
+
+export const videoOptionsSchema = z.object({
+	// ─── Required ───
+	publicDomain: z.string(),
+
+	// ─── R2 bindings ───
+	r2Binding: z.string().default('MEDIA_BUCKET'),
+
+	// ─── Admin import/upload helper route (optional) ───
+	admin: z
+		.object({
+			importRoute: z
+				.object({
+					enabled: z.boolean().default(false),
+					path: z.string().default('/api/video/import'),
+					requireAuth: z.boolean().default(true),
+				})
+				.default({}),
+		})
+		.default({}),
+
+	// ─── Premium gating (optional) ───
+	premium: z
+		.object({
+			enabled: z.boolean().default(false),
+			sessionRoute: z.string().default('/api/video/session'),
+			playbackRoute: z.string().default('/api/video/playback'),
+			sessionCookieName: z
+				.string()
+				.regex(/^[a-zA-Z0-9_-]+$/, 'cookie name must be alphanumeric with underscores or hyphens')
+				.default('gl_video_session'),
+			sessionScope: z.enum(['per-video', 'wildcard']).default('per-video'),
+			sessionTtl: z
+				.string()
+				.default('1h')
+				.transform((value, ctx) => {
+					const seconds = parseDurationToSeconds(value)
+					if (seconds === null) {
+						ctx.addIssue({
+							code: z.ZodIssueCode.custom,
+							message: `invalid sessionTtl "${value}". Expected a duration string like "1h", "30m", or "2h30m".`,
+						})
+						return z.NEVER
+					}
+					if (seconds < SESSION_TTL_MIN_SECONDS) {
+						ctx.addIssue({
+							code: z.ZodIssueCode.custom,
+							message: `sessionTtl "${value}" resolves to ${seconds}s; minimum is ${SESSION_TTL_MIN_SECONDS}s.`,
+						})
+						return z.NEVER
+					}
+					if (seconds > SESSION_TTL_MAX_SECONDS) {
+						ctx.addIssue({
+							code: z.ZodIssueCode.custom,
+							message: `sessionTtl "${value}" resolves to ${seconds}s; maximum is ${SESSION_TTL_MAX_SECONDS}s (24h).`,
+						})
+						return z.NEVER
+					}
+					return seconds
+				}),
+			signingSecretEnv: z.string().default('GL_VIDEO_SESSION_SECRET'),
+			accessCheckModule: z
+				.object({
+					module: z.string().min(1),
+					export: z.string().min(1).default('accessCheck'),
+				})
+				.optional(),
+		})
+		.optional(),
+
+	// ─── Player defaults ───
+	player: z
+		.object({
+			autoplay: z.boolean().default(false),
+			muted: z.boolean().default(false),
+			preload: z.enum(['none', 'metadata', 'auto']).default('metadata'),
+			showCaptions: z.boolean().default(true),
+			showChapters: z.boolean().default(true),
+			controls: z.boolean().default(true),
+			startingQuality: z.enum(['auto', 'highest', 'lowest']).default('auto'),
+		})
+		.default({}),
+
+	// ─── YouTube embed fallback ───
+	youtube: z
+		.object({
+			enabled: z.boolean().default(true),
+			privacyMode: z.boolean().default(true),
+			lazyLoad: z.boolean().default(true),
+		})
+		.default({}),
+
+	// ─── Analytics ───
+	analytics: z
+		.object({
+			enabled: z.boolean().default(true),
+			progressMarks: z.array(z.number().min(0).max(1)).default([0.25, 0.5, 0.75, 0.95]),
+		})
+		.default({}),
+})
+
+export type VideoOptions = z.input<typeof videoOptionsSchema>
+export type ResolvedVideoOptions = z.output<typeof videoOptionsSchema>

package/src/routes/import.ts

@@ -0,0 +1,92 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
+import { config } from 'virtual:growth-labs/video/config'
+import type { APIRoute } from 'astro'
+import { type HlsBundleFile, ingestHlsBundle, type VideoR2Bucket } from '../utils/ingest.js'
+
+function json(body: unknown, status: number): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+function isFile(value: FormDataEntryValue | null): value is File {
+	return typeof File !== 'undefined' && value instanceof File
+}
+
+async function fileToHlsAsset(file: File, path: string): Promise<HlsBundleFile> {
+	const normalizedPath = path || file.name
+	const body = normalizedPath.endsWith('.m3u8') ? await file.text() : file
+	return {
+		path: normalizedPath,
+		body,
+		contentType: file.type || undefined,
+	}
+}
+
+function isAuthenticated(locals: unknown): boolean {
+	const user = (locals as { user?: { authenticated?: boolean } }).user
+	return user?.authenticated === true
+}
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const routeOptions = config.admin.importRoute
+	if (routeOptions.requireAuth && !isAuthenticated(locals)) {
+		return json({ error: 'Unauthorized' }, 401)
+	}
+
+	const env = cloudflareEnv as Record<string, unknown>
+	const bucket = env[config.r2Binding] as VideoR2Bucket | undefined
+	if (!bucket) {
+		return json({ error: `R2 bucket "${config.r2Binding}" not configured` }, 500)
+	}
+
+	let formData: FormData
+	try {
+		formData = await request.formData()
+	} catch {
+		return json({ error: 'Expected multipart form data' }, 400)
+	}
+
+	const videoId = formData.get('videoId')
+	if (typeof videoId !== 'string' || videoId.trim().length === 0) {
+		return json({ error: 'Missing videoId' }, 400)
+	}
+
+	const files = formData.getAll('files').filter(isFile)
+	if (files.length === 0) {
+		return json({ error: 'No HLS files provided' }, 400)
+	}
+
+	const paths = formData.getAll('paths').map((value) => String(value))
+	if (paths.length > 0 && paths.length !== files.length) {
+		return json({ error: 'paths must match files length' }, 400)
+	}
+
+	const hlsFiles = await Promise.all(
+		files.map((file, index) => fileToHlsAsset(file, paths[index] ?? file.name)),
+	)
+
+	const posterValue = formData.get('poster')
+	const poster = isFile(posterValue)
+		? {
+				path: posterValue.name || 'poster.jpg',
+				body: posterValue as File,
+				contentType: posterValue.type || undefined,
+			}
+		: undefined
+
+	try {
+		const result = await ingestHlsBundle({
+			bucket,
+			publicDomain: config.publicDomain,
+			videoId,
+			files: hlsFiles,
+			poster,
+		})
+		return json(result, 200)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		return json({ error: message }, 400)
+	}
+}

package/src/routes/playback.ts

@@ -0,0 +1,101 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
+import { config } from 'virtual:growth-labs/video/config'
+import type { APIRoute } from 'astro'
+import { verifySession } from '../utils/session.js'
+
+interface R2LikeBucket {
+	get(
+		key: string,
+		opts?: { range?: { offset?: number; length?: number; suffix?: number } },
+	): Promise<R2LikeObject | null>
+}
+
+interface R2LikeObject {
+	body: ReadableStream
+	httpEtag: string
+	writeHttpMetadata(headers: Headers): void
+}
+
+function inferContentType(key: string): string {
+	if (key.endsWith('.m3u8')) return 'application/vnd.apple.mpegurl'
+	if (key.endsWith('.m4s')) return 'video/iso.segment'
+	if (key.endsWith('.mp4')) return 'video/mp4'
+	if (key.endsWith('.vtt')) return 'text/vtt'
+	return 'application/octet-stream'
+}
+
+function parseRangeHeader(
+	header: string,
+): { offset?: number; length?: number; suffix?: number } | undefined {
+	const m = header.match(/^bytes=(\d*)-(\d*)$/)
+	if (!m) return undefined
+	const start = m[1]
+	const end = m[2]
+	if (start === '' && end !== '') return { suffix: parseInt(end, 10) }
+	if (start !== '' && end === '') return { offset: parseInt(start, 10) }
+	if (start !== '' && end !== '') {
+		const s = parseInt(start, 10)
+		const e = parseInt(end, 10)
+		return { offset: s, length: e - s + 1 }
+	}
+	return undefined
+}
+
+function readCookie(header: string | null, name: string): string | null {
+	if (!header) return null
+	const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`))
+	return match ? match[1] : null
+}
+
+export const GET: APIRoute = async (context) => {
+	const { request, params } = context
+	const env = cloudflareEnv as Record<string, unknown>
+
+	const rest = params.path as string | undefined
+	if (!rest || rest.length === 0) {
+		return new Response('invalid path', { status: 400 })
+	}
+
+	const segments = rest.split('/').filter(Boolean)
+	if (segments.length < 2) {
+		return new Response('invalid path', { status: 400 })
+	}
+	if (segments.some((s) => s === '..' || s === '.')) {
+		return new Response('invalid path', { status: 400 })
+	}
+
+	if (!config.premium) return new Response('premium disabled', { status: 404 })
+
+	const videoId = segments[0]
+	const subKey = segments.slice(1).join('/')
+
+	const cookie = readCookie(request.headers.get('cookie'), config.premium.sessionCookieName)
+	if (!cookie) return new Response('unauthorized', { status: 401 })
+
+	const secret = env[config.premium.signingSecretEnv] as string | undefined
+	if (!secret) return new Response('misconfigured', { status: 500 })
+
+	const session = await verifySession(cookie, secret, videoId)
+	if (!session) return new Response('forbidden', { status: 403 })
+
+	const bucket = env[config.r2Binding] as R2LikeBucket | undefined
+	if (!bucket) return new Response('misconfigured', { status: 500 })
+
+	const rangeHeader = request.headers.get('range')
+	const range = rangeHeader ? parseRangeHeader(rangeHeader) : undefined
+
+	const r2Key = `video/${videoId}/${subKey}`
+	const obj = await bucket.get(r2Key, range ? { range } : undefined)
+	if (!obj) return new Response('not found', { status: 404 })
+
+	const headers = new Headers()
+	obj.writeHttpMetadata(headers)
+	headers.set('etag', obj.httpEtag)
+	headers.set('content-type', inferContentType(r2Key))
+	headers.set('cache-control', r2Key.endsWith('.m3u8') ? 'no-cache' : 'public, max-age=3600')
+
+	return new Response(obj.body, {
+		status: range ? 206 : 200,
+		headers,
+	})
+}

package/src/routes/session.ts

@@ -0,0 +1,85 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
+import { accessRegistry } from 'virtual:growth-labs/video/access-check'
+import { config } from 'virtual:growth-labs/video/config'
+import type { APIRoute } from 'astro'
+import { issueSession } from '../utils/session.js'
+
+const MIN_SECRET_BYTES = 32
+
+function json(body: unknown, status: number): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+export const POST: APIRoute = async (context) => {
+	const { request } = context
+	const env = cloudflareEnv as Record<string, unknown>
+
+	let raw: unknown
+	try {
+		raw = await request.json()
+	} catch {
+		return json({ error: 'invalid_body' }, 400)
+	}
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+		return json({ error: 'invalid_body' }, 400)
+	}
+	const body = raw as { videoId?: unknown }
+	if (typeof body.videoId !== 'string' || body.videoId.length === 0) {
+		return json({ error: 'missing_video_id' }, 400)
+	}
+
+	if (!config.premium) {
+		return json({ error: 'premium_not_enabled' }, 500)
+	}
+
+	const accessCheck = accessRegistry.check
+	if (typeof accessCheck !== 'function') {
+		return json({ error: 'access_check_not_configured' }, 500)
+	}
+
+	const result = await accessCheck({ videoId: body.videoId, request, env }, context)
+	if (!result.allowed) {
+		return json({ error: 'forbidden', reason: result.reason }, 403)
+	}
+
+	const secret = env[config.premium.signingSecretEnv]
+	if (typeof secret !== 'string' || secret.length === 0) {
+		return json({ error: 'signing_secret_not_configured' }, 500)
+	}
+	if (secret.length < MIN_SECRET_BYTES) {
+		return json({ error: 'signing_secret_too_short' }, 500)
+	}
+
+	const ttlSeconds = config.premium.sessionTtl
+	const videoIds = config.premium.sessionScope === 'wildcard' ? '*' : [body.videoId]
+	const now = Math.floor(Date.now() / 1000)
+	const cookieValue = await issueSession(
+		{
+			videoIds,
+			subjectId: result.subjectId ?? 'anonymous',
+			issuedAt: now,
+			expiresAt: now + ttlSeconds,
+		},
+		secret,
+	)
+
+	const cookieParts = [
+		`${config.premium.sessionCookieName}=${cookieValue}`,
+		`Max-Age=${ttlSeconds}`,
+		'Path=/',
+		'HttpOnly',
+		'Secure',
+		'SameSite=Lax',
+	]
+
+	return new Response(JSON.stringify({ ok: true }), {
+		status: 200,
+		headers: {
+			'Content-Type': 'application/json',
+			'Set-Cookie': cookieParts.join('; '),
+		},
+	})
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+import type { APIContext } from 'astro'
+
+export interface AccessCheckParams {
+	videoId: string
+	request: Request
+	env: Record<string, unknown>
+}
+
+export interface AccessResult {
+	allowed: boolean
+	reason?: string
+	subjectId?: string
+}
+
+export type AccessCheck = (params: AccessCheckParams, context: APIContext) => Promise<AccessResult>
+
+export interface Chapter {
+	index: number
+	title: string
+	startSeconds: number
+	endSeconds: number
+}
+
+export interface ChaptersFile {
+	chapters: Chapter[]
+}
+
+export interface VttCue {
+	startSeconds: number
+	endSeconds: number
+	text: string
+}
+
+export interface VideoObjectInput {
+	videoId: string
+	title: string
+	description: string
+	publicDomain: string
+	uploadDate: string
+	durationSeconds: number
+	contentUrl?: string
+	embedUrl: string
+	thumbnailUrls?: string[]
+	transcript?: string
+	chapters?: Array<{ title: string; startSeconds: number }>
+}

package/src/utils/captions.ts

@@ -0,0 +1,72 @@
+import type { VttCue } from '../types.js'
+
+function parseTimestamp(str: string): number | null {
+	const m = str.match(/^(?:(\d+):)?(\d{2}):(\d{2})\.(\d{3})$/)
+	if (!m) return null
+	const h = m[1] ? parseInt(m[1], 10) : 0
+	const mm = parseInt(m[2], 10)
+	const s = parseInt(m[3], 10)
+	const ms = parseInt(m[4], 10)
+	return h * 3600 + mm * 60 + s + ms / 1000
+}
+
+export function parseVtt(input: string): VttCue[] | null {
+	if (!input) return null
+	const normalized = input.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+	const lines = normalized.split('\n')
+	if (!lines[0].startsWith('WEBVTT')) return null
+
+	const cues: VttCue[] = []
+	let i = 1
+	while (i < lines.length) {
+		while (i < lines.length && lines[i].trim() === '') i++
+		if (i >= lines.length) break
+
+		// Optional cue identifier line — skip if it's not a timing line.
+		if (!lines[i].includes('-->')) {
+			i++
+			if (i >= lines.length) break
+		}
+
+		const timing = lines[i]
+		const mt = timing.match(/^([\d:.]+)\s+-->\s+([\d:.]+)/)
+		if (!mt) {
+			i++
+			continue
+		}
+		const start = parseTimestamp(mt[1])
+		const end = parseTimestamp(mt[2])
+		i++
+
+		const textLines: string[] = []
+		while (i < lines.length && lines[i].trim() !== '') {
+			textLines.push(lines[i])
+			i++
+		}
+
+		if (start == null || end == null) continue
+		cues.push({ startSeconds: start, endSeconds: end, text: textLines.join('\n') })
+	}
+
+	if (cues.length === 0) return null
+	return cues
+}
+
+export interface LoadCaptionsOptions {
+	fetcher?: typeof fetch
+}
+
+export async function loadCaptions(
+	url: string,
+	opts: LoadCaptionsOptions = {},
+): Promise<VttCue[] | null> {
+	const fetcher = opts.fetcher ?? fetch
+	try {
+		const res = await fetcher(url)
+		if (!res.ok) return null
+		const body = await res.text()
+		return parseVtt(body)
+	} catch {
+		return null
+	}
+}