Acuity SDK

A comprehensive TypeScript SDK for the Acuity Scheduling API.

Features

• Full TypeScript support - Comprehensive type definitions for all API entities
• Universal runtime - Works in Node.js 18+, browsers, and edge runtimes (Cloudflare Workers, Vercel Edge, etc.)
• Zero dependencies - Uses native fetch API
• Dual format - Ships both ESM and CommonJS builds
• Multiple auth methods - Supports both Basic Auth and OAuth2
• Complete API coverage - All Acuity Scheduling API endpoints

Installation

bun add acuity-js-sdk

npm install acuity-js-sdk

pnpm add acuity-js-sdk

Quick Start

Basic Authentication

import { AcuityClient } from 'acuity-js-sdk';

const client = new AcuityClient({
  auth: {
    userId: 'your-user-id',
    apiKey: 'your-api-key',
  },
});

// List all appointments
const appointments = await client.appointments.list();

OAuth Authentication

import { AcuityClient } from 'acuity-js-sdk';

const client = new AcuityClient({
  auth: {
    accessToken: 'your-oauth-access-token',
  },
});

Usage Examples

Managing Appointments

// List appointments with filters
const appointments = await client.appointments.list({
  minDate: '2024-01-01',
  maxDate: '2024-01-31',
  calendarID: 123,
});

// Get a single appointment
const appointment = await client.appointments.get(12345);

// Create an appointment
const newAppointment = await client.appointments.create({
  appointmentTypeID: 123,
  datetime: '2024-01-15T10:00:00-0500',
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  phone: '555-123-4567',
});

// Update an appointment
const updated = await client.appointments.update(12345, {
  notes: 'Updated notes',
});

// Reschedule an appointment
const rescheduled = await client.appointments.reschedule(12345, {
  datetime: '2024-01-16T14:00:00-0500',
});

// Cancel an appointment
const canceled = await client.appointments.cancel(12345, {
  cancelNote: 'Customer requested cancellation',
});

Checking Availability

// Get available dates for a month
const dates = await client.availability.getDates({
  appointmentTypeID: 123,
  month: '2024-01',
  calendarID: 456, // optional
  timezone: 'America/New_York', // optional
});

// Get available times for a specific date
const times = await client.availability.getTimes({
  appointmentTypeID: 123,
  date: '2024-01-15',
  timezone: 'America/New_York',
});

// Get available classes
const classes = await client.availability.getClasses({
  appointmentTypeID: 123,
  month: '2024-01',
});

Managing Clients

// List clients
const clients = await client.clients.list({
  search: 'john',
});

// Get a client
const clientDetails = await client.clients.get(12345);

// Create a client
const newClient = await client.clients.create({
  firstName: 'Jane',
  lastName: 'Smith',
  email: '[email protected]',
  phone: '555-987-6543',
});

// Update a client
const updatedClient = await client.clients.update(12345, {
  notes: 'VIP customer',
});

Working with Appointment Types

// List all appointment types
const types = await client.appointmentTypes.list();

// Get a specific appointment type
const type = await client.appointmentTypes.get(123);

// List addons for an appointment type
const addons = await client.appointmentTypes.listAddons(123);

Managing Calendars

// List all calendars
const calendars = await client.calendars.list();

// Get a specific calendar
const calendar = await client.calendars.get(123);

Working with Certificates/Packages

// List certificates
const certificates = await client.certificates.list({
  email: '[email protected]',
});

// Check a certificate code
const certificate = await client.certificates.check('ABC123', 456);

// Create a certificate
const newCert = await client.certificates.create({
  email: '[email protected]',
  productID: 789,
});

Managing Labels

// List labels
const labels = await client.labels.list();

// Create a label
const newLabel = await client.labels.create({
  name: 'VIP',
  color: '#FF0000',
});

Managing Blocks (Time Off)

// List blocks
const blocks = await client.blocks.list({
  calendarID: 123,
  minDate: '2024-01-01',
  maxDate: '2024-01-31',
});

// Create a block
const newBlock = await client.blocks.create({
  calendarID: 123,
  start: '2024-01-15T09:00:00-0500',
  end: '2024-01-15T12:00:00-0500',
  notes: 'Morning off',
});

Setting Up Webhooks

// List webhooks
const webhooks = await client.webhooks.list();

// Create a webhook
const webhook = await client.webhooks.create({
  event: 'appointment.scheduled',
  target: 'https://your-server.com/webhooks/acuity',
});

// Delete a webhook
await client.webhooks.delete(123);

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  AcuityClient,
  AcuityError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
} from 'acuity-js-sdk';

try {
  const appointment = await client.appointments.get(99999);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Appointment not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid credentials');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.log('Validation failed:', error.message);
  } else if (error instanceof AcuityError) {
    console.log(`API error: ${error.message} (${error.statusCode})`);
  }
}

Available Error Types

| Error Class | Status Code | Description | |------------|-------------|-------------| | AuthenticationError | 401 | Invalid or missing credentials | | AuthorizationError | 403 | Insufficient permissions | | NotFoundError | 404 | Resource not found | | ValidationError | 400 | Invalid request parameters | | RateLimitError | 429 | Rate limit exceeded | | ServerError | 5xx | Server-side error | | TimeoutError | - | Request timed out | | NetworkError | - | Network connectivity issue |

Configuration Options

const client = new AcuityClient({
  auth: {
    userId: 'your-user-id',
    apiKey: 'your-api-key',
  },
  // Optional: Custom base URL (default: https://acuityscheduling.com/api/v1)
  baseUrl: 'https://acuityscheduling.com/api/v1',
  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 60000,
});

API Reference

Resources

| Resource | Description | |----------|-------------| | client.appointments | Manage appointments | | client.appointmentTypes | Manage appointment types and addons | | client.availability | Check available dates, times, and classes | | client.calendars | Manage calendars | | client.clients | Manage client records | | client.forms | Access intake forms | | client.certificates | Manage certificates/packages | | client.products | Manage products and orders | | client.labels | Manage appointment labels | | client.blocks | Manage time blocks (time off) | | client.webhooks | Manage webhooks |

TypeScript Support

All types are exported from the main package:

import type {
  Appointment,
  AppointmentType,
  Calendar,
  Client,
  AvailableTime,
  CreateAppointmentParams,
} from 'acuity-js-sdk';

Development

Scripts

# Build the SDK
bun run build

# Watch mode for development
bun run dev

# Type checking
bun run typecheck

# Run tests
bun run test

# Run tests in watch mode
bun run test:watch

# Run tests with coverage
bun run test:coverage

# Lint code with oxlint
bun run lint

# Lint and auto-fix
bun run lint:fix

# Format code with oxfmt
bun run format

# Check formatting without writing
bun run format:check

# Clean build artifacts
bun run clean

Testing

This project uses Vitest for testing:

• Unit tests - Test utilities, auth providers, and error classes
• Integration tests - Test HTTP client and resource classes with mocked fetch

bun run test           # Run all tests
bun run test:watch     # Run in watch mode
bun run test:coverage  # Generate coverage report

Code Quality

This project uses Oxc for linting and formatting:

• oxlint - Fast linter (50-100x faster than ESLint)
• oxfmt - Prettier-compatible formatter

Releasing

This project uses Changesets for versioning and releases.

Adding a changeset (when making changes):

bun changeset

Follow the prompts to select the version bump type:

• patch (0.0.X) - Bug fixes, documentation
• minor (0.X.0) - New features (backwards compatible)
• major (X.0.0) - Breaking changes

Release process:

1. Create PR with changes + changeset file
2. Merge to main
3. CI creates a "Version Packages" PR
4. Merge the Version PR → automatically publishes to NPM

Requirements

• Bun 1.0+ or Node.js 18+ (or any environment with native fetch support)
• TypeScript 5.0+ (for type definitions)

License

MIT