Metadata-Version: 2.4
Name: icpay-bucket
Version: 1.1.1
Summary: ICPay Bucket client — full on-chain file storage API for the Internet Computer
License: MIT
Project-URL: Homepage, https://icpay.app/icpay-bucket-sdk
Project-URL: Documentation, https://icpay.app/bucket/docs
Project-URL: Repository, https://github.com/prasangapokharel/icpay-bucket
Keywords: icp,internet-computer,bucket,storage,cloud,icpay
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ic-py>=1.0.1
Requires-Dist: cbor2<6,>=5.4.2
Dynamic: license-file

# icpay-bucket

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

**Canister:** `6vbhm-nqaaa-aaaan-q6muq-cai` · **Version:** 1.1.1

**Docs:** [Package guide](https://icpay.app/icpay-bucket-sdk) · [API reference](https://icpay.app/bucket/docs)

Requires `ic-py>=1.0.1` and `cbor2>=5.4.2,<6` (pinned for query compatibility).

## Install

```bash
pip install icpay-bucket
```

## Quick start

```python
from icpay_bucket import BucketClient

client = BucketClient(api_key="icp_cloud_…")

result = client.upload_file("icp", "/hello.txt", b"hello world\n", "text/plain")
if "err" in result:
    raise RuntimeError(result["err"])

print(client.public_url("icp", "/hello.txt"))
print(client.list_files("icp", page=0, page_size=20))
client.delete_file("icp", "/hello.txt")
```

## Authentication

| Caller | Access |
|---|---|
| **Bucket owner** (Internet Identity) | All methods |
| **Read API key** | `list_files`, `download_file`, `get_file`, `file_exists`, `list_folder`, `search_files`, `get_file_metadata` |
| **Write API key** | Upload, move, copy, tags, metadata, chunked upload |
| **Delete API key** | `delete_file`, `bulk_delete_files` |

Pass `api_key=` per call or set `BucketClient(api_key=…)`.

## API reference

All methods return `{"ok": …}` or `{"err": "…"}`.

### Buckets

| Method | Auth |
|---|---|
| `get_bucket_price(capacity_gb)` | public |
| `create_bucket(name, capacity_gb, visibility="Public")` | owner |
| `get_bucket(bucket_id)` | owner |
| `list_buckets()` | owner |
| `get_bucket_cycle_status()` | public |

### Upload

| Method | Auth |
|---|---|
| `upload_file(bucket_id, path, data, content_type, api_key?)` | write key / owner |
| `begin_file_upload(bucket_id, path, content_type, total_size, api_key?)` | write key / owner |
| `upload_file_chunk_indexed(upload_id, chunk_index, data)` | write key / owner |
| `complete_file_upload(upload_id, api_key?)` | write key / owner |
| `get_upload(upload_id)` | owner principal |
| `cancel_upload(upload_id)` | owner principal |

### Read

| Method | Auth |
|---|---|
| `download_file(bucket_id, path, api_key?)` | read key / owner |
| `get_public_file_url(bucket_id, path)` | public |
| `list_files(bucket_id, page=0, page_size=20, api_key?)` | read key / owner |
| `get_file(bucket_id, path, api_key?)` | read key / owner |
| `file_exists(bucket_id, path, api_key?)` | read key / owner |
| `list_folder(bucket_id, prefix, page, page_size, api_key?)` | read key / owner |
| `search_files(bucket_id, search_query, page, page_size, api_key?)` | read key / owner |
| `get_file_metadata(bucket_id, path, api_key?)` | read key / owner |
| `public_url(bucket_name, path)` | local helper |

### Write

| Method | Auth |
|---|---|
| `move_file(bucket_id, source_path, destination_path, api_key?)` | write key / owner |
| `copy_file(bucket_id, source_path, destination_path, api_key?)` | write key / owner |
| `delete_file(bucket_id, path, api_key?)` | delete key / owner |
| `set_file_tags(bucket_id, path, tags, api_key?)` | write key / owner |
| `set_file_metadata(bucket_id, path, metadata, api_key?)` | write key / owner |

### Bulk (max 20)

| Method | Auth |
|---|---|
| `bulk_delete_files(bucket_id, paths, api_key?)` | delete key / owner |
| `bulk_move_files(bucket_id, operations, api_key?)` | write key / owner |
| `bulk_copy_files(bucket_id, operations, api_key?)` | write key / owner |

Bulk operations use `{"source": "…", "destination": "…"}` dicts.

## Public CDN

```
https://6vbhm-nqaaa-aaaan-q6muq-cai.raw.icp0.io/cloud/{bucketName}{path}
```

## Notes

- Paths must use allowed extensions — use `/file-copy.txt`, not `/file.txt.copy`.
- `get_upload` / `cancel_upload` need the bucket owner's Internet Identity principal.

## License

MIT
