@blazeo.com/appointment-client 1.0.5 → 1.0.6

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/config/applyBlazeoDefaults.ts

@@ -0,0 +1,13 @@
+import { configure } from "@blazeo.com/calendar-client";
+import { blazeoClientConfig } from "./blazeoClientDefaults.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() {
+  const baseUrl = blazeoClientConfig.baseUrl?.trim().replace(/\/+$/, "");
+  if (!baseUrl) return;
+  const consumer = blazeoClientConfig.consumer?.trim();
+  configure({
+    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: "",
+  consumer: "",
+};

package/src/config/initializeAppointmentClient.ts

@@ -0,0 +1,18 @@
+import { configure, getConfig } from "@blazeo.com/calendar-client";
+
+export interface AppointmentClientConfig {
+  baseUrl: string;
+  consumer?: string;
+  fetch?: typeof fetch;
+}
+
+let isConfigured = false;
+
+export function initializeAppointmentClient(config: AppointmentClientConfig) {
+  configure(config);
+  isConfigured = true;
+}
+
+export function isAppointmentClientConfigured() {
+  return isConfigured || getConfig() !== null;
+}

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);
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+import { getExampleSlots } from "./exampleData.js";
+
+export { initializeAppointmentClient, isAppointmentClientConfigured } from "./config/initializeAppointmentClient.js";
+export { blazeoClientConfig } from "./config/blazeoClientDefaults.js";
+export { applyBlazeoClientConfig } from "./config/applyBlazeoDefaults.js";
+export { createCalendarRoot, CalendarRootModel, CalendarSlotModel, EventModel, ParticipantModel } from "./models/CalendarRootModel.js";
+export { fetchCalendarDetails, fetchCalendarBundle, normalizeOpeningHours } from "./calendar/fetchCalendarDetails.js";
+export {
+  buildUnifiedCalendarView,
+  type UnifiedCalendarMember,
+  type UnifiedCalendarView,
+  type UnifiedOpeningHourRow,
+  type UnifiedParticipantWithHours,
+} from "./calendar/buildUnifiedCalendarView.js";
+export { fetchCalendarWithOpeningHours, unwrapCalendarGetData, pickOpeningHoursArrayFromCalendarPayload, normalizeParticipantOpeningHoursResponse } from "./calendar/fetchCalendarWithOpeningHours.js";
+export { getOpeningHours } from "./calendar/getOpeningHours.js";
+export { getParticipantOpeningHours } from "./calendar/getParticipantOpeningHours.js";
+export { getAllParticipantOpeningHours } from "./calendar/getAllParticipantOpeningHours.js";
+export { getParticipants } from "./calendar/getParticipants.js";
+export { getExampleSlots, getExampleEvents, getExampleParticipants, getExampleCalendarRoot, getExampleCalendarRootSnapshot } from "./exampleData.js";
+
+// Re-export core models from calendar-client for convenience
+export { createCalendarAsync, updateCalendarAsync, deleteCalendarAsync, resolveBlazeoConnection } from "./calendar/createCalendar.js";
+export { CalendarCreation, createCalendarWithRelationsAsync, updateCalendarWithRelationsAsync, resolveParticipantIdForOpeningHour } from "./calendar/calendarCreation.js";
+export { addParticipantToCalendar, removeParticipantFromCalendar, saveCalendarOpeningHour, saveCalendarOpeningHoursBatch } from "./calendar/blazeoCalendarRelationMethods.js";
+export { createAppointmentEventAsync, rescheduleAppointmentEventAsync, cancelAppointmentEventAsync } from "./events/appointmentEventFacade.js";
+export { mapAppointmentToEventSnapshot } from "./events/mapAppointmentToEventSnapshot.js";
+
+export { 
+  CalendarModel, 
+  EventModel as CoreEventModel, 
+  ParticipantModel as CoreParticipantModel, 
+  CalendarParticipantModel,
+  configure, 
+  getConfig 
+} from "@blazeo.com/calendar-client";
+
+export const packageName = "@blazeo.com/appointment-client";
+
+export class CalendarClient {
+  name = "CalendarClient";
+  getExampleSlots() {
+    return getExampleSlots();
+  }
+}

package/src/models/CalendarRootModel.ts

@@ -0,0 +1,60 @@
+import { types, Instance, SnapshotIn, SnapshotOut } from "mobx-state-tree";
+
+export const CalendarSlotModel = types.model("CalendarSlot", {
+  id: types.identifier,
+  title: types.maybeNull(types.string),
+  start: types.string,
+  end: types.string,
+  isAvailable: types.optional(types.boolean, true),
+});
+
+export const EventModel = types.model("Event", {
+  id: types.identifier,
+  title: types.string,
+  calendarId: types.maybeNull(types.string),
+  startsAt: types.maybeNull(types.string),
+  endsAt: types.maybeNull(types.string),
+  participantIds: types.optional(types.array(types.string), []),
+});
+
+export const ParticipantModel = types.model("Participant", {
+  id: types.identifier,
+  name: types.string,
+  email: types.maybeNull(types.string),
+  role: types.maybeNull(types.string),
+});
+
+export const CalendarRootModel = types
+  .model("CalendarRoot", {
+    slots: types.array(CalendarSlotModel),
+    events: types.array(EventModel),
+    participants: types.array(ParticipantModel),
+  })
+  .actions((self) => ({
+    removeSlot(id: string) {
+      const i = self.slots.findIndex((s) => s.id === id);
+      if (i >= 0) self.slots.splice(i, 1);
+    },
+    removeEvent(id: string) {
+      const i = self.events.findIndex((e) => e.id === id);
+      if (i >= 0) self.events.splice(i, 1);
+    },
+    removeParticipant(id: string) {
+      const i = self.participants.findIndex((p) => p.id === id);
+      if (i >= 0) self.participants.splice(i, 1);
+    },
+  }));
+
+export interface ICalendarRoot extends Instance<typeof CalendarRootModel> {}
+export interface ICalendarRootSnapshotIn extends SnapshotIn<typeof CalendarRootModel> {}
+export interface ICalendarRootSnapshotOut extends SnapshotOut<typeof CalendarRootModel> {}
+
+export function createCalendarRoot(snapshot?: ICalendarRootSnapshotIn): ICalendarRoot {
+  return snapshot
+    ? CalendarRootModel.create(snapshot)
+    : CalendarRootModel.create({
+        slots: [],
+        events: [],
+        participants: [],
+      });
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "sample"]
+}