# **WECHESS** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 7 - Gameplay Service** This document is a part of a REST API guide for the wechess project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of gameplay ## Service Access Gameplay service management is handled through service specific base urls. Gameplay service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the gameplay service, the base URLs are: * **Preview:** `https://wechess.prw.mindbricks.com/gameplay-api` * **Staging:** `https://wechess-stage.mindbricks.co/gameplay-api` * **Production:** `https://wechess.mindbricks.co/gameplay-api` ## Scope **Gameplay Service Description** Service for managing real-time chess games, matchmaking, move history, and private invitations, including lifecycle management (mutual game-save/resume, admin termination), supporting both guest and registered users. Enables API access for reviewing games, enforcing moderation actions, and tracking game results. Gameplay service provides apis and business logic for following data objects in wechess application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`chessGame` Data Object**: **`chessGameMove` Data Object**: Represents a single move in a chess game (FIDE-compliant SAN/LAN representation, timestamp, player, time, move number). **`chessGameInvitation` Data Object**: An invitation for a private chess game between two players; status tracked; expires at set time or when accepted/declined. **`customBoard` Data Object**: **`boardTheme` Data Object**: **`userPreference` Data Object**: **`gameHubMessage` Data Object**: Auto-generated message DataObject for the gameHub RealtimeHub. Stores all messages with typed content payloads. **`gameHubModeration` Data Object**: Auto-generated moderation DataObject for the gameHub RealtimeHub. Stores block and silence actions for room-level user moderation. ## Gameplay Service Frontend Description By The Backend Architect Focuses on all server-side logic for chess sessions, matchmaking flows, move recording, lifecycle events, and admin moderation features. Games may be public (matched) or private (via invitation code); history and result calculations are managed herein. Guests are supported in games but leaderboards/stats are maintained only for registered players (handled by leaderboard service). Admin UIs use advanced query/list/review APIs for game and event history. Special actions are available for mutual save/resume agreements and forced admin interrupts. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## ChessGame Data Object ### ChessGame Data Object Properties ChessGame data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `playerWhiteId` | ID | false | Yes | No | User ID of the player assigned White (guest or registered); references auth:user.id. | | `playerBlackId` | ID | | No | No | - | | `createdById` | ID | false | Yes | No | ID of the user who created the game (can be a guest or registered user). | | `status` | Enum | false | Yes | No | Lifecycle status: pending, active, paused, completed, terminated | | `mode` | Enum | false | Yes | No | Game mode: public (matchmaking), private (invitation-based) | | `invitationCode` | String | | No | No | - | | `currentFEN` | String | false | Yes | No | Current board state in FEN notation for restoration/resume. | | `gameType` | Enum | false | Yes | No | Game type: timed, untimed, blitz, rapid | | `saveStatus` | Enum | false | Yes | No | Game mutual-saving: notSaveable, requested, paused (both agreed) | | `saveRequestWhite` | Boolean | false | No | No | Whether white has requested save/resume; mutual save when both true. | | `saveRequestBlack` | Boolean | false | No | No | Whether black has requested save/resume; mutual save when both true. | | `movedAt` | Date | false | No | No | Timestamp of last move (heartbeat/game activity). | | `result` | Enum | false | No | No | Game result/outcome: whiteWin, blackWin, draw, aborted | | `terminatedById` | ID | false | No | No | ID of administrator who forced terminated the game (if applicable). | | `reportStatus` | Enum | false | No | No | Moderation/review status: none, reported, underReview | | `guestPlayerWhite` | Boolean | false | No | No | True if white is a guest (not a registered user); needed to distinguish guest/registered in history. | | `guestPlayerBlack` | Boolean | false | No | No | True if black is a guest (not a registered user); needed to distinguish guest/registered in history. | | `initialFEN` | String | false | No | No | The starting FEN position when the game was created. Used to identify custom games. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [pending, active, paused, completed, terminated] - **mode**: [public, private] - **gameType**: [timed, untimed, blitz, rapid] - **saveStatus**: [notSaveable, requested, paused] - **result**: [whiteWin, blackWin, draw, aborted] - **reportStatus**: [none, reported, underReview] ### Relation Properties `playerWhiteId` `playerBlackId` `createdById` `terminatedById` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **playerWhiteId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **playerBlackId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **createdById**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **terminatedById**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `status` `invitationCode` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **status**: Enum has a filter named `status` - **invitationCode**: String has a filter named `invitationCode` ## ChessGameMove Data Object Represents a single move in a chess game (FIDE-compliant SAN/LAN representation, timestamp, player, time, move number). ### ChessGameMove Data Object Frontend Description By The Backend Architect Every legal move in a chess game is stored as its own chessGameMove. Only admins or participants can create (add) moves. Used for reconstructing history and post-game analysis. Move time is stored for potential time control. ### ChessGameMove Data Object Properties ChessGameMove data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `gameId` | ID | false | Yes | No | Reference to the chessGame this move belongs to. | | `moveNumber` | Integer | false | Yes | No | Move number (starting from 1 in each game). | | `moveNotation` | String | false | Yes | No | Chess move in either Standard Algebraic or Long Algebraic Notation (SAN/LAN). | | `moveTime` | Integer | false | No | No | Time in milliseconds since the previous move (for time control, etc.). | | `movedById` | ID | false | Yes | No | User ID of the player who made the move (guest/registered); references auth:user.id. | | `moveTimestamp` | Date | false | Yes | No | Timestamp when move was made. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `gameId` `movedById` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **gameId**: ID Relation to `chessGame`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **movedById**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `gameId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **gameId**: ID has a filter named `gameId` ## ChessGameInvitation Data Object An invitation for a private chess game between two players; status tracked; expires at set time or when accepted/declined. ### ChessGameInvitation Data Object Frontend Description By The Backend Architect Create chessGameInvitation for private games. Used to notify recipient, with acceptance establishing game session. Expiration is enforced. Sender/recipient are references to user (guest or registered). Invalidation logic on decline/cancel/expiry. Invitation code is managed with target game. ### ChessGameInvitation Data Object Properties ChessGameInvitation data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `gameId` | ID | false | Yes | No | Game this invitation is linked to. | | `senderId` | ID | | Yes | No | - | | `recipientId` | ID | | Yes | No | - | | `status` | Enum | | Yes | No | - | | `expiresAt` | Date | false | Yes | No | Expiration date/time for the invitation. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [pending, accepted, declined, cancelled] ### Relation Properties `gameId` `senderId` `recipientId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **gameId**: ID Relation to `chessGame`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **senderId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **recipientId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `senderId` `recipientId` `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **senderId**: ID has a filter named `senderId` - **recipientId**: ID has a filter named `recipientId` - **status**: Enum has a filter named `status` ## CustomBoard Data Object ### CustomBoard Data Object Properties CustomBoard data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `name` | String | false | Yes | No | Name of the custom board position | | `fen` | String | false | Yes | No | FEN string representing the board position | | `description` | Text | false | No | No | Optional description of the custom board | | `isPublished` | Boolean | | Yes | No | - | | `category` | Enum | | Yes | No | - | | `createdById` | ID | | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **category**: [endgame, opening, puzzle, custom] ### Relation Properties `createdById` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **createdById**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `isPublished` `category` `createdById` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **isPublished**: Boolean has a filter named `isPublished` - **category**: Enum has a filter named `category` - **createdById**: ID has a filter named `createdById` ## BoardTheme Data Object ### BoardTheme Data Object Properties BoardTheme data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `name` | String | false | Yes | No | Theme display name | | `lightSquare` | String | false | Yes | No | Hex color for light squares | | `darkSquare` | String | false | Yes | No | Hex color for dark squares | | `isPublished` | Boolean | false | No | No | Whether the theme is publicly visible | | `createdById` | ID | false | Yes | No | User who created this theme | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `createdById` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **createdById**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `isPublished` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **isPublished**: Boolean has a filter named `isPublished` ## UserPreference Data Object ### UserPreference Data Object Properties UserPreference data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `userId` | ID | false | Yes | No | The user this preferences record belongs to | | `activeThemeId` | String | false | No | No | ID of the currently selected board theme (preset ID or custom theme ID) | | `soundEnabled` | Boolean | false | No | No | Whether game sounds are enabled | | `showAnimations` | Boolean | false | No | No | Whether board animations are shown | | `boardOrientation` | Enum | false | No | No | Default board orientation preference | | `premoveEnabled` | Boolean | false | No | No | Whether premove feature is enabled | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **boardOrientation**: [auto, white, black] ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ## GameHubMessage Data Object Auto-generated message DataObject for the gameHub RealtimeHub. Stores all messages with typed content payloads. ### GameHubMessage Data Object Properties GameHubMessage data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `roomId` | ID | false | Yes | No | Reference to the room this message belongs to | | `senderId` | ID | false | No | No | Reference to the user who sent this message | | `senderName` | String | false | No | No | Display name of the sender (denormalized from user profile at send time) | | `senderAvatar` | String | false | No | No | Avatar URL of the sender (denormalized from user profile at send time) | | `messageType` | Enum | false | Yes | No | Content type discriminator for this message | | `content` | Object | false | Yes | No | Type-specific content payload (structure depends on messageType) | | `timestamp` | | false | No | No | Message creation time | | `status` | Enum | false | No | No | Message moderation status | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **messageType**: [text, system, chessMove, drawOffer, drawAccepted, drawDeclined, resignation, saveRequest, saveAccepted, saveDeclined, resumeRequest, resumeAccepted, resumeDeclined] - **status**: [pending, approved, rejected] ### Filter Properties `roomId` `senderId` `senderName` `senderAvatar` `messageType` `content` `timestamp` `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **roomId**: ID has a filter named `roomId` - **senderId**: ID has a filter named `senderId` - **senderName**: String has a filter named `senderName` - **senderAvatar**: String has a filter named `senderAvatar` - **messageType**: Enum has a filter named `messageType` - **content**: Object has a filter named `content` - **timestamp**: has a filter named `timestamp` - **status**: Enum has a filter named `status` ## GameHubModeration Data Object Auto-generated moderation DataObject for the gameHub RealtimeHub. Stores block and silence actions for room-level user moderation. ### GameHubModeration Data Object Properties GameHubModeration data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `roomId` | ID | false | Yes | No | Reference to the room where the moderation action applies | | `userId` | ID | false | Yes | No | The user who is blocked or silenced | | `action` | Enum | false | Yes | No | Moderation action type | | `reason` | Text | false | No | No | Optional reason for the moderation action | | `duration` | Integer | false | No | No | Duration in seconds. 0 means permanent | | `expiresAt` | | false | No | No | Expiry timestamp. Null means permanent | | `issuedBy` | ID | false | No | No | The moderator who issued the action | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **action**: [blocked, silenced] ### Relation Properties `roomId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **roomId**: ID Relation to `chessGame`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `roomId` `userId` `action` `reason` `duration` `expiresAt` `issuedBy` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **roomId**: ID has a filter named `roomId` - **userId**: ID has a filter named `userId` - **action**: Enum has a filter named `action` - **reason**: Text has a filter named `reason` - **duration**: Integer has a filter named `duration` - **expiresAt**: has a filter named `expiresAt` - **issuedBy**: ID has a filter named `issuedBy` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### ChessGame Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createGame` | `/v1/game` | Yes | | Update | `updateGame` | `/v1/game/:chessGameId` | Yes | | Delete | `deleteGame` | `/v1/game/:chessGameId` | Yes | | Get | `getGame` | `/v1/game/:chessGameId` | Yes | | List | `listGames` | `/v1/games` | Yes | ### ChessGameMove Default APIs **Display Label Property:** `moveNotation` — Use this property as the human-readable label when displaying records of this data object (e.g., in dropdowns, references). | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createGameMove` | `/v1/gamemove` | Yes | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | _none_ | - | Auto | | List | `listGameMoves` | `/v1/gamemoves` | Yes | ### ChessGameInvitation Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createGameInvitation` | `/v1/gameinvitation` | Yes | | Update | `updateGameInvitation` | `/v1/gameinvitation/:chessGameInvitationId` | Yes | | Delete | `deleteGameInvitation` | `/v1/gameinvitation/:chessGameInvitationId` | Auto | | Get | _none_ | - | Auto | | List | `listGameInvitations` | `/v1/gameinvitations` | Yes | ### CustomBoard Default APIs **Display Label Property:** `name` — Use this property as the human-readable label when displaying records of this data object (e.g., in dropdowns, references). | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createCustomBoard` | `/v1/customboards` | Yes | | Update | `updateCustomBoard` | `/v1/customboards/:customBoardId` | Yes | | Delete | `deleteCustomBoard` | `/v1/customboards/:customBoardId` | Yes | | Get | `getCustomBoard` | `/v1/customboards/:customBoardId` | Yes | | List | `listCustomBoards` | `/v1/customboards` | Yes | ### BoardTheme Default APIs **Display Label Property:** `name` — Use this property as the human-readable label when displaying records of this data object (e.g., in dropdowns, references). | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createBoardTheme` | `/v1/boardthemes` | Yes | | Update | `updateBoardTheme` | `/v1/boardthemes/:boardThemeId` | Yes | | Delete | `deleteBoardTheme` | `/v1/boardthemes/:boardThemeId` | Yes | | Get | _none_ | - | Auto | | List | `listBoardThemes` | `/v1/boardthemes` | Yes | ### UserPreference Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createUserPreference` | `/v1/userpreferences` | Yes | | Update | `updateUserPreference` | `/v1/userpreferences/:userPreferenceId` | Yes | | Delete | _none_ | - | Auto | | Get | `getUserPreference` | `/v1/userpreferences/:userPreferenceId` | Yes | | List | `listUserPreferences` | `/v1/userpreferences` | Yes | ### GameHubMessage Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | `updateGameHubMessage` | `/v1/v1/gameHub-messages/:id` | Yes | | Delete | `deleteGameHubMessage` | `/v1/v1/gameHub-messages/:id` | Yes | | Get | `getGameHubMessage` | `/v1/v1/gameHub-messages/:id` | Yes | | List | `listGameHubMessages` | `/v1/v1/gameHub-messages` | Yes | ### GameHubModeration Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | _none_ | - | Auto | | List | _none_ | - | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Create Game` API **[Default create API]** — This is the designated default `create` API for the `chessGame` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Starts a new chess game session (public or private). Sets up all initial state, assigns player roles, and sets mode. **API Frontend Description By The Backend Architect** Called when matchmaking or private game is created. Invited/private games have invitationCode. Only logged-in users (guest or registered) can create games. Raise event for gameCreated for notification/bff. **Rest Route** The `createGame` API REST controller can be triggered via the following route: `/v1/game` **Rest Request Parameters** The `createGame` api has got 18 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | playerWhiteId | ID | true | request.body?.["playerWhiteId"] | | playerBlackId | ID | false | request.body?.["playerBlackId"] | | createdById | ID | true | request.body?.["createdById"] | | status | Enum | true | request.body?.["status"] | | mode | Enum | true | request.body?.["mode"] | | invitationCode | String | false | request.body?.["invitationCode"] | | currentFEN | String | true | request.body?.["currentFEN"] | | gameType | Enum | true | request.body?.["gameType"] | | saveStatus | Enum | true | request.body?.["saveStatus"] | | saveRequestWhite | Boolean | false | request.body?.["saveRequestWhite"] | | saveRequestBlack | Boolean | false | request.body?.["saveRequestBlack"] | | movedAt | Date | false | request.body?.["movedAt"] | | result | Enum | false | request.body?.["result"] | | terminatedById | ID | false | request.body?.["terminatedById"] | | reportStatus | Enum | false | request.body?.["reportStatus"] | | guestPlayerWhite | Boolean | false | request.body?.["guestPlayerWhite"] | | guestPlayerBlack | Boolean | false | request.body?.["guestPlayerBlack"] | | initialFEN | String | false | request.body?.["initialFEN"] | **playerWhiteId** : User ID of the player assigned White (guest or registered); references auth:user.id. **playerBlackId** : **createdById** : ID of the user who created the game (can be a guest or registered user). **status** : Lifecycle status: pending, active, paused, completed, terminated **mode** : Game mode: public (matchmaking), private (invitation-based) **invitationCode** : **currentFEN** : Current board state in FEN notation for restoration/resume. **gameType** : Game type: timed, untimed, blitz, rapid **saveStatus** : Game mutual-saving: notSaveable, requested, paused (both agreed) **saveRequestWhite** : Whether white has requested save/resume; mutual save when both true. **saveRequestBlack** : Whether black has requested save/resume; mutual save when both true. **movedAt** : Timestamp of last move (heartbeat/game activity). **result** : Game result/outcome: whiteWin, blackWin, draw, aborted **terminatedById** : ID of administrator who forced terminated the game (if applicable). **reportStatus** : Moderation/review status: none, reported, underReview **guestPlayerWhite** : True if white is a guest (not a registered user); needed to distinguish guest/registered in history. **guestPlayerBlack** : True if black is a guest (not a registered user); needed to distinguish guest/registered in history. **initialFEN** : The starting FEN position when the game was created. Used to identify custom games. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/game** ```js axios({ method: 'POST', url: '/v1/game', data: { playerWhiteId:"ID", playerBlackId:"ID", createdById:"ID", status:"Enum", mode:"Enum", invitationCode:"String", currentFEN:"String", gameType:"Enum", saveStatus:"Enum", saveRequestWhite:"Boolean", saveRequestBlack:"Boolean", movedAt:"Date", result:"Enum", terminatedById:"ID", reportStatus:"Enum", guestPlayerWhite:"Boolean", guestPlayerBlack:"Boolean", initialFEN:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGame", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "chessGame": { "id": "ID", "playerWhiteId": "ID", "playerBlackId": "ID", "createdById": "ID", "status": "Enum", "status_idx": "Integer", "mode": "Enum", "mode_idx": "Integer", "invitationCode": "String", "currentFEN": "String", "gameType": "Enum", "gameType_idx": "Integer", "saveStatus": "Enum", "saveStatus_idx": "Integer", "saveRequestWhite": "Boolean", "saveRequestBlack": "Boolean", "movedAt": "Date", "result": "Enum", "result_idx": "Integer", "terminatedById": "ID", "reportStatus": "Enum", "reportStatus_idx": "Integer", "guestPlayerWhite": "Boolean", "guestPlayerBlack": "Boolean", "initialFEN": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Game` API **[Default update API]** — This is the designated default `update` API for the `chessGame` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Updates chess game state including board position, status, save flags etc. Auth: only participants or admin. **API Frontend Description By The Backend Architect** Used for updating board state, status, mutual saving, etc. Most fields are read-only after game completion/termination except by admin. Raise event for gameUpdated for notification/bff. **Rest Route** The `updateGame` API REST controller can be triggered via the following route: `/v1/game/:chessGameId` **Rest Request Parameters** The `updateGame` api has got 13 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | chessGameId | ID | true | request.params?.["chessGameId"] | | playerBlackId | ID | | request.body?.["playerBlackId"] | | status | Enum | false | request.body?.["status"] | | currentFEN | String | false | request.body?.["currentFEN"] | | saveStatus | Enum | false | request.body?.["saveStatus"] | | saveRequestWhite | Boolean | false | request.body?.["saveRequestWhite"] | | saveRequestBlack | Boolean | false | request.body?.["saveRequestBlack"] | | movedAt | Date | false | request.body?.["movedAt"] | | result | Enum | false | request.body?.["result"] | | terminatedById | ID | false | request.body?.["terminatedById"] | | reportStatus | Enum | false | request.body?.["reportStatus"] | | guestPlayerWhite | Boolean | false | request.body?.["guestPlayerWhite"] | | guestPlayerBlack | Boolean | false | request.body?.["guestPlayerBlack"] | **chessGameId** : This id paremeter is used to select the required data object that will be updated **playerBlackId** : **status** : Lifecycle status: pending, active, paused, completed, terminated **currentFEN** : Current board state in FEN notation for restoration/resume. **saveStatus** : Game mutual-saving: notSaveable, requested, paused (both agreed) **saveRequestWhite** : Whether white has requested save/resume; mutual save when both true. **saveRequestBlack** : Whether black has requested save/resume; mutual save when both true. **movedAt** : Timestamp of last move (heartbeat/game activity). **result** : Game result/outcome: whiteWin, blackWin, draw, aborted **terminatedById** : ID of administrator who forced terminated the game (if applicable). **reportStatus** : Moderation/review status: none, reported, underReview **guestPlayerWhite** : True if white is a guest (not a registered user); needed to distinguish guest/registered in history. **guestPlayerBlack** : True if black is a guest (not a registered user); needed to distinguish guest/registered in history. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/game/:chessGameId** ```js axios({ method: 'PATCH', url: `/v1/game/${chessGameId}`, data: { playerBlackId:"ID", status:"Enum", currentFEN:"String", saveStatus:"Enum", saveRequestWhite:"Boolean", saveRequestBlack:"Boolean", movedAt:"Date", result:"Enum", terminatedById:"ID", reportStatus:"Enum", guestPlayerWhite:"Boolean", guestPlayerBlack:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGame", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "chessGame": { "id": "ID", "playerWhiteId": "ID", "playerBlackId": "ID", "createdById": "ID", "status": "Enum", "status_idx": "Integer", "mode": "Enum", "mode_idx": "Integer", "invitationCode": "String", "currentFEN": "String", "gameType": "Enum", "gameType_idx": "Integer", "saveStatus": "Enum", "saveStatus_idx": "Integer", "saveRequestWhite": "Boolean", "saveRequestBlack": "Boolean", "movedAt": "Date", "result": "Enum", "result_idx": "Integer", "terminatedById": "ID", "reportStatus": "Enum", "reportStatus_idx": "Integer", "guestPlayerWhite": "Boolean", "guestPlayerBlack": "Boolean", "initialFEN": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Game` API **[Default delete API]** — This is the designated default `delete` API for the `chessGame` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Deletes a chess game (soft-delete). Only allowed for admins or system cleanup. **API Frontend Description By The Backend Architect** Hard deletion not recommended; soft-deletion disables user/game access. Used for moderation/cleanup only. Regular users cannot delete games. Raise event for gameDeleted for moderation/audit. **Rest Route** The `deleteGame` API REST controller can be triggered via the following route: `/v1/game/:chessGameId` **Rest Request Parameters** The `deleteGame` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | chessGameId | ID | true | request.params?.["chessGameId"] | **chessGameId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/game/:chessGameId** ```js axios({ method: 'DELETE', url: `/v1/game/${chessGameId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGame", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "chessGame": { "id": "ID", "playerWhiteId": "ID", "playerBlackId": "ID", "createdById": "ID", "status": "Enum", "status_idx": "Integer", "mode": "Enum", "mode_idx": "Integer", "invitationCode": "String", "currentFEN": "String", "gameType": "Enum", "gameType_idx": "Integer", "saveStatus": "Enum", "saveStatus_idx": "Integer", "saveRequestWhite": "Boolean", "saveRequestBlack": "Boolean", "movedAt": "Date", "result": "Enum", "result_idx": "Integer", "terminatedById": "ID", "reportStatus": "Enum", "reportStatus_idx": "Integer", "guestPlayerWhite": "Boolean", "guestPlayerBlack": "Boolean", "initialFEN": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Game` API **[Default get API]** — This is the designated default `get` API for the `chessGame` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Fetch a single chess game by ID. Only participants, admin, or invitation recipient may access. **API Frontend Description By The Backend Architect** Retrieve all game details and limited move history for preview/study. If user is not participant, must check invitation. Raise event for gameFetched. **Rest Route** The `getGame` API REST controller can be triggered via the following route: `/v1/game/:chessGameId` **Rest Request Parameters** The `getGame` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | chessGameId | ID | true | request.params?.["chessGameId"] | **chessGameId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/game/:chessGameId** ```js axios({ method: 'GET', url: `/v1/game/${chessGameId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGame", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "chessGame": { "id": "ID", "playerWhiteId": "ID", "playerBlackId": "ID", "createdById": "ID", "status": "Enum", "status_idx": "Integer", "mode": "Enum", "mode_idx": "Integer", "invitationCode": "String", "currentFEN": "String", "gameType": "Enum", "gameType_idx": "Integer", "saveStatus": "Enum", "saveStatus_idx": "Integer", "saveRequestWhite": "Boolean", "saveRequestBlack": "Boolean", "movedAt": "Date", "result": "Enum", "result_idx": "Integer", "terminatedById": "ID", "reportStatus": "Enum", "reportStatus_idx": "Integer", "guestPlayerWhite": "Boolean", "guestPlayerBlack": "Boolean", "initialFEN": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "moves": [ { "moveNumber": "Integer", "moveNotation": "String", "moveTime": "Integer", "movedById": "ID", "moveTimestamp": "Date" }, {}, {} ] } } ``` ### `List Games` API **[Default list API]** — This is the designated default `list` API for the `chessGame` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List chess games by participant or admin query. Supports filtering by status, participants, mode, etc. **API Frontend Description By The Backend Architect** Used for history browsing, admin review, or finding ongoing/mutually saved games. Raise event for gameListFetched for audit/UX. **Rest Route** The `listGames` API REST controller can be triggered via the following route: `/v1/games` **Rest Request Parameters** **Filter Parameters** The `listGames` api supports 2 optional filter parameters for filtering list results: **status** (`Enum`): Lifecycle status: pending, active, paused, completed, terminated - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **invitationCode** (`String`): Filter by invitationCode - Single (partial match, case-insensitive): `?invitationCode=` - Multiple: `?invitationCode=&invitationCode=` - Null: `?invitationCode=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/games** ```js axios({ method: 'GET', url: '/v1/games', data: { }, params: { // Filter parameters (see Filter Parameters section above) // status: '' // Filter by status // invitationCode: '' // Filter by invitationCode } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGames", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "chessGames": [ { "id": "ID", "playerWhiteId": "ID", "playerBlackId": "ID", "createdById": "ID", "status": "Enum", "status_idx": "Integer", "mode": "Enum", "mode_idx": "Integer", "invitationCode": "String", "currentFEN": "String", "gameType": "Enum", "gameType_idx": "Integer", "saveStatus": "Enum", "saveStatus_idx": "Integer", "saveRequestWhite": "Boolean", "saveRequestBlack": "Boolean", "movedAt": "Date", "result": "Enum", "result_idx": "Integer", "terminatedById": "ID", "reportStatus": "Enum", "reportStatus_idx": "Integer", "guestPlayerWhite": "Boolean", "guestPlayerBlack": "Boolean", "initialFEN": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Gamemove` API **[Default create API]** — This is the designated default `create` API for the `chessGameMove` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Record a move in an ongoing chess game. Only participants or admin can add moves. **API Frontend Description By The Backend Architect** Called in-order for each legitimate move. Ensures move sequence is preserved. Move time and timestamp acquired on submit. Raises event for moveAdded. **Rest Route** The `createGameMove` API REST controller can be triggered via the following route: `/v1/gamemove` **Rest Request Parameters** The `createGameMove` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | gameId | ID | true | request.body?.["gameId"] | | moveNumber | Integer | true | request.body?.["moveNumber"] | | moveNotation | String | true | request.body?.["moveNotation"] | | moveTime | Integer | false | request.body?.["moveTime"] | | movedById | ID | true | request.body?.["movedById"] | | moveTimestamp | Date | true | request.body?.["moveTimestamp"] | **gameId** : Reference to the chessGame this move belongs to. **moveNumber** : Move number (starting from 1 in each game). **moveNotation** : Chess move in either Standard Algebraic or Long Algebraic Notation (SAN/LAN). **moveTime** : Time in milliseconds since the previous move (for time control, etc.). **movedById** : User ID of the player who made the move (guest/registered); references auth:user.id. **moveTimestamp** : Timestamp when move was made. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/gamemove** ```js axios({ method: 'POST', url: '/v1/gamemove', data: { gameId:"ID", moveNumber:"Integer", moveNotation:"String", moveTime:"Integer", movedById:"ID", moveTimestamp:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameMove", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "chessGameMove": { "id": "ID", "gameId": "ID", "moveNumber": "Integer", "moveNotation": "String", "moveTime": "Integer", "movedById": "ID", "moveTimestamp": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Gamemoves` API **[Default list API]** — This is the designated default `list` API for the `chessGameMove` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List moves for a given game. Only participants or admin can view. **API Frontend Description By The Backend Architect** Used for reviewing game history/study. Returns moves ordered by moveNumber asc. **Rest Route** The `listGameMoves` API REST controller can be triggered via the following route: `/v1/gamemoves` **Rest Request Parameters** **Filter Parameters** The `listGameMoves` api supports 1 optional filter parameter for filtering list results: **gameId** (`ID`): Reference to the chessGame this move belongs to. - Single: `?gameId=` - Multiple: `?gameId=&gameId=` - Null: `?gameId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/gamemoves** ```js axios({ method: 'GET', url: '/v1/gamemoves', data: { }, params: { // Filter parameters (see Filter Parameters section above) // gameId: '' // Filter by gameId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameMoves", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "chessGameMoves": [ { "id": "ID", "gameId": "ID", "moveNumber": "Integer", "moveNotation": "String", "moveTime": "Integer", "movedById": "ID", "moveTimestamp": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Gameinvitation` API **[Default create API]** — This is the designated default `create` API for the `chessGameInvitation` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Send an invitation for a private chess game to a user (guest or registered). **API Frontend Description By The Backend Architect** Used for starting private games. Invitation auto-invalidates on expiry. Raise event for invitationSent for notification. **Rest Route** The `createGameInvitation` API REST controller can be triggered via the following route: `/v1/gameinvitation` **Rest Request Parameters** The `createGameInvitation` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | gameId | ID | true | request.body?.["gameId"] | | senderId | ID | true | request.body?.["senderId"] | | recipientId | ID | true | request.body?.["recipientId"] | | status | Enum | true | request.body?.["status"] | | expiresAt | Date | true | request.body?.["expiresAt"] | **gameId** : Game this invitation is linked to. **senderId** : **recipientId** : **status** : **expiresAt** : Expiration date/time for the invitation. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/gameinvitation** ```js axios({ method: 'POST', url: '/v1/gameinvitation', data: { gameId:"ID", senderId:"ID", recipientId:"ID", status:"Enum", expiresAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameInvitation", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "chessGameInvitation": { "id": "ID", "gameId": "ID", "senderId": "ID", "recipientId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Gameinvitation` API **[Default update API]** — This is the designated default `update` API for the `chessGameInvitation` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update the status or expiry of a game invitation (accept, decline, cancel, expire). Only sender, recipient, or admin can change status. **API Frontend Description By The Backend Architect** Used for invitation workflow (accept, decline, cancel); handled securely as only involved users or admin can update. Event is raised for notification. **Rest Route** The `updateGameInvitation` API REST controller can be triggered via the following route: `/v1/gameinvitation/:chessGameInvitationId` **Rest Request Parameters** The `updateGameInvitation` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | chessGameInvitationId | ID | true | request.params?.["chessGameInvitationId"] | | senderId | ID | | request.body?.["senderId"] | | recipientId | ID | | request.body?.["recipientId"] | | status | Enum | | request.body?.["status"] | | expiresAt | Date | false | request.body?.["expiresAt"] | **chessGameInvitationId** : This id paremeter is used to select the required data object that will be updated **senderId** : **recipientId** : **status** : **expiresAt** : Expiration date/time for the invitation. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/gameinvitation/:chessGameInvitationId** ```js axios({ method: 'PATCH', url: `/v1/gameinvitation/${chessGameInvitationId}`, data: { senderId:"ID", recipientId:"ID", status:"Enum", expiresAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameInvitation", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "chessGameInvitation": { "id": "ID", "gameId": "ID", "senderId": "ID", "recipientId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Gameinvitation` API Delete a game invitation (soft-deletes); only admin may do this for moderation/cleanup. **API Frontend Description By The Backend Architect** Not available to normal users. Moderation purposes only. Raise event for invitationRemoved for mods. **Rest Route** The `deleteGameInvitation` API REST controller can be triggered via the following route: `/v1/gameinvitation/:chessGameInvitationId` **Rest Request Parameters** The `deleteGameInvitation` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | chessGameInvitationId | ID | true | request.params?.["chessGameInvitationId"] | **chessGameInvitationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/gameinvitation/:chessGameInvitationId** ```js axios({ method: 'DELETE', url: `/v1/gameinvitation/${chessGameInvitationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameInvitation", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "chessGameInvitation": { "id": "ID", "gameId": "ID", "senderId": "ID", "recipientId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Gameinvitations` API **[Default list API]** — This is the designated default `list` API for the `chessGameInvitation` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List game invitations. Supports filtering by recipientId, senderId, status, gameId. **API Frontend Description By The Backend Architect** Used to show pending invitations to a user, or to list all invitations for a game. **Rest Route** The `listGameInvitations` API REST controller can be triggered via the following route: `/v1/gameinvitations` **Rest Request Parameters** **Filter Parameters** The `listGameInvitations` api supports 3 optional filter parameters for filtering list results: **senderId** (`ID`): Filter by senderId - Single: `?senderId=` - Multiple: `?senderId=&senderId=` - Null: `?senderId=null` **recipientId** (`ID`): Filter by recipientId - Single: `?recipientId=` - Multiple: `?recipientId=&recipientId=` - Null: `?recipientId=null` **status** (`Enum`): Filter by status - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/gameinvitations** ```js axios({ method: 'GET', url: '/v1/gameinvitations', data: { }, params: { // Filter parameters (see Filter Parameters section above) // senderId: '' // Filter by senderId // recipientId: '' // Filter by recipientId // status: '' // Filter by status } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "chessGameInvitations", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "chessGameInvitations": [ { "id": "ID", "gameId": "ID", "senderId": "ID", "recipientId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Customboard` API **[Default create API]** — This is the designated default `create` API for the `customBoard` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a new custom chess board position. Any logged-in user can create boards. **API Frontend Description By The Backend Architect** Called when a user saves a custom board position from the board editor. createdById is auto-set from session. **Rest Route** The `createCustomBoard` API REST controller can be triggered via the following route: `/v1/customboards` **Rest Request Parameters** The `createCustomBoard` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.["name"] | | fen | String | true | request.body?.["fen"] | | description | Text | false | request.body?.["description"] | | isPublished | Boolean | true | request.body?.["isPublished"] | | category | Enum | true | request.body?.["category"] | | createdById | ID | true | request.body?.["createdById"] | **name** : Name of the custom board position **fen** : FEN string representing the board position **description** : Optional description of the custom board **isPublished** : **category** : **createdById** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/customboards** ```js axios({ method: 'POST', url: '/v1/customboards', data: { name:"String", fen:"String", description:"Text", isPublished:"Boolean", category:"Enum", createdById:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "customBoard", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "customBoard": { "id": "ID", "name": "String", "fen": "String", "description": "Text", "isPublished": "Boolean", "category": "Enum", "category_idx": "Integer", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Customboards` API **[Default list API]** — This is the designated default `list` API for the `customBoard` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List custom board positions. Supports filtering by isPublished, category, and createdById. **API Frontend Description By The Backend Architect** Used to browse published community boards or user's own boards. Filter by isPublished=true for public boards. **Rest Route** The `listCustomBoards` API REST controller can be triggered via the following route: `/v1/customboards` **Rest Request Parameters** **Filter Parameters** The `listCustomBoards` api supports 3 optional filter parameters for filtering list results: **isPublished** (`Boolean`): Filter by isPublished - True: `?isPublished=true` - False: `?isPublished=false` - Null: `?isPublished=null` **category** (`Enum`): Filter by category - Single: `?category=` (case-insensitive) - Multiple: `?category=&category=` - Null: `?category=null` **createdById** (`ID`): Filter by createdById - Single: `?createdById=` - Multiple: `?createdById=&createdById=` - Null: `?createdById=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/customboards** ```js axios({ method: 'GET', url: '/v1/customboards', data: { }, params: { // Filter parameters (see Filter Parameters section above) // isPublished: '' // Filter by isPublished // category: '' // Filter by category // createdById: '' // Filter by createdById } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "customBoards", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "customBoards": [ { "id": "ID", "name": "String", "fen": "String", "description": "Text", "isPublished": "Boolean", "category": "Enum", "category_idx": "Integer", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Customboard` API **[Default get API]** — This is the designated default `get` API for the `customBoard` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Fetch a single custom board position by ID. **API Frontend Description By The Backend Architect** Used to load a specific custom board for editing or playing. **Rest Route** The `getCustomBoard` API REST controller can be triggered via the following route: `/v1/customboards/:customBoardId` **Rest Request Parameters** The `getCustomBoard` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | customBoardId | ID | true | request.params?.["customBoardId"] | **customBoardId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/customboards/:customBoardId** ```js axios({ method: 'GET', url: `/v1/customboards/${customBoardId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "customBoard", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "customBoard": { "id": "ID", "name": "String", "fen": "String", "description": "Text", "isPublished": "Boolean", "category": "Enum", "category_idx": "Integer", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Customboard` API **[Default update API]** — This is the designated default `update` API for the `customBoard` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update a custom board position. Only the creator can update their own boards. **API Frontend Description By The Backend Architect** Used to edit board name, description, FEN, category, or publish/unpublish. **Rest Route** The `updateCustomBoard` API REST controller can be triggered via the following route: `/v1/customboards/:customBoardId` **Rest Request Parameters** The `updateCustomBoard` api has got 7 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | customBoardId | ID | true | request.params?.["customBoardId"] | | name | String | false | request.body?.["name"] | | fen | String | false | request.body?.["fen"] | | description | Text | false | request.body?.["description"] | | isPublished | Boolean | | request.body?.["isPublished"] | | category | Enum | | request.body?.["category"] | | createdById | ID | | request.body?.["createdById"] | **customBoardId** : This id paremeter is used to select the required data object that will be updated **name** : Name of the custom board position **fen** : FEN string representing the board position **description** : Optional description of the custom board **isPublished** : **category** : **createdById** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/customboards/:customBoardId** ```js axios({ method: 'PATCH', url: `/v1/customboards/${customBoardId}`, data: { name:"String", fen:"String", description:"Text", isPublished:"Boolean", category:"Enum", createdById:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "customBoard", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "customBoard": { "id": "ID", "name": "String", "fen": "String", "description": "Text", "isPublished": "Boolean", "category": "Enum", "category_idx": "Integer", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Customboard` API **[Default delete API]** — This is the designated default `delete` API for the `customBoard` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete a custom board position (soft-delete). Only creator or admin can delete. **API Frontend Description By The Backend Architect** Used to remove a custom board. Soft-deletes so data can be recovered if needed. **Rest Route** The `deleteCustomBoard` API REST controller can be triggered via the following route: `/v1/customboards/:customBoardId` **Rest Request Parameters** The `deleteCustomBoard` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | customBoardId | ID | true | request.params?.["customBoardId"] | **customBoardId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/customboards/:customBoardId** ```js axios({ method: 'DELETE', url: `/v1/customboards/${customBoardId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "customBoard", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "customBoard": { "id": "ID", "name": "String", "fen": "String", "description": "Text", "isPublished": "Boolean", "category": "Enum", "category_idx": "Integer", "createdById": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Boardtheme` API **[Default create API]** — This is the designated default `create` API for the `boardTheme` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a custom board color theme. **API Frontend Description By The Backend Architect** Called when user saves a new custom theme from the themes picker. **Rest Route** The `createBoardTheme` API REST controller can be triggered via the following route: `/v1/boardthemes` **Rest Request Parameters** The `createBoardTheme` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.["name"] | | lightSquare | String | true | request.body?.["lightSquare"] | | darkSquare | String | true | request.body?.["darkSquare"] | | createdById | ID | true | request.body?.["createdById"] | **name** : Theme display name **lightSquare** : Hex color for light squares **darkSquare** : Hex color for dark squares **createdById** : User who created this theme **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/boardthemes** ```js axios({ method: 'POST', url: '/v1/boardthemes', data: { name:"String", lightSquare:"String", darkSquare:"String", createdById:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "boardTheme", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "boardTheme": { "id": "ID", "name": "String", "lightSquare": "String", "darkSquare": "String", "isPublished": "Boolean", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Boardthemes` API **[Default list API]** — This is the designated default `list` API for the `boardTheme` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List board themes. Filter by isPublished for community themes or createdById for user's own. **API Frontend Description By The Backend Architect** Used to load user's custom themes and community-published themes. **Rest Route** The `listBoardThemes` API REST controller can be triggered via the following route: `/v1/boardthemes` **Rest Request Parameters** **Filter Parameters** The `listBoardThemes` api supports 1 optional filter parameter for filtering list results: **isPublished** (`Boolean`): Whether the theme is publicly visible - True: `?isPublished=true` - False: `?isPublished=false` - Null: `?isPublished=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/boardthemes** ```js axios({ method: 'GET', url: '/v1/boardthemes', data: { }, params: { // Filter parameters (see Filter Parameters section above) // isPublished: '' // Filter by isPublished } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "boardThemes", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "boardThemes": [ { "id": "ID", "name": "String", "lightSquare": "String", "darkSquare": "String", "isPublished": "Boolean", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Boardtheme` API **[Default update API]** — This is the designated default `update` API for the `boardTheme` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update a custom board theme. Only creator can update. **API Frontend Description By The Backend Architect** Used to edit theme colors/name or publish/unpublish. **Rest Route** The `updateBoardTheme` API REST controller can be triggered via the following route: `/v1/boardthemes/:boardThemeId` **Rest Request Parameters** The `updateBoardTheme` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | boardThemeId | ID | true | request.params?.["boardThemeId"] | | name | String | false | request.body?.["name"] | | lightSquare | String | false | request.body?.["lightSquare"] | | darkSquare | String | false | request.body?.["darkSquare"] | | isPublished | Boolean | false | request.body?.["isPublished"] | **boardThemeId** : This id paremeter is used to select the required data object that will be updated **name** : Theme display name **lightSquare** : Hex color for light squares **darkSquare** : Hex color for dark squares **isPublished** : Whether the theme is publicly visible **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/boardthemes/:boardThemeId** ```js axios({ method: 'PATCH', url: `/v1/boardthemes/${boardThemeId}`, data: { name:"String", lightSquare:"String", darkSquare:"String", isPublished:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "boardTheme", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "boardTheme": { "id": "ID", "name": "String", "lightSquare": "String", "darkSquare": "String", "isPublished": "Boolean", "createdById": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Boardtheme` API **[Default delete API]** — This is the designated default `delete` API for the `boardTheme` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete a custom board theme (soft-delete). Only creator can delete. **API Frontend Description By The Backend Architect** Used to remove user's custom theme. **Rest Route** The `deleteBoardTheme` API REST controller can be triggered via the following route: `/v1/boardthemes/:boardThemeId` **Rest Request Parameters** The `deleteBoardTheme` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | boardThemeId | ID | true | request.params?.["boardThemeId"] | **boardThemeId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/boardthemes/:boardThemeId** ```js axios({ method: 'DELETE', url: `/v1/boardthemes/${boardThemeId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "boardTheme", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "boardTheme": { "id": "ID", "name": "String", "lightSquare": "String", "darkSquare": "String", "isPublished": "Boolean", "createdById": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Userpreference` API **[Default create API]** — This is the designated default `create` API for the `userPreference` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create user preferences record. One per user, auto-sets userId from session. **API Frontend Description By The Backend Architect** Called once when user first changes a preference. userId is auto-set. **Rest Route** The `createUserPreference` API REST controller can be triggered via the following route: `/v1/userpreferences` **Rest Request Parameters** The `createUserPreference` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.body?.["userId"] | | activeThemeId | String | false | request.body?.["activeThemeId"] | | soundEnabled | Boolean | false | request.body?.["soundEnabled"] | | showAnimations | Boolean | false | request.body?.["showAnimations"] | | boardOrientation | Enum | false | request.body?.["boardOrientation"] | | premoveEnabled | Boolean | false | request.body?.["premoveEnabled"] | **userId** : The user this preferences record belongs to **activeThemeId** : ID of the currently selected board theme (preset ID or custom theme ID) **soundEnabled** : Whether game sounds are enabled **showAnimations** : Whether board animations are shown **boardOrientation** : Default board orientation preference **premoveEnabled** : Whether premove feature is enabled **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/userpreferences** ```js axios({ method: 'POST', url: '/v1/userpreferences', data: { userId:"ID", activeThemeId:"String", soundEnabled:"Boolean", showAnimations:"Boolean", boardOrientation:"Enum", premoveEnabled:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "userPreference", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "userPreference": { "id": "ID", "userId": "ID", "activeThemeId": "String", "soundEnabled": "Boolean", "showAnimations": "Boolean", "boardOrientation": "Enum", "boardOrientation_idx": "Integer", "premoveEnabled": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpreference` API **[Default update API]** — This is the designated default `update` API for the `userPreference` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update user preferences. Only the owner can update their own preferences. **API Frontend Description By The Backend Architect** Called when user changes theme, sound, animation, or other settings. **Rest Route** The `updateUserPreference` API REST controller can be triggered via the following route: `/v1/userpreferences/:userPreferenceId` **Rest Request Parameters** The `updateUserPreference` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userPreferenceId | ID | true | request.params?.["userPreferenceId"] | | activeThemeId | String | false | request.body?.["activeThemeId"] | | soundEnabled | Boolean | false | request.body?.["soundEnabled"] | | showAnimations | Boolean | false | request.body?.["showAnimations"] | | boardOrientation | Enum | false | request.body?.["boardOrientation"] | | premoveEnabled | Boolean | false | request.body?.["premoveEnabled"] | **userPreferenceId** : This id paremeter is used to select the required data object that will be updated **activeThemeId** : ID of the currently selected board theme (preset ID or custom theme ID) **soundEnabled** : Whether game sounds are enabled **showAnimations** : Whether board animations are shown **boardOrientation** : Default board orientation preference **premoveEnabled** : Whether premove feature is enabled **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpreferences/:userPreferenceId** ```js axios({ method: 'PATCH', url: `/v1/userpreferences/${userPreferenceId}`, data: { activeThemeId:"String", soundEnabled:"Boolean", showAnimations:"Boolean", boardOrientation:"Enum", premoveEnabled:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "userPreference", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "userPreference": { "id": "ID", "userId": "ID", "activeThemeId": "String", "soundEnabled": "Boolean", "showAnimations": "Boolean", "boardOrientation": "Enum", "boardOrientation_idx": "Integer", "premoveEnabled": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Userpreference` API **[Default get API]** — This is the designated default `get` API for the `userPreference` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a user's preferences by ID. **API Frontend Description By The Backend Architect** Called on app load to restore user's preferences. **Rest Route** The `getUserPreference` API REST controller can be triggered via the following route: `/v1/userpreferences/:userPreferenceId` **Rest Request Parameters** The `getUserPreference` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userPreferenceId | ID | true | request.params?.["userPreferenceId"] | **userPreferenceId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userpreferences/:userPreferenceId** ```js axios({ method: 'GET', url: `/v1/userpreferences/${userPreferenceId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "userPreference", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "userPreference": { "id": "ID", "userId": "ID", "activeThemeId": "String", "soundEnabled": "Boolean", "showAnimations": "Boolean", "boardOrientation": "Enum", "boardOrientation_idx": "Integer", "premoveEnabled": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Userpreferences` API **[Default list API]** — This is the designated default `list` API for the `userPreference` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List user preferences. Filter by userId to get a specific user's preferences. **API Frontend Description By The Backend Architect** Used to find user's preference record by userId filter. **Rest Route** The `listUserPreferences` API REST controller can be triggered via the following route: `/v1/userpreferences` **Rest Request Parameters** The `listUserPreferences` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userpreferences** ```js axios({ method: 'GET', url: '/v1/userpreferences', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "userPreferences", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "userPreferences": [ { "id": "ID", "userId": "ID", "activeThemeId": "String", "soundEnabled": "Boolean", "showAnimations": "Boolean", "boardOrientation": "Enum", "boardOrientation_idx": "Integer", "premoveEnabled": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Gamehubmessages` API **[Default list API]** — This is the designated default `list` API for the `gameHubMessage` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List messages in a gameHub hub room. Accessible by admins and room participants. **Rest Route** The `listGameHubMessages` API REST controller can be triggered via the following route: `/v1/v1/gameHub-messages` **Rest Request Parameters** **Filter Parameters** The `listGameHubMessages` api supports 8 optional filter parameters for filtering list results: **roomId** (`ID`): Reference to the room this message belongs to - Single: `?roomId=` - Multiple: `?roomId=&roomId=` - Null: `?roomId=null` **senderId** (`ID`): Reference to the user who sent this message - Single: `?senderId=` - Multiple: `?senderId=&senderId=` - Null: `?senderId=null` **senderName** (`String`): Display name of the sender (denormalized from user profile at send time) - Single (partial match, case-insensitive): `?senderName=` - Multiple: `?senderName=&senderName=` - Null: `?senderName=null` **senderAvatar** (`String`): Avatar URL of the sender (denormalized from user profile at send time) - Single (partial match, case-insensitive): `?senderAvatar=` - Multiple: `?senderAvatar=&senderAvatar=` - Null: `?senderAvatar=null` **messageType** (`Enum`): Content type discriminator for this message - Single: `?messageType=` (case-insensitive) - Multiple: `?messageType=&messageType=` - Null: `?messageType=null` **content** (`Object`): Type-specific content payload (structure depends on messageType) - Single: `?content=` - Multiple: `?content=&content=` - Null: `?content=null` **timestamp** (`String`): Message creation time - Single (partial match, case-insensitive): `?timestamp=` - Multiple: `?timestamp=×tamp=` - Null: `?timestamp=null` **status** (`Enum`): Message moderation status - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/v1/gameHub-messages** ```js axios({ method: 'GET', url: '/v1/v1/gameHub-messages', data: { }, params: { // Filter parameters (see Filter Parameters section above) // roomId: '' // Filter by roomId // senderId: '' // Filter by senderId // senderName: '' // Filter by senderName // senderAvatar: '' // Filter by senderAvatar // messageType: '' // Filter by messageType // content: '' // Filter by content // timestamp: '' // Filter by timestamp // status: '' // Filter by status } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "gameHubMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "gameHubMessages": [ { "id": "ID", "roomId": "ID", "senderId": "ID", "senderName": "String", "senderAvatar": "String", "messageType": "Enum", "messageType_idx": "Integer", "content": "Object", "timestamp": null, "status": "Enum", "status_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Gamehubmessage` API **[Default get API]** — This is the designated default `get` API for the `gameHubMessage` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a single gameHub hub message by ID. **Rest Route** The `getGameHubMessage` API REST controller can be triggered via the following route: `/v1/v1/gameHub-messages/:id` **Rest Request Parameters** The `getGameHubMessage` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | gameHubMessageId | ID | true | request.params?.["gameHubMessageId"] | | id | String | true | request.params?.["id"] | **gameHubMessageId** : This id paremeter is used to query the required data object. **id** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/v1/gameHub-messages/:id** ```js axios({ method: 'GET', url: `/v1/v1/gameHub-messages/${id}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "gameHubMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "gameHubMessage": { "id": "ID", "roomId": "ID", "senderId": "ID", "senderName": "String", "senderAvatar": "String", "messageType": "Enum", "messageType_idx": "Integer", "content": "Object", "timestamp": null, "status": "Enum", "status_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Gamehubmessage` API **[Default delete API]** — This is the designated default `delete` API for the `gameHubMessage` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Delete a gameHub hub message. Admins can delete any message; users can delete their own. **Rest Route** The `deleteGameHubMessage` API REST controller can be triggered via the following route: `/v1/v1/gameHub-messages/:id` **Rest Request Parameters** The `deleteGameHubMessage` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | gameHubMessageId | ID | true | request.params?.["gameHubMessageId"] | | id | String | true | request.params?.["id"] | **gameHubMessageId** : This id paremeter is used to select the required data object that will be deleted **id** : This parameter will be used to select the data object that want to be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/v1/gameHub-messages/:id** ```js axios({ method: 'DELETE', url: `/v1/v1/gameHub-messages/${id}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "gameHubMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "gameHubMessage": { "id": "ID", "roomId": "ID", "senderId": "ID", "senderName": "String", "senderAvatar": "String", "messageType": "Enum", "messageType_idx": "Integer", "content": "Object", "timestamp": null, "status": "Enum", "status_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Gamehubmessage` API **[Default update API]** — This is the designated default `update` API for the `gameHubMessage` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update a gameHub hub message content. Only the message sender or admins can edit. **Rest Route** The `updateGameHubMessage` API REST controller can be triggered via the following route: `/v1/v1/gameHub-messages/:id` **Rest Request Parameters** The `updateGameHubMessage` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | gameHubMessageId | ID | true | request.params?.["gameHubMessageId"] | | content | Object | false | request.body?.["content"] | | status | Enum | false | request.body?.["status"] | | id | String | true | request.params?.["id"] | **gameHubMessageId** : This id paremeter is used to select the required data object that will be updated **content** : Type-specific content payload (structure depends on messageType) **status** : Message moderation status **id** : This parameter will be used to select the data object that want to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/v1/gameHub-messages/:id** ```js axios({ method: 'PATCH', url: `/v1/v1/gameHub-messages/${id}`, data: { content:"Object", status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "gameHubMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "gameHubMessage": { "id": "ID", "roomId": "ID", "senderId": "ID", "senderName": "String", "senderAvatar": "String", "messageType": "Enum", "messageType_idx": "Integer", "content": "Object", "timestamp": null, "status": "Enum", "status_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.**