Metadata-Version: 2.4
Name: magiccampus-im-sdk
Version: 0.1.3
Summary: MagicCampus-flavoured SDK and CLI with a bundled OpenIM transport layer.
Author: MagicCampus Contributors
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: protobuf<7,>=6.32.0
Requires-Dist: websocket-client<2,>=1.8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# magiccampus-im-sdk

Python SDK and CLI for MagicCampus login, messaging, and websocket sync.

This project bundles the OpenIM transport implementation inside `magiccampus_sdk`, but removes direct user-facing dependency on OpenIM token and endpoint configuration. You only configure:

- `apiurl`
- `apikey`
- `platform`

At runtime, the SDK calls:

`GET /api/v1/accounts/imToken?platform=<PLATFORM>`

and uses the response fields:

- `userId`
- `imToken`
- `wsApi`
- `httpApi`

## Install locally

```bash
uv sync
```

This repository vendors only the OpenIM transport pieces that `magiccampus_sdk` actually uses.

## CLI quick start

```bash
magic-campus --help
magic-campus config init --apiurl https://api-test.pearlapi.com --apikey "$MAGICCAMPUS_APIKEY" --platform IOS --default true
magic-campus auth status --format pretty
magic-campus notify +send --to user:10134002 --text "hello"
```

`magic-campus config init` also supports an interactive TTY flow when you omit auth flags.

`notify +send` sends over MagicCampus HTTP `POST /agent/v1/im/sendMessage`. `notify +history` still relies on the websocket transport and local sync database.

CLI config is stored at:

`~/.mushroom_agent/auth/magiccampus-im-sdk.json`

Supported commands:

- `config init|list|use|remove`
- `auth status`
- `notify +send`
- `notify +history`

## Python websocket quick start

```python
from magiccampus_sdk import MagicCampusWSSDK, MagicCampusWSConfig

sdk = MagicCampusWSSDK(
    MagicCampusWSConfig(
        apiurl="https://api-test.pearlapi.com",
        apikey="YOUR_API_KEY",
        platform="IOS",
        data_dir="./magiccampus_data",
    )
)

sdk.login()
sdk.start()
sdk.send_text("hello", recv_id="10134002")
```

Runnable examples live in [magiccampus_sdk/example.py](magiccampus_sdk/example.py) and [magiccampus_sdk/example_ws.py](magiccampus_sdk/example_ws.py).

## CLI smoke script

An executable smoke helper lives at [scripts/smoke_cli.py](scripts/smoke_cli.py).

Offline-safe mode only exercises config persistence and notify dry-run:

```bash
uv run python scripts/smoke_cli.py
```

This mode does not require a real API key. It uses a placeholder key by default and avoids any live auth call.

## Real network mode

To run the live auth probe, provide a real API key and enable `--live`:

```bash
export MAGICCAMPUS_APIURL=https://api-test.pearlapi.com
export MAGICCAMPUS_APIKEY='your real api key'
export MAGICCAMPUS_PLATFORM=IOS
uv run python scripts/smoke_cli.py --live
```

Optional variables:

- `MAGICCAMPUS_SMOKE_TARGET`: target used by dry-run and optional live send, default `user:smoke-target`
- `MAGICCAMPUS_PLATFORM`: defaults to `IOS`

If you also want to send a real text message, set a real target and pass `--live-send`:

```bash
export MAGICCAMPUS_SMOKE_TARGET='user:10134002'
uv run python scripts/smoke_cli.py --live --live-send --text 'hello from smoke script'
```

`--live-send` performs a real outbound send, so use it only with a valid target and credentials.

## Notes

- `apiurl` can point to any MagicCampus API base URL; the CLI and SDK append `/api/v1/accounts/imToken`
- `platform` defaults to `IOS`
- low-level message send / receive behavior comes from the bundled transport modules inside `magiccampus_sdk`
- the wrapper does not persist raw OpenIM credentials in CLI config
