Metadata-Version: 2.4
Name: webex-byods-sdk
Version: 0.2.0
Summary: Reusable Webex Bring Your Own Data Source management utilities
License-Expression: LicenseRef-Cisco-Sample-Code
Project-URL: Repository, https://github.com/WebexCommunity/webex-python-byods-sdk
Project-URL: Issues, https://github.com/WebexCommunity/webex-python-byods-sdk/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: PyJWT>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# Webex BYODS Python SDK

Reusable Python utilities for managing Webex Bring Your Own Data Source (BYODS)
data sources. The SDK supports registration, retrieval, updates, schema
discovery, JWT claim inspection, service-app authentication, and data source
token extension.

The SDK does not read credentials from files, environment variables, or cloud
secret managers. The host application owns secret retrieval and provides an
explicit token provider to the SDK.

## Install

Until publication, install from a local checkout:

```bash
python3 -m pip install -e .
```

## Quick start with a service-app token

1. Create and authorize a [Webex Service App](https://developer.webex.com/create/docs/service-apps).
2. Select `spark-admin:datasource_read` to list data sources and
   `spark-admin:datasource_write` to register, update, or extend them. See the
   [Data Sources API reference](https://developer.webex.com/webex-contact-center/docs/api/v1/data-sources)
   for the required permissions.
3. Retrieve the authorized service app's access token and pass it directly to
   the SDK from your application's secret source. Do not commit it or embed it
   in source code.

```python
from webex_byods import StaticAccessTokenProvider, WebexDataSourceClient

client = WebexDataSourceClient(
    token_provider=StaticAccessTokenProvider(service_app_access_token)
)
data_sources = client.list_all_data_sources()
```

## Refresh service-app tokens

For automatic service-app token acquisition, the host application supplies
credentials and a personal-token provider. It can obtain those values from its
own configuration, AWS Secrets Manager, or another secret system.

```python
from webex_byods import (
    ServiceAppCredentials,
    StaticAccessTokenProvider,
    WebexDataSourceClient,
    WebexServiceAppTokenProvider,
)

credentials = ServiceAppCredentials(
    app_id="service-app-id",
    client_id="service-app-client-id",
    client_secret="service-app-client-secret",
    target_org_id="target-org-id",
)
service_token_provider = WebexServiceAppTokenProvider(
    credentials,
    StaticAccessTokenProvider("personal-access-token"),
)
client = WebexDataSourceClient(token_provider=service_token_provider)
```

`OAuthRefreshTokenProvider` is available when the host application manages an
OAuth refresh token. Providers use `InMemoryTokenStore` by default; applications
that need persistence can supply their own `TokenStore` implementation.

## Use the client

```python
data_sources = client.list_all_data_sources()
schemas = client.get_data_source_schemas()

result = client.extend_data_source_token(
    data_source_id="data-source-id",
    token_lifetime_minutes=1440,
)
```

BYODS API operations return dictionaries containing `success`, `data` or
`error`, and `status_code`. A 401 response causes one retry with
`token_provider.get_access_token(force_refresh=True)`.

`WebexDataSourceManager` remains an alias for `WebexDataSourceClient` during
the transition. `TokenManager` is deprecated; use
`WebexServiceAppTokenProvider` instead.

## Development

```bash
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
ruff check .
```

## License

[Cisco Sample Code License](LICENSE)
