bckt-sdk 0.1.0b1__tar.gz

bckt_sdk-0.1.0b1/.github/workflows/check.yml

@@ -0,0 +1,32 @@
+name: Check SDK
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff check .
+      - run: python -m mypy src/bckt
+      - run: python -m pytest
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: bckt-sdk-${{ matrix.os }}-${{ matrix.python }}
+          path: dist/*

bckt_sdk-0.1.0b1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.env
+.env.*
+!.env.example
+.coverage
+htmlcov/

bckt_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Alvenin
+
+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.

bckt_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: bckt-sdk
+Version: 0.1.0b1
+Summary: The official Python SDK for BCKT storage, uploads and logs.
+Project-URL: Homepage, https://bckt.io
+Project-URL: Repository, https://github.com/bcktio/bckt-python
+Project-URL: Documentation, https://bckt.io/docs
+Author-email: BCKT <hello@bckt.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bckt,cdn,logs,sdk,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://bckt.io">
+    <img src="docs/assets/bckt-sdk-header-1200x630-transparent.png" alt="BCKT object storage, edge delivery and logs" width="100%">
+  </a>
+</p>
+
+# BCKT for Python
+
+Upload the file. Keep the URL. Find the log.
+
+The official Python SDK for BCKT. Files, direct browser uploads and structured logs, with typed sync and async clients.
+
+Python 3.10 or newer. HTTPX handles the connections. Your API key stays on the server.
+
+This is a beta. Local checks cover HTTP requests, streaming, queue failures and the package. It still needs a live BCKT acceptance run before calling it production-tested.
+
+## Get started
+
+```bash
+python -m pip install --pre bckt-sdk
+```
+
+```python
+import os
+from bckt import Bckt
+
+with Bckt(os.environ["BCKT_API_KEY"]) as bckt:
+    uploaded = bckt.files.upload_file(
+        "./photo.webp",
+        folder="phone/photos",
+        private=False,
+    )
+
+print(uploaded["url"])
+```
+
+The package is installed as `bckt-sdk` and imported as `bckt`. If you are working from this repository before the first PyPI release, use `python -m pip install -e .` instead.
+
+Create a key in [API and S3](https://bckt.io/dashboard/credentials). Give it only the scopes your application needs. Don't put it in client-side code or a shared repository.
+
+## Don't load the whole backup into memory
+
+`upload_file` streams from disk. `upload` also accepts bytes, a binary file or an iterator of byte chunks. Streams need their byte length up front.
+
+```python
+from pathlib import Path
+import os
+from bckt import Bckt
+
+backup = Path("./backup.enc")
+
+with Bckt(os.environ["BCKT_API_KEY"]) as bckt, backup.open("rb") as source:
+    bckt.files.upload(
+        source,
+        filename=backup.name,
+        size=backup.stat().st_size,
+        folder="backups",
+        private=True,
+    )
+```
+
+Encrypt sensitive backups before uploading and keep an independent copy. Streams are consumed once. The SDK does not silently restart a failed upload.
+
+## Already using async?
+
+```python
+import asyncio
+import os
+from bckt import AsyncBckt
+
+async def main():
+    async with AsyncBckt(os.environ["BCKT_API_KEY"]) as bckt:
+        uploaded = await bckt.files.upload_file("./photo.webp", folder="photos")
+        print(uploaded["url"])
+
+        async for file in bckt.files.iterate(folder="photos"):
+            print(file["id"], file["original_name"])
+
+asyncio.run(main())
+```
+
+`AsyncBckt` uses native async HTTP requests. Keep one client open for the life of your worker or request handler instead of opening a connection pool per operation.
+
+## Let the browser send the photo
+
+Your server checks the user and issues an upload ticket. The browser sends the image straight to BCKT. Your server does not relay the file or expose its API key.
+
+```python
+ticket = bckt.files.create_upload_url(
+    filename="photo.webp",
+    size=image_size,
+    content_type="image/webp",
+    folder="phone/photos",
+    private=False,
+)
+```
+
+Validate the user's permission, file size and file type before issuing a ticket. Send the raw file body, not multipart form data. A ticket expires after 15 minutes. Don't log or share it.
+
+The [browser upload example](examples/browser-upload/README.md) includes a local Python server and a working file picker. It is a development demo, not an account or session system.
+
+## A file key is not a file ID
+
+Uploads return `file_key` and `url`. Management methods take the UUID from `files.list()`, not the public file key or URL.
+
+```python
+files = bckt.files.list(folder="phone/photos", search="photo.webp")
+
+for file in files["files"]:
+    access = bckt.files.get_access_url(file["id"])
+    print(file["original_name"], access["url"])
+```
+
+Use `get_access_url` for private files. The plain CDN URL returned by an upload is not a signed access link. Upload tickets currently last 15 minutes; private access links last one hour. Read the returned expiration instead of calculating it yourself.
+
+`files.iterate()` handles pagination. `files.download()` streams bytes through a context manager, and `download_to()` refuses to overwrite an existing file. The [file example](examples/files.py) shows both operations.
+
+## Logs you can find again
+
+Create your stream in the dashboard or with `logs.streams.create()` before sending events.
+
+```python
+bckt.logs.streams.create("Payments", "payments")
+
+bckt.logs.send("payments", {
+    "level": "info",
+    "event_type": "payment.completed",
+    "entity_id": "order_123",
+    "message": "Payment received",
+    "payload": {"amount": 29.99, "currency": "EUR"},
+})
+```
+
+`send` waits for API acceptance. `send_batch` accepts up to 1,000 events in one request. A successful response means BCKT accepted the events, not that your business transaction succeeded.
+
+For frequent events, use a bounded queue:
+
+```python
+with bckt.logs.create_logger("server") as logger:
+    logger.info("Worker started", {"worker": "invoices"})
+```
+
+Call `close()` during application shutdown. The queue lives in memory and is lost if the process exits. Failed batches stay queued and pause delivery until you retry or discard them. Read [queue behaviour](docs/operations.md) before using it for anything important.
+
+## Handle the failure
+
+```python
+from bckt import BcktError
+
+try:
+    bckt.files.upload_file("./report.pdf", private=True)
+except BcktError as error:
+    print(error.code, error.status, error.request_id)
+    if error.uncertain:
+        print("Check whether it arrived before uploading again.")
+```
+
+Reads have bounded retries. Writes do not. A lost response after a write may mean the operation succeeded. The SDK exposes that uncertainty instead of creating a second file or log batch.
+
+Local filesystem errors retain their native Python error types. Download stream errors are raised while consuming the context manager.
+
+## Pick what you need
+
+| Task | Methods |
+| --- | --- |
+| Upload content | `files.upload`, `files.upload_file`, `files.upload_json` |
+| Authorize a direct upload | `files.create_upload_url` |
+| Browse files | `files.list`, `files.iterate` |
+| Read files | `files.get_access_url`, `files.download`, `files.download_to` |
+| Manage files | `files.set_visibility`, `files.delete`, `files.delete_many` |
+| Work with folders | `folders.list`, `folders.create`, `folders.delete` |
+| Send and search logs | `logs.send`, `logs.send_batch`, `logs.query` |
+| Work with streams | `logs.streams.list`, `logs.streams.create` |
+| Buffer logs | `logs.create_logger` |
+| Sign an S3 operation | `s3.create_presigned_url` |
+
+The async client has the same resources with `await`, `async for` and `async with` where needed. API responses keep their original snake_case fields, including keys inside your own payloads. See the [method reference](docs/reference.md) for arguments, returns and permissions.
+
+## Something broken?
+
+Open an issue with your Python version, SDK version and a small reproduction. Include the BCKT request ID if you have one. Remove API keys, signed URLs and customer data before posting.
+
+Account question? [hello@bckt.io](mailto:hello@bckt.io).
+
+MIT licensed.

bckt_sdk-0.1.0b1/README.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <a href="https://bckt.io">
+    <img src="docs/assets/bckt-sdk-header-1200x630-transparent.png" alt="BCKT object storage, edge delivery and logs" width="100%">
+  </a>
+</p>
+
+# BCKT for Python
+
+Upload the file. Keep the URL. Find the log.
+
+The official Python SDK for BCKT. Files, direct browser uploads and structured logs, with typed sync and async clients.
+
+Python 3.10 or newer. HTTPX handles the connections. Your API key stays on the server.
+
+This is a beta. Local checks cover HTTP requests, streaming, queue failures and the package. It still needs a live BCKT acceptance run before calling it production-tested.
+
+## Get started
+
+```bash
+python -m pip install --pre bckt-sdk
+```
+
+```python
+import os
+from bckt import Bckt
+
+with Bckt(os.environ["BCKT_API_KEY"]) as bckt:
+    uploaded = bckt.files.upload_file(
+        "./photo.webp",
+        folder="phone/photos",
+        private=False,
+    )
+
+print(uploaded["url"])
+```
+
+The package is installed as `bckt-sdk` and imported as `bckt`. If you are working from this repository before the first PyPI release, use `python -m pip install -e .` instead.
+
+Create a key in [API and S3](https://bckt.io/dashboard/credentials). Give it only the scopes your application needs. Don't put it in client-side code or a shared repository.
+
+## Don't load the whole backup into memory
+
+`upload_file` streams from disk. `upload` also accepts bytes, a binary file or an iterator of byte chunks. Streams need their byte length up front.
+
+```python
+from pathlib import Path
+import os
+from bckt import Bckt
+
+backup = Path("./backup.enc")
+
+with Bckt(os.environ["BCKT_API_KEY"]) as bckt, backup.open("rb") as source:
+    bckt.files.upload(
+        source,
+        filename=backup.name,
+        size=backup.stat().st_size,
+        folder="backups",
+        private=True,
+    )
+```
+
+Encrypt sensitive backups before uploading and keep an independent copy. Streams are consumed once. The SDK does not silently restart a failed upload.
+
+## Already using async?
+
+```python
+import asyncio
+import os
+from bckt import AsyncBckt
+
+async def main():
+    async with AsyncBckt(os.environ["BCKT_API_KEY"]) as bckt:
+        uploaded = await bckt.files.upload_file("./photo.webp", folder="photos")
+        print(uploaded["url"])
+
+        async for file in bckt.files.iterate(folder="photos"):
+            print(file["id"], file["original_name"])
+
+asyncio.run(main())
+```
+
+`AsyncBckt` uses native async HTTP requests. Keep one client open for the life of your worker or request handler instead of opening a connection pool per operation.
+
+## Let the browser send the photo
+
+Your server checks the user and issues an upload ticket. The browser sends the image straight to BCKT. Your server does not relay the file or expose its API key.
+
+```python
+ticket = bckt.files.create_upload_url(
+    filename="photo.webp",
+    size=image_size,
+    content_type="image/webp",
+    folder="phone/photos",
+    private=False,
+)
+```
+
+Validate the user's permission, file size and file type before issuing a ticket. Send the raw file body, not multipart form data. A ticket expires after 15 minutes. Don't log or share it.
+
+The [browser upload example](examples/browser-upload/README.md) includes a local Python server and a working file picker. It is a development demo, not an account or session system.
+
+## A file key is not a file ID
+
+Uploads return `file_key` and `url`. Management methods take the UUID from `files.list()`, not the public file key or URL.
+
+```python
+files = bckt.files.list(folder="phone/photos", search="photo.webp")
+
+for file in files["files"]:
+    access = bckt.files.get_access_url(file["id"])
+    print(file["original_name"], access["url"])
+```
+
+Use `get_access_url` for private files. The plain CDN URL returned by an upload is not a signed access link. Upload tickets currently last 15 minutes; private access links last one hour. Read the returned expiration instead of calculating it yourself.
+
+`files.iterate()` handles pagination. `files.download()` streams bytes through a context manager, and `download_to()` refuses to overwrite an existing file. The [file example](examples/files.py) shows both operations.
+
+## Logs you can find again
+
+Create your stream in the dashboard or with `logs.streams.create()` before sending events.
+
+```python
+bckt.logs.streams.create("Payments", "payments")
+
+bckt.logs.send("payments", {
+    "level": "info",
+    "event_type": "payment.completed",
+    "entity_id": "order_123",
+    "message": "Payment received",
+    "payload": {"amount": 29.99, "currency": "EUR"},
+})
+```
+
+`send` waits for API acceptance. `send_batch` accepts up to 1,000 events in one request. A successful response means BCKT accepted the events, not that your business transaction succeeded.
+
+For frequent events, use a bounded queue:
+
+```python
+with bckt.logs.create_logger("server") as logger:
+    logger.info("Worker started", {"worker": "invoices"})
+```
+
+Call `close()` during application shutdown. The queue lives in memory and is lost if the process exits. Failed batches stay queued and pause delivery until you retry or discard them. Read [queue behaviour](docs/operations.md) before using it for anything important.
+
+## Handle the failure
+
+```python
+from bckt import BcktError
+
+try:
+    bckt.files.upload_file("./report.pdf", private=True)
+except BcktError as error:
+    print(error.code, error.status, error.request_id)
+    if error.uncertain:
+        print("Check whether it arrived before uploading again.")
+```
+
+Reads have bounded retries. Writes do not. A lost response after a write may mean the operation succeeded. The SDK exposes that uncertainty instead of creating a second file or log batch.
+
+Local filesystem errors retain their native Python error types. Download stream errors are raised while consuming the context manager.
+
+## Pick what you need
+
+| Task | Methods |
+| --- | --- |
+| Upload content | `files.upload`, `files.upload_file`, `files.upload_json` |
+| Authorize a direct upload | `files.create_upload_url` |
+| Browse files | `files.list`, `files.iterate` |
+| Read files | `files.get_access_url`, `files.download`, `files.download_to` |
+| Manage files | `files.set_visibility`, `files.delete`, `files.delete_many` |
+| Work with folders | `folders.list`, `folders.create`, `folders.delete` |
+| Send and search logs | `logs.send`, `logs.send_batch`, `logs.query` |
+| Work with streams | `logs.streams.list`, `logs.streams.create` |
+| Buffer logs | `logs.create_logger` |
+| Sign an S3 operation | `s3.create_presigned_url` |
+
+The async client has the same resources with `await`, `async for` and `async with` where needed. API responses keep their original snake_case fields, including keys inside your own payloads. See the [method reference](docs/reference.md) for arguments, returns and permissions.
+
+## Something broken?
+
+Open an issue with your Python version, SDK version and a small reproduction. Include the BCKT request ID if you have one. Remove API keys, signed URLs and customer data before posting.
+
+Account question? [hello@bckt.io](mailto:hello@bckt.io).
+
+MIT licensed.

bckt_sdk-0.1.0b1/docs/operations.md

@@ -0,0 +1,69 @@
+# Running it
+
+Keep the client open while your application runs. Close it on shutdown. Finish any buffered log flush before closing the HTTP client.
+
+## Keys and scopes
+
+Use `files:read` for catalog queries and downloads, `files:write` for uploads and changes, `logs:read` for log queries and `logs:write` for ingestion. Use a server-side key. A browser receives an upload ticket, never your key.
+
+Temporary upload and access URLs are bearer credentials. Don't put them in public logs. The SDK refuses insecure remote endpoints, upload tickets pointing to another origin and HTTP redirects. It attaches authorization only to API calls and authenticated folder creation. File transfers do not carry the key.
+
+Environment proxy variables are deliberately ignored. An explicitly provided HTTPX transport can configure proxies, certificate verification or testing. Treat custom transports as trusted application code.
+
+## Transfer limits
+
+The current API accepts upload-ticket sizes up to 20 GiB, while the current upload service enforces a 5 GiB file limit. Your request can hit an edge or plan limit earlier. This SDK does not bypass those limits, implement multipart S3 uploads, or resume a partially sent body.
+
+Uploads are raw POST bodies. Browser callers must pass the exact file described by their ticket. A successful upload response does not mean moderation has completed. Store the `file_key`, and resolve the catalog UUID when you need file management.
+
+Do not call `upload_file` on a file another process is still writing. The SDK declares its size before transfer and checks streamed byte counts. It cannot provide an atomic filesystem snapshot. Encrypt sensitive backups before uploading and keep an independent copy.
+
+Downloads stream through a context manager. There are no automatic retries after download bytes are delivered. A retry at that point would require your application to decide whether to restart or resume. `download_to` writes to a new destination and removes a partial result when it fails.
+
+## Retries and cancellation
+
+GET requests retry transport failures and HTTP 429, 502, 503 and 504, at most twice by default. Backoff is bounded by `max_retry_delay`. `Retry-After` supports seconds and HTTP dates. If that delay exceeds the configured maximum, the error is returned immediately instead of retrying too early.
+
+Writes never retry automatically. That includes uploads, log ingestion, stream creation, folder changes, signing and deletions. A timeout, lost response, malformed successful response or server error can leave a write's result unknown. Such `BcktError` instances have `uncertain=True`.
+
+Timeouts apply to individual HTTPX connect, read, write and pool operations. They aren't a deadline for the entire file. In async applications, use your application's cancellation/deadline mechanism if you need a total limit. Cancelling an operation stops waiting, not a write already accepted by the server. Python raises `asyncio.CancelledError` rather than wrapping it.
+
+## Recovering a log batch
+
+The logger takes an immutable JSON snapshot when you enqueue. It is bounded by event count and encoded bytes. It keeps unsent events when an API request fails and pauses until you make a decision.
+
+```python
+from bckt import BcktError
+
+try:
+    logger.flush()
+except BcktError as error:
+    print(error.code, logger.stats["queued"])
+```
+
+For a clear rejection, fix the underlying problem, then:
+
+```python
+logger.flush(retry_failed=True)
+```
+
+If the batch might already have arrived, inspect the stream first. When you accept the possibility of duplicates:
+
+```python
+logger.flush(retry_failed=True, accept_duplicates=True)
+```
+
+Or discard only the failed batch and keep later events:
+
+```python
+discarded = logger.discard_failed()
+logger.flush()
+```
+
+Use `await` for async flushes. An async flush cancelled during ingestion marks that batch uncertain. Concurrent flush calls are serialized, so they cannot send the same queued events twice. There is no automatic timer, persistence, shutdown hook or silent retry loop. On an exceptional logger context exit, explicitly decide what to do with the remaining queue.
+
+## Publishing
+
+The distribution name is `bckt-sdk`; the import is `bckt`; the initial version is `0.1.0b1`. PyPI uses PEP 440 prerelease notation, so this is a beta version. The name and publishing permissions must be confirmed on PyPI before the first upload. GitHub ownership does not grant PyPI ownership.
+
+Build with `python -m build`. The wheel is the installable package and the `.tar.gz` is the source distribution. Neither contains keys or a virtual environment. Publishing is a separate step; the CI workflow only validates and builds artifacts.

bckt_sdk-0.1.0b1/docs/reference.md

@@ -0,0 +1,120 @@
+# Python reference
+
+`Bckt` is synchronous. `AsyncBckt` has the same resource methods with `await`, except `iterate` and `download`, which use `async for` and `async with`. Logger enqueue methods are synchronous in both clients. Values returned by the API retain their original snake_case field names.
+
+## Client
+
+```python
+from bckt import Bckt, AsyncBckt
+
+client = Bckt(
+    api_key="your-server-key",
+    timeout=30,
+    upload_timeout=300,
+    max_retries=2,
+    max_retry_delay=30,
+)
+```
+
+Timeouts are seconds per HTTPX network operation, not a total upload deadline. `upload_timeout` also applies to downloads. `max_retries` counts retries after the first GET attempt. No mutation is retried, including access URL creation.
+
+`base_url` defaults to `https://api.bckt.io/api/v1`. `upload_base_url` defaults to `https://upload.bckt.io`. Custom endpoints must use HTTPS, except localhost for tests. Endpoint URLs cannot contain credentials, fragments or query strings. `http_transport` accepts an HTTPX transport for testing; the SDK owns and closes it. Environment proxy settings are not picked up automatically.
+
+Use `with Bckt(...)` or `async with AsyncBckt(...)`. Otherwise call `close()` or `await aclose()`. Closing a client does not flush separately created loggers. Flush those first. An async client belongs to one asyncio event loop.
+
+## Files
+
+| Method | Arguments | Result |
+| --- | --- | --- |
+| `upload_file` | `path`, optional `filename`, `folder`, `content_type`, `private` | Upload result |
+| `upload` | `source`, required `filename`, optional `size`, `folder`, `content_type`, `private` | Upload result |
+| `upload_json` | JSON value, required `filename`, optional `folder`, `private` | Upload result |
+| `create_upload_url` | `filename`, `size`, optional `folder`, `content_type`, `private` | Upload ticket |
+| `list` | Optional filters below | Files, folders and pagination |
+| `iterate` | Same filters, without `page` | Lazy iterator of catalog files |
+| `get_access_url` | File UUID | `url`, `expires_at` |
+| `download` | File UUID | Context manager yielding byte chunks |
+| `download_to` | File UUID, destination path | Number of bytes written |
+| `set_visibility` | File UUID, `private` boolean | Updated file ID and visibility |
+| `delete` | File UUID | `None` |
+| `delete_many` | List of file UUIDs, `concurrency=4` | Ordered individual results |
+
+Optional arguments are keyword-only. Uploads default to public. Set `private=True` for private objects. Content type is guessed from the filename unless supplied. Empty uploads are rejected by the API contract. A stream must yield exactly the declared number of bytes. The synchronous client also accepts open binary files. The async client accepts async byte iterators, not synchronous file handles.
+
+The upload result contains `success`, `file_key`, `url`, `size`, `is_private` and `moderation_status`. It does not contain a catalog UUID. Look up `id` in the catalog for subsequent management calls. A moderation status of `pending` does not mean review has completed.
+
+The upload ticket contains `success`, `upload_url`, `method`, `headers`, `max_bytes` and `expires_at`. Browser code should let the browser set `Content-Length`. The upload server gets the filename from the ticket. Never attach the API key to a ticket upload.
+
+`list` and `iterate` accept:
+
+| Filter | Default | Values |
+| --- | --- | --- |
+| `folder` | `""` | Folder path |
+| `search` | `None` | Up to 200 characters |
+| `access` | `"all"` | `all`, `public`, `private` |
+| `type` | `"all"` | `all`, `image`, `video`, `audio`, `other` |
+| `sort` | `"newest"` | `newest`, `oldest`, `name`, `size` |
+| `page` | `1` | Positive integer, only for `list` |
+| `limit` | `25` | 10 through 100 |
+
+List responses contain `files`, `folders` and `pagination` with `page`, `per_page`, `total`, `total_pages`. Catalog files include `id`, `public_key`, `original_name`, `folder`, `mime_type`, `size_bytes`, `is_private`, `created_at`, `url`. Byte counts may be strings. Iteration does not recursively visit subfolders or prefetch the next page. It uses offset pagination, so concurrent catalog changes can shift results.
+
+Access URLs for public files have `expires_at=null`. Private access links expire and must be treated as credentials. Download contexts always close their connection, even when you stop reading early. They do not retry an interrupted stream or follow redirects. `download_to` removes its incomplete file on failure and never overwrites an existing path.
+
+`delete_many` accepts at most 10,000 IDs, deduplicates them in input order and uses between 1 and 16 concurrent requests. Results contain `id` and `success`; failures also contain a `BcktError` under `error`. Deletion is not atomic. Cancelling the async call cannot undo completed deletions.
+
+## Folders
+
+`client.folders` and `client.files.folders` refer to the same resource.
+
+```python
+client.folders.list()
+client.folders.create("reports/2026")
+client.folders.delete("reports/2026", recursive=True)
+```
+
+Create returns `folder`. List returns `folders` with `folder`, `file_count`, `size_bytes`. Delete returns `deleted_objects`. Folder creation uses the BCKT upload endpoint with authorization. Root paths and dot segments are rejected for mutations. Removing a folder removes its contents; there is no trash operation.
+
+## Logs
+
+```python
+client.logs.streams.list()
+client.logs.streams.create("Orders", "orders")
+client.logs.send("orders", {"message": "Paid", "payload": {"order": 42}})
+client.logs.send_batch("orders", [{"message": "One"}, {"message": "Two"}])
+client.logs.query(
+    "orders",
+    start="2026-09-19T00:00:00Z",
+    end="2026-09-19T23:59:59Z",
+    search="Paid",
+    limit=200,
+)
+```
+
+Stream slugs contain 2 to 63 lowercase letters, digits, underscores or hyphens and start with a letter or digit. Stream names contain 2 to 80 characters. Duplicate creation is an API error, not an upsert.
+
+An event accepts `timestamp`, `level`, `event_type`, `entity_id`, `message`, `payload`. Default level is `info` and payload is `{}`. Put arbitrary data in `payload`; unknown top-level fields are rejected. Datetimes must carry a timezone. They are sent as UTC ISO timestamps. Batch size is 1 to 1,000 events, up to 9 MiB encoded JSON. Ingestion returns `accepted` and `bytes`.
+
+Query requires `start` and `end` (ISO strings or aware Python datetimes), in order and at most 31 days apart. Optional `event_type`, `entity_id`, `search` and `limit` (1 to 1,000). Results contain `events`, `timeline` and `scanned_segments`. The query API has no pagination cursor.
+
+## Buffered logs
+
+`logs.create_logger(stream, batch_size=100, max_queue_size=5000, max_queue_bytes=8388608)` creates an in-memory queue. It does not start a worker or timer. Schedule `flush()` in your application if you need periodic delivery.
+
+- `log(event)`, `debug(message, payload=None)`, `info`, `warn`, `error`: enqueue a snapshot of the event.
+- `flush(retry_failed=False, accept_duplicates=False)`: drain the queue, preserving a failed batch.
+- `discard_failed()`: remove only the failed batch and return how many events were discarded.
+- `stats`: `queued`, `bytes`, `sending`, `paused`, `closed`, `last_error`.
+- `close()`: stop accepting events and flush. A failed close preserves the queue for explicit recovery.
+
+Enqueue methods and `discard_failed()` do not need `await` in the async logger. Flush and close do. Each queued event is limited to 1 MiB. Each outgoing logger batch stays within 8 MiB. A full queue raises `QUEUE_FULL`, with no silent drops. No disk persistence or process-exit delivery guarantee is provided.
+
+## S3 URLs
+
+`s3.create_presigned_url(key, method="PUT", expires_in=None)` supports `GET`, `PUT`, `HEAD`, `DELETE`. An explicit expiry is between 1 and 604,800 seconds; omitted expiry uses the API default. Responses include `method`, `url`, `headers`, `expires_at`, and may include `upload_url` for PUT. A workspace S3 credential is required.
+
+## Errors
+
+`BcktError` has `code`, `status`, `request_id`, `retry_after` (seconds) and `uncertain`. Values may be `None` when no HTTP response arrived. Local errors include `INVALID_ARGUMENT`, `SIZE_MISMATCH`, `INVALID_RESPONSE`, `TIMEOUT`, `NETWORK_ERROR`, `DOWNLOAD_FAILED`, `QUEUE_FULL`, `LOGGER_CLOSED`, `LOGGER_BUSY`, `UNCERTAIN_BATCH`. API error codes are preserved.
+
+Non-JSON-serializable input raises `ValueError`. File opening and local disk failures use normal Python filesystem errors. Async cancellation remains `asyncio.CancelledError`. An uncertain write may already have succeeded. Check its state before repeating it.