Home
JS SDK (Browser)
JS SDK (Server)
FAQ
Home
JS SDK (Browser)
JS SDK (Server)
FAQ

Resources

Resources are the core building blocks of the Asterisms JS SDK, providing access to different backend services and capabilities. Each resource encapsulates a specific domain of functionality with consistent APIs and error handling.

Resource Overview

Resource Purpose Key Features
Auth Authentication & Sessions Login, logout, token management, providers
Account User Accounts & Workspaces User info, workspace management, permissions
Platform Application Discovery App registry, platform services, metadata
Storage File Upload & Storage File uploads, storage management, metadata
Drive File System Operations File/folder operations, sharing, permissions
Profile User Profiles & Settings Profile data, preferences, customization
Dashboard Application Dashboards Widgets, layouts, dashboard management
Notification Real-time Messaging Push notifications, in-app messages, events

Auth Resource

Handles all authentication-related operations.

Key Methods

// Authentication
await sdk.auth.login({ provider: 'srp6', credentials: { username, password } });
await sdk.auth.logout();

// State management
const isAuthenticated = sdk.auth.isAuthenticated();
const currentUser = sdk.auth.getCurrentUser();

// Token management
const token = sdk.auth.getToken();
await sdk.auth.refreshToken();

// Provider management
sdk.auth.registerProvider('custom', customProvider);

Events

sdk.auth.onAuthStateChanged((state) => {
  console.log('Auth state:', state.isAuthenticated);
});

sdk.auth.onTokenRefresh((token) => {
  console.log('Token refreshed');
});

Account Resource

Manages user accounts, workspaces, and related operations.

User Management

// Get current user information
const user = await sdk.account.getCurrentUser();

// Update user profile
await sdk.account.updateUser({
  displayName: 'New Display Name',
  email: 'new@example.com'
});

// Account operations
await sdk.account.changePassword(oldPassword, newPassword);
await sdk.account.deleteAccount();

Workspace Management

// List user workspaces
const workspaces = await sdk.account.getWorkspaces();

// Create new workspace
const workspace = await sdk.account.createWorkspace({
  name: 'My Workspace',
  description: 'Workspace description'
});

// Switch to workspace
await sdk.account.switchWorkspace(workspace.id);

// Get current workspace
const currentWorkspace = await sdk.account.getCurrentWorkspace();

Invitations & Access

// Send workspace invitation
await sdk.account.inviteUser({
  email: 'user@example.com',
  workspaceId: 'workspace-id',
  role: 'member'
});

// List pending invitations
const invitations = await sdk.account.getPendingInvitations();

// Accept invitation
await sdk.account.acceptInvitation(invitationId);

Platform Resource

Provides access to platform-wide services and application discovery.

Application Discovery

// Get available applications
const apps = await sdk.platform.getAvailableApplications();

// Get application details
const appDetails = await sdk.platform.getApplication('app-id');

// Launch application
await sdk.platform.launchApplication('app-id', {
  mode: 'embedded',
  container: '#app-container'
});

Platform Services

// Get platform configuration
const config = await sdk.platform.getConfiguration();

// Check feature availability
const hasFeature = await sdk.platform.hasFeature('advanced-analytics');

// Get platform status
const status = await sdk.platform.getStatus();

Storage Resource

Handles file uploads and storage operations.

File Upload

// Upload single file
const file = document.getElementById('fileInput').files[0];
const result = await sdk.storage.upload(file, {
  folder: '/documents',
  metadata: {
    description: 'Important document',
    tags: ['work', 'important']
  }
});

// Upload with progress tracking
const upload = sdk.storage.uploadWithProgress(file);
upload.onProgress((progress) => {
  console.log(`Upload: ${progress.percentage}%`);
});
const result = await upload.promise;

Batch Operations

// Upload multiple files
const files = Array.from(document.getElementById('multipleFiles').files);
const results = await sdk.storage.uploadBatch(files, {
  folder: '/uploads',
  concurrency: 3
});

// Monitor batch progress
sdk.storage.onBatchProgress((batch) => {
  console.log(`Batch ${batch.id}: ${batch.completedCount}/${batch.totalCount}`);
});

Storage Management

// List storage items
const items = await sdk.storage.list({
  folder: '/documents',
  recursive: true,
  filter: { type: 'image' }
});

// Get storage usage
const usage = await sdk.storage.getUsage();
console.log(`Used: ${usage.used} / ${usage.total}`);

// Delete items
await sdk.storage.delete(['file-id-1', 'file-id-2']);

Drive Resource

Provides file system-like operations with advanced sharing capabilities.

File & Folder Operations

// Create folder
const folder = await sdk.drive.createFolder({
  name: 'My Folder',
  parent: 'parent-folder-id'
});

// List folder contents
const contents = await sdk.drive.listFolder('folder-id');

// Move items
await sdk.drive.move(['item-id-1', 'item-id-2'], 'destination-folder-id');

// Copy items
await sdk.drive.copy(['item-id-1'], 'destination-folder-id');

// Rename item
await sdk.drive.rename('item-id', 'New Name');

Sharing & Permissions

// Share item with users
await sdk.drive.share('item-id', {
  users: ['user1@example.com', 'user2@example.com'],
  permission: 'read',
  message: 'Sharing this document with you'
});

// Create public share link
const shareLink = await sdk.drive.createShareLink('item-id', {
  permission: 'read',
  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days
});

// Get access list
const accessList = await sdk.drive.getAccessList('item-id');

// Update permissions
await sdk.drive.updatePermission('item-id', 'user@example.com', 'write');

Search & Metadata

// Search files and folders
const results = await sdk.drive.search({
  query: 'project proposal',
  type: ['document'],
  folder: 'projects-folder-id'
});

// Get/set metadata
const metadata = await sdk.drive.getMetadata('item-id');
await sdk.drive.setMetadata('item-id', {
  description: 'Updated description',
  tags: ['important', 'project']
});

Profile Resource

Manages user profiles and personal settings.

Profile Management

// Get user profile
const profile = await sdk.profile.getProfile();

// Update profile
await sdk.profile.updateProfile({
  displayName: 'John Doe',
  bio: 'Software Developer',
  avatar: avatarFile,
  socialLinks: {
    linkedin: 'https://linkedin.com/in/johndoe',
    github: 'https://github.com/johndoe'
  }
});

// Upload avatar
await sdk.profile.uploadAvatar(avatarFile);

Settings & Preferences

// Get user preferences
const preferences = await sdk.profile.getPreferences();

// Update preferences
await sdk.profile.updatePreferences({
  theme: 'dark',
  language: 'en',
  notifications: {
    email: true,
    push: true,
    inApp: true
  },
  privacy: {
    profileVisibility: 'public',
    allowDirectMessages: true
  }
});

// Get/set custom settings
const customSettings = await sdk.profile.getCustomSettings('myApp');
await sdk.profile.setCustomSettings('myApp', {
  dashboardLayout: 'grid',
  defaultView: 'list'
});

Dashboard Resource

Manages application dashboards and widgets.

Dashboard Management

// Get user dashboards
const dashboards = await sdk.dashboard.getDashboards();

// Create dashboard
const dashboard = await sdk.dashboard.create({
  name: 'My Dashboard',
  description: 'Personal workspace dashboard',
  layout: 'grid'
});

// Update dashboard
await sdk.dashboard.update(dashboard.id, {
  name: 'Updated Dashboard Name'
});

Widget Management

// Add widget to dashboard
const widget = await sdk.dashboard.addWidget(dashboard.id, {
  type: 'chart',
  title: 'Sales Chart',
  configuration: {
    dataSource: 'sales-data',
    chartType: 'line'
  },
  position: { x: 0, y: 0, width: 6, height: 4 }
});

// Update widget
await sdk.dashboard.updateWidget(widget.id, {
  title: 'Updated Chart Title',
  position: { x: 6, y: 0, width: 6, height: 4 }
});

// Remove widget
await sdk.dashboard.removeWidget(widget.id);

Notification Resource

Handles real-time notifications and messaging.

Notification Management

// Get notifications
const notifications = await sdk.notification.getNotifications({
  limit: 50,
  unreadOnly: true
});

// Mark as read
await sdk.notification.markAsRead(['notification-id-1', 'notification-id-2']);

// Mark all as read
await sdk.notification.markAllAsRead();

// Delete notifications
await sdk.notification.delete(['notification-id-1']);

Real-time Events

// Subscribe to notifications
sdk.notification.onNotificationReceived((notification) => {
  console.log('New notification:', notification);
  // Show in UI
});

// Subscribe to specific types
sdk.notification.onNotificationReceived(
  (notification) => {
    if (notification.type === 'mention') {
      // Handle mention notification
    }
  },
  { type: 'mention' }
);

Push Notifications

// Request permission for push notifications
const permission = await sdk.notification.requestPushPermission();

// Subscribe to push notifications
if (permission === 'granted') {
  await sdk.notification.subscribeToPush();
}

// Configure notification preferences
await sdk.notification.updatePreferences({
  push: {
    mentions: true,
    messages: true,
    updates: false
  },
  email: {
    weekly_digest: true,
    important_only: true
  }
});

Error Handling

All resources use consistent error handling:

import { AsterismsError, AsterismsBackendError } from '@asterisms/sdk';

try {
  const result = await sdk.storage.upload(file);
} catch (error) {
  if (error instanceof AsterismsBackendError) {
    // Handle backend errors
    console.error('Backend error:', error.status, error.message);
    if (error.status === 413) {
      console.error('File too large');
    }
  } else if (error instanceof AsterismsError) {
    // Handle SDK errors
    console.error('SDK error:', error.message);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

Resource Configuration

Resources can be configured individually:

const sdk = createAsterismsSDK({
  bundleId: 'your-app',
  rootDomain: 'yourapp.com',
  navigationAdapter: yourAdapter,
  resources: {
    storage: {
      maxFileSize: 100 * 1024 * 1024, // 100MB
      allowedTypes: ['image/*', 'application/pdf'],
      uploadTimeout: 60000
    },
    drive: {
      enableSharing: true,
      defaultPermission: 'read',
      maxShareLinks: 10
    },
    notification: {
      enablePush: true,
      batchSize: 50,
      pollInterval: 30000
    }
  }
});

Next Steps

ON THIS PAGE