@clovnet/casino-sdk 1.0.0

package/dist/contract-DtFe4bRy.d.cts

@@ -0,0 +1,205 @@
+/**
+ * Canonical realtime surface, aligned with the runtime's
+ * `docs/realtime-sdk-contract.ts` (the agreed contract; verbatim copy kept in
+ * `contract.vendored.ts` for diffing — `pnpm sync:contract` refreshes it). We
+ * ALIGN with that file — do not fork it. Naming note: the runtime doc calls the
+ * core-channel union `RealtimeChannel` and the core+ext union
+ * `AnyRealtimeChannel`; here they are {@link CoreRealtimeChannel} and
+ * {@link RealtimeChannel} respectively. The plugin `ext.*` channel family
+ * ({@link ExtChannel}, {@link ExtPluginEvent}) is part of the runtime contract.
+ * SDK-local additions: {@link WebSocketImpl}, `dedupeWindow`,
+ * {@link REALTIME_CHANNELS}, {@link isExtChannel}.
+ *
+ * Money amounts are scale-4 integer minor units (see `core/money.ts`).
+ */
+/** Statically-known core channels. Strings are stable, versioned, and authz-checked server-side. */
+type CoreRealtimeChannel = "wallet.balance" | "wallet.deposit" | "wallet.withdrawal" | "gaming" | "bonus" | "player";
+/**
+ * Channel family published by tenant-enabled plugins, e.g. `"ext.cashback"`.
+ * Which ones exist comes from the ext catalog (`ExtCatalogPlugin.channels`);
+ * subscribing for a non-enabled plugin is rejected by the gateway exactly like
+ * an unknown channel.
+ */
+type ExtChannel = `ext.${string}`;
+/** Logical channels: the static core set plus the dynamic plugin family. */
+type RealtimeChannel = CoreRealtimeChannel | ExtChannel;
+/**
+ * Narrow a plain string (e.g. an entry of `ExtCatalogPlugin.channels`, which the
+ * wire contract types as `string[]`) to a subscribable {@link ExtChannel}.
+ */
+declare function isExtChannel(value: string): value is ExtChannel;
+/**
+ * All statically-known subscribable channels, for runtime validation/iteration.
+ * Plugin `ext.*` channels are dynamic (discovered via the ext catalog) and
+ * intentionally not listed.
+ */
+declare const REALTIME_CHANNELS: readonly CoreRealtimeChannel[];
+type WalletBucket = "cash" | "bonus" | "locked";
+/** Minor units (scale-4 integer). Never do money math on the client beyond display. */
+type MinorUnits = number;
+/** Common envelope present on every server → client business event. */
+interface RealtimeEventMeta {
+    readonly event: string;
+    readonly eventId: string;
+    readonly v: number;
+    readonly occurredAt: string;
+    readonly tenantId: string;
+}
+interface WalletBalanceEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.balance";
+    readonly data: {
+        readonly currency: string;
+        readonly balances: Readonly<Record<WalletBucket, MinorUnits>>;
+        readonly change: {
+            readonly bucket: WalletBucket;
+            readonly direction: "credit" | "debit";
+            readonly amount: MinorUnits;
+            readonly reason: string;
+        };
+    };
+}
+type DepositStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";
+interface WalletDepositEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.deposit";
+    readonly data: {
+        readonly depositId: string;
+        readonly status: DepositStatus;
+        readonly amount: MinorUnits;
+        readonly currency: string;
+    };
+}
+type WithdrawalStatus = "requested" | "approved" | "rejected" | "processing" | "completed" | "reversed" | "cancelled";
+interface WalletWithdrawalEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.withdrawal";
+    readonly data: {
+        readonly withdrawalId: string;
+        readonly status: WithdrawalStatus;
+        readonly amount: MinorUnits;
+        readonly currency: string;
+    };
+}
+interface GamingEvent extends RealtimeEventMeta {
+    readonly channel: "gaming";
+    readonly data: {
+        readonly roundId: string;
+        readonly betId?: string;
+        readonly status: "placed" | "settled" | "rolled_back" | "round_closed";
+        /** Internal catalog game id — map to a display name from your catalog. */
+        readonly gameId?: string;
+        /** Provider key that produced the round (e.g. `"slotserv"`). */
+        readonly provider?: string;
+        /** Wager amount, present on `placed`. */
+        readonly betAmount?: MinorUnits;
+        /** Payout, present on `settled`. */
+        readonly winAmount?: MinorUnits;
+        readonly currency?: string;
+    };
+}
+interface BonusEvent extends RealtimeEventMeta {
+    readonly channel: "bonus";
+    readonly data: {
+        readonly bonusId: string;
+        readonly status: "granted" | "revoked";
+        readonly amount?: MinorUnits;
+        readonly currency?: string;
+        readonly reason?: string;
+    };
+}
+interface PlayerEvent extends RealtimeEventMeta {
+    readonly channel: "player";
+    readonly data: {
+        readonly change: "password_changed" | "social_linked" | "social_unlinked" | "account_locked" | "email_verified" | "phone_verified" | "session_revoked" | "kyc_status_changed" | "kyc_documents_requested" | "limit_changed" | "self_excluded" | "reality_check";
+        readonly data?: Readonly<Record<string, string | number | boolean | null>>;
+    };
+}
+/**
+ * An event published by a plugin on its `ext.<pluginKey>` channel. The standard
+ * realtime envelope applies (incl. `eventId` dedupe); `data.type` is the
+ * plugin-defined event type (e.g. `"cashback.claimed"`) and `data.payload` is
+ * opaque to the SDK.
+ */
+interface ExtPluginEvent extends RealtimeEventMeta {
+    readonly channel: ExtChannel;
+    readonly data: {
+        readonly type: string;
+        readonly payload: unknown;
+    };
+}
+/** Maps a channel name to its event payload type, for type-safe `on(...)`. */
+interface ChannelEventMap {
+    "wallet.balance": WalletBalanceEvent;
+    "wallet.deposit": WalletDepositEvent;
+    "wallet.withdrawal": WalletWithdrawalEvent;
+    gaming: GamingEvent;
+    bonus: BonusEvent;
+    player: PlayerEvent;
+    [channel: `ext.${string}`]: ExtPluginEvent;
+}
+type ConnectionState = "idle" | "connecting" | "ready" | "reconnecting" | "closed";
+interface RealtimeError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+}
+interface RealtimeClientOptions {
+    /** wss URL of the gateway, e.g. `wss://grandbet.example/realtime`. */
+    readonly url: string;
+    /**
+     * How the SDK obtains a handshake credential. Return `{ ticket }` (fetched from
+     * `POST /realtime/ticket`) or nothing to rely on a same-site HttpOnly cookie.
+     * Called again on every reconnect so an expiring credential never drops the socket.
+     */
+    readonly getAuthCredential?: () => Promise<{
+        ticket: string;
+    } | void>;
+    /**
+     * Snapshot read run after every (re)connect to reconcile missed state. The socket
+     * accelerates; REST is the truth. The SDK calls this; the app supplies the reads.
+     */
+    readonly resync?: (ctx: {
+        since?: string;
+    }) => Promise<void>;
+    /** Reconnect backoff. Defaults: base 500ms, factor 2, max 15s, full jitter. */
+    readonly backoff?: {
+        readonly baseMs?: number;
+        readonly maxMs?: number;
+        readonly factor?: number;
+    };
+    /** Override only for testing; the server dictates heartbeat in the `ready` frame. */
+    readonly heartbeatMs?: number;
+    /** Inject a WebSocket implementation (Node `ws`); defaults to the platform global. */
+    readonly WebSocketImpl?: WebSocketImpl;
+    /** Max remembered eventIds for dedupe. Default 512. */
+    readonly dedupeWindow?: number;
+}
+type Unsubscribe = () => void;
+interface RealtimeClient {
+    readonly state: ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    on<C extends RealtimeChannel>(channel: C, handler: (event: ChannelEventMap[C]) => void): Unsubscribe;
+    subscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    unsubscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    withSubscription<T>(channels: readonly RealtimeChannel[], scope: () => Promise<T>): Promise<T>;
+    activeChannels(): readonly RealtimeChannel[];
+    onStateChange(handler: (state: ConnectionState) => void): Unsubscribe;
+    onError(handler: (error: RealtimeError) => void): Unsubscribe;
+}
+type CreateRealtimeClient = (options: RealtimeClientOptions) => RealtimeClient;
+interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+type WebSocketImpl = new (url: string) => WebSocketLike;
+
+export { type BonusEvent as B, type ChannelEventMap as C, type DepositStatus as D, type ExtChannel as E, type GamingEvent as G, type MinorUnits as M, type PlayerEvent as P, REALTIME_CHANNELS as R, type Unsubscribe as U, type WalletBalanceEvent as W, type ConnectionState as a, type CoreRealtimeChannel as b, type ExtPluginEvent as c, type RealtimeChannel as d, type RealtimeError as e, type WalletBucket as f, type WalletDepositEvent as g, type WalletWithdrawalEvent as h, isExtChannel as i, type WebSocketImpl as j, type RealtimeClientOptions as k, type RealtimeClient as l, type CreateRealtimeClient as m, type RealtimeEventMeta as n, type WebSocketLike as o, type WithdrawalStatus as p };

package/dist/contract-DtFe4bRy.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Canonical realtime surface, aligned with the runtime's
+ * `docs/realtime-sdk-contract.ts` (the agreed contract; verbatim copy kept in
+ * `contract.vendored.ts` for diffing — `pnpm sync:contract` refreshes it). We
+ * ALIGN with that file — do not fork it. Naming note: the runtime doc calls the
+ * core-channel union `RealtimeChannel` and the core+ext union
+ * `AnyRealtimeChannel`; here they are {@link CoreRealtimeChannel} and
+ * {@link RealtimeChannel} respectively. The plugin `ext.*` channel family
+ * ({@link ExtChannel}, {@link ExtPluginEvent}) is part of the runtime contract.
+ * SDK-local additions: {@link WebSocketImpl}, `dedupeWindow`,
+ * {@link REALTIME_CHANNELS}, {@link isExtChannel}.
+ *
+ * Money amounts are scale-4 integer minor units (see `core/money.ts`).
+ */
+/** Statically-known core channels. Strings are stable, versioned, and authz-checked server-side. */
+type CoreRealtimeChannel = "wallet.balance" | "wallet.deposit" | "wallet.withdrawal" | "gaming" | "bonus" | "player";
+/**
+ * Channel family published by tenant-enabled plugins, e.g. `"ext.cashback"`.
+ * Which ones exist comes from the ext catalog (`ExtCatalogPlugin.channels`);
+ * subscribing for a non-enabled plugin is rejected by the gateway exactly like
+ * an unknown channel.
+ */
+type ExtChannel = `ext.${string}`;
+/** Logical channels: the static core set plus the dynamic plugin family. */
+type RealtimeChannel = CoreRealtimeChannel | ExtChannel;
+/**
+ * Narrow a plain string (e.g. an entry of `ExtCatalogPlugin.channels`, which the
+ * wire contract types as `string[]`) to a subscribable {@link ExtChannel}.
+ */
+declare function isExtChannel(value: string): value is ExtChannel;
+/**
+ * All statically-known subscribable channels, for runtime validation/iteration.
+ * Plugin `ext.*` channels are dynamic (discovered via the ext catalog) and
+ * intentionally not listed.
+ */
+declare const REALTIME_CHANNELS: readonly CoreRealtimeChannel[];
+type WalletBucket = "cash" | "bonus" | "locked";
+/** Minor units (scale-4 integer). Never do money math on the client beyond display. */
+type MinorUnits = number;
+/** Common envelope present on every server → client business event. */
+interface RealtimeEventMeta {
+    readonly event: string;
+    readonly eventId: string;
+    readonly v: number;
+    readonly occurredAt: string;
+    readonly tenantId: string;
+}
+interface WalletBalanceEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.balance";
+    readonly data: {
+        readonly currency: string;
+        readonly balances: Readonly<Record<WalletBucket, MinorUnits>>;
+        readonly change: {
+            readonly bucket: WalletBucket;
+            readonly direction: "credit" | "debit";
+            readonly amount: MinorUnits;
+            readonly reason: string;
+        };
+    };
+}
+type DepositStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";
+interface WalletDepositEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.deposit";
+    readonly data: {
+        readonly depositId: string;
+        readonly status: DepositStatus;
+        readonly amount: MinorUnits;
+        readonly currency: string;
+    };
+}
+type WithdrawalStatus = "requested" | "approved" | "rejected" | "processing" | "completed" | "reversed" | "cancelled";
+interface WalletWithdrawalEvent extends RealtimeEventMeta {
+    readonly channel: "wallet.withdrawal";
+    readonly data: {
+        readonly withdrawalId: string;
+        readonly status: WithdrawalStatus;
+        readonly amount: MinorUnits;
+        readonly currency: string;
+    };
+}
+interface GamingEvent extends RealtimeEventMeta {
+    readonly channel: "gaming";
+    readonly data: {
+        readonly roundId: string;
+        readonly betId?: string;
+        readonly status: "placed" | "settled" | "rolled_back" | "round_closed";
+        /** Internal catalog game id — map to a display name from your catalog. */
+        readonly gameId?: string;
+        /** Provider key that produced the round (e.g. `"slotserv"`). */
+        readonly provider?: string;
+        /** Wager amount, present on `placed`. */
+        readonly betAmount?: MinorUnits;
+        /** Payout, present on `settled`. */
+        readonly winAmount?: MinorUnits;
+        readonly currency?: string;
+    };
+}
+interface BonusEvent extends RealtimeEventMeta {
+    readonly channel: "bonus";
+    readonly data: {
+        readonly bonusId: string;
+        readonly status: "granted" | "revoked";
+        readonly amount?: MinorUnits;
+        readonly currency?: string;
+        readonly reason?: string;
+    };
+}
+interface PlayerEvent extends RealtimeEventMeta {
+    readonly channel: "player";
+    readonly data: {
+        readonly change: "password_changed" | "social_linked" | "social_unlinked" | "account_locked" | "email_verified" | "phone_verified" | "session_revoked" | "kyc_status_changed" | "kyc_documents_requested" | "limit_changed" | "self_excluded" | "reality_check";
+        readonly data?: Readonly<Record<string, string | number | boolean | null>>;
+    };
+}
+/**
+ * An event published by a plugin on its `ext.<pluginKey>` channel. The standard
+ * realtime envelope applies (incl. `eventId` dedupe); `data.type` is the
+ * plugin-defined event type (e.g. `"cashback.claimed"`) and `data.payload` is
+ * opaque to the SDK.
+ */
+interface ExtPluginEvent extends RealtimeEventMeta {
+    readonly channel: ExtChannel;
+    readonly data: {
+        readonly type: string;
+        readonly payload: unknown;
+    };
+}
+/** Maps a channel name to its event payload type, for type-safe `on(...)`. */
+interface ChannelEventMap {
+    "wallet.balance": WalletBalanceEvent;
+    "wallet.deposit": WalletDepositEvent;
+    "wallet.withdrawal": WalletWithdrawalEvent;
+    gaming: GamingEvent;
+    bonus: BonusEvent;
+    player: PlayerEvent;
+    [channel: `ext.${string}`]: ExtPluginEvent;
+}
+type ConnectionState = "idle" | "connecting" | "ready" | "reconnecting" | "closed";
+interface RealtimeError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+}
+interface RealtimeClientOptions {
+    /** wss URL of the gateway, e.g. `wss://grandbet.example/realtime`. */
+    readonly url: string;
+    /**
+     * How the SDK obtains a handshake credential. Return `{ ticket }` (fetched from
+     * `POST /realtime/ticket`) or nothing to rely on a same-site HttpOnly cookie.
+     * Called again on every reconnect so an expiring credential never drops the socket.
+     */
+    readonly getAuthCredential?: () => Promise<{
+        ticket: string;
+    } | void>;
+    /**
+     * Snapshot read run after every (re)connect to reconcile missed state. The socket
+     * accelerates; REST is the truth. The SDK calls this; the app supplies the reads.
+     */
+    readonly resync?: (ctx: {
+        since?: string;
+    }) => Promise<void>;
+    /** Reconnect backoff. Defaults: base 500ms, factor 2, max 15s, full jitter. */
+    readonly backoff?: {
+        readonly baseMs?: number;
+        readonly maxMs?: number;
+        readonly factor?: number;
+    };
+    /** Override only for testing; the server dictates heartbeat in the `ready` frame. */
+    readonly heartbeatMs?: number;
+    /** Inject a WebSocket implementation (Node `ws`); defaults to the platform global. */
+    readonly WebSocketImpl?: WebSocketImpl;
+    /** Max remembered eventIds for dedupe. Default 512. */
+    readonly dedupeWindow?: number;
+}
+type Unsubscribe = () => void;
+interface RealtimeClient {
+    readonly state: ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    on<C extends RealtimeChannel>(channel: C, handler: (event: ChannelEventMap[C]) => void): Unsubscribe;
+    subscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    unsubscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    withSubscription<T>(channels: readonly RealtimeChannel[], scope: () => Promise<T>): Promise<T>;
+    activeChannels(): readonly RealtimeChannel[];
+    onStateChange(handler: (state: ConnectionState) => void): Unsubscribe;
+    onError(handler: (error: RealtimeError) => void): Unsubscribe;
+}
+type CreateRealtimeClient = (options: RealtimeClientOptions) => RealtimeClient;
+interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+type WebSocketImpl = new (url: string) => WebSocketLike;
+
+export { type BonusEvent as B, type ChannelEventMap as C, type DepositStatus as D, type ExtChannel as E, type GamingEvent as G, type MinorUnits as M, type PlayerEvent as P, REALTIME_CHANNELS as R, type Unsubscribe as U, type WalletBalanceEvent as W, type ConnectionState as a, type CoreRealtimeChannel as b, type ExtPluginEvent as c, type RealtimeChannel as d, type RealtimeError as e, type WalletBucket as f, type WalletDepositEvent as g, type WalletWithdrawalEvent as h, isExtChannel as i, type WebSocketImpl as j, type RealtimeClientOptions as k, type RealtimeClient as l, type CreateRealtimeClient as m, type RealtimeEventMeta as n, type WebSocketLike as o, type WithdrawalStatus as p };