webex-byova 0.1.0__tar.gz

webex_byova-0.1.0/.github/workflows/build-and-test.yml

@@ -0,0 +1,50 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install build
+
+      - name: Ruff
+        run: ruff check src tests
+
+      - name: Pytest
+        run: pytest tests/ -v
+
+      - name: Build
+        if: matrix.python-version == '3.12'
+        run: python -m build
+
+      - name: Upload Distribution Files
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: distribution-files
+          path: dist/

webex_byova-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    uses: ./.github/workflows/build-and-test.yml
+    secrets: inherit
+
+  pypi:
+    needs: build-and-test
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi.org
+    permissions:
+      id-token: write
+    steps:
+      - name: Download Distribution Files
+        uses: actions/download-artifact@v4
+        with:
+          name: distribution-files
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ vars.PYPI_REPOSITORY_URL }}
+          print-hash: true

webex_byova-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+site/
+src/webex_byova/_version.py
+

webex_byova-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to webex-byova
+
+Thank you for contributing to the Webex BYOVA Python SDK.
+
+## Development setup
+
+```bash
+git clone <your-fork>
+cd BYOVA_SDK_STARTER
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+ruff check src tests
+ruff format src tests
+```
+
+## Pull request process
+
+1. Fork the repository and create a feature branch.
+2. Add tests for new behavior.
+3. Ensure `pytest` and `ruff check` pass.
+4. Update documentation under `docs/` for user-facing changes.
+5. Open a pull request with a clear description and test plan.
+
+## Release process (maintainers)
+
+1. Merge changes to `main`.
+2. Create and push a version tag (version is derived from the tag via hatch-vcs):
+
+   ```bash
+   git tag v0.x.x
+   git push origin v0.x.x
+   ```
+
+3. GitHub Actions runs tests, builds the package, and publishes to PyPI via trusted publishing.
+
+### One-time PyPI setup
+
+- Create a GitHub environment named `pypi.org`.
+- Configure [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) for this repository:
+  - Workflow: `release.yml`
+  - Environment: `pypi.org`
+- Optionally set repository variable `PYPI_REPOSITORY_URL` to `https://test.pypi.org/legacy/` for TestPyPI dry runs.
+
+## Code style
+
+- Python 3.10+
+- Type hints encouraged
+- Keep public API documented with docstrings
+- Match existing patterns in `src/webex_byova/`

webex_byova-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webex BYOVA SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

webex_byova-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: webex-byova
+Version: 0.1.0
+Summary: Python SDK for Webex Contact Center BYOVA / BYODS — Data Sources, Service App tokens, and Integration OAuth
+Project-URL: Homepage, https://github.com/Joezanini/byova-sdk-python
+Project-URL: Documentation, https://github.com/Joezanini/byova-sdk-python#readme
+Project-URL: Repository, https://github.com/Joezanini/byova-sdk-python
+Author: Webex BYOVA SDK Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: byods,byova,contact-center,virtual-agent,webex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# webex-byova
+
+Python SDK for **Webex Contact Center BYOVA** and the foundational **Bring Your Own Data Source (BYODS)** APIs.
+
+Simplify Service App token management, Integration OAuth, DataSource CRUD, schema discovery, and JWS verification.
+
+## Install
+
+```bash
+pip install webex-byova
+```
+
+## Quick start
+
+```python
+import asyncio
+from webex_byova import BYOVA
+from webex_byova.models import IntegrationCredentials, ServiceAppCredentials
+
+sdk = BYOVA(
+    integration=IntegrationCredentials(
+        client_id="YOUR_INTEGRATION_CLIENT_ID",
+        client_secret="YOUR_INTEGRATION_CLIENT_SECRET",
+        redirect_uri="http://127.0.0.1:8765/callback",
+    ),
+    service_app=ServiceAppCredentials(
+        client_id="YOUR_SERVICE_APP_CLIENT_ID",
+        client_secret="YOUR_SERVICE_APP_CLIENT_SECRET",
+    ),
+)
+
+async def main():
+  # Developer authorizes Integration (not customer admin)
+  await sdk.integration.aauthorize(
+      scopes=[
+          "spark:applications_token",
+          "application:webhooks_write",
+          "application:webhooks_read",
+      ],
+      open_browser=True,
+  )
+
+  await sdk.webhooks.aensure_service_app_webhooks(
+      target_url="https://your-app.example.com/webhooks/webex",
+  )
+
+asyncio.run(main())
+```
+
+After a customer admin authorizes your Service App in Control Hub, handle the webhook:
+
+```python
+result = await sdk.ahandle_service_app_webhook(webhook_json)
+client = await sdk.aget_client_for_org(result.org_id)
+sources = await client.data_sources.alist()
+```
+
+## Environment variables
+
+```bash
+export WEBEX_INTEGRATION_CLIENT_ID=...
+export WEBEX_INTEGRATION_CLIENT_SECRET=...
+export WEBEX_SA_CLIENT_ID=...
+export WEBEX_SA_CLIENT_SECRET=...
+export WEBEX_INTEGRATION_REDIRECT_URI=http://127.0.0.1:8765/callback
+```
+
+```python
+sdk = BYOVA.from_env()
+```
+
+## Documentation
+
+See the [docs/](docs/) directory and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

webex_byova-0.1.0/README.md

@@ -0,0 +1,78 @@
+# webex-byova
+
+Python SDK for **Webex Contact Center BYOVA** and the foundational **Bring Your Own Data Source (BYODS)** APIs.
+
+Simplify Service App token management, Integration OAuth, DataSource CRUD, schema discovery, and JWS verification.
+
+## Install
+
+```bash
+pip install webex-byova
+```
+
+## Quick start
+
+```python
+import asyncio
+from webex_byova import BYOVA
+from webex_byova.models import IntegrationCredentials, ServiceAppCredentials
+
+sdk = BYOVA(
+    integration=IntegrationCredentials(
+        client_id="YOUR_INTEGRATION_CLIENT_ID",
+        client_secret="YOUR_INTEGRATION_CLIENT_SECRET",
+        redirect_uri="http://127.0.0.1:8765/callback",
+    ),
+    service_app=ServiceAppCredentials(
+        client_id="YOUR_SERVICE_APP_CLIENT_ID",
+        client_secret="YOUR_SERVICE_APP_CLIENT_SECRET",
+    ),
+)
+
+async def main():
+  # Developer authorizes Integration (not customer admin)
+  await sdk.integration.aauthorize(
+      scopes=[
+          "spark:applications_token",
+          "application:webhooks_write",
+          "application:webhooks_read",
+      ],
+      open_browser=True,
+  )
+
+  await sdk.webhooks.aensure_service_app_webhooks(
+      target_url="https://your-app.example.com/webhooks/webex",
+  )
+
+asyncio.run(main())
+```
+
+After a customer admin authorizes your Service App in Control Hub, handle the webhook:
+
+```python
+result = await sdk.ahandle_service_app_webhook(webhook_json)
+client = await sdk.aget_client_for_org(result.org_id)
+sources = await client.data_sources.alist()
+```
+
+## Environment variables
+
+```bash
+export WEBEX_INTEGRATION_CLIENT_ID=...
+export WEBEX_INTEGRATION_CLIENT_SECRET=...
+export WEBEX_SA_CLIENT_ID=...
+export WEBEX_SA_CLIENT_SECRET=...
+export WEBEX_INTEGRATION_REDIRECT_URI=http://127.0.0.1:8765/callback
+```
+
+```python
+sdk = BYOVA.from_env()
+```
+
+## Documentation
+
+See the [docs/](docs/) directory and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

webex_byova-0.1.0/docs/authentication.md

@@ -0,0 +1,33 @@
+# Authentication
+
+## Responsibilities
+
+| Actor | Action |
+|-------|--------|
+| Developer | Authorize Integration via SDK |
+| Developer | Register webhooks, host HTTPS endpoint |
+| Customer admin | Authorize Service App in Control Hub |
+| SDK | Fetch/store per-org Service App tokens |
+
+## Token storage
+
+Implement `TokenStorage` for production (Redis, database, secrets manager):
+
+```python
+from webex_byova.auth import TokenStorage
+
+class RedisTokenStorage:
+    async def get_integration_tokens(self): ...
+    async def set_integration_tokens(self, tokens): ...
+    # ...
+```
+
+Default: `InMemoryTokenStorage` (development only).
+
+## Paths to Service App tokens
+
+**Webhook (production):** `handle_service_app_webhook` after customer admin authorizes.
+
+**Manual (sandbox):** `await sdk.service_app.asave_registration(org_id, refresh_token)`
+
+**On-demand:** `await sdk.service_app.afetch_token_for_org(org_id)` when org is already authorized.

webex_byova-0.1.0/docs/automated-token-flow.md

@@ -0,0 +1,37 @@
+# Automated Token Flow
+
+End-to-end flow for multi-tenant BYOVA apps.
+
+```mermaid
+sequenceDiagram
+  participant Dev as Developer
+  participant SDK as webex_byova
+  participant WX as Webex
+  participant Admin as CustomerAdmin
+
+  Dev->>SDK: integration.authorize()
+  Dev->>SDK: webhooks.ensure_service_app_webhooks(url)
+  Admin->>WX: Authorize Service App in Control Hub
+  WX->>Dev: POST webhook authorized
+  Dev->>SDK: handle_service_app_webhook(payload)
+  SDK->>WX: POST /applications/{id}/token
+  Dev->>SDK: get_client_for_org(org_id)
+  Dev->>SDK: data_sources.create(...)
+```
+
+## Steps
+
+1. **Developer** runs `integration.authorize()` (Integration OAuth).
+2. **Developer** calls `webhooks.ensure_service_app_webhooks(target_url)`.
+3. **Customer admin** authorizes the Service App in Control Hub.
+4. **Your HTTPS endpoint** receives `serviceApp` / `authorized` webhook.
+5. Call `sdk.ahandle_service_app_webhook(payload)` — SDK fetches and stores org tokens.
+6. Use `aget_client_for_org(org_id)` for DataSource CRUD.
+
+## Deauthorization
+
+On `deauthorized`, `handle_service_app_webhook` removes stored tokens for that org.
+
+## Service App events use webhooks (not Mercury)
+
+Unlike [webex_bot](https://github.com/fbradyirl/webex_bot) messaging bots, Service App lifecycle events are delivered via **HTTPS webhooks only**, not Webex Mercury WebSockets.

webex_byova-0.1.0/docs/credentials.md

@@ -0,0 +1,36 @@
+# Credentials
+
+The SDK uses a **two-tier credential model**. You supply all OAuth client credentials from the Webex Developer Portal.
+
+## Integration (developer-owned)
+
+| Field | Description |
+|-------|-------------|
+| `client_id` | Integration Client ID |
+| `client_secret` | Integration Client Secret |
+| `redirect_uri` | Must match a redirect URI on the Integration |
+
+Used for: Integration OAuth, webhook registration, fetching Service App tokens per org.
+
+**Who authorizes:** The developer who owns the Integration — via `integration.authorize()`.
+
+## Service App (per customer org)
+
+| Field | Description |
+|-------|-------------|
+| `client_id` | Service App Client ID |
+| `client_secret` | Service App Client Secret |
+
+Used for: Request body when calling `POST /applications/{id}/token`; Bearer token on DataSource API calls.
+
+**Who authorizes:** Each customer's Full Admin in Control Hub — not via SDK OAuth.
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WEBEX_INTEGRATION_CLIENT_ID` | Integration client ID |
+| `WEBEX_INTEGRATION_CLIENT_SECRET` | Integration client secret |
+| `WEBEX_INTEGRATION_REDIRECT_URI` | OAuth redirect (default `http://127.0.0.1:8765/callback`) |
+| `WEBEX_SA_CLIENT_ID` | Service App client ID |
+| `WEBEX_SA_CLIENT_SECRET` | Service App client secret |

webex_byova-0.1.0/docs/data-sources.md

@@ -0,0 +1,42 @@
+# Data Sources
+
+## CRUD operations
+
+```python
+client = await sdk.aget_client_for_org(org_id)
+
+# List
+items = await client.data_sources.alist()
+
+# Create
+from webex_byova.models import DataSourceCreate
+ds = await client.data_sources.acreate(DataSourceCreate(
+    audience="MyApp",
+    subject="callAudioData",
+    nonce="unique-nonce",
+    schema_id="78efc775-dccb-45ca-9acf-989a4a59f788",
+    url="https://dap.example.com/ingest",
+    token_lifetime_minutes=60,
+))
+
+# Get / Update / Delete
+detail = await client.data_sources.aget(ds.id)
+await client.data_sources.aupdate(ds.id, {"status": "disabled", "errorMessage": "maintenance"})
+await client.data_sources.adelete(ds.id)
+```
+
+## Schemas
+
+```python
+schemas = await client.schemas.alist()
+schema = await client.schemas.aget(schema_id)
+```
+
+## Token extension
+
+Update with a new `nonce` and `tokenLifetimeMinutes` before the JWS token expires (max 1440 minutes).
+
+## Scopes
+
+- Read: `spark-admin:datasource_read`
+- Write: `spark-admin:datasource_write`

webex_byova-0.1.0/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting Started
+
+## Prerequisites
+
+1. A [Webex Developer](https://developer.webex.com/) account
+2. A **Webex Integration** with scopes:
+   - `spark:applications_token`
+   - `application:webhooks_write`
+   - `application:webhooks_read`
+3. A **Webex Service App** with BYODS scopes:
+   - `spark-admin:datasource_read`
+   - `spark-admin:datasource_write`
+4. Redirect URI registered on the Integration (e.g. `http://127.0.0.1:8765/callback`)
+
+## Install
+
+```bash
+pip install webex-byova
+```
+
+## Authorize Integration and register webhooks
+
+```python
+import asyncio
+from webex_byova import BYOVA
+from webex_byova.models import IntegrationCredentials, ServiceAppCredentials
+
+sdk = BYOVA(
+    integration=IntegrationCredentials(...),
+    service_app=ServiceAppCredentials(...),
+)
+
+async def setup():
+    await sdk.integration.aauthorize(
+        scopes=[
+            "spark:applications_token",
+            "application:webhooks_write",
+            "application:webhooks_read",
+        ],
+    )
+    await sdk.webhooks.aensure_service_app_webhooks(
+        "https://your-server.example.com/webhooks/webex"
+    )
+
+asyncio.run(setup())
+```
+
+## Register a data source
+
+After a customer admin authorizes your Service App, handle the `authorized` webhook, then:
+
+```python
+client = await sdk.aget_client_for_org(org_id)
+await client.data_sources.acreate({
+    "audience": "MyVirtualAgent",
+    "subject": "callAudioData",
+    "nonce": "unique-nonce-string",
+    "schemaId": "<schema-uuid>",
+    "url": "https://your-dap.example.com/ingest",
+    "tokenLifetimeMinutes": 60,
+})
+```

webex_byova-0.1.0/docs/index.md

@@ -0,0 +1,19 @@
+# webex-byova
+
+Python SDK for Webex Contact Center **Bring Your Own Virtual Agent (BYOVA)** and **Bring Your Own Data Source (BYODS)**.
+
+## Features
+
+- **Integration OAuth** with built-in redirect listener (`integration.authorize()`)
+- **Service App tokens** per organization (webhook-driven or manual)
+- **DataSource CRUD** — register, list, update, delete data sources
+- **Schema discovery** — list and inspect BYODS schemas
+- **JWS verification** — validate inbound tokens from Webex
+
+## Install
+
+```bash
+pip install webex-byova
+```
+
+See [Getting Started](getting-started.md) for the full walkthrough.

webex_byova-0.1.0/docs/integration-oauth.md

@@ -0,0 +1,45 @@
+# Integration OAuth
+
+The developer authorizes the **Integration** on their own behalf. The SDK provides a built-in redirect listener — no separate OAuth server required for local development.
+
+## Primary flow: `authorize()`
+
+```python
+tokens = await sdk.integration.aauthorize(
+    scopes=[
+        "spark:applications_token",
+        "application:webhooks_write",
+        "application:webhooks_read",
+    ],
+    open_browser=True,
+    timeout=300,
+)
+```
+
+This will:
+
+1. Build the authorization URL
+2. Start a temporary HTTP server on `redirect_uri`
+3. Open the system browser (optional)
+4. Capture `?code=` from the redirect
+5. Exchange the code and store tokens
+
+## Manual / CI flow
+
+```python
+url, state = sdk.integration.get_authorization_url(scopes=[...])
+# Complete OAuth in browser, then:
+tokens = await sdk.integration.aexchange_code(code)
+```
+
+## Redirect URI requirements
+
+- Must be registered on your Integration in the Developer Portal
+- `http://127.0.0.1:8765/callback` works for local development
+- Production integrations may use HTTPS callbacks on your own server; use `exchange_code()` if you handle the redirect externally
+
+## Token refresh
+
+```python
+token = await sdk.integration.aget_access_token()  # auto-refreshes if expired
+```

webex_byova-0.1.0/docs/jws-verification.md

@@ -0,0 +1,28 @@
+# JWS Verification
+
+When Webex sends data to your DAP endpoint, it includes a JWS token in the request header. Verify it before processing:
+
+```python
+claims = sdk.verify_jws_token(jws_token)
+# or async:
+claims = await sdk.averify_jws_token(jws_token)
+```
+
+## Regions
+
+```python
+from webex_byova import BYOVAConfig
+
+config = BYOVAConfig(region="eu")  # uses EU JWK endpoint
+sdk = BYOVA(..., config=config)
+```
+
+US JWK: `https://idbroker.webex.com/idb/oauth2/v2/keys/verificationjwk`
+
+EU JWK: `https://idbroker-eu.webex.com/idb/oauth2/v2/keys/verificationjwk`
+
+## Security
+
+- Rotate `nonce` regularly on data source updates
+- Refresh tokens before `tokenLifetimeMinutes` expires
+- Never log full JWS tokens in production