Core Concepts#

The Asterisms JS SDK is built around several key concepts that provide a foundation for building modern web applications with secure, scalable backend services.

Architecture Overview#

The SDK follows a resource-based architecture where different capabilities are exposed through specialized resource classes:

• Auth Resource: Authentication and session management
• Account Resource: User account operations and workspace management
• Platform Resource: Application discovery and platform services
• Storage Resource: File upload and storage management
• Drive Resource: File system operations and sharing
• Profile Resource: User profile and settings management
• Dashboard Resource: Application dashboards and widgets
• Notification Resource: Real-time notifications and messaging

SDK Instance#

The AsterismsSDKInstance is the main entry point for all SDK operations. It manages:

import { createAsterismsSDK } from '@asterisms/sdk';

const sdk = createAsterismsSDK({
  bundleId: 'your-app-bundle-id',
  rootDomain: 'your-domain.com',
  navigationAdapter: yourNavigationAdapter
});

// Access resources through the SDK instance
const auth = sdk.auth;
const account = sdk.account;
const storage = sdk.storage;

Resource Pattern#

Each resource follows a consistent pattern:

1. Interface Definition: TypeScript interfaces define the contract
2. Implementation Class: Concrete implementation with business logic
3. Factory Function: Creates properly configured resource instances
4. Error Handling: Consistent error types and handling

// Example resource usage
try {
  const user = await sdk.account.getCurrentUser();
  console.log('Current user:', user);
} catch (error) {
  if (error instanceof AsterismsError) {
    // Handle known SDK errors
    console.error('SDK Error:', error.message);
  }
}

Event System#

The SDK includes a built-in event system for real-time updates:

// Subscribe to authentication events
sdk.auth.onAuthStateChanged((state) => {
  if (state.isAuthenticated) {
    console.log('User logged in:', state.user);
  } else {
    console.log('User logged out');
  }
});

// Subscribe to storage events
sdk.storage.onUploadProgress((progress) => {
  console.log(`Upload progress: ${progress.percentage}%`);
});

Configuration System#

The SDK uses a flexible configuration system:

const config = {
  // Required configuration
  bundleId: 'com.yourcompany.yourapp',
  rootDomain: 'yourapp.com',
  navigationAdapter: yourAdapter,

  // Optional configuration
  logLevel: 'debug',
  enableDevMode: true,
  requestTimeout: 30000,
  retryAttempts: 3,

  // Custom endpoints
  endpoints: {
    auth: 'https://auth.yourapp.com',
    api: 'https://api.yourapp.com'
  }
};

Error Handling#

The SDK provides a comprehensive error hierarchy:

• AsterismsError: Base error class for all SDK errors
• AsterismsBackendError: Server-side errors with HTTP context
• InvalidTokenError: Authentication token issues
• HttpFetchError: Network and HTTP request errors

TypeScript Support#

The SDK is built with TypeScript and provides:

• Full type definitions for all APIs
• Generic types for custom data structures
• Strict type checking for configuration
• IntelliSense support in modern editors

// Type-safe resource operations
interface CustomUserData {
  preferences: {
    theme: 'light' | 'dark';
    language: string;
  };
}

const userData = await sdk.account.getUserData<CustomUserData>();
// userData is fully typed with CustomUserData structure

Next Steps#

• Authentication Guide - Learn about authentication flows
• Resources Guide - Detailed guide to each resource
• Events Guide - Working with the event system
• Configuration Guide - Advanced configuration options