Metadata-Version: 2.4
Name: magic-campus-sdk
Version: 0.1.1
Summary: MagicCampus platform SDK and CLI with bundled IM transport support.
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"

# magic-campus-sdk

Python SDK and CLI for MagicCampus platform integrations. IM remains a supported domain, and this repository keeps the bundled OpenIM transport inside `magiccampus_sdk`.

This project removes direct user-facing dependency on OpenIM token and endpoint configuration. You only configure:

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

At runtime, IM-backed flows call:

`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, and layers platform-facing SDK / CLI commands on top.

IM-specific low-level internals, models, and protobufs now live under `magiccampus_sdk.im`.

## 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 im notify send --to user:10134002 --text "hello"
magic-campus im notify send --to user:10134002 --markdown "# title\n\nbody"
magic-campus user get --id 10134002 --format pretty
```

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

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

Legacy compatibility commands remain available:

```bash
magic-campus notify +send --to user:10134002 --text "hello"
magic-campus notify +history --to user:10134002
```

CLI config is stored at:

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

Supported commands:

- `config init|list|use|remove`
- `auth status`
- `im notify send`
- `im notify history`
- `user get`
- `feed list`
- `notify +send` (compat)
- `notify +history` (compat)

## Python SDK quick start

```python
from magiccampus_sdk import MagicCampusClient, MagicCampusClientConfig

client = MagicCampusClient(
    MagicCampusClientConfig(
        apiurl="https://api-test.pearlapi.com",
        apikey="YOUR_API_KEY",
        platform="IOS",
        data_dir="./magiccampus_data",
    )
)

user = client.user.get("10134002")
print(user.nickname)
print(user.avatar_url)
```

## 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")
sdk.send_markdown("# title\n\nbody", 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; IM-backed flows append `/api/v1/accounts/imToken`
- `client.user.get(...)` calls `GET /api/v1/accounts/getUserInfo` with `apiurl` and `apikey` directly
- `platform` defaults to `IOS`
- low-level IM send / receive behavior comes from the bundled transport modules inside `magiccampus_sdk`
- the wrapper does not persist raw OpenIM credentials in CLI config
