@agg-build/sdk 4.31.0 → 4.33.0

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_agg_websocket = require("./agg-websocket-CVZ7laJ4.js");
+const require_agg_websocket = require("./agg-websocket-MYZiMRXn.js");
 const require_candle_builder = require("./candle-builder-BULYdxB4.js");
 //#region ../common/src/enums/venue.ts
 /** Use these constants instead of hardcoding "kalshi" or "polymarket". */
@@ -782,24 +782,6 @@ const isBalanceRefillWithinDailyCap = (minimumRaw, refillAmountRaw, dailyCapRaw,
 	return BigInt(minimumRaw) <= maximum && BigInt(refillAmountRaw) <= maximum;
 };
 //#endregion
-//#region src/retry-after.ts
-/** Convert explicit retry hints to milliseconds without treating arbitrary strings as dates. */
-function parseRetryAfterSeconds(value) {
-	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return void 0;
-	const milliseconds = value * 1e3;
-	return Number.isSafeInteger(milliseconds) ? milliseconds : void 0;
-}
-function parseRetryAfterHeader(value, now = Date.now()) {
-	if (!value) return void 0;
-	const text = value.trim();
-	if (/^\d+$/.test(text)) return parseRetryAfterSeconds(Number(text));
-	if (!/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(text)) return void 0;
-	const timestamp = Date.parse(text);
-	if (!Number.isFinite(timestamp) || new Date(timestamp).toUTCString() !== text) return void 0;
-	const milliseconds = timestamp - now;
-	return Number.isSafeInteger(milliseconds) && milliseconds >= 0 ? milliseconds : void 0;
-}
-//#endregion
 //#region src/errors.ts
 /**
 * Thrown when the server returns `challenge_required` during auth start.
@@ -846,6 +828,163 @@ function isAggApiError(value) {
 	return value instanceof AggApiError;
 }
 //#endregion
+//#region src/venue-event-read-scheduler.ts
+const MAX_TIMER_DELAY_MS = 2147483647;
+const abortError = () => Object.assign(/* @__PURE__ */ new Error("The request was aborted"), { name: "AbortError" });
+/** Instance-local admission for event reads only. Never retries or retains successful data. */
+var VenueEventReadScheduler = class {
+	constructor(concurrency = 4, queueLimit = 128) {
+		this.concurrency = concurrency;
+		this.queueLimit = queueLimit;
+		this.jobs = /* @__PURE__ */ new Map();
+		this.queue = [];
+		this.active = 0;
+		this.cooldownUntil = 0;
+	}
+	read(key, run, signal) {
+		if (signal?.aborted) return Promise.reject(abortError());
+		let job = this.jobs.get(key);
+		if (!job) {
+			this.queue = this.queue.filter((entry) => entry.subscribers > 0);
+			if (this.queue.length >= this.queueLimit) return Promise.reject(new AggApiError("Too many pending event reads", 429, {
+				code: "client_read_queue_full",
+				retryable: true,
+				retryAfterMs: Math.max(1e3, this.cooldownUntil - Date.now())
+			}));
+			let resolve;
+			let reject;
+			job = {
+				key,
+				run,
+				promise: new Promise((res, rej) => {
+					resolve = res;
+					reject = rej;
+				}),
+				resolve,
+				reject,
+				controller: new AbortController(),
+				subscribers: 0
+			};
+			this.jobs.set(key, job);
+			this.queue.push(job);
+		}
+		const entry = job;
+		entry.subscribers += 1;
+		const result = new Promise((resolve, reject) => {
+			let settled = false;
+			const finish = (callback) => {
+				if (settled) return;
+				settled = true;
+				signal?.removeEventListener("abort", onAbort);
+				entry.subscribers -= 1;
+				if (entry.subscribers === 0) {
+					if (this.jobs.get(key) === entry) this.jobs.delete(key);
+					entry.controller.abort();
+					this.pump();
+				}
+				callback();
+			};
+			const onAbort = () => finish(() => reject(abortError()));
+			signal?.addEventListener("abort", onAbort, { once: true });
+			entry.promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+		});
+		this.pump();
+		return result;
+	}
+	reset() {
+		for (const job of this.jobs.values()) {
+			job.controller.abort();
+			job.reject(abortError());
+		}
+		this.jobs.clear();
+		this.queue = [];
+		this.cooldownUntil = 0;
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.timer = void 0;
+	}
+	pump() {
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.timer = void 0;
+		this.queue = this.queue.filter((job) => job.subscribers > 0);
+		if (this.queue.length === 0 || this.active >= this.concurrency) return;
+		const delay = this.cooldownUntil - Date.now();
+		if (delay > 0) {
+			this.timer = setTimeout(() => this.pump(), Math.min(delay, MAX_TIMER_DELAY_MS));
+			return;
+		}
+		while (this.active < this.concurrency && this.queue.length > 0) {
+			const job = this.queue.shift();
+			this.active += 1;
+			this.execute(job);
+		}
+	}
+	async execute(job) {
+		try {
+			job.resolve(await job.run(job.controller.signal));
+		} catch (error) {
+			if (!job.controller.signal.aborted && isAggApiError(error) && error.status === 429) {
+				const hint = error.retryAfterMs;
+				const delay = typeof hint === "number" && Number.isSafeInteger(hint) && hint >= 0 ? hint : 1e3;
+				this.cooldownUntil = Math.max(this.cooldownUntil, Date.now() + delay + 1 + Math.floor(Math.random() * 250));
+			}
+			job.reject(error);
+		} finally {
+			if (this.jobs.get(job.key) === job) this.jobs.delete(job.key);
+			this.active -= 1;
+			this.pump();
+		}
+	}
+};
+//#endregion
+//#region src/execution-poll-wakeup.ts
+/** A coalesced socket hint can interrupt one poll delay or precede it. */
+var ExecutionPollWakeup = class {
+	constructor() {
+		this.pending = false;
+	}
+	notify() {
+		if (this.resume) this.resume();
+		else this.pending = true;
+	}
+	wait(ms) {
+		if (this.pending) {
+			this.pending = false;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			const finish = () => {
+				clearTimeout(timer);
+				this.resume = void 0;
+				resolve();
+			};
+			const timer = setTimeout(finish, ms);
+			this.resume = finish;
+		});
+	}
+	dispose() {
+		this.resume?.();
+		this.pending = false;
+	}
+};
+//#endregion
+//#region src/retry-after.ts
+/** Convert explicit retry hints to milliseconds without treating arbitrary strings as dates. */
+function parseRetryAfterSeconds(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return void 0;
+	const milliseconds = value * 1e3;
+	return Number.isSafeInteger(milliseconds) ? milliseconds : void 0;
+}
+function parseRetryAfterHeader(value, now = Date.now()) {
+	if (!value) return void 0;
+	const text = value.trim();
+	if (/^\d+$/.test(text)) return parseRetryAfterSeconds(Number(text));
+	if (!/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(text)) return void 0;
+	const timestamp = Date.parse(text);
+	if (!Number.isFinite(timestamp) || new Date(timestamp).toUTCString() !== text) return void 0;
+	const milliseconds = timestamp - now;
+	return Number.isSafeInteger(milliseconds) && milliseconds >= 0 ? milliseconds : void 0;
+}
+//#endregion
 //#region src/eip55.ts
 /**
 * EIP-55 address checksumming, self-contained.
@@ -1132,6 +1271,227 @@ function withTimeout(promise, ms) {
 	});
 }
 //#endregion
+//#region src/catalog-feed.ts
+/** Recommended REST/WS overlap: re-read this much before the resume point. */
+const CATALOG_DEFAULT_OVERLAP_MS = 6e4;
+/** Live frames held during a catch-up. Past this the buffer is dropped and the catch-up re-reads. */
+const LIVE_BUFFER_MAX = 1e4;
+const RETRY_BASE_MS = 1e3;
+const RETRY_MAX_MS = 3e4;
+/** Live applies between dedupe-map prunes. */
+const PRUNE_EVERY = 1e3;
+/**
+* `GET /catalog/changes` answers 410 `resync_required` when the position is
+* older than the 24h retention window: re-list with the list endpoints, then
+* resume from the time that re-list started.
+*/
+function isCatalogResyncRequired(err) {
+	return isAggApiError(err) && (err.code === "resync_required" || err.status === 410);
+}
+/** See {@link AggClient.watchCatalog}. */
+function watchCatalog(deps, options) {
+	if (Number.isNaN(toMs(options.since))) throw new Error("watchCatalog: `since` must be a valid date or ISO string");
+	const overlapMs = options.overlapMs ?? 6e4;
+	const filter = {
+		...options.venues?.length ? { venues: options.venues } : {},
+		...options.entities?.length ? { entities: options.entities } : {}
+	};
+	let sinceMs = toMs(options.since);
+	let lastChangedAtMs;
+	let lastChangedAt;
+	/**
+	* Dedupe state per `${entity}:${id}`. Pruned below `lastChangedAt - 2 *
+	* overlap`: catch-ups re-read from `lastChangedAt - overlap` and REST
+	* serves each entity's latest state, so nothing older can come back.
+	*/
+	const held = /* @__PURE__ */ new Map();
+	/** matchedOnly: ids the caller holds, so a leave or delete still reaches them. Not pruned. */
+	const delivered = /* @__PURE__ */ new Set();
+	let appliedSincePrune = 0;
+	let buffering = true;
+	let buffer = [];
+	let bufferOverflowed = false;
+	let running = false;
+	let rerun = false;
+	let resyncRequired = false;
+	let stopped = false;
+	let retryTimer = null;
+	let wakeRetry = null;
+	const abort = new AbortController();
+	let resolveReady;
+	const ready = new Promise((resolve) => {
+		resolveReady = resolve;
+	});
+	const report = (err) => {
+		if (stopped) return;
+		try {
+			options.onError?.(err);
+		} catch {}
+	};
+	const prune = () => {
+		appliedSincePrune = 0;
+		if (lastChangedAtMs === void 0) return;
+		const floor = lastChangedAtMs - 2 * overlapMs;
+		for (const [key, h] of held) if (h.changedAtMs < floor) held.delete(key);
+	};
+	const apply = (change) => {
+		const key = `${change.entity}:${change.id}`;
+		const changedAtMs = toMs(change.changedAt);
+		if (Number.isNaN(changedAtMs)) return;
+		const prev = held.get(key);
+		if (prev && (change.version < prev.version || change.version === prev.version && changedAtMs <= prev.changedAtMs)) return;
+		held.set(key, {
+			version: change.version,
+			changedAtMs
+		});
+		if (lastChangedAtMs === void 0 || changedAtMs > lastChangedAtMs) {
+			lastChangedAtMs = changedAtMs;
+			lastChangedAt = change.changedAt;
+		}
+		if (++appliedSincePrune >= PRUNE_EVERY) prune();
+		if (options.matchedOnly) {
+			if ((change.event ?? change.market)?.matched === true && change.op !== "deleted") delivered.add(key);
+			else if (delivered.has(key)) delivered.delete(key);
+			else return;
+		}
+		const { type: _type, ...item } = change;
+		try {
+			options.onChange(item);
+		} catch (err) {
+			report(err);
+		}
+	};
+	const onLive = (frame) => {
+		if (stopped) return;
+		if (!buffering) {
+			apply(frame);
+			return;
+		}
+		if (buffer.length >= LIVE_BUFFER_MAX) {
+			buffer = [];
+			bufferOverflowed = true;
+			return;
+		}
+		buffer.push(frame);
+	};
+	const readAll = async () => {
+		const from = (lastChangedAtMs ?? sinceMs) - overlapMs;
+		let cursor;
+		for (;;) {
+			const page = await deps.getChanges({
+				...cursor ? { cursor } : { since: new Date(from).toISOString() },
+				...options.pageLimit ? { limit: options.pageLimit } : {},
+				...filter
+			}, abort.signal);
+			if (stopped) return;
+			for (const change of page.data) apply(change);
+			if (!page.hasMore) return;
+			cursor = page.nextCursor;
+		}
+	};
+	const sleep = (ms) => new Promise((resolve) => {
+		wakeRetry = resolve;
+		retryTimer = setTimeout(() => {
+			retryTimer = null;
+			wakeRetry = null;
+			resolve();
+		}, ms);
+	});
+	const catchUp = async () => {
+		running = true;
+		buffering = true;
+		let attempt = 0;
+		try {
+			do {
+				rerun = false;
+				bufferOverflowed = false;
+				try {
+					await readAll();
+				} catch (err) {
+					if (stopped) return;
+					if (isCatalogResyncRequired(err)) {
+						resyncRequired = true;
+						if (options.onResyncRequired) options.onResyncRequired();
+						else report(err);
+						return;
+					}
+					report(err);
+					const step = Math.min(RETRY_BASE_MS * 2 ** attempt++, RETRY_MAX_MS);
+					await sleep(Math.round(step * (.5 + Math.random() * .5)));
+					if (stopped) return;
+					rerun = true;
+					continue;
+				}
+				if (stopped) return;
+				attempt = 0;
+				const drained = buffer;
+				buffer = [];
+				for (const frame of drained) apply(frame);
+				if (bufferOverflowed) rerun = true;
+			} while (rerun && !stopped && !resyncRequired);
+			if (stopped || resyncRequired) return;
+			prune();
+			buffering = false;
+			options.onSynced?.({ lastChangedAt });
+			resolveReady();
+		} finally {
+			running = false;
+		}
+	};
+	const requestCatchUp = () => {
+		if (stopped || resyncRequired) return;
+		if (running) {
+			rerun = true;
+			return;
+		}
+		catchUp().catch(report);
+	};
+	const owned = !options.socket;
+	let socket = null;
+	let unsubscribe = null;
+	try {
+		socket = options.socket ?? deps.createSocket();
+		unsubscribe = socket.subscribeCatalog(filter, onLive, {
+			onSubscribed: requestCatchUp,
+			onInterrupted: requestCatchUp,
+			onError: report
+		});
+		if (owned) socket.connect();
+	} catch (err) {
+		report(err);
+	}
+	return {
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			abort.abort();
+			if (retryTimer) clearTimeout(retryTimer);
+			retryTimer = null;
+			wakeRetry?.();
+			wakeRetry = null;
+			buffer = [];
+			unsubscribe?.();
+			if (owned) socket?.destroy();
+		},
+		get lastChangedAt() {
+			return lastChangedAt;
+		},
+		resync(since) {
+			if (stopped) return;
+			if (Number.isNaN(toMs(since))) throw new Error("resync: `since` must be a valid date or ISO string");
+			sinceMs = toMs(since);
+			lastChangedAtMs = void 0;
+			lastChangedAt = void 0;
+			resyncRequired = false;
+			requestCatchUp();
+		},
+		ready
+	};
+}
+function toMs(value) {
+	return value instanceof Date ? value.getTime() : Date.parse(value);
+}
+//#endregion
 //#region src/client.ts
 const COOKIE_REFRESH_DELIVERY = "cookie-refresh";
 const DEFAULT_MIDPOINT_IDS_PER_REQUEST = 75;
@@ -1222,9 +1582,12 @@ const AUTH_PATHS = /* @__PURE__ */ new Set([
 ]);
 var AggClient = class {
 	constructor(options) {
+		this.venueEventReads = new VenueEventReadScheduler();
+		this.eventReadSession = 0;
 		this.listeners = /* @__PURE__ */ new Set();
 		this.webSocketAuthCleanups = /* @__PURE__ */ new Set();
 		this.tradeSockets = /* @__PURE__ */ new Set();
+		this.signatureWaitListeners = /* @__PURE__ */ new Set();
 		this._authStatus = "unauthenticated";
 		this.authChannel = null;
 		this.pendingRefresh = null;
@@ -1321,6 +1684,7 @@ var AggClient = class {
 			this.authChannel.onmessage = (event) => {
 				const { type } = event.data ?? {};
 				if (type === "logout") {
+					this.invalidateEventReadSession();
 					this.accessToken = void 0;
 					this.accessTokenUserId = void 0;
 					this.refreshTokenValue = void 0;
@@ -1336,6 +1700,7 @@ var AggClient = class {
 	}
 	/** Release resources (BroadcastChannel, etc.). Safe to call multiple times. */
 	destroy() {
+		this.venueEventReads.reset();
 		this.authChannel?.close();
 		this.authChannel = null;
 		for (const cleanup of this.webSocketAuthCleanups) cleanup();
@@ -1348,15 +1713,17 @@ var AggClient = class {
 	* @param init - Fetch init options, plus optional `query` object for URL search params
 	*/
 	async request(path, init, decode) {
+		const requestSession = this.eventReadSession;
 		const response = await this.rawFetch(path, init);
-		if (response.status === 401 && this.accessToken && !AUTH_PATHS.has(path)) try {
+		if (response.status === 401 && this.accessToken && !AUTH_PATHS.has(path) && this.eventReadSession === requestSession) try {
 			await this.refreshWithDedup();
+			if (this.eventReadSession !== requestSession) throw Object.assign(/* @__PURE__ */ new Error("Authentication changed during refresh"), { name: "AbortError" });
 			const retryResponse = await this.rawFetch(path, init);
 			if (!retryResponse.ok) return this.throwResponseError(retryResponse);
 			if (retryResponse.status === 204) return void 0;
 			return decode ? decode(retryResponse) : retryResponse.json();
 		} catch {
-			this.clearAccessToken();
+			if (!init?.signal?.aborted && this.eventReadSession === requestSession) this.clearAccessToken();
 			return this.throwResponseError(response);
 		}
 		if (!response.ok) return this.throwResponseError(response);
@@ -1412,9 +1779,12 @@ var AggClient = class {
 	* only one refresh call is made and the rest wait for it.
 	*/
 	refreshWithDedup() {
-		if (!this.pendingRefresh) this.pendingRefresh = this.refreshAccessToken().finally(() => {
-			this.pendingRefresh = null;
-		});
+		if (!this.pendingRefresh) {
+			const pending = this.refreshAccessToken().finally(() => {
+				if (this.pendingRefresh === pending) this.pendingRefresh = null;
+			});
+			this.pendingRefresh = pending;
+		}
 		return this.pendingRefresh;
 	}
 	buildAuthRequestInit(init, options) {
@@ -1445,7 +1815,10 @@ var AggClient = class {
 	}
 	/** Set the user access token (for future user-tier auth). */
 	setAccessToken(token) {
-		if (this.accessToken !== token) this.accessTokenUserId = void 0;
+		if (this.accessToken !== token) {
+			this.invalidateEventReadSession();
+			this.accessTokenUserId = void 0;
+		}
 		this.accessToken = token;
 		this._authStatus = "authenticated";
 		this.persistSession();
@@ -1453,8 +1826,12 @@ var AggClient = class {
 	}
 	/** Set the current auth session tokens and optionally seed the user profile. */
 	setSession(session) {
+		this.applySession(session);
+	}
+	applySession(session, tokenRenewal = false) {
 		const wasAuthenticated = this.isAuthenticated;
-		this.accessTokenUserId = session.user?.id ?? (this.accessToken === session.accessToken ? this.accessTokenUserId : void 0);
+		if (session.user !== void 0 && this.accessTokenUserId !== void 0 && session.user.id !== this.accessTokenUserId || !tokenRenewal && (this.accessToken !== session.accessToken || session.user && session.user.id !== this.accessTokenUserId)) this.invalidateEventReadSession();
+		this.accessTokenUserId = session.user?.id ?? (tokenRenewal || this.accessToken === session.accessToken ? this.accessTokenUserId : void 0);
 		this.accessToken = session.accessToken;
 		if ("refreshToken" in session) this.refreshTokenValue = session.refreshToken;
 		if (session.user !== void 0) this.currentUser = normalizeSessionUser(session.user, this.currentUser);
@@ -1465,6 +1842,7 @@ var AggClient = class {
 	}
 	/** Clear the user access token, refresh token, and user info. Broadcasts cross-tab logout. */
 	clearAccessToken() {
+		this.invalidateEventReadSession();
 		this.accessToken = void 0;
 		this.accessTokenUserId = void 0;
 		this.refreshTokenValue = void 0;
@@ -1474,6 +1852,11 @@ var AggClient = class {
 		this.notifyListeners();
 		this.broadcastAuth("logout");
 	}
+	invalidateEventReadSession() {
+		this.eventReadSession += 1;
+		this.pendingRefresh = null;
+		this.venueEventReads.reset();
+	}
 	broadcastAuth(type) {
 		try {
 			this.authChannel?.postMessage({ type });
@@ -1637,16 +2020,18 @@ var AggClient = class {
 	}
 	/** Refresh the access token using the stored refresh token. */
 	async refreshAccessToken() {
+		const refreshSession = this.eventReadSession;
 		if (this.authDelivery !== COOKIE_REFRESH_DELIVERY && !this.refreshTokenValue) throw new Error("No refresh token available");
 		const res = await this.request("/auth/token/refresh", this.buildAuthRequestInit({
 			method: "POST",
 			body: JSON.stringify(this.authDelivery === COOKIE_REFRESH_DELIVERY ? {} : { refreshToken: this.refreshTokenValue })
 		}));
-		this.setSession({
+		if (this.eventReadSession !== refreshSession) throw Object.assign(/* @__PURE__ */ new Error("Authentication changed during refresh"), { name: "AbortError" });
+		this.applySession({
 			accessToken: res.accessToken,
 			refreshToken: res.refreshToken,
 			user: res.user
-		});
+		}, true);
 		return res.accessToken;
 	}
 	/** Get the current user's profile. */
@@ -2034,14 +2419,24 @@ var AggClient = class {
 		});
 	}
 	async getVenueEventById(id, options) {
-		return this.request(`/venue-events/${encodeURIComponent(id)}`, {
-			query: {
-				expand: "",
-				...options?.cluster === false ? { cluster: "false" } : {},
-				...options?.minVolume != null && options.minVolume > 0 ? { minVolume: String(options.minVolume) } : {}
-			},
-			signal: options?.signal
-		});
+		const query = {
+			expand: "",
+			...options?.cluster === false ? { cluster: "false" } : {},
+			...options?.minVolume != null && options.minVolume > 0 ? { minVolume: String(options.minVolume) } : {}
+		};
+		const session = this.eventReadSession;
+		const key = JSON.stringify([
+			id,
+			query,
+			session
+		]);
+		return this.venueEventReads.read(key, (signal) => {
+			if (this.eventReadSession !== session) throw Object.assign(/* @__PURE__ */ new Error("Authentication changed before event read"), { name: "AbortError" });
+			return this.request(`/venue-events/${encodeURIComponent(id)}`, {
+				query,
+				signal
+			});
+		}, options?.signal);
 	}
 	/** Get normalized live score state for sports events. Requires appId or admin auth. */
 	async getSportsLive(eventIds, options) {
@@ -2411,27 +2806,77 @@ var AggClient = class {
 		});
 	}
 	/**
+	* Catalog changes (events and markets created, changed or deleted) after
+	* `since`, oldest first, one item per entity with its current state. Page
+	* with `nextCursor` until `hasMore` is false. Positions older than 24h
+	* throw an {@link AggApiError} with status 410 and code `resync_required`
+	* (see `isCatalogResyncRequired`). Most callers want {@link watchCatalog}.
+	*/
+	async getCatalogChanges(params, options) {
+		const query = {};
+		if (params.since !== void 0) query.since = params.since instanceof Date ? params.since.toISOString() : params.since;
+		if (params.cursor) query.cursor = params.cursor;
+		if (params.limit != null) query.limit = String(params.limit);
+		if (params.venues?.length) query.venues = params.venues;
+		if (params.entities?.length) query.entities = params.entities;
+		return this.request("/catalog/changes", {
+			query,
+			signal: options?.signal
+		});
+	}
+	/**
+	* Keep a copy of the catalog in sync from `since`: subscribes to the live
+	* `catalog` channel, catches up over `GET /catalog/changes` (from the last
+	* applied `changedAt` minus `overlapMs`) on every (re)subscribe and stream
+	* interruption, and delivers each entity's newer state once to `onChange`.
+	*
+	* Persist `handle.lastChangedAt` and pass it back as `since` to resume
+	* after a restart. When that is older than 24h, `onResyncRequired` fires:
+	* re-list with the list endpoints, then call `handle.resync(startOfReList)`.
+	*
+	* Without `socket`, opens a dedicated app-level connection (requires
+	* `wsUrl`) that `stop()` closes.
+	*/
+	watchCatalog(options) {
+		return watchCatalog({
+			getChanges: (params, signal) => this.getCatalogChanges(params, { signal }),
+			createSocket: () => new require_agg_websocket.AggWebSocket(this.webSocketOptions(options.webSocketImpl))
+		}, options);
+	}
+	/**
+	* URL and handshake headers for this client's app. Server-side clients with
+	* an API key authenticate the handshake with it (the gateway then skips the
+	* browser Origin check). Never in a browser: browsers cannot set handshake
+	* headers, and keys must not ship there.
+	*/
+	webSocketOptions(webSocketImpl) {
+		if (!this.wsUrl) throw new Error("AggClient WebSockets require wsUrl to be set in client options");
+		const url = new URL(this.wsUrl);
+		if (this._appId) url.searchParams.set("appId", this._appId);
+		const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+		const headers = this.apiKey && !isBrowser ? { "x-app-api-key": this.apiKey } : void 0;
+		return {
+			url: url.toString(),
+			...headers ? { headers } : {},
+			...webSocketImpl ? { webSocketImpl } : {}
+		};
+	}
+	/**
 	* Create an AggWebSocket instance configured with this client's appId and current auth session.
 	* Session changes update this socket until it or the client is destroyed.
 	* Requires `wsUrl` to be set in the client options.
 	*/
 	createWebSocket(callbacks, options) {
 		if (!this.wsUrl) throw new Error("AggClient.createWebSocket() requires wsUrl to be set in client options");
-		const url = new URL(this.wsUrl);
-		if (this._appId) url.searchParams.set("appId", this._appId);
 		const createSocket = this.webSocketFactory ?? ((socketOptions) => new require_agg_websocket.AggWebSocket(socketOptions));
 		const watchdogHeaders = {};
 		if (this._appId) watchdogHeaders["x-app-id"] = this._appId;
 		if (this.apiKey) watchdogHeaders["x-app-api-key"] = this.apiKey;
-		const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
-		const headers = this.apiKey && !isBrowser ? { "x-app-api-key": this.apiKey } : void 0;
 		const socket = createSocket({
-			url: url.toString(),
+			...this.webSocketOptions(options?.webSocketImpl),
 			callbacks,
 			initialToken: this.accessToken,
 			enableLogs: options?.enableLogs ?? false,
-			...headers ? { headers } : {},
-			...options?.webSocketImpl ? { webSocketImpl: options.webSocketImpl } : {},
 			bookWatchdog: options?.bookWatchdog === false ? void 0 : {
 				baseUrl: this.baseUrl,
 				headers: watchdogHeaders,
@@ -2492,7 +2937,9 @@ var AggClient = class {
 				handlers.onAuthenticated?.(message);
 			},
 			onOrderEvent: (message) => {
-				if (canReceiveUserEvent(message.userId)) handlers.onOrderEvent?.(message);
+				if (!canReceiveUserEvent(message.userId)) return;
+				if (message.event === "step_waiting" && message.waitingFor?.topic === "agg.user.signature") for (const listener of this.signatureWaitListeners) listener(message.orderId);
+				handlers.onOrderEvent?.(message);
 			},
 			onOrderEventReceipt: (message) => {
 				if (canReceiveUserEvent()) handlers.onOrderEventReceipt?.(message);
@@ -2545,7 +2992,7 @@ var AggClient = class {
 			userId = nextUserId;
 			if (resetConnection) {
 				const diagnostics = socket.getDiagnostics();
-				const reconnect = connectRequested || socket.connected || !manuallyDisconnected && (diagnostics.orderbookOutcomeIds.length > 0 || diagnostics.tradeOutcomeIds.length > 0 || diagnostics.arbMarketIds.length > 0 || diagnostics.arbFeedSubscribers > 0);
+				const reconnect = connectRequested || socket.connected || !manuallyDisconnected && (diagnostics.orderbookOutcomeIds.length > 0 || diagnostics.tradeOutcomeIds.length > 0 || diagnostics.arbMarketIds.length > 0 || diagnostics.arbFeedSubscribers > 0 || (diagnostics.catalogSubscribers ?? 0) > 0);
 				authenticatedUserId = void 0;
 				awaitingDisconnect = true;
 				this.tradeSocketAuthenticatedUserId = void 0;
@@ -2620,69 +3067,80 @@ var AggClient = class {
 		let ordersFilled = false;
 		const isPostFillFee = (req) => isPostFillFeeRequest(req, ordersFilled);
 		let orderSubmitted = false;
-		for (;;) {
-			pending = pending.filter((p) => !declinedOptional.has(p.stepId) && (orderSubmitted || !isOptionalFeeRequest(p)));
-			if (Date.now() > deadline) throw new Error(`Fill for quote ${quoteId} did not finish within the timeout.`);
-			if (pending.length === 0) {
-				await new Promise((r) => setTimeout(r, nextPollMs));
-				const polled = await this.getExecutionStatus({ quoteId });
-				nextPollMs = Number.isFinite(polled.pollAfterMs) ? Math.min(Math.max(polled.pollAfterMs, MIN_POLL_INTERVAL_MS), MAX_POLL_INTERVAL_MS) : SELF_CUSTODY_POLL_INTERVAL_MS;
-				if (TERMINAL_EXECUTION_STATES.has(polled.overallState)) {
-					if (polled.overallState !== "filled" && polled.overallState !== "partially_filled") throw new Error(`Fill for quote ${quoteId} ended as ${polled.overallState}.`);
-					return {
-						...first,
-						pendingSignatures: []
-					};
+		const wakeup = new ExecutionPollWakeup();
+		const orderIds = new Set(first.orderIds ?? []);
+		const onSignatureWait = (orderId) => {
+			if (orderIds.has(orderId)) wakeup.notify();
+		};
+		this.signatureWaitListeners.add(onSignatureWait);
+		try {
+			for (;;) {
+				pending = pending.filter((p) => !declinedOptional.has(p.stepId) && (orderSubmitted || !isOptionalFeeRequest(p)));
+				if (Date.now() > deadline) throw new Error(`Fill for quote ${quoteId} did not finish within the timeout.`);
+				if (pending.length === 0) {
+					await wakeup.wait(nextPollMs);
+					const polled = await this.getExecutionStatus({ quoteId });
+					nextPollMs = Number.isFinite(polled.pollAfterMs) ? Math.min(Math.max(polled.pollAfterMs, MIN_POLL_INTERVAL_MS), MAX_POLL_INTERVAL_MS) : SELF_CUSTODY_POLL_INTERVAL_MS;
+					if (TERMINAL_EXECUTION_STATES.has(polled.overallState)) {
+						if (polled.overallState !== "filled" && polled.overallState !== "partially_filled") throw new Error(`Fill for quote ${quoteId} ended as ${polled.overallState}.`);
+						return {
+							...first,
+							pendingSignatures: []
+						};
+					}
+					ordersFilled = areOrdersFilled(polled.orders);
+					pending = polled.pendingSignatures ?? [];
+					continue;
 				}
-				ordersFilled = areOrdersFilled(polled.orders);
-				pending = polled.pendingSignatures ?? [];
-				continue;
-			}
-			const key = pending.map((p) => p.stepId).sort().join(",");
-			if (key === lastKey) throw new Error(`Fill for quote ${quoteId} did not advance — still awaiting steps [${key}] after signing them.`);
-			lastKey = key;
-			const signatures = [];
-			const ordered = orderSignatureRound(pending, { orderSubmitted });
-			const userSigners = userSignerAddresses(pending, params.signingAddress);
-			for (const req of ordered) {
-				if (Date.now() > new Date(req.expiresAt).getTime()) {
-					if (req.optional) {
+				const key = pending.map((p) => p.stepId).sort().join(",");
+				if (key === lastKey) throw new Error(`Fill for quote ${quoteId} did not advance — still awaiting steps [${key}] after signing them.`);
+				lastKey = key;
+				const signatures = [];
+				const ordered = orderSignatureRound(pending, { orderSubmitted });
+				const userSigners = userSignerAddresses(pending, params.signingAddress);
+				for (const req of ordered) {
+					if (Date.now() > new Date(req.expiresAt).getTime()) {
+						if (req.optional) {
+							declinedOptional.add(req.stepId);
+							continue;
+						}
+						if (isPostFillFee(req)) return {
+							...first,
+							pendingSignatures: []
+						};
+						throw new Error(`Signature request ${req.stepId} for quote ${quoteId} expired at ${req.expiresAt}; the fill must be re-quoted.`);
+					}
+					let signed;
+					try {
+						signed = await withTimeout(signer(req), signatureTimeoutMs(req, userSigners));
+					} catch (err) {
+						if (isPostFillFee(req)) return {
+							...first,
+							pendingSignatures: []
+						};
+						if (!req.optional) throw err;
 						declinedOptional.add(req.stepId);
 						continue;
 					}
-					if (isPostFillFee(req)) return {
-						...first,
-						pendingSignatures: []
-					};
-					throw new Error(`Signature request ${req.stepId} for quote ${quoteId} expired at ${req.expiresAt}; the fill must be re-quoted.`);
+					signatures.push(typeof signed === "string" ? {
+						stepId: req.stepId,
+						signature: signed
+					} : {
+						stepId: req.stepId,
+						txHash: signed.txHash
+					});
 				}
-				let signed;
-				try {
-					signed = await withTimeout(signer(req), signatureTimeoutMs(req, userSigners));
-				} catch (err) {
-					if (isPostFillFee(req)) return {
-						...first,
-						pendingSignatures: []
-					};
-					if (!req.optional) throw err;
-					declinedOptional.add(req.stepId);
+				if (signatures.length === 0) {
+					pending = [];
 					continue;
 				}
-				signatures.push(typeof signed === "string" ? {
-					stepId: req.stepId,
-					signature: signed
-				} : {
-					stepId: req.stepId,
-					txHash: signed.txHash
-				});
-			}
-			if (signatures.length === 0) {
-				pending = [];
-				continue;
+				const next = await this.submitFillSignatures(quoteId, signatures);
+				if (signatures.some((s) => isOrderSignatureStep(s.stepId))) orderSubmitted = true;
+				pending = next.pendingSignatures ?? [];
 			}
-			const next = await this.submitFillSignatures(quoteId, signatures);
-			if (signatures.some((s) => isOrderSignatureStep(s.stepId))) orderSubmitted = true;
-			pending = next.pendingSignatures ?? [];
+		} finally {
+			this.signatureWaitListeners.delete(onSignatureWait);
+			wakeup.dispose();
 		}
 	}
 	/**
@@ -2766,6 +3224,14 @@ var AggClient = class {
 			body: JSON.stringify(params)
 		});
 	}
+	/** Submit signatures for a parked self-custody withdrawal. Returns whatever is still outstanding. */
+	async submitWithdrawalSignatures(withdrawalId, signatures) {
+		if (!withdrawalId) throw new Error("withdrawalId is required");
+		return this.request(`/execution/withdrawals/${encodeURIComponent(withdrawalId)}/signatures`, {
+			method: "POST",
+			body: JSON.stringify({ signatures })
+		});
+	}
 	/**
 	* Preview a withdrawal — real fee + receive estimate without creating one.
 	* Optional: `withdrawManaged` does NOT require a prior preview, so partners
@@ -3093,6 +3559,7 @@ exports.AccountType = AccountType;
 exports.AggApiError = AggApiError;
 exports.AggClient = AggClient;
 exports.AggWebSocket = require_agg_websocket.AggWebSocket;
+exports.CATALOG_DEFAULT_OVERLAP_MS = CATALOG_DEFAULT_OVERLAP_MS;
 exports.CONFIRMED_MATCH_STATUSES = CONFIRMED_MATCH_STATUSES;
 exports.CandleBuilder = require_candle_builder.CandleBuilder;
 exports.Chain = Chain;
@@ -3138,6 +3605,7 @@ exports.getWalletAddressFromUserProfile = getWalletAddressFromUserProfile;
 exports.hasShape = hasShape;
 exports.isAggApiError = isAggApiError;
 exports.isBalanceRefillWithinDailyCap = isBalanceRefillWithinDailyCap;
+exports.isCatalogResyncRequired = isCatalogResyncRequired;
 exports.isEmail = isEmail;
 exports.isEnum = isEnum;
 exports.isFiniteNonNeg = isFiniteNonNeg;