profy-sdk 0.1.0__py3-none-any.whl

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/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/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/contrib/__init__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+profy/__init__.py,sha256=pfaj0CDnxWYVPopT8xDdlhI09DPu1C0rCmTrzJ6C9ZM,444
+profy/auth.py,sha256=RMm0elSq0yVIMdCA1hGMgfryOg_pyhCnpeoYbE2Z3ZM,774
+profy/client.py,sha256=75QRY7Bl7_bIekM7he6rzeEI3lfAcYh44j0teN4-lLs,8353
+profy/exceptions.py,sha256=ZA8IC3A6vmJeiHYc3kXBZdX_C7XkXdM7KgiYC4K4Kn0,1233
+profy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profy/contrib/__init__.py,sha256=QrU2m7noMzcc9yBWJtxV4RudI_dlwC9KtEjiZQKvRv4,81
+profy/contrib/sqlalchemy.py,sha256=FApd3pDXTXikwlLUt2CRn-ns0hCugD7TGSLbu0yTRe4,6704
+profy_sdk-0.1.0.dist-info/METADATA,sha256=FsY2m--AL-rgK43_8VoTwzR1PUTC1RtDLE5STAvWFZc,4729
+profy_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+profy_sdk-0.1.0.dist-info/RECORD,,

profy_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any