@arkipay/booking-widget 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,521 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _ea_api_contracts from '@ea/api-contracts';
+import { PublicTenantConfigResponse, PublicServiceDto, PublicProviderDto, TimeSlotDto, CreatePublicAppointmentBody, AppointmentDto, BookingTimeDisplayDto } from '@ea/api-contracts';
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import { Temporal } from '@js-temporal/polyfill';
+
+interface BookingClientOptions {
+    readonly publishableKey: string;
+    readonly apiUrl?: string | undefined;
+    readonly origin?: string | undefined;
+}
+declare class BookingApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class BookingClient {
+    private readonly baseUrl;
+    private readonly publishableKey;
+    private readonly origin;
+    constructor(opts: BookingClientOptions);
+    getTenantConfig(): Promise<PublicTenantConfigResponse>;
+    listServices(): Promise<PublicServiceDto[]>;
+    listProviders(params?: {
+        serviceId?: string | undefined;
+    }): Promise<PublicProviderDto[]>;
+    getAvailability(params: {
+        providerId: string;
+        serviceId: string;
+        date: string;
+    }): Promise<TimeSlotDto[]>;
+    getUnavailableDates(params: {
+        providerId: string;
+        serviceId: string;
+        month: string;
+    }): Promise<string[]>;
+    createAppointment(body: CreatePublicAppointmentBody): Promise<AppointmentDto>;
+    private headers;
+    private getJson;
+    private postJson;
+    private parseJson;
+}
+
+/**
+ * Factory for the public booking API client.
+ * Uses the local fetch implementation until `@ea/booking-sdk` exports `BookingClient`.
+ */
+declare function createBookingClient(opts: BookingClientOptions): BookingClient;
+
+declare const enCatalog: {
+    readonly steps: {
+        readonly service: "Choose a service";
+        readonly provider: "Choose a provider";
+        readonly date: "Choose a date";
+        readonly time: "Choose a time";
+        readonly customer: "Your details";
+        readonly legal: "Legal information";
+        readonly confirm: "Confirm your booking";
+        readonly booked: "Booking confirmed";
+    };
+    readonly actions: {
+        readonly back: "Back";
+        readonly continue: "Continue";
+        readonly confirm: "Confirm booking";
+        readonly submitting: "Booking…";
+    };
+    readonly service: {
+        readonly empty: "No services are available right now.";
+        readonly durationMinutes: "{minutes} min";
+        readonly price: "{amount}";
+    };
+    readonly provider: {
+        readonly empty: "No providers are available for this service.";
+        readonly any: "Any available provider";
+    };
+    readonly date: {
+        readonly unavailable: "Unavailable";
+        readonly minHint: "Earliest booking is tomorrow.";
+    };
+    readonly time: {
+        readonly empty: "No time slots are available on this date.";
+        readonly timezone: "All times in {timezone}";
+        readonly timezoneHint: "Times shown in {timezone}";
+        readonly mismatchBanner: "This business uses {businessTimezone}. You are in {customerTimezone}.";
+        readonly showMyTime: "Show in my time";
+        readonly showBusinessTime: "Show business time";
+        readonly yourTimeLabel: "Your time ({timezone})";
+        readonly businessTimeLabel: "Business time ({timezone})";
+    };
+    readonly customer: {
+        readonly required: "Required";
+        readonly invalidEmail: "Enter a valid email address.";
+    };
+    readonly legal: {
+        readonly cookie: "Cookie notice";
+        readonly terms: "Terms & conditions";
+        readonly privacy: "Privacy policy";
+        readonly acceptCookie: "I accept the cookie notice";
+        readonly acceptTerms: "I accept the terms & conditions";
+        readonly acceptPrivacy: "I accept the privacy policy";
+        readonly readMore: "Read";
+    };
+    readonly confirm: {
+        readonly summary: "Review your appointment";
+        readonly service: "Service";
+        readonly provider: "Provider";
+        readonly when: "When";
+        readonly customer: "Customer";
+        readonly error: "We could not complete your booking. Please try again.";
+        readonly conflict: "That time slot is no longer available. Please choose another time.";
+    };
+    readonly booked: {
+        readonly reference: "Reference";
+        readonly message: "Your appointment has been booked.";
+    };
+    readonly disabled: {
+        readonly title: "Booking unavailable";
+    };
+    readonly fields: {
+        readonly first_name: "First name";
+        readonly last_name: "Last name";
+        readonly email: "Email";
+        readonly phone: "Phone";
+        readonly address: "Address";
+        readonly city: "City";
+        readonly state: "State / province";
+        readonly zip: "Postal code";
+        readonly notes: "Notes";
+        readonly custom_1: "Additional information";
+        readonly custom_2: "Additional information (2)";
+        readonly custom_3: "Additional information (3)";
+        readonly custom_4: "Additional information (4)";
+        readonly custom_5: "Additional information (5)";
+    };
+};
+
+type Catalog = typeof enCatalog;
+type NestedKeyOf<T, Prefix extends string = ""> = T extends string ? Prefix extends "" ? never : Prefix : {
+    [K in keyof T & string]: NestedKeyOf<T[K], Prefix extends "" ? K : `${Prefix}.${K}`>;
+}[keyof T & string];
+type TranslationKey = NestedKeyOf<Catalog>;
+type Params = Record<string, string | number>;
+declare function createTranslator(locale: string | undefined, tenantDefaultLanguage: string | undefined): (key: TranslationKey, params?: Params) => string;
+
+declare const ANY_PROVIDER_ID: "any";
+type AnyProviderId = typeof ANY_PROVIDER_ID;
+
+type CustomerFieldValues = {
+    readonly firstName: string;
+    readonly lastName: string;
+    readonly email: string;
+    readonly phone: string;
+    readonly address: string;
+    readonly city: string;
+    readonly state: string;
+    readonly zip: string;
+    readonly notes: string;
+    readonly customField1: string;
+    readonly customField2: string;
+    readonly customField3: string;
+    readonly customField4: string;
+    readonly customField5: string;
+    readonly timezone: string;
+};
+
+type BookingTimeDisplay = BookingTimeDisplayDto;
+type TimeDisplayMode = `business` | `customer`;
+declare function getCustomerTimezone(): string;
+declare function resolveBusinessTimezone(params: {
+    readonly providerId: ProviderSelection;
+    readonly providers: readonly PublicProviderDto[];
+    readonly tenantDefaultTimezone: string;
+    readonly anyProviderId?: AnyProviderId | undefined;
+}): string;
+declare function allowsTimeDisplayToggle(bookingTimeDisplay: BookingTimeDisplay | undefined): boolean;
+declare function resolveDisplayTimezone(params: {
+    readonly businessTimezone: string;
+    readonly customerTimezone: string;
+    readonly bookingTimeDisplay?: BookingTimeDisplay | undefined;
+    readonly timeDisplayMode?: TimeDisplayMode | undefined;
+}): string;
+declare function shouldShowSecondaryTimezone(params: {
+    readonly zonesDiffer: boolean;
+    readonly bookingTimeDisplay?: BookingTimeDisplay | undefined;
+}): boolean;
+
+type ProviderSelection = string | typeof ANY_PROVIDER_ID;
+type BookingConsents = {
+    readonly cookie?: boolean | undefined;
+    readonly terms?: boolean | undefined;
+    readonly privacy?: boolean | undefined;
+};
+type BookingStepState = {
+    readonly step: `service`;
+} | {
+    readonly step: `provider`;
+    readonly serviceId: string;
+} | {
+    readonly step: `date`;
+    readonly serviceId: string;
+    readonly providerId: ProviderSelection;
+} | {
+    readonly step: `time`;
+    readonly serviceId: string;
+    readonly providerId: ProviderSelection;
+    readonly date: string;
+} | {
+    readonly step: `customer`;
+    readonly serviceId: string;
+    readonly providerId: ProviderSelection;
+    readonly date: string;
+    readonly slot: TimeSlotDto;
+} | {
+    readonly step: `legal`;
+    readonly serviceId: string;
+    readonly providerId: ProviderSelection;
+    readonly date: string;
+    readonly slot: TimeSlotDto;
+    readonly customer: CustomerFieldValues;
+} | {
+    readonly step: `confirm`;
+    readonly serviceId: string;
+    readonly providerId: ProviderSelection;
+    readonly date: string;
+    readonly slot: TimeSlotDto;
+    readonly customer: CustomerFieldValues;
+    readonly consents: BookingConsents;
+} | {
+    readonly step: `booked`;
+    readonly appointment: AppointmentDto;
+};
+type BookingState = {
+    readonly timeDisplayMode: TimeDisplayMode;
+} & BookingStepState;
+type BookingAction = {
+    readonly type: `select_service`;
+    readonly serviceId: string;
+} | {
+    readonly type: `select_provider`;
+    readonly providerId: ProviderSelection;
+} | {
+    readonly type: `select_date`;
+    readonly date: string;
+} | {
+    readonly type: `select_slot`;
+    readonly slot: TimeSlotDto;
+} | {
+    readonly type: `set_customer`;
+    readonly customer: CustomerFieldValues;
+} | {
+    readonly type: `set_consents`;
+    readonly consents: BookingConsents;
+} | {
+    readonly type: `set_time_display_mode`;
+    readonly mode: TimeDisplayMode;
+} | {
+    readonly type: `booked`;
+    readonly appointment: AppointmentDto;
+} | {
+    readonly type: `back`;
+} | {
+    readonly type: `prefill`;
+    readonly serviceId?: string | undefined;
+    readonly providerId?: string | undefined;
+};
+declare function createInitialBookingState(prefill?: {
+    readonly serviceId?: string | undefined;
+    readonly providerId?: string | undefined;
+}): BookingState;
+declare function bookingReducer(state: BookingState, action: BookingAction, tenantConfig?: PublicTenantConfigResponse | null): BookingState;
+declare function useBooking(): {
+    state: BookingState;
+    dispatch: react.Dispatch<BookingAction>;
+    tenantConfig: {
+        business: {
+            displayName: string;
+            contactEmail: string | null;
+            link: string | null;
+            logoUrl: string | null;
+            brandColor: string;
+            theme: string;
+        };
+        localization: {
+            currency: string;
+            defaultLanguage: string;
+            defaultTimezone: string;
+            dateFormat: "DMY" | "MDY" | "YMD";
+            timeFormat: "h12" | "h24";
+            firstWeekday: "sunday" | "monday" | "saturday";
+        };
+        booking: {
+            disableBooking: boolean;
+            disableBookingMessage: string | null;
+            displayAnyProvider: boolean;
+            futureBookingLimitDays: number;
+            bookAdvanceTimeoutMinutes: number;
+            requireCaptcha: boolean;
+            bookingTimeDisplay: "customer" | "business" | "customer_only";
+        };
+        formFields: {
+            required: boolean;
+            sortOrder: number;
+            fieldKey: string;
+            isCustom: boolean;
+            display: boolean;
+            label: string | null;
+        }[];
+        legal: {
+            displayCookieNotice: boolean;
+            cookieNoticeContent: string | null;
+            displayTerms: boolean;
+            termsContent: string | null;
+            displayPrivacy: boolean;
+            privacyContent: string | null;
+        };
+        statuses: {
+            color: string | null;
+            slug: string;
+            label: string;
+            isDefault: boolean;
+        }[];
+    } | null;
+    onBooked: ((appointment: _ea_api_contracts.AppointmentDto) => void) | undefined;
+    timeDisplayMode: TimeDisplayMode;
+};
+
+/**
+ * Visual overrides for the widget. Every field is optional — anything left unset
+ * falls through to the host's CSS design-system token, then tenant config (brand
+ * only), then a built-in default. See `styles.css` for the full resolution order.
+ * Each field maps directly to a `--ea-*` custom property.
+ */
+type BookingTheme = {
+    /** Primary / call-to-action colour → `--ea-brand`. */
+    readonly brandColor?: string | undefined;
+    /** Text colour on primary buttons → `--ea-on-brand`. */
+    readonly onBrandColor?: string | undefined;
+    /** Body text colour → `--ea-text`. */
+    readonly textColor?: string | undefined;
+    /** Secondary / hint text colour → `--ea-muted`. */
+    readonly mutedColor?: string | undefined;
+    /** Card / input border colour → `--ea-border`. */
+    readonly borderColor?: string | undefined;
+    /** Card / input / surface background → `--ea-surface`. */
+    readonly surfaceColor?: string | undefined;
+    /** Error / validation colour → `--ea-error`. */
+    readonly errorColor?: string | undefined;
+    /** Corner radius for cards, inputs, buttons → `--ea-radius`. */
+    readonly borderRadius?: string | undefined;
+    /** Font stack → `--ea-font`. */
+    readonly fontFamily?: string | undefined;
+    /** Max width of the widget container → `--ea-max-width`. */
+    readonly maxWidth?: string | undefined;
+    /** Light/dark scheme. `"system"` follows `prefers-color-scheme`. */
+    readonly colorScheme?: "light" | "dark" | "system" | undefined;
+};
+
+type BookingProviderProps = {
+    readonly publishableKey: string;
+    readonly apiUrl?: string | undefined;
+    readonly locale?: string | undefined;
+    readonly theme?: BookingTheme | undefined;
+    readonly onBooked?: ((appointment: AppointmentDto) => void) | undefined;
+    readonly initialServiceId?: string | undefined;
+    readonly initialProviderId?: string | undefined;
+    readonly origin?: string | undefined;
+    /** Extra class(es) on the widget root, for host layout/positioning. */
+    readonly className?: string | undefined;
+    /** Inline styles on the widget root (merged after theme vars, so they win). */
+    readonly style?: CSSProperties | undefined;
+    /**
+     * Vercel BotID client-side protection on the booking POST. Defaults to `true`.
+     * Set `false` on hosts not running the Vercel BotID proxy — the API's
+     * server-side rate limiter is still the backstop.
+     */
+    readonly botProtection?: boolean | undefined;
+    readonly children: ReactNode;
+};
+declare function BookingProvider({ publishableKey, apiUrl, locale, theme, onBooked, initialServiceId, initialProviderId, origin, className, style, botProtection, children, }: BookingProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function BookingWidget(): react_jsx_runtime.JSX.Element;
+
+declare function ServicePicker(): react_jsx_runtime.JSX.Element | null;
+
+declare function ProviderPicker(): react_jsx_runtime.JSX.Element | null;
+
+declare function DatePicker(): react_jsx_runtime.JSX.Element | null;
+
+declare function TimeSlotPicker(): react_jsx_runtime.JSX.Element | null;
+
+declare function CustomerForm(): react_jsx_runtime.JSX.Element | null;
+
+declare function LegalGate(): react_jsx_runtime.JSX.Element | null;
+
+declare function ConfirmStep(): react_jsx_runtime.JSX.Element | null;
+
+declare function BookedSummary(): react_jsx_runtime.JSX.Element | null;
+
+declare function DisabledBooking(): react_jsx_runtime.JSX.Element | null;
+
+declare function useTenantConfig(): {
+    tenantConfig: {
+        business: {
+            displayName: string;
+            contactEmail: string | null;
+            link: string | null;
+            logoUrl: string | null;
+            brandColor: string;
+            theme: string;
+        };
+        localization: {
+            currency: string;
+            defaultLanguage: string;
+            defaultTimezone: string;
+            dateFormat: "DMY" | "MDY" | "YMD";
+            timeFormat: "h12" | "h24";
+            firstWeekday: "sunday" | "monday" | "saturday";
+        };
+        booking: {
+            disableBooking: boolean;
+            disableBookingMessage: string | null;
+            displayAnyProvider: boolean;
+            futureBookingLimitDays: number;
+            bookAdvanceTimeoutMinutes: number;
+            requireCaptcha: boolean;
+            bookingTimeDisplay: "customer" | "business" | "customer_only";
+        };
+        formFields: {
+            required: boolean;
+            sortOrder: number;
+            fieldKey: string;
+            isCustom: boolean;
+            display: boolean;
+            label: string | null;
+        }[];
+        legal: {
+            displayCookieNotice: boolean;
+            cookieNoticeContent: string | null;
+            displayTerms: boolean;
+            termsContent: string | null;
+            displayPrivacy: boolean;
+            privacyContent: string | null;
+        };
+        statuses: {
+            color: string | null;
+            slug: string;
+            label: string;
+            isDefault: boolean;
+        }[];
+    } | null;
+    loading: boolean;
+    error: string | null;
+};
+
+declare function useServices(): {
+    services: {
+        description: string | null;
+        name: string;
+        id: string;
+        durationMinutes: number;
+        categoryId: string | null;
+        priceMinor: number | null;
+        providerIds: string[];
+    }[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+
+declare function useProviders(serviceId: string | undefined): {
+    providers: {
+        id: string;
+        timezone: string;
+        services: {
+            name: string;
+            id: string;
+            color: string | null;
+            durationMinutes: number;
+        }[];
+        displayName: string;
+    }[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+
+declare function useAvailability(params: {
+    providerId: ProviderSelection | undefined;
+    serviceId: string | undefined;
+    date: string | undefined;
+    providerIdsForAny?: readonly string[] | undefined;
+}): {
+    slots: {
+        startAt: string;
+        endAt: string;
+        remainingCapacity: number;
+    }[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+
+declare function useUnavailableDates(params: {
+    providerId: ProviderSelection | undefined;
+    serviceId: string | undefined;
+    month: string | undefined;
+    providerIdsForAny?: readonly string[] | undefined;
+}): {
+    unavailableDates: string[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+
+declare function minBookableDate(timeZone: string): Temporal.PlainDate;
+declare function maxBookableDate(futureBookingLimitDays: number, timeZone: string): Temporal.PlainDate;
+declare function formatCalendarDate(date: Temporal.PlainDate): string;
+declare function formatSlotDateTimeDual(iso: string, locale: string, primaryTz: string, secondaryTz: string | null): string;
+
+export { ANY_PROVIDER_ID, BookedSummary, type BookingAction, BookingApiError, BookingClient, type BookingClientOptions, type BookingConsents, BookingProvider, type BookingProviderProps, type BookingState, type BookingTheme, type BookingTimeDisplay, BookingWidget, ConfirmStep, CustomerForm, DatePicker, DisabledBooking as DisableBookingMessage, DisabledBooking, LegalGate, ProviderPicker, type ProviderSelection, ServicePicker, type TimeDisplayMode, TimeSlotPicker, type TranslationKey, allowsTimeDisplayToggle, bookingReducer, createBookingClient, createInitialBookingState, createTranslator, enCatalog, formatCalendarDate, formatSlotDateTimeDual, getCustomerTimezone, maxBookableDate, minBookableDate, resolveBusinessTimezone, resolveDisplayTimezone, shouldShowSecondaryTimezone, useAvailability, useBooking, useProviders, useServices, useTenantConfig, useUnavailableDates };