insightful-js

A modern TypeScript SDK for the Insightful API - employee monitoring, time tracking, and productivity analytics.

Features

• Type-safe: Full TypeScript support with strict typing
• Modern: ESM-first with CJS fallback, Node 18+, native fetch
• Developer-friendly: Intuitive API, comprehensive API documentation
• Production-ready: Rate limiting, automatic retries with backoff
• Well-tested: Comprehensive unit tests

Documentation

Generate the API documentation locally:

pnpm docs

Then open docs/index.html in your browser to view the complete API reference with:

• All endpoint methods with examples
• Type definitions for request/response objects
• Error handling guides
• Pagination utilities

Installation

npm install insightful-js
# or
pnpm add insightful-js
# or
yarn add insightful-js

Quick Start

import { InsightfulClient } from 'insightful-js';

const client = new InsightfulClient({
  apiToken: process.env.INSIGHTFUL_API_TOKEN!
});

// Get all employees
const employees = await client.employees.getEmployees();

// Get employee activity
const activity = await client.employees.getEmployeeActivities('emp-123', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

// Stream all timesheets (handles pagination automatically)
import { fetchAll } from 'insightful-js';

for await (const timesheet of fetchAll((opts) => client.timesheets.getTimesheets(opts))) {
  console.log(timesheet);
}

Configuration

const client = new InsightfulClient({
  // Required
  apiToken: 'your-api-token',

  // Optional
  baseUrl: 'https://api.insightful.io', // Default API base URL
  timeout: 30000,                        // Request timeout in ms
  maxRetries: 3,                         // Max retry attempts
  rateLimitPerMinute: 200,               // Rate limit
  debug: false,                          // Enable debug logging
  logger: customLogger,                  // Custom logger implementation
});

API Reference

Employees

// List employees
const { data, pagination } = await client.employees.getEmployees({
  status: 'active',
  teamId: 'team-123',
  limit: 50
});

// Get single employee
const employee = await client.employees.getEmployee('emp-123');

// Create employee
const newEmployee = await client.employees.createEmployee({
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe'
});

// Update employee
const updated = await client.employees.updateEmployee('emp-123', {
  firstName: 'Jane'
});

// Delete employee
await client.employees.deleteEmployee('emp-123');

// Get employee activities
const activities = await client.employees.getEmployeeActivities('emp-123', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

// Get employee productivity
const productivity = await client.employees.getEmployeeProductivity('emp-123');

// Get employee screenshots
const screenshots = await client.employees.getEmployeeScreenshots('emp-123');

Teams

// List teams
const teams = await client.teams.getTeams();

// Get team
const team = await client.teams.getTeam('team-123');

// Create team
const newTeam = await client.teams.createTeam({
  name: 'Engineering',
  description: 'Engineering team'
});

// Add/remove team members
await client.teams.addTeamMember('team-123', 'emp-456', 'member');
await client.teams.removeTeamMember('team-123', 'emp-456');

// Get team productivity
const teamProductivity = await client.teams.getTeamProductivity('team-123');

Projects

// List projects
const projects = await client.projects.getProjects({ status: 'active' });

// Create project
const project = await client.projects.createProject({
  name: 'Website Redesign',
  clientName: 'Acme Corp'
});

// Manage tasks
const tasks = await client.projects.getTasks('proj-123');
const task = await client.projects.createTask('proj-123', {
  name: 'Design mockups',
  priority: 'high'
});

// Get time entries
const timeEntries = await client.projects.getProjectTimeEntries('proj-123', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Timesheets & Attendance

// Get timesheets
const timesheets = await client.timesheets.getTimesheets({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  status: 'approved'
});

// Get attendance
const attendance = await client.timesheets.getAttendance();
const summary = await client.timesheets.getAttendanceSummary({
  teamId: 'team-123'
});

// Manual time entries
const entry = await client.timesheets.createManualTimeEntry({
  employeeId: 'emp-123',
  date: '2024-01-15',
  startTime: '09:00',
  endTime: '17:00'
});

// Scheduled shifts
const shift = await client.timesheets.createScheduledShift({
  employeeId: 'emp-123',
  date: '2024-01-15',
  startTime: '09:00',
  endTime: '17:00'
});

Activity & Productivity

// Get activity logs (cursor-based pagination)
const logs = await client.activity.getActivityLogs({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 100
});

// Get productivity reports
const report = await client.activity.getProductivityReport({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'day'
});

// Real-time activity
const realtime = await client.activity.getRealTimeActivity();
const activeCount = await client.activity.getActiveEmployees();

// Manage categories
const appCategories = await client.activity.getAppCategories();
await client.activity.updateAppCategory('app-123', {
  category: 'Development',
  categoryType: 'productive'
});

Error Handling

import {
  InsightfulApiError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError
} from 'insightful-js';

try {
  await client.employees.getEmployees();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API token');
  } else if (error instanceof NotFoundError) {
    console.log('Resource not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation errors:', error.fieldErrors);
  } else if (error instanceof InsightfulApiError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  }
}

Pagination Helpers

import { fetchAll, collectAll } from 'insightful-js';

// Stream items one by one (memory efficient)
for await (const employee of fetchAll((opts) => client.employees.getEmployees(opts))) {
  console.log(employee);
}

// Collect all items into array
const allEmployees = await collectAll((opts) => client.employees.getEmployees(opts));

Requirements

• Node.js 18+
• TypeScript 5.x (for TypeScript users)

Development

Setup

pnpm install

Pre-push Hook

This repo includes a pre-push hook that runs all CI checks before pushing. To install it:

cp .githooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Running Checks Locally

Before pushing, ensure all checks pass:

pnpm lint        # Check code style
pnpm lint:fix    # Auto-fix lint issues
pnpm typecheck   # TypeScript type checking
pnpm build       # Build the package
pnpm test:run    # Run tests

Or run all checks at once:

pnpm lint && pnpm typecheck && pnpm build && pnpm test:run

License

MIT