### Development Setup Script

Source: https://context7.com/kash/cubedesk/llms.txt

Installs prerequisites like Node.js, PostgreSQL, and Redis using Homebrew, sets up the database, clones the repository, installs dependencies with Yarn, configures environment variables, initializes Prisma, and starts the development server.

```bash
# Install prerequisites (macOS)
brew install node postgresql@14 redis
brew services start postgresql@14
brew services start redis

# Set up the database
sudo -u postgres createuser -s root -P   # use "root" as password
createdb cubedesk -U root

# Clone and install
git clone https://github.com/kash/cubedesk.git
cd cubedesk
npm install --global yarn
yarn

# Configure environment
mv .default.env .env

# Initialize Prisma schema and run migrations
npx prisma format
npx prisma generate
npx prisma migrate dev

# Start the development server (Express + esbuild watch + GraphQL codegen)
yarn dev
open http://localhost:3000
```

--------------------------------

### Install Homebrew and Core Dependencies

Source: https://github.com/kash/cubedesk/wiki/Development-Onboarding

Installs Homebrew, Node.js, PostgreSQL v14.5, and Redis. Starts PostgreSQL and Redis services and creates a database user.

```bash
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js, PostgreSQL v14.5, Redis
brew install node
brew install postgresql@14
brew install redis

# Start PostgreSQL and Redis
brew services start postgresql@14
brew services start redis

# Start redis server
brew services start redis

# Create database user
sudo -u postgres createuser -s root -P

# Set the password to "root" when prompted for a password (no quotes)

# Set up the database
createdb cubedesk -U root
```

--------------------------------

### Start CubeDesk Development Server

Source: https://github.com/kash/cubedesk/wiki/Development-Onboarding

Starts the CubeDesk development server and opens the application in the default web browser.

```bash
# Start the server and open the development site!
yarn dev
open http://localhost:3000
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/kash/cubedesk/wiki/Development-Onboarding

Clones the CubeDesk repository, installs Yarn, and then installs all project dependencies. It also renames the default environment file and initiates database migrations.

```bash
# Change to the directory where you want the CubeDesk codebase to exist. Example:
cd ~/

# Clone the CubeDesk repository
git clone https://github.com/kash/cubedesk.git

# Install yarn
npm install --global yarn

# Install all packages
yarn

# Update .default.env name
mv .default.env .env

# Initiate database tables
npx prisma format
npx prisma generate
npx prisma migrate dev
```

--------------------------------

### Redux Client Actions for Timer and Account State

Source: https://context7.com/kash/cubedesk/llms.txt

Dispatches Redux actions to manage timer parameters, disable the timer, enable space-bar start, and process smart cube turns. Requires React Redux setup and imported action creators.

```typescript
import { useDispatch } from 'react-redux';
import {
  setTimerParamsAction,
  setTimerDisabled,
  setStartEnabled,
  turnSmartCube,
} from '../actions/timer';
import { getMe } from '../actions/account';

const dispatch = useDispatch();

// Load current user into Redux store
dispatch(getMe());

// Update timer parameters (e.g., switch session)
dispatch(setTimerParamsAction({
  session_id: 'se-abc123',
  cube_type: '333',
}));

// Disable the timer (e.g., during a match setup)
dispatch(setTimerDisabled(true));

// Enable the space-bar start
dispatch(setStartEnabled(true));

// Process an incoming smart cube turn
dispatch(turnSmartCube('R', Date.now()));
```

--------------------------------

### Get User Account Details for Admin

Source: https://context7.com/kash/cubedesk/llms.txt

Admin query to retrieve comprehensive details for a specific user account, including join information, pro status, solve summaries, bans, and reports.

```graphql
# Get full user details for admin panel
query GetUserForAdmin {
  getUserAccountForAdmin(userId: "user-id") {
    id
    username
    email
    join_ip
    join_country
    pro_status
    summary {
      solves
      bans
      reports_for
      matches { count wins losses }
    }
    bans {
      reason
      forever
      minutes
      created_at
    }
    reports_for {
      reason
      created_at
      created_by { username }
    }
  }
}
```

--------------------------------

### Fetch All Built-in Trainer Algorithms

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves a list of all available built-in trainer algorithms, including OLL, PLL, and F2L. Useful for accessing standard training content.

```graphql
query GetAlgorithms {
  trainerAlgorithms {
    id
    name
    cube_type
    algo_type
    group_name
    solution
    scrambles
    colors
    pro_only
    img_link
  }
}
```

--------------------------------

### Fetch all built-in trainer algorithms

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves a list of all available built-in trainer algorithms.

```APIDOC
## GetAlgorithms

### Description
Fetches all predefined trainer algorithms for various cube types and categories.

### Method
QUERY

### Endpoint
N/A (GraphQL Query)

### Response
#### Success Response (200)
- **trainerAlgorithms** (Array) - A list of trainer algorithm objects.
  - **id** (String)
  - **name** (String)
  - **cube_type** (String)
  - **algo_type** (String)
  - **group_name** (String)
  - **solution** (String)
  - **scrambles** (String)
  - **colors** (String)
  - **pro_only** (Boolean)
  - **img_link** (String)

### Request Example
```graphql
query GetAlgorithms {
  trainerAlgorithms {
    id
    name
    cube_type
    algo_type
    group_name
    solution
    scrambles
    colors
    pro_only
    img_link
  }
}
```
```

--------------------------------

### Count Unread Notifications

Source: https://context7.com/kash/cubedesk/llms.txt

Query to get the total count of unread notifications, typically used for displaying a badge count.

```graphql
# Count unread notifications (for badge display)
query UnreadCount {
  unreadNotificationCount
}
```

--------------------------------

### Create Smart Solve

Source: https://context7.com/kash/cubedesk/llms.txt

Records a new cube solve using data from a smart cube device.

```APIDOC
## Create Smart Solve

### Description
Submits a completed cube solve, including detailed turn data, from a smart cube device.

### Method
mutation

### Endpoint
N/A (GraphQL)

### Parameters
#### Input (`input` object)
- **time** (Float!) - The total time of the solve in seconds.
- **raw_time** (Float!) - The raw time of the solve in seconds before any adjustments.
- **cube_type** (String!) - The type of cube used (e.g., "333" for 3x3x3).
- **scramble** (String) - The scramble notation for the solve.
- **is_smart_cube** (Boolean!) - Indicates if the solve was performed with a smart cube.
- **smart_device_id** (String!) - The ID of the smart device used for the solve.
- **smart_turns** (String!) - A JSON string representing the sequence of turns made, including timing.
- **smart_turn_count** (Int) - The total number of turns in the solve.
- **smart_put_down_time** (Float) - Time taken to put down the cube after the solve.
- **inspection_time** (Float) - Time spent on inspection before starting the solve.
- **from_timer** (Boolean) - Indicates if the solve data originated from a timer.
- **session_id** (String) - The ID of the session this solve belongs to.
- **started_at** (Long) - Timestamp when the solve started.
- **ended_at** (Long) - Timestamp when the solve ended.

### Request Example
```graphql
mutation SmartSolve {
  createSolve(input: {
    time: 10.51
    raw_time: 10.51
    cube_type: "333"
    scramble: "R U R' F'"
    is_smart_cube: true
    smart_device_id: "device-id"
    smart_turns: "[{\"t\":\"R\",\"ms\":234},{\"t\":\"U\",\"ms\":456}]"
    smart_turn_count: 52
    smart_put_down_time: 0.3
    inspection_time: 3.2
    from_timer: true
    session_id: "se-abc"
    started_at: 1700000000000
    ended_at: 1700000010510
  }) {
    id
    time
    is_smart_cube
    smart_turn_count
    solve_method_steps {
      step_name
      step_index
      total_time
      tps
      recognition_time
      turn_count
      oll_case_key
      pll_case_key
      skipped
    }
  }
}
```

### Response
#### Success Response
- **id** (ID) - The unique identifier for the created solve.
- **time** (Float) - The total time of the solve.
- **is_smart_cube** (Boolean) - Indicates if the solve was from a smart cube.
- **smart_turn_count** (Int) - The number of turns in the solve.
- **solve_method_steps** (Array) - An array of objects detailing each step of the solve.
  - **step_name** (String) - Name of the step.
  - **step_index** (Int) - Index of the step.
  - **total_time** (Float) - Total time for the step.
  - **tps** (Float) - Turns per second for the step.
  - **recognition_time** (Float) - Time taken for recognition.
  - **turn_count** (Int) - Number of turns in the step.
  - **oll_case_key** (String) - OLL case identifier.
  - **pll_case_key** (String) - PLL case identifier.
  - **skipped** (Boolean) - Whether the step was skipped.

#### Response Example
```json
{
  "data": {
    "createSolve": {
      "id": "solve-id-123",
      "time": 10.51,
      "is_smart_cube": true,
      "smart_turn_count": 52,
      "solve_method_steps": [
        {
          "step_name": "Cross",
          "step_index": 0,
          "total_time": 2.5,
          "tps": 4.0,
          "recognition_time": 0.5,
          "turn_count": 10,
          "oll_case_key": null,
          "pll_case_key": null,
          "skipped": false
        }
      ]
    }
  }
}
```
```

--------------------------------

### Download a Community Trainer

Source: https://context7.com/kash/cubedesk/llms.txt

Enables users to download a community-created trainer, creating a local copy for personal use. Requires the 'sourceId' of the trainer to download.

```graphql
mutation DownloadTrainer {
  downloadCustomTrainer(sourceId: "source-trainer-id") {
    id
    name
    copy_of_id
  }
}
```

--------------------------------

### Create a Custom Algorithm Trainer

Source: https://context7.com/kash/cubedesk/llms.txt

Allows users to create their own custom algorithm trainers. Requires providing details such as name, cube type, solution, and algorithm type. Can be set as private or public.

```graphql
mutation CreateCustomTrainer {
  createCustomTrainer(data: {
    name: "My OLL Skip"
    cube_type: "333"
    solution: "U R U' R'"
    scrambles: "R U R' U'"
    algo_type: "OLL"
    group_name: "Skip"
    description: "My personal OLL skip setup"
    private: false
  }) {
    id
    name
    key
    like_count
  }
}
```

--------------------------------

### Match Creation

Source: https://context7.com/kash/cubedesk/llms.txt

Operations for creating competitive cubing matches.

```APIDOC
## GraphQL API — Matches (Real-time 1v1 and Multiplayer)

### Description
Operations for creating competitive cubing matches. CubeDesk supports Head-to-Head and Elimination game modes. Matches are created with a `MatchSession` and joined via a `link_code`. Spectators can join via `spectate_code`. Only Pro users can customize cube type, player count, or win conditions.

### Create Match
```graphql
# Create a new rated Head-to-Head 3x3 match
mutation CreateMatch {
  createMatchWithNewSession(input: {
    match_type: HEAD_TO_HEAD
    cube_type: "333"
    min_players: 2
    max_players: 2
    head_to_head_target_win_count: 5
  }) {
    id
    link_code
    spectate_code
    match_session {
      id
      rated
      game_options {
        game_type
        cube_type
        head_to_head_target_win_count
      }
    }
  }
}
```
```

--------------------------------

### Fetch available Pro pricing options

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves the available pricing options for CubeDesk Pro memberships.

```APIDOC
## MembershipOptions

### Description
Fetches the current pricing details for CubeDesk Pro memberships, including monthly and annual plans.

### Method
QUERY

### Endpoint
N/A (GraphQL Query)

### Response
#### Success Response (200)
- **membershipOptions** (Object)
  - **month** (Object) - Pricing details for the monthly plan.
    - **id** (String)
    - **currency** (String)
    - **unit_amount** (Int)
    - **interval** (String)
    - **interval_count** (Int)
  - **year** (Object) - Pricing details for the annual plan.
    - **id** (String)
    - **currency** (String)
    - **unit_amount** (Int)
    - **interval** (String)
    - **interval_count** (Int)

### Request Example
```graphql
query MembershipOptions {
  membershipOptions {
    month {
      id
      currency
      unit_amount
      interval
      interval_count
    }
    year {
      id
      currency
      unit_amount
      interval
      interval_count
    }
  }
}
```
```

--------------------------------

### Create Competitive Matches

Source: https://context7.com/kash/cubedesk/llms.txt

Create new Head-to-Head or Elimination matches. Matches are created with a `MatchSession` and joined via a `link_code`. Spectators can join via `spectate_code`. Pro users can customize match settings.

```graphql
mutation CreateMatch {
  createMatchWithNewSession(input: {
    match_type: HEAD_TO_HEAD
    cube_type: "333"
    min_players: 2
    max_players: 2
    head_to_head_target_win_count: 5
  }) {
    id
    link_code
    spectate_code
    match_session {
      id
      rated
      game_options {
        game_type
        cube_type
        head_to_head_target_win_count
      }
    }
  }
}
```

--------------------------------

### Create a custom algorithm trainer

Source: https://context7.com/kash/cubedesk/llms.txt

Creates a new custom algorithm trainer for personal use or sharing.

```APIDOC
## CreateCustomTrainer

### Description
Allows users to create and define their own custom algorithm trainers, specifying algorithms, scrambles, and other details.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Request Body
- **data** (Object) - Required - The data for the new custom trainer.
  - **name** (String) - Required - The name of the trainer.
  - **cube_type** (String) - Required - The type of cube (e.g., '333').
  - **solution** (String) - Required - The algorithm solution.
  - **scrambles** (String) - Required - Example scrambles for the algorithm.
  - **algo_type** (String) - Required - The type of algorithm (e.g., 'OLL').
  - **group_name** (String) - Required - The group the algorithm belongs to (e.g., 'Skip').
  - **description** (String) - Optional - A description for the trainer.
  - **private** (Boolean) - Optional - Whether the trainer should be private.

### Response
#### Success Response (200)
- **createCustomTrainer** (Object) - The created custom trainer details.
  - **id** (String)
  - **name** (String)
  - **key** (String)
  - **like_count** (Int)

### Request Example
```graphql
mutation CreateCustomTrainer {
  createCustomTrainer(data: {
    name: "My OLL Skip"
    cube_type: "333"
    solution: "U R U' R'"
    scrambles: "R U R' U'"
    algo_type: "OLL"
    group_name: "Skip"
    description: "My personal OLL skip setup"
    private: false
  }) {
    id
    name
    key
    like_count
  }
}
```
```

--------------------------------

### Download a community trainer

Source: https://context7.com/kash/cubedesk/llms.txt

Downloads a public community trainer, creating a local copy for the user.

```APIDOC
## DownloadTrainer

### Description
Allows users to download a public custom trainer, creating a personal copy that can be modified or used locally.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Request Body
- **sourceId** (String) - Required - The ID of the community trainer to download.

### Response
#### Success Response (200)
- **downloadCustomTrainer** (Object) - Details of the downloaded trainer copy.
  - **id** (String) - The ID of the newly created local copy.
  - **name** (String) - The name of the trainer.
  - **copy_of_id** (String) - The ID of the original community trainer.

### Request Example
```graphql
mutation DownloadTrainer {
  downloadCustomTrainer(sourceId: "source-trainer-id") {
    id
    name
    copy_of_id
  }
}
```
```

--------------------------------

### Manage User Settings

Source: https://context7.com/kash/cubedesk/llms.txt

Fetch and update per-user timer and application settings. Individual keys can be updated by passing only the desired key in the `SettingInput`. Beta features require Pro membership.

```graphql
query GetSettings {
  settings {
    id
    cube_type
    session_id
    focus_mode
    freeze_time
    inspection
    inspection_delay
    hide_time_when_solving
    pb_confetti
    timer_decimal_points
    manual_entry
    use_space_with_smart_cube
    beta_tester
    custom_cube_types {
      id
      name
      scramble
    }
  }
}
```

```graphql
mutation EnableInspection {
  setSetting(input: { inspection: true, inspection_delay: 15 }) {
    inspection
    inspection_delay
  }
}
```

```graphql
mutation SetDecimalPoints {
  setSetting(input: { timer_decimal_points: 3 }) {
    timer_decimal_points
  }
}
```

```graphql
mutation EnableFocusMode {
  setSetting(input: { focus_mode: true }) {
    focus_mode
  }
}
```

```graphql
mutation SetCubeType {
  setSetting(input: { cube_type: "222" }) {
    cube_type
  }
}
```

--------------------------------

### Fetch Available Pro Membership Pricing Options

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves available Pro membership pricing options, including monthly and annual plans. Data is cached in Redis for 3 days. Includes currency, amount, and interval details.

```graphql
query MembershipOptions {
  membershipOptions {
    month {
      id
      currency
      unit_amount
      interval
      interval_count
    }
    year {
      id
      currency
      unit_amount
      interval
      interval_count
    }
  }
}
```

--------------------------------

### Real-time Match Communication with Socket.IO

Source: https://context7.com/kash/cubedesk/llms.txt

Connects to the Socket.IO server to join match rooms, listen for updates, submit solves, send chat messages, and manage match presence. Ensure the server is running and accessible.

```typescript
import { io } from 'socket.io-client';

const socket = io('https://cubedesk.io', { withCredentials: true });

// Join a match room
socket.emit('join_match', { matchId: 'match-id', linkCode: 'abc123' });

// Listen for match state updates
socket.on('match_update', (match) => {
  console.log('Match updated:', match.id, 'Winner:', match.winner?.username);
});

// Submit a solve in an active match
socket.emit('submit_solve', {
  matchId: 'match-id',
  time: 10.34,
  rawTime: 10.34,
  cubeType: '333',
  scramble: 'R U R\' U\'',
  dnf: false,
  plusTwo: false,
});

// Listen for opponent's solve submission
socket.on('opponent_solve', (solve) => {
  console.log(`Opponent solved in ${solve.time}s`);
});

// Send a chat message in the match lobby
socket.emit('send_chat', { matchSessionId: 'session-id', message: 'Good luck!' });

// Listen for incoming chat messages
socket.on('chat_message', (msg) => {
  console.log(`${msg.user.username}: ${msg.message}`);
});

// Send periodic heartbeat to maintain match presence
socket.emit('heartbeat', { matchId: 'match-id' });

// Listen for match end
socket.on('match_ended', (result) => {
  console.log('Match over. Winner:', result.winner?.username);
  console.log('ELO change:', result.eloChange);
});

// Leave match
socket.emit('leave_match', { matchId: 'match-id' });
```

--------------------------------

### Create Smart Cube Solve

Source: https://context7.com/kash/cubedesk/llms.txt

Mutation to create a new solve record for a smart cube, including detailed turn data, timing, and metadata. Requires the smart device ID and solve parameters.

```graphql
# Create a smart cube solve with full turn data
mutation SmartSolve {
  createSolve(input: {
    time: 10.51
    raw_time: 10.51
    cube_type: "333"
    scramble: "R U R' F'"
    is_smart_cube: true
    smart_device_id: "device-id"
    smart_turns: "[{"t":"R","ms":234},{"t":"U","ms":456}]"
    smart_turn_count: 52
    smart_put_down_time: 0.3
    inspection_time: 3.2
    from_timer: true
    session_id: "se-abc"
    started_at: 1700000000000
    ended_at: 1700000010510
  }) {
    id
    time
    is_smart_cube
    smart_turn_count
    solve_method_steps {
      step_name
      step_index
      total_time
      tps
      recognition_time
      turn_count
      oll_case_key
      pll_case_key
      skipped
    }
  }
}
```

--------------------------------

### Smart Devices Query

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves a list of all registered smart devices.

```APIDOC
## Smart Devices Query

### Description
Retrieves a list of all registered smart devices associated with the user's account.

### Method
query

### Endpoint
N/A (GraphQL)

### Parameters
None

### Request Example
```graphql
query SmartDevices {
  smartDevices {
    id
    name
    device_id
    created_at
  }
}
```

### Response
#### Success Response
- **id** (ID) - The unique identifier for the device.
- **name** (String) - The name of the device.
- **device_id** (String) - The device ID.
- **created_at** (String) - The timestamp when the device was registered.

#### Response Example
```json
{
  "data": {
    "smartDevices": [
      {
        "id": "device-id-1",
        "name": "My GAN Cube",
        "device_id": "aa:bb:cc:dd:ee:ff",
        "created_at": "2023-10-27T10:00:00Z"
      }
    ]
  }
}
```
```

--------------------------------

### Add Smart Device

Source: https://context7.com/kash/cubedesk/llms.txt

Registers a new Bluetooth smart cube device with the CubeDesk system.

```APIDOC
## Add Smart Device

### Description
Registers a new Bluetooth smart cube device with the CubeDesk system.

### Method
mutation

### Endpoint
N/A (GraphQL)

### Parameters
#### Input
- **originalName** (String!) - The original name of the smart cube device.
- **deviceId** (String!) - The unique Bluetooth device ID of the smart cube.

### Request Example
```graphql
mutation AddSmartDevice {
  addNewSmartDevice(
    originalName: "GAN 356 i Carry"
    deviceId: "aa:bb:cc:dd:ee:ff"
  ) {
    id
    name
    internal_name
    device_id
  }
}
```

### Response
#### Success Response
- **id** (ID) - The unique identifier for the newly registered device.
- **name** (String) - The name of the device.
- **internal_name** (String) - The internal name of the device.
- **device_id** (String) - The device ID.

#### Response Example
```json
{
  "data": {
    "addNewSmartDevice": {
      "id": "some-device-id",
      "name": "GAN 356 i Carry",
      "internal_name": "gan_356_i_carry",
      "device_id": "aa:bb:cc:dd:ee:ff"
    }
  }
}
```
```

--------------------------------

### Settings Management

Source: https://context7.com/kash/cubedesk/llms.txt

Operations for reading and updating per-user timer and application settings.

```APIDOC
## GraphQL API — Settings

### Description
Operations for reading and updating per-user timer and application settings. Each user has one `Setting` record. Beta tester features require Pro membership.

### Read Settings
```graphql
# Fetch current settings
query GetSettings {
  settings {
    id
    cube_type
    session_id
    focus_mode
    freeze_time
    inspection
    inspection_delay
    hide_time_when_solving
    pb_confetti
    timer_decimal_points
    manual_entry
    use_space_with_smart_cube
    beta_tester
    custom_cube_types {
      id
      name
      scramble
    }
  }
}
```

### Enable Inspection
```graphql
# Enable WCA inspection (15-second countdown)
mutation EnableInspection {
  setSetting(input: { inspection: true, inspection_delay: 15 }) {
    inspection
    inspection_delay
  }
}
```

### Set Decimal Points
```graphql
# Adjust timer display to 3 decimal points
mutation SetDecimalPoints {
  setSetting(input: { timer_decimal_points: 3 }) {
    timer_decimal_points
  }
}
```

### Enable Focus Mode
```graphql
# Enable focus mode (hides UI distractions while solving)
mutation EnableFocusMode {
  setSetting(input: { focus_mode: true }) {
    focus_mode
  }
}
```

### Set Cube Type
```graphql
# Switch default cube type
mutation SetCubeType {
  setSetting(input: { cube_type: "222" }) {
    cube_type
  }
}
```
```

--------------------------------

### User Account Management

Source: https://context7.com/kash/cubedesk/llms.txt

Mutations and queries for creating, authenticating, and managing user accounts, including fetching user data and updating profiles.

```APIDOC
## GraphQL API — User Account

### Description
Create, authenticate, and manage user accounts. The `UserAccount` type is the root entity. Registration requires name, email, username, and password. Authentication sets a session cookie. The `me` query returns the fully hydrated account for the current session, including profile, badges, ELO rating, and Pro membership status.

### Mutations & Queries

#### Register a new account
```graphql
mutation CreateAccount {
  createUserAccount(
    first_name: "Alice"
    last_name: "Cuber"
    email: "alice@example.com"
    username: "alicecuber"
    password: "securePassword123"
  ) {
    id
    username
    email
    is_pro
    verified
  }
}
```

#### Log in
```graphql
mutation Login {
  authenticateUser(email: "alice@example.com", password: "securePassword123") {
    id
    username
    is_pro
    admin
    pro_status
  }
}
```

#### Fetch current user (requires session cookie)
```graphql
query Me {
  me {
    id
    username
    email
    is_pro
    pro_status
    verified
    profile {
      bio
      favorite_event
      youtube_link
      twitter_link
    }
    elo_rating {
      elo_333_rating
      elo_overall_rating
      games_333_count
    }
    badges {
      id
      badge_type {
        name
        color
        description
      }
    }
  }
}
```

#### Update profile fields
```graphql
mutation UpdateProfile {
  updateProfile(input: {
    bio: "3x3 main is MoYu RS3M"
    favorite_event: "333"
    three_method: "CFOP"
    youtube_link: "https://youtube.com/@alicecuber"
  }) {
    id
    bio
    favorite_event
  }
}
```

#### Update password
```graphql
mutation ChangePassword {
  updateUserPassword(old_password: "securePassword123", new_password: "newPassword456") {
    id
    username
  }
}
```

#### Log out
```graphql
mutation Logout {
  logOut {
    id
  }
}
```
```

--------------------------------

### Browse public community-created trainers

Source: https://context7.com/kash/cubedesk/llms.txt

Fetches a paginated list of public custom trainers, with optional search.

```APIDOC
## PublicTrainers

### Description
Browses and searches through publicly shared custom algorithm trainers created by the community.

### Method
QUERY

### Endpoint
N/A (GraphQL Query)

### Parameters
#### Query Parameters
- **page** (Int) - Optional - The page number for pagination.
- **pageSize** (Int) - Optional - The number of items per page.
- **searchQuery** (String) - Optional - A query string to filter trainers by name or description.

### Response
#### Success Response (200)
- **publicCustomTrainers** (Object)
  - **items** (Array) - A list of public custom trainer objects.
    - **id** (String)
    - **name** (String)
    - **description** (String)
    - **cube_type** (String)
    - **group_name** (String)
    - **solution** (String)
    - **like_count** (Int)
    - **user** (Object)
      - **username** (String)
  - **total** (Int) - The total number of trainers available.
  - **hasMore** (Boolean) - Indicates if there are more trainers available beyond the current page.

### Request Example
```graphql
query PublicTrainers {
  publicCustomTrainers(page: 0, pageSize: 25, searchQuery: "PLL") {
    items {
      id
      name
      description
      cube_type
      group_name
      solution
      like_count
      user { username }
    }
    total
    hasMore
  }
}
```
```

--------------------------------

### List Registered Smart Devices

Source: https://context7.com/kash/cubedesk/llms.txt

Query to retrieve a list of all registered smart cube devices, including their ID, name, device ID, and creation timestamp.

```graphql
# List all registered smart devices
query SmartDevices {
  smartDevices {
    id
    name
    device_id
    created_at
  }
}
```

--------------------------------

### Browse Public Community-Created Trainers

Source: https://context7.com/kash/cubedesk/llms.txt

Fetches a paginated list of public custom trainers. Supports searching by name and filtering by cube type or algorithm group. Use 'page' and 'pageSize' for pagination.

```graphql
query PublicTrainers {
  publicCustomTrainers(page: 0, pageSize: 25, searchQuery: "PLL") {
    items {
      id
      name
      description
      cube_type
      group_name
      solution
      like_count
      user { username }
    }
    total
    hasMore
  }
}
```

--------------------------------

### Register Smart Cube Device

Source: https://context7.com/kash/cubedesk/llms.txt

Mutation to register a new Bluetooth smart cube device with the system. Requires the device's original name and its Bluetooth ID.

```graphql
# Register a new smart cube device
mutation AddSmartDevice {
  addNewSmartDevice(
    originalName: "GAN 356 i Carry"
    deviceId: "aa:bb:cc:dd:ee:ff"
  ) {
    id
    name
    internal_name
    device_id
  }
}
```

--------------------------------

### Mark a trainer as favorite

Source: https://context7.com/kash/cubedesk/llms.txt

Marks a specific algorithm trainer as a favorite for quick access.

```APIDOC
## FavoriteTrainer

### Description
Allows users to mark algorithm trainers as favorites, making them easily accessible from a dedicated list.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Request Body
- **cubeKey** (String) - Required - The key of the trainer to mark as favorite.

### Response
#### Success Response (200)
- **createTrainerFavorite** (Object) - Confirmation of the favorite status.
  - **id** (String)
  - **cube_key** (String)

### Request Example
```graphql
mutation FavoriteTrainer {
  createTrainerFavorite(cubeKey: "pll-t") {
    id
    cube_key
  }
}
```
```

--------------------------------

### Solve Management

Source: https://context7.com/kash/cubedesk/llms.txt

Operations for recording, retrieving, and bulk-managing solve times, including filtering and sorting capabilities.

```APIDOC
## GraphQL API — Solves

### Description
Record, retrieve, and bulk-manage solve times. Each solve stores time, cube type, scramble, DNF/+2 status, smart cube data, and optional trainer metadata. Solves are paginated and filterable by cube type, status, and sort order. Bulk operations (Pro only) enable batch DNF, +2, delete, move, and cube type updates.

### Mutations & Queries

#### Record a single solve from the timer
```graphql
mutation CreateSolve {
  createSolve(input: {
    time: 12.34
    raw_time: 12.34
    cube_type: "333"
    scramble: "R U R' U' R U2 R'"
    from_timer: true
    session_id: "se-abc123"
    started_at: 1700000000000
    ended_at: 1700000012340
    dnf: false
    plus_two: false
  }) {
    id
    time
    cube_type
    scramble
    created_at
    share_code
  }
}
```

#### Retrieve paginated solve list (sorted, filtered)
```graphql
query GetSolves {
  solveList(
    cubeType: "333"
    sortBy: CREATED_AT_DESC
    filters: [NOT_DNF]
    page: 0
  ) {
    solves {
      id
      time
      raw_time
      cube_type
      scramble
      dnf
      plus_two
      created_at
      is_smart_cube
      smart_turn_count
    }
    more_results
    total_count
  }
}
```

#### Fetch a solve by its public share code
```graphql
query GetSolveByShareCode {
  solveByShareCode(shareCode: "abc123xyz") {
    id
    time
    cube_type
    scramble
    user {
      username
    }
    solve_method_steps {
      step_name
      total_time
      tps
      turn_count
    }
  }
}
```

#### Bulk import solves (e.g., from csTimer export)
```graphql
mutation BulkImport {
  bulkCreateSolves(solves: [
    { time: 9.87, raw_time: 9.87, cube_type: "333", scramble: "U R2 F", bulk: true }
    { time: 11.23, raw_time: 11.23, cube_type: "333", scramble: "R' F2 U", bulk: true }
  ])
}
```

#### Pro-only: bulk delete solves
```graphql
mutation BulkDelete {
  bulkDeleteSolves(solveIds: ["id-1", "id-2", "id-3"])
}
```

#### Pro-only: bulk DNF solves
```graphql
mutation BulkDNF {
  bulkDnfSolves(solveIds: ["id-1", "id-2"])
}
```

#### Pro-only: bulk move solves to another session
```graphql
mutation BulkMove {
  bulkMoveSolvesToSession(solveIds: ["id-1", "id-2"], sessionId: "se-xyz")
}
```

#### Pro-only: bulk apply +2 penalty
```graphql
mutation BulkPlusTwo {
  bulkPlusTwoSolves(solveIds: ["id-1", "id-2"])
}
```
```

--------------------------------

### Fetch match for spectating

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieves match details for spectating purposes using a spectate code.

```APIDOC
## SpectateMatch

### Description
Fetches match data suitable for spectating using a unique spectate code.

### Method
QUERY

### Endpoint
N/A (GraphQL Query)

### Parameters
#### Query Parameters
- **code** (String) - Required - The spectate code of the match.

### Response
#### Success Response (200)
- **matchBySpectateCode** (Object) - Basic match information for spectators.
  - **id** (String)
  - **participants** (Array)
    - **user** (Object)
      - **username** (String)
    - **solves** (Array)
      - **time** (Int)

### Request Example
```graphql
query SpectateMatch {
  matchBySpectateCode(code: "xyz789") {
    id
    participants {
      user { username }
      solves { time }
    }
  }
}
```
```

--------------------------------

### Override an Algorithm Solution

Source: https://context7.com/kash/cubedesk/llms.txt

Allows users to override the solution for a specific built-in algorithm. Requires the 'algoKey' and input data including the new solution, name, and rotation.

```graphql
mutation OverrideAlgorithm {
  updateAlgorithmOverride(algoKey: "pll-t", input: {
    solution: "R U R' U' R' F R2 U' R' U' R U R' F'"
    name: "My T-Perm"
    rotate: 1
  }) {
    id
    cube_key
    solution
    name
  }
}
```

--------------------------------

### List Incoming Friend Requests

Source: https://context7.com/kash/cubedesk/llms.txt

Fetches a paginated list of incoming friend requests. Use 'page' and 'pageSize' for pagination. Displays sender's username and request creation time.

```graphql
query IncomingRequests {
  friendshipRequestsReceived(page: 0, pageSize: 25) {
    items {
      id
      from_user { username }
      created_at
    }
    total
  }
}
```

--------------------------------

### GraphQL API - Solves Mutations and Queries

Source: https://context7.com/kash/cubedesk/llms.txt

These GraphQL operations are used to record, retrieve, and manage solve times. Some bulk operations require a Pro membership.

```graphql
# Record a single solve from the timer
mutation CreateSolve {
  createSolve(input: {
    time: 12.34
    raw_time: 12.34
    cube_type: "333"
    scramble: "R U R' U' R U2 R'"
    from_timer: true
    session_id: "se-abc123"
    started_at: 1700000000000
    ended_at: 1700000012340
    dnf: false
    plus_two: false
  }) {
    id
    time
    cube_type
    scramble
    created_at
    share_code
  }
}
```

```graphql
# Retrieve paginated solve list (sorted, filtered)
query GetSolves {
  solveList(
    cubeType: "333"
    sortBy: CREATED_AT_DESC
    filters: [NOT_DNF]
    page: 0
  ) {
    solves {
      id
      time
      raw_time
      cube_type
      scramble
      dnf
      plus_two
      created_at
      is_smart_cube
      smart_turn_count
    }
    more_results
    total_count
  }
}
```

```graphql
# Fetch a solve by its public share code
query GetSolveByShareCode {
  solveByShareCode(shareCode: "abc123xyz") {
    id
    time
    cube_type
    scramble
    user {
      username
    }
    solve_method_steps {
      step_name
      total_time
      tps
      turn_count
    }
  }
}
```

```graphql
# Bulk import solves (e.g., from csTimer export)
mutation BulkImport {
  bulkCreateSolves(solves: [
    { time: 9.87, raw_time: 9.87, cube_type: "333", scramble: "U R2 F", bulk: true }
    { time: 11.23, raw_time: 11.23, cube_type: "333", scramble: "R' F2 U", bulk: true }
  ])
}
```

```graphql
# Pro-only: bulk delete solves
mutation BulkDelete {
  bulkDeleteSolves(solveIds: ["id-1", "id-2", "id-3"])
}
```

```graphql
# Pro-only: bulk DNF solves
mutation BulkDNF {
  bulkDnfSolves(solveIds: ["id-1", "id-2"])
}
```

```graphql
# Pro-only: bulk move solves to another session
mutation BulkMove {
  bulkMoveSolvesToSession(solveIds: ["id-1", "id-2"], sessionId: "se-xyz")
}
```

```graphql
# Pro-only: bulk apply +2 penalty
mutation BulkPlusTwo {
  bulkPlusTwoSolves(solveIds: ["id-1", "id-2"])
}
```

--------------------------------

### GraphQL API - User Account Mutations and Queries

Source: https://context7.com/kash/cubedesk/llms.txt

These GraphQL operations allow for the creation, authentication, and management of user accounts. Ensure a valid session cookie is present for queries like 'me'.

```graphql
# Register a new account
mutation CreateAccount {
  createUserAccount(
    first_name: "Alice"
    last_name: "Cuber"
    email: "alice@example.com"
    username: "alicecuber"
    password: "securePassword123"
  ) {
    id
    username
    email
    is_pro
    verified
  }
}
```

```graphql
# Log in
mutation Login {
  authenticateUser(email: "alice@example.com", password: "securePassword123") {
    id
    username
    is_pro
    admin
    pro_status
  }
}
```

```graphql
# Fetch current user (requires session cookie)
query Me {
  me {
    id
    username
    email
    is_pro
    pro_status
    verified
    profile {
      bio
      favorite_event
      youtube_link
      twitter_link
    }
    elo_rating {
      elo_333_rating
      elo_overall_rating
      games_333_count
    }
    badges {
      id
      badge_type {
        name
        color
        description
      }
    }
  }
}
```

```graphql
# Update profile fields
mutation UpdateProfile {
  updateProfile(input: {
    bio: "3x3 main is MoYu RS3M"
    favorite_event: "333"
    three_method: "CFOP"
    youtube_link: "https://youtube.com/@alicecuber"
  }) {
    id
    bio
    favorite_event
  }
}
```

```graphql
# Update password
mutation ChangePassword {
  updateUserPassword(old_password: "securePassword123", new_password: "newPassword456") {
    id
    username
  }
}
```

```graphql
# Log out
mutation Logout {
  logOut {
    id
  }
}
```

--------------------------------

### Fetch Match for Spectating

Source: https://context7.com/kash/cubedesk/llms.txt

Retrieve match information for spectating purposes using a spectate code. Requires the 'code' argument.

```graphql
query SpectateMatch {
  matchBySpectateCode(code: "xyz789") {
    id
    participants {
      user { username }
      solves { time }
    }
  }
}
```

--------------------------------

### Generate a Stripe Checkout URL for the selected price

Source: https://context7.com/kash/cubedesk/llms.txt

Creates a Stripe Checkout session URL for purchasing a Pro membership.

```APIDOC
## BuyPro

### Description
Generates a secure Stripe Checkout URL to facilitate the purchase of a CubeDesk Pro membership.

### Method
MUTATION

### Endpoint
N/A (GraphQL Mutation)

### Parameters
#### Request Body
- **priceId** (String) - Required - The Stripe price ID for the desired membership plan.

### Response
#### Success Response (200)
- **generateBuyLink** (String) - The URL for the Stripe Checkout session.

### Request Example
```graphql
mutation BuyPro {
  generateBuyLink(priceId: "price_stripe_id_here")
}
```
```

--------------------------------

### Session Management

Source: https://context7.com/kash/cubedesk/llms.txt

Operations for creating, listing, renaming, reordering, merging, and deleting named solve sessions.

```APIDOC
## GraphQL API — Sessions

### Description
Operations for creating, listing, renaming, reordering, merging, and deleting named solve sessions. Sessions group solves into named collections and are ordered by their `order` field.

### List Sessions
```graphql
# List all sessions for the logged-in user
query GetSessions {
  sessions {
    id
    name
    order
    created_at
  }
}
```

### Create Session
```graphql
# Create a new session
mutation CreateSession {
  createSession(input: { name: "PLL Practice" }) {
    id
    name
    order
  }
}
```

### Rename Session
```graphql
# Rename a session
mutation RenameSession {
  updateSession(id: "se-abc123", input: { name: "3x3 Main" }) {
    id
    name
  }
}
```

### Reorder Sessions
```graphql
# Reorder sessions by providing an ordered list of IDs
mutation ReorderSessions {
  reorderSessions(ids: ["se-abc123", "se-def456", "se-ghi789"])
}
```

### Merge Sessions
```graphql
# Merge two sessions (moves all solves from old into new, then deletes old)
mutation MergeSessions {
  mergeSessions(oldSessionId: "se-old", newSessionId: "se-new") {
    id
    name
  }
}
```

### Delete Session
```graphql
# Delete a session
mutation DeleteSession {
  deleteSession(id: "se-abc123") {
    id
    name
  }
}
```
```