@relia-fe/core 0.0.1 → 0.0.2

package/dist/api/index.d.mts

@@ -0,0 +1,317 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren } from 'react';
+import * as swr__internal from 'swr/_internal';
+import * as swr from 'swr';
+import { SWRConfiguration } from 'swr';
+import * as swr_mutation from 'swr/mutation';
+import { SWRMutationConfiguration } from 'swr/mutation';
+
+/**
+ * API 客户端类型定义
+ */
+
+interface BaseResponse<T> {
+    datetime?: string;
+    success: boolean;
+    code: number;
+    message?: string;
+    data?: T;
+}
+interface PaginationReq {
+    page?: number;
+    size?: number;
+}
+interface PaginationResp<T> {
+    items: T[];
+    total: number;
+    current: number;
+    size: number;
+}
+/** 认证上下文类型 */
+type AuthType = "wallet-connect" | "token-refresh" | "request-init";
+/** 认证结果（成功时返回） */
+interface AuthResult {
+    success: true;
+    token: string;
+}
+/** 认证状态 */
+interface AuthState {
+    status: "idle" | "authenticating" | "authenticated" | "unauthenticated";
+    address?: string;
+    error?: AuthError;
+}
+/** 状态变化监听器 */
+type AuthStateListener = (state: AuthState) => void;
+
+/**
+ * Token 存储服务接口
+ */
+interface ITokenStorageService {
+    setToken(token: string | undefined, address?: string): void;
+    getToken(address?: string): string | null;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * 默认 Token 存储服务实现（localStorage）
+ * 支持多地址 token 存储
+ */
+declare class TokenStorageService implements ITokenStorageService {
+    private listeners;
+    private boundHandleStorage;
+    setToken(token: string | undefined, address?: string): void;
+    getToken(address?: string): string | null;
+    private getMap;
+    private saveMap;
+    subscribe(listener: () => void): () => void;
+}
+/** 默认单例 */
+declare const defaultTokenStorageService: TokenStorageService;
+
+type RefreshTokenFn = (context: AuthType) => Promise<AuthResult>;
+interface AuthServiceConfig {
+    refreshToken: RefreshTokenFn;
+    tokenStorageService?: ITokenStorageService;
+}
+/**
+ * Authentication service with concurrency control, token storage, and state management
+ */
+declare class AuthService {
+    private refreshToken;
+    private tokenStorageService;
+    private authPromise;
+    private state;
+    private listeners;
+    constructor(config: AuthServiceConfig);
+    /**
+     * Authenticate with concurrency control
+     * Multiple concurrent calls will share the same Promise
+     * Stores token on success
+     */
+    authenticate(context: AuthType): Promise<AuthResult>;
+    /**
+     * 重置内部认证状态（私有方法）
+     */
+    private reset;
+    /**
+     * Get current token for the current wallet address
+     */
+    getToken(): string | null;
+    /**
+     * 检查地址是否有有效 token（私有方法）
+     */
+    private isAddressAuthenticated;
+    /**
+     * Logout: clear token for current address and update state
+     */
+    logout(): void;
+    /**
+     * Get current authentication state
+     */
+    getState(): AuthState;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(listener: AuthStateListener): () => void;
+    /**
+     * Handle wallet address changes
+     * Note: Wallet disconnection should be handled externally by calling logout()
+     */
+    handleWalletChange(address: string | undefined): void;
+    /**
+     * 处理 StorageChange 事件（用于多选项卡同步）
+     * 当 localStorage 在另一个选项卡中发生更改时调用
+     */
+    private handleStorageChange;
+    /**
+     * 更新状态并通知监听者
+     */
+    private setState;
+}
+
+declare const isBrowser: boolean;
+interface BaseRequestConfig {
+    baseURL: string;
+    headers?: Record<string, string>;
+}
+/**
+ * 创建不带认证的基础请求实例
+ */
+declare const createBaseRequest: (config: BaseRequestConfig) => AxiosInstance;
+/**
+ * 获取或创建默认基础请求实例
+ */
+declare const getBaseRequest: () => AxiosInstance;
+/**
+ * 配置默认基础请求实例
+ */
+declare const configureBaseRequest: (config: BaseRequestConfig) => void;
+interface CreateAuthRequestConfig {
+    authService: AuthService;
+    axiosConfig?: AxiosRequestConfig;
+}
+/**
+ * 创建带鉴权 Axios 实例
+ */
+declare const createAuthRequest: (config: CreateAuthRequestConfig) => AxiosInstance;
+
+type FetchIdentity<Resp, Req> = ResourceIdentity<Resp, Req> | MutationIdentity<Resp, Req>;
+type ResourceIdentity<Resp = unknown, Req = unknown> = {
+    uri: string;
+    method?: "get";
+    host?: string;
+    noAuth?: boolean;
+};
+type MutationIdentity<Resp = unknown, Req = unknown> = {
+    uri: string;
+    method?: "post" | "delete";
+    host?: string;
+    noAuth?: boolean;
+};
+declare function defineFetch<Resp, Req>(uri: string, method?: "get" | "post" | "delete", option?: {
+    host?: string;
+    noAuth?: boolean;
+}): FetchIdentity<Resp, Req>;
+declare function defineResource<Resp, Req = undefined>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+}): ResourceIdentity<Resp, Req>;
+declare function defineResourceList<Resp, Req = undefined>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+}): ResourceIdentity<PaginationResp<Resp>, Req & PaginationReq>;
+declare function defineMutation<Resp, Req>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+    method?: "post" | "delete";
+}): MutationIdentity<Resp, Req>;
+
+/**
+ * 认证错误类型枚举
+ */
+declare const enum AuthErrorType {
+    /** 认证被取消 */
+    CANCELLED = "cancelled",
+    /** 地址在认证过程中改变 */
+    ADDRESS_CHANGED = "address_changed",
+    /** 未知错误 */
+    UNKNOWN = "unknown"
+}
+/**
+ * 通用认证错误类
+ */
+declare class AuthError<T extends string = string> extends Error {
+    readonly errorType: AuthErrorType | T;
+    constructor(message: string, errorType: AuthErrorType | T);
+}
+
+type AuthStatus = "idle" | "authenticating" | "authenticated" | "unauthenticated";
+interface AuthProviderInstanceConfig {
+    authService: AuthService;
+    authRequest: AxiosInstance;
+    address?: string;
+}
+interface AuthProviderFactoryConfig {
+    refreshTokenFn: (context: AuthType) => Promise<AuthResult>;
+    axiosConfig?: AxiosRequestConfig;
+    tokenStorageService?: ITokenStorageService;
+    address?: string;
+}
+/** 联合类型：支持两种配置方式 */
+type AuthProviderConfig = AuthProviderInstanceConfig | AuthProviderFactoryConfig;
+interface UseAuthResult {
+    status: AuthStatus;
+    error?: AuthError;
+    address?: string;
+    isAuthenticated: boolean;
+    isAuthenticating: boolean;
+    authenticate: () => Promise<void>;
+    logout: () => void;
+}
+declare const AuthProvider: ({ children, ...config }: PropsWithChildren<AuthProviderConfig>) => react_jsx_runtime.JSX.Element;
+
+declare const useAuth: () => UseAuthResult;
+
+type AuthChangeType = {
+    type: "authenticated";
+} | {
+    type: "unauthenticated";
+    error?: AuthError;
+} | {
+    type: "error";
+    error: AuthError;
+};
+/**
+ * 监听认证状态变化，通知调用方
+ * @param onChange 状态变化时的回调函数
+ */
+declare function useAuthChange(onChange: (change: AuthChangeType) => void): void;
+
+/**
+ * Hook for accessing the authenticated axios instance.
+ * This hook is for module internal use only and should NOT be exported from api/index.ts
+ */
+declare const useAuthRequest: () => AxiosInstance;
+
+declare const useResource: <Resp, Req>(requestIdentity?: ResourceIdentity<Resp, Req> | null, params?: Req, option?: SWRConfiguration<BaseResponse<Resp>>) => {
+    response: BaseResponse<Resp> | undefined;
+    data: Resp | undefined;
+    error: any;
+    mutate: swr.KeyedMutator<BaseResponse<Resp>>;
+    isValidating: boolean;
+    isLoading: swr__internal.IsLoadingResponse<Data, Config>;
+};
+
+declare const useResourceList: <RespItem, Req extends PaginationReq>(requestIdentity?: ResourceIdentity<PaginationResp<RespItem>, Req> | null, params?: Req, option?: SWRConfiguration<BaseResponse<PaginationResp<RespItem>>> & {
+    page?: number;
+    size?: number;
+    pageMapping?: (pageInfo: {
+        page: number;
+        size: number;
+    }) => Record<string, number>;
+}) => {
+    response: BaseResponse<PaginationResp<RespItem>> | undefined;
+    list: RespItem[] | undefined;
+    pagination: {
+        count: number;
+        page: number;
+        size: number;
+        setPage: react.Dispatch<react.SetStateAction<number>>;
+        setSize: react.Dispatch<react.SetStateAction<number>>;
+    };
+    error: any;
+    mutate: swr.KeyedMutator<BaseResponse<PaginationResp<RespItem>>>;
+    isValidating: boolean;
+    isLoading: swr__internal.IsLoadingResponse<Data, Config>;
+};
+
+declare const useMutation: <Resp, Req>(key: MutationIdentity<Resp, Req>, option?: SWRMutationConfiguration<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req>) => {
+    error: Error | undefined;
+    response: BaseResponse<Resp> | undefined;
+    data: Resp | undefined;
+    isMutating: boolean;
+    trigger: [Req] extends [never] ? swr_mutation.TriggerWithoutArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req> : (undefined extends Req ? true : false) extends true ? swr_mutation.TriggerWithOptionsArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req> : swr_mutation.TriggerWithArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req>;
+    reset: () => void;
+};
+
+type FetcherSingleParams<Resp, Req> = [
+    FetchIdentity<Resp, Req>,
+    Req | undefined
+];
+type FetcherBatchParams = Array<[FetchIdentity<unknown, unknown>, unknown]>;
+/**
+ * 创建 SWR fetcher（支持单个和批量请求）
+ */
+declare const createFetcherInterceptor: (authRequest: AxiosInstance) => {
+    <Resp, Req>(params: FetcherSingleParams<Resp, Req>): Promise<BaseResponse<Resp>>;
+    (params: FetcherBatchParams): Promise<BaseResponse<unknown>[]>;
+};
+/**
+ * 创建 SWR mutation fetcher
+ */
+declare const createFetcherMutation: (authRequest: AxiosInstance) => <Resp, Req>(requestIdentity: FetchIdentity<Resp, Req>, { arg }: Readonly<{
+    arg: Req;
+}>) => Promise<BaseResponse<Resp>>;
+
+export { type AuthChangeType, AuthError, AuthProvider, type AuthProviderConfig, type AuthResult, AuthService, type AuthServiceConfig, type AuthStatus, type AuthType, type BaseRequestConfig, type BaseResponse, type FetchIdentity, type ITokenStorageService, type MutationIdentity, type PaginationReq, type PaginationResp, type ResourceIdentity, TokenStorageService, type UseAuthResult, configureBaseRequest, createAuthRequest, createBaseRequest, createFetcherInterceptor, createFetcherMutation, defaultTokenStorageService, defineFetch, defineMutation, defineResource, defineResourceList, getBaseRequest, isBrowser, useAuth, useAuthChange, useAuthRequest, useMutation, useResource, useResourceList };

package/dist/api/index.d.ts

@@ -0,0 +1,317 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren } from 'react';
+import * as swr__internal from 'swr/_internal';
+import * as swr from 'swr';
+import { SWRConfiguration } from 'swr';
+import * as swr_mutation from 'swr/mutation';
+import { SWRMutationConfiguration } from 'swr/mutation';
+
+/**
+ * API 客户端类型定义
+ */
+
+interface BaseResponse<T> {
+    datetime?: string;
+    success: boolean;
+    code: number;
+    message?: string;
+    data?: T;
+}
+interface PaginationReq {
+    page?: number;
+    size?: number;
+}
+interface PaginationResp<T> {
+    items: T[];
+    total: number;
+    current: number;
+    size: number;
+}
+/** 认证上下文类型 */
+type AuthType = "wallet-connect" | "token-refresh" | "request-init";
+/** 认证结果（成功时返回） */
+interface AuthResult {
+    success: true;
+    token: string;
+}
+/** 认证状态 */
+interface AuthState {
+    status: "idle" | "authenticating" | "authenticated" | "unauthenticated";
+    address?: string;
+    error?: AuthError;
+}
+/** 状态变化监听器 */
+type AuthStateListener = (state: AuthState) => void;
+
+/**
+ * Token 存储服务接口
+ */
+interface ITokenStorageService {
+    setToken(token: string | undefined, address?: string): void;
+    getToken(address?: string): string | null;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * 默认 Token 存储服务实现（localStorage）
+ * 支持多地址 token 存储
+ */
+declare class TokenStorageService implements ITokenStorageService {
+    private listeners;
+    private boundHandleStorage;
+    setToken(token: string | undefined, address?: string): void;
+    getToken(address?: string): string | null;
+    private getMap;
+    private saveMap;
+    subscribe(listener: () => void): () => void;
+}
+/** 默认单例 */
+declare const defaultTokenStorageService: TokenStorageService;
+
+type RefreshTokenFn = (context: AuthType) => Promise<AuthResult>;
+interface AuthServiceConfig {
+    refreshToken: RefreshTokenFn;
+    tokenStorageService?: ITokenStorageService;
+}
+/**
+ * Authentication service with concurrency control, token storage, and state management
+ */
+declare class AuthService {
+    private refreshToken;
+    private tokenStorageService;
+    private authPromise;
+    private state;
+    private listeners;
+    constructor(config: AuthServiceConfig);
+    /**
+     * Authenticate with concurrency control
+     * Multiple concurrent calls will share the same Promise
+     * Stores token on success
+     */
+    authenticate(context: AuthType): Promise<AuthResult>;
+    /**
+     * 重置内部认证状态（私有方法）
+     */
+    private reset;
+    /**
+     * Get current token for the current wallet address
+     */
+    getToken(): string | null;
+    /**
+     * 检查地址是否有有效 token（私有方法）
+     */
+    private isAddressAuthenticated;
+    /**
+     * Logout: clear token for current address and update state
+     */
+    logout(): void;
+    /**
+     * Get current authentication state
+     */
+    getState(): AuthState;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(listener: AuthStateListener): () => void;
+    /**
+     * Handle wallet address changes
+     * Note: Wallet disconnection should be handled externally by calling logout()
+     */
+    handleWalletChange(address: string | undefined): void;
+    /**
+     * 处理 StorageChange 事件（用于多选项卡同步）
+     * 当 localStorage 在另一个选项卡中发生更改时调用
+     */
+    private handleStorageChange;
+    /**
+     * 更新状态并通知监听者
+     */
+    private setState;
+}
+
+declare const isBrowser: boolean;
+interface BaseRequestConfig {
+    baseURL: string;
+    headers?: Record<string, string>;
+}
+/**
+ * 创建不带认证的基础请求实例
+ */
+declare const createBaseRequest: (config: BaseRequestConfig) => AxiosInstance;
+/**
+ * 获取或创建默认基础请求实例
+ */
+declare const getBaseRequest: () => AxiosInstance;
+/**
+ * 配置默认基础请求实例
+ */
+declare const configureBaseRequest: (config: BaseRequestConfig) => void;
+interface CreateAuthRequestConfig {
+    authService: AuthService;
+    axiosConfig?: AxiosRequestConfig;
+}
+/**
+ * 创建带鉴权 Axios 实例
+ */
+declare const createAuthRequest: (config: CreateAuthRequestConfig) => AxiosInstance;
+
+type FetchIdentity<Resp, Req> = ResourceIdentity<Resp, Req> | MutationIdentity<Resp, Req>;
+type ResourceIdentity<Resp = unknown, Req = unknown> = {
+    uri: string;
+    method?: "get";
+    host?: string;
+    noAuth?: boolean;
+};
+type MutationIdentity<Resp = unknown, Req = unknown> = {
+    uri: string;
+    method?: "post" | "delete";
+    host?: string;
+    noAuth?: boolean;
+};
+declare function defineFetch<Resp, Req>(uri: string, method?: "get" | "post" | "delete", option?: {
+    host?: string;
+    noAuth?: boolean;
+}): FetchIdentity<Resp, Req>;
+declare function defineResource<Resp, Req = undefined>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+}): ResourceIdentity<Resp, Req>;
+declare function defineResourceList<Resp, Req = undefined>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+}): ResourceIdentity<PaginationResp<Resp>, Req & PaginationReq>;
+declare function defineMutation<Resp, Req>(uri: string, option?: {
+    host?: string;
+    noAuth?: boolean;
+    method?: "post" | "delete";
+}): MutationIdentity<Resp, Req>;
+
+/**
+ * 认证错误类型枚举
+ */
+declare const enum AuthErrorType {
+    /** 认证被取消 */
+    CANCELLED = "cancelled",
+    /** 地址在认证过程中改变 */
+    ADDRESS_CHANGED = "address_changed",
+    /** 未知错误 */
+    UNKNOWN = "unknown"
+}
+/**
+ * 通用认证错误类
+ */
+declare class AuthError<T extends string = string> extends Error {
+    readonly errorType: AuthErrorType | T;
+    constructor(message: string, errorType: AuthErrorType | T);
+}
+
+type AuthStatus = "idle" | "authenticating" | "authenticated" | "unauthenticated";
+interface AuthProviderInstanceConfig {
+    authService: AuthService;
+    authRequest: AxiosInstance;
+    address?: string;
+}
+interface AuthProviderFactoryConfig {
+    refreshTokenFn: (context: AuthType) => Promise<AuthResult>;
+    axiosConfig?: AxiosRequestConfig;
+    tokenStorageService?: ITokenStorageService;
+    address?: string;
+}
+/** 联合类型：支持两种配置方式 */
+type AuthProviderConfig = AuthProviderInstanceConfig | AuthProviderFactoryConfig;
+interface UseAuthResult {
+    status: AuthStatus;
+    error?: AuthError;
+    address?: string;
+    isAuthenticated: boolean;
+    isAuthenticating: boolean;
+    authenticate: () => Promise<void>;
+    logout: () => void;
+}
+declare const AuthProvider: ({ children, ...config }: PropsWithChildren<AuthProviderConfig>) => react_jsx_runtime.JSX.Element;
+
+declare const useAuth: () => UseAuthResult;
+
+type AuthChangeType = {
+    type: "authenticated";
+} | {
+    type: "unauthenticated";
+    error?: AuthError;
+} | {
+    type: "error";
+    error: AuthError;
+};
+/**
+ * 监听认证状态变化，通知调用方
+ * @param onChange 状态变化时的回调函数
+ */
+declare function useAuthChange(onChange: (change: AuthChangeType) => void): void;
+
+/**
+ * Hook for accessing the authenticated axios instance.
+ * This hook is for module internal use only and should NOT be exported from api/index.ts
+ */
+declare const useAuthRequest: () => AxiosInstance;
+
+declare const useResource: <Resp, Req>(requestIdentity?: ResourceIdentity<Resp, Req> | null, params?: Req, option?: SWRConfiguration<BaseResponse<Resp>>) => {
+    response: BaseResponse<Resp> | undefined;
+    data: Resp | undefined;
+    error: any;
+    mutate: swr.KeyedMutator<BaseResponse<Resp>>;
+    isValidating: boolean;
+    isLoading: swr__internal.IsLoadingResponse<Data, Config>;
+};
+
+declare const useResourceList: <RespItem, Req extends PaginationReq>(requestIdentity?: ResourceIdentity<PaginationResp<RespItem>, Req> | null, params?: Req, option?: SWRConfiguration<BaseResponse<PaginationResp<RespItem>>> & {
+    page?: number;
+    size?: number;
+    pageMapping?: (pageInfo: {
+        page: number;
+        size: number;
+    }) => Record<string, number>;
+}) => {
+    response: BaseResponse<PaginationResp<RespItem>> | undefined;
+    list: RespItem[] | undefined;
+    pagination: {
+        count: number;
+        page: number;
+        size: number;
+        setPage: react.Dispatch<react.SetStateAction<number>>;
+        setSize: react.Dispatch<react.SetStateAction<number>>;
+    };
+    error: any;
+    mutate: swr.KeyedMutator<BaseResponse<PaginationResp<RespItem>>>;
+    isValidating: boolean;
+    isLoading: swr__internal.IsLoadingResponse<Data, Config>;
+};
+
+declare const useMutation: <Resp, Req>(key: MutationIdentity<Resp, Req>, option?: SWRMutationConfiguration<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req>) => {
+    error: Error | undefined;
+    response: BaseResponse<Resp> | undefined;
+    data: Resp | undefined;
+    isMutating: boolean;
+    trigger: [Req] extends [never] ? swr_mutation.TriggerWithoutArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req> : (undefined extends Req ? true : false) extends true ? swr_mutation.TriggerWithOptionsArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req> : swr_mutation.TriggerWithArgs<BaseResponse<Resp>, Error, MutationIdentity<Resp, Req>, Req>;
+    reset: () => void;
+};
+
+type FetcherSingleParams<Resp, Req> = [
+    FetchIdentity<Resp, Req>,
+    Req | undefined
+];
+type FetcherBatchParams = Array<[FetchIdentity<unknown, unknown>, unknown]>;
+/**
+ * 创建 SWR fetcher（支持单个和批量请求）
+ */
+declare const createFetcherInterceptor: (authRequest: AxiosInstance) => {
+    <Resp, Req>(params: FetcherSingleParams<Resp, Req>): Promise<BaseResponse<Resp>>;
+    (params: FetcherBatchParams): Promise<BaseResponse<unknown>[]>;
+};
+/**
+ * 创建 SWR mutation fetcher
+ */
+declare const createFetcherMutation: (authRequest: AxiosInstance) => <Resp, Req>(requestIdentity: FetchIdentity<Resp, Req>, { arg }: Readonly<{
+    arg: Req;
+}>) => Promise<BaseResponse<Resp>>;
+
+export { type AuthChangeType, AuthError, AuthProvider, type AuthProviderConfig, type AuthResult, AuthService, type AuthServiceConfig, type AuthStatus, type AuthType, type BaseRequestConfig, type BaseResponse, type FetchIdentity, type ITokenStorageService, type MutationIdentity, type PaginationReq, type PaginationResp, type ResourceIdentity, TokenStorageService, type UseAuthResult, configureBaseRequest, createAuthRequest, createBaseRequest, createFetcherInterceptor, createFetcherMutation, defaultTokenStorageService, defineFetch, defineMutation, defineResource, defineResourceList, getBaseRequest, isBrowser, useAuth, useAuthChange, useAuthRequest, useMutation, useResource, useResourceList };