Repository navigation
docs: mirror the auth-token retry and provider wording from fern-docs - #96
Conversation
0.2.6 drops a token Uploadcare refuses and retries the request once, and
accepts a `{ getToken, invalidate }` provider, which the plugin now passes
through. Neither was in the guides.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REj6M5RMiJpFdPqGgdkBvV
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The new guidance promises automatic invalidation and retries that generation, edit and job-status requests do not perform.
Review effort: Balanced
Findings: 2
Open (2)
What changed in this PR
This docs-only PR updates authentication guidance to mirror the changes described in fern-docs.
Changes:
- Documents provider objects and shared token caching.
- Adds guidance about token invalidation and retry behavior.
| File | Description |
|---|---|
| packages/ai-image-editor/docs/guide/plugin.md | Clarifies the uploader’s shared token provider and cache. |
| packages/ai-image-editor/docs/guide/integrating.md | Adds provider, invalidation and retry guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| whatever `cacheAuthToken` says, and calls your `invalidate()` on a refused | ||
| token. That is the shape the File Uploader plugin passes through, which is why | ||
| the editor inside the uploader shares the uploader's cache. See `authToken`, |
There was a problem hiding this comment.
Both findings are correct, and I verified them against the code rather than taking them on trust.
startJob() and getJobStatus() are the only two requests the editor makes, and both go out through the raw doFetch in UploadcareApiClient. resolveAuthToken() resolves the token and nothing more, so retryIfFailed is never in that path and nothing calls invalidate() on a refusal. The retry is real, but only for uploads, where upload-client's request helper runs. This PR extended it to the editor, which was wrong.
Fixed in 1a66e35: the guide now says the editor raises the error and stops, and names invalidateAuthToken() as what replaces a spent token. I also corrected the comment on AuthTokenController.provider, which claimed the retry was the reason for the object form; the real reason is that it lets a host drop a token rather than only read one.
The matching claims in fern-docs were wrong the same way and are fixed in uploadcare/fern-docs#425 (00da145).
🤖 Written by Claude Code on behalf of @nd0ut
| refuses the token, or `auth_token_failed` when your function throws. An expired | ||
| or spent token reaches you only after the editor has already fetched a new one | ||
| and retried the request once, which it can do whenever `authToken` is a | ||
| function rather than a plain token. See |
There was a problem hiding this comment.
Correct, and this was the more serious of the two. I traced it before changing anything: startJob() and getJobStatus() are the only requests the editor makes, both go out through the raw doFetch in UploadcareApiClient, and resolveAuthToken() resolves the token without wrapping the call. retryIfFailed never runs on that path, for a string, a function or a provider alike, exactly as you describe.
The guarantee is gone. integrating.md now states the opposite outright: the editor raises the error and stops, a spent or expired token keeps being sent until something replaces it, and editor.invalidateAuthToken() is what replaces it. The uc:error paragraph says each code arrives on the first refusal.
Two things worth recording beyond the wording:
- The same false claim had spread to fern-docs, which had it on three pages plus a blanket statement on the signed-uploads hub. Fixed in uploadcare/fern-docs#425 (00da145), with every retry claim now scoped to uploads and two rows added for the editor case.
- The retry genuinely does work for uploads through File Uploader and Upload Client, where upload-client's request helper runs. It is the editor that was mis-documented, not the feature.
Worth noting the existing e2e tests were never wrong: they only assert that a provider is accepted and that invalidateAuthToken() forwards to it. Nothing asserted a retry, which is consistent with there not being one.
🤖 Written by Claude Code on behalf of @nd0ut
Copilot was right on #96. `startJob` and `getJobStatus` go out through a plain fetch in UploadcareApiClient, and `resolveAuthToken` only resolves: nothing retries, nothing calls `invalidate()`. The guide promised recovery that does not happen, and the comment on AuthTokenController.provider claimed the retry was the reason for the object form. The guide now says the editor raises the error and stops, and names `invalidateAuthToken()` as what replaces a spent token. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01REj6M5RMiJpFdPqGgdkBvV
`{ getToken, invalidate }` read as something you have to build yourself, when
the cache the docs already recommend satisfies it as is.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REj6M5RMiJpFdPqGgdkBvV
Follow-up to #92, which shipped in 0.2.6. Two behaviors landed in the code and never reached the guides:
integrating.mdlisted those codes as if they always surfaced immediately.authTokennow also takes a{ getToken, invalidate }object, which is the shape the File Uploader plugin passes through.plugin.mdstill called it "the uploader's own cached resolver".Found by a cross-page consistency pass over the matching fern-docs pages; the same corrections are in fern-docs#425, which
AGENTS.mdasks to keep in sync with these guides.Docs only, no code.
🤖 Generated with Claude Code
https://claude.ai/code/session_01REj6M5RMiJpFdPqGgdkBvV