Metadata-Version: 2.5
Name: burdenoff-hookmovies-sdk
Version: 2026.1102.1
Summary: Official Python SDK for Hookmovies — thin shell over burdenoff-sdk-libs
Project-URL: Homepage, https://github.com/algoshred/hookmovies-sdk-python
Project-URL: Documentation, https://docs.algoshred.com/sdk/python
Project-URL: Repository, https://github.com/algoshred/hookmovies-sdk-python
Project-URL: Issues, https://github.com/algoshred/hookmovies-sdk-python/issues
Project-URL: Changelog, https://github.com/algoshred/hookmovies-sdk-python/blob/main/CHANGELOG.md
Author-email: "Vignesh T.V" <vignesh@algoshred.com>
Maintainer-email: "Vignesh T.V" <vignesh@algoshred.com>
License: Copyright (c) 2025 Burdenoff Consultancy Services Private Limited, Algoshred Technologies Private Limited and all sister companies.
        
        All rights reserved.
        
        This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without the express written permission of the copyright holders.
        
        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.
        
        For licensing inquiries, please contact: legal@algoshred.com
License-File: LICENSE
Keywords: api-client,burdenoff,graphql,hookmovies,media,python,sdk,streaming,video-on-demand
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: burdenoff-sdk-libs>=2026.1101.2
Requires-Dist: httpx>=0.24.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == 'docs'
Requires-Dist: sphinx>=6.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# burdenoff-hookmovies-sdk

Official Python SDK for **HookMovies**, the multi-language streaming network on the Burdenoff platform. It gives you typed async clients for the catalog (titles, studios, people, episodes), short-form clips, rights windows, entitlements and public embeds, plus helpers for the embeddable player.

The package is a thin shell over [`burdenoff-sdk-libs`](https://pypi.org/project/burdenoff-sdk-libs/); the import name is `hookmovies_sdk`. Its TypeScript twin is [`@burdenoff/hookmovies-sdk`](https://www.npmjs.com/package/@burdenoff/hookmovies-sdk).

## Features

- Async/await throughout, built on `httpx`
- Dual-endpoint GraphQL client (workspace + global gateways)
- `sdk.hookmovies` with titles, clips, rights, entitlements, embeds and the rest of the HookMovies domain
- Anonymous public-embed lookup and the app's `<iframe>` snippet
- Multiple auth flows: email/password, device code, PKCE, client credentials
- Automatic token refresh, typed error hierarchy, `py.typed`

## Installation

```bash
pip install burdenoff-hookmovies-sdk
```

## Quick Start

```python
import asyncio
from hookmovies_sdk import HookmoviesSDK, HokCreateEmbedInput, HokPaginationInput


async def main():
    # Defaults to the production gateways. Override with constructor arguments
    # or HOOKMOVIES_WORKSPACE_ENDPOINT / HOOKMOVIES_GLOBAL_ENDPOINT.
    sdk = HookmoviesSDK()
    await sdk.auth.sign_in(email="user@example.com", password="secret")

    page = await sdk.hookmovies.titles.list(HokPaginationInput(limit=20), status="PUBLISHED")
    title = page.items[0]

    clips = await sdk.hookmovies.clips.list(HokPaginationInput(limit=10), title_id=title.id)
    windows = await sdk.hookmovies.rights.list(title_id=title.id)
    access = await sdk.hookmovies.entitlements.check(title.id, "IN")

    embed = await sdk.hookmovies.embeds.create(
        HokCreateEmbedInput(title_id=title.id, kind="TRAILER")
    )
    print(sdk.embed_url(embed.public_id))
    print(sdk.iframe_snippet(embed.public_id, title=title.title))

    await sdk.close()


asyncio.run(main())
```

## Embeds and the public player

`iframe_snippet` returns the same responsive snippet the HookMovies app shows on a title's Embeds panel. `get_public_embed` resolves an embed anonymously, exactly like the player inside a third-party page: it sends no credentials, returns `None` for unknown or revoked embeds, and its `media_url` / `poster_url` are presigned until `expires_at`. Failures raise the usual SDK errors (`NetworkError`, or `HookmoviesError` when the gateway rejects the request). It runs the shared `burdenoff-sdk-libs` operation on a credential-less client.

```python
from hookmovies_sdk import embed_url, get_public_embed, iframe_snippet

public = await get_public_embed("<publicId>")  # no SDK instance or sign-in needed
html = iframe_snippet("<publicId>", title="My Film")
```

`sdk.hookmovies.embeds` also has `list(pagination, status, title_id)` and `revoke(id)`; a revoked embed's public link stops resolving.

## Modules

All methods are async. Only modules whose GraphQL documents validate against the production supergraph (the sdk-libs Operation Conformance check) are mounted: `auth`, `conversations`, `export`, `files`, `groups`, `health`, `hookmovies`, `integrations`, `notifications`, `organizations`, `products`, `rbac`, `security`, `store`, `support`, `tags`, `tours`, `workspaces`.

`sdk.hookmovies` nests the domain: `titles`, `studios`, `people`, `episodes`, `productions`, `auditions`, `reviews`, `lists`, `entitlements`, `watch_progress`, `rights`, `clips`, `embeds`, `analytics`.

## Configuration

```python
from hookmovies_sdk import HookmoviesSDK

sdk = HookmoviesSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_hookmovies",   # 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,
    app_origin="https://app.hookmovies.com",  # app shell serving the public player
)
```

## Error Handling

```python
from hookmovies_sdk import (
    HookmoviesError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in(email="user@example.com", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except HookmoviesError as e:
    print(f"SDK error: {e}")
```

## Releases

Versions are CalVer (`YYYY.MDD.PATCH`). A release is cut from `.github/workflows/release.yml` (tag push or manual dispatch) and published to PyPI by CI; the version is stamped at build time and never committed back.

## Development

```bash
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
```

## License

Proprietary — Copyright Burdenoff Consultancy Services Pvt. Ltd.

## Support

- Issues: [GitHub Issues](https://github.com/algoshred/hookmovies-sdk-python/issues)
