@markwharton/wol

WhosOnLocation API client for staff presence, visitor management, and location data.

Install

npm install @markwharton/wol

Quick Start

import { WOLClient } from '@markwharton/wol';

const client = new WOLClient({
  apiKey: 'your-api-key',
  cache: {},   // enable caching with defaults
  retry: {},   // enable retry with defaults
});

// Validate credentials
const validation = await client.validateApiKey();
if (!validation.ok) throw new Error(validation.error);

// Get onsite staff
const result = await client.getStaff({ query: 'onsite_status:onsite' });
if (result.ok) {
  for (const staff of result.data!) {
    console.log(staff.name, staff.onsiteStatus);
  }
}

Configuration

| Field | Type | Default | Description | |-------|------|---------|-------------| | apiKey | string | required | API key for APIKEY authentication | | baseUrl | string | WOL API URL | Override API base URL | | onRequest | callback | - | Debug callback for each API request | | cache | WOLCacheConfig | disabled | Enable caching with optional TTL overrides | | cacheInstance | Cache | - | Custom cache backend (e.g., LayeredCache) | | retry | RetryConfig | disabled | Enable retry for 429/503 with exponential backoff | | rateLimitPerSecond | number | 1.67 | Client-side rate limiting (~100/min). Set 0 to disable | | timeZone | string | - | Time zone for API requests (e.g., 'Pacific/Auckland') |

Cache TTLs

Pass cache: {} to enable with defaults:

| Key | Default | Description | |-----|---------|-------------| | staffTtl | 1 min | Staff members | | visitorEventsTtl | 1 min | Visitor events | | visitorGroupsTtl | 5 min | Visitor groups | | locationsTtl | 5 min | Locations |

Methods

Staff

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | validateApiKey | - | Result<void> | Validate API key | | getStaff | options? | Result<WOLStaff[]> | Get staff members (cached) | | getStaffMember | staffId: number | Result<WOLStaff> | Get single staff member (cached) |

Staff options: query? — WOL query filter (e.g., 'onsite_status:onsite')

Visitors

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | getVisitorEvents | options? | Result<WOLVisitorEvent[]> | Get visitor events (cached) | | getVisitorGroups | - | Result<WOLVisitorGroup[]> | Get visitor groups (cached) |

Visitor event options: signedInAfter? — ISO timestamp filter

Locations

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | getLocations | - | Result<WOLLocation[]> | Get all locations (cached) | | getLocation | locationId: number | Result<WOLLocation> | Get single location (cached) |

Cache Management

| Method | Description | |--------|-------------| | clearCache() | Clear all cached data | | invalidateStaffCache() | Invalidate staff data | | invalidateVisitorEventCache() | Invalidate visitor events | | invalidateVisitorGroupCache() | Invalidate visitor groups | | invalidateLocationCache() | Invalidate locations |

License

MIT