onepin 0.2.0__py3-none-any.whl

onepin/.fern/metadata.json

@@ -0,0 +1,14 @@
+{
+  "cliVersion": "5.38.0",
+  "generatorName": "fernapi/fern-python-sdk",
+  "generatorVersion": "latest",
+  "generatorConfig": {
+    "client_class_name": "OnePinClient",
+    "package_name": "onepin",
+    "flat_layout": false
+  },
+  "originGitCommit": "babfb180c9f10bd3e41e7f774d958819ad52e34e",
+  "originGitCommitIsDirty": false,
+  "invokedBy": "ci",
+  "ciProvider": "github"
+}

onepin/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing
+
+Thanks for your interest in contributing to this SDK! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9+
+- pip
+- poetry
+
+### Installation
+
+Install the project dependencies:
+
+```bash
+poetry install
+```
+
+### Building
+
+Build the project:
+
+```bash
+poetry build
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+poetry run pytest
+```
+
+### Linting and Formatting
+
+Check code style:
+
+```bash
+poetry run ruff check .
+poetry run ruff format .
+```
+
+### Type Checking
+
+Run the type checker:
+
+```bash
+poetry run mypy .
+```
+
+## About Generated Code
+
+**Important**: Most files in this SDK are automatically generated by [Fern](https://buildwithfern.com) from the API definition. Direct modifications to generated files will be overwritten the next time the SDK is generated.
+
+### Generated Files
+
+The following directories contain generated code:
+- `src/` - API client classes and types
+- Most Python files in the project
+
+### How to Customize
+
+If you need to customize the SDK, you have two options:
+
+#### Option 1: Use `.fernignore`
+
+For custom code that should persist across SDK regenerations:
+
+1. Create a `.fernignore` file in the project root
+2. Add file patterns for files you want to preserve (similar to `.gitignore` syntax)
+3. Add your custom code to those files
+
+Files listed in `.fernignore` will not be overwritten when the SDK is regenerated.
+
+For more information, see the [Fern documentation on custom code](https://buildwithfern.com/learn/sdks/overview/custom-code).
+
+#### Option 2: Contribute to the Generator
+
+If you want to change how code is generated for all users of this SDK:
+
+1. The Python SDK generator lives in the [Fern repository](https://github.com/fern-api/fern)
+2. Generator code is located at `generators/python-v2/`
+3. Follow the [Fern contributing guidelines](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md)
+4. Submit a pull request with your changes to the generator
+
+This approach is best for:
+- Bug fixes in generated code
+- New features that would benefit all users
+- Improvements to code generation patterns
+
+## Making Changes
+
+### Workflow
+
+1. Create a new branch for your changes
+2. Make your modifications
+3. Run tests to ensure nothing breaks: `poetry run pytest`
+4. Run linting and formatting: `poetry run ruff check .` and `poetry run ruff format .`
+5. Run type checking: `poetry run mypy .`
+6. Build the project: `poetry build`
+7. Commit your changes with a clear commit message
+8. Push your branch and create a pull request
+
+### Commit Messages
+
+Write clear, descriptive commit messages that explain what changed and why.
+
+### Code Style
+
+This project uses automated code formatting and linting. Run `poetry run ruff format .` and `poetry run ruff check .` before committing to ensure your code meets the project's style guidelines.
+
+## Questions or Issues?
+
+If you have questions or run into issues:
+
+1. Check the [Fern documentation](https://buildwithfern.com)
+2. Search existing [GitHub issues](https://github.com/fern-api/fern/issues)
+3. Open a new issue if your question hasn't been addressed
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

onepin/__init__.py

@@ -0,0 +1,48 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+import typing
+from importlib import import_module
+
+if typing.TYPE_CHECKING:
+    from ._default_clients import DefaultAioHttpClient, DefaultAsyncHttpxClient
+    from .client import AsyncOnePinClient, OnePinClient
+    from .environment import OnePinClientEnvironment
+_dynamic_imports: typing.Dict[str, str] = {
+    "AsyncOnePinClient": ".client",
+    "DefaultAioHttpClient": "._default_clients",
+    "DefaultAsyncHttpxClient": "._default_clients",
+    "OnePinClient": ".client",
+    "OnePinClientEnvironment": ".environment",
+}
+
+
+def __getattr__(attr_name: str) -> typing.Any:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"No {attr_name} found in _dynamic_imports for module name -> {__name__}")
+    try:
+        module = import_module(module_name, __package__)
+        if module_name == f".{attr_name}":
+            return module
+        else:
+            return getattr(module, attr_name)
+    except ImportError as e:
+        raise ImportError(f"Failed to import {attr_name} from {module_name}: {e}") from e
+    except AttributeError as e:
+        raise AttributeError(f"Failed to get {attr_name} from {module_name}: {e}") from e
+
+
+def __dir__():
+    lazy_attrs = list(_dynamic_imports.keys())
+    return sorted(lazy_attrs)
+
+
+__all__ = [
+    "AsyncOnePinClient",
+    "DefaultAioHttpClient",
+    "DefaultAsyncHttpxClient",
+    "OnePinClient",
+    "OnePinClientEnvironment",
+]

onepin/_cli/__init__.py

@@ -0,0 +1,13 @@
+"""OnePin CLI -- hand-rolled Typer CLI atop the Fern-generated SDK."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("onepin")
+except PackageNotFoundError:  # editable install pre-build
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

onepin/_cli/_ctx.py

@@ -0,0 +1,28 @@
+"""Build OnePinClient from resolved credentials.
+
+Pending Fern SDK regen -- raises NotImplementedError until client.py exists.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from onepin._cli.auth.resolver import ResolvedCredentials
+
+
+def build_client(creds: ResolvedCredentials) -> Any:
+    """Build and return an OnePinClient from resolved credentials.
+
+    Args:
+        creds: Resolved credentials from the priority chain.
+
+    Returns:
+        OnePinClient instance.
+
+    Raises:
+        NotImplementedError: Until the first Fern SDK regen lands.
+    """
+    raise NotImplementedError(
+        "OnePinClient is not yet available -- Fern SDK regen has not run yet. "
+        "See podonos/onepin-sdks for the Fern configuration."
+    )

onepin/_cli/_http.py

@@ -0,0 +1,126 @@
+"""Shared httpx helper for CLI auth calls.
+
+Provides a typed exception hierarchy and a single _call_whoami() function
+used by login, logout, and whoami commands.
+
+No Fern SDK dependency -- direct httpx calls only.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, Optional
+
+import httpx
+
+from onepin._cli import __version__
+
+
+class OnePinHTTPError(Exception):
+    """Base error for all HTTP-layer failures.
+
+    Attributes:
+        status_code: HTTP status code, or None for network-level errors.
+        error_code: Machine-readable error code from the response envelope.
+        message: Human-readable message.
+        request_id: Request-ID from the response meta envelope, if available.
+        response_body: Raw response body string, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_code: str = "HTTP_ERROR",
+        request_id: Optional[str] = None,
+        response_body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message
+        self.request_id = request_id
+        self.response_body = response_body
+
+
+class OnePinAuthError(OnePinHTTPError):
+    """Raised for 401 / 403 responses."""
+
+
+class OnePinNetworkError(OnePinHTTPError):
+    """Raised for connection / timeout failures (no status code)."""
+
+
+def _user_agent() -> str:
+    major = sys.version_info.major
+    minor = sys.version_info.minor
+    return f"onepin-python/{__version__} python/{major}.{minor}"
+
+
+def _call_whoami(key: str, base_url: str, timeout: float = 10.0) -> Dict[str, Any]:
+    """Call GET /api/v1/auth/whoami and return the ``data`` field.
+
+    Args:
+        key: API key to authenticate with.
+        base_url: Base URL of the OnePin API (no trailing slash).
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Parsed ``data`` dict from the response envelope.
+
+    Raises:
+        OnePinAuthError: On 401 or 403.
+        OnePinNetworkError: On connection or timeout failure.
+        OnePinHTTPError: On any other non-2xx response.
+    """
+    url = f"{base_url.rstrip('/')}/api/v1/auth/whoami"
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "User-Agent": _user_agent(),
+    }
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(url, headers=headers)
+    except (httpx.ConnectError, httpx.TimeoutException) as exc:
+        raise OnePinNetworkError(
+            f"Could not reach {base_url}. Pass --verbose for details.",
+            error_code="NETWORK_ERROR",
+        ) from exc
+
+    # Try to extract envelope fields for richer errors
+    request_id: Optional[str] = None
+    error_code = "HTTP_ERROR"
+    error_message = response.reason_phrase or "Request failed"
+    body_text = response.text
+
+    if response.status_code != 200:
+        try:
+            payload = response.json()
+            meta = payload.get("meta", {})
+            request_id = meta.get("request_id")
+            error_obj = payload.get("error", {})
+            error_code = error_obj.get("code", error_code)
+            error_message = error_obj.get("message", error_message)
+        except Exception:  # noqa: BLE001
+            pass
+
+        if response.status_code in (401, 403):
+            raise OnePinAuthError(
+                error_message,
+                status_code=response.status_code,
+                error_code="INVALID_API_KEY",
+                request_id=request_id,
+                response_body=body_text,
+            )
+
+        raise OnePinHTTPError(
+            error_message,
+            status_code=response.status_code,
+            error_code=error_code,
+            request_id=request_id,
+            response_body=body_text,
+        )
+
+    payload = response.json()
+    return payload["data"]

onepin/_cli/_state.py

@@ -0,0 +1,7 @@
+"""Process-local CLI option state shared between root callback and commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+root_options: dict[str, Any] = {}

onepin/_cli/auth/__init__.py

@@ -0,0 +1,3 @@
+"""CLI auth helpers: credential resolution and file I/O."""
+
+from __future__ import annotations

onepin/_cli/auth/credentials.py

@@ -0,0 +1,114 @@
+"""Read/write ~/.onepin/credentials TOML file with mode 0600.
+
+Uses ``tomllib`` (stdlib 3.11+) or ``tomli`` (backport for 3.10).
+Writes are hand-formatted TOML -- avoids the ``tomli_w`` dependency.
+
+Malformed TOML on read raises SystemExit(1) -- fail fast, no silent skip.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path, PosixPath, WindowsPath
+from typing import Any, Dict, Optional
+
+
+def _home_path() -> Path:
+    """Resolve the CLI home directory in a testable, cross-platform way."""
+    path_cls = WindowsPath if sys.platform == "win32" else PosixPath
+
+    home = os.environ.get("HOME")
+    if home:
+        return path_cls(home)
+
+    if sys.platform == "win32":
+        user_profile = os.environ.get("USERPROFILE")
+        if user_profile:
+            return path_cls(user_profile)
+
+        home_drive = os.environ.get("HOMEDRIVE")
+        home_path = os.environ.get("HOMEPATH")
+        if home_drive and home_path:
+            return path_cls(home_drive + home_path)
+
+    return Path.home()
+
+
+def _credentials_path() -> Path:
+    return _home_path() / ".onepin" / "credentials"
+
+
+def _load_toml(path: Path) -> Dict[str, Any]:
+    """Parse TOML from path. Hard-fails on parse error."""
+    try:
+        if sys.version_info >= (3, 11):
+            import tomllib
+
+            with open(path, "rb") as f:
+                return tomllib.load(f)
+        else:
+            import tomli  # type: ignore[import-not-found]
+
+            with open(path, "rb") as f:
+                return tomli.load(f)
+    except Exception as exc:  # noqa: BLE001
+        sys.stderr.write(f"[ERROR] Malformed credentials file at {path}: {exc}\n")
+        sys.exit(1)
+
+
+def read_credentials() -> Optional[Dict[str, Any]]:
+    """Read credentials file. Returns None if file does not exist.
+
+    Raises:
+        SystemExit(1): If the file exists but cannot be parsed as TOML.
+    """
+    path = _credentials_path()
+    if not path.exists():
+        return None
+    return _load_toml(path)
+
+
+def write_credentials(api_key: str, base_url: str, profile: str = "default") -> Path:
+    """Write credentials to ~/.onepin/credentials with mode 0600.
+
+    Creates ~/.onepin/ with mode 0700 if it does not exist.
+
+    Args:
+        api_key: The API key to store.
+        base_url: The base URL to store.
+        profile: Profile name (default: "default").
+
+    Returns:
+        Path to the written credentials file.
+    """
+    path = _credentials_path()
+    parent = path.parent
+
+    # Create parent directory with mode 0700
+    parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+    content = f'[{profile}]\napi_key = "{api_key}"\nbase_url = "{base_url}"\n'
+
+    # Write atomically: write to temp file, then rename
+    tmp_path = path.with_suffix(".tmp")
+    try:
+        tmp_path.write_text(content, encoding="utf-8")
+        if os.name != "nt":
+            os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+        tmp_path.replace(path)
+    except Exception:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+    return path
+
+
+def delete_credentials() -> bool:
+    """Delete credentials file. Returns True if deleted, False if not found."""
+    path = _credentials_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False

onepin/_cli/auth/resolver.py

@@ -0,0 +1,76 @@
+"""Credential resolution: flag > env > file > None.
+
+Priority chain (highest wins):
+  1. Explicit --api-key flag (passed as ``flag_api_key``)
+  2. ``ONEPIN_API_KEY`` environment variable
+  3. ``~/.onepin/credentials`` TOML file, ``[default]`` profile
+  4. None (caller decides whether to abort)
+
+Malformed TOML file raises hard error -- no silent fallback per project policy.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from onepin._cli.auth.credentials import read_credentials
+
+
+@dataclass
+class ResolvedCredentials:
+    api_key: Optional[str]
+    base_url: Optional[str]
+    source: Literal["flag", "env", "file", "default"]
+
+
+def resolve_credentials(
+    flag_api_key: Optional[str] = None,
+    flag_base_url: Optional[str] = None,
+) -> ResolvedCredentials:
+    """Resolve credentials from the priority chain.
+
+    Args:
+        flag_api_key: Value of --api-key CLI flag (None if not provided).
+        flag_base_url: Value of --base-url CLI flag (None if not provided).
+
+    Returns:
+        ResolvedCredentials with source indicating where the key came from.
+
+    Raises:
+        SystemExit: If the credentials file exists but is malformed TOML.
+    """
+    # 1. Explicit flag
+    if flag_api_key is not None:
+        return ResolvedCredentials(
+            api_key=flag_api_key,
+            base_url=flag_base_url,
+            source="flag",
+        )
+
+    # 2. Environment variable
+    env_key = os.environ.get("ONEPIN_API_KEY")
+    if env_key:
+        env_url = os.environ.get("ONEPIN_BASE_URL", flag_base_url)
+        return ResolvedCredentials(
+            api_key=env_key,
+            base_url=env_url,
+            source="env",
+        )
+
+    # 3. Credentials file (~/.onepin/credentials)
+    file_data = read_credentials()  # raises hard on malformed TOML
+    if file_data is not None:
+        profile = file_data.get("default", {})
+        file_key = profile.get("api_key")
+        file_url = flag_base_url or profile.get("base_url")
+        if file_key:
+            return ResolvedCredentials(
+                api_key=file_key,
+                base_url=file_url,
+                source="file",
+            )
+
+    # 4. Nothing found
+    return ResolvedCredentials(api_key=None, base_url=flag_base_url, source="default")

onepin/_cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command modules."""
+
+from __future__ import annotations

onepin/_cli/commands/_registry.py

@@ -0,0 +1,17 @@
+"""Wire subcommands into the root Typer app."""
+
+from __future__ import annotations
+
+import typer
+
+from onepin._cli.commands import auth, templates, uploads, voices, workflows
+
+
+def register(app: typer.Typer) -> None:
+    app.command(name="login")(auth.login)
+    app.command(name="logout")(auth.logout)
+    app.command(name="whoami")(auth.whoami)
+    app.add_typer(workflows.app, name="workflows")
+    app.add_typer(voices.app, name="voices")
+    app.add_typer(templates.app, name="templates")
+    app.add_typer(uploads.app, name="uploads")