@turinhub/tale-js-sdk 1.3.0

package/dist/auth/index.js

@@ -0,0 +1,522 @@
+import { getAppToken } from "../token.js";
+import { ApiError, ConfigurationError, NetworkError } from "../errors.js";
+/**
+ * Authenticates a user with username and password.
+ *
+ * @param credentials - User login credentials
+ * @param options - Optional configuration for the login request
+ * @returns Promise resolving to login response with user info and token
+ * @throws {ConfigurationError} When required environment variables (TALE_BASE_URL, TALE_APP_KEY) are missing
+ * @throws {ApiError} When authentication fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { login } from '@tale/client';
+ *
+ * try {
+ *   const result = await login({
+ *     username: 'johndoe',
+ *     password: 'secure_password_123'
+ *   });
+ *   console.log('Login successful:', result.user.username);
+ *   console.log('User token:', result.token.token);
+ * } catch (error) {
+ *   console.error('Login failed:', error.message);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { login } from '@tale/client';
+ *
+ * // Login with include parameters to control what data is returned
+ * const result = await login({
+ *   username: 'johndoe',
+ *   password: 'secure_password_123'
+ * }, {
+ *   include_rbac: true,           // Include roles and privileges (SDK default: false)
+ *   include_user_groups: true,    // Include user groups (SDK default: false)
+ *   include_login_methods: true,  // Include login methods (SDK default: false)
+ *   include_attributes: true,     // Include user attributes (SDK default: false)
+ *   include_acl: true             // Include ACL records (SDK default: false)
+ * });
+ * ```
+ *
+ * @note The function requires the following environment variables:
+ * - TALE_BASE_URL: Base URL for Tale backend services
+ * - TALE_APP_KEY: Application key for authentication
+ * @note By default, all include parameters are set to false for better performance.
+ *       Explicitly set them to true if you need the additional data.
+ *
+ * @param options.include_rbac Include roles and privileges; default false
+ * @param options.include_login_methods Include user login methods; default false
+ * @param options.include_user_groups Include user groups; default false
+ * @param options.include_attributes Include user attributes; default false
+ * @param options.include_acl Include ACL records; default false
+ */
+export async function login(credentials, options) {
+    // Validate required fields
+    if (!credentials.username || credentials.username.trim() === "") {
+        throw new ApiError("username is required", 400, "9400");
+    }
+    if (!credentials.password || credentials.password.trim() === "") {
+        throw new ApiError("password is required", 400, "9400");
+    }
+    // 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");
+    }
+    // Get app key from environment variable
+    const appKey = env?.TALE_APP_KEY;
+    if (!appKey) {
+        throw new ConfigurationError("Missing required environment variable: TALE_APP_KEY");
+    }
+    // Build URL with query parameters
+    const url = new URL(String(base).replace(/\/+$/, "") + "/auth/v1/login/username-password");
+    // Add include parameters as query params (SDK defaults to false)
+    url.searchParams.set("include_rbac", String(options?.include_rbac ?? false));
+    url.searchParams.set("include_login_methods", String(options?.include_login_methods ?? false));
+    url.searchParams.set("include_user_groups", String(options?.include_user_groups ?? false));
+    url.searchParams.set("include_attributes", String(options?.include_attributes ?? false));
+    url.searchParams.set("include_acl", String(options?.include_acl ?? false));
+    // Build request body
+    const requestBody = {
+        username: credentials.username.trim(),
+        password: credentials.password,
+        app_key: appKey,
+        device_name: options?.device_name,
+        device_fingerprint: options?.device_fingerprint,
+        scope: options?.scope || "",
+    };
+    let response;
+    try {
+        response = await globalThis.fetch(url.toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to authenticate user: ${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 login response: ${error instanceof Error ? error.message : "Invalid JSON"}`, response.status);
+    }
+    // Handle authentication errors based on response status
+    if (response.status === 400) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "Authentication failed";
+        throw new ApiError(errorMsg, response.status, "9400");
+    }
+    if (response.status === 403) {
+        throw new ApiError("Account is frozen or access forbidden", response.status, "9403");
+    }
+    if (response.status === 401) {
+        throw new ApiError("Invalid app_key or authentication failed", response.status, "9401");
+    }
+    if (!response.ok) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "Authentication failed";
+        throw new ApiError(errorMsg, response.status);
+    }
+    // Handle response data structure - check if data is wrapped in a 'data' field
+    const responseData = json.data || json;
+    // Validate response structure
+    if (!responseData || !responseData.user || !responseData.token) {
+        console.error("Invalid response structure:", { json, responseData });
+        throw new ApiError("Invalid login response: missing required data", response.status);
+    }
+    // Build standard response structure
+    const loginResponse = {
+        app: responseData.app,
+        user: responseData.user,
+        token: responseData.token,
+        user_roles: responseData.user_roles || [],
+        user_privileges: responseData.user_privileges || [],
+        user_groups: responseData.user_groups || [],
+        user_login_methods: responseData.user_login_methods || [],
+    };
+    return loginResponse;
+}
+/**
+ * Validates a user token.
+ *
+ * @param token - User token to validate
+ * @param options - Optional configuration for validation
+ * @returns Promise resolving to validation result
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When validation fails
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { validateToken } from '@tale/client';
+ *
+ * try {
+ *   const result = await validateToken('tu_user_token_here');
+ *   console.log('Token is valid');
+ * } catch (error) {
+ *   console.error('Token validation failed:', error.message);
+ * }
+ * ```
+ */
+export async function validateToken(token, options) {
+    // Validate required fields
+    if (!token || token.trim() === "") {
+        throw new ApiError("token is required", 400, "9400");
+    }
+    // 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 = new URL(String(base).replace(/\/+$/, "") + "/auth/v1/assert_token");
+    if (options?.scope) {
+        url.searchParams.append("scope", options.scope);
+    }
+    let response;
+    try {
+        response = await globalThis.fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "x-t-token": token.trim(),
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to validate token: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    // Token is valid if we get a 200 response
+    return response.ok;
+}
+/**
+ * Initiates SMS login by sending verification code for login or registration.
+ *
+ * @param phone - Phone number for sending SMS
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to SMS sending response
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When SMS sending fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { loginWithSms } from '@tale/client';
+ *
+ * try {
+ *   const result = await loginWithSms('+8613800138000');
+ *   console.log('SMS sent:', result.sms_id);
+ *   console.log('Type:', result.type); // 'login' or 'register'
+ * } catch (error) {
+ *   console.error('SMS sending failed:', error.message);
+ * }
+ * ```
+ */
+export async function loginWithSms(phone, options) {
+    // Validate required fields
+    if (!phone || phone.trim() === "") {
+        throw new ApiError("phone number is required", 400, "9400");
+    }
+    // Determine base URL from environment variables
+    const env = globalThis?.process?.env ?? import.meta?.env ?? undefined;
+    const base = env?.TALE_BASE_URL;
+    if (!base) {
+        throw new ConfigurationError("Missing required environment variable: TALE_BASE_URL");
+    }
+    // Use provided app token or get one from token service
+    const authToken = options?.appToken ?? (await getAppToken());
+    const url = new URL(String(base).replace(/\/+$/, "") + "/auth/v1/sms/login_or_register");
+    url.searchParams.append("phone", phone.trim());
+    let response;
+    try {
+        response = await globalThis.fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "x-t-token": authToken,
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to send SMS verification: ${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 SMS response: ${error instanceof Error ? error.message : "Invalid JSON"}`, response.status);
+    }
+    // Handle API errors
+    if (response.status === 400) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "Invalid phone number format";
+        throw new ApiError(errorMsg, response.status, "9400");
+    }
+    if (response.status === 429) {
+        throw new ApiError("SMS sending rate limit exceeded", response.status, "9705");
+    }
+    if (!response.ok) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "SMS sending failed";
+        throw new ApiError(errorMsg, response.status);
+    }
+    // Handle response data structure - check if data is wrapped in a 'data' field
+    const responseData = json.data || json;
+    // Validate response structure
+    if (!responseData || !responseData.sms_id || !responseData.type) {
+        throw new ApiError("Invalid SMS response: missing required data", response.status);
+    }
+    return {
+        app_key: responseData.app_key,
+        phone: responseData.phone,
+        type: responseData.type,
+        sms_id: responseData.sms_id,
+        expired_at: responseData.expired_at,
+    };
+}
+/**
+ * Verifies SMS code and authenticates user (login or register).
+ *
+ * @param request - SMS verification request with sms_id, code, and optional user data
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to login response with user info and token
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When verification fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { verifySmsCode } from '@tale/client';
+ *
+ * try {
+ *   const result = await verifySmsCode({
+ *     sms_id: 'uuid-here',
+ *     sms_type: 'login',
+ *     verification_code: '123456'
+ *   });
+ *   console.log('Login successful:', result.user.user_id);
+ *   console.log('User token:', result.token.token);
+ * } catch (error) {
+ *   console.error('SMS verification failed:', error.message);
+ * }
+ * ```
+ */
+export async function verifySmsCode(request, options) {
+    // Validate required fields
+    if (!request.sms_id || request.sms_id.trim() === "") {
+        throw new ApiError("sms_id is required", 400, "9400");
+    }
+    if (!request.sms_type || !["login", "register"].includes(request.sms_type)) {
+        throw new ApiError('sms_type must be "login" or "register"', 400, "9400");
+    }
+    if (!request.verification_code || request.verification_code.trim() === "") {
+        throw new ApiError("verification_code is required", 400, "9400");
+    }
+    // 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");
+    }
+    // Use provided app token or get one from token service
+    const authToken = options?.appToken ?? (await getAppToken(options));
+    const url = new URL(String(base).replace(/\/+$/, "") + "/auth/v1/sms/verify");
+    url.searchParams.append("sms_id", request.sms_id.trim());
+    url.searchParams.append("sms_type", request.sms_type);
+    url.searchParams.append("verification_code", request.verification_code.trim());
+    let response;
+    try {
+        response = await globalThis.fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "x-t-token": authToken,
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to verify SMS code: ${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 SMS verification response: ${error instanceof Error ? error.message : "Invalid JSON"}`, response.status);
+    }
+    // Handle verification errors
+    if (response.status === 400) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "SMS verification failed";
+        throw new ApiError(errorMsg, response.status, "9739");
+    }
+    if (response.status === 403) {
+        throw new ApiError("Account is frozen or access forbidden", response.status, "9403");
+    }
+    if (!response.ok) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "SMS verification failed";
+        throw new ApiError(errorMsg, response.status);
+    }
+    // Handle response data structure - check if data is wrapped in a 'data' field
+    const responseData = json.data || json;
+    // Validate response structure
+    if (!responseData || !responseData.user || !responseData.token) {
+        throw new ApiError("Invalid SMS verification response: missing required data", response.status);
+    }
+    // Build standard response structure
+    const smsLoginResponse = {
+        app: responseData.app,
+        user: responseData.user,
+        token: responseData.token,
+        user_roles: responseData.user_roles || [],
+        user_privileges: responseData.user_privileges || [],
+        user_groups: responseData.user_groups || [],
+        user_login_methods: responseData.user_login_methods || [],
+    };
+    return smsLoginResponse;
+}
+/**
+ * Registers a new user with SMS verification and optional additional information.
+ *
+ * @param request - Registration request with SMS verification and optional user data
+ * @param options - Optional configuration for the request
+ * @returns Promise resolving to registration response with user info and token
+ * @throws {ConfigurationError} When required environment variables are missing
+ * @throws {ApiError} When registration fails or returns invalid response
+ * @throws {NetworkError} When network request fails
+ *
+ * @example
+ * ```typescript
+ * import { registerWithSms } from '@tale/client';
+ *
+ * try {
+ *   const result = await registerWithSms({
+ *     sms_id: 'uuid-here',
+ *     sms_type: 'register',
+ *     verification_code: '123456',
+ *     username: 'newuser',
+ *     password_encrypted: 'encrypted_password'
+ *   });
+ *   console.log('Registration successful:', result.user.user_id);
+ *   console.log('User token:', result.token.token);
+ * } catch (error) {
+ *   console.error('Registration failed:', error.message);
+ * }
+ * ```
+ */
+export async function registerWithSms(request, options) {
+    // Validate required fields for registration
+    if (request.sms_type !== "register") {
+        throw new ApiError('sms_type must be "register" for registration', 400, "9400");
+    }
+    // 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");
+    }
+    // Use provided app token or get one from token service
+    const authToken = options?.appToken ?? (await getAppToken(options));
+    const url = String(base).replace(/\/+$/, "") + "/auth/v1/sms/register/verify";
+    // Build request body
+    const requestBody = {
+        sms_id: request.sms_id.trim(),
+        sms_type: request.sms_type,
+        verification_code: request.verification_code.trim(),
+        username: request.username?.trim(),
+        password_encrypted: request.password_encrypted,
+    };
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: "POST",
+            headers: {
+                "x-t-token": authToken,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (error) {
+        throw new NetworkError(`Failed to register with SMS: ${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 registration response: ${error instanceof Error ? error.message : "Invalid JSON"}`, response.status);
+    }
+    // Handle registration errors
+    if (response.status === 400) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "SMS registration failed";
+        throw new ApiError(errorMsg, response.status, "9739");
+    }
+    if (response.status === 403) {
+        throw new ApiError("Account is frozen or access forbidden", response.status, "9403");
+    }
+    if (!response.ok) {
+        const errorMsg = typeof json === "object" &&
+            json !== null &&
+            ("message" in json || "msg" in json)
+            ? String(json.message || json.msg)
+            : "SMS registration failed";
+        throw new ApiError(errorMsg, response.status);
+    }
+    // Handle response data structure - check if data is wrapped in a 'data' field
+    const responseData = json.data || json;
+    // Validate response structure
+    if (!responseData || !responseData.user || !responseData.token) {
+        throw new ApiError("Invalid registration response: missing required data", response.status);
+    }
+    // Build standard response structure
+    const registrationResponse = {
+        app: responseData.app,
+        user: responseData.user,
+        token: responseData.token,
+        user_roles: responseData.user_roles || [],
+        user_privileges: responseData.user_privileges || [],
+        user_groups: responseData.user_groups || [],
+        user_login_methods: responseData.user_login_methods || [],
+    };
+    return registrationResponse;
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,127 @@
+import type { AppInfo, User, UserGroup, Role, Privilege, CommonOptions } from "../common/types.js";
+export type { AppInfo, UserGroup };
+/**
+ * Auth user information (extends User with non-null remark)
+ */
+export interface AuthUser extends Omit<User, "remark"> {
+    remark: string;
+}
+/**
+ * User token information
+ */
+export interface UserToken {
+    token: string;
+    scope: string;
+    device_name?: string;
+    device_fingerprint?: string;
+    granted_at: string;
+    expired_at: string;
+}
+/**
+ * Auth role (extends base Role with additional fields)
+ */
+export interface AuthRole extends Role {
+    assigned_at: string;
+    expires_at?: string;
+    is_active: boolean;
+}
+/**
+ * Auth privilege (extends base Privilege with additional fields)
+ */
+export interface AuthPrivilege extends Privilege {
+    granted_directly: boolean;
+    role_id?: string;
+    assigned_at: string;
+    expires_at?: string;
+    is_active: boolean;
+}
+/**
+ * Auth user login method
+ */
+export interface AuthUserLoginMethod {
+    method_type: string;
+    identifier: string;
+    is_active: boolean;
+    created_at: string;
+    last_used_at?: string;
+}
+export interface LoginRequest {
+    username: string;
+    password: string;
+}
+export interface LoginOptions {
+    baseUrl?: string;
+    device_name?: string;
+    device_fingerprint?: string;
+    scope?: string;
+    include_rbac?: boolean;
+    include_login_methods?: boolean;
+    include_user_groups?: boolean;
+    include_attributes?: boolean;
+    include_acl?: boolean;
+}
+export interface LoginResponse {
+    app: AppInfo;
+    user: AuthUser;
+    token: UserToken;
+    user_roles: AuthRole[];
+    user_privileges: AuthPrivilege[];
+    user_groups: UserGroup[];
+    user_login_methods: AuthUserLoginMethod[];
+}
+export interface LoginJson {
+    app: AppInfo;
+    user: AuthUser;
+    token: UserToken;
+    user_roles: AuthRole[];
+    user_privileges: AuthPrivilege[];
+    user_groups: UserGroup[];
+    user_login_methods: AuthUserLoginMethod[];
+}
+export interface LoginWithSmsOptions {
+    appToken?: string;
+}
+export interface VerifySmsOptions extends CommonOptions {
+    device_name?: string;
+    device_fingerprint?: string;
+    scope?: string;
+}
+export interface SendSmsResponse {
+    app_key: string;
+    phone: string;
+    type: "login" | "register";
+    sms_id: string;
+    expired_at: string;
+}
+export interface SendSmsJson {
+    app_key: string;
+    phone: string;
+    type: "login" | "register";
+    sms_id: string;
+    expired_at: string;
+}
+export interface VerifySmsRequest {
+    sms_id: string;
+    sms_type: "login" | "register";
+    verification_code: string;
+    username?: string;
+    password_encrypted?: string;
+}
+export interface SmsLoginResponse {
+    app: AppInfo;
+    user: AuthUser;
+    token: UserToken;
+    user_roles: AuthRole[];
+    user_privileges: AuthPrivilege[];
+    user_groups: UserGroup[];
+    user_login_methods: AuthUserLoginMethod[];
+}
+export interface SmsLoginJson {
+    app: AppInfo;
+    user: AuthUser;
+    token: UserToken;
+    user_roles: AuthRole[];
+    user_privileges: AuthPrivilege[];
+    user_groups: UserGroup[];
+    user_login_methods: AuthUserLoginMethod[];
+}

package/dist/auth/types.js

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