Feat/browser extension docs #78
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
|
WalkthroughThis pull request adds comprehensive documentation for the Reclaim Browser Extension SDK, introducing guides for both Extension Integration and Web Integration paths. New pages cover installation, manifest configuration, setup, usage, troubleshooting, and security best practices with code examples and architecture diagrams. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (8)
content/docs/browser-extension/extension-integration/manifest-configuration.mdx (1)
186-186: Minor grammar suggestion at line 186.Consider adding "the" before "offscreen" for better flow: "Manages the offscreen document lifecycle" (or review context for correct phrasing).
content/docs/browser-extension/extension-integration/usage.mdx (1)
587-587: Explain why proofs are URL-encoded in the callback.Line 587 includes a comment stating proofs are "urlencoded proof object that is returned to the callback url," but there's no explanation for developers about why this encoding happens or when to expect it. Add a brief note clarifying:
- Why proofs come URL-encoded (protocol/transport reason)
- When to use
decodeURIComponent()(always for callback, or conditionally?)- Whether this applies to other SDK usage patterns or only callbacks
This will help developers understand the pattern rather than blindly copy-pasting the decode logic.
Also applies to: 632-632
content/docs/browser-extension/troubleshooting.mdx (3)
223-223: Clarifyrun_at: "document_start"requirement.Line 223 states the requirement as "Must be document_start!" but doesn't explain the consequences of not using it. Add clarity on:
- Why this timing is critical (proofs generation, interception)?
- What breaks if
"document_end"or"document_idle"is used instead?- Whether there are any trade-offs (performance, etc.) to running at document start?
This helps developers understand the constraint rather than just follow a rule.
411-425: Clarify when CORS is needed for server-side config.Line 411–425 shows CORS configuration in the debugging section, but it's unclear whether CORS is:
- Always required when using server-side config?
- Only needed if backend and frontend are on different domains?
- Required for production but optional for development?
Add a note explaining the CORS requirement context (e.g., "CORS is required if your backend API is on a different domain than your website").
256-264: Clarifyworld: "ISOLATED"recommendation.Line 260 recommends using
"world": "ISOLATED"for content scripts as the "Recommended" option, but doesn't explain:
- What the default is if not specified?
- Why isolated world is recommended (security? compatibility?)?
- Are there scenarios where the default world is preferable?
Add context so developers understand when and why to use this setting.
content/docs/browser-extension/web-integration/usage.mdx (1)
596-719: Well-structured custom hook for verification logic.The
useReclaimVerificationhook cleanly extracts verification logic and state management, making it reusable across components. The hook includes:
- Proper cleanup and state reset
- Memoized callbacks to prevent unnecessary re-renders
- Comprehensive state tracking
Consider adding a TypeScript version or at least JSDoc type hints (e.g.,
@param {string} providerId) for better IDE support and discoverability.content/docs/browser-extension/web-integration/index.mdx (1)
1-12: Clarify "Optional" vs. "Alternative" integration path.Lines 1–7 label web integration as "Optional Integration," which might suggest it's a lesser or secondary path. However, web integration is a legitimate and valuable integration pattern for websites. Consider reframing the language to be clearer:
- "Web Integration (Optional)" → "Web Integration: Website Integration Path" or "Web Integration: For Websites"
- The callout could say: "This section is for websites that want to integrate with a compatible extension" rather than framing it as optional.
This avoids potentially discouraging developers who legitimately need web integration (non-extension developers).
content/docs/browser-extension/web-integration/setup.mdx (1)
226-317: Backend API examples are comprehensive but lack error details.Both Express.js (lines 226–317) and Next.js (lines 328–406) backend examples provide solid foundations, but they lack:
Input validation: Beyond checking if
providerIdis present, the examples don't validate that it's a valid provider from the Reclaim platform. Should add validation or a comment noting this should be done.Error codes: Callback handlers return generic 500 errors without distinguishing between different failure modes (config generation failure vs. proof validation failure vs. database storage failure).
Rate limiting: The examples don't show rate limiting or abuse prevention, which should be implemented before production.
Add a comment in each example suggesting these production-ready enhancements, or consider creating a "Production Hardening" section before these examples.
Also applies to: 328-406
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (14)
content/docs/browser-extension/extension-integration/index.mdx(1 hunks)content/docs/browser-extension/extension-integration/manifest-configuration.mdx(1 hunks)content/docs/browser-extension/extension-integration/meta.json(1 hunks)content/docs/browser-extension/extension-integration/setup.mdx(1 hunks)content/docs/browser-extension/extension-integration/usage.mdx(1 hunks)content/docs/browser-extension/index.mdx(1 hunks)content/docs/browser-extension/installation.mdx(1 hunks)content/docs/browser-extension/meta.json(1 hunks)content/docs/browser-extension/troubleshooting.mdx(1 hunks)content/docs/browser-extension/web-integration/index.mdx(1 hunks)content/docs/browser-extension/web-integration/meta.json(1 hunks)content/docs/browser-extension/web-integration/setup.mdx(1 hunks)content/docs/browser-extension/web-integration/usage.mdx(1 hunks)content/docs/meta.json(1 hunks)
🧰 Additional context used
🪛 LanguageTool
content/docs/browser-extension/extension-integration/manifest-configuration.mdx
[grammar] ~186-~186: Ensure spelling is correct
Context: ...alization occurs in this file - Manages offscreen document lifecycle - Handles message ro...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (12)
content/docs/browser-extension/extension-integration/manifest-configuration.mdx (5)
14-61: Verify manifest JSON examples are complete and valid.The complete manifest configuration is well-structured and detailed. Ensure that:
- All JSON paths match the actual SDK asset structure after running the installation setup script
- The
"run_at": "document_start"setting is correct for all use cases mentioned in the guide
65-95: Excellent CSP explanation.The Content Security Policy section clearly explains why
'wasm-unsafe-eval'is required and provides good context for security trade-offs. The warning callout appropriately contextualizes this as an approved and necessary exception.
97-135: Permissions section is well-documented with comprehensive rationale.Each permission (offscreen, cookies, scripting) is explained with clear context about purpose, usage, and security implications. The scripting permission rationale particularly helps users understand why this broad permission is required.
136-173: Host permissions approach is well-balanced.The guide appropriately presents both the broad
<all_urls>approach and the alternative of listing specific provider domains, with clear trade-offs explained. The security implications and user trust callout is helpful.
292-321: Validation checklist and testing section provide excellent practical guidance.The checklist (lines 292-301) is comprehensive and covers all critical configuration points. The testing section (lines 305-321) provides clear step-by-step verification procedures that developers can follow immediately.
content/docs/browser-extension/extension-integration/usage.mdx (2)
541-562: Well-documented security best practice guidance.The production security section clearly articulates why server-side configuration is essential, and the distinction between
@reclaimprotocol/js-sdk(backend) and@reclaimprotocol/browser-extension-sdk(frontend) is helpful for developers. However, consider clarifying earlier in the document (perhaps in the "Overview" section) that the dev-only quick-start example is strictly for learning and prototyping.
770-877: Comprehensive testing and debugging guidance.The section covers manual testing, debugging tips, and common issues well. The state-tracking pattern for preventing concurrent verification attempts (lines 849–876) is especially valuable and could be promoted to the "Basic Popup Implementation" section as a best practice.
content/docs/browser-extension/extension-integration/index.mdx (1)
146-146: Resolve incomplete link references.Line 146 references server-side configuration with
[server-side configuration](#) (coming soon)— the empty fragment link should either:
- Point to the actual path
/web/backend/usage(or wherever the backend guide lives)- Or remove the placeholder link if the backend integration guide isn't ready
Similarly, line 164 includes a comment
(link to be added)for the sample extension. Ensure the URL is populated before merge, or document how developers can find the sample.Also applies to: 164-164
content/docs/browser-extension/web-integration/usage.mdx (1)
302-494: Excellent production-ready React component example.The component demonstrates best practices including:
- Proper state initialization and management
- Extension installation checking on mount
- Graceful fallback UI for missing extension
- Full event lifecycle handling
- Error boundary-like states
- Loading indicators
This is a strong reference implementation. Consider adding a note about accessibility (ARIA labels, keyboard navigation) or a link to WCAG guidelines if the project has accessibility requirements.
content/docs/browser-extension/web-integration/index.mdx (1)
62-71: Comparison table provides clear integration decision framework.The table comparing Extension Integration vs. Web Integration effectively communicates the key differences in control, complexity, and user experience. Developers can quickly determine which path matches their use case.
content/docs/browser-extension/web-integration/setup.mdx (2)
45-49: Well-demonstrated security-first environment variable pattern for Next.js.Lines 45–49 correctly show separating public and private environment variables for Next.js:
NEXT_PUBLIC_*for extension ID (safe for client)- Plain
RECLAIM_APP_SECRETstored server-side onlyThis pattern is a best practice and serves as a good model for developers. Clear comments (
# Server-side only,# NEVER put secret...) reinforce the security intent.
738-823: Extension installation checking examples are practical and complete.Lines 738–823 provide two solid patterns for detecting and prompting users to install the extension:
- Vanilla JS approach with manual error handling
- React component approach with state management
Both handle the null state (checking), installed state (proceed), and not-installed state (prompt) clearly. Consider highlighting this pattern in the troubleshooting guide as a best practice.
| ## SDK API Reference | ||
|
|
||
| ### Initialization Methods | ||
|
|
||
| #### `reclaimExtensionSDK.init()` | ||
|
|
||
| Initialize a new verification request with credentials. | ||
|
|
||
| ```javascript | ||
| const request = await reclaimExtensionSDK.init(appId, appSecret, providerId, { | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `appId` (string): Your application ID from Reclaim dashboard | ||
| - `appSecret` (string): Your application secret (keep secure!) | ||
| - `providerId` (string): ID of the provider to verify (e.g., `"google-login"`) | ||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: Promise that resolves to a `ReclaimRequest` object | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.fromConfig()` | ||
|
|
||
| Initialize from a pre-generated configuration (recommended for production). | ||
|
|
||
| ```javascript | ||
| const requestConfig = await fetchFromBackend(); // Get config from your server | ||
| const request = reclaimExtensionSDK.fromConfig(requestConfig, { | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `requestConfig` (object): Configuration object from backend | ||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: `ReclaimRequest` object | ||
|
|
||
| **Use Case**: When using server-side request generation for better security | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.isExtensionInstalled()` | ||
|
|
||
| Check if the Reclaim extension is installed in the user's browser. | ||
|
|
||
| ```javascript | ||
| const isInstalled = await reclaimExtensionSDK.isExtensionInstalled({ | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: Promise that resolves to `true` if installed, `false` otherwise | ||
|
|
||
| **Use Case**: Check extension status before starting verification to show appropriate UI | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.getVersion()` | ||
|
|
||
| Get the current version of the Reclaim Extension SDK. | ||
|
|
||
| ```javascript | ||
| const version = reclaimExtensionSDK.getVersion(); | ||
| console.log("SDK Version:", version); | ||
| ``` | ||
|
|
||
| **Parameters**: None | ||
|
|
||
| **Returns**: String containing the SDK version (e.g., `"1.0.0"`) | ||
|
|
||
| **Use Case**: | ||
|
|
||
| - Display SDK version in your application | ||
| - Log version information for debugging | ||
| - Check SDK version for compatibility | ||
|
|
||
| --- | ||
|
|
||
| ### Request Object Methods | ||
|
|
||
| After calling `reclaimExtensionSDK.init()`, you receive a `request` object with these methods: | ||
|
|
||
| #### `request.setAppCallbackUrl()` | ||
|
|
||
| Set a callback URL where proofs will be sent automatically. | ||
|
|
||
| ```javascript | ||
| request.setAppCallbackUrl("https://your.server/receive-proofs"); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `url` (string): Your backend endpoint to receive proofs | ||
|
|
||
| **Use Case**: Automatically send proofs to your server when verification completes | ||
|
|
||
| --- | ||
|
|
||
| #### `request.setParams()` | ||
|
|
||
| Add custom parameters to the verification request. | ||
|
|
||
| ```javascript | ||
| request.setParams({ | ||
| userId: "user123", | ||
| action: "login", | ||
| timestamp: Date.now(), | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `params` (object): Custom key-value pairs to include with the proof | ||
|
|
||
| **Use Case**: Pass additional context or metadata with the verification | ||
|
|
||
| --- | ||
|
|
||
| #### `request.addContext()` | ||
|
|
||
| Add context information to the verification. | ||
|
|
||
| ```javascript | ||
| request.addContext("0x0", "web app verification"); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `address` (string): Context address or identifier | ||
| - `message` (string): Context message or description | ||
|
|
||
| **Use Case**: Add on-chain context or additional verification metadata | ||
|
|
||
| --- | ||
|
|
||
| #### `request.startVerification()` | ||
|
|
||
| Start the verification process and return a promise that resolves with proofs. | ||
|
|
||
| ```javascript | ||
| const proofs = await request.startVerification(); | ||
| console.log("Verification complete:", proofs); | ||
| ``` | ||
|
|
||
| **Returns**: Promise that resolves with proof data when verification completes | ||
|
|
||
| **Use Case**: | ||
|
|
||
| - Get proofs via promise instead of event listeners | ||
| - Use with async/await for cleaner code flow | ||
| - Combine with event listeners for both immediate and async handling | ||
|
|
||
| **Note**: You can use both the promise return value AND event listeners together. The `completed` event will fire, and the promise will resolve with the same proof data. | ||
|
|
||
| --- | ||
|
|
||
| #### `request.on()` | ||
|
|
||
| Register event listeners for verification lifecycle events. | ||
|
|
||
| ```javascript | ||
| request.on("started", ({ sessionId }) => { | ||
| console.log("Verification started:", sessionId); | ||
| }); | ||
|
|
||
| request.on("completed", (proofs) => { | ||
| console.log("Proofs received:", proofs); | ||
| }); | ||
|
|
||
| request.on("error", (error) => { | ||
| console.error("Error:", error); | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `event` (string): Event name (`"started"`, `"completed"`, or `"error"`) | ||
| - `callback` (function): Function to call when event fires | ||
|
|
||
| **Available Events**: | ||
|
|
||
| - `started`: Fired when verification session begins (payload: `{ sessionId }`) | ||
| - `completed`: Fired when verification succeeds (payload: `proofs` object) | ||
| - `error`: Fired when verification fails or is cancelled (payload: `error` object/string) | ||
|
|
||
| --- | ||
|
|
||
| ### Complete Usage Example | ||
|
|
||
| ```javascript | ||
| // Initialize the request | ||
| const request = await reclaimExtensionSDK.init(APP_ID, APP_SECRET, "google-login", { extensionID: EXTENSION_ID }); | ||
|
|
||
| // Configure the request | ||
| request.setAppCallbackUrl("https://your.server/receive-proofs"); | ||
| request.setParams({ userId: "user123", action: "verify_email" }); | ||
| request.addContext("0x0", "email verification"); | ||
|
|
||
| // Set up event listeners | ||
| request.on("started", ({ sessionId }) => { | ||
| console.log("Session started:", sessionId); | ||
| }); | ||
|
|
||
| request.on("completed", (proofs) => { | ||
| console.log("Verification complete:", proofs); | ||
| // Send to backend, update UI, etc. | ||
| }); | ||
|
|
||
| request.on("error", (error) => { | ||
| console.error("Verification failed:", error); | ||
| }); | ||
|
|
||
| // Start verification (also returns a promise) | ||
| const proofs = await request.startVerification(); | ||
| console.log("Got proofs via promise:", proofs); | ||
| ``` | ||
|
|
||
| ## Checking Extension Installation | ||
|
|
||
| Before starting verification, check if the extension is installed: | ||
|
|
||
| ```javascript | ||
| import { reclaimExtensionSDK } from "@reclaimprotocol/browser-extension-sdk"; | ||
|
|
||
| const EXTENSION_ID = import.meta.env.VITE_RECLAIM_EXTENSION_ID; | ||
|
|
||
| async function checkExtensionInstalled() { | ||
| try { | ||
| const isInstalled = await reclaimExtensionSDK.isExtensionInstalled({ | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
|
|
||
| if (isInstalled) { | ||
| console.log("✅ Extension is installed"); | ||
| return true; | ||
| } else { | ||
| console.log("❌ Extension not installed"); | ||
| return false; | ||
| } | ||
| } catch (error) { | ||
| console.error("Error checking extension:", error); | ||
| return false; | ||
| } | ||
| } | ||
|
|
||
| // Use before verification | ||
| async function handleVerifyClick() { | ||
| const installed = await checkExtensionInstalled(); | ||
|
|
||
| if (!installed) { | ||
| showInstallExtensionPrompt(); | ||
| return; | ||
| } | ||
|
|
||
| // Proceed with verification | ||
| startVerification(); | ||
| } | ||
| ``` | ||
|
|
||
| ### React Component with Installation Check | ||
|
|
||
| ```javascript | ||
| import { useState, useEffect } from "react"; | ||
| import { reclaimExtensionSDK } from "@reclaimprotocol/browser-extension-sdk"; | ||
|
|
||
| function ReclaimVerificationWithCheck() { | ||
| const [extensionInstalled, setExtensionInstalled] = useState(null); | ||
| const EXTENSION_ID = import.meta.env.VITE_RECLAIM_EXTENSION_ID; | ||
|
|
||
| useEffect(() => { | ||
| checkExtension(); | ||
| }, []); | ||
|
|
||
| const checkExtension = async () => { | ||
| const installed = await reclaimExtensionSDK.isExtensionInstalled({ | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| setExtensionInstalled(installed); | ||
| }; | ||
|
|
||
| if (extensionInstalled === null) { | ||
| return <div>Checking extension...</div>; | ||
| } | ||
|
|
||
| if (!extensionInstalled) { | ||
| return ( | ||
| <div> | ||
| <p>Reclaim extension is required for verification.</p> | ||
| <a href="https://chrome.google.com/webstore" target="_blank" rel="noopener noreferrer"> | ||
| Install Extension | ||
| </a> | ||
| <button onClick={checkExtension}>Check Again</button> | ||
| </div> | ||
| ); | ||
| } | ||
|
|
||
| return ( | ||
| <div> | ||
| <button onClick={handleVerification}>Verify with Reclaim</button> | ||
| </div> | ||
| ); | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Critical: API reference is triplicatedacross three documentation files.
The API reference (lines 508–823) appears verbatim in:
extension-integration/usage.mdx(lines 245–440)web-integration/usage.mdx(lines 72–300)web-integration/setup.mdx(lines 508–823)
Maintenance risk: Any future SDK API changes must be synchronized across three separate locations, increasing the likelihood of documentation drift and inconsistency.
Recommended solution:
- Create a shared MDX partial (e.g.,
_api-reference.mdx) - Include it in all three files using a component like:
<ApiReference /> - Or create a single canonical reference page and link to it from all three files
This ensures a single source of truth for API documentation.
🤖 Prompt for AI Agents
In content/docs/browser-extension/web-integration/setup.mdx around lines 508–823
the SDK API reference is duplicated across three docs, causing maintenance risk;
extract the entire API reference content into a single shared MDX partial (e.g.,
content/docs/browser-extension/_api-reference.mdx) or a canonical doc page,
remove the duplicated block from this file and replace it with a single include
or component reference (e.g., <ApiReference /> or a link to the canonical page),
then update the other two files (extension-integration/usage.mdx and
web-integration/usage.mdx) to import or link to the same shared partial so all
three pages reference the single source of truth.
| ## SDK API Reference | ||
|
|
||
| ### Initialization Methods | ||
|
|
||
| #### `reclaimExtensionSDK.init()` | ||
|
|
||
| Initialize a new verification request with credentials. | ||
|
|
||
| ```javascript | ||
| const request = await reclaimExtensionSDK.init(appId, appSecret, providerId, { | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `appId` (string): Your application ID from Reclaim dashboard | ||
| - `appSecret` (string): Your application secret (keep secure!) | ||
| - `providerId` (string): ID of the provider to verify (e.g., `"google-login"`) | ||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: Promise that resolves to a `ReclaimRequest` object | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.fromConfig()` | ||
|
|
||
| Initialize from a pre-generated configuration (recommended for production). | ||
|
|
||
| ```javascript | ||
| const requestConfig = await fetchFromBackend(); // Get config from your server | ||
| const request = reclaimExtensionSDK.fromConfig(requestConfig, { | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `requestConfig` (object): Configuration object from backend | ||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: `ReclaimRequest` object | ||
|
|
||
| **Use Case**: When using server-side request generation for better security | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.isExtensionInstalled()` | ||
|
|
||
| Check if the Reclaim extension is installed in the user's browser. | ||
|
|
||
| ```javascript | ||
| const isInstalled = await reclaimExtensionSDK.isExtensionInstalled({ | ||
| extensionID: EXTENSION_ID, | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `options` (object): Configuration options | ||
| - `extensionID` (string): Required - Browser extension ID | ||
|
|
||
| **Returns**: Promise that resolves to `true` if installed, `false` otherwise | ||
|
|
||
| **Use Case**: Check extension status before starting verification to show appropriate UI | ||
|
|
||
| --- | ||
|
|
||
| #### `reclaimExtensionSDK.getVersion()` | ||
|
|
||
| Get the current version of the Reclaim Extension SDK. | ||
|
|
||
| ```javascript | ||
| const version = reclaimExtensionSDK.getVersion(); | ||
| console.log("SDK Version:", version); | ||
| ``` | ||
|
|
||
| **Parameters**: None | ||
|
|
||
| **Returns**: String containing the SDK version (e.g., `"1.0.0"`) | ||
|
|
||
| **Use Case**: | ||
|
|
||
| - Display SDK version in your application | ||
| - Log version information for debugging | ||
| - Check SDK version for compatibility | ||
|
|
||
| --- | ||
|
|
||
| ### Request Object Methods | ||
|
|
||
| After calling `reclaimExtensionSDK.init()` or `fromConfig()`, you receive a `request` object with these methods: | ||
|
|
||
| #### `request.setAppCallbackUrl()` | ||
|
|
||
| Set a callback URL where proofs will be sent automatically. | ||
|
|
||
| ```javascript | ||
| request.setAppCallbackUrl("https://your.server/receive-proofs"); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `url` (string): Your backend endpoint to receive proofs | ||
|
|
||
| **Use Case**: Automatically send proofs to your server when verification completes | ||
|
|
||
| --- | ||
|
|
||
| #### `request.setParams()` | ||
|
|
||
| Add custom parameters to the verification request. | ||
|
|
||
| ```javascript | ||
| request.setParams({ | ||
| userId: "user123", | ||
| action: "login", | ||
| timestamp: Date.now(), | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `params` (object): Custom key-value pairs to include with the proof | ||
|
|
||
| **Use Case**: Pass additional context or metadata with the verification | ||
|
|
||
| --- | ||
|
|
||
| #### `request.addContext()` | ||
|
|
||
| Add context information to the verification. | ||
|
|
||
| ```javascript | ||
| request.addContext("0x0", "web app verification"); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `address` (string): Context address or identifier | ||
| - `message` (string): Context message or description | ||
|
|
||
| **Use Case**: Add on-chain context or additional verification metadata | ||
|
|
||
| --- | ||
|
|
||
| #### `request.startVerification()` | ||
|
|
||
| Start the verification process and return a promise that resolves with proofs. | ||
|
|
||
| ```javascript | ||
| const proofs = await request.startVerification(); | ||
| console.log("Verification complete:", proofs); | ||
| ``` | ||
|
|
||
| **Returns**: Promise that resolves with proof data when verification completes | ||
|
|
||
| **Use Case**: | ||
|
|
||
| - Get proofs via promise instead of event listeners | ||
| - Use with async/await for cleaner code flow | ||
| - Combine with event listeners for both immediate and async handling | ||
|
|
||
| **Note**: You can use both the promise return value AND event listeners together. The `completed` event will fire, and the promise will resolve with the same proof data. | ||
|
|
||
| --- | ||
|
|
||
| #### `request.on()` | ||
|
|
||
| Register event listeners for verification lifecycle events. | ||
|
|
||
| ```javascript | ||
| request.on("started", ({ sessionId }) => { | ||
| console.log("Verification started:", sessionId); | ||
| }); | ||
|
|
||
| request.on("completed", (proofs) => { | ||
| console.log("Proofs received:", proofs); | ||
| }); | ||
|
|
||
| request.on("error", (error) => { | ||
| console.error("Error:", error); | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters**: | ||
|
|
||
| - `event` (string): Event name (`"started"`, `"completed"`, or `"error"`) | ||
| - `callback` (function): Function to call when event fires | ||
|
|
||
| **Available Events**: | ||
|
|
||
| - `started`: Fired when verification session begins (payload: `{ sessionId }`) | ||
| - `completed`: Fired when verification succeeds (payload: `proofs` object) | ||
| - `error`: Fired when verification fails or is cancelled (payload: `error` object/string) | ||
|
|
||
| --- | ||
|
|
||
| ### Complete Usage Example | ||
|
|
||
| ```javascript | ||
| // Initialize the request | ||
| const request = await reclaimExtensionSDK.init(APP_ID, APP_SECRET, "google-login", { extensionID: EXTENSION_ID }); | ||
|
|
||
| // Configure the request | ||
| request.setAppCallbackUrl("https://your.server/receive-proofs"); | ||
| request.setParams({ userId: "user123", action: "verify_email" }); | ||
| request.addContext("0x0", "email verification"); | ||
|
|
||
| // Set up event listeners | ||
| request.on("started", ({ sessionId }) => { | ||
| console.log("Session started:", sessionId); | ||
| }); | ||
|
|
||
| request.on("completed", (proofs) => { | ||
| console.log("Verification complete:", proofs); | ||
| // Send to backend, update UI, etc. | ||
| }); | ||
|
|
||
| request.on("error", (error) => { | ||
| console.error("Verification failed:", error); | ||
| }); | ||
|
|
||
| // Start verification (also returns a promise) | ||
| const proofs = await request.startVerification(); | ||
| console.log("Got proofs via promise:", proofs); | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Consolidate duplicated API reference documentation.
The API reference for initialization methods (lines 72–300) duplicates content from extension-integration/usage.mdx (lines 245–440) with only minor parameter differences (extensionID added). This creates a maintenance burden—any future SDK API changes must be updated in both files.
Consider:
- Extract to shared file: Create a common
_api-reference.mdxpartial and include it in both places. - Reference model: Add a note like: "See Extension Integration API Reference for full API documentation. The main difference for web integration is passing
extensionIDoption." - Web-specific override: Keep only web-integration-specific examples, link to full reference for shared methods.
This pattern will reduce maintenance overhead as the SDK evolves.
Description
Testing (ignore for documentation update)
Type of change
Checklist:
Additional Notes:
Summary by CodeRabbit
Release Notes