Add core of the new API design

[scotttrinh]

This begins the clean-room vercel.stable API redesign: a lazy root client now owns transport and lifecycle, and service clients become thin views over that shared runtime instead of each service building its own HTTP/auth stack.

In this slice, the stable root surface lands with SDK (projects, deployments) and cache clients, plus shared stable errors/options/pagination. The generic RequestClient is reduced to transport concerns only, while SDK and cache-specific request policy moves into stable internal clients. Sync and async stay aligned by sharing the same internal backend shape and transport lineage, with tests focused on lazy env resolution, transport reuse, option overlays, and stable error behavior.

Reviewer notes

Focus on whether the new ownership boundary is right:

• root client owns lazy transport initialization and shutdown
• derived clients reuse that transport but get isolated request state for with_options() overlays
• service-specific auth/config/error handling now lives above the generic HTTP layer

Edits

• Decided to remove the cache refactor until I have a better understanding of how the python runtime use of the context ContextVar.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vercel-py	Ready	Preview	Mar 13, 2026 8:54pm

[Copilot]

Pull request overview

This PR introduces the first “clean-room” vercel.stable client surface, centered on a lazy root client that owns transport lifecycle and exposes thin, option-overlayable service clients (SDK + cache), with shared stable options/errors/pagination utilities and accompanying tests.

Changes:

• Add stable root clients (SyncVercel / AsyncVercel) with lazy, shared runtime/transport and derived SDK/cache clients that support with_options() overlays via isolated request state.
• Add stable SDK surfaces for projects and deployments, plus stable cache clients and internal request backends (sync/async aligned).
• Refactor generic RequestClient to be transport-focused (no token/env resolution), moving bearer setup into client factories and stable-layer request clients; add extensive unit/integration + property-based tests.

Reviewed changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/test_request_client.py	Updates tests to reflect RequestClient no longer auto-injects auth; verifies header behavior and compatibility token accessor.
tests/unit/stable/test_root_client.py	Tests lazy env access and thread-safe single runtime initialization; adds property test for mapping merge.
tests/unit/stable/test_projects_client.py	Property-based test for snake→camel helper behavior.
tests/unit/stable/test_cache_client.py	Property-based tests for cache hashing and key transformation.
tests/unit/stable/test_api_errors.py	Tests stable error parsing/mapping and stable SDK request defaults (headers, env token fallback).
tests/unit/stable/init.py	Marks stable unit test package for discovery.
tests/unit/init.py	Marks unit test package for discovery.
tests/integration/stable/test_projects_api.py	Integration tests for stable projects API surface, lazy connection behavior, and option overlays.
tests/integration/stable/test_deployments_api.py	Integration tests for stable deployments API surface including file upload and option overlays.
tests/integration/stable/test_cache_client.py	Integration tests for in-memory + remote cache behavior, overlays, lineage reuse, and closed-transport behavior (sync/async).
tests/integration/stable/init.py	Marks stable integration test package for discovery.
tests/integration/init.py	Marks integration test package for discovery.
tests/init.py	Marks test package for stable submodule collection.
src/vercel/stable/sdk/projects.py	Public stable Projects client + models + pagination helpers (sync/async).
src/vercel/stable/sdk/deployments.py	Public stable Deployments client + models (sync/async).
src/vercel/stable/sdk/client.py	Public stable SDK wrapper (SyncSdk/AsyncSdk) with with_options() overlays and service accessors.
src/vercel/stable/sdk/init.py	Stable SDK public exports.
src/vercel/stable/sandbox/client.py	Placeholder stable sandbox clients with with_options().
src/vercel/stable/sandbox/init.py	Stable sandbox exports.
src/vercel/stable/queues/init.py	Placeholder stable queues package.
src/vercel/stable/pagination.py	Public pagination wrappers (Page, Paginator, AsyncPaginator).
src/vercel/stable/options.py	Public immutable option dataclasses for stable surface.
src/vercel/stable/errors.py	Public stable error types (API response errors + transport closed).
src/vercel/stable/client.py	Public stable root clients (SyncVercel/AsyncVercel) + create_sync_client/create_async_client.
src/vercel/stable/cache/client.py	Public stable cache clients with overlays and backend wiring.
src/vercel/stable/cache/init.py	Stable cache exports.
src/vercel/stable/blob/client.py	Placeholder stable blob clients with with_options().
src/vercel/stable/blob/init.py	Stable blob exports.
src/vercel/stable/init.py	Stable top-level exports.
src/vercel/_internal/stable/sdk/request_client.py	Internal stable SDK request client: builds auth/headers/params, lazy transport acquisition, error extraction.
src/vercel/_internal/stable/sdk/projects.py	Internal async-shaped Projects backend (request building + parsing).
src/vercel/_internal/stable/sdk/deployments.py	Internal async-shaped Deployments backend (params/body mapping + parsing).
src/vercel/_internal/stable/sdk/init.py	Internal stable SDK exports.
src/vercel/_internal/stable/sandbox/init.py	Internal stable sandbox placeholder.
src/vercel/_internal/stable/runtime.py	Shared lazy runtime that initializes/owns transports and enforces closed-lineage behavior.
src/vercel/_internal/stable/queues/init.py	Internal stable queues placeholder.
src/vercel/_internal/stable/pagination.py	Internal minimal (a)sync page iterators.
src/vercel/_internal/stable/options.py	Internal stable option overlay helpers (merge_mapping, dataclass merging).
src/vercel/_internal/stable/errors.py	Internal mapping from HTTP status to stable error types.
src/vercel/_internal/stable/cache/client.py	Internal stable cache implementation (in-memory store + optional remote cache request client).
src/vercel/_internal/stable/cache/init.py	Internal stable cache exports.
src/vercel/_internal/stable/blob/init.py	Internal stable blob placeholder.
src/vercel/_internal/stable/init.py	Internal stable convenience exports.
src/vercel/_internal/http/request_client.py	Refactors RequestClient to stop resolving tokens; adds bearer-token compatibility accessor.
src/vercel/_internal/http/clients.py	Moves token resolution and bearer header injection into request-client factory functions.
src/vercel/init.py	Adds top-level exports for stable root client creation.
pyproject.toml	Adds Hypothesis as a dev dependency for property-based tests.
examples/runtime_cache.py	Updates cache example to use new stable root + cache APIs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	hypothesis@​6.151.9

View full report