@blazeo.com/appointment-client 1.0.5 → 1.0.7

package/src/calendar/getAllParticipantOpeningHours.ts

@@ -0,0 +1,30 @@
+import { CalendarModel } from "@blazeo.com/calendar-client";
+import { ensureBlazeoHttpReady } from "../config/ensureBlazeoHttpReady.js";
+import { normalizeParticipantOpeningHoursResponse } from "./fetchCalendarWithOpeningHours.js";
+
+/**
+ * Fetch all participant opening hours for a calendar.
+ * Uses `GET /Calendar/Participant/OpeningHours/All/Get`.
+ */
+export async function getAllParticipantOpeningHours(
+  calendarId: string,
+  options: { baseUrl?: string; consumer?: string } = {}
+) {
+  const ready = ensureBlazeoHttpReady(options);
+  if (!ready.ok) {
+    throw new Error(ready.error);
+  }
+  const raw: any = await (CalendarModel as any).getAllParticipantOpeningHours(calendarId);
+
+  // calendar-client static helper returns either `unknown[] | null` or an envelope depending on version/entrypoint.
+  if (Array.isArray(raw)) {
+    return { openingHours: raw, raw, meta: { ok: true as const, shape: "array" as const } };
+  }
+
+  const { list } = normalizeParticipantOpeningHoursResponse(raw);
+  const openingHours = Array.isArray(list) ? list : [];
+  const ok = Array.isArray(list) ? true : raw?.status === "success";
+
+  return { openingHours, raw, meta: { ok: !!ok as boolean } };
+}
+

package/src/calendar/getOpeningHours.ts

@@ -0,0 +1,10 @@
+import { fetchCalendarWithOpeningHours } from "./fetchCalendarWithOpeningHours.js";
+
+/**
+ * Fetches opening hours for a calendar.
+ * Automatically handles embedded calendar-level hours and participant-level fallbacks.
+ */
+export async function getOpeningHours(calendarId: string, options: { baseUrl?: string; consumer?: string } = {}) {
+  const result = await fetchCalendarWithOpeningHours(calendarId, options);
+  return result.openingHours;
+}

package/src/calendar/getParticipantOpeningHours.ts

@@ -0,0 +1,55 @@
+import { CalendarModel } from "@blazeo.com/calendar-client";
+import { resolveBlazeoConnection } from "./createCalendar.js";
+import { unwrapCalendarGetData, normalizeParticipantOpeningHoursResponse } from "./fetchCalendarWithOpeningHours.js";
+
+/**
+ * Direct wrapper around `calendar.getParticipantOpeningHours()` for a calendar id.
+ *
+ * This hits `GET /Calendar/Participant/OpeningHours/Get` (server-side shape may vary),
+ * so we also return a normalized list alongside the raw response.
+ */
+export async function getParticipantOpeningHours(calendarId: string, options: any = {}) {
+  try {
+    const { baseUrl, consumer, ...passThrough } = options;
+    const { baseUrl: resolvedBase, consumer: resolvedConsumer } = resolveBlazeoConnection({ baseUrl, consumer });
+    const rawRes = await (CalendarModel as any).getRaw(calendarId);
+    const payload = unwrapCalendarGetData(rawRes);
+
+    if (!payload) {
+      return {
+        openingHours: [] as any[],
+        raw: null as any,
+        meta: { ok: false as const, reason: "calendar_not_found" },
+      };
+    }
+
+    const cal = (CalendarModel as any).create(
+      { ...payload, calendarId },
+      { baseUrl: resolvedBase, consumer: resolvedConsumer }
+    );
+
+    const raw = await cal.getParticipantOpeningHours({ calendarId, ...(passThrough ?? {}) });
+    const { list } = normalizeParticipantOpeningHoursResponse(raw);
+    const openingHours = Array.isArray(list) ? list : [];
+
+    return {
+      openingHours,
+      raw,
+      meta: {
+        ok: true as const,
+        count: openingHours.length,
+        status: raw?.status ?? (raw?.Status || "unknown"),
+      },
+    };
+  } catch (err) {
+    return {
+      openingHours: [] as any[],
+      raw: null as any,
+      meta: {
+        ok: false as const,
+        reason: "exception",
+        error: err instanceof Error ? err.message : String(err),
+      },
+    };
+  }
+}

package/src/calendar/getParticipants.ts

@@ -0,0 +1,17 @@
+import { CalendarModel } from "@blazeo.com/calendar-client";
+import { ensureBlazeoHttpReady } from "../config/ensureBlazeoHttpReady.js";
+
+/**
+ * Fetches participants for a calendar.
+ */
+export async function getParticipants(
+  calendarId: string,
+  options: { baseUrl?: string; consumer?: string } = {}
+) {
+  const ready = ensureBlazeoHttpReady(options);
+  if (!ready.ok) {
+    throw new Error(ready.error);
+  }
+  const participants = await CalendarModel.getParticipants(calendarId);
+  return Array.isArray(participants) ? participants : [];
+}

package/src/calendar/mapCalendarToBlazeoSnapshot.ts

@@ -0,0 +1,46 @@
+/** Default enum values aligned with ApexFlows / Blazeo (`AssignmentMethod`, `Unit`). */
+const DEFAULT_ASSIGNMENT_METHOD = 1;
+const DEFAULT_UNIT_MINUTES = 1;
+
+/**
+ * For Blazeo `Calendar` MST: `types.optional(types.number)` accepts `undefined` (uses default)
+ * but not `null`. Coerce null/absent to `undefined`.
+ */
+function optionalNumber(v: any) {
+  return v == null ? undefined : v;
+}
+
+/**
+ * Maps Apex `CalendarBO`-shaped input to a snapshot for
+ * {@link CalendarModel.create} from `@blazeo.com/calendar-client`.
+ *
+ * Only fields that exist on Blazeo's `Calendar` model are included so MST does not receive
+ * unknown keys or invalid `null`s on optional numbers.
+ */
+export function mapCalendarBOToSnapshot(bo: any) {
+  const c = globalThis.crypto;
+  const generatedId = c?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  const calendarId = bo.calendarId ?? generatedId;
+  return {
+    companyKey: bo.companyKey ?? null,
+    calendarId,
+    name: bo.name ?? null,
+    timeZoneId: bo.timeZoneId ?? null,
+    purpose: bo.purpose ?? bo.bookingPageTitle ?? "",
+    description: bo.description ?? null,
+    assignmentMethod: bo.assignmentMethod ?? bo.assignmentType ?? DEFAULT_ASSIGNMENT_METHOD,
+    duration: optionalNumber(bo.duration) ?? 30,
+    durationUnit: optionalNumber(bo.durationUnit) ?? DEFAULT_UNIT_MINUTES,
+    minimumBookingNotice: optionalNumber(bo.minimumBookingNotice) ?? 0,
+    minimumBookingNoticeUnit: optionalNumber(bo.minimumBookingNoticeUnit) ?? DEFAULT_UNIT_MINUTES,
+    minimumCancelationNotice: optionalNumber(bo.minimumCancelationNotice) ?? 0,
+    minimumCancelationNoticeUnit: optionalNumber(bo.minimumCancelationNoticeUnit) ?? DEFAULT_UNIT_MINUTES,
+    futureLimit: optionalNumber(bo.futureLimit) ?? 0,
+    futureLimitUnit: optionalNumber(bo.futureLimitUnit) ?? 3,
+    bufferTime: optionalNumber(bo.bufferTime),
+    bufferTimeUnit: optionalNumber(bo.bufferTimeUnit) ?? DEFAULT_UNIT_MINUTES,
+    bookingLimit: optionalNumber(bo.bookingLimit),
+    createdOn: bo.createdOn ?? null,
+    modifiedOn: bo.modifiedOn ?? null,
+  };
+}

package/src/calendar/mapToDesiredResponse.ts

@@ -0,0 +1,104 @@
+/**
+ * Maps a raw Blazeo API calendar payload (often PascalCase) to the specific camelCase 
+ * shape requested by the user, including typenames and normalized fields.
+ */
+export function mapToDesiredCalendarResponse(payload: any, openingHours: any[] = [], members: any[] = []) {
+  if (!payload) return null;
+
+  const pick = (obj: any, ...keys: string[]) => {
+    for (const k of keys) {
+      if (obj[k] !== undefined && obj[k] !== null) return obj[k];
+    }
+    return undefined;
+  };
+
+  const n = (v: any) => (v != null && v !== "" ? Number(v) : null);
+
+  // Map members with typename
+  const mappedMembers = members.map(m => ({
+    id: m.id ?? pick(m, "id", "Id"),
+    name: m.name ?? pick(m, "name", "Name", "alias", "Alias"),
+    email: m.email ?? pick(m, "email", "Email") ?? null,
+    status: m.status ?? pick(m, "status", "Status") ?? 0,
+    __typename: "Member"
+  }));
+
+  // Map opening hours with typename and raw fields
+  const mappedOpeningHours = openingHours.map(oh => ({
+    id: pick(oh, "id", "Id") ?? 0,
+    createdOn: pick(oh, "createdOn", "CreatedOn", "created_on") ?? "0001-01-01T00:00:00.000Z",
+    modifiedOn: pick(oh, "modifiedOn", "ModifiedOn", "modified_on") ?? "0001-01-01T00:00:00.000Z",
+    member: pick(oh, "member", "Member"),
+    openingHourId: pick(oh, "openingHourId", "OpeningHourId", "opening_hour_id") ?? "",
+    calendarId: pick(oh, "calendarId", "CalendarId", "calendar_id") ?? "",
+    participantId: pick(oh, "participantId", "ParticipantId", "participant_id") ?? "",
+    days: oh.days ?? [],
+    startHour: oh.startHour ?? pick(oh, "startHour", "StartHour") ?? 0,
+    startMinute: oh.startMinute ?? pick(oh, "startMinute", "StartMinute") ?? 0,
+    endHour: oh.endHour ?? pick(oh, "endHour", "EndHour") ?? 0,
+    endMinute: oh.endMinute ?? pick(oh, "endMinute", "EndMinute") ?? 0,
+    off: !!(oh.off ?? pick(oh, "off", "Off")),
+    __typename: "OpeningHour"
+  }));
+
+  // Map theme
+  const rawTheme = pick(payload, "theme", "Theme");
+  const theme = rawTheme ? {
+    id: pick(rawTheme, "id", "Id"),
+    color: pick(rawTheme, "color", "Color"),
+    logoUrl: pick(rawTheme, "logoUrl", "LogoUrl") ?? null,
+    __typename: "Theme"
+  } : null;
+
+  // Map reminders
+  const rawReminders = pick(payload, "reminderChannelStatuses", "ReminderChannelStatuses") ?? [];
+  const reminderChannelStatuses = Array.isArray(rawReminders) ? rawReminders.map((r: any) => ({
+    id: pick(r, "id", "Id"),
+    calendarId: pick(r, "calendarId", "CalendarId"),
+    channelId: pick(r, "channelId", "ChannelId"),
+    status: !!pick(r, "status", "Status"),
+    appointmentReminders: (pick(r, "appointmentReminders", "AppointmentReminders") ?? []).map((ar: any) => ({
+      id: pick(ar, "id", "Id"),
+      reminderChannelStatusId: pick(ar, "reminderChannelStatusId", "ReminderChannelStatusId"),
+      recipientType: pick(ar, "recipientType", "RecipientType"),
+      beforeEventTime: pick(ar, "beforeEventTime", "BeforeEventTime"),
+      unit: pick(ar, "unit", "Unit"),
+      __typename: "AppointmentReminder"
+    })),
+    __typename: "ReminderChannelStatus"
+  })) : [];
+
+  return {
+    id: n(pick(payload, "id", "Id")),
+    durationUnit: n(pick(payload, "durationUnit", "DurationUnit")),
+    minimumBookingNotice: n(pick(payload, "minimumBookingNotice", "MinimumBookingNotice")),
+    minimumBookingNoticeUnit: n(pick(payload, "minimumBookingNoticeUnit", "MinimumBookingNoticeUnit")),
+    minimumCancelationNotice: n(pick(payload, "minimumCancelationNotice", "MinimumCancelationNotice")),
+    minimumCancelationNoticeUnit: n(pick(payload, "minimumCancelationNoticeUnit", "MinimumCancelationNoticeUnit")),
+    futureLimit: n(pick(payload, "futureLimit", "FutureLimit")),
+    futureLimitUnit: n(pick(payload, "futureLimitUnit", "FutureLimitUnit")),
+    bufferTime: n(pick(payload, "bufferTime", "BufferTime")),
+    bufferTimeUnit: n(pick(payload, "bufferTimeUnit", "BufferTimeUnit")),
+    calendarLink: pick(payload, "calendarLink", "CalendarLink"),
+    uuid: pick(payload, "uuid", "Uuid", "calendarId", "CalendarId"),
+    location: pick(payload, "location", "Location") ?? "",
+    bookingPageTitle: pick(payload, "bookingPageTitle", "BookingPageTitle") ?? null,
+    reminderChannelStatuses,
+    members: mappedMembers,
+    createdOn: pick(payload, "createdOn", "CreatedOn") ?? "0001-01-01T00:00:00.000Z",
+    modifiedOn: pick(payload, "modifiedOn", "ModifiedOn") ?? "0001-01-01T00:00:00.000Z",
+    name: pick(payload, "name", "Name"),
+    timeZoneId: pick(payload, "timeZoneId", "TimeZoneId"),
+    description: pick(payload, "description", "Description") ?? "",
+    assignmentType: n(pick(payload, "assignmentType", "AssignmentType", "assignmentMethod", "AssignmentMethod")),
+    duration: n(pick(payload, "duration", "Duration")),
+    bookingLimit: n(pick(payload, "bookingLimit", "BookingLimit")),
+    calendarJson: pick(payload, "calendarJson", "CalendarJson") ?? null,
+    isThirdPartySaved: !!pick(payload, "isThirdPartySaved", "IsThirdPartySaved"),
+    themeId: n(pick(payload, "themeId", "ThemeId")),
+    theme,
+    openingHours: mappedOpeningHours,
+    appointmentUserDefinedFields: pick(payload, "appointmentUserDefinedFields", "AppointmentUserDefinedFields") ?? [],
+    __typename: "Calendar"
+  };
+}

package/src/config/applyBlazeoDefaults.ts

@@ -0,0 +1,14 @@
+import { blazeoClientConfig } from "./blazeoClientDefaults.js";
+import { syncBlazeoConnection } from "./syncBlazeoConnection.js";
+
+/** Push {@link blazeoClientConfig} into `@blazeo.com/calendar-client` (global store). Call explicitly if you use file defaults; otherwise use {@link initializeAppointmentClient}. */
+export function applyBlazeoClientConfig() {
+  debugger;
+  const baseUrl = blazeoClientConfig.baseUrl?.trim().replace(/\/+$/, "");
+  if (!baseUrl) return;
+  const consumer = blazeoClientConfig.consumer?.trim();
+  syncBlazeoConnection({
+    baseUrl,
+    ...(consumer ? { consumer } : {}),
+  });
+}

package/src/config/blazeoClientDefaults.ts

@@ -0,0 +1,11 @@
+/**
+ * Optional file-based defaults for local development or publishing a fork.
+ * Host apps should prefer {@link initializeAppointmentClient} with env-driven `baseUrl` / `consumer`.
+ * To apply these values, call {@link applyBlazeoClientConfig} during bootstrap (not automatic on import).
+ *
+ * @example baseUrl: "https://apptscheduling.azurewebsites.net"
+ */
+export const blazeoClientConfig = {
+  baseUrl: "https://apptscheduling.azurewebsites.net",
+  consumer: "smarthub",
+};

package/src/config/ensureBlazeoHttpReady.ts

@@ -0,0 +1,41 @@
+import { configure } from "@blazeo.com/calendar-client";
+import { resolveBlazeoConnection } from "../calendar/createCalendar.js";
+
+export type EnsureBlazeoHttpOptions = {
+  baseUrl?: string;
+  consumer?: string;
+};
+
+/**
+ * Ensures global Blazeo `configure({ baseUrl })` runs before any `CalendarModel` / `EventModel` HTTP.
+ * Uses the same resolution as {@link resolveBlazeoConnection}: explicit args, existing `getConfig()`,
+ * then `blazeoClientDefaults` — so file defaults apply even if the host never called `configure`.
+ */
+export function ensureBlazeoHttpReady(options: EnsureBlazeoHttpOptions = {}):
+  | { ok: true; baseUrl: string; consumer?: string }
+  | { ok: false; error: string } {
+  // Hard-prefer explicit args (call-site can bypass any module-resolution mismatch).
+  const explicitBase = options.baseUrl?.trim().replace(/\/+$/, "");
+  const explicitConsumer = options.consumer?.trim() || undefined;
+  if (explicitBase) {
+    configure({
+      baseUrl: explicitBase,
+      ...(explicitConsumer ? { consumer: explicitConsumer } : {}),
+    });
+    return { ok: true, baseUrl: explicitBase, ...(explicitConsumer ? { consumer: explicitConsumer } : {}) };
+  }
+
+  const { baseUrl, consumer } = resolveBlazeoConnection(options);
+  if (!baseUrl) {
+    return {
+      ok: false,
+      error:
+        "Blazeo base URL is not set. Call initializeAppointmentClient({ baseUrl }) or configure({ baseUrl }) at app startup, set blazeoClientConfig.baseUrl, or pass baseUrl when calling fetch APIs.",
+    };
+  }
+  configure({
+    baseUrl,
+    ...(consumer ? { consumer } : {}),
+  });
+  return { ok: true, baseUrl, ...(consumer ? { consumer } : {}) };
+}

package/src/config/initializeAppointmentClient.ts

@@ -0,0 +1,24 @@
+import { getConfig } from "@blazeo.com/calendar-client";
+import { syncBlazeoConnection } from "./syncBlazeoConnection.js";
+
+export interface AppointmentClientConfig {
+  baseUrl: string;
+  consumer?: string;
+  fetch?: typeof fetch;
+}
+
+let isConfigured = false;
+
+/**
+ * Applies Blazeo connection (same as {@link syncBlazeoConnection}) and marks the client as configured
+ * when a non-empty `baseUrl` was written to `@blazeo.com/calendar-client`.
+ */
+export function initializeAppointmentClient(config: AppointmentClientConfig) {
+  if (syncBlazeoConnection(config)) {
+    isConfigured = true;
+  }
+}
+
+export function isAppointmentClientConfigured() {
+  return isConfigured || getConfig() !== null;
+}

package/src/config/syncBlazeoConnection.ts

@@ -0,0 +1,19 @@
+import { configure } from "@blazeo.com/calendar-client";
+import type { AppointmentClientConfig } from "./initializeAppointmentClient.js";
+
+/**
+ * Writes `baseUrl` / `consumer` into the global `@blazeo.com/calendar-client` `configure()` store.
+ * Returns whether anything was applied (skipped when `baseUrl` is empty after trim).
+ */
+export function syncBlazeoConnection(config: AppointmentClientConfig): boolean {
+  const baseUrl = config.baseUrl?.trim().replace(/\/+$/, "");
+  if (!baseUrl) return false;
+  configure({
+    baseUrl,
+    ...(config.consumer != null && String(config.consumer).trim() !== ""
+      ? { consumer: String(config.consumer).trim() }
+      : {}),
+    ...(config.fetch ? { fetch: config.fetch } : {}),
+  });
+  return true;
+}

package/src/events/appointmentEventFacade.ts

@@ -0,0 +1,148 @@
+import { EventModel, configure } from "@blazeo.com/calendar-client";
+import { buildModelEnv, resolveBlazeoConnection } from "../calendar/createCalendar.js";
+import { mapAppointmentToEventSnapshot } from "./mapAppointmentToEventSnapshot.js";
+
+function isFailureStatus(res: any) {
+  return res.status !== "success" && res.status !== "Success";
+}
+
+function ensureConfigure(resolvedBase: string | undefined, resolvedConsumer: string | undefined) {
+  if (resolvedBase) {
+    configure({
+      baseUrl: resolvedBase,
+      ...(resolvedConsumer ? { consumer: resolvedConsumer } : {}),
+    });
+  }
+}
+
+async function runEventMutation(input: any, mode: "create" | "reschedule", options: any) {
+  const { baseUrl: resolvedBase, consumer: resolvedConsumer } = resolveBlazeoConnection(options);
+  ensureConfigure(resolvedBase, resolvedConsumer);
+
+  const baseUrl = resolvedBase;
+  const consumer = resolvedConsumer;
+
+  if (!options.localOnly && !baseUrl) {
+    return {
+      ok: false,
+      error:
+        "baseUrl is missing. Set `blazeoClientConfig.baseUrl` in `appointment-client/src/config/blazeoClientDefaults.ts` or call `configure({ baseUrl })`.",
+    };
+  }
+
+  const snapshot = mapAppointmentToEventSnapshot(input, mode);
+  const eventIdForApi = snapshot.eventId;
+
+  if (mode === "reschedule" && (!eventIdForApi || eventIdForApi === "new")) {
+    return {
+      ok: false,
+      error: "thirdPartyAppointmentId is required for reschedule (existing Blazeo event id).",
+    };
+  }
+
+  const env = buildModelEnv(baseUrl, consumer, Boolean(options.localOnly));
+  if (!options.localOnly && env.baseUrl == null) {
+    return {
+      ok: false,
+      error: "Model env requires baseUrl. Set `blazeoClientConfig` or pass `baseUrl` in options.",
+    };
+  }
+
+  const eventNode: any = EventModel.create(snapshot, env);
+
+  if (options.localOnly) {
+    return { ok: true, event: eventNode };
+  }
+
+  const offset = options.offsetMinutes;
+  const apiRes: any =
+    mode === "create" ? await eventNode.create(offset) : await eventNode.reschedule(offset);
+
+  if (isFailureStatus(apiRes)) {
+    const msg =
+      apiRes.message ??
+      (typeof apiRes.data === "string" ? apiRes.data : undefined) ??
+      JSON.stringify(apiRes);
+    return {
+      ok: false,
+      error:
+        mode === "create" ? msg || "Event create failed" : msg || "Event reschedule failed",
+      apiResponse: apiRes,
+    };
+  }
+
+  return { ok: true, event: eventNode, apiResponse: apiRes };
+}
+
+/**
+ * Creates an appointment event — `Event.create()` → `POST /event/create`
+ * (aligned with `AppointmentAPIAdapter.Create`).
+ */
+export async function createAppointmentEventAsync(input: any, options: any = {}) {
+  try {
+    return await runEventMutation(input, "create", options);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/**
+ * Reschedules an appointment — `Event.reschedule()` → `POST /event/reschedule`
+ * (aligned with `AppointmentAPIAdapter.Reschedule`).
+ */
+export async function rescheduleAppointmentEventAsync(input: any, options: any = {}) {
+  try {
+    return await runEventMutation(input, "reschedule", options);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/**
+ * Cancels an appointment — `EventModel.cancel` → `GET /event/cancel`
+ * (aligned with `AppointmentAPIAdapter.Cancel`).
+ */
+export async function cancelAppointmentEventAsync(appointmentEventId: string, options: any = {}) {
+  try {
+    const id = appointmentEventId.trim();
+    if (!id) {
+      return { ok: false, error: "appointmentEventId is required for cancel." };
+    }
+
+    const { baseUrl: resolvedBase, consumer: resolvedConsumer } = resolveBlazeoConnection(options);
+    ensureConfigure(resolvedBase, resolvedConsumer);
+
+    const baseUrl = resolvedBase;
+    if (!options.localOnly && !baseUrl) {
+      return {
+        ok: false,
+        error:
+          "baseUrl is missing. Set `blazeoClientConfig.baseUrl` in `appointment-client/src/config/blazeoClientDefaults.ts` or call `configure({ baseUrl })`.",
+      };
+    }
+
+    if (options.localOnly) {
+      return { ok: true, apiResponse: undefined };
+    }
+
+    const apiRes: any = await (EventModel as any).cancel(id);
+    if (isFailureStatus(apiRes)) {
+      const msg =
+        apiRes.message ??
+        (typeof apiRes.data === "string" ? apiRes.data : undefined) ??
+        JSON.stringify(apiRes);
+      return {
+        ok: false,
+        error: msg || "Event cancel failed",
+        apiResponse: apiRes,
+      };
+    }
+
+    return { ok: true, apiResponse: apiRes };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}

package/src/events/mapAppointmentToEventSnapshot.ts

@@ -0,0 +1,65 @@
+function parseDate(value: any) {
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) {
+    throw new Error("Invalid startDate or endDate");
+  }
+  return d;
+}
+
+function formatYmd(d: Date) {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+function normalizeParticipantId(id: string) {
+  return id.trim().replace(/^\{|\}$/g, "");
+}
+
+/**
+ * Maps Apex appointment input to a Blazeo `Event` MST snapshot for
+ * {@link EventModel.create} from `@blazeo.com/calendar-client`.
+ */
+export function mapAppointmentToEventSnapshot(input: any, mode: "create" | "reschedule") {
+  const start = parseDate(input.startDate);
+  const end = parseDate(input.endDate);
+  const description =
+    mode === "create"
+      ? (input.description ?? null)
+      : (input.description ?? input.notes ?? null);
+
+  const eventIdRaw = input.thirdPartyAppointmentId?.trim();
+  const eventId = eventIdRaw && eventIdRaw !== "new" ? eventIdRaw : "new";
+  const email = input.email ?? input.visitorEmail ?? null;
+  const phone = input.phone ?? input.visitorPhone ?? null;
+  const visitorName = input.visitorName?.trim() || null;
+
+  const snap: any = {
+    eventId,
+    calendarId: input.thirdPartyCalendarId?.trim() ?? "",
+    participantId: normalizeParticipantId(input.participantId),
+    title: input.title ?? null,
+    description,
+    startDate: formatYmd(start),
+    endDate: formatYmd(end),
+    startHour: start.getHours(),
+    startMinute: start.getMinutes(),
+    endHour: end.getHours(),
+    endMinute: end.getMinutes(),
+    visitorName,
+    visitorEmail: email,
+    visitorPhone: phone,
+    rescheduleLink: input.rescheduleUrl ?? null,
+    cancelLink: input.cancelUrl ?? null,
+    timeZone: input.timeZone ?? null,
+  };
+
+  if (mode === "create") {
+    const now = new Date().toISOString();
+    snap.createdOn = now;
+    snap.modifiedOn = now;
+  }
+
+  return snap;
+}

package/src/exampleData.ts

@@ -0,0 +1,79 @@
+import { CalendarSlotModel } from "./models/CalendarRootModel.js";
+import { CalendarRootModel } from "./models/CalendarRootModel.js";
+import { EventModel } from "./models/CalendarRootModel.js";
+import { ParticipantModel } from "./models/CalendarRootModel.js";
+
+const EXAMPLE_SLOT_SNAPSHOTS = [
+  {
+    id: "slot-1",
+    title: "Team standup",
+    start: "09:00",
+    end: "09:15",
+  },
+  {
+    id: "slot-2",
+    title: "Focus block",
+    start: "10:00",
+    end: "12:00",
+  },
+  {
+    id: "slot-3",
+    title: "1:1 with design",
+    start: "14:00",
+    end: "14:30",
+  },
+];
+
+const EXAMPLE_EVENT_SNAPSHOTS = [
+  {
+    id: "ev-1",
+    title: "Product roadmap review",
+    calendarId: "cal-eng",
+    startsAt: "2026-04-02T15:00:00.000Z",
+    endsAt: "2026-04-02T16:00:00.000Z",
+    participantIds: ["p-1", "p-2"],
+  },
+  {
+    id: "ev-2",
+    title: "Customer onboarding call",
+    calendarId: "cal-sales",
+    startsAt: "2026-04-03T10:30:00.000Z",
+    endsAt: "2026-04-03T11:00:00.000Z",
+    participantIds: ["p-3"],
+  },
+];
+
+const EXAMPLE_PARTICIPANT_SNAPSHOTS = [
+  { id: "p-1", name: "Alex Morgan", email: "alex@example.com", role: "Organizer" },
+  { id: "p-2", name: "Jordan Lee", email: "jordan@example.com", role: "Required" },
+  { id: "p-3", name: "Sam Rivera", email: "sam@example.com", role: "Optional" },
+];
+
+/** Example slot nodes (MST instances). */
+export function getExampleSlots() {
+  return EXAMPLE_SLOT_SNAPSHOTS.map((s) => CalendarSlotModel.create(s as any));
+}
+
+/** Example event nodes. */
+export function getExampleEvents() {
+  return EXAMPLE_EVENT_SNAPSHOTS.map((s) => EventModel.create(s as any));
+}
+
+/** Example participant nodes. */
+export function getExampleParticipants() {
+  return EXAMPLE_PARTICIPANT_SNAPSHOTS.map((s) => ParticipantModel.create(s as any));
+}
+
+/** Full root store snapshot suitable for `createCalendarRoot(snapshot)`. */
+export function getExampleCalendarRootSnapshot() {
+  return {
+    slots: EXAMPLE_SLOT_SNAPSHOTS,
+    events: EXAMPLE_EVENT_SNAPSHOTS,
+    participants: EXAMPLE_PARTICIPANT_SNAPSHOTS,
+  };
+}
+
+/** Root store with example slots, events, and participants. */
+export function getExampleCalendarRoot() {
+  return CalendarRootModel.create(getExampleCalendarRootSnapshot() as any);
+}