Calendar Client

Official TypeScript client for the ModularIoT Calendar API.

Status: Available — npm  | GitHub 

Overview

@microboxlabs/miot-calendar-client provides a typed, zero-dependency client for managing calendars, time windows, slots, slot managers, and bookings through the ModularIoT Calendar API. It uses the native fetch API and works in any JavaScript runtime (browsers, Node.js, Deno, Bun, edge runtimes).

Installation

npm install @microboxlabs/miot-calendar-client

Quick Start

import { createMiotCalendarClient } from "@microboxlabs/miot-calendar-client";
 
const client = createMiotCalendarClient({
  baseUrl: "https://your-api-host.com",
  headers: { Authorization: "Bearer your-token" },
});
 
// Create a calendar
const calendar = await client.calendars.create({
  code: "maintenance",
  name: "Vehicle Maintenance",
});
 
// Add a time window (Mon–Fri, 8 AM – 5 PM)
await client.calendars.createTimeWindow(calendar.id, {
  name: "Business Hours",
  startHour: 8,
  endHour: 17,
  validFrom: "2026-03-01",
  daysOfWeek: "1,2,3,4,5",
});
 
// Generate slots and create a booking
await client.slots.generate({
  calendarId: calendar.id,
  startDate: "2026-03-01",
  endDate: "2026-03-14",
});
 
const { data: slots } = await client.slots.list({
  calendarId: calendar.id,
  available: true,
});
 
const booking = await client.bookings.create({
  calendarId: calendar.id,
  resource: { id: "truck-42", type: "vehicle", label: "Truck 42" },
  slot: { date: slots[0].slotDate, hour: slots[0].slotHour, minutes: slots[0].slotMinutes },
});

Features

Calendars

Create and manage calendars with timezone support. Each calendar groups time windows, slots, and bookings. Optionally assign calendars to one or more groups via the groups field, persist task filters such as origin and destination with filter, and inspect whether a SlotManager has been provisioned with hasSlotManager.

Calendar Groups

Organize calendars into named groups with client.groups. Filter calendar lists by groupCode, and read which groups a calendar belongs to from CalendarResponse.groups.

Time Windows

Define recurring availability windows with hours, days of week, capacity, and UI color tokens. Time windows can also be marked as WINDOW for bookable capacity or BLOCK for non-bookable closures such as holidays, maintenance, or manual downtime.

Slots

Generate slots automatically from time windows, or manage them individually. Filter by availability, date range, and calendar.

Slot Managers

Automate slot generation with client.slotManagers. Each manager keeps slots generated a configurable number of days in advance for a calendar. Trigger runs manually via the API or let an external scheduler (e.g. K8s CronJob) call runAll(). Inspect run history and status per manager.

Bookings

Create bookings for specific slots with resource tracking. Supports user attribution via X-User-Id header.

Error Handling

All API errors throw MiotCalendarApiError with typed error bodies, HTTP status codes, and structured error information.

Configuration

Full API Reference

For complete method documentation, parameter tables, type definitions, and error code reference, see the package README on npm .