docs: rewrite the SDK page, fix realtime auth and inputs claims - #48
Merged
Conversation
The realtime section said API keys can't stream and that only cookie auth
works. The SDK appends the key as a ?token= query param and the API
authenticates it, so the warning sent API-key users to polling for no
reason. Verified against production.
The uploads example passed inputs as { source } and referenced {source}
in the command. There is no placeholder substitution: inputs keys are
filenames staged in the working directory, referenced by bare name, so
that example never worked.
Also: the output type block duplicated /concepts/job and the error code
list duplicated /support/errors, both now linked instead of restated.
Adds the wait errors and options shipped in 4.x (WaitTimeoutError,
JobFailedError, throwOnFailure), the client attribution option, and a
diagram of the create/poll-or-push/outcome path. Drops getTimings, which
exposes internal pipeline stages we don't want callers depending on.
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
1 participant
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.
Two claims on the live page were wrong, both verified against production with a live API key.
Realtime. The page warned that realtime needs session-cookie auth and that API-key users must poll. The SDK appends the key as
?token=andapps/api/src/routes/events-ws.tsauthenticates it. Live check: WS upgraded and streamed 18 events for a running job.Uploads. The example passed
inputs: { source: asset.url }and referenced{source}in the command. No placeholder substitution exists.inputskeys are filenames staged in the working directory and referenced by bare name, so the example could not work as written.Other changes:
/concepts/joband/support/errorsinstead of restated in two places.WaitTimeoutError,JobFailedError,throwOnFailure,jobs.stats, and theclientattribution option, all shipped in 4.x and previously undocumented.jobs.getTimingsfrom the page. It works, but it exposes internal pipeline stages (queue wait, consumer, DB insert) that callers shouldn't build against.Test plan
Two probe scripts run against production with a real key, non-destructive (self-expiring assets, own jobs, a webhook endpoint created and deleted in the same run):
probe-sdk-live.mjs: 21/21. Upload to job to signed output URL fetched at 200, logs, download, cancel, realtime WS over an API key, webhook signature accept plus tampered and stale rejects.probe-sdk-rest.mjs: 18/18. Webhook endpoint lifecycle, idempotency key dedupe, persisted upload and delete, ffprobejobData, HLS output whereoutputUrlreturns the .m3u8 across 3 files, timeout, orgId, baseUrl.mint broken-linksclean for this page. Frontmatter and plan-limit validators pass.