Skip to content

Commit b9ba911

Browse files
AdriaCarreraAdriaCarrera
authored
Merge pull request #27 from Peersyst/docs/feat/browser-sdk
[TA-4793] @fast-auth/browser-sdk docs
2 parents 574d2b0 + f80b17c commit b9ba911

File tree

13 files changed

+1774
-15
lines changed

13 files changed

+1774
-15
lines changed

‎docs/docs/sdk/browser.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/docs/sdk/browser/client.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Client
2+
3+
The `FastAuthClient` is the main entry point for interacting with the FastAuth system in browser environments. It provides a high-level interface for authentication operations and transaction signing through various providers.
4+
5+
## Overview
6+
7+
The `FastAuthClient` is a generic TypeScript class that orchestrates authentication and signing operations by delegating to a configurable provider. It serves as an abstraction layer that standardizes the interface for different authentication providers while maintaining type safety.
8+
9+
## Dependencies
10+
11+
### Configuration Types
12+
13+
```typescript
14+
type FastAuthClientOptions = {
15+
mpcContractId: string; // MPC contract address
16+
fastAuthContractId: string; // FastAuth contract address
17+
};
18+
```
19+
20+
## Constructor
21+
22+
```typescript
23+
constructor(
24+
provider: P,
25+
connection: Connection,
26+
options: FastAuthClientOptions
27+
)
28+
```
29+
30+
- **`provider`**: An instance implementing `IFastAuthProvider` interface
31+
- **`connection`**: NEAR network connection from `near-api-js`
32+
- **`options`**: Configuration object containing contract IDs
33+
34+
## Methods
35+
36+
### `login`
37+
38+
Initiates the authentication process using the configured provider.
39+
40+
- **Parameters**: Variable arguments that are passed directly to the provider's login method
41+
- **Returns**: Result from the provider's login implementation (typically void)
42+
- **Usage**: Delegates to `provider.login()` with all provided arguments
43+
44+
### `logout`
45+
46+
Terminates the user session.
47+
48+
- **Returns**: Result from the provider's logout implementation (typically void)
49+
- **Usage**: Delegates to `provider.logout()`
50+
51+
### `getSigner`
52+
53+
Creates and returns a configured signer instance for transaction operations.
54+
55+
- **Returns**: Promise resolving to a `FastAuthSigner` instance
56+
- **Throws**: `FastAuthClientError` with code `USER_NOT_LOGGED_IN` if user is not authenticated
57+
- **Behavior**:
58+
1. Checks authentication status via `provider.isLoggedIn()`
59+
2. Creates a new `FastAuthSigner` instance if authenticated
60+
3. Initializes the signer before returning
61+
62+
## Provider Interface
63+
64+
```typescript
65+
interface IFastAuthProvider {
66+
// Base signer provider methods
67+
isLoggedIn(): Promise<boolean>;
68+
requestTransactionSignature(...args: any[]): Promise<void>;
69+
requestDelegateActionSignature(...args: any[]): Promise<void>;
70+
getSignatureRequest(): Promise<SignatureRequest>;
71+
getPath(): Promise<string>;
72+
73+
// Client-specific methods
74+
login(...args: any[]): void;
75+
logout(): void;
76+
}
77+
```
78+
79+
## Usage
80+
81+
### Client instantiation
82+
83+
```typescript
84+
import { FastAuthClient } from "@near/fast-auth-sdk";
85+
import { connect } from "near-api-js";
86+
87+
// 1. Set up NEAR connection
88+
const connection = await connect(nearConfig);
89+
90+
// 2. Create provider instance
91+
const provider = new SomeAuthProvider(config);
92+
93+
// 3. Initialize client
94+
const client = new FastAuthClient(provider, connection, {
95+
mpcContractId: "mpc.contract.near",
96+
fastAuthContractId: "fastauth.contract.near",
97+
});
98+
99+
// 4. Authenticate
100+
await client.login(/* provider-specific args */);
101+
102+
// 5. Get signer for transactions
103+
const signer = await client.getSigner();
104+
```
105+
106+
### Error Handling
107+
108+
```typescript
109+
try {
110+
const signer = await client.getSigner();
111+
// Use signer for transactions
112+
} catch (error) {
113+
if (error instanceof FastAuthClientError) {
114+
// Handle authentication errors
115+
console.error("Authentication required:", error.message);
116+
}
117+
}
118+
```

‎docs/docs/sdk/browser/concepts.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Concepts
2+
3+
The FastAuth Browser SDK is designed with a modular architecture that separates concerns between authentication, signing, and blockchain interactions. This section provides a high-level overview of the core components and their relationships.
4+
5+
## Architecture Overview
6+
7+
```mermaid
8+
graph TD
9+
Client["FastAuthClient&lt;P&gt;"]
10+
Provider["IFastAuthProvider"]
11+
Signer["FastAuthSigner&lt;P&gt;"]
12+
Connection["NEAR Connection"]
13+
14+
subgraph "Authentication Layer"
15+
Provider
16+
AuthProviders["Auth0Provider<br/>CustomProvider<br/>..."]
17+
end
18+
19+
subgraph "Application Layer"
20+
Client
21+
end
22+
23+
subgraph "Transaction Layer"
24+
Signer
25+
Actions["Transaction Actions<br/>Delegate Actions<br/>Account Creation"]
26+
end
27+
28+
subgraph "Blockchain Layer"
29+
Connection
30+
Contracts["MPC Contract<br/>FastAuth Contract"]
31+
end
32+
33+
Client -->|"uses"| Provider
34+
Client -->|"creates"| Signer
35+
Client -->|"uses"| Connection
36+
Signer -->|"uses"| Provider
37+
Signer -->|"uses"| Connection
38+
39+
Provider -.->|"implements"| AuthProviders
40+
Signer -->|"creates"| Actions
41+
Connection -->|"interacts with"| Contracts
42+
```
43+
44+
## Core Components
45+
46+
### FastAuthClient
47+
48+
The **FastAuthClient** is the main orchestrator and entry point for the SDK. It provides a unified interface for authentication and transaction operations.
49+
50+
**Key Responsibilities:**
51+
52+
- Manages the authentication lifecycle (login/logout)
53+
- Creates and configures signer instances
54+
- Abstracts provider-specific implementations
55+
- Enforces authentication requirements before transaction operations
56+
57+
### FastAuthProvider
58+
59+
The **FastAuthProvider** interface defines the contract for authentication providers. This abstraction allows the SDK to support multiple authentication backends.
60+
61+
**Key Capabilities:**
62+
63+
- Authentication state management (`isLoggedIn()`)
64+
- Login/logout operations
65+
- Transaction signature requests
66+
- Cryptographic path derivation
67+
68+
**Provider Types:**
69+
70+
- **Auth0Provider**: Integration with Auth0 authentication service
71+
- **CustomProvider**: Support for custom authentication backends
72+
73+
### FastAuthSigner
74+
75+
The **FastAuthSigner** handles all transaction-related operations and blockchain interactions. It bridges the authentication layer with NEAR blockchain functionality.
76+
77+
**Key Features:**
78+
79+
- Transaction signing and submission
80+
- Account creation operations
81+
- Delegate action handling
82+
- Public key derivation from MPC contracts
83+
84+
**Transaction Types:**
85+
86+
- Standard NEAR transactions
87+
- Delegate actions for gasless transactions
88+
- Account creation with public key registration
89+
90+
### NEAR Connection
91+
92+
The **NEAR Connection** (from `near-api-js`) provides the blockchain connectivity layer.
93+
94+
**Responsibilities:**
95+
96+
- Network communication with NEAR blockchain
97+
- Contract method calls and queries
98+
- Transaction broadcasting
99+
- Block and state queries
100+
101+
## Component Interactions
102+
103+
### Authentication Flow
104+
105+
1. **Client** receives login request from application
106+
2. **Client** delegates to **Provider** for authentication
107+
3. **Provider** handles authentication mechanism (OAuth, custom, etc.)
108+
4. **Provider** maintains authentication state
109+
110+
### Transaction Flow
111+
112+
1. Application requests **Signer** from **Client**
113+
2. **Client** verifies authentication status via **Provider**
114+
3. **Client** creates and initializes **Signer** instance
115+
4. **Signer** uses **Provider** for signature requests
116+
5. **Signer** interacts with NEAR contracts via **Connection**
117+
118+
### Key Benefits
119+
120+
**Modularity**: Each component has a single responsibility, making the SDK maintainable and testable.
121+
122+
**Extensibility**: The provider pattern allows easy integration of new authentication mechanisms.
123+
124+
**Type Safety**: Generic types ensure compile-time validation across component interactions.
125+
126+
**Separation of Concerns**: Authentication, signing, and blockchain interactions are cleanly separated.
127+
128+
**Provider Abstraction**: Applications can switch authentication providers without changing business logic.
129+
130+
## Integration Points
131+
132+
### Smart Contracts
133+
134+
- **MPC Contract**: Handles multi-party computation for key derivation
135+
- **FastAuth Contract**: Manages authentication and signature verification
136+
137+
### External Services
138+
139+
- **Authentication Providers**: Auth0, custom backends, identity providers
140+
- **NEAR Network**: Mainnet, testnet, or custom networks
141+
- **Browser APIs**: LocalStorage, SessionStorage for state persistence

‎docs/docs/sdk/browser/getting-started.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Getting Started
2+
3+
Welcome to the FastAuth Browser SDK documentation! This section provides comprehensive guides and references for integrating FastAuth into your web applications.
4+
5+
## Documentation Overview
6+
7+
The FastAuth Browser SDK documentation is organized into the following sections:
8+
9+
### Core Documentation
10+
11+
- **[Installation](./installation.md)** - Learn how to install the SDK using npm, yarn, or pnpm
12+
- **[Concepts](./concepts.md)** - Understand the SDK architecture and how components interact
13+
14+
### API Reference
15+
16+
- **[Client](./client.md)** - Complete reference for the `FastAuthClient` class
17+
- **[Signer](./signer.md)** - Complete reference for the `FastAuthSigner` class
18+
- **[Providers](./providers.md)** - Documentation for authentication providers
19+
20+
## Quick Navigation
21+
22+
### For New Users
23+
24+
1. Start with **[Installation](./installation.md)** to set up the SDK
25+
2. Read **[Concepts](./concepts.md)** to understand the architecture
26+
3. Use **[Client](./client.md)** to learn about the main entry point
27+
4. Explore **[Signer](./signer.md)** for transaction operations
28+
29+
### For API Reference
30+
31+
- **[Client API](./client.md)** - FastAuthClient methods and configuration
32+
- **[Signer API](./signer.md)** - FastAuthSigner methods and transaction handling
33+
- **[Providers API](./providers.md)** - Authentication provider interfaces

‎docs/docs/sdk/browser/installation.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Installation
2+
3+
To start using the FastAuth Browser SDK, you need to install it first. You can install the latest version or a specific version.
4+
5+
## Latest version
6+
7+
To install the latest version, you can use the following commands:
8+
9+
### Using npm
10+
11+
```bash
12+
npm install @fast-auth/browser-sdk
13+
```
14+
15+
### Using yarn
16+
17+
```bash
18+
yarn add @fast-auth/browser-sdk
19+
```
20+
21+
### Using pnpm
22+
23+
```bash
24+
pnpm add @fast-auth/browser-sdk
25+
```
26+
27+
## Specific version
28+
29+
If you want to install a specific version, you can find all the available versions in the Changelog page.
30+
31+
### Using npm
32+
33+
```bash
34+
npm install @fast-auth/browser-sdk@<version>
35+
```
36+
37+
### Using yarn
38+
39+
```bash
40+
yarn add @fast-auth/browser-sdk@<version>
41+
```
42+
43+
### Using pnpm
44+
45+
```bash
46+
pnpm add @fast-auth/browser-sdk@<version>
47+
```

0 commit comments

Comments
 (0)