Initial release of 1Claw Python SDK (v0.1.0)

Full-featured Python SDK for the 1Claw secrets management platform,
mirroring the TypeScript SDK architecture. Built from the OpenAPI spec.

- Core HTTP client with auto JWT refresh for agent keys (ocv_)
- 18 resource modules: auth, vaults, secrets, agents, policies, chains,
  sharing, billing, audit, org, api_keys, signing_keys, treasury,
  treasury_wallets, platform, approvals, webhooks, risk
- Comprehensive error hierarchy (AuthError, NotFoundError, etc.)
- Envelope response pattern (OneclawResponse with data/error/meta)
- Single runtime dependency: httpx
- 17 unit tests with respx mocking
- Clean ruff linting and mypy type stubs (py.typed)
- PyPI-ready with hatchling build system
- CI/CD workflow for automated testing and publishing

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: kmjones1979

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/oneclaw/ --ignore-missing-imports
+
+      - name: Test
+        run: pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+venv/
+env/
+*.so
+.coverage
+htmlcov/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 1Claw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,255 @@
+# 1Claw Python SDK
+
+Official Python SDK for the [1Claw](https://1claw.xyz) secrets management platform.
+
+[![PyPI version](https://img.shields.io/pypi/v/oneclaw.svg)](https://pypi.org/project/oneclaw/)
+[![Python versions](https://img.shields.io/pypi/pyversions/oneclaw.svg)](https://pypi.org/project/oneclaw/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install oneclaw
+```
+
+## Quick Start
+
+### Agent Authentication (API Key)
+
+```python
+from oneclaw import create_client
+
+# Agent keys (ocv_) auto-exchange for JWTs and refresh before expiry
+client = create_client(api_key="ocv_your_agent_key")
+
+# Agent ID is auto-discovered from the token exchange
+print(client.resolved_agent_id)
+```
+
+### User Authentication
+
+```python
+from oneclaw import create_client
+
+# User API key (1ck_) — auto-exchanges for JWT
+client = create_client(api_key="1ck_your_user_key")
+
+# Or login with email/password
+client = create_client()
+client.auth.login("user@example.com", "password")
+```
+
+### Pre-authenticated with JWT
+
+```python
+client = create_client(token="eyJ...")
+```
+
+## Usage
+
+### Vaults
+
+```python
+# Create a vault
+resp = client.vaults.create("my-vault", description="Production secrets")
+vault_id = resp.data["id"]
+
+# List vaults
+vaults = client.vaults.list()
+for v in vaults.data["vaults"]:
+    print(v["name"])
+```
+
+### Secrets
+
+```python
+# Store a secret
+client.secrets.set(vault_id, "api-key", "sk-secret-value")
+
+# Retrieve a secret
+secret = client.secrets.get(vault_id, "api-key")
+print(secret.data["value"])
+
+# Server-side rotation (vault generates a random value)
+client.secrets.rotate_generate(vault_id, "api-key", length=64, charset="base64")
+
+# List versions
+versions = client.secrets.list_versions(vault_id, "api-key")
+```
+
+### Agents
+
+```python
+# Register an agent
+resp = client.agents.create("my-agent", description="CI/CD bot")
+agent = resp.data["agent"]
+api_key = resp.data["api_key"]  # Save this — shown only once
+
+# Self-enroll (no auth required)
+client.agents.enroll("my-agent", "admin@example.com")
+```
+
+### Access Policies
+
+```python
+# Grant an agent read access to secrets matching a pattern
+client.policies.create(
+    vault_id,
+    principal_type="agent",
+    principal_id=agent_id,
+    secret_path_pattern="production/*",
+    permissions=["read"],
+)
+```
+
+### Intents API (Transaction Signing)
+
+```python
+# Submit a transaction
+resp = client.agents.submit_transaction(
+    agent_id,
+    chain="ethereum",
+    to="0x...",
+    value="1000000000000000",  # wei
+    max_fee_per_gas="30000000000",
+    max_priority_fee_per_gas="1000000000",
+)
+print(resp.data["tx_hash"])
+
+# Unified signing (personal_sign, typed_data, transaction)
+resp = client.agents.sign_intent(
+    agent_id,
+    intent_type="personal_sign",
+    chain="ethereum",
+    message="0x48656c6c6f",
+)
+print(resp.data["signature"])
+```
+
+### Signing Keys
+
+```python
+# Provision a signing key
+client.signing_keys.create(agent_id, "ethereum")
+
+# List keys
+keys = client.signing_keys.list(agent_id)
+
+# Check balance
+balance = client.signing_keys.balance(agent_id, "ethereum")
+```
+
+### Treasury
+
+```python
+# Create a treasury
+client.treasury.create("Team Treasury", safe_address="0x...", chain="ethereum")
+
+# Create a multisig proposal
+client.treasury.propose(treasury_id, chain="ethereum", to="0x...", value="1000000000")
+
+# Sign a proposal
+client.treasury.sign_proposal(treasury_id, proposal_id, signature="0x...", decision="approve")
+```
+
+### Treasury Wallets
+
+```python
+# Generate wallets for all supported chains
+client.treasury_wallets.generate()
+
+# Check balance
+balance = client.treasury_wallets.balance("ethereum")
+
+# Send tokens (requires password re-auth)
+client.treasury_wallets.send(
+    "ethereum",
+    to="0x...",
+    value="1000000000000000",
+    password="your-account-password",
+)
+```
+
+### Platform API
+
+```python
+# Register a platform app
+resp = client.platform.create_app("My App", "my-app")
+plt_key = resp.data["api_key"]  # Save this
+
+# Provision a user
+conn = client.platform.upsert_user(email="user@example.com")
+
+# Bootstrap resources from a template
+bootstrap = client.platform.bootstrap_user(conn.data["connection_id"])
+```
+
+### Webhooks
+
+```python
+client.webhooks.create(
+    url="https://example.com/webhook",
+    events=["agent.transaction.broadcast", "proposal.executed"],
+    secret="whsec_...",
+)
+```
+
+### Risk Engine
+
+```python
+# List risk events
+events = client.risk.list_events(severity="high")
+
+# Register a honeytoken
+client.risk.create_honeytoken(vault_id, "canary/secret-key")
+```
+
+## Error Handling
+
+```python
+from oneclaw import create_client, OneclawError, AuthError, NotFoundError
+
+client = create_client(api_key="ocv_...")
+
+# Envelope-style (no exceptions)
+resp = client.vaults.get("nonexistent-id")
+if resp.error:
+    print(f"Error: {resp.error.message}")
+
+# Exception-style (use the underlying HTTP client)
+try:
+    data = client._http.request_or_throw("GET", "/v1/vaults/bad-id")
+except NotFoundError:
+    print("Vault not found")
+except AuthError:
+    print("Authentication failed")
+except OneclawError as e:
+    print(f"API error: {e} (status={e.status})")
+```
+
+## Context Manager
+
+```python
+with create_client(api_key="ocv_...") as client:
+    vaults = client.vaults.list()
+    # Connection pool is automatically closed
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `base_url` | `https://api.1claw.xyz` | API base URL |
+| `token` | `None` | Pre-existing JWT |
+| `api_key` | `None` | `ocv_` (agent) or `1ck_` (user) key |
+| `agent_id` | `None` | Agent UUID (optional, auto-discovered) |
+| `timeout` | `30.0` | HTTP timeout in seconds |
+
+## Requirements
+
+- Python 3.9+
+- [httpx](https://www.python-httpx.org/) (only runtime dependency)
+
+## License
+
+MIT