@limitless-exchange/sdk 1.0.3 → 1.0.4

package/dist/index.d.mts

@@ -167,63 +167,113 @@ interface UserData {
 }
 
 /**
- * Logger interface for SDK integration.
- * Allows users to inject their own logging implementation.
- *
+ * API token, HMAC auth, and partner capability types.
  * @public
  */
-interface ILogger {
-    /**
-     * Log debug information (verbose, development only)
-     */
-    debug(message: string, meta?: Record<string, any>): void;
-    /**
-     * Log informational messages
-     */
-    info(message: string, meta?: Record<string, any>): void;
-    /**
-     * Log warning messages
-     */
-    warn(message: string, meta?: Record<string, any>): void;
-    /**
-     * Log error messages
-     */
-    error(message: string, error?: Error, meta?: Record<string, any>): void;
+/**
+ * HMAC credentials for scoped API-token authentication.
+ * @public
+ */
+interface HMACCredentials {
+    tokenId: string;
+    secret: string;
 }
 /**
- * No-op logger (default) - does nothing.
- * Zero performance overhead when logging is not needed.
- *
- * @internal
+ * Profile reference embedded in API-token responses.
+ * @public
  */
-declare class NoOpLogger implements ILogger {
-    debug(): void;
-    info(): void;
-    warn(): void;
-    error(): void;
+interface ApiTokenProfile {
+    id: number;
+    account: string;
 }
 /**
- * Simple console logger for development.
- * Can be used as a starting point or for debugging.
- *
- * @example
- * ```typescript
- * import { ConsoleLogger } from '@limitless-exchange/sdk';
- *
- * const logger = new ConsoleLogger('debug');
- * const authenticator = new Authenticator(httpClient, signer, logger);
- * ```
- *
+ * Request payload for self-service token derivation.
+ * `label` is token metadata only and does not affect any profile display name.
  * @public
  */
-declare class ConsoleLogger implements ILogger {
-    private level;
-    constructor(level?: 'debug' | 'info' | 'warn' | 'error');
-    private shouldLog;
-    debug(message: string, meta?: Record<string, any>): void;
-    info(message: string, meta?: Record<string, any>): void;
-    warn(message: string, meta?: Record<string, any>): void;
-    error(message: string, error?: Error, meta?: Record<string, any>): void;
+interface DeriveApiTokenInput {
+    label?: string;
+    scopes?: string[];
+}
+/**
+ * One-time token derivation response.
+ * @public
+ */
+interface DeriveApiTokenResponse {
+    apiKey: string;
+    secret: string;
+    tokenId: string;
+    createdAt: string;
+    scopes: string[];
+    profile: ApiTokenProfile;
+}
+/**
+ * Active token list item.
+ * @public
+ */
+interface ApiToken {
+    tokenId: string;
+    label: string | null;
+    scopes: string[];
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/**
+ * Partner self-service capability config.
+ * @public
+ */
+interface PartnerCapabilities {
+    partnerProfileId: number;
+    tokenManagementEnabled: boolean;
+    allowedScopes: string[];
+}
+/**
+ * Update partner capabilities request.
+ * @public
+ */
+interface UpdatePartnerCapabilitiesInput {
+    tokenManagementEnabled: boolean;
+    allowedScopes: string[];
+}
+/**
+ * Scope constants.
+ * @public
+ */
+declare const ScopeTrading = "trading";
+declare const ScopeAccountCreation = "account_creation";
+declare const ScopeDelegatedSigning = "delegated_signing";
+
+/**
+ * Partner-account creation types.
+ * @public
+ */
+/**
+ * Partner-owned profile creation payload.
+ * `displayName` is the public profile name for the created partner account.
+ * If omitted, the backend defaults it to the created or verified account address.
+ * The backend currently enforces a maximum length of 44 characters.
+ * @public
+ */
+interface CreatePartnerAccountInput {
+    displayName?: string;
+    createServerWallet?: boolean;
+}
+/**
+ * EOA verification headers for partner-account creation.
+ * @public
+ */
+interface CreatePartnerAccountEOAHeaders {
+    account: string;
+    signingMessage: string;
+    signature: string;
+}
+/**
+ * Partner-account creation response.
+ * @public
+ */
+interface PartnerAccountResponse {
+    profileId: number;
+    account: string;
 }
 
 /**
@@ -506,8 +556,11 @@ interface CreatedOrder {
     signatureType: number;
     /**
      * Unique salt for order identification
+     *
+     * @remarks
+     * May be returned as a string when value exceeds JavaScript safe integer range.
      */
-    salt: number;
+    salt: number | string;
     /**
      * Maker address
      */
@@ -615,6 +668,121 @@ interface OrderSigningConfig {
     contractAddress: string;
 }
 
+/**
+ * Delegated-order creation parameters.
+ * @public
+ */
+interface CreateDelegatedOrderParams {
+    marketSlug: string;
+    orderType: OrderType;
+    onBehalfOf: number;
+    feeRateBps?: number;
+    args: OrderArgs;
+}
+/**
+ * Order submission payload where signature may be omitted.
+ * @public
+ */
+interface DelegatedOrderSubmission {
+    salt: number;
+    maker: string;
+    signer: string;
+    taker: string;
+    tokenId: string;
+    makerAmount: number;
+    takerAmount: number;
+    expiration: string;
+    nonce: number;
+    feeRateBps: number;
+    side: Side;
+    signatureType: SignatureType;
+    price?: number;
+    signature?: string;
+}
+/**
+ * POST /orders payload for delegated flows.
+ * @public
+ */
+interface CreateDelegatedOrderRequest {
+    order: DelegatedOrderSubmission;
+    orderType: OrderType;
+    marketSlug: string;
+    ownerId: number;
+    onBehalfOf?: number;
+}
+/**
+ * Cancel endpoint response.
+ * @public
+ */
+interface CancelResponse {
+    message: string;
+}
+/**
+ * Re-export of the normal order response for delegated-create helpers.
+ * @public
+ */
+type DelegatedOrderResponse = OrderResponse;
+
+/**
+ * Logger interface for SDK integration.
+ * Allows users to inject their own logging implementation.
+ *
+ * @public
+ */
+interface ILogger {
+    /**
+     * Log debug information (verbose, development only)
+     */
+    debug(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log informational messages
+     */
+    info(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log warning messages
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log error messages
+     */
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+}
+/**
+ * No-op logger (default) - does nothing.
+ * Zero performance overhead when logging is not needed.
+ *
+ * @internal
+ */
+declare class NoOpLogger implements ILogger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+/**
+ * Simple console logger for development.
+ * Can be used as a starting point or for debugging.
+ *
+ * @example
+ * ```typescript
+ * import { ConsoleLogger } from '@limitless-exchange/sdk';
+ *
+ * const logger = new ConsoleLogger('debug');
+ * const authenticator = new Authenticator(httpClient, signer, logger);
+ * ```
+ *
+ * @public
+ */
+declare class ConsoleLogger implements ILogger {
+    private level;
+    constructor(level?: 'debug' | 'info' | 'warn' | 'error');
+    private shouldLog;
+    debug(message: string, meta?: Record<string, any>): void;
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+}
+
 /**
  * Portfolio and position types for Limitless Exchange.
  * @module types/portfolio
@@ -1582,6 +1750,13 @@ interface WebSocketConfig {
      * and the LIMITLESS_API_KEY environment variable.
      */
     apiKey?: string;
+    /**
+     * HMAC credentials for authenticated subscriptions.
+     *
+     * @remarks
+     * When configured alongside `apiKey`, this client uses HMAC headers for authenticated subscriptions.
+     */
+    hmacCredentials?: HMACCredentials;
     /**
      * Auto-reconnect on connection loss (default: true)
      */
@@ -1769,6 +1944,42 @@ interface TransactionEvent {
     /** Trade side (optional) */
     side?: 'BUY' | 'SELL';
 }
+/**
+ * Market-created websocket event payload.
+ *
+ * @public
+ */
+interface MarketCreatedEvent {
+    /** Market slug identifier */
+    slug: string;
+    /** Human-readable market title */
+    title: string;
+    /** Market venue type */
+    type: 'AMM' | 'CLOB';
+    /** Group market slug when this market belongs to a group */
+    groupSlug?: string;
+    /** Category identifiers when provided by the backend */
+    categoryIds?: number[];
+    /** Market creation timestamp */
+    createdAt: Date | number | string;
+}
+/**
+ * Market-resolved websocket event payload.
+ *
+ * @public
+ */
+interface MarketResolvedEvent {
+    /** Market slug identifier */
+    slug: string;
+    /** Market venue type */
+    type: 'AMM' | 'CLOB';
+    /** Winning outcome label */
+    winningOutcome: 'YES' | 'NO';
+    /** Winning outcome index */
+    winningIndex: 0 | 1;
+    /** Resolution timestamp */
+    resolutionDate: Date | number | string;
+}
 /**
  * WebSocket event types.
  * @public
@@ -1814,6 +2025,14 @@ interface WebSocketEvents {
      * Market updates
      */
     market: (data: MarketUpdate) => void;
+    /**
+     * Market-created lifecycle events.
+     */
+    marketCreated: (data: MarketCreatedEvent) => void;
+    /**
+     * Market-resolved lifecycle events.
+     */
+    marketResolved: (data: MarketResolvedEvent) => void;
     /**
      * Position updates
      */
@@ -1879,6 +2098,13 @@ interface HttpClientConfig {
      * Required for authenticated endpoints (portfolio, orders, etc.)
      */
     apiKey?: string;
+    /**
+     * HMAC credentials for scoped API-token authentication.
+     *
+     * @remarks
+     * When configured alongside `apiKey`, this client uses HMAC headers for authenticated requests.
+     */
+    hmacCredentials?: HMACCredentials;
     /**
      * Optional logger for debugging
      * @defaultValue NoOpLogger (no logging)
@@ -1967,6 +2193,7 @@ interface HttpRawResponse<T = any> {
 declare class HttpClient {
     private client;
     private apiKey?;
+    private hmacCredentials?;
     private logger;
     /**
      * Creates a new HTTP client instance.
@@ -1995,10 +2222,39 @@ declare class HttpClient {
      * @param apiKey - API key value
      */
     setApiKey(apiKey: string): void;
+    /**
+     * Returns the configured API key, if any.
+     */
+    getApiKey(): string | undefined;
     /**
      * Clears the API key.
      */
     clearApiKey(): void;
+    /**
+     * Sets HMAC credentials for scoped API-token authentication.
+     */
+    setHMACCredentials(credentials: HMACCredentials): void;
+    /**
+     * Clears HMAC credentials.
+     */
+    clearHMACCredentials(): void;
+    /**
+     * Returns a copy of the configured HMAC credentials, if any.
+     */
+    getHMACCredentials(): HMACCredentials | undefined;
+    /**
+     * Returns the logger attached to this HTTP client.
+     */
+    getLogger(): ILogger;
+    /**
+     * Returns true when cookie/header-based auth is configured on the underlying client.
+     * This is primarily used for custom authenticated flows that don't use API keys or HMAC.
+     */
+    private hasConfiguredHeaderAuth;
+    /**
+     * Ensures the client has some authenticated transport configured.
+     */
+    requireAuth(operation: string): void;
     /**
      * Performs a GET request.
      *
@@ -2007,6 +2263,10 @@ declare class HttpClient {
      * @returns Promise resolving to the response data
      */
     get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Performs a GET request with identity-token authentication.
+     */
+    getWithIdentity<T = any>(url: string, identityToken: string, config?: AxiosRequestConfig): Promise<T>;
     /**
      * Performs a GET request and returns raw response metadata.
      *
@@ -2027,6 +2287,18 @@ declare class HttpClient {
      * @returns Promise resolving to the response data
      */
     post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Performs a POST request with identity-token authentication.
+     */
+    postWithIdentity<T = any>(url: string, identityToken: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Performs a POST request with additional per-request headers.
+     */
+    postWithHeaders<T = any>(url: string, data?: any, headers?: Record<string, string>, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Performs a PATCH request.
+     */
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
     /**
      * Performs a DELETE request.
      *
@@ -2039,6 +2311,9 @@ declare class HttpClient {
      * @returns Promise resolving to the response data
      */
     delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    private getRequestPath;
+    private getRequestBodyForSignature;
+    private maskSensitiveHeaders;
 }
 
 /**
@@ -2646,6 +2921,58 @@ declare class RetryableClient {
     [key: string]: any;
 }
 
+/**
+ * Builds the canonical HMAC message used by the API-token auth flow.
+ * @public
+ */
+declare function buildHMACMessage(timestamp: string, method: string, path: string, body: string): string;
+/**
+ * Computes a base64 HMAC-SHA256 request signature from a base64 secret.
+ * @public
+ */
+declare function computeHMACSignature(secret: string, timestamp: string, method: string, path: string, body: string): string;
+
+/**
+ * Partner self-service API-token operations.
+ * @public
+ */
+declare class ApiTokenService {
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger?: ILogger);
+    deriveToken(identityToken: string, input: DeriveApiTokenInput): Promise<DeriveApiTokenResponse>;
+    listTokens(): Promise<ApiToken[]>;
+    getCapabilities(identityToken: string): Promise<PartnerCapabilities>;
+    revokeToken(tokenId: string): Promise<string>;
+}
+
+/**
+ * Partner-owned profile creation API.
+ * @public
+ */
+declare class PartnerAccountService {
+    private static readonly DISPLAY_NAME_MAX_LENGTH;
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger?: ILogger);
+    createAccount(input: CreatePartnerAccountInput, eoaHeaders?: CreatePartnerAccountEOAHeaders): Promise<PartnerAccountResponse>;
+}
+
+/**
+ * Delegated partner-order operations.
+ * @public
+ */
+declare class DelegatedOrderService {
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger?: ILogger);
+    createOrder(params: CreateDelegatedOrderParams): Promise<DelegatedOrderResponse>;
+    cancel(orderId: string): Promise<string>;
+    cancelOnBehalfOf(orderId: string, onBehalfOf: number): Promise<string>;
+    cancelAll(marketSlug: string): Promise<string>;
+    cancelAllOnBehalfOf(marketSlug: string, onBehalfOf: number): Promise<string>;
+}
+
 /**
  * Default API endpoints and configuration constants.
  * @public
@@ -2719,6 +3046,20 @@ declare const CONTRACT_ADDRESSES: {
  */
 declare function getContractAddress(contractType: 'USDC' | 'CTF', chainId?: number): string;
 
+/**
+ * Numeric parsing helpers for API payloads that may return numbers as strings.
+ */
+/**
+ * Converts number-like values to finite numbers.
+ * Returns undefined when value is not numeric.
+ */
+declare function toFiniteNumber(value: unknown): number | undefined;
+/**
+ * Converts number-like values to finite integers.
+ * Returns undefined when value is not a safe integer.
+ */
+declare function toFiniteInteger(value: unknown): number | undefined;
+
 /**
  * Order builder for constructing unsigned order payloads.
  * @module orders/builder
@@ -3689,6 +4030,17 @@ declare class WebSocketClient {
      * If already connected, this will trigger a reconnection with the new API key.
      */
     setApiKey(apiKey: string): void;
+    /**
+     * Sets HMAC credentials for authenticated subscriptions.
+     *
+     * @remarks
+     * When configured alongside `apiKey`, this client uses HMAC headers for authenticated subscriptions.
+     */
+    setHMACCredentials(hmacCredentials: NonNullable<WebSocketConfig['hmacCredentials']>): void;
+    /**
+     * Clears HMAC credentials.
+     */
+    clearHMACCredentials(): void;
     /**
      * Reconnects with new authentication credentials.
      * @internal
@@ -3821,4 +4173,35 @@ declare class WebSocketClient {
     private getChannelFromKey;
 }
 
-export { type AMMPosition, APIError, type ActiveMarketsParams, type ActiveMarketsResponse, type ActiveMarketsSortBy, type AmmPriceEntry, AuthenticationError, BASE_SEPOLIA_CHAIN_ID, type BaseOrderArgs, type BreadcrumbItem, type CLOBPosition, CONTRACT_ADDRESSES, type CollateralToken, ConsoleLogger, type CreatedOrder, type CursorPagination, DEFAULT_API_URL, DEFAULT_CHAIN_ID, DEFAULT_WS_URL, type FOKOrderArgs, type FillEvent, type FilterGroup, type FilterGroupOption, type GTCOrderArgs, type HistoryEntry, type HistoryResponse, HttpClient, type HttpClientConfig, type HttpRawResponse, type ILogger, type LatestTrade, Market, type MarketCreator, MarketFetcher, type Market$1 as MarketInterface, type MarketMetadata, type MarketOutcome, type MarketPage, MarketPageFetcher, type MarketPageFilterPrimitive, type MarketPageFilterValue, type MarketPageMarketsCursorResponse, type MarketPageMarketsOffsetResponse, type MarketPageMarketsParams, type MarketPageMarketsResponse, type MarketPageSort, type MarketPageSortField, type MarketSettings, type MarketTokens, type MarketUpdate, type MarketsResponse, type ModeInfo, type NavigationNode, type NewOrderPayload, type NewPriceData, NoOpLogger, type OffsetPagination, type OrderArgs, type OrderBook, OrderBuilder, OrderClient, type OrderClientConfig, type OrderMatch, type OrderResponse, OrderSigner, type OrderSigningConfig, OrderType, type OrderUpdate, OrderValidationError, type OrderbookData, type OrderbookEntry, type OrderbookUpdate, PortfolioFetcher, type PortfolioPositionsResponse, type PortfolioSummary, type Position, type PositionMarket, type PositionSide, type PriceOracleMetadata, type PriceUpdate, type PropertyKey, type PropertyOption, RateLimitError, type ReferralData, RetryConfig, type RetryConfigOptions, RetryableClient, SIGNING_MESSAGE_TEMPLATE, Side, SignatureType, type SignedOrder, type SubscriptionChannel, type SubscriptionOptions, type TokenBalance, type TradeEvent, type TradePrices, type TradingMode, type TransactionEvent, type UnsignedOrder, type UserData, type UserProfile, type UserRank, ValidationError, type Venue, WebSocketClient, type WebSocketConfig, type WebSocketEvents, WebSocketState, ZERO_ADDRESS, getContractAddress, retryOnErrors, validateOrderArgs, validateSignedOrder, validateUnsignedOrder, withRetry };
+/**
+ * Root OOP entrypoint for the SDK.
+ *
+ * @remarks
+ * This mirrors the Go SDK shape: one shared transport plus composed domain services.
+ *
+ * @public
+ */
+declare class Client {
+    http: HttpClient;
+    markets: MarketFetcher;
+    portfolio: PortfolioFetcher;
+    pages: MarketPageFetcher;
+    apiTokens: ApiTokenService;
+    partnerAccounts: PartnerAccountService;
+    delegatedOrders: DelegatedOrderService;
+    constructor(config?: HttpClientConfig);
+    /**
+     * Creates a root client around an existing shared HTTP client.
+     */
+    static fromHttpClient(httpClient: HttpClient): Client;
+    /**
+     * Creates a regular EIP-712 order client reusing the shared transport and market cache.
+     */
+    newOrderClient(walletOrPrivateKey: ethers.Wallet | string, config?: Omit<OrderClientConfig, 'httpClient' | 'wallet'>): OrderClient;
+    /**
+     * Creates a WebSocket client reusing shared auth where possible.
+     */
+    newWebSocketClient(config?: WebSocketConfig): WebSocketClient;
+}
+
+export { type AMMPosition, APIError, type ActiveMarketsParams, type ActiveMarketsResponse, type ActiveMarketsSortBy, type AmmPriceEntry, type ApiToken, type ApiTokenProfile, ApiTokenService, AuthenticationError, BASE_SEPOLIA_CHAIN_ID, type BaseOrderArgs, type BreadcrumbItem, type CLOBPosition, CONTRACT_ADDRESSES, type CancelResponse, Client, type CollateralToken, ConsoleLogger, type CreateDelegatedOrderParams, type CreateDelegatedOrderRequest, type CreatePartnerAccountEOAHeaders, type CreatePartnerAccountInput, type CreatedOrder, type CursorPagination, DEFAULT_API_URL, DEFAULT_CHAIN_ID, DEFAULT_WS_URL, type DelegatedOrderResponse, DelegatedOrderService, type DelegatedOrderSubmission, type DeriveApiTokenInput, type DeriveApiTokenResponse, type FOKOrderArgs, type FillEvent, type FilterGroup, type FilterGroupOption, type GTCOrderArgs, type HMACCredentials, type HistoryEntry, type HistoryResponse, HttpClient, type HttpClientConfig, type HttpRawResponse, type ILogger, type LatestTrade, Market, type MarketCreatedEvent, type MarketCreator, MarketFetcher, type Market$1 as MarketInterface, type MarketMetadata, type MarketOutcome, type MarketPage, MarketPageFetcher, type MarketPageFilterPrimitive, type MarketPageFilterValue, type MarketPageMarketsCursorResponse, type MarketPageMarketsOffsetResponse, type MarketPageMarketsParams, type MarketPageMarketsResponse, type MarketPageSort, type MarketPageSortField, type MarketResolvedEvent, type MarketSettings, type MarketTokens, type MarketUpdate, type MarketsResponse, type ModeInfo, type NavigationNode, type NewOrderPayload, type NewPriceData, NoOpLogger, type OffsetPagination, type OrderArgs, type OrderBook, OrderBuilder, OrderClient, type OrderClientConfig, type OrderMatch, type OrderResponse, OrderSigner, type OrderSigningConfig, OrderType, type OrderUpdate, OrderValidationError, type OrderbookData, type OrderbookEntry, type OrderbookUpdate, type PartnerAccountResponse, PartnerAccountService, type PartnerCapabilities, PortfolioFetcher, type PortfolioPositionsResponse, type PortfolioSummary, type Position, type PositionMarket, type PositionSide, type PriceOracleMetadata, type PriceUpdate, type PropertyKey, type PropertyOption, RateLimitError, type ReferralData, RetryConfig, type RetryConfigOptions, RetryableClient, SIGNING_MESSAGE_TEMPLATE, ScopeAccountCreation, ScopeDelegatedSigning, ScopeTrading, Side, SignatureType, type SignedOrder, type SubscriptionChannel, type SubscriptionOptions, type TokenBalance, type TradeEvent, type TradePrices, type TradingMode, type TransactionEvent, type UnsignedOrder, type UpdatePartnerCapabilitiesInput, type UserData, type UserProfile, type UserRank, ValidationError, type Venue, WebSocketClient, type WebSocketConfig, type WebSocketEvents, WebSocketState, ZERO_ADDRESS, buildHMACMessage, computeHMACSignature, getContractAddress, retryOnErrors, toFiniteInteger, toFiniteNumber, validateOrderArgs, validateSignedOrder, validateUnsignedOrder, withRetry };