script.service.ultimate/lib/streaming_providers/providers/_template/README.md

# Provider template

Copy this directory to `providers/{your_provider}/`, rename the classes,
and fill in the stubs. Read this file first — it explains the contract.

## What you get for free

- HTTP manager setup, proxying, retries.
- Credential storage / Kodi sync via the base `settings_manager` (if the
  provider needs credentials).
- Token caching and session persistence (in your Auth class, if you have one).
- Capability flags (`implements_vod`, `implements_epg`, `implements_recordings`,
  ...) — derived from whether you wire up the corresponding manager.
- Shared error types, shared `VodPage` shape, shared `Content`/`Channel`
  data model.

## What you implement

1. **Provider** — `provider.py`. Required. Declares the provider's class
   members, wires up whatever managers it has, and exposes the public
   interface.
2. **Auth** — `auth.py`. Optional. Required only if the provider
   authenticates requests. Free / static-key providers can omit it
   entirely, or provide a minimal `Auth` that only sets base headers.
3. **Managers** — one file per capability the provider supports. Each
   subclasses the corresponding ABC from `base/managers/` and implements
   the abstract methods. **All seven managers are optional** — a
   VOD-only provider has no `ChannelManager`; a linear-only provider has
   no `VodManager`; a favorites-sync-only provider may have neither.
   See "The manager ABCs" below.
4. **Constants** — `constants.py`. URLs, endpoints, static headers.
5. **Models** — often required. A custom `AuthToken` subclass is
   mandatory whenever the auth class returns a `BaseAuthToken`, because
   `BaseAuthToken` is an ABC with an abstract `to_dict()`. A custom
   Channel subclass is optional. See "Models" below.

## Files in this template

    provider.py             orchestrator (required)
    auth.py                 token + credential surface (if the provider authenticates)
    models.py               AuthToken subclass (mandatory with auth); Channel/Credentials examples
    constants.py            URLs, paths, headers, parameter names, PROVIDER_NAME
    channel_manager.py      ChannelManager + module-scope content-id parsers
    vod_manager.py          VodManager
    epg_manager.py          EpgManager
    recordings_manager.py   RecordingsManager
    favorites_manager.py    FavoritesManager
    bookmarks_manager.py    BookmarksManager
    catchup_manager.py      CatchupManager
    drm_manager.py          dedicated DRM manager (a protocol, not an ABC) + patterns

Delete the files for capabilities the provider does not have.

## Provider class members

Every provider declares these. Some are abstract (must be implemented by
the concrete class, or the class cannot be instantiated); some are class
attributes with defaults.

### Required abstract property

    @property
    def provider_name(self) -> str: ...

**This is abstract on StreamingProvider.** A subclass that does not
override it cannot be instantiated — Python raises
`TypeError: Can't instantiate abstract class ... with abstract method
provider_name` the moment the registry calls `YourProvider(country=...)`.

The failure is silent if you don't notice it: the registry catches the
exception, logs "Failed to create instance for {name}: ..." at ERROR
level, and moves on. The provider simply does not appear in the UI. If
your provider is registered but never instantiates, this is the first
thing to check.

The value is the provider's machine identifier — lowercase, no spaces,
used in settings keys, log lines, and the `provider` field on models.
It should match the plugin directory name and the `PROVIDER_NAME`
constant in `constants.py`.

    @property
    def provider_name(self) -> str:
        return "your_provider_name"

### Required class attributes

    PROVIDER_LABEL: ClassVar[str]
        Display name, e.g. "simpliTV". Used by the registry and the UI.

    PROVIDER_LOGO: ClassVar[str]
        Logo URL.

    SUPPORTED_AUTH_TYPES: ClassVar[List[str]]
        e.g. ["user_credentials"], ["anonymous"], or ["user_credentials",
        "anonymous"] if the provider supports both.

    SUPPORTED_COUNTRIES: ClassVar[List[str]]
        ALWAYS set this. See "SUPPORTED_COUNTRIES is not optional" below.

### SUPPORTED_COUNTRIES is not optional

**Always declare `SUPPORTED_COUNTRIES`.** Never leave it at the base
default. The base class defines it as an empty list, which has a
specific meaning: "the provider does not support country-specific
instances." That meaning is easy to collide with the accidental case of
"the author forgot to declare it," and the failure mode is silent — the
provider shows up in every country's list or in none, depending on
which code path reads it.

Declare it explicitly, even for a single-country provider:

    # Single country
    SUPPORTED_COUNTRIES: ClassVar[List[str]] = ["AT"]

    # Multi-country with per-country instances
    SUPPORTED_COUNTRIES: ClassVar[List[str]] = ["hr", "pl", "me", "at", "hu"]

    # Multi-country with per-country instances but no explicit list —
    # the provider discovers its country at runtime (Discovery+ shape)
    SUPPORTED_COUNTRIES: ClassVar[List[str]] = ["*"]

The three cases:

* **Single country** — one-element list. The registry creates one
  instance for that country.
* **Multi-country** — one instance per listed country. `country` is a
  constructor argument; each instance is independent.
* **Wildcard** — `["*"]`. The registry creates one instance for the
  default country; the provider discovers its actual country at
  runtime (e.g. from a `/users/me` call).

An empty list is reserved for providers with no country concept at all
(a purely global, country-agnostic service). If you find yourself
wanting to leave it empty because "I'm not sure yet," declare `["*"]`
instead — it's honest about the ambiguity and behaves correctly in
both the registry and the runtime.

### Cross-check: what the registry reads

The registry's `ProviderMetadata._extract_metadata` reads these members
before any instance exists. If any are missing or wrong, the provider
misbehaves in the UI even if the runtime works.

    PROVIDER_LABEL                -> metadata.label
    PROVIDER_LOGO                 -> metadata.logo
    SUPPORTED_AUTH_TYPES          -> metadata.supported_auth_types
    SUPPORTED_COUNTRIES           -> metadata.supported_countries
    class.__name__                -> metadata.plugin_name (derived)

The plugin name is derived from the class name:
`cls.__name__.lower().replace("provider", "")`. `YourProvider` becomes
`your`. If your class name is non-standard the derived name will be
wrong — pick a class name whose lowercase form (minus the word
"provider") matches your intended plugin name.

## Models

The base package provides `Content` (the base dataclass) and its
subclass `Channel`. Both are dataclasses, and providers build on them
rather than replacing them.

### `Content` — the base dataclass

`Content` holds every field that all provider content shares: name,
id, provider, manifest URLs, DRM placeholders, metadata, pricing.
`Channel` extends it with channel-specific fields. See
`base/models/content.py` and `base/models/channel.py` for the full
field list.

**Key fields and how to set them:**

- `manifest: Optional[str]` — the static manifest URL, when the
  provider has one. Set directly, or via `set_static_manifest(url)`.
- `manifest_script: Optional[str]` — for dynamic manifests, provider-
  specific parameters fetched at request time. Set via
  `set_dynamic_manifest(params)`.
- `session_manifest: bool` — True when the manifest must be fetched
  per-session. Mutually exclusive with `manifest` in practice: if
  `session_manifest=True` and `manifest` is also set, `Channel`'s
  `_validate_fields` logs a warning and the static URL is ignored.
- `streaming_format: Optional[str]` — `"dash"`, `"hls"`, or None.
  Serialized as `"StreamingFormat"` in `to_dict()`.

**Do not set both `manifest` and `manifest_script` and expect both to
be used.** They are alternatives. If the provider fetches the manifest
per-session, use `set_dynamic_manifest` and leave `manifest` None.

**Serialization key convention.** `to_dict()` emits TitleCase keys
(`Name`, `Id`, `Provider`, `Manifest`, `StreamingFormat`, ...). A
subclass adding fields via `result["YourField"] = ...` must match this
convention — TitleCase, no underscores. Downstream consumers expect
uniform keys.

### `Channel` — the base channel dataclass

`Channel` extends `Content` with `channel_number`, `is_radio`, and
`catchup_hours`. It also provides:

**Three factory classmethods — use these, don't construct directly:**

    Channel.create_live_channel(name, channel_id, provider, **kwargs)
    Channel.create_vod_channel(name, content_id, provider, **kwargs)
    Channel.create_radio_channel(name, channel_id, provider, **kwargs)

Each sets `mode` and `content_type` (and `is_radio`/`quality` for
radio) correctly, so the resulting object never trips the
`__post_init__` consistency warnings. The factories use `cls(...)`, so
a subclass `SimpliTVChannel.create_live_channel(...)` returns a
`SimpliTVChannel`, not a base `Channel`. Subclasses should use the
inherited factories rather than construct directly.

**Note the parameter-name inconsistency:** `create_live_channel` and
`create_radio_channel` take `channel_id`, while `create_vod_channel`
takes `content_id`. All three set the dataclass field `content_id`
internally. If you call `create_vod_channel(channel_id=...)` you get
`TypeError`. Pass positionally or use the right keyword.

**`__post_init__` mutates `content_type` and `quality` for radio.** If
`is_radio=True` and `content_type="LIVE"`, the base class rewrites the
content_type to `"RADIO"` and quality to `"AUDIO"`. This happens in the
base class, so a subclass that sets these differently must account for
it (or pass `content_type` and `quality` explicitly and skip the
`is_radio=True` path). See `channel.py`'s `__post_init__`.

**`__post_init__` also logs warnings for inconsistent fields.** A
`Channel` with `mode="vod"` and `content_type="LIVE"` gets a warning,
not an exception. Same for `session_manifest=True` combined with a
static `manifest`. These are advisory — the code runs — but they
indicate a likely provider bug. Check the logs during development; a
clean startup log with no `Channel ...:` warnings is the goal.

**`detect_and_set_radio()` is heuristic and mutates in place.** It
looks at `name`, `quality`, `description`, and `genre` for radio
indicators and sets `is_radio=True` if any match. Providers whose
channel classification is authoritative (from an API field) should set
`is_radio` at construction and not call this method. Providers whose
classification comes from names or metadata can call it after
construction.

### Subclassing `Channel`

A provider that carries extra per-channel fields subclasses `Channel`
and adds them. MoveTV, Discovery, HRTi, and simpliTV all do this.

Rules:

1. **Call `super().to_dict()` and add fields in TitleCase.** The base
   serializer emits TitleCase; subclasses must match.

2. **Keep the base field names and defaults.** Add new fields at the
   end with sensible defaults, so existing construction patterns
   (positional or keyword) don't break.

3. **Do not remove or rename base fields.** Downstream consumers read
   `channel_id` / `content_id`, `name`, `manifest`, and the other base
   fields. If the provider needs a differently-named field, add it as
   a new field rather than renaming.

4. **Use the inherited factory methods.** `YourChannel.create_live_channel(...)`
   returns a `YourChannel` because the factories use `cls(...)`. Do not
   override them unless you need to change what they set.

Example:

    @dataclass
    class YourChannel(Channel):
        codename: str = ""
        recording_id: str = ""
        recording_status: str = ""

        def to_dict(self) -> Dict[str, Any]:
            result = super().to_dict()
            result["Codename"] = self.codename
            result["RecordingId"] = self.recording_id
            result["RecordingStatus"] = self.recording_status
            return result

### The `StreamingChannel` alias

`base/models/channel.py` ends with:

    StreamingChannel = Channel

`StreamingChannel` and `Channel` are the same class. Providers and
consumers may import either name; both refer to the same type.
Do not treat them as distinct classes — `isinstance(x, StreamingChannel)`
and `isinstance(x, Channel)` are identical checks.

### `StreamingMode` and `ContentType` are not Enums

`base/models/content.py` defines them as plain classes with string
class attributes:

    class StreamingMode:
        LIVE = "live"
        VOD = "vod"

    class ContentType:
        LIVE = "LIVE"
        VOD = "VOD"
        SERIES = "SERIES"
        MOVIE = "MOVIE"
        RADIO = "RADIO"

Consequences:

- Compare with `==`, not `is`. `channel.mode == StreamingMode.LIVE`
  works; `channel.mode is StreamingMode.LIVE` is fragile (string
  interning makes it usually work, but not guaranteed).
- `isinstance(x, StreamingMode)` never works. There is no instance of
  `StreamingMode` — it's a namespace, not a type.
- Do not `import Enum` and try to `StreamingMode.LIVE.value`. The
  attribute is already a string.

If you find yourself wanting stricter typing, use the string values
directly (`"live"`, `"vod"`, `"LIVE"`, ...). The classes exist for
readability and autocomplete, not type enforcement.

### `AuthToken` subclasses

`BaseAuthToken` is an ABC with an abstract `to_dict()`, so it cannot be
instantiated directly. Every provider whose `_perform_authentication()`
returns a `BaseAuthToken` needs a concrete subclass — usually tiny:

    @dataclass
    class YourAuthToken(BaseAuthToken):
        def to_dict(self) -> Dict[str, Any]:
            return {
                "access_token": self.access_token,
                "token_type": self.token_type,
                "expires_in": self.expires_in,
                "issued_at": self.issued_at,
                "refresh_token": self.refresh_token,
                "refresh_expires_in": self.refresh_expires_in,
                "auth_level": self.auth_level.value,
                "credential_type": self.credential_type,
            }

If the provider doesn't persist tokens, `to_dict()` is never called at
runtime — but it still must exist, because the ABC requires it. Provide
a real implementation so that a future change to persist tokens works
without a follow-up edit.

### `Credentials` subclasses (optional)

Only needed when the provider's login payload isn't the usual
`{username, password}` shape. HRTi's `grant_access` takes
`{Username, Password, OperatorReferenceId}`, so it has a custom
`HRTiCredentials(UserPasswordCredentials)` with a `to_auth_payload()`
override. Most providers use `UserPasswordCredentials` directly.

## The manager ABCs

There are **seven** manager ABCs. **All seven are optional.** A provider
implements the ones its service offers and returns `None` from the
corresponding `_build_*()` for the rest.

    ChannelManager     -- live channels, channel manifest, channel DRM
    VodManager         -- browseable VOD catalogue
    EpgManager         -- EPG
    RecordingsManager  -- cloud / network PVR
    FavoritesManager   -- user favorites on programs / channels
    BookmarksManager   -- resume positions
    CatchupManager     -- timeshift / restart

**The rule: if a capability area has a public interface in the base
layer, it gets a manager ABC. If the provider has the capability, wire
the manager; if not, return `None` from the factory.** The base layer's
`ProviderRecordingsMixin`, `ProviderFavoritesMixin`,
`ProviderBookmarksMixin`, and `ProviderCatchupMixin` correspond
one-to-one to the four optional managers. Do not fold a capability into
another manager because the data happens to come from the same
endpoint — the public interface is the contract, not the URL.

### Providers vary in which managers they have

Common shapes:

    Linear-only free provider    -> ChannelManager + EpgManager
    Linear + catchup             -> ChannelManager + EpgManager + CatchupManager
    VOD-only                     -> VodManager
    VOD + linear                 -> ChannelManager + VodManager
    Linear + recordings          -> ChannelManager + RecordingsManager (+ EpgManager)
    Metadata-only (EPG feed)     -> EpgManager only
    Favorites-sync-only          -> FavoritesManager only

Do not assume "every provider has channels." Do not assume "every
provider has VOD." Do not assume "every provider has EPG." If a
capability is missing, `_build_*()` returns `None`, the capability flag
is `False`, and callers that gate on the flag skip it cleanly.

### Constructor contract

All seven managers share the same constructor contract:

    def __init__(
        self,
        *,
        http_manager,
        auth,
        country,
        config,
        your_extra_collaborator=None,     # optional, subclass-specific
    ):
        super().__init__(
            http_manager=http_manager,
            auth=auth,
            country=country,
            config=config,
        )
        self._your_extra_collaborator = your_extra_collaborator

The base constructor accepts ONLY the four required collaborators. There
is no `**provider_opts` passthrough. This is deliberate: a typo at a call
site (`channel_cache=` instead of `channels_cache=`) raises `TypeError`
immediately rather than silently producing a half-configured manager.

Subclasses declare their extra keyword-only args explicitly, call
`super().__init__` with only the four required, and store extra state on
`self` after the super call.

Managers never hold a reference to the provider. If you need something
the provider owns, inject it at construction.

### Cross-manager collaborators

Some managers need collaborators from other managers. Common cases:

* **CatchupManager** needs `channels` (to resolve a live manifest URL or
  a stream uid) and/or `epg` (to resolve an epg_id from a start_time).
* **RecordingsManager** *may* need `channels` if the provider resolves
  a recording's manifest through the channel manager (simpliTV does
  this by default; the recordings manager itself never implements
  `get_manifest`, so the collaborator is only needed if the recordings
  manager fetches supplementary channel metadata).
* **DrmManager** (dedicated architecture) may need `channels` or `vod`
  to look up an asset's DRM config.
* **FavoritesManager** and **BookmarksManager** rarely need other
  managers, but if the content_id needs resolving to a program id, they
  may need a lookup helper.

Pass these as explicit keyword-only constructor arguments. The provider
builds them in dependency order:

    self.channels = self._build_channels()
    self.epg = self._build_epg()
    self.recordings = self._build_recordings()
    self.catchup = self._build_catchup()   # sees channels + epg
    ...

Don't introduce cycles between managers. If two managers need each
other, one of them should own the shared state and the other should
borrow it via a cache argument, not via a mutual reference.

If you find that a manager needs a provider-owned cache that isn't
otherwise exposed, pass the cache dict itself as a keyword-only
collaborator (as `playback_cache` is passed to simpliTV's channel and
catchup managers). Do not reach back to the provider.

Managers may also need each other's **content-id parsers**. Put the
parsers at module scope in the primary content-id namespace file
(usually `channel_manager.py`), and import them where needed. Parsers
are pure functions — no cross-manager state is involved.

### Capability flags

The provider exposes a derived boolean per capability:

    @property
    def implements_channels(self) -> bool:
        return self.channels is not None

    @property
    def implements_vod(self) -> bool:
        return self.vod is not None

    @property
    def implements_epg(self) -> bool:
        return self.epg is not None

    @property
    def implements_recordings(self) -> bool:
        return self.recordings is not None

    @property
    def implements_favorites(self) -> bool:
        return self.favorites is not None

    @property
    def implements_bookmarks(self) -> bool:
        return self.bookmarks is not None

    @property
    def implements_catchup(self) -> bool:
        return self.catchup is not None

    @property
    def implements_drm(self) -> bool:
        # See the DRM section for the folded-vs-dedicated derivation.

The pattern is uniform: a capability is present iff its manager object is
present. There is no separate boolean to keep in sync.

## Return-value rule: None vs exception

This is the single most important convention. Every manager follows it.

**Return None / [] for "not in my domain."**

`get_channel_manifest("clip_123")` from a channel manager that only
handles live channels returns `None`. Not an error — the router uses it
to fall through to the VOD manager. Same for `get_vod_manifest`,
`get_channel_drm`, `get_vod_drm`, `get_epg`, `get_recordings`,
`get_favorites`, `get_bookmarks`.

**Raise for genuine failures.**

- `AuthError` — token expired or invalid. Caller refreshes and retries.
- `GeoBlockError` — content not available in the caller's region.
- `EntitlementError` — authenticated but not subscribed.
- `RateLimitError` — caller should back off.
- `ServerError`, `TransportError` — transient.
- `PlaybackRestrictedError` — refused for a non-entitlement reason.
- `NotFoundError` — the provider knows this content belongs in its domain
  but has been removed.
- `BadRequestError` — 400 from the wrong endpoint. Not swallowed by the
  router; providers that use 400 as a routing signal should override
  `handles_content_id()` instead.

`NotFoundError` and `None` mean different things, and the router preserves
the distinction:

    provider.get_manifest("gone_123")     -> raises NotFoundError
    provider.get_manifest("unknown_456")  -> returns None

The router tracks any `NotFoundError` raised by a manager, tries the next
manager, and re-raises the last `NotFoundError` if nobody resolved. So a
caller can distinguish "removed" from "not in anyone's domain."

Rule of thumb: **"I don't handle this" is a return value; "this is a real
failure" is an exception.**

## Routing with handles_content_id()

The router pattern in the provider's `_route()` helper is used for
methods whose input is an **opaque content_id** with multiple possible
owners. In practice that means:

    get_manifest(content_id)  -> channel | vod | catchup (whichever owns it)
    get_drm(content_id, ...)  -> channel | vod (whichever owns it)

Not every capability needs routing:

* **Capabilities with their own ID namespace** (recordings) don't route.
  `get_recordings()` and `delete_recording(recording_id)` are named
  methods on the recordings manager. The caller names the capability
  explicitly; there is no ambiguity to resolve.
* **Capabilities that operate on all content** (EPG, favorites,
  bookmarks) don't route. `get_epg(channel_id, ...)`,
  `add_favorite(content_id)`, `update_bookmark(content_id)` are named
  methods that go straight to their manager.
* **Capabilities that need cross-manager collaborators** (catchup) route
  through the provider if their content_id namespace overlaps with
  another manager's, or are called directly on their manager otherwise.

The rule: **route when a content_id could belong to more than one
manager. Otherwise, name the capability explicitly.**

### handles_content_id

For managers that DO participate in routing, override
`handles_content_id()` when the manager's content_id grammar has a
distinguishable shape:

    # In your VodManager:
    def handles_content_id(self, content_id: str) -> bool:
        return content_id.startswith(("details_", "clip_", "program_"))

    # In your ChannelManager:
    def handles_content_id(self, content_id: str) -> bool:
        return content_id.startswith(("live:", "vod:", "series:"))

If your provider has no content_id grammar, leave it returning `True` and
the router falls back to try-and-catch.

Which managers typically override `handles_content_id`:

* **ChannelManager**, **VodManager**, **CatchupManager** — yes.
  Content-id grammar usually has a prefix or shape that discriminates.
* **EpgManager** — has `handles_channel_id()`, used internally by
  `get_epg_grid()`. Does not participate in `_route`.
* **RecordingsManager** — has `handles_recording_id()` for the case
  where multiple recordings managers exist (cloud PVR + local PVR,
  say). Does not participate in `_route` for content_id, because
  recordings have their own ID namespace.
* **FavoritesManager**, **BookmarksManager** — usually no. They operate
  on whatever content_id the caller provides; there is no grammar to
  discriminate on.

`BadRequestError` is intentionally not caught by the router. Providers
that use a 400 response as an endpoint-dispatch signal (like Magenta's
page-vs-component guess) should override `handles_content_id()` instead,
so the router never has to guess.

### Parsers vs. dispatch

Two separate concerns that look similar:

* **Grammar**: what content_id shapes a manager will accept. Exposed
  as `handles_content_id()`. A manager whose grammar covers several
  prefixes returns True for all of them.

* **Dispatch**: which manager the router tries for a given id. This is
  the router's own decision, expressed by what it passes to `_route()`
  (or by explicit prefix branches above `_route`).

They can differ. In simpliTV:

* The channel manager's grammar covers `live:` and `rec:` — it accepts
  both.
* The router routes both through `_route` uniformly, because they
  resolve to the same endpoint.
* The catchup manager's grammar covers `catchup:<codename>@<ts>` — but
  the router does NOT route catchup through `_route`, because it needs
  to parse the `@<ts>` suffix and pass it as an argument.

The rule: **route through `_route` when the manager needs only the
content_id. Add an explicit prefix branch above `_route` when the
manager needs parsed arguments (a timestamp, an episode index, a
query-like suffix).** One parser, in the router.

### Content-id grammar parsers

Put content-id grammar parsers at module scope in the file that owns
the provider's primary content-id namespace (usually
`channel_manager.py`):

    def parse_live_id(content_id): ...
    def parse_recording_id(content_id): ...
    def parse_catchup_id(content_id): ...

Other managers and the provider import them from there. Do not
duplicate the parsers per manager — one grammar, one parser, imported
everywhere it's needed.

Parsers should raise `BadRequestError` on malformed input. The router
does not catch `BadRequestError`, so a malformed id surfaces to the
caller rather than silently falling through to the wrong manager.

Parsers must live at module scope, not as class methods, so multiple
managers can import them without a circular dependency.

### Multiple managers with the same prefix

Two managers may claim the same content-id prefix if their
responsibilities are disjoint. simpliTV:

* `SimpliTVChannelManager` accepts `rec:<codename>` for manifest and
  DRM — the streaming side.
* `SimpliTVRecordingsManager` owns `get_recordings` and
  `delete_recording` — the list side.

Only one of them participates in `_route` for the prefix, and the
choice is which manager owns the manifest fetch. The provider's
`get_manifest` is the authoritative declaration of that choice.

Do not give the same prefix two router branches. Two branches for the same prefix means two code paths for the same content, and they will
drift.

### Sentinels for unused ABC parameters

If the ABC's method signature requires a parameter your provider's API
does not use, prefer `None` for optional arguments. The
`CatchupManager.get_catchup_manifest` signature declares `end_time` as
`Optional[int]` for exactly this reason — providers whose catchup API
only takes a start bound can pass `None` and document that they ignore
it.

Never pass `None` where the ABC expects `int`. Never pass `0` without a
comment — `0` is ambiguous (a valid timestamp? a "no value" marker?).
Prefer `None` when the ABC permits it; if it doesn't, add a comment
explaining the sentinel.

### Routing for recordings manifests

Some providers (simpliTV) route a recording's manifest through the
channel manager, because the API shares the codename namespace between
a channel and its recordings. Others may route through the VOD manager
or a dedicated playback path.

The routing lives in the provider's `get_manifest`, not in the
recordings manager. The recordings manager owns the *list* and the
*delete*; manifest resolution is the router's job. See
`providers/simplitv/provider.py` for a concrete example — it routes the
`rec:` prefix to the channel manager, whose `handles_content_id`
accepts it alongside `live:`.

Do not add a `get_manifest` method to `RecordingsManager`.

### Private helpers used by multiple managers

If a helper function is used by more than one manager, it is public by
default. Name it without the underscore.

    # Bad: catchup_manager imports _prefer_dash from channel_manager
    from .channel_manager import _prefer_dash

    # Good: the helper is public
    from .channel_manager import prefer_dash

The underscore-prefixed convention is for helpers private to one file.
An underscore-prefixed name imported across modules is a signal the
helper should either be renamed public or moved to a shared module
(`constants.py`, or a new `helpers.py`).

## The Auth protocol

Auth is a documented protocol (see `base/protocols.py`), not an ABC.
**Auth is optional** — a free provider that never authenticates requests
does not need one at all.

### Providers without auth

Some providers need no authentication:

* Free, public-content providers with no user accounts.
* Static-API-key providers where the key never changes and is best
  expressed in `constants.py` headers.
* Providers where every request is anonymous and no session state is
  carried.

For these, `_build_auth()` returns `None`, `self.auth = None`, and any
manager that receives `auth=None` must not call its methods. This is
supportable but produces a warning from the manager base constructors
(the `AuthProtocol` isinstance check fires). If you are writing a
provider with no auth:

* Return `None` from `_build_auth()`.
* Either accept the warning (it is non-fatal — the manager still
  constructs and runs), or
* Provide a minimal `Auth` stub that only implements `build_headers()`
  and returns the static headers. This is usually cheaper than
  suppressing the warning, because managers that call `auth.build_headers()`
  still work.

Minimal no-auth stub:

    class YourNoAuth:
        """Auth stub for a provider with no authentication."""

        def get_access_token(self, force_refresh=False):
            return ""

        def build_headers(self, token=None, **opts):
            return {"User-Agent": "...", "Accept": "application/json"}

        def invalidate(self):
            pass

        # Credential methods are no-ops for a no-auth provider.
        def has_credentials(self):
            return True

        def set_credentials(self, username, password):
            return False

        def clear_credentials(self):
            return False

Wire it as `self.auth = YourNoAuth()` in `_build_auth()`. The manager
ABCs' isinstance check passes (all three required methods are present),
and `build_headers()` returns whatever static headers the provider
needs.

### Providers with auth

Every provider with auth writes:

    get_access_token(force_refresh=False) -> str
        Raw token string. No scheme prefix.

    build_headers(token=None, **opts) -> Dict[str, str]
        Request-ready headers including auth. If token is None, use the
        cached token (via get_access_token).

    invalidate() -> None
        Drop cached token and session state. Called after 401s.

Optional extensions — implement only if needed:

    get_scoped_token(scope, **opts) -> Optional[str]
        Secondary tokens. RTL+ uses this for bedrock / upfront.

    get_session_context() -> Optional[Dict[str, Any]]
        Opaque session state needed by build_headers. Magenta uses this
        for guest device/session ids; Discovery for cookie + session-state
        headers.

    authorize_playback(content_id, **opts) -> Dict[str, Any]
        Provider-specific pre-playback step. HRTi's AuthorizeSession,
        MoveTV's live-source fetch, Discovery's playbackInfo POST,
        RTL+'s upfront token, Magenta's persona JWT retrieval.

There is no fixed interface for `authorize_playback`. The name is a
convention; the shape is provider-specific.

**Thread safety.** If the host serves requests from multiple threads
(which it does), and your auth flow involves more than one HTTP call
(e.g. login + device registration, or login + feature-flags fetch), wrap
`get_access_token()` and any other stateful accessor in a
`threading.RLock`. Without it, two threads hitting a cold cache will each
start the full flow, and the second one will either duplicate the work
or observe partial state. Providers whose auth flow is a single HTTP
call can skip the lock; providers whose flow has two or more round-trips
need it.

**Token placement deviation: not in a header.** Some providers pass the
token as a URL query parameter or body field rather than an
`Authorization` header. simpliTV does this — `build_headers()` returns
base headers only, and callers attach the token via
`auth.with_token(url)` / `auth.auth_body()`. If your provider deviates
this way, document it prominently in your `auth.py` module docstring
**and** add a one-line comment at every manager call site that uses
`build_headers()`, so a future reader doesn't assume a bearer token is
being sent.

When the query-parameter name differs per endpoint (simpliTV's
`GetRecordings` uses `tokenValue` instead of `token`), put both names in
`constants.py` and give `with_token()` a `param=` keyword so the caller
can pick. Do not hardcode the parameter name in the auth class.

**Content-Type deviation: JSON body, non-JSON header.** Some endpoints
reject `Content-Type: application/json` even though the body is valid
JSON, and return a different (often empty) response when the header is
"correct". simpliTV's `/Authenticate` is the canonical example: it
requires `Content-Type: text/plain` with a JSON body. If your provider
has an endpoint like this, send the body as a raw string
(`data=json.dumps(payload)`) with the header set explicitly **for that
call only**, and add a comment explaining why — a future reader will
otherwise "fix" the header and silently break the login.

The manager ABCs verify `auth` against `AuthProtocol` at construction
time via `isinstance` (this works because the protocol is
`@runtime_checkable`). The check confirms method *presence*, not
signatures — a mismatched signature will not be caught here. A warning
from this check means the `auth` object is missing one of the three
required methods; it is not fatal, but it usually means a wiring
mistake.

### Credentials — how they get loaded, saved, and re-checked

The `AuthProtocol` names the three *token* methods. It does not name the
*credential* methods, because credentials only exist for providers that
have them. But every provider that has credentials must implement the
credential surface correctly, or the auth class works only when the
caller passes credentials directly at construction — which never happens
in the real runtime. This is the failure mode most likely to slip
through a naive implementation: the provider instantiates cleanly,
`_build_auth` returns an object, and then the first `get_access_token()`
raises `CredentialsError` because nothing ever populated the
credentials.

The three credential methods:

    has_credentials() -> bool
        Return True if this auth can authenticate right now — i.e.
        credentials are available from the constructor argument, the
        settings manager, or a fallback that always succeeds.
        Called by the UI and the registry to decide whether the
        provider is usable.

    set_credentials(username, password) -> bool
        Persist credentials via
        settings_manager.save_provider_credentials(provider_name,
        UserPasswordCredentials(username, password), country).
        Called by the settings UI when the user enters credentials.
        Return True on success.

    clear_credentials() -> bool
        Clear stored credentials via
        settings_manager.clear_provider_credentials(...) or
        credential_manager.delete_credentials(provider_name, country).
        Also call self.invalidate() to drop the cached token.
        Return True on success.

**Credentials source priority, checked in this order:**

1. **Constructor argument.** The provider's `_build_auth()` passes
   `credentials=self._credentials`, which is non-None only when the
   caller constructed the provider with explicit credentials. This is
   the case for CLI tools and tests, not for the runtime UI flow.
2. **Injected `settings_manager`.** If the host passed a
   `settings_manager` to the provider's constructor (or the provider
   forwards one to `_build_auth`), call
   `settings_manager.get_provider_credentials(provider_name, country)`.
   This reads credentials the settings UI wrote through
   `save_provider_credentials`. **This path is preferred when present,
   but is not guaranteed to be present.**
3. **`CredentialManager` (direct file read).** The host's provider
   registry constructs providers *without* a settings_manager, so in
   normal runtime the injected-manager path above is a no-op. Fall back
   to reading `credentials.json` directly:

        from ...base.auth.credential_manager import CredentialManager
        creds = CredentialManager().load_credentials(provider, country)

   `CredentialManager.load_credentials` tries the country-nested format
   (`{"provider": {"country": {...}}}`) first and falls back to the flat
   format (`{"provider": {...}}`), so a single call covers both storage
   layouts. Do not branch on the format yourself.
4. **Fallback.** Providers with anonymous or free access return a
   fallback credentials object from `get_fallback_credentials()` (as
   `BaseAuthenticator` does). The fallback is what lets the auth class
   succeed even when the user hasn't configured anything — useful for
   providers that offer a limited anonymous tier.

**Implementing this in the template `auth.py`.** Wrap paths 2 and 3 in
a single `_load_stored_credentials()` helper that tries the
settings_manager first (guarded by `hasattr` and a try/except, because
it may be None), then falls back to `CredentialManager`. The auth
class's `_resolve_credentials()` calls that helper only if
`self._credentials` is None.

The template's `auth.py` implements this whole surface
(`has_credentials`, `set_credentials`, `clear_credentials`,
`_load_stored_credentials`, `_ensure_credentials`) and the provider's
`_build_auth()` forwards `credentials=self._credentials`. Keep both.

**Re-read credentials on every authenticate, not just at construction.**
A user can store credentials through the UI at any time after the
provider was constructed. If your auth class caches
`self._credentials = None` at construction and never re-reads, the
provider stays broken until the app restarts. The pattern from
`BaseAuthenticator` is:

    def _ensure_credentials(self) -> bool:
        # 1. If current credentials are valid, keep them.
        if self._credentials and self._credentials.validate():
            return True
        # 2. Otherwise try the settings manager / CredentialManager,
        #    in case the user just stored them.
        fresh = self._load_stored_credentials()
        if fresh and fresh.validate():
            self._credentials = fresh
            return True
        # 3. Otherwise try the fallback.
        self._credentials = self.get_fallback_credentials()
        return self._credentials is not None and self._credentials.validate()

Call `_ensure_credentials()` at the start of `_perform_authentication()`,
before building the login payload. This makes the auth class work
whether credentials were supplied at construction, stored by the UI
before first use, or stored by the UI after the provider was already
running.

**Reference.** The full pattern lives in
`base/auth/base_auth.py`:
`_load_credentials_from_manager`, `_ensure_credentials`,
`save_credentials`, `clear_stored_credentials`, `has_stored_credentials`.
Read them before writing your auth class.

**Providers with no user credentials** (anonymous-only, static-key,
free):

* `has_credentials()` returns `True` unconditionally.
* `set_credentials()` and `clear_credentials()` are no-ops returning
  `False` (there is nothing to store).
* `_ensure_credentials()` in `_perform_authentication` is not needed —
  the login flow doesn't depend on stored credentials.

### Per-authenticate credential flow

A correct `_perform_authentication()` looks like this:

    def _perform_authentication(self):
        if not self._ensure_credentials():
            raise CredentialsError(
                f"no credentials available for {self.provider_name}"
            )
        payload = self._build_login_payload(self._credentials)
        resp = self.http_manager.post(
            self._login_url(), json=payload, headers=self.build_headers()
        )
        return self._create_token_from_response(resp.json())

The critical piece is `_ensure_credentials()`. Without it, the auth
class silently depends on the caller having passed credentials — which
the registry never does.

### Session persistence is optional

Not every provider persists tokens. simpliTV, for example, uses a plain
opaque token with no refresh flow, so re-authenticating is cheap and
the auth class caches the token in-process only. No
`_save_session()` / `_load_session()` calls.

If your provider *does* persist tokens, use the settings_manager:

    # In get_access_token, after _perform_authentication():
    self.settings_manager.save_token_data(
        provider_name, token.to_dict(), country
    )

    # At construction:
    stored = self.settings_manager.load_token_data(provider_name, country)
    if stored:
        self._cached_token = self._token_from_dict(stored)

Decide whether persistence is worth the complexity. Providers with
cheap re-auth should skip it. Providers whose auth flow is expensive
(multi-step, has a rate limit, or requires user interaction like a
device code) should persist.

## DRM

DRM is optional. Providers with no DRM leave `_build_drm()` returning
`None` and don't override `get_channel_drm` / `get_vod_drm`. The
provider's `get_drm()` returns `[]` and `implements_drm` is `False`.

Providers with DRM make two independent choices.

### Architecture: dedicated manager vs. folded into managers

    Rule: Does the DRM step share state with the manifest step?
          yes -> fold into the channel/vod managers
          no  -> use a dedicated DRM manager

    Tie-breaker: when both work, prefer the dedicated manager, because it
    keeps DRM logic in one place. Folded exists for cases where the
    alternative would be plumbing session state, an upfront token, or a
    playbackInfo response between two managers that both need it.

"State" means any value the DRM step would otherwise have to receive
from the manifest step: a session id, an upfront token, a playbackInfo
response, an account/licence structure, and so on.

### Source pattern: how the licence URL is produced

Four source patterns appear across the existing providers. The source
pattern is orthogonal to the architecture — any source can be wired
into either architecture. See `drm_manager.py` in this directory for
file-level references and mechanics:

    A. Per-content upfront token                    (RTL+)
    B. Constructed from token claims + /user/account  (Magenta)
    C. Arrives with the playbackInfo response         (Discovery, simpliTV)
    D. Session id becomes a base64 auth blob          (HRTi)

New-provider guidance: pick the architecture first (state-sharing rule
above), then pick the source pattern that most closely matches how the
provider's licence URL is produced, and adapt the mechanics.

The existing providers currently sit in a mix of shapes — some have DRM
logic directly on the provider class, some in a playback manager, some
in a VOD manager that predates this template. "Source pattern" describes
what their code does, not what class it lives in. Migrating any provider
onto the dedicated or folded architecture is optional; when migrated,
each will map to whichever architecture the state-sharing rule selects.

### The three method names

Three names appear in the DRM path. They are not interchangeable:

    get_drm_configs   -- the dedicated DrmManager's only method
                         (matches DrmManagerProtocol)
    get_channel_drm   -- the folded architecture's live-channel entry point
    get_vod_drm       -- the folded architecture's VOD entry point

New providers using the dedicated-manager architecture implement
`get_drm_configs` and leave the other two alone. Providers using the
folded architecture override `get_channel_drm` and/or `get_vod_drm` and
leave `get_drm_configs` alone.

`StreamingProvider.get_drm(content_id, content_type=None)` is the public
method callers use; it dispatches to whichever architecture the provider
chose.

### content_type hint semantics

`content_type` is an optional hint. Pass it when you already know the
content type (e.g. the backend streaming route, which has already
resolved the item). It is a *narrowing* hint, not a required argument.

On the folded path, only two values narrow the search:

    "live"  -> channel manager only
    "vod"   -> VOD manager only

Any other value -- including None, "event", "catchup", or a typo --
tries both. This is deliberate: widening on unknown input is always
safe, but a wrong narrowing produces a silent `[]` for protected
content, which is the hardest kind of bug to trace.

On the dedicated-manager path, the hint is passed through to
`get_drm_configs`. The manager may honour it, ignore it, or infer the
type from `content_id` grammar when `content_type is None`. Managers are
encouraged to widen when in doubt, for the same reason as above.

## Catchup

Catchup is a distinct capability with its own manager. It is optional —
providers without catchup leave `_build_catchup()` returning `None` and
`implements_catchup` is `False`.

The catchup step is a *modified* live-manifest URL (with time
parameters) for some providers, a distinct URL from a different origin
for others, and an EPG-based resolution for others. The ABC names the
entry point; the shape is provider-specific.

**Do not fall back to the live manifest.** If `get_catchup_manifest`
cannot resolve catchup for the requested window, return `None`. Do not
return the live manifest URL — the DRM pipeline would extract PSSH from
the live stream, which may differ from the catchup stream's encryption
context. Callers that want the live manifest on failure should call
`provider.get_manifest()` themselves.

`end_time` is **Optional[int]** on the ABC. Providers whose catchup API
only takes a start bound (simpliTV) pass `None` and document that they
ignore the argument. Providers whose API uses both bounds require the
caller to pass it and raise `BadRequestError` on `None`. Do not pass a
sentinel value (`0`, `start_time + 1800`) when the ABC accepts `None`.

Catchup usually needs collaborators from other managers:

* **channels** — to resolve a live manifest URL (Magenta, simpliTV) or
  a stream uid (MoveTV).
* **epg** — to resolve an `epg_id` from a `start_time` (MoveTV).

Pass these as explicit keyword-only constructor arguments. See "Cross-
manager collaborators" above.

## Recordings

Recordings are a distinct capability with their own manager. Optional.

Recording identity is separate from content identity:

* `recording_id` is what you pass to `delete_recording`.
* `content_id` is what you pass to `get_manifest` to play the recording.

These are usually different namespaces. Keep them separate.

`get_recordings()` returns `Channel` objects (or a subclass carrying
`recording_id` and programme metadata). The base Channel shape is
preserved because downstream callers expect a `content_id` and a `name`.

`delete_recording` raises `KeyError` if the recording doesn't exist and
a `ProviderError` subclass on backend failure. It does **not** silently
return on failure — deleting a recording the user asked to delete and
having the deletion fail must surface.

**No manifest method.** The recordings manager deliberately has no
`get_manifest`. Recordings are played via a content_id that the
provider's router resolves — usually through the channel manager
(simpliTV) or the VOD manager, depending on how the provider's API
exposes the manifest. See "Routing for recordings manifests" above.

**Two managers may touch the `rec:` prefix.** The channel manager
accepts `rec:` for manifest and DRM fetch (the recording shares an
endpoint with its live channel). The recordings manager owns the list
and delete. This is not a conflict — they touch disjoint concerns.
Only one of them participates in the routing; the provider's
`get_manifest` is authoritative about which. See "Multiple managers
with the same prefix" above.

## Favorites and bookmarks

Both are optional, both are user-scoped, both follow the standard
manager contract.

Favorites: `FavoriteType` on each returned `Favorite` distinguishes
program / channel / clip / live / event. Providers that only support
one type validate the incoming type in `add_favorite` and reject the
others. Removing a non-existent favorite raises `KeyError`.

Bookmarks: `update_bookmark` is called on every playback stop / pause,
often consecutively for the same position. Providers should tolerate
repeated no-op writes to the same position without erroring or firing
spurious events. `position_seconds = -1` marks the content as
completed. Deleting a non-existent bookmark raises `KeyError`. Backend
failures raise a `ProviderError` subclass from `base.errors`, like every
other manager.

## Conventions

- **Custom Channel / AuthToken subclasses are fine.** Call
  `super().to_dict()` in your override. MoveTV, Discovery, HRTi, and
  simpliTV all do this.
- **Provider owns caches; managers borrow them.** Create caches in the
  provider's `__init__`; pass them into manager constructors by
  reference.
- **Content ID grammar is provider-specific.** Pick one and document it
  in the manager's docstring, or in a module-scope parser (see
  "Content-id grammar parsers" above).
- **Playback authorization is provider-specific.** Don't force it into a
  shared interface. See the existing providers for examples.
- **Extra capabilities that don't fit an ABC.** If the provider has a
  capability area that doesn't correspond to a base-layer mixin and
  doesn't warrant a new ABC, put the methods on the concrete manager
  that owns the domain, and pass them through on the provider. Document
  the capability in the manager's class docstring. Don't invent an
  ad-hoc manager class.

## Errors

Raise from `base.errors`:

    AuthError, CredentialsError, SessionExpiredError,
    GeoBlockError, EntitlementError, AccountRestrictedError,
    PlaybackRestrictedError,
    NotFoundError, BadRequestError,
    RateLimitError, ServerError, TransportError,
    CatchupRequiredError, NotImplementedYetError, ConfigurationError

Subclass when you need to carry payload:

    class MyProviderCatchupError(CatchupRequiredError): ...

Existing callers that catch the base class catch your subclass too.
`ProviderError.__reduce__` preserves subclass payload across pickle and
`copy.deepcopy`, so payload-carrying subclasses are safe to pass through
queues and process boundaries.

## VOD return type

Every VOD navigation method returns `VodPage` (base/vod.py):

    return VodPage(entries=[...], next_cursor="2", total=120)
    return VodPage(entries=[...])                     # no pagination
    return VodPage()                                  # empty

Pagination rule: use `page.has_more` — NOT `bool(page)` — to decide
whether to keep paging. `bool(page)` follows list semantics (empty page
is falsy, page with entries is truthy), which is correct for "are there
entries to display?" but wrong for pagination, because a page can have
zero entries and a non-None `next_cursor`.

`total` may be `None`. It is informational; do not use it as an
end-of-list signal. `next_cursor is None` (equivalently, `not
page.has_more`) is the authoritative signal.

## Lazy auth

The template does NOT authenticate in `__init__`. The first
`build_headers()` / `get_access_token()` call triggers authentication.
This avoids network I/O in constructors and lets you create a provider
object for inspection without hitting the network.

If your provider has a strong reason to authenticate eagerly (e.g. you
need to fail fast on bad credentials), do it in the provider's `__init__`
inside a try/except and log a warning — do not raise.

For providers with no auth, this section does not apply — there is
nothing to authenticate.

## Reference providers

The six existing providers, in order of implementation complexity:

    simpliTV    -- built from this template. Recordings + catchup + folded
                   DRM. Content-id grammar with three prefixes, module-scope
                   parsers, and a router that parses the catchup timestamp.
                   Token-in-body deviation, per-endpoint param naming,
                   custom AuthToken subclass, direct-CredentialManager
                   credential loading. Good first read.
    MoveTV      -- dynamic manifests, play-auth headers, EPG-based catchup.
    Magenta EU  -- EPG-heavy, VOD with typed errors, multi-country.
    HRTi        -- session-authorize playback, custom credentials shape.
    Discovery   -- dynamic endpoint discovery, Arkose challenge, playbackInfo.
    RTL+        -- layout-driven, three tokens, largest surface.

Read the closest one before writing a new provider. Each demonstrates a
different source pattern for DRM, a different content-id grammar, and a
different shape for playback authorization.