Master (#1262)

* clear * feat: Add everything * fix: Commenht
2026-08-04 18:31:41 +00:00 · 2025-10-03 14:45:52 -04:00
parent 43b4a11c06
commit 13e6c3e84d
1935 changed files with 655061 additions and 40058 deletions
@@ -0,0 +1,298 @@
+# @sonr.io/sdk
+
+This is the TypeScript SDK for Highway WebAuthn authentication gateway. It provides a comprehensive client library for interacting with Highway APIs, including WebAuthn authentication, session management, and blockchain operations.
+
+## Features
+
+- **WebAuthn Client**: Complete WebAuthn registration and authentication flows
+- **Session Management**: Automatic session handling and token management
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **HTTP Client**: Configured HTTP client with automatic retries and error handling
+- **Blockchain Integration**: Client methods for DID and blockchain operations
+- **Environment Support**: Configurable for development, staging, and production
+
+## Installation
+
+```bash
+npm install @sonr.io/sdk
+# or
+yarn add @sonr.io/sdk
+# or
+pnpm add @sonr.io/sdk
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { HighwaySDK } from "@sonr.io/sdk";
+
+const sdk = new HighwaySDK({
+  apiUrl: "https://api.yourdomain.com",
+  environment: "production",
+});
+```
+
+### WebAuthn Authentication
+
+```typescript
+// Register a new user
+try {
+  const registrationResult = await sdk.auth.register({
+    username: "user@example.com",
+    displayName: "John Doe",
+  });
+
+  console.log("Registration successful:", registrationResult);
+} catch (error) {
+  console.error("Registration failed:", error);
+}
+
+// Authenticate existing user
+try {
+  const authResult = await sdk.auth.authenticate({
+    username: "user@example.com",
+  });
+
+  console.log("Authentication successful:", authResult);
+} catch (error) {
+  console.error("Authentication failed:", error);
+}
+```
+
+### Session Management
+
+```typescript
+// Get current session
+const session = await sdk.session.getCurrent();
+
+// Validate session
+const isValid = await sdk.session.validate();
+
+// Logout
+await sdk.session.logout();
+```
+
+### Blockchain Operations
+
+```typescript
+// Create DID
+const didResult = await sdk.blockchain.createDID({
+  username: "user@example.com",
+  credentialId: "webauthn-credential-id",
+  publicKey: "public-key-data",
+});
+
+// Resolve DID
+const didDocument = await sdk.blockchain.resolveDID("did:sonr:123456789");
+```
+
+## API Reference
+
+### HighwaySDK
+
+The main SDK class that provides access to all Highway services.
+
+#### Constructor Options
+
+```typescript
+interface HighwaySDKOptions {
+  apiUrl: string;
+  environment?: "development" | "staging" | "production";
+  timeout?: number;
+  retries?: number;
+}
+```
+
+#### Methods
+
+- `auth`: WebAuthn authentication methods
+- `session`: Session management methods
+- `blockchain`: Blockchain and DID operations
+- `profile`: User profile management
+
+### Authentication (`sdk.auth`)
+
+- `register(options)`: Register new WebAuthn credential
+- `authenticate(options)`: Authenticate with WebAuthn
+- `getProfile()`: Get current user profile
+
+### Session (`sdk.session`)
+
+- `getCurrent()`: Get current session information
+- `validate()`: Validate current session
+- `logout()`: End current session
+
+### Blockchain (`sdk.blockchain`)
+
+- `createDID(options)`: Create new DID document
+- `resolveDID(id)`: Resolve DID document by ID
+- `getHealth()`: Get blockchain service health
+
+## Development Roadmap
+
+### 🔮 **Future Implementation** (Planned)
+
+- [ ] **SDK Core**: TypeScript SDK with HTTP client configuration
+- [ ] **Authentication Module**: WebAuthn registration and authentication methods
+- [ ] **Session Management**: Automatic session handling and token management
+- [ ] **Blockchain Module**: DID creation and resolution methods
+- [ ] **Profile Management**: User profile operations and management
+- [ ] **Type Definitions**: Comprehensive TypeScript type definitions
+- [ ] **Error Handling**: Robust error handling and retry logic
+
+### 🚧 **Production Readiness** (Next)
+
+- [ ] **Testing Suite**: Unit tests for all SDK methods
+- [ ] **Documentation**: Complete API documentation and examples
+- [ ] **Performance Optimization**: Request caching and optimization
+- [ ] **Bundle Optimization**: Tree-shaking and minimal bundle size
+- [ ] **Browser Support**: Cross-browser compatibility testing
+- [ ] **Node.js Support**: Server-side usage support
+
+### 🔮 **Future Enhancements**
+
+- [ ] **React Hooks**: React hooks for easy integration
+- [ ] **Vue Composables**: Vue.js composables for Vue applications
+- [ ] **Offline Support**: Offline capability with background sync
+- [ ] **Real-time Features**: WebSocket support for real-time updates
+- [ ] **Advanced Caching**: Intelligent caching strategies
+- [ ] **Plugin System**: Extensible plugin architecture
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```typescript
+import { HighwayError, WebAuthnError, SessionError } from "@sonr.io/sdk";
+
+try {
+  await sdk.auth.register(options);
+} catch (error) {
+  if (error instanceof WebAuthnError) {
+    console.error("WebAuthn error:", error.message);
+  } else if (error instanceof SessionError) {
+    console.error("Session error:", error.message);
+  } else if (error instanceof HighwayError) {
+    console.error("Highway error:", error.message);
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```env
+# Default API URL
+HIGHWAY_API_URL=https://api.yourdomain.com
+
+# Development
+HIGHWAY_API_URL=http://localhost:8080
+```
+
+### SDK Configuration
+
+```typescript
+const sdk = new HighwaySDK({
+  apiUrl: process.env.HIGHWAY_API_URL || "https://api.yourdomain.com",
+  environment: process.env.NODE_ENV || "production",
+  timeout: 10000,
+  retries: 3,
+});
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the SDK
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+```
+
+## Integration Examples
+
+### React Application
+
+```typescript
+import { HighwaySDK } from "@sonr.io/sdk";
+import { useEffect, useState } from "react";
+
+function useHighway() {
+  const [sdk] = useState(
+    () =>
+      new HighwaySDK({
+        apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+      })
+  );
+
+  return sdk;
+}
+
+function AuthComponent() {
+  const sdk = useHighway();
+
+  const handleRegister = async () => {
+    try {
+      await sdk.auth.register({
+        username: "user@example.com",
+        displayName: "John Doe",
+      });
+    } catch (error) {
+      console.error("Registration failed:", error);
+    }
+  };
+
+  return <button onClick={handleRegister}>Register with WebAuthn</button>;
+}
+```
+
+### Node.js Application
+
+```typescript
+import { HighwaySDK } from "@sonr.io/sdk";
+
+const sdk = new HighwaySDK({
+  apiUrl: "https://api.yourdomain.com",
+  environment: "production",
+});
+
+async function createUser() {
+  try {
+    const result = await sdk.auth.register({
+      username: "user@example.com",
+      displayName: "John Doe",
+    });
+
+    console.log("User created:", result);
+  } catch (error) {
+    console.error("Failed to create user:", error);
+  }
+}
+```
+
+## Dependencies
+
+- **TypeScript**: ^5.3.0
+- **Axios**: ^1.6.0 (HTTP client)
+- **Zod**: ^3.22.0 (Schema validation)
+- **@simplewebauthn/browser**: ^9.0.0 (WebAuthn client)
+
+## Contributing
+
+When contributing to the SDK:
+
+1. Follow TypeScript best practices
+2. Add comprehensive type definitions
+3. Include unit tests for new features
+4. Update documentation and examples
+5. Ensure backward compatibility