captionpack-api 0.1.0__tar.gz

captionpack_api-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: captionpack-api
+Version: 0.1.0
+Summary: Python client for the Caption-Pack API — social captions as a service
+Author: Jeshua Domingo
+License: MIT
+Project-URL: Homepage, https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh
+Project-URL: Repository, https://github.com/jeshuadomingo-byte/caption-pack-api
+Keywords: captions,social-media,api-client,ai-agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# captionpack — Python client for the Caption-Pack API
+
+Turn a topic, audience, and tone into ready-to-post social captions + hashtags, as JSON. Built for developers and AI agents.
+
+## Install
+
+```bash
+pip install captionpack
+```
+
+(Get your API key at the [Caption-Pack site](https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh) — $10 for 500 calls.)
+
+## Quickstart
+
+```python
+from captionpack import Client
+
+client = Client(api_key="cp_live_...")
+pack = client.caption_pack(topic="morning routines", audience="busy parents")
+print(pack.captions[0].body, pack.hashtags)
+```
+
+You can also set the `CAPTIONPACK_API_KEY` environment variable instead of passing `api_key=`.
+
+## Usage
+
+```python
+from captionpack import (
+    Client,
+    AuthenticationError,
+    InsufficientCreditsError,
+    RateLimitedError,
+)
+
+client = Client()  # reads CAPTIONPACK_API_KEY
+
+# Generate captions (1 credit per call)
+pack = client.caption_pack(
+    topic="password managers",
+    audience="small business owners",
+    tone="warm",            # warm | bold | professional | playful
+    platform="linkedin",    # instagram | linkedin | x | tiktok
+    count=5,                # 1-10
+    include_hashtags=True,
+)
+for caption in pack.captions:
+    print(caption.hook, "|", caption.body, "|", caption.cta)
+print(pack.hashtags)
+print("credits left:", pack.credits_remaining)  # from X-Credits-Remaining
+
+# Check balance
+balance = client.balance()
+print(balance.credits)
+
+# Handle errors explicitly
+try:
+    pack = client.caption_pack(topic="x", audience="y")
+except InsufficientCreditsError as e:
+    print("Out of credits — top up:", e.top_up_url)
+except RateLimitedError:
+    print("Slow down — 60 requests/minute per key.")
+except AuthenticationError:
+    print("Bad API key.")
+```
+
+## Behavior notes
+
+- One automatic retry on HTTP 429 (with backoff, honoring `Retry-After`).
+- `X-Credits-Remaining` is surfaced on every `caption_pack` result.
+- Point at a local/dev server with `Client(api_key=..., base_url="http://localhost:8000")`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # or: pip install -e . && pip install pytest
+# integration tests need the API source; set CAPTIONPACK_TEST_API_DIR
+CAPTIONPACK_TEST_API_DIR=/path/to/caption-pack-api pytest
+```

captionpack_api-0.1.0/README.md

@@ -0,0 +1,78 @@
+# captionpack — Python client for the Caption-Pack API
+
+Turn a topic, audience, and tone into ready-to-post social captions + hashtags, as JSON. Built for developers and AI agents.
+
+## Install
+
+```bash
+pip install captionpack
+```
+
+(Get your API key at the [Caption-Pack site](https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh) — $10 for 500 calls.)
+
+## Quickstart
+
+```python
+from captionpack import Client
+
+client = Client(api_key="cp_live_...")
+pack = client.caption_pack(topic="morning routines", audience="busy parents")
+print(pack.captions[0].body, pack.hashtags)
+```
+
+You can also set the `CAPTIONPACK_API_KEY` environment variable instead of passing `api_key=`.
+
+## Usage
+
+```python
+from captionpack import (
+    Client,
+    AuthenticationError,
+    InsufficientCreditsError,
+    RateLimitedError,
+)
+
+client = Client()  # reads CAPTIONPACK_API_KEY
+
+# Generate captions (1 credit per call)
+pack = client.caption_pack(
+    topic="password managers",
+    audience="small business owners",
+    tone="warm",            # warm | bold | professional | playful
+    platform="linkedin",    # instagram | linkedin | x | tiktok
+    count=5,                # 1-10
+    include_hashtags=True,
+)
+for caption in pack.captions:
+    print(caption.hook, "|", caption.body, "|", caption.cta)
+print(pack.hashtags)
+print("credits left:", pack.credits_remaining)  # from X-Credits-Remaining
+
+# Check balance
+balance = client.balance()
+print(balance.credits)
+
+# Handle errors explicitly
+try:
+    pack = client.caption_pack(topic="x", audience="y")
+except InsufficientCreditsError as e:
+    print("Out of credits — top up:", e.top_up_url)
+except RateLimitedError:
+    print("Slow down — 60 requests/minute per key.")
+except AuthenticationError:
+    print("Bad API key.")
+```
+
+## Behavior notes
+
+- One automatic retry on HTTP 429 (with backoff, honoring `Retry-After`).
+- `X-Credits-Remaining` is surfaced on every `caption_pack` result.
+- Point at a local/dev server with `Client(api_key=..., base_url="http://localhost:8000")`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # or: pip install -e . && pip install pytest
+# integration tests need the API source; set CAPTIONPACK_TEST_API_DIR
+CAPTIONPACK_TEST_API_DIR=/path/to/caption-pack-api pytest
+```

captionpack_api-0.1.0/captionpack/__init__.py

@@ -0,0 +1,35 @@
+"""captionpack — Python client for the Caption-Pack API."""
+
+from .client import (
+    API_KEY_ENV_VAR,
+    DEFAULT_BASE_URL,
+    BalanceResult,
+    Caption,
+    CaptionPackResult,
+    Client,
+)
+from .exceptions import (
+    AuthenticationError,
+    CaptionPackError,
+    InsufficientCreditsError,
+    InvalidParamsError,
+    RateLimitedError,
+    ServerError,
+)
+
+__all__ = [
+    "API_KEY_ENV_VAR",
+    "DEFAULT_BASE_URL",
+    "BalanceResult",
+    "Caption",
+    "CaptionPackResult",
+    "Client",
+    "AuthenticationError",
+    "CaptionPackError",
+    "InsufficientCreditsError",
+    "InvalidParamsError",
+    "RateLimitedError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

captionpack_api-0.1.0/captionpack/client.py

@@ -0,0 +1,259 @@
+"""Synchronous client for the Caption-Pack API.
+
+Quickstart::
+
+    from captionpack import Client
+
+    client = Client(api_key="cp_live_...")
+    pack = client.caption_pack(topic="morning routines", audience="busy parents")
+    print(pack.captions[0].body, pack.hashtags)
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    CaptionPackError,
+    InsufficientCreditsError,
+    InvalidParamsError,
+    RateLimitedError,
+    ServerError,
+)
+
+DEFAULT_BASE_URL = "https://caption-pack-api.onrender.com"
+API_KEY_ENV_VAR = "CAPTIONPACK_API_KEY"
+
+# One retry on 429 only; everything else fails fast so callers see real errors.
+_MAX_429_RETRIES = 1
+_DEFAULT_BACKOFF_SECONDS = 1.0
+
+
+@dataclass
+class Caption:
+    """A single generated caption: hook + body + call to action."""
+
+    hook: str
+    body: str
+    cta: str
+    hashtags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CaptionPackResult:
+    """Result of :meth:`Client.caption_pack`."""
+
+    captions: list[Caption] = field(default_factory=list)
+    hashtags: list[str] = field(default_factory=list)
+    credits_used: int = 1
+    credits_remaining: int | None = None
+
+
+@dataclass
+class BalanceResult:
+    """Result of :meth:`Client.balance`."""
+
+    credits: int
+    key_id: int | None = None
+
+
+def _error_from_response(resp: requests.Response) -> CaptionPackError:
+    """Map an HTTP error response to the matching typed exception."""
+    code: str | None = None
+    message = f"Caption-Pack API request failed (HTTP {resp.status_code})."
+    top_up_url: str | None = None
+    try:
+        payload = resp.json()
+        err = payload.get("error", {}) if isinstance(payload, dict) else {}
+        code = err.get("code")
+        if err.get("message"):
+            message = err["message"]
+        top_up_url = err.get("top_up_url")
+    except ValueError:
+        pass  # non-JSON body: keep the generic message
+
+    status = resp.status_code
+    if status == 400:
+        return InvalidParamsError(message, code=code, status_code=status)
+    if status == 401:
+        return AuthenticationError(message, code=code, status_code=status)
+    if status == 402:
+        return InsufficientCreditsError(
+            message, code=code, status_code=status, top_up_url=top_up_url
+        )
+    if status == 429:
+        return RateLimitedError(message, code=code, status_code=status)
+    if 500 <= status < 600:
+        return ServerError(message, code=code, status_code=status)
+    return CaptionPackError(message, code=code, status_code=status)
+
+
+class Client:
+    """Client for the Caption-Pack API.
+
+    Args:
+        api_key: Your ``cp_live_...`` key. Falls back to the
+            ``CAPTIONPACK_API_KEY`` environment variable. Required.
+        base_url: API base URL. Defaults to the production service.
+        timeout: Seconds to wait for a response before giving up.
+        user_agent: Optional custom User-Agent suffix for your app/agent.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        key = api_key or os.environ.get(API_KEY_ENV_VAR)
+        if not key:
+            raise ValueError(
+                "An API key is required: pass api_key=... or set the "
+                f"{API_KEY_ENV_VAR} environment variable."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        ua = "captionpack-python/0.1.0"
+        if user_agent:
+            ua = f"{ua} {user_agent}"
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {key}",
+                "Content-Type": "application/json",
+                "User-Agent": ua,
+            }
+        )
+
+    # -- internals ----------------------------------------------------
+
+    def _request(
+        self, method: str, path: str, *, json: dict | None = None
+    ) -> tuple[dict, requests.Response]:
+        """Send a request; retry once on 429, then raise typed errors."""
+        url = f"{self.base_url}{path}"
+        attempts = 0
+        while True:
+            try:
+                resp = self.session.request(
+                    method, url, json=json, timeout=self.timeout
+                )
+            except requests.RequestException as exc:
+                raise CaptionPackError(f"Could not reach {url}: {exc}") from exc
+
+            if resp.status_code == 429 and attempts < _MAX_429_RETRIES:
+                attempts += 1
+                wait = self._retry_wait_seconds(resp)
+                time.sleep(wait)
+                continue
+
+            if resp.status_code >= 400:
+                raise _error_from_response(resp)
+
+            try:
+                return resp.json(), resp
+            except ValueError as exc:
+                raise CaptionPackError(
+                    f"API returned a non-JSON response (HTTP {resp.status_code}).",
+                    status_code=resp.status_code,
+                ) from exc
+
+    @staticmethod
+    def _retry_wait_seconds(resp: requests.Response) -> float:
+        retry_after = resp.headers.get("Retry-After")
+        if retry_after:
+            try:
+                return max(0.0, float(retry_after))
+            except ValueError:
+                pass
+        return _DEFAULT_BACKOFF_SECONDS
+
+    # -- public API ---------------------------------------------------
+
+    def caption_pack(
+        self,
+        topic: str,
+        audience: str,
+        *,
+        tone: str = "warm",
+        platform: str = "instagram",
+        count: int = 5,
+        include_hashtags: bool = True,
+        niche: str | None = None,
+    ) -> CaptionPackResult:
+        """Generate a pack of captions + hashtags.
+
+        Costs 1 credit per call. ``X-Credits-Remaining`` from the API is
+        surfaced on the result so callers always know their balance.
+        """
+        body: dict = {
+            "topic": topic,
+            "audience": audience,
+            "tone": tone,
+            "platform": platform,
+            "count": count,
+            "include_hashtags": include_hashtags,
+        }
+        if niche is not None:
+            body["niche"] = niche
+
+        payload, resp = self._request("POST", "/v1/caption-pack", json=body)
+
+        captions = []
+        seen_tags: list[str] = []
+        for c in payload.get("captions", []):
+            tags = list(c.get("hashtags", []))
+            for tag in tags:
+                if tag not in seen_tags:
+                    seen_tags.append(tag)
+            captions.append(
+                Caption(
+                    hook=c.get("hook", ""),
+                    body=c.get("body", ""),
+                    cta=c.get("cta", ""),
+                    hashtags=tags,
+                )
+            )
+        # The API may return hashtags per-caption rather than top-level;
+        # aggregate a de-duplicated list so callers get one simple field.
+        top_level_tags = payload.get("hashtags")
+        hashtags = (
+            list(top_level_tags) if isinstance(top_level_tags, list) else seen_tags
+        )
+        remaining = payload.get("credits_remaining")
+        if remaining is None:
+            header_val = resp.headers.get("X-Credits-Remaining")
+            remaining = int(header_val) if header_val is not None else None
+
+        return CaptionPackResult(
+            captions=captions,
+            hashtags=hashtags,
+            credits_used=int(payload.get("credits_used", 1)),
+            credits_remaining=remaining,
+        )
+
+    def balance(self) -> BalanceResult:
+        """Return the remaining credit balance for this API key."""
+        payload, _ = self._request("GET", "/v1/balance")
+        return BalanceResult(
+            credits=int(payload.get("credits", 0)),
+            key_id=payload.get("key_id"),
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self.session.close()
+
+    def __enter__(self) -> "Client":  # pragma: no cover - convenience
+        return self
+
+    def __exit__(self, *exc: object) -> None:  # pragma: no cover - convenience
+        self.close()

captionpack_api-0.1.0/captionpack/exceptions.py

@@ -0,0 +1,65 @@
+"""Typed exceptions for the Caption-Pack API client.
+
+The API returns errors as JSON envelopes like::
+
+    {"error": {"code": "invalid_key", "message": "API key is missing or invalid."}}
+
+with the HTTP status carrying the error class. This module maps those
+statuses to typed exceptions so callers can handle each case explicitly.
+"""
+
+from __future__ import annotations
+
+
+class CaptionPackError(Exception):
+    """Base error for all Caption-Pack client failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.message
+
+
+class AuthenticationError(CaptionPackError):
+    """HTTP 401 — the API key is missing, invalid, or revoked."""
+
+
+class InsufficientCreditsError(CaptionPackError):
+    """HTTP 402 — the key is out of credits.
+
+    The API points at a top-up URL when one is configured; it is exposed
+    here when present so callers can direct the user to buy more.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+        top_up_url: str | None = None,
+    ) -> None:
+        super().__init__(message, code=code, status_code=status_code)
+        self.top_up_url = top_up_url
+
+
+class RateLimitedError(CaptionPackError):
+    """HTTP 429 — too many requests for this key. Slow down and retry."""
+
+
+class InvalidParamsError(CaptionPackError):
+    """HTTP 400 — a request parameter was missing or invalid."""
+
+
+class ServerError(CaptionPackError):
+    """HTTP 5xx — the API had an internal problem. Safe to retry later."""

captionpack_api-0.1.0/captionpack_api.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: captionpack-api
+Version: 0.1.0
+Summary: Python client for the Caption-Pack API — social captions as a service
+Author: Jeshua Domingo
+License: MIT
+Project-URL: Homepage, https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh
+Project-URL: Repository, https://github.com/jeshuadomingo-byte/caption-pack-api
+Keywords: captions,social-media,api-client,ai-agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# captionpack — Python client for the Caption-Pack API
+
+Turn a topic, audience, and tone into ready-to-post social captions + hashtags, as JSON. Built for developers and AI agents.
+
+## Install
+
+```bash
+pip install captionpack
+```
+
+(Get your API key at the [Caption-Pack site](https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh) — $10 for 500 calls.)
+
+## Quickstart
+
+```python
+from captionpack import Client
+
+client = Client(api_key="cp_live_...")
+pack = client.caption_pack(topic="morning routines", audience="busy parents")
+print(pack.captions[0].body, pack.hashtags)
+```
+
+You can also set the `CAPTIONPACK_API_KEY` environment variable instead of passing `api_key=`.
+
+## Usage
+
+```python
+from captionpack import (
+    Client,
+    AuthenticationError,
+    InsufficientCreditsError,
+    RateLimitedError,
+)
+
+client = Client()  # reads CAPTIONPACK_API_KEY
+
+# Generate captions (1 credit per call)
+pack = client.caption_pack(
+    topic="password managers",
+    audience="small business owners",
+    tone="warm",            # warm | bold | professional | playful
+    platform="linkedin",    # instagram | linkedin | x | tiktok
+    count=5,                # 1-10
+    include_hashtags=True,
+)
+for caption in pack.captions:
+    print(caption.hook, "|", caption.body, "|", caption.cta)
+print(pack.hashtags)
+print("credits left:", pack.credits_remaining)  # from X-Credits-Remaining
+
+# Check balance
+balance = client.balance()
+print(balance.credits)
+
+# Handle errors explicitly
+try:
+    pack = client.caption_pack(topic="x", audience="y")
+except InsufficientCreditsError as e:
+    print("Out of credits — top up:", e.top_up_url)
+except RateLimitedError:
+    print("Slow down — 60 requests/minute per key.")
+except AuthenticationError:
+    print("Bad API key.")
+```
+
+## Behavior notes
+
+- One automatic retry on HTTP 429 (with backoff, honoring `Retry-After`).
+- `X-Credits-Remaining` is surfaced on every `caption_pack` result.
+- Point at a local/dev server with `Client(api_key=..., base_url="http://localhost:8000")`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # or: pip install -e . && pip install pytest
+# integration tests need the API source; set CAPTIONPACK_TEST_API_DIR
+CAPTIONPACK_TEST_API_DIR=/path/to/caption-pack-api pytest
+```

captionpack_api-0.1.0/captionpack_api.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+captionpack/__init__.py
+captionpack/client.py
+captionpack/exceptions.py
+captionpack_api.egg-info/PKG-INFO
+captionpack_api.egg-info/SOURCES.txt
+captionpack_api.egg-info/dependency_links.txt
+captionpack_api.egg-info/requires.txt
+captionpack_api.egg-info/top_level.txt
+tests/test_errors.py
+tests/test_live.py

captionpack_api-0.1.0/captionpack_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

captionpack_api-0.1.0/captionpack_api.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

captionpack_api-0.1.0/captionpack_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+captionpack

captionpack_api-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "captionpack-api"
+version = "0.1.0"
+description = "Python client for the Caption-Pack API — social captions as a service"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Jeshua Domingo" }]
+dependencies = ["requests>=2.28"]
+keywords = ["captions", "social-media", "api-client", "ai-agents"]
+
+[project.urls]
+Homepage = "https://muse.ai/s/caption-pack-api-xfxt62ya0xcxlxhh"
+Repository = "https://github.com/jeshuadomingo-byte/caption-pack-api"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["captionpack*"]

captionpack_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

captionpack_api-0.1.0/tests/test_errors.py

@@ -0,0 +1,168 @@
+"""Unit tests for error mapping, retries, and key handling.
+
+These tests never touch the network: they stub out
+``requests.Session.request`` with canned responses.
+"""
+
+import json
+import os
+
+import pytest
+import requests
+
+from captionpack import (
+    API_KEY_ENV_VAR,
+    AuthenticationError,
+    CaptionPackError,
+    Client,
+    InsufficientCreditsError,
+    InvalidParamsError,
+    RateLimitedError,
+    ServerError,
+)
+
+
+def _fake_response(status_code, payload=None, headers=None, raw_body=None):
+    resp = requests.Response()
+    resp.status_code = status_code
+    if raw_body is not None:
+        resp._content = raw_body
+    else:
+        resp._content = json.dumps(payload or {}).encode()
+    resp.headers.update(headers or {})
+    return resp
+
+
+def _client_with_stub(monkeypatch, responses, sleep_recorder=None):
+    """Build a Client whose session.request yields the given responses."""
+    calls = {"n": 0, "sleeps": []}
+    recorder = sleep_recorder if sleep_recorder is not None else calls["sleeps"]
+
+    def fake_request(self, method, url, **kwargs):
+        idx = min(calls["n"], len(responses) - 1)
+        calls["n"] += 1
+        return responses[idx]
+
+    def fake_sleep(seconds):
+        recorder.append(seconds)
+
+    monkeypatch.setattr(requests.Session, "request", fake_request)
+    monkeypatch.setattr("captionpack.client.time.sleep", fake_sleep)
+    client = Client(api_key="cp_live_test")
+    return client, calls
+
+
+def test_missing_key_raises_value_error(monkeypatch):
+    monkeypatch.delenv(API_KEY_ENV_VAR, raising=False)
+    with pytest.raises(ValueError, match="API key is required"):
+        Client(api_key=None)
+
+
+def test_key_from_env_var(monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV_VAR, "cp_live_from_env")
+    monkeypatch.delenv("nope", raising=False)
+    client = Client(api_key=None)
+    assert client.session.headers["Authorization"] == "Bearer cp_live_from_env"
+
+
+def test_401_maps_to_authentication_error(monkeypatch):
+    client, _ = _client_with_stub(
+        monkeypatch,
+        [_fake_response(401, {"error": {"code": "invalid_key", "message": "bad key"}})],
+    )
+    with pytest.raises(AuthenticationError) as exc_info:
+        client.balance()
+    assert exc_info.value.code == "invalid_key"
+    assert exc_info.value.status_code == 401
+
+
+def test_400_maps_to_invalid_params_error(monkeypatch):
+    client, _ = _client_with_stub(
+        monkeypatch,
+        [_fake_response(400, {"error": {"code": "invalid_params", "message": "nope"}})],
+    )
+    with pytest.raises(InvalidParamsError):
+        client.caption_pack(topic="t", audience="a", tone="bogus")
+
+
+def test_402_maps_to_insufficient_credits_with_top_up_url(monkeypatch):
+    client, _ = _client_with_stub(
+        monkeypatch,
+        [
+            _fake_response(
+                402,
+                {
+                    "error": {
+                        "code": "insufficient_credits",
+                        "message": "Out of credits.",
+                        "top_up_url": "https://example.com/topup",
+                    }
+                },
+            )
+        ],
+    )
+    with pytest.raises(InsufficientCreditsError) as exc_info:
+        client.caption_pack(topic="t", audience="a")
+    assert exc_info.value.top_up_url == "https://example.com/topup"
+
+
+def test_429_retries_once_then_succeeds(monkeypatch):
+    ok = _fake_response(200, {"credits": 7, "key_id": 1})
+    client, calls = _client_with_stub(
+        monkeypatch,
+        [_fake_response(429, {"error": {"code": "rate_limited", "message": "slow"}}), ok],
+    )
+    assert client.balance().credits == 7
+    assert calls["n"] == 2  # one retry happened
+    assert calls["sleeps"] == [1.0]  # default backoff, no Retry-After header
+
+
+def test_429_honors_retry_after_header(monkeypatch):
+    ok = _fake_response(200, {"credits": 3, "key_id": 1})
+    client, calls = _client_with_stub(
+        monkeypatch,
+        [
+            _fake_response(
+                429, {"error": {"code": "rate_limited"}}, headers={"Retry-After": "2"}
+            ),
+            ok,
+        ],
+    )
+    assert client.balance().credits == 3
+    assert calls["sleeps"] == [2.0]
+
+
+def test_429_twice_raises_rate_limited_error(monkeypatch):
+    client, calls = _client_with_stub(
+        monkeypatch,
+        [_fake_response(429, {"error": {"code": "rate_limited", "message": "slow"}})],
+    )
+    with pytest.raises(RateLimitedError):
+        client.balance()
+    assert calls["n"] == 2  # initial + exactly one retry
+
+
+def test_500_maps_to_server_error(monkeypatch):
+    client, _ = _client_with_stub(
+        monkeypatch, [_fake_response(500, {"error": {"code": "boom"}})]
+    )
+    with pytest.raises(ServerError):
+        client.balance()
+
+
+def test_non_json_error_body_still_raises(monkeypatch):
+    client, _ = _client_with_stub(
+        monkeypatch, [_fake_response(401, raw_body=b"<html>nope</html>")]
+    )
+    with pytest.raises(AuthenticationError):
+        client.balance()
+
+
+def test_connection_failure_raises_caption_pack_error(monkeypatch):
+    def boom(self, method, url, **kwargs):
+        raise requests.ConnectionError("down")
+
+    monkeypatch.setattr(requests.Session, "request", boom)
+    client = Client(api_key="cp_live_test")
+    with pytest.raises(CaptionPackError, match="Could not reach"):
+        client.balance()

captionpack_api-0.1.0/tests/test_live.py

@@ -0,0 +1,108 @@
+"""Integration tests against a local run of the real Caption-Pack API.
+
+These tests mint keys in the LOCAL credits.db only (backed up and restored
+by the session fixture) — they never touch production.
+"""
+
+import pytest
+
+from captionpack import (
+    AuthenticationError,
+    Client,
+    InsufficientCreditsError,
+    InvalidParamsError,
+    RateLimitedError,
+)
+
+from .conftest import mint_key
+
+
+def _client(base_url, key):
+    return Client(api_key=key, base_url=base_url, timeout=15)
+
+
+def test_caption_pack_success(live_server, venv_python):
+    key = mint_key(venv_python, 10)
+    client = _client(live_server, key)
+    pack = client.caption_pack(topic="morning routines", audience="busy parents")
+
+    assert len(pack.captions) == 5  # default count
+    first = pack.captions[0]
+    assert first.hook and first.body and first.cta
+    assert pack.hashtags, "expected hashtags by default"
+    assert first.hashtags, "expected per-caption hashtags"
+    assert pack.hashtags[0] in first.hashtags  # aggregated from captions
+    assert pack.credits_used == 1
+    assert pack.credits_remaining == 9
+    client.close()
+
+
+def test_caption_pack_options(live_server, venv_python):
+    key = mint_key(venv_python, 10)
+    client = _client(live_server, key)
+    pack = client.caption_pack(
+        topic="password managers",
+        audience="small business owners",
+        tone="bold",
+        platform="linkedin",
+        count=3,
+        include_hashtags=False,
+    )
+    assert len(pack.captions) == 3
+    assert pack.hashtags == []
+    assert pack.credits_remaining == 9
+    client.close()
+
+
+def test_balance_reflects_spend(live_server, venv_python):
+    key = mint_key(venv_python, 5)
+    client = _client(live_server, key)
+    assert client.balance().credits == 5
+    client.caption_pack(topic="t", audience="a", count=1)
+    client.caption_pack(topic="t", audience="a", count=1)
+    assert client.balance().credits == 3
+    client.close()
+
+
+def test_bad_key_raises_authentication_error(live_server):
+    client = _client(live_server, "cp_live_thiskeydoesnotexist")
+    with pytest.raises(AuthenticationError):
+        client.balance()
+    with pytest.raises(AuthenticationError):
+        client.caption_pack(topic="t", audience="a")
+    client.close()
+
+
+def test_zero_credits_raises_insufficient_credits(live_server, venv_python):
+    key = mint_key(venv_python, 0)
+    client = _client(live_server, key)
+    with pytest.raises(InsufficientCreditsError) as exc_info:
+        client.caption_pack(topic="t", audience="a")
+    assert exc_info.value.top_up_url  # API always includes the top-up link
+    # balance still works with 0 credits
+    assert client.balance().credits == 0
+    client.close()
+
+
+def test_invalid_tone_raises_invalid_params(live_server, venv_python):
+    key = mint_key(venv_python, 5)
+    client = _client(live_server, key)
+    with pytest.raises(InvalidParamsError):
+        client.caption_pack(topic="t", audience="a", tone="nope")
+    # the rejected call must not spend a credit
+    assert client.balance().credits == 5
+    client.close()
+
+
+def test_rate_limit_raises_after_retry(live_server, venv_python):
+    key = mint_key(venv_python, 100)
+    client = _client(live_server, key)
+    hit_limit = False
+    for _ in range(80):  # limit is 60/min; the 61st trips it
+        try:
+            client.caption_pack(topic="t", audience="a", count=1)
+        except RateLimitedError:
+            hit_limit = True
+            break
+    assert hit_limit, "expected the 60 req/min limit to trip"
+    client.close()