JSPM – @bigdigital/kiosk-content-sdk@0.4.63

Package Exports

@bigdigital/kiosk-content-sdk
@bigdigital/kiosk-content-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@bigdigital/kiosk-content-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

npm install @bigdigital/kiosk-content-sdk


## Features

- 🔄 Real-time kiosk connection monitoring with automatic reconnection
- 📡 WebSocket-based status updates with heartbeat mechanism
- 💾 Offline-first content delivery with IndexedDB caching
- 📐 Dynamic template management with type-safe content
- 🔒 Secure Firebase authentication integration
- 🚀 React hooks for seamless integration
- 🌐 Network resilience with automatic retry

## Quick Start

```typescript
import { kioskSDK, useKioskContent } from '@bigdigital/kiosk-content-sdk';

// Initialize kiosk monitoring with proper error handling
const connection = kioskSDK.initializeMonitoring({
  url: 'ws://your-server.com/api/ws/kiosk',
  onConnectionUpdate: (isConnected) => {
    console.log(`Connection status: ${isConnected ? 'Online' : 'Offline'}`);
  }
});

// Handle connection events
connection.on('error', (error) => {
  console.error('Connection error:', error);
});

connection.on('reconnecting', (attempt) => {
  console.log(`Attempting to reconnect (${attempt})`);
});

React Integration Examples

Basic Content Display

import { useKioskContent } from '@bigdigital/kiosk-content-sdk';
import type { Content } from '@bigdigital/kiosk-content-sdk';

function ContentDisplay() {
  const { 
    content, 
    isLoading, 
    error, 
    isOnline 
  } = useKioskContent<Content>({
    projectId: 'your-firebase-project',
    offlineSupport: true,
    cacheStrategy: 'network-first'
  });

  if (isLoading) {
    return <LoadingSpinner />;
  }

  if (error) {
    return <ErrorDisplay message={error.message} />;
  }

  return (
    <div>
      <OfflineIndicator isOnline={isOnline} />
      <ContentRenderer content={content} />
    </div>
  );
}

Template Management

import { 
  useTemplate, 
  useTemplateContent,
  type Template,
  type TemplateContent 
} from '@bigdigital/kiosk-content-sdk';

function TemplateDisplay() {
  const { template, isLoading: templateLoading } = useTemplate<Template>('template-id');
  const { content, isLoading: contentLoading } = useTemplateContent<TemplateContent>('content-id');

  if (templateLoading || contentLoading) {
    return <LoadingSpinner />;
  }

  return (
    <div>
      <h1>{template.name}</h1>
      <TemplateRenderer 
        template={template} 
        content={content}
        fallback={<OfflineContent content={content} />} 
      />
    </div>
  );
}

Advanced Connection Management

import { KioskConnection } from '@bigdigital/kiosk-content-sdk';

const connection = new KioskConnection({
  url: 'ws://your-server.com/api/ws/kiosk',
  kioskId: 'kiosk-123',
  reconnectOptions: {
    maxAttempts: 5,
    interval: 5000,
    backoff: 'exponential'
  }
});

// Listen for all connection events
connection.on('connected', () => {
  console.log('Kiosk connected successfully');
});

connection.on('disconnected', () => {
  console.log('Kiosk disconnected, attempting reconnection...');
});

connection.on('error', (error) => {
  console.error('Connection error:', error);
});

connection.on('maxRetriesExceeded', () => {
  console.warn('Maximum reconnection attempts reached');
});

// Monitor heartbeat
connection.on('ping', () => {
  console.log('Heartbeat received');
});

// Custom status updates
connection.on('status', (status) => {
  console.log('Kiosk status:', status);
});

Offline Support with Sync Control

import { useOfflineContent, type SyncOptions } from '@bigdigital/kiosk-content-sdk';

const syncOptions: SyncOptions = {
  syncOnReconnect: true,
  backgroundSync: true,
  retryStrategy: {
    maxAttempts: 3,
    backoff: 'exponential',
    initialDelay: 1000
  }
};

function OfflineAwareContent() {
  const { 
    content, 
    sync, 
    lastSyncTime,
    syncStatus 
  } = useOfflineContent({
    cacheStrategy: 'offline-first',
    syncOptions,
    onSyncComplete: (result) => {
      console.log('Sync completed:', result);
    },
    onSyncError: (error) => {
      console.error('Sync failed:', error);
    }
  });

  return (
    <div>
      <SyncStatus 
        status={syncStatus} 
        lastSync={lastSyncTime} 
      />
      <button onClick={sync}>
        Manual Sync
      </button>
      <ContentList items={content} />
    </div>
  );
}

Error Handling

The SDK provides comprehensive error handling:

import { 
  KioskConnection, 
  ConnectionError,
  type ErrorHandler 
} from '@bigdigital/kiosk-content-sdk';

const errorHandler: ErrorHandler = {
  onConnectionError: (error) => {
    if (error instanceof ConnectionError) {
      console.error('Connection failed:', error.message);
      // Implement recovery logic
    }
  },
  onSyncError: (error) => {
    console.error('Content sync failed:', error);
    // Handle offline fallback
  },
  onTemplateError: (error) => {
    console.error('Template processing failed:', error);
    // Show fallback template
  }
};

const connection = new KioskConnection({
  url: 'ws://your-server.com/api/ws/kiosk',
  kioskId: 'kiosk-123',
  errorHandler
});

API Reference

KioskSDK

Main SDK instance for managing kiosk connections:

const kioskSDK = new KioskSDK({
  kioskId: string;
  reconnectInterval?: number;
  maxReconnectAttempts?: number;
  heartbeatInterval?: number;
  errorHandler?: ErrorHandler;
});

KioskConnection

Handles individual kiosk WebSocket connections:

interface KioskConnectionOptions {
  url: string;
  kioskId: string;
  reconnectInterval?: number;
  maxReconnectAttempts?: number;
  onConnectionUpdate?: (isConnected: boolean) => void;
  errorHandler?: ErrorHandler;
}

Content Types

export interface Content {
  id: string;
  type: string;
  data: Record<string, any>;
  metadata?: {
    createdAt: string;
    updatedAt: string;
    version: number;
  };
}

export interface Template {
  id: string;
  name: string;
  version: string;
  fields: Field[];
  layout: Layout;
}

export interface SyncOptions {
  syncOnReconnect?: boolean;
  backgroundSync?: boolean;
  retryStrategy?: RetryStrategy;
}

// ... more type definitions available in the SDK

Testing

The SDK includes a comprehensive test suite and mock implementations for testing:

import { MockKioskConnection } from '@bigdigital/kiosk-content-sdk/testing';

// Create a mock connection for testing
const mockConnection = new MockKioskConnection({
  simulateLatency: true,
  latencyMs: 100,
  mockResponses: {
    'content-1': { /* mock content */ },
    'template-1': { /* mock template */ }
  }
});

// Test your components
test('handles connection events', async () => {
  mockConnection.simulateConnect();
  // Assert connection handling
  mockConnection.simulateDisconnect();
  // Assert disconnection handling
});