tale-js-sdk 0.1.2 → 0.1.3

package/dist/acl/index.js

@@ -0,0 +1,747 @@
+import { getAppToken } from '../token.js';
+import { ApiError, ConfigurationError, NetworkError } from '../errors.js';
+// ===== ACL Record 管理 =====
+/**
+ * Creates a new ACL record in the Tale application.
+ *
+ * @param recordData - ACL record data to create
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the created ACL record information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createRecord } from '@tale/client';
+ *
+ * try {
+ *   const result = await createRecord({
+ *     template_id: 'template_user_read',
+ *     subject_type: 'user',
+ *     subject_id: 'user_123',
+ *     resource_type: 'document',
+ *     resource_id: 'doc_456',
+ *     effect_type: 'allow',
+ *     priority: 50,
+ *     description: 'Allow user to read document'
+ *   });
+ *   console.log('ACL record created:', result.record.record_id);
+ * } catch (error) {
+ *   console.error('Failed to create ACL record:', error.message);
+ * }
+ * ```
+ */
+export async function createRecord(recordData, options) {
+    // Validate required fields
+    if (!recordData.template_id || recordData.template_id.trim() === '') {
+        throw new ApiError('template_id is required for ACL record creation', 400, '9400');
+    }
+    if (!recordData.subject_type || !['user', 'role', 'group'].includes(recordData.subject_type)) {
+        throw new ApiError('subject_type is required and must be one of: user, role, group', 400, '9400');
+    }
+    if (!recordData.resource_type || recordData.resource_type.trim() === '') {
+        throw new ApiError('resource_type is required for ACL record creation', 400, '9400');
+    }
+    if (!recordData.subject_id && !recordData.subject_identifier) {
+        throw new ApiError('Either subject_id or subject_identifier is required', 400, '9400');
+    }
+    if (!recordData.resource_id && !recordData.resource_identifier) {
+        throw new ApiError('Either resource_id or resource_identifier is required', 400, '9400');
+    }
+    if (!recordData.effect_type || !['allow', 'deny', 'inherit'].includes(recordData.effect_type)) {
+        throw new ApiError('effect_type is required and must be one of: allow, deny, inherit', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + '/acl/v1/records';
+    // Validate priority range
+    if (recordData.priority !== undefined && (recordData.priority < 0 || recordData.priority > 100)) {
+        throw new ApiError('priority must be between 0 and 100', 400, '9400');
+    }
+    // Set default priority if not provided
+    const finalRecordData = {
+        ...recordData,
+        priority: recordData.priority ?? 50
+    };
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-t-token': token,
+            },
+            body: JSON.stringify(finalRecordData),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to create ACL record: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL record creation response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL record creation failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.record) {
+        throw new ApiError('Invalid ACL record creation response: missing record data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Updates an existing ACL record by ID.
+ *
+ * @param recordId - ACL record ID to update
+ * @param updateData - ACL record information to update
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the updated ACL record information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function updateRecord(recordId, updateData, options) {
+    // Validate required fields
+    if (!recordId || recordId.trim() === '') {
+        throw new ApiError('record_id is required for ACL record update', 400, '9400');
+    }
+    if (updateData.effect_type && !['allow', 'deny', 'inherit'].includes(updateData.effect_type)) {
+        throw new ApiError('effect_type must be one of: allow, deny, inherit', 400, '9400');
+    }
+    // Validate priority range
+    if (updateData.priority !== undefined && (updateData.priority < 0 || updateData.priority > 100)) {
+        throw new ApiError('priority must be between 0 and 100', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/records/${encodeURIComponent(recordId)}`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-t-token': token,
+            },
+            body: JSON.stringify(updateData),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to update ACL record: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL record update response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL record update failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.record) {
+        throw new ApiError('Invalid ACL record update response: missing record data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Deletes an ACL record by ID.
+ *
+ * @param recordId - ACL record ID to delete
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the deletion result
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function deleteRecord(recordId, options) {
+    // Validate required fields
+    if (!recordId || recordId.trim() === '') {
+        throw new ApiError('record_id is required for ACL record deletion', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/records/${encodeURIComponent(recordId)}`;
+    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 ACL record: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL record deletion response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL record deletion failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || json.data.deleted !== true) {
+        throw new ApiError('Invalid ACL record deletion response: deletion not confirmed', response.status);
+    }
+    return json.data;
+}
+/**
+ * Retrieves ACL record information by ID.
+ *
+ * @param recordId - ACL record ID to query
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the ACL record information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function getRecordById(recordId, options) {
+    // Validate required fields
+    if (!recordId || recordId.trim() === '') {
+        throw new ApiError('record_id is required for ACL record query', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/records/${encodeURIComponent(recordId)}`;
+    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 ACL record: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL record response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL record retrieval failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.record) {
+        throw new ApiError('Invalid ACL record response: missing record data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Lists ACL records with pagination and filtering.
+ *
+ * @param options - Optional parameters for pagination, filtering, and configuration
+ * @returns Promise resolving to paginated ACL record list with metadata
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function listRecords(options) {
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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');
+    }
+    // Build URL with query parameters
+    const url = new URL(String(base).replace(/\/+$/, '') + '/acl/v1/records');
+    // Add query parameters with defaults
+    const queryParams = {
+        page: 0,
+        size: 20,
+        sort_by: 'priority',
+        sort_direction: 'desc',
+        ...options
+    };
+    // Add parameters to URL
+    if (queryParams.template_id) {
+        url.searchParams.append('template_id', queryParams.template_id);
+    }
+    if (queryParams.subject_type) {
+        url.searchParams.append('subject_type', queryParams.subject_type);
+    }
+    if (queryParams.subject_id) {
+        url.searchParams.append('subject_id', queryParams.subject_id);
+    }
+    if (queryParams.subject_identifier) {
+        url.searchParams.append('subject_identifier', queryParams.subject_identifier);
+    }
+    if (queryParams.resource_type) {
+        url.searchParams.append('resource_type', queryParams.resource_type);
+    }
+    if (queryParams.resource_id) {
+        url.searchParams.append('resource_id', queryParams.resource_id);
+    }
+    if (queryParams.resource_identifier) {
+        url.searchParams.append('resource_identifier', queryParams.resource_identifier);
+    }
+    if (queryParams.page !== undefined) {
+        url.searchParams.append('page', String(queryParams.page));
+    }
+    if (queryParams.size !== undefined) {
+        url.searchParams.append('size', String(queryParams.size));
+    }
+    if (queryParams.sort_by) {
+        url.searchParams.append('sort', `${queryParams.sort_by},${queryParams.sort_direction || 'desc'}`);
+    }
+    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 ACL records: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL records list response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL records list retrieval failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !Array.isArray(json.data.content)) {
+        throw new ApiError('Invalid ACL records list response: missing required data', response.status);
+    }
+    return json.data;
+}
+// ===== ACL Template 管理 =====
+/**
+ * Creates a new ACL template in the Tale application.
+ *
+ * @param templateData - ACL template data to create
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the created ACL template information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createTemplate } from '@tale/client';
+ *
+ * try {
+ *   const result = await createTemplate({
+ *     template_name: 'User Document Read Template',
+ *     template_code: 'user_doc_read',
+ *     subject_type: 'user',
+ *     resource_type: 'document',
+ *     effect_type: 'allow',
+ *     default_priority: 30,
+ *     description: 'Template for allowing users to read documents'
+ *   });
+ *   console.log('ACL template created:', result.template.template_id);
+ * } catch (error) {
+ *   console.error('Failed to create ACL template:', error.message);
+ * }
+ * ```
+ */
+export async function createTemplate(templateData, options) {
+    // Validate required fields
+    if (!templateData.template_name || templateData.template_name.trim() === '') {
+        throw new ApiError('template_name is required for ACL template creation', 400, '9400');
+    }
+    if (!templateData.template_code || templateData.template_code.trim() === '') {
+        throw new ApiError('template_code is required for ACL template creation', 400, '9400');
+    }
+    if (templateData.effect_type && !['allow', 'deny', 'inherit'].includes(templateData.effect_type)) {
+        throw new ApiError('effect_type must be one of: allow, deny, inherit', 400, '9400');
+    }
+    // Validate default priority range
+    if (templateData.default_priority !== undefined && (templateData.default_priority < 0 || templateData.default_priority > 100)) {
+        throw new ApiError('default_priority must be between 0 and 100', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + '/acl/v1/templates';
+    // Set default values
+    const finalTemplateData = {
+        ...templateData,
+        default_priority: templateData.default_priority ?? 50,
+        effect_type: templateData.effect_type ?? 'allow'
+    };
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-t-token': token,
+            },
+            body: JSON.stringify(finalTemplateData),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to create ACL template: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL template creation response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL template creation failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.template) {
+        throw new ApiError('Invalid ACL template creation response: missing template data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Updates an existing ACL template by ID.
+ *
+ * @param templateId - ACL template ID or code to update
+ * @param updateData - ACL template information to update
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the updated ACL template information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function updateTemplate(templateId, updateData, options) {
+    // Validate required fields
+    if (!templateId || templateId.trim() === '') {
+        throw new ApiError('template_id is required for ACL template update', 400, '9400');
+    }
+    if (updateData.effect_type && !['allow', 'deny', 'inherit'].includes(updateData.effect_type)) {
+        throw new ApiError('effect_type must be one of: allow, deny, inherit', 400, '9400');
+    }
+    // Validate default priority range
+    if (updateData.default_priority !== undefined && (updateData.default_priority < 0 || updateData.default_priority > 100)) {
+        throw new ApiError('default_priority must be between 0 and 100', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/templates/${encodeURIComponent(templateId)}`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-t-token': token,
+            },
+            body: JSON.stringify(updateData),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to update ACL template: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL template update response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL template update failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.template) {
+        throw new ApiError('Invalid ACL template update response: missing template data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Deletes an ACL template by ID.
+ *
+ * @param templateId - ACL template ID or code to delete
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the deletion result
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function deleteTemplate(templateId, options) {
+    // Validate required fields
+    if (!templateId || templateId.trim() === '') {
+        throw new ApiError('template_id is required for ACL template deletion', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/templates/${encodeURIComponent(templateId)}`;
+    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 ACL template: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL template deletion response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL template deletion failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || json.data.deleted !== true) {
+        throw new ApiError('Invalid ACL template deletion response: deletion not confirmed', response.status);
+    }
+    return json.data;
+}
+/**
+ * Retrieves ACL template information by ID or code.
+ *
+ * @param templateId - ACL template ID or code to query
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to the ACL template information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function getTemplateById(templateId, options) {
+    // Validate required fields
+    if (!templateId || templateId.trim() === '') {
+        throw new ApiError('template_id is required for ACL template query', 400, '9400');
+    }
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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(/\/+$/, '') + `/acl/v1/templates/${encodeURIComponent(templateId)}`;
+    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 ACL template: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL template response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL template retrieval failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !json.data.template) {
+        throw new ApiError('Invalid ACL template response: missing template data', response.status);
+    }
+    return json.data;
+}
+/**
+ * Lists ACL templates with pagination and filtering.
+ *
+ * @param options - Optional parameters for pagination, filtering, and configuration
+ * @returns Promise resolving to paginated ACL template list with metadata
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ */
+export async function listTemplates(options) {
+    // Use provided app token or get one from token service
+    const token = options?.appToken ?? await getAppToken(options);
+    // Determine base URL
+    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');
+    }
+    // Build URL with query parameters
+    const url = new URL(String(base).replace(/\/+$/, '') + '/acl/v1/templates');
+    // Add query parameters with defaults
+    const queryParams = {
+        page: 0,
+        size: 20,
+        sort_by: 'created_at',
+        sort_direction: 'desc',
+        ...options
+    };
+    // Add parameters to URL
+    if (queryParams.resource_type) {
+        url.searchParams.append('resource_type', queryParams.resource_type);
+    }
+    if (queryParams.subject_type) {
+        url.searchParams.append('subject_type', queryParams.subject_type);
+    }
+    if (queryParams.page !== undefined) {
+        url.searchParams.append('page', String(queryParams.page));
+    }
+    if (queryParams.size !== undefined) {
+        url.searchParams.append('size', String(queryParams.size));
+    }
+    if (queryParams.sort_by) {
+        url.searchParams.append('sort_by', queryParams.sort_by);
+    }
+    if (queryParams.sort_direction) {
+        url.searchParams.append('sort_direction', queryParams.sort_direction);
+    }
+    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 ACL templates: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    let json;
+    try {
+        const responseJson = await response.json();
+        json = responseJson;
+    }
+    catch (error) {
+        throw new ApiError(`Failed to parse ACL templates list response: ${error instanceof Error ? error.message : 'Invalid JSON'}`, response.status);
+    }
+    // Handle API errors
+    if (json.code !== 200) {
+        const errorMsg = typeof json.msg === 'string' ? json.msg : 'ACL templates list retrieval failed';
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    // Validate response structure
+    if (!json.data || !Array.isArray(json.data.content)) {
+        throw new ApiError('Invalid ACL templates list response: missing required data', response.status);
+    }
+    return json.data;
+}
+// ===== ACL 核心工具函数 (AclCoreUtils) =====
+/**
+ * ACL 核心工具函数，包含跨应用通用的业务逻辑
+ */
+export const AclCoreUtils = {
+    /**
+     * 验证优先级范围
+     */
+    validatePriority(priority) {
+        return priority >= 0 && priority <= 100;
+    },
+    /**
+     * 获取可用的效果类型
+     */
+    getEffectTypes() {
+        return ['allow', 'deny', 'inherit'];
+    },
+    /**
+     * 获取可用的主体类型
+     */
+    getSubjectTypes() {
+        return ['user', 'role', 'group'];
+    }
+};