@aranova/tracking-next 0.20.1 → 0.21.0

package/dist/calendar.d.mts

@@ -0,0 +1,112 @@
+import { A as AranovaApiError } from './date-BHetnL7s.mjs';
+export { f as formatDateInTz } from './date-BHetnL7s.mjs';
+import { r as CalendarSummary, m as BusyResponse, C as CalendarTransportConfig, q as CalendarErrorCode, d as BusyInterval } from './transport-Bku8zftU.mjs';
+export { e as BOOKING_SOURCES, f as BOOKING_STATUSES, a as Booking, g as BookingAttendee, c as BookingCancelInput, B as BookingCreateInput, h as BookingCustomer, i as BookingLocation, j as BookingMetadata, k as BookingReminders, b as BookingRescheduleInput, l as BookingStatus, n as CALENDAR_ERROR_CODES, o as CALENDAR_METADATA_SCHEMA_VERSION, p as CALENDAR_SYNC_STATUSES, s as CalendarSyncStatus, G as GOOGLE_SYNC_STATES, t as GoogleSyncState, J as JsonScalar, M as MAX_ATTENDEES, u as MAX_BOOKING_MINUTES, v as MAX_REMINDER_MINUTES, w as MAX_REMINDER_OVERRIDES, x as bookingAttendeeSchema, y as bookingCancelSchema, z as bookingCreateSchema, A as bookingCustomerSchema, D as bookingLocationNullableSchema, E as bookingLocationSchema, F as bookingMetadataSchema, H as bookingReminderSchema, I as bookingRemindersSchema, K as bookingRescheduleSchema } from './transport-Bku8zftU.mjs';
+import 'zod';
+import './request-Doq36Rt0.mjs';
+
+/**
+ * The browser-side calendar client — reads only.
+ *
+ * There is deliberately no write verb on this type. A public key ships in a JS
+ * bundle and its Origin allowlist is a browser-enforced header a script forges
+ * trivially; a booking is not a database row but an event on a real person's
+ * calendar that mails their contacts. Writes live in
+ * `@aranova/tracking-next/calendar-server`, which is `server-only`.
+ */
+interface CalendarReadClientConfig extends CalendarTransportConfig {
+    /** Falls back to the visitor's own zone. */
+    defaultTimeZone?: string;
+    /** Required when the key is not already scoped to one business. */
+    businessId?: string;
+}
+interface BusyQuery {
+    /**
+     * ISO 8601 instants WITH an offset — the API rejects a naive or date-only
+     * value with a 400. `startOfDayInTz`/`endOfDayInTz` turn a picked date into
+     * the right pair for a given zone.
+     */
+    since: string;
+    until: string;
+    timeZone?: string;
+}
+interface CalendarReadClient<TCalendarKey extends string = string> {
+    /** Labels, timezones and status — everything a widget needs before booking. */
+    listCalendars(): Promise<CalendarSummary[]>;
+    /** Busy intervals only. Never the contents of the grantee's events. */
+    busy(calendarKey: TCalendarKey, query: BusyQuery): Promise<BusyResponse>;
+}
+declare function createCalendarReadClient<TCalendarKey extends string = string>(config: CalendarReadClientConfig): CalendarReadClient<TCalendarKey>;
+/** Narrow an unknown error to a specific calendar failure code. */
+declare function isCalendarError(error: unknown, code?: CalendarErrorCode): error is AranovaApiError;
+
+/** The visitor's own zone, so a booking page defaults to their local times. */
+declare function resolveBrowserTimeZone(): string;
+/** Offset in minutes between UTC and `timeZone` at a given instant. */
+declare function offsetMinutesAt(date: Date, timeZone: string): number;
+/**
+ * The instant matching a wall-clock time in `timeZone`.
+ *
+ * Two passes because the offset itself depends on the instant: guess with the
+ * offset at the naive time, then re-solve with the offset that guess landed in.
+ * That second pass is what makes DST-transition days come out right.
+ */
+declare function instantFromWallClock(timeZone: string, year: number, month: number, day: number, hour?: number, minute?: number): Date;
+/** `YYYY-MM-DD` for an instant as seen in `timeZone`. */
+declare function localDateKey(iso: string, timeZone: string): string;
+declare function startOfDayInTz(dateKey: string, timeZone: string): Date;
+declare function endOfDayInTz(dateKey: string, timeZone: string): Date;
+declare function durationMinutes(startIso: string, endIso: string): number;
+/** `10:00 – 10:30` in the given zone. */
+declare function formatSlotRange(startIso: string, endIso: string, timeZone: string, locale?: string): string;
+
+/**
+ * Slot computation lives in the client site, not in our database.
+ *
+ * Opening hours, slot length, notice and buffers differ per client and per use
+ * case; modelling them as dashboard config would mean every new client needs
+ * data entry before their site works. The API answers only "when is this person
+ * busy" — this pure helper turns that plus the site's own hours into offerable
+ * slots.
+ */
+interface OpeningInterval {
+    /** Local wall-clock `HH:MM` in the calendar's zone. */
+    start: string;
+    end: string;
+}
+interface OpeningHours {
+    /** 0 = Sunday … 6 = Saturday. A missing weekday is closed. */
+    weekly: Partial<Record<number, OpeningInterval[]>>;
+    /** `YYYY-MM-DD` → intervals, replacing that day's weekly rule entirely. */
+    overrides?: Record<string, OpeningInterval[]>;
+    /** `YYYY-MM-DD` dates that are closed regardless of the weekly rule. */
+    closedDates?: string[];
+}
+interface ComputeSlotsOptions {
+    busy: BusyInterval[];
+    openingHours: OpeningHours;
+    timeZone: string;
+    durationMinutes: number;
+    granularityMinutes?: number;
+    minNoticeMinutes?: number;
+    bufferBeforeMinutes?: number;
+    bufferAfterMinutes?: number;
+    windowDays?: number;
+    now?: Date;
+}
+interface Slot {
+    start_at: string;
+    end_at: string;
+}
+interface ComputeSlotsResult {
+    slots: Slot[];
+    nextAvailableAt: string | null;
+}
+declare function computeSlots(options: ComputeSlotsOptions): ComputeSlotsResult;
+/** Group slots by local date, the shape every date-picker UI wants. */
+declare function groupSlotsByDay(slots: Slot[], timeZone: string): {
+    date: string;
+    slots: Slot[];
+}[];
+
+export { AranovaApiError, BusyInterval, type BusyQuery, BusyResponse, CalendarErrorCode, type CalendarReadClient, type CalendarReadClientConfig, CalendarSummary, CalendarTransportConfig, type ComputeSlotsOptions, type ComputeSlotsResult, type OpeningHours, type OpeningInterval, type Slot, computeSlots, createCalendarReadClient, durationMinutes, endOfDayInTz, formatSlotRange, groupSlotsByDay, instantFromWallClock, isCalendarError, localDateKey, offsetMinutesAt, resolveBrowserTimeZone, startOfDayInTz };

package/dist/calendar.d.ts

@@ -0,0 +1,112 @@
+import { A as AranovaApiError } from './date-BHetnL7s.js';
+export { f as formatDateInTz } from './date-BHetnL7s.js';
+import { r as CalendarSummary, m as BusyResponse, C as CalendarTransportConfig, q as CalendarErrorCode, d as BusyInterval } from './transport-DsOY6kcW.js';
+export { e as BOOKING_SOURCES, f as BOOKING_STATUSES, a as Booking, g as BookingAttendee, c as BookingCancelInput, B as BookingCreateInput, h as BookingCustomer, i as BookingLocation, j as BookingMetadata, k as BookingReminders, b as BookingRescheduleInput, l as BookingStatus, n as CALENDAR_ERROR_CODES, o as CALENDAR_METADATA_SCHEMA_VERSION, p as CALENDAR_SYNC_STATUSES, s as CalendarSyncStatus, G as GOOGLE_SYNC_STATES, t as GoogleSyncState, J as JsonScalar, M as MAX_ATTENDEES, u as MAX_BOOKING_MINUTES, v as MAX_REMINDER_MINUTES, w as MAX_REMINDER_OVERRIDES, x as bookingAttendeeSchema, y as bookingCancelSchema, z as bookingCreateSchema, A as bookingCustomerSchema, D as bookingLocationNullableSchema, E as bookingLocationSchema, F as bookingMetadataSchema, H as bookingReminderSchema, I as bookingRemindersSchema, K as bookingRescheduleSchema } from './transport-DsOY6kcW.js';
+import 'zod';
+import './request-Doq36Rt0.js';
+
+/**
+ * The browser-side calendar client — reads only.
+ *
+ * There is deliberately no write verb on this type. A public key ships in a JS
+ * bundle and its Origin allowlist is a browser-enforced header a script forges
+ * trivially; a booking is not a database row but an event on a real person's
+ * calendar that mails their contacts. Writes live in
+ * `@aranova/tracking-next/calendar-server`, which is `server-only`.
+ */
+interface CalendarReadClientConfig extends CalendarTransportConfig {
+    /** Falls back to the visitor's own zone. */
+    defaultTimeZone?: string;
+    /** Required when the key is not already scoped to one business. */
+    businessId?: string;
+}
+interface BusyQuery {
+    /**
+     * ISO 8601 instants WITH an offset — the API rejects a naive or date-only
+     * value with a 400. `startOfDayInTz`/`endOfDayInTz` turn a picked date into
+     * the right pair for a given zone.
+     */
+    since: string;
+    until: string;
+    timeZone?: string;
+}
+interface CalendarReadClient<TCalendarKey extends string = string> {
+    /** Labels, timezones and status — everything a widget needs before booking. */
+    listCalendars(): Promise<CalendarSummary[]>;
+    /** Busy intervals only. Never the contents of the grantee's events. */
+    busy(calendarKey: TCalendarKey, query: BusyQuery): Promise<BusyResponse>;
+}
+declare function createCalendarReadClient<TCalendarKey extends string = string>(config: CalendarReadClientConfig): CalendarReadClient<TCalendarKey>;
+/** Narrow an unknown error to a specific calendar failure code. */
+declare function isCalendarError(error: unknown, code?: CalendarErrorCode): error is AranovaApiError;
+
+/** The visitor's own zone, so a booking page defaults to their local times. */
+declare function resolveBrowserTimeZone(): string;
+/** Offset in minutes between UTC and `timeZone` at a given instant. */
+declare function offsetMinutesAt(date: Date, timeZone: string): number;
+/**
+ * The instant matching a wall-clock time in `timeZone`.
+ *
+ * Two passes because the offset itself depends on the instant: guess with the
+ * offset at the naive time, then re-solve with the offset that guess landed in.
+ * That second pass is what makes DST-transition days come out right.
+ */
+declare function instantFromWallClock(timeZone: string, year: number, month: number, day: number, hour?: number, minute?: number): Date;
+/** `YYYY-MM-DD` for an instant as seen in `timeZone`. */
+declare function localDateKey(iso: string, timeZone: string): string;
+declare function startOfDayInTz(dateKey: string, timeZone: string): Date;
+declare function endOfDayInTz(dateKey: string, timeZone: string): Date;
+declare function durationMinutes(startIso: string, endIso: string): number;
+/** `10:00 – 10:30` in the given zone. */
+declare function formatSlotRange(startIso: string, endIso: string, timeZone: string, locale?: string): string;
+
+/**
+ * Slot computation lives in the client site, not in our database.
+ *
+ * Opening hours, slot length, notice and buffers differ per client and per use
+ * case; modelling them as dashboard config would mean every new client needs
+ * data entry before their site works. The API answers only "when is this person
+ * busy" — this pure helper turns that plus the site's own hours into offerable
+ * slots.
+ */
+interface OpeningInterval {
+    /** Local wall-clock `HH:MM` in the calendar's zone. */
+    start: string;
+    end: string;
+}
+interface OpeningHours {
+    /** 0 = Sunday … 6 = Saturday. A missing weekday is closed. */
+    weekly: Partial<Record<number, OpeningInterval[]>>;
+    /** `YYYY-MM-DD` → intervals, replacing that day's weekly rule entirely. */
+    overrides?: Record<string, OpeningInterval[]>;
+    /** `YYYY-MM-DD` dates that are closed regardless of the weekly rule. */
+    closedDates?: string[];
+}
+interface ComputeSlotsOptions {
+    busy: BusyInterval[];
+    openingHours: OpeningHours;
+    timeZone: string;
+    durationMinutes: number;
+    granularityMinutes?: number;
+    minNoticeMinutes?: number;
+    bufferBeforeMinutes?: number;
+    bufferAfterMinutes?: number;
+    windowDays?: number;
+    now?: Date;
+}
+interface Slot {
+    start_at: string;
+    end_at: string;
+}
+interface ComputeSlotsResult {
+    slots: Slot[];
+    nextAvailableAt: string | null;
+}
+declare function computeSlots(options: ComputeSlotsOptions): ComputeSlotsResult;
+/** Group slots by local date, the shape every date-picker UI wants. */
+declare function groupSlotsByDay(slots: Slot[], timeZone: string): {
+    date: string;
+    slots: Slot[];
+}[];
+
+export { AranovaApiError, BusyInterval, type BusyQuery, BusyResponse, CalendarErrorCode, type CalendarReadClient, type CalendarReadClientConfig, CalendarSummary, CalendarTransportConfig, type ComputeSlotsOptions, type ComputeSlotsResult, type OpeningHours, type OpeningInterval, type Slot, computeSlots, createCalendarReadClient, durationMinutes, endOfDayInTz, formatSlotRange, groupSlotsByDay, instantFromWallClock, isCalendarError, localDateKey, offsetMinutesAt, resolveBrowserTimeZone, startOfDayInTz };