Metadata-Version: 2.4
Name: amongapi
Version: 1.1.3
Summary: Unofficial Among us API for AmongBot
Home-page: https://github.com/BronzeSource/AmongAPI
Author: RawanF4X
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: aiohttp>=3.8.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AmongAPI
[![PyPi Project](https://img.shields.io/pypi/v/amongapi)](https://pypi.org/project/amongapi) <img align="right" width="128" height="128" src="https://i.top4top.io/p_37665srem0.jpg" alt="AmongAPI" />

**AmongAPI** is an Open-Source Python library for [AmongBot](https://github.com/BronzeSource/AmongBot), it wraps the Innersloth API and implements the [Hazel Game Protocol](https://github.com/willardf/Hazel-Networking), so the bot can verify players, join lobbies, read chat, and track game states

## Features
- **Token Verification**: validate Among Us Account tokens via the official Innersloth API
- **Public Profiles**: look up any player by their PUID
- **Lobby Verification**: Join Private lobbies using the [Hazel Protocol](https://github.com/willardf/Hazel-Networking), read lobby chat, and confirm Discord usernames
- **Game Tracking**: Checks Game Phases (lobby / tasks / discussion / voting) and player states (alive / dead) for Automute

## How to Contribute

Contributions are very welcomed, and we love your help :3, just fork the repoistory and make new branch and make your changes, then open a pull request

## Installation
```bash
pip install amongapi
```
> Requirements: Python 3.8+, 'requests', 'aiohttp'

## Examples
### Token Verification
```py
# note: if you're using VPN, disable it, sometimes innersloth api rejects requests from VPN IP
from amongapi import verify_token

# proxies = {'http': 'http://user:pass@ip:port', 'https': 'http://user:pass@ip:port'} (optional)
result = verify_token('your token here') # if you added proxies then rewrite this line to = result = verify_token('your token here', proxies=proxies)

if result.valid:
  print(result.name, result.level, result.puid, result.friend_code, result.platform)
else:
  print('Failed:', result.error)
```

### Friend Requests
> [!WARNING]
> This Feature is not avaliable in AmongBot, It will be avaliable in next updates, and Token Verification is required and is the only method to send friend requests (only you who have to verify with token method, and not the puid target)

```py
# note: if you're using VPN, disable it, sometimes innersloth api rejects requests from VPN IP
from amongapi import send_friend_request

success = send_friend_request('your token', 'target player PUID') # note that api/v1/friendlist requires the target's player PUID and not the friend code like lotkilted#5441, the PUID looks like: apple-orange-banana, its the same as discord ID, and only avaliable method to get your PUID, is to verify with your token

if success:
  print('Friend request sent')
```

### Public Profile Lookup
```py
# note: if you're using VPN, disable it, sometimes innersloth api rejects requests from VPN IP
from amongapi import get_public_profile

profile = get_public_profile('put puid here')
if profile:
  print(profile['name'], profile['level'])
```

### Lobby Verification
> [!CAUTION]
> We are not Responsible for you getting banned using that for illegal things or things that violates innersloth's rules

```py
import asyncio
from amongapi import lobbyValidator

async def verify_with_lobby():
  validator = lobbyValidator(region='North America') # you can put 'Europe', 'Asia', 'North America'
  try:
    await validator.connect()
    joined = await validator.join_lobby('AMOBOT') # lobby code 
    if joined:
      found = await validator.wait_for_chat_message('DiscordUsername', timeout=30.0)
    if found:
      print('User Verified Successfully yipeeeeee :3')
  finally:
    await validator.close()

asyncio.run(verify_with_lobby())
```

## Game Tracking (AutoMute)
```py
# note: if you're using VPN, disable it, sometimes innersloth api rejects requests from VPN IP
import asyncio
from amongapi import gameTracker

async def track_game():
  tracker = gameTracker(region='North America') # options: 'Europe', 'Asia', 'North America'
  try:
    await tracker.connect()
    if await tracker.join_lobby('AMOBOT'):
      while True:
        print('Phase:', tracker.phase)
        for p in tracker.get_players_snapshot():
          print(f"  {p['name']}: {'alive' if p['is_alive'] else 'dead'}")
        await asyncio.sleep(2)
  finally:
    await tracker.close()

asyncio.run(track_game())
```

## How the Hazel Protocol is used
the `amongapi/client.py` module contains a **custom UDP Client** that speaks Hazel, the networking protocol used by Among Us, it is a full self.contained implemenation **written from scratch**, no external game libraries required

### What it does
- Connects to the region master servers (Asia, Europe, North America)
- Receives a redirect to a game server
- Sends a join request with a lobby code
- Parses incoming packets to extract:
  - **Game State:** lobby, tasks, discussion, voting
  - **Player Info:** name, level, alive/dead status, color
  - **Chat messages:** text message sent by players

**This client is used internally by**:
- `lobbyValidator`: to join a lobby and read chat for verification
- `gameTracker`: to continuously check game phases and player states for AutoMute

**Because the protocol is built into the library, the bot can join Among Us Lobbies and interact with the game just like a normal player

## Innersloth API Guide (Endpoints)
| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| `/api/v1/user` | `GET` | Yes | returns the authenticated user account info (name, level, PUID, friend code, platform, cosmetics) |
| `/api/v1/friendlist` | `GET` | Yes | returns the authenticated user friend list |
| `/api/v1/friendlist` | `POST` | Yes | sends a friend request to another player by their PUID |
| `/api/v1/player/public/{puid}` | `GET` | No | gets a player's public profile (name, level, cosmetics) without authentication |
| `/api/v1/account` | `GET` | Yes | returns account details similar to `/user` |
| `/api/v1/account/link` | `POST` | Yes | links an external platform (Steam, Mobile, XBOX, more...) to the Innersloth account |
| `/api/v1/active-games` | `GET` | Unknown | return a list of active games |
| `/api/v1/chat` | `GET/POST` | Unknown | related to the game chat |

### How each Endpoint Works
| Endpoint | Used by `AmongAPI` | What it Does |
|----------|--------------------|--------------|
| `GET /api/v1/user` | `verify_token()` | validates an account token and returns the user name, level, PUID, friend code, platform, and cosmetics, if the token is invalid/expired, returns 401, if the account is banned, returns 403 |
| `POST /api/v1/friendlist` | `send_friend_request()` | send a friend request to the player identified by the PUID in the request body, requires a valid token from the sender, returns 200 on success |
| `GET /api/v1/player/public/{puid}` | `get_public_profile()` | returns public profile info for any player, no authentication required, useful for looking up a player name and level without having their token |
| `GET /api/v1/friendlist` | **not added in amongapi** | returns the list of friend for the authenticated user, may be added in the future updates |

## About 
- Made by Rawan :3
- Made for **AmongBot**
