@proveanything/smartlinks 2.0.70 → 2.0.71

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.70  |  Generated: 2026-10-24T08:16:51.896Z
+Version: 2.0.71  |  Generated: 2026-10-24T17:23:20.711Z
 
 This is a concise summary of all available API functions and types.
 
@@ -140,6 +140,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **async** - Functions for async operations
 - **attestation** - Functions for attestation operations
 - **attestations** - Functions for attestations operations
+- **bookings** - Functions for bookings operations
 - **config** - Functions for config operations
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
@@ -3817,6 +3818,7 @@ interface Asset {
   proofId: string | null
   appId: string | null
   url: string
+  assetUrl: string | null
   thumbnail: string | null
   name: string
   cleanName: string | null
@@ -4054,6 +4056,7 @@ interface CreateResumableUploadOptions {
   appId?: string
   admin?: boolean
   token?: string
+  replaceAssetId?: string
 }
 ```
 
@@ -5065,6 +5068,329 @@ interface BatchTag {
 }
 ```
 
+### bookings
+
+**BookingAllocation** (interface)
+```typescript
+interface BookingAllocation {
+  id: string
+  bookingId: string | null
+  slotId: string | null
+  resourceType: string
+  resourceId: string
+  startsAt: string
+  endsAt: string
+  quantity: number
+  mode: 'exclusive' | 'capacity'
+  active: boolean
+  sourceSystem?: string | null
+  data: Record<string, any>
+}
+```
+
+**Booking** (interface)
+```typescript
+interface Booking {
+  id: string
+  collectionId: string
+  appId: string
+  visibility: BookingVisibility
+  contactId?: string
+  status: BookingStatus
+  startsAt: string
+  endsAt: string
+  timezone?: string | null
+  quantity: number
+  holdExpiresAt?: string | null
+  flags: string[]
+  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?: Record<string, any>
+  admin?: Record<string, any>
+  allocations: BookingAllocation[]
+  editToken?: string
+}
+```
+
+**BookingSlot** (interface)
+```typescript
+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
+  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>
+}
+```
+
+**CreateBookingInput** (interface)
+```typescript
+interface CreateBookingInput {
+  slotId?: string
+  quantity?: number
+  resourceType?: string
+  resourceId?: string
+  resource?: { type: string; id: string }
+  startsAt?: string | Date
+  endsAt?: string | Date
+  allocations?: BookingClaimInput[]
+  status?: 'held' | 'pending' | 'confirmed' | 'waitlisted'
+  holdMinutes?: number
+  bufferBefore?: number
+  bufferAfter?: number
+  idempotencyKey?: string
+  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?: Record<string, any>
+}
+```
+
+**UpdateBookingInput** (interface)
+```typescript
+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[]
+}
+```
+
+**MoveBookingInput** (interface)
+```typescript
+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
+}
+```
+
+**BookingListQueryParams** (interface)
+```typescript
+interface BookingListQueryParams {
+  status?: string
+  contactId?: string
+  slotId?: string
+  resourceType?: string
+  resourceId?: string
+  from?: string | Date
+  to?: string | Date
+  ref?: string
+  customId?: string
+  sourceSystem?: string
+  productId?: string
+  seriesId?: string
+  sort?: string
+  limit?: number
+  offset?: number
+}
+```
+
+**CreateSlotInput** (interface)
+```typescript
+interface CreateSlotInput {
+  startsAt: string | Date
+  endsAt: string | Date
+  capacity: number
+  perContactLimit?: number
+  resourceType?: string
+  resourceId?: string
+  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>
+}
+```
+
+**SlotListQueryParams** (interface)
+```typescript
+interface SlotListQueryParams {
+  status?: string
+  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
+}
+```
+
+**CreateBlockInput** (interface)
+```typescript
+interface CreateBlockInput {
+  resourceType: string
+  resourceId: string
+  startsAt: string | Date
+  endsAt: string | Date
+  sourceSystem?: string
+  data?: Record<string, any>
+}
+```
+
+**BlockListQueryParams** (interface)
+```typescript
+interface BlockListQueryParams {
+  resourceType?: string
+  resourceId?: string
+  from?: string | Date
+  to?: string | Date
+  limit?: number
+  offset?: number
+}
+```
+
+**FreeBusyQuery** (interface)
+```typescript
+interface FreeBusyQuery {
+  resources: BookingResourceRef[]
+  from: string | Date
+  to: string | Date
+}
+```
+
+**FreeBusyInterval** (interface)
+```typescript
+interface FreeBusyInterval {
+  start: string
+  end: string
+}
+```
+
+**FreeBusyResponse** (interface)
+```typescript
+interface FreeBusyResponse {
+  from: string
+  to: string
+  resources: Array<{ resourceType: string; resourceId: string; busy: FreeBusyInterval[] }>
+}
+```
+
+**BookingAccessOptions** (interface)
+```typescript
+interface BookingAccessOptions {
+  editToken?: string
+}
+```
+
+**ScheduleHours** (interface)
+```typescript
+interface ScheduleHours {
+  start: string
+  end: string
+}
+```
+
+**ScheduleOverride** (interface)
+```typescript
+interface ScheduleOverride {
+  date?: string
+  from?: string
+  to?: string
+  hours: ScheduleHours[]
+}
+```
+
+**StandardSchedule** (interface)
+```typescript
+interface StandardSchedule {
+  timezone: string
+  weekly?: Partial<Record<ScheduleDay, ScheduleHours[]>>
+  overrides?: ScheduleOverride[]
+}
+```
+
+**BookingStatus** = ``
+
+**BookingVisibility** = `'public' | 'owner' | 'admin'`
+
+**BookingClaimInput** = ``
+
+**UpdateSlotInput** = `Partial<Omit<CreateSlotInput, 'blockResource' | 'seriesId' | 'resourceType' | 'resourceId'>>`
+
+**BookingResourceRef** (type)
+```typescript
+type BookingResourceRef = { type: string; id: string }
+```
+
+**BookingList** = `PaginatedResponse<Booking>`
+
+**SlotList** = `PaginatedResponse<BookingSlot>`
+
+**BlockList** = `PaginatedResponse<BookingAllocation>`
+
+**BookingErrorCode** = ``
+
+**ScheduleDay** = `'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun'`
+
 ### broadcasts
 
 **ListBroadcastsQuery** (interface)
@@ -10568,6 +10894,41 @@ interface ConditionDebugOptions {
 
 **ConditionDebugLogger** = `(...args: any[]) => void`
 
+### freeTimes (utils)
+
+**TimeInterval** (interface)
+```typescript
+interface TimeInterval {
+  start: number
+  end: number
+}
+```
+
+**FreeTimesOptions** (interface)
+```typescript
+interface FreeTimesOptions {
+  hours: StandardSchedule | TimeInterval[]
+  busy?: Array<FreeBusyInterval | TimeInterval>
+  from: string | number | Date
+  to: string | number | Date
+  duration: number
+  step?: number
+  bufferBefore?: number
+  bufferAfter?: number
+  minNotice?: number
+  now?: number
+  buffersWithinHours?: boolean
+}
+```
+
+**FreeTimeSlot** (interface)
+```typescript
+interface FreeTimeSlot {
+  start: string
+  end: string
+}
+```
+
 ### paths (utils)
 
 **PortalPathParams** (interface)
@@ -11065,6 +11426,9 @@ Soft-delete an asset. Schedules CDN purge after `graceDays` (default 30). Recove
 **restoreAdmin**(collectionId: string, assetId: string) → `Promise<Asset>`
 Restore a soft-deleted asset (clears `deletedAt`).
 
+**ensureAssetUrl**(collectionId: string, assetId: string) → `Promise<Asset>`
+Give an existing asset its own address (`assetUrl`). New and replaced assets get one automatically; this is for assets made before asset addresses existed. Safe to call again. → the asset, with `assetUrl`.
+
 **bulkDelete**(options: BulkDeleteAssetsOptions) → `Promise<`
 Soft-delete multiple assets in one request.
 
@@ -11468,6 +11832,72 @@ Find a specific batch by ID across all products in a collection. Returns the bat
     claimSetId?: string) → `Promise<BatchTag[]>`
 Get all tags/codes assigned to a specific batch. Shows which claim set codes have been assigned to this batch. ```typescript // Get all tags assigned to a batch const tags = await batch.getBatchTags('coll_123', 'BATCH-2024-001') console.log(`Batch has ${tags.length} tags assigned`) tags.forEach(tag => { console.log(`Code: ${tag.code}, ClaimSet: ${tag.claimSetId}, TagID: ${tag.tagId}`) }) // Get tags from a specific claim set const claimSetTags = await batch.getBatchTags('coll_123', 'BATCH-2024-001', '000001') ```
 
+### bookings
+
+**create**(collectionId: string, appId: string, input: CreateBookingInput, admin: boolean = false) → `Promise<Booking>`
+Book. All claims succeed together or nothing is written; a clash fails with 409 (`SLOT_FULL`, `RESOURCE_TAKEN`, `PER_CONTACT_LIMIT`, …). Pass `idempotencyKey` so a retry never books twice. Public (admin = false): the app's `publicCreate.bookings` rules decide the status and limits; an anonymous guest may get `editToken` back (once) to manage the booking later. POST /bookings
+
+**list**(collectionId: string, appId: string, params?: BookingListQueryParams, admin: boolean = true) → `Promise<PaginatedResponse<Booking>>`
+List bookings (admin). GET /bookings
+
+**mine**(collectionId: string, appId: string, params?: BookingListQueryParams) → `Promise<PaginatedResponse<Booking>>`
+The signed-in caller's own bookings (public). GET /bookings/mine
+
+**get**(collectionId: string, appId: string, bookingId: string, admin: boolean = false, opts?: BookingAccessOptions) → `Promise<Booking>`
+Get one booking. Public: the signed-in booker, or a guest passing `{ editToken }`. GET /bookings/:bookingId
+
+**update**(collectionId: string, appId: string, bookingId: string, input: UpdateBookingInput, admin: boolean = true) → `Promise<Booking>`
+Update zones and descriptive fields (admin). PATCH /bookings/:bookingId
+
+**confirm**(collectionId: string, appId: string, bookingId: string, admin: boolean = false, opts?: BookingAccessOptions) → `Promise<Booking>`
+held / pending / waitlisted → confirmed (idempotent). A held booking whose hold has run out fails with HOLD_EXPIRED. Public: only the booker's own hold, when `ownerActions.bookings.confirm` allows. POST /bookings/:bookingId/confirm
+
+**cancel**(collectionId: string, appId: string, bookingId: string, admin: boolean = false, opts?: BookingAccessOptions & { reason?: string }) → `Promise<Booking>`
+Cancel and give the places back (idempotent). Public: per `ownerActions.bookings.cancel` and its cutoff. `reason` is admin-only (public cancels record 'owner'). POST /bookings/:bookingId/cancel
+
+**move**(collectionId: string, appId: string, bookingId: string, input: MoveBookingInput, admin: boolean = false, opts?: BookingAccessOptions) → `Promise<Booking>`
+Move to a new slot / time, all-or-nothing (a failed move leaves the booking as it was). Public: per `ownerActions.bookings.move`; the create rules are re-checked for the new time. POST /bookings/:bookingId/move
+
+**extendHold**(collectionId: string, appId: string, bookingId: string, holdMinutes: number) → `Promise<Booking>`
+Extend a hold by `holdMinutes` from now (admin; capped at 24h after the booking was made).
+
+**complete**(collectionId: string, appId: string, bookingId: string) → `Promise<Booking>`
+confirmed → completed (admin).
+
+**noShow**(collectionId: string, appId: string, bookingId: string) → `Promise<Booking>`
+confirmed → no_show (admin).
+
+**freebusy**(collectionId: string, appId: string, q: FreeBusyQuery, admin: boolean = false) → `Promise<FreeBusyResponse>`
+Busy intervals per resource (bookings, blocks, slots' own blocks) — never booking details. Public only when the app sets `publicRead.bookings.freebusy: true`. GET /bookings/freebusy
+
+### bookings.blocks
+
+**create**(collectionId: string, appId: string, input: CreateBlockInput) → `Promise<BookingAllocation>`
+
+**list**(collectionId: string, appId: string, params?: BlockListQueryParams) → `Promise<PaginatedResponse<BookingAllocation>>`
+
+**remove**(collectionId: string, appId: string, blockId: string) → `Promise<`
+
+### bookings.slots
+
+**create**(collectionId: string, appId: string, input: CreateSlotInput) → `Promise<BookingSlot>`
+Create a slot (admin). POST /bookings/slots
+
+**createMany**(collectionId: string, appId: string, slots: CreateSlotInput[], opts?: { seriesId?: string }) → `Promise<`
+Create many slots at once — a series — all-or-nothing (admin, max 500). POST /bookings/slots/batch
+
+**list**(collectionId: string, appId: string, params?: SlotListQueryParams, admin: boolean = false) → `Promise<PaginatedResponse<BookingSlot>>`
+List slots. Public: open, public slots only, each with `remaining`. GET /bookings/slots
+
+**get**(collectionId: string, appId: string, slotId: string, admin: boolean = false) → `Promise<BookingSlot>`
+GET /bookings/slots/:slotId
+
+**update**(collectionId: string, appId: string, slotId: string, input: UpdateSlotInput) → `Promise<BookingSlot>`
+Update a slot (admin). Capacity can't drop below what's booked (SLOT_OVERBOOKED); times can't change once anything is booked (SLOT_HAS_BOOKINGS).
+
+**remove**(collectionId: string, appId: string, slotId: string) → `Promise<`
+Delete a slot (admin; refused while places are booked).
+
 ### broadcasts
 
 **create**(collectionId: string,

package/docs/app-objects.md

@@ -12,6 +12,10 @@ SmartLinks provides three generic data models scoped to your app that can be ada
 - **Threads** — Manage discussions, comments, or any reply-based content
 - **Records** — Store structured data with flexible lifecycles
 
+> **Bookings** (anything that claims time or a place — events, classes, appointments, rooms) have
+> their own objects with no-double-booking and capacity guarantees: see [bookings.md](bookings.md).
+> A booking app still uses records for its schedules, staff and settings.
+
 Each object type supports:
 - **JSONB zones** (`data`, `owner`, `admin`) for granular access control
 - **Visibility levels** (`public`, `owner`, `admin`) for content exposure

package/docs/assets.md

@@ -2,6 +2,10 @@
 
 Reference for asset types, endpoints, and public (token-based) uploads.
 
+> **Showing an asset in a page, email or other static content? Use `assetUrl`.** It's the asset's own
+> address and always shows its current file, so replacing the file needs no code change or redeploy. See
+> [Asset addresses: `assetUrl` vs `url`](#asset-addresses-asseturl-vs-url).
+
 ---
 
 ## Asset object
@@ -17,7 +21,9 @@ interface Asset {
   appId:        string | null     // app that owns this asset, e.g. 'homepage'
 
   // File
-  url:          string            // CDN URL of the original file
+  url:          string            // address of the current FILE — versioned, changes when the file is replaced
+  assetUrl:     string | null     // the ASSET's own address — always its current file; use in static content
+                                  // (see "Asset addresses" below)
   thumbnail:    string | null     // CDN URL of WebP thumbnail (max 512px longest edge, no crop)
                                   // Always .webp — null until thumbnail generation has run
   name:         string            // original filename
@@ -84,6 +90,12 @@ interface AssetRef {
 }
 ```
 
+An `AssetRef` has no `assetUrl`, on purpose. A product's image is part of the product record: to change it,
+point the record at a new asset (upload, then save the product). That's a record change, so the product's
+change event fires and integrations and syndication pick it up. Retailers cache images by URL, so the new
+address is what makes them fetch the new image. Show product images from the record, never copied into
+static HTML.
+
 Render the thumbnail wherever a compact preview is needed; fall back to `url` if null:
 
 ```typescript
@@ -185,7 +197,10 @@ await Api.asset.updateAdmin({
 POST /asset/:assetId/replace
 ```
 
-Replaces the file; the previous URL is snapshotted into `versions[]`.
+Replaces the file; the previous URL is snapshotted into `versions[]`. The id and `assetUrl` stay the same,
+and `assetUrl` serves the new file straight away. `url` becomes the new file's address. See
+[Asset addresses](#asset-addresses-asseturl-vs-url). For a large file, use a resumable upload with
+`replaceAssetId`.
 
 ```typescript
 await Api.asset.replaceFile({
@@ -304,6 +319,7 @@ interface CreateResumableUploadOptions {
   appId?: string
   admin?: boolean          // admin route (default is the public route)
   token?: string           // upload token for public/unauthenticated uploads
+  replaceAssetId?: string  // admin: replace this asset's file (any size) instead of creating a new asset
 }
 
 interface ResumableUploadHandle {
@@ -321,6 +337,51 @@ interface ResumableUploadHandle {
 - On completion, `start()`/`resume()` resolves to the finalized `Asset` record.
 - `pause()` causes the in-flight `start()`/`resume()` promise to reject with an `UploadPausedError`; call `resume()` to continue.
 - `asset.upload()` also now accepts an `AbortSignal` (`upload({ ..., signal })`) for cancelling a stalled single-shot upload.
+- With `replaceAssetId`, the completed upload becomes a new version of that asset (same id and `assetUrl`), so a
+  200 MB video can be swapped without touching the pages that show it.
+
+---
+
+## Asset addresses: `assetUrl` vs `url`
+
+An asset is a named thing in the library, such as "Hero image". Its file can be replaced over time, so it has
+two addresses:
+
+| Field | Is the address of | When the file is replaced |
+|---|---|---|
+| `assetUrl` | the **asset**: `https://cdn.smartlinks.app/sites/{collectionId}/a/{assetId}` | stays the same, and shows the new file |
+| `url` | the asset's current **file** | becomes the new file's address (the old one moves to `versions[]`) |
+
+### Which to use
+
+| You're showing it in… | Use |
+|---|---|
+| Static content: a built site's HTML or CSS, an email, a banner, anything written once and published | `assetUrl` |
+| A product or collection image (`heroImage`, `additionalImages`, `logoImage`, `headerImage`) | the record's `AssetRef`, read from the record (see [AssetRef](#assetref--slim-embedded-shape)) |
+| Version history, a "compare versions" view, an exact file for an audit | `url` and `versions[]` |
+
+```html
+<!-- In a built page: swap "Hero image" in the library and this shows the new one, no rebuild -->
+<img src="https://cdn.smartlinks.app/sites/my-collection/a/3f0c…" alt="…">
+```
+
+```typescript
+const hero = await Api.asset.getAdmin('my-collection', heroId)
+const src = hero.assetUrl ?? hero.url   // fall back for outside links and older assets
+```
+
+### How it behaves
+
+- **Replace** (`replaceFile`, or a resumable upload with `replaceAssetId`): `assetUrl` shows the new file. The CDN
+  copy is cleared at once, and browsers re-check within a minute. There's no redeploy and no extra API call.
+- **Delete**: `assetUrl` stops serving (the asset is withdrawn). **Restore** brings it back.
+- `assetUrl` is `null` for an outside link (an asset that is a link to someone else's file). Fall back to `url`.
+- Assets made before asset addresses existed have `assetUrl: null` until they're given one:
+
+```typescript
+const a = await Api.asset.ensureAssetUrl('my-collection', 'abc123')
+a.assetUrl  // https://cdn.smartlinks.app/sites/my-collection/a/abc123
+```
 
 ---