@turinhub/tale-js-sdk 1.3.0

package/dist/user-group/index.js

@@ -0,0 +1,566 @@
+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;
+}
+// ==================== Functions ====================
+/**
+ * Gets a user group by ID.
+ *
+ * @param groupId - User group ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to user group information
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getUserGroup } from '@tale/client';
+ *
+ * try {
+ *   const group = await getUserGroup('group_id_here');
+ *   console.log('Group name:', group.name);
+ * } catch (error) {
+ *   console.error('Failed to get user group:', error.message);
+ * }
+ * ```
+ */
+export async function getUserGroup(groupId, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}`;
+    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 user group: ${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 get user group";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    if (!json.data) {
+        throw new ApiError("Invalid user group response: missing data", response.status);
+    }
+    return json.data;
+}
+/**
+ * Lists user groups with pagination and optional keyword filtering.
+ *
+ * @param options - Optional parameters for pagination and filtering
+ * @returns Promise resolving to paginated user group list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listUserGroups } from '@tale/client';
+ *
+ * try {
+ *   const result = await listUserGroups({
+ *     page: 0,
+ *     size: 20,
+ *     keyword: 'admin'
+ *   });
+ *   console.log(`Found ${result.totalElements} user groups`);
+ * } catch (error) {
+ *   console.error('Failed to list user groups:', error.message);
+ * }
+ * ```
+ */
+export async function listUserGroups(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(/\/+$/, "") + "/user-group/v2");
+    const { appToken, baseUrl, ...requestParams } = options || {};
+    const queryParams = {
+        page: 0,
+        size: 10,
+        sort: "createdAt,desc",
+        ...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 user groups: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to list user groups", response.status);
+}
+/**
+ * Creates a new user group.
+ *
+ * @param request - User group creation request
+ * @param options - Optional configuration
+ * @returns Promise resolving to created user group
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { createUserGroup } from '@tale/client';
+ *
+ * try {
+ *   const group = await createUserGroup({
+ *     name: 'Administrators',
+ *     description: 'Admin users',
+ *     type: 'system'
+ *   });
+ *   console.log('Group created:', group.group_id);
+ * } catch (error) {
+ *   console.error('Failed to create user group:', error.message);
+ * }
+ * ```
+ */
+export async function createUserGroup(request, options) {
+    if (!request.name || request.name.trim() === "") {
+        throw new ApiError("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(/\/+$/, "") + "/user-group/v1";
+    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 user group: ${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 create user group";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    if (!json.data) {
+        throw new ApiError("Invalid user group creation response: missing data", response.status);
+    }
+    return json.data;
+}
+/**
+ * Updates an existing user group.
+ *
+ * @param groupId - User group ID to update
+ * @param request - Update request with fields to modify
+ * @param options - Optional configuration
+ * @returns Promise resolving to updated user group
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { updateUserGroup } from '@tale/client';
+ *
+ * try {
+ *   const group = await updateUserGroup('group_id_here', {
+ *     name: 'Updated Name',
+ *     description: 'Updated description'
+ *   });
+ *   console.log('Group updated:', group.name);
+ * } catch (error) {
+ *   console.error('Failed to update user group:', error.message);
+ * }
+ * ```
+ */
+export async function updateUserGroup(groupId, request, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}`;
+    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 user group: ${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 update user group";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    if (!json.data) {
+        throw new ApiError("Invalid user group update response: missing data", response.status);
+    }
+    return json.data;
+}
+/**
+ * Deletes a user group.
+ *
+ * @param groupId - User group 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 { deleteUserGroup } from '@tale/client';
+ *
+ * try {
+ *   await deleteUserGroup('group_id_here');
+ *   console.log('Group deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete user group:', error.message);
+ * }
+ * ```
+ */
+export async function deleteUserGroup(groupId, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}`;
+    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 user group: ${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 user group";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+}
+/**
+ * Gets members of a user group with pagination.
+ *
+ * @param groupId - User group ID
+ * @param options - Optional parameters for pagination
+ * @returns Promise resolving to paginated member list
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { listUserGroupMembers } from '@tale/client';
+ *
+ * try {
+ *   const result = await listUserGroupMembers('group_id_here', {
+ *     page: 0,
+ *     size: 20
+ *   });
+ *   console.log(`Found ${result.totalElements} members`);
+ * } catch (error) {
+ *   console.error('Failed to list user group members:', error.message);
+ * }
+ * ```
+ */
+export async function listUserGroupMembers(groupId, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}/members`);
+    const { appToken, baseUrl, ...requestParams } = options || {};
+    const queryParams = {
+        page: 0,
+        size: 10,
+        sort: "createdAt,desc",
+        ...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 user group members: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    const json = await response.json();
+    return parseApiResponse(json, "Failed to list user group members", response.status);
+}
+/**
+ * Adds members to a user group.
+ *
+ * @param groupId - User group ID
+ * @param request - Request containing user IDs to add
+ * @param options - Optional configuration
+ * @returns Promise that resolves when members are added
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { addUserGroupMembers } from '@tale/client';
+ *
+ * try {
+ *   await addUserGroupMembers('group_id_here', {
+ *     user_ids: ['user1', 'user2', 'user3']
+ *   });
+ *   console.log('Members added successfully');
+ * } catch (error) {
+ *   console.error('Failed to add members:', error.message);
+ * }
+ * ```
+ */
+export async function addUserGroupMembers(groupId, request, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId is required", 400, "9400");
+    }
+    if (!request.user_ids ||
+        !Array.isArray(request.user_ids) ||
+        request.user_ids.length === 0) {
+        throw new ApiError("user_ids is required and must be a non-empty array", 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}/members`;
+    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 add user group members: ${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 add user group members";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+}
+/**
+ * Removes members from a user group.
+ *
+ * @param groupId - User group ID
+ * @param request - Request containing user IDs to remove
+ * @param options - Optional configuration
+ * @returns Promise that resolves when members are removed
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { removeUserGroupMembers } from '@tale/client';
+ *
+ * try {
+ *   await removeUserGroupMembers('group_id_here', {
+ *     user_ids: ['user1', 'user2']
+ *   });
+ *   console.log('Members removed successfully');
+ * } catch (error) {
+ *   console.error('Failed to remove members:', error.message);
+ * }
+ * ```
+ */
+export async function removeUserGroupMembers(groupId, request, options) {
+    if (!groupId || groupId.trim() === "") {
+        throw new ApiError("groupId is required", 400, "9400");
+    }
+    if (!request.user_ids ||
+        !Array.isArray(request.user_ids) ||
+        request.user_ids.length === 0) {
+        throw new ApiError("user_ids is required and must be a non-empty array", 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(/\/+$/, "") +
+        `/user-group/v1/${encodeURIComponent(groupId)}/members`;
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "DELETE",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token,
+            },
+            body: JSON.stringify(request),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to remove user group members: ${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 remove user group members";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+}
+/**
+ * Gets all user groups that a user belongs to.
+ *
+ * @param userId - User ID
+ * @param options - Optional configuration
+ * @returns Promise resolving to list of user groups
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When API request fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { getUserGroups } from '@tale/client';
+ *
+ * try {
+ *   const groups = await getUserGroups('user_id_here');
+ *   console.log(`User belongs to ${groups.length} groups`);
+ *   groups.forEach(group => console.log('-', group.name));
+ * } catch (error) {
+ *   console.error('Failed to get user groups:', error.message);
+ * }
+ * ```
+ */
+export async function getUserGroups(userId, options) {
+    if (!userId || userId.trim() === "") {
+        throw new ApiError("userId 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(/\/+$/, "") +
+        `/user-group/v1/by-user/${encodeURIComponent(userId)}`;
+    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 user groups: ${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 get user groups";
+        throw new ApiError(errorMsg, response.status, json.code);
+    }
+    if (!json.data || !Array.isArray(json.data)) {
+        throw new ApiError("Invalid user groups response: missing data", response.status);
+    }
+    return json.data;
+}

package/dist/user-group/types.d.ts

@@ -0,0 +1,50 @@
+import type { CommonOptions } from "../common/types.js";
+export interface UserGroupInfo {
+    groupId: string;
+    name: string;
+    description?: string;
+    type?: string;
+    remark?: string;
+    memberCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UserGroupMember {
+    userId: string;
+    nickname: string;
+    username: string;
+    phone: string;
+    email: string;
+    avatarUrl: string;
+    isFrozen: boolean;
+    createdAt: string;
+    remark: string;
+}
+export interface CreateUserGroupRequest {
+    name: string;
+    description?: string;
+    type?: string;
+    remark?: string;
+}
+export interface UpdateUserGroupRequest {
+    name?: string;
+    description?: string;
+    type?: string;
+    remark?: string;
+}
+export interface UserGroupMemberRequest {
+    user_ids: string[];
+}
+export interface UserGroupOptions extends CommonOptions {
+}
+export interface ListUserGroupsRequest {
+    page?: number;
+    size?: number;
+    keyword?: string;
+    sort?: string;
+}
+export interface ListUserGroupMembersRequest {
+    page?: number;
+    size?: number;
+    sort?: string;
+}

package/dist/user-group/types.js

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@turinhub/tale-js-sdk",
+  "version": "1.3.0",
+  "description": "Official TypeScript SDK for Tale backend services",
+  "keywords": [
+    "tale",
+    "sdk",
+    "client",
+    "api",
+    "backend",
+    "typescript"
+  ],
+  "homepage": "https://github.com/turinhub/tale-js-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/turinhub/tale-js-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/turinhub/tale-js-sdk.git"
+  },
+  "license": "MIT",
+  "author": "Turinhub <dev@turinhub.com>",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "pnpm run build && node --env-file=.env --experimental-vm-modules ./node_modules/jest/bin/jest.js",
+    "test:unit": "pnpm run build && node --env-file=.env --experimental-vm-modules ./node_modules/jest/bin/jest.js --testPathIgnorePatterns='integration'",
+    "test:integration": "pnpm run build && node --env-file=.env --experimental-vm-modules ./node_modules/jest/bin/jest.js --testPathPatterns='integration'",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx}\" \"*.json\" \"*.md\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx}\" \"*.json\" \"*.md\"",
+    "docs": "typedoc --entryPoints src/index.ts --out docs",
+    "docs:md": "typedoc --entryPoints src/index.ts --plugin typedoc-plugin-markdown --hideBreadcrumbs --out docs"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.9.3"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}