@fullstackcraftllc/floe 0.0.18 → 0.0.19

package/dist/apiclient/index.js

@@ -0,0 +1,721 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = exports.APIError = exports.AMTEventCode = exports.AMTEventCategory = void 0;
+exports.NewApiClient = NewApiClient;
+const DEFAULT_HINDSIGHT_BASE_URL = 'https://hindsightapi.com/api';
+const DEFAULT_DEALER_BASE_URL = 'https://vannacharm.com/api';
+const DEFAULT_AMT_BASE_URL = 'https://amtjoy.com/api';
+const DEFAULT_WHEELSCREENER_BASE_URL = 'https://wheelscreener.com/api';
+const DEFAULT_LEAPSSCREENER_BASE_URL = 'https://leapsscreener.com/api';
+const DEFAULT_OPTIONSCREENER_BASE_URL = 'https://option-screener.com/api';
+const DATE_ONLY_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+// --- AMT Event Categories & Codes ---
+/** Event categories for filtering AMT minute events. */
+exports.AMTEventCategory = {
+    TPO: 'TPO',
+    Price: 'Price',
+    Volume: 'Volume',
+    Session: 'Session',
+    Overnight: 'Overnight',
+};
+/** Typed event codes emitted by the AMT pipeline (66 codes across 5 categories). */
+exports.AMTEventCode = {
+    // --- TPO Events ---
+    TPONewPrint: 'TPO_NEW_PRINT',
+    TPOPeriodFirstPrint: 'TPO_PERIOD_FIRST_PRINT',
+    TPOFirst3Wide: 'TPO_FIRST_3WIDE',
+    TPOFirst4Wide: 'TPO_FIRST_4WIDE',
+    TPOFirst5Wide: 'TPO_FIRST_5WIDE',
+    TPOSinglePrintCreated: 'TPO_SINGLE_PRINT_CREATED',
+    TPOSinglePrintFilled: 'TPO_SINGLE_PRINT_FILLED',
+    TPOPoorHigh: 'TPO_POOR_HIGH',
+    TPOPoorLow: 'TPO_POOR_LOW',
+    TPOExcessHigh: 'TPO_EXCESS_HIGH',
+    TPOExcessLow: 'TPO_EXCESS_LOW',
+    // --- Price Cross Events ---
+    PriceNHOD: 'PRICE_NHOD',
+    PriceNLOD: 'PRICE_NLOD',
+    PriceCrossHBUp: 'PRICE_CROSS_HB_UP',
+    PriceCrossHBDown: 'PRICE_CROSS_HB_DOWN',
+    PriceCrossTPOCUp: 'PRICE_CROSS_TPOC_UP',
+    PriceCrossTPOCDown: 'PRICE_CROSS_TPOC_DOWN',
+    PriceCrossVPOCUp: 'PRICE_CROSS_VPOC_UP',
+    PriceCrossVPOCDown: 'PRICE_CROSS_VPOC_DOWN',
+    PriceCrossVAHUp: 'PRICE_CROSS_VAH_UP',
+    PriceCrossVAHDown: 'PRICE_CROSS_VAH_DOWN',
+    PriceCrossVALUp: 'PRICE_CROSS_VAL_UP',
+    PriceCrossVALDown: 'PRICE_CROSS_VAL_DOWN',
+    PriceCrossORHighUp: 'PRICE_CROSS_OR_HIGH_UP',
+    PriceCrossORHighDown: 'PRICE_CROSS_OR_HIGH_DOWN',
+    PriceCrossORLowUp: 'PRICE_CROSS_OR_LOW_UP',
+    PriceCrossORLowDown: 'PRICE_CROSS_OR_LOW_DOWN',
+    PriceCrossIBHighUp: 'PRICE_CROSS_IB_HIGH_UP',
+    PriceCrossIBHighDown: 'PRICE_CROSS_IB_HIGH_DOWN',
+    PriceCrossIBLowUp: 'PRICE_CROSS_IB_LOW_UP',
+    PriceCrossIBLowDown: 'PRICE_CROSS_IB_LOW_DOWN',
+    PriceCrossPHODUp: 'PRICE_CROSS_PHOD_UP',
+    PriceCrossPHODDown: 'PRICE_CROSS_PHOD_DOWN',
+    PriceCrossPLODUp: 'PRICE_CROSS_PLOD_UP',
+    PriceCrossPLODDown: 'PRICE_CROSS_PLOD_DOWN',
+    PriceCrossPrevCloseUp: 'PRICE_CROSS_PREV_CLOSE_UP',
+    PriceCrossPrevCloseDown: 'PRICE_CROSS_PREV_CLOSE_DOWN',
+    PriceCrossPrevOpenUp: 'PRICE_CROSS_PREV_OPEN_UP',
+    PriceCrossPrevOpenDown: 'PRICE_CROSS_PREV_OPEN_DOWN',
+    PriceCrossONHUp: 'PRICE_CROSS_ONH_UP',
+    PriceCrossONHDown: 'PRICE_CROSS_ONH_DOWN',
+    PriceCrossONLUp: 'PRICE_CROSS_ONL_UP',
+    PriceCrossONLDown: 'PRICE_CROSS_ONL_DOWN',
+    PriceCrossVWAPUp: 'PRICE_CROSS_VWAP_UP',
+    PriceCrossVWAPDown: 'PRICE_CROSS_VWAP_DOWN',
+    PriceCrossVWAPSD1Up: 'PRICE_CROSS_VWAP_SD1_UP',
+    PriceCrossVWAPSD1Down: 'PRICE_CROSS_VWAP_SD1_DOWN',
+    PriceCrossVWAPSD2Up: 'PRICE_CROSS_VWAP_SD2_UP',
+    PriceCrossVWAPSD2Down: 'PRICE_CROSS_VWAP_SD2_DOWN',
+    // --- Volume Profile Events ---
+    VolVPOCShiftUp: 'VOL_VPOC_SHIFT_UP',
+    VolVPOCShiftDown: 'VOL_VPOC_SHIFT_DOWN',
+    VolVAMigrationUp: 'VOL_VA_MIGRATION_UP',
+    VolVAMigrationDown: 'VOL_VA_MIGRATION_DOWN',
+    VolVAExpanding: 'VOL_VA_EXPANDING',
+    VolVAContracting: 'VOL_VA_CONTRACTING',
+    // --- Session Structure Events ---
+    SessionPeriodTransition: 'SESSION_PERIOD_TRANSITION',
+    SessionOREstablished: 'SESSION_OR_ESTABLISHED',
+    SessionIBEstablished: 'SESSION_IB_ESTABLISHED',
+    SessionIBExtensionUp: 'SESSION_IB_EXTENSION_UP',
+    SessionIBExtensionDown: 'SESSION_IB_EXTENSION_DOWN',
+    SessionORExtensionUp: 'SESSION_OR_EXTENSION_UP',
+    SessionORExtensionDown: 'SESSION_OR_EXTENSION_DOWN',
+    SessionGapFill: 'SESSION_GAP_FILL',
+    SessionGlobexGapFill: 'SESSION_GLOBEX_GAP_FILL',
+    SessionHalfbackReached: 'SESSION_HALFBACK_REACHED',
+    // --- Overnight Events (futures only) ---
+    ONAsiaOpen: 'ON_ASIA_OPEN',
+    ONAsiaClose: 'ON_ASIA_CLOSE',
+    ONEUOpen: 'ON_EU_OPEN',
+    ONEUClose: 'ON_EU_CLOSE',
+    ONNewHigh: 'ON_NEW_HIGH',
+    ONNewLow: 'ON_NEW_LOW',
+};
+const STATUS_TEXT = {
+    200: 'OK',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    408: 'Request Timeout',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+};
+class APIError extends Error {
+    constructor(params) {
+        const statusCode = params.StatusCode;
+        const message = params.Message ?? '';
+        const statusText = statusCode > 0 ? `${statusCode} ${statusTextForCode(statusCode)}`.trim() : '';
+        const errorMessage = statusText !== '' && message !== ''
+            ? `api error: ${statusText}: ${message}`
+            : message !== ''
+                ? `api error: ${message}`
+                : statusText !== ''
+                    ? `api error: ${statusText}`
+                    : 'api error';
+        super(errorMessage);
+        this.name = 'APIError';
+        this.StatusCode = statusCode;
+        this.Message = message;
+        this.SubscriptionEnd = params.SubscriptionEnd ?? '';
+        this.RawBody = params.RawBody ?? '';
+    }
+}
+exports.APIError = APIError;
+class ApiClient {
+    constructor(apiKey, httpClient) {
+        this.apiKey = apiKey.trim();
+        const resolvedClient = httpClient ??
+            (typeof globalThis.fetch === 'function'
+                ? ((input, init) => globalThis.fetch(input, init))
+                : undefined);
+        if (typeof resolvedClient !== 'function') {
+            throw new Error('http client is required');
+        }
+        this.httpClient = resolvedClient;
+        this.hindsightBaseURL = DEFAULT_HINDSIGHT_BASE_URL;
+        this.dealerBaseURL = DEFAULT_DEALER_BASE_URL;
+        this.amtBaseURL = DEFAULT_AMT_BASE_URL;
+        this.wheelScreenerBaseURL = DEFAULT_WHEELSCREENER_BASE_URL;
+        this.leapsScreenerBaseURL = DEFAULT_LEAPSSCREENER_BASE_URL;
+        this.optionScreenerBaseURL = DEFAULT_OPTIONSCREENER_BASE_URL;
+    }
+    async GetHindsightData(ctx, req) {
+        validateHindsightDataRequest(req);
+        const query = new URLSearchParams();
+        query.set('start_date', req.start_date.trim());
+        query.set('end_date', req.end_date.trim());
+        if (typeof req.country === 'string' && req.country.trim() !== '') {
+            query.set('country', req.country.trim());
+        }
+        if (typeof req.min_volatility === 'number') {
+            query.set('min_volatility', String(req.min_volatility));
+        }
+        if (typeof req.event === 'string' && req.event.trim() !== '') {
+            query.set('event', req.event.trim());
+        }
+        const body = await this.getRaw(ctx, this.hindsightBaseURL, '/getData', query, true);
+        return decodeHindsightEvents(body);
+    }
+    async GetHindsightSample(ctx) {
+        const body = await this.getRaw(ctx, this.hindsightBaseURL, '/getSample', null, true);
+        return decodeHindsightEvents(body);
+    }
+    async GetDealerMinuteSurfaces(ctx, req) {
+        validateDealerMinuteSurfacesRequest(req);
+        const query = new URLSearchParams();
+        query.set('symbol', req.symbol.trim());
+        query.set('trade_date', req.trade_date.trim());
+        const body = await this.getRaw(ctx, this.dealerBaseURL, '/getMinuteSurfaces', query, true);
+        return decodeDealerMinuteSurfaces(body);
+    }
+    async GetAMTSessionStats(ctx, req) {
+        validateAMTRequest(req);
+        const query = new URLSearchParams();
+        query.set('symbol', req.symbol.trim().toUpperCase());
+        query.set('session_id', req.session_id.trim());
+        const body = await this.getRaw(ctx, this.amtBaseURL, '/getSessionStats', query, true);
+        return decodeAMTSessionStats(body);
+    }
+    async GetAMTEvents(ctx, req) {
+        validateAMTRequest(req);
+        const query = new URLSearchParams();
+        query.set('symbol', req.symbol.trim().toUpperCase());
+        query.set('session_id', req.session_id.trim());
+        const body = await this.getRaw(ctx, this.amtBaseURL, '/getAMTEvents', query, true);
+        return decodeAMTEvents(body);
+    }
+    async GetWheelScreenerData(ctx, req) {
+        return this.getOptionsScreenerData(ctx, this.wheelScreenerBaseURL, '/get-options', req);
+    }
+    async GetLeapsScreenerData(ctx, req) {
+        return this.getOptionsScreenerData(ctx, this.leapsScreenerBaseURL, '/get-options', req);
+    }
+    async GetOptionScreenerData(ctx, req) {
+        return this.getOptionsScreenerData(ctx, this.optionScreenerBaseURL, '/getOptionsData', req);
+    }
+    async getOptionsScreenerData(ctx, baseURL, path, req) {
+        validateOptionsScreenerRequest(req);
+        const query = new URLSearchParams();
+        query.set('strategy', req.strategy.trim().toUpperCase());
+        if (typeof req.search === 'string' && req.search.trim() !== '') {
+            query.set('search', req.search.trim());
+        }
+        if (typeof req.page === 'number' && req.page > 0) {
+            query.set('page', String(req.page));
+        }
+        if (typeof req.page_size === 'number' && req.page_size > 0) {
+            query.set('page_size', String(req.page_size));
+        }
+        if (typeof req.order_by === 'string' && req.order_by.trim() !== '') {
+            query.set('order_by', req.order_by.trim());
+        }
+        if (typeof req.order_direction === 'string' && req.order_direction.trim() !== '') {
+            query.set('order_direction', req.order_direction.trim());
+        }
+        if (req.extra_params !== undefined && req.extra_params !== null) {
+            for (const [key, value] of Object.entries(req.extra_params)) {
+                if (typeof value === 'string' && value.trim() !== '') {
+                    query.set(key, value.trim());
+                }
+            }
+        }
+        const body = await this.getRaw(ctx, baseURL, path, query, true);
+        return decodeOptionsScreenerResponse(body);
+    }
+    async getRaw(ctx, baseURL, path, query, requiresAPIKey) {
+        if (requiresAPIKey && this.apiKey.trim() === '') {
+            throw new Error('api key is required');
+        }
+        const trimmedBaseURL = baseURL.trim();
+        if (trimmedBaseURL === '') {
+            throw new Error('base URL is required');
+        }
+        let endpoint;
+        try {
+            endpoint = new URL(`${trimmedBaseURL.replace(/\/$/, '')}${path}`);
+        }
+        catch (error) {
+            throw new Error(`failed to parse endpoint URL: ${toErrorMessage(error)}`);
+        }
+        if (query !== null) {
+            endpoint.search = query.toString();
+        }
+        const headers = {
+            Accept: 'application/json',
+        };
+        if (requiresAPIKey) {
+            headers['X-API-Key'] = this.apiKey;
+        }
+        const signal = resolveSignal(ctx);
+        let response;
+        try {
+            response = await this.httpClient(endpoint.toString(), {
+                method: 'GET',
+                headers,
+                signal,
+            });
+        }
+        catch (error) {
+            throw new Error(`request failed: ${toErrorMessage(error)}`);
+        }
+        let body;
+        try {
+            body = await response.text();
+        }
+        catch (error) {
+            throw new Error(`failed to read response body: ${toErrorMessage(error)}`);
+        }
+        if (!response.ok) {
+            throw decodeAPIError(response.status, body);
+        }
+        if (body.trim() === '') {
+            throw new Error('empty response body');
+        }
+        return body;
+    }
+}
+exports.ApiClient = ApiClient;
+function NewApiClient(apiKey, httpClient) {
+    return new ApiClient(apiKey, httpClient);
+}
+function validateHindsightDataRequest(req) {
+    const startDate = (req.start_date ?? '').trim();
+    const endDate = (req.end_date ?? '').trim();
+    if (startDate === '') {
+        throw new Error('start_date is required');
+    }
+    if (endDate === '') {
+        throw new Error('end_date is required');
+    }
+    const start = parseDateOnly(startDate);
+    if (start === null) {
+        throw new Error('start_date must be in YYYY-MM-DD format');
+    }
+    const end = parseDateOnly(endDate);
+    if (end === null) {
+        throw new Error('end_date must be in YYYY-MM-DD format');
+    }
+    if (end.getTime() < start.getTime()) {
+        throw new Error('end_date must be on or after start_date');
+    }
+    if (req.min_volatility !== undefined &&
+        req.min_volatility !== null &&
+        (!Number.isInteger(req.min_volatility) || req.min_volatility < 1 || req.min_volatility > 3)) {
+        throw new Error('min_volatility must be between 1 and 3 when provided');
+    }
+}
+function validateDealerMinuteSurfacesRequest(req) {
+    const symbol = (req.symbol ?? '').trim();
+    const tradeDate = (req.trade_date ?? '').trim();
+    if (symbol === '') {
+        throw new Error('symbol is required');
+    }
+    if (tradeDate === '') {
+        throw new Error('trade_date is required');
+    }
+    if (parseDateOnly(tradeDate) === null) {
+        throw new Error('trade_date must be in YYYY-MM-DD format');
+    }
+}
+function validateAMTRequest(req) {
+    const symbol = (req.symbol ?? '').trim();
+    const sessionID = (req.session_id ?? '').trim();
+    if (symbol === '') {
+        throw new Error('symbol is required');
+    }
+    if (sessionID === '') {
+        throw new Error('session_id is required');
+    }
+    if (parseDateOnly(sessionID) === null) {
+        throw new Error('session_id must be in YYYY-MM-DD format');
+    }
+}
+function decodeAPIError(statusCode, body) {
+    const trimmed = body.trim();
+    if (trimmed === '') {
+        return new APIError({
+            StatusCode: statusCode,
+            Message: statusTextForCode(statusCode),
+        });
+    }
+    let message = '';
+    let subscriptionEnd = '';
+    const parsed = parseJSON(body);
+    const obj = asRecord(parsed);
+    if (obj !== null) {
+        message = firstNonEmpty(getStringOrEmpty(obj.error), getStringOrEmpty(obj.message));
+        subscriptionEnd = firstNonEmpty(getStringOrEmpty(obj.subscriptionEnd), getStringOrEmpty(obj.subscription_end));
+    }
+    if (message === '') {
+        message = truncateForError(trimmed);
+    }
+    if (message === '') {
+        message = statusTextForCode(statusCode);
+    }
+    return new APIError({
+        StatusCode: statusCode,
+        Message: message,
+        SubscriptionEnd: subscriptionEnd,
+        RawBody: body,
+    });
+}
+function decodeHindsightEvents(body) {
+    const parsed = parseJSON(body);
+    const envelope = asRecord(parsed);
+    if (envelope !== null) {
+        const hasEnvelope = envelope.success === true ||
+            Array.isArray(envelope.data) ||
+            nonEmptyString(envelope.error) ||
+            nonEmptyString(envelope.message) ||
+            nonEmptyString(envelope.subscriptionEnd) ||
+            nonEmptyString(envelope.subscription_end);
+        if (hasEnvelope) {
+            if (envelope.success !== true) {
+                throw new APIError({
+                    StatusCode: 200,
+                    Message: firstNonEmpty(getStringOrEmpty(envelope.error), getStringOrEmpty(envelope.message), 'request failed'),
+                    SubscriptionEnd: firstNonEmpty(getStringOrEmpty(envelope.subscriptionEnd), getStringOrEmpty(envelope.subscription_end)),
+                    RawBody: body,
+                });
+            }
+            const rows = Array.isArray(envelope.data) ? envelope.data : [];
+            return rows.map(normalizeHindsightEvent);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.map(normalizeHindsightEvent);
+    }
+    throw new Error('failed to decode hindsight response');
+}
+function decodeDealerMinuteSurfaces(body) {
+    const parsed = parseJSON(body);
+    const envelope = asRecord(parsed);
+    if (envelope !== null) {
+        const hasEnvelope = envelope.success === true ||
+            Array.isArray(envelope.data) ||
+            nonEmptyString(envelope.error) ||
+            nonEmptyString(envelope.message) ||
+            nonEmptyString(envelope.subscriptionEnd) ||
+            nonEmptyString(envelope.subscription_end);
+        if (hasEnvelope) {
+            if (envelope.success !== true) {
+                throw new APIError({
+                    StatusCode: 200,
+                    Message: firstNonEmpty(getStringOrEmpty(envelope.error), getStringOrEmpty(envelope.message), 'request failed'),
+                    SubscriptionEnd: firstNonEmpty(getStringOrEmpty(envelope.subscriptionEnd), getStringOrEmpty(envelope.subscription_end)),
+                    RawBody: body,
+                });
+            }
+            const rows = Array.isArray(envelope.data) ? envelope.data : [];
+            return rows.map(normalizeDealerMinuteSurface);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.map(normalizeDealerMinuteSurface);
+    }
+    throw new Error('failed to decode dealer minute surfaces response');
+}
+function decodeAMTSessionStats(body) {
+    const parsed = parseJSON(body);
+    const envelope = asRecord(parsed);
+    if (envelope !== null) {
+        const hasEnvelope = envelope.success === true ||
+            Array.isArray(envelope.data) ||
+            nonEmptyString(envelope.error) ||
+            nonEmptyString(envelope.message) ||
+            nonEmptyString(envelope.subscriptionEnd) ||
+            nonEmptyString(envelope.subscription_end);
+        if (hasEnvelope) {
+            if (envelope.success !== true) {
+                throw new APIError({
+                    StatusCode: 200,
+                    Message: firstNonEmpty(getStringOrEmpty(envelope.error), getStringOrEmpty(envelope.message), 'request failed'),
+                    SubscriptionEnd: firstNonEmpty(getStringOrEmpty(envelope.subscriptionEnd), getStringOrEmpty(envelope.subscription_end)),
+                    RawBody: body,
+                });
+            }
+            const rows = Array.isArray(envelope.data) ? envelope.data : [];
+            return rows.map(normalizeAMTSessionStatsRow);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.map(normalizeAMTSessionStatsRow);
+    }
+    throw new Error('failed to decode amt session stats response');
+}
+function decodeAMTEvents(body) {
+    const parsed = parseJSON(body);
+    const envelope = asRecord(parsed);
+    if (envelope !== null) {
+        const hasEnvelope = envelope.success === true ||
+            Array.isArray(envelope.data) ||
+            nonEmptyString(envelope.error) ||
+            nonEmptyString(envelope.message) ||
+            nonEmptyString(envelope.subscriptionEnd) ||
+            nonEmptyString(envelope.subscription_end);
+        if (hasEnvelope) {
+            if (envelope.success !== true) {
+                throw new APIError({
+                    StatusCode: 200,
+                    Message: firstNonEmpty(getStringOrEmpty(envelope.error), getStringOrEmpty(envelope.message), 'request failed'),
+                    SubscriptionEnd: firstNonEmpty(getStringOrEmpty(envelope.subscriptionEnd), getStringOrEmpty(envelope.subscription_end)),
+                    RawBody: body,
+                });
+            }
+            const rows = Array.isArray(envelope.data) ? envelope.data : [];
+            return rows.map(normalizeAMTEventsRow);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.map(normalizeAMTEventsRow);
+    }
+    throw new Error('failed to decode amt events response');
+}
+function validateOptionsScreenerRequest(req) {
+    const strategy = (req.strategy ?? '').trim();
+    if (strategy === '') {
+        throw new Error('strategy is required');
+    }
+}
+function decodeOptionsScreenerResponse(body) {
+    const parsed = parseJSON(body);
+    const envelope = asRecord(parsed);
+    if (envelope !== null) {
+        const hasEnvelope = envelope.success === true ||
+            Array.isArray(envelope.data) ||
+            nonEmptyString(envelope.error) ||
+            nonEmptyString(envelope.message) ||
+            nonEmptyString(envelope.subscriptionEnd) ||
+            nonEmptyString(envelope.subscription_end);
+        if (hasEnvelope) {
+            if (envelope.success !== true) {
+                throw new APIError({
+                    StatusCode: 200,
+                    Message: firstNonEmpty(getStringOrEmpty(envelope.error), getStringOrEmpty(envelope.message), 'request failed'),
+                    SubscriptionEnd: firstNonEmpty(getStringOrEmpty(envelope.subscriptionEnd), getStringOrEmpty(envelope.subscription_end)),
+                    RawBody: body,
+                });
+            }
+            const rows = Array.isArray(envelope.data) ? envelope.data : [];
+            return {
+                data: rows.map((item) => asRecord(item) ?? {}),
+                total: toInteger(envelope.total),
+                page: toInteger(envelope.page),
+                page_size: toInteger(envelope.page_size),
+            };
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return {
+            data: parsed.map((item) => asRecord(item) ?? {}),
+            total: parsed.length,
+            page: 1,
+            page_size: parsed.length,
+        };
+    }
+    throw new Error('failed to decode options screener response');
+}
+function normalizeHindsightEvent(value) {
+    const row = asRecord(value) ?? {};
+    return {
+        id: toInteger(row.id),
+        event_id: getStringOrEmpty(row.event_id),
+        date: getStringOrEmpty(row.date),
+        time: getStringOrEmpty(row.time),
+        timezone: getStringOrEmpty(row.timezone),
+        country: getStringOrEmpty(row.country),
+        country_code: getStringOrEmpty(row.country_code),
+        event_name: getStringOrEmpty(row.event_name),
+        volatility: toInteger(row.volatility),
+        actual: toNullableString(row.actual),
+        forecast: toNullableString(row.forecast),
+        previous: toNullableString(row.previous),
+        created_at: toDateOrNull(row.created_at),
+        updated_at: toDateOrNull(row.updated_at),
+    };
+}
+function normalizeDealerMinuteSurface(value) {
+    const row = asRecord(value) ?? {};
+    const rawSurfaces = asRecord(row.surfaces) ?? asRecord(row.surfaces_jsonb) ?? {};
+    const rawMetadata = asRecord(row.metadata) ?? asRecord(row.metadata_jsonb) ?? {};
+    return {
+        id: getStringOrEmpty(row.id),
+        run_at: toDateOrNull(row.run_at),
+        symbol: getStringOrEmpty(row.symbol),
+        trade_date: getStringOrEmpty(row.trade_date),
+        minute_ts: toDateOrNull(row.minute_ts),
+        session_minute: toInteger(row.session_minute),
+        spot: toNumber(row.spot),
+        vix: toNumber(row.vix),
+        surfaces: normalizeMinuteSurface(rawSurfaces),
+        metadata: rawMetadata,
+    };
+}
+function normalizeAMTSessionStatsRow(value) {
+    const row = asRecord(value) ?? {};
+    return {
+        symbol: getStringOrEmpty(row.symbol),
+        session_id: getStringOrEmpty(row.session_id),
+        session_data: asRecord(row.session_data) ?? {},
+    };
+}
+function normalizeAMTEventsRow(value) {
+    const row = asRecord(value) ?? {};
+    const events = Array.isArray(row.events)
+        ? row.events.map((event) => asRecord(event) ?? {}).filter((event) => Object.keys(event).length > 0)
+        : [];
+    return {
+        symbol: getStringOrEmpty(row.symbol),
+        session_id: getStringOrEmpty(row.session_id),
+        events,
+    };
+}
+function normalizeMinuteSurface(value) {
+    return {
+        gamma: normalizeSurfacePoints(value.gamma),
+        vanna: normalizeSurfacePoints(value.vanna),
+        charm: normalizeSurfacePoints(value.charm),
+        iv: normalizeSurfacePoints(value.iv),
+    };
+}
+function normalizeSurfacePoints(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((point) => {
+        const rawPoint = asRecord(point) ?? {};
+        return {
+            strike: rawPoint.strike !== undefined ? toNumber(rawPoint.strike) : undefined,
+            value: rawPoint.value !== undefined ? toNumber(rawPoint.value) : undefined,
+            x: rawPoint.x !== undefined ? toNumber(rawPoint.x) : undefined,
+            y: rawPoint.y !== undefined ? toNumber(rawPoint.y) : undefined,
+        };
+    });
+}
+function resolveSignal(ctx) {
+    if (ctx === null || ctx === undefined) {
+        return undefined;
+    }
+    if (isAbortSignal(ctx)) {
+        return ctx;
+    }
+    return ctx.signal;
+}
+function isAbortSignal(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.aborted === 'boolean' &&
+        typeof value.addEventListener === 'function');
+}
+function parseJSON(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function parseDateOnly(value) {
+    if (!DATE_ONLY_REGEX.test(value)) {
+        return null;
+    }
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return null;
+    }
+    const [year, month, day] = value.split('-').map((part) => Number(part));
+    if (parsed.getUTCFullYear() !== year ||
+        parsed.getUTCMonth() + 1 !== month ||
+        parsed.getUTCDate() !== day) {
+        return null;
+    }
+    return parsed;
+}
+function toDateOrNull(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    if (typeof value === 'string' || typeof value === 'number') {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    return null;
+}
+function toInteger(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number.parseInt(value, 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function toNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function asRecord(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function getStringOrEmpty(value) {
+    return typeof value === 'string' ? value : '';
+}
+function toNullableString(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    return String(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (value.trim() !== '') {
+            return value.trim();
+        }
+    }
+    return '';
+}
+function truncateForError(value) {
+    const maxLength = 300;
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}...`;
+}
+function statusTextForCode(statusCode) {
+    return STATUS_TEXT[statusCode] ?? '';
+}
+function toErrorMessage(value) {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    return String(value);
+}