@perdieminc/time-slots 0.0.1

package/src/schedule/get-schedules.ts

@@ -0,0 +1,264 @@
+import { differenceInDays } from "date-fns";
+import {
+	DEFAULT_TIMEZONE,
+	FULFILLMENT_TYPES,
+	PLATFORM,
+	PREP_TIME_CADENCE,
+} from "../constants";
+import type {
+	CartItem,
+	FulfillmentSchedule,
+	GetSchedulesParams,
+	GetSchedulesResult,
+	PrepTimeSettings,
+	PreSaleConfig,
+} from "../types";
+import { getLocationsBusinessHoursOverrides } from "../utils/business-hours";
+import { getCateringPrepTimeConfig } from "../utils/catering";
+import { getPreSalePickupDates, overrideTimeZoneOnUTC } from "../utils/date";
+import { filterBusyTimesFromSchedule } from "../utils/schedule-filter";
+import { generateLocationFulfillmentSchedule } from "./location";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function deriveCartInfo(cartItems: CartItem[]) {
+	return {
+		hasPreSaleItem: cartItems.some((item) => item.preSale),
+		hasWeeklyPreSaleItem: cartItems.some((item) => item.weeklyPreSale),
+		categoryIds: Array.from(
+			new Set(
+				cartItems
+					.map((item) => item.internalCategoryId)
+					.filter((id): id is string => Boolean(id)),
+			),
+		),
+	};
+}
+
+function resolvePreSaleDates(
+	preSaleConfig: PreSaleConfig | undefined,
+	timezone: string,
+) {
+	return {
+		startDate: preSaleConfig?.due_start_date
+			? overrideTimeZoneOnUTC(preSaleConfig.due_start_date, timezone)
+			: new Date(),
+		endDate: preSaleConfig?.due_end_date
+			? overrideTimeZoneOnUTC(preSaleConfig.due_end_date, timezone)
+			: new Date(),
+	};
+}
+
+function getPreSaleHoursOverride(
+	preSaleConfig: PreSaleConfig | undefined,
+	hasPreSaleItem: boolean,
+) {
+	if (
+		preSaleConfig &&
+		!preSaleConfig.use_store_hours_due &&
+		hasPreSaleItem &&
+		preSaleConfig.due_start_time &&
+		preSaleConfig.due_end_time
+	) {
+		return [
+			{
+				startTime: preSaleConfig.due_start_time,
+				endTime: preSaleConfig.due_end_time,
+			},
+		];
+	}
+	return null;
+}
+
+function resolveStartDate(
+	zonedDueStartDate: Date,
+	hasPreSaleItem: boolean,
+): Date {
+	if (hasPreSaleItem) {
+		return new Date(Math.max(zonedDueStartDate.getTime(), Date.now()));
+	}
+	return new Date();
+}
+const WEEKDAY_KEYS = [0, 1, 2, 3, 4, 5, 6] as const;
+
+function addEstimatedDeliveryToWeekDays(
+	weekDayPrepTimes: Record<number, number>,
+	estimatedDeliveryMinutes: number,
+): Record<number, number> {
+	const result: Record<number, number> = {};
+	for (const day of WEEKDAY_KEYS) {
+		result[day] = (weekDayPrepTimes[day] ?? 0) + estimatedDeliveryMinutes;
+	}
+	return result;
+}
+
+/**
+ * Resolves prep time config: for catering flow uses cart-derived cadence/frequency;
+ * when fulfillment is DELIVERY, adds estimatedDeliveryMinutes to all weekday prep times.
+ */
+function resolvePrepTimeConfig(
+	prepTimeSettings: PrepTimeSettings,
+	cartItems: CartItem[],
+	isCateringFlow: boolean,
+	fulfillmentPreference: "PICKUP" | "DELIVERY" | "CURBSIDE",
+	timezone: string = DEFAULT_TIMEZONE,
+): PrepTimeSettings {
+	let resolved: PrepTimeSettings;
+
+	if (!isCateringFlow) {
+		const isDayCadence =
+			prepTimeSettings.prepTimeCadence === PREP_TIME_CADENCE.DAY;
+		resolved = {
+			...prepTimeSettings,
+			...(isDayCadence && { weekDayPrepTimes: {} }),
+		};
+	} else {
+		const cateringPrepTimeConfig = getCateringPrepTimeConfig({
+			items: cartItems,
+			prepTimeCadence: prepTimeSettings.prepTimeCadence,
+			prepTimeFrequency: prepTimeSettings.prepTimeFrequency,
+			timezone,
+		});
+		resolved = {
+			...prepTimeSettings,
+			...cateringPrepTimeConfig,
+		};
+	}
+	const { estimatedDeliveryMinutes = 0 } = prepTimeSettings;
+	if (
+		fulfillmentPreference === FULFILLMENT_TYPES.DELIVERY &&
+		estimatedDeliveryMinutes > 0
+	) {
+		const baseWeekDays = resolved.weekDayPrepTimes ?? {};
+		resolved = {
+			...resolved,
+			weekDayPrepTimes: addEstimatedDeliveryToWeekDays(
+				baseWeekDays,
+				prepTimeSettings.estimatedDeliveryMinutes ?? 0,
+			),
+		};
+	}
+
+	return resolved;
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export function getSchedules({
+	store,
+	locations,
+	cartItems,
+	fulfillmentPreference,
+	prepTimeSettings,
+	currentLocation,
+	isCateringFlow = false,
+	platform = PLATFORM.WEB,
+}: GetSchedulesParams): GetSchedulesResult {
+	const {
+		isAsapOrders,
+		isSameDayOrders,
+		max_future_order_days: daysCount = 7,
+		weeklyPreSaleConfig,
+		preSaleConfig,
+	} = store;
+
+	const cart = deriveCartInfo(cartItems);
+	const resolvedPrepTime = resolvePrepTimeConfig(
+		prepTimeSettings,
+		cartItems,
+		isCateringFlow,
+		fulfillmentPreference,
+		currentLocation?.timezone,
+	);
+	const {
+		gapInMinutes,
+		busyTimes: busyTimesByLocationId,
+		prepTimeFrequency,
+		prepTimeCadence,
+		weekDayPrepTimes,
+	} = resolvedPrepTime;
+
+	const busyTimes = busyTimesByLocationId?.[currentLocation.location_id] ?? [];
+
+	const businessHoursOverrides =
+		getLocationsBusinessHoursOverrides(store.businessHoursOverrides, locations)[
+			currentLocation.location_id
+		] ?? [];
+
+	const filterSchedule = (schedule: FulfillmentSchedule) =>
+		filterBusyTimesFromSchedule({
+			schedule,
+			busyTimes,
+			cartCategoryIds: cart.categoryIds,
+		});
+
+	// ── Weekly pre-sale path (early return) ─────────────────────────────────
+	if (
+		cart.hasWeeklyPreSaleItem &&
+		weeklyPreSaleConfig?.active &&
+		!isCateringFlow
+	) {
+		const weeklyPickupDates = getPreSalePickupDates(
+			weeklyPreSaleConfig?.pickup_days,
+			weeklyPreSaleConfig?.ordering_days,
+		);
+
+		if (weeklyPickupDates.length > 0) {
+			const schedule = generateLocationFulfillmentSchedule({
+				startDate: weeklyPickupDates[0],
+				location: currentLocation,
+				fulfillmentPreference,
+				businessHoursOverrides,
+				gapInMinutes,
+				daysCount: 7,
+				preSaleDates: weeklyPickupDates.map((d) => d.getDate()),
+				presalePickupWeekDays: weeklyPreSaleConfig.pickup_days,
+				platform,
+			});
+
+			return {
+				schedule: filterSchedule(schedule),
+				isWeeklyPreSaleAvailable: true,
+			};
+		}
+	}
+
+	// ── Main schedule path ──────────────────────────────────────────────────
+	const isPreSaleEnabled =
+		(preSaleConfig?.active ?? false) && cart.hasPreSaleItem && !isCateringFlow;
+	const preSaleDates = resolvePreSaleDates(
+		preSaleConfig,
+		currentLocation.timezone,
+	);
+	const preSaleHoursOverride = getPreSaleHoursOverride(
+		preSaleConfig,
+		cart.hasPreSaleItem,
+	);
+
+	const schedule = generateLocationFulfillmentSchedule({
+		startDate: resolveStartDate(preSaleDates.startDate, cart.hasPreSaleItem),
+		prepTimeFrequency,
+		prepTimeCadence,
+		location: currentLocation,
+		fulfillmentPreference,
+		businessHoursOverrides,
+		gapInMinutes,
+		daysCount: isPreSaleEnabled
+			? differenceInDays(preSaleDates.endDate, preSaleDates.startDate) + 1
+			: !isAsapOrders && !isSameDayOrders
+				? daysCount
+				: 1,
+		platform,
+
+		...(!isPreSaleEnabled && {
+			weekDayPrepTimes,
+		}),
+		...(preSaleHoursOverride && { preSaleHoursOverride }),
+		...(isPreSaleEnabled && { endDate: preSaleDates.endDate }),
+	});
+
+	return {
+		schedule: filterSchedule(schedule),
+		isWeeklyPreSaleAvailable: false,
+	};
+}

package/src/schedule/location.ts

@@ -0,0 +1,58 @@
+import { roundToNearestMinutes } from "date-fns";
+import { PLATFORM, PREP_TIME_CADENCE } from "../constants";
+import type {
+	FulfillmentSchedule,
+	GenerateLocationFulfillmentScheduleParams,
+} from "../types";
+import { getLocationBusinessHoursForFulfillment } from "../utils/business-hours";
+import { getNextAvailableDates } from "./available-dates";
+import { generateSchedule } from "./generate";
+
+export function generateLocationFulfillmentSchedule({
+	startDate,
+	prepTimeFrequency = 0,
+	prepTimeCadence = PREP_TIME_CADENCE.MINUTE,
+	weekDayPrepTimes,
+	location,
+	fulfillmentPreference,
+	businessHoursOverrides = [],
+	preSaleHoursOverride,
+	gapInMinutes,
+	daysCount = 1,
+	preSaleDates = [],
+	presalePickupWeekDays = [],
+	endDate = null,
+	platform = PLATFORM.WEB,
+}: GenerateLocationFulfillmentScheduleParams): FulfillmentSchedule {
+	const isDaysCadence = prepTimeCadence === PREP_TIME_CADENCE.DAY;
+	const businessHours = getLocationBusinessHoursForFulfillment(
+		location,
+		fulfillmentPreference,
+	);
+
+	const dates = getNextAvailableDates({
+		startDate,
+		businessHours,
+		businessHoursOverrides,
+		timeZone: location.timezone,
+		datesCount: daysCount,
+		preSaleDates,
+		endDate,
+		presalePickupWeekDays,
+		isDaysCadence,
+		platform,
+	});
+	// If prepTimeCadence is days, we need to skip opening days by prepTimeFrequency
+	const availableDates = isDaysCadence ? dates.slice(prepTimeFrequency) : dates;
+	return generateSchedule({
+		currentDate: roundToNearestMinutes(startDate),
+		weekDayPrepTimes,
+		timeZone: location.timezone,
+		dates: availableDates,
+		businessHours,
+		businessHoursOverrides,
+		preSaleHoursOverride,
+		gapInMinutes,
+		prepTimeCadence,
+	});
+}

package/src/types/business-hours.d.ts

@@ -0,0 +1,32 @@
+/** Raw business-hour record from the API (snake_case keys). */
+export interface BusinessHourInput {
+	day: number;
+	start_time: string;
+	end_time: string;
+}
+
+/** Normalised business-hour used internally (camelCase keys). */
+export interface BusinessHour {
+	day: number;
+	startTime: string;
+	endTime: string;
+}
+
+/** Raw business-hours override coming from the API. */
+export interface BusinessHoursOverrideInput {
+	all_locations?: boolean;
+	location_ids?: string[];
+	month: number;
+	day: number;
+	start_time: string | null;
+	end_time: string | null;
+	is_open?: boolean;
+}
+
+/** Normalised business-hours override. */
+export interface BusinessHoursOverrideOutput {
+	month: number;
+	day: number;
+	startTime: string | null;
+	endTime: string | null;
+}

package/src/types/common.d.ts

@@ -0,0 +1,5 @@
+export interface BusyTimeItem {
+	startTime: string;
+	endTime: string;
+	threshold?: { categoryIds?: string[] };
+}

package/src/types/get-schedules.d.ts

@@ -0,0 +1,122 @@
+import type { PrepTimeCadence } from "../constants";
+
+export interface GetCateringPrepTimeParams {
+	items: CartItem[];
+	prepTimeCadence?: PrepTimeCadence;
+	prepTimeFrequency?: number;
+	timezone?: string;
+}
+
+import type {
+	BusinessHoursOverrideInput,
+	BusinessHoursOverrideOutput,
+} from "./business-hours";
+import type { BusyTimeItem } from "./common";
+import type { FulfillmentPreference, LocationLike } from "./location";
+import type { FulfillmentSchedule, Platform } from "./schedule";
+
+// ── High-level input objects ────────────────────────────────────────────────
+
+export interface PreSaleConfig {
+	active: boolean;
+	due_start_date?: string | Date;
+	due_end_date?: string | Date;
+	use_store_hours_due?: boolean;
+	due_start_time?: string | null;
+	due_end_time?: string | null;
+}
+
+export interface WeeklyPreSaleConfig {
+	active: boolean;
+	pickup_days: number[];
+	ordering_days: number[];
+}
+
+export interface StoreConfig {
+	isAsapOrders: boolean;
+	isSameDayOrders: boolean;
+	max_future_order_days?: number;
+	businessHoursOverrides: BusinessHoursOverrideInput[];
+	preSaleConfig?: PreSaleConfig;
+	weeklyPreSaleConfig?: WeeklyPreSaleConfig;
+}
+export type CateringServiceType = {
+	min_quantity: number;
+	max_quantity: number;
+	serve_count: number;
+	prep_time: {
+		cadence: PrepTimeCadence;
+		frequency: number;
+	};
+};
+export interface CartItem {
+	preSale?: boolean;
+	weeklyPreSale?: boolean;
+	internalCategoryId?: string;
+	cateringService?: CateringServiceType;
+}
+export interface CateringPrepTimeResult {
+	prepTimeCadence: PrepTimeCadence;
+	prepTimeFrequency: number;
+	/** Only set when prepTimeCadence is not DAY (e.g. HOUR). */
+	weekDayPrepTimes?: Record<number, number>;
+}
+
+export interface PrepTimeSettings {
+	prepTimeInMinutes: number;
+	weekDayPrepTimes: Record<number, number>;
+	gapInMinutes: number;
+	busyTimes: Record<string, BusyTimeItem[]>;
+	prepTimeFrequency: number;
+	prepTimeCadence: PrepTimeCadence;
+	/** When fulfillment is DELIVERY, added to each weekday prep time so slots reflect when order is received. */
+	estimatedDeliveryMinutes?: number;
+}
+
+// ── getSchedules params / result ────────────────────────────────────────────
+
+export interface GetSchedulesParams {
+	store: StoreConfig;
+	locations: LocationLike[];
+	cartItems: CartItem[];
+	fulfillmentPreference: FulfillmentPreference;
+	prepTimeSettings: PrepTimeSettings;
+	currentLocation: LocationLike;
+	isCateringFlow?: boolean;
+	/** Platform for timezone handling in next-available-date logic. Default "web". */
+	platform?: Platform;
+}
+
+export interface GetSchedulesResult {
+	schedule: FulfillmentSchedule;
+	isWeeklyPreSaleAvailable: boolean;
+}
+
+// ── Legacy flat params (kept for backward-compat if needed) ─────────────────
+
+export interface InitScheduleParams {
+	isAsapOrders: boolean;
+	isSameDayOrders: boolean;
+	preSalePickupDays: number[];
+	isWeeklyPreSaleActive: boolean;
+	preSaleOrderingDays: number[];
+	locations: LocationLike[];
+	daysCount?: number;
+	fulfillmentPreference: FulfillmentPreference;
+	prepTimeInMinutes: number;
+	weekDayPrepTimes: Record<number, number>;
+	hasCartWeeklyPreSaleItem: boolean;
+	busyTimes: BusyTimeItem[];
+	cartCategoryIds: string[];
+	gapInMinutes: number;
+	businessHoursOverrides: Record<string, BusinessHoursOverrideOutput[]>;
+	currentLocation: LocationLike;
+}
+
+export interface InitScheduleResult {
+	businessHoursOverrides: Record<string, BusinessHoursOverrideOutput[]>;
+	locationId: string;
+	fulfillmentPreference: FulfillmentPreference;
+	schedule: FulfillmentSchedule;
+	isWeeklyPreSaleAvailable: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,34 @@
+export type {
+	BusinessHour,
+	BusinessHourInput,
+	BusinessHoursOverrideInput,
+	BusinessHoursOverrideOutput,
+} from "./business-hours";
+export type { BusyTimeItem } from "./common";
+export type {
+	CartItem,
+	CateringPrepTimeResult,
+	GetCateringPrepTimeParams,
+	GetSchedulesParams,
+	GetSchedulesResult,
+	InitScheduleParams,
+	InitScheduleResult,
+	PrepTimeSettings,
+	PreSaleConfig,
+	StoreConfig,
+	WeeklyPreSaleConfig,
+} from "./get-schedules";
+export type { FulfillmentPreference, LocationLike } from "./location";
+export type {
+	DaySchedule,
+	FulfillmentSchedule,
+	GenerateLocationFulfillmentScheduleParams,
+	GenerateScheduleParams,
+	GetNextAvailableDatesParams,
+	GetOpeningClosingTimeOnDateParams,
+	Platform,
+} from "./schedule";
+export type {
+	FilterBusyTimesFromScheduleParams,
+	MenuType,
+} from "./schedule-filter";

package/src/types/location.d.ts

@@ -0,0 +1,25 @@
+import type { BusinessHourInput } from "./business-hours";
+
+export type FulfillmentPreference = "PICKUP" | "DELIVERY" | "CURBSIDE";
+export type BusinessHourType = {
+	day: number;
+	start_time: string;
+	end_time: string;
+};
+export interface LocationLike {
+	location_id: string;
+	id?: string;
+	timezone: string;
+	pickup_hours?: BusinessHourInput[];
+	delivery_hours?: BusinessHourInput[];
+	curbside_hours?: {
+		use_pickup_hours?: boolean;
+		times?: BusinessHourInput[];
+	};
+	catering?: {
+		enabled: boolean | string;
+		pickup: Omit<BusinessHourType, "day">;
+		delivery: Omit<BusinessHourType, "day">;
+	};
+	[key: string]: unknown;
+}

package/src/types/schedule-filter.d.ts

@@ -0,0 +1,27 @@
+import type { BusyTimeItem } from "./common";
+import type { FulfillmentSchedule } from "./schedule";
+export type MenuTimeSlot = {
+	all_day: boolean;
+	end_time: string | null;
+	start_time: string | null;
+};
+
+export type MenuType = {
+	menu_id: string;
+	store_id: string;
+	location_id: string | null;
+	all_locations: boolean;
+	display_name: string;
+	description: string | null;
+	times: Record<string, MenuTimeSlot>;
+	category_ids: string[];
+	last_modified_by: string;
+	created_at: string;
+	updated_at: string;
+};
+
+export interface FilterBusyTimesFromScheduleParams {
+	schedule: FulfillmentSchedule;
+	busyTimes?: BusyTimeItem[];
+	cartCategoryIds?: string[];
+}

package/src/types/schedule.d.ts

@@ -0,0 +1,83 @@
+import type { PLATFORM } from "../constants";
+import type {
+	BusinessHour,
+	BusinessHoursOverrideOutput,
+} from "./business-hours";
+import type { FulfillmentPreference, LocationLike } from "./location";
+
+export interface DaySchedule {
+	date: Date;
+	originalStoreOpeningTime: Date | null;
+	originalStoreClosingTime: Date | null;
+	remainingShifts: number;
+	openingTime: Date;
+	closingTime: Date;
+	firstAvailableSlot: Date;
+	slots: Date[];
+	[key: string]: unknown;
+}
+
+export type FulfillmentSchedule = DaySchedule[];
+
+export interface GenerateScheduleParams {
+	currentDate?: Date;
+	prepTimeBehaviour?: number;
+	prepTimeInMinutes?: number;
+	weekDayPrepTimes?: Record<number, number>;
+	timeZone: string;
+	dates?: Date[];
+	businessHours?: BusinessHour[];
+	businessHoursOverrides?: BusinessHoursOverrideOutput[];
+	preSaleHoursOverride?: Array<{
+		startTime: string;
+		endTime: string;
+		month?: number;
+		day?: number;
+	}> | null;
+	gapInMinutes?: number;
+	prepTimeCadence?: PrepTimeCadence;
+}
+export type Platform = (typeof PLATFORM)[keyof typeof PLATFORM];
+export interface GetNextAvailableDatesParams {
+	startDate: Date;
+	timeZone: string;
+	businessHours: BusinessHour[];
+	businessHoursOverrides?: BusinessHoursOverrideOutput[];
+	datesCount?: number;
+	preSaleDates?: number[];
+	presalePickupWeekDays?: number[];
+	endDate?: Date | null;
+	isDaysCadence?: boolean;
+	/** Platform for timezone handling. Web uses @date-fns/tz; ios/android use timezone-support. Default "web". */
+	platform?: Platform;
+}
+
+export interface GenerateLocationFulfillmentScheduleParams {
+	startDate: Date;
+	prepTimeFrequency?: number;
+	prepTimeCadence?: PrepTimeCadence;
+	weekDayPrepTimes?: Record<number, number>;
+	location: LocationLike;
+	fulfillmentPreference: FulfillmentPreference;
+	/** Overrides for this location only (not keyed by location_id). */
+	businessHoursOverrides?: BusinessHoursOverrideOutput[];
+	preSaleHoursOverride?: Array<{
+		startTime: string;
+		endTime: string;
+		month?: number;
+		day?: number;
+	}> | null;
+	gapInMinutes?: number;
+	daysCount?: number;
+	preSaleDates?: number[];
+	presalePickupWeekDays?: number[];
+	endDate?: Date | null;
+	platform?: Platform;
+}
+
+export interface GetOpeningClosingTimeOnDateParams {
+	date?: Date;
+	businessHours?: BusinessHour[];
+	businessHoursOverrides?: BusinessHoursOverrideOutput[];
+	timeZone: string;
+}

package/src/types/timezone-support.d.ts

@@ -0,0 +1,31 @@
+declare module "timezone-support" {
+	export function findTimeZone(timezone: string): string;
+	export function getUnixTime(time: {
+		zone: string;
+		year: number;
+		month: number;
+		day: number;
+		hours: number | string;
+		minutes: number | string;
+		seconds: number | string;
+		milliseconds: number | string;
+	}): number;
+	export function getZonedTime(
+		date: Date | number,
+		timezone: string,
+	): {
+		zone: string;
+		year: number;
+		month: number;
+		day: number;
+		hours: number | string;
+		minutes: number | string;
+		seconds: number | string;
+		milliseconds: number | string;
+		dayOfWeek: number;
+	};
+	export function toZonedTime(
+		date: Date | number | string,
+		timezone: string,
+	): Date;
+}