@turinhub/tale-js-sdk 1.3.0

package/dist/cms/file.d.ts

@@ -0,0 +1,398 @@
+import type { PageResponse } from "../common/types.js";
+import type { File, CreateFileRequest, UpdateFileRequest, ListFilesRequest, FileOptions } from "./types.js";
+/**
+ * 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 declare function getFile(fileId: string, options?: FileOptions): Promise<File>;
+/**
+ * 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 declare function listFiles(options?: ListFilesRequest & FileOptions): Promise<PageResponse<File>>;
+/**
+ * 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 declare function createFile(request: CreateFileRequest, options?: FileOptions): Promise<File>;
+/**
+ * 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 declare function updateFile(fileId: string, request: UpdateFileRequest, options?: FileOptions): Promise<File>;
+/**
+ * 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 declare function updateFileContent(fileId: string, content: string, options?: FileOptions): Promise<File>;
+/**
+ * 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 declare function deleteFile(fileId: string, options?: FileOptions): Promise<void>;
+/**
+ * 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 declare function getFilePresignedUrl(fileId: string, expireTimeInSeconds?: number, options?: FileOptions): Promise<{
+    file_id: string;
+    file_name: string;
+    oss_key: string;
+    presigned_url: string;
+    expire_time_in_seconds: number;
+}>;
+/**
+ * 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 declare function batchGetFilePresignedUrl(fileIds: string[], expireTimeInSeconds?: number, options?: FileOptions): Promise<Array<{
+    file_id: string;
+    file_name?: string;
+    oss_key?: string;
+    presigned_url?: string;
+    expire_time_in_seconds?: number;
+    error?: string;
+}>>;
+/**
+ * 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 declare function getOssMetadata(ossKey: string, options?: FileOptions): Promise<{
+    oss_key: string;
+    content_type?: string;
+    content_length?: number;
+    last_modified?: string;
+    etag?: string;
+    metadata?: Record<string, string>;
+}>;
+/**
+ * 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 declare function getUploadAuthorization(request: {
+    folder_id: string;
+    file_name: string;
+    file_type: string;
+    expire_time_in_seconds?: number;
+}, options?: FileOptions): Promise<{
+    oss_key: string;
+    presigned_url: string;
+    file_name: string;
+    file_type: string;
+    expire_time_in_seconds: number;
+    file_id: string;
+}>;
+/**
+ * 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 declare function getFileStsCredentials(fileId: string, fileExtension: string, durationSeconds?: number, options?: FileOptions): Promise<{
+    access_key_id: string;
+    secret_access_key: string;
+    session_token: string;
+    expiration: string;
+    upload_path: string;
+    region: string;
+}>;
+/**
+ * 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 declare function fileUploadComplete(fileId: string, request: {
+    oss_key: string;
+    file_size: number;
+    etag: string;
+}, options?: FileOptions): Promise<{
+    message: string;
+    file_id: string;
+}>;
+/**
+ * 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 declare function setFilePreviewImage(fileId: string, imageFile: File | Blob, options?: FileOptions): Promise<File>;