Metadata-Version: 2.4
Name: icpay-bucket
Version: 1.0.0
Summary: Minimal ICPay Bucket client — on-chain encrypted file storage on the Internet Computer
License: MIT
Project-URL: Homepage, https://icpay.app
Keywords: icp,internet-computer,bucket,storage,cloud,icpay
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ic-py>=1.0.1

# icpay-bucket

Minimal client for [ICPay Bucket](https://icpay.app) — on-chain encrypted file
storage on the Internet Computer.

```
pip install icpay-bucket
```

## Quick start

```python
from icpay_bucket import BucketClient

# Writes are authorized by a bucket API key (create it in the ICPay UI).
client = BucketClient(api_key="icp_cloud_…")

# Upload (single call, files up to ~1.85 MB)
result = client.upload_file(
    bucket_id="icp",
    path="/logo.webp",
    data=b"webp bytes…",
    content_type="image/webp",
)
if "err" in result:
    raise RuntimeError(result["err"])

# Public CDN URL — no call needed
url = client.public_url("icp", "/logo.webp")

# List files
listing = client.list_files("icp", page=0, page_size=20)
print([f["path"] for f in listing["ok"]["items"]])

# Delete with the API key
client.delete_file("icp", "/logo.webp")
```

## API

- `upload_file(bucket_id, path, data, content_type, api_key?)` — returns
  `{"ok": file_id} | {"err": …}`.
- `delete_file(bucket_id, path, api_key?)` — returns
  `{"ok": None} | {"err": …}`.
- `list_files(bucket_id, page, page_size)` — paginated file list.
- `download_file(bucket_id, path)` — file bytes (public + private buckets).
- `get_public_file_url(bucket_id, path)` — canister-provided CDN URL.
- `public_url(bucket_name, path)` — CDN URL computed locally (no call).
- `public_file_url(canister_id, bucket_name, path)` — same, standalone.

Writes are authorized by a bucket API key. Reads on public buckets work for any
caller.

## License

MIT
