@brandcast_app/zoomshift-api-client/README.md

Unofficial TypeScript/JavaScript client for ZoomShift employee scheduling API (reverse-engineered)

# ZoomShift API Client

[![npm version](https://badge.fury.io/js/%40brandcast_app%2Fzoomshift-api-client.svg)](https://badge.fury.io/js/%40brandcast_app%2Fzoomshift-api-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Unofficial TypeScript/JavaScript client for the ZoomShift employee scheduling API.

## ⚠️ Important Disclaimer

**This is an UNOFFICIAL client library.** ZoomShift does not provide a public API, and this library is based on reverse engineering their internal endpoints.

**Use at your own risk:**
- The API may change without notice
- Your account could be suspended for using unofficial clients
- This library is provided AS-IS with no warranties
- Not affiliated with or endorsed by ZoomShift

## Features

- 🔐 Cookie-based session authentication with CSRF token handling
- 📅 Fetch employee shift schedules for date ranges
- 🔍 Filter shifts by employee or location
- 📦 TypeScript support with full type definitions
- 🛡️ Error handling and type safety
- 🐛 Optional debug logging

## Installation

```bash
npm install @brandcast_app/zoomshift-api-client
```

or

```bash
yarn add @brandcast_app/zoomshift-api-client
```

## Quick Start

```typescript
import { ZoomShiftClient } from '@brandcast_app/zoomshift-api-client';

// Create a client instance
const client = new ZoomShiftClient({
  debug: true, // Optional: enable debug logging
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
});

// Authenticate with ZoomShift
const auth = await client.authenticate(
  'your@email.com',
  'your-password',
  '58369' // Your schedule ID (found in ZoomShift URL)
);

console.log('Authenticated:', auth.authenticated);

// Get shifts for a date range
const shifts = await client.getShifts({
  startDate: '2025-10-10',
  endDate: '2025-10-17',
});

console.log(`Found ${shifts.length} shifts:`);

for (const shift of shifts) {
  console.log(`${shift.employeeName} - ${shift.role}`);
  console.log(`  ${shift.startTime} to ${shift.endTime}`);
  console.log(`  Duration: ${shift.duration} hours`);
}
```

## API Reference

### Constructor

#### `new ZoomShiftClient(options?)`

Create a new ZoomShift API client.

**Parameters:**
- `options` (optional) - Configuration options
  - `debug?: boolean` - Enable debug logging (default: false)
  - `timeout?: number` - Request timeout in milliseconds (default: 30000)
  - `userAgent?: string` - Custom user agent string

```typescript
const client = new ZoomShiftClient({
  debug: true,
  timeout: 30000,
});
```

### Methods

#### `authenticate(email, password, scheduleId): Promise<ZoomShiftAuthResponse>`

Authenticate with ZoomShift using email, password, and schedule ID.

**Parameters:**
- `email: string` - Your ZoomShift account email
- `password: string` - Your ZoomShift account password
- `scheduleId: string` - Your schedule ID (found in ZoomShift URL)

**Returns:** `Promise<ZoomShiftAuthResponse>`
```typescript
{
  authenticated: boolean;
  scheduleId: string;
  userName: string;
}
```

**Example:**
```typescript
const auth = await client.authenticate(
  'manager@example.com',
  'mypassword',
  '58369'
);
```

**Finding Your Schedule ID:**
Your schedule ID is in the ZoomShift URL:
```
https://app.zoomshift.com/58369/dashboard
                            ^^^^^ This is your schedule ID
```

#### `getShifts(request): Promise<ZoomShiftShift[]>`

Get employee shifts for a date range with optional filters.

**Parameters:**
- `request: GetShiftsRequest`
  - `startDate: string` - Start date (YYYY-MM-DD format)
  - `endDate: string` - End date (YYYY-MM-DD format)
  - `employeeId?: string` - (Optional) Filter by employee ID
  - `location?: string` - (Optional) Filter by location

**Returns:** `Promise<ZoomShiftShift[]>`

**Example:**
```typescript
// Get all shifts for next week
const shifts = await client.getShifts({
  startDate: '2025-10-10',
  endDate: '2025-10-17',
});

// Get shifts for specific employee
const employeeShifts = await client.getShifts({
  startDate: '2025-10-10',
  endDate: '2025-10-17',
  employeeId: '12345',
});

// Get shifts for specific location
const storeShifts = await client.getShifts({
  startDate: '2025-10-10',
  endDate: '2025-10-17',
  location: 'Main Store',
});
```

#### `isAuthenticated(): boolean`

Check if the client is currently authenticated.

```typescript
if (client.isAuthenticated()) {
  console.log('Client is ready to make API calls');
}
```

#### `getScheduleId(): string | null`

Get the current schedule ID.

```typescript
const scheduleId = client.getScheduleId();
console.log('Using schedule:', scheduleId);
```

## Type Definitions

### ZoomShiftShift

```typescript
interface ZoomShiftShift {
  id: string;
  employeeName: string;
  employeeId: string;
  role: string;
  startTime: string;        // ISO 8601 format
  endTime: string;          // ISO 8601 format
  duration: number;         // hours
  breakDuration?: number;   // hours
  location?: string;
  notes?: string;
  status: 'scheduled' | 'in_progress' | 'completed' | 'cancelled';
}
```

### ZoomShiftAuthResponse

```typescript
interface ZoomShiftAuthResponse {
  authenticated: boolean;
  scheduleId: string;
  userName: string;
}
```

### GetShiftsRequest

```typescript
interface GetShiftsRequest {
  startDate: string;  // YYYY-MM-DD
  endDate: string;    // YYYY-MM-DD
  employeeId?: string;
  location?: string;
}
```

### ZoomShiftError

```typescript
interface ZoomShiftError {
  code: string;
  message: string;
  details?: unknown;
}
```

## Error Handling

The client throws `ZoomShiftError` objects with descriptive error codes:

```typescript
try {
  await client.authenticate('user@example.com', 'wrong-password', '58369');
} catch (error) {
  const zsError = error as ZoomShiftError;
  console.error('Error code:', zsError.code);
  console.error('Error message:', zsError.message);

  // Handle specific errors
  switch (zsError.code) {
    case 'AUTH_FAILED':
      console.error('Invalid credentials');
      break;
    case 'SESSION_EXPIRED':
      console.error('Please re-authenticate');
      break;
    default:
      console.error('Unknown error');
  }
}
```

**Common Error Codes:**
- `CSRF_TOKEN_MISSING` - Failed to extract CSRF token
- `AUTH_FAILED` - Invalid credentials
- `NOT_AUTHENTICATED` - Must call authenticate() first
- `SESSION_EXPIRED` - Session expired, need to re-authenticate
- `FETCH_FAILED` - Failed to fetch shifts
- `AUTH_REQUEST_FAILED` - Network error during authentication
- `AUTH_UNKNOWN_ERROR` - Unknown authentication error

## Complete Example

```typescript
import { ZoomShiftClient } from '@brandcast_app/zoomshift-api-client';

async function main() {
  // Create client with debug logging
  const client = new ZoomShiftClient({ debug: true });

  try {
    // Authenticate
    console.log('Authenticating...');
    const auth = await client.authenticate(
      'manager@example.com',
      'mypassword',
      '58369'
    );
    console.log('✓ Authenticated successfully');

    // Get shifts for next 7 days
    const today = new Date();
    const nextWeek = new Date(today);
    nextWeek.setDate(nextWeek.getDate() + 7);

    const formatDate = (date: Date) => date.toISOString().split('T')[0];

    console.log('Fetching shifts...');
    const shifts = await client.getShifts({
      startDate: formatDate(today),
      endDate: formatDate(nextWeek),
    });

    console.log(`✓ Found ${shifts.length} shifts`);

    // Display shifts grouped by day
    const shiftsByDay = new Map<string, typeof shifts>();

    for (const shift of shifts) {
      const day = shift.startTime.split('T')[0];
      if (!shiftsByDay.has(day)) {
        shiftsByDay.set(day, []);
      }
      shiftsByDay.get(day)!.push(shift);
    }

    for (const [day, dayShifts] of shiftsByDay) {
      console.log(`\n${day}:`);
      for (const shift of dayShifts) {
        const start = new Date(shift.startTime).toLocaleTimeString();
        const end = new Date(shift.endTime).toLocaleTimeString();
        console.log(`  ${shift.employeeName} (${shift.role})`);
        console.log(`    ${start} - ${end} (${shift.duration}h)`);
      }
    }

  } catch (error) {
    console.error('Error:', error);
  }
}

main();
```

## Development

### Building

```bash
npm install
npm run build
```

### Testing

```bash
npm test
```

### Watch Mode

```bash
npm run dev
```

## Credits

Inspired by reverse engineering work similar to the [py-cozi](https://github.com/Wetzel402/py-cozi) Python library.

## Legal

This is an unofficial library and is not affiliated with, endorsed by, or connected to ZoomShift. Use at your own risk. The developers of this library are not responsible for any issues that may arise from its use.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- 🐛 [Report Issues](https://github.com/jduncan-rva/zoomshift-api-client/issues)

## Changelog

### 0.1.0 (Initial Release)

- ✨ Initial implementation
- 🔐 Cookie-based authentication with CSRF token handling
- 📅 Fetch shifts for date ranges
- 🔍 Filter by employee and location
- 📦 Full TypeScript support
- 🐛 Debug logging option

---

**Status**: 🚧 Pre-alpha - API under active development