feat: initialize BYODS Python SDK

Author: Adam Weeks

.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[aws]" pytest ruff
+      - run: ruff check .
+      - run: python -m pytest -q

.gitignore

@@ -0,0 +1,10 @@
+token-config.json
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/

LICENSE

@@ -0,0 +1,81 @@
+                           CISCO SAMPLE CODE LICENSE
+                                  Version 1.1
+                Copyright (c) 2018 Cisco and/or its affiliates
+
+   These terms govern this Cisco Systems, Inc. ("Cisco"), example or demo
+   source code and its associated documentation (together, the "Sample
+   Code"). By downloading, copying, modifying, compiling, or redistributing
+   the Sample Code, you accept and agree to be bound by the following terms
+   and conditions (the "License"). If you are accepting the License on
+   behalf of an entity, you represent that you have the authority to do so
+   (either you or the entity, "you"). Sample Code is not supported by Cisco
+   TAC and is not tested for quality or performance. This is your only
+   license to the Sample Code and all rights not expressly granted are
+   reserved.
+
+   1. LICENSE GRANT: Subject to the terms and conditions of this License,
+      Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non-
+      transferable, non-sublicensable, royalty-free license to copy and
+      modify the Sample Code in source code form, and compile and
+      redistribute the Sample Code in binary/object code or other executable
+      forms, in whole or in part, solely for use with Cisco products and
+      services. For interpreted languages like Java and Python, the
+      executable form of the software may include source code and
+      compilation is not required.
+
+   2. CONDITIONS: You shall not use the Sample Code independent of, or to
+      replicate or compete with, a Cisco product or service. Cisco products
+      and services are licensed under their own separate terms and you shall
+      not use the Sample Code in any way that violates or is inconsistent
+      with those terms (for more information, please visit:
+      www.cisco.com/go/terms).
+
+   3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample
+      Code, including all intellectual property rights therein, except with
+      respect to any third-party material that may be used in or by the
+      Sample Code. Any such third-party material is licensed under its own
+      separate terms (such as an open source license) and all use must be in
+      full accordance with the applicable license. This License does not
+      grant you permission to use any trade names, trademarks, service
+      marks, or product names of Cisco. If you provide any feedback to Cisco
+      regarding the Sample Code, you agree that Cisco, its partners, and its
+      customers shall be free to use and incorporate such feedback into the
+      Sample Code, and Cisco products and services, for any purpose, and
+      without restriction, payment, or additional consideration of any kind.
+      If you initiate or participate in any litigation against Cisco, its
+      partners, or its customers (including cross-claims and counter-claims)
+      alleging that the Sample Code and/or its use infringe any patent,
+      copyright, or other intellectual property right, then all rights
+      granted to you under this License shall terminate immediately without
+      notice.
+
+   4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION
+      WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR
+      DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL,
+      AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION,
+      PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE
+      POSSIBILITY OF SUCH DAMAGES.
+
+   5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES
+      ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT
+      WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY
+      LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND
+      WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR
+      CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-
+      INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY,
+      ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT
+      WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL
+      USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT
+      ERROR OR DEFECT.
+
+   6. GENERAL: This License shall be governed by and interpreted in
+      accordance with the laws of the State of California, excluding its
+      conflict of laws provisions. You agree to comply with all applicable
+      United States export laws, rules, and regulations. If any provision of
+      this License is judged illegal, invalid, or otherwise unenforceable,
+      that provision shall be severed and the rest of the License shall
+      remain in full force and effect. No failure by Cisco to enforce any of
+      its rights related to the Sample Code or to a breach of this License
+      in a particular situation will act as a waiver of such rights. In the
+      event of any inconsistencies with any other terms, this License shall
+      take precedence.

README.md

@@ -0,0 +1,76 @@
+# Webex BYODS Python SDK
+
+Reusable Python utilities for managing Webex Bring Your Own Data Source (BYODS)
+data sources. The SDK supports data source registration, retrieval, updates,
+schema discovery, JWT claim inspection, service-app authentication, and data
+source token extension.
+
+This repository is the source of truth for the SDK. The companion CLI project
+uses this package as a consumer.
+
+## Install
+
+Until the package is published, install it directly from a local checkout:
+
+```bash
+python3 -m pip install -e .
+```
+
+Install AWS Secrets Manager support when running in Lambda or supplying a
+secret name:
+
+```bash
+python3 -m pip install -e ".[aws]"
+```
+
+## Configure authentication
+
+Copy the safe template and provide service-app credentials plus a personal
+token that can request service-app tokens:
+
+```bash
+cp token-config.json.template token-config.json
+```
+
+Do not commit `token-config.json`.
+
+## Use the SDK
+
+```python
+from webex_byods import TokenManager, WebexDataSourceManager
+
+token_manager = TokenManager(config_path="token-config.json")
+client = WebexDataSourceManager(
+    token_manager.get_service_app_token(), token_manager=token_manager
+)
+
+data_sources = client.list_all_data_sources()
+schemas = client.get_data_source_schemas()
+```
+
+BYODS API operations preserve a dictionary result contract containing
+`success`, `data` or `error`, and `status_code`. If a data-source API request
+returns HTTP 401, the client obtains a fresh service-app token and retries the
+request once.
+
+To rotate a data source nonce and obtain a fresh JWS token:
+
+```python
+result = token_manager.extend_data_source_token(
+    data_source_id="data-source-id",
+    token_lifetime_minutes=1440,
+)
+```
+
+## Development
+
+```bash
+python3 -m pip install -e ".[aws]"
+python3 -m pip install pytest ruff
+python3 -m pytest -q
+ruff check .
+```
+
+## License
+
+[Cisco Sample Code License](LICENSE)

pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "webex-byods-sdk"
+version = "0.1.0"
+description = "Reusable Webex Bring Your Own Data Source management utilities"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.31.0",
+    "PyJWT>=2.8.0",
+]
+
+[project.optional-dependencies]
+aws = ["boto3>=1.28.0"]
+dev = ["pytest>=7", "ruff>=0.5"]
+
+[project.urls]
+Repository = "https://github.com/WebexCommunity/webex-python-byods-sdk"
+Issues = "https://github.com/WebexCommunity/webex-python-byods-sdk/issues"
+
+[tool.setuptools]
+packages = ["webex_byods"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tests/test_auth.py

@@ -0,0 +1,72 @@
+from unittest.mock import Mock, patch
+
+import jwt
+
+from webex_byods import TokenManager
+
+
+@patch("webex_byods.auth.uuid.uuid4", return_value="new-nonce")
+@patch("webex_byods.auth.requests.put")
+@patch("webex_byods.auth.requests.get")
+def test_extend_data_source_token_updates_nonce_and_preserves_claim_values(
+    get, put, uuid4
+):
+    jws_token = jwt.encode(
+        {
+            "aud": "audience-from-token",
+            "sub": "subject-from-token",
+            "com.cisco.datasource.schema.uuid": "schema-from-token",
+        },
+        "unused",
+        algorithm="HS256",
+    )
+    get_response = Mock(status_code=200)
+    get_response.json.return_value = {
+        "jwsToken": jws_token,
+        "url": "https://gateway.example.com/data",
+        "status": "active",
+    }
+    get.return_value = get_response
+    put_response = Mock(status_code=200)
+    put_response.json.return_value = {"tokenExpiryTime": "2026-07-10T00:00:00Z"}
+    put.return_value = put_response
+    manager = TokenManager(config_path="unused.json")
+    manager.get_service_app_token = Mock(return_value="service-token")
+
+    result = manager.extend_data_source_token("source-1", 60)
+
+    assert result == {
+        "success": True,
+        "data": {"tokenExpiryTime": "2026-07-10T00:00:00Z"},
+        "nonce_updated": "new-nonce",
+        "token_lifetime_minutes": 60,
+        "token_expiry": "2026-07-10T00:00:00Z",
+        "message": "Data source token extended successfully. New expiry: 2026-07-10T00:00:00Z",
+    }
+    put.assert_called_once_with(
+        "https://webexapis.com/v1/dataSources/source-1",
+        headers={
+            "Authorization": "Bearer service-token",
+            "Content-Type": "application/json",
+        },
+        json={
+            "audience": "audience-from-token",
+            "nonce": "new-nonce",
+            "schemaId": "schema-from-token",
+            "subject": "subject-from-token",
+            "url": "https://gateway.example.com/data",
+            "tokenLifetimeMinutes": 60,
+            "status": "active",
+        },
+    )
+
+
+def test_extend_data_source_token_rejects_lifetime_over_limit():
+    result = TokenManager(config_path="unused.json").extend_data_source_token(
+        "source-1", 1441
+    )
+
+    assert result == {
+        "success": False,
+        "error": "Token lifetime cannot exceed 1440 minutes (24 hours). Requested: 1441 minutes",
+    }

tests/test_client.py

@@ -0,0 +1,81 @@
+from unittest.mock import Mock, call, patch
+
+from webex_byods import WebexDataSourceManager
+
+
+@patch("webex_byods.client.requests.request")
+def test_list_data_sources_returns_existing_result_shape(request):
+    response = Mock(status_code=200)
+    response.json.return_value = {"items": [{"id": "source-1"}]}
+    request.return_value = response
+
+    result = WebexDataSourceManager("token").list_all_data_sources()
+
+    assert result == {
+        "success": True,
+        "data": {"items": [{"id": "source-1"}]},
+        "status_code": 200,
+    }
+    request.assert_called_once_with(
+        "GET",
+        "https://webexapis.com/v1/dataSources",
+        headers={
+            "Authorization": "Bearer token",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        timeout=30,
+    )
+
+
+@patch("webex_byods.client.requests.request")
+def test_request_retries_once_after_token_refresh(request):
+    expired_response = Mock(status_code=401)
+    refreshed_response = Mock(status_code=200)
+    refreshed_response.json.return_value = {"items": []}
+    request.side_effect = [expired_response, refreshed_response]
+    token_manager = Mock()
+    token_manager.get_service_app_token.return_value = "new-token"
+
+    result = WebexDataSourceManager("old-token", token_manager=token_manager).list_all_data_sources()
+
+    assert result["success"] is True
+    token_manager.get_service_app_token.assert_called_once_with(force_refresh=True)
+    assert request.call_args_list == [
+        call(
+            "GET",
+            "https://webexapis.com/v1/dataSources",
+            headers={
+                "Authorization": "Bearer old-token",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout=30,
+        ),
+        call(
+            "GET",
+            "https://webexapis.com/v1/dataSources",
+            headers={
+                "Authorization": "Bearer new-token",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout=30,
+        ),
+    ]
+
+
+@patch("webex_byods.client.requests.request")
+def test_schema_cache_is_loaded_once(request):
+    response = Mock(status_code=200)
+    response.json.return_value = {
+        "items": [{"id": "schema-1", "serviceType": "Contact Center"}]
+    }
+    request.return_value = response
+    manager = WebexDataSourceManager("token")
+
+    assert manager.get_schema_display_name("schema-1") == "Contact Center (schema-1...)"
+    assert manager.get_available_schemas() == [
+        {"id": "schema-1", "serviceType": "Contact Center"}
+    ]
+    assert request.call_count == 1