@brandcast_app/zoomshift-api-client

ZoomShift API Client

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

npm install @brandcast_app/zoomshift-api-client

or

yarn add @brandcast_app/zoomshift-api-client

Quick Start

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(
  '[e-mail]',
  '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

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>

{
  authenticated: boolean;
  scheduleId: string;
  userName: string;
}

Example:

const auth = await client.authenticate(
  '[e-mail]',
  '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:

// 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.

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

getScheduleId(): string | null

Get the current schedule ID.

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

Type Definitions

ZoomShiftShift

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

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

GetShiftsRequest

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

ZoomShiftError

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

Error Handling

The client throws ZoomShiftError objects with descriptive error codes:

try {
  await client.authenticate('[e-mail]', '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

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(
      '[e-mail]',
      '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

npm install
npm run build

Testing

npm test

Watch Mode

npm run dev

Credits

Inspired by reverse engineering work similar to the 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 file for details.

Contributing

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

Support

• 🐛 Report 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