npm package: @markwharton/wol
Description: WhosOnLocation (WOL) API client
Author: Mark Wharton
Latest version: 1.0.1

# @markwharton/wol

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

## Install

```bash
npm install @markwharton/wol
```

## Quick Start

```typescript
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