feat: timeline.export() for NLE project bundles

[videodb-kal]

timeline.export() — NLE project bundles

Adds a public surface for exporting a timeline as an editable NLE project — FCP7
XML, OTIO, EDL, captions and the media the sequence references — rather than a
rendered video. Additive only.

---

Why

generate_stream() answers "render this timeline". This answers "give me the
project": something an editor opens in Premiere and keeps working on, from the
same timeline.

The work takes minutes, so it cannot be synchronous. export() submits and
returns a job.

job = timeline.export(format="nle", name="My cut")

job.wait()
if job.done:
    url = job.download_url()
    print(job.fidelity)

What's here

Timeline.export()

Mirrors generate_stream rather than inventing a shape: serialize to_json(),
POST it inline under editor, and fall back to uploading the JSON when it exceeds
MAX_PAYLOAD_SIZE.

That inheritance is the point. A long timeline posted inline can exceed the
request body limit and fail with nothing useful in the response. generate_stream
already solved it; export gets the solution rather than rediscovering it the first
time someone exports a feature-length timeline.

ExportJob — videodb/export.py

refresh(), wait(), download_url(), plus status, progress, done,
failed and fidelity. Its own module rather than editor.py, which is already
~1,200 lines.

An ExportJob carries timeline_id and builds its own path from it — an export is
read back under the timeline that produced it. A job built from a response without
one raises a sentence saying so, rather than composing a malformed path and
reporting whatever error comes back.

Package export and docs

ExportJob is exported from the package root and listed in __all__, alongside
GenerationJob, Sandbox, VoiceClone and CaptureSession. README gains an
example next to the existing Timeline one.

---

Design decisions, each with a test

download_url() is a method, not a property. What it returns is a signed URL
with a short life. A property invites caching, and a cached signed URL works in
testing and fails a day later. Minted per call, never held on the job.

done and failed are both False for an unrecognised status. The status
vocabulary can grow, and reporting an unknown status as done sends a caller after
an artifact that does not exist. Waiting on a status the client cannot interpret is
the recoverable mistake.

wait() raises TimeoutError rather than returning a still-running job. A
caller handed an unfinished job by a method named wait will treat it as finished.

Optional fields are omitted, not sent as null. Absent means "fall back to the
timeline id"; null means "there is no name". Different answers.

A submit response with no job_id raises. A job that cannot be refreshed,
waited on or downloaded is not a job — failing at the call site names the problem
instead of deferring it to whichever attribute is touched first.

fidelity is surfaced deliberately. Not everything in a timeline has an
equivalent in a project file. An export that succeeds while dropping colour grades
is not a plain success, and a client that cannot see that will report it as one.

---

Flow

sequenceDiagram
    participant C as Your code
    participant S as SDK
    participant A as VideoDB API

    C->>S: timeline.export(format="nle")
    alt payload > MAX_PAYLOAD_SIZE
        S->>A: upload timeline JSON
        S->>A: POST editor/export {timeline_url}
    else
        S->>A: POST editor/export {timeline}
    end
    A-->>S: 202 {job_id, timeline_id}
    S-->>C: ExportJob

    loop job.wait()
        C->>S: refresh()
        S->>A: GET editor/export/{timeline}/{job}
        A-->>S: status, progress
    end

    C->>S: download_url()
    S->>A: GET editor/export/{timeline}/{job}/download
    A-->>S: {download_url} — signed, short-lived
    S-->>C: url

Loading

---

Compatibility

Additive. One new module, one new method, one new package export. No existing
signature or behaviour changes. No new dependencies. Nothing to migrate.

---

Requires

Server-side support for POST editor/export, GET editor/export/{timeline_id}/{job_id} and its /download. Until those are
available, export() raises InvalidRequestError. Nothing else in the SDK is
affected.

---

Verification

20 tests, all against a stub connection — no network, no credentials.

Also exercised against a running server end to end: submit, refresh(), wait()
polling a real export through to done, and download_url() resolving to a
downloadable bundle. That run is what surfaced the timeline-scoped read — no stub
could have.

Known follow-up

download_url() is annotated -> str but can return None when the response
carries no URL.