sectl-client 1.0.0

SECTL OAuth API 和云存储 API 的 Python 客户端库

SECTL Python SDK

SECTL OAuth API 和云存储 API 的 Python 客户端库，提供分离的认证客户端（SectinAuthClient）和云存储客户端（CloudStorageClient）。

功能特性

• OAuth 2.0 授权：完整的 OAuth 2.0 授权流程（强制 PKCE 模式）
• Token 管理：获取、刷新、验证、撤销 Token
• 用户信息：获取用户信息、平台权限配置
• 云存储：文件上传、下载、预览、删除、重命名
• 分享管理：创建、管理文件分享链接
• KV 存储：键值对存储服务
• 通知管理：获取、发送、管理通知
• 统计功能：上报在线状态、访问记录
• 职责分离：认证能力使用 SectinAuthClient，云存储能力使用 CloudStorageClient

安装

从源码安装

cd sdk/python
pip install -e .

使用 pip 安装（发布后）

pip install sectl-client

快速开始

1. 配置文件

创建 config.yaml 文件：

sectl:
  base_url: "https://appwrite.sectl.top"
  auth_url: "https://sectl.top"
  platform:
    client_id: "your_platform_id"
    callback_url: "http://localhost:5000/callback"
    callback_port: 5000

2. OAuth 授权

from sectl_client import SectinAuthClient

# 使用配置文件初始化
client = SectinAuthClient(config_path="config.yaml")

# 执行 OAuth 授权（会自动打开浏览器）
token_info = client.authorize(scope=["user:read", "cloud:read", "cloud:write"])

print(f"Access Token: {client.access_token}")
print(f"User ID: {client.user_id}")

3. 获取用户信息

# 获取用户信息
user_info = client.get_user_info()
print(user_info)

# 验证 Token
token_info = client.introspect_token()
print(token_info)

4. 云存储操作

from sectl_client import CloudStorageClient

# 初始化云存储客户端
cloud_client = CloudStorageClient(
    platform_id=client.platform_id,
    access_token=client.access_token,
    base_url=client.base_url,
    user_id=client.user_id
)

# 上传文件
result = cloud_client.upload_file("/path/to/file.txt")
print(f"File ID: {result['file_id']}")

# 获取文件列表
files = cloud_client.list_files(limit=10)
print(files)

# 创建分享链接
share = cloud_client.create_share(
    file_id=result['file_id'],
    expires_in=86400,  # 1天
    password="123456"  # 可选
)
print(f"Share URL: {share['share_url']}")

5. KV 存储

# 设置键值对
cloud_client.set_kv("my_key", {"name": "value", "count": 42})

# 获取键值对
data = cloud_client.get_kv("my_key")
print(data)

# 更新 JSON 字段
cloud_client.update_kv_field("my_key", "count", 43)

# 获取键列表
items = cloud_client.list_kv(prefix="my_", limit=10)
print(items)

6. 通知管理

# 获取通知列表
notifications = client.get_notifications(limit=10, unread_only=True)
print(notifications)

# 标记所有通知为已读
client.mark_all_notifications_read()

# 发送通知（需要平台权限）
client.send_notification(
    user_id="target_user_id",
    title="通知标题",
    content="通知内容",
    priority="high"
)

API 文档

SectinAuthClient

主要的 OAuth 客户端类。

初始化参数

• config_path: 配置文件路径（可选）
• base_url: API 基础 URL（默认：https://appwrite.sectl.top）
• platform_id: 平台 ID / Client ID
• callback_url: OAuth 回调地址
• callback_port: 回调服务器端口（默认：5000）

主要方法

OAuth 流程

• get_authorization_url(scope=None): 生成授权 URL
• authorize(scope=None): 执行完整的 OAuth 授权流程
• exchange_code_for_token(code, scope=None): 使用授权码换取 Token

Token 管理

• refresh_access_token(): 刷新 Access Token
• introspect_token(token=None): 验证 Token 有效性
• logout(): 撤销 Token（登出）
• load_token(): 从文件加载 Token

用户信息

• get_user_info(): 获取用户信息

认证配套接口

• get_platform_permissions(platform_id=None): 获取平台权限配置
• update_user_permissions(platform_id, permissions): 更新用户权限（第一方账户接口，使用 Appwrite 用户 JWT）
• get_user_platforms(): 获取用户已授权平台列表（第一方账户接口，使用 Appwrite 用户 JWT）

通知管理

• get_notifications(limit=20, offset=0, unread_only=False): 获取通知列表
• mark_notification_read(notification_id): 标记通知为已读
• mark_all_notifications_read(): 标记所有通知为已读
• delete_notification(notification_id): 删除通知
• send_notification(...): 发送通知

统计功能

• report_online(device_uuid, ...): 上报在线状态
• report_visit(device_uuid, ...): 上报访问记录
• get_platform_stats(platform_id=None): 获取平台统计数据

CloudStorageClient

云存储客户端类。

初始化参数

• platform_id: 平台 ID
• access_token: OAuth 访问令牌
• base_url: API 基础 URL
• user_id: 用户 ID（Bearer Token 模式通常可省略）

主要方法

文件操作

• upload_file(file_path, folder_id=None): 上传文件
• list_files(folder_id=None, limit=100, offset=0): 获取文件列表
• get_file_info(file_id): 获取文件信息
• download_file(file_id): 获取文件下载链接
• preview_file(file_id): 获取文件预览链接
• rename_file(file_id, new_filename): 重命名文件
• delete_file(file_id): 删除文件

分享管理

• create_share(file_id, expires_in=86400, password=None): 创建分享链接
• list_shares(): 获取分享列表
• disable_share(share_id): 禁用分享
• enable_share(share_id): 启用分享
• delete_share(share_id): 删除分享

KV 存储

• set_kv(key, value, ttl=None): 设置键值对
• get_kv(key): 获取单个键值对
• list_kv(prefix=None, limit=100, offset=0): 获取键列表
• update_kv_field(key, field, value): 更新 KV JSON 字段
• delete_kv(key): 删除键值对

存储管理

• get_storage_usage(): 获取存储使用情况

异常处理

SDK 提供了完整的异常处理机制：

from sectl_client import (
    SectinAuthException,
    AuthenticationError,
    TokenError,
    CloudStorageError,
    NetworkError,
    TokenExpiredError,
    InvalidTokenError
)

try:
    user_info = client.get_user_info()
except TokenExpiredError:
    # Token 过期，刷新 Token
    client.refresh_access_token()
    user_info = client.get_user_info()
except NetworkError as e:
    print(f"网络错误: {e}")
except SectinAuthException as e:
    print(f"SECTL 错误: {e}")

示例代码

查看 examples/ 目录获取更多示例：

• basic_usage.py: 基本使用示例
• cloud_storage.py: 云存储操作示例
• oauth_flow.py: OAuth 授权流程示例

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest tests/

代码格式化

black sectl_client/
flake8 sectl_client/

许可证

MIT License

支持

• 文档：https://github.com/SECTL/sectl-auth
• 问题反馈：https://github.com/SECTL/sectl-auth/issues