@wix/headless-bookings 0.0.10 → 0.0.11

package/cjs/dist/services/service-list/service-list.js

@@ -0,0 +1,274 @@
+/**
+ * ServiceList Service - Reactive service list data management
+ * Handles querying and pagination of services list (NO selection management)
+ */
+import { defineService, implementService } from '@wix/services-definitions';
+import { SignalsServiceDefinition, } from '@wix/services-definitions/core-services/signals';
+import { queryServices } from '../../api/query-services/index.js';
+/**
+ * Booking app ID constant
+ */
+const BOOKING_APP_ID = '13d21c63-b5ec-5912-8397-c3a5ddb27a97';
+/**
+ * Default query limit
+ */
+const DEFAULT_QUERY_LIMIT = 100;
+/**
+ * Service definition for the ServiceList service
+ */
+export const ServiceListServiceDefinition = defineService('service-list');
+/**
+ * Implementation of the ServiceList service that manages reactive services list data.
+ * This service provides signals for services data, query options, pagination metadata
+ * (including hasNext flag), loading state, and error handling.
+ * It automatically re-fetches services when query options change.
+ *
+ * @example
+ * ```tsx
+ * import { ServiceListService, ServiceListServiceDefinition } from '@wix/bookings/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function ServicesComponent({ serviceListConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ServiceListServiceDefinition, ServiceListService.withConfig(serviceListConfig)]
+ *     ])}>
+ *       <ServicesDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function ServicesDisplay() {
+ *   const serviceListService = useService(ServiceListServiceDefinition);
+ *   const services = serviceListService.servicesSignal.get();
+ *   const isLoading = serviceListService.isLoadingSignal.get();
+ *   const error = serviceListService.errorSignal.get();
+ *   const pagingMetadata = serviceListService.pagingMetadataSignal.get();
+ *   const hasMore = serviceListService.hasMoreServicesSignal.get();
+ *
+ *   if (isLoading) return <div>Loading services...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {services.map(service => (
+ *         <div key={service._id}>
+ *           <h3>{service.name}</h3>
+ *           <p>{service.description}</p>
+ *         </div>
+ *       ))}
+ *       {hasMore && (
+ *         <button onClick={() => serviceListService.actions.loadMore(10)}>
+ *           Load More
+ *         </button>
+ *       )}
+ *       {pagingMetadata.hasNext && (
+ *         <span>More services available</span>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const ServiceListService = implementService.withConfig()(ServiceListServiceDefinition, ({ getService, config }) => {
+    let firstRun = true;
+    const signalsService = getService(SignalsServiceDefinition);
+    // Default appId to BOOKING_APP_ID if not provided
+    const appId = config.options?.appId ?? BOOKING_APP_ID;
+    // Check if services are provided (showcase mode vs query mode)
+    const hasInitialServices = config.services && config.services.length > 0;
+    // Initialize services signal - use empty array if not provided
+    const initialServices = config.services || [];
+    const servicesSignal = signalsService.signal(initialServices);
+    // Initialize query options based on mode:
+    // - If services provided: reset to defaults (appId only) - showcase mode
+    // - If no services: use full queryOptions from config - query mode
+    const initialQueryOptions = hasInitialServices
+        ? { appId } // Reset to defaults when services are provided
+        : {
+            appId,
+            filters: config.options?.filters,
+            sort: config.options?.sort,
+        };
+    // Initialize paging metadata separately (response data - doesn't trigger effect)
+    const initialPagingMetadata = config.options
+        ?.pagingMetadata || {
+        limit: DEFAULT_QUERY_LIMIT,
+        offset: 0,
+        count: initialServices.length,
+        hasNext: false,
+    };
+    // Ensure count and hasNext are set
+    if (!initialPagingMetadata.count) {
+        initialPagingMetadata.count = initialServices.length;
+    }
+    if (initialPagingMetadata.hasNext === undefined) {
+        initialPagingMetadata.hasNext = false;
+    }
+    // Query options signal - effect subscribes to this, changes trigger re-fetch
+    const queryOptionsSignal = signalsService.signal(initialQueryOptions);
+    // Paging metadata signal - updated after fetches, does NOT trigger effect
+    const pagingMetadataSignal = signalsService.signal(initialPagingMetadata);
+    const isLoadingSignal = signalsService.signal(false);
+    const errorSignal = signalsService.signal(null);
+    // Auto-query on queryOptions changes (client-side only)
+    // IMPORTANT: Only subscribes to queryOptionsSignal, NOT pagingMetadataSignal
+    if (typeof window !== 'undefined') {
+        signalsService.effect(async () => {
+            // CRITICAL: Read queryOptionsSignal to establish dependency
+            // Do NOT read pagingMetadataSignal here to avoid infinite loop
+            const queryOptions = queryOptionsSignal.get();
+            if (firstRun) {
+                firstRun = false;
+                // If we have initial services (showcase mode), don't query on first run
+                if (hasInitialServices) {
+                    return;
+                }
+            }
+            // Read paging metadata outside of dependency tracking for the fetch
+            const currentPaging = pagingMetadataSignal.get();
+            try {
+                isLoadingSignal.set(true);
+                errorSignal.set(null);
+                const result = await queryServices({
+                    appId: queryOptions.appId,
+                    filters: queryOptions.filters,
+                    pagingMetadata: {
+                        limit: currentPaging.limit,
+                        offset: 0, // Reset to first page when query options change
+                    },
+                    sort: queryOptions.sort,
+                });
+                servicesSignal.set(result.services);
+                // Update ONLY pagingMetadataSignal (not queryOptionsSignal) to avoid re-triggering effect
+                pagingMetadataSignal.set(result.pagingMetadata);
+            }
+            catch (error) {
+                errorSignal.set(error instanceof Error ? error.message : 'Unknown error');
+            }
+            finally {
+                isLoadingSignal.set(false);
+            }
+        });
+    }
+    firstRun = false;
+    const loadMoreCursor = async (count) => {
+        const currentQueryOptions = queryOptionsSignal.get();
+        // Calculate next page offset based on current services count
+        const currentServicesCount = servicesSignal.get().length;
+        const nextOffset = currentServicesCount;
+        const nextPaging = {
+            limit: count || DEFAULT_QUERY_LIMIT,
+            offset: nextOffset,
+            hasNext: false, // Will be updated after query
+        };
+        try {
+            isLoadingSignal.set(true);
+            errorSignal.set(null);
+            const result = await queryServices({
+                appId: currentQueryOptions.appId,
+                filters: currentQueryOptions.filters,
+                pagingMetadata: nextPaging,
+                sort: currentQueryOptions.sort,
+            });
+            // Append new services to existing ones
+            servicesSignal.set([...servicesSignal.get(), ...result.services]);
+            // Update ONLY pagingMetadataSignal (not queryOptionsSignal)
+            pagingMetadataSignal.set(result.pagingMetadata);
+        }
+        catch (error) {
+            errorSignal.set(error instanceof Error ? error.message : 'Unknown error');
+        }
+        finally {
+            isLoadingSignal.set(false);
+        }
+    };
+    return {
+        servicesSignal,
+        queryOptionsSignal,
+        pagingMetadataSignal,
+        isLoadingSignal,
+        errorSignal,
+        actions: {
+            loadMore: async (count) => {
+                await loadMoreCursor(count);
+            },
+            setQueryOptions: (options) => {
+                // Reset services and paging when query options change
+                servicesSignal.set([]);
+                pagingMetadataSignal.set({
+                    limit: pagingMetadataSignal.get().limit || DEFAULT_QUERY_LIMIT,
+                    offset: 0,
+                    count: 0,
+                    hasNext: false,
+                });
+                queryOptionsSignal.set(options);
+            },
+        },
+        hasMoreServicesSignal: signalsService.computed(() => {
+            const paging = pagingMetadataSignal.get();
+            // Use hasNext flag from pagingMetadata to determine if more services are available
+            return paging.hasNext ?? false;
+        }),
+    };
+});
+/**
+ * Load service list configuration for Server-Side Rendering (SSR).
+ * This function is designed to be called during the build or server-side rendering phase
+ * to pre-fetch services data before the React components are hydrated on the client.
+ * The returned config includes paging metadata with hasNext flag indicating if more services are available.
+ *
+ * @param options - Query options following QueryServicesRequest type, or a URL string (to be implemented)
+ * @returns A promise that resolves to either a success result with the config or an error result
+ *
+ * @example
+ * ```ts
+ * // In an Astro page or API route
+ * import { loadServiceListServiceInitialData } from '@wix/bookings/services';
+ *
+ * // Load with query options
+ * const serviceListResult = await loadServiceListServiceInitialData({
+ *   appId: '13d21c63-b5ec-5912-8397-c3a5ddb27a97',
+ *   pagingMetadata: { limit: 20, offset: 0 },
+ * });
+ *
+ * if (serviceListResult.type === 'error') {
+ *   console.error('Failed to load services:', serviceListResult.error);
+ *   return Astro.redirect('/500');
+ * }
+ *
+ * const serviceListConfig = serviceListResult.config;
+ *
+ * // Check if more services are available
+ * if (serviceListConfig.options?.pagingMetadata?.hasNext) {
+ *   // More services can be loaded
+ * }
+ * ```
+ */
+export async function loadServiceListServiceInitialData(options) {
+    try {
+        const result = await queryServices({
+            appId: options.appId,
+            filters: options.filters,
+            pagingMetadata: options.pagingMetadata,
+            sort: options.sort,
+        });
+        return {
+            type: 'success',
+            config: {
+                services: result.services,
+                options: {
+                    ...options,
+                    pagingMetadata: result.pagingMetadata,
+                },
+            },
+        };
+    }
+    catch (error) {
+        console.error('Failed to load service list config:', error);
+        return {
+            type: 'error',
+            error: error instanceof Error ? error : new Error('Unknown error'),
+        };
+    }
+}

package/cjs/dist/utils/dateAndTime.d.ts

@@ -0,0 +1,2 @@
+export declare const formatDate: (date: Date) => string;
+export declare const formatDuration: (minutes: number) => string;

package/cjs/dist/utils/dateAndTime.js

@@ -0,0 +1,18 @@
+export const formatDate = (date) => {
+    return date.toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+    });
+};
+export const formatDuration = (minutes) => {
+    if (minutes < 60) {
+        return `${minutes} min`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    if (mins === 0) {
+        return `${hours} hour${hours > 1 ? 's' : ''}`;
+    }
+    return `${hours}h ${mins}m`;
+};

package/cjs/dist/utils/money.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Money utility functions for converting between SDK Money types and MoneyData
+ */
+import type { MoneyData } from '@wix/headless-components/react';
+/**
+ * Converts SDK Money format to MoneyData format
+ *
+ * @param sdkMoney - The SDK money object with value, currency, and optional formattedValue
+ * @returns MoneyData object with amount and currency, or null if conversion fails
+ *
+ * @example
+ * ```ts
+ * const money = convertToMoneyData({ value: "25.50", currency: "USD" });
+ * // Returns: { amount: 25.50, currency: "USD" }
+ * ```
+ */
+export declare function convertToMoneyData(sdkMoney: {
+    value?: string;
+    currency?: string;
+    formattedValue?: string | null;
+} | undefined): MoneyData | null;

package/cjs/dist/utils/money.js

@@ -0,0 +1,34 @@
+/**
+ * Money utility functions for converting between SDK Money types and MoneyData
+ */
+/**
+ * Converts SDK Money format to MoneyData format
+ *
+ * @param sdkMoney - The SDK money object with value, currency, and optional formattedValue
+ * @returns MoneyData object with amount and currency, or null if conversion fails
+ *
+ * @example
+ * ```ts
+ * const money = convertToMoneyData({ value: "25.50", currency: "USD" });
+ * // Returns: { amount: 25.50, currency: "USD" }
+ * ```
+ */
+export function convertToMoneyData(sdkMoney) {
+    if (!sdkMoney)
+        return null;
+    const priceValue = sdkMoney.value;
+    const currency = sdkMoney.currency || 'USD';
+    // Convert price value to number
+    let amount = undefined;
+    if (typeof priceValue === 'string') {
+        const parsed = parseFloat(priceValue);
+        amount = !isNaN(parsed) ? parsed : undefined;
+    }
+    else if (typeof priceValue === 'number') {
+        amount = priceValue;
+    }
+    if (amount !== undefined && !isNaN(amount) && amount >= 0) {
+        return { amount, currency };
+    }
+    return null;
+}

package/dist/api/index.d.ts

@@ -1,5 +1,14 @@
 /**
  * API Layer
  * Exports all Wix Bookings API functions
+ *
+ * @module API
+ */
+export { getServiceById, getServiceBySlug, queryServices, type PagingMetadata, type ServiceListFilters, type QueryServicesRequest, } from './query-services/index.js';
+/**
+ * PagingMetadata includes:
+ * - limit: Number of items per page
+ * - offset: Number of items to skip
+ * - count: Number of items returned in the current page
+ * - hasNext: Whether there are more services available to load
  */
-export { getServiceById, getServiceBySlug } from './query-service/index.js';

package/dist/api/index.js

@@ -1,5 +1,14 @@
 /**
  * API Layer
  * Exports all Wix Bookings API functions
+ *
+ * @module API
+ */
+export { getServiceById, getServiceBySlug, queryServices, } from './query-services/index.js';
+/**
+ * PagingMetadata includes:
+ * - limit: Number of items per page
+ * - offset: Number of items to skip
+ * - count: Number of items returned in the current page
+ * - hasNext: Whether there are more services available to load
  */
-export { getServiceById, getServiceBySlug } from './query-service/index.js';

package/dist/api/query-services/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Query Services API
+ * Fetches single or multiple services with pagination and sorting
+ */
+import { services } from '@wix/bookings';
+import type { services as servicesTypes } from '@wix/bookings';
+/**
+ * Paging metadata from query services response.
+ * Extends the SDK's Paging type with hasNext flag to indicate if more services are available.
+ */
+export type PagingMetadata = services.Paging & {
+    /** Number of items returned in the current page */
+    count?: number;
+    /** Whether there are more services available to load */
+    hasNext?: boolean;
+};
+/**
+ * Service list filters
+ */
+export interface ServiceListFilters {
+    serviceIds?: string[];
+    categoryIds?: string[];
+    locationIds?: string[];
+    staffMemberIds?: string[];
+}
+/**
+ * Query services request options
+ * Used internally by ServiceListService to track query state
+ */
+export interface QueryServicesRequest {
+    appId: string;
+    filters?: ServiceListFilters;
+    pagingMetadata?: PagingMetadata;
+    sort?: services.Sorting[];
+}
+/**
+ * Fetches a service by its ID
+ * @param id - The service ID
+ * @param appId - Optional app ID, defaults to booking app ID
+ * @returns Object containing the service or null if not found
+ */
+export declare const getServiceById: (id: string, appId?: string) => Promise<{
+    service: servicesTypes.Service | null;
+}>;
+/**
+ * Fetches a service by its slug
+ * @param slug - The service slug
+ * @param appId - Optional app ID, defaults to booking app ID
+ * @returns Object containing the service or null if not found
+ */
+export declare const getServiceBySlug: (slug: string, appId?: string) => Promise<{
+    service: servicesTypes.Service | null;
+}>;
+/**
+ * Query services with pagination and sorting.
+ * Returns services array and paging metadata including hasNext flag.
+ *
+ * @param params - Query parameters including appId, filters, paging metadata, and sort options
+ * @returns Promise that resolves to services array and paging metadata with hasNext flag
+ *
+ * @example
+ * ```ts
+ * const { services, pagingMetadata } = await queryServices({
+ *   appId: '13d21c63-b5ec-5912-8397-c3a5ddb27a97',
+ *   filters: { serviceIds: ['service1', 'service2'] },
+ *   pagingMetadata: { limit: 20, offset: 0 },
+ *   sort: [{ fieldName: 'name', order: 'ASC' }]
+ * });
+ *
+ * if (pagingMetadata.hasNext) {
+ *   // Load more services
+ * }
+ * ```
+ */
+export declare function queryServices({ appId, filters, pagingMetadata, sort, }: QueryServicesRequest): Promise<{
+    services: servicesTypes.Service[];
+    pagingMetadata: PagingMetadata;
+}>;

package/dist/api/query-services/index.js

@@ -0,0 +1,137 @@
+/**
+ * Query Services API
+ * Fetches single or multiple services with pagination and sorting
+ */
+import { services } from '@wix/bookings';
+/**
+ * Booking app ID constant
+ */
+const BOOKING_APP_ID = '13d21c63-b5ec-5912-8397-c3a5ddb27a97';
+/**
+ * Fetches a service by its ID
+ * @param id - The service ID
+ * @param appId - Optional app ID, defaults to booking app ID
+ * @returns Object containing the service or null if not found
+ */
+export const getServiceById = async (id, appId) => {
+    try {
+        const finalAppId = appId ?? BOOKING_APP_ID;
+        // Query services where _id equals the provided id and appId matches
+        const query = services.queryServices({
+            conditionalFields: ['STAFF_MEMBER_DETAILS'],
+        });
+        const result = await query
+            .eq('_id', id)
+            // @ts-ignore
+            .eq('appId', finalAppId)
+            .limit(1)
+            .find();
+        const service = result.items?.[0] || null;
+        return { service };
+    }
+    catch (error) {
+        console.error(`Failed to load service for id "${id}":`, error);
+        return { service: null };
+    }
+};
+/**
+ * Fetches a service by its slug
+ * @param slug - The service slug
+ * @param appId - Optional app ID, defaults to booking app ID
+ * @returns Object containing the service or null if not found
+ */
+export const getServiceBySlug = async (slug, appId) => {
+    try {
+        const finalAppId = appId ?? BOOKING_APP_ID;
+        // Query services where mainSlug.name equals the provided slug and appId matches
+        const query = services.queryServices({
+            conditionalFields: ['STAFF_MEMBER_DETAILS'],
+        });
+        const result = await query
+            .eq('mainSlug.name', slug)
+            // @ts-ignore
+            .eq('appId', finalAppId)
+            .limit(1)
+            .find();
+        const service = result.items?.[0] || null;
+        return { service };
+    }
+    catch (error) {
+        console.error(`Failed to load service for slug "${slug}":`, error);
+        return { service: null };
+    }
+};
+/**
+ * Builds a QueryServicesRequest from appId, filters, paging, and sort
+ * @param params - Parameters including appId, filters, paging, and sort
+ * @returns QueryServicesRequest object
+ */
+const buildServicesQueryRequest = ({ appId, filters, paging, sort, }) => {
+    const filter = {
+        appId,
+    };
+    // Add serviceIds filter if provided
+    if (filters?.serviceIds && filters.serviceIds.length > 0) {
+        filter['_id'] = { $in: filters.serviceIds };
+    }
+    // Add other filters as they are implemented in future phases
+    // categoryIds, locationIds, staffMemberIds to be added later
+    const query = {
+        filter: Object.keys(filter).length > 0 ? filter : undefined,
+        paging: paging || {
+            limit: 100, // Default limit
+        },
+        sort,
+    };
+    return { query };
+};
+/**
+ * Query services with pagination and sorting.
+ * Returns services array and paging metadata including hasNext flag.
+ *
+ * @param params - Query parameters including appId, filters, paging metadata, and sort options
+ * @returns Promise that resolves to services array and paging metadata with hasNext flag
+ *
+ * @example
+ * ```ts
+ * const { services, pagingMetadata } = await queryServices({
+ *   appId: '13d21c63-b5ec-5912-8397-c3a5ddb27a97',
+ *   filters: { serviceIds: ['service1', 'service2'] },
+ *   pagingMetadata: { limit: 20, offset: 0 },
+ *   sort: [{ fieldName: 'name', order: 'ASC' }]
+ * });
+ *
+ * if (pagingMetadata.hasNext) {
+ *   // Load more services
+ * }
+ * ```
+ */
+export async function queryServices({ appId, filters, pagingMetadata, sort, }) {
+    try {
+        const queryRequest = buildServicesQueryRequest({
+            appId,
+            filters,
+            paging: pagingMetadata,
+            sort,
+        });
+        // Call queryServices with QueryServicesRequest and execute the query
+        const result = await services.queryServices(queryRequest).find();
+        // Construct PagingMetadata from result properties
+        // Includes count (number of items returned) and hasNext (whether more items are available)
+        const resultPagingMetadata = {
+            limit: pagingMetadata?.limit,
+            offset: pagingMetadata?.offset,
+            count: result.items.length,
+            hasNext: (result?.totalCount || 0) >
+                result.items.length + (pagingMetadata?.offset || 0),
+        };
+        return {
+            services: result.items || [],
+            pagingMetadata: resultPagingMetadata,
+        };
+    }
+    catch (error) {
+        console.error('Failed to query services:', error);
+        throw error;
+    }
+}

package/dist/react/core/location/Location.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Core Location Component - Parses service location data
+ * Handles business, custom, and customer location types
+ * Converts location data to Address component format
+ */
+import React from 'react';
+import { services } from '@wix/bookings';
+import type { AddressData as AddressDataType } from '@wix/headless-components/react';
+/**
+ * Re-export AddressData type from Address component for convenience
+ */
+export type AddressData = AddressDataType;
+/**
+ * Location render props passed to children
+ */
+export interface LocationRenderProps {
+    locationType: services.LocationType;
+    address: AddressData | null;
+}
+/**
+ * Props for the core Location component
+ */
+export interface LocationProps {
+    location: NonNullable<services.Service['locations']>[number];
+    children: (props: LocationRenderProps) => React.ReactNode;
+}
+/**
+ * Core Location component that parses service location data
+ * and provides location type and address data to children
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CoreLocation location={serviceLocation}>
+ *   {({ locationType, address }) => (
+ *     <div>
+ *       <span>Type: {locationType}</span>
+ *       {address && <Address.Root address={address}><Address.Formatted /></Address.Root>}
+ *     </div>
+ *   )}
+ * </CoreLocation>
+ * ```
+ */
+export declare function Location(props: LocationProps): React.ReactNode;