timeback-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/.gitignore

@@ -1,3 +1,6 @@
+# ai
+.claude
+
 # Python
 __pycache__/
 *.py[cod]

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timeback-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Timeback SDK for Python - adapters for FastAPI, Django, and more
 Project-URL: Homepage, https://developer.timeback.com
 Project-URL: Documentation, https://docs.timeback.com

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "timeback-sdk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Timeback SDK for Python - adapters for FastAPI, Django, and more"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/src/timeback/server/handlers/activity/heartbeat_handler.py

@@ -106,53 +106,59 @@ def create_heartbeat_handler(
     api_env = map_env_for_api(env)
 
     async def handler(request: Request) -> Response:
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 1: Authenticate
-        # ═══════════════════════════════════════════════════════════════════
-        user_info = await get_activity_user_info(identity, request)
-        if not user_info:
-            return error_response("UNAUTHORIZED", "Unauthorized", 401)
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 2: Validate request
-        # ═══════════════════════════════════════════════════════════════════
-        body = await request.json()
-        result = validate_heartbeat_request(body, app_config)
-
-        if isinstance(result, ValidationError):
-            return result.response
-
-        payload = result.payload
-        course_config = result.course
-        sensor = result.sensor
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 3: Check for duplicate (idempotency)
-        # ═══════════════════════════════════════════════════════════════════
-        window_start_ms = _parse_iso_to_ms(payload.started_at)
-        window_key = f"{payload.run_id}:{window_start_ms}"
-
-        if _is_duplicate(window_key):
-            log.debug(
-                "Duplicate heartbeat, skipping: runId=%s, windowKey=%s", payload.run_id, window_key
-            )
-            return JSONResponse({"duplicate": True})
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 4: Verify course is synced
-        # ═══════════════════════════════════════════════════════════════════
-        synced_course_id = (course_config.get("ids") or {}).get(api_env)
-        if not isinstance(synced_course_id, str) or not synced_course_id:
-            err = MissingSyncedCourseIdError(course_config, api_env)
-            log.warning("Course not synced: %s, env=%s", err.course, err.env)
-            return error_response("MISSING_SYNCED_COURSE_ID", str(err), 503)
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 5: Resolve user and send event
-        # ═══════════════════════════════════════════════════════════════════
-        client = get_client()
-
         try:
+            # ═══════════════════════════════════════════════════════════════
+            # Step 1: Authenticate
+            # ═══════════════════════════════════════════════════════════════
+            user_info = await get_activity_user_info(identity, request)
+            if not user_info:
+                return error_response("UNAUTHORIZED", "Unauthorized", 401)
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 2: Validate request
+            # ═══════════════════════════════════════════════════════════════
+            try:
+                body = await request.json()
+            except Exception:
+                return error_response("INVALID_PAYLOAD", "Malformed JSON in request body", 400)
+
+            result = validate_heartbeat_request(body, app_config)
+
+            if isinstance(result, ValidationError):
+                return result.response
+
+            payload = result.payload
+            course_config = result.course
+            sensor = result.sensor
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 3: Check for duplicate (idempotency)
+            # ═══════════════════════════════════════════════════════════════
+            window_start_ms = _parse_iso_to_ms(payload.started_at)
+            window_key = f"{payload.run_id}:{window_start_ms}"
+
+            if _is_duplicate(window_key):
+                log.debug(
+                    "Duplicate heartbeat, skipping: runId=%s, windowKey=%s",
+                    payload.run_id,
+                    window_key,
+                )
+                return JSONResponse({"duplicate": True})
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 4: Verify course is synced
+            # ═══════════════════════════════════════════════════════════════
+            synced_course_id = (course_config.get("ids") or {}).get(api_env)
+            if not isinstance(synced_course_id, str) or not synced_course_id:
+                err = MissingSyncedCourseIdError(course_config, api_env)
+                log.warning("Course not synced: %s, env=%s", err.course, err.env)
+                return error_response("MISSING_SYNCED_COURSE_ID", str(err), 503)
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 5: Resolve user and send event
+            # ═══════════════════════════════════════════════════════════════
+            client = get_client()
+
             timeback_id = (
                 user_info.timeback_id
                 if user_info.timeback_id

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/src/timeback/server/handlers/activity/submit_handler.py

@@ -117,28 +117,32 @@ def create_submit_handler(
     api_env = map_env_for_api(env)
 
     async def handler(request: Request) -> Response:
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 1: Authenticate
-        # ═══════════════════════════════════════════════════════════════════
-        user_info = await get_activity_user_info(identity, request)
-        if not user_info:
-            return error_response("UNAUTHORIZED", "Unauthorized", 401)
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 2: Validate request
-        # ═══════════════════════════════════════════════════════════════════
-        body = await request.json()
-        result = validate_submit_request(body, app_config)
-
-        if isinstance(result, ValidationError):
-            return result.response
-
-        payload = result.payload
-
-        # ═══════════════════════════════════════════════════════════════════
-        # Step 3: Delegate to record_completion
-        # ═══════════════════════════════════════════════════════════════════
         try:
+            # ═══════════════════════════════════════════════════════════════
+            # Step 1: Authenticate
+            # ═══════════════════════════════════════════════════════════════
+            user_info = await get_activity_user_info(identity, request)
+            if not user_info:
+                return error_response("UNAUTHORIZED", "Unauthorized", 401)
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 2: Validate request
+            # ═══════════════════════════════════════════════════════════════
+            try:
+                body = await request.json()
+            except Exception:
+                return error_response("INVALID_PAYLOAD", "Malformed JSON in request body", 400)
+
+            result = validate_submit_request(body, app_config)
+
+            if isinstance(result, ValidationError):
+                return result.response
+
+            payload = result.payload
+
+            # ═══════════════════════════════════════════════════════════════
+            # Step 3: Delegate to record_completion
+            # ═══════════════════════════════════════════════════════════════
             completion_result = await record_completion(
                 user_info=user_info,
                 body=body,
@@ -193,23 +197,12 @@ def create_submit_handler(
             return error_response("INVALID_SENSOR_URL", str(e), 500)
 
         except CaliperValidationError as e:
-            selector_desc = format_course_selector(payload.course)
-            log.error(
-                "Caliper validation error: course=%s, id=%s, error=%s",
-                selector_desc,
-                payload.id,
-                str(e),
-            )
+            log.error("Caliper validation error: %s", str(e))
             return error_response("INTERNAL_ERROR", str(e), 502, details=e.response)
 
         except Exception as e:
-            selector_desc = format_course_selector(payload.course)
-            log.error(
-                "Failed to submit activity: course=%s, id=%s, error=%s",
-                selector_desc,
-                payload.id,
-                str(e),
-            )
-            return error_response("INTERNAL_ERROR", str(e), 502)
+            message = str(e) if str(e) else "Unknown error"
+            log.error("Failed to submit activity: %s", message)
+            return error_response("INTERNAL_ERROR", message, 502)
 
     return handler

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/src/timeback/server/handlers/identity/handler.py

@@ -85,74 +85,90 @@ def create_identity_handlers(
     )
 
     async def sso_signin(request: Request) -> Response:
-        # Build callback URL
-        callback_url = sso_config.redirect_uri
-        if not callback_url:
-            base = str(request.base_url).rstrip("/")
-            # Derive from current path: /api/timeback/identity/signin -> /api/timeback/identity/callback
-            path = str(request.url.path)
-            callback_path = path.replace("/signin", "/callback")
-            callback_url = f"{base}{callback_path}"
-
-        sso_log.debug(
-            "SSO sign-in initiated, env=%s, issuer=%s, client_id=%s",
-            env,
-            issuer,
-            sso_config.client_id,
-        )
-
-        # Build state - default to {} (state always decodes to object)
-        state_data: dict | None = {}
-        if sso_config.build_state:
-            ctx = BuildStateContext(
-                request=request,
-                url=str(request.url),
+        try:
+            # Build callback URL
+            callback_url = sso_config.redirect_uri
+            if not callback_url:
+                base = str(request.base_url).rstrip("/")
+                path = str(request.url.path)
+                callback_path = path.replace("/signin", "/callback")
+                callback_url = f"{base}{callback_path}"
+
+            sso_log.debug(
+                "SSO sign-in initiated, env=%s, issuer=%s, client_id=%s",
+                env,
+                issuer,
+                sso_config.client_id,
             )
-            state_data = sso_config.build_state(ctx)
-
-        # Generate auth URL
-        auth_url = await oidc.get_authorization_url(redirect_uri=callback_url, state=state_data)
-        return RedirectResponse(url=auth_url, status_code=302)
-
-    async def sso_callback(request: Request) -> Response:
-        code = request.query_params.get("code")
-        state_param = request.query_params.get("state")
-        error = request.query_params.get("error")
 
-        sso_log.debug("Received callback from IdP, has_code=%s, error=%s", bool(code), error)
-
-        # Parse state early for error context
-        state = oidc.decode_state(state_param) if state_param else None
+            # Build state - default to {} (state always decodes to object)
+            state_data: dict | None = {}
+            if sso_config.build_state:
+                ctx = BuildStateContext(
+                    request=request,
+                    url=str(request.url),
+                )
+                state_data = sso_config.build_state(ctx)
 
-        if error:
-            error_desc = request.query_params.get("error_description")
-            sso_log.error("IdP returned error: %s, description=%s", error, error_desc)
+            # Generate auth URL
+            auth_url = await oidc.get_authorization_url(redirect_uri=callback_url, state=state_data)
+            return RedirectResponse(url=auth_url, status_code=302)
 
-            error_ctx = CallbackErrorContext(
-                error=Exception(error_desc or error),
-                error_code=error,
-                state=state,
-                request=request,
-            )
-            if sso_config.on_callback_error:
-                result = sso_config.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
-            return JSONResponse({"error": error}, status_code=400)
+        except Exception as e:
+            sso_log.error("SSO sign-in failed: %s", str(e))
+            return JSONResponse({"error": "SSO sign-in failed"}, status_code=500)
 
-        if not code:
-            sso_log.error("Missing authorization code in callback")
-            error_ctx = CallbackErrorContext(
-                error=Exception("Missing authorization code"),
-                error_code="missing_code",
-                state=state,
-                request=request,
-            )
-            if sso_config.on_callback_error:
-                result = sso_config.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
-            return JSONResponse({"error": "Missing authorization code"}, status_code=400)
+    async def sso_callback(request: Request) -> Response:
+        state: dict | None = None
 
         try:
+            code = request.query_params.get("code")
+            state_param = request.query_params.get("state")
+            error = request.query_params.get("error")
+
+            sso_log.debug("Received callback from IdP, has_code=%s, error=%s", bool(code), error)
+
+            # Parse state early for error context
+            try:
+                state = oidc.decode_state(state_param) if state_param else None
+            except Exception as decode_err:
+                sso_log.warning("Failed to decode state param: %s", str(decode_err))
+                state = None
+
+            if error:
+                error_desc = request.query_params.get("error_description")
+                sso_log.error("IdP returned error: %s, description=%s", error, error_desc)
+
+                error_ctx = CallbackErrorContext(
+                    error=Exception(error_desc or error),
+                    error_code=error,
+                    state=state,
+                    request=request,
+                )
+                if sso_config.on_callback_error:
+                    try:
+                        result = sso_config.on_callback_error(error_ctx)
+                        return await result if inspect.isawaitable(result) else result
+                    except Exception as cb_err:
+                        sso_log.error("on_callback_error raised: %s", str(cb_err))
+                return JSONResponse({"error": error}, status_code=400)
+
+            if not code:
+                sso_log.error("Missing authorization code in callback")
+                error_ctx = CallbackErrorContext(
+                    error=Exception("Missing authorization code"),
+                    error_code="missing_code",
+                    state=state,
+                    request=request,
+                )
+                if sso_config.on_callback_error:
+                    try:
+                        result = sso_config.on_callback_error(error_ctx)
+                        return await result if inspect.isawaitable(result) else result
+                    except Exception as cb_err:
+                        sso_log.error("on_callback_error raised: %s", str(cb_err))
+                return JSONResponse({"error": "Missing authorization code"}, status_code=400)
+
             # Build callback URL (same as signin)
             callback_url = sso_config.redirect_uri
             if not callback_url:
@@ -193,8 +209,12 @@ def create_identity_handlers(
             )
 
             if sso_config.on_callback_success:
-                result = sso_config.on_callback_success(success_ctx)
-                return await result if inspect.isawaitable(result) else result
+                try:
+                    result = sso_config.on_callback_success(success_ctx)
+                    return await result if inspect.isawaitable(result) else result
+                except Exception as cb_err:
+                    sso_log.error("on_callback_success raised: %s", str(cb_err))
+                    return JSONResponse({"error": "Callback handler failed"}, status_code=500)
 
             return RedirectResponse(url="/", status_code=302)
 
@@ -207,13 +227,12 @@ def create_identity_handlers(
                 request=request,
             )
             if sso_config.on_callback_error:
-                result = sso_config.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
+                try:
+                    result = sso_config.on_callback_error(error_ctx)
+                    return await result if inspect.isawaitable(result) else result
+                except Exception as cb_err:
+                    sso_log.error("on_callback_error raised: %s", str(cb_err))
 
-            # Map resolution errors consistently with other handlers:
-            # - ambiguous -> 409
-            # - not_found -> 404
-            # - missing_email / lookup_failed -> 502 (upstream dependency / identity provider mismatch)
             if e.code == "timeback_user_ambiguous":
                 return JSONResponse({"error": str(e)}, status_code=409)
             if e.code == "timeback_user_not_found":
@@ -229,8 +248,11 @@ def create_identity_handlers(
                 request=request,
             )
             if sso_config.on_callback_error:
-                result = sso_config.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
+                try:
+                    result = sso_config.on_callback_error(error_ctx)
+                    return await result if inspect.isawaitable(result) else result
+                except Exception as cb_err:
+                    sso_log.error("on_callback_error raised: %s", str(cb_err))
             return JSONResponse({"error": str(e)}, status_code=500)
 
     def sso_signout() -> Response:

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/src/timeback/server/handlers/identity_only/handler.py

@@ -81,76 +81,94 @@ def create_identity_only_handlers(
     )
 
     async def identity_only_signin(request: Request) -> Response:
-        # Build callback URL
-        callback_url = identity.redirect_uri
-        if not callback_url:
-            base = str(request.base_url).rstrip("/")
-            # Derive from current path: /api/timeback/identity/signin -> /api/timeback/identity/callback
-            path = str(request.url.path)
-            callback_path = path.replace("/signin", "/callback")
-            callback_url = f"{base}{callback_path}"
-
-        sso_log.debug(
-            "SSO sign-in initiated (identity-only), env=%s, issuer=%s, client_id=%s",
-            env,
-            issuer,
-            identity.client_id,
-        )
-
-        # Build state - default to {} (state always decodes to object)
-        state_data: dict | None = {}
-        if identity.build_state:
-            ctx = BuildStateContext(
-                request=request,
-                url=str(request.url),
+        try:
+            # Build callback URL
+            callback_url = identity.redirect_uri
+            if not callback_url:
+                base = str(request.base_url).rstrip("/")
+                path = str(request.url.path)
+                callback_path = path.replace("/signin", "/callback")
+                callback_url = f"{base}{callback_path}"
+
+            sso_log.debug(
+                "SSO sign-in initiated (identity-only), env=%s, issuer=%s, client_id=%s",
+                env,
+                issuer,
+                identity.client_id,
             )
-            state_data = identity.build_state(ctx)
-
-        # Generate auth URL
-        auth_url = await oidc.get_authorization_url(redirect_uri=callback_url, state=state_data)
-        return RedirectResponse(url=auth_url, status_code=302)
 
-    async def identity_only_callback(request: Request) -> Response:
-        code = request.query_params.get("code")
-        state_param = request.query_params.get("state")
-        error = request.query_params.get("error")
+            # Build state - default to {} (state always decodes to object)
+            state_data: dict | None = {}
+            if identity.build_state:
+                ctx = BuildStateContext(
+                    request=request,
+                    url=str(request.url),
+                )
+                state_data = identity.build_state(ctx)
 
-        sso_log.debug(
-            "Received callback from IdP (identity-only), has_code=%s, error=%s", bool(code), error
-        )
+            # Generate auth URL
+            auth_url = await oidc.get_authorization_url(redirect_uri=callback_url, state=state_data)
+            return RedirectResponse(url=auth_url, status_code=302)
 
-        # Parse state early for error context
-        state = oidc.decode_state(state_param) if state_param else None
+        except Exception as e:
+            sso_log.error("SSO sign-in failed (identity-only): %s", str(e))
+            return JSONResponse({"error": "SSO sign-in failed"}, status_code=500)
 
-        if error:
-            error_desc = request.query_params.get("error_description")
-            sso_log.error("IdP returned error: %s, description=%s", error, error_desc)
+    async def identity_only_callback(request: Request) -> Response:
+        state: dict | None = None
 
-            error_ctx = CallbackErrorContext(
-                error=Exception(error_desc or error),
-                error_code=error,
-                state=state,
-                request=request,
+        try:
+            code = request.query_params.get("code")
+            state_param = request.query_params.get("state")
+            error = request.query_params.get("error")
+
+            sso_log.debug(
+                "Received callback from IdP (identity-only), has_code=%s, error=%s",
+                bool(code),
+                error,
             )
-            if identity.on_callback_error:
-                result = identity.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
-            return JSONResponse({"error": error}, status_code=400)
 
-        if not code:
-            sso_log.error("Missing authorization code in callback")
-            error_ctx = CallbackErrorContext(
-                error=Exception("Missing authorization code"),
-                error_code="missing_code",
-                state=state,
-                request=request,
-            )
-            if identity.on_callback_error:
-                result = identity.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
-            return JSONResponse({"error": "Missing authorization code"}, status_code=400)
+            # Parse state early for error context
+            try:
+                state = oidc.decode_state(state_param) if state_param else None
+            except Exception as decode_err:
+                sso_log.warning("Failed to decode state param: %s", str(decode_err))
+                state = None
+
+            if error:
+                error_desc = request.query_params.get("error_description")
+                sso_log.error("IdP returned error: %s, description=%s", error, error_desc)
+
+                error_ctx = CallbackErrorContext(
+                    error=Exception(error_desc or error),
+                    error_code=error,
+                    state=state,
+                    request=request,
+                )
+                if identity.on_callback_error:
+                    try:
+                        result = identity.on_callback_error(error_ctx)
+                        return await result if inspect.isawaitable(result) else result
+                    except Exception as cb_err:
+                        sso_log.error("on_callback_error raised: %s", str(cb_err))
+                return JSONResponse({"error": error}, status_code=400)
+
+            if not code:
+                sso_log.error("Missing authorization code in callback")
+                error_ctx = CallbackErrorContext(
+                    error=Exception("Missing authorization code"),
+                    error_code="missing_code",
+                    state=state,
+                    request=request,
+                )
+                if identity.on_callback_error:
+                    try:
+                        result = identity.on_callback_error(error_ctx)
+                        return await result if inspect.isawaitable(result) else result
+                    except Exception as cb_err:
+                        sso_log.error("on_callback_error raised: %s", str(cb_err))
+                return JSONResponse({"error": "Missing authorization code"}, status_code=400)
 
-        try:
             # Build callback URL (same as signin)
             callback_url = identity.redirect_uri
             if not callback_url:
@@ -175,8 +193,12 @@ def create_identity_only_handlers(
             )
 
             if identity.on_callback_success:
-                result = identity.on_callback_success(success_ctx)
-                return await result if inspect.isawaitable(result) else result
+                try:
+                    result = identity.on_callback_success(success_ctx)
+                    return await result if inspect.isawaitable(result) else result
+                except Exception as cb_err:
+                    sso_log.error("on_callback_success raised: %s", str(cb_err))
+                    return JSONResponse({"error": "Callback handler failed"}, status_code=500)
 
             return RedirectResponse(url="/", status_code=302)
 
@@ -189,8 +211,11 @@ def create_identity_only_handlers(
                 request=request,
             )
             if identity.on_callback_error:
-                result = identity.on_callback_error(error_ctx)
-                return await result if inspect.isawaitable(result) else result
+                try:
+                    result = identity.on_callback_error(error_ctx)
+                    return await result if inspect.isawaitable(result) else result
+                except Exception as cb_err:
+                    sso_log.error("on_callback_error raised: %s", str(cb_err))
             return JSONResponse({"error": str(e)}, status_code=500)
 
     def identity_only_signout() -> Response:

{timeback_sdk-0.2.0 → timeback_sdk-0.2.1}/src/timeback/server/handlers/lessons/errors.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING
 from ...lib.logger import create_scoped_logger
 from ...lib.resolve import TimebackUserResolutionError, resolve_status_for_user_resolution_error
 from ...lib.utils import error_response
+from ...namespaces.lessons.next import LessonTypeMismatchError
 
 if TYPE_CHECKING:
     from starlette.responses import Response
@@ -31,6 +32,9 @@ def to_lesson_error_response(error: BaseException, message: str) -> Response:
             resolve_status_for_user_resolution_error(error),
         )
 
+    if isinstance(error, LessonTypeMismatchError):
+        return error_response("LESSON_TYPE_MISMATCH", str(error), 400)
+
     detail = str(error) if isinstance(error, Exception) else "Unknown error"
     log.error("%s: %s", message, detail)
     return error_response("INTERNAL_ERROR", detail, 500)