@growth-labs/video 0.3.4 → 0.3.6

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

package/src/utils/chapters.ts

@@ -0,0 +1,63 @@
+import type { Chapter, ChaptersFile } from '../types.js'
+import { parseVtt } from './captions.js'
+
+export function parseChaptersJson(raw: unknown): ChaptersFile | null {
+	if (!raw || typeof raw !== 'object') return null
+	const obj = raw as Record<string, unknown>
+	if (!Array.isArray(obj.chapters)) return null
+	const out: Chapter[] = []
+	for (const item of obj.chapters) {
+		if (!item || typeof item !== 'object') return null
+		const ch = item as Record<string, unknown>
+		if (
+			typeof ch.index !== 'number' ||
+			typeof ch.title !== 'string' ||
+			typeof ch.startSeconds !== 'number' ||
+			typeof ch.endSeconds !== 'number'
+		) {
+			return null
+		}
+		out.push({
+			index: ch.index,
+			title: ch.title,
+			startSeconds: ch.startSeconds,
+			endSeconds: ch.endSeconds,
+		})
+	}
+	return { chapters: out }
+}
+
+export function parseChaptersVtt(input: string): ChaptersFile | null {
+	const cues = parseVtt(input)
+	if (!cues) return null
+	return {
+		chapters: cues.map((cue, index) => ({
+			index,
+			title: cue.text.trim(),
+			startSeconds: cue.startSeconds,
+			endSeconds: cue.endSeconds,
+		})),
+	}
+}
+
+export interface LoadChaptersOptions {
+	fetcher?: typeof fetch
+}
+
+export async function loadChapters(
+	url: string,
+	opts: LoadChaptersOptions = {},
+): Promise<ChaptersFile | null> {
+	const fetcher = opts.fetcher ?? fetch
+	try {
+		const res = await fetcher(url)
+		if (!res.ok) return null
+		const body = await res.text()
+		if (body.trimStart().startsWith('{')) {
+			return parseChaptersJson(JSON.parse(body) as unknown)
+		}
+		return parseChaptersVtt(body)
+	} catch {
+		return null
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+export * from './captions.js'
+export * from './chapters.js'
+export * from './ingest.js'
+export * from './jsonld.js'
+export * from './keys.js'
+export * from './session.js'
+export * from './text-tracks.js'
+export * from './url.js'
+export * from './youtube.js'

package/src/utils/ingest.ts

@@ -0,0 +1,220 @@
+import { normalizeVideoId, posterKey } from './keys.js'
+import { manifestUrl, posterUrl } from './url.js'
+
+export type VideoR2PutBody =
+	| string
+	| ArrayBuffer
+	| ArrayBufferView
+	| Blob
+	| ReadableStream<Uint8Array>
+
+export interface VideoR2Bucket {
+	put(
+		key: string,
+		value: VideoR2PutBody,
+		options?: {
+			httpMetadata?: { contentType?: string }
+			customMetadata?: Record<string, string>
+		},
+	): Promise<R2Object | undefined>
+}
+
+export interface HlsBundleFile {
+	path: string
+	body: VideoR2PutBody
+	contentType?: string
+	customMetadata?: Record<string, string>
+}
+
+export interface ValidatedHlsBundleFile extends HlsBundleFile {
+	hlsPath: string
+}
+
+export interface ValidatedHlsBundle {
+	files: ValidatedHlsBundleFile[]
+	referencedPaths: string[]
+}
+
+export interface IngestHlsBundleOptions {
+	bucket: VideoR2Bucket
+	publicDomain: string
+	videoId: string
+	files: HlsBundleFile[]
+	poster?: HlsBundleFile
+}
+
+export interface HlsBundleIngestResult {
+	videoId: string
+	manifestUrl: string
+	posterUrl?: string
+}
+
+function assertSafeSegments(path: string): string {
+	const segments = path.split('/').filter(Boolean)
+	if (
+		path.length === 0 ||
+		path.startsWith('/') ||
+		segments.length === 0 ||
+		segments.some((segment) => segment === '.' || segment === '..')
+	) {
+		throw new Error(`invalid HLS path: ${path}`)
+	}
+	return segments.join('/')
+}
+
+function normalizeHlsPath(rawPath: string): string {
+	let path = rawPath.trim().replace(/\\/g, '/').replace(/^\/+/, '')
+	if (path.startsWith('video/')) {
+		const segments = path.split('/')
+		const hlsIndex = segments.indexOf('hls')
+		if (hlsIndex >= 0) path = segments.slice(hlsIndex + 1).join('/')
+	}
+	if (path.startsWith('hls/')) path = path.slice('hls/'.length)
+	return assertSafeSegments(path)
+}
+
+function directoryOf(path: string): string {
+	const index = path.lastIndexOf('/')
+	return index === -1 ? '' : path.slice(0, index)
+}
+
+function stripQueryAndHash(uri: string): string {
+	return uri.split(/[?#]/, 1)[0] ?? ''
+}
+
+function resolveManifestUri(manifestPath: string, uri: string): string {
+	const cleanUri = stripQueryAndHash(uri.trim())
+	if (/^[a-z][a-z0-9+.-]*:/i.test(cleanUri) || cleanUri.startsWith('//')) {
+		throw new Error(`external HLS URI is not supported: ${uri}`)
+	}
+	const baseDir = directoryOf(manifestPath)
+	return normalizeHlsPath(baseDir ? `${baseDir}/${cleanUri}` : cleanUri)
+}
+
+function extractUriAttributes(line: string): string[] {
+	return [...line.matchAll(/\bURI="([^"]*)"/g)].map((match) => match[1] ?? '')
+}
+
+function extractReferencedUris(manifestPath: string, manifest: string): string[] {
+	const refs: string[] = []
+	for (const rawLine of manifest.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n')) {
+		const line = rawLine.trim()
+		if (!line) continue
+		if (line.startsWith('#')) {
+			for (const uri of extractUriAttributes(line)) {
+				refs.push(resolveManifestUri(manifestPath, uri))
+			}
+			continue
+		}
+		refs.push(resolveManifestUri(manifestPath, line))
+	}
+	return refs
+}
+
+function readManifestText(file: HlsBundleFile): string {
+	if (typeof file.body === 'string') return file.body
+	if (file.body instanceof Uint8Array) return new TextDecoder().decode(file.body)
+	if (file.body instanceof ArrayBuffer) return new TextDecoder().decode(file.body)
+	if (ArrayBuffer.isView(file.body)) {
+		return new TextDecoder().decode(file.body)
+	}
+	throw new Error(`manifest ${file.path} must be text`)
+}
+
+async function bodyToText(body: VideoR2PutBody): Promise<string> {
+	if (typeof body === 'string') return body
+	if (body instanceof Blob) return body.text()
+	if (body instanceof Uint8Array) return new TextDecoder().decode(body)
+	if (body instanceof ArrayBuffer) return new TextDecoder().decode(body)
+	if (ArrayBuffer.isView(body)) return new TextDecoder().decode(body)
+	throw new Error('manifest body must be text, Blob, or ArrayBuffer')
+}
+
+async function prepareFiles(files: HlsBundleFile[]): Promise<HlsBundleFile[]> {
+	return Promise.all(
+		files.map(async (file) => {
+			const hlsPath = normalizeHlsPath(file.path)
+			if (!hlsPath.endsWith('.m3u8')) return file
+			return { ...file, body: await bodyToText(file.body) }
+		}),
+	)
+}
+
+function inferContentType(path: string, provided?: string): string {
+	if (provided) return provided
+	if (path.endsWith('.m3u8')) return 'application/vnd.apple.mpegurl'
+	if (path.endsWith('.m4s')) return 'video/iso.segment'
+	if (path.endsWith('.mp4')) return 'video/mp4'
+	if (path.endsWith('.vtt')) return 'text/vtt; charset=utf-8'
+	if (path.endsWith('.jpg') || path.endsWith('.jpeg')) return 'image/jpeg'
+	if (path.endsWith('.png')) return 'image/png'
+	if (path.endsWith('.webp')) return 'image/webp'
+	return 'application/octet-stream'
+}
+
+export function validateHlsBundle(files: HlsBundleFile[]): ValidatedHlsBundle {
+	const normalizedFiles = files.map((file) => ({ ...file, hlsPath: normalizeHlsPath(file.path) }))
+	const fileMap = new Map<string, ValidatedHlsBundleFile>()
+	for (const file of normalizedFiles) {
+		if (fileMap.has(file.hlsPath)) throw new Error(`duplicate HLS path: ${file.hlsPath}`)
+		fileMap.set(file.hlsPath, file)
+	}
+
+	const master = fileMap.get('master.m3u8')
+	if (!master) throw new Error('HLS bundle must include master.m3u8')
+
+	const referenced = new Set<string>()
+	const visitedManifests = new Set<string>()
+	const visitManifest = (manifestPath: string) => {
+		if (visitedManifests.has(manifestPath)) return
+		visitedManifests.add(manifestPath)
+		const manifestFile = fileMap.get(manifestPath)
+		if (!manifestFile) throw new Error(`missing HLS manifest: ${manifestPath}`)
+		const manifest = readManifestText(manifestFile)
+		if (!manifest.trimStart().startsWith('#EXTM3U')) {
+			throw new Error(`invalid HLS manifest: ${manifestPath}`)
+		}
+		for (const ref of extractReferencedUris(manifestPath, manifest)) {
+			referenced.add(ref)
+			const target = fileMap.get(ref)
+			if (!target) throw new Error(`missing HLS referenced file: ${ref}`)
+			if (ref.endsWith('.m3u8')) visitManifest(ref)
+		}
+	}
+
+	visitManifest('master.m3u8')
+
+	return { files: normalizedFiles, referencedPaths: [...referenced].sort() }
+}
+
+export async function ingestHlsBundle(
+	options: IngestHlsBundleOptions,
+): Promise<HlsBundleIngestResult> {
+	const videoId = normalizeVideoId(options.videoId)
+	const preparedFiles = await prepareFiles(options.files)
+	const bundle = validateHlsBundle(preparedFiles)
+
+	await Promise.all(
+		bundle.files.map((file) =>
+			options.bucket.put(`video/${videoId}/hls/${file.hlsPath}`, file.body, {
+				httpMetadata: { contentType: inferContentType(file.hlsPath, file.contentType) },
+				customMetadata: file.customMetadata,
+			}),
+		),
+	)
+
+	if (options.poster) {
+		await options.bucket.put(posterKey(videoId), options.poster.body, {
+			httpMetadata: {
+				contentType: inferContentType(options.poster.path, options.poster.contentType),
+			},
+			customMetadata: options.poster.customMetadata,
+		})
+	}
+
+	return {
+		videoId,
+		manifestUrl: manifestUrl(options.publicDomain, videoId),
+		posterUrl: options.poster ? posterUrl(options.publicDomain, videoId) : undefined,
+	}
+}

package/src/utils/jsonld.ts

@@ -0,0 +1,42 @@
+import type { VideoObjectInput } from '../types.js'
+import { posterUrl } from './url.js'
+
+function toIsoDuration(seconds: number): string {
+	const h = Math.floor(seconds / 3600)
+	const m = Math.floor((seconds % 3600) / 60)
+	const s = seconds % 60
+	let out = 'PT'
+	if (h) out += `${h}H`
+	if (m) out += `${m}M`
+	if (s) out += `${s}S`
+	if (out === 'PT') out = 'PT0S'
+	return out
+}
+
+export function generateVideoObjectJsonLd(input: VideoObjectInput): object {
+	const thumbnailUrl = input.thumbnailUrls ?? [posterUrl(input.publicDomain, input.videoId)]
+
+	const ld: Record<string, unknown> = {
+		'@context': 'https://schema.org',
+		'@type': 'VideoObject',
+		name: input.title,
+		description: input.description,
+		uploadDate: input.uploadDate,
+		duration: toIsoDuration(input.durationSeconds),
+		thumbnailUrl,
+		embedUrl: input.embedUrl,
+	}
+
+	if (input.contentUrl) ld.contentUrl = input.contentUrl
+	if (input.transcript) ld.transcript = input.transcript
+
+	if (input.chapters && input.chapters.length > 0) {
+		ld.potentialAction = {
+			'@type': 'SeekToAction',
+			target: `${input.embedUrl}#t={seek_to_second_number}`,
+			'startOffset-input': 'required name=seek_to_second_number',
+		}
+	}
+
+	return ld
+}

package/src/utils/keys.ts

@@ -0,0 +1,42 @@
+export function normalizeVideoId(videoId: string): string {
+	const normalized = videoId.trim()
+	if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(normalized)) {
+		throw new Error('invalid videoId')
+	}
+	return normalized
+}
+
+export function videoManifestKey(videoId: string): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	return `video/${safeVideoId}/hls/master.m3u8`
+}
+
+export function posterKey(videoId: string): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	return `video/${safeVideoId}/poster.jpg`
+}
+
+export function captionsKey(videoId: string, lang: string = 'en'): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	const normalized =
+		lang
+			.trim()
+			.toLowerCase()
+			.replace(/[^a-z0-9-]/g, '_') || 'en'
+	return `video/${safeVideoId}/captions_${normalized}.vtt`
+}
+
+export function chaptersKey(videoId: string): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	return `video/${safeVideoId}/chapters.vtt`
+}
+
+export function chaptersJsonKey(videoId: string): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	return `video/${safeVideoId}/chapters.json`
+}
+
+export function hlsBundlePrefix(videoId: string): string {
+	const safeVideoId = normalizeVideoId(videoId)
+	return `video/${safeVideoId}/hls/`
+}

package/src/utils/session.ts

@@ -0,0 +1,96 @@
+export interface SessionPayload {
+	videoIds: string[] | '*'
+	subjectId: string
+	issuedAt: number
+	expiresAt: number
+	nonce: string
+}
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function toBase64Url(bytes: Uint8Array): string {
+	let bin = ''
+	for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+	return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function fromBase64Url(str: string): Uint8Array {
+	const padded = str.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (str.length % 4)) % 4)
+	const bin = atob(padded)
+	const bytes = new Uint8Array(bin.length)
+	for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+	return bytes
+}
+
+async function importKey(secret: string): Promise<CryptoKey> {
+	return crypto.subtle.importKey(
+		'raw',
+		encoder.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign', 'verify'],
+	)
+}
+
+async function sign(secret: string, data: string): Promise<string> {
+	const key = await importKey(secret)
+	const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(data))
+	return toBase64Url(new Uint8Array(sig))
+}
+
+async function verify(secret: string, data: string, signatureB64: string): Promise<boolean> {
+	const key = await importKey(secret)
+	const sig = fromBase64Url(signatureB64)
+	return crypto.subtle.verify('HMAC', key, sig.buffer as ArrayBuffer, encoder.encode(data))
+}
+
+function randomNonce(): string {
+	const bytes = new Uint8Array(16)
+	crypto.getRandomValues(bytes)
+	let hex = ''
+	for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, '0')
+	return hex
+}
+
+export async function issueSession(
+	payload: Omit<SessionPayload, 'nonce'>,
+	secret: string,
+): Promise<string> {
+	const full: SessionPayload = { ...payload, nonce: randomNonce() }
+	const payloadB64 = toBase64Url(encoder.encode(JSON.stringify(full)))
+	const sig = await sign(secret, payloadB64)
+	return `${payloadB64}.${sig}`
+}
+
+export async function verifySession(
+	cookie: string,
+	secret: string,
+	requestedVideoId: string,
+): Promise<SessionPayload | null> {
+	const dot = cookie.indexOf('.')
+	if (dot === -1) return null
+	const payloadB64 = cookie.slice(0, dot)
+	const sig = cookie.slice(dot + 1)
+	if (!payloadB64 || !sig) return null
+	if (!(await verify(secret, payloadB64, sig))) return null
+
+	let payload: SessionPayload
+	try {
+		payload = JSON.parse(decoder.decode(fromBase64Url(payloadB64))) as SessionPayload
+	} catch {
+		return null
+	}
+
+	const now = Math.floor(Date.now() / 1000)
+	if (payload.expiresAt <= now) return null
+
+	if (
+		payload.videoIds !== '*' &&
+		(!Array.isArray(payload.videoIds) || !payload.videoIds.includes(requestedVideoId))
+	) {
+		return null
+	}
+
+	return payload
+}

package/src/utils/text-tracks.ts

@@ -0,0 +1,100 @@
+import type { VttCue } from '../types.js'
+import { parseVtt } from './captions.js'
+import { captionsKey, chaptersKey } from './keys.js'
+
+export interface VideoTextTrackBucket {
+	put(
+		key: string,
+		value: string,
+		options?: { httpMetadata?: { contentType?: string } },
+	): Promise<{ etag?: string } | undefined>
+	get(key: string): Promise<{ text(): Promise<string> } | null>
+}
+
+export interface VideoTextTrackWriteResult {
+	key: string
+	etag?: string
+}
+
+export interface VideoTextTrackReadResult {
+	key: string
+	vtt: string
+	cues: VttCue[]
+}
+
+export interface CaptionsVttOptions {
+	bucket: VideoTextTrackBucket
+	videoId: string
+	vtt: string
+	language?: string
+}
+
+export interface ReadCaptionsVttOptions {
+	bucket: VideoTextTrackBucket
+	videoId: string
+	language?: string
+}
+
+export interface ChaptersVttOptions {
+	bucket: VideoTextTrackBucket
+	videoId: string
+	vtt: string
+}
+
+export interface ReadChaptersVttOptions {
+	bucket: VideoTextTrackBucket
+	videoId: string
+}
+
+function assertValidVtt(vtt: string): VttCue[] {
+	const cues = parseVtt(vtt)
+	if (!cues) throw new Error('Expected valid WEBVTT text')
+	return cues
+}
+
+async function putVtt(
+	bucket: VideoTextTrackBucket,
+	key: string,
+	vtt: string,
+): Promise<VideoTextTrackWriteResult> {
+	assertValidVtt(vtt)
+	const result = await bucket.put(key, vtt, {
+		httpMetadata: { contentType: 'text/vtt; charset=utf-8' },
+	})
+	return { key, etag: result?.etag }
+}
+
+async function readVtt(
+	bucket: VideoTextTrackBucket,
+	key: string,
+): Promise<VideoTextTrackReadResult | null> {
+	const object = await bucket.get(key)
+	if (!object) return null
+	const vtt = await object.text()
+	const cues = assertValidVtt(vtt)
+	return { key, vtt, cues }
+}
+
+export async function writeCaptionsVtt(
+	options: CaptionsVttOptions,
+): Promise<VideoTextTrackWriteResult> {
+	return putVtt(options.bucket, captionsKey(options.videoId, options.language), options.vtt)
+}
+
+export async function readCaptionsVtt(
+	options: ReadCaptionsVttOptions,
+): Promise<VideoTextTrackReadResult | null> {
+	return readVtt(options.bucket, captionsKey(options.videoId, options.language))
+}
+
+export async function writeChaptersVtt(
+	options: ChaptersVttOptions,
+): Promise<VideoTextTrackWriteResult> {
+	return putVtt(options.bucket, chaptersKey(options.videoId), options.vtt)
+}
+
+export async function readChaptersVtt(
+	options: ReadChaptersVttOptions,
+): Promise<VideoTextTrackReadResult | null> {
+	return readVtt(options.bucket, chaptersKey(options.videoId))
+}

package/src/utils/url.ts

@@ -0,0 +1,41 @@
+export function manifestUrl(publicDomain: string, videoId: string): string {
+	return `https://${publicDomain}/video/${videoId}/hls/master.m3u8`
+}
+
+export function posterUrl(publicDomain: string, videoId: string): string {
+	return `https://${publicDomain}/cdn-cgi/image/width=1200,height=675,fit=cover,quality=80,format=auto/video/${videoId}/poster.jpg`
+}
+
+export function captionsUrl(publicDomain: string, videoId: string, lang: string = 'en'): string {
+	const normalized =
+		lang
+			.trim()
+			.toLowerCase()
+			.replace(/[^a-z0-9-]/g, '_') || 'en'
+	return `https://${publicDomain}/video/${videoId}/captions_${normalized}.vtt`
+}
+
+export function chaptersUrl(publicDomain: string, videoId: string): string {
+	return `https://${publicDomain}/video/${videoId}/chapters.vtt`
+}
+
+export function chaptersJsonUrl(publicDomain: string, videoId: string): string {
+	return `https://${publicDomain}/video/${videoId}/chapters.json`
+}
+
+function normalizeRoute(route: string): string {
+	return route.endsWith('/') ? route.slice(0, -1) : route
+}
+
+export function premiumManifestUrl(playbackRoute: string, videoId: string): string {
+	return `${normalizeRoute(playbackRoute)}/${videoId}/hls/master.m3u8`
+}
+
+export function premiumPlaybackUrl(
+	playbackRoute: string,
+	videoId: string,
+	subpath: string,
+): string {
+	const trimmed = subpath.startsWith('/') ? subpath.slice(1) : subpath
+	return `${normalizeRoute(playbackRoute)}/${videoId}/${trimmed}`
+}