### Basic JavaScript 'Hello World' Example

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/advanced/scripting.md

A simple JavaScript snippet to verify correct setup by logging 'Hello, World!' to the console. This is a fundamental test for any scripting environment.

```javascript
console.log('Hello, World!');
```

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

### Install Millennium on Windows (PowerShell)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/getting-started/installation.md

Installs Millennium on Windows using a PowerShell script. This method is automatic and does not alter system configurations. It fetches the installation script directly from a URL and executes it.

```powershell
iwr -useb "https://steambrew.app/install.ps1" | iex
```

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

### Example CSS for Theme Colors - CSS

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/intermediate/colors.md

This CSS example demonstrates how to define theme colors using various formats (RGB, RGBA, Hex) within a `:root` block. It also shows how to add custom names and descriptions using `@name` and `@description` selectors for better usability in the theme editor.

```css
:root {
	/* 
    * @name this is a name 
    * @description this is a description 
    */
	--raw-rgb: 123, 123, 123;
	/*
    * @name this is a name 1
    */
	--raw-rgba: 123, 123, 123, 0.5;
	--rgb: rgb(123, 123, 123);
	--rgba: rgba(123, 123, 123, 0.5);
	--hex: #123456;

	/* these are examples of invalid, unparsable colors */
	--invalid-1: hsl(123, 50%, 50%);
	--invalid-2: blue;
}
```

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

### HTML Structure for Selectors Examples

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/basics/selectors.md

This HTML snippet provides the basic structure used in the following CSS examples to demonstrate selector specificity. It includes a main container, a main content area, and a heading.

```html
<div class="site-container">
  <main id="myContent">
    <h1>Text</h1>
  </main>
</div>
```

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

### Clone Theme Template (Linux Bash)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/introduction/quick-start.md

This script navigates to the Steam skins directory on Linux, clones the ThemeTemplate repository, and optionally opens it in VSCode.

```bash
# cd into Steam skins folder
cd ~/.steam/steam/steamui/skins
# clone the repository
git clone "https://github.com/SteamClientHomebrew/ThemeTemplate"
cd ThemeTemplate

# Optional: Open VSCode
code .
```

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

### Clone Theme Template (Windows PowerShell)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/introduction/quick-start.md

This script navigates to the Steam skins directory on Windows using a registry key, clones the ThemeTemplate repository, and optionally opens it in VSCode.

```powershell
# Note: this is a PowerShell script
# cd into Steam skins folder
cd "$(gp 'HKLM:\SOFTWARE\Wow6432Node\Valve\Steam' | % InstallPath)\steamui\skins"
# clone the repository
git clone "https://github.com/SteamClientHomebrew/ThemeTemplate"
cd ThemeTemplate

# Optional: Open VSCode
code .
```

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

### Basic logging examples at different severity levels in Lua

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/logger.md

Provides examples of logging messages at info, warn, and error levels to demonstrate basic logging patterns.

```lua
-- Log at different severity levels
logger:info("Starting data processing")
logger:warn("Cache is getting full")
logger:error("Failed to save data")
```

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

### GET /api/v1/plugins/

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Retrieves a complete list of all available plugins with their associated metadata, download counts, and file sizes. This endpoint utilizes a 30-minute cache for performance.

```APIDOC
## GET /api/v1/plugins/

### Description
Retrieves a complete list of all available plugins with metadata, download counts, and file sizes.

### Method
GET

### Endpoint
/api/v1/plugins/

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Fetch all plugins
curl https://steambrew.app/api/v1/plugins/
```

### Response
#### Success Response (200)
Returns an array of plugin objects, each containing:
- **id** (string) - Unique identifier for the plugin.
- **commitId** (string) - The commit ID of the plugin's source code.
- **initCommitId** (string) - The initial commit ID for the plugin.
- **repoOwner** (string) - The GitHub repository owner.
- **repoName** (string) - The GitHub repository name.
- **commitDate** (string) - The date and time of the last commit (ISO 8601 format).
- **pluginJson** (object) - Contains common plugin metadata:
  - **common_name** (string) - The common name of the plugin.
  - **description** (string) - A brief description of the plugin.
  - **tags** (array) - An array of tags associated with the plugin.
- **downloadCount** (integer) - The total number of downloads for the plugin.
- **downloadSize** (string) - The size of the plugin download (e.g., "245.67 KB").

#### Response Example
```json
[
  {
    "id": "a1b2c3d4e5f6",
    "commitId": "a1b2c3d4e5f6789012345678901234567890abcd",
    "initCommitId": "a1b2c3d4e5f6789012345678901234567890abcd",
    "repoOwner": "username",
    "repoName": "my-steam-plugin",
    "commitDate": "2024-01-15T10:30:00Z",
    "pluginJson": {
      "common_name": "My Steam Plugin",
      "description": "Adds awesome features to Steam",
      "tags": ["ui", "enhancement"]
    },
    "downloadCount": 1234,
    "downloadSize": "245.67 KB"
  }
]
```

### Notes
- This API aggregates data from plugin lists, metadata.json, Cloud Storage, and Firestore download records.
- The endpoint response is cached for 30 minutes.
```

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

### Install Millennium on Other Linux Distributions (Shell)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/getting-started/installation.md

Installs Millennium on Linux distributions other than Arch or NixOS using a pre-built binary via a shell script. The installation script is open-source and can be audited. After installation, a patch command is required.

```bash
curl -fsSL "https://raw.githubusercontent.com/SteamClientHomebrew/Millennium/main/scripts/install.sh" | sudo sh
```

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

### Custom Patch Example for Steambrew

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/intermediate/custom-structure.md

This JSON object demonstrates a single custom patch configuration. It specifies a regular expression to match the '.FullModalOverlay' class in the DOM body. If matched, it instructs Millennium to load 'libraryroot.custom.js' and 'libraryroot.custom.css' into the matching Steam window. This is an example of how to target specific elements for custom theming.

```json
{
	"MatchRegexString": ".FullModalOverlay",
	"TargetCss": "libraryroot.custom.css",
	"TargetJs": "libraryroot.custom.js"
}
```

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

### Get Steam Installation Path (Lua)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Provides a Lua snippet to get the installation path of Steam. It includes a warning that this path is not guaranteed to be where Millennium itself is installed.

```lua
millennium.steam_path()
```

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

### Get Millennium Installation Path (Lua)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Shows how to retrieve the installation path of the Millennium module itself. A warning is included stating this may differ from the Steam installation path.

```lua
millennium.get_install_path()
```

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

### GET /api/v2/

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Fetches featured themes and plugins, including their GitHub repository data and configuration files. This endpoint is filtered to exclude disabled themes and uses GraphQL batching for efficient GitHub data retrieval.

```APIDOC
## GET /api/v2/

### Description
Fetches featured themes and plugins with GitHub repository data and configuration files. Excludes disabled themes and uses efficient GitHub data fetching.

### Method
GET

### Endpoint
/api/v2/

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Get featured content
curl https://steambrew.app/api/v2/
```

### Response
#### Success Response (200)
Returns an array of featured content objects, each containing:
- **name** (string) - The name of the theme or plugin.
- **description** (string) - A description of the theme or plugin.
- **version** (string) - The version number.
- **header_image** (string) - URL to the header image.
- **splash_image** (string) - URL to the splash image.
- **tags** (array) - An array of tags.
- **download** (string) - Direct download URL for the content.
- **commit_data** (object) - Data related to the GitHub commit:
  - **oid** (string) - The commit object ID.
  - **committedDate** (string) - The date and time of the commit (ISO 8601 format).
  - **commitUrl** (string) - URL to the commit on GitHub.
- **data** (object) - Additional platform-specific data:
  - **id** (string) - The Firestore document ID.
  - **create_time** (string) - The creation time in Firestore (ISO 8601 format).
  - **github** (object) - GitHub repository information:
    - **owner** (string) - The repository owner.
    - **repo** (string) - The repository name.

#### Response Example
```json
[
  {
    "name": "Dark Modern Theme",
    "description": "A sleek dark theme for Steam",
    "version": "1.2.3",
    "header_image": "https://example.com/header.png",
    "splash_image": "https://example.com/splash.png",
    "tags": ["dark", "modern", "minimal"],
    "download": "https://github.com/owner/repo/archive/refs/heads/main.zip",
    "commit_data": {
      "oid": "abc123...",
      "committedDate": "2024-01-20T14:25:00Z",
      "commitUrl": "https://github.com/owner/repo/commit/abc123"
    },
    "data": {
      "id": "theme-doc-id",
      "create_time": "2024-01-01T00:00:00Z",
      "github": {
        "owner": "username",
        "repo": "my-theme"
      }
    }
  }
]
```

### Notes
- This endpoint filters out themes that have been disabled by administrators.
- It employs GraphQL batching to efficiently retrieve data from the GitHub API.
```

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

### Core Functions and Utilities - FetchPlugins()

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Describes the `FetchPlugins()` function, which is the main aggregation function used to build the complete plugin catalog by combining data from multiple sources. This function is called by the `GET /api/v1/plugins/` route.

```APIDOC
## Core Functions and Utilities - FetchPlugins()

### Description
Main aggregation function that combines data from multiple sources to build a complete plugin catalog. This function is called internally by the `GET /api/v1/plugins/` route.

### Method
Internal Function (Called via API)

### Endpoint
(Internal - Called by GET /api/v1/plugins/)

### Parameters
None directly exposed via API. Internally takes dependencies for data fetching.

### Request Example
(Internal function call, not directly from API client)
```typescript
import { FetchPlugins } from './GetPlugins';

async function getPluginCatalog() {
  const result = await FetchPlugins();
  return result.pluginData;
}
```

### Response
#### Success Response
- **pluginData** (array) - An array of complete plugin objects.
- **metadata** (object) - Build metadata, including commit IDs.

#### Response Example
```json
{
  "pluginData": [
    {
      "name": "Example Plugin",
      "version": "1.0.0",
      "description": "A sample plugin.",
      "githubUrl": "https://github.com/user/repo",
      "commitId": "abcdef123456"
      // ... other plugin properties
    }
  ],
  "metadata": {
    "commitId": "abcdef123456",
    "buildDate": "2023-10-27T12:00:00Z"
  }
}
```

### Implementation Flow
1. Check `PluginCache` collection for a valid 30-minute cache.
2. On cache miss:
   a. Fetch plugin list from `github.com/shdwmtr/plugdb`.
   b. Get metadata from `metadata.json` (commit IDs, build info).
   c. Retrieve file sizes from Cloud Storage (`plugins/*.zip`).
   d. Get download counts from Firestore `downloads` collection.
   e. Merge all data sources by commit ID.
3. Cache the result in Firestore with a timestamp.
4. Return the combined dataset.

### Cache Structure
```typescript
interface PluginCacheEntry {
  data: PluginDataTable;
  timestamp: Timestamp; // When cached
  expiresAt: Timestamp; // 30 minutes from timestamp
}
```

### Notes
- Automatic cache invalidation on expiry.
- Fire-and-forget cache updates (non-blocking).
```

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

### Dropdown Configuration Example (JSON)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/intermediate/user.md

This JSON snippet demonstrates how to define a dropdown configuration option for a Steam theme. It includes a description, default value, and multiple selectable values, each associated with a CSS file to be loaded based on the user's selection. This is useful for allowing users to choose visual styles like color themes.

```json
{
  "Conditions": {
    "A ComboBox Item": {
      "description": "A simple combo box",
      "tab": "Theme",
      "default": "Dark",
      "values": {
        "Dark": {
          "TargetCss": {
            "affects": ["^Steam$", "^Steam Big Picture Mode$"],
            "src": "dark.css"
          }
        },
        "Amoled": {
          "TargetCss": {
            "affects": [".*"],
            "src": "amoled.css"
          }
        },
        "Nord": {
          "TargetCss": {
            "affects": [".*"],
            "src": "nord.css"
          }
        }
      }
    }
  }
}
```

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

### Millennium Steam Information Functions

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Functions to retrieve the Steam installation path and the Millennium installation path.

```APIDOC
## `millennium.steam_path()`

### Description
Returns the detected path to the Steam installation directory. Note: This path is not guaranteed to be where Millennium itself is installed.

### Method
`millennium.steam_path(): string

### Parameters
None

### Returns
*   **path** (string) - The absolute path to the Steam installation directory.

### Usage
```lua
local steam_dir = millennium.steam_path()
print("Steam is installed at: " .. steam_dir)
```

## `millennium.get_install_path()`

### Description
Returns the installation path of the Millennium module. This may differ from the Steam installation path.

### Method
`millennium.get_install_path(): string

### Parameters
None

### Returns
*   **path** (string) - The absolute path where Millennium is installed.

### Usage
```lua
local millennium_dir = millennium.get_install_path()
print("Millennium is installed at: " .. millennium_dir)
```
```

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

### Make HTTP GET Request in Lua

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/http.md

Illustrates how to make an HTTP GET request using the `http.get` function. This is a convenient shortcut for common GET operations and supports additional request options like custom headers and timeouts.

```lua
-- Simple GET request
local response, err = http.get("https://api.example.com/users")
if response then
    print("Status:", response.status)
    print("Body:", response.body)
else
    print("Error:", err)
end

-- GET with custom headers
local response, err = http.get("https://api.example.com/data", {
    headers = {
        ["Accept"] = "application/json",
        ["X-API-Key"] = "your-api-key"
    },
    timeout = 5
})

-- GET with query parameters (encode them in the URL)
local response, err = http.get("https://api.example.com/search?q=lua&limit=10")
```

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

### Load CSS and JS into Steam Windows (JSON Example)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/intermediate/user.md

This configuration demonstrates how to load a CSS file into all Steam windows and a JavaScript file into the main Steam UI and community pages. It uses regular expressions to define which windows the assets should be applied to. The `affects` field takes a list of regex strings, and the `src` field specifies the relative path to the asset.

```json
{
	"TargetCss": {
		"affects": [" விளம்பர"],
		"src": "some.css"
	},
	"TargetJs": {
		"affects": ["^Steam$", "https:\/\/steamcommunity.com\/ விளம்பர"],
		"src": "some.js"
	}
}
```

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

### Add Millennium to NixOS Flake Configuration

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/getting-started/installation.md

Configures Millennium for NixOS by adding it as an input to your flake and applying its overlay. This allows Millennium to be used as a package within your NixOS system. It requires updating the flake to fetch the latest commit.

```nix
inputs.millennium.url = "git+https://github.com/SteamClientHomebrew/Millennium";
```

```nix
nixpkgs.overlays = [ inputs.millennium.overlays.default ];
```

```nix
programs.steam = {
  enable = true;
  package = pkgs.steam-millennium;
};
```

```nix
environment.systemPackages = with pkgs;
[
# Your other packages...
steam-millennium
];
```

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

### Require and Use Millennium Module (Lua)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Demonstrates how to load and use the Millennium module in Lua. It shows a basic example of calling the `steam_path` function.

```lua
local millennium = require("millennium")
-- Ex. use Millennium module to get Steam path
millennium.steam_path()
```

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

### POST /api/v2/checkupdates

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Checks for available updates across multiple plugins or themes in a single request. This is useful for batch checking updates for installed add-ons.

```APIDOC
## POST /api/v2/checkupdates

### Description
Checks for available updates across multiple plugins/themes in a single request.

### Method
POST

### Endpoint
/api/v2/checkupdates

### Parameters
#### Request Body
- **installedAddons** (array of objects) - Required - An array of installed add-ons to check for updates.
  - **owner** (string) - Required - The GitHub owner of the repository.
  - **repo** (string) - Required - The GitHub repository name.
  - **commit** (string) - Required - The current commit SHA of the installed add-on.

### Request Example
```json
[
  {
    "owner": "user1",
    "repo": "dark-theme",
    "commit": "abc123old"
  },
  {
    "owner": "user2",
    "repo": "compact-ui",
    "commit": "def456old"
  }
]
```

### Response
#### Success Response (200)
- Returns an array of objects, where each object represents an add-on with available updates.
  - **name** (string) - The name of the repository.
  - **latestCommit** (string) - The latest commit SHA.
  - **commitUrl** (string) - The URL to the latest commit.
  - **committedDate** (string) - The date and time the latest commit was made.
  - **commitMessage** (string) - The commit message of the latest commit.
  - **hasUpdate** (boolean) - True if an update is available, false otherwise.

#### Response Example
```json
[
  {
    "name": "dark-theme",
    "latestCommit": "xyz789new",
    "commitUrl": "https://github.com/.../commit/xyz789new",
    "committedDate": "2023-10-27T10:00:00Z",
    "commitMessage": "Feat: Add new feature",
    "hasUpdate": true
  }
]
```
```

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

### GET /api/millennium/stats

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Returns aggregate download statistics and the latest version for the Millennium project itself. Useful for displaying project metrics.

```APIDOC
## GET /api/millennium/stats

### Description
Returns aggregate download statistics and latest version for Millennium itself.

### Method
GET

### Endpoint
/api/millennium/stats

### Parameters
None

### Request Example
```bash
curl https://steambrew.app/api/millennium/stats
```

### Response
#### Success Response (200)
- **downloadCount** (integer) - The total number of downloads for Millennium.
- **latestVersion** (string) - The latest released version of Millennium.

#### Response Example
```json
{
  "downloadCount": 234567,
  "latestVersion": "v1.5.2"
}
```

### Notes
- Includes historical downloads (174,452) from legacy CDN.
- Paginated through all GitHub releases with rate limiting.
- Cached for 30 minutes (revalidate: 1800).
```

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

### Checkbox Configuration Example (JSON)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/intermediate/user.md

This JSON snippet illustrates the configuration for a checkbox option in a Steam theme. It sets a default value ('yes' or 'no') and links different CSS files to each option. This allows users to toggle features or styles on or off, such as enabling or disabling specific visual elements.

```json
{
  "Conditions": {
    "A Boolean Checkbox": {
      "default": "yes",
      "description": "A simple boolean checkbox",
      "tab": "General",
      "values": {
        "no": {
          "TargetCss": {
            "affects": ["Recoil"],
            "src": "no.css"
          }
        },
        "yes": {
          "TargetCss": {
            "affects": ["Recoil"],
            "src": "yes.css"
          }
        }
      }
    }
  }
}
```

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

### JavaScript DOM Element Finder Helper Function

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/themes/advanced/scripting.md

Demonstrates using the `window.opener.Millennium.findElement` helper function to reliably find DOM elements, even when Steam's UI is not fully loaded. It includes an example with a timeout to prevent infinite waiting.

```javascript
// No matter how long the DOM or Steam's UI takes to load, this helper function will find target DOM element (if it exists)
const elements = await window.opener.Millennium.findElement(window.document, 'body');
// Timeout and reject the promise if the element isn't found within 3 seconds
const timeoutElements = await window.opener.Millennium.findElement(window.document, 'body', 3000);

console.log(elements, timeoutElements); // the <body /> element is logged.
```

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

### Get Millennium Logs (Windows & Linux)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/getting-started/troubleshooting.md

Command to launch Steam with development tools enabled, which is useful for generating Millennium logs. Ensure Steam is fully closed before executing. This command helps in debugging by providing detailed logs for issue analysis.

```powershell
& "$((gp 'HKLM:\SOFTWARE\WOW6432Node\Valve\Steam').InstallPath)\steam.exe" -dev
```

```bash
steam -dev
```

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

### GET /api/v2/details/[slug]

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Retrieves comprehensive details for a specific theme or plugin using its Firestore document ID (slug). This endpoint provides detailed information including README content, customization options, patch details, and Discord integration links.

```APIDOC
## GET /api/v2/details/[slug]

### Description
Retrieves comprehensive details for a specific theme or plugin by its Firestore document ID (slug).

### Method
GET

### Endpoint
/api/v2/details/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The Firestore document ID (slug) of the theme or plugin.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
async function fetchThemeDetails(themeId: string) {
  try {
    const response = await fetch(`https://steambrew.app/api/v2/details/${themeId}`);

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    const theme = await response.json();

    return {
      name: theme.name,
      description: theme.description,
      version: theme.version,
      headerImage: theme.header_image,
      readme: theme.read_me, // Full README.md content
      downloadUrl: theme.download,
      customization: {
        available: theme.customize.able,
        colorCount: theme.customize.length
      },
      patches: {
        windowTargets: theme.patches.specific_windows,
        usesDefault: theme.patches.patches_default,
        count: theme.patches.length
      },
      discord: theme.discord ? {
        serverName: theme.discord.name,
        iconUrl: theme.discord.icon,
        inviteLink: theme.discord.link
      } : null,
      listingStyle: theme.listing_style, // Custom CSS for theme card
      commitInfo: theme.commit_data
    };
  } catch (error) {
    console.error('Failed to fetch theme:', error);
    // Handle specific error codes
    if (error.message.includes('not found')) {
      // 404 - Theme doesn't exist
    } else if (error.message.includes('disabled')) {
      // 403 - Theme disabled by administrators
    } else if (error.message.includes('rate limit')) {
      // 429 - GitHub API rate limit hit
    }
    throw error;
  }
}

// Usage
const theme = await fetchThemeDetails('my-theme-id-123');
console.log(`${theme.name} v${theme.version}`);
```

### Response
#### Success Response (200)
Returns a detailed object for the specified theme or plugin:
- **name** (string) - The name of the theme or plugin.
- **description** (string) - A detailed description.
- **version** (string) - The current version.
- **header_image** (string) - URL to the header image.
- **read_me** (string) - The full content of the README.md file.
- **download** (string) - Direct download URL.
- **customize** (object) - Customization options:
  - **able** (boolean) - Whether the theme is customizable.
  - **length** (integer) - Number of customization options (e.g., color count).
- **patches** (object) - Information about applied patches:
  - **specific_windows** (array) - Targets for specific windows.
  - **patches_default** (boolean) - Indicates if default patches are used.
  - **length** (integer) - The number of patches.
- **discord** (object | null) - Discord integration details:
  - **name** (string) - Server name.
  - **icon** (string) - URL to the server icon.
  - **link** (string) - Invite link to the Discord server.
- **listing_style** (string) - Custom CSS for the theme card in listings.
- **commit_data** (object) - GitHub commit information (see GET /api/v2/ response).

#### Response Example
```json
{
  "name": "My Awesome Plugin",
  "description": "Enhances Steam functionality with new features.",
  "version": "1.0.0",
  "header_image": "https://example.com/header.png",
  "read_me": "# My Awesome Plugin\nThis plugin does amazing things...",
  "download": "https://github.com/owner/repo/archive/refs/heads/main.zip",
  "customize": {
    "able": true,
    "length": 5
  },
  "patches": {
    "specific_windows": ["steamwebhelper"],
    "patches_default": false,
    "length": 2
  },
  "discord": {
    "name": "Plugin Support",
    "icon": "https://example.com/discord-icon.png",
    "link": "https://discord.gg/example"
  },
  "listing_style": ".theme-card { background-color: #f0f0f0; }",
  "commit_data": {
    "oid": "abcdef123...",
    "committedDate": "2024-01-25T12:00:00Z",
    "commitUrl": "https://github.com/owner/repo/commit/abcdef123"
  },
  "data": {
    "id": "my-plugin-id-456",
    "create_time": "2024-01-05T09:00:00Z",
    "github": {
      "owner": "username",
      "repo": "my-awesome-plugin"
    }
  }
}
```

### Error Handling
- **404 Not Found**: If the slug does not match any existing theme or plugin.
- **403 Forbidden**: If the theme or plugin has been disabled by administrators.
- **429 Too Many Requests**: If the GitHub API rate limit is exceeded during data fetching.
```

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

### Check for Plugin Updates via POST /api/v2/checkupdates

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Checks for available updates across multiple plugins or themes in a single request. It takes an array of installed addons with their current commit SHAs and returns a list of repositories that have newer versions available.

```typescript
interface UpdateRequest {
  owner: string;
  repo: string;
  commit: string; // Current commit SHA user has installed
}

async function checkForUpdates(installedAddons: UpdateRequest[]) {
  const response = await fetch('https://steambrew.app/api/v2/checkupdates', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(installedAddons)
  });

  const updates = await response.json();

  // Returns array of repositories with updates available
  return updates.map(update => ({
    name: update.name,
    latestCommit: update.defaultBranchRef.target.oid,
    commitUrl: update.defaultBranchRef.target.commitUrl,
    committedDate: update.defaultBranchRef.target.committedDate,
    commitMessage: update.defaultBranchRef.target.history.edges[0]?.node.message,
    hasUpdate: update.defaultBranchRef.target.oid !== installedAddons.find(
      a => a.repo === update.name
    )?.commit
  }));
}

// Example: Check updates for user's installed themes
const installed = [
  { owner: 'user1', repo: 'dark-theme', commit: 'abc123old' },
  { owner: 'user2', repo: 'compact-ui', commit: 'def456old' }
];

const updates = await checkForUpdates(installed);
updates.forEach(update => {
  if (update.hasUpdate) {
    console.log(`Update available for ${update.name}!`);
    console.log(`Latest: ${update.commitMessage}`);
  }
});
```

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

### Retrieve All Plugins API (Bash)

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Fetches a complete list of all available plugins, including their metadata, download counts, and file sizes. This endpoint aggregates data from multiple sources and utilizes a 30-minute cache.

```bash
# Fetch all plugins
curl https://steambrew.app/api/v1/plugins/

# Response structure
[
  {
    "id": "a1b2c3d4e5f6",
    "commitId": "a1b2c3d4e5f6789012345678901234567890abcd",
    "initCommitId": "a1b2c3d4e5f6789012345678901234567890abcd",
    "repoOwner": "username",
    "repoName": "my-steam-plugin",
    "commitDate": "2024-01-15T10:30:00Z",
    "pluginJson": {
      "common_name": "My Steam Plugin",
      "description": "Adds awesome features to Steam",
      "tags": ["ui", "enhancement"]
    },
    "downloadCount": 1234,
    "downloadSize": "245.67 KB"
  }
]

# Implementation uses 30-minute cache
# Aggregates from: plugin list, metadata.json, Cloud Storage, Firestore downloads

```

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

### Get Millennium Stats via GET /api/millennium/stats

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Retrieves aggregate download statistics and the latest version for Millennium. This endpoint can be accessed via a cURL command or integrated into JavaScript applications to display usage data.

```bash
# Get Millennium download stats
curl https://steambrew.app/api/millennium/stats

# Response
{
  "downloadCount": 234567,
  "latestVersion": "v1.5.2"
}

# JavaScript integration for homepage stats
async function displayMillenniumStats() {
  const response = await fetch('/api/millennium/stats');
  const { downloadCount, latestVersion } = await response.json();

  // Use with react-countup for animated display
  return {
    downloads: downloadCount,
    version: latestVersion
  };
}

# Note: Includes historical downloads (174,452) from legacy CDN
# Paginated through all GitHub releases with rate limiting
# Cached for 30 minutes (revalidate: 1800)
```

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

### Fetch Featured Themes and Plugins API (Bash)

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Retrieves featured themes and plugins, including their GitHub repository data and configuration files. This endpoint filters out disabled themes and uses GraphQL batching for efficient data fetching.

```bash
# Get featured content
curl https://steambrew.app/api/v2/

# Response includes parsed skin.json and repository metadata
[
  {
    "name": "Dark Modern Theme",
    "description": "A sleek dark theme for Steam",
    "version": "1.2.3",
    "header_image": "https://example.com/header.png",
    "splash_image": "https://example.com/splash.png",
    "tags": ["dark", "modern", "minimal"],
    "download": "https://github.com/owner/repo/archive/refs/heads/main.zip",
    "commit_data": {
      "oid": "abc123...",
      "committedDate": "2024-01-20T14:25:00Z",
      "commitUrl": "https://github.com/owner/repo/commit/abc123"
    },
    "data": {
      "id": "theme-doc-id",
      "create_time": "2024-01-01T00:00:00Z",
      "github": {
        "owner": "username",
        "repo": "my-theme"
      }
    }
  }
]

# Filtered: excludes disabled themes
# Uses GraphQL batching for efficient GitHub data fetching

```

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

### Build GitHub GraphQL Queries for Batch Operations

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

These JavaScript functions dynamically build GitHub GraphQL queries to perform batch operations such as fetching multiple themes, checking for repository updates, and retrieving single repository details. They utilize helper classes from './GraphQLHandler' and interact with GitHub's API via 'GraphQLInterop'. The queries are cached in Firestore for 45 minutes.

```javascript
import { GraphQLFeatured, GraphQLUpdates, GraphQLRepository } from './GraphQLHandler';
import { GithubGraphQL } from './GraphQLInterop';

// Example 1: Fetch multiple themes in single GraphQL request
async function getFeaturedThemes(themes) {
  const handler = new GraphQLFeatured();

  // Add each theme to batch query
  themes.forEach(theme => {
    handler.add_doc(theme.owner, theme.repo);
  });

  // Execute single GraphQL request for all themes
  const result = await GithubGraphQL.Post(handler.get());

  // Result structure: { data: { _0: {...}, _1: {...}, ... } }
  // Each key (_0, _1, etc.) corresponds to a repository

  return Object.values(result.data).map(repo => ({
    name: repo.name,
    defaultBranch: repo.defaultBranchRef.name,
    skinConfig: JSON.parse(repo.file.text), // skin.json
    latestCommit: repo.defaultBranchRef.target.oid,
    downloadUrl: repo.defaultBranchRef.target.zipballUrl
  }));
}

// Example 2: Check updates for multiple repos
async function checkUpdates(repositories) {
  const handler = new GraphQLUpdates();

  repositories.forEach(repo => {
    handler.add(repo.owner, repo.name);
  });

  const updates = await GithubGraphQL.Post(handler.get());

  return Object.values(updates.data).map(repo => ({
    name: repo.name,
    latestCommit: repo.defaultBranchRef.target.oid,
    commitDate: repo.defaultBranchRef.target.committedDate,
    commitMessage: repo.defaultBranchRef.target.history.edges[0].node.message
  }));
}

// Example 3: Get single repository details
async function getRepoDetails(owner, repo, readmePath = 'README.md') {
  const handler = new GraphQLRepository();
  const query = handler.get(owner, repo, readmePath);

  const result = await GithubGraphQL.Post(query);
  const repoData = result.data.repository;

  return {
    config: JSON.parse(repoData.file.text), // skin.json
    readme: repoData.read_me.text, // README content
    customCSS: repoData.listing_style?.text, // millennium.styles.css
    defaultBranch: repoData.default_branch.name
  };
}

// All queries use 45-minute cache in GraphQLCache Firestore collection
// Normalized query keys for consistent caching

```

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

### Common API Patterns

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/http.md

Illustrates common patterns for interacting with APIs, including robust error handling, working with JSON data, accessing response headers, and managing request timeouts.

```APIDOC
## Common API Patterns

### Error Handling

This example shows how to check for network errors and handle different HTTP status codes.

```lua
local response, err = http.get("https://api.example.com/data")

if not response then
    print("Request failed:", err)
    return
end

if response.status >= 200 and response.status < 300 then
    print("Success:", response.body)
elseif response.status == 404 then
    print("Resource not found")
elseif response.status >= 500 then
    print("Server error:", response.status)
else
    print("Unexpected status:", response.status)
end
```

### Working with JSON APIs

Demonstrates how to send JSON data in a request body and parse JSON responses.

```lua
-- Making a JSON API request
local payload = cjson.encode({
    username = "user123",
    email = "user@example.com"
})

local response, err = http.post("https://api.example.com/register", payload, {
    headers = {
        ["Content-Type"] = "application/json",
        ["Accept"] = "application/json"
    }
})

if response and response.status == 201 then
    local data = cjson.decode(response.body)
    print("User ID:", data.id)
end
```

### Accessing Response Headers

Shows how to retrieve specific headers from an HTTP response.

```lua
local response, err = http.get("https://api.example.com/data")

if response then
    print("Content-Type:", response.headers["content-type"])
    print("Content-Length:", response.headers["content-length"])

    -- Headers are case-insensitive in HTTP, but stored as-is
    for key, value in pairs(response.headers) do
        print(key .. ": " .. value)
    end
end
```

### Using Timeouts

Explains how to set timeouts for requests to prevent them from hanging indefinitely.

```lua
-- Short timeout for health checks
local response, err = http.get("https://api.example.com/health", {
    timeout = 2
})

-- Longer timeout for data processing endpoints
local response, err = http.post("https://api.example.com/process", data, {
    timeout = 60
})
```
```

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

### POST /api/v2/download

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

Increments the download counter for a theme or plugin tracked by GitHub owner/repo. This endpoint is used to track user downloads.

```APIDOC
## POST /api/v2/download

### Description
Increments download counter for a theme or plugin tracked by GitHub owner/repo.

### Method
POST

### Endpoint
/api/v2/download

### Parameters
#### Request Body
- **owner** (string) - Required - The GitHub owner of the repository.
- **repo** (string) - Required - The GitHub repository name.

### Request Example
```json
{
  "owner": "steamuser",
  "repo": "awesome-theme"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the download tracking was successful.
- **data** (object) - Contains additional data related to the download count.
  - **count** (integer) - The new total download count.

#### Response Example
```json
{
  "success": true,
  "data": {
    "count": 12345
  }
}
```
```

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

### Remove Millennium from NixOS System Packages

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/parting-ways/uninstall.md

This Nix code snippet shows how to remove `steam-millennium` from the `environment.systemPackages` list in a NixOS `configuration.nix` file. This ensures that Millennium is no longer installed as a system-wide package.

```nix
steam-millennium # [!code --]
```

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

### Fetch Plugin Catalog via FetchPlugins()

Source: https://context7.com/steamclienthomebrew/steambrew/llms.txt

The main aggregation function that combines data from multiple sources to build a complete plugin catalog. It checks a cache, fetches data from GitHub and Cloud Storage, retrieves download counts from Firestore, merges the data, and caches the result.

```typescript
import { FetchPlugins } from './GetPlugins';

// Called by GET /api/v1/plugins/ route
async function getPluginCatalog() {
  const result = await FetchPlugins();

  // Returns { pluginData: [...], metadata: [...] }
  const { pluginData, metadata } = result;

  // pluginData: array of complete plugin objects
  // metadata: build metadata with commit IDs

  return pluginData;
}

// Implementation flow:
// 1. Check PluginCache collection for valid 30-min cache
// 2. On cache miss:
//    a. Fetch plugin list from github.com/shdwmtr/plugdb
//    b. Get metadata from metadata.json (commit IDs, build info)
//    c. Retrieve file sizes from Cloud Storage (plugins/*.zip)
//    d. Get download counts from Firestore downloads collection
//    e. Merge all data sources by commit ID
// 3. Cache result in Firestore with timestamp
// 4. Return combined dataset

// Cache entry structure
interface PluginCacheEntry {
  data: PluginDataTable;
  timestamp: Timestamp; // When cached
  expiresAt: Timestamp; // 30 minutes from timestamp
}

// Automatic cache invalidation on expiry
// Fire-and-forget cache updates (non-blocking)
```

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

### Find Millennium Version on Windows

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/users/guides/finding-millennium-version.md

This PowerShell command retrieves the file version of the Millennium DLL. It assumes Millennium is installed in the default Steam directory. This command might error if the version is prior to v2.25.1.

```powershell
(gi "$(gp 'HKLM:\SOFTWARE\Wow6432Node\Valve\Steam' | % InstallPath)\millennium.dll").VersionInfo.FileVersion
```

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

### Make POST Request with Steambrew HTTP Client

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/http.md

Demonstrates how to make POST requests using the Steambrew HTTP client. Supports sending JSON or form data, and includes options for authentication and custom headers. Handles response objects or nil on failure with an optional error message.

```lua
-- POST JSON data
local json_data = cjson.encode({ name = "John", age = 30 })
local response, err = http.post("https://api.example.com/users", json_data, {
    headers = {
        ["Content-Type"] = "application/json"
    }
})

-- POST form data
local form_data = "username=john&password=secret"
local response, err = http.post("https://example.com/login", form_data, {
    headers = {
        ["Content-Type"] = "application/x-www-form-urlencoded"
    }
})

-- POST with authentication
local response, err = http.post("https://api.example.com/submit", '{"data":"value"}', {
    headers = {
        ["Content-Type"] = "application/json"
    },
    auth = {
        user = "apiuser",
        pass = "apipass"
    }
})
```

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

### Get Millennium Version (Lua)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Explains how to retrieve the current version of the Millennium module. The version is returned as a string following Semantic Versioning standards (e.g., 'v2.30.0'). Pre-release versions have a different format.

```lua
millennium.version()
```

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

### Signal Plugin Ready with Millennium (Lua)

Source: https://github.com/steamclienthomebrew/steambrew/blob/main/apps/docs/src/plugins/lua-module-docs/millennium.md

Shows how to signal that the Millennium Lua plugin backend is ready. Millennium waits for this signal for 10 seconds, and calling it promptly is crucial for user experience.

```lua
local millennium = require("millennium")

local function on_load()
    -- let millennium know your plugin has loaded.
    millennium.ready()
end

return {
    -- ... other functions ...
    on_load = on_load
}
```