@catalyst-team/poly-sdk 0.4.0 → 0.4.5

package/dist/src/wallet-report/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * WalletReport Service Types
+ *
+ * Types for querying the WalletReportWorker API
+ */
+/**
+ * Report type identifiers
+ */
+export type ReportType = 'wallet' | 'leaderboard_daily' | 'leaderboard_weekly' | 'leaderboard_monthly';
+/**
+ * Report status
+ */
+export type ReportStatus = 'pending' | 'generating' | 'completed' | 'failed';
+/**
+ * Daily performance entry
+ */
+export interface DailyPerformance {
+    date: string;
+    pnl: number;
+    volume: number;
+    tradeCount: number;
+    winRate: number;
+}
+/**
+ * Wallet report data structure
+ */
+export interface WalletReportData {
+    address: string;
+    displayName?: string;
+    metrics: {
+        totalPnL: number;
+        totalVolume: number;
+        winRate: number;
+        tradeCount: number;
+        avgHoldingDays: number;
+        bestTrade: number;
+        worstTrade: number;
+    };
+    recentPerformance: DailyPerformance[];
+    marketBreakdown: {
+        category: string;
+        volume: number;
+        pnl: number;
+        tradeCount: number;
+    }[];
+    topPositions: {
+        marketTitle: string;
+        conditionId: string;
+        size: number;
+        avgPrice: number;
+        currentPrice: number;
+        unrealizedPnL: number;
+    }[];
+    generatedAt: number;
+}
+/**
+ * Leaderboard entry
+ */
+export interface LeaderboardEntry {
+    rank: number;
+    address: string;
+    displayName?: string;
+    pnl: number;
+    volume: number;
+    winRate: number;
+    tradeCount: number;
+    rankChange: number | null;
+}
+/**
+ * Leaderboard report data structure
+ */
+export interface LeaderboardReportData {
+    period: 'daily' | 'weekly' | 'monthly';
+    periodStart: string;
+    periodEnd: string;
+    entries: LeaderboardEntry[];
+    stats: {
+        totalTraders: number;
+        totalVolume: number;
+        totalPnL: number;
+        avgWinRate: number;
+    };
+    generatedAt: number;
+}
+/**
+ * Health response
+ */
+export interface WalletReportHealthResponse {
+    status: string;
+    service: string;
+    version: string;
+    now: number;
+    stats: {
+        totalReports: number;
+        byType: {
+            wallet: number;
+            leaderboard_daily: number;
+            leaderboard_weekly: number;
+            leaderboard_monthly: number;
+        };
+        byStatus: {
+            pending: number;
+            generating: number;
+            completed: number;
+            failed: number;
+        };
+        schedulerEnabled: boolean;
+    };
+}
+/**
+ * Stats response
+ */
+export interface WalletReportStatsResponse {
+    totalReports: number;
+    byType: {
+        wallet: number;
+        leaderboard_daily: number;
+        leaderboard_weekly: number;
+        leaderboard_monthly: number;
+    };
+    byStatus: {
+        pending: number;
+        generating: number;
+        completed: number;
+        failed: number;
+    };
+    oldestReport: number | null;
+    newestReport: number | null;
+}
+/**
+ * Wallet report response
+ */
+export interface GetWalletReportResponse {
+    source: 'cache' | 'generated';
+    report: WalletReportData;
+}
+/**
+ * Report generating response
+ */
+export interface ReportGeneratingResponse {
+    status: 'generating';
+    message: string;
+    reportId: string;
+}
+/**
+ * Leaderboard response
+ */
+export interface GetLeaderboardResponse {
+    identifier: string;
+    report: LeaderboardReportData | null;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Report summary (list view)
+ */
+export interface ReportSummary {
+    id: string;
+    type: ReportType;
+    status: ReportStatus;
+    identifier: string;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+    hasData: boolean;
+    error: string | null;
+}
+/**
+ * List reports response
+ */
+export interface ListReportsResponse {
+    reports: ReportSummary[];
+    pagination: {
+        limit: number;
+        offset: number;
+    };
+}
+/**
+ * List reports params
+ */
+export interface ListReportsParams {
+    type?: ReportType;
+    status?: ReportStatus;
+    limit?: number;
+    offset?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/wallet-report/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/wallet-report/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,mBAAmB,GAAG,oBAAoB,GAAG,qBAAqB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,eAAe,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;IACJ,YAAY,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;IACJ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE;YACN,MAAM,EAAE,MAAM,CAAC;YACf,iBAAiB,EAAE,MAAM,CAAC;YAC1B,kBAAkB,EAAE,MAAM,CAAC;YAC3B,mBAAmB,EAAE,MAAM,CAAC;SAC7B,CAAC;QACF,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;YACnB,SAAS,EAAE,MAAM,CAAC;YAClB,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC;QACF,gBAAgB,EAAE,OAAO,CAAC;KAC3B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/src/wallet-report/types.js

@@ -0,0 +1,7 @@
+/**
+ * WalletReport Service Types
+ *
+ * Types for querying the WalletReportWorker API
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/wallet-report/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/wallet-report/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/wallet-report/wallet-report-service.d.ts

@@ -0,0 +1,91 @@
+/**
+ * WalletReportService
+ *
+ * Client for querying the WalletReportWorker API.
+ *
+ * @example
+ * ```typescript
+ * const service = new WalletReportService({
+ *   baseUrl: 'http://localhost:8789',
+ * });
+ *
+ * // Get health status
+ * const health = await service.health();
+ *
+ * // Get or generate wallet report
+ * const report = await service.getWalletReport('0x...');
+ *
+ * // Get daily leaderboard
+ * const leaderboard = await service.getDailyLeaderboard();
+ * ```
+ */
+import type { WalletReportHealthResponse, WalletReportStatsResponse, GetWalletReportResponse, ReportGeneratingResponse, GetLeaderboardResponse, ListReportsResponse, ListReportsParams, WalletReportData, LeaderboardReportData } from './types.js';
+export interface WalletReportServiceConfig {
+    /** Base URL of WalletReportWorker (e.g., http://localhost:8789) */
+    baseUrl: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeoutMs?: number;
+}
+export declare class WalletReportService {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: WalletReportServiceConfig);
+    /**
+     * Check worker health and get basic stats
+     */
+    health(): Promise<WalletReportHealthResponse>;
+    /**
+     * Get detailed statistics
+     */
+    getStats(): Promise<WalletReportStatsResponse>;
+    /**
+     * Get or generate a wallet report
+     *
+     * Returns cached report if available, otherwise generates a new one.
+     * Use forceRefresh to skip cache and generate a fresh report.
+     *
+     * @param address - Wallet address
+     * @param forceRefresh - Force regeneration even if cached (default: false)
+     */
+    getWalletReport(address: string, forceRefresh?: boolean): Promise<GetWalletReportResponse | ReportGeneratingResponse>;
+    /**
+     * Get wallet report data directly (convenience method)
+     *
+     * Throws if report is still generating.
+     */
+    getWalletReportData(address: string, forceRefresh?: boolean): Promise<WalletReportData>;
+    /**
+     * Get the latest daily leaderboard
+     */
+    getDailyLeaderboard(): Promise<GetLeaderboardResponse | null>;
+    /**
+     * Get the latest weekly leaderboard
+     */
+    getWeeklyLeaderboard(): Promise<GetLeaderboardResponse | null>;
+    /**
+     * Get the latest monthly leaderboard
+     */
+    getMonthlyLeaderboard(): Promise<GetLeaderboardResponse | null>;
+    /**
+     * Get leaderboard report data directly (convenience method)
+     */
+    getLeaderboardData(period: 'daily' | 'weekly' | 'monthly'): Promise<LeaderboardReportData | null>;
+    /**
+     * Force generate a leaderboard report
+     */
+    forceGenerateLeaderboard(type: 'daily' | 'weekly' | 'monthly'): Promise<void>;
+    /**
+     * List all reports
+     */
+    listReports(params?: ListReportsParams): Promise<ListReportsResponse>;
+    /**
+     * Delete a report by ID
+     */
+    deleteReport(id: string): Promise<boolean>;
+    /**
+     * Cleanup expired reports
+     */
+    cleanupExpired(): Promise<number>;
+    private fetchJson;
+}
+//# sourceMappingURL=wallet-report-service.d.ts.map

package/dist/src/wallet-report/wallet-report-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-report-service.d.ts","sourceRoot":"","sources":["../../../src/wallet-report/wallet-report-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,yBAAyB;IAS7C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAInD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,yBAAyB,CAAC;IAQpD;;;;;;;;OAQG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,YAAY,UAAQ,GACnB,OAAO,CAAC,uBAAuB,GAAG,wBAAwB,CAAC;IAO9D;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAc3F;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAWnE;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAWpE;;OAEG;IACG,qBAAqB,IAAI,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAWrE;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAkBvG;;OAEG;IACG,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnF;;OAEG;IACG,WAAW,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAW/E;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;YASzB,SAAS;CAwBxB"}

package/dist/src/wallet-report/wallet-report-service.js

@@ -0,0 +1,208 @@
+/**
+ * WalletReportService
+ *
+ * Client for querying the WalletReportWorker API.
+ *
+ * @example
+ * ```typescript
+ * const service = new WalletReportService({
+ *   baseUrl: 'http://localhost:8789',
+ * });
+ *
+ * // Get health status
+ * const health = await service.health();
+ *
+ * // Get or generate wallet report
+ * const report = await service.getWalletReport('0x...');
+ *
+ * // Get daily leaderboard
+ * const leaderboard = await service.getDailyLeaderboard();
+ * ```
+ */
+export class WalletReportService {
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = config.timeoutMs ?? 60_000;
+    }
+    // ============================================================================
+    // Health & Stats
+    // ============================================================================
+    /**
+     * Check worker health and get basic stats
+     */
+    async health() {
+        return this.fetchJson('/v1/health');
+    }
+    /**
+     * Get detailed statistics
+     */
+    async getStats() {
+        return this.fetchJson('/v1/stats');
+    }
+    // ============================================================================
+    // Wallet Reports
+    // ============================================================================
+    /**
+     * Get or generate a wallet report
+     *
+     * Returns cached report if available, otherwise generates a new one.
+     * Use forceRefresh to skip cache and generate a fresh report.
+     *
+     * @param address - Wallet address
+     * @param forceRefresh - Force regeneration even if cached (default: false)
+     */
+    async getWalletReport(address, forceRefresh = false) {
+        const query = forceRefresh ? '?refresh=true' : '';
+        return this.fetchJson(`/v1/wallets/${address.toLowerCase()}/report${query}`);
+    }
+    /**
+     * Get wallet report data directly (convenience method)
+     *
+     * Throws if report is still generating.
+     */
+    async getWalletReportData(address, forceRefresh = false) {
+        const response = await this.getWalletReport(address, forceRefresh);
+        if ('status' in response && response.status === 'generating') {
+            throw new Error('Report is still generating');
+        }
+        return response.report;
+    }
+    // ============================================================================
+    // Leaderboards
+    // ============================================================================
+    /**
+     * Get the latest daily leaderboard
+     */
+    async getDailyLeaderboard() {
+        try {
+            return await this.fetchJson('/v1/leaderboards/daily');
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get the latest weekly leaderboard
+     */
+    async getWeeklyLeaderboard() {
+        try {
+            return await this.fetchJson('/v1/leaderboards/weekly');
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get the latest monthly leaderboard
+     */
+    async getMonthlyLeaderboard() {
+        try {
+            return await this.fetchJson('/v1/leaderboards/monthly');
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get leaderboard report data directly (convenience method)
+     */
+    async getLeaderboardData(period) {
+        let response;
+        switch (period) {
+            case 'daily':
+                response = await this.getDailyLeaderboard();
+                break;
+            case 'weekly':
+                response = await this.getWeeklyLeaderboard();
+                break;
+            case 'monthly':
+                response = await this.getMonthlyLeaderboard();
+                break;
+        }
+        return response?.report ?? null;
+    }
+    /**
+     * Force generate a leaderboard report
+     */
+    async forceGenerateLeaderboard(type) {
+        await this.fetchJson(`/v1/leaderboards/${type}/generate`, { method: 'POST' });
+    }
+    // ============================================================================
+    // Report Management
+    // ============================================================================
+    /**
+     * List all reports
+     */
+    async listReports(params = {}) {
+        const query = new URLSearchParams();
+        if (params.type)
+            query.set('type', params.type);
+        if (params.status)
+            query.set('status', params.status);
+        if (params.limit != null)
+            query.set('limit', String(params.limit));
+        if (params.offset != null)
+            query.set('offset', String(params.offset));
+        const q = query.toString();
+        return this.fetchJson(`/v1/reports${q ? `?${q}` : ''}`);
+    }
+    /**
+     * Delete a report by ID
+     */
+    async deleteReport(id) {
+        try {
+            await this.fetchJson(`/v1/reports/${id}`, { method: 'DELETE' });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Cleanup expired reports
+     */
+    async cleanupExpired() {
+        const result = await this.fetchJson('/v1/reports/cleanup', { method: 'POST' });
+        return result.deletedCount;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    async fetchJson(path, options = {}) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}${path}`, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...options.headers,
+                },
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`WalletReportService HTTP ${res.status}: ${text || res.statusText}`);
+            }
+            return await res.json();
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+//# sourceMappingURL=wallet-report-service.js.map

package/dist/src/wallet-report/wallet-report-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-report-service.js","sourceRoot":"","sources":["../../../src/wallet-report/wallet-report-service.ts"],"names":[],"mappings":"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"}

package/dist/src/wallets/hot-wallet-service.d.ts

@@ -0,0 +1,162 @@
+/**
+ * HotWalletService - 自管 Hot Wallet 服务
+ *
+ * 为每个用户创建专用的 hot wallet，私钥加密存储在服务端。
+ * 策略引擎可以完全自动执行所有链上操作。
+ *
+ * 安全措施：
+ * 1. 私钥使用 AES-256-GCM 加密存储
+ * 2. 加密密钥从环境变量读取（生产环境应使用 KMS）
+ * 3. 私钥解密后仅在内存中短暂存在
+ * 4. 操作完成后立即清除内存中的私钥
+ *
+ * @example
+ * ```typescript
+ * const hotWalletService = new HotWalletService({
+ *   encryptionKey: process.env.WALLET_ENCRYPTION_KEY!,
+ *   store: new UserStore(), // 实现 IWalletStore 接口
+ * });
+ *
+ * // 创建新钱包
+ * const { address, encryptedKey } = await hotWalletService.createWallet();
+ *
+ * // 执行操作
+ * await hotWalletService.executeWithWallet(userId, async (wallet) => {
+ *   await wallet.sendTransaction({ to: '0x...', data: '0x...' });
+ * });
+ * ```
+ */
+import { ethers } from 'ethers';
+export interface HotWalletServiceConfig {
+    /** 32-byte hex string for AES-256 encryption */
+    encryptionKey: string;
+    /** Wallet store implementation */
+    store: IWalletStore;
+    /** RPC URL (default: Polygon mainnet) */
+    rpcUrl?: string;
+    /** Chain ID (default: 137) */
+    chainId?: number;
+}
+export interface IWalletStore {
+    /** Get encrypted private key by user ID */
+    getEncryptedKey(userId: string): Promise<string | null>;
+    /** Store encrypted private key for user */
+    setEncryptedKey(userId: string, encryptedKey: string, address: string): Promise<void>;
+    /** Get wallet address by user ID */
+    getWalletAddress(userId: string): Promise<string | null>;
+    /** Check if user has a wallet */
+    hasWallet(userId: string): Promise<boolean>;
+}
+export interface WalletInfo {
+    address: string;
+    encryptedKey: string;
+}
+export interface EncryptedData {
+    /** Initialization vector (hex) */
+    iv: string;
+    /** Auth tag for GCM (hex) */
+    authTag: string;
+    /** Encrypted data (hex) */
+    data: string;
+}
+export declare class HotWalletService {
+    private config;
+    private provider;
+    constructor(config: HotWalletServiceConfig);
+    /**
+     * 创建新的 Hot Wallet
+     *
+     * @returns 钱包地址和加密后的私钥
+     */
+    createWallet(): Promise<WalletInfo>;
+    /**
+     * 为用户创建并存储钱包
+     *
+     * @param userId - 用户 ID
+     * @returns 钱包地址
+     */
+    createWalletForUser(userId: string): Promise<string>;
+    /**
+     * 获取用户的钱包地址
+     *
+     * @param userId - 用户 ID
+     * @returns 钱包地址，如果没有则返回 null
+     */
+    getWalletAddress(userId: string): Promise<string | null>;
+    /**
+     * 检查用户是否有钱包
+     *
+     * @param userId - 用户 ID
+     */
+    hasWallet(userId: string): Promise<boolean>;
+    /**
+     * 使用用户钱包执行操作
+     *
+     * 私钥仅在回调执行期间存在于内存中，执行完毕后立即清除。
+     *
+     * @param userId - 用户 ID
+     * @param callback - 使用钱包执行的操作
+     * @returns 回调的返回值
+     */
+    executeWithWallet<T>(userId: string, callback: (wallet: ethers.Wallet) => Promise<T>): Promise<T>;
+    /**
+     * 获取用户钱包的私钥（危险操作，仅用于初始化 SDK）
+     *
+     * 调用者必须负责安全处理私钥！
+     *
+     * @param userId - 用户 ID
+     * @returns 私钥
+     */
+    getPrivateKey(userId: string): Promise<string>;
+    /**
+     * 获取用户钱包余额
+     *
+     * @param userId - 用户 ID
+     */
+    getBalance(userId: string): Promise<{
+        matic: string;
+        maticWei: string;
+    }>;
+    /**
+     * 发送交易
+     *
+     * @param userId - 用户 ID
+     * @param tx - 交易参数
+     */
+    sendTransaction(userId: string, tx: ethers.providers.TransactionRequest): Promise<ethers.providers.TransactionResponse>;
+    /**
+     * 签名消息
+     *
+     * @param userId - 用户 ID
+     * @param message - 消息
+     */
+    signMessage(userId: string, message: string): Promise<string>;
+    /**
+     * 签名 EIP-712 类型数据
+     *
+     * @param userId - 用户 ID
+     * @param domain - EIP-712 domain
+     * @param types - EIP-712 types
+     * @param value - 要签名的数据
+     */
+    signTypedData(userId: string, domain: ethers.TypedDataDomain, types: Record<string, ethers.TypedDataField[]>, value: Record<string, any>): Promise<string>;
+    /**
+     * 加密私钥
+     */
+    private encryptPrivateKey;
+    /**
+     * 解密私钥
+     */
+    private decryptPrivateKey;
+    /**
+     * 生成加密密钥
+     *
+     * 用于首次设置时生成 WALLET_ENCRYPTION_KEY
+     */
+    static generateEncryptionKey(): string;
+    /**
+     * 验证加密密钥格式
+     */
+    static validateEncryptionKey(key: string): boolean;
+}
+//# sourceMappingURL=hot-wallet-service.d.ts.map

package/dist/src/wallets/hot-wallet-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-wallet-service.d.ts","sourceRoot":"","sources":["../../../src/wallets/hot-wallet-service.ts"],"names":[],"mappings":"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"}