/**
 * Media Service v2 Type Definitions
 *
 * This file contains JSDoc type definitions for the Media Service v2 API.
 * Import types using: @typedef {import('./useMediaServiceV2.types').TypeName} TypeName
 *
 * @module useMediaServiceV2Types
 */

// ============================================================================
// ENUMS / CONSTANTS
// ============================================================================

/**
 * Account type for context resolution.
 * @typedef {"personal" | "instructor" | "enterprise"} AccountType
 */

/**
 * Upload type for file uploads.
 * @typedef {"put" | "multipart"} UploadType
 */

/**
 * Processing status for media files.
 * @typedef {"pending" | "processing" | "complete" | "failed"} ProcessingStatus
 */

// ============================================================================
// CONTEXT TYPES
// ============================================================================

/**
 * Context for API calls.
 * @typedef {Object} MediaServiceContext
 * @property {AccountType} [accountType] - The account type (personal/instructor/enterprise)
 * @property {string} [accountId] - The account ID for _account query param
 * @property {string} [enterpriseAccountId] - Enterprise ID for instructor affiliate context
 * @property {string} [affiliateAccountId] - Alias for enterpriseAccountId
 */

/**
 * Hook initialization options.
 * @typedef {Object} MediaServiceOptions
 * @property {AccountType} [accountType] - Override default account type
 * @property {string} [accountId] - Override default account ID
 * @property {string} [enterpriseAccountId] - Enterprise ID for instructor affiliate context
 * @property {string} [affiliateAccountId] - Alias for enterpriseAccountId
 */

// ============================================================================
// REQUEST TYPES
// ============================================================================

/**
 * File metadata for upload request.
 * @typedef {Object} FileUploadRequest
 * @property {string} name - Original filename (e.g., "intro.mp4")
 * @property {string} mimetype - MIME type (e.g., "video/mp4")
 * @property {number} size - File size in bytes
 * @property {UploadType} upload_type - Upload method ("put" for single, "multipart" for chunked)
 */

/**
 * Request payload for creating file records.
 * POST /files/
 * @typedef {Object} CreateFilesPayload
 * @property {string} [tag] - File tag/category (e.g., "lesson", "profile")
 * @property {string} [caption] - File caption/description
 * @property {string} [duration] - Duration in "HH:MM:SS" format (for audio/video)
 * @property {string} [lecture_id] - Associated lecture ID
 * @property {FileUploadRequest[]} files - Array of file metadata
 */

/**
 * Request payload for refreshing presigned upload URLs.
 * POST /files/{id}/presign_upload_urls/
 * @typedef {Object} PresignUploadUrlsPayload
 * @property {UploadType} upload_type - Upload method
 * @property {string} [upload_id] - Multipart upload ID (required for multipart)
 * @property {number[]} [part_numbers] - Part numbers to refresh (for multipart)
 */

/**
 * Multipart upload part for confirmation.
 * @typedef {Object} UploadPart
 * @property {string} ETag - ETag returned from S3 after uploading the part (include quotes)
 * @property {number} PartNumber - Part number (1-indexed)
 */

/**
 * Request payload for confirming upload completion.
 * POST /files/{id}/confirm_upload/
 * @typedef {Object} ConfirmUploadPayload
 * @property {UploadType} upload_type - Upload method used
 * @property {string} [upload_id] - Multipart upload ID (required for multipart)
 * @property {UploadPart[]} [parts] - Array of uploaded parts (required for multipart)
 */

/**
 * Request payload for updating a file.
 * PATCH /files/{id}/
 * @typedef {Object} UpdateFilePayload
 * @property {string} [tag] - File tag/category
 * @property {string} [caption] - File caption/description
 * @property {string} [duration] - Duration in "HH:MM:SS" format
 * @property {string} [lecture_id] - Associated lecture ID
 */

/**
 * Request payload for bulk download.
 * POST /files/download-files/
 * @typedef {Object} DownloadFilesPayload
 * @property {string[]} ids - Array of file IDs to download
 */

/**
 * Category filter for deletable files download.
 * @typedef {"video" | "audio" | "image" | "others"} FileCategory
 */

// ============================================================================
// RESPONSE TYPES
// ============================================================================

/**
 * Multipart upload URL entry.
 * @typedef {Object} MultipartUploadUrl
 * @property {number} part_number - Part number (1-indexed)
 * @property {string} url - Presigned URL for this part
 */

/**
 * Upload result from create files or presign refresh.
 * @typedef {Object} UploadResult
 * @property {string} file_id - Unique file identifier
 * @property {string} object_key - S3/storage object key path (e.g., "media/media/videos/.../intro.mp4")
 * @property {UploadType} upload_type - Upload method
 * @property {string | null} upload_url - Presigned PUT URL (for single upload, null for multipart)
 * @property {MultipartUploadUrl[] | null} upload_urls - Presigned URLs per part (for multipart, null for single)
 * @property {string | null} upload_id - Multipart upload ID (for multipart, null for single)
 * @property {Object.<string, string>} required_headers - Headers to include in upload request (e.g., {"Content-Type": "video/mp4"})
 * @property {string} expires_at - ISO 8601 timestamp when presigned URLs expire (default 15 min)
 * @property {string} upload_complete_url - Full URL to call for confirming upload
 */

/**
 * Response from POST /files/ (create files).
 * @typedef {Object} CreateFilesResponse
 * @property {UploadResult[]} results - Array of upload results, one per file in request
 */

/**
 * Response from POST /files/{id}/presign_upload_urls/.
 * Same structure as UploadResult.
 * @typedef {UploadResult} PresignUploadUrlsResponse
 */

/**
 * Response from POST /files/{id}/confirm_upload/.
 * @typedef {Object} ConfirmUploadResponse
 * @property {boolean} uploaded - Whether upload was confirmed successfully
 */

/**
 * File record from list/retrieve operations.
 * @typedef {Object} MediaFile
 * @property {string} id - Unique file identifier
 * @property {string} name - Original filename
 * @property {string} mimetype - MIME type (e.g., "video/mp4", "audio/wav")
 * @property {number} size - File size in bytes
 * @property {string} [tag] - File tag/category
 * @property {string} [caption] - File caption/description
 * @property {string} [duration] - Duration in "HH:MM:SS" format
 * @property {string} [lecture_id] - Associated lecture ID
 * @property {string} [url] - Stream URL
 * @property {string} [download_url] - Download URL
 * @property {string} [thumbnail_url] - Thumbnail URL (for images/videos)
 * @property {ProcessingStatus} [processing_status] - Processing status
 * @property {string} created_at - ISO 8601 creation timestamp
 * @property {string} updated_at - ISO 8601 last update timestamp
 */

/**
 * Paginated list response.
 * @typedef {Object} ListFilesResponse
 * @property {number} count - Total number of files matching query
 * @property {string | null} next - URL for next page (null if no more pages)
 * @property {string | null} previous - URL for previous page (null if first page)
 * @property {MediaFile[]} results - Array of file records for current page
 */

/**
 * Download URL result from V2 bulk download endpoints.
 * @typedef {Object} DownloadUrlResult
 * @property {string} id - File ID
 * @property {string} url - Presigned download URL (short-lived, download immediately)
 */

/**
 * Response from GET /files/download-all-deletable-files/ or POST /files/download-files/.
 * @typedef {Object} DownloadFilesResponse
 * @property {DownloadUrlResult[]} results - Array of file IDs with presigned download URLs
 */

/**
 * Result from bulk download helper functions.
 * @typedef {Object} BulkDownloadResult
 * @property {string[]} success - Array of successfully downloaded file IDs
 * @property {string[]} failed - Array of failed file IDs
 */

// ============================================================================
// UPLOAD HELPER TYPES
// ============================================================================

/**
 * Result from uploading to presigned URL.
 * @typedef {Object} PresignedUploadResult
 * @property {Response} response - Fetch Response object
 * @property {string | null} etag - ETag header from response (needed for multipart confirm)
 */

/**
 * Options for uploading to presigned URL.
 * @typedef {Object} UploadToPresignedUrlOptions
 * @property {string} url - Presigned URL from server
 * @property {File | Blob} file - File or blob to upload
 * @property {Object.<string, string>} [headers] - Headers from required_headers (do not add extra headers)
 * @property {"PUT" | "POST"} [method] - HTTP method (default: "PUT")
 */

/**
 * Options for multipart upload.
 * @typedef {Object} MultipartUploadOptions
 * @property {File} file - File to upload
 * @property {MultipartUploadUrl[]} uploadUrls - Presigned URLs from server response
 * @property {number} [partSize] - Part size in bytes (default: 5MB, must match server config)
 * @property {Object.<string, string>} [headers] - Headers from required_headers
 * @property {Array<{partNumber: number, url: string, body: Blob}>} [parts] - Pre-built parts (optional, for resuming)
 */

/**
 * Built multipart part ready for upload.
 * @typedef {Object} MultipartPart
 * @property {number} partNumber - Part number (1-indexed)
 * @property {string} url - Presigned URL for this part
 * @property {Blob} body - Blob slice of the file for this part
 */

// ============================================================================
// HOOK RETURN TYPE
// ============================================================================

/**
 * Return type of useMediaServiceV2 hook.
 * @typedef {Object} MediaServiceV2Hook
 * @property {MediaServiceContext} context - Current resolved context
 * @property {function(MediaServiceContext=): string} getBasePath - Get base API path
 * @property {function(string, MediaServiceContext=): string} buildFileUrl - Build file URL
 * @property {function(string, MediaServiceContext=): string} buildStreamUrl - Build stream URL
 * @property {function(string, string, MediaServiceContext=): string} buildStreamPathUrl - Build stream path URL
 * @property {function(string, MediaServiceContext=): string} buildDownloadUrl - Build download URL
 * @property {function(CreateFilesPayload, {context?: MediaServiceContext, config?: Object}=): Promise<{data: CreateFilesResponse}>} createFiles - Create file records
 * @property {function({params?: Object, context?: MediaServiceContext, config?: Object}=): Promise<{data: ListFilesResponse}>} listFiles - List files
 * @property {function(string, {context?: MediaServiceContext, config?: Object}=): Promise<{data: MediaFile}>} getFile - Get single file
 * @property {function(string, UpdateFilePayload, {context?: MediaServiceContext, config?: Object}=): Promise<{data: MediaFile}>} updateFile - Update file
 * @property {function(string, {context?: MediaServiceContext, config?: Object}=): Promise<void>} deleteFile - Delete file
 * @property {function(string, PresignUploadUrlsPayload, {context?: MediaServiceContext, config?: Object}=): Promise<{data: PresignUploadUrlsResponse}>} presignUploadUrls - Refresh presigned URLs
 * @property {function(string, ConfirmUploadPayload, {context?: MediaServiceContext, config?: Object}=): Promise<{data: ConfirmUploadResponse}>} confirmUpload - Confirm upload
 * @property {function(UploadToPresignedUrlOptions): Promise<PresignedUploadResult>} uploadToPresignedUrl - Upload to presigned URL
 * @property {function(MultipartUploadOptions): Promise<UploadPart[]>} uploadMultipartParts - Upload multipart parts
 * @property {function(string, {context?: MediaServiceContext, config?: Object}=): Promise<Object>} requestStream - Request stream
 * @property {function(string, string, {context?: MediaServiceContext, config?: Object}=): Promise<Object>} requestStreamPath - Request stream path
 * @property {function(string, {context?: MediaServiceContext, config?: Object}=): Promise<Object>} requestDownload - Request download
 * @property {function({category?: FileCategory, context?: MediaServiceContext, config?: Object}=): Promise<{data: DownloadFilesResponse}>} downloadAllDeletableFiles - Get presigned URLs for all deletable files
 * @property {function(string[], {context?: MediaServiceContext, config?: Object}=): Promise<{data: DownloadFilesResponse}>} downloadFiles - Get presigned URLs for specific files (bulk)
 * @property {function(string[], {filenames?: Object, context?: MediaServiceContext, config?: Object}=): Promise<BulkDownloadResult>} bulkDownloadFiles - Download multiple files with browser triggers
 * @property {function({category?: FileCategory, filenames?: Object, context?: MediaServiceContext, config?: Object}=): Promise<BulkDownloadResult>} bulkDownloadDeletableFiles - Download all deletable files with browser triggers
 * @property {function(string, string=): void} triggerBrowserDownload - Trigger browser download from URL
 */

export {};
