Release 0.3.1

[omgate234]

Pull Request

Description:
Fixes four regressions in the Search v2 surface, all found while exercising search() → Shot → getEmbedCode() end to end. Three come from the server sending shapes the SDK's types did not allow (length: null, absent title, explicit null stream keys); the fourth is an ask() signature that could not accept the options object its own docs implied. Behaviour is aligned with videodb-python in each case.

No version bump: 0.3.1 is still unpublished (npm latest is 0.3.0), so these entries fold into the existing [0.3.1] CHANGELOG section rather than opening a [0.3.2].

Changes:

• ask() accepts an options object — Video.ask() / Collection.ask() now take AskOptions (topK, mode, includeSources) as the second argument. Previously that parameter was topK: number, so an options object was serialised straight into top_k and mode / includeSources were dropped without error. The positional form still works; AskOptions is exported from @/types/search
• getEmbedCode({ autoGenerate: true }) works on search shots — generateStream() returned early when streamUrl alone was set, so shots from search never fetched playerUrl and getEmbedCode() threw despite auto-generation. It now skips the request only when both URLs are known, and sends length: null for shots with no video length instead of letting JSON.stringify coerce NaN
• videoLength is no longer NaN — parseFloat(result.length) produced NaN when Search v2 sent length: null; values now pass through a finite-number coercion returning undefined for null/empty/non-numeric input
• streamUrl is no longer dropped from serialised shots — doc.streamLink ?? doc.streamUrl fell through a real null onto a key the server never emits, leaving undefined so JSON.stringify() omitted the field. Now uses || and normalises absent streams to null
• Types widened to match the wire — videoLength / videoTitle optional and streamUrl / playerUrl nullable on Shot and ShotBase; SearchResponse allows length: string | number | null and title: string | null
• CHANGELOG entries added under the unreleased [0.3.1]

Related Issues:

• None filed on this repo; raised through internal triage.

Testing:

• npx tsc --noEmit — passes (exit 0). This carries real signal here, since the ShotBase / SearchResponse widenings are the fix for three of the four bugs
• npx jest — passes, but only exercises the pre-existing test/index.spec.ts placeholder; it covers none of this
• Manual verification still required against a live collection, because every one of these depends on server response shapes that cannot be reproduced offline:
  1. video.ask('...', { topK: 5, includeSources: true }) → confirm the request body carries top_k: 5 and include_sources: true, and that the positional form ask('...', 5, 'default', true) still produces the same body
  2. collection.search(...) on an indexed video → take a returned Shot, call getEmbedCode({ autoGenerate: true }), confirm it returns an iframe rather than throwing player_url not available
  3. On the same shot, confirm videoLength is undefined (never NaN) and that JSON.stringify(shot) still contains a streamUrl key — null when there is no stream
• Re-test scope: any caller of Video.ask / Collection.ask, and anything consuming Shot.videoLength / videoTitle / streamUrl / playerUrl, since those four are now optional or nullable

Checklist:

• Code follows project coding standards
• Tests have been added or updated — no; see note below
• Code Review
• Manual test after merge
• All checks passed

On tests: this branch adds none. The repo has no HTTP-mocking harness, and the four bugs are all about real server response shapes, so a spec would mostly assert the fixtures it declares. Landing a proper mocked-transport suite is worth doing as its own change rather than smuggling a half-harness in here.

Compatibility: no breaking changes at the call site. ask() keeps its positional form. The Shot field widenings are type-level and will surface in downstream TypeScript that assumed videoLength: number or non-null streamUrl — which is the point, since the server was already sending those values.