magiccampus-im-sdk 0.1.0__tar.gz

magiccampus_im_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: magiccampus-im-sdk
+Version: 0.1.0
+Summary: MagicCampus-flavoured SDK and CLI built on top of openim-sdk-core.
+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: openim-sdk-core>=0.1.10
+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 keeps the OpenIM transport implementation in `openim_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 is configured to resolve `openim-sdk-core` from the sibling directory `../openim-python-sdk`.
+
+## CLI quick start
+
+```bash
+magiccampus-cli --help
+magiccampus-cli config init --apiurl https://api-test.pearlapi.com --apikey "$MAGICCAMPUS_APIKEY" --platform IOS --default true
+magiccampus-cli auth status --format pretty
+magiccampus-cli notify +send --to user:10134002 --text "hello"
+```
+
+`magiccampus-cli config init` also supports an interactive TTY flow when you omit auth flags.
+
+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 `openim_sdk`
+- the wrapper does not persist raw OpenIM credentials in CLI config

magiccampus_im_sdk-0.1.0/README.md

@@ -0,0 +1,115 @@
+# magiccampus-im-sdk
+
+Python SDK and CLI for MagicCampus login, messaging, and websocket sync.
+
+This project keeps the OpenIM transport implementation in `openim_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 is configured to resolve `openim-sdk-core` from the sibling directory `../openim-python-sdk`.
+
+## CLI quick start
+
+```bash
+magiccampus-cli --help
+magiccampus-cli config init --apiurl https://api-test.pearlapi.com --apikey "$MAGICCAMPUS_APIKEY" --platform IOS --default true
+magiccampus-cli auth status --format pretty
+magiccampus-cli notify +send --to user:10134002 --text "hello"
+```
+
+`magiccampus-cli config init` also supports an interactive TTY flow when you omit auth flags.
+
+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 `openim_sdk`
+- the wrapper does not persist raw OpenIM credentials in CLI config

magiccampus_im_sdk-0.1.0/magiccampus_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

magiccampus_im_sdk-0.1.0/magiccampus_cli/__main__.py

@@ -0,0 +1,9 @@
+from .cli import main as cli_main
+
+
+def main() -> int:
+    return cli_main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

magiccampus_im_sdk-0.1.0/magiccampus_cli/accounts.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from magiccampus_sdk.auth import normalize_apiurl, normalize_platform
+
+from .utils import env_string, mask_secret, trim_string
+
+
+@dataclass(frozen=True)
+class AccountConfig:
+    account_id: str
+    enabled: bool
+    apiurl: str
+    apikey: str
+    platform: str
+
+
+def account_config_to_raw(account: AccountConfig) -> dict[str, object]:
+    return {
+        "enabled": account.enabled,
+        "apiUrl": account.apiurl,
+        "apiKey": account.apikey,
+        "platform": account.platform,
+    }
+
+
+def normalize_stored_account(raw: object) -> dict[str, object]:
+    source = raw if isinstance(raw, dict) else {}
+    apiurl = trim_string(source.get("apiUrl") or source.get("apiurl"))
+    platform = trim_string(source.get("platform")) or "IOS"
+    normalized: dict[str, object] = {
+        "enabled": source.get("enabled") is not False,
+        "apiUrl": normalize_apiurl(apiurl) if apiurl else "",
+        "apiKey": trim_string(source.get("apiKey") or source.get("apikey")),
+        "platform": normalize_platform(platform),
+    }
+    return normalized
+
+
+def env_default_account() -> dict[str, object] | None:
+    apiurl = env_string("MAGICCAMPUS_APIURL")
+    apikey = env_string("MAGICCAMPUS_APIKEY")
+    if not apiurl or not apikey:
+        return None
+
+    return {
+        "enabled": True,
+        "apiUrl": apiurl,
+        "apiKey": apikey,
+        "platform": env_string("MAGICCAMPUS_PLATFORM") or "IOS",
+    }
+
+
+def normalize_account(account_id: str, raw: object) -> AccountConfig | None:
+    stored = normalize_stored_account(raw)
+    if not stored["apiUrl"] or not stored["apiKey"]:
+        return None
+
+    return AccountConfig(
+        account_id=account_id,
+        enabled=stored.get("enabled") is not False,
+        apiurl=str(stored["apiUrl"]),
+        apikey=str(stored["apiKey"]),
+        platform=str(stored["platform"]),
+    )
+
+
+def list_account_ids(root: dict[str, object]) -> list[str]:
+    accounts = root.get("accounts")
+    ids = list(accounts.keys()) if isinstance(accounts, dict) else []
+    if env_default_account() and "default" not in ids:
+        ids.insert(0, "default")
+    return ids
+
+
+def get_account_config(root: dict[str, object], account_id: str | None) -> AccountConfig | None:
+    resolved_id = account_id or str(root.get("defaultAccountId") or "default")
+    if resolved_id == "default":
+        env_account = env_default_account()
+        if env_account is not None:
+            return normalize_account("default", env_account)
+
+    accounts = root.get("accounts")
+    configured = accounts.get(resolved_id) if isinstance(accounts, dict) else None
+    if configured is not None:
+        return normalize_account(resolved_id, configured)
+    return None
+
+
+def list_account_summaries(root: dict[str, object]) -> list[dict[str, object]]:
+    summaries: list[dict[str, object]] = []
+    default_account_id = str(root.get("defaultAccountId") or "default")
+    for account_id in list_account_ids(root):
+        account = get_account_config(root, account_id)
+        if account is None:
+            continue
+        summaries.append(
+            {
+                "accountId": account.account_id,
+                "default": account.account_id == default_account_id,
+                "enabled": account.enabled,
+                "apiUrl": account.apiurl,
+                "platform": account.platform,
+            }
+        )
+    return summaries
+
+
+def upsert_stored_account(root: dict[str, object], account_id: str, raw_account: dict[str, object], make_default: bool = False) -> dict[str, object]:
+    accounts = root.get("accounts")
+    next_accounts = dict(accounts) if isinstance(accounts, dict) else {}
+    next_accounts[account_id] = normalize_stored_account(raw_account)
+    default_account_id = account_id if make_default else str(root.get("defaultAccountId") or account_id)
+    return {"defaultAccountId": default_account_id, "accounts": next_accounts}
+
+
+def remove_stored_account(root: dict[str, object], account_id: str) -> dict[str, object]:
+    accounts = root.get("accounts")
+    next_accounts = dict(accounts) if isinstance(accounts, dict) else {}
+    next_accounts.pop(account_id, None)
+    remaining_ids = list(next_accounts.keys())
+    default_account_id = str(root.get("defaultAccountId") or "default")
+    if default_account_id == account_id:
+        default_account_id = remaining_ids[0] if remaining_ids else "default"
+    return {"defaultAccountId": default_account_id, "accounts": next_accounts}

magiccampus_im_sdk-0.1.0/magiccampus_cli/cli.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+from .commands.auth import run_auth_command
+from .commands.config import run_config_command
+from .commands.notify import run_notify_command
+from .output import print_output
+
+
+def _has_explicit_output_format(argv: list[str]) -> bool:
+    return "--format" in argv
+
+
+def parse_argv(argv: list[str]) -> tuple[str, list[str]]:
+    args = list(argv)
+    output_format = "json"
+    index = 0
+    while index < len(args):
+        if args[index] == "--format":
+            if index + 1 >= len(args):
+                raise RuntimeError("--format requires a value.")
+            output_format = args[index + 1]
+            del args[index:index + 2]
+            continue
+        index += 1
+    return output_format, args
+
+
+def parse_options(argv: list[str]) -> tuple[dict[str, object], list[str]]:
+    options: dict[str, object] = {}
+    positionals: list[str] = []
+    index = 0
+    while index < len(argv):
+        value = argv[index]
+        if value.startswith("--"):
+            key = value[2:]
+            next_value = argv[index + 1] if index + 1 < len(argv) else None
+            if next_value is not None and not next_value.startswith("--"):
+                options[key] = next_value
+                index += 2
+                continue
+            options[key] = True
+            index += 1
+            continue
+        positionals.append(value)
+        index += 1
+    return options, positionals
+
+
+def usage() -> str:
+    return "\n".join(
+        [
+            "magiccampus-cli",
+            "",
+            "Commands:",
+            "  config init [--account <id>] --apiurl <url> --apikey <token> [--platform <name> --enabled <bool> --default <bool>]",
+            "  config list",
+            "  config use <accountId>",
+            "  config remove <accountId>",
+            "  auth status [--account <id>]",
+            "  notify +send --to <user:ID|group:ID> (--text <text> | --image <path|url> | --file <path|url> | --video <path|url>) [--name <filename>] [--account <id>] [--dry-run]",
+            "  notify +history --to <user:ID|group:ID> [--limit <count>] [--account <id>]",
+            "",
+            "Global flags:",
+            "  --format json|pretty|table|ndjson",
+        ]
+    )
+
+
+def main(raw_argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if raw_argv is None else raw_argv)
+    try:
+        has_explicit_output_format = _has_explicit_output_format(argv)
+        output_format, args = parse_argv(argv)
+        if not args or "--help" in args or "-h" in args:
+            if not has_explicit_output_format:
+                sys.stdout.write(f"{usage()}\n")
+                return 0
+            print_output({"ok": True, "usage": usage()}, output_format)
+            return 0
+
+        if args[0] == "--version":
+            print_output({"ok": True, "version": __version__, "runtime": "python"}, output_format)
+            return 0
+
+        if args[0] == "config":
+            result = run_config_command(args[1] if len(args) > 1 else None, args[2:], parse_options)
+        elif args[0] == "auth":
+            result = run_auth_command(args[1] if len(args) > 1 else None, args[2:], parse_options)
+        elif args[0] == "notify":
+            result = run_notify_command(args[1] if len(args) > 1 else None, args[2:], parse_options)
+        else:
+            raise RuntimeError(f"Unknown command: {args[0]}")
+
+        print_output(result, output_format)
+        return 0
+    except Exception as error:
+        print_output({"ok": False, "error": str(error)}, output_format if "output_format" in locals() else "json")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

magiccampus_im_sdk-0.1.0/magiccampus_cli/client.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Callable, TypeVar
+
+from magiccampus_sdk import MagicCampusWSConfig, MagicCampusWSSDK
+from magiccampus_sdk.auth import resolve_platform_id
+
+from . import __version__
+from .accounts import AccountConfig
+from .config_store import get_runtime_data_dir
+from .utils import mask_secret
+
+T = TypeVar("T")
+
+
+def _build_data_dir(account: AccountConfig) -> Path:
+    path = get_runtime_data_dir() / account.account_id
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_account_db_path(account_id: str, user_id: str) -> Path:
+    return get_runtime_data_dir() / account_id / f"OpenIM_pyws_{user_id}.db"
+
+
+def build_sdk(account: AccountConfig) -> MagicCampusWSSDK:
+    config = MagicCampusWSConfig(
+        apiurl=account.apiurl,
+        apikey=account.apikey,
+        platform=account.platform,
+        data_dir=str(_build_data_dir(account)),
+        timeout_seconds=30.0,
+        sdk_version=f"magiccampus-cli/{__version__}",
+        auto_sync_on_connect=False,
+        auto_sync_on_reconnect=False,
+        auto_reconnect=False,
+        enable_heartbeat=False,
+    )
+    return MagicCampusWSSDK(config)
+
+
+def with_connected_sdk(account: AccountConfig, action: Callable[[MagicCampusWSSDK], T]) -> T:
+    sdk = build_sdk(account)
+    sdk.login()
+    try:
+        sdk.start()
+        return action(sdk)
+    finally:
+        try:
+            time.sleep(0.25)
+        finally:
+            sdk.logout()
+
+
+def get_auth_status(account: AccountConfig) -> dict[str, object]:
+    def _probe(sdk: MagicCampusWSSDK) -> dict[str, object]:
+        credentials = sdk.credentials
+        now = int(time.time())
+        expire_at = credentials.expire_time if credentials else 0
+        return {
+            "ok": True,
+            "accountId": account.account_id,
+            "userID": sdk.user_id,
+            "platformID": resolve_platform_id(account.platform),
+            "provider": "magiccampus",
+            "transport": "ws_client",
+            "connected": True,
+            "loginStatus": "connected",
+            "wsAddr": credentials.ws_addr if credentials else "",
+            "apiAddr": credentials.api_addr if credentials else "",
+            "magiccampus": {
+                "enabled": account.enabled,
+                "platform": account.platform,
+                "apiUrl": account.apiurl,
+                "apiKeyPreview": mask_secret(account.apikey),
+                "expireAt": expire_at,
+                "expiresInSeconds": max(0, expire_at - now) if expire_at else 0,
+                "dataDir": str(_build_data_dir(account)),
+            },
+        }
+
+    return with_connected_sdk(account, _probe)

magiccampus_im_sdk-0.1.0/magiccampus_cli/commands/auth.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from ..accounts import get_account_config
+from ..config_store import read_config_root
+
+
+def resolve_account_or_throw(root: dict[str, object], account_id: str | None):
+    account = get_account_config(root, account_id)
+    if account is None:
+        resolved = account_id or str(root.get("defaultAccountId") or "default")
+        raise RuntimeError(
+            f"No usable MagicCampus account found for '{resolved}'. Run 'config init' or set MAGICCAMPUS_* env vars."
+        )
+    return account
+
+
+def run_auth_command(subcommand: str | None, argv: list[str], parse_options):
+    if subcommand != "status":
+        raise RuntimeError(f"Unknown auth subcommand: {subcommand}")
+
+    options, _ = parse_options(argv)
+    root = read_config_root()
+    account = resolve_account_or_throw(root, options.get("account"))
+    from ..client import get_auth_status
+
+    return get_auth_status(account)

magiccampus_im_sdk-0.1.0/magiccampus_cli/commands/config.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from ..accounts import account_config_to_raw, get_account_config, list_account_summaries, remove_stored_account, upsert_stored_account
+from ..config_store import get_config_path, read_config_root, write_config_root
+from ..prompts import prompt_for_account
+from ..utils import env_string, parse_optional_bool, trim_string
+
+
+def _first_non_empty(*values: object) -> str:
+    for value in values:
+        text = trim_string(value)
+        if text:
+            return text
+    return ""
+
+
+def _has_non_interactive_input(options: dict[str, object]) -> bool:
+    return any(
+        options.get(key) is not None
+        for key in (
+            "apiurl",
+            "api-url",
+            "apikey",
+            "api-key",
+            "platform",
+            "enabled",
+            "default",
+        )
+    )
+
+
+def _build_input(existing: dict[str, object], options: dict[str, object], account_id: str) -> dict[str, object]:
+    return {
+        "apiUrl": _first_non_empty(options.get("apiurl"), options.get("api-url"), existing.get("apiUrl"), env_string("MAGICCAMPUS_APIURL")),
+        "apiKey": _first_non_empty(options.get("apikey"), options.get("api-key"), existing.get("apiKey"), env_string("MAGICCAMPUS_APIKEY")),
+        "platform": _first_non_empty(options.get("platform"), existing.get("platform"), env_string("MAGICCAMPUS_PLATFORM"), "IOS"),
+        "enabled": parse_optional_bool(options.get("enabled"), existing.get("enabled") is not False),
+        "makeDefault": parse_optional_bool(options.get("default"), account_id == "default"),
+    }
+
+
+def run_config_command(subcommand: str | None, argv: list[str], parse_options):
+    root = read_config_root()
+    options, positionals = parse_options(argv)
+
+    if subcommand == "init":
+        account_id = trim_string(options.get("account")) or "default"
+        resolved_existing = get_account_config(root, account_id)
+        existing = account_config_to_raw(resolved_existing) if resolved_existing is not None else {}
+        configured = _build_input(existing, options, account_id)
+        prompted = configured if _has_non_interactive_input(options) else prompt_for_account(existing, account_id)
+
+        if not trim_string(prompted.get("apiUrl")) or not trim_string(prompted.get("apiKey")):
+            raise RuntimeError("apiurl and apikey are required.")
+
+        next_root = upsert_stored_account(root, account_id, prompted, bool(prompted.get("makeDefault")))
+        write_config_root(next_root)
+        return {
+            "ok": True,
+            "accountId": account_id,
+            "defaultAccountId": next_root["defaultAccountId"],
+            "configPath": str(get_config_path()),
+        }
+
+    if subcommand == "list":
+        return list_account_summaries(root)
+
+    if subcommand == "use":
+        account_id = positionals[0] if positionals else ""
+        accounts = root.get("accounts")
+        if not account_id:
+            raise RuntimeError("config use requires <accountId>.")
+        if not isinstance(accounts, dict) or account_id not in accounts:
+            raise RuntimeError(f"Unknown account: {account_id}")
+        next_root = dict(root)
+        next_root["defaultAccountId"] = account_id
+        write_config_root(next_root)
+        return {"ok": True, "defaultAccountId": account_id}
+
+    if subcommand == "remove":
+        account_id = positionals[0] if positionals else ""
+        accounts = root.get("accounts")
+        if not account_id:
+            raise RuntimeError("config remove requires <accountId>.")
+        if not isinstance(accounts, dict) or account_id not in accounts:
+            raise RuntimeError(f"Unknown account: {account_id}")
+        next_root = remove_stored_account(root, account_id)
+        write_config_root(next_root)
+        return {
+            "ok": True,
+            "removedAccountId": account_id,
+            "defaultAccountId": next_root["defaultAccountId"],
+        }
+
+    raise RuntimeError(f"Unknown config subcommand: {subcommand}")