imbot-sdk-python 0.1.1__tar.gz → 0.1.2__tar.gz

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.2] - 2026-06-26
+
+### Added
+
+- `examples/register_bot.py`: register a bot/user via the Server API and print a
+  connection token (standard library only, no hard-coded credentials).
+- Token acquisition documented in the README and protocol docs (Server API
+  endpoint, signature auth, response envelope).
+
 ## [0.1.1] - 2026-06-25
 
 ### Changed
@@ -31,5 +40,6 @@ All notable changes to this project are documented here. The format follows
   text, recall info, merge, thumbnail-packed image, snapshot-packed video) with
   an `UnknownMessage` fallback.
 
+[0.1.2]: https://github.com/juggleim/imbot-sdk-python/releases/tag/v0.1.2
 [0.1.1]: https://github.com/juggleim/imbot-sdk-python/releases/tag/v0.1.1
 [0.1.0]: https://github.com/juggleim/imbot-sdk-python/releases/tag/v0.1.0

{imbot_sdk_python-0.1.1/imbot_sdk_python.egg-info → imbot_sdk_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbot-sdk-python
-Version: 0.1.1
+Version: 0.1.2
 Summary: JuggleIM Python Bot SDK — WebSocket long-connection IM client for bots and server-side agents
 Author-email: Tyler <tyler@juggle.im>
 Maintainer-email: Tyler <tyler@juggle.im>
@@ -78,6 +78,37 @@ pip install .
 > + AppSecret via the Server API. The SDK itself only establishes the
 > connection and sends/receives messages.
 
+## Obtaining a token
+
+`connect(token)` needs a per-user token. Tokens are minted by your app server
+through the JuggleIM Server API using your AppKey + AppSecret. Registering a bot
+(or a user) returns a token:
+
+- Endpoint: `POST {ServerAPI}/bots/register` (or `/users/register`)
+- Auth headers: `appkey`, `nonce` (random 0-9999), `timestamp` (epoch ms),
+  `signature = lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`,
+  `Content-Type: application/json`
+- Response: `{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`
+
+A ready-to-use helper (standard library only, no hard-coded credentials) is
+[`examples/register_bot.py`](examples/register_bot.py):
+
+```bash
+export IMBOT_API_URL="https://api.juggleim.com/apigateway"
+export IMBOT_APPKEY="<your-appkey>"
+export IMBOT_APPSECRET="<your-appsecret>"
+
+# register a bot and print its token
+python examples/register_bot.py --bot-id my-bot --nickname "My Bot"
+
+# or register a normal user
+python examples/register_bot.py --user --user-id u1 --nickname "User 1"
+```
+
+> Keep your AppSecret on the server side — never ship it inside client apps.
+> If the Server API host presents an expired/invalid TLS certificate, pass
+> `--insecure` to bypass verification (use only against endpoints you trust).
+
 ## Feature overview
 
 - Connection management: `connect`, `disconnect`, `logout`, heartbeat keep-alive,

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/README.md

@@ -44,6 +44,37 @@ pip install .
 > + AppSecret via the Server API. The SDK itself only establishes the
 > connection and sends/receives messages.
 
+## Obtaining a token
+
+`connect(token)` needs a per-user token. Tokens are minted by your app server
+through the JuggleIM Server API using your AppKey + AppSecret. Registering a bot
+(or a user) returns a token:
+
+- Endpoint: `POST {ServerAPI}/bots/register` (or `/users/register`)
+- Auth headers: `appkey`, `nonce` (random 0-9999), `timestamp` (epoch ms),
+  `signature = lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`,
+  `Content-Type: application/json`
+- Response: `{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`
+
+A ready-to-use helper (standard library only, no hard-coded credentials) is
+[`examples/register_bot.py`](examples/register_bot.py):
+
+```bash
+export IMBOT_API_URL="https://api.juggleim.com/apigateway"
+export IMBOT_APPKEY="<your-appkey>"
+export IMBOT_APPSECRET="<your-appsecret>"
+
+# register a bot and print its token
+python examples/register_bot.py --bot-id my-bot --nickname "My Bot"
+
+# or register a normal user
+python examples/register_bot.py --user --user-id u1 --nickname "User 1"
+```
+
+> Keep your AppSecret on the server side — never ship it inside client apps.
+> If the Server API host presents an expired/invalid TLS certificate, pass
+> `--insecure` to bypass verification (use only against endpoints you trust).
+
 ## Feature overview
 
 - Connection management: `connect`, `disconnect`, `logout`, heartbeat keep-alive,

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/README.zh-CN.md

@@ -37,6 +37,35 @@ pip install .
 
 > Token 由你的 JuggleIM 应用服务端 / 控制台用 AppKey + AppSecret 通过 Server API 颁发。SDK 本身只负责建立长连接与收发消息。
 
+## 获取 Token
+
+`connect(token)` 需要一个用户级 Token，由应用服务端通过 JuggleIM Server API 用
+AppKey + AppSecret 颁发。注册一个 bot（或用户）即可拿到 Token：
+
+- 接口：`POST {ServerAPI}/bots/register`（或 `/users/register`）
+- 鉴权头：`appkey`、`nonce`（0-9999 随机）、`timestamp`（毫秒）、
+  `signature = lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`、
+  `Content-Type: application/json`
+- 返回：`{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`
+
+提供了开箱即用的脚本（纯标准库、不硬编码凭证）
+[`examples/register_bot.py`](examples/register_bot.py)：
+
+```bash
+export IMBOT_API_URL="https://api.juggleim.com/apigateway"
+export IMBOT_APPKEY="<你的 appkey>"
+export IMBOT_APPSECRET="<你的 appsecret>"
+
+# 注册一个 bot 并打印其 token
+python examples/register_bot.py --bot-id my-bot --nickname "My Bot"
+
+# 或注册一个普通用户
+python examples/register_bot.py --user --user-id u1 --nickname "User 1"
+```
+
+> AppSecret 只应保存在服务端，切勿打包进客户端应用。
+> 若 Server API 域名的 TLS 证书已过期 / 无效，可加 `--insecure` 跳过校验（仅对你信任的端点使用）。
+
 ## 能力概览
 
 - 连接管理：`connect`、`disconnect`、`logout`、心跳保活、断线自动重连

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/docs/PROTOCOL.md

@@ -5,6 +5,27 @@
 The wire protocol implemented by this SDK interoperates with the other JuggleIM
 client SDKs and the JuggleIM server.
 
+## Server API: obtaining a token
+
+`connect(token)` needs a user token, minted via the JuggleIM **Server API**
+(HTTP) using your AppKey + AppSecret. This is separate from the WebSocket wire
+protocol below.
+
+- Register a bot: `POST {ServerAPI}/bots/register` with JSON body
+  `{"bot_id": "...", "nickname": "...", "ext_fields": {}}`.
+- Register a user: `POST {ServerAPI}/users/register` with `{"user_id": "...", ...}`.
+- Auth headers on every Server API request:
+  - `appkey`: your AppKey
+  - `nonce`: random integer `0..9999` as a string
+  - `timestamp`: current epoch milliseconds as a string
+  - `signature`: `lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`
+  - `Content-Type: application/json`
+- Response envelope: `{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`.
+  Use `data.token` as the argument to `connect`.
+
+See [`examples/register_bot.py`](../examples/register_bot.py) for a runnable
+reference (standard library only, credentials read from env/flags).
+
 ## Connection
 
 - Address: the `address` passed to `ImBotClient(address, app_key)` is the base

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/docs/PROTOCOL.zh-CN.md

@@ -4,6 +4,25 @@
 
 本 SDK 实现的线协议可与其它 JuggleIM 客户端 SDK 及 JuggleIM 服务端互通。
 
+## Server API：获取 Token
+
+`connect(token)` 需要一个用户 Token，通过 JuggleIM **Server API**（HTTP）用
+AppKey + AppSecret 颁发。这与下文的 WebSocket 线协议是相互独立的。
+
+- 注册 bot：`POST {ServerAPI}/bots/register`，JSON body
+  `{"bot_id": "...", "nickname": "...", "ext_fields": {}}`。
+- 注册用户：`POST {ServerAPI}/users/register`，body 为 `{"user_id": "...", ...}`。
+- 每个 Server API 请求的鉴权头：
+  - `appkey`：你的 AppKey
+  - `nonce`：`0..9999` 的随机整数（字符串）
+  - `timestamp`：当前毫秒时间戳（字符串）
+  - `signature`：`lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`
+  - `Content-Type: application/json`
+- 返回信封：`{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`，
+  其中 `data.token` 即用于 `connect` 的 Token。
+
+可运行的参考见 [`examples/register_bot.py`](../examples/register_bot.py)（纯标准库，凭证从环境变量/参数读取）。
+
 ## 连接
 
 - 地址：`ImBotClient(address, app_key)` 中的 `address` 为基础地址（`ws://host`

imbot_sdk_python-0.1.2/examples/register_bot.py

@@ -0,0 +1,125 @@
+"""Register a bot (or user) via the JuggleIM Server API and print its token.
+
+The token returned here is what `ImBotClient.connect(token)` expects.
+
+Authentication (JuggleIM Server API): each request carries the headers
+``appkey``, ``nonce`` (random 0-9999), ``timestamp`` (epoch ms) and
+``signature = lowercase_hex( SHA1(AppSecret + nonce + timestamp) )``.
+
+No server credentials are hard-coded — supply them via environment variables or
+CLI flags:
+
+    export IMBOT_API_URL="https://api.juggleim.com/apigateway"
+    export IMBOT_APPKEY="<your-appkey>"
+    export IMBOT_APPSECRET="<your-appsecret>"
+
+    # register a bot
+    python examples/register_bot.py --bot-id my-bot --nickname "My Bot"
+
+    # or register a normal user
+    python examples/register_bot.py --user --user-id u1 --nickname "User 1"
+
+Uses only the Python standard library.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import random
+import ssl
+import sys
+import time
+import urllib.request
+
+
+def _auth_headers(appsecret: str, appkey: str) -> dict:
+    nonce = str(random.randint(0, 9999))
+    timestamp = str(int(time.time() * 1000))
+    signature = hashlib.sha1((appsecret + nonce + timestamp).encode("utf-8")).hexdigest()
+    return {
+        "Content-Type": "application/json",
+        "appkey": appkey,
+        "nonce": nonce,
+        "timestamp": timestamp,
+        "signature": signature,
+    }
+
+
+def _post(api_url: str, path: str, appkey: str, appsecret: str, body: dict, insecure: bool):
+    url = api_url.rstrip("/") + path
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, headers=_auth_headers(appsecret, appkey), method="POST"
+    )
+    ctx = ssl._create_unverified_context() if insecure else None
+    with urllib.request.urlopen(req, timeout=15, context=ctx) as resp:
+        return resp.status, resp.read().decode("utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Register a JuggleIM bot/user and print its token")
+    parser.add_argument("--api-url", default=os.getenv("IMBOT_API_URL", ""),
+                        help="Server API base, e.g. https://api.juggleim.com/apigateway (env IMBOT_API_URL)")
+    parser.add_argument("--appkey", default=os.getenv("IMBOT_APPKEY", ""),
+                        help="App AppKey (env IMBOT_APPKEY)")
+    parser.add_argument("--appsecret", default=os.getenv("IMBOT_APPSECRET", ""),
+                        help="App AppSecret (env IMBOT_APPSECRET)")
+    parser.add_argument("--bot-id", default="", help="bot id to register")
+    parser.add_argument("--user-id", default="", help="user id to register (with --user)")
+    parser.add_argument("--nickname", default="", help="display name")
+    parser.add_argument("--user", action="store_true",
+                        help="register a normal user (/users/register) instead of a bot")
+    parser.add_argument("--insecure", action="store_true",
+                        help="skip TLS verification (workaround for an expired server certificate)")
+    args = parser.parse_args()
+
+    missing = [n for n, v in (("--api-url", args.api_url), ("--appkey", args.appkey),
+                              ("--appsecret", args.appsecret)) if not v]
+    if missing:
+        print("error: missing required config: " + ", ".join(missing)
+              + " (pass the flag or set the matching IMBOT_* env var)", file=sys.stderr)
+        return 2
+
+    if args.user:
+        ident = args.user_id
+        if not ident:
+            print("error: --user-id is required with --user", file=sys.stderr)
+            return 2
+        path = "/users/register"
+        body = {"user_id": ident, "nickname": args.nickname, "ext_fields": {}}
+    else:
+        ident = args.bot_id
+        if not ident:
+            print("error: --bot-id is required", file=sys.stderr)
+            return 2
+        path = "/bots/register"
+        body = {"bot_id": ident, "nickname": args.nickname, "ext_fields": {}}
+
+    try:
+        status, text = _post(args.api_url, path, args.appkey, args.appsecret, body, args.insecure)
+    except Exception as exc:  # noqa: BLE001
+        print(f"request failed: {exc}", file=sys.stderr)
+        if "CERTIFICATE_VERIFY_FAILED" in str(exc):
+            print("hint: the server's TLS certificate may be invalid/expired; "
+                  "retry with --insecure if you trust the endpoint.", file=sys.stderr)
+        return 1
+
+    try:
+        payload = json.loads(text)
+    except ValueError:
+        print(f"HTTP {status}, non-JSON response: {text}", file=sys.stderr)
+        return 1
+
+    if payload.get("code") != 0:
+        print(f"register failed: HTTP {status} {text}", file=sys.stderr)
+        return 1
+
+    data = payload.get("data", {})
+    print(f"user_id: {data.get('user_id', '')}")
+    print(f"token:   {data.get('token', '')}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/imbot_sdk/__init__.py

@@ -35,7 +35,7 @@ from .models import (
     UserInfo,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "ImBotClient",

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2/imbot_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbot-sdk-python
-Version: 0.1.1
+Version: 0.1.2
 Summary: JuggleIM Python Bot SDK — WebSocket long-connection IM client for bots and server-side agents
 Author-email: Tyler <tyler@juggle.im>
 Maintainer-email: Tyler <tyler@juggle.im>
@@ -78,6 +78,37 @@ pip install .
 > + AppSecret via the Server API. The SDK itself only establishes the
 > connection and sends/receives messages.
 
+## Obtaining a token
+
+`connect(token)` needs a per-user token. Tokens are minted by your app server
+through the JuggleIM Server API using your AppKey + AppSecret. Registering a bot
+(or a user) returns a token:
+
+- Endpoint: `POST {ServerAPI}/bots/register` (or `/users/register`)
+- Auth headers: `appkey`, `nonce` (random 0-9999), `timestamp` (epoch ms),
+  `signature = lowercase_hex( SHA1(AppSecret + nonce + timestamp) )`,
+  `Content-Type: application/json`
+- Response: `{"code":0,"msg":"success","data":{"user_id":"...","token":"..."}}`
+
+A ready-to-use helper (standard library only, no hard-coded credentials) is
+[`examples/register_bot.py`](examples/register_bot.py):
+
+```bash
+export IMBOT_API_URL="https://api.juggleim.com/apigateway"
+export IMBOT_APPKEY="<your-appkey>"
+export IMBOT_APPSECRET="<your-appsecret>"
+
+# register a bot and print its token
+python examples/register_bot.py --bot-id my-bot --nickname "My Bot"
+
+# or register a normal user
+python examples/register_bot.py --user --user-id u1 --nickname "User 1"
+```
+
+> Keep your AppSecret on the server side — never ship it inside client apps.
+> If the Server API host presents an expired/invalid TLS certificate, pass
+> `--insecure` to bypass verification (use only against endpoints you trust).
+
 ## Feature overview
 
 - Connection management: `connect`, `disconnect`, `logout`, heartbeat keep-alive,

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/imbot_sdk_python.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ docs/PROTOCOL.zh-CN.md
 examples/.env.example
 examples/echo_bot.py
 examples/quickstart.py
+examples/register_bot.py
 examples/run.sh
 imbot_sdk/__init__.py
 imbot_sdk/client.py

{imbot_sdk_python-0.1.1 → imbot_sdk_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "imbot-sdk-python"
-version = "0.1.1"
+version = "0.1.2"
 description = "JuggleIM Python Bot SDK — WebSocket long-connection IM client for bots and server-side agents"
 readme = "README.md"
 requires-python = ">=3.8"