Repository navigation
feat!: 0.4.0: clear error messages, real timeouts, search filter and text, compile() chaining, install and poll resilience - #71
Merged
Conversation
…install and polling
Errors
- Error messages now come from the server (e.g. "Error 402: You have reached
the budget for this model tier..."), not the HTTP status text.
- All errors extend VideodbError and carry status, code (server error_code)
and data. VdbBaseError is kept as a deprecated alias.
Search
- search() keeps the server's warnings on .warnings and prints each once,
matching the Python SDK.
- search({ filter }) now sends the filter.
- Shots from new-style search fill text from metadata.
- SearchResponse gains getShotResults(), compile(), play() and
getEmbedCode(), so search(...).compile() works again.
Uploads
- uploadURL()/uploadFile() return Video, Audio or Image when mediaType is
given, and drop undefined when there is no callbackUrl.
- A missing local file fails with "File not found: <path>".
Install and polling
- The capture binary download never fails npm install, and
VIDEODB_SKIP_CAPTURE_INSTALL=1 skips it. Fixed a hang on failed downloads.
- Polling retries network errors, 429 and 5xx. A timeout throws
RequestTimeoutError with the output URL.
Docs and tests
- README rewritten for the current API.
- Added test/dx.spec.ts and compile-time upload type tests
(npm run typecheck:tests).
…lbackUrl upload type - e.cause on HTTP errors keeps its 0.3.2 shape, so e.cause.cause still holds the server message. - new AuthenticationError(cause) still works; cause defaults to the message. - uploadURL()/uploadFile() with a callbackUrl return the media type | undefined, as in 0.3.2, so existing if (result) guards still compile. - CHANGELOG lists the remaining behaviour changes under Upgrade notes.
Restore 0.3.2 runtime behaviour exactly and keep only additions: - Error classes, hierarchy, name, message and cause are as in 0.3.2. API errors additionally carry status, code and data (data.message is the server's explanation). VdbBaseError is exported as the catch-all. - A poll timeout is wrapped exactly as before and also carries data.outputUrl. - search() no longer prints warnings (still on .warnings), no longer sends filter, and shot.text is no longer back-filled, matching 0.3.2. - uploadFile() error messages and flow are back to 0.3.2. Kept: poll retries on transient failures, non-fatal capture install, VIDEODB_SKIP_CAPTURE_INSTALL, SearchResponse compile/play/getEmbedCode, search warnings on .warnings, and narrower upload return types.
- SearchResponse.compile()/play()/getEmbedCode() are async, so a non-shots response rejects instead of throwing synchronously. - success:false errors carry status from a numeric error_code, matching HTTP errors. - Comment the poll-retry policy (consecutive failures, no backoff) and the limits of UploadResult narrowing.
videodb-engg
changed the title
… shot text, upload errors
- Error messages include the server's explanation (Error 400: Video not
found, Authentication Error: Invalid API key, the connect() hint).
Network and unexpected errors include their reason. Classes and cause
are unchanged.
- A poll timeout throws RequestTimeoutError with the output URL instead of
VideodbError('Unidentified Error').
- search({ filter }) sends the filter on Video and Collection.
- Search V2 shots fill text from metadata.embeddedText.
- uploadFile() names a missing file (File not found: <path>) and other
upload failures include their reason.
CHANGELOG lists these under Changed with upgrade notes; release as minor.
videodb-engg
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
We audited the published
videodb@0.3.2against prod (api.videodb.io) and the docs. Several SDK behaviours make first-time users give up:search()returns nothing with no reason, and ignoresfilter.search().compile()throws after the v0.3 change.npm installfails on the capture binary download.Release this as a minor version: 0.4.0. Some of the fixes change what existing code sees. Each one is listed under "Upgrade notes" in
CHANGELOG.md.Changed (behaviour differs from 0.3.2)
Error 400: Bad RequestError 400: Video not foundAuthentication Error:Authentication Error: Invalid API keyAuthentication Error:(hint only incause)Authentication Error: No API key provided. Set an API key…Error 402: Payment RequiredError 402: You have reached the … budget for this model tier…VideodbError: Unidentified Error(timeout incause.cause)RequestTimeoutError: Polling timed out after Ns. The job may still finish; its result will be at <url>search({ filter })shot.textnullmetadata.embedded_textuploadFile()missing pathUpload failed, reason:File not found: <path>Error classes,
instanceofresults,nameandcauseare unchanged.Added
status: the HTTP status, or a numericerror_codefrom asuccess: falsebody.code: the server'serror_code, e.g.llm_dollar_budget_reached.data: the response body.VdbBaseErrorexported: every SDK error extends it, so it works as a catch-all.SearchResponse,SearchResultandAskResponseexpose the server'swarnings, e.g. whysearch()on a video with no new-style index came back empty. Nothing is printed.SearchResponsechaining: it gains asynccompile(),play(),getEmbedCode()andgetShotResults(), as in Python.uploadURL()anduploadFile()returnVideo,AudioorImagewhenmediaTypeis passed, and drop| undefinedwithout acallbackUrl.VIDEODB_SKIP_CAPTURE_INSTALL=1.Fixed
README
Rewritten for the current API: connect, upload, understand → index → semanticSearch, ask, legacy search, EditorTimeline, subtitles and error handling. The old README taught the v0.1 API. The snippets were run against prod.
Testing
npx jest: 39 tests pass. They cover the new messages, the timeout class, filter forwarding, shot text, upload errors, error details andSearchResponsechaining.npm run typecheck:tests: compile-time checks for upload return types.tsc --noEmitand the build are clean. Lint and formatting warnings are unchanged frommain.search()with and withoutfilter.shot.texton new-style search hits.SearchResponse.compile()returning a stream URL.Testworkflow (.github/workflows/test.yml): typecheck, type tests, jest and build on every PR and push tomain.