@pokertools/types 1.0.1 → 1.0.6

package/dist/WebSocketMessages.d.ts

@@ -0,0 +1,232 @@
+import { PublicState } from "./PublicState";
+/**
+ * WebSocket Protocol Definitions
+ *
+ * This file defines the complete WebSocket message protocol for real-time
+ * poker game communication. All messages are strongly typed discriminated unions.
+ */
+/**
+ * Join a table's real-time updates
+ */
+export interface JoinTableMessage {
+    readonly type: "JOIN";
+    readonly tableId: string;
+    readonly requestId?: string;
+}
+/**
+ * Leave a table's real-time updates
+ */
+export interface LeaveTableMessage {
+    readonly type: "LEAVE";
+    readonly tableId: string;
+    readonly requestId?: string;
+}
+/**
+ * Application-level heartbeat (in addition to WebSocket ping/pong)
+ * Useful for detecting issues at application layer
+ */
+export interface PingMessage {
+    readonly type: "PING";
+    readonly requestId: string;
+    readonly timestamp?: number;
+}
+/**
+ * Union of all client-to-server messages
+ */
+export type ClientMessage = JoinTableMessage | LeaveTableMessage | PingMessage;
+/**
+ * State snapshot sent when client joins a table
+ * or when requested via REST API
+ */
+export interface SnapshotMessage {
+    readonly type: "SNAPSHOT";
+    readonly tableId: string;
+    readonly state: PublicState;
+    readonly version: number;
+    readonly timestamp: number;
+}
+/**
+ * Lightweight notification that state has changed
+ * Client should fetch full state via REST if needed
+ */
+export interface StateUpdateMessage {
+    readonly type: "STATE_UPDATE";
+    readonly tableId: string;
+    readonly version: number;
+    readonly timestamp: number;
+}
+/**
+ * Error message
+ */
+export interface ErrorMessage {
+    readonly type: "ERROR";
+    readonly code: string;
+    readonly message: string;
+    readonly requestId?: string;
+    readonly context?: Record<string, unknown>;
+}
+/**
+ * Acknowledgment of successful operation
+ */
+export interface AckMessage {
+    readonly type: "ACK";
+    readonly requestId: string;
+    readonly message?: string;
+}
+/**
+ * Pong response to client PING
+ */
+export interface PongMessage {
+    readonly type: "PONG";
+    readonly requestId: string;
+    readonly timestamp: number;
+}
+/**
+ * Player action notification (informational only)
+ * Not required for state sync, but useful for animations/UX
+ */
+export interface ActionNotificationMessage {
+    readonly type: "ACTION";
+    readonly tableId: string;
+    readonly playerId: string;
+    readonly actionType: string;
+    readonly amount?: number;
+    readonly timestamp: number;
+}
+/**
+ * Union of all server-to-client messages
+ */
+export type ServerMessage = SnapshotMessage | StateUpdateMessage | ErrorMessage | AckMessage | PongMessage | ActionNotificationMessage;
+export declare function isClientMessage(msg: unknown): msg is ClientMessage;
+export declare function isJoinMessage(msg: ClientMessage): msg is JoinTableMessage;
+export declare function isLeaveMessage(msg: ClientMessage): msg is LeaveTableMessage;
+export declare function isPingMessage(msg: ClientMessage): msg is PingMessage;
+export declare function isServerMessage(msg: unknown): msg is ServerMessage;
+import { z } from "zod";
+export declare const JoinTableMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"JOIN">;
+    tableId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const LeaveTableMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"LEAVE">;
+    tableId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PingMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"PING">;
+    requestId: z.ZodString;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"JOIN">;
+    tableId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"LEAVE">;
+    tableId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"PING">;
+    requestId: z.ZodString;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+/**
+ * Utility to parse and validate a client message
+ */
+export declare function parseClientMessage(data: unknown): ClientMessage;
+/**
+ * Safe parser that returns result object instead of throwing
+ */
+export declare function safeParseClientMessage(data: unknown): {
+    success: true;
+    data: ClientMessage;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+export declare const SnapshotMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SNAPSHOT">;
+    tableId: z.ZodString;
+    state: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    version: z.ZodNumber;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export declare const StateUpdateMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"STATE_UPDATE">;
+    tableId: z.ZodString;
+    version: z.ZodNumber;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ERROR">;
+    code: z.ZodString;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const AckMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ACK">;
+    requestId: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PongMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"PONG">;
+    requestId: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ActionNotificationMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ACTION">;
+    tableId: z.ZodString;
+    playerId: z.ZodString;
+    actionType: z.ZodString;
+    amount: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"SNAPSHOT">;
+    tableId: z.ZodString;
+    state: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    version: z.ZodNumber;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"STATE_UPDATE">;
+    tableId: z.ZodString;
+    version: z.ZodNumber;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ERROR">;
+    code: z.ZodString;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ACK">;
+    requestId: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"PONG">;
+    requestId: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ACTION">;
+    tableId: z.ZodString;
+    playerId: z.ZodString;
+    actionType: z.ZodString;
+    amount: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>], "type">;
+/**
+ * Parse and validate a server message (throws on invalid)
+ */
+export declare function parseServerMessage(data: unknown): ServerMessage;
+/**
+ * Safe parser for server messages
+ */
+export declare function safeParseServerMessage(data: unknown): {
+    success: true;
+    data: ServerMessage;
+} | {
+    success: false;
+    error: z.ZodError;
+};

package/dist/WebSocketMessages.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerMessageSchema = exports.ActionNotificationMessageSchema = exports.PongMessageSchema = exports.AckMessageSchema = exports.ErrorMessageSchema = exports.StateUpdateMessageSchema = exports.SnapshotMessageSchema = exports.ClientMessageSchema = exports.PingMessageSchema = exports.LeaveTableMessageSchema = exports.JoinTableMessageSchema = void 0;
+exports.isClientMessage = isClientMessage;
+exports.isJoinMessage = isJoinMessage;
+exports.isLeaveMessage = isLeaveMessage;
+exports.isPingMessage = isPingMessage;
+exports.isServerMessage = isServerMessage;
+exports.parseClientMessage = parseClientMessage;
+exports.safeParseClientMessage = safeParseClientMessage;
+exports.parseServerMessage = parseServerMessage;
+exports.safeParseServerMessage = safeParseServerMessage;
+// ============================================================================
+// Type Guards
+// ============================================================================
+function isClientMessage(msg) {
+    if (typeof msg !== "object" || msg === null)
+        return false;
+    const { type } = msg;
+    return type === "JOIN" || type === "LEAVE" || type === "PING";
+}
+function isJoinMessage(msg) {
+    return msg.type === "JOIN";
+}
+function isLeaveMessage(msg) {
+    return msg.type === "LEAVE";
+}
+function isPingMessage(msg) {
+    return msg.type === "PING";
+}
+function isServerMessage(msg) {
+    if (typeof msg !== "object" || msg === null)
+        return false;
+    const { type } = msg;
+    return (type === "SNAPSHOT" ||
+        type === "STATE_UPDATE" ||
+        type === "ERROR" ||
+        type === "ACK" ||
+        type === "PONG" ||
+        type === "ACTION");
+}
+// ============================================================================
+// Zod Schemas for Runtime Validation
+// ============================================================================
+const zod_1 = require("zod");
+exports.JoinTableMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("JOIN"),
+    tableId: zod_1.z.string().min(1),
+    requestId: zod_1.z.string().optional(),
+});
+exports.LeaveTableMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("LEAVE"),
+    tableId: zod_1.z.string().min(1),
+    requestId: zod_1.z.string().optional(),
+});
+exports.PingMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("PING"),
+    requestId: zod_1.z.string().min(1),
+    timestamp: zod_1.z.number().optional(),
+});
+exports.ClientMessageSchema = zod_1.z.discriminatedUnion("type", [
+    exports.JoinTableMessageSchema,
+    exports.LeaveTableMessageSchema,
+    exports.PingMessageSchema,
+]);
+/**
+ * Utility to parse and validate a client message
+ */
+function parseClientMessage(data) {
+    return exports.ClientMessageSchema.parse(data);
+}
+/**
+ * Safe parser that returns result object instead of throwing
+ */
+function safeParseClientMessage(data) {
+    const result = exports.ClientMessageSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}
+// ============================================================================
+// Server Message Zod Schemas
+// ============================================================================
+exports.SnapshotMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("SNAPSHOT"),
+    tableId: zod_1.z.string().min(1),
+    state: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    version: zod_1.z.number(),
+    timestamp: zod_1.z.number(),
+});
+exports.StateUpdateMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("STATE_UPDATE"),
+    tableId: zod_1.z.string().min(1),
+    version: zod_1.z.number(),
+    timestamp: zod_1.z.number(),
+});
+exports.ErrorMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("ERROR"),
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    requestId: zod_1.z.string().optional(),
+    context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+exports.AckMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("ACK"),
+    requestId: zod_1.z.string(),
+    message: zod_1.z.string().optional(),
+});
+exports.PongMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("PONG"),
+    requestId: zod_1.z.string(),
+    timestamp: zod_1.z.number(),
+});
+exports.ActionNotificationMessageSchema = zod_1.z.object({
+    type: zod_1.z.literal("ACTION"),
+    tableId: zod_1.z.string().min(1),
+    playerId: zod_1.z.string(),
+    actionType: zod_1.z.string(),
+    amount: zod_1.z.number().optional(),
+    timestamp: zod_1.z.number(),
+});
+exports.ServerMessageSchema = zod_1.z.discriminatedUnion("type", [
+    exports.SnapshotMessageSchema,
+    exports.StateUpdateMessageSchema,
+    exports.ErrorMessageSchema,
+    exports.AckMessageSchema,
+    exports.PongMessageSchema,
+    exports.ActionNotificationMessageSchema,
+]);
+/**
+ * Parse and validate a server message (throws on invalid)
+ */
+function parseServerMessage(data) {
+    return exports.ServerMessageSchema.parse(data);
+}
+/**
+ * Safe parser for server messages
+ */
+function safeParseServerMessage(data) {
+    const result = exports.ServerMessageSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}

package/dist/api/auth.d.ts

@@ -0,0 +1,14 @@
+export interface LoginRequest {
+    message: string;
+    signature: `0x${string}`;
+}
+export interface LoginResponse {
+    token: string;
+    user: {
+        id: string;
+        username: string;
+    };
+}
+export interface NonceResponse {
+    nonce: string;
+}

package/dist/api/auth.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/common.d.ts

@@ -0,0 +1,10 @@
+export interface ApiErrorResponse {
+    error: string;
+    message?: string;
+    code?: string;
+}
+export interface SuccessResponse {
+    success: true;
+}
+export type GameMode = "CASH" | "TOURNAMENT";
+export type TableStatus = "WAITING" | "ACTIVE" | "FINISHED";

package/dist/api/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/tables.d.ts

@@ -0,0 +1,17 @@
+import { TableConfig } from "../Config";
+import { PublicState } from "../PublicState";
+import { TableStatus } from "./common";
+export interface TableListItem {
+    id: string;
+    name: string;
+    config: TableConfig;
+    status: TableStatus;
+}
+export interface GetTablesResponse {
+    tables: TableListItem[];
+}
+export interface StandRequest {
+}
+export interface TableStateResponse {
+    state: PublicState;
+}

package/dist/api/tables.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -2,6 +2,13 @@ export * from "./Player";
 export * from "./Pot";
 export * from "./Config";
 export * from "./Action";
+export * from "./ActionWhitelist";
 export * from "./GameState";
 export * from "./PublicState";
 export * from "./HandHistory";
+export * from "./schemas";
+export * from "./WebSocketMessages";
+export * from "./ErrorCodes";
+export * from "./api/common";
+export * from "./api/auth";
+export * from "./api/tables";

package/dist/index.js

@@ -19,6 +19,14 @@ __exportStar(require("./Player"), exports);
 __exportStar(require("./Pot"), exports);
 __exportStar(require("./Config"), exports);
 __exportStar(require("./Action"), exports);
+__exportStar(require("./ActionWhitelist"), exports);
 __exportStar(require("./GameState"), exports);
 __exportStar(require("./PublicState"), exports);
 __exportStar(require("./HandHistory"), exports);
+__exportStar(require("./schemas"), exports);
+__exportStar(require("./WebSocketMessages"), exports);
+__exportStar(require("./ErrorCodes"), exports);
+// API DTOs
+__exportStar(require("./api/common"), exports);
+__exportStar(require("./api/auth"), exports);
+__exportStar(require("./api/tables"), exports);