ascendkit 0.1.0__tar.gz

ascendkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

ascendkit-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Environment
+.env
+.env.*
+!.env.example
+.venv/
+
+# OS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.ruff_cache/
+.pytest_cache/

ascendkit-0.1.0/CLAUDE.md

@@ -0,0 +1,22 @@
+# SDK Python — `ascendkit`
+
+Python 3.10+ SDK. httpx (async), published to PyPI.
+
+## Commands
+```bash
+pip install -e ".[dev]"      # Install editable
+pytest                       # Tests
+ruff check . && ruff format .  # Lint + format
+mypy ascendkit/              # Type checking
+```
+
+## Rules
+- MUST use `httpx` — not `requests`. Support both sync and async patterns.
+- Logger: drop-in for `logging` module. Keyword args for context: `logger.info("msg", port=3000)`
+- Batch logs (5s / 100 events) via `POST /api/logs/ingest` — NEVER send one-at-a-time
+- Flush on interpreter shutdown via `atexit`
+- Public API through `ascendkit/__init__.py` — internal modules prefixed `_` (e.g., `_client.py`)
+- Typed exceptions (`AscendKitError`, `AuthenticationError`) — NEVER swallow errors
+- All public functions MUST have type annotations
+- Gracefully handle network failures on flush — buffer and retry, NEVER crash host app
+- In async frameworks, use `httpx.AsyncClient` — sync client blocks the event loop

ascendkit-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: ascendkit
+Version: 0.1.0
+Summary: AscendKit Python SDK
+Project-URL: Homepage, https://ascendkit.dev
+Project-URL: Documentation, https://ascendkit.dev/docs
+Author: ascendkit.dev
+License: MIT
+Keywords: ascendkit,auth,b2b,saas,sdk,webhooks
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.10.0

ascendkit-0.1.0/ascendkit/__init__.py

@@ -0,0 +1,23 @@
+"""AscendKit Python SDK."""
+
+from ascendkit._access_token import AccessTokenVerifier
+from ascendkit._client import AscendKit, AsyncAscendKit
+from ascendkit._errors import AscendKitError, AuthError, NotFoundError, ValidationError
+from ascendkit._webhooks import verify_webhook_signature
+from ascendkit.auth import AuthClient, AsyncAuthClient
+from ascendkit.fastapi import get_current_user_dependency, get_current_user
+
+__all__ = [
+    "AccessTokenVerifier",
+    "AscendKit",
+    "AsyncAscendKit",
+    "AuthClient",
+    "AsyncAuthClient",
+    "AscendKitError",
+    "AuthError",
+    "NotFoundError",
+    "ValidationError",
+    "verify_webhook_signature",
+    "get_current_user_dependency",
+    "get_current_user",
+]

ascendkit-0.1.0/ascendkit/_access_token.py

@@ -0,0 +1,103 @@
+"""Access token verification with JWKS caching."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient
+
+from ascendkit._client import _DEFAULT_API_URL
+from ascendkit._errors import AuthError
+_JWKS_CACHE_TTL = 3600  # 1 hour, matches server Cache-Control
+
+
+class AccessTokenVerifier:
+    """Verify AscendKit RS256 access tokens using JWKS.
+
+    Caches the JWKS response in memory for 1 hour. Thread-safe.
+
+    The ``public_key`` parameter is optional — if omitted, the constructor
+    reads ``ASCENDKIT_ENV_KEY`` from the environment. Raises ``ValueError``
+    if neither is provided.
+
+    Usage (sync)::
+
+        verifier = AccessTokenVerifier()
+        claims = verifier.verify(token)
+        print(claims["sub"])  # usr_...
+
+    Usage (async)::
+
+        verifier = AccessTokenVerifier()
+        claims = await verifier.verify_async(token)
+
+    Usage with FastAPI::
+
+        from fastapi import Depends, Header
+
+        verifier = AccessTokenVerifier()
+
+        async def get_current_user(authorization: str = Header()) -> dict:
+            token = authorization.removeprefix("Bearer ")
+            return await verifier.verify_async(token)
+    """
+
+    def __init__(
+        self,
+        public_key: str | None = None,
+        api_url: str = _DEFAULT_API_URL,
+        cache_ttl: int = _JWKS_CACHE_TTL,
+    ) -> None:
+        resolved_key = public_key or os.environ.get("ASCENDKIT_ENV_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "AscendKit AccessTokenVerifier: missing public key. "
+                "Pass public_key or set ASCENDKIT_ENV_KEY."
+            )
+        self._public_key = resolved_key
+        self._jwks_url = f"{api_url}/api/.well-known/jwks.json?pk={resolved_key}"
+        self._jwks_client = PyJWKClient(
+            self._jwks_url,
+            cache_jwk_set=True,
+            lifespan=cache_ttl,
+            headers={"User-Agent": "ascendkit-python/1.0"},
+        )
+
+    def verify(self, token: str) -> dict[str, Any]:
+        """Verify an access token synchronously. Returns decoded claims.
+
+        Raises:
+            AuthError: If the token is invalid, expired, or signature fails.
+        """
+        try:
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+            claims: dict[str, Any] = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                issuer="ascendkit",
+            )
+            return claims
+        except jwt.ExpiredSignatureError:
+            raise AuthError("Access token expired", status_code=401)
+        except jwt.exceptions.PyJWKClientConnectionError:
+            raise AuthError(
+                f"Failed to fetch JWKS from {self._jwks_url} — "
+                "is the AscendKit backend reachable?",
+                status_code=503,
+            )
+        except jwt.InvalidTokenError as e:
+            raise AuthError(f"Invalid access token: {e}", status_code=401)
+
+    async def verify_async(self, token: str) -> dict[str, Any]:
+        """Verify an access token asynchronously. Returns decoded claims.
+
+        Uses the same JWKS cache as ``verify()``. The JWKS HTTP fetch is
+        synchronous (PyJWKClient limitation) but runs in a thread pool to
+        avoid blocking the event loop. Cached results return immediately.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.verify, token)

ascendkit-0.1.0/ascendkit/_analytics.py

@@ -0,0 +1,201 @@
+"""Server-side analytics client for AscendKit.
+
+.. deprecated::
+    This module is not in use. Analytics has moved to the JS SDK
+    (@ascendkit/nextjs). This file is kept for reference only.
+
+Tracks events from your backend with trusted identity (secret key auth).
+Events are queued in-memory and flushed in batches via a background thread.
+
+Example::
+
+    from ascendkit import Analytics
+
+    analytics = Analytics("sk_prod_abc123")
+    analytics.track("usr_456", "checkout.completed", {"orderId": "ord_789"})
+
+    # Events flush automatically every 30s or when batch size (10) is reached.
+    # On process exit, remaining events are flushed automatically via atexit.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import os
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any
+from urllib.request import Request, urlopen
+from urllib.error import URLError
+
+from ascendkit._client import _DEFAULT_API_URL
+from ascendkit._version import SDK_VERSION
+
+logger = logging.getLogger("ascendkit.analytics")
+DEFAULT_FLUSH_INTERVAL = 30.0  # seconds
+DEFAULT_BATCH_SIZE = 10
+MAX_RETRY_ATTEMPTS = 3
+
+
+class Analytics:
+    """Server-side analytics client with background flushing.
+
+    The ``secret_key`` parameter is optional — if omitted, the constructor
+    reads ``ASCENDKIT_SECRET_KEY`` from the environment. Raises ``ValueError``
+    if neither is provided.
+
+    Args:
+        secret_key: Your project's secret key (sk_prod_...). Falls back to ASCENDKIT_SECRET_KEY env var.
+        api_url: AscendKit API base URL. Defaults to https://api.ascendkit.dev.
+        flush_interval: Seconds between automatic flushes. Defaults to 30.
+        batch_size: Max events before auto-flush. Defaults to 10.
+
+    Example::
+
+        analytics = Analytics()
+        analytics.track("usr_456", "feature.used", {"feature": "dashboard"})
+        analytics.shutdown()
+    """
+
+    def __init__(
+        self,
+        secret_key: str | None = None,
+        *,
+        api_url: str = _DEFAULT_API_URL,
+        flush_interval: float = DEFAULT_FLUSH_INTERVAL,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+    ) -> None:
+        resolved_key = secret_key or os.environ.get("ASCENDKIT_SECRET_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "AscendKit Analytics: missing secret key. "
+                "Pass secret_key or set ASCENDKIT_SECRET_KEY."
+            )
+        self._secret_key = resolved_key
+        self._api_url = api_url.rstrip("/")
+        self._flush_interval = flush_interval
+        self._batch_size = batch_size
+        self._queue: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._running = True
+
+        # Background flush thread
+        self._flush_thread = threading.Thread(target=self._flush_loop, daemon=True)
+        self._flush_thread.start()
+
+        # Register atexit handler for graceful shutdown
+        atexit.register(self.shutdown)
+
+    def track(
+        self,
+        user_id: str,
+        event_name: str,
+        properties: dict[str, Any] | None = None,
+    ) -> None:
+        """Queue a server-side event for a user.
+
+        Args:
+            user_id: The user ID (usr_ prefixed).
+            event_name: Event name (e.g. "checkout.completed").
+            properties: Optional event properties.
+
+        Example::
+
+            analytics.track("usr_456", "checkout.completed", {"total": 99.99})
+        """
+        prefixed_name = event_name if event_name.startswith("app.") else f"app.{event_name}"
+        event = {
+            "eventName": prefixed_name,
+            "userId": user_id,
+            "properties": properties,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "context": {
+                "sdk": "python",
+                "sdkVersion": SDK_VERSION,
+            },
+        }
+
+        batch: list[dict[str, Any]] | None = None
+        with self._lock:
+            self._queue.append(event)
+            if len(self._queue) >= self._batch_size:
+                batch = self._queue[:]
+                self._queue.clear()
+
+        # Flush outside the lock if batch size reached
+        if batch is not None:
+            self._send_batch(batch, attempt=0)
+
+    def flush(self) -> None:
+        """Manually flush the event queue."""
+        with self._lock:
+            if not self._queue:
+                return
+            batch = self._queue[:]
+            self._queue.clear()
+
+        self._send_batch(batch, attempt=0)
+
+    def shutdown(self) -> None:
+        """Gracefully shut down: stop the flush thread and flush remaining events."""
+        self._running = False
+        self.flush()
+
+    # -----------------------------------------------------------------------
+    # Internal
+    # -----------------------------------------------------------------------
+
+    def _flush_loop(self) -> None:
+        """Background thread that periodically flushes the queue."""
+        while self._running:
+            time.sleep(self._flush_interval)
+            try:
+                self.flush()
+            except Exception:
+                logger.debug("Flush failed in background thread", exc_info=True)
+
+    def _send_batch(self, batch: list[dict[str, Any]], attempt: int) -> None:
+        """Send a batch of events to the API with retry."""
+        if not batch:
+            return
+
+        url = f"{self._api_url}/api/v1/events"
+        # Convert internal format to backend EventBatchRequest schema
+        api_batch = [
+            {"event": e["eventName"], "userId": e["userId"], "properties": e.get("properties"), "timestamp": e.get("timestamp")}
+            for e in batch
+        ]
+        payload = json.dumps({"batch": api_batch}).encode("utf-8")
+
+        req = Request(
+            url,
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "X-AscendKit-Secret-Key": self._secret_key,
+                "X-AscendKit-Client-Version": f"python/{SDK_VERSION}",
+            },
+            method="POST",
+        )
+
+        try:
+            with urlopen(req, timeout=10) as response:
+                if response.status >= 400:
+                    raise URLError(f"HTTP {response.status}")
+        except Exception:
+            if attempt < MAX_RETRY_ATTEMPTS:
+                delay = (2 ** attempt)  # 1s, 2s, 4s
+                time.sleep(delay)
+                self._send_batch(batch, attempt + 1)
+            else:
+                logger.warning(
+                    "Failed to send %d events after %d retries",
+                    len(batch),
+                    MAX_RETRY_ATTEMPTS,
+                )
+                # Put events back in the queue
+                with self._lock:
+                    self._queue = batch + self._queue

ascendkit-0.1.0/ascendkit/_client.py

@@ -0,0 +1,131 @@
+"""AscendKit API client (sync and async)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from ascendkit._errors import AscendKitError, AuthError, NotFoundError, ValidationError
+from ascendkit._version import SDK_VERSION
+
+logger = logging.getLogger("ascendkit")
+
+_DEFAULT_API_URL = "https://api.ascendkit.dev"
+_VERSION_HEADER = {"X-AscendKit-Client-Version": f"python/{SDK_VERSION}"}
+
+_upgrade_warned = False
+
+
+def _check_upgrade(response: httpx.Response) -> None:
+    global _upgrade_warned
+    if _upgrade_warned:
+        return
+    upgrade = response.headers.get("X-AscendKit-Upgrade")
+    if upgrade == "recommended":
+        latest = response.headers.get("X-AscendKit-Latest-Version", "latest")
+        logger.warning(
+            "A newer SDK version (v%s) is available. "
+            "You are running v%s. Run 'pip install --upgrade ascendkit' to upgrade.",
+            latest,
+            SDK_VERSION,
+        )
+        _upgrade_warned = True
+
+
+def _handle_error(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        body = response.json()
+        detail = body.get("error") or body.get("detail") or str(body)
+    except Exception:
+        detail = response.text
+
+    if response.status_code == 401:
+        raise AuthError(detail, status_code=401)
+    if response.status_code == 404:
+        raise NotFoundError(detail, status_code=404)
+    if response.status_code == 422:
+        raise ValidationError(detail, status_code=422)
+    raise AscendKitError(detail, status_code=response.status_code)
+
+
+class AscendKit:
+    """Synchronous AscendKit client.
+
+    The ``public_key`` parameter is optional — if omitted, the constructor
+    reads ``ASCENDKIT_ENV_KEY`` from the environment.
+    """
+
+    def __init__(self, public_key: str | None = None, api_url: str = _DEFAULT_API_URL) -> None:
+        resolved_key = public_key or os.environ.get("ASCENDKIT_ENV_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "AscendKit: missing public key. Pass public_key or set ASCENDKIT_ENV_KEY."
+            )
+        self.public_key = resolved_key
+        self._client = httpx.Client(
+            base_url=api_url,
+            headers={
+                "X-AscendKit-Public-Key": resolved_key,
+                **_VERSION_HEADER,
+            },
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self._client.request(method, path, **kwargs)
+        _check_upgrade(response)
+        _handle_error(response)
+        body = response.json()
+        return body.get("data", body)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> AscendKit:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncAscendKit:
+    """Asynchronous AscendKit client.
+
+    The ``public_key`` parameter is optional — if omitted, the constructor
+    reads ``ASCENDKIT_ENV_KEY`` from the environment.
+    """
+
+    def __init__(self, public_key: str | None = None, api_url: str = _DEFAULT_API_URL) -> None:
+        resolved_key = public_key or os.environ.get("ASCENDKIT_ENV_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "AscendKit: missing public key. Pass public_key or set ASCENDKIT_ENV_KEY."
+            )
+        self.public_key = resolved_key
+        self._client = httpx.AsyncClient(
+            base_url=api_url,
+            headers={
+                "X-AscendKit-Public-Key": resolved_key,
+                **_VERSION_HEADER,
+            },
+        )
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = await self._client.request(method, path, **kwargs)
+        _check_upgrade(response)
+        _handle_error(response)
+        body = response.json()
+        return body.get("data", body)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAscendKit:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

ascendkit-0.1.0/ascendkit/_errors.py

@@ -0,0 +1,21 @@
+"""AscendKit SDK exceptions."""
+
+
+class AscendKitError(Exception):
+    """Base exception for AscendKit SDK."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(AscendKitError):
+    """Authentication or authorization error."""
+
+
+class NotFoundError(AscendKitError):
+    """Resource not found."""
+
+
+class ValidationError(AscendKitError):
+    """Request validation error."""

ascendkit-0.1.0/ascendkit/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version."""
+
+SDK_VERSION = "0.1.0"

ascendkit-0.1.0/ascendkit/_webhooks.py

@@ -0,0 +1,118 @@
+"""Webhook signature verification for AscendKit.
+
+AscendKit signs every webhook request with an HMAC-SHA256 signature. The
+signature header contains a timestamp and one or more versioned signatures
+in the format: ``t=<unix_seconds>,v1=<hex_hmac>``.
+
+The signed content is ``<timestamp>.<raw_body>``, ensuring both freshness
+and integrity.
+
+Usage with FastAPI::
+
+    from fastapi import Request, Response
+    from ascendkit import verify_webhook_signature
+
+    WEBHOOK_SECRET = "whsec_..."
+
+    @app.post("/webhooks/ascendkit")
+    async def handle_webhook(request: Request) -> Response:
+        body = await request.body()
+        signature = request.headers.get("x-ascendkit-signature", "")
+
+        if not verify_webhook_signature(
+            secret=WEBHOOK_SECRET,
+            signature_header=signature,
+            payload=body.decode(),
+        ):
+            return Response(status_code=401, content="Invalid signature")
+
+        event = await request.json()
+        # Handle the event...
+        return Response(status_code=200, content="OK")
+
+Usage with Flask::
+
+    from flask import Flask, request
+    from ascendkit import verify_webhook_signature
+
+    WEBHOOK_SECRET = "whsec_..."
+
+    @app.route("/webhooks/ascendkit", methods=["POST"])
+    def handle_webhook():
+        body = request.get_data(as_text=True)
+        signature = request.headers.get("x-ascendkit-signature", "")
+
+        if not verify_webhook_signature(
+            secret=WEBHOOK_SECRET,
+            signature_header=signature,
+            payload=body,
+        ):
+            return "Invalid signature", 401
+
+        event = request.get_json()
+        # Handle the event...
+        return "OK", 200
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+_DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def verify_webhook_signature(
+    secret: str,
+    signature_header: str,
+    payload: str,
+    tolerance: int = _DEFAULT_TOLERANCE_SECONDS,
+) -> bool:
+    """Verify an AscendKit webhook signature.
+
+    Args:
+        secret: Your webhook signing secret.
+        signature_header: The value of the ``X-AscendKit-Signature`` header.
+        payload: The raw request body as a string.
+        tolerance: Maximum allowed age of the timestamp in seconds (default 300).
+
+    Returns:
+        ``True`` if the signature is valid and the timestamp is within tolerance.
+    """
+    # Parse header: t=<timestamp>,v1=<hmac>
+    parts = signature_header.split(",")
+
+    timestamp: str | None = None
+    signature_hex: str | None = None
+
+    for part in parts:
+        key, _, value = part.partition("=")
+        if key == "t":
+            timestamp = value
+        elif key == "v1":
+            signature_hex = value
+
+    if not timestamp or not signature_hex:
+        return False
+
+    # Validate timestamp freshness
+    try:
+        timestamp_seconds = int(timestamp)
+    except ValueError:
+        return False
+
+    now = int(time.time())
+    if abs(now - timestamp_seconds) > tolerance:
+        return False
+
+    # Compute expected signature: HMAC-SHA256 of "<timestamp>.<payload>"
+    signed_content = f"{timestamp}.{payload}"
+    expected_hmac = hmac.new(
+        secret.encode(),
+        signed_content.encode(),
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Constant-time comparison to prevent timing attacks
+    return hmac.compare_digest(expected_hmac, signature_hex)