Skip to main content

Python SDK

Official Python SDK for Subscriberbot — recurring-subscription management on the Burdenoff platform.

This SDK is a thin shell over burdenoff-sdk-libs. It mounts the shared platform modules plus the Subscriberbot domain module and a standalone sandbox module, and exposes them as one ergonomic, fully typed client.

Features​

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

Installation​

pip install subscriberbot-sdk

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

Quick Start​

import asyncio
from subscriberbot_sdk import SubscriberbotSDK


async def main():
    # Defaults to the shared prod gateways and the burdenoff_cli_subscriberbot
    # OIDC client. Override the endpoints for local dev.
    sdk = SubscriberbotSDK()

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

    # Subscriberbot-domain operations are nested under sdk.subscriberbot
    providers = await sdk.subscriberbot.providers.list()
    relationships = await sdk.subscriberbot.relationships.list()

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

    await sdk.close()


asyncio.run(main())

Nested namespace​

Per the platform mandate (no compatibility shim), every module surface is nested under its owning module. The Subscriberbot domain bundle keeps its sub-entities nested:

await sdk.subscriberbot.providers.list()
await sdk.subscriberbot.plans.list()
await sdk.subscriberbot.relationships.list()
await sdk.subscriberbot.entitlements.list()
await sdk.subscriberbot.invoices.list()
await sdk.subscriberbot.payment_instruments.list()
await sdk.subscriberbot.workflows.list()
await sdk.subscriberbot.system.health()

Modules​

All methods are async. The following modules are mounted on the SubscriberbotSDK instance: auth, billing, channels, conversations, devportal, export, files, groups, health, integrations, notifications, organizations, products, rbac, sandbox, scheduler, security, store, subscriberbot, support, tags, tours, workspaces.

Configuration​

from subscriberbot_sdk import SubscriberbotSDK

sdk = SubscriberbotSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_subscriberbot",   # default
    oidc_issuer=None,                       # derived from global_endpoint
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Error Handling​

from subscriberbot_sdk import (
    SubscriberbotError,
    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 SubscriberbotError as e:
    print(f"SDK error: {e}")

Development​

git clone https://github.com/algoshred/subscriberbot-sdk-python.git
cd subscriberbot-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
Environment selection

The SDK defaults to production endpoints. Pass explicit workspace_endpoint and global_endpoint for local or alpha. See Environment Selection for endpoint details.