@turinhub/tale-js-sdk 1.3.0

package/dist/cms/folder.d.ts

@@ -0,0 +1,128 @@
+import type { PageResponse } from "../common/types.js";
+import type { Folder, CreateFolderRequest, UpdateFolderRequest, FolderOptions, ListFoldersRequest } from "./types.js";
+/**
+ * Gets a folder by ID.
+ *
+ * @param folderId - Folder ID (UUID)
+ * @param options - Optional configuration
+ * @returns Promise resolving to folder information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await getFolder('folder_id_here');
+ *   console.log('Folder name:', folder.folder_name);
+ * } catch (error) {
+ *   console.error('Failed to get folder:', error.message);
+ * }
+ * ```
+ */
+export declare function getFolder(folderId: string, options?: FolderOptions): Promise<Folder>;
+/**
+ * Lists folders with pagination.
+ *
+ * @param options - Optional parameters for pagination
+ * @returns Promise resolving to paginated folder list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listFolders } from '@tale/client';
+ *
+ * try {
+ *   const result = await listFolders({
+ *     page: 0,
+ *     size: 20,
+ *     sort_by: 'createdAt'
+ *   });
+ *   console.log(`Found ${result.total} folders`);
+ * } catch (error) {
+ *   console.error('Failed to list folders:', error.message);
+ * }
+ * ```
+ */
+export declare function listFolders(options?: ListFoldersRequest & FolderOptions): Promise<PageResponse<Folder>>;
+/**
+ * Creates a new folder.
+ *
+ * @param request - Folder creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created folder
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await createFolder({
+ *     folder_name: 'Images',
+ *     folder_type: ['IMAGE', 'VIDEO'],
+ *     remark: 'Image and video files'
+ *   });
+ *   console.log('Folder created:', folder.id);
+ * } catch (error) {
+ *   console.error('Failed to create folder:', error.message);
+ * }
+ * ```
+ */
+export declare function createFolder(request: CreateFolderRequest, options?: FolderOptions): Promise<Folder>;
+/**
+ * Updates an existing folder.
+ *
+ * @param folderId - Folder ID to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated folder
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await updateFolder('folder_id_here', {
+ *     folder_name: 'Updated Name',
+ *     remark: 'Updated remark'
+ *   });
+ *   console.log('Folder updated:', folder.folder_name);
+ * } catch (error) {
+ *   console.error('Failed to update folder:', error.message);
+ * }
+ * ```
+ */
+export declare function updateFolder(folderId: string, request: UpdateFolderRequest, options?: FolderOptions): Promise<Folder>;
+/**
+ * Deletes a folder.
+ *
+ * @param folderId - Folder 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 { deleteFolder } from '@tale/client';
+ *
+ * try {
+ *   await deleteFolder('folder_id_here');
+ *   console.log('Folder deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete folder:', error.message);
+ * }
+ * ```
+ */
+export declare function deleteFolder(folderId: string, options?: FolderOptions): Promise<void>;

package/dist/cms/folder.js

@@ -0,0 +1,294 @@
+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;
+}
+// ==================== Folder API Functions ====================
+/**
+ * Gets a folder by ID.
+ *
+ * @param folderId - Folder ID (UUID)
+ * @param options - Optional configuration
+ * @returns Promise resolving to folder information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await getFolder('folder_id_here');
+ *   console.log('Folder name:', folder.folder_name);
+ * } catch (error) {
+ *   console.error('Failed to get folder:', error.message);
+ * }
+ * ```
+ */
+export async function getFolder(folderId, options) {
+    if (!folderId || folderId.trim() === "") {
+        throw new ApiError("folderId 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/folders/${encodeURIComponent(folderId)}`;
+    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 folder: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to get folder", response.status);
+}
+/**
+ * Lists folders with pagination.
+ *
+ * @param options - Optional parameters for pagination
+ * @returns Promise resolving to paginated folder list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listFolders } from '@tale/client';
+ *
+ * try {
+ *   const result = await listFolders({
+ *     page: 0,
+ *     size: 20,
+ *     sort_by: 'createdAt'
+ *   });
+ *   console.log(`Found ${result.total} folders`);
+ * } catch (error) {
+ *   console.error('Failed to list folders:', error.message);
+ * }
+ * ```
+ */
+export async function listFolders(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 url = new URL(String(base).replace(/\/+$/, "") + "/cms/v1/folders");
+    const { appToken, baseUrl, ...requestParams } = options || {};
+    const queryParams = {
+        page: 0,
+        size: 10,
+        sort_by: "createdAt",
+        ...requestParams,
+    };
+    Object.entries(queryParams).forEach(([key, value]) => {
+        if (value !== undefined) {
+            url.searchParams.append(key, String(value));
+        }
+    });
+    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 list folders: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to list folders", response.status);
+}
+/**
+ * Creates a new folder.
+ *
+ * @param request - Folder creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created folder
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await createFolder({
+ *     folder_name: 'Images',
+ *     folder_type: ['IMAGE', 'VIDEO'],
+ *     remark: 'Image and video files'
+ *   });
+ *   console.log('Folder created:', folder.id);
+ * } catch (error) {
+ *   console.error('Failed to create folder:', error.message);
+ * }
+ * ```
+ */
+export async function createFolder(request, options) {
+    if (!request.folder_name || request.folder_name.trim() === "") {
+        throw new ApiError("folder_name 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/folders";
+    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 folder: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to create folder", response.status);
+}
+/**
+ * Updates an existing folder.
+ *
+ * @param folderId - Folder ID to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated folder
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateFolder } from '@tale/client';
+ *
+ * try {
+ *   const folder = await updateFolder('folder_id_here', {
+ *     folder_name: 'Updated Name',
+ *     remark: 'Updated remark'
+ *   });
+ *   console.log('Folder updated:', folder.folder_name);
+ * } catch (error) {
+ *   console.error('Failed to update folder:', error.message);
+ * }
+ * ```
+ */
+export async function updateFolder(folderId, request, options) {
+    if (!folderId || folderId.trim() === "") {
+        throw new ApiError("folderId 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/folders/${encodeURIComponent(folderId)}`;
+    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 folder: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to update folder", response.status);
+}
+/**
+ * Deletes a folder.
+ *
+ * @param folderId - Folder 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 { deleteFolder } from '@tale/client';
+ *
+ * try {
+ *   await deleteFolder('folder_id_here');
+ *   console.log('Folder deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete folder:', error.message);
+ * }
+ * ```
+ */
+export async function deleteFolder(folderId, options) {
+    if (!folderId || folderId.trim() === "") {
+        throw new ApiError("folderId 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/folders/${encodeURIComponent(folderId)}`;
+    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 folder: ${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 folder";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+}

package/dist/cms/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./folder.js";
+export * from "./file.js";
+export * from "./types.js";

package/dist/cms/index.js

@@ -0,0 +1,6 @@
+// ==================== Folder API ====================
+export * from "./folder.js";
+// ==================== File API ====================
+export * from "./file.js";
+// ==================== Types ====================
+export * from "./types.js";

package/dist/cms/types.d.ts

@@ -0,0 +1,157 @@
+import type { CommonOptions } from "../common/types.js";
+/**
+ * File type enumeration
+ */
+export type FileType = "IMAGE" | "LINK" | "MARKDOWN" | "PDF" | "DOC" | "VIDEO" | "AUDIO" | "ZIP" | "OTHER";
+/**
+ * Folder information
+ */
+export interface Folder {
+    /** Folder ID (UUID) */
+    id: string;
+    /** Application key */
+    app_key: string;
+    /** Folder name */
+    folder_name: string;
+    /** Folder types (array of file types allowed in this folder) */
+    folder_type: FileType[];
+    /** Folder attributes (custom metadata) */
+    folder_attr: Record<string, unknown> | null;
+    /** Remark/note */
+    remark: string | null;
+    /** Creation timestamp */
+    created_at: string;
+    /** Last update timestamp */
+    updated_at: string;
+}
+/**
+ * Request to create a folder
+ */
+export interface CreateFolderRequest {
+    /** Folder name (required) */
+    folder_name: string;
+    /** Folder types (optional) */
+    folder_type?: FileType[];
+    /** Folder attributes (optional) */
+    folder_attr?: Record<string, unknown>;
+    /** Remark (optional) */
+    remark?: string;
+}
+/**
+ * Request to update a folder
+ */
+export interface UpdateFolderRequest {
+    /** Folder name (optional) */
+    folder_name?: string;
+    /** Folder types (optional) */
+    folder_type?: FileType[];
+    /** Folder attributes (optional) */
+    folder_attr?: Record<string, unknown>;
+    /** Remark (optional) */
+    remark?: string;
+}
+/**
+ * Options for folder operations
+ */
+export interface FolderOptions extends CommonOptions {
+}
+/**
+ * Options for file operations
+ */
+export interface FileOptions extends CommonOptions {
+}
+/**
+ * Request to list folders with pagination
+ */
+export interface ListFoldersRequest {
+    /** Page number (0-based, default: 0) */
+    page?: number;
+    /** Page size (default: 10) */
+    size?: number;
+    /** Sort field (default: "createdAt") */
+    sort_by?: string;
+}
+/**
+ * File information
+ */
+export interface File {
+    /** File ID (UUID) */
+    id: string;
+    /** Application key */
+    app_key: string;
+    /** Folder ID (UUID) */
+    folder_id: string;
+    /** File name */
+    file_name: string;
+    /** File type */
+    file_type: FileType;
+    /** File attributes (custom metadata) */
+    file_attr: Record<string, unknown> | null;
+    /** Link URL (for LINK type files) */
+    link_url: string | null;
+    /** OSS URL (for uploaded files) */
+    oss_url: string | null;
+    /** Content (for MARKDOWN type files) */
+    content: string | null;
+    /** Remark/note */
+    remark: string | null;
+    /** Preview image URL (presigned) */
+    preview_image_url: string | null;
+    /** Creation timestamp */
+    created_at: string;
+    /** Last update timestamp */
+    updated_at: string;
+}
+/**
+ * Request to create a file
+ */
+export interface CreateFileRequest {
+    /** Folder ID (UUID, required) */
+    folder_id: string;
+    /** File name (required) */
+    file_name: string;
+    /** File type (required) */
+    file_type: FileType;
+    /** File attributes (optional) */
+    file_attr?: Record<string, unknown>;
+    /** Link URL (for LINK type, optional) */
+    link_url?: string;
+    /** Content (for MARKDOWN type, optional) */
+    content?: string;
+    /** Remark (optional) */
+    remark?: string;
+}
+/**
+ * Request to update a file
+ */
+export interface UpdateFileRequest {
+    /** Folder ID (optional) */
+    folder_id?: string;
+    /** File name (optional) */
+    file_name?: string;
+    /** File type (optional) */
+    file_type?: FileType;
+    /** File attributes (optional) */
+    file_attr?: Record<string, unknown>;
+    /** Link URL (optional) */
+    link_url?: string;
+    /** Content (optional) */
+    content?: string;
+    /** Remark (optional) */
+    remark?: string;
+}
+/**
+ * Request to list files with pagination
+ */
+export interface ListFilesRequest {
+    /** Folder ID (optional, filters by folder if provided) */
+    folder_id?: string;
+    /** Page number (0-based, default: 0) */
+    page?: number;
+    /** Page size (default: 10) */
+    size?: number;
+    /** Sort field (default: "createdAt") */
+    sort_by?: string;
+    /** Include attachments in response (default: false) */
+    include_attachments?: boolean;
+}

package/dist/cms/types.js

@@ -0,0 +1 @@
+export {};

package/dist/common/types.d.ts

@@ -0,0 +1,91 @@
+export interface CommonOptions {
+    baseUrl?: string;
+    appToken?: string;
+}
+/**
+ * Pagination response format used by Tale backend
+ *
+ * This matches the actual backend response format with simplified pagination metadata
+ */
+export interface PageResponse<T> {
+    /** Page content */
+    content: T[];
+    /** Total number of elements across all pages */
+    total: number;
+    /** Pagination information */
+    pageable: {
+        /** Current page number (0-based) */
+        pageNumber: number;
+        /** Page size */
+        pageSize: number;
+        /** Sort information */
+        sort?: {
+            orders?: Array<{
+                direction: "ASC" | "DESC";
+                property: string;
+                ignoreCase: boolean;
+                nullHandling: string;
+            }>;
+        };
+    };
+}
+export interface UserGroup {
+    group_id: string;
+    group_name: string;
+    description?: string;
+    remark?: string;
+}
+export interface Role {
+    role_id: string;
+    role_name: string;
+    role_type?: string;
+    role_property?: Record<string, unknown>;
+    role_privileges?: Privilege[];
+    privilege_ids?: string[];
+    resource_ids?: string[];
+    expired_at?: string;
+    remark?: string;
+}
+export interface Privilege {
+    privilege_id: string;
+    privilege_name: string;
+    privilege_type?: string;
+    privilege_property?: Record<string, unknown>;
+    resource_ids?: string[];
+    expired_at?: string;
+    remark?: string;
+}
+export interface AppInfo {
+    app_id: string;
+    app_key: string;
+    app_name: string;
+}
+export interface User {
+    user_id: string;
+    open_id: string;
+    username: string;
+    nick_name: string;
+    email: string;
+    phone: string;
+    avatar_url?: string;
+    is_frozen: boolean;
+    created_at: string;
+    updated_at: string;
+    remark?: string;
+}
+/**
+ * Attachment data (common type used across modules)
+ */
+export interface Attachment {
+    attachment_id: string;
+    app_id: string;
+    attachment_type_id: string;
+    ref_id: string;
+    file_name: string;
+    file_url: string;
+    file_size: number;
+    mime_type: string;
+    remark?: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/common/types.js

@@ -0,0 +1,2 @@
+// ==================== Common Types ====================
+export {};