API Client Library

pnpm install @repo/webkasa-api-client
# or
pnpm add @repo/webkasa-api-client
# or
pnpm add @repo/webkasa-api-client

// List events with filters
const events = await client.events.list({
  status: 'published',
  upcoming: true,
  limit: 20,
});

// Get upcoming events (shorthand)
const upcoming = await client.events.getUpcoming(10);

// Get a single event
const event = await client.events.get('evt_abc123');

// Create an event
const newEvent = await client.events.create({
  title: 'Monthly Meditation',
  start_date: '2024-02-15',
  start_time: '19:00',
  end_time: '21:00',
  timezone: 'America/Los_Angeles',
  location: 'Community Center',
  slots: 30,
  status: 'published',
});

// Update an event
const updated = await client.events.update('evt_abc123', {
  slots: 50,
});

// Delete an event
await client.events.delete('evt_abc123');

// List bookings with filters
const bookings = await client.bookings.list({
  status: 'CONFIRMED',
  upcoming: true,
});

// Get upcoming bookings (shorthand)
const upcoming = await client.bookings.getUpcoming(10);

// Get a single booking
const booking = await client.bookings.get('bk_abc123');

// Create a booking
const newBooking = await client.bookings.create({
  schedule_id: 'sch_xxx',
  event_type_id: 'evt_xxx',
  start_time: '2024-02-15T10:00:00Z',
  end_time: '2024-02-15T11:00:00Z',
  attendee: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
  },
});

// Confirm a booking
await client.bookings.confirm('bk_abc123');

// Complete a booking
await client.bookings.complete('bk_abc123');

// Cancel a booking
await client.bookings.cancel('bk_abc123');

// List posts with filters
const posts = await client.posts.list({
  site_id: '1e22232e-0461-477b-9097-158b262aee0d',
  status: 'published',
  category: 'wellness',
  featured: true,
});

// Get published posts (shorthand)
const published = await client.posts.getPublished({
  site_id: '1e22232e-0461-477b-9097-158b262aee0d',
  limit: 10,
});

// Resolve a post slug within one site
const post = await client.posts.get('getting-started-meditation', {
  siteId: '1e22232e-0461-477b-9097-158b262aee0d',
});

// Create a post
const newPost = await client.posts.create({
  title: 'Getting Started with Meditation',
  slug: 'getting-started-meditation',
  site_id: '1e22232e-0461-477b-9097-158b262aee0d',
  author_name: 'Mia',
  author_avatar: 'https://example.com/mia.jpg',
  excerpt: 'A beginner\'s guide to meditation',
  status: 'draft',
});

// Update a post
const updated = await client.posts.update('post_abc123', {
  status: 'published',
});

// Read the current organization snapshot
const context = await client.agent.getContext();

// Drain incremental notification pages
const since = await loadNotificationCheckpoint();
let cursor: string | undefined;
let checkpointAt: string | undefined;
do {
  const page = await client.agent.listNotifications({
    since,
    cursor,
    limit: 20,
  });

  for (const notification of page.data) {
    // Back this with durable storage keyed by notification.id. The replay
    // overlap crosses polling runs, so an in-memory Set is not sufficient.
    await processNotificationOnce(notification.id, notification);
  }

  cursor = page.meta?.next_cursor;
  checkpointAt = page.meta?.checkpoint_at ?? checkpointAt;
} while (cursor);

// At-least-once delivery replays a short overlap; advance only after every
// page succeeds and deduplicate replayed notifications by ID.
if (checkpointAt) await saveNotificationCheckpoint(checkpointAt);

// Write an update using the source platform's message ID
const result = await client.agent.createNotification({
  title: 'Telegram workflow update',
  message: 'The scheduled workflow completed.',
  source: 'telegram',
  external_id: 'telegram-message-42',
});

console.log(result.data.created ? 'Created' : 'Already delivered');

import { WebKasaError, RateLimitError, ValidationError } from '@repo/webkasa-api-client';

try {
  await client.bookings.create({
    schedule_id: 'sch_xxx',
    start_time: '2024-02-15T10:00:00Z',
    end_time: '2024-02-15T11:00:00Z',
    attendee: {
      name: 'John Doe',
      email: 'john@example.com',
    },
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    // Show validation errors to user
    console.log('Validation errors:', error.errors);
  } else if (error instanceof WebKasaError) {
    // Handle other API errors
    console.log(`API error: ${error.message}`);
  } else {
    // Handle network errors
    throw error;
  }
}

import type {
  Event,
  Booking,
  Post,
  CreateBookingInput,
  BookingStatus,
} from '@repo/webkasa-api-client';

// All responses are fully typed
const events: Event[] = await client.events.list();

// Input types help catch errors at compile time
const input: CreateBookingInput = {
  schedule_id: 'sch_xxx',
  start_time: '2024-02-15T10:00:00Z',
  end_time: '2024-02-15T11:00:00Z',
  attendee: {
    name: 'John Doe',
    email: 'john@example.com',
  },
};

const booking: Booking = await client.bookings.create(input);

const client = createWebKasaClient({
  // Required
  baseUrl: 'https://api.webkasa.app',
  apiKey: process.env.WEBKASA_API_KEY!,

  // Optional
  timeout: 30000,  // Request timeout in ms (default: 30000)
  retries: 3,      // Number of retries for failed requests (default: 3)

  // Custom fetch implementation (for testing or custom behavior)
  fetch: customFetch,
});