Metadata-Version: 2.4
Name: sectl-client
Version: 1.0.0
Summary: SECTL OAuth API 和云存储 API 的 Python 客户端库
Home-page: https://github.com/SECTL/sectl-auth
Author: SECTL Team
Author-email: SECTL Studio <lzy.12@foxmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SECTL/SECTL-One-Stop
Project-URL: Documentation, https://github.com/SECTL/SECTL-One-Stop#readme
Project-URL: Repository, https://github.com/SECTL/SECTL-One-Stop.git
Project-URL: Issues, https://github.com/SECTL/SECTL-One-Stop/issues
Keywords: sectl,oauth,cloud-storage,api-client,sectl-one-stop
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# SECTL Python SDK

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

## 功能特性

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

## 安装

### 从源码安装

```bash
cd sdk/python
pip install -e .
```

### 使用 pip 安装（发布后）

```bash
pip install sectl-client
```

## 快速开始

### 1. 配置文件

创建 `config.yaml` 文件：

```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 授权

```python
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. 获取用户信息

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

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

### 4. 云存储操作

```python
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 存储

```python
# 设置键值对
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. 通知管理

```python
# 获取通知列表
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 提供了完整的异常处理机制：

```python
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 授权流程示例

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest tests/
```

### 代码格式化

```bash
black sectl_client/
flake8 sectl_client/
```

## 许可证

MIT License

## 支持

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