[TA-4793] @fast-auth/browser-sdk docs#27
Conversation
📝 WalkthroughWalkthroughThis update restructures and expands the FastAuth Browser SDK documentation by introducing detailed guides and API references for core concepts, installation, client usage, providers, and the signer component. It also updates site configuration to support Mermaid diagrams, enhances sidebar navigation, and includes minor JSDoc and error handling improvements in the SDK source code. Changes
Sequence Diagram(s)sequenceDiagram
participant App as Application
participant Client as FastAuthClient
participant Provider as IFastAuthProvider
participant Signer as FastAuthSigner
participant NEAR as NEAR Blockchain
App->>Client: login()
Client->>Provider: login()
Provider-->>Client: Authenticated
App->>Client: getSigner()
Client->>Provider: isLoggedIn()
Provider-->>Client: true
Client->>Signer: new FastAuthSigner(provider, connection, options)
Signer->>Provider: getPath()
Signer-->>Client: FastAuthSigner instance
App->>Signer: createAccount(accountId)
Signer->>Provider: getPath()
Signer->>NEAR: createAccount with derived public key
NEAR-->>Signer: Account created
App->>Signer: requestTransactionSignature(tx)
Signer->>Provider: requestTransactionSignature(tx)
Provider-->>Signer: SignatureRequest
App->>Signer: sendTransaction(tx, signature)
Signer->>NEAR: Broadcast signed transaction
NEAR-->>Signer: Transaction result
Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
⏰ Context from checks skipped due to timeout of 90000ms (1)
✨ Finishing Touches
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (9)
docs/docs/sdk/browser/signer.md (9)
9-9: Ambiguous "Dependencies" SectionThe “Dependencies” heading is misleading since it covers configuration types, not external dependencies. Rename it to something like “Type Definitions” or “Configuration Types” to better reflect its content.
13-23: Link Configuration Types to API ReferenceConsider adding hyperlinks or import statements to the source code for
FastAuthSignerOptions,CreateAccountOptions, andSignatureRequesttypes. This will help readers jump directly to the type definitions in the SDK codebase.
33-39: Include Class Signature in Constructor SnippetThe constructor snippet shows only the parameters. For completeness, include the class declaration (e.g.,
class FastAuthSigner<P extends IFastAuthProvider>) so users see how the constructor integrates into the class.
41-46: Fix Parameter List IndentationThe bullets under “Parameters” are not indented properly according to markdownlint rules. Collapse the list to a single level or use two spaces for the sub‐list indent to satisfy MD007.
67-71: Correct Unordered List Indentation increateAccountMarkdownlint flags indent errors for the sub-list under “Parameters”. Reduce the indent from 4 to 2 spaces for list items like
accountIdandoptions.
98-101: Correct Unordered List Indentation inrequestTransactionSignatureThe list items for “Usage” and “Flow” should be indented by 2 spaces under the parent list to comply with markdownlint MD007.
175-179: Correct Unordered List Indentation in Error CodesUnder “Error Codes,” the
INVALID_ARGUMENTSlist item is over-indented. Use a 2-space indent for the sub-list to match markdownlint expectations.
189-205: Clarify Imports in Basic Transaction Flow ExampleThe example invokes
buildTransactionandFastAuthSignaturewithout import statements. Includeimport { buildTransaction } from '...'andimport { FastAuthSignature } from '...'so readers can copy the snippet directly.
212-220: Clarify Utility Imports in Account Creation ExampleIn the account creation snippet, you parse NEAR amounts with
parseNearAmount. Show the import (e.g.,import { parseNearAmount } from 'near-api-js/utils') or clarify that it comes from an external utility.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (12)
docs/docs/sdk/browser.md(0 hunks)docs/docs/sdk/browser/client.md(1 hunks)docs/docs/sdk/browser/concepts.md(1 hunks)docs/docs/sdk/browser/getting-started.md(1 hunks)docs/docs/sdk/browser/installation.md(1 hunks)docs/docs/sdk/browser/providers.md(1 hunks)docs/docs/sdk/browser/signer.md(1 hunks)docs/docusaurus.config.ts(3 hunks)docs/package.json(1 hunks)docs/sidebars.ts(1 hunks)packages/sdks/browser/src/client/client.ts(2 hunks)packages/sdks/browser/src/providers/auth0/auth0.provider.ts(1 hunks)
💤 Files with no reviewable changes (1)
- docs/docs/sdk/browser.md
🧰 Additional context used
🪛 LanguageTool
docs/docs/sdk/browser/getting-started.md
[uncategorized] ~11-~11: A punctuation mark might be missing here.
Context: ...install the SDK using npm, yarn, or pnpm - Concepts - Understand ...
(AI_EN_LECTOR_MISSING_PUNCTUATION)
[uncategorized] ~17-~17: A punctuation mark might be missing here.
Context: ...reference for the FastAuthSigner class - Providers - Documenta...
(AI_EN_LECTOR_MISSING_PUNCTUATION)
docs/docs/sdk/browser/concepts.md
[duplication] ~122-~122: Possible typo: you repeated a word.
Context: ... Application requests Signer from Client 2. Client verifies authentication status via **...
(ENGLISH_WORD_REPEAT_RULE)
docs/docs/sdk/browser/client.md
[uncategorized] ~30-~30: Loose punctuation mark.
Context: ...uthClientOptions ) ``` - provider: An instance implementing `IFastAuthProv...
(UNLIKELY_OPENING_PUNCTUATION)
docs/docs/sdk/browser/signer.md
[uncategorized] ~43-~43: Loose punctuation mark.
Context: ...### Parameters - fastAuthProvider: An instance implementing `IFastAuthProv...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~175-~175: Loose punctuation mark.
Context: ...Error Types - FastAuthSignerError: Base error class for signer operations ...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 markdownlint-cli2 (0.17.2)
docs/docs/sdk/browser/signer.md
68-68: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
69-69: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
150-150: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
151-151: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
177-177: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: integration-packages / Build
🔇 Additional comments (14)
docs/package.json (1)
20-20: LGTM! Proper dependency addition for Mermaid support.The addition of
@docusaurus/theme-mermaidwith version 3.7.0 aligns well with other Docusaurus dependencies and properly enables Mermaid diagram rendering for the new SDK documentation.packages/sdks/browser/src/providers/auth0/auth0.provider.ts (1)
43-43: LGTM! Improved error handling with proper TypeScript typing.The change to explicitly type the caught error as
unknownand use underscore prefix follows TypeScript best practices. This improves type safety while clearly indicating the parameter is intentionally unused.docs/docs/sdk/browser/installation.md (1)
1-47: LGTM! Comprehensive installation documentation.The installation guide is well-structured and thorough, covering all major package managers (npm, yarn, pnpm) with clear examples for both latest and specific version installations. The reference to the changelog for version selection is a helpful addition for users.
docs/docs/sdk/browser/getting-started.md (1)
1-34: LGTM! Excellent documentation structure and navigation.The getting started guide provides clear organization of the SDK documentation with logical sections for Core Documentation and API Reference. The Quick Navigation section with recommended reading order is particularly helpful for guiding users through the documentation effectively.
docs/docusaurus.config.ts (3)
36-38: LGTM! Proper Mermaid configuration.The markdown configuration correctly enables Mermaid diagram support, which aligns with the addition of the Mermaid theme dependency.
50-50: LGTM! Mermaid theme properly added.The Mermaid theme is correctly included to work with the markdown configuration for diagram rendering.
112-113: LGTM! Navigation updated for new documentation structure.The Browser SDK navigation correctly points to the new getting-started page and properly associates with the browserSdkSidebar. This aligns well with the restructured documentation organization.
docs/sidebars.ts (1)
44-61: Excellent documentation structure organization!The sidebar restructuring from a single flat entry to organized Introduction and Reference sections provides much better navigation and discoverability. The logical grouping of getting-started, installation, and concepts under Introduction, followed by detailed API references (client, providers, signer) under Reference follows documentation best practices.
packages/sdks/browser/src/client/client.ts (2)
21-21: JSDoc parameter naming improvement.Good alignment of JSDoc with the actual implementation - using
argsinstead ofoptsbetter reflects the rest parameter usage.
31-31: Added helpful return description.The addition of the return description for the
logoutmethod improves API documentation clarity.docs/docs/sdk/browser/concepts.md (1)
1-152: Excellent comprehensive conceptual documentation!This conceptual overview provides outstanding architectural insights with:
- Clear modular architecture explanation
- Effective Mermaid diagram showing component relationships
- Detailed component responsibilities and interactions
- Well-structured sections covering authentication and transaction flows
- Strong emphasis on key benefits like modularity and type safety
The documentation effectively bridges high-level concepts with implementation details, making it an excellent reference for developers.
docs/docs/sdk/browser/client.md (1)
1-119: Comprehensive and well-structured client API documentation!This documentation provides excellent coverage of the FastAuthClient with:
- Clear overview and purpose explanation
- Detailed constructor and method documentation
- Practical usage examples with error handling
- Complete TypeScript interfaces and type definitions
- Step-by-step integration guide
The structure and content make it easy for developers to understand and implement the client effectively.
docs/docs/sdk/browser/providers.md (1)
1-251: Outstanding comprehensive providers documentation!This documentation excellently covers the provider system with:
- Clear IFastAuthProvider interface definition with detailed method explanations
- Comprehensive Auth0Provider setup and configuration guide
- Practical usage examples and authentication flow demonstrations
- Complete custom provider implementation template with key considerations
- Strong emphasis on security and integration best practices
The documentation effectively serves both users of the Auth0Provider and developers implementing custom providers, providing the right level of detail for each use case.
docs/docs/sdk/browser/signer.md (1)
1-2: ```shell
#!/bin/bash
set -eecho "=== Extracting docs plugin configuration from docusaurus.config.ts ==="
grep -R "docsPlugin" -n docs/docusaurus.config.ts || true
echo "----"
grep -R "plugin-?content-docs" -n docs/docusaurus.config.ts || true
echo "----"
grep -R "path:" -n docs/docusaurus.config.ts | sed -n '1,200p'</details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
|
All alerts resolved. Learn more about Socket for GitHub. This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/docs/sdk/browser/concepts.md (3)
57-60: Ensure consistent naming for the provider interfaceThe heading introduces FastAuthProvider, but the rest of the documentation – and the Mermaid diagram – refer to
IFastAuthProvider. Pick one name and stick to it to avoid confusing readers.
111-113: Tweak wording to remove the repeated noun and improve flowThe sentence starts abruptly and repeats Application. Consider re-phrasing:
-1. Application requests **Signer** from **Client** +1. The application requests a **Signer** from the **Client**This eliminates the duplication flagged by the linter and reads more smoothly.
7-42: Add an accessible caption or alt-text for the Mermaid diagramScreen-reader users will not benefit from the visual diagram. Add a short descriptive caption or alt-text immediately before or after the diagram explaining what it depicts (e.g., “Component interaction diagram showing Client, Provider, Signer and NEAR Connection relationships”).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/sdk/browser/concepts.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/docs/sdk/browser/concepts.md
[duplication] ~112-~112: Possible typo: you repeated a word.
Context: ... Application requests Signer from Client 2. Client verifies authentication status via **...
(ENGLISH_WORD_REPEAT_RULE)
2 participants
[TA-4793] @fast-auth/browser-sdk docs
Changes 🛠️
docs
@fast-auth/browser-sdkpackageSummary by CodeRabbit
Documentation
Style