@amaster.ai/auth-client 1.0.0-beta.1

package/dist/types-4MBObpYA.d.cts

@@ -0,0 +1,449 @@
+/**
+ * ============================================================================
+ * @amaster.ai/auth-client - Type Definitions
+ * ============================================================================
+ * 
+ * 🤖 AI NAVIGATION - Read these files based on your task:
+ * 
+ * 1. Need LOGIN/REGISTER/LOGOUT? → Read: ./auth.d.ts
+ * 2. Need PERMISSION checks? → Read: ./permissions.d.ts
+ * 3. Need USER profile management? → Read: ./user.d.ts
+ * 4. Need OAUTH binding? → Read: ./oauth.d.ts
+ * 5. Need SESSION management? → Read: ./sessions.d.ts
+ * 
+ * ============================================================================
+ */
+/**
+ * Authentication SDK Types
+ */
+/**
+ * Authentication client configuration options
+ *
+ * @example
+ * Minimal configuration (recommended):
+ * ```typescript
+ * const options: AuthClientOptions = {
+ *   onTokenExpired: () => window.location.href = "/login",
+ * };
+ * ```
+ *
+ * @example
+ * Full configuration:
+ * ```typescript
+ * const options: AuthClientOptions = {
+ *   baseURL: "https://api.example.com",
+ *   storage: "sessionStorage",
+ *   onTokenExpired: () => handleTokenExpired(),
+ *   onUnauthorized: () => handleUnauthorized(),
+ * };
+ * ```
+ */
+interface AuthClientOptions {
+    /**
+     * API base URL (defaults to window.location.origin)
+     * @example "https://api.example.com"
+     */
+    baseURL?: string;
+    /**
+     * Token storage type (defaults to "localStorage")
+     * - localStorage: Persistent across browser sessions
+     * - sessionStorage: Cleared when browser tab closes
+     */
+    storage?: "localStorage" | "sessionStorage";
+    /**
+     * Callback when token expires
+     * @example () => window.location.href = "/login"
+     */
+    onTokenExpired?: () => void;
+    /**
+     * Callback when server returns 401 Unauthorized
+     * @example () => alert("Session expired")
+     */
+    onUnauthorized?: () => void;
+}
+/**
+ * User information with roles and permissions
+ *
+ * Note: This is an optimized format for client-side use.
+ * - roles: Only role codes (e.g., ["admin", "user"])
+ * - permissions: Only permission names (e.g., ["user.read", "user.write"])
+ * - dataScopes: Not included, use getPermissionScope() to load on-demand
+ *
+ * @example
+ * ```typescript
+ * const user: User = {
+ *   uid: "123",
+ *   email: "user@example.com",
+ *   displayName: "John Doe",
+ *   roles: ["admin", "user"],
+ *   permissions: ["user.read", "user.write", "order.read"],
+ *   // ... other fields
+ * };
+ *
+ * // Check permissions
+ * if (user.permissions.includes("user.delete")) {
+ *   // Can delete users
+ * }
+ * ```
+ */
+interface User {
+    /** Unique user ID */
+    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 for 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 */
+    emailVerifiedAt: string | null;
+    /** Phone verification timestamp */
+    phoneVerifiedAt: string | null;
+    /**
+     * Role codes assigned to user
+     * @example ["admin", "user", "manager"]
+     */
+    roles: string[];
+    /**
+     * Permission names granted to user
+     * @example ["user.read", "user.write", "order.read"]
+     */
+    permissions: string[];
+    /** Account creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/** Detailed role information (for admin/management use) */
+interface RoleDetail {
+    id: number;
+    code: string;
+    displayName: string;
+    description?: string;
+    isSystem: boolean;
+}
+/** Detailed permission information (for admin/management use) */
+interface PermissionDetail {
+    id: number;
+    name: string;
+    resource: string;
+    action: string;
+    description?: string;
+    sourceType: "system" | "role" | "direct";
+}
+/** @deprecated Use string[] for roles in User type */
+interface Role {
+    id: number;
+    code: string;
+    displayName: string;
+    description?: string;
+    isSystem: boolean;
+}
+/** @deprecated Use string[] for permissions in User type */
+interface Permission {
+    id: number;
+    name: string;
+    resource: string;
+    action: string;
+    description?: string;
+    sourceType: "system" | "role" | "direct";
+}
+/**
+ * Data scope defining what data a user can access for a permission
+ *
+ * @example
+ * All data:
+ * ```typescript
+ * { scopeType: "all", scopeFilter: null }
+ * ```
+ *
+ * @example
+ * Department-scoped:
+ * ```typescript
+ * {
+ *   scopeType: "department",
+ *   scopeFilter: { departmentId: 123 }
+ * }
+ * ```
+ *
+ * @example
+ * Self only:
+ * ```typescript
+ * { scopeType: "self", scopeFilter: null }
+ * ```
+ */
+interface DataScope {
+    /**
+     * Type of data scope:
+     * - "all": User can access all data
+     * - "organization": User can access data in their organization
+     * - "department": User can access data in their department
+     * - "self": User can only access their own data
+     * - "custom": Custom filter defined in scopeFilter
+     */
+    scopeType: "all" | "organization" | "department" | "self" | "custom";
+    /**
+     * Custom filter conditions (used when scopeType="custom")
+     * @example { departmentId: 123, regionId: 456 }
+     */
+    scopeFilter: any;
+}
+/**
+ * User registration parameters
+ * At least one of username/email/phone must be provided
+ *
+ * @example
+ * Register with email:
+ * ```typescript
+ * const params: RegisterParams = {
+ *   email: "user@example.com",
+ *   password: "Password@123",
+ *   displayName: "John Doe",
+ * };
+ * ```
+ *
+ * @example
+ * Register with captcha:
+ * ```typescript
+ * const captcha = await authClient.getCaptcha();
+ * const userInput = "AB12"; // User enters this
+ * const params: RegisterParams = {
+ *   email: "user@example.com",
+ *   password: "Password@123",
+ *   captcha: `${captcha.data.captchaId}:${userInput}`,
+ * };
+ * ```
+ */
+interface RegisterParams {
+    /** Username (optional, at least one of username/email/phone required) */
+    username?: string;
+    /** Email address (optional, at least one of username/email/phone required) */
+    email?: string;
+    /** Phone number (optional, at least one of username/email/phone required) */
+    phone?: string;
+    /**
+     * Password (required)
+     * @example "Password@123"
+     */
+    password: string;
+    /**
+     * Display name for UI
+     * @example "John Doe"
+     */
+    displayName?: string;
+    /**
+     * Captcha verification (optional)
+     * Format: "captchaId:userInput"
+     * @example "uuid-123:AB12"
+     */
+    captcha?: string;
+}
+/**
+ * Login type: username, email, or phone
+ */
+type LoginType = "username" | "email" | "phone";
+/**
+ * Login parameters for password-based authentication
+ *
+ * @example
+ * Login with email:
+ * ```typescript
+ * const params: LoginParams = {
+ *   loginType: "email",
+ *   email: "user@example.com",
+ *   password: "Password@123",
+ * };
+ * ```
+ *
+ * @example
+ * Login with username:
+ * ```typescript
+ * const params: LoginParams = {
+ *   loginType: "username",
+ *   username: "john_doe",
+ *   password: "Password@123",
+ * };
+ * ```
+ */
+interface LoginParams {
+    /** Login method: "username" | "email" | "phone" */
+    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;
+}
+type CodeLoginType = "email" | "phone";
+interface CodeLoginParams {
+    loginType: CodeLoginType;
+    email?: string;
+    phone?: string;
+    code: string;
+}
+type SendCodeType = "email" | "phone";
+interface SendCodeParams {
+    type: SendCodeType;
+    email?: string;
+    phone?: string;
+}
+/**
+ * Login response with user info and access token
+ * Both user and accessToken are required for successful login
+ *
+ * @example
+ * ```typescript
+ * const result = await authClient.login({ ... });
+ * if (result.data) {
+ *   const { user, accessToken } = result.data;
+ *   console.log(`Welcome ${user.displayName}`);
+ *   console.log(`Token: ${accessToken}`);
+ * }
+ * ```
+ */
+interface LoginResponse {
+    /** User information with roles and permissions */
+    user: User;
+    /** Access token (JWT) for API authentication */
+    accessToken: string;
+    /** Refresh token for obtaining new access tokens */
+    refreshToken?: string;
+    /** Token expiration time in seconds */
+    expiresIn?: number;
+}
+/**
+ * Register response - user and accessToken are optional
+ * depending on backend configuration:
+ * - Both returned: Auto-login after registration
+ * - Only user: Registration successful but requires email verification
+ * - Neither: Registration successful, user must login separately
+ *
+ * @example
+ * ```typescript
+ * const result = await authClient.register({ ... });
+ * if (result.data?.user && result.data?.accessToken) {
+ *   console.log("Registered and logged in:", result.data.user);
+ * } else {
+ *   console.log("Registered, please verify email or login manually");
+ * }
+ * ```
+ */
+interface RegisterResponse {
+    /** User information with roles and permissions (optional) */
+    user?: User;
+    /** Access token (JWT) for API authentication (optional) */
+    accessToken?: string;
+}
+/**
+ * Captcha response with image and verification ID
+ *
+ * @example
+ * ```typescript
+ * const result = await authClient.getCaptcha();
+ * if (result.data) {
+ *   // Display image to user
+ *   document.getElementById("img").src = result.data.captchaImage;
+ *
+ *   // After user inputs code, verify with:
+ *   const captcha = `${result.data.captchaId}:${userInputCode}`;
+ * }
+ * ```
+ */
+interface CaptchaResponse {
+    /** Unique captcha ID for verification */
+    captchaId: string;
+    /** Base64 encoded captcha image (data:image/png;base64,...) */
+    captchaImage: string;
+    /** Expiration time in seconds (typically 300 = 5 minutes) */
+    expiresIn: number;
+}
+interface RefreshTokenResponse {
+    accessToken: string;
+}
+interface UpdateMeParams {
+    displayName?: string;
+    avatarUrl?: string;
+}
+interface ChangePasswordParams {
+    oldPassword: string;
+    newPassword: string;
+}
+type OAuthProvider = "google" | "github" | "wechat" | "platform";
+interface OAuthBinding {
+    provider: OAuthProvider;
+    providerId: string;
+    email: string;
+    displayName: string;
+    avatarUrl: string | null;
+    createdAt: string;
+}
+interface Session {
+    id: string;
+    userAgent: string;
+    ip: string;
+    lastActiveAt: string;
+    createdAt: string;
+    isCurrent: boolean;
+}
+type AuthEvent = "login" | "logout" | "tokenExpired" | "tokenRefreshed" | "unauthorized";
+type EventHandler = (...args: any[]) => void;
+/**
+ * Standard success response from backend
+ * @example
+ * ```typescript
+ * {
+ *   statusCode: 200,
+ *   message: "操作成功",
+ *   timestamp: "2026-02-02T08:17:11.045072301Z"
+ * }
+ * ```
+ */
+interface SuccessResponse {
+    statusCode: number;
+    message?: string;
+    timestamp?: string;
+}
+/**
+ * Revoke all sessions response
+ * @example
+ * ```typescript
+ * {
+ *   statusCode: 200,
+ *   message: "已撤销所有会话",
+ *   timestamp: "2026-02-02T08:17:11.045072301Z",
+ *   revokedCount: 3
+ * }
+ * ```
+ */
+interface RevokeAllSessionsResponse {
+    statusCode: number;
+    message?: string;
+    timestamp?: string;
+    revokedCount: number;
+}
+interface CheckPermissionResponse {
+    hasPermission: boolean;
+    dataScope?: DataScope;
+}
+interface BatchCheckPermissionsResponse {
+    [permission: string]: boolean;
+}
+interface PermissionScopeResponse {
+    permission: string;
+    dataScope: DataScope;
+}
+
+export type { AuthClientOptions as A, BatchCheckPermissionsResponse as B, ChangePasswordParams as C, DataScope as D, EventHandler as E, LoginParams as L, OAuthBinding as O, Permission as P, RefreshTokenResponse as R, SendCodeParams as S, UpdateMeParams as U, AuthEvent as a, CaptchaResponse as b, CheckPermissionResponse as c, CodeLoginParams as d, CodeLoginType as e, LoginResponse as f, LoginType as g, OAuthProvider as h, PermissionDetail as i, PermissionScopeResponse as j, RegisterParams as k, RegisterResponse as l, RevokeAllSessionsResponse as m, Role as n, RoleDetail as o, SendCodeType as p, Session as q, SuccessResponse as r, User as s };