@fnd-platform/api 1.0.0-alpha.1 → 1.0.0-alpha.11

package/lib/api-project.js

@@ -81,7 +81,6 @@ class FndApiProject extends projen_1.typescript.TypeScriptProject {
                     rootDir: 'src',
                     declaration: true,
                     declarationMap: true,
-                    sourceMap: true,
                     strict: true,
                     esModuleInterop: true,
                     skipLibCheck: true,
@@ -99,6 +98,8 @@ class FndApiProject extends projen_1.typescript.TypeScriptProject {
         this.dynamodbEnabled = options.dynamodb ?? true;
         this.cognitoEnabled = options.cognito ?? true;
         this.corsEnabled = options.cors ?? true;
+        // Add @fnd-platform/api to parent's devDependencies (for .projenrc.ts imports)
+        this.parentProject.addDevDeps('@fnd-platform/api@^1.0.0-alpha.1');
         // Add dependencies
         this.addApiDependencies();
         // Generate directory structure and files
@@ -114,6 +115,8 @@ class FndApiProject extends projen_1.typescript.TypeScriptProject {
         if (this.dynamodbEnabled) {
             this.addDeps('@aws-sdk/client-dynamodb', '@aws-sdk/lib-dynamodb');
         }
+        // S3 dependencies for media uploads
+        this.addDeps('@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner');
         // Dev dependencies
         this.addDevDeps('@types/aws-lambda', 'esbuild', 'vitest', '@vitest/coverage-v8');
     }
@@ -125,6 +128,16 @@ class FndApiProject extends projen_1.typescript.TypeScriptProject {
         new projen_1.SampleFile(this, 'src/handlers/health.ts', {
             contents: this.getHealthHandlerTemplate(),
         });
+        // Content CRUD handler - included when DynamoDB is enabled
+        if (this.dynamodbEnabled) {
+            new projen_1.SampleFile(this, 'src/handlers/content.ts', {
+                contents: this.getContentHandlerTemplate(),
+            });
+        }
+        // Media upload handler - always included for S3 uploads
+        new projen_1.SampleFile(this, 'src/handlers/media.ts', {
+            contents: this.getMediaHandlerTemplate(),
+        });
     }
     /**
      * Generates the lib directory with utility files.
@@ -138,6 +151,16 @@ class FndApiProject extends projen_1.typescript.TypeScriptProject {
         new projen_1.SampleFile(this, 'src/lib/errors.ts', {
             contents: this.getErrorsTemplate(),
         });
+        // Request utilities
+        new projen_1.SampleFile(this, 'src/lib/request.ts', {
+            contents: this.getRequestTemplate(),
+        });
+        // DynamoDB key builders (included when DynamoDB is enabled)
+        if (this.dynamodbEnabled) {
+            new projen_1.SampleFile(this, 'src/lib/keys.ts', {
+                contents: this.getKeysTemplate(),
+            });
+        }
         // Middleware utilities (stub for Sprint 03)
         new projen_1.SampleFile(this, 'src/lib/middleware.ts', {
             contents: this.getMiddlewareTemplate(),
@@ -661,6 +684,953 @@ export interface UserEntity extends BaseEntity {
 }
 
 // Add your custom entity types below
+`;
+    }
+    /**
+     * Returns the request utilities template content.
+     */
+    getRequestTemplate() {
+        return `import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { ValidationError, UnauthorizedError } from './errors';
+
+/**
+ * API Gateway event with Cognito authorizer claims.
+ */
+interface AuthenticatedEvent extends APIGatewayProxyEvent {
+  requestContext: APIGatewayProxyEvent['requestContext'] & {
+    authorizer: {
+      claims: {
+        sub: string;
+        email: string;
+        'cognito:groups'?: string[];
+      };
+    };
+  };
+}
+
+/**
+ * Parse JSON body from API Gateway event.
+ *
+ * @param event - API Gateway proxy event
+ * @returns Parsed JSON body as type T
+ * @throws {ValidationError} If body is missing or invalid JSON
+ */
+export function parseBody<T>(event: APIGatewayProxyEvent): T {
+  if (!event.body) {
+    throw new ValidationError('Request body is required');
+  }
+
+  try {
+    return JSON.parse(event.body) as T;
+  } catch {
+    throw new ValidationError('Invalid JSON in request body');
+  }
+}
+
+/**
+ * Get a required path parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the path parameter
+ * @returns The path parameter value
+ * @throws {ValidationError} If the parameter is missing
+ */
+export function requirePathParam(event: APIGatewayProxyEvent, name: string): string {
+  const value = event.pathParameters?.[name];
+  if (!value) {
+    throw new ValidationError(\`Missing path parameter: \${name}\`);
+  }
+  return value;
+}
+
+/**
+ * Get an optional query parameter from the event.
+ *
+ * @param event - API Gateway proxy event
+ * @param name - Name of the query parameter
+ * @param defaultValue - Optional default value if parameter is missing
+ * @returns The query parameter value or default
+ */
+export function getQueryParam(
+  event: APIGatewayProxyEvent,
+  name: string,
+  defaultValue?: string
+): string | undefined {
+  return event.queryStringParameters?.[name] ?? defaultValue;
+}
+
+/**
+ * Get user ID from an authenticated request.
+ *
+ * @param event - Authenticated API Gateway event
+ * @returns The user ID from the JWT token
+ * @throws {UnauthorizedError} If user ID is not found in the token
+ */
+export function getUserId(event: AuthenticatedEvent): string {
+  const userId = event.requestContext.authorizer?.claims?.sub;
+  if (!userId) {
+    throw new UnauthorizedError('User ID not found in token');
+  }
+  return userId;
+}
+`;
+    }
+    /**
+     * Returns the DynamoDB key builders template content.
+     */
+    getKeysTemplate() {
+        return `/**
+ * DynamoDB key builders for single-table design.
+ *
+ * These helpers generate consistent key structures for content entities
+ * following the fnd-platform single-table design patterns.
+ */
+
+/**
+ * Key structure for DynamoDB primary key.
+ */
+export interface PrimaryKey {
+  PK: string;
+  SK: string;
+}
+
+/**
+ * Key structure for GSI1 (slug lookup).
+ */
+export interface GSI1Key {
+  GSI1PK: string;
+  GSI1SK: string;
+}
+
+/**
+ * Key structure for GSI2 (type/status listing).
+ */
+export interface GSI2Key {
+  GSI2PK: string;
+  GSI2SK: string;
+}
+
+/**
+ * Content key builders for DynamoDB operations.
+ */
+export const contentKeys = {
+  /**
+   * Generate partition key for content item.
+   */
+  pk: (id: string): string => \`CONTENT#\${id}\`,
+
+  /**
+   * Generate sort key for content item.
+   */
+  sk: (): string => 'CONTENT',
+
+  /**
+   * Generate full primary key for content item.
+   */
+  keys: (id: string): PrimaryKey => ({
+    PK: contentKeys.pk(id),
+    SK: contentKeys.sk(),
+  }),
+
+  /**
+   * GSI1 key builders for slug-based lookups.
+   */
+  gsi1: {
+    /**
+     * Generate GSI1 keys for looking up content by slug.
+     */
+    bySlug: (slug: string): GSI1Key => ({
+      GSI1PK: \`CONTENT#SLUG#\${slug}\`,
+      GSI1SK: 'CONTENT',
+    }),
+  },
+
+  /**
+   * GSI2 key builders for listing content by type.
+   */
+  gsi2: {
+    /**
+     * Generate GSI2 keys for listing content by type with timestamp sorting.
+     */
+    byType: (contentType: string, timestamp: string): GSI2Key => ({
+      GSI2PK: contentType,
+      GSI2SK: timestamp,
+    }),
+  },
+};
+
+/**
+ * User key builders for DynamoDB operations.
+ */
+export const userKeys = {
+  /**
+   * Generate partition key for user.
+   */
+  pk: (id: string): string => \`USER#\${id}\`,
+
+  /**
+   * Sort key generators for user-related items.
+   */
+  sk: {
+    /**
+     * Generate sort key for user profile.
+     */
+    profile: (): string => 'PROFILE',
+  },
+
+  /**
+   * Generate full primary key for user profile.
+   */
+  keys: (id: string): PrimaryKey => ({
+    PK: userKeys.pk(id),
+    SK: userKeys.sk.profile(),
+  }),
+};
+`;
+    }
+    /**
+     * Returns the content handler template content.
+     */
+    getContentHandlerTemplate() {
+        return `/**
+ * Content CRUD handlers with DynamoDB operations.
+ *
+ * Implements full CRUD operations for content entities using
+ * single-table design patterns with GSI support for efficient queries.
+ */
+
+import type { APIGatewayProxyHandler, APIGatewayProxyEvent } from 'aws-lambda';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  DynamoDBDocumentClient,
+  QueryCommand,
+  GetCommand,
+  PutCommand,
+  UpdateCommand,
+  DeleteCommand,
+} from '@aws-sdk/lib-dynamodb';
+import { success, notFound, created, badRequest } from '../lib/response';
+import { parseBody, requirePathParam, getQueryParam, getUserId } from '../lib/request';
+import { contentKeys } from '../lib/keys';
+
+/**
+ * Content item interface.
+ */
+interface ContentItem {
+  id: string;
+  slug: string;
+  title: string;
+  excerpt?: string;
+  content: string;
+  contentType: string;
+  status: 'draft' | 'published';
+  authorId: string;
+  createdAt: string;
+  updatedAt: string;
+  publishedAt?: string;
+}
+
+/**
+ * Input for creating new content.
+ */
+interface CreateContentInput {
+  slug: string;
+  title: string;
+  excerpt?: string;
+  content: string;
+  contentType: string;
+  status?: 'draft' | 'published';
+}
+
+/**
+ * Input for updating existing content.
+ */
+interface UpdateContentInput {
+  slug?: string;
+  title?: string;
+  excerpt?: string;
+  content?: string;
+  contentType?: string;
+  status?: 'draft' | 'published';
+}
+
+/**
+ * Authenticated event type with Cognito claims.
+ */
+interface AuthenticatedEvent extends APIGatewayProxyEvent {
+  requestContext: APIGatewayProxyEvent['requestContext'] & {
+    authorizer: {
+      claims: { sub: string; email: string; 'cognito:groups'?: string[] };
+    };
+  };
+}
+
+// Initialize DynamoDB client
+const ddbClient = new DynamoDBClient({});
+const client = DynamoDBDocumentClient.from(ddbClient, {
+  marshallOptions: {
+    removeUndefinedValues: true,
+  },
+});
+
+const TABLE_NAME = process.env.TABLE_NAME ?? '';
+
+/**
+ * Map DynamoDB item to ContentItem.
+ */
+function mapToContentItem(item: Record<string, unknown>): ContentItem {
+  return {
+    id: item.id as string,
+    slug: item.slug as string,
+    title: item.title as string,
+    excerpt: item.excerpt as string | undefined,
+    content: item.content as string,
+    contentType: item.contentType as string,
+    status: item.status as 'draft' | 'published',
+    authorId: item.authorId as string,
+    createdAt: item.createdAt as string,
+    updatedAt: item.updatedAt as string,
+    publishedAt: item.publishedAt as string | undefined,
+  };
+}
+
+/**
+ * GET /content - List content items.
+ */
+export const list: APIGatewayProxyHandler = async (event) => {
+  const limit = Math.min(parseInt(getQueryParam(event, 'limit', '20') ?? '20', 10), 100);
+  const cursor = getQueryParam(event, 'cursor');
+  const contentType = getQueryParam(event, 'type') ?? 'blog-post';
+  const status = getQueryParam(event, 'status') ?? 'published';
+
+  const result = await client.send(
+    new QueryCommand({
+      TableName: TABLE_NAME,
+      IndexName: 'GSI2',
+      KeyConditionExpression: 'GSI2PK = :pk',
+      FilterExpression: '#status = :status',
+      ExpressionAttributeNames: { '#status': 'status' },
+      ExpressionAttributeValues: {
+        ':pk': contentType,
+        ':status': status,
+      },
+      ScanIndexForward: false,
+      Limit: limit,
+      ExclusiveStartKey: cursor
+        ? JSON.parse(Buffer.from(cursor, 'base64').toString())
+        : undefined,
+    })
+  );
+
+  const items = (result.Items ?? []).map(mapToContentItem);
+
+  return success({
+    items,
+    nextCursor: result.LastEvaluatedKey
+      ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString('base64')
+      : undefined,
+  });
+};
+
+/**
+ * GET /content/:id - Get content by ID.
+ */
+export const get: APIGatewayProxyHandler = async (event) => {
+  const id = requirePathParam(event, 'id');
+  const keys = contentKeys.keys(id);
+
+  const result = await client.send(
+    new GetCommand({
+      TableName: TABLE_NAME,
+      Key: keys,
+    })
+  );
+
+  if (!result.Item) {
+    return notFound(\`Content with id '\${id}' not found\`);
+  }
+
+  return success(mapToContentItem(result.Item));
+};
+
+/**
+ * GET /content/slug/:slug - Get content by slug.
+ */
+export const getBySlug: APIGatewayProxyHandler = async (event) => {
+  const slug = requirePathParam(event, 'slug');
+  const gsi1Keys = contentKeys.gsi1.bySlug(slug);
+
+  const result = await client.send(
+    new QueryCommand({
+      TableName: TABLE_NAME,
+      IndexName: 'GSI1',
+      KeyConditionExpression: 'GSI1PK = :pk AND GSI1SK = :sk',
+      ExpressionAttributeValues: {
+        ':pk': gsi1Keys.GSI1PK,
+        ':sk': gsi1Keys.GSI1SK,
+      },
+      Limit: 1,
+    })
+  );
+
+  if (!result.Items?.length) {
+    return notFound(\`Content with slug '\${slug}' not found\`);
+  }
+
+  return success(mapToContentItem(result.Items[0]));
+};
+
+/**
+ * POST /content - Create new content.
+ */
+export const create: APIGatewayProxyHandler = async (event) => {
+  const body = parseBody<CreateContentInput>(event);
+
+  if (!body.slug || !body.title || !body.content || !body.contentType) {
+    return badRequest('Missing required fields: slug, title, content, contentType');
+  }
+
+  if (!/^[a-z0-9-]+$/.test(body.slug)) {
+    return badRequest('Slug must contain only lowercase letters, numbers, and hyphens');
+  }
+
+  // Check slug uniqueness
+  const gsi1Keys = contentKeys.gsi1.bySlug(body.slug);
+  const existingResult = await client.send(
+    new QueryCommand({
+      TableName: TABLE_NAME,
+      IndexName: 'GSI1',
+      KeyConditionExpression: 'GSI1PK = :pk AND GSI1SK = :sk',
+      ExpressionAttributeValues: {
+        ':pk': gsi1Keys.GSI1PK,
+        ':sk': gsi1Keys.GSI1SK,
+      },
+      Limit: 1,
+    })
+  );
+
+  if (existingResult.Items?.length) {
+    return badRequest(\`Content with slug '\${body.slug}' already exists\`);
+  }
+
+  const authorId = getUserId(event as AuthenticatedEvent);
+  const now = new Date().toISOString();
+  const id = crypto.randomUUID();
+  const status = body.status ?? 'draft';
+
+  const keys = contentKeys.keys(id);
+  const gsi2Keys = contentKeys.gsi2.byType(body.contentType, now);
+
+  const item = {
+    ...keys,
+    ...gsi1Keys,
+    ...gsi2Keys,
+    id,
+    slug: body.slug,
+    title: body.title,
+    excerpt: body.excerpt,
+    content: body.content,
+    contentType: body.contentType,
+    status,
+    authorId,
+    createdAt: now,
+    updatedAt: now,
+    publishedAt: status === 'published' ? now : undefined,
+  };
+
+  await client.send(
+    new PutCommand({
+      TableName: TABLE_NAME,
+      Item: item,
+    })
+  );
+
+  return created(mapToContentItem(item));
+};
+
+/**
+ * PUT /content/:id - Update content.
+ */
+export const update: APIGatewayProxyHandler = async (event) => {
+  const id = requirePathParam(event, 'id');
+  const body = parseBody<UpdateContentInput>(event);
+  const keys = contentKeys.keys(id);
+
+  const existingResult = await client.send(
+    new GetCommand({
+      TableName: TABLE_NAME,
+      Key: keys,
+    })
+  );
+
+  if (!existingResult.Item) {
+    return notFound(\`Content with id '\${id}' not found\`);
+  }
+
+  const existingItem = existingResult.Item;
+  const now = new Date().toISOString();
+
+  // Build update expression
+  const updateExpressionParts: string[] = ['#updatedAt = :updatedAt'];
+  const expressionAttributeNames: Record<string, string> = { '#updatedAt': 'updatedAt' };
+  const expressionAttributeValues: Record<string, unknown> = { ':updatedAt': now };
+
+  if (body.slug && body.slug !== existingItem.slug) {
+    if (!/^[a-z0-9-]+$/.test(body.slug)) {
+      return badRequest('Slug must contain only lowercase letters, numbers, and hyphens');
+    }
+    const newGsi1Keys = contentKeys.gsi1.bySlug(body.slug);
+    updateExpressionParts.push('#slug = :slug', 'GSI1PK = :gsi1pk', 'GSI1SK = :gsi1sk');
+    expressionAttributeNames['#slug'] = 'slug';
+    expressionAttributeValues[':slug'] = body.slug;
+    expressionAttributeValues[':gsi1pk'] = newGsi1Keys.GSI1PK;
+    expressionAttributeValues[':gsi1sk'] = newGsi1Keys.GSI1SK;
+  }
+
+  if (body.title !== undefined) {
+    updateExpressionParts.push('#title = :title');
+    expressionAttributeNames['#title'] = 'title';
+    expressionAttributeValues[':title'] = body.title;
+  }
+
+  if (body.excerpt !== undefined) {
+    updateExpressionParts.push('excerpt = :excerpt');
+    expressionAttributeValues[':excerpt'] = body.excerpt;
+  }
+
+  if (body.content !== undefined) {
+    updateExpressionParts.push('#content = :content');
+    expressionAttributeNames['#content'] = 'content';
+    expressionAttributeValues[':content'] = body.content;
+  }
+
+  if (body.contentType !== undefined) {
+    const newGsi2Keys = contentKeys.gsi2.byType(body.contentType, existingItem.createdAt as string);
+    updateExpressionParts.push('contentType = :contentType', 'GSI2PK = :gsi2pk');
+    expressionAttributeValues[':contentType'] = body.contentType;
+    expressionAttributeValues[':gsi2pk'] = newGsi2Keys.GSI2PK;
+  }
+
+  if (body.status !== undefined) {
+    updateExpressionParts.push('#status = :status');
+    expressionAttributeNames['#status'] = 'status';
+    expressionAttributeValues[':status'] = body.status;
+
+    if (body.status === 'published' && !existingItem.publishedAt) {
+      updateExpressionParts.push('publishedAt = :publishedAt');
+      expressionAttributeValues[':publishedAt'] = now;
+    }
+  }
+
+  const result = await client.send(
+    new UpdateCommand({
+      TableName: TABLE_NAME,
+      Key: keys,
+      UpdateExpression: \`SET \${updateExpressionParts.join(', ')}\`,
+      ExpressionAttributeNames: expressionAttributeNames,
+      ExpressionAttributeValues: expressionAttributeValues,
+      ReturnValues: 'ALL_NEW',
+    })
+  );
+
+  return success(mapToContentItem(result.Attributes!));
+};
+
+/**
+ * DELETE /content/:id - Delete content.
+ */
+export const remove: APIGatewayProxyHandler = async (event) => {
+  const id = requirePathParam(event, 'id');
+  const keys = contentKeys.keys(id);
+
+  const existingResult = await client.send(
+    new GetCommand({
+      TableName: TABLE_NAME,
+      Key: keys,
+    })
+  );
+
+  if (!existingResult.Item) {
+    return notFound(\`Content with id '\${id}' not found\`);
+  }
+
+  await client.send(
+    new DeleteCommand({
+      TableName: TABLE_NAME,
+      Key: keys,
+    })
+  );
+
+  return success({ deleted: true, id });
+};
+
+/**
+ * Main router handler for content operations.
+ *
+ * Routes requests to the appropriate CRUD function based on HTTP method and path.
+ * This handler is invoked by API Gateway and delegates to the specific operation.
+ *
+ * @example
+ * // API Gateway routes:
+ * // GET /content -> list
+ * // POST /content -> create
+ * // GET /content/{id} -> get
+ * // PUT /content/{id} -> update
+ * // DELETE /content/{id} -> remove
+ * // GET /content/slug/{slug} -> getBySlug
+ */
+export const handler: APIGatewayProxyHandler = async (event, context, callback) => {
+  const method = event.httpMethod;
+  const resource = event.resource;
+
+  try {
+    // Route to the appropriate handler based on resource and method
+    let result: Awaited<ReturnType<typeof list>> | undefined;
+
+    switch (resource) {
+      case '/content':
+        if (method === 'GET') result = await list(event, context, callback);
+        else if (method === 'POST') result = await create(event, context, callback);
+        break;
+      case '/content/{id}':
+        if (method === 'GET') result = await get(event, context, callback);
+        else if (method === 'PUT') result = await update(event, context, callback);
+        else if (method === 'DELETE') result = await remove(event, context, callback);
+        break;
+      case '/content/slug/{slug}':
+        if (method === 'GET') result = await getBySlug(event, context, callback);
+        break;
+    }
+
+    if (result) {
+      return result;
+    }
+
+    return {
+      statusCode: 405,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        success: false,
+        error: {
+          code: 'METHOD_NOT_ALLOWED',
+          message: \`Method \${method} not allowed for \${resource}\`,
+        },
+      }),
+    };
+  } catch (error) {
+    console.error('Content handler error:', error);
+    return {
+      statusCode: 500,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        success: false,
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: 'Internal server error',
+        },
+      }),
+    };
+  }
+};
+`;
+    }
+    /**
+     * Returns the media handler template content.
+     */
+    getMediaHandlerTemplate() {
+        return `/**
+ * Media upload and management handler.
+ *
+ * Provides endpoints for uploading files to S3 using presigned URLs
+ * and managing media records.
+ */
+
+import type { APIGatewayProxyHandler } from 'aws-lambda';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { success, notFound, created, badRequest } from '../lib/response';
+import { parseBody, requirePathParam, getQueryParam } from '../lib/request';
+
+/**
+ * Allowed media MIME types.
+ */
+const ALLOWED_MIME_TYPES = [
+  'image/jpeg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+  'application/pdf',
+  'video/mp4',
+  'video/webm',
+  'audio/mpeg',
+  'audio/wav',
+  'audio/ogg',
+];
+
+/**
+ * Maximum file size in bytes (50MB default).
+ */
+const MAX_FILE_SIZE = parseInt(process.env.MAX_FILE_SIZE || '52428800', 10);
+
+/**
+ * S3 bucket name for media storage.
+ */
+const BUCKET_NAME = process.env.MEDIA_BUCKET_NAME || '';
+
+/**
+ * Base URL for media access (CloudFront or S3).
+ */
+const MEDIA_BASE_URL = process.env.MEDIA_BASE_URL || '';
+
+/**
+ * Presigned URL expiration time in seconds.
+ */
+const PRESIGNED_URL_EXPIRES_IN = 300;
+
+/**
+ * S3 client instance.
+ */
+const s3Client = new S3Client({});
+
+/**
+ * Media item interface.
+ */
+interface MediaItem {
+  id: string;
+  key: string;
+  filename: string;
+  mimeType: string;
+  size: number;
+  url: string;
+  uploadedAt: string;
+  uploadedBy?: string;
+}
+
+/**
+ * Paginated response structure.
+ */
+interface PaginatedResponse<T> {
+  items: T[];
+  nextCursor?: string;
+  total?: number;
+}
+
+/**
+ * Generates a unique ID for media items.
+ */
+function generateId(): string {
+  const timestamp = Date.now().toString(36);
+  const randomPart = Math.random().toString(36).substring(2, 10);
+  return \`\${timestamp}\${randomPart}\`;
+}
+
+/**
+ * Extracts file extension from MIME type.
+ */
+function getExtensionFromMimeType(mimeType: string): string {
+  const mimeToExt: Record<string, string> = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'application/pdf': 'pdf',
+    'video/mp4': 'mp4',
+    'video/webm': 'webm',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+    'audio/ogg': 'ogg',
+  };
+  return mimeToExt[mimeType] || 'bin';
+}
+
+/**
+ * Validates the content type is allowed.
+ */
+function isValidContentType(contentType: string): boolean {
+  return ALLOWED_MIME_TYPES.includes(contentType);
+}
+
+/**
+ * POST /media/upload-url - Get a presigned URL for direct S3 upload.
+ */
+export const getUploadUrl: APIGatewayProxyHandler = async (event) => {
+  const body = parseBody<{
+    filename: string;
+    contentType: string;
+    size: number;
+  }>(event);
+
+  if (!body.filename || !body.contentType || !body.size) {
+    return badRequest('Missing required fields: filename, contentType, size');
+  }
+
+  if (!isValidContentType(body.contentType)) {
+    return badRequest(
+      \`Invalid content type: \${body.contentType}. Allowed types: \${ALLOWED_MIME_TYPES.join(', ')}\`
+    );
+  }
+
+  if (body.size > MAX_FILE_SIZE) {
+    return badRequest(
+      \`File size \${body.size} exceeds maximum allowed size of \${MAX_FILE_SIZE} bytes\`
+    );
+  }
+
+  const id = generateId();
+  const ext = getExtensionFromMimeType(body.contentType);
+  const datePath = new Date().toISOString().slice(0, 7);
+  const key = \`uploads/\${datePath}/\${id}.\${ext}\`;
+
+  const command = new PutObjectCommand({
+    Bucket: BUCKET_NAME,
+    Key: key,
+    ContentType: body.contentType,
+    ContentLength: body.size,
+    Metadata: {
+      'original-filename': encodeURIComponent(body.filename),
+    },
+  });
+
+  const uploadUrl = await getSignedUrl(s3Client, command, {
+    expiresIn: PRESIGNED_URL_EXPIRES_IN,
+  });
+
+  return success({
+    uploadUrl,
+    key,
+    id,
+    expiresIn: PRESIGNED_URL_EXPIRES_IN,
+  });
+};
+
+/**
+ * POST /media - Create a media record after successful S3 upload.
+ */
+export const create: APIGatewayProxyHandler = async (event) => {
+  const body = parseBody<{
+    id: string;
+    key: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+  }>(event);
+
+  if (!body.id || !body.key || !body.filename || !body.mimeType || !body.size) {
+    return badRequest('Missing required fields: id, key, filename, mimeType, size');
+  }
+
+  const url = MEDIA_BASE_URL
+    ? \`\${MEDIA_BASE_URL}/\${body.key}\`
+    : \`https://\${BUCKET_NAME}.s3.amazonaws.com/\${body.key}\`;
+
+  const media: MediaItem = {
+    id: body.id,
+    key: body.key,
+    filename: body.filename,
+    mimeType: body.mimeType,
+    size: body.size,
+    url,
+    uploadedAt: new Date().toISOString(),
+  };
+
+  return created(media);
+};
+
+/**
+ * GET /media - List media items with pagination.
+ */
+export const list: APIGatewayProxyHandler = async (event) => {
+  const _limit = parseInt(getQueryParam(event, 'limit', '20') ?? '20', 10);
+  const _cursor = getQueryParam(event, 'cursor');
+  const _type = getQueryParam(event, 'type');
+
+  // TODO: Implement with DynamoDB
+  const items: MediaItem[] = [];
+  const response: PaginatedResponse<MediaItem> = {
+    items,
+    nextCursor: undefined,
+    total: 0,
+  };
+
+  return success(response);
+};
+
+/**
+ * GET /media/:id - Get a single media item.
+ */
+export const get: APIGatewayProxyHandler = async (event) => {
+  const id = requirePathParam(event, 'id');
+
+  // TODO: Implement with DynamoDB
+  return notFound(\`Media with id '\${id}' not found\`);
+};
+
+/**
+ * DELETE /media/:id - Delete a media item.
+ */
+export const remove: APIGatewayProxyHandler = async (event) => {
+  const id = requirePathParam(event, 'id');
+
+  // TODO: Implement with DynamoDB and S3 deletion
+  return success({ deleted: true, id });
+};
+
+/**
+ * Main router handler for media operations.
+ */
+export const handler: APIGatewayProxyHandler = async (event, context, callback) => {
+  const method = event.httpMethod;
+  const resource = event.resource;
+
+  try {
+    let result: Awaited<ReturnType<typeof list>> | undefined;
+
+    switch (resource) {
+      case '/media':
+        if (method === 'GET') result = await list(event, context, callback);
+        else if (method === 'POST') result = await create(event, context, callback);
+        break;
+      case '/media/upload-url':
+        if (method === 'POST') result = await getUploadUrl(event, context, callback);
+        break;
+      case '/media/{id}':
+        if (method === 'GET') result = await get(event, context, callback);
+        else if (method === 'DELETE') result = await remove(event, context, callback);
+        break;
+    }
+
+    if (result) {
+      return result;
+    }
+
+    return {
+      statusCode: 405,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        success: false,
+        error: {
+          code: 'METHOD_NOT_ALLOWED',
+          message: \`Method \${method} not allowed for \${resource}\`,
+        },
+      }),
+    };
+  } catch (error) {
+    console.error('Media handler error:', error);
+    return {
+      statusCode: 500,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        success: false,
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: 'Internal server error',
+        },
+      }),
+    };
+  }
+};
 `;
     }
 }