profy-sdk 0.1.0__tar.gz

profy_sdk-0.1.0/.gitignore

@@ -0,0 +1,279 @@
+# =============================================================================
+# Profy Monorepo .gitignore
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Global / 通用
+# -----------------------------------------------------------------------------
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+pnpm-lock.yaml
+
+# Environment files
+!.env*
+*.pem
+
+# Core: local / server-only secrets (never commit)
+services/core/.env.local
+services/core/.env.secrets
+services/agent-runtime/.env.secrets
+**/.env.secrets
+
+
+
+
+# -----------------------------------------------------------------------------
+# Static assets served from CDN (too large for Git)
+# -----------------------------------------------------------------------------
+apps/web/public/images/
+
+# -----------------------------------------------------------------------------
+# Web (Next.js / Frontend)
+# -----------------------------------------------------------------------------
+
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Next.js
+.next/
+web/.next/
+out/
+web/out/
+
+# Vite
+web/dist/
+web/.vite/
+web/coverage/
+coverage/
+tests/eval/golden/report-*.json
+tests/e2e/playwright-report/
+tests/e2e/test-results/
+*.local
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+
+# Drizzle migrations (auto-generated, should be committed carefully)
+# Uncomment if you want to ignore all migrations:
+# apps/web/drizzle/*.sql
+# apps/web/drizzle/meta/*.json
+
+# -----------------------------------------------------------------------------
+# AI-Backend (Python)
+# -----------------------------------------------------------------------------
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv
+venv/
+env.bak/
+venv.bak/
+
+# Package manager
+uv.lock
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+/downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask
+instance/
+.webassets-cache
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter / IPython
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath
+*.sage.py
+
+# Milvus Lite data
+data/
+*.db
+
+# Spyder / Rope
+.spyderproject
+.spyproject
+.ropeproject
+
+# mkdocs
+/site
+
+# -----------------------------------------------------------------------------
+# Desktop (Electron / Tauri)
+# -----------------------------------------------------------------------------
+
+# (详细规则见 apps/desktop/.gitignore)
+
+# -----------------------------------------------------------------------------
+# iOS (Xcode / Swift)
+# -----------------------------------------------------------------------------
+
+# Xcode - 用户数据 (个人偏好，不应提交)
+xcuserdata/
+*.xcuserstate
+
+# Xcode - 构建产物
+DerivedData/
+
+# SourceKit-LSP (由 setup.sh 动态生成)
+buildServer.json
+
+# -----------------------------------------------------------------------------
+# Chrome Extension (Plasmo)
+# -----------------------------------------------------------------------------
+
+.plasmo/
+apps/browser-extension/build/
+
+# -----------------------------------------------------------------------------
+# Documentation (Mintlify)
+# -----------------------------------------------------------------------------
+.mintlify/
+
+# -----------------------------------------------------------------------------
+# Docker Compose per-service env (generated by deploy/standalone/environments/generate.sh)
+deploy/standalone/environments/*.generated.env
+
+# LiteLLM (model config now in DB, no config files needed)
+
+# K8s secrets (generated, never commit)
+deploy/k8s/generated/secrets/
+deploy/k8s/kubeconfig.yaml
+
+# K8s configmaps (generated but git-tracked — do NOT add to gitignore)
+
+# Archives
+# -----------------------------------------------------------------------------
+*.zip
+*.sql.gz
+*.sql.bz2
+*.dump
+
+# SSL certificates (never commit private keys)
+deploy/standalone/ssl/
+
+# -----------------------------------------------------------------------------
+# External reference repos (cloned for API research, not part of Profy)
+# -----------------------------------------------------------------------------
+lark-openapi-mcp/
+feishu-cli/
+openclaw-lark/

profy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: profy-sdk
+Version: 0.1.0
+Summary: Profy App SDK — OAuth token management and event reporting
+Project-URL: Homepage, https://profy.cn
+Project-URL: Documentation, https://profy.cn/zh/documentation/sdk-guide
+Project-URL: Repository, https://github.com/profy-ai/profy
+Project-URL: Issues, https://github.com/profy-ai/profy/issues
+License: MIT
+Keywords: billing,events-api,oauth,profy,saas,sdk
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# profy-sdk
+
+Official Python SDK for the [Profy](https://profy.cn) App platform — OAuth token management and event reporting.
+
+## Installation
+
+```bash
+pip install profy-sdk
+
+# With optional SQLAlchemy token storage:
+pip install profy-sdk[sqlalchemy]
+```
+
+## Quick Start
+
+```python
+from profy import ProfyApp
+
+async with ProfyApp(
+    client_id="your-app-id",
+    client_secret="your-app-secret",
+) as profy:
+    # Exchange authorization code for tokens
+    token = await profy.exchange_code(code, "https://your-app.com/callback")
+
+    # Report a billing event
+    await profy.report_event("generate_report", token=token)
+```
+
+### Synchronous Usage
+
+```python
+from profy import ProfyAppSync
+
+with ProfyAppSync(
+    client_id="your-app-id",
+    client_secret="your-app-secret",
+) as profy:
+    token = profy.exchange_code(code, redirect_uri)
+    profy.report_event("generate_report", token=token)
+```
+
+## Features
+
+- **OAuth2 Authorization Code Flow** — exchange codes, refresh tokens automatically
+- **Events API** — report billing events with auto token refresh and retry on 401
+- **Async + Sync** — `ProfyApp` (async) and `ProfyAppSync` (sync) clients
+- **Type hints** — full type annotations, PEP 561 compatible
+- **Minimal dependencies** — only `httpx`
+- **Optional SQLAlchemy integration** — pre-built token model + store
+
+## Token Persistence (Optional)
+
+### Using SQLAlchemy
+
+```python
+from profy import ProfyApp
+from profy.contrib.sqlalchemy import create_token_model, SQLAlchemyTokenStore
+
+# 1. Create the ORM model (auto-creates table with Base.metadata.create_all())
+ProfyOAuthToken = create_token_model(Base)
+
+# 2. Create store
+store = SQLAlchemyTokenStore(async_session_factory, ProfyOAuthToken)
+
+# 3. Initialize SDK with persistence
+profy = ProfyApp(
+    client_id="...",
+    client_secret="...",
+    on_token_refresh=store.on_refresh,
+)
+
+# 4. Save after exchange
+token = await profy.exchange_code(code, redirect_uri)
+await store.save(token.user_id, token, scope="events:write")
+
+# 5. Load later
+saved = await store.load(user_id)
+```
+
+### Custom Storage
+
+```python
+from profy import ProfyApp, TokenData
+
+async def persist_token(token: TokenData):
+    await redis.set(f"profy:{token.user_id}", token.access_token)
+
+profy = ProfyApp(
+    client_id="...",
+    client_secret="...",
+    on_token_refresh=persist_token,
+)
+```
+
+## API Reference
+
+### `ProfyApp` / `ProfyAppSync`
+
+| Method | Description |
+|--------|-------------|
+| `exchange_code(code, redirect_uri)` | Exchange authorization code for tokens |
+| `refresh_token(refresh_token)` | Manually refresh an expired token |
+| `report_event(event_name, *, token, idempotency_key?, metadata?)` | Report a billing event |
+
+### `TokenData`
+
+```python
+@dataclass
+class TokenData:
+    access_token: str
+    refresh_token: str
+    user_id: str
+    expires_at: float  # unix timestamp
+
+    @property
+    def is_expired(self) -> bool: ...
+```
+
+### Exceptions
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `AuthExpired` | 401 | Token expired and refresh failed |
+| `InsufficientBalance` | 402 | User has insufficient credits |
+| `InvalidEvent` | 400 | Event name not configured |
+| `ProfyApiError` | varies | Generic API error |
+
+## Documentation
+
+- [Integration Quickstart](https://profy.cn/zh/documentation/integration-quickstart)
+- [SDK Guide](https://profy.cn/zh/documentation/sdk-guide)
+- [API Reference](https://profy.cn/zh/api/post-token)
+
+## License
+
+MIT

profy_sdk-0.1.0/README.md

@@ -0,0 +1,137 @@
+# profy-sdk
+
+Official Python SDK for the [Profy](https://profy.cn) App platform — OAuth token management and event reporting.
+
+## Installation
+
+```bash
+pip install profy-sdk
+
+# With optional SQLAlchemy token storage:
+pip install profy-sdk[sqlalchemy]
+```
+
+## Quick Start
+
+```python
+from profy import ProfyApp
+
+async with ProfyApp(
+    client_id="your-app-id",
+    client_secret="your-app-secret",
+) as profy:
+    # Exchange authorization code for tokens
+    token = await profy.exchange_code(code, "https://your-app.com/callback")
+
+    # Report a billing event
+    await profy.report_event("generate_report", token=token)
+```
+
+### Synchronous Usage
+
+```python
+from profy import ProfyAppSync
+
+with ProfyAppSync(
+    client_id="your-app-id",
+    client_secret="your-app-secret",
+) as profy:
+    token = profy.exchange_code(code, redirect_uri)
+    profy.report_event("generate_report", token=token)
+```
+
+## Features
+
+- **OAuth2 Authorization Code Flow** — exchange codes, refresh tokens automatically
+- **Events API** — report billing events with auto token refresh and retry on 401
+- **Async + Sync** — `ProfyApp` (async) and `ProfyAppSync` (sync) clients
+- **Type hints** — full type annotations, PEP 561 compatible
+- **Minimal dependencies** — only `httpx`
+- **Optional SQLAlchemy integration** — pre-built token model + store
+
+## Token Persistence (Optional)
+
+### Using SQLAlchemy
+
+```python
+from profy import ProfyApp
+from profy.contrib.sqlalchemy import create_token_model, SQLAlchemyTokenStore
+
+# 1. Create the ORM model (auto-creates table with Base.metadata.create_all())
+ProfyOAuthToken = create_token_model(Base)
+
+# 2. Create store
+store = SQLAlchemyTokenStore(async_session_factory, ProfyOAuthToken)
+
+# 3. Initialize SDK with persistence
+profy = ProfyApp(
+    client_id="...",
+    client_secret="...",
+    on_token_refresh=store.on_refresh,
+)
+
+# 4. Save after exchange
+token = await profy.exchange_code(code, redirect_uri)
+await store.save(token.user_id, token, scope="events:write")
+
+# 5. Load later
+saved = await store.load(user_id)
+```
+
+### Custom Storage
+
+```python
+from profy import ProfyApp, TokenData
+
+async def persist_token(token: TokenData):
+    await redis.set(f"profy:{token.user_id}", token.access_token)
+
+profy = ProfyApp(
+    client_id="...",
+    client_secret="...",
+    on_token_refresh=persist_token,
+)
+```
+
+## API Reference
+
+### `ProfyApp` / `ProfyAppSync`
+
+| Method | Description |
+|--------|-------------|
+| `exchange_code(code, redirect_uri)` | Exchange authorization code for tokens |
+| `refresh_token(refresh_token)` | Manually refresh an expired token |
+| `report_event(event_name, *, token, idempotency_key?, metadata?)` | Report a billing event |
+
+### `TokenData`
+
+```python
+@dataclass
+class TokenData:
+    access_token: str
+    refresh_token: str
+    user_id: str
+    expires_at: float  # unix timestamp
+
+    @property
+    def is_expired(self) -> bool: ...
+```
+
+### Exceptions
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `AuthExpired` | 401 | Token expired and refresh failed |
+| `InsufficientBalance` | 402 | User has insufficient credits |
+| `InvalidEvent` | 400 | Event name not configured |
+| `ProfyApiError` | varies | Generic API error |
+
+## Documentation
+
+- [Integration Quickstart](https://profy.cn/zh/documentation/integration-quickstart)
+- [SDK Guide](https://profy.cn/zh/documentation/sdk-guide)
+- [API Reference](https://profy.cn/zh/api/post-token)
+
+## License
+
+MIT

profy_sdk-0.1.0/profy/__init__.py

@@ -0,0 +1,22 @@
+"""Profy App SDK — OAuth + Events API client for Profy App developers."""
+
+from .auth import TokenData
+from .client import ProfyApp, ProfyAppSync
+from .exceptions import (
+    AuthExpired,
+    InsufficientBalance,
+    InvalidEvent,
+    ProfyApiError,
+    ProfyError,
+)
+
+__all__ = [
+    "ProfyApp",
+    "ProfyAppSync",
+    "TokenData",
+    "ProfyError",
+    "ProfyApiError",
+    "AuthExpired",
+    "InsufficientBalance",
+    "InvalidEvent",
+]

profy_sdk-0.1.0/profy/auth.py

@@ -0,0 +1,30 @@
+"""Token data model and refresh utilities."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class TokenData:
+    """Holds an OAuth token pair with metadata."""
+
+    access_token: str
+    refresh_token: str
+    user_id: str
+    expires_at: float  # unix timestamp
+
+    @property
+    def is_expired(self) -> bool:
+        return time.time() >= self.expires_at - 30  # 30s safety buffer
+
+    @classmethod
+    def from_response(cls, data: dict) -> "TokenData":
+        expires_in = int(data.get("expires_in", 3600))
+        return cls(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            user_id=data["user_id"],
+            expires_at=time.time() + expires_in,
+        )

profy_sdk-0.1.0/profy/client.py

@@ -0,0 +1,263 @@
+"""Profy App SDK — async client for OAuth + Events API."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import httpx
+
+from .auth import TokenData
+from .exceptions import (
+    AuthExpired,
+    InsufficientBalance,
+    InvalidEvent,
+    ProfyApiError,
+)
+
+DEFAULT_BASE_URL = "https://profy.cn"
+
+
+class ProfyApp:
+    """Async Profy App client.
+
+    Handles OAuth token exchange, automatic refresh, and event reporting.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        on_token_refresh: Callable[[TokenData], None] | None = None,
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.base_url = base_url.rstrip("/")
+        self.on_token_refresh = on_token_refresh
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=30.0,
+            headers={"User-Agent": "profy-sdk-python/0.1.0"},
+        )
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "ProfyApp":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def exchange_code(self, code: str, redirect_uri: str) -> TokenData:
+        """Exchange an authorization code for access + refresh tokens."""
+        resp = await self._http.post(
+            "/oauth/token",
+            json={
+                "grant_type": "authorization_code",
+                "code": code,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "redirect_uri": redirect_uri,
+            },
+        )
+        if resp.status_code != 200:
+            raise ProfyApiError(resp.status_code, resp.json())
+        data = resp.json()
+        if "data" in data:
+            data = data["data"]
+        return TokenData.from_response(data)
+
+    async def refresh_token(self, refresh_token: str) -> TokenData:
+        """Use a refresh token to obtain a new access token."""
+        resp = await self._http.post(
+            "/oauth/token",
+            json={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+        )
+        if resp.status_code != 200:
+            raise AuthExpired()
+        data = resp.json()
+        if "data" in data:
+            data = data["data"]
+        token = TokenData.from_response(data)
+        if self.on_token_refresh:
+            self.on_token_refresh(token)
+        return token
+
+    async def report_event(
+        self,
+        event_name: str,
+        *,
+        token: TokenData,
+        idempotency_key: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> dict:
+        """Report a billing event. Auto-refreshes token if expired.
+
+        Args:
+            event_name: The meter event name defined in your profy.json.
+            token: User's OAuth token (auto-refreshes if expired).
+            idempotency_key: Dedup key (auto-generated from event+timestamp if omitted).
+            metadata: Optional key-value pairs attached to this event.
+        """
+        import uuid
+
+        active_token = token
+        if active_token.is_expired:
+            active_token = await self.refresh_token(token.refresh_token)
+
+        idem_key = idempotency_key or f"{event_name}:{uuid.uuid4().hex[:16]}"
+        payload: dict = {"event": event_name, "idempotency_key": idem_key}
+        if metadata:
+            payload["metadata"] = metadata
+
+        resp = await self._http.post(
+            "/openapi/v1/events",
+            headers={"Authorization": f"Bearer {active_token.access_token}"},
+            json=payload,
+        )
+
+        if resp.status_code == 401:
+            try:
+                active_token = await self.refresh_token(token.refresh_token)
+            except AuthExpired:
+                raise
+            resp = await self._http.post(
+                "/openapi/v1/events",
+                headers={"Authorization": f"Bearer {active_token.access_token}"},
+                json=payload,
+            )
+
+        if resp.status_code == 402:
+            raise InsufficientBalance()
+        if resp.status_code == 400:
+            raise InvalidEvent(resp.json().get("message", "Invalid event"))
+        if resp.status_code == 429:
+            raise ProfyApiError(429, resp.json())
+        if resp.status_code >= 400:
+            raise ProfyApiError(resp.status_code, resp.json())
+
+        return resp.json()
+
+
+class ProfyAppSync:
+    """Synchronous wrapper around ProfyApp for non-async contexts."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        on_token_refresh: Callable[[TokenData], None] | None = None,
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.base_url = base_url.rstrip("/")
+        self.on_token_refresh = on_token_refresh
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=30.0,
+            headers={"User-Agent": "profy-sdk-python/0.1.0"},
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "ProfyAppSync":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def exchange_code(self, code: str, redirect_uri: str) -> TokenData:
+        resp = self._http.post(
+            "/oauth/token",
+            json={
+                "grant_type": "authorization_code",
+                "code": code,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "redirect_uri": redirect_uri,
+            },
+        )
+        if resp.status_code != 200:
+            raise ProfyApiError(resp.status_code, resp.json())
+        data = resp.json()
+        if "data" in data:
+            data = data["data"]
+        return TokenData.from_response(data)
+
+    def refresh_token(self, refresh_token: str) -> TokenData:
+        resp = self._http.post(
+            "/oauth/token",
+            json={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+        )
+        if resp.status_code != 200:
+            raise AuthExpired()
+        data = resp.json()
+        if "data" in data:
+            data = data["data"]
+        token = TokenData.from_response(data)
+        if self.on_token_refresh:
+            self.on_token_refresh(token)
+        return token
+
+    def report_event(
+        self,
+        event_name: str,
+        *,
+        token: TokenData,
+        idempotency_key: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> dict:
+        """Report a billing event (sync version)."""
+        import uuid
+
+        active_token = token
+        if active_token.is_expired:
+            active_token = self.refresh_token(token.refresh_token)
+
+        idem_key = idempotency_key or f"{event_name}:{uuid.uuid4().hex[:16]}"
+        payload: dict = {"event": event_name, "idempotency_key": idem_key}
+        if metadata:
+            payload["metadata"] = metadata
+
+        resp = self._http.post(
+            "/openapi/v1/events",
+            headers={"Authorization": f"Bearer {active_token.access_token}"},
+            json=payload,
+        )
+
+        if resp.status_code == 401:
+            try:
+                active_token = self.refresh_token(token.refresh_token)
+            except AuthExpired:
+                raise
+            resp = self._http.post(
+                "/openapi/v1/events",
+                headers={"Authorization": f"Bearer {active_token.access_token}"},
+                json=payload,
+            )
+
+        if resp.status_code == 402:
+            raise InsufficientBalance()
+        if resp.status_code == 400:
+            raise InvalidEvent(resp.json().get("message", "Invalid event"))
+        if resp.status_code == 429:
+            raise ProfyApiError(429, resp.json())
+        if resp.status_code >= 400:
+            raise ProfyApiError(resp.status_code, resp.json())
+
+        return resp.json()

profy_sdk-0.1.0/profy/contrib/__init__.py

@@ -0,0 +1 @@
+"""Optional contrib modules — storage backends for Profy token persistence."""

profy_sdk-0.1.0/profy/contrib/sqlalchemy.py

@@ -0,0 +1,186 @@
+"""Optional SQLAlchemy token storage for Profy SDK.
+
+Usage:
+    from sqlalchemy.orm import DeclarativeBase
+    from profy.contrib.sqlalchemy import create_token_model, SQLAlchemyTokenStore
+
+    class Base(DeclarativeBase):
+        pass
+
+    ProfyOAuthToken = create_token_model(Base)
+    # Base.metadata.create_all(engine) will auto-create the table.
+
+    # For automatic token persistence + refresh:
+    store = SQLAlchemyTokenStore(session_factory)
+    app = ProfyApp(client_id=..., client_secret=..., on_token_refresh=store.on_refresh)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any, Callable
+
+from ..auth import TokenData
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+    from sqlalchemy.orm import DeclarativeBase, Session
+
+
+def create_token_model(Base: type[Any], table_name: str = "profy_oauth_token"):
+    """Dynamically create a ProfyOAuthToken ORM model bound to the given Base.
+
+    The table is created when you call Base.metadata.create_all().
+    No migration tool needed for new databases.
+
+    Args:
+        Base: Your SQLAlchemy DeclarativeBase class.
+        table_name: Override table name if needed.
+
+    Returns:
+        The ORM model class (also registered on Base).
+    """
+    from sqlalchemy import Column, DateTime, Integer, String, Text
+
+    class ProfyOAuthToken(Base):  # type: ignore[valid-type]
+        __tablename__ = table_name
+
+        id = Column(Integer, primary_key=True, index=True)
+        profy_user_id = Column(String(64), unique=True, nullable=False, index=True)
+        access_token = Column(Text, nullable=False)
+        refresh_token = Column(Text, nullable=False)
+        expires_at = Column(DateTime, nullable=False)
+        scope = Column(String(255), nullable=True)
+        created_at = Column(DateTime, default=datetime.utcnow)
+        updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+        def to_token_data(self) -> TokenData:
+            return TokenData(
+                access_token=self.access_token,
+                refresh_token=self.refresh_token,
+                user_id=self.profy_user_id,
+                expires_at=self.expires_at.timestamp() if self.expires_at else 0,
+            )
+
+    return ProfyOAuthToken
+
+
+class SQLAlchemyTokenStore:
+    """Async token store backed by SQLAlchemy.
+
+    Provides save/load/on_refresh for use with ProfyApp.
+
+    Args:
+        session_factory: Callable that returns an AsyncSession (e.g. async_sessionmaker()).
+        model: The ORM model class created by create_token_model().
+    """
+
+    def __init__(self, session_factory: Callable[[], Any], model: type[Any]):
+        self._session_factory = session_factory
+        self._model = model
+
+    async def save(self, user_id: str, token: TokenData, scope: str | None = None) -> None:
+        """Upsert token for a Profy user."""
+        from sqlalchemy import select
+
+        async with self._session_factory() as session:
+            result = await session.execute(
+                select(self._model).where(self._model.profy_user_id == user_id)
+            )
+            record = result.scalar_one_or_none()
+            expires_at = datetime.utcfromtimestamp(token.expires_at)
+
+            if record:
+                record.access_token = token.access_token
+                record.refresh_token = token.refresh_token
+                record.expires_at = expires_at
+                record.scope = scope
+            else:
+                record = self._model(
+                    profy_user_id=user_id,
+                    access_token=token.access_token,
+                    refresh_token=token.refresh_token,
+                    expires_at=expires_at,
+                    scope=scope,
+                )
+                session.add(record)
+
+            await session.commit()
+
+    async def load(self, user_id: str) -> TokenData | None:
+        """Load token for a Profy user. Returns None if not found."""
+        from sqlalchemy import select
+
+        async with self._session_factory() as session:
+            result = await session.execute(
+                select(self._model).where(self._model.profy_user_id == user_id)
+            )
+            record = result.scalar_one_or_none()
+            if not record:
+                return None
+            return record.to_token_data()
+
+    def on_refresh(self, token: TokenData) -> None:
+        """Callback for ProfyApp.on_token_refresh — persists refreshed tokens.
+
+        Since on_token_refresh is sync, we fire-and-forget via a background task.
+        For guaranteed persistence, call save() directly in your async code.
+        """
+        import asyncio
+
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(self.save(token.user_id, token))
+        except RuntimeError:
+            pass
+
+
+class SQLAlchemyTokenStoreSync:
+    """Sync token store for use with ProfyAppSync."""
+
+    def __init__(self, session_factory: Callable[[], Any], model: type[Any]):
+        self._session_factory = session_factory
+        self._model = model
+
+    def save(self, user_id: str, token: TokenData, scope: str | None = None) -> None:
+        from sqlalchemy import select
+
+        with self._session_factory() as session:
+            result = session.execute(
+                select(self._model).where(self._model.profy_user_id == user_id)
+            )
+            record = result.scalar_one_or_none()
+            expires_at = datetime.utcfromtimestamp(token.expires_at)
+
+            if record:
+                record.access_token = token.access_token
+                record.refresh_token = token.refresh_token
+                record.expires_at = expires_at
+                record.scope = scope
+            else:
+                record = self._model(
+                    profy_user_id=user_id,
+                    access_token=token.access_token,
+                    refresh_token=token.refresh_token,
+                    expires_at=expires_at,
+                    scope=scope,
+                )
+                session.add(record)
+
+            session.commit()
+
+    def load(self, user_id: str) -> TokenData | None:
+        from sqlalchemy import select
+
+        with self._session_factory() as session:
+            result = session.execute(
+                select(self._model).where(self._model.profy_user_id == user_id)
+            )
+            record = result.scalar_one_or_none()
+            if not record:
+                return None
+            return record.to_token_data()
+
+    def on_refresh(self, token: TokenData) -> None:
+        """Sync callback for ProfyAppSync.on_token_refresh."""
+        self.save(token.user_id, token)

profy_sdk-0.1.0/profy/exceptions.py

@@ -0,0 +1,39 @@
+"""Profy SDK exception hierarchy."""
+
+
+class ProfyError(Exception):
+    """Base exception for all Profy SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthExpired(ProfyError):
+    """Access token expired and refresh also failed."""
+
+    def __init__(self, message: str = "Authentication expired, re-authorize required"):
+        super().__init__(message, status_code=401)
+
+
+class InsufficientBalance(ProfyError):
+    """User does not have enough credits for this event."""
+
+    def __init__(self, message: str = "Insufficient balance"):
+        super().__init__(message, status_code=402)
+
+
+class InvalidEvent(ProfyError):
+    """The event_name is not configured for this app."""
+
+    def __init__(self, message: str = "Invalid event name"):
+        super().__init__(message, status_code=400)
+
+
+class ProfyApiError(ProfyError):
+    """Generic API error with status code and response body."""
+
+    def __init__(self, status_code: int, body: dict | None = None):
+        self.body = body or {}
+        msg = self.body.get("message", f"API error {status_code}")
+        super().__init__(msg, status_code=status_code)

profy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "profy-sdk"
+version = "0.1.0"
+description = "Profy App SDK — OAuth token management and event reporting"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["profy", "oauth", "sdk", "events-api", "billing", "saas"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://profy.cn"
+Documentation = "https://profy.cn/zh/documentation/sdk-guide"
+Repository = "https://github.com/profy-ai/profy"
+Issues = "https://github.com/profy-ai/profy/issues"
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["profy"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"