hykecal-client

A typed client for HykeCal's booking API — list event types, fetch available slots, create and cancel bookings, and manage availability, from any Node.js or browser project. No UI included; this just saves you from hand-rolling fetch calls against the raw REST API.

Package: https://www.npmjs.com/package/hykecal-client Repo: https://github.com/hykelauncher/hykecal-client HykeCal itself: https://github.com/hykelauncher/hykecal

Install

npm install hykecal-client

Public usage (no API key — safe in browser code)

import { createHykeCalClient } from "hykecal-client";

const hykecal = createHykeCalClient({ baseUrl: "https://hykecal.vercel.app" });

const eventTypes = await hykecal.listEventTypes();

const slots = await hykecal.getSlots(
  "15-min-call",
  new Date(),
  new Date(Date.now() + 14 * 24 * 60 * 60 * 1000),
);

const { id, cancelUrl } = await hykecal.createBooking({
  eventTypeSlug: "15-min-call",
  start: slots[0],
  name: "Ada Lovelace",
  email: "[email protected]",
  notes: "Looking forward to it!",
});

await hykecal.cancelBooking(id, tokenFromCancelUrl);

Admin usage (requires an API key — server-to-server only)

Never put apiKey in code that ships to a browser — it's the same credential that unlocks HykeCal's own dashboard.

const hykecal = createHykeCalClient({
  baseUrl: "https://hykecal.vercel.app",
  apiKey: process.env.HYKECAL_API_KEY,
});

await hykecal.admin.createEventType({
  slug: "1-hour-consult",
  name: "1 hour consult",
  durationMinutes: 60,
  bufferBeforeMinutes: 10,
  bufferAfterMinutes: 10,
});

await hykecal.admin.setWeeklyRules([
  { dayOfWeek: 1, startMinute: 9 * 60, endMinute: 17 * 60 }, // Monday 9-5
]);

const upcoming = await hykecal.admin.listBookings({ status: "confirmed" });

Errors

Every non-2xx response throws HykeCalApiError, with .status and a .message taken from the API's own error body:

import { HykeCalApiError } from "hykecal-client";

try {
  await hykecal.createBooking({ eventTypeSlug: "15-min-call", start, name, email });
} catch (err) {
  if (err instanceof HykeCalApiError && err.status === 409) {
    // that slot's gone — refetch and show a different one
  }
  if (err instanceof HykeCalApiError && err.status === 429) {
    // rate-limited — HykeCal's public endpoints are keyless and CORS-open,
    // so they're capped per caller IP: booking creation at 5/hour, slot
    // lookups at 60 per 10 minutes. Back off and retry later.
  }
}

Used by

hykewebcreator's Booking plugin (src/components/booking-widget.tsx) uses this to embed a real booking calendar directly on a published site — the calendar you see there is calling HykeCal through this package, from the visitor's own browser.

What this is not

This client is JS/TS only. If you're calling HykeCal from Python, Ruby, PHP, or anywhere else, the REST API itself is the integration surface — plain HTTP, no SDK required. See HykeCal's own README for the full endpoint list.