@taskon/widget-react 0.0.1-beta.1

package/dist/core.d.ts

@@ -0,0 +1,803 @@
+import { ChainInfo } from '@taskon/core';
+import { CommunityInfo } from '@taskon/core';
+import { LoginResult } from '@taskon/core';
+import { ReactNode } from 'react';
+import { RewardType } from '@taskon/core';
+import { TaskOnClient } from '@taskon/core';
+import { UserInfo } from '@taskon/core';
+
+/**
+ * Clear the locale cache
+ * Useful for testing or when you need to force reload locales
+ */
+export declare function clearLocaleCache(): void;
+
+/**
+ * Common messages type definition
+ *
+ * These are shared messages used across multiple widgets.
+ * All language files must implement this interface.
+ */
+export declare interface CommonMessages {
+    /** Loading state text */
+    loading: string;
+    /** Generic error message */
+    error: string;
+    /** Retry action text */
+    retry: string;
+    /** Success message */
+    success: string;
+    /** Cancel action text */
+    cancel: string;
+    /** Confirm action text */
+    confirm: string;
+}
+
+/**
+ * Create a locale loader function for a widget
+ *
+ * @template T - The shape of the messages object
+ * @param defaultMessages - English messages (used as fallback)
+ * @param imports - Map of locale codes to dynamic import functions
+ * @returns A function that loads messages for a given locale
+ *
+ * @example
+ * ```ts
+ * import enMessages from './locales/en';
+ *
+ * const loadMessages = createLocaleLoader(enMessages, {
+ *   ko: () => import('./locales/ko'),
+ *   ja: () => import('./locales/ja'),
+ * });
+ * ```
+ */
+export declare function createLocaleLoader<T>(defaultMessages: T, imports: LocaleImportMap<T>): (locale: Locale) => Promise<{
+    default: T;
+}>;
+
+/**
+ * Create a translation function from a messages object
+ *
+ * @param messages - Object containing translation strings
+ * @returns A function that retrieves and interpolates translations
+ *
+ * @example
+ * ```ts
+ * const messages = {
+ *   greeting: 'Hello, {name}!',
+ *   points: 'You have {count} points',
+ * };
+ *
+ * const t = createT(messages);
+ *
+ * t('greeting', { name: 'John' })  // => 'Hello, John!'
+ * t('points', { count: 100 })      // => 'You have 100 points'
+ * t('greeting')                    // => 'Hello, {name}!' (no params)
+ * ```
+ */
+export declare function createT<T extends Record<string, string>>(messages: T): <K extends keyof T>(key: K, params?: InterpolationParams) => string;
+
+/**
+ * Interpolate a string with parameters
+ *
+ * @param template - String template with {key} placeholders
+ * @param params - Object containing values to replace placeholders
+ * @returns Interpolated string
+ *
+ * @example
+ * ```ts
+ * interpolate('Hello, {name}!', { name: 'John' })
+ * // => 'Hello, John!'
+ *
+ * interpolate('You have {count} points', { count: 100 })
+ * // => 'You have 100 points'
+ *
+ * interpolate('{a} + {b} = {result}', { a: 1, b: 2, result: 3 })
+ * // => '1 + 2 = 3'
+ * ```
+ */
+export declare function interpolate(template: string, params?: InterpolationParams): string;
+
+/**
+ * interpolate - Simple string interpolation utility
+ *
+ * Replaces placeholders in the format {key} with values from the params object.
+ * This is a lightweight alternative to full i18n libraries when only simple
+ * variable replacement is needed.
+ */
+/**
+ * Params object type for interpolation
+ */
+export declare type InterpolationParams = Record<string, string | number | undefined>;
+
+/**
+ * Parameters for contract invocation
+ */
+declare interface InvokeContractParams {
+    /** Contract address */
+    contract: string;
+    /** Contract ABI (Application Binary Interface) */
+    abi: unknown[];
+    /** Method name to call */
+    method: string;
+    /** Method parameters */
+    params: unknown[];
+    /** Target chain ID (optional, will switch network if needed) */
+    chainId?: number;
+    /** Transaction value in wei (for payable methods) */
+    value?: string;
+}
+
+/**
+ * Check if a locale has full translation support
+ */
+export declare function isSupportedLocale(locale: Locale): locale is SupportedLocale;
+
+export declare type Locale = "en" | "ko" | "ja" | "ru" | "es";
+
+/**
+ * Locale import map type
+ * Maps supported locales to their dynamic import functions
+ */
+export declare type LocaleImportMap<T> = {
+    [K in Exclude<SupportedLocale, "en">]?: () => Promise<{
+        default: T;
+    }>;
+};
+
+/**
+ * Supported login methods
+ */
+export declare type LoginMethod = "evm_wallet" | "email" | "discord" | "twitter" | "telegram";
+
+/**
+ * Unified login parameters
+ */
+export declare interface LoginParams {
+    /** Login method */
+    method: LoginMethod;
+    /** Value: wallet address / email / OAuth token */
+    value: string;
+    /** Signature from backend */
+    sign: string;
+    /** Timestamp used for signing (seconds) */
+    timestamp: number;
+}
+
+export { LoginResult }
+
+/**
+ * Map Token - Can override derived values
+ */
+export declare interface MapToken {
+    colorPrimary?: string;
+    colorPrimaryHover?: string;
+    colorPrimaryActive?: string;
+    colorPrimaryBg?: string;
+    colorSecondary?: string;
+    colorSuccess?: string;
+    colorWarning?: string;
+    colorError?: string;
+    colorBg?: string;
+    colorBgElevated?: string;
+    colorBgSpotlight?: string;
+    colorText?: string;
+    colorTextSecondary?: string;
+    colorTextTertiary?: string;
+    colorTextDisabled?: string;
+    colorBorder?: string;
+    colorBorderSecondary?: string;
+    borderRadius?: number;
+    borderRadiusSm?: number;
+    borderRadiusLg?: number;
+    fontSize?: number;
+    fontSizeSm?: number;
+    fontSizeLg?: number;
+    spacing?: number;
+    spacingXs?: number;
+    spacingSm?: number;
+    spacingMd?: number;
+    spacingLg?: number;
+    spacingXl?: number;
+}
+
+/**
+ * Mode-specific configuration
+ */
+declare interface ModeThemeConfig {
+    seed?: SeedToken;
+    map?: MapToken;
+}
+
+export { RewardType }
+
+/**
+ * Seed Token - Input values that auto-derive other tokens
+ */
+export declare interface SeedToken {
+    /** Primary color */
+    colorPrimary?: string;
+    /** Secondary color */
+    colorSecondary?: string;
+    /** Success color */
+    colorSuccess?: string;
+    /** Warning color */
+    colorWarning?: string;
+    /** Error color */
+    colorError?: string;
+    /** Base border radius */
+    borderRadius?: number;
+    /** Base font size */
+    fontSize?: number;
+}
+
+/**
+ * Locales that have full translation support in all widgets
+ * Other locales in the Locale type will fallback to English
+ */
+export declare type SupportedLocale = "en" | "ko" | "ja";
+
+/**
+ * TaskOn Context value
+ */
+export declare interface TaskOnContextValue {
+    /**
+     * Provider configuration
+     */
+    config: TaskOnProviderConfig;
+    /**
+     * TaskOn client instance from @taskon/core
+     */
+    client: TaskOnClient | null;
+    /**
+     * Whether the provider is initializing
+     */
+    isInitializing: boolean;
+    /**
+     * Resolved locale
+     */
+    locale: Locale;
+    /**
+     * TaskOn user ID, null if not logged in
+     */
+    userId: number | null;
+    /**
+     * Current user info, null if not logged in
+     */
+    userInfo: UserInfo | null;
+    /**
+     * Current user token, null if not logged in
+     */
+    userToken: string | null;
+    /**
+     * Whether user is logged in
+     */
+    isLoggedIn: boolean;
+    /**
+     * Unified login method
+     */
+    login: (params: LoginParams) => Promise<void>;
+    /**
+     * Logout current user
+     */
+    logout: () => void;
+    /**
+     * Request login callback
+     * Triggers config.onRequestLogin if provided
+     */
+    requestLogin: () => void;
+    /**
+     * Refresh user info from server
+     * Call this after binding social accounts to update userInfo
+     */
+    refreshUserInfo: () => Promise<void>;
+    /**
+     * Chain info list (loaded on init)
+     * Used for determining chain types for wallet binding
+     */
+    chains: ChainInfo[];
+    /**
+     * Community info (auto-loaded on init based on apiKey)
+     * Used for displaying community logo and name in reward cards
+     */
+    communityInfo: CommunityInfo | null;
+}
+
+/**
+ * TaskOn Provider Component
+ *
+ * Root component for TaskOn Widget, providing:
+ * - TaskOn client management (based on @taskon/core)
+ * - User authentication (login/logout)
+ * - Locale configuration
+ * - Wallet management (uses window.ethereum adapter)
+ * - Widget locale preloading (optional)
+ * - Toast notifications (internal, user-transparent)
+ */
+export declare function TaskOnProvider({ config, children, preloadLocales, }: TaskOnProviderProps): ReactNode;
+
+/**
+ * TaskOn Provider configuration
+ */
+export declare interface TaskOnProviderConfig {
+    /**
+     * API Key for authentication (X-API-Key header)
+     * Note: apiKey already contains community info, no need to configure communityId/communityKey separately
+     */
+    apiKey: string;
+    /**
+     * API base URL (optional)
+     * @default https://white-label-api.taskon.xyz
+     */
+    baseURL?: string;
+    /**
+     * Locale setting for internationalization
+     * @default auto-detect from browser
+     */
+    locale?: Locale;
+    /**
+     * Wallet configuration for blockchain interactions
+     *
+     * When not provided, TaskOn will use built-in window.ethereum adapter
+     * for EVM wallet connections (MetaMask, etc.)
+     */
+    walletConfig?: WalletConfig;
+    /**
+     * Callback when user requests to login
+     *
+     * This is triggered when user clicks on login overlay in widgets.
+     * Use this to show your login modal or redirect to login page.
+     *
+     * @example
+     * ```tsx
+     * <TaskOnProvider
+     *   config={{
+     *     apiKey: 'your-api-key',
+     *     onRequestLogin: () => {
+     *       setShowLoginModal(true);
+     *     },
+     *   }}
+     * >
+     * ```
+     */
+    onRequestLogin?: () => void;
+    /**
+     * OAuth tool URL for social account binding
+     *
+     * When users need to bind Twitter/Discord/Telegram accounts,
+     * this URL will be used to open the OAuth authorization popup.
+     *
+     * @default https://generalauthservice.com (main environment)
+     *
+     * For stage/test environment, use: https://stage.generalauthservice.com
+     */
+    oauthToolUrl?: string;
+    /**
+     * WalletConnect Project ID
+     *
+     * Required for WalletConnect functionality.
+     * Get your project ID at https://cloud.walletconnect.com
+     *
+     * If not provided, WalletConnect option will be disabled in the wallet dialog.
+     */
+    walletConnectProjectId?: string;
+}
+
+export declare interface TaskOnProviderProps {
+    /**
+     * TaskOn configuration object
+     */
+    config: TaskOnProviderConfig;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+    /**
+     * List of widgets to preload locales for
+     */
+    preloadLocales?: WidgetName[];
+}
+
+/**
+ * Resolved theme object (returned by useTaskOnTheme)
+ */
+export declare interface TaskOnTheme {
+    /** Current mode (resolved, never "auto") */
+    mode: "light" | "dark";
+    /** Whether compact mode is enabled */
+    compact: boolean;
+    /** All tokens (resolved) */
+    tokens: Required<MapToken>;
+}
+
+/**
+ * Theme configuration
+ */
+export declare interface TaskOnThemeConfig {
+    /** Theme mode */
+    mode?: ThemeMode;
+    /** Compact mode */
+    compact?: boolean;
+    /** Seed tokens */
+    seed?: SeedToken;
+    /** Map tokens (override derived values) */
+    map?: MapToken;
+    /** Light mode specific configuration */
+    light?: ModeThemeConfig;
+    /** Dark mode specific configuration */
+    dark?: ModeThemeConfig;
+}
+
+/**
+ * Translation function type
+ */
+export declare type TFunction<T> = <K extends keyof T>(key: K, params?: InterpolationParams) => string;
+
+/**
+ * Theme mode
+ * - light: Light mode
+ * - dark: Dark mode
+ * - auto: Follow system preference
+ */
+export declare type ThemeMode = "light" | "dark" | "auto";
+
+/**
+ * Theme Provider Component
+ *
+ * Provides theme configuration with support for:
+ * - light/dark/auto modes
+ * - Seed token derivation
+ * - Map token overrides
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider theme={{ mode: 'dark', seed: { colorPrimary: '#6366f1' } }}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export declare function ThemeProvider({ theme: themeConfig, children, }: ThemeProviderProps): ReactNode;
+
+/**
+ * ThemeProvider Props
+ */
+export declare interface ThemeProviderProps {
+    /** Theme configuration */
+    theme?: TaskOnThemeConfig;
+    /** Child components */
+    children: React.ReactNode;
+}
+
+/**
+ * Hook for loading common locale messages
+ *
+ * @returns Object containing common messages and loading state
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const { messages: common, isLoading } = useCommonLocale();
+ *
+ *   if (isLoading) return <div>{common.loading}</div>;
+ *
+ *   return <button onClick={retry}>{common.retry}</button>;
+ * }
+ * ```
+ */
+export declare function useCommonLocale(): UseWidgetLocaleResult<CommonMessages>;
+
+/**
+ * Hook to access EVM wallet
+ */
+export declare function useEvmWallet(): {
+    adapter: WalletAdapter | null;
+    address: string | null;
+    chainId: number | null;
+    isConnected: boolean;
+    connect: () => Promise<string | null>;
+    disconnect: () => Promise<void>;
+    signMessage: (message: string) => Promise<string | null>;
+};
+
+export { UserInfo }
+
+/**
+ * Public hook for TaskOn authentication
+ *
+ * @example
+ * ```tsx
+ * const { login, logout, userId, isLoggedIn, requestLogin } = useTaskOnAuth();
+ *
+ * // EVM wallet login
+ * await login({ method: 'evm_wallet', value: '0x...', sign, timestamp });
+ *
+ * // Email login
+ * await login({ method: 'email', value: 'user@example.com', sign, timestamp });
+ *
+ * // Discord login
+ * await login({ method: 'discord', value: oauthToken, sign, timestamp });
+ *
+ * // Request login (triggers config.onRequestLogin)
+ * requestLogin();
+ * ```
+ */
+export declare function useTaskOnAuth(): {
+    userId: number | null;
+    isLoggedIn: boolean;
+    isInitializing: boolean;
+    login: (params: LoginParams) => Promise<void>;
+    logout: () => void;
+    requestLogin: () => void;
+};
+
+/**
+ * Get current theme
+ * Must be used within a ThemeProvider
+ */
+export declare function useTaskOnTheme(): TaskOnTheme;
+
+/**
+ * Hook for widget translations with interpolation support
+ *
+ * This is a higher-level hook that wraps useWidgetLocale and adds
+ * a `t` function for convenient string interpolation.
+ *
+ * @template T - The shape of the messages object
+ * @param options - Same options as useWidgetLocale
+ * @returns Object containing t function, messages, and loading state
+ *
+ * @example
+ * ```tsx
+ * // messages/en.ts
+ * export default {
+ *   greeting: 'Hello, {name}!',
+ *   points: 'You have {count} points',
+ *   title: 'Task Widget',
+ * };
+ *
+ * // Component
+ * function TaskWidget() {
+ *   const { t, isLoading } = useTranslation({
+ *     widgetId: 'TaskWidget',
+ *     defaultMessages: enMessages,
+ *     loadMessages,
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t('title')}</h1>
+ *       <p>{t('greeting', { name: 'John' })}</p>
+ *       <p>{t('points', { count: 100 })}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTranslation<T>(options: UseWidgetLocaleOptions<T>): UseTranslationResult<T>;
+
+/**
+ * Return type for useTranslation hook
+ */
+export declare interface UseTranslationResult<T> {
+    /**
+     * Translation function with interpolation support
+     *
+     * @example
+     * ```ts
+     * t('greeting', { name: 'John' })  // => 'Hello, John!'
+     * t('points', { count: 100 })      // => 'You have 100 points'
+     * ```
+     */
+    t: TFunction<T>;
+    /**
+     * Raw messages object (without interpolation)
+     * Useful when you need direct access to message strings
+     */
+    messages: T;
+    /**
+     * Whether translations are currently loading
+     */
+    isLoading: boolean;
+}
+
+/**
+ * Hook to access wallet context
+ * Returns wallet state and actions for EVM
+ *
+ * @example
+ * ```tsx
+ * const { evmAddress, isEvmConnected, connectEvm, signEvmMessage } = useWallet();
+ *
+ * // Connect EVM wallet
+ * const address = await connectEvm();
+ *
+ * // Sign message
+ * const signature = await signEvmMessage("Hello World");
+ * ```
+ */
+export declare function useWallet(): WalletContextValue;
+
+/**
+ * Hook for loading widget-specific locale messages
+ *
+ * @template T - The shape of the messages object
+ * @param options - Configuration options
+ * @param options.defaultMessages - English messages (inlined, no loading needed)
+ * @param options.loadMessages - Function to dynamically import other locales
+ * @returns Object containing messages and loading state
+ *
+ * @example
+ * ```tsx
+ * import enMessages from './locales/en';
+ *
+ * function TaskWidget() {
+ *   const { messages, isLoading } = useWidgetLocale({
+ *     defaultMessages: enMessages,
+ *     loadMessages: (locale) => import(`./locales/${locale}.ts`),
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return <button>{messages.claim}</button>;
+ * }
+ * ```
+ */
+export declare function useWidgetLocale<T>(options: UseWidgetLocaleOptions<T>): UseWidgetLocaleResult<T>;
+
+/**
+ * Options for useWidgetLocale hook
+ *
+ * @template T - The shape of the messages object
+ */
+export declare interface UseWidgetLocaleOptions<T> {
+    /**
+     * Unique identifier for this widget
+     * Used as cache key prefix to avoid conflicts between widgets
+     *
+     * @example "TaskWidget", "WalletWidget"
+     */
+    widgetId: string;
+    /**
+     * Default messages (English) - inlined in bundle
+     * These are used immediately without any loading
+     */
+    defaultMessages: T;
+    /**
+     * Function to dynamically load messages for other locales
+     * Should return a dynamic import promise
+     *
+     * @example
+     * ```ts
+     * loadMessages: (locale) => import(`./locales/${locale}.ts`)
+     * ```
+     */
+    loadMessages: (locale: Locale) => Promise<{
+        default: T;
+    }>;
+}
+
+/**
+ * Return type for useWidgetLocale hook
+ *
+ * @template T - The shape of the messages object
+ */
+export declare interface UseWidgetLocaleResult<T> {
+    /**
+     * Current messages object based on active locale
+     * Falls back to default (English) messages if loading fails
+     */
+    messages: T;
+    /**
+     * Whether the locale messages are currently loading
+     * Only true when switching to a non-default locale
+     */
+    isLoading: boolean;
+}
+
+/**
+ * Wallet adapter interface for blockchain interactions
+ *
+ * This interface abstracts wallet operations, allowing widgets to work with
+ * different wallet providers (custom implementations or built-in adapters)
+ */
+export declare interface WalletAdapter {
+    /**
+     * Connect to wallet and return the connected address
+     * Should open wallet selection UI if needed
+     */
+    connect: () => Promise<string>;
+    /**
+     * Disconnect from wallet
+     */
+    disconnect: () => Promise<void>;
+    /**
+     * Sign a message with the connected wallet
+     * @param message - The message to sign
+     * @returns The signature
+     */
+    signMessage: (message: string) => Promise<string>;
+    /**
+     * Get the currently connected address
+     * @returns The address or null if not connected
+     */
+    getAddress: () => string | null;
+    /**
+     * Get the current chain ID
+     * @returns The chain ID or null if not available
+     */
+    getChainId?: () => number | null;
+    /**
+     * Switch to a different network
+     * @param chainId - The target chain ID
+     */
+    switchNetwork?: (chainId: number) => Promise<void>;
+    /**
+     * Invoke a smart contract method
+     * @param params - Contract invocation parameters
+     * @returns Transaction hash
+     */
+    invokeContract?: (params: InvokeContractParams) => Promise<string>;
+    /**
+     * Get wallet's native token balance (for gas estimation)
+     * @returns Balance in wei (string)
+     */
+    getBalance?: () => Promise<string>;
+    /**
+     * Subscribe to account changes
+     * @param callback - Called when account changes
+     * @returns Unsubscribe function
+     */
+    onAccountChange?: (callback: (address: string | null) => void) => () => void;
+    /**
+     * Subscribe to chain/network changes
+     * @param callback - Called when chain changes
+     * @returns Unsubscribe function
+     */
+    onChainChange?: (callback: (chainId: number) => void) => () => void;
+}
+
+/**
+ * Wallet configuration for TaskOnProvider
+ */
+export declare interface WalletConfig {
+    /**
+     * Custom EVM wallet adapter
+     * If not provided, uses built-in window.ethereum adapter
+     */
+    evmAdapter?: WalletAdapter;
+    /**
+     * Disable auto-detection of wallet providers
+     * When true, only uses adapter explicitly provided above
+     * @default false
+     */
+    disableAutoDetect?: boolean;
+}
+
+/**
+ * Wallet context value type
+ */
+declare interface WalletContextValue extends WalletState {
+    connectEvm: () => Promise<string | null>;
+    disconnectEvm: () => Promise<void>;
+    signEvmMessage: (message: string) => Promise<string | null>;
+}
+
+/**
+ * Wallet state exposed through context
+ */
+export declare interface WalletState {
+    evmAdapter: WalletAdapter | null;
+    evmAddress: string | null;
+    evmChainId: number | null;
+    isEvmConnected: boolean;
+    isDetecting: boolean;
+}
+
+/**
+ * Supported widget names for preloading
+ */
+export declare type WidgetName = "CommunityTask";
+
+export { }