timeback-edubridge 0.1.0__tar.gz

timeback_edubridge-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_edubridge-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: timeback-edubridge
+Version: 0.1.0
+Summary: Python client for the Timeback EduBridge API
+Project-URL: Homepage, https://timeback.ai
+Project-URL: Documentation, https://docs.timeback.ai
+Project-URL: Repository, https://github.com/timeback-ai/timeback-python
+Author: Timeback
+License-Expression: MIT
+Keywords: api,edubridge,education,sdk,timeback
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: timeback-common>=0.1.0
+Description-Content-Type: text/markdown
+
+# Timeback EduBridge Client
+
+Python client for the Timeback EduBridge API with async support.
+
+## Installation
+
+```bash
+pip install timeback-edubridge
+```
+
+## Quick Start
+
+```python
+from timeback_edubridge import EdubridgeClient
+
+# Initialize with explicit configuration
+client = EdubridgeClient(
+    base_url="https://api.timeback.ai",
+    auth_url="https://auth.timeback.ai/oauth2/token",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+
+# Or use environment variables with a prefix
+client = EdubridgeClient(env="PRODUCTION")
+# Reads: PRODUCTION_EDUBRIDGE_BASE_URL, PRODUCTION_EDUBRIDGE_TOKEN_URL, etc.
+```
+
+## Resources
+
+### Enrollments
+
+```python
+# List enrollments for a user
+enrollments = await client.enrollments.list(user_id="user-123")
+
+# Enroll a user in a course
+enrollment = await client.enrollments.enroll(
+    user_id="user-123",
+    course_id="course-456",
+    school_id="school-789",  # Optional
+)
+
+# Unenroll a user
+await client.enrollments.unenroll(
+    user_id="user-123",
+    course_id="course-456",
+)
+
+# Reset goals for a course
+result = await client.enrollments.reset_goals("course-456")
+
+# Reset a user's progress
+await client.enrollments.reset_progress("user-123", "course-456")
+
+# Get default class for a course
+default_class = await client.enrollments.get_default_class("course-456")
+```
+
+### Users
+
+```python
+# List users by role
+users = await client.users.list(roles=["student", "teacher"])
+
+# Convenience methods
+students = await client.users.list_students()
+teachers = await client.users.list_teachers()
+
+# Search users
+results = await client.users.search(
+    roles=["student"],
+    search="john",
+    limit=50,
+)
+
+# With additional filters
+filtered = await client.users.list(
+    roles=["student"],
+    org_sourced_ids=["school-123"],
+    limit=100,
+    offset=0,
+)
+```
+
+### Analytics
+
+```python
+# Get activity for a date range
+activity = await client.analytics.get_activity(
+    student_id="student-123",  # or email="student@example.com"
+    start_date="2025-01-01",
+    end_date="2025-01-31",
+    timezone="America/New_York",
+)
+
+# Get weekly facts
+facts = await client.analytics.get_weekly_facts(
+    student_id="student-123",
+    week_date="2025-01-15",
+)
+
+# Get enrollment-specific facts
+enrollment_facts = await client.analytics.get_enrollment_facts(
+    enrollment_id="enrollment-123",
+    start_date="2025-01-01",
+    end_date="2025-01-31",
+)
+
+# Get highest grade mastered
+grade = await client.analytics.get_highest_grade_mastered(
+    student_id="student-123",
+    subject="Math",
+)
+```
+
+### Applications
+
+```python
+# List all applications
+apps = await client.applications.list()
+
+# Get metrics for an application
+metrics = await client.applications.get_metrics("app-123")
+```
+
+### Subject Tracks
+
+```python
+from timeback_edubridge import SubjectTrackInput
+
+# List all subject tracks
+tracks = await client.subject_tracks.list()
+
+# Create or update a subject track
+track = await client.subject_tracks.upsert(
+    id="track-123",
+    data=SubjectTrackInput(
+        subject="Math",
+        grade_level="9",
+        target_course_id="course-456",
+    ),
+)
+
+# Delete a subject track
+await client.subject_tracks.delete("track-123")
+
+# List subject track groups
+groups = await client.subject_tracks.list_groups()
+```
+
+### Learning Reports
+
+```python
+# Get MAP profile for a user
+profile = await client.learning_reports.get_map_profile("user-123")
+
+# Get time saved metrics
+time_saved = await client.learning_reports.get_time_saved("user-123")
+```
+
+## Context Manager
+
+The client can be used as an async context manager:
+
+```python
+async with EdubridgeClient(base_url="...") as client:
+    enrollments = await client.enrollments.list(user_id="user-123")
+# Client is automatically closed
+```
+
+## Error Handling
+
+```python
+from timeback_edubridge import (
+    EdubridgeError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    APIError,
+)
+
+try:
+    enrollments = await client.enrollments.list(user_id="user-123")
+except AuthenticationError:
+    print("Invalid credentials")
+except ForbiddenError:
+    print("Access denied")
+except NotFoundError:
+    print("Resource not found")
+except ValidationError as e:
+    print(f"Invalid request: {e}")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Environment Variables
+
+When using `env` parameter, the client looks for these variables:
+
+| Variable | Description |
+|----------|-------------|
+| `{PREFIX}_EDUBRIDGE_BASE_URL` | Base URL for the API |
+| `{PREFIX}_EDUBRIDGE_TOKEN_URL` | OAuth2 token endpoint |
+| `{PREFIX}_EDUBRIDGE_CLIENT_ID` | OAuth2 client ID |
+| `{PREFIX}_EDUBRIDGE_CLIENT_SECRET` | OAuth2 client secret |
+
+Without a prefix, it uses the variables without the prefix (e.g., `EDUBRIDGE_BASE_URL`).

timeback_edubridge-0.1.0/README.md

@@ -0,0 +1,209 @@
+# Timeback EduBridge Client
+
+Python client for the Timeback EduBridge API with async support.
+
+## Installation
+
+```bash
+pip install timeback-edubridge
+```
+
+## Quick Start
+
+```python
+from timeback_edubridge import EdubridgeClient
+
+# Initialize with explicit configuration
+client = EdubridgeClient(
+    base_url="https://api.timeback.ai",
+    auth_url="https://auth.timeback.ai/oauth2/token",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+
+# Or use environment variables with a prefix
+client = EdubridgeClient(env="PRODUCTION")
+# Reads: PRODUCTION_EDUBRIDGE_BASE_URL, PRODUCTION_EDUBRIDGE_TOKEN_URL, etc.
+```
+
+## Resources
+
+### Enrollments
+
+```python
+# List enrollments for a user
+enrollments = await client.enrollments.list(user_id="user-123")
+
+# Enroll a user in a course
+enrollment = await client.enrollments.enroll(
+    user_id="user-123",
+    course_id="course-456",
+    school_id="school-789",  # Optional
+)
+
+# Unenroll a user
+await client.enrollments.unenroll(
+    user_id="user-123",
+    course_id="course-456",
+)
+
+# Reset goals for a course
+result = await client.enrollments.reset_goals("course-456")
+
+# Reset a user's progress
+await client.enrollments.reset_progress("user-123", "course-456")
+
+# Get default class for a course
+default_class = await client.enrollments.get_default_class("course-456")
+```
+
+### Users
+
+```python
+# List users by role
+users = await client.users.list(roles=["student", "teacher"])
+
+# Convenience methods
+students = await client.users.list_students()
+teachers = await client.users.list_teachers()
+
+# Search users
+results = await client.users.search(
+    roles=["student"],
+    search="john",
+    limit=50,
+)
+
+# With additional filters
+filtered = await client.users.list(
+    roles=["student"],
+    org_sourced_ids=["school-123"],
+    limit=100,
+    offset=0,
+)
+```
+
+### Analytics
+
+```python
+# Get activity for a date range
+activity = await client.analytics.get_activity(
+    student_id="student-123",  # or email="student@example.com"
+    start_date="2025-01-01",
+    end_date="2025-01-31",
+    timezone="America/New_York",
+)
+
+# Get weekly facts
+facts = await client.analytics.get_weekly_facts(
+    student_id="student-123",
+    week_date="2025-01-15",
+)
+
+# Get enrollment-specific facts
+enrollment_facts = await client.analytics.get_enrollment_facts(
+    enrollment_id="enrollment-123",
+    start_date="2025-01-01",
+    end_date="2025-01-31",
+)
+
+# Get highest grade mastered
+grade = await client.analytics.get_highest_grade_mastered(
+    student_id="student-123",
+    subject="Math",
+)
+```
+
+### Applications
+
+```python
+# List all applications
+apps = await client.applications.list()
+
+# Get metrics for an application
+metrics = await client.applications.get_metrics("app-123")
+```
+
+### Subject Tracks
+
+```python
+from timeback_edubridge import SubjectTrackInput
+
+# List all subject tracks
+tracks = await client.subject_tracks.list()
+
+# Create or update a subject track
+track = await client.subject_tracks.upsert(
+    id="track-123",
+    data=SubjectTrackInput(
+        subject="Math",
+        grade_level="9",
+        target_course_id="course-456",
+    ),
+)
+
+# Delete a subject track
+await client.subject_tracks.delete("track-123")
+
+# List subject track groups
+groups = await client.subject_tracks.list_groups()
+```
+
+### Learning Reports
+
+```python
+# Get MAP profile for a user
+profile = await client.learning_reports.get_map_profile("user-123")
+
+# Get time saved metrics
+time_saved = await client.learning_reports.get_time_saved("user-123")
+```
+
+## Context Manager
+
+The client can be used as an async context manager:
+
+```python
+async with EdubridgeClient(base_url="...") as client:
+    enrollments = await client.enrollments.list(user_id="user-123")
+# Client is automatically closed
+```
+
+## Error Handling
+
+```python
+from timeback_edubridge import (
+    EdubridgeError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    APIError,
+)
+
+try:
+    enrollments = await client.enrollments.list(user_id="user-123")
+except AuthenticationError:
+    print("Invalid credentials")
+except ForbiddenError:
+    print("Access denied")
+except NotFoundError:
+    print("Resource not found")
+except ValidationError as e:
+    print(f"Invalid request: {e}")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Environment Variables
+
+When using `env` parameter, the client looks for these variables:
+
+| Variable | Description |
+|----------|-------------|
+| `{PREFIX}_EDUBRIDGE_BASE_URL` | Base URL for the API |
+| `{PREFIX}_EDUBRIDGE_TOKEN_URL` | OAuth2 token endpoint |
+| `{PREFIX}_EDUBRIDGE_CLIENT_ID` | OAuth2 client ID |
+| `{PREFIX}_EDUBRIDGE_CLIENT_SECRET` | OAuth2 client secret |
+
+Without a prefix, it uses the variables without the prefix (e.g., `EDUBRIDGE_BASE_URL`).

timeback_edubridge-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "timeback-edubridge"
+version = "0.1.0"
+description = "Python client for the Timeback EduBridge API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Timeback" }]
+keywords = ["timeback", "edubridge", "education", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["timeback-common>=0.1.0"]
+
+[tool.uv.sources]
+timeback-common = { workspace = true }
+
+[project.urls]
+Homepage = "https://timeback.ai"
+Documentation = "https://docs.timeback.ai"
+Repository = "https://github.com/timeback-ai/timeback-python"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/timeback_edubridge"]

timeback_edubridge-0.1.0/pytest.ini

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

timeback_edubridge-0.1.0/src/timeback_edubridge/__init__.py

@@ -0,0 +1,158 @@
+"""
+Timeback EduBridge Client
+
+A Python client for the Timeback EduBridge API with async support.
+
+Example:
+    ```python
+    from timeback_edubridge import EdubridgeClient
+
+    client = EdubridgeClient(
+        base_url="https://api.example.com",
+        auth_url="https://auth.example.com/oauth2/token",
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+    )
+
+    # List enrollments for a user
+    enrollments = await client.enrollments.list(user_id="user-123")
+
+    # Get analytics
+    activity = await client.analytics.get_activity(
+        student_id="student-123",
+        start_date="2025-01-01",
+        end_date="2025-01-31",
+    )
+    ```
+"""
+
+from .client import EdubridgeClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    EdubridgeError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+)
+from .types import (
+    # Analytics
+    ActivityMetricsData,
+    AggregatedMetrics,
+    # Applications
+    Application,
+    ApplicationMetrics,
+    DailyActivityMap,
+    # Base
+    DataResponse,
+    # Enrollments
+    DefaultClass,
+    Enrollment,
+    EnrollmentCourse,
+    EnrollmentFacts,
+    EnrollmentGoals,
+    EnrollmentMetadata,
+    EnrollmentMetrics,
+    EnrollmentPeriod,
+    EnrollmentPrimaryApp,
+    EnrollmentRole,
+    EnrollmentSchool,
+    EnrollOptions,
+    GradeMasteryData,
+    GUIDRef,
+    HighestGradeMastered,
+    # Learning Reports
+    MapProfile,
+    # Users
+    PrimaryOrg,
+    ResetGoalsResult,
+    Role,
+    Status,
+    SubjectMetrics,
+    # Subject Track
+    SubjectTrack,
+    SubjectTrackGroup,
+    SubjectTrackInput,
+    SubjectTrackUpsertInput,
+    TimeSaved,
+    TimeSpentMetricsData,
+    User,
+    UserApp,
+    UserCredential,
+    UserId,
+    UserProfile,
+    UserRole,
+    WeeklyFactRecord,
+    WeeklyFacts,
+)
+from .utils import (
+    aggregate_activity_metrics,
+    normalize_boolean,
+    normalize_date,
+    normalize_user,
+)
+
+__all__ = [
+    # Exceptions
+    "APIError",
+    # Analytics
+    "ActivityMetricsData",
+    "AggregatedMetrics",
+    # Applications
+    "Application",
+    "ApplicationMetrics",
+    "AuthenticationError",
+    "DailyActivityMap",
+    # Base
+    "DataResponse",
+    # Enrollments
+    "DefaultClass",
+    # Client
+    "EdubridgeClient",
+    "EdubridgeError",
+    "EnrollOptions",
+    "Enrollment",
+    "EnrollmentCourse",
+    "EnrollmentFacts",
+    "EnrollmentGoals",
+    "EnrollmentMetadata",
+    "EnrollmentMetrics",
+    "EnrollmentPeriod",
+    "EnrollmentPrimaryApp",
+    "EnrollmentRole",
+    "EnrollmentSchool",
+    "ForbiddenError",
+    "GUIDRef",
+    "GradeMasteryData",
+    "HighestGradeMastered",
+    # Learning Reports
+    "MapProfile",
+    "NotFoundError",
+    # Users
+    "PrimaryOrg",
+    "ResetGoalsResult",
+    "Role",
+    "Status",
+    "SubjectMetrics",
+    # Subject Track
+    "SubjectTrack",
+    "SubjectTrackGroup",
+    "SubjectTrackInput",
+    "SubjectTrackUpsertInput",
+    "TimeSaved",
+    "TimeSpentMetricsData",
+    "User",
+    "UserApp",
+    "UserCredential",
+    "UserId",
+    "UserProfile",
+    "UserRole",
+    "ValidationError",
+    "WeeklyFactRecord",
+    "WeeklyFacts",
+    # Utilities
+    "aggregate_activity_metrics",
+    "normalize_boolean",
+    "normalize_date",
+    "normalize_user",
+]