Metadata-Version: 2.4
Name: juicychat-client
Version: 0.2.21
Summary: Unofficial Python client for juicychat.ai
Author: Kirby Wirby
License: MIT
Project-URL: Homepage, https://github.com/kirby900/juicychat-client
Project-URL: Repository, https://github.com/kirby900/juicychat-client
Keywords: juicychat,chat,api,client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: curl-cffi>=0.14
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# JuicyChat Client

Unofficial Python client for [JuicyChat](https://www.juicychat.ai). It handles login, encrypted request/response payloads, and provides a CLI for interactive chat, character search, user discovery, personas, and tasks.

## Features

- **Authentication** — Login with user number and password
- **Characters** — Search characters by term, tags, gender, and sort order; get character details
- **Chat** — Send messages and stream replies; list, clear, and delete chat history
- **Users** — Search users, view profiles, follow/unfollow
- **Creator Rankings** — Browse ranked creators (monthly, all-time, new creators)
- **Personas** — Create personas and attach them to character chats
- **Tasks** — View task list, check progress, claim task rewards
- **Content Filter** — Toggle NSFW content filter
- **Crypto** — AES-encrypted API payloads; key/IV from env or auto-discovered from the site bundle
- **Bundle Discovery** — Extract crypto keys, app version, and API endpoints from the site JS bundle

## Requirements

- Python 3.11+
- `cryptography`, `python-dotenv`, `requests` (see `pyproject.toml`)

## Installation

```bash
pip install juicychat-client
```

## Configuration

Credentials and crypto can be set via environment variables or a `.env` file.

| Variable | Description |
|----------|-------------|
| `JUICYCHAT_USERNUMBER` | Account user number |
| `JUICYCHAT_PASSWORD` | Account password |
| `JUICYCHAT_KEY` | 16-byte AES key (UTF-8) for request/response encryption |
| `JUICYCHAT_IV` | 16-byte AES IV (UTF-8) |

If `JUICYCHAT_KEY` and `JUICYCHAT_IV` are not set, the client will fetch the site's JS bundle and extract the current key/IV automatically. For stability, setting them in `.env` is recommended once you have them.

## Usage

### CLI

Run the interactive menu (login uses env or prompts for user number/password):

```bash
juicychat
# or
python -m juicychat.cli
```

Menu options (available options depend on whether a conversation is selected):

- **Select Conversation** — Pick from existing chat relations
- **Continue Conversation** — View history and send messages in the selected chat
- **Clear Conversation** — Clear message history for the selected chat
- **Delete Conversation** — Remove the selected chat relation
- **Character Detail** — View details for the selected character
- **Search Characters** — Search and select a character
- **Get Task List** — View available tasks
- **Create Persona** — Create a new persona (title, name, description, gender, age)
- **User Info** — View current user details
- **Toggle Content Filter** — Toggle the NSFW content filter on/off
- **Search Users** — Search for users and view their profiles

### Library

```python
import os
from dotenv import load_dotenv
from juicychat.client import JuicyChatClient, Gender, SortName

load_dotenv()

client = JuicyChatClient(
    user_number=os.getenv("JUICYCHAT_USERNUMBER"),
    password=os.getenv("JUICYCHAT_PASSWORD"),
    key=os.getenv("JUICYCHAT_KEY"),
    iv=os.getenv("JUICYCHAT_IV"),
)

info = client.get_user_info()
characters = client.search_characters("elf", gender=Gender.FEMALE, sort_name=SortName.POPULAR)
relations = client.get_chat_relations()
reply = client.send_chat_message(character_id="...", message="Hello")
```

#### Client Methods

**User**

- `get_user_info()` — Current user details
- `get_other_user_info(user_id)` — Another user's profile
- `get_user_coins()` — Coin balance
- `get_user_progress()` — Task/level progress
- `get_user_checkin_prompt()` — Daily check-in prompt
- `get_user_claim_coupon()` — Claim available coupon
- `update_content_filter(allow_nsfw)` — Toggle NSFW content filter

**Characters**

- `search_characters(search_content, character_tags, gender, sort_name, page_no, page_size)` — Search characters
- `get_character_list_and_config(...)` — Characters with site config
- `get_character_detail(character_id)` — Full character details

**Chat**

- `get_chat_relations(page_no, page_size)` — List chat relations
- `get_chat_config(character_id)` — Chat configuration for a character
- `get_chat_messages(character_id, chat_id)` — Message history
- `send_chat_message(character_id, message, request_type)` — Send message and get streamed reply
- `clear_chat_history(character_id)` — Clear chat messages
- `delete_chat_relation(character_id)` — Remove a chat relation

**Personas**

- `get_personas(page_no, page_size)` — List personas
- `create_persona(title, name, description, gender, age)` — Create a persona
- `set_persona(character_id, persona_id)` — Attach a persona to a chat

**Tasks**

- `get_tasks()` — List available tasks
- `get_task_progress(task_id)` — Progress for a specific task
- `claim_task_reward(task_id)` — Claim a task reward

**Social**

- `search_users(search_content, page_no, page_size)` — Search users
- `follow_user(user_id)` / `unfollow_user(user_id)` — Follow or unfollow a user
- `get_ranked_creators(ranking_type, page_no, page_size)` — Creator leaderboard

**Other**

- `get_launch_data()` — App launch/config data

#### Enums

- `SortName` — `EDITOR_CHOICE`, `FOLLOWING`, `NEW`, `POPULAR`, `RECENT`, `TRENDING`
- `Gender` — `ALL`, `FEMALE`, `MALE`, `NON_BINARY`, `TRANS_MALE`, `TRANS_FEMALE`
- `TaskId` — `DAILY_CHECK_IN`, `SEND_10_MESSAGES`, `CHAT_3_CHARACTERS`, `DAILY_FOLLOWING`, `GENERATE_IMAGE`
- `RankingType` — `ALL_CREATORS_MONTHLY`, `NEW_CREATORS_MONTHLY`, `ALL_CREATORS_ALL_TIME`, `NEW_CREATORS_ALL_TIME`

### Standalone Tools

**Bundle discovery** — extract crypto keys, app version, and API endpoints:

```bash
python -m juicychat.discover
```

**Decrypt response data** — decrypt an encrypted API response from a file or stdin:

```bash
python -m juicychat.crypto response.txt
# or
echo "..." | python -m juicychat.crypto
```

## Notes

- **Unofficial** — This project is not affiliated with JuicyChat. The API may change; key/IV discovery depends on the current web bundle.
- **Credentials** — Store user number, password, and key/IV securely.
