timeback-sdk 0.1.0__tar.gz

timeback_sdk-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# uv
+uv.lock
+
+# ruff
+.ruff_cache/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

timeback_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: timeback-sdk
+Version: 0.1.0
+Summary: Timeback SDK for Python - adapters for FastAPI, Django, and more
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: starlette>=0.35.0
+Requires-Dist: timeback-core
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'

timeback_sdk-0.1.0/README.md

@@ -0,0 +1,43 @@
+# Timeback SDK
+
+Server-side SDK for integrating Timeback into Python web applications.
+
+## Installation
+
+```bash
+# With FastAPI
+pip install timeback[fastapi]
+
+# With Django
+pip install timeback[django]
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from timeback.fastapi import create_timeback_router
+
+app = FastAPI()
+
+timeback_router = create_timeback_router(
+    env="staging",
+    client_id="...",
+    client_secret="...",
+    identity={
+        "mode": "sso",
+        "client_id": "...",
+        "client_secret": "...",
+        "get_user": lambda req: get_session_user(req),
+        "on_callback_success": lambda ctx: handle_sso_success(ctx),
+    },
+)
+
+app.include_router(timeback_router, prefix="/api/timeback")
+```
+
+## Django
+
+```python
+# Coming soon
+```

timeback_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "timeback-sdk"
+version = "0.1.0"
+description = "Timeback SDK for Python - adapters for FastAPI, Django, and more"
+requires-python = ">=3.11"
+dependencies = [
+    "timeback-core",
+    "httpx>=0.27.0",
+    "starlette>=0.35.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0"]
+django = ["django>=4.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/timeback"]
+
+[tool.uv.sources]
+timeback-core = { workspace = true }

timeback_sdk-0.1.0/pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*

timeback_sdk-0.1.0/src/timeback/__init__.py

@@ -0,0 +1,135 @@
+"""
+Timeback SDK for Python.
+
+Server-side SDK for integrating Timeback into Python web applications.
+
+Example (FastAPI with SSO - Full SDK):
+    ```python
+    from fastapi import FastAPI
+    from timeback import ApiCredentials, SsoIdentityConfig
+    from timeback.server import create_server, to_fastapi_router
+
+    async def create_app():
+        timeback = await create_server(TimebackConfig(
+            env="staging",
+            api=ApiCredentials(
+                client_id=os.environ["TIMEBACK_API_CLIENT_ID"],
+                client_secret=os.environ["TIMEBACK_API_CLIENT_SECRET"],
+            ),
+            identity=SsoIdentityConfig(
+                mode="sso",
+                client_id=os.environ["COGNITO_CLIENT_ID"],
+                client_secret=os.environ["COGNITO_CLIENT_SECRET"],
+                get_user=get_session_user,  # returns { id: timebackId, email }
+                on_callback_success=handle_sso_success,
+            ),
+        ))
+
+        app = FastAPI()
+        app.include_router(to_fastapi_router(timeback), prefix="/api/timeback")
+        return app
+    ```
+
+Example (FastAPI with custom auth):
+    ```python
+    from timeback import ApiCredentials, CustomIdentityConfig
+    from timeback.server import create_server, to_fastapi_router
+
+    timeback = await create_server(TimebackConfig(
+        env="staging",
+        api=ApiCredentials(client_id="...", client_secret="..."),
+        identity=CustomIdentityConfig(
+            mode="custom",
+            get_email=lambda req: get_session(req).email,  # returns email string
+        ),
+    ))
+    ```
+
+Example (FastAPI with SSO - Identity-Only):
+    ```python
+    from fastapi import FastAPI
+    from timeback import IdentityOnlyConfig, IdentityOnlySsoConfig
+    from timeback.server import create_identity_only_server, to_fastapi_router
+
+    timeback = create_identity_only_server(IdentityOnlyConfig(
+        env="staging",
+        identity=IdentityOnlySsoConfig(
+            mode="sso",
+            client_id=os.environ["COGNITO_CLIENT_ID"],
+            client_secret=os.environ["COGNITO_CLIENT_SECRET"],
+            on_callback_success=lambda ctx: ctx.redirect("/dashboard"),
+        ),
+    ))
+
+    app = FastAPI()
+    app.include_router(to_fastapi_router(timeback), prefix="/api/auth")
+    ```
+"""
+
+from .server.types import (
+    ApiCredentials,
+    BuildStateContext,
+    CallbackErrorContext,
+    CallbackSuccessContext,
+    CustomIdentityConfig,
+    IdentityConfig,
+    IdentityOnlyCallbackSuccessContext,
+    IdentityOnlyConfig,
+    IdentityOnlySsoConfig,
+    IdpData,
+    OIDCTokens,
+    OIDCUserInfo,
+    SsoIdentityConfig,
+    TimebackConfig,
+)
+from .shared.types import (
+    ActivityCourseRef,
+    ActivityEndPayload,
+    ActivityMetrics,
+    ActivityParams,
+    ActivityResponse,
+    CourseCodeRef,
+    Environment,
+    IdentityClaims,
+    SubjectGradeCourseRef,
+    TimebackAuthUser,
+    TimebackIdentity,
+    TimebackProfile,
+    TimebackSessionUser,
+    TimebackUser,
+    TimebackUserResolutionErrorCode,
+    is_subject_grade_course_ref,
+)
+
+__all__ = [
+    "ActivityCourseRef",
+    "ActivityEndPayload",
+    "ActivityMetrics",
+    "ActivityParams",
+    "ActivityResponse",
+    "ApiCredentials",
+    "BuildStateContext",
+    "CallbackErrorContext",
+    "CallbackSuccessContext",
+    "CourseCodeRef",
+    "CustomIdentityConfig",
+    "Environment",
+    "IdentityClaims",
+    "IdentityConfig",
+    "IdentityOnlyCallbackSuccessContext",
+    "IdentityOnlyConfig",
+    "IdentityOnlySsoConfig",
+    "IdpData",
+    "OIDCTokens",
+    "OIDCUserInfo",
+    "SsoIdentityConfig",
+    "SubjectGradeCourseRef",
+    "TimebackAuthUser",
+    "TimebackConfig",
+    "TimebackIdentity",
+    "TimebackProfile",
+    "TimebackSessionUser",
+    "TimebackUser",
+    "TimebackUserResolutionErrorCode",
+    "is_subject_grade_course_ref",
+]

timeback_sdk-0.1.0/src/timeback/server/__init__.py

@@ -0,0 +1,77 @@
+"""Timeback server SDK."""
+
+from .adapters.fastapi import to_fastapi_router
+from .handlers import IdentityOnlyHandlers, InvalidSensorUrlError, MissingSyncedCourseIdError
+from .lib.resolve import (
+    ActivityCourseResolutionError,
+    TimebackUserResolutionError,
+    lookup_timeback_id_by_email,
+    resolve_activity_course,
+    resolve_status_for_user_resolution_error,
+    resolve_timeback_user_by_email,
+)
+from .timeback import (
+    AppConfig,
+    ConfigValidationError,
+    CourseEnvOverrides,
+    CourseOverrides,
+    IdentityOnlyInstance,
+    TimebackInstance,
+    create_identity_only_server,
+    create_server,
+)
+from .types import (
+    ActivityBeforeSendData,
+    ApiCredentials,
+    BuildStateContext,
+    CallbackErrorContext,
+    CallbackSuccessContext,
+    CustomIdentityConfig,
+    IdentityConfig,
+    IdentityOnlyCallbackSuccessContext,
+    IdentityOnlyConfig,
+    IdentityOnlySsoConfig,
+    IdpData,
+    OIDCTokens,
+    OIDCUserInfo,
+    SsoIdentityConfig,
+    TimebackConfig,
+    TimebackHooks,
+)
+
+__all__ = [
+    "ActivityBeforeSendData",
+    "ActivityCourseResolutionError",
+    "ApiCredentials",
+    "AppConfig",
+    "BuildStateContext",
+    "CallbackErrorContext",
+    "CallbackSuccessContext",
+    "ConfigValidationError",
+    "CourseEnvOverrides",
+    "CourseOverrides",
+    "CustomIdentityConfig",
+    "IdentityConfig",
+    "IdentityOnlyCallbackSuccessContext",
+    "IdentityOnlyConfig",
+    "IdentityOnlyHandlers",
+    "IdentityOnlyInstance",
+    "IdentityOnlySsoConfig",
+    "IdpData",
+    "InvalidSensorUrlError",
+    "MissingSyncedCourseIdError",
+    "OIDCTokens",
+    "OIDCUserInfo",
+    "SsoIdentityConfig",
+    "TimebackConfig",
+    "TimebackHooks",
+    "TimebackInstance",
+    "TimebackUserResolutionError",
+    "create_identity_only_server",
+    "create_server",
+    "lookup_timeback_id_by_email",
+    "resolve_activity_course",
+    "resolve_status_for_user_resolution_error",
+    "resolve_timeback_user_by_email",
+    "to_fastapi_router",
+]

timeback_sdk-0.1.0/src/timeback/server/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Server adapters."""
+
+from .fastapi import to_fastapi_router
+
+__all__ = ["to_fastapi_router"]

timeback_sdk-0.1.0/src/timeback/server/adapters/django.py

@@ -0,0 +1,35 @@
+"""
+Django adapter for Timeback SDK.
+
+Provides URL patterns and views for Django integration.
+
+Status: Not yet implemented. Coming soon.
+
+Example (future API):
+    ```python
+    # urls.py
+    from django.urls import path, include
+    from timeback.django import get_timeback_urls
+
+    urlpatterns = [
+        path("api/timeback/", include(get_timeback_urls(
+            env="staging",
+            api={"client_id": "...", "client_secret": "..."},
+            identity={"mode": "custom", "get_user": get_request_user},
+        ))),
+    ]
+    ```
+"""
+
+# Django adapter implementation will be added when there's demand.
+# Key considerations:
+# - Django uses sync views by default (async views available in 3.1+)
+# - Django has its own Request/Response objects (not Starlette)
+# - Session handling is built-in via django.contrib.sessions
+# - Authentication is built-in via django.contrib.auth
+#
+# Implementation approach:
+# 1. Create view functions that wrap the core handlers
+# 2. Convert Django HttpRequest to a common format
+# 3. Convert handler responses back to Django HttpResponse
+# 4. Provide both sync (using async_to_sync) and async views

timeback_sdk-0.1.0/src/timeback/server/adapters/fastapi.py

@@ -0,0 +1,170 @@
+"""
+FastAPI Adapter
+
+Adapts Timeback handlers for FastAPI.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast, overload
+
+from fastapi import APIRouter, Request
+
+if TYPE_CHECKING:
+    from starlette.responses import Response
+
+    from ..handlers.factory import Handlers
+    from ..timeback import IdentityOnlyInstance, TimebackInstance
+
+
+# Type for flexible input (full or identity-only instance)
+AnyTimebackInstance = "TimebackInstance | IdentityOnlyInstance"
+
+
+@overload
+def to_fastapi_router(
+    timeback: TimebackInstance,
+    *,
+    callback_path: str | None = None,
+) -> APIRouter: ...
+
+
+@overload
+def to_fastapi_router(
+    timeback: IdentityOnlyInstance,
+    *,
+    callback_path: str | None = None,
+) -> APIRouter: ...
+
+
+def to_fastapi_router(
+    timeback: TimebackInstance | IdentityOnlyInstance,
+    *,
+    callback_path: str | None = None,
+) -> APIRouter:
+    """
+    Convert Timeback instance to FastAPI router.
+
+    Supports both full SDK instances (from create_server()) and identity-only
+    instances (from create_identity_only_server()).
+
+    Args:
+        timeback: Timeback instance (full or identity-only)
+        callback_path: Custom callback path for OAuth redirects. If your IdP has
+            a pre-registered callback URL that differs from the SDK default
+            (/identity/callback), specify the path here. The path should be
+            relative to the router mount point (e.g., "/auth/callback").
+
+    Returns:
+        FastAPI APIRouter with Timeback endpoints
+
+    Example (Full SDK):
+        ```python
+        from timeback.server import create_server, TimebackConfig, SsoIdentityConfig
+        from timeback.server.adapters.fastapi import to_fastapi_router
+
+        timeback = await create_server(TimebackConfig(
+            env="staging",
+            api=ApiCredentials(client_id="...", client_secret="..."),
+            identity=SsoIdentityConfig(
+                mode="sso",
+                client_id="...",
+                client_secret="...",
+                get_user=get_session_user,
+                on_callback_success=lambda ctx: ctx.redirect("/"),
+            ),
+        ))
+
+        app = FastAPI()
+        app.include_router(to_fastapi_router(timeback), prefix="/api/timeback")
+        ```
+
+    Example (Identity-Only):
+        ```python
+        from timeback.server import (
+            create_identity_only_server,
+            IdentityOnlyConfig,
+            IdentityOnlySsoConfig,
+        )
+        from timeback.server.adapters.fastapi import to_fastapi_router
+
+        timeback = create_identity_only_server(IdentityOnlyConfig(
+            env="staging",
+            identity=IdentityOnlySsoConfig(
+                mode="sso",
+                client_id="...",
+                client_secret="...",
+                on_callback_success=lambda ctx: ctx.redirect("/dashboard"),
+            ),
+        ))
+
+        app = FastAPI()
+        app.include_router(to_fastapi_router(timeback), prefix="/api/auth")
+        ```
+
+    Example (Custom Callback Path):
+        ```python
+        # When your IdP requires a specific callback URL like:
+        # https://example.com/api/auth/sso/callback/timeback
+
+        timeback = create_identity_only_server(IdentityOnlyConfig(
+            env="staging",
+            identity=IdentityOnlySsoConfig(
+                mode="sso",
+                client_id="...",
+                client_secret="...",
+                redirect_uri="https://example.com/api/auth/sso/callback/timeback",
+                on_callback_success=lambda ctx: ctx.redirect("/dashboard"),
+            ),
+        ))
+
+        app = FastAPI()
+        app.include_router(
+            to_fastapi_router(timeback, callback_path="/sso/callback/timeback"),
+            prefix="/api/auth",
+        )
+        ```
+    """
+    router = APIRouter()
+    handle = timeback.handle
+
+    # Determine if this is a full instance or identity-only
+    is_full_instance = hasattr(handle, "activity") and hasattr(handle, "user")
+
+    # Register identity routes
+    @router.get("/identity/signin")
+    async def identity_signin(request: Request) -> Response:
+        return await handle.identity.sign_in(request)
+
+    # Default callback path
+    @router.get("/identity/callback")
+    async def identity_callback(request: Request) -> Response:
+        return await handle.identity.callback(request)
+
+    # Custom callback path (if provided and different from default)
+    if callback_path and callback_path != "/identity/callback":
+        # Normalize path to ensure it starts with /
+        normalized_path = callback_path if callback_path.startswith("/") else f"/{callback_path}"
+
+        @router.get(normalized_path)
+        async def identity_callback_custom(request: Request) -> Response:
+            return await handle.identity.callback(request)
+
+    @router.get("/identity/signout")
+    async def identity_signout(_request: Request) -> Response:
+        return handle.identity.sign_out()
+
+    # Register full SDK routes only for full instances
+    if is_full_instance:
+        # Cast to Handlers since we've confirmed it has activity and user
+        full_handle = cast("Handlers", handle)
+
+        @router.post("/activity", response_model=None)
+        async def submit_activity(request: Request) -> Response:
+            return await full_handle.activity(request)
+
+        @router.get("/user/me")
+        async def user_me(request: Request) -> Response:
+            return await full_handle.user.me(request)
+
+    return router

timeback_sdk-0.1.0/src/timeback/server/handlers/__init__.py

@@ -0,0 +1,24 @@
+"""SDK request handlers."""
+
+from .activity import InvalidSensorUrlError, MissingSyncedCourseIdError, create_activity_handler
+from .factory import Handlers, create_handlers
+from .identity import (
+    IdentityHandlers,
+    IdentityOnlyHandlers,
+    create_identity_handlers,
+    create_identity_only_handlers,
+)
+from .user import create_user_handler
+
+__all__ = [
+    "Handlers",
+    "IdentityHandlers",
+    "IdentityOnlyHandlers",
+    "InvalidSensorUrlError",
+    "MissingSyncedCourseIdError",
+    "create_activity_handler",
+    "create_handlers",
+    "create_identity_handlers",
+    "create_identity_only_handlers",
+    "create_user_handler",
+]