@onlive.ai/calendar v0.0.9

Onlive Calendar Client

An npm client that provides a simple interface to interact with a calendar service. Includes strongly typed methods that make HTTP requests to service endpoints using the Fetch API.

Features

• ✅ Native TypeScript: Fully typed with TypeScript
• ✅ Zod Validation: Runtime schema validation
• ✅ ESM/CJS Support: Compatible with ES modules and CommonJS
• ✅ Modern API: Uses native Fetch API
• ✅ Lightweight: No heavy external dependencies

Installation

Using pnpm (recommended)

pnpm add @onlive.ai/calendar
# or
npm install @onlive.ai/calendar

Package Structure

@onlive.ai/calendar/
├── index.js                 # Main entry point (ESM)
├── index.cjs               # CommonJS entry point
├── index.d.ts              # Main TypeScript types
├── client/
│   ├── client.service.js   # Client implementation (ESM)
│   ├── client.service.cjs  # Client implementation (CJS)
│   ├── client.service.d.ts # Service types
│   ├── client.types.js     # Types and schemas (ESM)
│   ├── client.types.cjs    # Types and schemas (CJS)
│   └── client.types.d.ts   # Type definitions
└── package.json

Available Exports

• Main entry: @onlive.ai/calendar - Exports CalendarClient and all types
• Submodules: @onlive.ai/calendar/client/* - Direct access to client files

Basic Usage

Import and Initialization

import { CalendarClient } from "@onlive.ai/calendar";
import type { ClientOptions } from "@onlive.ai/calendar";

const clientOptions: ClientOptions = {
  baseUrl: "https://api.example.com",
  organizationId: "ORGANIZATION_UUID",
};

const calendarClient = new CalendarClient(clientOptions);

Specific imports from submodules

import { CalendarClient } from "@onlive.ai/calendar/client/client.service";
import type { ClientOptions } from "@onlive.ai/calendar/client/client.types";

API Documentation

The main CalendarClient class is implemented in client.service.ts and uses the types defined in client.types.ts.

Class: CalendarClient

Constructor

Signature:

constructor(options: ClientOptions)

Parameters:

• options: Client configuration. Must comply with the ClientOptions type defined in client.types.ts.
  • baseUrl (string): The base endpoint URL, must be a valid URL.
  • organizationId (string): The unique organization UUID.

The constructor validates the provided options using a Zod schema.

Private Method: request

Signature:

private async request<T>(path: string, options?: RequestInit): Promise<T>

Purpose:

• This utility method sends an HTTP request to the service and returns the response as parsed JSON of generic type T.

Parameters:

• path: The endpoint path that is added to the base URL.
• options: Fetch API configuration options (RequestInit). Defaults to an empty object.

Response:

• Returns a promise that resolves to a parsed JSON object of type T.

Error Handling:

• Throws an error if the HTTP response status is not OK.

Public Method: getAvailability

Signature:

public async getAvailability(options: GetAvailabilityOptions): Promise<AvailabilityResponse>

Purpose:

• Gets the availability of a service.

Parameters:

• options: The options must adhere to the GetAvailabilityOptions type from client.types.ts:
  • serviceId (string - UUID): Required ID for the service.
  • startDate (string - ISO datetime, optional): Start date for availability search.
  • endDate (string - non-empty, optional): End date for availability search.
  • calendarFilters (Record<string, any>, optional): Filter criteria for the calendar.
  • relatedCalendarFilters (Record<string, any>, optional): Filter criteria for related calendars.

Response:

• Returns a promise that resolves to an AvailabilityResponse, which is an array of objects. Each object has:
  • availabilityTime (string - ISO datetime): Availability time.
  • owners (string[]): Array of owner UUIDs.
  • assets (string[]): Array of asset UUIDs.

Complete Usage Example

import { CalendarClient } from "@onlive.ai/calendar";
import type { GetAvailabilityOptions } from "@onlive.ai/calendar";

// Configure the client
const calendarClient = new CalendarClient({
  baseUrl: "https://api.example.com",
  organizationId: "ORGANIZATION-UUID",
});

// Options for querying availability
const availabilityOptions: GetAvailabilityOptions = {
  serviceId: "SERVICE-UUID",
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-01-02T00:00:00Z",
};

// Perform the query
try {
  const response = await calendarClient.getAvailability(availabilityOptions);
  console.log("Availability Response:", response);
} catch (error) {
  console.error("Error getting availability:", error);
}

Files and Code Structure

TypeScript Source Files

• client.types.ts: Contains Zod schemas and TypeScript types for:
  • ClientOptions: Client configuration
  • GetAvailabilityOptions: Options for querying availability
  • AvailabilityResponse: Availability response
• client.service.ts: Contains the implementation of the CalendarClient class and its methods
• index.ts: Main entry point that exports classes and types

Compiled Files

The package is distributed with compiled files for both ESM and CommonJS:

• .js: ES Modules (ECMAScript Modules)
• .cjs: CommonJS modules
• .d.ts: TypeScript type definitions for ESM
• .d.cts: TypeScript type definitions for CommonJS

This structure allows for easy validation and strict type checking for both client configuration and API request/response data.

Compatibility

• Node.js: >= 18.0.0
• TypeScript: >= 4.5.0
• Browsers: Compatible with native Fetch API

Development

Available Scripts

# Build the package
pnpm run build:package

# Run tests
pnpm run test

# Run tests with coverage
pnpm run test:coverage

# Clean compiled files
pnpm run clean