@proveanything/smartlinks 2.0.69 → 2.0.71

package/dist/testing/index.js

@@ -241,7 +241,7 @@ export function createFunctionTestContext(opts) {
             mem.contacts.push(Object.assign(Object.assign({}, d), { email, phone, contactId }));
             return { contactId, created: true };
         }), 'contacts.upsert'),
-        forCaller: gated('contacts', 'write', ct.forCaller ? ct.forCaller.bind(ct) : (async () => (opts.caller && opts.caller.userId ? { contactId: `contact-of-${opts.caller.userId}` } : null)), 'contacts.forCaller'),
+        forCaller: gated('contacts', 'write', ct.forCaller ? ct.forCaller.bind(ct) : (async () => (opts.caller && opts.caller.userId ? { contactId: `contact-of-${opts.caller.userId}`, email: null, phone: null, firstName: null, lastName: null, displayName: null, tags: [], customFields: {} } : null)), 'contacts.forCaller'),
     };
     const it = impl.interactions || {};
     sl.interactions = {

package/dist/types/appManifest.d.ts

@@ -437,16 +437,16 @@ export interface ServerFunctionSl {
     /**
      * Contacts (`sl:contacts:write`). `upsert` finds by email/phone or creates, and only FILLS EMPTY
      * fields — never overwrites (details typed by a visitor are unverified). `forCaller` is the signed-in
-     * caller's own contact (null when anonymous). Never return contact ids to public callers.
+     * caller's own contact with its tags and custom fields (null when anonymous) — check a member's level
+     * (`customFields.level`) here before returning member-only content. It includes staff-only fields:
+     * return only what the caller may see. Never return contact ids to public callers.
      */
     contacts: {
         upsert(details: ContactUpsertDetails): Promise<{
             contactId: string;
             created: boolean;
         }>;
-        forCaller(): Promise<{
-            contactId: string;
-        } | null>;
+        forCaller(): Promise<CallerContact | null>;
     };
     /**
      * Interactions (`sl:interactions:write`). `record` stores an event of one of THIS app's interaction
@@ -502,6 +502,18 @@ export interface ServerFunctionCaller {
     /** How the function was triggered. */
     via: AppFunctionTriggerType;
 }
+/** The signed-in caller's own contact, as a server function sees it (`ctx.sl.contacts.forCaller()`). */
+export interface CallerContact {
+    contactId: string;
+    email: string | null;
+    phone: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    tags: string[];
+    /** The collection's custom contact fields — including staff-only ones (a member's level, a paid-until date). */
+    customFields: Record<string, unknown>;
+}
 /**
  * The context handed to every SmartLinks server function. The platform builds a
  * fresh one per invocation and pre-scopes each handle to the function's declared

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/authKit.d.ts

@@ -128,7 +128,9 @@ export interface AppleLoginOptions {
  * `ACCOUNT_EXISTS_UNVERIFIED` case also carries `requiresEmailVerification: true`
  * in `SmartlinksApiError.details`.
  */
-export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED';
+export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED' | 'SIGN_UP_CLOSED';
+/** A second-step method: a code by email or text message, or from an authenticator app. */
+export type MfaFactor = 'email' | 'sms' | 'totp';
 /**
  * Details carried on the `MFA_REQUIRED` error thrown by any session-issuing login method
  * (see the gate list above) when the client's MFA policy requires a step-up. Surfaced as
@@ -139,18 +141,20 @@ export interface MfaRequiredDetails {
     /** Short-lived (10 min) and single-use. Pass it to every challenge/finalize call below. */
     mfaSessionToken: string;
     /** Only factors the user actually enrolled. */
-    availableFactors: Array<'email' | 'sms'>;
-    /** `sms` is preferred over `email` when both are enrolled. */
-    preferredFactor: 'email' | 'sms';
+    availableFactors: MfaFactor[];
+    /** `totp`, then `sms`, then `email`: the first one the user enrolled. */
+    preferredFactor: MfaFactor;
+    /** `totp` is "your authenticator app" (nothing is sent for it). */
     maskedDestinations: {
         email?: string;
         sms?: string;
+        totp?: string;
     };
 }
 /** Response from {@link authKit.mfaChallengeSend}. */
 export interface MfaChallengeSendResponse {
     success: true;
-    factor: 'email' | 'sms';
+    factor: MfaFactor;
     /** Masked, e.g. `"j***@x.com"` or `"+1******1234"`. */
     destination: string;
     /** ISO timestamp, 10 minutes from send. */
@@ -179,10 +183,22 @@ export interface MfaEnrollSendResponse {
     destination: string;
     expiresAt: string;
 }
-/** Response from {@link authKit.confirmEmailMfa} / {@link authKit.confirmSmsMfa}. */
+/** Response from {@link authKit.enrollTotpMfa}: show `otpauthUri` as a QR code, and `secret` for typing in. */
+export interface MfaTotpEnrollResponse {
+    mfaSessionToken: string;
+    /** Base32, for people who type it into their app instead of scanning. Returned only here. */
+    secret: string;
+    /** `otpauth://totp/…` — render it as a QR code for the app to scan. */
+    otpauthUri: string;
+    /** What the app shows the entry as: the site, and the account. */
+    issuer: string;
+    account: string;
+    expiresAt: string;
+}
+/** Response from {@link authKit.confirmEmailMfa} / {@link authKit.confirmSmsMfa} / {@link authKit.confirmTotpMfa}. */
 export interface MfaEnrolledResponse {
     enrolled: true;
-    factor: 'email' | 'sms';
+    factor: MfaFactor;
 }
 /** Response from {@link authKit.getMfaFactors}. */
 export interface MfaFactorsResponse {
@@ -195,6 +211,11 @@ export interface MfaFactorsResponse {
             enrolledAt: string;
             destination: string;
         };
+        /** `destination` is "Authenticator app". */
+        totp?: {
+            enrolledAt: string;
+            destination: string;
+        };
     };
     recoveryCodesRemaining: number;
     mfaEnabledForClient: boolean;
@@ -415,6 +436,36 @@ export interface AuthKitConfig {
      * site, its own passwords). Switch with {@link authKit.setIdentity}; never via create/update.
      */
     identity?: AuthKitIdentity;
+    /**
+     * Who may join a site with its own logins. `open` (default): anyone can create an account.
+     * `invite`: only people the site's admins invite ({@link authKit.invite}). Every way of signing up
+     * (password, magic link, phone, Google, Apple, LinkedIn, WhatsApp) then refuses anyone else with
+     * `SIGN_UP_CLOSED` (403), and "send me a link / a code" answers as if sent without sending anything,
+     * so nobody can find out who is a member. Hide your "Create an account" option when it's `invite`.
+     * Setting `invite` needs own logins first (`OWN_LOGINS_REQUIRED`, 409).
+     */
+    signUp?: 'open' | 'invite';
+}
+/** Body of {@link authKit.invite}. */
+export interface AuthKitInviteRequest {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    /** Set on their contact in this collection, e.g. `{ level: 'member' }` (staff-only and visible fields alike). */
+    customFields?: Record<string, unknown>;
+    /** Where the emailed link opens: the site's sign-in page (one of its own addresses). Default: the kit's `redirectUrl`. */
+    redirectUrl?: string;
+}
+/** Result of {@link authKit.invite}. The sign-in link itself only goes to their inbox. */
+export interface AuthKitInviteResponse {
+    ok: true;
+    userId: string;
+    contactId: string;
+    /** true when their account was made by this invite; false when they had one (they got a new link). */
+    created: boolean;
+    /** When the emailed link stops working (it works once). */
+    expiresAt: string;
 }
 /** An AuthKit's member pool. */
 export interface AuthKitIdentity {

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