@mrdoge/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,417 @@
+import { WelcomeParams, MethodName, MethodParams, MethodResult, SubscriptionEventParams, SubscriptionClosedParams, SubscriptionMethodName, PushEventsOf, SubscriptionClosedReason, ErrorCode } from '@mrdoge/protocol';
+export { AiPick, BetItem, Clock, Competition, ErrorCode, Market, Match, MatchDetail, MatchDetailSelect, MatchSelect, MatchState, MatchStats, MatchStatus, Pagination, Period, PickConfidence, PickLeg, PickResult, Recommendation, Region, Selector, Sport, StatPlayer, SubscriptionClosedReason, Team, TeamDetail, TeamForm, TeamFormMatch, TeamFormResult, WelcomeParams } from '@mrdoge/protocol';
+import { MrDogeHttpClient } from '@mrdoge/http';
+
+interface BackoffConfig {
+    minMs: number;
+    maxMs: number;
+    /** Jitter as a fraction of the computed delay (0.2 = ±20%). */
+    jitter: number;
+}
+
+/**
+ * Per-call options accepted by every method that makes a request. Mirrors
+ * the `fetch` convention so callers can plug in a standard `AbortController`.
+ *
+ * When `signal` fires, the in-flight request is dropped client-side and the
+ * returned promise rejects with `AbortError` (`err.name === "AbortError"`).
+ */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+
+interface ConnectionConfig {
+    baseUrl: string;
+    apiKey: string;
+    /** Default locale applied to method params. Per-call overrides win. */
+    locale?: string;
+    /** Default timezone applied to method params. Per-call overrides win. */
+    timezone?: string;
+    requestTimeoutMs: number;
+    maxReconnectAttempts: number;
+    reconnectBackoff: BackoffConfig;
+    compression: boolean;
+    /** Auth must complete (auth ack + welcome) within this many ms. */
+    authTimeoutMs: number;
+}
+interface ConnectionEvents {
+    connected: {
+        welcome: WelcomeParams;
+    };
+    disconnected: {
+        reason: string;
+        code: number;
+    };
+    reconnecting: {
+        attempt: number;
+        delayMs: number;
+    };
+}
+/**
+ * Active subscriptions tracked by the connection. The handle's `subId` is
+ * mutable — it changes on reconnect when the server issues a fresh id.
+ */
+interface SubscriptionRegistration {
+    /** Current server-issued sub id. Changes on reconnect. */
+    subId: string;
+    method: MethodName;
+    params: unknown;
+    onEvent: (event: SubscriptionEventParams) => void;
+    onClosed: (params: SubscriptionClosedParams) => void;
+    /** Called by the connection when a reconnect resubscribe produced a fresh snapshot. */
+    onSnapshot: (newSubId: string, snapshot: unknown) => void;
+}
+/**
+ * Long-lived WebSocket connection with JSON-RPC dispatch and automatic
+ * reconnection. Subscriptions are resubscribed transparently on reconnect.
+ */
+declare class Connection {
+    private readonly emitter;
+    private readonly config;
+    private ws;
+    private nextRequestId;
+    private readonly pending;
+    private readonly subscriptions;
+    private connectingPromise;
+    private welcome;
+    private closed;
+    private reconnectAttempt;
+    private reconnectAbort;
+    constructor(config: ConnectionConfig);
+    on: <E extends keyof ConnectionEvents>(event: E, fn: (payload: ConnectionEvents[E]) => void) => () => void;
+    off: <E extends keyof ConnectionEvents>(event: E, fn: (payload: ConnectionEvents[E]) => void) => void;
+    get isConnected(): boolean;
+    /**
+     * Idempotent. Returns the welcome payload once connected + authed.
+     */
+    connect(): Promise<WelcomeParams>;
+    call<M extends MethodName>(method: M, params: MethodParams<M>, options?: CallOptions): Promise<MethodResult<M>>;
+    /**
+     * Registers a subscription with the connection. The connection sends the
+     * subscribe call, stores the registration for reconnect, and routes incoming
+     * push events to the handler.
+     */
+    registerSubscription<M extends MethodName>(method: M, params: MethodParams<M>, handlers: {
+        onEvent: SubscriptionRegistration["onEvent"];
+        onClosed: SubscriptionRegistration["onClosed"];
+        onSnapshot: SubscriptionRegistration["onSnapshot"];
+    }, options?: CallOptions): Promise<{
+        subId: string;
+        snapshot: unknown;
+    }>;
+    /**
+     * Cancels a subscription server-side and removes the registration locally.
+     */
+    cancelSubscription(subId: string): Promise<void>;
+    close(): Promise<void>;
+    private openAndAuth;
+    private performAuth;
+    /**
+     * Set during `performAuth` so we can resolve when the `welcome` notification arrives.
+     */
+    private pendingWelcome;
+    private send;
+    private handleMessage;
+    private handleNotification;
+    private handleClose;
+    private handleSocketError;
+    private scheduleReconnect;
+    private resubscribeAll;
+}
+
+declare class Regions {
+    private readonly conn;
+    private readonly defaults;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+    list(params?: MethodParams<"regions.list">, options?: CallOptions): Promise<MethodResult<"regions.list">>;
+}
+
+declare class Competitions {
+    private readonly conn;
+    private readonly defaults;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+    list(params?: MethodParams<"competitions.list">, options?: CallOptions): Promise<MethodResult<"competitions.list">>;
+}
+
+declare class Teams {
+    private readonly conn;
+    private readonly defaults;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+    list(params?: MethodParams<"teams.list">, options?: CallOptions): Promise<MethodResult<"teams.list">>;
+    get(params: MethodParams<"teams.get">, options?: CallOptions): Promise<MethodResult<"teams.get">>;
+    form(params: MethodParams<"teams.form">, options?: CallOptions): Promise<MethodResult<"teams.form">>;
+}
+
+/**
+ * Maps each push event name to the typed `data` payload it carries.
+ * Derived from the discriminated union in `@mrdoge/protocol`.
+ */
+type EventDataMap = {
+    [E in SubscriptionEventParams as E["event"]]: E["data"];
+};
+type SnapshotOf<M extends SubscriptionMethodName> = MethodResult<M> extends {
+    snapshot: infer S;
+} ? S : never;
+type SubEventMap<M extends SubscriptionMethodName> = {
+    [E in PushEventsOf<M> & keyof EventDataMap]: EventDataMap[E];
+} & {
+    snapshot: SnapshotOf<M>;
+    closed: {
+        reason: SubscriptionClosedReason;
+        message?: string;
+    };
+};
+/**
+ * Handle returned by `mrdoge.matches.subscribe(...)` and `subscribeLive(...)`.
+ *
+ * Stable across reconnects: the underlying server-issued `sub` id may change,
+ * but this handle and its listeners persist. On reconnect, the SDK refreshes
+ * `snapshot` and emits a `snapshot` event so callers can replace their local
+ * state.
+ */
+declare class Subscription<M extends SubscriptionMethodName> {
+    private readonly emitter;
+    private readonly connection;
+    private internalSubId;
+    private currentSnapshot;
+    private cancelled;
+    /**
+     * True when `cancel()` was called before the WS subscribe arrived (subId
+     * still pending). Once WS resolves, `_deliverSnapshot` issues the
+     * server-side cancel so we don't leak a registered subscription.
+     */
+    private pendingCancel;
+    /** @internal — constructed by the SDK, not by user code. */
+    constructor(connection: Connection, subId: string, initialSnapshot: SnapshotOf<M>);
+    /** The latest snapshot the server has emitted (initial, or post-reconnect). */
+    get snapshot(): SnapshotOf<M>;
+    /** Current server-issued subscription id. Changes on reconnect. */
+    get id(): string;
+    /**
+     * Listen for a push event from this subscription. Returns an unsubscribe
+     * function that removes only this listener.
+     *
+     * In addition to protocol push events, two synthetic events fire:
+     * - `snapshot` — when a reconnect produced a fresh snapshot
+     * - `closed`   — when the server terminates the subscription (or cancel)
+     */
+    on<E extends keyof SubEventMap<M>>(event: E, fn: (payload: SubEventMap<M>[E]) => void): () => void;
+    /**
+     * Cancel the subscription server-side. Idempotent — calling twice is safe.
+     */
+    cancel(): Promise<void>;
+    /** @internal */
+    _deliverEvent(params: SubscriptionEventParams): void;
+    /** @internal */
+    _deliverSnapshot(newSubId: string, snapshot: SnapshotOf<M>): void;
+    /** @internal */
+    _deliverClosed(reason: SubscriptionClosedReason, message?: string): void;
+}
+
+interface Defaults {
+    locale?: string;
+    timezone?: string;
+}
+declare class Matches {
+    private readonly conn;
+    private readonly defaults;
+    private readonly http;
+    constructor(conn: Connection, defaults: Defaults, http: MrDogeHttpClient);
+    list(params?: MethodParams<"matches.list">, options?: CallOptions): Promise<MethodResult<"matches.list">>;
+    get(params: MethodParams<"matches.get">, options?: CallOptions): Promise<MethodResult<"matches.get">>;
+    trending(params?: MethodParams<"matches.trending">, options?: CallOptions): Promise<MethodResult<"matches.trending">>;
+    search(params: MethodParams<"matches.search">, options?: CallOptions): Promise<MethodResult<"matches.search">>;
+    subscribeLive(params?: MethodParams<"matches.subscribeLive">, options?: CallOptions): Promise<Subscription<"matches.subscribeLive">>;
+    subscribe(params: MethodParams<"matches.subscribe">, options?: CallOptions): Promise<Subscription<"matches.subscribe">>;
+}
+
+declare class Picks {
+    private readonly conn;
+    private readonly defaults;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+    list(params?: MethodParams<"ai.picks.list">, options?: CallOptions): Promise<MethodResult<"ai.picks.list">>;
+}
+declare class Recommendations {
+    private readonly conn;
+    private readonly defaults;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+    list(params?: MethodParams<"ai.recommendations.list">, options?: CallOptions): Promise<MethodResult<"ai.recommendations.list">>;
+}
+declare class Ai {
+    readonly picks: Picks;
+    readonly recommendations: Recommendations;
+    constructor(conn: Connection, defaults: {
+        locale?: string;
+    });
+}
+
+/**
+ * Server-side resource for minting short-lived auth tokens for client-side use.
+ *
+ * Typical use: customer's backend has the `sk_live_...` key and exposes an
+ * HTTP route that mints tokens for their frontend (browser / React Native):
+ *
+ * ```ts
+ * app.post("/api/mrdoge/token", async (req, res) => {
+ *   const { token, expiresAt } = await mrdoge.tokens.create({ ttl: 600 })
+ *   res.json({ token, expiresAt })
+ * })
+ * ```
+ *
+ * The frontend uses these tokens with `@mrdoge/client` — the sk_live_... key
+ * never leaves the backend.
+ */
+declare class Tokens {
+    private readonly conn;
+    constructor(conn: Connection);
+    /**
+     * Mint a short-lived JWT auth token.
+     *
+     * @param params.ttl  Token lifetime in seconds. Default 600 (10 min).
+     *                    Server-enforced bounds: min 60, max 86400 (24h).
+     * @returns { token, expiresAt } — `token` is opaque to the customer; pass
+     *          it to `@mrdoge/client`. `expiresAt` is ISO-8601.
+     */
+    create(params?: MethodParams<"tokens.create">, options?: CallOptions): Promise<MethodResult<"tokens.create">>;
+}
+
+declare const DEFAULT_BASE_URL = "wss://api.mrdoge.co/sdk/v1";
+interface MrDogeOptions {
+    apiKey: string;
+    /** Override the server URL (e.g. for local dev). Defaults to production. */
+    baseUrl?: string;
+    /** Default locale applied to every call; overridable per-call. */
+    locale?: string;
+    /** Default timezone applied to every call; overridable per-call. */
+    timezone?: string;
+    /** Request-level timeout in milliseconds. Default 10s. */
+    requestTimeoutMs?: number;
+    /** Max reconnect attempts on transient disconnects. Default Infinity. */
+    maxReconnectAttempts?: number;
+    /** Exponential backoff config for reconnects. */
+    reconnectBackoff?: Partial<BackoffConfig>;
+    /**
+     * Whether to negotiate `permessage-deflate` compression at the WS handshake.
+     * Default `true`. Disable for CPU-constrained environments.
+     */
+    compression?: boolean;
+}
+/**
+ * Mr. Doge SDK entrypoint.
+ *
+ * ```ts
+ * const mrdoge = new MrDoge({ apiKey: process.env.MRDOGE_API_KEY! })
+ * const matches = await mrdoge.matches.list({ date: "2026-05-12" })
+ * ```
+ *
+ * The constructor does not open a connection. The WebSocket is opened lazily
+ * on the first method call and reused for the lifetime of the client.
+ */
+declare class MrDoge {
+    readonly regions: Regions;
+    readonly competitions: Competitions;
+    readonly teams: Teams;
+    readonly matches: Matches;
+    readonly ai: Ai;
+    readonly tokens: Tokens;
+    private readonly connection;
+    private readonly http;
+    constructor(options: MrDogeOptions);
+    /**
+     * Listen to connection lifecycle events.
+     */
+    on<E extends keyof ConnectionEvents>(event: E, fn: (payload: ConnectionEvents[E]) => void): () => void;
+    /**
+     * Force-open the connection now instead of waiting for the first call.
+     * Returns the welcome payload from the server.
+     */
+    connect(): Promise<{
+        protocolVersion: number;
+        serverVersion: string;
+        tier: string;
+        rateLimit: {
+            requestsPerMinute: number;
+            subscriptionsMax: number;
+        };
+    }>;
+    /**
+     * Close the connection and cancel every active subscription. The client is
+     * unusable after `close()`.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Base class for every SDK-thrown error. Map by `instanceof` or by `code`.
+ */
+declare class MrDogeError extends Error {
+    readonly code: ErrorCode | "connection_error" | "disconnected" | "timeout" | "aborted" | "unknown";
+    readonly data?: unknown;
+    constructor(code: MrDogeError["code"], message: string, data?: unknown);
+}
+declare class UnauthorizedError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class ForbiddenError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class NotFoundError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class ValidationError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class RateLimitError extends MrDogeError {
+    readonly retryAfterMs: number;
+    readonly limit?: number;
+    readonly remaining?: number;
+    readonly resetAt?: Date;
+    constructor(message: string, data?: unknown);
+}
+declare class SubscriptionLimitError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class ConnectionLimitError extends MrDogeError {
+    readonly current?: number;
+    readonly max?: number;
+    constructor(message: string, data?: unknown);
+}
+declare class UnavailableError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class InternalError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+declare class ProtocolError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+/** Raised when the SDK can't reach or stay connected to the server. */
+declare class ConnectionError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+/** A request was in flight when the connection dropped. The caller should retry if safe. */
+declare class DisconnectedError extends MrDogeError {
+    constructor(message?: string, data?: unknown);
+}
+declare class TimeoutError extends MrDogeError {
+    constructor(message: string, data?: unknown);
+}
+/**
+ * Thrown when a request is aborted via the customer-supplied
+ * `options.signal`. Matches `fetch` convention — `err.name === "AbortError"`.
+ */
+declare class AbortError extends MrDogeError {
+    constructor(message?: string);
+}
+
+export { AbortError, type CallOptions, ConnectionError, ConnectionLimitError, DEFAULT_BASE_URL, DisconnectedError, ForbiddenError, InternalError, MrDoge, MrDogeError, type MrDogeOptions, NotFoundError, ProtocolError, RateLimitError, Subscription, SubscriptionLimitError, TimeoutError, UnauthorizedError, UnavailableError, ValidationError };