Metadata-Version: 2.4
Name: xfcloudcard
Version: 0.1.0
Summary: 云控卡密验证客户端库 - 支持 AES+HMAC 加密通信、心跳保活、离线上报
Author: songxf
License-Expression: MIT
Project-URL: Homepage, https://github.com/songxf/xfcloudcard
Project-URL: Source, https://github.com/songxf/xfcloudcard
Project-URL: Issues, https://github.com/songxf/xfcloudcard/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pycryptodome>=3.15.0

# xfcloudcard

云控卡密验证客户端库，支持 AES-256-CBC + HMAC-SHA256 加密通信、心跳保活、离线上报。

## 安装

```bash
pip install xfcloudcard
```

## 快速开始

### 方式一：上下文管理器（推荐）

```python
from xfcloudcard import CardClient

with CardClient(server_url="http://localhost:8000", key="your-key") as client:
    result = client.verify("CARD-XXXX-XXXX-XXXX-XXXX")
    if result['success']:
        # 业务代码写这里
        pass
# 退出 with 块时自动停止心跳 + 发送离线通知
```

### 方式二：装饰器（最简洁）

```python
from xfcloudcard import require_card

@require_card(server_url="http://localhost:8000", key="your-key")
def main():
    # 仅当卡密验证通过后才执行
    print("验证通过，执行业务逻辑...")

main()
```

### 方式三：命令行

```bash
# 交互模式
xfcloudcard

# 直接验证
xfcloudcard --card CARD-XXXX-XXXX-XXXX-XXXX

# 只验证，不启动心跳
xfcloudcard --card CARD-XXXX-... --once
```

## API

### `CardClient(server_url, key, heartbeat_interval=60)`

| 方法 | 说明 |
|------|------|
| `verify(card_key)` | 验证卡密，成功后自动启动心跳 |
| `verify_only(card_key)` | 只验证，不启动心跳 |
| `close()` | 停止心跳并发送离线通知 |
| `is_online()` | 返回心跳是否运行中 |

### `require_card(server_url, key, heartbeat_interval=60, exit_on_fail=True)`

装饰器，在业务函数执行前自动验证卡密。

## 依赖

- `requests >= 2.25.0`
- `pycryptodome >= 3.15.0`

## 协议

MIT
