Skip to main content

Python SDK

Official Python SDK for TimeCampus — a privacy-first AI time-intelligence platform on the Burdenoff platform.

Features​

  • Async/await throughout, built on httpx
  • Dual-endpoint GraphQL client (workspace + global gateways)
  • 23 mounted modules: shared platform set + timecampus + sandbox
  • Multiple auth flows: email/password, device code, PKCE, client credentials
  • Automatic token refresh
  • Typed error hierarchy
  • Full type hints with py.typed marker

Install​

pip install timecampus-sdk

# Development install
pip install -e ".[dev]"

Quick start​

import asyncio
from timecampus_sdk import TimecampusSDK


async def main():
    # Defaults to production Burdenoff gateways.
    # Override via BURDENOFF_ENV or constructor args for local dev.
    sdk = TimecampusSDK()

    # Sign in with email/password
    await sdk.auth.sign_in(email="[email protected]", password="secret")

    # TimeCampus-domain operations are nested under sdk.timecampus
    entries = await sdk.timecampus.time_entries.list()
    projects = await sdk.timecampus.projects.list()

    # Shared cross-product modules are mounted at the top level
    tags = await sdk.tags.list()

    await sdk.close()


asyncio.run(main())

Configuration​

from timecampus_sdk import TimecampusSDK

sdk = TimecampusSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_timecampus",
    oidc_issuer=None,
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Endpoints are resolved in this order: constructor argument, product-prefixed environment variable (TIMECAMPUS_WORKSPACE_ENDPOINT, TIMECAMPUS_GLOBAL_ENDPOINT), generic environment variable (BURDENOFF_WORKSPACE_ENDPOINT, BURDENOFF_GLOBAL_ENDPOINT), and finally the production gateways.

Nested namespace​

Per the platform mandate, every module surface is nested under its owning module:

await sdk.timecampus.time_entries.list()
await sdk.timecampus.projects.list()
await sdk.timecampus.tasks.list()
await sdk.timecampus.approvals.list()
await sdk.timecampus.expenses.list()
await sdk.timecampus.meetings.list()
await sdk.timecampus.pomodoro.list()
await sdk.timecampus.focus_scores.list()

Modules​

All methods are async. Mounted modules: auth, billing, channels, conversations, devportal, export, files, groups, health, integrations, notifications, organizations, products, rbac, sandbox, scheduler, security, store, support, tags, timecampus, tours, workspaces.

Error handling​

from timecampus_sdk import (
    TimecampusError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in(email="[email protected]", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except TimecampusError as e:
    print(f"SDK error: {e}")

Development​

git clone https://github.com/algoshred/timecampus-sdk-python.git
cd timecampus-sdk-python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

make format        # black + isort
make lint          # flake8
make type-check    # mypy (strict)
make test          # pytest
make sanity        # format-check + lint + type-check + test (cov>=80) + build

Source​

Published as timecampus-sdk on PyPI; source at github.com/algoshred/timecampus-sdk-python.

Next steps​