@amaster.ai/client 1.1.1 → 1.1.2

package/types/auth/password-auth.d.ts

@@ -3,7 +3,7 @@
  * - Email/username/phone + password login
  * - User registration
  * - Password change
- * 
+ *
  * @module auth/password-auth
  */
 
@@ -14,30 +14,29 @@ import type { User } from './user';
 
 /**
  * User registration parameters
- * 
- * At least one identifier (username, email, or phone) must be provided.
  *
+ * At least one identifier (username, email, or phone) must be provided.
  */
 export interface RegisterParams {
   /** Username (optional, but one of username/email/phone required) */
   username?: string;
-  
+
   /** Email address (optional, but one of username/email/phone required) */
   email?: string;
-  
+
   /** Phone number (optional, but one of username/email/phone required) */
   phone?: string;
-  
-  /** 
+
+  /**
    * Password (required, 8-128 characters)
    * Must contain at least: uppercase, lowercase, number
    */
   password: string;
-  
+
   /** Display name for UI */
   displayName?: string;
-  
-  /** 
+
+  /**
    * Captcha verification (optional)
    * Format: "captchaId:userInput"
    */
@@ -51,37 +50,35 @@ export type LoginType = 'username' | 'email' | 'phone';
 
 /**
  * Login parameters for password-based authentication
- * 
+ *
  * The `loginType` field is optional - it will be auto-detected based on
  * which identifier field (username/email/phone) you provide.
- *
  */
 export interface LoginParams {
   /** Login method (optional, auto-detected if not provided) */
   loginType?: LoginType;
-  
+
   /** Username (required if loginType='username') */
   username?: string;
-  
+
   /** Email (required if loginType='email') */
   email?: string;
-  
+
   /** Phone (required if loginType='phone') */
   phone?: string;
-  
+
   /** Password (always required) */
   password: string;
 }
 
 /**
  * Change password parameters
- *
  */
 export interface ChangePasswordParams {
   /** Current password (for verification) */
   oldPassword: string;
-  
-  /** 
+
+  /**
    * New password (8-128 characters)
    * Must contain: uppercase, lowercase, number
    */
@@ -91,53 +88,86 @@ export interface ChangePasswordParams {
 // ==================== Responses ====================
 
 /**
- * Login/Registration response with user info and access token
- *
+ * Login response with user info and access token
  */
 export interface LoginResponse {
   /** User information */
   user: User;
-  
+
   /** JWT access token */
   accessToken: string;
-  
+
   /** Refresh token (if configured) */
   refreshToken?: string;
-  
+
   /** Token expiration time in seconds */
   expiresIn?: number;
+
+  /**
+   * Whether the SDK already handled the current page redirect target.
+   */
+  redirectHandled?: boolean;
+
+  /**
+   * Redirect target consumed by the SDK when `redirectHandled` is true.
+   */
+  redirectTarget?: string;
+}
+
+/**
+ * Registration response
+ *
+ * Depending on backend configuration, registration may or may not auto-login.
+ */
+export interface RegisterResponse {
+  /** Newly created user info */
+  user?: User;
+
+  /** JWT access token when auto-login is enabled */
+  accessToken?: string;
+}
+
+/**
+ * Access token refresh response
+ */
+export interface RefreshTokenResponse {
+  /** New access token */
+  accessToken: string;
 }
 
 /**
  * Generic success response
  */
 export interface SuccessResponse {
-  /** Whether operation was successful */
-  success: boolean;
-  
+  /** Backend status code */
+  statusCode: number;
+
   /** Optional message */
   message?: string;
+
+  /** Backend timestamp */
+  timestamp?: string;
 }
 
 // ==================== API ====================
 
 /**
  * Password Authentication API
- * 
+ *
  * Methods for password-based authentication and account management.
- * 
+ *
  * @since 1.0.0
  */
 export interface PasswordAuthAPI {
   /**
    * Register a new user account
-   * 
+   *
    * Creates a new user account with the provided credentials.
    * Depending on backend configuration, may auto-login after registration.
-   * 
+   *
    * @param params - Registration parameters
    * @returns User info and access token (if auto-login enabled)
-   * 
+   *
    * @example
    * // Register with email
    * const result = await client.auth.register({
@@ -145,81 +175,81 @@ export interface PasswordAuthAPI {
    *   password: 'SecurePass123',
    *   displayName: 'John Doe'
    * });
-   * 
-   * if (result.success) {
+   *
+   * if (result.data) {
    *   console.log('User registered:', result.data.user.uid);
    * }
-   * 
+   *
    * @example
    * // Register with username
    * const result = await client.auth.register({
    *   username: 'johndoe',
    *   password: 'SecurePass123'
    * });
-   * 
+   *
    * @since 1.0.0
    */
   register(params: RegisterParams): Promise<ClientResult<LoginResponse>>;
 
   /**
    * Login with password
-   * 
+   *
    * Authenticates a user with username/email/phone and password.
    * On success, access token is automatically stored and attached to all subsequent requests.
-   * 
+   *
    * @param params - Login credentials
    * @returns User info and access token
-   * 
+   *
    * @example
    * // Login with email
    * const result = await client.auth.login({
    *   email: 'user@example.com',
    *   password: 'myPassword123'
    * });
-   * 
-   * if (result.success) {
+   *
+   * if (result.data) {
    *   console.log('Welcome,', result.data.user.displayName);
    * } else {
-   *   console.error('Login failed:', result.error.message);
+   *   console.error('Login failed:', result.error?.message);
    * }
-   * 
+   *
    * @example
    * // Login with username
    * const result = await client.auth.login({
    *   username: 'johndoe',
    *   password: 'myPassword123'
    * });
-   * 
+   *
    * @example
    * // Login with phone
    * const result = await client.auth.login({
    *   phone: '+1234567890',
    *   password: 'myPassword123'
    * });
-   * 
+   *
    * @since 1.0.0
    */
   login(params: LoginParams): Promise<ClientResult<LoginResponse>>;
 
   /**
    * Change password
-   * 
+   *
    * Changes the password for the current user.
    * Requires the old password for verification.
-   * 
+   *
    * @param params - Old and new passwords
    * @returns Success status
-   * 
+   *
    * @example
    * const result = await client.auth.changePassword({
    *   oldPassword: 'currentPass123',
    *   newPassword: 'newSecurePass456'
    * });
-   * 
-   * if (result.success) {
+   *
+   * if (result.data) {
    *   console.log('Password changed successfully');
    * }
-   * 
+   *
    * @since 1.0.0
    */
   changePassword(params: ChangePasswordParams): Promise<ClientResult<SuccessResponse>>;

package/types/auth/permissions.d.ts

@@ -0,0 +1,46 @@
+/**
+ *  * Local permission checks including:
+ * - Role checks
+ * - Single permission checks
+ * - Any/all permission checks
+ *
+ * @module auth/permissions
+ */
+
+/**
+ * Permission check input
+ */
+export interface PermissionCheck {
+  /** Resource name, such as `user` or `order` */
+  resource: string;
+
+  /** Action name, such as `read` or `write` */
+  action: string;
+}
+
+/**
+ * Local permission helper API
+ *
+ * These methods are synchronous checks against the current cached user state.
+ */
+export interface PermissionsAPI {
+  /**
+   * Check whether the current user has the specified role
+   */
+  hasRole(roleCode: string): boolean;
+
+  /**
+   * Check whether the current user has the specified permission
+   */
+  hasPermission(resource: string, action: string): boolean;
+
+  /**
+   * Check whether the current user has at least one of the specified permissions
+   */
+  hasAnyPermission(permissions: PermissionCheck[]): boolean;
+
+  /**
+   * Check whether the current user has all of the specified permissions
+   */
+  hasAllPermissions(permissions: PermissionCheck[]): boolean;
+}

package/types/auth/profile.d.ts

@@ -3,7 +3,7 @@
  * - Get current user information
  * - Update profile fields
  * - Avatar management
- * 
+ *
  * @module auth/profile
  */
 
@@ -13,52 +13,48 @@ import type { User } from './user';
 // ==================== Parameters ====================
 
 /**
- * Update user profile parameters
- * 
- * All fields are optional - only update what you want to change.
+ * Update current user profile parameters
  *
+ * All fields are optional - only update what you want to change.
  */
-export interface UpdateProfileParams {
+export interface UpdateMeParams {
   /** New display name */
   displayName?: string;
-  
+
   /** New avatar URL */
   avatarUrl?: string;
-  
-  /** New email (may require verification) */
-  email?: string;
-  
-  /** New phone (may require verification) */
-  phone?: string;
 }
 
+/**
+ * @deprecated Use `UpdateMeParams`
+ */
+export type UpdateProfileParams = UpdateMeParams;
+
 // ==================== API ====================
 
 /**
  * User Profile Management API
- * 
+ *
  * Methods for managing user profile information.
  */
 export interface ProfileAPI {
   /**
    * Get current user information
-   * 
+   *
    * Retrieves the profile of the currently authenticated user.
-   * 
-   * @returns Current user info with roles and permissions
    *
+   * @returns Current user info with roles and permissions
    */
   getMe(): Promise<ClientResult<User>>;
 
   /**
-   * Update user profile
-   * 
+   * Update current user profile
+   *
    * Updates one or more fields of the current user's profile.
    * Only the fields provided will be updated.
-   * 
+   *
    * @param params - Fields to update
    * @returns Updated user info
-   *
    */
-  updateProfile(params: UpdateProfileParams): Promise<ClientResult<User>>;
+  updateMe(params: UpdateMeParams): Promise<ClientResult<User>>;
 }

package/types/auth/sessions.d.ts

@@ -0,0 +1,83 @@
+/**
+ *  * Session management including:
+ * - Current session lookup
+ * - Multi-device session listing
+ * - Revoking one session
+ * - Revoking all other sessions
+ *
+ * @module auth/sessions
+ */
+
+import type { ClientResult } from '../common';
+import type { SuccessResponse } from './password-auth';
+
+/**
+ * Session information for multi-device management
+ */
+export interface Session {
+  /** Session ID */
+  id: number;
+
+  /** Session name, such as browser and OS */
+  sessionName?: string;
+
+  /** IP address */
+  ipAddress?: string;
+
+  /** Approximate login location */
+  location?: string;
+
+  /** User agent string */
+  userAgent?: string;
+
+  /** Last-used timestamp */
+  lastUsedAt?: string;
+
+  /** Session creation timestamp */
+  createdAt: string;
+
+  /** Whether this is the current session */
+  isCurrent: boolean;
+}
+
+/**
+ * Revoke-all-sessions response
+ */
+export interface RevokeAllSessionsResponse {
+  /** Backend status code */
+  statusCode: number;
+
+  /** Optional message */
+  message?: string;
+
+  /** Backend timestamp */
+  timestamp?: string;
+
+  /** Number of revoked sessions */
+  revokedCount: number;
+}
+
+/**
+ * Session management API
+ */
+export interface SessionsAPI {
+  /**
+   * Get the current active session
+   */
+  getSession(): Promise<ClientResult<Session>>;
+
+  /**
+   * Get all active sessions for the current user
+   */
+  getSessions(): Promise<ClientResult<Session[]>>;
+
+  /**
+   * Revoke a specific session by ID
+   */
+  revokeSession(sessionId: string): Promise<ClientResult<SuccessResponse>>;
+
+  /**
+   * Revoke all sessions except the current one
+   */
+  revokeAllSessions(): Promise<ClientResult<RevokeAllSessionsResponse>>;
+}

package/types/auth/user.d.ts

@@ -3,71 +3,115 @@
  * - User profile information
  * - Role and permission types
  * - User status enums
- * 
+ *
  * @module auth/user
  */
 
 /**
  * User information with optimized roles and permissions
- * 
+ *
  * Roles and permissions are returned as simple string arrays for efficient client-side use:
  * - `roles`: ["admin", "user", "manager"]
  * - `permissions`: ["user.read", "user.write", "order.read"]
- *
  */
 export interface User {
   /** Unique user identifier */
   uid: string;
-  
+
   /** Username (null if not set) */
   username: string | null;
-  
+
   /** Email address (null if not set) */
   email: string | null;
-  
+
   /** Phone number (null if not set) */
   phone: string | null;
-  
+
   /** Display name shown in UI */
   displayName: string | null;
-  
+
   /** Avatar image URL */
   avatarUrl: string | null;
-  
+
   /** Whether account is active */
   isActive: boolean;
-  
+
   /** Whether email is verified */
   emailVerified: boolean;
-  
+
   /** Whether phone is verified */
   phoneVerified: boolean;
-  
+
   /** Email verification timestamp (ISO 8601) */
   emailVerifiedAt: string | null;
-  
+
   /** Phone verification timestamp (ISO 8601) */
   phoneVerifiedAt: string | null;
-  
-  /** 
+
+  /**
    * Role codes assigned to user
-   * 
+   *
    * Includes system roles and custom roles:
    * - System roles: "anonymous" (unauthenticated), "member" (default), "admin"
    * - Custom roles: defined in app.settings.yml
-   *
    */
   roles: string[];
-  
-  /** 
+
+  /**
    * Permission names granted to user
    * Format: "resource.action"
    */
   permissions: string[];
-  
+
   /** Account creation timestamp (ISO 8601) */
   createdAt: string;
-  
+
   /** Last update timestamp (ISO 8601) */
   updatedAt: string;
 }
+
+/**
+ * Detailed role information
+ */
+export interface RoleDetail {
+  id: number;
+  code: string;
+  displayName: string;
+  description?: string;
+  isSystem: boolean;
+}
+
+/**
+ * Detailed permission information
+ */
+export interface PermissionDetail {
+  id: number;
+  name: string;
+  resource: string;
+  action: string;
+  description?: string;
+  sourceType: 'system' | 'role' | 'direct';
+}
+
+/**
+ * @deprecated Use string role codes from `User.roles`
+ */
+export interface Role {
+  id: number;
+  code: string;
+  displayName: string;
+  description?: string;
+  isSystem: boolean;
+}
+
+/**
+ * @deprecated Use string permission names from `User.permissions`
+ */
+export interface Permission {
+  id: number;
+  name: string;
+  resource: string;
+  action: string;
+  description?: string;
+  sourceType: 'system' | 'role' | 'direct';
+}