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

uv sync

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

CLI quick start

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

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 and magiccampus_sdk/example_ws.py.

CLI smoke script

An executable smoke helper lives at scripts/smoke_cli.py.

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

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:

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:

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