@turinhub/tale-js-sdk 1.3.0

package/dist/cms/file.js

@@ -0,0 +1,800 @@
+import { getAppToken } from "../token.js";
+import { ApiError, ConfigurationError, NetworkError } from "../errors.js";
+// ==================== Helper Functions ====================
+/**
+ * Parses standard API response format: { code, msg, data }
+ */
+function parseApiResponse(json, errorMessage, statusCode) {
+    if (typeof json !== "object" || json === null) {
+        throw new ApiError(`Invalid response: ${errorMessage} - not an object`, statusCode);
+    }
+    const response = json;
+    if (response.code !== 200) {
+        const errorMsg = typeof response.msg === "string" ? response.msg : errorMessage;
+        throw new ApiError(errorMsg, statusCode, response.code);
+    }
+    if (!response.data) {
+        throw new ApiError(`Invalid response: ${errorMessage} - missing data`, statusCode);
+    }
+    return response.data;
+}
+// ==================== File API Functions ====================
+/**
+ * Gets a file by ID.
+ *
+ * @param fileId - File ID (UUID)
+ * @param options - Optional configuration
+ * @returns Promise resolving to file information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getFile } from '@tale/client';
+ *
+ * try {
+ *   const file = await getFile('file_id_here');
+ *   console.log('File name:', file.file_name);
+ *   console.log('File type:', file.file_type);
+ * } catch (error) {
+ *   console.error('Failed to get file:', error.message);
+ * }
+ * ```
+ */
+export async function getFile(fileId, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to get file: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get file", response.status);
+}
+/**
+ * Lists files with pagination.
+ *
+ * @param options - Optional parameters for pagination and filtering
+ * @returns Promise resolving to paginated file list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listFiles } from '@tale/client';
+ *
+ * try {
+ *   const result = await listFiles({
+ *     folder_id: 'folder_id_here',
+ *     page: 0,
+ *     size: 20,
+ *     sort_by: 'createdAt'
+ *   });
+ *   console.log(`Found ${result.total} files`);
+ * } catch (error) {
+ *   console.error('Failed to list files:', error.message);
+ * }
+ * ```
+ */
+export async function listFiles(options) {
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const { appToken, baseUrl, folder_id, ...requestParams } = options || {};
+    // If folder_id is provided, use folder-based endpoint
+    let url;
+    if (folder_id) {
+        url =
+            String(base).replace(/\/+$/, "") +
+                `/cms/v1/folders/${encodeURIComponent(folder_id)}/files`;
+    }
+    else {
+        url = String(base).replace(/\/+$/, "") + "/cms/v1/files";
+    }
+    const urlObj = new URL(url);
+    const queryParams = {
+        page: 0,
+        size: 10,
+        sort_by: "createdAt",
+        include_attachments: false,
+        ...requestParams,
+    };
+    Object.entries(queryParams).forEach(([key, value]) => {
+        if (value !== undefined) {
+            urlObj.searchParams.append(key, String(value));
+        }
+    });
+    let response;
+    try {
+        response = await globalThis.fetch(urlObj.toString(), {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to list files: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to list files", response.status);
+}
+/**
+ * Creates a new file.
+ *
+ * @param request - File creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created file
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createFile } from '@tale/client';
+ *
+ * try {
+ *   const file = await createFile({
+ *     folder_id: 'folder_id_here',
+ *     file_name: 'My Document',
+ *     file_type: 'markdown',
+ *     content: '# Hello World'
+ *   });
+ *   console.log('File created:', file.id);
+ * } catch (error) {
+ *   console.error('Failed to create file:', error.message);
+ * }
+ * ```
+ */
+export async function createFile(request, options) {
+    if (!request.folder_id || request.folder_id.trim() === "") {
+        throw new ApiError("folder_id is required", 400, "9400");
+    }
+    if (!request.file_name || request.file_name.trim() === "") {
+        throw new ApiError("file_name is required", 400, "9400");
+    }
+    if (!request.file_type || request.file_type.trim() === "") {
+        throw new ApiError("file_type is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") + "/cms/v1/files";
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to create file: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to create file", response.status);
+}
+/**
+ * Updates an existing file.
+ *
+ * @param fileId - File ID to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated file
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateFile } from '@tale/client';
+ *
+ * try {
+ *   const file = await updateFile('file_id_here', {
+ *     file_name: 'Updated Name',
+ *     remark: 'Updated remark'
+ *   });
+ *   console.log('File updated:', file.file_name);
+ * } catch (error) {
+ *   console.error('Failed to update file:', error.message);
+ * }
+ * ```
+ */
+export async function updateFile(fileId, request, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to update file: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to update file", response.status);
+}
+/**
+ * Updates the Markdown content of a file.
+ *
+ * @param fileId - File ID to update
+ * @param content - New Markdown content
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated file
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateFileContent } from '@tale/client';
+ *
+ * try {
+ *   const file = await updateFileContent('file_id_here', '# New Content');
+ *   console.log('Content updated:', file.content);
+ * } catch (error) {
+ *   console.error('Failed to update content:', error.message);
+ * }
+ * ```
+ */
+export async function updateFileContent(fileId, content, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    if (content === undefined || content === null) {
+        throw new ApiError("content is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}/content`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify({ content }),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to update file content: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to update file content", response.status);
+}
+/**
+ * Deletes a file.
+ *
+ * @param fileId - File ID to delete
+ * @param options - Optional configuration
+ * @returns Promise that resolves when deletion is successful
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { deleteFile } from '@tale/client';
+ *
+ * try {
+ *   await deleteFile('file_id_here');
+ *   console.log('File deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete file:', error.message);
+ * }
+ * ```
+ */
+export async function deleteFile(fileId, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "DELETE",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to delete file: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = (await response.json());
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === "string" ? json.msg : "Failed to delete file";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+}
+/**
+ * Gets a presigned URL for file download.
+ *
+ * @param fileId - File ID
+ * @param expireTimeInSeconds - Expiration time in seconds (default: 3600)
+ * @param options - Optional configuration
+ * @returns Promise resolving to presigned URL information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getFilePresignedUrl } from '@tale/client';
+ *
+ * try {
+ *   const result = await getFilePresignedUrl('file_id_here', 3600);
+ *   console.log('Presigned URL:', result.presigned_url);
+ *   // Now you can download the file directly
+ * } catch (error) {
+ *   console.error('Failed to get presigned URL:', error.message);
+ * }
+ * ```
+ */
+export async function getFilePresignedUrl(fileId, expireTimeInSeconds = 3600, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}/presigned-url`;
+    const urlObj = new URL(url);
+    if (expireTimeInSeconds !== undefined) {
+        urlObj.searchParams.append("expireTimeInSeconds", String(expireTimeInSeconds));
+    }
+    let response;
+    try {
+        response = await globalThis.fetch(urlObj.toString(), {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to get presigned URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get presigned URL", response.status);
+}
+/**
+ * Batch gets presigned URLs for multiple files.
+ *
+ * @param fileIds - Array of file IDs (max 10)
+ * @param expireTimeInSeconds - Expiration time in seconds (default: 3600)
+ * @param options - Optional configuration
+ * @returns Promise resolving to array of presigned URL information or errors
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { batchGetFilePresignedUrl } from '@tale/client';
+ *
+ * try {
+ *   const results = await batchGetFilePresignedUrl(
+ *     ['file_id_1', 'file_id_2'],
+ *     3600
+ *   );
+ *   results.forEach(result => {
+ *     if (result.error) {
+ *       console.error('Error for file:', result.file_id, result.error);
+ *     } else {
+ *       console.log('URL:', result.presigned_url);
+ *     }
+ *   });
+ * } catch (error) {
+ *   console.error('Failed to batch get presigned URLs:', error.message);
+ * }
+ * ```
+ */
+export async function batchGetFilePresignedUrl(fileIds, expireTimeInSeconds = 3600, options) {
+    if (!fileIds || fileIds.length === 0) {
+        throw new ApiError("fileIds is required", 400, "9400");
+    }
+    if (fileIds.length > 10) {
+        throw new ApiError("Too many file IDs, max 10 allowed", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") + "/cms/v1/files/batch-presigned-url";
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify({
+                file_ids: fileIds,
+                expire_time_in_seconds: expireTimeInSeconds,
+            }),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to batch get presigned URLs: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to batch get presigned URLs", response.status);
+}
+/**
+ * Gets OSS object metadata.
+ *
+ * @param ossKey - OSS key
+ * @param options - Optional configuration
+ * @returns Promise resolving to OSS metadata
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getOssMetadata } from '@tale/client';
+ *
+ * try {
+ *   const metadata = await getOssMetadata('cms/appkey/folder/fileid.pdf');
+ *   console.log('File size:', metadata.content_length);
+ *   console.log('Content type:', metadata.content_type);
+ * } catch (error) {
+ *   console.error('Failed to get OSS metadata:', error.message);
+ * }
+ * ```
+ */
+export async function getOssMetadata(ossKey, options) {
+    if (!ossKey || ossKey.trim() === "") {
+        throw new ApiError("ossKey is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = new URL(String(base).replace(/\/+$/, "") + "/cms/v1/oss/metadata");
+    url.searchParams.append("key", ossKey);
+    let response;
+    try {
+        response = await globalThis.fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to get OSS metadata: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get OSS metadata", response.status);
+}
+/**
+ * Gets upload authorization for a new file (presets OSS key + presigned upload URL).
+ *
+ * @param request - Upload authorization request
+ * @param options - Optional configuration
+ * @returns Promise resolving to upload authorization response
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getUploadAuthorization } from '@tale/client';
+ *
+ * try {
+ *   const auth = await getUploadAuthorization({
+ *     folder_id: 'folder_id_here',
+ *     file_name: 'document.pdf',
+ *     file_type: 'pdf'
+ *   });
+ *   console.log('OSS Key:', auth.oss_key);
+ *   console.log('Upload URL:', auth.presigned_url);
+ *   console.log('File ID:', auth.file_id);
+ *   // Use presigned_url to upload the file directly to OSS
+ * } catch (error) {
+ *   console.error('Failed to get upload authorization:', error.message);
+ * }
+ * ```
+ */
+export async function getUploadAuthorization(request, options) {
+    if (!request.folder_id || request.folder_id.trim() === "") {
+        throw new ApiError("folder_id is required", 400, "9400");
+    }
+    if (!request.file_name || request.file_name.trim() === "") {
+        throw new ApiError("file_name is required", 400, "9400");
+    }
+    if (!request.file_type || request.file_type.trim() === "") {
+        throw new ApiError("file_type is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") + "/cms/v1/files/upload-authorization";
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to get upload authorization: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get upload authorization", response.status);
+}
+/**
+ * Gets STS credentials for uploading to an existing file.
+ *
+ * @param fileId - File ID
+ * @param fileExtension - File extension (e.g., ".pdf")
+ * @param durationSeconds - Credential duration in seconds (default: 1800)
+ * @param options - Optional configuration
+ * @returns Promise resolving to STS credentials
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getFileStsCredentials } from '@tale/client';
+ *
+ * try {
+ *   const credentials = await getFileStsCredentials('file_id_here', '.pdf', 1800);
+ *   console.log('Access Key ID:', credentials.access_key_id);
+ *   console.log('Secret Access Key:', credentials.secret_access_key);
+ *   console.log('Session Token:', credentials.session_token);
+ *   console.log('Upload Path:', credentials.upload_path);
+ *   // Use these credentials to upload with OSS SDK
+ * } catch (error) {
+ *   console.error('Failed to get STS credentials:', error.message);
+ * }
+ * ```
+ */
+export async function getFileStsCredentials(fileId, fileExtension, durationSeconds = 1800, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    if (!fileExtension || fileExtension.trim() === "") {
+        throw new ApiError("fileExtension is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}/sts-credentials`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify({
+                file_extension: fileExtension,
+                duration_seconds: durationSeconds,
+            }),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to get STS credentials: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get STS credentials", response.status);
+}
+/**
+ * Marks file upload as complete and updates OSS information.
+ *
+ * @param fileId - File ID
+ * @param request - Upload completion information
+ * @param options - Optional configuration
+ * @returns Promise resolving to success message
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { fileUploadComplete } from '@tale/client';
+ *
+ * try {
+ *   const result = await fileUploadComplete('file_id_here', {
+ *     oss_key: 'cms/appkey/folder/fileid.pdf',
+ *     file_size: 12345,
+ *     etag: 'abc123'
+ *   });
+ *   console.log('Upload complete:', result.message);
+ * } catch (error) {
+ *   console.error('Failed to mark upload complete:', error.message);
+ * }
+ * ```
+ */
+export async function fileUploadComplete(fileId, request, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    if (!request.oss_key || request.oss_key.trim() === "") {
+        throw new ApiError("oss_key is required", 400, "9400");
+    }
+    if (!request.file_size && request.file_size !== 0) {
+        throw new ApiError("file_size is required", 400, "9400");
+    }
+    if (!request.etag || request.etag.trim() === "") {
+        throw new ApiError("etag is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}/upload-complete`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to mark upload complete: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to mark upload complete", response.status);
+}
+/**
+ * Sets a preview image for a file.
+ *
+ * @param fileId - File ID
+ * @param imageFile - Image file to upload (File or Blob)
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated file
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { setFilePreviewImage } from '@tale/client';
+ *
+ * try {
+ *   // Get file from input element
+ *   const input = document.getElementById('previewInput');
+ *   const file = input.files[0];
+ *
+ *   const updatedFile = await setFilePreviewImage('file_id_here', file);
+ *   console.log('Preview image set:', updatedFile.preview_image_url);
+ * } catch (error) {
+ *   console.error('Failed to set preview image:', error.message);
+ * }
+ * ```
+ */
+export async function setFilePreviewImage(fileId, imageFile, options) {
+    if (!fileId || fileId.trim() === "") {
+        throw new ApiError("fileId is required", 400, "9400");
+    }
+    if (!imageFile) {
+        throw new ApiError("imageFile is required", 400, "9400");
+    }
+    const token = options?.appToken ?? (await getAppToken(options));
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = options?.baseUrl ?? env?.TALE_BASE_URL ?? undefined;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    const url = String(base).replace(/\/+$/, "") +
+        `/cms/v1/files/${encodeURIComponent(fileId)}/preview-image`;
+    // Create FormData
+    const formData = new FormData();
+    // Handle File type which extends Blob
+    if (typeof File !== "undefined" && imageFile instanceof File) {
+        formData.append("file", imageFile, imageFile.name);
+    }
+    else {
+        formData.append("file", imageFile);
+    }
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "x-t-token": token,
+            },
+            body: formData,
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to set preview image: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to set preview image", response.status);
+}