20139 - Add filterset search, and the clip poster URL

[ghultink]

Mirrors bb-sapi-php-sdk#20. Same design, same wire format — review that one first if you're reviewing both.

Why

The SDK can list, page and sort media clips, but it cannot filter them. MediaClip.list() takes only limit, offset and sort, and the query layer is Record<string, string> fed to searchParams.set(), which cannot express indexed parameters at all.

So every integration hand-rolls a filter query — and a wrong one fails silently: SAPI ignores it and still answers HTTP 200 with a body carrying neither numfound nor items, indistinguishable from an empty library. The TYPO3 extension's library grid showed no videos for exactly this reason.

What

const filterSet = FilterSet.create()
  .where('status', 'is', 'published')
  .where('title', 'contains', 'koert');

await sdk.mediaclip.search(filterSet);

Groups are AND-ed, filters within a group OR-ed — the structure OVP6 builds (app/services/filter-set.types.ts), mirrored here so a filterset moves between the UI, the API and any SDK unchanged.

The filterset is sent, not compiled

The part worth reviewing. SAPI compiles filtersets itself, via the same SearchRequestHelper that serves the OVP — and that is what OVP6 sends (filter-set.service.ts:609). Compiling in the SDK would be a second implementation of semantics the server owns, free to drift, with a failure mode nobody sees. Multiply by four SDKs and you get four subtly different compilers.

Verified equivalent against a live publication of 5777 clips:

filter	numfound
status is published	4361
title contains "koert"	1 — finds Koert Live
hasInteractivity is true	868
published AND video	3679

The fq escape hatch, and its trap

search() still accepts raw filter queries for the rare thing a filterset cannot express. Its encoding is pinned by a test:

• fq[0]=… — accepted
• fq=… repeated, or a nested fq[][0]=… — ignored, silently, with HTTP 200 and an empty envelope

Also: the clip poster URL

Thumbnail.getMediaClipPosterPath(). A clip's src is its source media file, so building a poster from it yields a link to a .mov — the service replies Invalid src mime type: video/quicktime. The route is /mediaclip/{id}/spthumbnail/{w}/{h}.webp, and a draft clip needs a read-only RPC token (never the write key — this URL ends up in page source).

Checks

• 154 tests pass (14 new), tsc --noEmit clean
• No new dependencies

Note on browser use

The SDK is otherwise browser-ready — pure ESM, fetch transport, no Node built-ins — except src/util/hotp.ts, which uses node:crypto and Buffer. That is also the one part that must never run in a browser, since HOTP minting needs the API secret. A browser entry point that omits the RPC authenticator would be a small change if it's ever wanted; not in this PR.

🤖 Generated with Claude Code

---

Self-review findings — addressed in the latest commit

A thorough adversarial review of this PR (all three SDK PRs plus the TYPO3 consumer) found three behaviour bugs that the original tests pinned as if correct — green CI over broken code:

1. isEmpty / isNotEmpty were silent no-ops. The backend compiler skips any filter whose value is empty — presence tests included. Verified live: a bare isEmpty returned the full unfiltered publication (5777/5777). OVP6 sends the placeholder * with the comment "backend needs a value to work"; the wire format now does the same (live: author isEmpty 5496, isNotEmpty 278).
2. Numeric values in ingested filtersets now normalise to decimal strings. SAPI accepts numbers (views > 100 as number and string both return 99), but dropping or mishandling them varied per SDK.
3. Booleans now normalise to 'true'/'false'. The backend mangles a JSON true into "1", which matches nothing — verified live: 0 results as a boolean vs 868 as the string.

Plus per-SDK hardening (tolerant ingestion of malformed groups, descriptive errors for unknown operators, documented server-side quirks). Details in the fix commit message.