021-python-clients 0.1.0__tar.gz → 0.2.0__tar.gz

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes are recorded here by release-please from Conventional Commits.
 
+## [0.2.0](https://github.com/from021-io/python-clients/compare/v0.1.0...v0.2.0) (2026-10-21)
+
+
+### Features
+
+* **storage:** add observed Vercel Blob client ([9850d03](https://github.com/from021-io/python-clients/commit/9850d0381eed264c5d2962dec1340eb110621480))
+* **storage:** add observed Vercel Blob client ([2cd982d](https://github.com/from021-io/python-clients/commit/2cd982d79b5ebe7e3c5f473c41403803f2803a72))
+* **storage:** add observed Vercel Blob client ([#7](https://github.com/from021-io/python-clients/issues/7)) ([9850d03](https://github.com/from021-io/python-clients/commit/9850d0381eed264c5d2962dec1340eb110621480))
+
+
+### Refactors
+
+* **clients:** group providers by capability ([56d4d89](https://github.com/from021-io/python-clients/commit/56d4d89ac69f757a059fed5d19a636a16ce417ed))
+* **clients:** group providers by capability ([3bac4c1](https://github.com/from021-io/python-clients/commit/3bac4c14cf1c9b7157e1dec42c6a827d0fc46890))
+* **clients:** group providers by capability ([#6](https://github.com/from021-io/python-clients/issues/6)) ([56d4d89](https://github.com/from021-io/python-clients/commit/56d4d89ac69f757a059fed5d19a636a16ce417ed))
+
+## [Unreleased]
+
+### Added
+
+- Add an optional Vercel Blob client with observed CRUD, explicit public/private access, bounded operations and SDK-native metadata/errors.
+
+### Changed
+
+- Group Redis, S3 and KMS under cache, storage and crypto, retaining the 0.1.0 imports as compatibility aliases.
+
 ## 0.1.0 (2026-10-21)
 
 

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/CONTRACT.md

@@ -8,13 +8,19 @@ semantics below is a breaking change.
 Queue providers live in `clients_021.queue.sqs` (`SqsClient`, `ReceivedMessage`) and
 `clients_021.queue.qstash` (`QStashClient`, `PublishedMessage`, `QStashResponseError`).
 Use these imports in place of the initial draft's root-level `clients_021.sqs` and
-`clients_021.qstash` paths. This organization is part of the first unreleased API.
+`clients_021.qstash` paths. These capability paths shipped in 0.1.0.
 Importing `clients_021.queue` or its QStash module does not require the `aws` extra.
 
 The queue package groups providers by purpose. SQS owns polling, receipts and visibility;
 QStash owns HTTP delivery. Their public methods and observability contracts remain distinct.
 Shared email types and the interchangeable `EmailSender` protocol live in `clients_021.email`.
 
+Redis lives in `clients_021.cache.redis`, S3 in `clients_021.storage.s3` and KMS in
+`clients_021.crypto.kms`. The 0.1.0 root modules (`redis`, `s3`, `kms`) continue to re-export
+the same clients and result types (`ObjectInfo`, `DataKey`). Existing call signatures,
+metric/span names and error semantics are unchanged. Capability package imports do not
+load optional SDKs. HTTP transports remain in `clients_021.http` and `clients_021.httpx2`.
+
 ## Metrics
 
 All on the service's `Observability` meter, so they carry its resource (service name,
@@ -26,8 +32,8 @@ version, environment). Durations use 021-python-observability's buckets.
 | `db.client.operation.duration` | Histogram / `s` | same | Redis |
 | `messaging.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | SQS, QStash, email (Resend, SES) |
 | `messaging.client.operation.duration` | Histogram / `s` | same | SQS, QStash, email (Resend, SES) |
-| `storage.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | S3 |
-| `storage.client.operation.duration` | Histogram / `s` | same | S3 |
+| `storage.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | S3, Vercel Blob |
+| `storage.client.operation.duration` | Histogram / `s` | same | S3, Vercel Blob |
 | `crypto.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | KMS |
 | `crypto.client.operation.duration` | Histogram / `s` | same | KMS |
 | `http.client.request.count` | Counter / `{request}` | dependency, http.request.method, http.response.status_code, error.type | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
@@ -36,10 +42,11 @@ version, environment). Durations use 021-python-observability's buckets.
 - `status`: `ok` or `error`. `error.type` only on errors.
 - `operation`: a fixed set per client. Redis: `get_json`, `set_json`, `take_json`,
   `delete`, `incr_window`, `ping`. SQS: `send`, `receive`, `delete`, `change_visibility`.
-  S3: `put`, `get`, `head`, `delete`. QStash: `publish`. Email (Resend, SES): `send`. KMS:
+  S3 and Vercel Blob: `put`, `get`, `head`, `delete`. QStash: `publish`.
+  Email (Resend, SES): `send`. KMS:
   `encrypt`, `decrypt`, `generate_data_key`; `seal` and `unseal` record the KMS call they make
   (`generate_data_key`, `decrypt`), not the local AES work.
-- Redis/SQS/S3/QStash/email/KMS `error.type`: `timeout`, `connection_error`, `throttled`,
+- Redis/SQS/S3/Vercel Blob/QStash/email/KMS `error.type`: `timeout`, `connection_error`, `throttled`,
   `status_<5xx>`, `cancelled`, or the exception class name for errors that are not outages
   (`EmailRejected` for every email rejection; botocore's class, such as `ClientError` or
   `NotFoundException`, for KMS).
@@ -50,7 +57,7 @@ version, environment). Durations use 021-python-observability's buckets.
   `DependencyUnavailable.reason` describes the failure returned to the caller.
 - httpx2 uses `timeout`, `connection_error`, `cancelled`, or the exception class name.
   HTTP status errors set the span's ERROR status and status-code label, with no `error.type`.
-- A missing S3 object or Redis key is `status=ok`.
+- A missing S3/Blob object or Redis key is `status=ok`.
 - `dependency` is a static identifier, validated consistently with 021-python-observability.
   User ids, tenant ids and request-derived values are forbidden even if they match its syntax.
 
@@ -59,8 +66,8 @@ version, environment). Durations use 021-python-observability's buckets.
 CLIENT spans named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
 metric labels plus `db.system.name=redis`, `messaging.system=aws_sqs`,
 `messaging.system=upstash_qstash`, `messaging.system=resend`, `messaging.system=aws_ses`, or
-`rpc.system=aws-api` + `rpc.service=S3` / `rpc.service=KMS`. Resend's `HTTP <dependency>`
-span is a child of its `<dependency> send` span. Status ERROR on failure (and on HTTP
+`rpc.system=aws-api` + `rpc.service=S3` / `rpc.service=KMS`, or `rpc.system=vercel-blob`.
+Resend's `HTTP <dependency>` span is a child of its `<dependency> send` span. Status ERROR on failure (and on HTTP
 status ≥ 400).
 Cancellation propagates unchanged and records ERROR with `error.type=cancelled`.
 HTTP transports measure through response headers; they do not measure body consumption.
@@ -78,7 +85,7 @@ Local input validation occurs before either operation is recorded.
   When enabled, both caller-supplied trace headers are replaced with the current context.
 - Resend: nothing is sent. The `traceparent`, `tracestate` and `x-request-id` headers that
   021-python-observability's transport adds are removed before the request leaves.
-- SES and KMS: nothing is sent.
+- SES, KMS and Vercel Blob: nothing is sent by the default transports.
 - SQS: `traceparent` and `tracestate` are message attributes; `ReceivedMessage.trace_context()`
   returns the producer's context. Caller-supplied values for both trace attributes are
   replaced with the current context.
@@ -127,6 +134,16 @@ tampered ciphertext (`InvalidCiphertextException`) and a ciphertext from another
 Every call requires a non-empty encryption context. `unseal` raises `ValueError` for a
 malformed envelope and `cryptography.exceptions.InvalidTag` when the payload was altered.
 
+Vercel Blob (`clients_021.storage.vercel_blob`): HTTP 429 maps to `throttled`; 5xx to
+`status_<code>`; HTTP timeouts and total deadlines to `timeout`; network/remote protocol
+failures to `connection_error`. Known transport causes wrapped by the SDK are classified
+without inspecting provider messages. Other errors retain their SDK type, including
+`BlobAccessError`, `BlobStoreNotFoundError`, `BlobPreconditionFailedError`, and
+`BlobStreamError` for malformed acknowledgements. Only `BlobNotFoundError` becomes `None`
+for `get`/`head`, counted as success. `put` returns the SDK's `PutResult` (exported as
+`BlobUpload`); `head` returns its `HeadResult` (`BlobInfo`). These types are provider-specific.
+SDK validation and credential failures can produce an error span but perform no network I/O.
+
 ## Sealed envelope format
 
 `KmsClient.seal` output is stored data, so its layout is part of this contract: version
@@ -138,7 +155,7 @@ A new data key is generated for every envelope.
 
 ## Lifecycle and retry limits
 
-HTTP, Redis, SQS, QStash, S3, Resend, SES and KMS expose `aclose()`. Close them after
+HTTP, Redis, SQS, QStash, S3, Vercel Blob, Resend, SES and KMS expose `aclose()`. Close them after
 in-flight calls complete; the wrapper owns the underlying client, including one supplied
 through the constructor.
 AWS factories configure three total attempts; injected clients retain their own policy.
@@ -155,9 +172,20 @@ publish again.
 `HttpClient.request` accepts at most one of `json`, `form` or raw byte `content`. Passing
 more than one non-None body format raises `ValueError` before sending a request.
 
+Vercel Blob uses the optional `vercel-blob>=0.5,<0.6` SDK and explicit read-write credentials,
+store ID and access mode. It owns a shared transport; each operation borrows it in a separate
+SDK session. No environment credentials or global SDK client perform requests. The total
+operation deadline defaults to 10 seconds and includes buffered downloads. Timeout and
+cancellation do not imply a remote write was undone. Neither this wrapper nor the SDK
+retries operations; an injected transport must respect this policy. Overwrite and random
+suffixes default to false. Callers decide whether a repeated write is safe. A closed client
+cannot reopen its pool. No additional HTTP metrics are emitted by this client.
+
 ## Never recorded
 
 Keys, URLs, query strings, bodies, message ids, receipts, object names, bucket or queue
 names, provider error messages. Email: sender, recipient and reply-to addresses, subjects,
 text and HTML bodies, tags, idempotency keys, API keys, configuration set names. KMS: key
 ids, ARNs and aliases, encryption contexts, plaintext, ciphertext and data keys.
+
+Vercel Blob: read-write tokens, store IDs, pathnames, delivery URLs, content and ETags.

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/CONTRIBUTING.md

@@ -7,25 +7,30 @@ not need to be reimplemented here.
 
 ## Layout and public API
 
-Group providers by capability when more than one serves the same purpose, with a module
-per provider inside that package. Keep standalone clients at the root until a second
-provider makes grouping useful. Tests stay in `tests/test_<provider>.py`.
+Group domain clients by capability, with a module per provider even when the package
+currently has one provider. HTTP transports are cross-cutting infrastructure and stay at
+the root. Tests stay in `tests/test_<provider>.py`.
 
 ```text
 clients_021/
   email/          # _message.py (shared protocol/types), resend.py, ses.py
   queue/          # sqs.py, qstash.py
   http.py
-  redis.py
-  s3.py
-  kms.py
+  httpx2.py
+  cache/          # redis.py
+  storage/        # s3.py, vercel_blob.py
+  crypto/         # kms.py
 ```
 
+The original `clients_021.redis`, `clients_021.s3` and `clients_021.kms` imports remain
+compatibility re-exports of the same classes and result types. New code uses the capability
+paths. Do not remove compatibility modules without a breaking release.
+
 Public result and exception types live beside their provider unless they are truly shared.
 A common protocol requires interchangeable operations and semantics: `EmailSender.send`
 qualifies. SQS polling/receipts and QStash HTTP delivery do not share a consumer API, so
-`queue/` groups them without inventing one. Provider imports are explicit, and importing
-the capability package must not load optional SDKs.
+`queue/` groups them without inventing one. S3 and Blob also keep provider-specific metadata
+and write options. Provider imports are explicit, and importing the capability package must not load optional SDKs.
 
 Use private helpers for actual shared behavior: `_observe.py` owns instrumentation and
 `_aws.py` owns AWS configuration and error classification. Avoid a universal base class:

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: 021-python-clients
-Version: 0.1.0
-Summary: Observed clients for Redis, SQS, QStash, S3, HTTP, email and KMS, built on 021-python-observability
+Version: 0.2.0
+Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability
 Project-URL: Repository, https://github.com/from021-io/python-clients
 Project-URL: Changelog, https://github.com/from021-io/python-clients/blob/main/CHANGELOG.md
 Project-URL: Contract, https://github.com/from021-io/python-clients/blob/main/CONTRACT.md
@@ -29,6 +29,9 @@ Provides-Extra: httpx2
 Requires-Dist: httpx2<3,>=2; extra == 'httpx2'
 Provides-Extra: redis
 Requires-Dist: redis<9,>=6; extra == 'redis'
+Provides-Extra: vercel-blob
+Requires-Dist: httpx2<3,>=2; extra == 'vercel-blob'
+Requires-Dist: vercel-blob<0.6,>=0.5; extra == 'vercel-blob'
 Description-Content-Type: text/markdown
 
 # 021-python-clients
@@ -40,20 +43,21 @@ dependency call gets the same span, the same metrics under a stable dependency n
 the same failure type.
 
 ```bash
-uv add "021-python-clients[redis,aws,httpx2]"   # pick the extras you use
+uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras you use
 ```
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
 | `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
 | `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
-| `clients_021.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
+| `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
-| `clients_021.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.vercel_blob` | `vercel-blob` | `VercelBlobClient`: put, get, head and conditional delete for public/private stores |
 | `clients_021.email` | none | `EmailMessage`, the `EmailSender` protocol, `ResendSender` (Resend's HTTP API) |
 | `clients_021.email.ses` | `aws` | `SesSender`: the same protocol over Amazon SES v2 |
-| `clients_021.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
+| `clients_021.crypto.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
 
 Every client takes the service's `Observability` (from `setup_observability`) and a
 `dependency` name, which becomes the `dependency` label of its metrics.
@@ -61,11 +65,16 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 ## Organization
 
 Providers with the same purpose live under one capability package: `email/` contains
-Resend and SES; `queue/` contains SQS and QStash. Import queue clients explicitly:
+Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
+contains Redis; `crypto/` contains KMS. HTTP transports remain at the root. Import providers
+explicitly:
 
 ```python
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
+from clients_021.storage.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.crypto.kms import KmsClient
 ```
 
 SQS supports polling, receipts and visibility changes; QStash delivers to an HTTP endpoint.
@@ -74,16 +83,20 @@ because both implement the same send operation. A shared package does not imply
 provider implements an interchangeable consumption protocol. Importing `queue` or QStash
 does not load the optional AWS SDK.
 
+The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
+compatible aliases for the same classes and result types. Importing a capability package
+does not load its optional SDKs.
+
 ## What every call gets
 
 - A CLIENT span named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
   system attribute (`db.system.name=redis`, `messaging.system=aws_sqs|resend|aws_ses`,
-  `rpc.service=S3|KMS`).
+  `rpc.service=S3|KMS`, `rpc.system=vercel-blob`).
 - A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
-  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3),
+  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3, Vercel Blob),
   `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
-- Redis, SQS, QStash, S3, email and KMS emit a `dependency.call_failed` warning on failure,
+- Redis, SQS, QStash, S3, Vercel Blob, email and KMS emit a `dependency.call_failed` warning on failure,
   with dependency, operation and error type only. HTTP transports emit spans and metrics.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
@@ -100,8 +113,8 @@ them from a tenant, user or request. All clients apply observability's identifie
 
 ```python
 from clients_021 import DependencyUnavailable, HttpClient
-from clients_021.redis import RedisClient
-from clients_021.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.storage.s3 import S3Client
 from clients_021.queue.sqs import SqsClient
 
 redis = RedisClient.from_url(obs, settings.redis_url)
@@ -123,6 +136,59 @@ http = HttpClient(obs, timeout_seconds=10)
 response = await http.request("GET", jwks_url, dependency="identity-provider")
 ```
 
+### Vercel Blob
+
+```python
+from clients_021.storage.vercel_blob import VercelBlobClient
+
+files = VercelBlobClient(
+    obs,
+    token=settings.blob_token,
+    store_id=settings.blob_store_id,
+    access="private",  # Required; must match the store. Public is also supported.
+    dependency="documents",
+    timeout_seconds=10,
+)
+try:
+    uploaded = await files.put("reports/report.pdf", pdf_bytes, content_type="application/pdf")
+    content = await files.get(uploaded.url)  # bytes, or None for a missing object
+    info = await files.head(uploaded.url)    # metadata, or None for a missing object
+    if info is not None:
+        await files.delete(uploaded.url, if_match=info.etag)
+finally:
+    await files.aclose()
+```
+
+Uses the [official Python Blob SDK](https://vercel.com/docs/vercel-blob/python-sdk-reference),
+`vercel-blob>=0.5,<0.6`, installed with the `vercel-blob` extra. This is the current functional
+SDK API; it does not depend on the earlier `AsyncBlobClient` API or the full `vercel` bundle.
+Credentials and store access are explicit; no environment or default SDK session is used
+for requests. A read-write token's store must match `store_id` (the `store_` prefix is allowed).
+
+`put` returns `BlobUpload` (the SDK's `PutResult`); `head` returns `BlobInfo` (its `HeadResult`).
+These are provider-specific types, not a common S3 protocol. Uploads require a pathname;
+reads, metadata and deletes accept a pathname or a Vercel delivery URL. The SDK validates
+those URLs and does not follow redirects. `get` buffers the entire body in memory.
+
+Each operation has one attempt and a finite total deadline, including body consumption.
+The client reuses its connection pool across calls and closes it through `aclose()`,
+including an injected `httpx2.AsyncBaseTransport`. Call `aclose()` only after in-flight calls
+finish. Calls after close fail locally. SDK sessions are scoped to each operation so
+concurrent clients keep their credentials separate. No trace headers are sent by default.
+
+`allow_overwrite=False` and `add_random_suffix=False` by default. Both can be explicitly
+enabled, along with `cache_control_max_age`. A timeout may follow a successful upload:
+retrying with a random suffix can create another object; overwriting a stable pathname can
+race with other writers. Deleting a missing object succeeds. `if_match` guards a delete
+against a changed ETag. CDN caches can retain deleted content briefly.
+
+429, 5xx, transport failures and deadlines become `DependencyUnavailable`. Authentication,
+missing stores, precondition failures, invalid inputs and malformed responses retain SDK
+exceptions; only a missing object becomes `None` for `get`/`head`. Cancellation propagates.
+The storage operation includes the complete request and response body; this client does
+not emit an additional HTTP metric. Signed URLs, multipart and streaming APIs stay outside
+this initial client.
+
 ### QStash
 
 ```python
@@ -207,7 +273,7 @@ The encryption context is required on every call, so a ciphertext only decrypts
 purpose it was made for:
 
 ```python
-from clients_021.kms import KmsClient
+from clients_021.crypto.kms import KmsClient
 
 keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
 context = {"purpose": "refresh-token", "tenant": tenant_id}
@@ -292,6 +358,8 @@ Retry policies are explicit:
   `DependencyUnavailable`; other rejected statuses and invalid acknowledgements raise
   `QStashResponseError` with a status code and no provider body. Delivery timeouts and
   delays use integer seconds and remain subject to the provider plan's limits.
+- Vercel Blob sends each operation once, with a finite total deadline (10 seconds by default).
+  An injected transport must also avoid automatic retries of uncertain writes.
 - httpx2 SDKs own their retries; `ObservedTransport` adds no extra retry loop.
 
 `DependencyUnavailable` signals a transient dependency failure, **not permission to replay

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/README.md

@@ -7,20 +7,21 @@ dependency call gets the same span, the same metrics under a stable dependency n
 the same failure type.
 
 ```bash
-uv add "021-python-clients[redis,aws,httpx2]"   # pick the extras you use
+uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras you use
 ```
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
 | `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
 | `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
-| `clients_021.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
+| `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
-| `clients_021.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.vercel_blob` | `vercel-blob` | `VercelBlobClient`: put, get, head and conditional delete for public/private stores |
 | `clients_021.email` | none | `EmailMessage`, the `EmailSender` protocol, `ResendSender` (Resend's HTTP API) |
 | `clients_021.email.ses` | `aws` | `SesSender`: the same protocol over Amazon SES v2 |
-| `clients_021.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
+| `clients_021.crypto.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
 
 Every client takes the service's `Observability` (from `setup_observability`) and a
 `dependency` name, which becomes the `dependency` label of its metrics.
@@ -28,11 +29,16 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 ## Organization
 
 Providers with the same purpose live under one capability package: `email/` contains
-Resend and SES; `queue/` contains SQS and QStash. Import queue clients explicitly:
+Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
+contains Redis; `crypto/` contains KMS. HTTP transports remain at the root. Import providers
+explicitly:
 
 ```python
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
+from clients_021.storage.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.crypto.kms import KmsClient
 ```
 
 SQS supports polling, receipts and visibility changes; QStash delivers to an HTTP endpoint.
@@ -41,16 +47,20 @@ because both implement the same send operation. A shared package does not imply
 provider implements an interchangeable consumption protocol. Importing `queue` or QStash
 does not load the optional AWS SDK.
 
+The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
+compatible aliases for the same classes and result types. Importing a capability package
+does not load its optional SDKs.
+
 ## What every call gets
 
 - A CLIENT span named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
   system attribute (`db.system.name=redis`, `messaging.system=aws_sqs|resend|aws_ses`,
-  `rpc.service=S3|KMS`).
+  `rpc.service=S3|KMS`, `rpc.system=vercel-blob`).
 - A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
-  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3),
+  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3, Vercel Blob),
   `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
-- Redis, SQS, QStash, S3, email and KMS emit a `dependency.call_failed` warning on failure,
+- Redis, SQS, QStash, S3, Vercel Blob, email and KMS emit a `dependency.call_failed` warning on failure,
   with dependency, operation and error type only. HTTP transports emit spans and metrics.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
@@ -67,8 +77,8 @@ them from a tenant, user or request. All clients apply observability's identifie
 
 ```python
 from clients_021 import DependencyUnavailable, HttpClient
-from clients_021.redis import RedisClient
-from clients_021.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.storage.s3 import S3Client
 from clients_021.queue.sqs import SqsClient
 
 redis = RedisClient.from_url(obs, settings.redis_url)
@@ -90,6 +100,59 @@ http = HttpClient(obs, timeout_seconds=10)
 response = await http.request("GET", jwks_url, dependency="identity-provider")
 ```
 
+### Vercel Blob
+
+```python
+from clients_021.storage.vercel_blob import VercelBlobClient
+
+files = VercelBlobClient(
+    obs,
+    token=settings.blob_token,
+    store_id=settings.blob_store_id,
+    access="private",  # Required; must match the store. Public is also supported.
+    dependency="documents",
+    timeout_seconds=10,
+)
+try:
+    uploaded = await files.put("reports/report.pdf", pdf_bytes, content_type="application/pdf")
+    content = await files.get(uploaded.url)  # bytes, or None for a missing object
+    info = await files.head(uploaded.url)    # metadata, or None for a missing object
+    if info is not None:
+        await files.delete(uploaded.url, if_match=info.etag)
+finally:
+    await files.aclose()
+```
+
+Uses the [official Python Blob SDK](https://vercel.com/docs/vercel-blob/python-sdk-reference),
+`vercel-blob>=0.5,<0.6`, installed with the `vercel-blob` extra. This is the current functional
+SDK API; it does not depend on the earlier `AsyncBlobClient` API or the full `vercel` bundle.
+Credentials and store access are explicit; no environment or default SDK session is used
+for requests. A read-write token's store must match `store_id` (the `store_` prefix is allowed).
+
+`put` returns `BlobUpload` (the SDK's `PutResult`); `head` returns `BlobInfo` (its `HeadResult`).
+These are provider-specific types, not a common S3 protocol. Uploads require a pathname;
+reads, metadata and deletes accept a pathname or a Vercel delivery URL. The SDK validates
+those URLs and does not follow redirects. `get` buffers the entire body in memory.
+
+Each operation has one attempt and a finite total deadline, including body consumption.
+The client reuses its connection pool across calls and closes it through `aclose()`,
+including an injected `httpx2.AsyncBaseTransport`. Call `aclose()` only after in-flight calls
+finish. Calls after close fail locally. SDK sessions are scoped to each operation so
+concurrent clients keep their credentials separate. No trace headers are sent by default.
+
+`allow_overwrite=False` and `add_random_suffix=False` by default. Both can be explicitly
+enabled, along with `cache_control_max_age`. A timeout may follow a successful upload:
+retrying with a random suffix can create another object; overwriting a stable pathname can
+race with other writers. Deleting a missing object succeeds. `if_match` guards a delete
+against a changed ETag. CDN caches can retain deleted content briefly.
+
+429, 5xx, transport failures and deadlines become `DependencyUnavailable`. Authentication,
+missing stores, precondition failures, invalid inputs and malformed responses retain SDK
+exceptions; only a missing object becomes `None` for `get`/`head`. Cancellation propagates.
+The storage operation includes the complete request and response body; this client does
+not emit an additional HTTP metric. Signed URLs, multipart and streaming APIs stay outside
+this initial client.
+
 ### QStash
 
 ```python
@@ -174,7 +237,7 @@ The encryption context is required on every call, so a ciphertext only decrypts
 purpose it was made for:
 
 ```python
-from clients_021.kms import KmsClient
+from clients_021.crypto.kms import KmsClient
 
 keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
 context = {"purpose": "refresh-token", "tenant": tenant_id}
@@ -259,6 +322,8 @@ Retry policies are explicit:
   `DependencyUnavailable`; other rejected statuses and invalid acknowledgements raise
   `QStashResponseError` with a status code and no provider body. Delivery timeouts and
   delays use integer seconds and remain subject to the provider plan's limits.
+- Vercel Blob sends each operation once, with a finite total deadline (10 seconds by default).
+  An injected transport must also avoid automatic retries of uncertain writes.
 - httpx2 SDKs own their retries; `ObservedTransport` adds no extra retry loop.
 
 `DependencyUnavailable` signals a transient dependency failure, **not permission to replay

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "021-python-clients"
-version = "0.1.0"
-description = "Observed clients for Redis, SQS, QStash, S3, HTTP, email and KMS, built on 021-python-observability"
+version = "0.2.0"
+description = "Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
@@ -34,6 +34,10 @@ redis = ["redis>=6,<9"]
 # cryptography is for KmsClient.seal / unseal (AES-256-GCM envelopes).
 aws = ["boto3>=1.40,<2", "cryptography>=44"]
 httpx2 = ["httpx2>=2,<3"]
+vercel-blob = [
+    "httpx2>=2,<3",
+    "vercel-blob>=0.5,<0.6",
+]
 
 [project.urls]
 Repository = "https://github.com/from021-io/python-clients"

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/src/clients_021/__init__.py

@@ -1,9 +1,10 @@
 """Observed clients for the external services Python services call.
 
 `clients_021.http`, `clients_021.queue.qstash` and `clients_021.email` (Resend) need no extras;
-`clients_021.redis` needs the `redis` extra; `clients_021.queue.sqs`, `clients_021.s3`,
-`clients_021.email.ses` and `clients_021.kms` the `aws` extra; `clients_021.httpx2` the
-`httpx2` extra.
+`clients_021.cache.redis` needs the `redis` extra; `clients_021.queue.sqs`,
+`clients_021.storage.s3`, `clients_021.email.ses` and `clients_021.crypto.kms` the `aws` extra;
+`clients_021.httpx2` the `httpx2` extra.
+`clients_021.storage.vercel_blob` needs the `vercel-blob` extra.
 """
 
 from importlib.metadata import version

{021_python_clients-0.1.0 → 021_python_clients-0.2.0}/src/clients_021/_observe.py

@@ -2,7 +2,7 @@
 
 The `db` family reuses the instruments 021-python-observability already creates for SQL
 (`db.client.operation.*`), so Redis and Postgres share dashboards. `messaging` (SQS, email),
-`storage` (S3) and `crypto` (KMS) get their own pair on the same meter. Attributes are
+`storage` (S3, Vercel Blob) and `crypto` (KMS) get their own pair on the same meter. Attributes are
 bounded: dependency, operation, status and error.type; never keys, URLs, bodies or ids.
 """
 

021_python_clients-0.2.0/src/clients_021/cache/__init__.py

@@ -0,0 +1 @@
+"""Cache clients. Import providers explicitly; SDKs are optional extras."""

{021_python_clients-0.1.0/src/clients_021 → 021_python_clients-0.2.0/src/clients_021/cache}/redis.py

@@ -1,6 +1,6 @@
 """Redis, observed: JSON values with a TTL, one-time reads, windowed counters and a ping.
 
-    from clients_021.redis import RedisClient
+    from clients_021.cache.redis import RedisClient
 
     redis = RedisClient.from_url(obs, settings.redis_url, dependency="redis")
     await redis.set_json("session:abc", {"user": "ana"}, ttl_seconds=1800)

021_python_clients-0.2.0/src/clients_021/crypto/__init__.py

@@ -0,0 +1 @@
+"""Crypto clients. Import providers explicitly; SDKs are optional extras."""

{021_python_clients-0.1.0/src/clients_021 → 021_python_clients-0.2.0/src/clients_021/crypto}/kms.py

@@ -1,6 +1,6 @@
 """AWS KMS, observed: encrypt, decrypt and data keys, always bound to an encryption context.
 
-    from clients_021.kms import KmsClient
+    from clients_021.crypto.kms import KmsClient
 
     keys = KmsClient.create(obs, settings.session_key_id, region="us-east-1")
     context = {"purpose": "session", "tenant": tenant_id}

021_python_clients-0.2.0/src/clients_021/kms.py

@@ -0,0 +1,5 @@
+"""Compatibility imports for 0.1.0; prefer ``clients_021.crypto.kms``."""
+
+from clients_021.crypto.kms import SYSTEM, DataKey, KmsClient
+
+__all__ = ["KmsClient", "DataKey", "SYSTEM"]

021_python_clients-0.2.0/src/clients_021/redis.py

@@ -0,0 +1,5 @@
+"""Compatibility imports for 0.1.0; prefer ``clients_021.cache.redis``."""
+
+from clients_021.cache.redis import SYSTEM, RedisClient
+
+__all__ = ["RedisClient", "SYSTEM"]

021_python_clients-0.2.0/src/clients_021/s3.py

@@ -0,0 +1,5 @@
+"""Compatibility imports for 0.1.0; prefer ``clients_021.storage.s3``."""
+
+from clients_021.storage.s3 import MAX_PRESIGN_SECONDS, SYSTEM, ObjectInfo, S3Client
+
+__all__ = ["S3Client", "ObjectInfo", "MAX_PRESIGN_SECONDS", "SYSTEM"]

021_python_clients-0.2.0/src/clients_021/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage clients. Import providers explicitly; SDKs are optional extras."""

{021_python_clients-0.1.0/src/clients_021 → 021_python_clients-0.2.0/src/clients_021/storage}/s3.py

@@ -1,6 +1,6 @@
 """S3 (or any S3-compatible store), observed: put, get, head, delete and presigned URLs.
 
-    from clients_021.s3 import S3Client
+    from clients_021.storage.s3 import S3Client
 
     files = S3Client.create(obs, bucket="service-uploads", region="us-east-1")
     await files.put("reports/2026-10.pdf", data, content_type="application/pdf")