@usherlabs/cex-broker 0.2.37 → 0.2.40

package/dist/handlers/subscribe/handler.d.ts

@@ -2,6 +2,7 @@ import * as grpc from "@grpc/grpc-js";
 import { type BrokerPoolEntry } from "../../helpers/broker";
 import type { BrokerExecutionArchiver } from "../../helpers/broker-execution-archive";
 import type { OtelMetrics } from "../../helpers/otel";
+import type { UserDataStreamSupervisor } from "../../helpers/user-data-stream-supervisor";
 import type { SubscribeRequest, SubscribeResponse } from "../types";
 import { SubscribeBrokerLifecycle } from "./broker-lifecycle";
 export type SubscribeDeps = {
@@ -10,6 +11,7 @@ export type SubscribeDeps = {
     otelMetrics?: OtelMetrics;
     brokerArchiver?: BrokerExecutionArchiver;
     brokerLifecycle?: SubscribeBrokerLifecycle;
+    userDataStreamSupervisor?: UserDataStreamSupervisor;
 };
 type SubscribeCall = grpc.ServerWritableStream<SubscribeRequest, SubscribeResponse>;
 export declare function createSubscribeHandler(deps: SubscribeDeps): (call: SubscribeCall) => Promise<void>;

package/dist/helpers/binance-user-data-normalization.d.ts

@@ -0,0 +1,3 @@
+import type { Exchange } from "@usherlabs/ccxt";
+export declare function normalizeBinanceSpotBalanceEvent(exchange: Exchange, event: Record<string, unknown>): Promise<unknown>;
+export declare function normalizeBinanceExecutionReport(exchange: Exchange, event: Record<string, unknown>): Record<string, unknown>;

package/dist/helpers/binance-user-data-stream.d.ts

@@ -5,6 +5,16 @@ export type BinanceUserDataEvent = {
     subscriptionId: number;
     event: Record<string, unknown>;
 };
+export type BinanceUserDataStreamFailureKind = "auth_failed" | "transport_error" | "remote_closed" | "protocol_error" | "backpressure";
+export type BinanceUserDataStreamObserver = {
+    onConnected?: () => void;
+    onAuthenticated?: () => void;
+    onEvent?: (event: BinanceUserDataEvent) => void;
+    onFailure?: (failure: {
+        kind: BinanceUserDataStreamFailureKind;
+        reason: string;
+    }) => void;
+};
 type WebSocketLike = {
     on(event: "open", listener: () => void): unknown;
     on(event: "message", listener: (data: unknown) => void): unknown;
@@ -16,6 +26,7 @@ type WebSocketLike = {
 type WebSocketFactory = (url: string) => WebSocketLike;
 type BinanceSpotUserDataStreamOptions = {
     maxBufferedEvents?: number;
+    observer?: BinanceUserDataStreamObserver;
 };
 export declare function setBinanceUserDataWebSocketFactoryForTests(factory: WebSocketFactory): () => void;
 export declare function getBinanceSpotWsApiUrl(exchange: Exchange): string;
@@ -25,6 +36,7 @@ export declare class BinanceSpotUserDataStream implements AsyncIterable<BinanceU
     private readonly secretValues;
     private readonly requestId;
     private readonly maxBufferedEvents;
+    private readonly observer?;
     private readonly queue;
     private readonly waiters;
     private closed;

package/dist/helpers/broker-execution-archive/index.d.ts

@@ -1,6 +1,6 @@
 export { archiveOrderExecutionInBackground, archiveSubscribeStreamInBackground, archiveTransferEventInBackground, archiveWithdrawalObservationsInBackground, captureMarketMetadataSnapshot, captureMarketMetadataSnapshotInBackground, } from "./capture";
 export { hashMarketMetadata, redactErrorForArchive, redactSecretLiterals, redactStreamPayload, } from "./redact";
-export { buildAccountBalanceSnapshotRow, buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, extractBinanceInternalTransferId, type FillArchiveFields, type NormalizedCcxtBalance, type NormalizedCcxtTransfer, normalizeCcxtBalanceForArchive, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, type TransferArchiveFields, } from "./rows";
+export { buildAccountBalanceSnapshotRow, buildCommonArchiveTags, buildFillEventArchiveRow, buildMarketMetadataSnapshotRow, buildOrderEventArchiveRow, buildSubscribeStreamArchiveRow, buildTransferEventArchiveRow, extractBinanceInternalTransferId, type FillArchiveFields, type NormalizedCcxtBalance, type NormalizedCcxtTransfer, normalizeCcxtBalanceForArchive, normalizeCcxtTradeForArchive, normalizeCcxtTransactionForArchive, normalizeTimestamp, type TransferArchiveFields, } from "./rows";
 export { ACCOUNT_BALANCE_PRECISION_BASIS, ACCOUNT_BALANCE_SCOPE, ARCHIVE_SCHEMA_VERSION, BROKER_READ_SOURCE, BROKER_WRITE_SOURCE, type BrokerArchiveCommonTags, type BrokerArchiveRow, type BrokerArchiveSource, type BrokerArchiveTable, type OrderArchiveAction, type SubscribeArchiveType, type TransferEventKind, type TransferLifecycleAction, } from "./types";
 export { DEFAULT_WITHDRAWAL_OBSERVATION_TRACKER_MAX_ENTRIES, WithdrawalObservationTracker, } from "./withdrawal-observation-tracker";
 export { BrokerExecutionArchiveDurabilityError, BrokerExecutionArchiver, type BrokerExecutionArchiverOptions, createBrokerExecutionArchiverFromEnv, isArchiveOtelLogsEnabled, isBrokerExecutionArchiveTable, resolveArchiveForwarderUrlFromEnv, rethrowArchiveDurabilityError, } from "./writer";

package/dist/helpers/broker-execution-archive/rows.d.ts

@@ -12,6 +12,7 @@ export type NormalizedCcxtBalance = {
     usedMapPresent: boolean;
     totalMapPresent: boolean;
 };
+export declare function normalizeTimestamp(value: unknown): string | undefined;
 export declare function normalizeCcxtBalanceForArchive(balance: unknown): NormalizedCcxtBalance;
 export declare function buildAccountBalanceSnapshotRow(input: {
     tags: BrokerArchiveCommonTags;

package/dist/helpers/deposit-archive-poller.d.ts

@@ -3,6 +3,7 @@ import { type BrokerExecutionArchiver } from "./broker-execution-archive";
 import type { OtelMetrics } from "./otel";
 export type DepositArchivePollerConfig = {
     pollIntervalMs: number;
+    fetchTimeoutMs: number;
     lookbackMs: number;
     depositsLimit: number;
 };

package/dist/helpers/market-data-archive/capture-context.d.ts

@@ -16,10 +16,31 @@ export declare function createMarketCaptureContext(input: {
     accountSelector?: string;
     environment?: CaptureEnvironment;
 }): MarketCaptureContext;
-export declare function validateProductionCollectorArchive(input: {
-    source: BrokerArchiveSource;
+export type MarketCaptureArchiveDisabledReason = "archive_disabled" | "market_archive_disabled" | "invalid_capture_environment" | "missing_deployment_id" | "missing_capture_bundle_id";
+export type MarketCaptureArchiveState = {
+    enabled: true;
+} | {
+    enabled: false;
+    reason: MarketCaptureArchiveDisabledReason;
+};
+export declare function resolveMarketCaptureArchiveState(input: {
+    archiveEnabled: boolean;
+    marketArchiveEnabled: boolean;
+    environment?: string;
+    deploymentId?: string;
     captureBundleId?: string;
-}): void;
+}): MarketCaptureArchiveState;
+/**
+ * Throws when archival was requested but its capture identity is incomplete.
+ *
+ * `archive_disabled` and `market_archive_disabled` are deliberate opt-outs and
+ * must keep the broker available — that is the whole point of resolving to a
+ * typed state instead of throwing. Every other disabled reason means archival
+ * was asked for and cannot be honoured, which is a misconfiguration: a broker
+ * started in that state serves RPC and passes health while writing no
+ * market-data row at all, and the only trace is one line at boot.
+ */
+export declare function assertMarketCaptureArchiveStartable(state: MarketCaptureArchiveState): void;
 export declare function validateExternalFallbackContext(input: {
     configuredExchange: string;
     configuredSymbol: string;

package/dist/helpers/market-data-archive/index.d.ts

@@ -1,6 +1,6 @@
 export { buildCanonicalOrderBookRows, OrderBookValidationError, } from "./canonical-orderbook";
 export { archiveCexStreamEventInBackground, archiveOhlcvInBackground, archiveOrderbookInBackground, archiveOrderbookSnapshotInBackground, archiveOrderbookTobInBackground, archiveTickerInBackground, archiveTradesInBackground, createOhlcvBarTracker, createOrderbookSampler, createOrderbookTobSampler, } from "./capture";
-export { captureEnvironmentFromEnv, createMarketCaptureContext, validateExternalFallbackContext, validateProductionCollectorArchive, } from "./capture-context";
+export { assertMarketCaptureArchiveStartable, captureEnvironmentFromEnv, createMarketCaptureContext, type MarketCaptureArchiveDisabledReason, type MarketCaptureArchiveState, resolveMarketCaptureArchiveState, validateExternalFallbackContext, } from "./capture-context";
 export { ARCHIVE_SOURCES, CAPTURE_FEEDS, CHECKSUM_ALGORITHM, CONSTRUCTION_MODES, canonicalDecimal, canonicalSerialize, createRawCapture, GAP_POLICIES, MARKET_CAPTURE_SCHEMA_VERSION, RAW_CAPTURE_SCOPES, SOURCE_MODES, sha256Canonical, } from "./capture-contract";
 export { buildLegacyOhlcvMigrationRow, buildLegacyOrderBookMigrationRows, type LegacyCandle, type LegacyOrderBookSnapshot, } from "./legacy-migration";
 export { extractLatestOhlcvBar, extractOhlcvBars, OhlcvBarTracker, parseOhlcvBar, } from "./ohlcv-bar-tracker";

package/dist/helpers/stream-health-publisher.d.ts

@@ -0,0 +1,41 @@
+export type StreamHealthState = "connecting" | "connected" | "disconnected" | "error";
+export type StreamHealthFailureKind = "none" | "auth_failed" | "transport_error" | "remote_closed" | "protocol_error" | "backpressure" | "unsupported_connector" | "shutdown";
+export type StreamHealthSnapshot = {
+    exchange: string;
+    accountSelector: string;
+    accountRole?: string;
+    streamKind: "user_data";
+    accountScope: "spot";
+    registryStatus: "active" | "retired";
+    retiredAt: string | null;
+    state: StreamHealthState;
+    stateChangedAt: string;
+    lastConnectedAt: string | null;
+    lastAuthenticatedAt: string | null;
+    lastReceivedAt: string | null;
+    connectAttemptCount: string;
+    reconnectCount: string;
+    errorCount: string;
+    lastFailureKind: StreamHealthFailureKind;
+    lastFailureReason: string;
+    trafficMode: "event_driven" | "continuous" | "unknown";
+    sourceWatermark: string | null;
+};
+export type StreamHealthPublisherOptions = {
+    deploymentId: string;
+    statePath: string;
+    forwarderUrl: string;
+    forwarderAuthToken?: string;
+    heartbeatIntervalMs?: number;
+    forwarderTimeoutMs?: number;
+    post?: (body: string) => Promise<void>;
+};
+/** A whole health batch is persisted before POST so retries are exact replays. */
+export declare class StreamHealthPublisher {
+    #private;
+    constructor(options: StreamHealthPublisherOptions);
+    start(): void;
+    publish(snapshots: readonly StreamHealthSnapshot[]): void;
+    close(snapshots: readonly StreamHealthSnapshot[], timeoutMs?: number): Promise<void>;
+}
+export declare function streamHealthPublisherConfigFromEnv(env?: NodeJS.ProcessEnv): StreamHealthPublisherOptions;

package/dist/helpers/user-data-stream-supervisor.d.ts

@@ -0,0 +1,27 @@
+import { type BinanceUserDataEvent } from "./binance-user-data-stream";
+import type { BrokerPoolEntry } from "./broker";
+import type { StreamHealthPublisher } from "./stream-health-publisher";
+export type UserDataSubscriptionKind = "balance" | "orders";
+export type UserDataSubscription = AsyncIterable<BinanceUserDataEvent> & {
+    close(): void;
+};
+export type UserDataStreamSupervisorOptions = {
+    brokers: Record<string, BrokerPoolEntry>;
+    publisher: StreamHealthPublisher;
+};
+type UserDataSubscriptionOptions = {
+    exchange: string;
+    accountSelector: string;
+    kind: UserDataSubscriptionKind;
+    marketId?: string;
+};
+/** Owns one physical authenticated venue stream for each configured account. */
+export declare class UserDataStreamSupervisor {
+    #private;
+    private readonly options;
+    constructor(options: UserDataStreamSupervisorOptions);
+    start(): void;
+    subscribe(options: UserDataSubscriptionOptions): UserDataSubscription;
+    close(): Promise<void>;
+}
+export {};

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export default class CEXBroker {
     private fillArchivePoller?;
     private depositArchivePoller?;
     private accountBalanceArchivePoller?;
+    private userDataStreamSupervisor?;
     /**
      * Loads environment variables prefixed with CEX_BROKER_
      * Expected format: