sonr/packages/sdk

@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

npm install @sonr.io/sdk
# or
yarn add @sonr.io/sdk
# or
pnpm add @sonr.io/sdk

Usage

Basic Setup

import { HighwaySDK } from "@sonr.io/sdk";

const sdk = new HighwaySDK({
  apiUrl: "https://api.yourdomain.com",
  environment: "production",
});

WebAuthn Authentication

// 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

// Get current session
const session = await sdk.session.getCurrent();

// Validate session
const isValid = await sdk.session.validate();

// Logout
await sdk.session.logout();

Blockchain Operations

// 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

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:

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

# Default API URL
HIGHWAY_API_URL=https://api.yourdomain.com

# Development
HIGHWAY_API_URL=http://localhost:8080

SDK Configuration

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

# 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

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

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