Sync SDK with API spec: float duration, live recording flag, playback access restrictions (v1.2.0)

[rohit-fastpix]

FastPix Python SDK - Documentation PR

This PR is a full SDK sync with the updated OpenAPI spec (code + docs + tests), released as v1.2.0. Documentation sections below cover the doc half; code changes are summarized at the end.

Documentation Changes

What Changed

• New documentation added
• Existing documentation updated
• Documentation errors fixed
• Code examples updated
• Links and references updated
• Other: test-harness README rewritten, tests/.env.example added

Files Modified

• README.md
• docs/ files
• USAGE.md
• CONTRIBUTING.md
• Other: CHANGELOG.md, tests/README.md, tests/.env.example, examples/live_streaming.py

Summary

Brief description of changes:

Docs synced with the API spec changes shipped in v1.2.0:

- Media `duration` documented as float seconds (was "HH:MM:SS" string) across
  media.md, mediaclipresponsedata.md, playlistbyidresponsemedialistitem.md and
  the five legacy media-response pages still linked from the docs tree.
- `enable_recording` documented on InputMediaSettings and added to the
  create-stream example in docs/sdks/startlivestream.
- `access_restrictions` documented on PlaybackIDRequest, PlaybackSettings and
  PlaybackIDSuccessResponseData, with a worked example in docs/sdks/liveplayback.
- Ten new model pages for the live domain / user-agent restriction endpoints,
  two new operation sections in docs/sdks/liveplayback, and README index entries.
- CHANGELOG entry for 1.2.0 (breaking / added / fixed).
- tests/README.md rewritten to describe the four offline pytest suites and the
  live validation harness; the stale embedded January report and the removed
  Node-based workflow instructions are gone. tests/.env.example added.

Code Examples (if Applicable)

from fastpix_python import Fastpix, models

fastpix = Fastpix(
    security=models.Security(username="your-username", password="your-password")
)

# Every method returns the {success, data} envelope; read fields through .data.

# Create a live stream; recording to VOD is on by default, opt out with enable_recording=False
stream = fastpix.start_live_stream.create_new_stream(
    playback_settings={"access_policy": "public"},
    input_media_settings={"max_resolution": "1080p", "enable_recording": True},
)
stream_id = stream.data.stream_id

# Create a playback ID with domain/user-agent restrictions
playback = fastpix.live_playback.create_playback_id_of_stream(
    stream_id=stream_id,
    access_policy="public",
    access_restrictions={
        "domains": {"default_policy": "deny", "allow": ["example.com"], "deny": []},
        "user_agents": {"default_policy": "allow", "allow": [], "deny": []},
    },
)

# Update restrictions on an existing live playback ID (new endpoints)
fastpix.live_playback.update_live_stream_domain_restrictions(
    stream_id=stream_id,
    playback_id=playback.data.id,
    default_policy="deny",
    allow=["example.com"],
)

# Media duration is now a float (seconds)
media = fastpix.manage_videos.get_media(media_id="your-media-id")
print(media.data.duration)  # e.g. 145.821315

Testing

• All code examples tested — tests/test_examples.py passes; examples/live_streaming.py exercised against the dev workspace
• Links verified — tests/check_broken_links.py run; only pre-existing external 404s remain (API base URLs that reject GET, one old changelog link)
• Grammar checked
• Formatting consistent

Review Checklist

• Content is accurate — every documented field/endpoint validated live against dev (39/40 non-GET, all changed GETs pass; the one failure is an upstream API bug, see below)
• Code examples work
• Links are working
• Grammar is correct
• Formatting is consistent

Code Changes (summary)

Breaking

• Media duration is Optional[float] seconds instead of str, on Media, MediaClipResponseData, PlaylistCreatedSchemaMediaList, PlaylistByIDResponseMediaList — affects get_media, list_media, list_live_clips, get_media_clips, updated_media, updated_source_access, updated_mp4_support, and playlist mediaList items. Strict float, no legacy-string parsing.

Added

• enable_recording (default True) on InputMediaSettings.
• access_restrictions on PlaybackIDRequest, PlaybackIDSuccessResponseData, PlaybackSettings, reusing the existing PlaybackIDAccessRestrictions model; new access_restrictions kwarg on create_playback_id_of_stream.
• update_live_stream_domain_restrictions / update_live_stream_user_agent_restrictions (+ _async) on LivePlayback, with new operation models.
• Async variants for the on-demand update_domain_restrictions / update_user_agent_restrictions.

Fixed

• Async methods called _raise_for_status_async without await, so failed responses returned None instead of raising — fixed across all resource modules.
• Return annotations on 104 resource methods declared the inner data type or a list where the SDK returns the {success, data} envelope; all now name the returned class.

Tests

• tests/test_models.py — model contract tests (duration, enableRecording, accessRestrictions, new op models, method presence).
• tests/test_async_errors.py — mocked-transport checks that async and sync methods raise typed errors on 4XX/5XX.
• tests/test_return_annotations.py — AST scan asserting every method's declared return type equals the class it unmarshals (144 cases).
• Live validators honor FASTPIX_BASE_URL; fixtures updated (flat restriction bodies, enableRecording, accessRestrictions); superseded TS validator and one-time scripts removed.

Ready for review!