@proveanything/smartlinks 2.0.70 → 2.1.0

package/dist/types/appManifest.d.ts

@@ -3,6 +3,8 @@
 import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
 import type { RealtimeChannelDeclaration } from './realtime.js';
 import type { AppManifestAdminCards } from './adminCards.js';
+import type { PaginatedResponse } from './appObjects.js';
+import type { Booking, BookingSlot, BookingAllocation, CreateBookingInput, UpdateBookingInput, MoveBookingInput, BookingListQueryParams, CreateSlotInput, UpdateSlotInput, SlotListQueryParams, CreateBlockInput, BlockListQueryParams, FreeBusyQuery, FreeBusyResponse } from './bookings.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -416,7 +418,60 @@ export interface ServerFunctionInteractionEvent {
     batchId?: string;
     eventType?: string;
 }
+/**
+ * `ctx.sl.bookings` — THIS app's own bookings, slots and blocks (docs/bookings.md, "In a server
+ * function"). Gated by `sl:bookings:read` / `sl:bookings:write` only. Writes are admin-side: any
+ * status, the admin zone, any contact — the app's `publicCreate.bookings` rules don't apply, because
+ * the function IS the app's rules (hours, queue tokens, payment). The platform's guarantees still do:
+ * a clash fails with an Error carrying `code` (SLOT_FULL, RESOURCE_TAKEN, PER_CONTACT_LIMIT,
+ * HOLD_EXPIRED, …), `status` and `details`.
+ */
+export interface ServerFunctionBookings {
+    /** Book; pass `idempotencyKey` (e.g. the payment intent id) so a retry returns the first booking (`replayed: true`). */
+    create(input: CreateBookingInput): Promise<Booking & {
+        replayed: boolean;
+    }>;
+    get(bookingId: string): Promise<Booking | null>;
+    query(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+    /** The signed-in caller's own bookings (empty when anonymous). */
+    mine(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+    update(bookingId: string, fields: UpdateBookingInput): Promise<Booking>;
+    /** held / pending / waitlisted → confirmed (idempotent). */
+    confirm(bookingId: string): Promise<Booking>;
+    /** Cancel and give the places back (idempotent). */
+    cancel(bookingId: string, opts?: {
+        reason?: string;
+    }): Promise<Booking>;
+    /** All-or-nothing move to new claims. */
+    move(bookingId: string, input: MoveBookingInput): Promise<Booking>;
+    extendHold(bookingId: string, holdMinutes: number): Promise<Booking>;
+    complete(bookingId: string): Promise<Booking>;
+    noShow(bookingId: string): Promise<Booking>;
+    /** Busy intervals per resource — feed them to `utils.freeTimes` with your schedule. */
+    freebusy(q: FreeBusyQuery): Promise<FreeBusyResponse>;
+    slots: {
+        create(input: CreateSlotInput): Promise<BookingSlot>;
+        createMany(inputs: CreateSlotInput[], opts?: {
+            seriesId?: string;
+        }): Promise<BookingSlot[]>;
+        get(slotId: string): Promise<BookingSlot | null>;
+        query(params?: SlotListQueryParams): Promise<PaginatedResponse<BookingSlot>>;
+        update(slotId: string, fields: UpdateSlotInput): Promise<BookingSlot>;
+        delete(slotId: string): Promise<{
+            success: boolean;
+        }>;
+    };
+    blocks: {
+        create(input: CreateBlockInput): Promise<BookingAllocation>;
+        query(params?: BlockListQueryParams): Promise<PaginatedResponse<BookingAllocation>>;
+        delete(blockId: string): Promise<{
+            success: boolean;
+        }>;
+    };
+}
 export interface ServerFunctionSl {
+    /** THIS app's bookings, slots and blocks (`sl:bookings:read` / `sl:bookings:write`). */
+    bookings: ServerFunctionBookings;
     /**
      * THIS app's records (own namespace): create / update / upsert / delete / get / query / listTypes,
      * plus `claim(fields)` — a race-safe UNIQUE create. The record names a unique key — `singletonPer`

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[];