@alpha-arcade/sdk 0.3.1 → 0.3.5

package/dist/index.d.cts

@@ -276,6 +276,11 @@ type AggregatedOrderbook = {
     yes: AggregatedOrderbookSide;
     no: AggregatedOrderbookSide;
 };
+/**
+ * Full processed market orderbook keyed by marketAppId.
+ * Matches the REST `/get-full-orderbook` response and `orderbook_changed.orderbook`.
+ */
+type FullOrderbookSnapshot = Record<string, WsOrderbookApp>;
 /** Parameters for split shares */
 type SplitSharesParams = {
     /** Market app ID */
@@ -362,6 +367,78 @@ type EscrowGlobalState = {
     asset_listed?: number;
     fee_timer_start?: number;
 };
+/** Configuration for AlphaWebSocket */
+type AlphaWebSocketConfig = {
+    /** WebSocket URL override (default: wss://wss.platform.alphaarcade.com) */
+    url?: string;
+    /** Enable auto-reconnect on unexpected disconnect (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnect attempts before giving up (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 60000) */
+    heartbeatIntervalMs?: number;
+    /**
+     * WebSocket constructor to use. Defaults to the global `WebSocket`.
+     * On Node.js < 22, pass the `ws` package: `import WebSocket from 'ws'; new AlphaWebSocket({ WebSocket })`
+     */
+    WebSocket?: unknown;
+};
+/** Orderbook bid/ask entry at the top level (decimal cents) */
+type WsOrderbookAggregatedEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+};
+/** Orderbook bid/ask entry with escrow details (raw microunit prices) */
+type WsOrderbookDetailEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+    escrowAppId: number;
+    owner: string;
+};
+/** Per-side orderbook detail (yes or no) */
+type WsOrderbookDetailSide = {
+    bids: WsOrderbookDetailEntry[];
+    asks: WsOrderbookDetailEntry[];
+};
+/** Orderbook data for a single app within the orderbook payload */
+type WsOrderbookApp = {
+    bids: WsOrderbookAggregatedEntry[];
+    asks: WsOrderbookAggregatedEntry[];
+    spread: number;
+    yes: WsOrderbookDetailSide;
+    no: WsOrderbookDetailSide;
+};
+/** Payload for orderbook_changed events */
+type OrderbookChangedEvent = {
+    type: 'orderbook_changed';
+    ts: number;
+    marketId: string;
+    slug?: string;
+    version: number;
+    orderbook: FullOrderbookSnapshot;
+};
+/** Payload for markets_changed events (incremental diffs) */
+type MarketsChangedEvent = {
+    type: 'markets_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for market_changed events (single market) */
+type MarketChangedEvent = {
+    type: 'market_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for wallet_orders_changed events */
+type WalletOrdersChangedEvent = {
+    type: 'wallet_orders_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Discriminated union of all WebSocket stream events */
+type WebSocketStreamEvent = MarketsChangedEvent | MarketChangedEvent | OrderbookChangedEvent | WalletOrdersChangedEvent;
 
 /**
  * The main client for interacting with Alpha Market prediction markets on Algorand.
@@ -369,7 +446,7 @@ type EscrowGlobalState = {
  * Provides methods for:
  * - **Trading**: Create limit/market orders, cancel orders, propose matches
  * - **Positions**: Split/merge shares, claim resolved tokens, view positions
- * - **Orderbook**: Read on-chain orderbook for any market
+ * - **Orderbook**: Read on-chain orderbooks or fetch full API-backed market snapshots
  * - **Markets**: Fetch live markets from the Alpha API
  *
  * @example
@@ -523,6 +600,17 @@ declare class AlphaClient {
      * @returns Orderbook with yes and no sides, each having bids and asks
      */
     getOrderbook(marketAppId: number): Promise<Orderbook>;
+    /**
+     * Fetches the full processed orderbook snapshot for a market from the Alpha REST API.
+     *
+     * Returns the same shape as websocket `orderbook_changed.orderbook`: a record keyed by
+     * `marketAppId`, where each value includes aggregated bids/asks plus detailed yes/no orders.
+     * Requires `apiKey`.
+     *
+     * @param marketId - The Alpha market UUID
+     * @returns Full processed market orderbook keyed by marketAppId
+     */
+    getFullOrderbookFromApi(marketId: string): Promise<FullOrderbookSnapshot>;
     /**
      * Gets open orders for a specific wallet on a market.
      *
@@ -597,6 +685,96 @@ declare class AlphaClient {
     getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/**
+ * Real-time WebSocket client for Alpha Market platform streams.
+ *
+ * Connects to `wss://wss.platform.alphaarcade.com` and provides typed,
+ * callback-based subscriptions for live market data. No auth required.
+ *
+ * @example
+ * ```typescript
+ * // Node.js 22+ or browser (native WebSocket)
+ * const ws = new AlphaWebSocket();
+ *
+ * // Node.js < 22 — pass the `ws` package
+ * import WebSocket from 'ws';
+ * const ws = new AlphaWebSocket({ WebSocket });
+ *
+ * const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+ *   console.log('Orderbook:', event.orderbook);
+ * });
+ *
+ * // Later
+ * unsub();
+ * ws.close();
+ * ```
+ */
+declare class AlphaWebSocket {
+    private url;
+    private reconnectEnabled;
+    private maxReconnectAttempts;
+    private heartbeatIntervalMs;
+    private WebSocketImpl;
+    private ws;
+    private subscriptions;
+    private pendingRequests;
+    private lastOrderbookVersionBySubscription;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionallyClosed;
+    private connectPromise;
+    constructor(config?: AlphaWebSocketConfig);
+    /** Whether the WebSocket is currently open and connected */
+    get connected(): boolean;
+    /**
+     * Subscribe to live market probability updates (incremental diffs).
+     * @returns An unsubscribe function
+     */
+    subscribeLiveMarkets(callback: (event: MarketsChangedEvent) => void): () => void;
+    /**
+     * Subscribe to change events for a single market.
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeMarket(slug: string, callback: (event: MarketChangedEvent) => void): () => void;
+    /**
+     * Subscribe to full orderbook snapshots (~5s interval on changes).
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeOrderbook(slug: string, callback: (event: OrderbookChangedEvent) => void): () => void;
+    /**
+     * Subscribe to wallet order updates.
+     * @param wallet - The wallet address
+     * @returns An unsubscribe function
+     */
+    subscribeWalletOrders(wallet: string, callback: (event: WalletOrdersChangedEvent) => void): () => void;
+    /** Query the server for the list of active subscriptions on this connection */
+    listSubscriptions(): Promise<unknown>;
+    /** Query a server property (e.g. "heartbeat", "limits") */
+    getProperty(property: string): Promise<unknown>;
+    /** Open the WebSocket connection. Called automatically on first subscribe. */
+    connect(): Promise<void>;
+    /** Close the connection and clean up all resources */
+    close(): void;
+    private buildStreamKey;
+    private buildQueryString;
+    private subscribe;
+    private doConnect;
+    private handleMessage;
+    private matchesSubscriptionMessage;
+    private shouldDispatchSubscriptionMessage;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    private sendRequest;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearTimers;
+}
+
 /**
  * Fetches all live, tradeable markets directly from the Algorand blockchain.
  *
@@ -639,6 +817,7 @@ declare const getLiveMarketsFromApi: (config: AlphaClientConfig) => Promise<Mark
 declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
 
 declare const DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+declare const DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 /**
@@ -720,4 +899,4 @@ declare const getEscrowGlobalState: (indexerClient: algosdk.Indexer, escrowAppId
  */
 declare const checkAssetOptIn: (algodClient: algosdk.Algodv2, address: string, assetId: number) => Promise<boolean>;
 
-export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, type EscrowGlobalState, type Market, type MarketGlobalState, type MarketOption, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletPosition, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, AlphaWebSocket, type AlphaWebSocketConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, DEFAULT_WSS_BASE_URL, type EscrowGlobalState, type FullOrderbookSnapshot, type Market, type MarketChangedEvent, type MarketGlobalState, type MarketOption, type MarketsChangedEvent, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookChangedEvent, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletOrdersChangedEvent, type WalletPosition, type WebSocketStreamEvent, type WsOrderbookAggregatedEntry, type WsOrderbookApp, type WsOrderbookDetailEntry, type WsOrderbookDetailSide, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };

package/dist/index.d.ts

@@ -276,6 +276,11 @@ type AggregatedOrderbook = {
     yes: AggregatedOrderbookSide;
     no: AggregatedOrderbookSide;
 };
+/**
+ * Full processed market orderbook keyed by marketAppId.
+ * Matches the REST `/get-full-orderbook` response and `orderbook_changed.orderbook`.
+ */
+type FullOrderbookSnapshot = Record<string, WsOrderbookApp>;
 /** Parameters for split shares */
 type SplitSharesParams = {
     /** Market app ID */
@@ -362,6 +367,78 @@ type EscrowGlobalState = {
     asset_listed?: number;
     fee_timer_start?: number;
 };
+/** Configuration for AlphaWebSocket */
+type AlphaWebSocketConfig = {
+    /** WebSocket URL override (default: wss://wss.platform.alphaarcade.com) */
+    url?: string;
+    /** Enable auto-reconnect on unexpected disconnect (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnect attempts before giving up (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 60000) */
+    heartbeatIntervalMs?: number;
+    /**
+     * WebSocket constructor to use. Defaults to the global `WebSocket`.
+     * On Node.js < 22, pass the `ws` package: `import WebSocket from 'ws'; new AlphaWebSocket({ WebSocket })`
+     */
+    WebSocket?: unknown;
+};
+/** Orderbook bid/ask entry at the top level (decimal cents) */
+type WsOrderbookAggregatedEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+};
+/** Orderbook bid/ask entry with escrow details (raw microunit prices) */
+type WsOrderbookDetailEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+    escrowAppId: number;
+    owner: string;
+};
+/** Per-side orderbook detail (yes or no) */
+type WsOrderbookDetailSide = {
+    bids: WsOrderbookDetailEntry[];
+    asks: WsOrderbookDetailEntry[];
+};
+/** Orderbook data for a single app within the orderbook payload */
+type WsOrderbookApp = {
+    bids: WsOrderbookAggregatedEntry[];
+    asks: WsOrderbookAggregatedEntry[];
+    spread: number;
+    yes: WsOrderbookDetailSide;
+    no: WsOrderbookDetailSide;
+};
+/** Payload for orderbook_changed events */
+type OrderbookChangedEvent = {
+    type: 'orderbook_changed';
+    ts: number;
+    marketId: string;
+    slug?: string;
+    version: number;
+    orderbook: FullOrderbookSnapshot;
+};
+/** Payload for markets_changed events (incremental diffs) */
+type MarketsChangedEvent = {
+    type: 'markets_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for market_changed events (single market) */
+type MarketChangedEvent = {
+    type: 'market_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for wallet_orders_changed events */
+type WalletOrdersChangedEvent = {
+    type: 'wallet_orders_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Discriminated union of all WebSocket stream events */
+type WebSocketStreamEvent = MarketsChangedEvent | MarketChangedEvent | OrderbookChangedEvent | WalletOrdersChangedEvent;
 
 /**
  * The main client for interacting with Alpha Market prediction markets on Algorand.
@@ -369,7 +446,7 @@ type EscrowGlobalState = {
  * Provides methods for:
  * - **Trading**: Create limit/market orders, cancel orders, propose matches
  * - **Positions**: Split/merge shares, claim resolved tokens, view positions
- * - **Orderbook**: Read on-chain orderbook for any market
+ * - **Orderbook**: Read on-chain orderbooks or fetch full API-backed market snapshots
  * - **Markets**: Fetch live markets from the Alpha API
  *
  * @example
@@ -523,6 +600,17 @@ declare class AlphaClient {
      * @returns Orderbook with yes and no sides, each having bids and asks
      */
     getOrderbook(marketAppId: number): Promise<Orderbook>;
+    /**
+     * Fetches the full processed orderbook snapshot for a market from the Alpha REST API.
+     *
+     * Returns the same shape as websocket `orderbook_changed.orderbook`: a record keyed by
+     * `marketAppId`, where each value includes aggregated bids/asks plus detailed yes/no orders.
+     * Requires `apiKey`.
+     *
+     * @param marketId - The Alpha market UUID
+     * @returns Full processed market orderbook keyed by marketAppId
+     */
+    getFullOrderbookFromApi(marketId: string): Promise<FullOrderbookSnapshot>;
     /**
      * Gets open orders for a specific wallet on a market.
      *
@@ -597,6 +685,96 @@ declare class AlphaClient {
     getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/**
+ * Real-time WebSocket client for Alpha Market platform streams.
+ *
+ * Connects to `wss://wss.platform.alphaarcade.com` and provides typed,
+ * callback-based subscriptions for live market data. No auth required.
+ *
+ * @example
+ * ```typescript
+ * // Node.js 22+ or browser (native WebSocket)
+ * const ws = new AlphaWebSocket();
+ *
+ * // Node.js < 22 — pass the `ws` package
+ * import WebSocket from 'ws';
+ * const ws = new AlphaWebSocket({ WebSocket });
+ *
+ * const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+ *   console.log('Orderbook:', event.orderbook);
+ * });
+ *
+ * // Later
+ * unsub();
+ * ws.close();
+ * ```
+ */
+declare class AlphaWebSocket {
+    private url;
+    private reconnectEnabled;
+    private maxReconnectAttempts;
+    private heartbeatIntervalMs;
+    private WebSocketImpl;
+    private ws;
+    private subscriptions;
+    private pendingRequests;
+    private lastOrderbookVersionBySubscription;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionallyClosed;
+    private connectPromise;
+    constructor(config?: AlphaWebSocketConfig);
+    /** Whether the WebSocket is currently open and connected */
+    get connected(): boolean;
+    /**
+     * Subscribe to live market probability updates (incremental diffs).
+     * @returns An unsubscribe function
+     */
+    subscribeLiveMarkets(callback: (event: MarketsChangedEvent) => void): () => void;
+    /**
+     * Subscribe to change events for a single market.
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeMarket(slug: string, callback: (event: MarketChangedEvent) => void): () => void;
+    /**
+     * Subscribe to full orderbook snapshots (~5s interval on changes).
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeOrderbook(slug: string, callback: (event: OrderbookChangedEvent) => void): () => void;
+    /**
+     * Subscribe to wallet order updates.
+     * @param wallet - The wallet address
+     * @returns An unsubscribe function
+     */
+    subscribeWalletOrders(wallet: string, callback: (event: WalletOrdersChangedEvent) => void): () => void;
+    /** Query the server for the list of active subscriptions on this connection */
+    listSubscriptions(): Promise<unknown>;
+    /** Query a server property (e.g. "heartbeat", "limits") */
+    getProperty(property: string): Promise<unknown>;
+    /** Open the WebSocket connection. Called automatically on first subscribe. */
+    connect(): Promise<void>;
+    /** Close the connection and clean up all resources */
+    close(): void;
+    private buildStreamKey;
+    private buildQueryString;
+    private subscribe;
+    private doConnect;
+    private handleMessage;
+    private matchesSubscriptionMessage;
+    private shouldDispatchSubscriptionMessage;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    private sendRequest;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearTimers;
+}
+
 /**
  * Fetches all live, tradeable markets directly from the Algorand blockchain.
  *
@@ -639,6 +817,7 @@ declare const getLiveMarketsFromApi: (config: AlphaClientConfig) => Promise<Mark
 declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
 
 declare const DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+declare const DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 /**
@@ -720,4 +899,4 @@ declare const getEscrowGlobalState: (indexerClient: algosdk.Indexer, escrowAppId
  */
 declare const checkAssetOptIn: (algodClient: algosdk.Algodv2, address: string, assetId: number) => Promise<boolean>;
 
-export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, type EscrowGlobalState, type Market, type MarketGlobalState, type MarketOption, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletPosition, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, AlphaWebSocket, type AlphaWebSocketConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, DEFAULT_WSS_BASE_URL, type EscrowGlobalState, type FullOrderbookSnapshot, type Market, type MarketChangedEvent, type MarketGlobalState, type MarketOption, type MarketsChangedEvent, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookChangedEvent, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletOrdersChangedEvent, type WalletPosition, type WebSocketStreamEvent, type WsOrderbookAggregatedEntry, type WsOrderbookApp, type WsOrderbookDetailEntry, type WsOrderbookDetailSide, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };