devranta/README.md

# devRanta

devRanta is the best async devRant client written in Python. Authentication is only needed for half of the functionality; thus, the username and password are optional parameters when constructing the main class of this package (Api). You can find the latest packages in tar and wheel format [here](https://retoor.molodetz.nl/retoor/devranta/packages).

## Running
```
make run
```

## Testing
Tests are only made for methods not requireing authentication.
I do not see value in mocking requests.
```
make test
```

## How to use
Implementation:
```
from devranta.api import Api 

api = Api(username="optional!", password="optional!")

async def list_rants():
    async for rant in api.get_rants():
        print(rant["user_username"], ":", rant["text"])
```
See [tests](src/devranta/tests.py) for [examples](src/devranta/tests.py) on how to use. 


# devRant API Documentation

For people wanting to build their own client.

TODO: document responses.

## Base URL
`https://devrant.com/api`

## Authentication
- Uses `dr_token` cookie with `token_id`, `token_key`, and `user_id`.
- Required for endpoints needing user authentication.
- `guid`, `plat`, `sid`, `seid` included in requests for session tracking.

## Endpoints

### User Management
1. **Register User**
   - **URL**: `/api/users`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3 (constant)
     - `type`: 1 (constant)
     - `email`: User email
     - `username`: User username
     - `password`: User password
     - `guid`: Unique identifier (from `getMyGuid`)
     - `plat`: 3 (constant)
     - `sid`: Session start time (from `getSessionStartTime`)
     - `seid`: Session event ID (from `getSessionEventId`)
   - **Response**: JSON with `success`, `auth_token`, or `error` and `error_field`
   - **Description**: Creates a new user account.

2. **Login User**
   - **URL**: `/api/users/auth-token`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `username`: User username
     - `password`: User password
     - `guid`: Unique identifier
     - `plat`: 3
     - `sid`: Session start time
     - `seid`: Session event ID
   - **Response**: JSON with `success`, `auth_token`, or `error`
   - **Description**: Authenticates user and returns auth token.

3. **Edit Profile**
   - **URL**: `/api/users/me/edit-profile`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`: Token ID
     - `token_key`: Token key
     - `user_id`: User ID
     - `guid`, `plat`, `sid`, `seid`
     - `profile_about`: User bio
     - `profile_skills`: User skills
     - `profile_location`: User location
     - `profile_website`: User website
     - `profile_github`: GitHub username
   - **Response**: JSON with `success`
   - **Description**: Updates user profile information.

4. **Forgot Password**
   - **URL**: `/api/users/forgot-password`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `username`: User username
     - `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Initiates password reset process.

5. **Resend Confirmation Email**
   - **URL**: `/api/users/me/resend-confirm`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Resends account confirmation email.

6. **Delete Account**
   - **URL**: `/api/users/me`
   - **Method**: DELETE
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Deletes user account.

7. **Mark News as Read**
   - **URL**: `/api/users/me/mark-news-read`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `news_id`: News item ID
   - **Response**: JSON with `success`
   - **Description**: Marks a news item as read for logged-in users.

### Rants
1. **Get Rant**
   - **URL**: `/api/devrant/rants/{rant_id}`
   - **Method**: GET
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `last_comment_id`: 999999999999 (optional)
     - `links`: 0 (optional)
   - **Response**: JSON with `rant` (text, tags)
   - **Description**: Retrieves a specific rant by ID.

2. **Post Rant**
   - **URL**: `/api/devrant/rants`
   - **Method**: POST
   - **Parameters** (FormData):
     - `app`: 3
     - `rant`: Rant text
     - `tags`: Comma-separated tags
     - `token_id`, `token_key`, `user_id`
     - `type`: Rant type ID
     - `image`: Optional image file (img/gif)
   - **Response**: JSON with `success`, `rant_id`, or `error`
   - **Description**: Creates a new rant.

3. **Edit Rant**
   - **URL**: `/api/devrant/rants/{rant_id}`
   - **Method**: POST
   - **Parameters** (FormData):
     - `app`: 3
     - `rant`: Rant text
     - `tags`: Comma-separated tags
     - `token_id`, `token_key`, `user_id`
     - `image`: Optional image file
   - **Response**: JSON with `success` or `fail_reason`
   - **Description**: Updates an existing rant.

4. **Delete Rant**
   - **URL**: `/api/devrant/rants/{rant_id}`
   - **Method**: DELETE
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Deletes a rant.

5. **Vote on Rant**
   - **URL**: `/api/devrant/rants/{rant_id}/vote`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `vote`: 1 (upvote), -1 (downvote), 0 (remove vote)
     - `reason`: Downvote reason ID (required for downvote)
   - **Response**: JSON with `success` or `confirmed` (false if unverified)
   - **Description**: Votes on a rant.

6. **Favorite/Unfavorite Rant**
   - **URL**: `/api/devrant/rants/{rant_id}/{favorite|unfavorite}`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Favorites or unfavorites a rant.

7. **Get Rant Feed**
   - **URL**: `/api/devrant/rants`
   - **Method**: GET
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `ids`: JSON string of IDs (optional)
   - **Response**: JSON with `success`, `num_notifs`
   - **Description**: Retrieves rant feed with notification count.

### Comments
1. **Get Comment**
   - **URL**: `/api/comments/{comment_id}`
   - **Method**: GET
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `links`: 0 (optional)
   - **Response**: JSON with `comment` (body)
   - **Description**: Retrieves a specific comment by ID.

2. **Post Comment**
   - **URL**: `/api/devrant/rants/{rant_id}/comments`
   - **Method**: POST
   - **Parameters** (FormData):
     - `app`: 3
     - `comment`: Comment text
     - `token_id`, `token_key`, `user_id`
     - `image`: Optional image file (img/gif)
   - **Response**: JSON with `success` or `confirmed` (false if unverified)
   - **Description**: Posts a comment on a rant.

3. **Edit Comment**
   - **URL**: `/api/comments/{comment_id}`
   - **Method**: POST
   - **Parameters** (FormData):
     - `app`: 3
     - `comment`: Comment text
     - `token_id`, `token_key`, `user_id`
   - **Response**: JSON with `success` or `fail_reason`
   - **Description**: Updates an existing comment.

4. **Delete Comment**
   - **URL**: `/api/comments/{comment_id}`
   - **Method**: DELETE
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Deletes a comment.

5. **Vote on Comment**
   - **URL**: `/api/comments/{comment_id}/vote`
   - **Method**: POST
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `vote`: 1 (upvote), -1 (downvote), 0 (remove vote)
     - `reason`: Downvote reason ID (required for downvote)
   - **Response**: JSON with `success` or `confirmed` (false if unverified)
   - **Description**: Votes on a comment.

### Notifications
1. **Get Notification Feed**
   - **URL**: `/api/users/me/notif-feed`
   - **Method**: GET
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
     - `ext_prof`: 1 (optional)
     - `last_time`: Last notification check time
   - **Response**: JSON with `success`, `data` (items, check_time, username_map)
   - **Description**: Retrieves user notifications.

2. **Clear Notifications**
   - **URL**: `/api/users/me/notif-feed`
   - **Method**: DELETE
   - **Parameters**:
     - `app`: 3
     - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid`
   - **Response**: JSON with `success`
   - **Description**: Clears user notifications.

## External API
- **Beta List Signup**
  - **URL**: `https://www.hexicallabs.com/api/beta-list`
  - **Method**: GET (JSONP)
  - **Parameters**:
    - `email`: User email
    - `platform`: Platform name
    - `app`: 3
  - **Description**: Signs up user for beta list (external service).

## Notes
- All endpoints expect `app=3` for identification.
- Authenticated endpoints require `dr_token` cookie with `token_id`, `token_key`, `user_id`.
- `guid`, `plat`, `sid`, `seid` are used for session tracking.
- Image uploads use FormData for rants and comments.
- Downvotes require a reason ID, prompting a modal if not provided.
- Responses typically include `success` boolean; errors include `error` or `fail_reason`.
- Cookies (`dr_token`, `dr_guid`, `dr_session_start`, `dr_event_id`, `dr_feed_sort`, `dr_theme`, `dr_rants_viewed`, `dr_stickers_seen`, `rant_type_filters`, `news_seen`) manage state and preferences.