fathom-charts 0.2.0__py3-none-any.whl

fathom_charts/__init__.py

@@ -0,0 +1,154 @@
+"""Fathom Charts client: real-time order-flow indicator streams (WebSocket) and history (REST)."""
+
+from .errors import ERROR_CODES, ErrorCode, FathomChartsError, ProblemFieldError
+from .protocol import (
+    AuthMessage,
+    ClientMessage,
+    CloseCode,
+    CursorFrom,
+    ErrorMessage,
+    From,
+    HeartbeatMessage,
+    MaintenanceWindow,
+    Mode,
+    NoticeKind,
+    NoticeMessage,
+    PingMessage,
+    PongMessage,
+    RemoveMessage,
+    ResetMessage,
+    ResetReason,
+    ServerMessage,
+    SnapshotItem,
+    SnapshotMessage,
+    SourceState,
+    StatusMessage,
+    SubscribedMessage,
+    SubscribeMessage,
+    TimeFrom,
+    UnsubscribeMessage,
+    UpsertMessage,
+    compare_cursors,
+)
+from .rest import (
+    Catalog,
+    CatalogField,
+    CatalogIndicator,
+    CatalogObject,
+    CatalogParam,
+    Estimate,
+    ExportResume,
+    ExportStream,
+    FathomChartsRest,
+    HistorySnapshot,
+    Instrument,
+    Instruments,
+    Limits,
+    Mutation,
+    OfferCode,
+    Offers,
+    Page,
+    PageQuery,
+    PageSnapshot,
+    PlanCode,
+    RangeQuery,
+    Resolved,
+    ServiceStatus,
+    StatusMaintenance,
+    StreamToken,
+    Usage,
+)
+from .stream import (
+    ConnectionState,
+    FathomChartsStream,
+    Item,
+    Notice,
+    Reconnect,
+    Remove,
+    Reset,
+    Snapshot,
+    Status,
+    StreamEvent,
+    Subscribed,
+    SubscribeRequest,
+    Subscription,
+    Upsert,
+    WebSocketFactory,
+    WebSocketLike,
+)
+
+__all__ = [
+    "ERROR_CODES",
+    "AuthMessage",
+    "Catalog",
+    "CatalogField",
+    "CatalogIndicator",
+    "CatalogObject",
+    "CatalogParam",
+    "ClientMessage",
+    "CloseCode",
+    "ConnectionState",
+    "CursorFrom",
+    "ErrorCode",
+    "ErrorMessage",
+    "Estimate",
+    "ExportResume",
+    "ExportStream",
+    "FathomChartsError",
+    "FathomChartsRest",
+    "FathomChartsStream",
+    "From",
+    "HeartbeatMessage",
+    "HistorySnapshot",
+    "Instrument",
+    "Instruments",
+    "Item",
+    "Limits",
+    "MaintenanceWindow",
+    "Mode",
+    "Mutation",
+    "Notice",
+    "NoticeKind",
+    "NoticeMessage",
+    "OfferCode",
+    "Offers",
+    "Page",
+    "PageQuery",
+    "PageSnapshot",
+    "PingMessage",
+    "PlanCode",
+    "PongMessage",
+    "ProblemFieldError",
+    "RangeQuery",
+    "Reconnect",
+    "Remove",
+    "RemoveMessage",
+    "Reset",
+    "ResetMessage",
+    "ResetReason",
+    "Resolved",
+    "ServerMessage",
+    "ServiceStatus",
+    "Snapshot",
+    "SnapshotItem",
+    "SnapshotMessage",
+    "SourceState",
+    "Status",
+    "StatusMaintenance",
+    "StatusMessage",
+    "StreamEvent",
+    "StreamToken",
+    "SubscribeMessage",
+    "SubscribeRequest",
+    "Subscribed",
+    "SubscribedMessage",
+    "Subscription",
+    "TimeFrom",
+    "UnsubscribeMessage",
+    "Upsert",
+    "UpsertMessage",
+    "Usage",
+    "WebSocketFactory",
+    "WebSocketLike",
+    "compare_cursors",
+]

fathom_charts/errors.py

@@ -0,0 +1,91 @@
+"""Stable error codes and the error the SDK raises."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+ErrorCode = Literal[
+    "INVALID_PARAMETERS", "UNKNOWN_INDICATOR", "UNKNOWN_INSTRUMENT", "NOT_COVERED", "WARMING", "QUOTA_EXCEEDED",
+    "RATE_LIMITED", "CAPACITY", "CURSOR_EXPIRED", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT",
+    "WITHDRAWAL_WAIVER_REQUIRED", "SOURCE_DOWN", "UPSTREAM_ERROR", "INTERNAL",
+    "CONFIGURATION", "CLOSED", "KEY_REVOKED", "ENTITLEMENTS_CHANGED", "TOO_MANY_CONNECTIONS", "PROTOCOL_ERROR", "BINARY_NOT_SUPPORTED",
+    "INVALID_UTF8", "MESSAGE_TOO_BIG", "ABORTED", "NETWORK_ERROR",
+]
+"""A code of `ERROR_CODES`. An HTTP error answer without a problem document has the code `HTTP_<status>` (e.g. `HTTP_502`)."""
+
+ERROR_CODES: tuple[ErrorCode, ...] = (
+    "INVALID_PARAMETERS", "UNKNOWN_INDICATOR", "UNKNOWN_INSTRUMENT", "NOT_COVERED", "WARMING", "QUOTA_EXCEEDED",
+    "RATE_LIMITED", "CAPACITY", "CURSOR_EXPIRED", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT",
+    "WITHDRAWAL_WAIVER_REQUIRED", "SOURCE_DOWN", "UPSTREAM_ERROR", "INTERNAL",
+    "CONFIGURATION", "CLOSED", "KEY_REVOKED", "ENTITLEMENTS_CHANGED", "TOO_MANY_CONNECTIONS", "PROTOCOL_ERROR", "BINARY_NOT_SUPPORTED",
+    "INVALID_UTF8", "MESSAGE_TOO_BIG", "ABORTED", "NETWORK_ERROR",
+)
+"""
+Stable error codes.
+
+Codes of the API (RFC 9457 `code`) and of the WebSocket `error` messages: INVALID_PARAMETERS to INTERNAL. FORBIDDEN covers
+the rights of the offers: historical data (queries, estimates, exports, `from:{time}`) needs the Historical offer, real time
+the Live offer. WITHDRAWAL_WAIVER_REQUIRED: a checkout without the waiver of the right of withdrawal.
+
+Codes raised by the SDK itself:
+- CONFIGURATION: invalid client options.
+- CLOSED: `subscribe()` on a stream closed by `close()`.
+- KEY_REVOKED: the gateway closed the connection (4003) because the API key was revoked.
+- ENTITLEMENTS_CHANGED: the gateway closed the connection (4003) because the account's rights no longer cover it (offer
+  ended, account suspended, subscription quota exceeded).
+- TOO_MANY_CONNECTIONS: the connection quota of the plan stayed reached (4029) for `Reconnect.quota_retry`.
+- PROTOCOL_ERROR, BINARY_NOT_SUPPORTED, INVALID_UTF8, MESSAGE_TOO_BIG: the gateway refused a message (close 1002, 1003,
+  1007, 1009); it would refuse it again, so the stream fails.
+- ABORTED: kept for the other SDKs (a call stopped by its signal); in Python a call is stopped by cancelling its task
+  (`asyncio.timeout()`, `Task.cancel()`), and the `asyncio.CancelledError` goes through untouched, as asyncio requires.
+- NETWORK_ERROR: the API could not be reached, or the connection was lost during an answer (DNS, refused or reset
+  connection, TLS); the error of httpx is the `__cause__`.
+- `HTTP_<status>` (e.g. `HTTP_502`): an HTTP error answer without a problem document.
+
+Every error the SDK raises or ends an iteration with is a `FathomChartsError`; the error it stems from, if any, is its `__cause__`.
+"""
+
+
+class ProblemFieldError(TypedDict):
+    """One invalid field of a request: JSON Pointer from the root of the body, and what is wrong with it."""
+
+    path: str
+    message: str
+
+
+class FathomChartsError(Exception):
+    """Error raised by the SDK: a stable code (`ErrorCode`), the HTTP status or WebSocket close code when known."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int | None = None,
+        close_code: int | None = None,
+        retry_after: float | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.close_code = close_code
+        self.retry_after = retry_after
+        self.problem = problem
+        """The RFC 9457 problem document of an HTTP error, with its `errors` (invalid fields, `ProblemFieldError`) when the API
+        gives them; None when the answer is not a problem document."""
+
+    def __repr__(self) -> str:
+        return f"FathomChartsError({self.code!r}, {self.message!r})"
+
+
+def api_key_problem(api_key: object) -> str | None:
+    """Why `api_key` cannot be used (an unset or empty environment variable, typically), or None."""
+    if api_key is None:
+        return "api_key is missing: is the variable holding the API key set?"
+    if not isinstance(api_key, str):
+        return f"api_key must be a string, not {type(api_key).__name__}"
+    if api_key.strip() == "":
+        return "api_key is an empty string: is the variable holding the API key set and not empty?"
+    return None

fathom_charts/generate_types.py

@@ -0,0 +1,237 @@
+"""
+Generates Python types (TypedDict) of indicator parameters and mutation data from the indicator catalog (GET /v1/indicators),
+with its descriptions as docstrings.
+
+Usage: fathom-charts-types <catalog.json | catalog URL> <out.py>
+
+JSON Schema → Python: an object is a TypedDict (a nested one is named after its parent and its key), an optional property
+`NotRequired`, `const` and `enum` a `Literal`, `prefixItems` a tuple. A tuple whose last elements are optional (from `minItems`
+on) is the union of its allowed lengths, e.g. `tuple[int, int, int] | tuple[int, int, int, int]`; one that allows more items
+ends with `*tuple[T, ...]`. JSON arrays still arrive as lists: the tuple types describe their positions.
+"""
+
+from __future__ import annotations
+
+import json
+import keyword
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+_INTEGER_OR_STRING = (bool, int, str)
+
+
+def _pascal(id: str) -> str:
+    return "".join(p[0].upper() + p[1:] for p in re.split(r"[^A-Za-z0-9]+", id) if p)
+
+
+def _identifier(key: str) -> bool:
+    return re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key) is not None and not keyword.iskeyword(key)
+
+
+def _docstring(text: str, indent: str) -> str:
+    """One-line docstring of a description."""
+    one_line = re.sub(r"\s*\n\s*", " ", text.strip()).replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+    if one_line.endswith('"'):
+        one_line = one_line[:-1] + '\\"'
+    return f'{indent}"""{one_line}"""\n'
+
+
+def _comment(text: str, indent: str) -> str:
+    """One-line comment of a description."""
+    one_line = re.sub(r"\s+", " ", text.strip())
+    return f"{indent}# {one_line}\n"
+
+
+def _description(schema: Any) -> str | None:
+    if isinstance(schema, dict) and isinstance(schema.get("description"), str) and schema["description"].strip():
+        text: str = schema["description"]
+        return text
+    return None
+
+
+def _literal(value: Any) -> str:
+    if value is None:
+        return "None"
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    return json.dumps(value, ensure_ascii=False) if isinstance(value, str) else str(value)
+
+
+class Generator:
+    """Turns JSON Schemas (the subset the catalog uses) into Python type expressions; objects become named TypedDicts, defined in
+    `definitions` before their use."""
+
+    def __init__(self) -> None:
+        self.definitions: list[str] = []
+        self.names: set[str] = set()
+        self.typing: set[str] = set()
+
+    def _use(self, name: str) -> str:
+        self.typing.add(name)
+        return name
+
+    def type_of(self, schema: Any, name: str = "Object") -> str:
+        """The type of `schema`; `name` is the name of the TypedDict an object schema becomes."""
+        if not isinstance(schema, dict) or len(schema) == 0:
+            return self._use("Any")
+        if "const" in schema:
+            return self._literals([schema["const"]])
+        if isinstance(schema.get("enum"), list):
+            return self._literals(schema["enum"])
+        for k in ("oneOf", "anyOf"):
+            if isinstance(schema.get(k), list):
+                return " | ".join(self.type_of(s, f"{name}{i + 1}") for i, s in enumerate(schema[k]))
+        if isinstance(schema.get("type"), list):
+            return " | ".join(self.type_of({**schema, "type": t}, name) for t in schema["type"])
+        match schema.get("type"):
+            case "integer":
+                return "int"
+            case "number":
+                return "float"
+            case "string":
+                return "str"
+            case "boolean":
+                return "bool"
+            case "null":
+                return "None"
+            case "array":
+                if isinstance(schema.get("prefixItems"), list):
+                    return self._tuple_of(schema, name)
+                return f"list[{self.type_of(schema.get('items'), f'{name}Item')}]"
+            case "object":
+                properties = schema.get("properties") or {}
+                if schema.get("additionalProperties") is not False and len(properties) == 0:
+                    return f"dict[str, {self._use('Any')}]"
+                return self.define(name, schema)
+            case _:
+                return self._use("Any")
+
+    def _literals(self, values: list[Any]) -> str:
+        """`Literal` of JSON values; a float is not a valid `Literal` value: its type stands for it."""
+        exact = [v for v in values if v is None or isinstance(v, _INTEGER_OR_STRING)]
+        others = sorted({"float" for v in values if isinstance(v, float)})
+        parts = [f"{self._use('Literal')}[{', '.join(_literal(v) for v in exact)}]"] if exact else []
+        return " | ".join(parts + others)
+
+    def _tuple_of(self, schema: dict[str, Any], name: str) -> str:
+        """Tuple of `prefixItems`: elements from `minItems` on are optional (a union of the allowed lengths); a rest element when
+        more items are allowed."""
+        prefix = [self.type_of(s, f"{name}{i + 1}") for i, s in enumerate(schema["prefixItems"])]
+        minimum = min(schema.get("minItems", 0), len(prefix))
+        items = schema.get("items")
+        closed = items is False or (isinstance(schema.get("maxItems"), int) and schema["maxItems"] <= len(prefix))
+        rest = None if closed else f"*tuple[{self.type_of(items, f'{name}Item') if isinstance(items, dict) else self._use('Any')}, ...]"
+        variants = []
+        for length in range(minimum, len(prefix) + 1):
+            elements = prefix[:length] + ([rest] if rest is not None and length == len(prefix) else [])
+            variants.append(f"tuple[{', '.join(elements)}]" if elements else "tuple[()]")
+        return " | ".join(variants)
+
+    def define(self, name: str, schema: dict[str, Any], doc: str | None = None) -> str:
+        """Defines the TypedDict `name` of an object schema; returns its (unique) name."""
+        unique, n = name, 1
+        while unique in self.names:
+            n += 1
+            unique = f"{name}{n}"
+        self.names.add(unique)
+        self._use("TypedDict")
+        required = set(schema.get("required") or [])
+        fields = []
+        for key, s in (schema.get("properties") or {}).items():
+            t = self.type_of(s, f"{unique}{_pascal(key)}")
+            fields.append((key, t if key in required else f"{self._use('NotRequired')}[{t}]", _description(s)))
+        if all(_identifier(key) for key, _, _ in fields):
+            lines = [_docstring(doc, "    ") + ("\n" if fields else "")] if doc else []
+            for key, t, d in fields:
+                lines.append(f"    {key}: {t}\n" + (_docstring(d, "    ") if d else ""))
+            self.definitions.append(f"class {unique}(TypedDict):\n" + ("".join(lines) or "    pass\n"))
+        else:
+            # Keys that are not identifiers: functional syntax, descriptions as comments.
+            entries = "".join(
+                (_comment(d, "        ") if d else "") + f"        {json.dumps(key, ensure_ascii=False)}: {t},\n" for key, t, d in fields
+            )
+            self.definitions.append((_comment(doc, "") if doc else "") + f'{unique} = TypedDict(\n    "{unique}",\n    {{\n{entries}    }},\n)\n')
+        return unique
+
+
+def type_of(schema: Any, name: str = "Object") -> str:
+    """Python type expression of a JSON Schema alone (the TypedDicts it needs are not returned)."""
+    return Generator().type_of(schema, name)
+
+
+def generate(catalog: Any) -> str:
+    if not isinstance(catalog, dict) or catalog.get("version") != 1 or not isinstance(catalog.get("indicators"), list):
+        raise ValueError("Not a version 1 catalog")
+    g = Generator()
+    g._use("TypedDict")
+    g._use("Literal")
+    for ind in catalog["indicators"]:
+        name = _pascal(ind["id"])
+        summary = f"{ind['name']}: {ind.get('summary') or ''}"
+        _named(g, f"{name}Params", ind.get("paramsSchema"), summary)
+        _named(g, f"{name}Data", ind.get("dataSchema"), _description(ind.get("dataSchema")))
+    ids = [ind["id"] for ind in catalog["indicators"]]
+    for kind in ("Params", "Data"):
+        entries = ", ".join(f"{json.dumps(i, ensure_ascii=False)}: {_pascal(i)}{kind}" for i in ids)
+        g.definitions.append(f'Indicator{kind} = TypedDict("Indicator{kind}", {{{entries}}})\n')
+    g.definitions.append(f"IndicatorId = Literal[{', '.join(json.dumps(i, ensure_ascii=False) for i in ids)}]\n")
+    header = [
+        f"# Generated from the indicator catalog (engine {catalog.get('engineFingerprint')}). Do not edit.",
+        "",
+        f"from typing import {', '.join(sorted(g.typing))}",
+        "",
+    ]
+    return "\n".join(header) + "\n" + "\n\n".join(g.definitions)
+
+
+def _named(g: Generator, name: str, schema: Any, doc: str | None) -> None:
+    """Defines `name` for an indicator schema: a TypedDict for an object with properties, an alias otherwise."""
+    if isinstance(schema, dict) and schema.get("type") == "object" and (schema.get("properties") or schema.get("additionalProperties") is False):
+        g.define(name, schema, doc)
+        return
+    expression = g.type_of(schema, name)
+    g.names.add(name)
+    g.definitions.append((_comment(doc, "") if doc else "") + f"{name} = {expression}\n")
+
+
+USAGE = (
+    "Usage: fathom-charts-types <catalog.json | catalog URL> <out.py>\n"
+    "  The catalog is a file saved from GET /v1/indicators, or its URL (https://api.fathomcharts.com/v1/indicators).\n"
+)
+
+
+def parse_args(argv: list[str]) -> tuple[str, str] | None:
+    """Arguments of the command: the two paths, or None when they do not fit the usage."""
+    if len(argv) != 2 or any(not a or a.startswith("--") for a in argv):
+        return None
+    return argv[0], argv[1]
+
+
+def load_catalog(source: str) -> Any:
+    """The catalog of `source`: a file, or an http(s) URL."""
+    if not re.match(r"https?://", source):
+        return json.loads(Path(source).read_text(encoding="utf-8"))
+    response = httpx.get(source, headers={"accept": "application/json"})
+    if not response.is_success:
+        raise RuntimeError(f"GET {source} answered {response.status_code}")
+    return response.json()
+
+
+def main(argv: list[str] | None = None) -> None:
+    """The `fathom-charts-types` command."""
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    if args is None:
+        sys.stderr.write(USAGE)
+        raise SystemExit(2)
+    source = generate(load_catalog(args[0]))
+    output = Path(args[1])
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(source, encoding="utf-8", newline="\n")
+
+
+if __name__ == "__main__":
+    main()

fathom_charts/protocol.py

@@ -0,0 +1,216 @@
+"""Public WebSocket protocol. Every message is a JSON object whose `t` field names it."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Generic, Literal, NotRequired, TypedDict, TypeVar
+
+from .errors import FathomChartsError
+
+D = TypeVar("D")
+
+Mode = Literal["live", "confirmed"]
+
+
+class CursorFrom(TypedDict):
+    """After a known cursor. `engine` is the engine build that cursor comes from (`subscribed.engine`): under another build the
+    subscription restarts from a snapshot after `reset` (`engine_change`) instead of resuming state computed differently."""
+
+    cursor: str
+    engine: NotRequired[str]
+
+
+class TimeFrom(TypedDict):
+    """From a time (Unix ns, decimal string) through history into live."""
+
+    time: str
+
+
+From = Literal["live"] | CursorFrom | TimeFrom
+"""Start point: live edge, after a known cursor, or from a time through history into live."""
+
+SourceState = Literal["live", "warming", "source_delayed", "source_down", "market_closed"]
+ResetReason = Literal["roll", "slow_consumer", "cursor_expired", "entitlement_changed", "engine_change"]
+NoticeKind = Literal["reconnect", "maintenance", "maintenance-cancelled", "breaking-change"]
+"""
+`reconnect`: the gateway restarts (deployment) and closes the connection (1012) within seconds; `maintenance`: a window
+(`id`, `effectiveAt` to `endsAt`, `message`) during which the service may pause; `maintenance-cancelled`: the window
+`id` is cancelled; `breaking-change`: a protocol change takes effect at `effectiveAt`.
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class MaintenanceWindow:
+    """A maintenance window announced and not cancelled: the service may pause between `starts_at` and `ends_at` (Unix ns)."""
+
+    id: str
+    starts_at: str
+    ends_at: str
+    message: str
+
+
+class SnapshotItem(TypedDict, Generic[D]):
+    """One object of a snapshot, as on the wire: the latest state of an indicator object."""
+
+    id: str
+    final: bool
+    ts: str
+    data: D
+
+
+# Client → server
+class AuthMessage(TypedDict):
+    t: Literal["auth"]
+    token: str
+
+
+SubscribeMessage = TypedDict(
+    "SubscribeMessage",
+    {"t": Literal["subscribe"], "sub": str, "instrument": str, "indicator": str, "params": dict[str, Any], "mode": Mode, "from": From},
+)
+
+
+class UnsubscribeMessage(TypedDict):
+    t: Literal["unsubscribe"]
+    sub: str
+
+
+class PingMessage(TypedDict):
+    t: Literal["ping"]
+
+
+ClientMessage = AuthMessage | SubscribeMessage | UnsubscribeMessage | PingMessage
+
+
+# Server → client
+class SubscribedMessage(TypedDict):
+    """The subscription is served: its topic key and the contract it follows (an alias resolved, e.g. `NQ.front` -> `NQZ6`), with
+    its price increment (1e-9 units, decimal string), and the fingerprint of the engine build computing it (`engine`, given back
+    with a cursor to resume). The starting cursor is the one of the snapshot, or of the resumed records."""
+
+    t: Literal["subscribed"]
+    sub: str
+    topic: str
+    instrument: str
+    tickSizeNanos: str
+    engine: str
+
+
+class SnapshotMessage(TypedDict, Generic[D]):
+    t: Literal["snapshot"]
+    sub: str
+    cursor: str
+    items: list[SnapshotItem[D]]
+
+
+class UpsertMessage(TypedDict, Generic[D]):
+    t: Literal["upsert"]
+    sub: str
+    cursor: str
+    id: str
+    final: bool
+    ts: str
+    data: D
+
+
+class RemoveMessage(TypedDict):
+    t: Literal["remove"]
+    sub: str
+    cursor: str
+    id: str
+    final: bool
+    ts: str
+    data: NotRequired[Any]
+
+
+class StatusMessage(TypedDict):
+    t: Literal["status"]
+    sub: str
+    state: SourceState
+    lagMs: int
+
+
+class ResetMessage(TypedDict):
+    t: Literal["reset"]
+    sub: str
+    reason: ResetReason
+
+
+class ErrorMessage(TypedDict):
+    t: Literal["error"]
+    sub: NotRequired[str]
+    code: str
+    message: str
+
+
+class HeartbeatMessage(TypedDict):
+    t: Literal["hb"]
+    cursors: dict[str, str]
+
+
+class NoticeMessage(TypedDict):
+    """A notice to the connection (all its subscriptions). Times: Unix ns, decimal strings."""
+
+    t: Literal["notice"]
+    kind: NoticeKind
+    id: NotRequired[str]
+    effectiveAt: NotRequired[str]
+    endsAt: NotRequired[str]
+    message: NotRequired[str]
+
+
+class PongMessage(TypedDict):
+    """Answer to a `ping`, sent ahead of the queued messages."""
+
+    t: Literal["pong"]
+
+
+ServerMessage = (
+    SubscribedMessage | SnapshotMessage[Any] | UpsertMessage[Any] | RemoveMessage | StatusMessage | ResetMessage | ErrorMessage
+    | HeartbeatMessage | NoticeMessage | PongMessage
+)
+
+
+class CloseCode(IntEnum):
+    """WebSocket close codes of the gateway."""
+
+    NORMAL = 1000
+    PROTOCOL_ERROR = 1002
+    BINARY_NOT_SUPPORTED = 1003
+    INVALID_UTF8 = 1007
+    RATE_LIMITED = 1008
+    MESSAGE_TOO_BIG = 1009
+    SERVICE_RESTART = 1012
+    TRY_AGAIN_LATER = 1013
+    UNAUTHORIZED = 4001
+    FORBIDDEN = 4003
+    SLOW_CONSUMER = 4008
+    TOO_MANY_CONNECTIONS = 4029
+
+
+_CURSOR = re.compile(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)")
+
+
+def _cursor_parts(cursor: str) -> tuple[int, int, int]:
+    match = _CURSOR.fullmatch(cursor) if isinstance(cursor, str) else None
+    if match is None:
+        raise FathomChartsError(
+            "INVALID_PARAMETERS",
+            f"Invalid cursor {json.dumps(cursor, ensure_ascii=False)}: expected <day>.<rank>.<k>, decimal integers without leading zeros",
+        )
+    return int(match[1]), int(match[2]), int(match[3])
+
+
+def compare_cursors(a: str, b: str) -> int:
+    """
+    Orders two cursors `<day>.<rank>.<k>` (decimal integers without leading zeros), part by part. Returns a negative number, zero
+    or a positive number. Raises a `FathomChartsError` INVALID_PARAMETERS when either is not a well-formed cursor.
+    """
+    x, y = _cursor_parts(a), _cursor_parts(b)
+    for i in range(3):
+        if x[i] != y[i]:
+            return -1 if x[i] < y[i] else 1
+    return 0