Metadata-Version: 2.4
Name: x-api-rs
Version: 3.0.13
Classifier: Programming Language :: Rust
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21 ; extra == 'test'
Provides-Extra: test
Summary: Twitter/X API 客户端库 (Rust 实现, 提供 Python 绑定)
Author-email: robin <robin528919@gmail.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://x-api-rs.es007.com
Project-URL: Homepage, https://github.com/open-luban/x-api-rs
Project-URL: Issues, https://github.com/open-luban/x-api-rs/issues
Project-URL: Repository, https://github.com/open-luban/x-api-rs.git

# x-api-rs

X/Twitter Web 私有 API 的 Rust 核心库、Python 绑定和 CLI 工具。

## 当前架构

本仓库已经拆分为 Rust workspace：

```text
src/core  # x-api-core：真实业务实现
src/py    # x-api-py：Python 绑定
src/cli   # x-api-cli：命令行工具，二进制名 x-api
```

核心协议边界统一放在 `x_api_core::web`。XChat 是 Web 协议下的复杂子域，位于 `web::xchat`。

## Rust 用法

```rust
use x_api_core::web::{WebClient, WebProfile};

#[tokio::main]
async fn main() -> x_api_core::Result<()> {
    let cookies = "ct0=xxx; auth_token=yyy; twid=u%3D123456789";
    let client = WebClient::builder()
        .cookies(cookies)
        .profile(WebProfile::default_latest())
        .build()
        .await?;

    let result = client.dm().send_message("123456789", "hello", None).await?;
    println!("{result:?}");
    Ok(())
}
```

## Python 用法

```python
from x_api_rs.web import Client, WebProfile

client = await Client.create(
    cookies,
    proxy_url=None,
    profile=WebProfile.default_latest(),
)

# 只有 auth_token、还没有完整 cookies 时，先换取 cookies 再创建客户端：
res = await Client.auth_token_to_cookies(auth_token, proxy_url=None)
client = await Client.create(res.cookies)  # res.cookies 含 auth_token + ct0 + twid
```

## Web 环境快照

`WebEnvironmentSnapshot` 可把 cookies、CSRF、auth token、user id、代理、WebProfile、UA/请求头策略、ClientTransaction 材料和可选 XChat keystore 材料导出为 JSON，适合存入数据库后下次离线还原客户端。

快照是明文敏感数据，包含可直接恢复账号会话的 cookies/token，启用 XChat 时还可能包含私钥材料。生产环境应由调用方使用数据库加密、KMS 或应用层加密后存储。

```rust
let snapshot_json = client.export_environment()?.to_json()?;
let restored = WebClient::restore_environment(WebEnvironmentSnapshot::from_json(&snapshot_json)?)?;
```

```python
snapshot_json = client.export_environment_json()
restored = Client.restore_environment_json(snapshot_json)
```

## CLI 用法

```bash
x-api --cookies-file cookies.txt dm send --user-id 123 --text "hello"
x-api --cookies-file cookies.txt environment export --allow-plaintext-secrets > state.jsonl
x-api environment restore-check --state-file state.json
x-api auth token-to-cookies --token <auth_token> --allow-plaintext-secrets
x-api version-full
x-api output-schema
```

CLI 输出保持 JSONL envelope，适合 agent、脚本和管道消费。

## 验证命令

```bash
cargo check --workspace --all-features
cargo test -p x-api-core --all-features --no-run
cargo test -p x-api-cli --all-features
```

Python wheel 构建需要安装 `maturin`：

```bash
python3 -m maturin build --manifest-path src/py/Cargo.toml --features "dm upload inbox user posts communities settings search xchat"
```

