skyllful-bolt-api-integration

API integration package for Skyllful Bolt

Installation

npm install skyllful-bolt-api-integration

Usage

This package automatically reads all configuration and parameters from the current URL query string.

import { getLearnersStatistics } from 'skyllful-bolt-api-integration';

// Call the function - it will read all parameters from URL query string
const stats = await getLearnersStatistics();

console.log(stats.list); // Array of learner statistics
console.log(stats.totalItems); // Total number of learners
console.log(stats.hasNext); // Whether there are more pages
console.log(stats.currentPage); // Current page number (0 indexed)
console.log(stats.pageCount); // Total number of pages

Required URL Parameters

Your page URL must include these query parameters:

• apiToken (required): Your bearer authentication token
• trainingCampaignId: Training campaign ID
• trainingProgramId: Training program ID

Optional URL Parameters

• baseURL: API base URL (defaults to 'https://api.skyllful.com')
• hideCompletedLessons: true/false (defaults to false)
• region, market, warehouse, tag, jobRoleId, managerId
• showInactiveLearnersData: true/false (defaults to false)
• dashboardRole
• pageNumber: Page number (defaults to 1)
• pageSize: Results per page (defaults to 10)
• filter: Filter string
• sortingDirection: 'ascending' or 'descending' (defaults to 'ascending')
• sortBy: Sort field (defaults to 'name')

Example URL

https://your-app.com/page?apiToken=your-token&trainingCampaignId=906490e3-4209-4e34-9e49-f711a598f435&trainingProgramId=b804a11b-d343-4e69-f9f8-08d7e2f9e879&pageNumber=1&pageSize=10

Response Object

The getLearnersStatistics() function returns a LearnersStatisticsResponse object with the following structure:

interface LearnersStatisticsResponse {
  list: LearnerStatistics[];      // List of learner statistics
  hasNext: boolean;                // If there can be another page of results
  currentPage: number;             // The current page requested (0 indexed)
  pageCount: number;               // The total number of pages
  totalItems: number;              // The total number of items available
}

LearnerStatistics Object

Each learner in the list array contains:

interface LearnerStatistics {
  id: string;                              // Unique learner ID
  name: string;                            // Learner's full name
  location: string;                        // Learner's location
  managerName: string;                     // Manager's full name
  managerFirstName: string;                // Manager's first name
  managerLastName: string;                 // Manager's last name
  managerId?: string;                      // Manager's unique ID (optional)
  region: string;                          // Geographic region
  role: string;                            // Job role
  avgLessonTime?: number;                  // Average time per lesson (optional)
  readiness?: number;                      // Readiness score (optional)
  lastKnowledgeCheckScore?: number;        // Last knowledge check score (optional)
  knowledgeCheckAttempts?: number;         // Total knowledge check attempts (optional)
  failedKnowledgeCheckAttempts?: number;   // Failed attempts (optional)
  passedKnowledgeCheckAttempts?: number;   // Passed attempts (optional)
  estimatedLessonTimeRemaining?: number;   // Estimated time remaining (optional)
  assignedModules: number;                 // Total assigned modules
  completedModules?: number;               // Completed modules (optional)
  assignedLessons: number;                 // Total assigned lessons
  completedLessons?: number;               // Completed lessons (optional)
  lessonsRemaining?: number;               // Lessons remaining (optional)
  belongsToAnotherReadinessGroup: boolean; // Belongs to another readiness group
  market: string;                          // Market segment
  warehouse: string;                       // Warehouse location
  personNumber?: number;                   // Employee/person number (optional)
  lastInteractionTimestamp?: number;       // Last interaction timestamp (optional)
  dateCompletedTimestamp?: number;         // Completion date timestamp (optional)
  dateAddedTimestamp?: number;             // Date added timestamp (optional)
}

Get Lesson Data

The getLessonData() function fetches all lessons for a training program by retrieving modules and their associated lessons.

Usage

import { getLessonData } from 'skyllful-bolt-api-integration';

// Call the function - it will read all parameters from URL query string
const lessons = await getLessonData();

console.log(lessons); // Array of all lessons with module information

Required URL Parameters

• apiToken (required): Your bearer authentication token
• trainingProgramId (required): Training program ID
• baseURL (optional): API base URL (defaults to 'https://api.skyllful.com')

Example URL

https://your-app.com/page?apiToken=your-token&trainingProgramId=b804a11b-d343-4e69-f9f8-08d7e2f9e879

How It Works

1. Fetches all modules for the training program
2. Iterates through each module to fetch its lessons
3. Enriches each lesson with module information (moduleName, trackId, trackName)
4. Returns a flattened list of all lessons

LessonContract Response

The function returns an array of LessonContract objects:

interface LessonContract {
  id: string;                           // Unique lesson ID
  moduleId: string;                     // Parent module ID
  moduleName: string;                   // Parent module name
  trackId: string;                      // Track/class ID
  trackName: string;                    // Track/class name
  name: string;                         // Lesson name
  status: number | string;              // Lesson status
  createdDateTimestamp: number;         // Created date timestamp
  lastModifiedTimestamp?: number;       // Last modified timestamp (optional)
  description: string;                  // Lesson description
  richTextDescription: string;          // Rich text description
  order: number;                        // Lesson order
  stepCount?: number;                   // Number of steps (optional)
  iconId?: string;                      // Icon ID (optional)
  iconUrl: string;                      // Icon URL
  isFollowed: boolean;                  // Whether lesson is followed
  lessonType: number | string;          // Lesson type
  onlineOnly: boolean;                  // Online only flag
  isApproved: boolean;                  // Approval status
  openThreads: number;                  // Number of open threads
  isProcessing: boolean;                // Processing status
  hasError: boolean;                    // Error status
  latestVersionCreatorType: number | string; // Creator type of latest version
}

Development

Install dependencies:

npm install

Build the package:

npm run build

Run tests:

npm test

License

ISC