Metadata-Version: 2.4
Name: magic-campus-sdk
Version: 0.2.12
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 space get --group group_123 --format pretty
magic-campus space list-notice --space space_123 --format table
magic-campus space list-notice --group group_123 --format table
magic-campus space create-notice --space space_123 --title "Maintenance" --text "Starts at 22:00" --expiretime 1785510000000
magic-campus space create-notice --group group_123 --title "Maintenance" --text "Starts at 22:00" --expiretime 1785510000000
magic-campus space group update-name --group group_123 --name "New group name"
magic-campus user get --id 10134002 --format pretty
magic-campus user list --all --fields userId,nickname,email --format table
magic-campus user list --random --fields userId,nickname --format table
magic-campus user update-profile --id 10134002 --nickname "New Name" --avatar-url "https://cdn.example.com/avatar.png"
magic-campus user update-profile --id 10134002 --avatar-url "" # restore the default avatar
```

`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:

`~/.magic-campus/auth/magiccampus-im-sdk.json`

Supported commands:

- `config init|list|use|remove`
- `auth status`
- `im notify send`
- `im notify history`
- `space get`
- `space list-notice (--space <spaceId> | --group <groupId>)`
- `space create-notice (--space <spaceId> | --group <groupId>)`
- `space group update-name`
- `user get`
- `user list (--all | --random) [--fields <field1,field2>]`
- `user update-profile --id <userId> [--nickname <name>] [--avatar-url <url>]`
- `feed list`
- `notify +send` (compat)
- `notify +history` (compat)

## Python SDK quick start

```python
from magiccampus_sdk import MagicCampusConfig, MagicCampusSDK

sdk = MagicCampusSDK(
    MagicCampusConfig(
        apiurl="https://api-test.pearlapi.com",
        apikey="YOUR_API_KEY",
        platform="IOS",
    )
)

space = sdk.get_space_by_group_id("GROUP_ID")
print(space.id)
print(space.name)
print(space.introduction)
```

## 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",
    )
)

space = sdk.get_space_by_group_id("GROUP_ID")
print(space.name)

sdk.login()
sdk.start()
sdk.send_text("hello", recv_id="10134002")
sdk.send_markdown("# title\n\nbody", recv_id="10134002")

group = sdk.get_group_info("GROUP_ID")
print(group["groupName"])

groups = sdk.get_groups_info(["GROUP_ID_1", "GROUP_ID_2"])
```

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
