@proveanything/smartlinks 2.0.70 → 2.0.71

package/dist/types/asset.d.ts

@@ -39,8 +39,26 @@ export interface Asset {
     proofId: string | null;
     /** App that owns this asset, e.g. 'homepage' */
     appId: string | null;
-    /** CDN URL of the original file */
+    /**
+     * Address of the asset's current **file**. Versioned: it changes when the file is replaced (the old one moves
+     * to `versions[]`). For static content, use `assetUrl` instead.
+     */
     url: string;
+    /**
+     * The **asset's** own address: `https://cdn.smartlinks.app/sites/{collectionId}/a/{assetId}`.
+     *
+     * It's the address of the asset (the named thing, e.g. "Hero image"), not of one file. It always serves the
+     * asset's current file: replace the file and everything using `assetUrl` shows the new one, with no redeploy
+     * and no extra API call (the CDN copy is cleared; browsers re-check within a minute). Deleting the asset takes
+     * the address down; restoring it brings it back.
+     *
+     * Use it in static content: a built site's HTML and CSS, emails, banners. Product and collection images are
+     * different: they are references in the record (`AssetRef`), and a new image is a record change.
+     *
+     * `null` for an outside link, and for an asset made before asset addresses existed until it's given one
+     * ({@link asset.ensureAssetUrl}).
+     */
+    assetUrl: string | null;
     /**
      * CDN URL of the WebP thumbnail (max 512px longest edge, no crop).
      * Always .webp — null until thumbnail generation has run.
@@ -336,6 +354,12 @@ export interface CreateResumableUploadOptions {
      * uploads. When provided, the public resumable route is used.
      */
     token?: string;
+    /**
+     * Replace this asset's file instead of creating a new asset (admin). The id and `assetUrl` stay the same,
+     * so everything using `assetUrl` shows the new file; the previous file goes into `versions[]`. Any size —
+     * use this to replace a large video.
+     */
+    replaceAssetId?: string;
 }
 export interface ResumableStartOptions {
     /** Progress callback (0-100), driven by bytes confirmed by storage. */

package/dist/types/bookings.d.ts

@@ -0,0 +1,301 @@
+import type { PaginatedResponse } from './appObjects.js';
+export type BookingStatus = 'held' | 'pending' | 'confirmed' | 'completed' | 'cancelled' | 'no_show' | 'waitlisted';
+export type BookingVisibility = 'public' | 'owner' | 'admin';
+/** A claim on a resource's time: seats on a slot (`capacity`) or exclusive time (`exclusive`). */
+export interface BookingAllocation {
+    id: string;
+    bookingId: string | null;
+    slotId: string | null;
+    resourceType: string;
+    resourceId: string;
+    /** The time actually blocked — buffers included. */
+    startsAt: string;
+    endsAt: string;
+    quantity: number;
+    mode: 'exclusive' | 'capacity';
+    active: boolean;
+    sourceSystem?: string | null;
+    data: Record<string, any>;
+}
+export interface Booking {
+    id: string;
+    collectionId: string;
+    appId: string;
+    visibility: BookingVisibility;
+    /** Admin / owner callers only. */
+    contactId?: string;
+    status: BookingStatus;
+    /** The customer-visible time (buffers excluded). */
+    startsAt: string;
+    endsAt: string;
+    timezone?: string | null;
+    quantity: number;
+    holdExpiresAt?: string | null;
+    /** Platform flags, e.g. 'hold_expired'. */
+    flags: string[];
+    /** 'admin' | 'owner' | 'hold_expired' | an app-defined reason. */
+    cancelReason?: string | null;
+    idempotencyKey?: string | null;
+    seriesId?: string | null;
+    ref?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
+    productId?: string | null;
+    proofId?: string;
+    parentType?: string | null;
+    parentId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    cancelledAt?: string | null;
+    data: Record<string, any>;
+    /** Owner + admin only. */
+    owner?: Record<string, any>;
+    /** Admin only. */
+    admin?: Record<string, any>;
+    allocations: BookingAllocation[];
+    /**
+     * Anonymous public creates only, when the app enables `publicCreate.bookings.anonymous.edit.editToken`.
+     * Returned ONCE — store it to let the guest view / cancel / move / confirm their booking.
+     */
+    editToken?: string;
+}
+export interface BookingSlot {
+    id: string;
+    collectionId: string;
+    appId: string;
+    visibility: BookingVisibility;
+    resourceType?: string | null;
+    resourceId?: string | null;
+    startsAt: string;
+    endsAt: string;
+    timezone?: string | null;
+    capacity: number;
+    booked: number;
+    /** capacity - booked */
+    remaining: number;
+    perContactLimit?: number | null;
+    status: 'open' | 'closed' | 'cancelled';
+    seriesId?: string | null;
+    ref?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
+    productId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    data: Record<string, any>;
+    owner?: Record<string, any>;
+    admin?: Record<string, any>;
+}
+/** One claim in a booking request: seats on a slot, or exclusive time on a resource. */
+export type BookingClaimInput = {
+    slotId: string;
+    quantity?: number;
+} | {
+    resourceType: string;
+    resourceId: string;
+    /** Defaults to the booking's startsAt / endsAt. */
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    /** Admin only (public bookings take buffers from the app's rules). Minutes. */
+    bufferBefore?: number;
+    bufferAfter?: number;
+};
+export interface CreateBookingInput {
+    /** Seats on one slot … */
+    slotId?: string;
+    quantity?: number;
+    /** … or exclusive time on one resource … */
+    resourceType?: string;
+    resourceId?: string;
+    resource?: {
+        type: string;
+        id: string;
+    };
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    /** … or several claims at once (all-or-nothing): a stylist and a chair, two tables. */
+    allocations?: BookingClaimInput[];
+    /** Admin only — public bookings get the status the app's rules enforce. Default 'confirmed'. */
+    status?: 'held' | 'pending' | 'confirmed' | 'waitlisted';
+    /** For status 'held' (admin: default 15, max 1440). */
+    holdMinutes?: number;
+    /** Admin only: blocked time around an exclusive claim, in minutes. */
+    bufferBefore?: number;
+    bufferAfter?: number;
+    /** A retried create with the same key returns the first booking instead of booking twice. */
+    idempotencyKey?: string;
+    /** Admin only — public bookings use the signed-in caller's contact. */
+    contactId?: string;
+    timezone?: string;
+    visibility?: BookingVisibility;
+    ref?: string;
+    customId?: string;
+    sourceSystem?: string;
+    productId?: string;
+    proofId?: string;
+    parentType?: string;
+    parentId?: string;
+    seriesId?: string;
+    data?: Record<string, any>;
+    owner?: Record<string, any>;
+    /** Admin only. */
+    admin?: Record<string, any>;
+}
+export interface UpdateBookingInput {
+    data?: Record<string, any>;
+    owner?: Record<string, any>;
+    admin?: Record<string, any>;
+    visibility?: BookingVisibility;
+    ref?: string;
+    timezone?: string;
+    productId?: string;
+    proofId?: string;
+    contactId?: string;
+    sourceSystem?: string;
+    customId?: string;
+    flags?: string[];
+}
+export interface MoveBookingInput {
+    slotId?: string;
+    resourceType?: string;
+    resourceId?: string;
+    resource?: {
+        type: string;
+        id: string;
+    };
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    allocations?: BookingClaimInput[];
+    bufferBefore?: number;
+    bufferAfter?: number;
+}
+export interface BookingListQueryParams {
+    status?: string;
+    contactId?: string;
+    slotId?: string;
+    resourceType?: string;
+    resourceId?: string;
+    /** Bookings overlapping [from, to). */
+    from?: string | Date;
+    to?: string | Date;
+    ref?: string;
+    customId?: string;
+    sourceSystem?: string;
+    productId?: string;
+    seriesId?: string;
+    /** Default 'starts_at:asc'. */
+    sort?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateSlotInput {
+    startsAt: string | Date;
+    endsAt: string | Date;
+    capacity: number;
+    perContactLimit?: number;
+    /** What the slot runs on (an instructor, a room) … */
+    resourceType?: string;
+    resourceId?: string;
+    /** … and whether the slot blocks that resource's time (no double-booking across slots). */
+    blockResource?: boolean;
+    status?: 'open' | 'closed' | 'cancelled';
+    timezone?: string;
+    visibility?: BookingVisibility;
+    seriesId?: string;
+    ref?: string;
+    customId?: string;
+    sourceSystem?: string;
+    productId?: string;
+    data?: Record<string, any>;
+    owner?: Record<string, any>;
+    admin?: Record<string, any>;
+}
+export type UpdateSlotInput = Partial<Omit<CreateSlotInput, 'blockResource' | 'seriesId' | 'resourceType' | 'resourceId'>>;
+export interface SlotListQueryParams {
+    status?: string;
+    /** Only slots with places left. */
+    available?: boolean;
+    from?: string | Date;
+    to?: string | Date;
+    resourceType?: string;
+    resourceId?: string;
+    productId?: string;
+    seriesId?: string;
+    ref?: string;
+    customId?: string;
+    sort?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateBlockInput {
+    resourceType: string;
+    resourceId: string;
+    startsAt: string | Date;
+    endsAt: string | Date;
+    sourceSystem?: string;
+    data?: Record<string, any>;
+}
+export interface BlockListQueryParams {
+    resourceType?: string;
+    resourceId?: string;
+    from?: string | Date;
+    to?: string | Date;
+    limit?: number;
+    offset?: number;
+}
+/** A resource reference: `{ type, id }` or the string form `'record:staff-1'`. */
+export type BookingResourceRef = {
+    type: string;
+    id: string;
+} | string;
+export interface FreeBusyQuery {
+    resources: BookingResourceRef[];
+    from: string | Date;
+    to: string | Date;
+}
+export interface FreeBusyInterval {
+    start: string;
+    end: string;
+}
+export interface FreeBusyResponse {
+    from: string;
+    to: string;
+    resources: Array<{
+        resourceType: string;
+        resourceId: string;
+        busy: FreeBusyInterval[];
+    }>;
+}
+/** Public calls on a booking made by an anonymous guest: pass the edit token returned at create. */
+export interface BookingAccessOptions {
+    editToken?: string;
+}
+export type BookingList = PaginatedResponse<Booking>;
+export type SlotList = PaginatedResponse<BookingSlot>;
+export type BlockList = PaginatedResponse<BookingAllocation>;
+/** Error codes a booking call can fail with (HTTP 409 unless noted). */
+export type BookingErrorCode = 'SLOT_FULL' | 'SLOT_CLOSED' | 'RESOURCE_TAKEN' | 'PER_CONTACT_LIMIT' | 'QUANTITY_LIMIT' | 'HOLD_EXPIRED' | 'INVALID_STATE' | 'SLOT_OVERBOOKED' | 'SLOT_HAS_BOOKINGS' | 'TOO_SOON' | 'TOO_FAR_AHEAD' | 'IN_THE_PAST' | 'DURATION_NOT_ALLOWED' | 'OUTSIDE_SCHEDULE' | 'NO_SCHEDULE' | 'SCHEDULE_INVALID' | 'CUTOFF_PASSED' | 'FORBIDDEN' | 'NOT_FOUND' | 'BAD_REQUEST';
+export interface ScheduleHours {
+    /** 'HH:MM' (24h) */
+    start: string;
+    /** 'HH:MM' (24h); '24:00' allowed. Hours never cross midnight — split them. */
+    end: string;
+}
+export type ScheduleDay = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+export interface ScheduleOverride {
+    /** One date (YYYY-MM-DD) … */
+    date?: string;
+    /** … or an inclusive range. */
+    from?: string;
+    to?: string;
+    /** [] = closed */
+    hours: ScheduleHours[];
+}
+export interface StandardSchedule {
+    /** IANA timezone, e.g. 'Europe/London'. */
+    timezone: string;
+    /** A missing day is closed. */
+    weekly?: Partial<Record<ScheduleDay, ScheduleHours[]>>;
+    /** Dated exceptions; the last matching one wins over `weekly`. */
+    overrides?: ScheduleOverride[];
+}

package/dist/types/bookings.js

@@ -0,0 +1,3 @@
+// src/types/bookings.ts
+// Generic booking objects (Slots, Bookings, Allocations) — see docs/bookings.md.
+export {};

package/dist/types/index.d.ts

@@ -37,6 +37,7 @@ export * from "./iframeResponder.js";
 export * from "./ai.js";
 export * from "./appManifest.js";
 export * from "./appObjects.js";
+export * from "./bookings.js";
 export * from "./loyalty.js";
 export * from "./translations.js";
 export * from "./integrations.js";

package/dist/types/index.js

@@ -39,6 +39,7 @@ export * from "./iframeResponder.js";
 export * from "./ai.js";
 export * from "./appManifest.js";
 export * from "./appObjects.js";
+export * from "./bookings.js";
 export * from "./loyalty.js";
 export * from "./translations.js";
 export * from "./integrations.js";

package/dist/utils/freeTimes.d.ts

@@ -0,0 +1,57 @@
+import type { StandardSchedule, FreeBusyInterval } from '../types/bookings.js';
+export interface TimeInterval {
+    /** epoch ms (UTC) */
+    start: number;
+    /** epoch ms (UTC) */
+    end: number;
+}
+/** Throws a readable Error when `schedule` isn't the standard shape. */
+export declare function validateSchedule(schedule: StandardSchedule): true;
+/** The UTC instant (ms) of local date `ymd` + `minutes` past midnight in `tz`. */
+export declare function zonedToUtc(ymd: string, minutes: number, tz: string): number;
+/** The schedule's open hours overlapping [from, to), as merged UTC intervals. */
+export declare function openIntervals(schedule: StandardSchedule, from: string | number | Date, to: string | number | Date): TimeInterval[];
+/** True when [start, end) lies entirely inside the schedule's open hours. */
+export declare function withinSchedule(schedule: StandardSchedule, start: string | number | Date, end: string | number | Date): boolean;
+/** `open` minus `busy` (both lists of intervals). */
+export declare function subtractIntervals(open: TimeInterval[], busy: TimeInterval[]): TimeInterval[];
+export interface FreeTimesOptions {
+    /** Open hours: a standard schedule, or open intervals you've worked out yourself. */
+    hours: StandardSchedule | TimeInterval[];
+    /** Busy intervals, e.g. `resources[i].busy` from bookings.freebusy (ISO strings or ms). */
+    busy?: Array<FreeBusyInterval | TimeInterval>;
+    from: string | number | Date;
+    to: string | number | Date;
+    /** Appointment length, minutes. */
+    duration: number;
+    /** Minutes between candidate start times. Default: `duration`. */
+    step?: number;
+    /** Blocked time around each appointment, minutes (must also fit in a free gap). */
+    bufferBefore?: number;
+    bufferAfter?: number;
+    /** No start sooner than this many minutes from `now`. */
+    minNotice?: number;
+    /** "Now", for notice (default Date.now()). */
+    now?: number;
+    /**
+     * Whether buffers must also fall inside opening hours. Default false: a buffer may run past
+     * closing (cleaning up after the last appointment) but never into busy time.
+     */
+    buffersWithinHours?: boolean;
+}
+export interface FreeTimeSlot {
+    /** ISO start of the appointment (buffers excluded). */
+    start: string;
+    end: string;
+}
+/**
+ * Bookable start times: open hours minus busy time, stepped at `step`, each long enough for
+ * `duration` (+ buffers against busy time), not sooner than `minNotice`.
+ *
+ *   const fb = await bookings.freebusy(collectionId, appId, { resources: ['record:sam'], from, to }, true)
+ *   const times = utils.freeTimes({ hours: samsSchedule, busy: fb.resources[0].busy, from, to, duration: 30 })
+ *
+ * Start times are aligned to `step` from local midnight in the schedule's timezone (so 30-minute
+ * steps land on :00 and :30), or from each open interval's start when you pass intervals.
+ */
+export declare function freeTimes(opts: FreeTimesOptions): FreeTimeSlot[];

package/dist/utils/freeTimes.js

@@ -0,0 +1,206 @@
+// src/utils/freeTimes.ts
+// Free-time maths for booking apps — pure, no I/O (docs/bookings.md, "Schedules belong to the app").
+//
+// Your app owns its schedule and its booking policy; this helper just does the fiddly part:
+// turning local wall-clock opening hours into UTC intervals (daylight-saving safe), subtracting busy
+// time (from bookings.freebusy), and stepping out bookable start times with durations, buffers and
+// notice. Use it or ignore it — the platform never reads your schedule, except a schedule in this
+// standard shape when your app allows public free-form booking with `rules.schedule: true`.
+const DAY_KEYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const HHMM = /^([01]\d|2[0-4]):([0-5]\d)$/;
+const YMD = /^\d{4}-\d{2}-\d{2}$/;
+function minutesOf(hhmm) {
+    const m = HHMM.exec(hhmm || '');
+    if (!m)
+        throw new Error(`Invalid time "${hhmm}" (use HH:MM)`);
+    const mins = Number(m[1]) * 60 + Number(m[2]);
+    if (mins > 24 * 60)
+        throw new Error(`Invalid time "${hhmm}"`);
+    return mins;
+}
+/** Throws a readable Error when `schedule` isn't the standard shape. */
+export function validateSchedule(schedule) {
+    if (!schedule || typeof schedule !== 'object')
+        throw new Error('Schedule must be an object');
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: schedule.timezone });
+    }
+    catch (_a) {
+        throw new Error('Schedule needs a valid IANA timezone');
+    }
+    if (!schedule.timezone)
+        throw new Error('Schedule needs a valid IANA timezone');
+    const check = (hours, where) => {
+        if (!Array.isArray(hours))
+            throw new Error(`${where}: hours must be an array`);
+        for (const h of hours)
+            if (minutesOf(h.end) <= minutesOf(h.start))
+                throw new Error(`${where}: end must be after start (split hours that cross midnight)`);
+    };
+    for (const [day, hours] of Object.entries(schedule.weekly || {})) {
+        if (!DAY_KEYS.includes(day))
+            throw new Error(`Unknown day "${day}" (use ${DAY_KEYS.join(', ')})`);
+        check(hours, day);
+    }
+    for (const o of schedule.overrides || []) {
+        const ok = (o.date && YMD.test(o.date)) || (o.from && o.to && YMD.test(o.from) && YMD.test(o.to));
+        if (!ok)
+            throw new Error('Each override needs `date` or `from` + `to` (YYYY-MM-DD)');
+        check(o.hours || [], `override ${o.date || o.from}`);
+    }
+    return true;
+}
+function tzOffsetMs(ts, tz) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz, hourCycle: 'h23',
+        year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+    }).formatToParts(new Date(ts));
+    const v = {};
+    for (const p of parts)
+        if (p.type !== 'literal')
+            v[p.type] = Number(p.value);
+    const asUtc = Date.UTC(v.year, v.month - 1, v.day, v.hour === 24 ? 0 : v.hour, v.minute, v.second);
+    return asUtc - (ts - (ts % 1000));
+}
+/** The UTC instant (ms) of local date `ymd` + `minutes` past midnight in `tz`. */
+export function zonedToUtc(ymd, minutes, tz) {
+    const [y, mo, d] = ymd.split('-').map(Number);
+    const guess = Date.UTC(y, mo - 1, d) + minutes * 60000;
+    let ts = guess - tzOffsetMs(guess, tz);
+    const off2 = tzOffsetMs(ts, tz);
+    if (guess - off2 !== ts)
+        ts = guess - off2;
+    return ts;
+}
+function localYmd(ts, tz) {
+    return new Intl.DateTimeFormat('en-CA', { timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date(ts));
+}
+function addDaysYmd(ymd, n) {
+    const [y, m, d] = ymd.split('-').map(Number);
+    return new Date(Date.UTC(y, m - 1, d + n)).toISOString().slice(0, 10);
+}
+function dayKey(ymd) {
+    const [y, m, d] = ymd.split('-').map(Number);
+    return DAY_KEYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+function hoursFor(schedule, ymd) {
+    let hours = (schedule.weekly || {})[dayKey(ymd)] || [];
+    for (const o of schedule.overrides || []) {
+        if ((o.date && o.date === ymd) || (o.from && o.to && o.from <= ymd && ymd <= o.to))
+            hours = o.hours || [];
+    }
+    return hours;
+}
+function toMs(v) {
+    return v instanceof Date ? v.getTime() : typeof v === 'number' ? v : new Date(v).getTime();
+}
+function merge(list) {
+    const sorted = [...list].sort((a, b) => a.start - b.start);
+    const out = [];
+    for (const i of sorted) {
+        const last = out[out.length - 1];
+        if (last && i.start <= last.end)
+            last.end = Math.max(last.end, i.end);
+        else
+            out.push(Object.assign({}, i));
+    }
+    return out;
+}
+/** The schedule's open hours overlapping [from, to), as merged UTC intervals. */
+export function openIntervals(schedule, from, to) {
+    const fromMs = toMs(from);
+    const toMsV = toMs(to);
+    const tz = schedule.timezone;
+    const out = [];
+    let ymd = addDaysYmd(localYmd(fromMs, tz), -1);
+    const last = addDaysYmd(localYmd(toMsV, tz), 1);
+    while (ymd <= last) {
+        for (const h of hoursFor(schedule, ymd)) {
+            const start = zonedToUtc(ymd, minutesOf(h.start), tz);
+            const end = zonedToUtc(ymd, minutesOf(h.end), tz);
+            if (end > fromMs && start < toMsV)
+                out.push({ start, end });
+        }
+        ymd = addDaysYmd(ymd, 1);
+    }
+    return merge(out);
+}
+/** True when [start, end) lies entirely inside the schedule's open hours. */
+export function withinSchedule(schedule, start, end) {
+    const s = toMs(start);
+    const e = toMs(end);
+    return openIntervals(schedule, s, e).some((i) => i.start <= s && e <= i.end);
+}
+/** `open` minus `busy` (both lists of intervals). */
+export function subtractIntervals(open, busy) {
+    const b = merge(busy);
+    const out = [];
+    for (const o of merge(open)) {
+        let cursor = o.start;
+        for (const x of b) {
+            if (x.end <= cursor || x.start >= o.end)
+                continue;
+            if (x.start > cursor)
+                out.push({ start: cursor, end: x.start });
+            cursor = Math.max(cursor, x.end);
+            if (cursor >= o.end)
+                break;
+        }
+        if (cursor < o.end)
+            out.push({ start: cursor, end: o.end });
+    }
+    return out;
+}
+/**
+ * Bookable start times: open hours minus busy time, stepped at `step`, each long enough for
+ * `duration` (+ buffers against busy time), not sooner than `minNotice`.
+ *
+ *   const fb = await bookings.freebusy(collectionId, appId, { resources: ['record:sam'], from, to }, true)
+ *   const times = utils.freeTimes({ hours: samsSchedule, busy: fb.resources[0].busy, from, to, duration: 30 })
+ *
+ * Start times are aligned to `step` from local midnight in the schedule's timezone (so 30-minute
+ * steps land on :00 and :30), or from each open interval's start when you pass intervals.
+ */
+export function freeTimes(opts) {
+    var _a;
+    const from = toMs(opts.from);
+    const to = toMs(opts.to);
+    const duration = opts.duration * 60000;
+    const step = (opts.step || opts.duration) * 60000;
+    const before = (opts.bufferBefore || 0) * 60000;
+    const after = (opts.bufferAfter || 0) * 60000;
+    const earliest = ((_a = opts.now) !== null && _a !== void 0 ? _a : Date.now()) + (opts.minNotice || 0) * 60000;
+    if (!(duration > 0) || !(step > 0) || !(to > from))
+        return [];
+    const isSchedule = !Array.isArray(opts.hours);
+    const schedule = isSchedule ? opts.hours : null;
+    const open = isSchedule ? openIntervals(schedule, from - before, to + after) : merge(opts.hours);
+    const busy = merge((opts.busy || []).map((b) => ({ start: toMs(b.start), end: toMs(b.end) })));
+    const freeForBuffers = subtractIntervals([{ start: from - before - 86400000, end: to + after + 86400000 }], busy);
+    const out = [];
+    for (const o of open) {
+        // Alignment origin: local midnight of the interval's day (schedules), or the interval start.
+        let t;
+        if (schedule) {
+            const ymd = localYmd(o.start, schedule.timezone);
+            const midnight = zonedToUtc(ymd, 0, schedule.timezone);
+            t = midnight + Math.ceil((o.start - midnight) / step) * step;
+        }
+        else {
+            t = o.start;
+        }
+        for (; t + duration <= o.end; t += step) {
+            if (t < from || t + duration > to || t < earliest)
+                continue;
+            const blockStart = t - before;
+            const blockEnd = t + duration + after;
+            if (opts.buffersWithinHours && (blockStart < o.start || blockEnd > o.end))
+                continue;
+            // The whole blocked span (appointment + buffers) must be clear of busy time.
+            if (!freeForBuffers.some((f) => f.start <= blockStart && blockEnd <= f.end))
+                continue;
+            out.push({ start: new Date(t).toISOString(), end: new Date(t + duration).toISOString() });
+        }
+    }
+    return out;
+}

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@
 export * from './paths.js';
 export * from './conditions.js';
 export * from './anonId.js';
+export * from './freeTimes.js';

package/dist/utils/index.js

@@ -6,3 +6,4 @@
 export * from './paths.js';
 export * from './conditions.js';
 export * from './anonId.js';
+export * from './freeTimes.js';