vercel-connect 0.1.0__tar.gz

vercel_connect-0.1.0/.gitignore

@@ -0,0 +1,130 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.benchmarks/
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+.zed/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_connect-0.1.0/LICENSE

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

vercel_connect-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: vercel-connect
+Version: 0.1.0
+Summary: Python SDK for Vercel Connect
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: pydantic<3,>=2.7.0
+Requires-Dist: vercel-internal-core<0.2.0,>=0.1.2
+Requires-Dist: vercel-oidc[verify]>=0.8.0
+Description-Content-Type: text/markdown
+
+# vercel-connect
+
+Python SDK for [Vercel Connect](https://vercel.com/docs), a credential broker for
+third-party APIs.
+
+You exchange your deployment's token for a short-lived credential for an upstream
+service. Your project never stores provider secrets, and Connect owns the OAuth
+client, PKCE, refresh, and revocation server-side.
+
+```sh
+pip install vercel-connect
+```
+
+## Usage
+
+```python
+import httpx
+from vercel.connect import ConnectAppTokenSubject, get_token
+
+token = await get_token("github/my-app", subject=ConnectAppTokenSubject())
+
+async with httpx.AsyncClient() as client:
+    await client.get(
+        "https://api.github.com/user/repos",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+```
+
+The same surface is available synchronously, with identical names and arguments:
+
+```python
+from vercel.connect.sync import ConnectAppTokenSubject, get_token
+
+token = get_token("github/my-app", subject=ConnectAppTokenSubject())
+```
+
+Use a plain `with` block and `vercel.connect.sync` together; mixing an async call
+into a sync session, or the reverse, is rejected.
+
+## Subjects
+
+Whose authority the credential carries:
+
+| Subject | Authority | Needs |
+| --- | --- | --- |
+| `ConnectAppTokenSubject()` | The integration itself | An installation |
+| `ConnectUserTokenSubject(id=...)` | One named end user | That user's consent |
+| `ConnectJwtBearerTokenSubject(sub=...)` | A user asserted by your app | Pre-established trust |
+| `ConnectTokenExchangeSubject(token=...)` | A credential you already hold | The inbound token |
+
+`app` is one shared credential per installation: simple, always available, but
+ambient authority. `user` preserves the provider's own permission model per
+person and names them in the provider's audit log, at the cost of a consent flow.
+
+Subjects are typed values rather than plain strings because three of the four
+carry their own fields, so `subject="user"` could not say *which* user:
+
+```python
+ConnectUserTokenSubject(id="u_123", issuer="https://idp.example.com")
+ConnectJwtBearerTokenSubject(sub="u_123", additional_claims={"tenant": "acme"})
+```
+
+## Value types
+
+Every type on this surface is a frozen Pydantic model, so you get validation on
+construction, autocompletion, exact `match`/`case` narrowing, `model_dump()` for
+logging, and immutability, which means a subject cannot be mutated after a
+credential has been cached against it:
+
+```python
+detail = ConnectGitHubAppInstallationAuthorizationDetail(permissions=["contents:read"])
+detail.model_dump()                    # {'org': None, 'permissions': ('contents:read',), ...}
+detail.permissions = ["admin"]         # ConnectValidationError: frozen
+```
+
+Construction is by keyword, a misspelled field is an error rather than a silently
+dropped value, and every rejection raises `ConnectValidationError`, so you never
+need to catch Pydantic's own error type. Containers of strings accept any
+container and store a tuple; a bare string is rejected rather than expanded into
+one entry per character:
+
+```python
+get_token(..., scopes="repo:read")     # ConnectValidationError, and a type error
+get_token(..., scopes=["repo:read"])   # correct
+```
+
+## Authorization as control flow
+
+The two "required" errors are not bugs, they are states with a remedy:
+
+```python
+from vercel.connect import (
+    ConnectUserTokenSubject,
+    UserAuthorizationRequiredError,
+    get_token,
+    start_authorization,
+)
+
+subject = ConnectUserTokenSubject(id=user_id)
+try:
+    token = await get_token("linear/my-app", subject=subject)
+except UserAuthorizationRequiredError:
+    authorization = await start_authorization(
+        "linear/my-app", subject=subject, return_url="https://myapp.com/cb"
+    )
+    return redirect(authorization.url)
+```
+
+A CLI or headless process has nowhere to redirect to, so it asks for a device
+code and polls. Each outcome is its own error, so the loop never inspects an
+error code:
+
+```python
+import anyio
+from vercel.connect import (
+    AuthorizationDeniedError,
+    AuthorizationExpiredError,
+    AuthorizationPendingError,
+    ConnectOptions,
+)
+
+authorization = await start_authorization(
+    "linear/my-app", subject=subject, device_code=True
+)
+print(f"Enter {authorization.device_code} at {authorization.url}")
+
+while True:
+    try:
+        token = await get_token(
+            "linear/my-app", subject=subject, options=ConnectOptions(force_refresh=True)
+        )
+        break
+    except AuthorizationPendingError:
+        await anyio.sleep(5)
+    except (AuthorizationDeniedError, AuthorizationExpiredError):
+        raise  # terminal: nothing to wait for
+```
+
+`force_refresh=True` is what makes the poll reach the server; without it a cached
+credential would be returned. `slow_down` is reported as
+`AuthorizationPendingError` too, so a fixed interval stays correct.
+
+## Inbound triggers
+
+A connector with triggers enabled forwards provider webhooks to your project with
+a Vercel OIDC token attached, so you verify one thing instead of a different
+signature scheme per provider:
+
+```python
+from vercel.connect import verify_connect_webhook
+
+claims = await verify_connect_webhook(request.headers)
+```
+
+Verification pins the issuer to Vercel's OIDC service, accepting both
+`https://oidc.vercel.com` and the team-scoped `https://oidc.vercel.com/<team>`,
+allows only RS256, and fails closed when the expected project and environment cannot be resolved. It
+accepts any valid Vercel OIDC token for this project and environment; it is not
+pinned to a specific connector or deployment.
+
+## Configuration
+
+To configure advanced options, use a `session` context manager, and pass
+`ConnectServiceOptions`:
+
+```python
+from vercel.api import session
+from vercel.connect import ConnectAppTokenSubject, ConnectServiceOptions, get_token
+
+async with session(
+    service_options=[ConnectServiceOptions(base_url="https://staging.example.com")]
+):
+    token = await get_token("github/my-app", subject=ConnectAppTokenSubject())
+```
+
+## Local development
+
+On Vercel the OIDC token is injected automatically. Locally:
+
+```sh
+vercel link
+vercel env pull    # writes VERCEL_OIDC_TOKEN into .env.local
+```
+
+The connector must be attached to your project and enabled for the target
+environment, or every call fails.

vercel_connect-0.1.0/README.md

@@ -0,0 +1,186 @@
+# vercel-connect
+
+Python SDK for [Vercel Connect](https://vercel.com/docs), a credential broker for
+third-party APIs.
+
+You exchange your deployment's token for a short-lived credential for an upstream
+service. Your project never stores provider secrets, and Connect owns the OAuth
+client, PKCE, refresh, and revocation server-side.
+
+```sh
+pip install vercel-connect
+```
+
+## Usage
+
+```python
+import httpx
+from vercel.connect import ConnectAppTokenSubject, get_token
+
+token = await get_token("github/my-app", subject=ConnectAppTokenSubject())
+
+async with httpx.AsyncClient() as client:
+    await client.get(
+        "https://api.github.com/user/repos",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+```
+
+The same surface is available synchronously, with identical names and arguments:
+
+```python
+from vercel.connect.sync import ConnectAppTokenSubject, get_token
+
+token = get_token("github/my-app", subject=ConnectAppTokenSubject())
+```
+
+Use a plain `with` block and `vercel.connect.sync` together; mixing an async call
+into a sync session, or the reverse, is rejected.
+
+## Subjects
+
+Whose authority the credential carries:
+
+| Subject | Authority | Needs |
+| --- | --- | --- |
+| `ConnectAppTokenSubject()` | The integration itself | An installation |
+| `ConnectUserTokenSubject(id=...)` | One named end user | That user's consent |
+| `ConnectJwtBearerTokenSubject(sub=...)` | A user asserted by your app | Pre-established trust |
+| `ConnectTokenExchangeSubject(token=...)` | A credential you already hold | The inbound token |
+
+`app` is one shared credential per installation: simple, always available, but
+ambient authority. `user` preserves the provider's own permission model per
+person and names them in the provider's audit log, at the cost of a consent flow.
+
+Subjects are typed values rather than plain strings because three of the four
+carry their own fields, so `subject="user"` could not say *which* user:
+
+```python
+ConnectUserTokenSubject(id="u_123", issuer="https://idp.example.com")
+ConnectJwtBearerTokenSubject(sub="u_123", additional_claims={"tenant": "acme"})
+```
+
+## Value types
+
+Every type on this surface is a frozen Pydantic model, so you get validation on
+construction, autocompletion, exact `match`/`case` narrowing, `model_dump()` for
+logging, and immutability, which means a subject cannot be mutated after a
+credential has been cached against it:
+
+```python
+detail = ConnectGitHubAppInstallationAuthorizationDetail(permissions=["contents:read"])
+detail.model_dump()                    # {'org': None, 'permissions': ('contents:read',), ...}
+detail.permissions = ["admin"]         # ConnectValidationError: frozen
+```
+
+Construction is by keyword, a misspelled field is an error rather than a silently
+dropped value, and every rejection raises `ConnectValidationError`, so you never
+need to catch Pydantic's own error type. Containers of strings accept any
+container and store a tuple; a bare string is rejected rather than expanded into
+one entry per character:
+
+```python
+get_token(..., scopes="repo:read")     # ConnectValidationError, and a type error
+get_token(..., scopes=["repo:read"])   # correct
+```
+
+## Authorization as control flow
+
+The two "required" errors are not bugs, they are states with a remedy:
+
+```python
+from vercel.connect import (
+    ConnectUserTokenSubject,
+    UserAuthorizationRequiredError,
+    get_token,
+    start_authorization,
+)
+
+subject = ConnectUserTokenSubject(id=user_id)
+try:
+    token = await get_token("linear/my-app", subject=subject)
+except UserAuthorizationRequiredError:
+    authorization = await start_authorization(
+        "linear/my-app", subject=subject, return_url="https://myapp.com/cb"
+    )
+    return redirect(authorization.url)
+```
+
+A CLI or headless process has nowhere to redirect to, so it asks for a device
+code and polls. Each outcome is its own error, so the loop never inspects an
+error code:
+
+```python
+import anyio
+from vercel.connect import (
+    AuthorizationDeniedError,
+    AuthorizationExpiredError,
+    AuthorizationPendingError,
+    ConnectOptions,
+)
+
+authorization = await start_authorization(
+    "linear/my-app", subject=subject, device_code=True
+)
+print(f"Enter {authorization.device_code} at {authorization.url}")
+
+while True:
+    try:
+        token = await get_token(
+            "linear/my-app", subject=subject, options=ConnectOptions(force_refresh=True)
+        )
+        break
+    except AuthorizationPendingError:
+        await anyio.sleep(5)
+    except (AuthorizationDeniedError, AuthorizationExpiredError):
+        raise  # terminal: nothing to wait for
+```
+
+`force_refresh=True` is what makes the poll reach the server; without it a cached
+credential would be returned. `slow_down` is reported as
+`AuthorizationPendingError` too, so a fixed interval stays correct.
+
+## Inbound triggers
+
+A connector with triggers enabled forwards provider webhooks to your project with
+a Vercel OIDC token attached, so you verify one thing instead of a different
+signature scheme per provider:
+
+```python
+from vercel.connect import verify_connect_webhook
+
+claims = await verify_connect_webhook(request.headers)
+```
+
+Verification pins the issuer to Vercel's OIDC service, accepting both
+`https://oidc.vercel.com` and the team-scoped `https://oidc.vercel.com/<team>`,
+allows only RS256, and fails closed when the expected project and environment cannot be resolved. It
+accepts any valid Vercel OIDC token for this project and environment; it is not
+pinned to a specific connector or deployment.
+
+## Configuration
+
+To configure advanced options, use a `session` context manager, and pass
+`ConnectServiceOptions`:
+
+```python
+from vercel.api import session
+from vercel.connect import ConnectAppTokenSubject, ConnectServiceOptions, get_token
+
+async with session(
+    service_options=[ConnectServiceOptions(base_url="https://staging.example.com")]
+):
+    token = await get_token("github/my-app", subject=ConnectAppTokenSubject())
+```
+
+## Local development
+
+On Vercel the OIDC token is injected automatically. Locally:
+
+```sh
+vercel link
+vercel env pull    # writes VERCEL_OIDC_TOKEN into .env.local
+```
+
+The connector must be attached to your project and enabled for the target
+environment, or every call fails.

vercel_connect-0.1.0/_vercel_hatch_build.py

@@ -0,0 +1,151 @@
+"""Hatch metadata hook for publish-time workspace dependency bounds."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+class WorkspaceDependenciesMetadataHook(MetadataHookInterface):
+    """Generate package dependencies from the repo-owned dependency table."""
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        """Populate dynamic dependencies for Hatchling metadata generation."""
+        pyproject = _load_pyproject(Path(self.root))
+        release = pyproject.get("tool", {}).get("vercel", {}).get("release", {})
+        dependency_table = release.get("dependencies", {})
+        workspace_sources = pyproject.get("tool", {}).get("uv", {}).get("sources", {})
+        workspace_names = {
+            name for name, source in workspace_sources.items() if source.get("workspace") is True
+        }
+        workspace_root = _find_workspace_root(Path(self.root))
+
+        package = pyproject.get("project", {}).get("name", str(self.root))
+
+        metadata["dependencies"] = [
+            _rewrite_dependency(requirement, workspace_names, workspace_root, package)
+            for requirement in dependency_table.get("dependencies", [])
+        ]
+
+
+def _load_pyproject(path: Path) -> dict[str, Any]:
+    with (path / "pyproject.toml").open("rb") as fp:
+        return tomllib.load(fp)
+
+
+def _find_workspace_root(start: Path) -> Path | None:
+    for path in [start, *start.parents]:
+        pyproject = path / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+        data = _load_pyproject(path)
+        if "workspace" in data.get("tool", {}).get("uv", {}):
+            return path
+    return None
+
+
+def _rewrite_dependency(
+    requirement: str,
+    workspace_names: set[str],
+    workspace_root: Path | None,
+    package: str,
+) -> str:
+    parsed = Requirement(requirement)
+    normalized = parsed.name.lower().replace("_", "-")
+    if normalized not in workspace_names or workspace_root is None:
+        return requirement
+    version = _read_workspace_version(workspace_root, normalized)
+    return _with_lower_bound(parsed, version, requirement, package)
+
+
+def _with_lower_bound(requirement: Requirement, version: str, declared: str, package: str) -> str:
+    extras = f"[{','.join(sorted(requirement.extras))}]" if requirement.extras else ""
+    specifiers = [
+        str(specifier) for specifier in requirement.specifier if specifier.operator != ">="
+    ]
+    specifier_text = ",".join([f">={version}", *specifiers])
+    _reject_unsatisfiable(package, requirement.name, declared, specifier_text, version)
+    marker = f" ; {requirement.marker}" if requirement.marker else ""
+    return f"{requirement.name}{extras}{specifier_text}{marker}"
+
+
+def _reject_unsatisfiable(
+    package: str, dependency: str, declared: str, specifier_text: str, version: str
+) -> None:
+    """Refuse to publish a bound that no version of *dependency* can satisfy.
+
+    The lower bound is generated from the sibling's current version while the
+    rest of the specifier is whatever the package declared, so a hand-written
+    upper bound that the sibling has since reached produces something like
+    ``>=0.3.0,<0.3.0``. Nothing rejects that later: the wheel builds, uploads,
+    and only fails when someone tries to install it. Fail the build instead --
+    CI builds every package, so the bump that crosses the bound is caught by
+    its own pull request.
+
+    The test is that the sibling version *being released* satisfies the bound,
+    which is narrower than the range being non-empty: `>=0.7.1,!=0.7.1` leaves
+    room for a later version, but says the release under way is unusable.
+    """
+    # `prereleases=True` so a workspace version like `0.4.0b1` is judged
+    # against its own bound rather than excluded for being a prerelease.
+    if SpecifierSet(specifier_text).contains(version, prereleases=True):
+        return
+    raise RuntimeError(
+        f"{package} declares {declared!r}, but {dependency} is at {version} in "
+        f"the workspace, so publishing would pin {dependency}{specifier_text} — "
+        f"which excludes {version} itself, the version being released. "
+        f"Raise the upper bound in [tool.vercel.release.dependencies] of {package}."
+    )
+
+
+def _read_workspace_version(workspace_root: Path, package_name: str) -> str:
+    for pattern in ("src/*/pyproject.toml", "integrations/*/pyproject.toml"):
+        for pyproject_path in workspace_root.glob(pattern):
+            version = _version_from_pyproject(pyproject_path, package_name)
+            if version is not None:
+                return version
+    raise RuntimeError(f"unknown workspace dependency {package_name!r}")
+
+
+def _version_from_pyproject(pyproject_path: Path, package_name: str) -> str | None:
+    data = _load_pyproject(pyproject_path.parent)
+    if data.get("project", {}).get("name") != package_name:
+        return None
+    version_path = pyproject_path.parent / data["tool"]["hatch"]["version"]["path"]
+    module = ast.parse(version_path.read_text(encoding="utf-8"), filename=str(version_path))
+    for node in module.body:
+        value = _version_value(node)
+        if value is None:
+            continue
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            return value.value
+    raise RuntimeError(f"could not find __version__ in {version_path}")
+
+
+def _version_value(node: ast.stmt) -> ast.expr | None:
+    if isinstance(node, ast.Assign) and any(
+        isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets
+    ):
+        return node.value
+    if (
+        isinstance(node, ast.AnnAssign)
+        and isinstance(node.target, ast.Name)
+        and node.target.id == "__version__"
+    ):
+        return node.value
+    return None
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the hook class used by Hatchling's custom hook loader."""
+    return WorkspaceDependenciesMetadataHook