docs(exa): review revisions from #266 - #268
Conversation
- State the plan runs on live and needs a live-prefixed key (Info block) - Reword the environment-warning troubleshooting row: actionable when the option is passed; link payments#416 for the 1.10.0 self-firing case - Add a wrong-environment troubleshooting row (sandbox key vs live plan)
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
Pull request overview
Follow-up documentation adjustments to the Exa integration page to address review feedback from #266: clarifies that Exa’s Nevermined plan is on the live environment (and how key prefixes affect resolution), and corrects the guidance around the SDK’s deprecated environment option warning (including linking the confirmed SDK regression).
Changes:
- Updated the Exa plan info block to state the purchase runs on live and that a live API key is required.
- Rewrote the troubleshooting guidance for the deprecated
environmentwarning to be actionable and referenced the SDK regression ticket. - Added a troubleshooting row explaining why the Exa plan ID won’t resolve when using a
sandbox:-prefixed key.
Suppressed comments (1)
integrations/exa.mdx:75
- This troubleshooting row explains what’s wrong with a
sandbox:key, but it doesn’t explicitly state the correct prefix to use. Addinglive:here makes the fix unambiguous and consistent with the rest of the page.
| The plan ID above does not resolve, or token mint fails against it | Check your key prefix: this is a live plan, and a `sandbox:`-prefixed key targets a different environment where the plan does not exist. |
|
|
||
| <Info> | ||
| Exa's Nevermined plan ID:<br />`27800462147494506865542649899724877617306579171265399959488097895839186996870`<br />The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. | ||
| Exa's Nevermined plan ID:<br />`27800462147494506865542649899724877617306579171265399959488097895839186996870`<br />This plan and purchase run on **live**; use a live-prefixed Nevermined API key. The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. |
aaitor
left a comment
aaitor
left a comment
There was a problem hiding this comment.
Tight, well-scoped follow-up that lands both MEDIUM comments from #266 accurately: the live-environment note and the reworked environment-warning row are both correct, and payments#416 is characterized exactly as the issue reads (self-fires on 1.10.0 with only nvmApiKey, root cause = dist/payments.js passing environment: this.environmentName into its sub-API constructors). No HIGH/MEDIUM; three LOW polish notes below, none blocking. Approving.
Verification I ran
gh pr view/diff/checkson #268; read the full post-PRintegrations/exa.mdx(84 lines), not just the 3-line diff.- Base is
main(not a chain) — no parent branch to cross-check. - Cross-checked both claims against primary sources: payments#416 (OPEN; root cause matches the L74 row verbatim) and #266's merge thread (live-plan + byte-exact
Exhaustedconfirmations fromlistDelegations()). - Over-engineering / leanness pass: lean already — 3 added lines, information-dense, nothing to cut. Net removable: 0.
- CI: Mintlify preview 🟢, 2/2 checks green.
- Specialist agent panel (security / database / tdd / architect / code-explorer) is N/A to a prose-only docs diff — no handlers, DTOs, schema, runtime behavior, or exported symbols touched; reviewed inline.
The live-environment claim rests on the author's runtime validation (real $7 live purchases documented in #266); I did not independently re-run it.
|
|
||
| <Info> | ||
| Exa's Nevermined plan ID:<br />`27800462147494506865542649899724877617306579171265399959488097895839186996870`<br />The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. | ||
| Exa's Nevermined plan ID:<br />`27800462147494506865542649899724877617306579171265399959488097895839186996870`<br />This plan and purchase run on **live**; use a live-prefixed Nevermined API key. The purchase is for API credits, not for a single search request. \$7 covers roughly 1,000 standard searches; see [Exa pricing](https://exa.ai/pricing) for current rates. |
There was a problem hiding this comment.
LOW — Use the exact live: token for consistency. L75 refers to a `sandbox:`-prefixed key (the exact prefix token), but here it's the looser "live-prefixed". A reader matching prefixes across the page sees two different forms. Change live-prefixed to `live:`-prefixed so both places use the exact token.
| | Token mint fails: `Required token-generation input is missing or incomplete (HTTP 402)` | The mint referenced no existing delegation (e.g., legacy create-on-the-fly `delegationConfig` with card details). Create or discover a delegation first and pass `delegationConfig: { delegationId }`. | | ||
| | `ERR_PACKAGE_PATH_NOT_EXPORTED` on import | The SDK is ESM-only. Set `"type": "module"` in `package.json` or use `.mts`. | | ||
| | Console warning: `The 'environment' option is deprecated…` even though you never passed it | Known SDK issue; harmless. The environment is derived from your key prefix. | | ||
| | Console warning: `The 'environment' option is deprecated…` | Something is still passing the deprecated `environment` option (a wrapper or copied example). Remove it; the environment is derived from your key prefix. On SDK 1.10.0 the warning can also self-fire with nothing passed ([payments#416](https://github.com/nevermined-io/payments/issues/416)); if you have removed the option and still see it, that issue is why. | |
There was a problem hiding this comment.
LOW — Ordering vs. the pinned SDK version (non-blocking). The page pins SDK 1.10.0 (L25), and per payments#416 the warning self-fires on 1.10.0 regardless of what the caller passes — so for anyone following this doc verbatim, the self-fire is the default case, not the "something is still passing it" case this row leads with. The row does recover at the end ("if you have removed the option and still see it, that issue is why"), so it's correct as written; but a reader on the documented version will first go hunting for a wrapper/copied example that isn't there. Consider leading with the 1.10.0 behaviour, e.g.:
On SDK 1.10.0 this fires on instantiation even with nothing passed (payments#416) — expected, ignore it. On other versions it means something is still passing the deprecated
environmentoption (a wrapper or copied example); remove it, the environment is derived from your key prefix.
Purely a most-common-path reordering — flagging, not gating.
| | `ERR_PACKAGE_PATH_NOT_EXPORTED` on import | The SDK is ESM-only. Set `"type": "module"` in `package.json` or use `.mts`. | | ||
| | Console warning: `The 'environment' option is deprecated…` even though you never passed it | Known SDK issue; harmless. The environment is derived from your key prefix. | | ||
| | Console warning: `The 'environment' option is deprecated…` | Something is still passing the deprecated `environment` option (a wrapper or copied example). Remove it; the environment is derived from your key prefix. On SDK 1.10.0 the warning can also self-fire with nothing passed ([payments#416](https://github.com/nevermined-io/payments/issues/416)); if you have removed the option and still see it, that issue is why. | | ||
| | The plan ID above does not resolve, or token mint fails against it | Check your key prefix: this is a live plan, and a `sandbox:`-prefixed key targets a different environment where the plan does not exist. | |
There was a problem hiding this comment.
LOW — Row names the cause but not the fix. This entry explains why a sandbox: key fails but leaves the remedy implicit (it's only stated far up in the Info block at L10). A troubleshooting row reads best when it carries its own fix. Copilot flagged the same (suppressed comment). Suggestion:
| | The plan ID above does not resolve, or token mint fails against it | Check your key prefix: this is a live plan, and a `sandbox:`-prefixed key targets a different environment where the plan does not exist. | | |
| | The plan ID above does not resolve, or token mint fails against it | Check your key prefix: this is a live plan, so use a `live:`-prefixed key. A `sandbox:`-prefixed key targets a different environment where the plan does not exist. | |
Follow-up to #266, addressing aaitor's two MEDIUM review comments (merged as approved to unblock the deploy and the dependent website PR; revisions split out here per merge-order plan).
environmentis actually passed (remove the option). The 1.10.0 self-firing case is confirmed as an SDK regression, root cause pinned and filed as environment deprecation warning fires even when the caller never passes the option (1.10.0) payments#416, linked from the row.Also replied on #266: the literal
Exhaustedstatus value is confirmed byte-exact fromlistDelegations()output in both runtime validation runs.🤖 Generated with Claude Code