@connect4/contracts

Versioned public protocol contracts shared by Connect4 clients and backend.

The protocol version in this release is 4. Version 4 uses one authoritative game snapshot, removes duplicated viewer-specific fields, and adds the game:surrender command.

Contents

• Native WebSocket event names and protocol version.
• Client-to-server and server-to-client typed event maps.
• Generic typed message envelopes.
• Zod schemas for runtime validation.
• HTTP authentication-session request and response schemas.
• Public protocol enums and error codes.
• Bot strategy values shared by matchmaking and gameplay (REMOTE_MINIMAX, REMOTE_ALPHAGO, and REMOTE_MCTS). All bot computation runs in BotConnect4Live.

This package contains no NestJS code, persistence model, repository, business logic, or frontend-specific implementation.

Usage

Install the package together with Zod:

npm install @connect4/contracts zod

import {
  GameMovePayloadSchema,
  WsEvent,
  type ClientMessage,
} from '@connect4/contracts';

const message: ClientMessage<typeof WsEvent.GameMove> = {
  version: '4',
  event: WsEvent.GameMove,
  data: {
    gameId: 'game-id',
    column: 3,
    stateVersion: 0,
  },
};

GameMovePayloadSchema.parse(message.data);

matchmaking:matched contains the game id, mode, and both player profiles. game:state is the authoritative reconnectable snapshot. The client derives its own disc and opponent from players using the authenticated user id. game:finished is a terminal notification; result:state carries the complete result records for both players.

All current bot profiles are computed by the backend BotConnect4Live service. Clients never calculate or submit a bot move.

To surrender, send game:surrender with { gameId }. The server emits the same terminal flow as other endgame reasons.

To load the authenticated player's recent matches, send history:get with {}. The server replies with history:state and at most the 10 most recent completed games. This is a compact summary; replay details remain a separate permission-controlled operation.

leaderboard:get accepts page: 1 or page: 2. The two pages cover at most the top 50 entries (20 entries on page 1 and 30 entries on page 2).

The package follows semantic versioning. Protocol breaking changes require a major version.

Authentication session

Clients create a game session through one HTTP endpoint, POST /auth/session. The request is a strict discriminated union on provider: GUEST accepts an installation id and an optional rotated guest session credential; CRAZYGAMES accepts the platform JWT; and TIKTOK accepts the temporary silent-login code. The response always returns a short-lived internal access token for the WebSocket auth:login command. Only a GUEST response includes the next opaque guest session credential.

import {
  AuthenticationSessionRequestSchema,
  AuthenticationSessionResponseSchema,
} from '@connect4/contracts';

Platform credentials are never valid WebSocket credentials. Each client validates the response before using its internal access token for the existing WebSocket authentication flow.

Cocos Creator runtime

Cocos Creator 2.4 clients must import the runtime-safe core entry:

import { WsEvent, createClientMessage } from '@connect4/contracts/core';

The core entry contains protocol constants, enums, payload types, and envelope helpers. It has no Zod runtime dependency. The package root remains the backend entry and includes Zod schemas for runtime validation.

The package also ships a CommonJS-compatible dist/core.js artifact because Cocos Creator 2.4's quick compiler resolves the file path directly instead of applying npm exports conditions. Modern ESM consumers continue to use the ESM core export automatically.