### Execute Setup Scripts and Launch Containers

Source: https://github.com/swgoh-utils/swgoh-comlink/blob/main/installation/raspberry_pi/README.md

Run the provided shell scripts to configure the environment and start the services via Docker Compose.

```bash
1_setup_docker_apt_repo.sh
2_install_docker_pkgs.sh
3_setup_docker_env.sh

docker compose up
```

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

### Python Client Example

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Example usage of the official Python client library for simplified API access.

```APIDOC
## Python Client Example

Use the official Python client library for simplified API access.

### Installation
```bash
pip install swgoh-comlink
```

### Usage

```python
import requests

COMLINK_URL = "http://localhost:3000"

def get_player(ally_code):
    response = requests.post(
        f"{COMLINK_URL}/player",
        json={
            "payload": {"allyCode": str(ally_code)},
            "enums": False
        }
    )
    return response.json()

def get_guild_roster(guild_id):
    """Get complete guild roster by fetching all member profiles"""
    # Get guild data
    guild_response = requests.post(
        f"{COMLINK_URL}/guild",
        json={
            "payload": {
                "guildId": guild_id,
                "includeRecentGuildActivityInfo": True
            },
            "enums": False
        }
    )
    guild_data = guild_response.json()

    # Fetch each member's full profile
    roster = []
    for member in guild_data.get("member", []):
        player_data = requests.post(
            f"{COMLINK_URL}/player",
            json={
                "payload": {"playerId": member["playerId"]},
                "enums": False
            }
        ).json()
        roster.append(player_data)

    return roster

# Example usage
player = get_player("596966614")
print(f"Player: {player['name']}, GP: {player.get('galacticPower', 'N/A')}")
```
```

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

### Get Guild Leaderboard (Total Raid Points)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

This cURL example demonstrates how to retrieve the total raid points leaderboard for guilds. Ensure the leaderboardType is set to 0.

```bash
# Get Total Raid Points leaderboard
curl -X POST "http://localhost:3000/getGuildLeaderboard" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "leaderboardId": [
        {
          "leaderboardType": 0,
          "monthOffset": 0
        }
      ],
      "count": 200
    },
    "enums": false
  }'
```

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

### Unit Guide Layout API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Contains information about the Journey Guide's layout structure.

```APIDOC
## GET /unitGuideLayout

### Description
Retrieves information on the Journey Guide layout structure.

### Method
GET

### Endpoint
/unitGuideLayout

### Parameters
#### Query Parameters
- **id** (string) - Required - Identifier for the unit guide layout.

### Response
#### Success Response (200)
- **id** (string) - Identifier for the unit guide layout.

#### Response Example
{
  "id": "some_layout_id"
}
```

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

### Metadata Request Body Example

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Example JSON payload for requesting metadata, including client specifications and enum preference.

```json
{
  "payload": {
    "clientSpecs": {
      "platform": "Android",
      "bundleId": "string",
      "externalVersion": "string",
      "internalVersion": "string",
      "region": "string"
    }
  },
  "enums": false
}
```

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

### Docker Compose Setup for Comlink and Stats

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Configure a complete environment using Docker Compose, including SWGoH Comlink and the SWGoH Stats service. This setup allows for stats calculation and defines environment variables for application name, port, and optional HMAC signing keys. It also includes a healthcheck for the Comlink service.

```yaml
services:
  swgoh-comlink:
    container_name: swgoh-comlink
    image: ghcr.io/swgoh-utils/swgoh-comlink:latest
    restart: always
    environment:
      APP_NAME: swgoh-comlink-dev
      PORT: 3000
      ACCESS_KEY: my-access-key    # Optional: for HMAC signing
      SECRET_KEY: my-secret-key    # Optional: for HMAC signing
    ports:
      - 5000:3000
    healthcheck:
      test: ["CMD", "/swgoh-comlink", "--check"]
      start_period: 10s

  swgoh-stats:
    container_name: swgoh-stats
    image: ghcr.io/swgoh-utils/swgoh-stats:latest
    restart: always
    depends_on:
      swgoh-comlink:
        condition: service_healthy
    environment:
      CLIENT_URL: http://swgoh-comlink:3000
      PORT: 3223
    ports:
      - 3223:3223
```

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

### Get Game Events

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve all currently displayed and scheduled game events, including training events, Journey Guide events, and GAC schedules. Typically shows events up to 5-10 days out.

```bash
curl -X POST "http://localhost:3000/getEvents" \
  -H "Content-Type: application/json" \
  -d '{
    "enums": false
  }'
```

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

### Unit Guide Definition API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Provides detailed information on all Journey Guide units, used for retrieving assets and data related to Journey Guide events.

```APIDOC
## GET /unitGuideDefinition

### Description
Retrieves detailed information on all Journey Guide units.

### Method
GET

### Endpoint
/unitGuideDefinition

### Parameters
#### Query Parameters
- **activityId** (string) - Required - Identifier for the activity.
- **id** (string) - Required - Reference ID for the unit guide.

### Response
#### Success Response (200)
- **campaign** (object) - Information about campaign references.
  - **campaignNode** (string) - Referenced in campaign node.
  - **campaignId** (string) - Reference ID for the campaign.
- **material** (object) - Information about material references.
  - **missionIdentifier** (string) - Referenced in material mission.

#### Response Example
{
  "campaign": {
    "campaignNode": "some_node",
    "campaignId": "some_campaign_id"
  },
  "material": {
    "missionIdentifier": "some_mission_id"
  }
}
```

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

### Example response for player data

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Player-Data

The structure of the JSON object returned by the /player endpoint.

```json
{
  "rosterUnit": [],
  "playerRating": [],
  "profileStat": [],
  "pvpProfile": [],
  "unlockedPlayerTitle": [],
  "unlockedPlayerPortrait": [],
  "seasonStatus": [],
  "datacron": [],
  "selectedPlayerTitle": {},
  "selectedPlayerPortrait": {},
  "name": "Kidori",
  "level": 85,
  "allyCode": "596966614",
  "playerId": "xW1z7pRBS4q-aTs1uQjGys",
  "guildId": "PdxGl_0-Tjec_h_qE5o9jA",
  "guildName": "Galactic Kn??ghts",
  "guildLogoBackground": "",
  "guildBannerColor": "bright_blue_dark_blue",
  "guildBannerLogo": "guild_icon_jedi",
  "guildTypeId": "NORMAL",
  "localTimeZoneOffsetMinutes": -240,
  "lastActivityTime": "1651947547000",
  "lifetimeSeasonScore": "246798"
}
```

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

### Request In-Game Events

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Example payload for retrieving currently scheduled in-game events.

```json
{
  "enums": false
}
```

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

### POST /localization - Get Localization Data

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Obtain localization bundles for game content in various languages. Use the localization version obtained from the `/metadata` endpoint. The `unzip` option can be set to true to receive unzipped data. Specify the locale ID for the desired language.

```bash
# Get English localization only (smaller response)
curl -X POST "http://localhost:3000/localization" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "id": "AfjAusw7RraFX011_Kwi2Q:ENG_US"
    },
    "unzip": true
  }'
```

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

### POST /data - Get Game Data (All)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve all game data, which can be a large response (200+ MB). Specify the game data version obtained from the `/metadata` endpoint and set `requestSegment` to 0. `includePveUnits` can be set to false to exclude player-versus-environment units.

```bash
# Get all game data (200+ MB)
curl -X POST "http://localhost:3000/data" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "version": "0.28.6:benKkOetTsaMZVWKY4E-LA",
      "includePveUnits": false,
      "requestSegment": 0
    },
    "enums": false
  }'
```

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

### Request Guild Profile

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Example payload for retrieving a guild profile by ID.

```json
{
  "payload": {
    "guildId": "jrl9Q-_CRDGdMyNjTQH1rQ",
    "includeRecentGuildActivityInfo": true
  },
  "enums": false
}
```

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

### Install Postman v9 via Chocolatey

Source: https://github.com/swgoh-utils/swgoh-comlink/blob/main/postman/README.md

Use these commands to remove newer versions of Postman and install version 9.31.0 to maintain collection import/export functionality.

```sh
choco uninstall postman -n
choco install postman --version=9.31.0
```

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

### Guild Profile Data Structure

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Guild-Data

Example JSON object representing a guild's profile information.

```json
{
  "messageCriteriaKey":  []
  "raidLaunchConfig": […]
  "guildEventTracker": […]
  "id": "jrl9Q-_CRDGdMyNjTQH1rQ"
  "name": "MΔW"
  "externalMessageKey": "#1 TW guild. 40 *s & 50/…619 or Chiss#0066 MΔW-C"
  "logoBackground": ""
  "enrollmentStatus": 2
  "trophy": 0
  "memberCount": 50
  "memberMax": 50
  "level": 1
  "rank": 0
  "levelRequirement": 20
  "raidWin": 0
  "leaderboardScore": "0"
  "bannerColorId": "red_white"
  "bannerLogoId": "guild_icon_empire"
  "guildGalacticPower": "595835461"
  "chatChannelId": "guild-{jrl9Q-_CRDGdMyNjTQH1rQ}"
  "guildType": ""
  "guildGalacticPowerForRequirement": "595835461"
}
```

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

### Member Data Structure

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Guild-Data

Example JSON object representing a guild member's profile data.

```json
{
  "memberContribution": [],
  "seasonStatus": [],
  "playerId": "p5dB_6irTVuIWWUoTky3qT",
  "playerName": "Kidori",
  "playerLevel": 85,
  "memberLevel": 3,
  "guildXp": 0,
  "lastActivityTime": "1674843042000",
  "squadPower": 206096,
  "guildJoinTime": "1611264476",
  "galacticPower": "4324722",
  "playerTitle": "PLAYERTITLE_SEPARATIST_COMMANDER",
  "playerPortrait": "PLAYERPORTRAIT_SMUG3",
  "lifetimeSeasonScore": "978389",
  "leagueId": "CARBONITE"
}
```

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

### Set Up HMAC Authentication for Comlink

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Configure HMAC authentication for your Comlink instance by setting the ACCESS_KEY and SECRET_KEY environment variables when starting the Docker container.

```bash
# Set environment variables when starting Comlink
docker run --name swgoh-comlink \
  -e APP_NAME=my-app \
  -e ACCESS_KEY=your-access-key \
  -e SECRET_KEY=your-secret-key \
  -p 3000:3000 \
  ghcr.io/swgoh-utils/swgoh-comlink:latest
```

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

### POST /localization - Get Localization Data

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieves localization bundles that contain names and descriptions for all game content in various languages. It is recommended to use the localization version obtained from the `/metadata` endpoint.

```APIDOC
## POST /localization - Get Localization Data

### Description
Returns localization bundles containing names and descriptions for all game content in multiple languages. Use the localization version from `/metadata` endpoint.

### Method
POST

### Endpoint
/localization

### Parameters
#### Request Body
- **payload** (object) - Required - Payload for the request.
  - **id** (string) - Required - The identifier for the localization bundle, typically in the format "{version}:{locale}" (e.g., "AfjAusw7RraFX011_Kwi2Q:ENG_US").
- **unzip** (boolean) - Optional - Whether to unzip the localization data. Defaults to false.

### Request Example
```bash
# Get English localization only (smaller response)
curl -X POST "http://localhost:3000/localization" \
  -H "Content-Type: application/json" \
  -d 
  '{
    "payload": {
      "id": "AfjAusw7RraFX011_Kwi2Q:ENG_US"
    },
    "unzip": true
  }'
```

### Response
#### Success Response (200)
- **locale** (string) - The locale of the returned data (e.g., "ENG_US").
- **data** (object) - An object containing localized strings.

#### Response Example
```json
{
  "locale": "ENG_US",
  "data": {
    "characters": {
      "LUKE_SKYWALKER": {
        "name": "Luke Skywalker",
        "description": "A farm boy who discovers his destiny."
      }
    },
    "abilities": {
      "LIGHTSABER_SLASH": {
        "name": "Lightsaber Slash",
        "description": "A basic attack with a lightsaber."
      }
    }
  }
}
```

### Available Locales
- ENG_US (English)
- CHS_CN (Chinese Simplified)
- CHT_CN (Chinese Traditional)
- FRE_FR (French)
- GER_DE (German)
- IND_ID (Indonesian)
- ITA_IT (Italian)
- JPN_JP (Japanese)
- KOR_KR (Korean)
- POR_BR (Portuguese Brazil)
- RUS_RU (Russian)
- SPA_XM (Spanish)
- THA_TH (Thai)
- TUR_TR (Turkish)
```

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

### Search Guilds by Criteria

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Example payload for searching guilds based on specific galactic power and territory battle participation criteria.

```json
{
  "payload": {
    "filterType": 5,
    "count": 10,
    "searchCriteria": {
      "minGuildGalacticPower": 430000000,
      "recentTbParticipatedIn": ["T05D"]
    }
  },
  "enums": false
}
```

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

### GET /enums

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Retrieves an object containing all of the game data enums.

```APIDOC
## GET /enums

### Description
Returns an object containing all of the game data enums.

### Method
GET

### Endpoint
/enums
```

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

### POST /data - Get Game Data (Specific Collections)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Fetch specific game data collections using a binary mask for the `items` parameter. This allows for more targeted data retrieval, reducing response size. The `enums` parameter can be set to true to include enum values in the response.

```bash
# Get specific collections using binary mask (units + skill + category)
# units=137438953472, skill=4, category=1
# Sum: 137438953477
curl -X POST "http://localhost:3000/data" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "version": "0.28.6:benKkOetTsaMZVWKY4E-LA",
      "includePveUnits": false,
      "items": "137438953477"
    },
    "enums": true
  }'
```

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

### GET /enums - Get Game Enums

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve all game data enums used for decoding integer values to their string representations. This endpoint is useful for interpreting raw API responses.

```bash
curl -X GET "http://localhost:3000/enums"
```

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

### Raid Data Structure

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Guild-Data

Example JSON object representing raid performance and status data.

```json
{
  "raidMember": [],
  "raidId": "rancor_challenge",
  "identifier": {},
  "duration": "80813",
  "progress": 0,
  "endTime": "1674584862",
  "outcome": 1
}
```

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

### SWGOH Comlink Data Object Example

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Illustrates how 'Identifier' and 'Reference ID' keys are used to link objects between different data collections in SWGOH Comlink. Pay attention to how 'id' and 'baseId' in 'units' are referenced in other collections.

```json
//Main Object
units: [
   0: {
      "id": "BB8:SEVEN_STAR",    //Identifier A
      "baseId": "BB8",           //Identifier B
      ...
   },...
]
//Referenced in object for ID A
//Reference ID = id
//Referenced in = requirement => requirementItem
requirement: [
   0: {
      "requirementItem": [
         0: {
            "id": "BB8:SEVEN_STAR",
            ...
         },...
      ],...
   },...
]
//Referenced in object for ID B
//Reference ID = unitBaseId
//Reference in = unitGuideDefinition
unitGuideDefinition: [
   0: {
      unitBaseId: "BB8",
      ...
   },...
]
```

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

### Run Comlink with Docker

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Pull and run the latest SWGoH Comlink image using Docker. This command starts the service in detached mode, restarts it automatically, and maps port 3200 on the host to port 3000 in the container. Verify the service is running by curling the root endpoint.

```bash
docker pull ghcr.io/swgoh-utils/swgoh-comlink:latest
docker run --name swgoh-comlink \
  -d \
  --restart always \
  -e APP_NAME=my-app-name \
  -p 3200:3000 \
  ghcr.io/swgoh-utils/swgoh-comlink:latest

# Verify service is running
curl http://localhost:3200/
```

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

### Get Guild Leaderboard (Territory Battle)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Use this cURL command to fetch guild leaderboard data for Territory Battles. Specify the leaderboard type and defId for the desired battle.

```bash
# Get Territory Battle leaderboard (Rise of the Empire)
curl -X POST "http://localhost:3000/getGuildLeaderboard" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "leaderboardId": [
        {
          "leaderboardType": 4,
          "defId": "t05D",
          "monthOffset": 0
        }
      ],
      "count": 100
    },
    "enums": false
  }'
```

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

### Get Guild Profile with Activity Info

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve a guild's complete profile, including member list, recent raid results, and Territory War history. Set 'includeRecentGuildActivityInfo' to true for activity details.

```bash
curl -X POST "http://localhost:3000/guild" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "guildId": "jrl9Q-_CRDGdMyNjTQH1rQ",
      "includeRecentGuildActivityInfo": true
    },
    "enums": false
  }'
```

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

### Get GAC Leaderboard (Top 50)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve the top 50 Grand Arena Championship (GAC) players for a specific league and division. League and division values are provided in the documentation.

```bash
curl -X POST "http://localhost:3000/getLeaderboard" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "leaderboardType": 6,
      "league": 100,
      "division": 25
    },
    "enums": false
  }'
```

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

### POST /metadata - Get Game Metadata

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Fetch the current game metadata, including the latest game data version and localization bundle version. This information is crucial for subsequent API calls that require specific version identifiers. The request requires client specifications.

```bash
curl -X POST "http://localhost:3000/metadata" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "clientSpecs": {
        "platform": "Android"
      }
    },
    "enums": false
  }'
```

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

### Python Client: Get Guild Roster

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

This Python function retrieves a complete guild roster by first fetching guild data and then fetching individual member profiles. It requires the guild ID.

```python
def get_guild_roster(guild_id):
    """Get complete guild roster by fetching all member profiles"""
    # Get guild data
    guild_response = requests.post(
        f"{COMLINK_URL}/guild",
        json={
            "payload": {
                "guildId": guild_id,
                "includeRecentGuildActivityInfo": True
            },
            "enums": False
        }
    )
    guild_data = guild_response.json()

    # Fetch each member's full profile
    roster = []
    for member in guild_data.get("member", []):
        player_data = requests.post(
            f"{COMLINK_URL}/player",
            json={
                "payload": {"playerId": member["playerId"]},
                "enums": False
            }
        ).json()
        roster.append(player_data)

    return roster

# Example usage
player = get_player("596966614")
print(f"Player: {player['name']}, GP: {player.get('galacticPower', 'N/A')}")

```

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

### Fetch Metadata and Game Data in Node.js

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Demonstrates how to retrieve game metadata and specific game data collections using the official npm package.

```javascript
// npm install @swgoh-utils/comlink

const fetch = require('node-fetch');

const COMLINK_URL = 'http://localhost:3000';

async function getMetadata() {
  const response = await fetch(`${COMLINK_URL}/metadata`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ enums: false })
  });
  return response.json();
}

async function getGameData(version, collections = []) {
  const payload = {
    version,
    includePveUnits: false
  };

  if (collections.length > 0) {
    // Calculate binary mask from collection names
    const COLLECTION_IDS = {
      units: 137438953472,
      skill: 4,
      category: 1,
      ability: 2097152,
      equipment: 8
    };
    const items = collections.reduce((sum, c) => sum + (COLLECTION_IDS[c] || 0), 0);
    payload.items = items.toString();
  } else {
    payload.requestSegment = 0;
  }

  const response = await fetch(`${COMLINK_URL}/data`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ payload, enums: true })
  });
  return response.json();
}

async function main() {
  const metadata = await getMetadata();
  const gameVersion = metadata.latestGamedataVersion;

  console.log(`Game Version: ${gameVersion}`);

  // Get just units and skills
  const data = await getGameData(gameVersion, ['units', 'skill']);
  console.log(`Units loaded: ${data.units?.length || 0}`);
}

main();
```

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

### Run SWGOH Comlink Binary

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Execute the SWGOH Comlink API locally using the downloaded binary. Set the application name and other environment variables as needed.

```sh
1. file path/swgoh-comlink-version.exe -n "Your app name"
2. file path/swgoh-comlink-version.exe -name "Your app name"
3.
```

```sh
SET APP_NAME="Your app name" (windows)
or
EXPORT APP_NAME="Your app name" (mac)
file path/swgoh-comlink-version.exe
```

```sh
SET ACCESS_KEY="your-key"
SET SECRET_KEY="your-key"
or
EXPORT ACCESS_KEY=your-key
EXPORT SECRET_KEY=your-key
```

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

### Deploy SWGoH Comlink with Docker

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Commands to pull the latest image, stop existing containers, and run a new instance with environment variables.

```sh
docker pull ghcr.io/swgoh-utils/swgoh-comlink:latest
docker stop swgoh-comlink
docker rm swgoh-comlink
docker run --name swgoh-comlink \
  -d \
  --restart always \
  --network swgoh-comlink \
  --env APP_NAME=your-app-name-goes-here \
  -p 3200:3000 \
  ghcr.io/swgoh-utils/swgoh-comlink:latest
```

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

### GET /enums - Get Game Enums

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieves an object containing all game data enums, which are used for decoding integer values to their string representations in API responses.

```APIDOC
## GET /enums - Get Game Enums

### Description
Returns an object containing all of the game data enums used throughout the API responses for decoding integer values to their string representations.

### Method
GET

### Endpoint
/enums

### Request Example
```bash
curl -X GET "http://localhost:3000/enums"
```

### Response
#### Success Response (200)
- **enums** (object) - An object containing various game data enums.

#### Response Example
```json
{
  "enums": {
    "UnitType": {
      "UNIDENTIFIED": 0,
      "PLAYER": 1,
      "NPC": 2
    },
    "AbilityType": {
      "ABILITY_TYPE_PERMANENT": 0,
      "ABILITY_TYPE_ATTACK": 1,
      "ABILITY_TYPE_BUFF": 2
    }
  }
}
```
```

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

### SWGOH Comlink Deployment and Usage

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Information on deploying the SWGOH Comlink service using Docker or binaries, and setting environment variables.

```APIDOC
## Deploying SWGOH Comlink

### Using Docker
Deploy the service using provided GitHub repositories:
- [SWGOH Comlink](https://github.com/swgoh-utils/deploy-swgoh-comlink)
- [SWGOH Stats](https://github.com/swgoh-utils/deploy-swgoh-stats)

### Using the Binary
Run the API locally by downloading the release version for your system and executing it from the command line/terminal.

**Setting Application Name:**
1. `file path/swgoh-comlink-version.exe -n "Your app name"`
2. `file path/swgoh-comlink-version.exe -name "Your app name"`
3. Using environment variables:
   - Windows: `SET APP_NAME="Your app name"`
   - macOS/Linux: `EXPORT APP_NAME="Your app name"`
   Then run: `file path/swgoh-comlink-version.exe`

**Setting Other Environment Variables:**
- Windows: `SET ACCESS_KEY="your-key"` and `SET SECRET_KEY="your-key"`
- macOS/Linux: `EXPORT ACCESS_KEY=your-key` and `EXPORT SECRET_KEY=your-key`
```

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

### Tips for Using SWGOH API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Guild-Data

Provides practical advice and strategies for leveraging the SWGOH API, including obtaining guild rosters, calculating daily raid tickets and guild activities, and tracking raid participation.

```APIDOC
## API Usage Tips

### 1. Getting Guild Rosters
To obtain a guild roster without the guild ID:
1. Use the `/player` endpoint with a known ally code to retrieve the `guildId` from the response.
2. Use the `/guild` endpoint with the obtained `guildId` to get the list of members.
3. Parse the `member` field from the guild response to get each member's `playerId`.
4. Send each `playerId` to the `/player` endpoint to fetch the rest of the guild members' rosters.
5. **Optimization**: Save the first player response to the guild roster and exclude it from the list retrieved from the `/guild` endpoint to avoid redundant calls.

### 2. Getting Daily Raid Tickets and Guild Activities
Daily contributions reset daily at the Guild Reset time. To retrieve current daily counts:
1. Call the `/guild` endpoint as close to the Guild Reset time as possible.
2. Identify the Guild Reset time from the `nextChallengesRefresh` field (Epoch Time).
3. For each member in the `member` array:
   - Look for `memberContribution` entries.
   - For Raid Tickets, find entries with `type` = 2.
   - For Guild Tokens (from Guild Activities), find entries with `type` = 1.
   - The daily amount is found in the `currentValue` field.
   - **Note**: Guild Activities `currentValue` reflects rewards collected from the inbox, not necessarily earned that day.
4. **Alternative (using history)**: If historical data is saved, calculate daily contributions using the formula: `(lifetimeValue - currentValue) - previousLifetime`. Update `previousLifetime` with `lifetimeValue - currentValue` for the next calculation.

### 3. Tracking Raid Participation
To track participation in completed raids:
1. Fetch guild data using the `/guild` endpoint.
2. Parse the `recentRaidResult` field.
3. Search for the appropriate `raidId`.
4. For each raid found, iterate through the `raidMember` array.
5. Extract the `playerId` and `memberProgress` (total damage done for completed phases).
   - **Limitation**: This method only works for ended raids that have been successfully completed and cannot track live raid progress.
```

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

### GET /data - Retrieve Game Data

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

This endpoint allows you to retrieve game data. You may need to first call the /metadata endpoint to get the latest game data version ID.

```APIDOC
## POST /data

### Description
Retrieves game data from the SWGOH API. Requires a version ID, which can be obtained from the `/metadata` endpoint.

### Method
POST

### Endpoint
`/data`

### Parameters
#### Request Body
- **payload** (object) - Required - Contains the data request parameters.
  - **version** (string) - Required - The version ID of the game data to retrieve.
  - **includePveUnits** (boolean) - Optional - Specifies whether to include NPC unit information. Defaults to false.
  - **requestSegment** (integer or string) - Optional - Indicates how to request data segments. Use 0 for all data, or 1-4 for partial data. Can also be specified as "items": "-1" for all data.
- **enums** (boolean) - Optional - Specifies whether to include enums. Defaults to false.

### Request Example
```json
{
  "payload": {
    "version": "0.28.6:benKkOetTsaMZVWKY4E-LA",
    "includePveUnits": true,
    "requestSegment": 0
  },
  "enums": false
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the requested game data.

#### Response Example
```json
{
  "data": { ... game data ... }
}
```

### Notes
- `includePveUnits`: Setting this to `true` can increase file size by 30+ MB by including NPC unit information.
- `requestSegment`: Controls the amount and type of data returned. Values 1-4 return partial data for specific objects, with varying sizes and content.
```

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

### API Documentation Access

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Information on accessing the built-in OpenAPI documentation and Redoc UI.

```APIDOC
## Documentation Access

### Built-in Documentation
- **OpenAPI JSON:** `openapi.json`
- **Redoc UI:** Accessible via web browser at `http://localhost:3000/api-docs` (replace 3000 with your configured port).

### Additional Documentation
Detailed information, examples, and parsing guides are available on the wiki:
- [Game Data](Game-Data)
- [Player Data](Player-Data)
- [Guild Data](Guild-Data)
```

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

### Recommended Squad API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Provides a list of squads recommended for the Journey Guide, used for defining recommended teams.

```APIDOC
## GET /api/recommendedSquads

### Description
Retrieves a list of recommended squads for the Journey Guide.

### Method
GET

### Endpoint
/api/recommendedSquads

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **recommendedSquads** (array) - A list of recommended squad objects.
  - **_id** (string) - Unique identifier for the squad.
  - **_id** (string) - Reference ID for the squad, referenced in `requirement`.
  - **_hideRequirement** (string) - Requirement to hide the squad, referenced in `requirement`.
  - **_showRequirement** (string) - Requirement to show the squad, referenced in `requirement`.

#### Response Example
{
  "recommendedSquads": [
    {
      "_id": "journey_guide_squad_1",
      "_hideRequirement": "req_hide_squad_1",
      "_showRequirement": "req_show_squad_1"
    }
  ]
}
```

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

### POST /metadata

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Retrieves the metadata for the game, optionally filtered by client specifications.

```APIDOC
## POST /metadata

### Description
Returns the metadata for the game. You can specify client details to tailor the response.

### Method
POST

### Endpoint
/metadata

### Parameters
#### Request Body
- **payload** (Object) - Optional: Contains request information, including `clientSpecs`.
  - **payload.clientSpecs** (Object) - Optional: Specifies client details.
    - **payload.clientSpecs.platform** (String) - Optional: The device platform (e.g., "Android").
    - **payload.clientSpecs.bundleId** (String) - Optional: The bundle ID.
    - **payload.clientSpecs.externalVersion** (String) - Optional: The external version.
    - **payload.clientSpecs.internalVersion** (String) - Optional: The internal version.
    - **payload.clientSpecs.region** (String) - Optional: The region.
- **enums** (Boolean) - Optional: If true, returns data using enum values instead of integers.

### Request Example
```json
{
  "payload": {
    "clientSpecs": {
      "platform": "Android",
      "bundleId": "string",
      "externalVersion": "string",
      "internalVersion": "string",
      "region": "string"
    }
  },
  "enums": false
}
```

### Response
#### Success Response (200)
- **metadata** (Object) - Contains the game metadata.
- **enums** (Object) - Contains game enums if requested.
```

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

### Get GAC Leaderboard (Bracket)

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

Retrieve a GAC bracket leaderboard. This is only available during active GAC events. Requires 'eventInstanceId' and 'groupId'.

```bash
curl -X POST "http://localhost:3000/getLeaderboard" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "leaderboardType": 4,
      "eventInstanceId": "CHAMPIONSHIPS_GRAND_ARENA_GA2_EVENT_SEASON_36:O1676412000000",
      "groupId": "CHAMPIONSHIPS_GRAND_ARENA_GA2_EVENT_SEASON_36:O1676412000000:KYBER:100"
    },
    "enums": false
  }'
```

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

### GET Guild Data

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Guild-Data

Retrieve guild data by providing a guild ID. The `includeRecentGuildActivityInfo` parameter controls the level of detail for recent activity.

```APIDOC
## POST /guild

### Description
Retrieves detailed information about a specific guild using its unique ID. You can optionally include recent activity information for members and events.

### Method
POST

### Endpoint
/guild

### Parameters
#### Request Body
- **payload** (object) - Required - Contains the guild ID and activity information flag.
  - **guildId** (string) - Required - The unique identifier for the guild.
  - **includeRecentGuildActivityInfo** (boolean) - Optional - If true, includes recent activity details; otherwise, returns a smaller payload. Defaults to false.
- **enums** (boolean) - Optional - Specifies whether to return enum values or their raw data. Defaults to false.

### Request Example
```json
{
  "payload":{
        "guildId": "jrl9Q-_CRDGdMyNjTQH1rQ",
        "includeRecentGuildActivityInfo": true
  },
  "enums": false
}
```

### Response
#### Success Response (200)
- **member** (array) - List of guild members with brief details.
- **inviteStatus** (array) - Currently not returned.
- **raidStatus** (array) - Currently not returned.
- **raidResult** (array) - Currently not returned.
- **territoryBattleStatus** (array) - Currently not returned.
- **guildEvents** (array) - Currently not returned.
- **territoryBattleResult** (array) - Currently not returned.
- **territoryWarStatus** (array) - Currently not returned.
- **roomAvailable** (array) - Currently not returned.
- **arcadeRaidStatus** (array) - Currently not returned.
- **stat** (array) - Currently not returned.
- **recentRaidResult** (array) - Information for the last attempt for each raid.
- **recentTerritoryWarResult** (array) - Details of the past 8 Territory Wars.
- **profile** (object) - Object containing guild profile details.
- **inventory** (null) - Currently not returned.
- **progress** (null) - Currently not returned.
- **nextChallengeRefresh** (string) - The guild reset time for Guild Activities.

#### Response Example
```json
{
  "member": [],
  "inviteStatus": [],
  "raidStatus": [],
  "raidResult": [],
  "territoryBattleStatus": [],
  "guildEvents": [],
  "territoryBattleResult": [],
  "territoryWarStatus": [],
  "roomAvailable": [],
  "arcadeRaidStatus": [],
  "stat": [],
  "recentRaidResult": [],
  "recentTerritoryWarResult": [],
  "profile": {},
  "inventory": null,
  "progress": null,
  "nextChallengeRefresh": ""
}
```

### Notes
Fields marked as 'Currently not returned' are only accessible if the requesting account is part of the guild. Comlink cannot access private guild data.
```

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

### XP Table API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Provides data related to leveling up various game elements.

```APIDOC
## GET /xpTable

### Description
Retrieves experience tables for leveling up mods and units, and information for calculating crew rating and galactic power.

### Method
GET

### Endpoint
/xpTable

### Parameters
#### Query Parameters
- **id** (string) - Required - Identifier for the XP table.
- **xpTableId** (string) - Required - Reference ID for the XP table.
- **levelTableId** (string) - Required - Reference ID for the level table.

### Response
#### Success Response (200)
- **id** (string) - Identifier for the XP table entry.
- **xpTableId** (string) - Reference ID for the XP table.
- **levelTableId** (string) - Reference ID for the level table.

#### Response Example
{
  "id": "xp_table_entry_1",
  "xpTableId": "xp_table_ref_1",
  "levelTableId": "level_table_ref_1"
}
```

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

### Skill API

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Contains information on abilities, used for leveling details including recipes, required levels, and zeta/omicron status.

```APIDOC
## GET /api/skills

### Description
Retrieves information on in-game skills.

### Method
GET

### Endpoint
/api/skills

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **skills** (array) - A list of skill objects.
  - **_id** (string) - Unique identifier for the skill.
  - **_skillId** (string) - Reference ID for the skill, referenced in `units`.
  - **tier** (object) - Information on skill tiers.
    - **_id** (string) - Reference ID for the skill tier.
    - **isZeta** (boolean) - Indicates if the tier is a Zeta ability.
    - **isOmicron** (boolean) - Indicates if the tier is an Omicron ability.
    - **omicronArea** (string) - The area of the Omicron ability.
    - **recipe** (object) - Recipe information for the skill tier.
      - **_id** (string) - Reference ID for the recipe.

#### Response Example
{
  "skills": [
    {
      "_id": "skill_1",
      "_skillId": "skill_ref_1",
      "tier": {
        "_id": "tier_1",
        "isZeta": false,
        "isOmicron": true,
        "omicronArea": "Galactic War",
        "recipe": {
          "_id": "recipe_for_skill_tier_1"
        }
      }
    }
  ]
}
```

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

### Get Guild Leaderboard Request

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Construct this request body to retrieve guild leaderboard data. Specify the `leaderboardType` and optionally `defId` and `monthOffset` for specific data.

```json
{
  "payload" : {
    "leaderboardId":[
      {
        "leaderboardType": 4,
        "defId": "t05D",
        "monthOffset": 0
      }
    ],
    "count": 100
  },
  "enums": false
}
```

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

### Get GAC League Leaderboard Request

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

This payload is used to fetch GAC top 50 league and division leaderboard data. Specify the desired `league` and `division` IDs.

```json
{
  "payload": {
    "leaderboardType": 6,
    "league": 100,
    "division": 25
  },
  "enums": false
}
```

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

### Get GAC Bracket Leaderboard Request

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Getting-Started

Use this payload to retrieve GAC bracket leaderboard data. Ensure `eventInstanceId` and `groupId` are correctly formatted for the specified GAC season.

```json
{
  "payload": {
    "leaderboardType": 4,
    "eventInstanceId": "CHAMPIONSHIPS_GRAND_ARENA_GA2_EVENT_SEASON_36:O1676412000000",
    "groupId": "CHAMPIONSHIPS_GRAND_ARENA_GA2_EVENT_SEASON_36:O1676412000000:KYBER:100"
  },
  "enums": false
}
```

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

### Python Client: Get Player Data

Source: https://context7.com/swgoh-utils/swgoh-comlink/llms.txt

This Python function uses the 'requests' library to fetch player data from the Comlink API. It requires the player's ally code.

```python
# pip install swgoh-comlink (community package)
import requests

COMLINK_URL = "http://localhost:3000"

def get_player(ally_code):
    response = requests.post(
        f"{COMLINK_URL}/player",
        json={
            "payload": {"allyCode": str(ally_code)},
            "enums": False
        }
    )
    return response.json()

```

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

### Data Definitions Overview

Source: https://github.com/swgoh-utils/swgoh-comlink/wiki/Game-Data

Documentation for various game data structures including mods, territory battles, and tournament definitions.

```APIDOC
## Data Definitions

### starterGuild
- **Description**: Contains information for starter guilds.

### statMod
- **Description**: Contains information on mods, including locations and tier up recipes.
- **Identifier**: _id_
- **Reference ID**: _definitionId_

### statModSet
- **Description**: Contains details on mod sets for stat calculations and requirements.
- **Identifier**: _id_
- **Reference ID**: _setId_

### statProgression
- **Description**: Contains a list of all stat tables for units, used for calculating stats at different gear tiers and rarity.
- **Identifier**: _id_
- **Reference ID**: _statProgressionId_

### table
- **Description**: Contains lists of various tables for calculations like Territory Battle points, mod slicing, and galactic power.
- **Identifier**: _id_
- **Reference ID**: _tierUpRecipeTableId_, _encounterRewardTableId_

### targetingSet
- **Description**: Contains a list of targeting settings for AI attack functionality.
- **Identifier**: _id_

### territoryBattleDefinition
- **Description**: Contains detailed information on Territory Battles including rewards, requirements, and enemy info.
- **Identifier**: _id_
- **Reference ID**: _id_

### territoryTournamentDailyRewardTable
- **Description**: Contains a list of daily crystals rewarded at each Grand Arena League and Division ranking.
- **Identifier**: _league_ & _division_

### territoryTournamentDefinition
- **Description**: Contains details for each Grand Arena, including assets, durations, limits, and zone definitions.
- **Identifier**: _id_
- **Reference ID**: _id_, _seasonId_

### territoryTournamentDivisionDefinition
- **Description**: Contains a list of divisions for Grand Arena.
- **Identifier**: _id_
- **Reference ID**: _divisionId_, _division_

### territoryTournamentLeagueDefinition
- **Description**: Contains a list of leagues for Grand Arena.
- **Identifier**: _id_, _rank_
- **Reference ID**: _leagueId_, _league_

### territoryWarDefinition
- **Description**: Contains details about Territory War structure, rewards, and zones.
- **Identifier**: _id_

### timeZoneChangeConfig
- **Description**: Contains information about player's time zones and adjustment rules.
```