@0xmonaco/core 0.7.7 → 0.7.9

package/dist/api/profile/api.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Profile API Implementation
+ *
+ * Handles user profile operations including fetching profile information.
+ * All operations use JWT authentication and go through the API Gateway.
+ *
+ * This class provides a complete interface for profile operations on the Monaco protocol,
+ * including fetching user profile data from the /api/v1/accounts/me endpoint.
+ *
+ * @example
+ * ```typescript
+ * const profileAPI = new ProfileAPIImpl(apiUrl);
+ * profileAPI.setAccessToken(jwtToken);
+ *
+ * // Get user profile
+ * const profile = await profileAPI.getProfile();
+ * console.log(`User: ${profile.username} (${profile.address})`);
+ * ```
+ */
+import type { AccountBalance, GetPaginatedUserMovementsResponse, GetUserBalancesParams, GetUserBalancesResponse, GetUserMovementsParams, GetUserTradesParams, GetUserTradesResponse, PortfolioChartResponse, PortfolioMetric, PortfolioPeriod, PortfolioStats, ProfileAPI, UserProfile } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+export declare class ProfileAPIImpl extends BaseAPI implements ProfileAPI {
+    /**
+     * Get the current user's profile information.
+     *
+     * Fetches the profile data for the authenticated user using the /api/v1/accounts/me endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @returns Promise resolving to the user's profile information
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Set access token first
+     * profileAPI.setAccessToken(authResult.accessToken);
+     *
+     * // Get profile
+     * const profile = await profileAPI.getProfile();
+     * console.log(`User ID: ${profile.id}`);
+     * console.log(`Address: ${profile.address}`);
+     * console.log(`Username: ${profile.username}`);
+     * console.log(`Account type: ${profile.account_type}`);
+     * console.log(`Can withdraw: ${profile.can_withdraw}`);
+     * ```
+     */
+    getProfile(): Promise<UserProfile>;
+    /**
+     * Get the current user's ledger movements (transaction history) with pagination.
+     *
+     * Fetches the user's transaction history from the /api/v1/accounts/movements endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination and filtering
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.limit - Number of items per page (default: 20, max: 100)
+     * @param params.entry_type - Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE)
+     * @param params.transaction_type - Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD)
+     * @param params.asset_id - Filter by asset ID (UUID)
+     * @returns Promise resolving to paginated movements response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first page with default page_size (20)
+     * const movements = await profileAPI.getPaginatedUserMovements();
+     * console.log(`Total movements: ${movements.total}`);
+     *
+     * // Get second page with custom page_size
+     * const page2 = await profileAPI.getPaginatedUserMovements({ page: 2, page_size: 50 });
+     * console.log(`Page ${page2.page} of ${page2.total_pages}`);
+     *
+     * // Filter by entry type and transaction type
+     * const deposits = await profileAPI.getPaginatedUserMovements({ entry_type: "CREDIT", transaction_type: "DEPOSIT" });
+     *
+     * // Filter by asset
+     * const usdcMovements = await profileAPI.getPaginatedUserMovements({ asset_id: "550e8400-e29b-41d4-a716-446655440000" });
+     * ```
+     */
+    getPaginatedUserMovements(params?: GetUserMovementsParams): Promise<GetPaginatedUserMovementsResponse>;
+    /**
+     * Get the current user's token balances with pagination.
+     *
+     * Fetches the user's token balances from the /api/v1/accounts/balances endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.page_size - Number of items per page (default: 20, max: 100)
+     * @returns Promise resolving to paginated balances response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first 20 balances (default limit)
+     * const balances = await profileAPI.getUserBalances();
+     * console.log(`Total balances: ${balances.total}`);
+     * balances.balances.forEach(balance => {
+     *   console.log(`${balance.symbol}: ${balance.available_balance}`);
+     * });
+     *
+     * // Get page 2 with 50 items per page
+     * const nextBalances = await profileAPI.getUserBalances({ page: 2, page_size: 50 });
+     * console.log(`Returned ${nextBalances.balances.length} balances`);
+     * ```
+     */
+    getUserBalances(params?: GetUserBalancesParams): Promise<GetUserBalancesResponse>;
+    /**
+     * Get the current user's balance for a specific asset.
+     *
+     * Fetches the user's balance for a specific asset from the /api/v1/accounts/balances/{asset_id} endpoint.
+     * Requires a valid access token to be set. If no balance exists for a valid asset, returns zero balances.
+     *
+     * @param assetId - The asset identifier (UUID)
+     * @returns Promise resolving to the account balance for the asset
+     * @throws {APIError} When the request fails, user is not authenticated, or asset not found (404)
+     *
+     * @example
+     * ```typescript
+     * // Get balance for a specific asset
+     * const balance = await profileAPI.getUserBalanceByAssetId('123e4567-e89b-12d3-a456-426614174000');
+     * console.log(`${balance.symbol}: ${balance.available_balance}`);
+     * console.log(`Locked: ${balance.locked_balance}`);
+     * console.log(`Total: ${balance.total_balance}`);
+     * ```
+     */
+    getUserBalanceByAssetId(assetId: string): Promise<AccountBalance>;
+    /**
+     * Get the current user's portfolio statistics for a given time period.
+     *
+     * Fetches aggregate stats from the /api/v1/accounts/me/portfolio endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param period - Time period to scope the stats ("24h" | "7d" | "30d" | "all")
+     * @returns Promise resolving to the user's portfolio statistics
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const stats = await profileAPI.getPortfolioStats("30d");
+     * console.log(`PnL: ${stats.pnl}`);
+     * console.log(`Volume: ${stats.volume}`);
+     * console.log(`Total equity: ${stats.total_equity}`);
+     * ```
+     */
+    getPortfolioStats(period: PortfolioPeriod): Promise<PortfolioStats>;
+    /**
+     * Get the current user's portfolio chart time series for a given period and metric.
+     *
+     * Fetches bucketed time series data from the /api/v1/accounts/me/portfolio/chart endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param period - Time period ("24h" | "7d" | "30d" | "all")
+     * @param metric - Metric to chart ("volume" | "pnl")
+     * @returns Promise resolving to the portfolio chart response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const chart = await profileAPI.getPortfolioChart("7d", "pnl");
+     * chart.data.forEach(point => {
+     *   console.log(`${point.timestamp}: ${point.value}`);
+     * });
+     * ```
+     */
+    getPortfolioChart(period: PortfolioPeriod, metric: PortfolioMetric): Promise<PortfolioChartResponse>;
+    /**
+     * Get the current user's trade history with pagination.
+     *
+     * Fetches the user's executed trades from the /api/v1/accounts/trades endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination and filtering
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.page_size - Number of items per page (default: 20, max: 100)
+     * @param params.trading_pair_id - Filter by trading pair ID (UUID)
+     * @returns Promise resolving to paginated trades response
+     * @throws {ValidationError} When the provided params fail client-side validation
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first page of trades
+     * const trades = await profileAPI.getUserTrades();
+     * console.log(`Total trades: ${trades.total}`);
+     *
+     * // Filter by trading pair
+     * const pairTrades = await profileAPI.getUserTrades({ trading_pair_id: "550e8400-e29b-41d4-a716-446655440000" });
+     * ```
+     */
+    getUserTrades(params?: GetUserTradesParams): Promise<GetUserTradesResponse>;
+}

package/dist/api/profile/api.js

@@ -0,0 +1,259 @@
+/**
+ * Profile API Implementation
+ *
+ * Handles user profile operations including fetching profile information.
+ * All operations use JWT authentication and go through the API Gateway.
+ *
+ * This class provides a complete interface for profile operations on the Monaco protocol,
+ * including fetching user profile data from the /api/v1/accounts/me endpoint.
+ *
+ * @example
+ * ```typescript
+ * const profileAPI = new ProfileAPIImpl(apiUrl);
+ * profileAPI.setAccessToken(jwtToken);
+ *
+ * // Get user profile
+ * const profile = await profileAPI.getProfile();
+ * console.log(`User: ${profile.username} (${profile.address})`);
+ * ```
+ */
+import { GetUserMovementsSchema, GetUserTradesSchema, validate } from "@0xmonaco/types";
+import { APIError } from "../../errors";
+import { BaseAPI } from "../base";
+export class ProfileAPIImpl extends BaseAPI {
+    /**
+     * Get the current user's profile information.
+     *
+     * Fetches the profile data for the authenticated user using the /api/v1/accounts/me endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @returns Promise resolving to the user's profile information
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Set access token first
+     * profileAPI.setAccessToken(authResult.accessToken);
+     *
+     * // Get profile
+     * const profile = await profileAPI.getProfile();
+     * console.log(`User ID: ${profile.id}`);
+     * console.log(`Address: ${profile.address}`);
+     * console.log(`Username: ${profile.username}`);
+     * console.log(`Account type: ${profile.account_type}`);
+     * console.log(`Can withdraw: ${profile.can_withdraw}`);
+     * ```
+     */
+    async getProfile() {
+        return await this.makeAuthenticatedRequest("/api/v1/accounts/me");
+    }
+    /**
+     * Get the current user's ledger movements (transaction history) with pagination.
+     *
+     * Fetches the user's transaction history from the /api/v1/accounts/movements endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination and filtering
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.limit - Number of items per page (default: 20, max: 100)
+     * @param params.entry_type - Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE)
+     * @param params.transaction_type - Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD)
+     * @param params.asset_id - Filter by asset ID (UUID)
+     * @returns Promise resolving to paginated movements response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first page with default page_size (20)
+     * const movements = await profileAPI.getPaginatedUserMovements();
+     * console.log(`Total movements: ${movements.total}`);
+     *
+     * // Get second page with custom page_size
+     * const page2 = await profileAPI.getPaginatedUserMovements({ page: 2, page_size: 50 });
+     * console.log(`Page ${page2.page} of ${page2.total_pages}`);
+     *
+     * // Filter by entry type and transaction type
+     * const deposits = await profileAPI.getPaginatedUserMovements({ entry_type: "CREDIT", transaction_type: "DEPOSIT" });
+     *
+     * // Filter by asset
+     * const usdcMovements = await profileAPI.getPaginatedUserMovements({ asset_id: "550e8400-e29b-41d4-a716-446655440000" });
+     * ```
+     */
+    async getPaginatedUserMovements(params) {
+        if (params) {
+            validate(GetUserMovementsSchema, params);
+        }
+        const searchParams = new URLSearchParams();
+        if (params?.page !== undefined) {
+            searchParams.append("page", params.page.toString());
+        }
+        if (params?.page_size !== undefined) {
+            searchParams.append("page_size", params.page_size.toString());
+        }
+        if (params?.entry_type !== undefined) {
+            searchParams.append("entry_type", params.entry_type);
+        }
+        if (params?.transaction_type !== undefined) {
+            searchParams.append("transaction_type", params.transaction_type);
+        }
+        if (params?.asset_id !== undefined) {
+            searchParams.append("asset_id", params.asset_id);
+        }
+        const queryString = searchParams.toString();
+        const url = queryString ? `/api/v1/accounts/movements?${queryString}` : "/api/v1/accounts/movements";
+        return await this.makeAuthenticatedRequest(url);
+    }
+    /**
+     * Get the current user's token balances with pagination.
+     *
+     * Fetches the user's token balances from the /api/v1/accounts/balances endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.page_size - Number of items per page (default: 20, max: 100)
+     * @returns Promise resolving to paginated balances response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first 20 balances (default limit)
+     * const balances = await profileAPI.getUserBalances();
+     * console.log(`Total balances: ${balances.total}`);
+     * balances.balances.forEach(balance => {
+     *   console.log(`${balance.symbol}: ${balance.available_balance}`);
+     * });
+     *
+     * // Get page 2 with 50 items per page
+     * const nextBalances = await profileAPI.getUserBalances({ page: 2, page_size: 50 });
+     * console.log(`Returned ${nextBalances.balances.length} balances`);
+     * ```
+     */
+    async getUserBalances(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.page !== undefined) {
+            searchParams.append("page", params.page.toString());
+        }
+        if (params?.page_size !== undefined) {
+            searchParams.append("page_size", params.page_size.toString());
+        }
+        const queryString = searchParams.toString();
+        const url = queryString ? `/api/v1/accounts/balances?${queryString}` : "/api/v1/accounts/balances";
+        return await this.makeAuthenticatedRequest(url);
+    }
+    /**
+     * Get the current user's balance for a specific asset.
+     *
+     * Fetches the user's balance for a specific asset from the /api/v1/accounts/balances/{asset_id} endpoint.
+     * Requires a valid access token to be set. If no balance exists for a valid asset, returns zero balances.
+     *
+     * @param assetId - The asset identifier (UUID)
+     * @returns Promise resolving to the account balance for the asset
+     * @throws {APIError} When the request fails, user is not authenticated, or asset not found (404)
+     *
+     * @example
+     * ```typescript
+     * // Get balance for a specific asset
+     * const balance = await profileAPI.getUserBalanceByAssetId('123e4567-e89b-12d3-a456-426614174000');
+     * console.log(`${balance.symbol}: ${balance.available_balance}`);
+     * console.log(`Locked: ${balance.locked_balance}`);
+     * console.log(`Total: ${balance.total_balance}`);
+     * ```
+     */
+    async getUserBalanceByAssetId(assetId) {
+        if (!assetId || assetId.trim() === "") {
+            throw new APIError("assetId is required and cannot be empty", {
+                endpoint: "/api/v1/accounts/balances/{asset_id}",
+            });
+        }
+        const url = `/api/v1/accounts/balances/${assetId}`;
+        return await this.makeAuthenticatedRequest(url);
+    }
+    /**
+     * Get the current user's portfolio statistics for a given time period.
+     *
+     * Fetches aggregate stats from the /api/v1/accounts/me/portfolio endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param period - Time period to scope the stats ("24h" | "7d" | "30d" | "all")
+     * @returns Promise resolving to the user's portfolio statistics
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const stats = await profileAPI.getPortfolioStats("30d");
+     * console.log(`PnL: ${stats.pnl}`);
+     * console.log(`Volume: ${stats.volume}`);
+     * console.log(`Total equity: ${stats.total_equity}`);
+     * ```
+     */
+    async getPortfolioStats(period) {
+        const searchParams = new URLSearchParams({ period });
+        return await this.makeAuthenticatedRequest(`/api/v1/accounts/me/portfolio?${searchParams}`);
+    }
+    /**
+     * Get the current user's portfolio chart time series for a given period and metric.
+     *
+     * Fetches bucketed time series data from the /api/v1/accounts/me/portfolio/chart endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param period - Time period ("24h" | "7d" | "30d" | "all")
+     * @param metric - Metric to chart ("volume" | "pnl")
+     * @returns Promise resolving to the portfolio chart response
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const chart = await profileAPI.getPortfolioChart("7d", "pnl");
+     * chart.data.forEach(point => {
+     *   console.log(`${point.timestamp}: ${point.value}`);
+     * });
+     * ```
+     */
+    async getPortfolioChart(period, metric) {
+        const searchParams = new URLSearchParams({ period, metric });
+        return await this.makeAuthenticatedRequest(`/api/v1/accounts/me/portfolio/chart?${searchParams}`);
+    }
+    /**
+     * Get the current user's trade history with pagination.
+     *
+     * Fetches the user's executed trades from the /api/v1/accounts/trades endpoint.
+     * Requires a valid access token to be set.
+     *
+     * @param params - Optional query parameters for pagination and filtering
+     * @param params.page - Page number (starts from 1, default: 1)
+     * @param params.page_size - Number of items per page (default: 20, max: 100)
+     * @param params.trading_pair_id - Filter by trading pair ID (UUID)
+     * @returns Promise resolving to paginated trades response
+     * @throws {ValidationError} When the provided params fail client-side validation
+     * @throws {APIError} When the request fails or user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get first page of trades
+     * const trades = await profileAPI.getUserTrades();
+     * console.log(`Total trades: ${trades.total}`);
+     *
+     * // Filter by trading pair
+     * const pairTrades = await profileAPI.getUserTrades({ trading_pair_id: "550e8400-e29b-41d4-a716-446655440000" });
+     * ```
+     */
+    async getUserTrades(params) {
+        if (params) {
+            validate(GetUserTradesSchema, params);
+        }
+        const searchParams = new URLSearchParams();
+        if (params?.page !== undefined) {
+            searchParams.append("page", params.page.toString());
+        }
+        if (params?.page_size !== undefined) {
+            searchParams.append("page_size", params.page_size.toString());
+        }
+        if (params?.trading_pair_id !== undefined) {
+            searchParams.append("trading_pair_id", params.trading_pair_id);
+        }
+        const queryString = searchParams.toString();
+        const url = queryString ? `/api/v1/accounts/trades?${queryString}` : "/api/v1/accounts/trades";
+        return await this.makeAuthenticatedRequest(url);
+    }
+}

package/dist/api/profile/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Profile API Module
+ *
+ * Exports the ProfileAPI implementation for user profile operations.
+ */
+export * from "./api";

package/dist/api/profile/index.js

@@ -0,0 +1,6 @@
+/**
+ * Profile API Module
+ *
+ * Exports the ProfileAPI implementation for user profile operations.
+ */
+export * from "./api";

package/dist/api/trades/api.d.ts

@@ -0,0 +1,44 @@
+import type { TradeEvent } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+/**
+ * Raw trade event from the API (snake_case) - matches websocket structure
+ */
+interface RawTradeEvent {
+    event_type: string;
+    trading_pair_id: string;
+    trading_mode: string;
+    data: {
+        trade_id: string;
+        price: string;
+        quantity: string;
+        maker_side: string;
+        executed_at: string;
+    };
+}
+/**
+ * Convert a raw trade event (snake_case) to a TradeEvent (camelCase)
+ */
+export declare function parseRawTradeEvent(raw: RawTradeEvent): TradeEvent;
+/**
+ * Options for fetching trades
+ */
+export interface GetTradesOptions {
+    /** Page number (starts from 1, default: 1) */
+    page?: number;
+    /** Maximum number of records to return (default: 25, max: 100) */
+    page_size?: number;
+}
+/**
+ * Trades API for fetching historical trade data
+ */
+export declare class TradesAPIImpl extends BaseAPI {
+    /**
+     * Get historical trades for a trading pair
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param options - Pagination options
+     * @returns Array of TradeEvent records sorted by executed_at descending (newest first)
+     */
+    getTrades(tradingPairId: string, options?: GetTradesOptions): Promise<TradeEvent[]>;
+}
+export {};

package/dist/api/trades/api.js

@@ -0,0 +1,42 @@
+import { BaseAPI } from "../base";
+/**
+ * Convert a raw trade event (snake_case) to a TradeEvent (camelCase)
+ */
+export function parseRawTradeEvent(raw) {
+    return {
+        eventType: "trade",
+        tradingPairId: raw.trading_pair_id,
+        tradingMode: raw.trading_mode.toUpperCase(),
+        data: {
+            tradeId: raw.data.trade_id,
+            price: raw.data.price,
+            quantity: raw.data.quantity,
+            makerSide: raw.data.maker_side.toUpperCase(),
+            executedAt: raw.data.executed_at,
+        },
+    };
+}
+/**
+ * Trades API for fetching historical trade data
+ */
+export class TradesAPIImpl extends BaseAPI {
+    /**
+     * Get historical trades for a trading pair
+     *
+     * @param tradingPairId - The trading pair UUID
+     * @param options - Pagination options
+     * @returns Array of TradeEvent records sorted by executed_at descending (newest first)
+     */
+    async getTrades(tradingPairId, options = {}) {
+        const { page = 1 } = options;
+        // Ensure page_size is a positive number between 1 and 100, defaulting to 25
+        const page_size = options.page_size != null && options.page_size > 0 ? Math.min(options.page_size, 100) : 25;
+        const params = new URLSearchParams();
+        if (page > 1) {
+            params.set("page", String(page));
+        }
+        params.set("page_size", String(page_size));
+        const response = await this.makePublicRequest(`/api/v1/trades/${encodeURIComponent(tradingPairId)}?${params.toString()}`);
+        return response.trades.map(parseRawTradeEvent);
+    }
+}

package/dist/api/trades/index.d.ts

@@ -0,0 +1 @@
+export * from "./api";

package/dist/api/trades/index.js

@@ -0,0 +1 @@
+export * from "./api";