convex-cms 0.0.1

package/dist/component/lib/metadataExtractor.js

@@ -0,0 +1,548 @@
+/**
+ * Media Metadata Extractor
+ *
+ * Internal utility functions for extracting and normalizing metadata from uploaded files.
+ * This module provides type-safe metadata extraction based on file MIME types.
+ *
+ * Since Convex functions don't have direct file access (files are in storage),
+ * this extractor works with:
+ * 1. Client-provided metadata (dimensions, duration from browser APIs)
+ * 2. MIME type analysis for capability detection
+ * 3. Filename analysis for additional hints
+ *
+ * The extractor normalizes and validates this information into a structured format
+ * that can be stored in the media asset's metadata field.
+ */
+// =============================================================================
+// MIME Type Mappings
+// =============================================================================
+/**
+ * MIME types classified as images.
+ */
+const IMAGE_MIME_TYPES = new Set([
+    "image/jpeg",
+    "image/jpg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "image/svg+xml",
+    "image/bmp",
+    "image/tiff",
+    "image/x-icon",
+    "image/ico",
+    "image/heic",
+    "image/heif",
+]);
+/**
+ * MIME types classified as videos.
+ */
+const VIDEO_MIME_TYPES = new Set([
+    "video/mp4",
+    "video/webm",
+    "video/ogg",
+    "video/quicktime",
+    "video/x-msvideo",
+    "video/mpeg",
+    "video/3gpp",
+    "video/x-matroska",
+    "video/x-flv",
+]);
+/**
+ * MIME types classified as audio.
+ */
+const AUDIO_MIME_TYPES = new Set([
+    "audio/mpeg",
+    "audio/mp3",
+    "audio/ogg",
+    "audio/wav",
+    "audio/webm",
+    "audio/aac",
+    "audio/flac",
+    "audio/x-m4a",
+    "audio/mp4",
+    "audio/x-wav",
+]);
+/**
+ * MIME types classified as documents.
+ */
+const DOCUMENT_MIME_TYPES = new Set([
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "text/plain",
+    "text/csv",
+    "text/markdown",
+    "application/rtf",
+    "application/json",
+    "application/xml",
+    "text/xml",
+]);
+/**
+ * MIME types that support transparency.
+ */
+const TRANSPARENT_MIME_TYPES = new Set([
+    "image/png",
+    "image/webp",
+    "image/gif",
+    "image/avif",
+    "image/svg+xml",
+]);
+/**
+ * Vector image MIME types.
+ */
+const VECTOR_MIME_TYPES = new Set(["image/svg+xml"]);
+/**
+ * MIME types that support animation.
+ */
+const ANIMATED_MIME_TYPES = new Set([
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "image/png", // APNG
+]);
+/**
+ * Web-compatible image MIME types (work natively in all modern browsers).
+ */
+const WEB_COMPATIBLE_IMAGE_TYPES = new Set([
+    "image/jpeg",
+    "image/jpg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+    "image/avif",
+]);
+/**
+ * Web-compatible video MIME types.
+ */
+const WEB_COMPATIBLE_VIDEO_TYPES = new Set([
+    "video/mp4",
+    "video/webm",
+    "video/ogg",
+]);
+/**
+ * Web-compatible audio MIME types.
+ */
+const WEB_COMPATIBLE_AUDIO_TYPES = new Set([
+    "audio/mpeg",
+    "audio/mp3",
+    "audio/ogg",
+    "audio/wav",
+    "audio/webm",
+    "audio/aac",
+]);
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Extracts the file extension from a filename.
+ *
+ * @param filename - The filename to extract the extension from
+ * @returns The lowercase extension without the dot, or empty string if none
+ */
+export function extractExtension(filename) {
+    const lastDot = filename.lastIndexOf(".");
+    if (lastDot === -1 || lastDot === filename.length - 1) {
+        return "";
+    }
+    return filename.slice(lastDot + 1).toLowerCase();
+}
+/**
+ * Classifies a MIME type into a media category.
+ *
+ * @param mimeType - The MIME type to classify
+ * @returns The media type category
+ */
+export function classifyMimeType(mimeType) {
+    const normalizedMime = mimeType.toLowerCase();
+    if (IMAGE_MIME_TYPES.has(normalizedMime)) {
+        return "image";
+    }
+    if (VIDEO_MIME_TYPES.has(normalizedMime)) {
+        return "video";
+    }
+    if (AUDIO_MIME_TYPES.has(normalizedMime)) {
+        return "audio";
+    }
+    if (DOCUMENT_MIME_TYPES.has(normalizedMime)) {
+        return "document";
+    }
+    // Fallback: check MIME type prefix
+    if (normalizedMime.startsWith("image/")) {
+        return "image";
+    }
+    if (normalizedMime.startsWith("video/")) {
+        return "video";
+    }
+    if (normalizedMime.startsWith("audio/")) {
+        return "audio";
+    }
+    if (normalizedMime.startsWith("text/") ||
+        normalizedMime.startsWith("application/")) {
+        // Check for common document patterns
+        if (normalizedMime.includes("document") ||
+            normalizedMime.includes("sheet") ||
+            normalizedMime.includes("presentation")) {
+            return "document";
+        }
+    }
+    return "other";
+}
+/**
+ * Calculates aspect ratio from dimensions.
+ *
+ * @param width - Width in pixels
+ * @param height - Height in pixels
+ * @returns Aspect ratio rounded to 3 decimal places, or undefined if invalid
+ */
+export function calculateAspectRatio(width, height) {
+    if (!width || !height || height <= 0 || width <= 0) {
+        return undefined;
+    }
+    return Math.round((width / height) * 1000) / 1000;
+}
+/**
+ * Formats duration in seconds to HH:MM:SS format.
+ *
+ * @param seconds - Duration in seconds
+ * @returns Formatted duration string, or undefined if invalid
+ */
+export function formatDuration(seconds) {
+    if (seconds === undefined || seconds < 0 || !Number.isFinite(seconds)) {
+        return undefined;
+    }
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+    if (hours > 0) {
+        return `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+    }
+    return `${minutes.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+}
+/**
+ * Determines the optimal image format for web delivery.
+ *
+ * @param mimeType - Original MIME type
+ * @param supportsTransparency - Whether transparency is needed
+ * @returns Suggested format for optimization
+ */
+export function suggestImageFormat(mimeType, supportsTransparency) {
+    const normalizedMime = mimeType.toLowerCase();
+    // SVG stays as SVG (vector)
+    if (normalizedMime === "image/svg+xml") {
+        return "svg";
+    }
+    // For photos/complex images, suggest modern formats
+    if (supportsTransparency) {
+        return "webp"; // WebP supports transparency and has broad support
+    }
+    // For photos without transparency, AVIF or WebP
+    if (normalizedMime === "image/jpeg" || normalizedMime === "image/jpg") {
+        return "webp"; // Better compression than JPEG
+    }
+    return "webp"; // Default to WebP for best compatibility
+}
+/**
+ * Categorizes document MIME types into subcategories.
+ *
+ * @param mimeType - The document MIME type
+ * @returns Document category
+ */
+export function categorizeDocument(mimeType) {
+    const normalizedMime = mimeType.toLowerCase();
+    if (normalizedMime === "application/pdf") {
+        return "pdf";
+    }
+    if (normalizedMime === "application/msword" ||
+        normalizedMime.includes("wordprocessingml")) {
+        return "word";
+    }
+    if (normalizedMime === "application/vnd.ms-excel" ||
+        normalizedMime.includes("spreadsheetml") ||
+        normalizedMime === "text/csv") {
+        return "spreadsheet";
+    }
+    if (normalizedMime === "application/vnd.ms-powerpoint" ||
+        normalizedMime.includes("presentationml")) {
+        return "presentation";
+    }
+    if (normalizedMime.startsWith("text/") ||
+        normalizedMime === "application/json" ||
+        normalizedMime === "application/xml") {
+        return "text";
+    }
+    return "other";
+}
+/**
+ * Determines if a document can be previewed in the browser.
+ *
+ * @param mimeType - The document MIME type
+ * @returns Whether the document can be previewed
+ */
+export function canPreviewDocument(mimeType) {
+    const normalizedMime = mimeType.toLowerCase();
+    // PDFs can be previewed in most browsers
+    if (normalizedMime === "application/pdf") {
+        return true;
+    }
+    // Text-based formats can be displayed
+    if (normalizedMime.startsWith("text/")) {
+        return true;
+    }
+    // JSON and XML can be displayed
+    if (normalizedMime === "application/json" ||
+        normalizedMime === "application/xml" ||
+        normalizedMime === "text/xml") {
+        return true;
+    }
+    return false;
+}
+// =============================================================================
+// Main Extraction Function
+// =============================================================================
+/**
+ * Extracts and normalizes metadata from uploaded file information.
+ *
+ * This is the main function to call for metadata extraction. It analyzes
+ * the MIME type, filename, and any provided dimensions/duration to build
+ * a comprehensive metadata object specific to the file type.
+ *
+ * @param input - The file information to extract metadata from
+ * @returns Structured metadata object with type-specific properties
+ *
+ * @example
+ * ```typescript
+ * // Image with dimensions from browser
+ * const imageMetadata = extractMetadata({
+ *   filename: "photo.jpg",
+ *   mimeType: "image/jpeg",
+ *   size: 500000,
+ *   width: 1920,
+ *   height: 1080,
+ * });
+ * // Returns ImageMetadata with aspectRatio, suggestedFormat, etc.
+ *
+ * // Video with duration from browser
+ * const videoMetadata = extractMetadata({
+ *   filename: "clip.mp4",
+ *   mimeType: "video/mp4",
+ *   size: 10000000,
+ *   width: 1920,
+ *   height: 1080,
+ *   duration: 120,
+ * });
+ * // Returns VideoMetadata with durationFormatted, hasBroadBrowserSupport, etc.
+ *
+ * // Document
+ * const docMetadata = extractMetadata({
+ *   filename: "report.pdf",
+ *   mimeType: "application/pdf",
+ *   size: 2000000,
+ *   pageCount: 15,
+ * });
+ * // Returns DocumentMetadata with documentCategory, canPreviewInBrowser, etc.
+ * ```
+ */
+export function extractMetadata(input) {
+    const { filename, mimeType, size, width, height, duration, pageCount } = input;
+    const normalizedMime = mimeType.toLowerCase();
+    const extension = extractExtension(filename);
+    const mediaType = classifyMimeType(normalizedMime);
+    // Build base metadata
+    const base = {
+        filename,
+        mimeType: normalizedMime,
+        size,
+        mediaType,
+        extension,
+        isWebCompatible: false, // Will be set by type-specific logic
+    };
+    switch (mediaType) {
+        case "image":
+            return extractImageMetadata(base, normalizedMime, width, height);
+        case "video":
+            return extractVideoMetadata(base, normalizedMime, width, height, duration);
+        case "audio":
+            return extractAudioMetadata(base, normalizedMime, duration);
+        case "document":
+            return extractDocumentMetadata(base, normalizedMime, pageCount);
+        default:
+            return {
+                ...base,
+                mediaType: "other",
+                isWebCompatible: false,
+            };
+    }
+}
+/**
+ * Extracts image-specific metadata.
+ */
+function extractImageMetadata(base, mimeType, width, height) {
+    const supportsTransparency = TRANSPARENT_MIME_TYPES.has(mimeType);
+    const isVector = VECTOR_MIME_TYPES.has(mimeType);
+    const supportsAnimation = ANIMATED_MIME_TYPES.has(mimeType);
+    const isWebCompatible = WEB_COMPATIBLE_IMAGE_TYPES.has(mimeType);
+    const metadata = {
+        ...base,
+        mediaType: "image",
+        isWebCompatible,
+        supportsTransparency,
+        isVector,
+        supportsAnimation,
+    };
+    if (width !== undefined && width > 0) {
+        metadata.width = width;
+    }
+    if (height !== undefined && height > 0) {
+        metadata.height = height;
+    }
+    const aspectRatio = calculateAspectRatio(width, height);
+    if (aspectRatio !== undefined) {
+        metadata.aspectRatio = aspectRatio;
+    }
+    const suggestedFormat = suggestImageFormat(mimeType, supportsTransparency);
+    if (suggestedFormat) {
+        metadata.suggestedFormat = suggestedFormat;
+    }
+    return metadata;
+}
+/**
+ * Extracts video-specific metadata.
+ */
+function extractVideoMetadata(base, mimeType, width, height, duration) {
+    const hasBroadBrowserSupport = WEB_COMPATIBLE_VIDEO_TYPES.has(mimeType);
+    const isWebCompatible = hasBroadBrowserSupport;
+    const metadata = {
+        ...base,
+        mediaType: "video",
+        isWebCompatible,
+        hasBroadBrowserSupport,
+    };
+    if (width !== undefined && width > 0) {
+        metadata.width = width;
+    }
+    if (height !== undefined && height > 0) {
+        metadata.height = height;
+    }
+    const aspectRatio = calculateAspectRatio(width, height);
+    if (aspectRatio !== undefined) {
+        metadata.aspectRatio = aspectRatio;
+    }
+    if (duration !== undefined && duration >= 0) {
+        metadata.duration = duration;
+        metadata.durationFormatted = formatDuration(duration);
+    }
+    // Infer codec from MIME type
+    if (mimeType === "video/mp4") {
+        metadata.codec = "H.264/AVC";
+    }
+    else if (mimeType === "video/webm") {
+        metadata.codec = "VP8/VP9";
+    }
+    else if (mimeType === "video/ogg") {
+        metadata.codec = "Theora";
+    }
+    return metadata;
+}
+/**
+ * Extracts audio-specific metadata.
+ */
+function extractAudioMetadata(base, mimeType, duration) {
+    const hasBroadBrowserSupport = WEB_COMPATIBLE_AUDIO_TYPES.has(mimeType);
+    const isWebCompatible = hasBroadBrowserSupport;
+    const metadata = {
+        ...base,
+        mediaType: "audio",
+        isWebCompatible,
+        hasBroadBrowserSupport,
+    };
+    if (duration !== undefined && duration >= 0) {
+        metadata.duration = duration;
+        metadata.durationFormatted = formatDuration(duration);
+    }
+    // Infer codec from MIME type
+    if (mimeType === "audio/mpeg" || mimeType === "audio/mp3") {
+        metadata.codec = "MP3";
+    }
+    else if (mimeType === "audio/ogg") {
+        metadata.codec = "Vorbis";
+    }
+    else if (mimeType === "audio/wav" || mimeType === "audio/x-wav") {
+        metadata.codec = "PCM";
+    }
+    else if (mimeType === "audio/aac") {
+        metadata.codec = "AAC";
+    }
+    else if (mimeType === "audio/flac") {
+        metadata.codec = "FLAC";
+    }
+    return metadata;
+}
+/**
+ * Extracts document-specific metadata.
+ */
+function extractDocumentMetadata(base, mimeType, pageCount) {
+    const documentCategory = categorizeDocument(mimeType);
+    const canPreview = canPreviewDocument(mimeType);
+    const metadata = {
+        ...base,
+        mediaType: "document",
+        isWebCompatible: canPreview,
+        documentCategory,
+        canPreviewInBrowser: canPreview,
+    };
+    if (pageCount !== undefined && pageCount > 0) {
+        metadata.pageCount = pageCount;
+    }
+    return metadata;
+}
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Validates that dimensions are positive integers.
+ *
+ * @param width - Width to validate
+ * @param height - Height to validate
+ * @returns Whether both dimensions are valid
+ */
+export function validateDimensions(width, height) {
+    if (width !== undefined) {
+        if (!Number.isInteger(width) || width <= 0) {
+            return false;
+        }
+    }
+    if (height !== undefined) {
+        if (!Number.isInteger(height) || height <= 0) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Validates that duration is a non-negative number.
+ *
+ * @param duration - Duration to validate
+ * @returns Whether the duration is valid
+ */
+export function validateDuration(duration) {
+    if (duration === undefined) {
+        return true;
+    }
+    return Number.isFinite(duration) && duration >= 0;
+}
+/**
+ * Validates that file size is a positive integer.
+ *
+ * @param size - File size to validate
+ * @returns Whether the size is valid
+ */
+export function validateFileSize(size) {
+    return Number.isInteger(size) && size > 0;
+}
+//# sourceMappingURL=metadataExtractor.js.map

package/dist/component/lib/metadataExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataExtractor.js","sourceRoot":"","sources":["../../../src/component/lib/metadataExtractor.ts"],"names":[],"mappings":"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"}

package/dist/component/lib/mutationAuth.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Mutation-Level Authorization Helper
+ *
+ * Provides defense-in-depth authorization for component mutations.
+ * When auth context is provided, mutations verify the role has permission.
+ *
+ * This complements the client wrapper's authorization:
+ * - Client wrapper: Primary authorization layer (runs hooks, RBAC)
+ * - Mutation auth: Secondary validation layer (pure RBAC check)
+ *
+ * @example
+ * ```typescript
+ * import { requireMutationAuth } from "./lib/mutationAuth.js";
+ *
+ * export const createEntry = mutation({
+ *   args: {
+ *     ...createContentEntryArgs.fields,
+ *     _auth: v.optional(mutationAuthContext),
+ *   },
+ *   handler: async (ctx, args) => {
+ *     requireMutationAuth(args._auth, "contentEntries", "create");
+ *     // ... mutation logic
+ *   },
+ * });
+ * ```
+ */
+import type { MutationAuthContext } from "../validators.js";
+import { type Resource, type Action, type RoleDefinition } from "../roles.js";
+/**
+ * Options for mutation authorization check.
+ */
+export interface MutationAuthOptions {
+    /**
+     * Custom role definitions to include in permission checks.
+     * These are in addition to the default roles (admin, editor, author, viewer).
+     */
+    customRoles?: Record<string, RoleDefinition>;
+}
+/**
+ * Verify the auth context has permission for the requested operation.
+ *
+ * This function:
+ * 1. If `_auth` is undefined, does nothing (backwards compatible)
+ * 2. If `_auth` is provided, checks the role has permission
+ * 3. Throws CMSError with PERMISSION_DENIED if check fails
+ *
+ * For ownership-scoped permissions (e.g., author editing their own content):
+ * - If the role only has "own" scope, verifies resourceOwnerId matches userId
+ * - If the role has "all" scope, ownership is not checked
+ *
+ * @param auth - The auth context from mutation args (may be undefined)
+ * @param resource - The resource being accessed (e.g., "contentEntries")
+ * @param action - The action being performed (e.g., "create", "update")
+ * @param options - Optional configuration including custom roles
+ * @throws CMSError with code PERMISSION_DENIED if authorization fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - check if role can create content entries
+ * requireMutationAuth(args._auth, "contentEntries", "create");
+ *
+ * // For update/delete - include resource owner for "own" scope check
+ * const entry = await ctx.db.get(args.id);
+ * requireMutationAuth(
+ *   { ...args._auth, resourceOwnerId: entry.createdBy },
+ *   "contentEntries",
+ *   "update"
+ * );
+ * ```
+ */
+export declare function requireMutationAuth(auth: MutationAuthContext | undefined, resource: Resource, action: Action, options?: MutationAuthOptions): void;
+/**
+ * Check if auth context has permission without throwing.
+ *
+ * Useful for conditional logic based on permissions.
+ *
+ * @param auth - The auth context from mutation args
+ * @param resource - The resource being accessed
+ * @param action - The action being performed
+ * @param options - Optional configuration including custom roles
+ * @returns true if authorized, false otherwise
+ */
+export declare function hasMutationAuth(auth: MutationAuthContext | undefined, resource: Resource, action: Action, options?: MutationAuthOptions): boolean;
+/**
+ * Augment auth context with resource owner information.
+ *
+ * Use this when you have an auth context and need to add ownership info
+ * for permission checks on existing resources.
+ *
+ * @param auth - The original auth context
+ * @param resourceOwnerId - The owner of the resource being accessed
+ * @returns Auth context with resourceOwnerId set
+ */
+export declare function withResourceOwner(auth: MutationAuthContext | undefined, resourceOwnerId: string | undefined): MutationAuthContext | undefined;
+//# sourceMappingURL=mutationAuth.d.ts.map

package/dist/component/lib/mutationAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationAuth.d.ts","sourceRoot":"","sources":["../../../src/component/lib/mutationAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAiB,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7F;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,GAAG,SAAS,EACrC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CAoDN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,mBAAmB,GAAG,SAAS,EACrC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CA6BT;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,mBAAmB,GAAG,SAAS,EACrC,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,mBAAmB,GAAG,SAAS,CAKjC"}