@waterx/sdk 4.3.2 → 5.0.0

package/dist/cjs/src/oracle/schedule.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `schedule.ts` — Pyth `attributes.schedule` grammar parser + the pure
+ * market-status walker (WL-2345): the ONE implementation both consumers fold
+ * onto (the FE fallback `/api/markets` route and the BE
+ * `PythScheduleService` / markets service carried drifting twins).
+ *
+ * Parser grammar (https://docs.pyth.network/price-feeds/market-hours):
+ *
+ *   {IANA_timezone};{Mon},{Tue},{Wed},{Thu},{Fri},{Sat},{Sun};{holidays_csv}
+ *
+ * Each weekday slot is `Open`/`O`/`open`, `Closed`/`C`/`closed`, one
+ * `HHMM-HHMM` range, `&`-joined ranges (the new multi-session encoding), or
+ * comma-joined ranges (the old encoding — disambiguated from the weekday
+ * separator by lookahead). Holidays are `MMDD` (old) or `MMDD/C` (new; a
+ * `MMDD/HHMM-HHMM` modified-hours entry is NOT a closure and is skipped, as
+ * are non-MMDD sentinels like Pyth's `"0"`). This is the reconciled SUPERSET
+ * of the two prior ports — accepting either era's tokens is what lets one
+ * parser serve the `v1/symbols` catalog and any cached Hermes-era strings.
+ *
+ * Pyth weekday order is Mon=0..Sun=6; `TradingHours.days` uses ISO-ish
+ * Sun=0..Sat=6 (converted in `groupIntoSessions`).
+ *
+ * The schedule catalog itself comes from `fetchPythSymbolCatalog`
+ * (`symbol-catalog.ts`); pairing a record's `schedule` with this parser and
+ * `getMarketStatus` is the whole market-hours pipeline.
+ */
+export interface TradingSession {
+    /** HH:MM (24h) open time in the market's timezone */
+    open: string;
+    /** HH:MM (24h) close time — may be next day (e.g. "17:00" Sunday open to "17:00" Friday) */
+    close: string;
+    /** ISO day-of-week: 0=Sunday … 6=Saturday */
+    days: number[];
+}
+/**
+ * Year-agnostic `(month, day)` pair, matching Pyth's `MMDD` holiday encoding.
+ * The same `{month, day}` matches in *every* year, so moving holidays
+ * (Good Friday, MLK Day, Thanksgiving, etc.) need to be republished by Pyth
+ * each year and picked up by the consumer's next catalog refresh.
+ */
+export interface HolidayDate {
+    /** 1..12, in the schedule's timezone */
+    month: number;
+    /** 1..31, in the schedule's timezone */
+    day: number;
+    /**
+     * MODIFIED hours for this date, in place of the weekly schedule — an early
+     * close (`1224/0930-1300`) or a split session (`1224/0000-1430&1800-2400`).
+     * Absent means a FULL closure, the `MMDD/C` form.
+     *
+     * These were previously discarded, which meant the venue fell back to its
+     * NORMAL weekly hours on an early-close day and reported itself open after it
+     * had shut. They are not an edge case: the live Pyth catalog carries
+     * thousands (`0930-1300` alone appears ~2.5k times).
+     */
+    sessions?: {
+        open: string;
+        close: string;
+    }[];
+}
+export interface TradingHours {
+    /** IANA timezone identifier, e.g. "America/New_York" */
+    timezone: string;
+    sessions: TradingSession[];
+    /**
+     * Days when the venue is fully closed regardless of the weekly schedule.
+     * Optional — many feeds (crypto, FX) have none. Encoded as `(month, day)`
+     * in `timezone`'s local calendar, matching Pyth's `attributes.schedule`
+     * holiday list.
+     */
+    holidays?: HolidayDate[];
+}
+export interface ParsedPythSchedule {
+    tradingHours: TradingHours;
+    /** True iff every weekday is fully open and there are no holidays — callers treat as `tradingHours = null` (24/7, no schedule needed). */
+    alwaysOpen: boolean;
+}
+export declare class PythScheduleParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a Pyth schedule string. Throws {@link PythScheduleParseError} on
+ * malformed input — callers guard with try/catch so one bad feed does not break
+ * a whole market list.
+ *
+ * DEGRADE CLOSED, not open. The obvious fallback — treat an unparseable
+ * schedule as "no schedule (24/7)" — is the wrong direction: the shapes that
+ * actually fail here are venues WITH sessions (a lunch-break equity schedule in
+ * the legacy comma encoding, an ambiguous weekday fold), and calling those 24/7
+ * reports a closed venue as tradable. That is the failure class this module
+ * exists to prevent. Prefer marking the market unavailable, or reusing the last
+ * schedule that parsed; use 24/7 only where a wrong "open" is harmless.
+ */
+export declare function parsePythSchedule(input: string): ParsedPythSchedule;
+export interface MarketStatusResult {
+    status: "open" | "closed" | "paused";
+    /** Milliseconds until next status change; null for 24/7 or paused. */
+    nextStatusChangeIn: number | null;
+}
+/**
+ * Pure function — calculates market open/closed status from trading hours + now.
+ *
+ * @param tradingHours  null means 24/7 (crypto)
+ * @param paused        forces `paused`, short-circuiting the schedule. Checked
+ *                      BEFORE the 24/7 branch, so an on-chain-paused crypto
+ *                      market (tradingHours === null) still reports paused.
+ * @param now           injectable for testing; defaults to new Date()
+ */
+export declare function getMarketStatus(tradingHours: TradingHours | null, paused: boolean, now?: Date): MarketStatusResult;