onstoa 0.2.0__tar.gz

onstoa-0.2.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

onstoa-0.2.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# Stoa SDK
+
+Usage-based billing SDK for AI applications.
+
+## Build System
+
+Use `just` for all build, test, and lint commands. Run `just` to see available recipes.
+
+### Key Recipes
+
+```bash
+just lint        # Run all linting (ruff + mypy strict)
+just test        # Run tests
+just check       # Run all checks (lint + test)
+just fmt         # Format code with ruff
+just ruff-fix    # Auto-fix ruff issues
+```
+
+### Other Recipes
+
+- `just install` - Install all dependencies with uv
+- `just mypy` - Run mypy type checker only
+- `just ruff` - Run ruff linter only
+- `just test-cov` - Run tests with coverage
+- `just build` - Build package
+- `just clean` - Clean build artifacts
+
+## Conventions
+
+- Python 3.10+ required
+- Use `orjson` instead of `json` for serialization
+- Use function-based tests (no class-based pytest tests)
+- mypy strict mode is enforced
+- Line length: 100 characters
+- asyncio_mode is auto for pytest-asyncio

onstoa-0.2.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: onstoa
+Version: 0.2.0
+Summary: Usage-based billing SDK for AI applications
+Project-URL: Homepage, https://onstoa.com
+Project-URL: Repository, https://github.com/stoa-org/stoa
+Project-URL: Documentation, https://docs.onstoa.com
+Author-email: Stoa <hello@stoa.dev>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: uuid-utils>=0.6.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18.0; extra == 'all'
+Requires-Dist: elevenlabs>=1.0.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.18.0; extra == 'dev'
+Requires-Dist: elevenlabs>=1.0.0; extra == 'dev'
+Requires-Dist: openai>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: ty>=0.0.7; extra == 'dev'
+Provides-Extra: elevenlabs
+Requires-Dist: elevenlabs>=1.0.0; extra == 'elevenlabs'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Stoa SDK
+
+Usage-based billing SDK for AI applications. Wrap your AI provider calls to automatically meter usage and bill your users.
+
+## Installation
+
+```bash
+pip install stoa
+```
+
+## Quick Start
+
+```python
+from stoa import Stoa, InsufficientBalanceError
+
+# Reads STOA_API_KEY and STOA_APP_ID from environment
+stoa = Stoa()
+
+# 1. Register or reuse the member from your backend
+stoa.register_member(
+    connect_secret=STOA_CONNECT_SECRET,
+    user_id="user_123",
+    email="ada@example.com",
+)
+
+# 2. Use your app's own user ID for billing calls
+client = stoa.openai(user_id="user_123")
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+except InsufficientBalanceError as e:
+    print(f"Please top up: {e.topup_url}")
+```
+
+Typical flow:
+1. call `stoa.register_member(...)` from your backend
+2. keep using your own app `user_id` in SDK billing calls
+3. send the user to `e.topup_url` if they need funds
+
+## Onboard Users
+
+Stoa can stay invisible to the customer while still owning the canonical user
+and membership records.
+
+### User onboards via your app
+
+From your backend, call the SDK once with your connect secret and the user's
+verified app identity:
+
+```python
+from stoa import Stoa
+
+stoa = Stoa(api_key=STOA_API_KEY, base_url=STOA_BASE_URL, app_id=STOA_APP_ID)
+
+result = stoa.register_member(
+    connect_secret=STOA_CONNECT_SECRET,
+    user_id=user.id,
+    email=user.email,
+    name=user.name,
+    avatar_url=user.avatar_url,
+)
+
+# Optional: store the membership ID for debugging or richer account UX.
+persist_membership_binding(
+    user_id=user.id,
+    membership_id=result.membership_id,
+)
+```
+
+Stoa registers the user for billing in your app.
+
+Your app can continue billing that user with its own `user_id`.
+
+#### Optional: open a hosted top-up page
+
+If you want an explicit "Add funds" action in your product:
+
+```python
+topup_url = stoa.get_topup_url(user_id=user.id)
+```
+
+This returns a hosted Stoa payment page for that app user.
+
+### User installs via Stoa marketplace
+
+Marketplace installs use the install flow below.
+
+#### Install callback
+
+Add a callback endpoint that verifies the Stoa install token and activates the
+membership for your app user. Both flows should converge on the same stored
+membership binding in your app.
+
+```python
+from stoa import Stoa
+
+stoa = Stoa()
+
+
+def stoa_callback(token: str):
+    claims = stoa.verify_install_callback(token=token)
+
+    user = find_or_create_user(
+        email=claims["email"],
+        name=claims["name"],
+    )
+
+    install = stoa.exchange_install_token(
+        token=token,
+        user_id=user.id,
+    )
+
+    persist_membership_binding(
+        user_id=user.id,
+        membership_id=install.membership_id,
+    )
+    return create_session_and_redirect(user)
+```
+
+The SDK fetches Stoa's public key for you and keeps the server-side activation
+step in place, so the secure flow does not become app boilerplate.
+
+## Supported Providers
+
+### OpenAI
+
+```python
+client = stoa.openai(user_id="user_123")
+
+# Chat completions
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Explain quantum computing"}]
+)
+
+# Embeddings
+embeddings = client.embeddings.create(
+    model="text-embedding-3-small",
+    input="Hello world"
+)
+```
+
+### Anthropic
+
+```python
+client = stoa.anthropic(user_id="user_123")
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Write a haiku about Python"}]
+)
+```
+
+### OpenRouter
+
+Access 100+ models through a single API:
+
+```python
+client = stoa.openrouter(user_id="user_123")
+
+# Use any model available on OpenRouter
+response = client.chat.completions.create(
+    model="meta-llama/llama-3.1-70b-instruct",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+### ElevenLabs
+
+```python
+client = stoa.elevenlabs(user_id="user_123")
+
+audio = client.text_to_speech.convert(
+    voice_id="JBFqnCBsd6RMkjVDRZzb",
+    text="Hello, welcome to our application!"
+)
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STOA_API_KEY` | Yes | - | Your Stoa application API key |
+| `STOA_APP_ID` | No | - | Your Stoa application ID (required for member registration unless passed explicitly) |
+| `STOA_BASE_URL` | No | `https://api.onstoa.com` | Stoa API base URL (for self-hosted or testing) |
+
+### Example .env file
+
+```bash
+# Required
+STOA_API_KEY=stoa_app_xxx
+STOA_APP_ID=app_xxx
+
+# Optional - override API endpoint
+STOA_BASE_URL=https://api.onstoa.com
+
+# Provider keys (only needed for providers you use)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
+ELEVENLABS_API_KEY=...
+```
+
+## Documentation
+
+See [docs.onstoa.com](https://docs.onstoa.com) for full documentation.

onstoa-0.2.0/README.md

@@ -0,0 +1,210 @@
+# Stoa SDK
+
+Usage-based billing SDK for AI applications. Wrap your AI provider calls to automatically meter usage and bill your users.
+
+## Installation
+
+```bash
+pip install stoa
+```
+
+## Quick Start
+
+```python
+from stoa import Stoa, InsufficientBalanceError
+
+# Reads STOA_API_KEY and STOA_APP_ID from environment
+stoa = Stoa()
+
+# 1. Register or reuse the member from your backend
+stoa.register_member(
+    connect_secret=STOA_CONNECT_SECRET,
+    user_id="user_123",
+    email="ada@example.com",
+)
+
+# 2. Use your app's own user ID for billing calls
+client = stoa.openai(user_id="user_123")
+
+try:
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+except InsufficientBalanceError as e:
+    print(f"Please top up: {e.topup_url}")
+```
+
+Typical flow:
+1. call `stoa.register_member(...)` from your backend
+2. keep using your own app `user_id` in SDK billing calls
+3. send the user to `e.topup_url` if they need funds
+
+## Onboard Users
+
+Stoa can stay invisible to the customer while still owning the canonical user
+and membership records.
+
+### User onboards via your app
+
+From your backend, call the SDK once with your connect secret and the user's
+verified app identity:
+
+```python
+from stoa import Stoa
+
+stoa = Stoa(api_key=STOA_API_KEY, base_url=STOA_BASE_URL, app_id=STOA_APP_ID)
+
+result = stoa.register_member(
+    connect_secret=STOA_CONNECT_SECRET,
+    user_id=user.id,
+    email=user.email,
+    name=user.name,
+    avatar_url=user.avatar_url,
+)
+
+# Optional: store the membership ID for debugging or richer account UX.
+persist_membership_binding(
+    user_id=user.id,
+    membership_id=result.membership_id,
+)
+```
+
+Stoa registers the user for billing in your app.
+
+Your app can continue billing that user with its own `user_id`.
+
+#### Optional: open a hosted top-up page
+
+If you want an explicit "Add funds" action in your product:
+
+```python
+topup_url = stoa.get_topup_url(user_id=user.id)
+```
+
+This returns a hosted Stoa payment page for that app user.
+
+### User installs via Stoa marketplace
+
+Marketplace installs use the install flow below.
+
+#### Install callback
+
+Add a callback endpoint that verifies the Stoa install token and activates the
+membership for your app user. Both flows should converge on the same stored
+membership binding in your app.
+
+```python
+from stoa import Stoa
+
+stoa = Stoa()
+
+
+def stoa_callback(token: str):
+    claims = stoa.verify_install_callback(token=token)
+
+    user = find_or_create_user(
+        email=claims["email"],
+        name=claims["name"],
+    )
+
+    install = stoa.exchange_install_token(
+        token=token,
+        user_id=user.id,
+    )
+
+    persist_membership_binding(
+        user_id=user.id,
+        membership_id=install.membership_id,
+    )
+    return create_session_and_redirect(user)
+```
+
+The SDK fetches Stoa's public key for you and keeps the server-side activation
+step in place, so the secure flow does not become app boilerplate.
+
+## Supported Providers
+
+### OpenAI
+
+```python
+client = stoa.openai(user_id="user_123")
+
+# Chat completions
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Explain quantum computing"}]
+)
+
+# Embeddings
+embeddings = client.embeddings.create(
+    model="text-embedding-3-small",
+    input="Hello world"
+)
+```
+
+### Anthropic
+
+```python
+client = stoa.anthropic(user_id="user_123")
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Write a haiku about Python"}]
+)
+```
+
+### OpenRouter
+
+Access 100+ models through a single API:
+
+```python
+client = stoa.openrouter(user_id="user_123")
+
+# Use any model available on OpenRouter
+response = client.chat.completions.create(
+    model="meta-llama/llama-3.1-70b-instruct",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+### ElevenLabs
+
+```python
+client = stoa.elevenlabs(user_id="user_123")
+
+audio = client.text_to_speech.convert(
+    voice_id="JBFqnCBsd6RMkjVDRZzb",
+    text="Hello, welcome to our application!"
+)
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STOA_API_KEY` | Yes | - | Your Stoa application API key |
+| `STOA_APP_ID` | No | - | Your Stoa application ID (required for member registration unless passed explicitly) |
+| `STOA_BASE_URL` | No | `https://api.onstoa.com` | Stoa API base URL (for self-hosted or testing) |
+
+### Example .env file
+
+```bash
+# Required
+STOA_API_KEY=stoa_app_xxx
+STOA_APP_ID=app_xxx
+
+# Optional - override API endpoint
+STOA_BASE_URL=https://api.onstoa.com
+
+# Provider keys (only needed for providers you use)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
+ELEVENLABS_API_KEY=...
+```
+
+## Documentation
+
+See [docs.onstoa.com](https://docs.onstoa.com) for full documentation.

onstoa-0.2.0/justfile

@@ -0,0 +1,17 @@
+# Default recipe runs all checks
+default: check
+
+# Run all checks (lint, typecheck, test)
+check: lint typecheck test
+
+# Run ruff linter
+lint:
+	uv run ruff check stoa
+
+# Run ty type checker
+typecheck:
+	uv run ty check stoa
+
+# Run pytest with parallel execution
+test:
+	uv run pytest -n auto

onstoa-0.2.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onstoa"
+version = "0.2.0"
+description = "Usage-based billing SDK for AI applications"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Stoa", email = "hello@stoa.dev" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "orjson>=3.9.0",
+    "pydantic>=2.0.0",
+    "PyJWT[crypto]>=2.0.0",
+    "tenacity>=8.0.0",
+    "uuid-utils>=0.6.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.18.0"]
+elevenlabs = ["elevenlabs>=1.0.0"]
+all = [
+    "openai>=1.0.0",
+    "anthropic>=0.18.0",
+    "elevenlabs>=1.0.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-httpx>=0.30.0",
+    "pytest-xdist>=3.5.0",
+    "ruff>=0.1.0",
+    "ty>=0.0.7",
+    "pre-commit>=3.0.0",
+    "openai>=1.0.0",
+    "anthropic>=0.18.0",
+    "elevenlabs>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://onstoa.com"
+Repository = "https://github.com/stoa-org/stoa"
+Documentation = "https://docs.onstoa.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["stoa"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[[tool.mypy.overrides]]
+module = ["elevenlabs.*", "uuid_utils"]
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "live: tests that require real services (control on :8000, events on :8001)",
+]

onstoa-0.2.0/stoa/__init__.py

@@ -0,0 +1,82 @@
+from stoa.client import Stoa
+from stoa.connect import (
+    ConnectTokenClaims,
+    verify_connect_token,
+)
+from stoa.embedded import (
+    EmbeddedMembershipResult,
+)
+from stoa.events import (
+    AnthropicMessagesPayload,
+    CustomPayload,
+    DeepgramTranscriptionPayload,
+    DeepgramTTSPayload,
+    ElevenLabsSTSPayload,
+    ElevenLabsTTSPayload,
+    ElevenLabsVoiceClonePayload,
+    EventPayload,
+    EventType,
+    OpenAIAudioSpeechPayload,
+    OpenAIAudioTranscriptionPayload,
+    OpenAIChatCompletionPayload,
+    OpenAICompletionPayload,
+    OpenAIEmbeddingPayload,
+    OpenAIImageGenerationPayload,
+    OpenRouterChatCompletionPayload,
+    UsageEvent,
+    UsageEventBatch,
+)
+from stoa.exceptions import (
+    InsufficientBalanceError,
+    StoaAPIError,
+    StoaError,
+    UserNotFoundError,
+)
+from stoa.install import (
+    InstallExchangeResult,
+    InstallPublicKey,
+    InstallTokenClaims,
+    verify_install_token,
+)
+
+__all__ = [
+    # Client
+    "Stoa",
+    # Events
+    "EventType",
+    "EventPayload",
+    "UsageEvent",
+    "UsageEventBatch",
+    # Payloads
+    "OpenAIChatCompletionPayload",
+    "OpenAICompletionPayload",
+    "OpenAIEmbeddingPayload",
+    "OpenAIImageGenerationPayload",
+    "OpenAIAudioTranscriptionPayload",
+    "OpenAIAudioSpeechPayload",
+    "AnthropicMessagesPayload",
+    "OpenRouterChatCompletionPayload",
+    "ElevenLabsTTSPayload",
+    "ElevenLabsVoiceClonePayload",
+    "ElevenLabsSTSPayload",
+    "DeepgramTranscriptionPayload",
+    "DeepgramTTSPayload",
+    "CustomPayload",
+    # Exceptions
+    "StoaError",
+    "StoaAPIError",
+    "InsufficientBalanceError",
+    "UserNotFoundError",
+    # Install flow
+    "verify_install_token",
+    "InstallTokenClaims",
+    "InstallPublicKey",
+    "InstallExchangeResult",
+    # Connect flow
+    "verify_connect_token",
+    "ConnectTokenClaims",
+    # Vetted member registration
+    "EmbeddedMembershipResult",
+]
+
+__version__ = "0.2.0"