@proveanything/smartlinks 2.0.71 → 2.1.0

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.71  |  Generated: 2026-10-24T17:23:20.711Z
+Version: 2.1.0  |  Generated: 2026-10-24T18:38:40.481Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2801,9 +2801,41 @@ interface ServerFunctionInteractionEvent {
 }
 ```
 
+**ServerFunctionBookings** (interface)
+```typescript
+interface ServerFunctionBookings {
+  create(input: CreateBookingInput): Promise<Booking & { replayed: boolean }>;
+  get(bookingId: string): Promise<Booking | null>;
+  query(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+  mine(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+  update(bookingId: string, fields: UpdateBookingInput): Promise<Booking>;
+  confirm(bookingId: string): Promise<Booking>;
+  cancel(bookingId: string, opts?: { reason?: string }): Promise<Booking>;
+  move(bookingId: string, input: MoveBookingInput): Promise<Booking>;
+  extendHold(bookingId: string, holdMinutes: number): Promise<Booking>;
+  complete(bookingId: string): Promise<Booking>;
+  noShow(bookingId: string): Promise<Booking>;
+  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 }>;
+  };
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
+  bookings: ServerFunctionBookings;
   appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
   counters: ServerFunctionCounters;
   tags: { resolve(id: string): Promise<ResolvedTag | null> };

package/dist/docs/app-objects.md

@@ -927,6 +927,9 @@ The server reads this document at request time — no cache invalidation or serv
 
 ### Policy Structure
 
+Bookings use the same policy as a fourth object type, `publicCreate.bookings`, with booking-specific
+`limits` and `rules` — see [bookings.md](bookings.md).
+
 Each object type (`cases`, `threads`, `records`) has **independent branches** for anonymous and authenticated callers. Each branch carries its own `allow` flag, optional field overrides (`enforce`), and — for records — optional edit-token config (`edit`).
 
 ```typescript

package/dist/docs/bookings.md

@@ -248,6 +248,33 @@ Off by default — most apps serve free times through their own function.
 
 ---
 
+## In a server function — `ctx.sl.bookings`
+
+When public booking is off, your app books through its own server function. `ctx.sl.bookings` is
+the same API, admin-side, for **your app's** bookings only (`sl:bookings:read` / `sl:bookings:write`):
+
+```ts
+// manifest: { name: 'book', trigger: { type: 'http' }, visibility: 'public', authority: 'collection',
+//             capabilities: ['sl:bookings:write', 'sl:contacts:write'] }
+export async function book(ctx, req) {
+  const me = await ctx.sl.contacts.forCaller()          // null when signed out
+  // … your rules: hours (utils.withinSchedule), a queue token, a member level, a price …
+  const b = await ctx.sl.bookings.create({
+    resourceType: 'record', resourceId: req.body.staffId,
+    startsAt: req.body.startsAt, endsAt: req.body.endsAt, bufferAfter: 10,
+    contactId: me?.contactId, status: 'confirmed', idempotencyKey: req.body.requestId,
+  })
+  return Response.json({ id: b.id, startsAt: b.startsAt })
+}
+```
+
+`create`, `get`, `query`, `mine` (the caller's own), `update`, `confirm`, `cancel`, `move`,
+`extendHold`, `complete`, `noShow`, `freebusy`, `slots.*`, `blocks.*`. Errors carry `code`,
+`status` and `details` exactly as over HTTP. The local test harness
+(`@proveanything/smartlinks/testing`) runs bookings in memory with the same rules.
+
+---
+
 ## Payments and high-demand sales
 
 The platform takes no payments. It gives you what a payment or credits flow needs:

package/dist/docs/server-functions.md

@@ -167,7 +167,7 @@ Declare the minimum you need.
 
 | Capability | Grants |
 |---|---|
-| `sl:<resource>:read` / `sl:<resource>:write` | SDK access to that resource, e.g. `sl:products:read`, `sl:records:write`, `sl:attestations:write`, `sl:contacts:write`. |
+| `sl:<resource>:read` / `sl:<resource>:write` | SDK access to that resource, e.g. `sl:products:read`, `sl:records:write`, `sl:attestations:write`, `sl:contacts:write`, `sl:bookings:write`. |
 | `network` | `ctx.fetch` to any host. |
 | `network:<host>` | `ctx.fetch` to that host only (repeat for several). Prefer this over blanket `network`. |
 | `network:*.<domain>` | `ctx.fetch` to any subdomain of `<domain>` (not `<domain>` itself), for a customer's own endpoint at a provider, e.g. `network:*.servicebus.windows.net`. `<domain>` needs at least two labels (`*.com` is not honoured). |
@@ -517,6 +517,7 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
 | Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
 | Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
+| Take a booking with your own checks (hours, queue token, payment) | `ctx.sl.bookings.create({ slotId \| resource + time, contactId, status, idempotencyKey })` — never oversold, never double-booked; also `confirm` / `cancel` / `move` / `mine` / `freebusy` / `slots.*` / `blocks.*` (see [bookings.md](bookings.md)) | `sl:bookings:write` (`sl:bookings:read` to read) |
 
 Notes:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -611,6 +612,33 @@ await ctx.sl.interactions.record({
 })
 ```
 
+### `bookings.*` — places and time that can't be oversold
+
+`ctx.sl.bookings` is your app's own bookings, slots and blocks (`sl:bookings:read` / `write`). A
+function books **admin-side**: any status, the admin zone, any contact — your app's public booking
+rules (`publicCreate.bookings`) don't apply, because the function *is* your rules. The platform still
+guarantees no overbooking and no overlapping time, so a clash throws (`code`: `SLOT_FULL`,
+`RESOURCE_TAKEN`, `PER_CONTACT_LIMIT`, `HOLD_EXPIRED`, …; with `status` and `details`). Pass an
+`idempotencyKey` so a retried request returns the first booking (`replayed: true`).
+
+```ts
+const me = await ctx.sl.contacts.forCaller()
+if (!me) return Response.json({ error: 'sign in' }, { status: 401 })
+try {
+  const booking = await ctx.sl.bookings.create({
+    slotId: body.slotId, quantity: body.quantity, contactId: me.contactId,
+    status: 'held', holdMinutes: 15, idempotencyKey: body.requestId,
+  })
+  return Response.json({ id: booking.id, holdExpiresAt: booking.holdExpiresAt })
+} catch (e: any) {
+  if (e.code === 'SLOT_FULL') return Response.json({ error: 'sold out', remaining: e.details?.remaining }, { status: 409 })
+  throw e
+}
+```
+
+The local harness runs bookings in memory with the same rules (capacity, per-person limits, no
+overlaps, idempotency, holds): `ctx.memory.bookings`.
+
 ---
 
 ## Platform tools — PDFs, labels, barcodes

package/dist/openapi.yaml

@@ -20224,9 +20224,23 @@ components:
           type: string
       required:
         - interactionId
+    ServerFunctionBookings:
+      type: object
+      properties:
+        slots:
+          type: object
+          additionalProperties: true
+        blocks:
+          type: object
+          additionalProperties: true
+      required:
+        - slots
+        - blocks
     ServerFunctionSl:
       type: object
       properties:
+        bookings:
+          $ref: "#/components/schemas/ServerFunctionBookings"
         appRecords:
           type: object
           additionalProperties: true
@@ -20249,6 +20263,7 @@ components:
         appData:
           $ref: "#/components/schemas/AppDataHandle"
       required:
+        - bookings
         - appRecords
         - counters
         - tags

package/dist/testing/bookingsMemory.d.ts

@@ -0,0 +1,75 @@
+export interface BookingsMemory {
+    slots: any[];
+    bookings: any[];
+    allocations: any[];
+}
+export declare function createBookingsMemory(): BookingsMemory;
+export declare function bookingsMemoryImpl(mem: BookingsMemory, caller?: {
+    contactId?: string | null;
+}): {
+    create(input?: any): Promise<any>;
+    get(bookingId: string): Promise<any>;
+    query(params?: any): Promise<{
+        data: any[];
+        pagination: {
+            total: number;
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        };
+    }>;
+    mine(params?: any): Promise<{
+        data: any[];
+        pagination: {
+            total: number;
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        };
+    }>;
+    update(bookingId: string, fields?: any): Promise<any>;
+    confirm(bookingId: string): Promise<any>;
+    cancel(bookingId: string, opts?: any): Promise<any>;
+    move(bookingId: string, input?: any): Promise<any>;
+    extendHold(bookingId: string, holdMinutes: number): Promise<any>;
+    complete(bookingId: string): Promise<any>;
+    noShow(bookingId: string): Promise<any>;
+    freebusy(q?: any): Promise<{
+        from: string;
+        to: string;
+        resources: any;
+    }>;
+    slots: {
+        create(input?: any): Promise<any>;
+        createMany(inputs: any[], opts?: any): Promise<any[]>;
+        get(slotId: string): Promise<any>;
+        query(params?: any): Promise<{
+            data: any[];
+            pagination: {
+                total: number;
+                limit: number;
+                offset: number;
+                hasMore: boolean;
+            };
+        }>;
+        update(slotId: string, fields?: any): Promise<any>;
+        delete(slotId: string): Promise<{
+            success: boolean;
+        }>;
+    };
+    blocks: {
+        create(input?: any): Promise<any>;
+        query(params?: any): Promise<{
+            data: any[];
+            pagination: {
+                total: number;
+                limit: number;
+                offset: number;
+                hasMore: boolean;
+            };
+        }>;
+        delete(blockId: string): Promise<{
+            success: boolean;
+        }>;
+    };
+};

package/dist/testing/bookingsMemory.js

@@ -0,0 +1,413 @@
+// src/testing/bookingsMemory.ts
+//
+// In-memory ctx.sl.bookings for the server-function test harness — the platform's booking rules,
+// small enough to read: slot capacity, per-person limits, no overlapping exclusive time, idempotent
+// creates, holds that expire, all-or-nothing writes. Each operation checks and writes without an
+// `await` in between, so concurrent calls in one test behave like the database: of ten requests for
+// the last seat, exactly one wins. Errors carry the platform's `code` / `status` / `details`.
+export function createBookingsMemory() {
+    return { slots: [], bookings: [], allocations: [] };
+}
+const ACTIVE = new Set(['held', 'pending', 'confirmed', 'completed', 'no_show']);
+function fail(code, message, status = 409, details) {
+    throw Object.assign(new Error(message), Object.assign({ code, status }, (details ? { details } : {})));
+}
+const ms = (v) => (v instanceof Date ? v.getTime() : new Date(v).getTime());
+const iso = (t) => new Date(t).toISOString();
+const overlaps = (a, b) => ms(a.startsAt) < ms(b.endsAt) && ms(b.startsAt) < ms(a.endsAt);
+const copy = (v) => JSON.parse(JSON.stringify(v));
+const page = (all, params = {}) => {
+    const limit = Math.min(Number(params.limit) || 25, 100);
+    const offset = Number(params.offset) || 0;
+    const data = all.slice(offset, offset + limit).map(copy);
+    return { data, pagination: { total: all.length, limit, offset, hasMore: offset + data.length < all.length } };
+};
+export function bookingsMemoryImpl(mem, caller = {}) {
+    let seq = 1;
+    const id = (p) => `${p}-${seq++}-${Math.random().toString(36).slice(2, 8)}`;
+    const now = () => Date.now();
+    const slotOf = (slotId) => mem.slots.find((s) => s.id === slotId && !s.deletedAt);
+    const withAllocations = (b) => (Object.assign(Object.assign({}, b), { allocations: mem.allocations.filter((a) => a.bookingId === b.id) }));
+    const remaining = (s) => Math.max(0, s.capacity - s.booked);
+    const slotView = (s) => copy(Object.assign(Object.assign({}, s), { remaining: remaining(s) }));
+    // Turn a request into claims (same forms as the platform).
+    function claimsOf(input) {
+        var _a, _b, _c, _d;
+        const quantity = input.quantity == null ? 1 : Number(input.quantity);
+        if (!Number.isInteger(quantity) || quantity < 1)
+            fail('BAD_REQUEST', 'quantity must be a positive integer', 400);
+        const raw = Array.isArray(input.allocations) && input.allocations.length ? input.allocations : [{
+                slotId: input.slotId, quantity,
+                resourceType: (_a = input.resourceType) !== null && _a !== void 0 ? _a : (_b = input.resource) === null || _b === void 0 ? void 0 : _b.type, resourceId: (_c = input.resourceId) !== null && _c !== void 0 ? _c : (_d = input.resource) === null || _d === void 0 ? void 0 : _d.id,
+            }];
+        return raw.map((c) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+            if (c.slotId)
+                return { kind: 'capacity', slotId: c.slotId, quantity: c.quantity == null ? quantity : Number(c.quantity) };
+            const startsAt = (_a = c.startsAt) !== null && _a !== void 0 ? _a : input.startsAt;
+            const endsAt = (_b = c.endsAt) !== null && _b !== void 0 ? _b : input.endsAt;
+            if (!((_c = c.resourceType) !== null && _c !== void 0 ? _c : (_d = c.resource) === null || _d === void 0 ? void 0 : _d.type) || !((_e = c.resourceId) !== null && _e !== void 0 ? _e : (_f = c.resource) === null || _f === void 0 ? void 0 : _f.id))
+                fail('BAD_REQUEST', 'A booking needs a slotId or a resource and a time', 400);
+            if (!startsAt || !endsAt || ms(endsAt) <= ms(startsAt))
+                fail('BAD_REQUEST', 'startsAt and endsAt are required, with endsAt after startsAt', 400);
+            const before = ((_h = (_g = c.bufferBefore) !== null && _g !== void 0 ? _g : input.bufferBefore) !== null && _h !== void 0 ? _h : 0) * 60000;
+            const after = ((_k = (_j = c.bufferAfter) !== null && _j !== void 0 ? _j : input.bufferAfter) !== null && _k !== void 0 ? _k : 0) * 60000;
+            return {
+                kind: 'exclusive', resourceType: String((_l = c.resourceType) !== null && _l !== void 0 ? _l : (_m = c.resource) === null || _m === void 0 ? void 0 : _m.type), resourceId: String((_o = c.resourceId) !== null && _o !== void 0 ? _o : (_p = c.resource) === null || _p === void 0 ? void 0 : _p.id),
+                startsAt: iso(ms(startsAt)), endsAt: iso(ms(endsAt)), blockStartsAt: iso(ms(startsAt) - before), blockEndsAt: iso(ms(endsAt) + after),
+            };
+        });
+    }
+    // Check every claim, then write them all — all-or-nothing, with no await in between.
+    function claimAll(bookingId, claims, contactId, active, ignoreBookingId) {
+        const writes = [];
+        const out = [];
+        for (const c of claims) {
+            if (c.kind === 'capacity') {
+                const s = slotOf(c.slotId);
+                if (!s)
+                    fail('NOT_FOUND', 'Slot not found', 404);
+                if (active) {
+                    if (s.status !== 'open')
+                        fail('SLOT_CLOSED', 'This slot is not taking bookings', 409, { slotId: s.id });
+                    if (s.booked + c.quantity > s.capacity)
+                        fail('SLOT_FULL', 'Not enough places left on this slot', 409, { slotId: s.id, remaining: remaining(s) });
+                    if (s.perContactLimit) {
+                        if (c.quantity > s.perContactLimit)
+                            fail('PER_CONTACT_LIMIT', `At most ${s.perContactLimit} per person on this slot`, 409, { slotId: s.id, limit: s.perContactLimit });
+                        if (contactId) {
+                            const held = mem.allocations.filter((a) => a.slotId === s.id && a.active && a.mode === 'capacity' && a.bookingId !== ignoreBookingId &&
+                                mem.bookings.find((b) => b.id === a.bookingId && b.contactId === contactId)).reduce((n, a) => n + a.quantity, 0);
+                            if (held + c.quantity > s.perContactLimit)
+                                fail('PER_CONTACT_LIMIT', `At most ${s.perContactLimit} per person on this slot`, 409, { slotId: s.id, limit: s.perContactLimit, held });
+                        }
+                    }
+                    writes.push(() => { s.booked += c.quantity; });
+                }
+                out.push({ bookingId, slotId: s.id, resourceType: 'slot', resourceId: s.id, startsAt: s.startsAt, endsAt: s.endsAt, quantity: c.quantity, mode: 'capacity', active, visible: [s.startsAt, s.endsAt] });
+            }
+            else {
+                const a = { bookingId, slotId: null, resourceType: c.resourceType, resourceId: c.resourceId, startsAt: c.blockStartsAt, endsAt: c.blockEndsAt, quantity: 1, mode: 'exclusive', active, visible: [c.startsAt, c.endsAt] };
+                if (active) {
+                    const clash = [...mem.allocations, ...out].find((x) => x.active && x.mode === 'exclusive' && x.bookingId !== ignoreBookingId &&
+                        x.resourceType === a.resourceType && x.resourceId === a.resourceId && overlaps(x, a));
+                    if (clash)
+                        fail('RESOURCE_TAKEN', 'That time is no longer free', 409, { resourceType: a.resourceType, resourceId: a.resourceId, startsAt: a.startsAt, endsAt: a.endsAt });
+                }
+                out.push(a);
+            }
+        }
+        for (const w of writes)
+            w();
+        let minStart = null;
+        let maxEnd = null;
+        for (const a of out) {
+            const [s, e] = a.visible;
+            delete a.visible;
+            if (!minStart || ms(s) < ms(minStart))
+                minStart = s;
+            if (!maxEnd || ms(e) > ms(maxEnd))
+                maxEnd = e;
+            mem.allocations.push(Object.assign({ id: id('alloc'), data: {}, sourceSystem: null }, a));
+        }
+        return { startsAt: minStart, endsAt: maxEnd };
+    }
+    function release(b, remove = false) {
+        for (const a of mem.allocations.filter((x) => x.bookingId === b.id)) {
+            if (a.active && a.mode === 'capacity') {
+                const s = mem.slots.find((x) => x.id === a.slotId);
+                if (s)
+                    s.booked = Math.max(0, s.booked - a.quantity);
+            }
+            a.active = false;
+        }
+        if (remove)
+            mem.allocations = mem.allocations.filter((x) => x.bookingId !== b.id);
+    }
+    const find = (bookingId) => {
+        const b = mem.bookings.find((x) => x.id === bookingId && !x.deletedAt);
+        if (!b)
+            fail('NOT_FOUND', 'Booking not found', 404);
+        return b;
+    };
+    const holdLapsed = (b) => b.status === 'held' && b.holdExpiresAt && ms(b.holdExpiresAt) < now();
+    return {
+        async create(input = {}) {
+            var _a;
+            const status = input.status || 'confirmed';
+            if (!['held', 'pending', 'confirmed', 'waitlisted'].includes(status))
+                fail('BAD_REQUEST', 'status must be held, pending, confirmed or waitlisted', 400);
+            if (input.idempotencyKey) {
+                const prior = mem.bookings.find((b) => b.idempotencyKey === String(input.idempotencyKey));
+                if (prior)
+                    return Object.assign(Object.assign({}, copy(withAllocations(prior))), { replayed: true });
+            }
+            const claims = claimsOf(input);
+            const bookingId = id('booking');
+            const contactId = input.contactId || null;
+            const visible = claimAll(bookingId, claims, contactId, status !== 'waitlisted');
+            const b = {
+                id: bookingId, status, contactId, visibility: input.visibility || 'owner',
+                startsAt: input.startsAt ? iso(ms(input.startsAt)) : visible.startsAt, endsAt: input.endsAt ? iso(ms(input.endsAt)) : visible.endsAt,
+                timezone: input.timezone || null, quantity: input.quantity == null ? 1 : Number(input.quantity),
+                holdExpiresAt: status === 'held' ? iso(now() + ((_a = input.holdMinutes) !== null && _a !== void 0 ? _a : 15) * 60000) : null,
+                flags: [], cancelReason: null, idempotencyKey: input.idempotencyKey ? String(input.idempotencyKey) : null,
+                ref: input.ref || null, customId: input.customId || null, productId: input.productId || null,
+                data: input.data || {}, owner: input.owner || {}, admin: input.admin || {},
+                createdAt: iso(now()), updatedAt: iso(now()), cancelledAt: null,
+            };
+            mem.bookings.push(b);
+            return Object.assign(Object.assign({}, copy(withAllocations(b))), { replayed: false });
+        },
+        async get(bookingId) {
+            const b = mem.bookings.find((x) => x.id === bookingId && !x.deletedAt);
+            return b ? copy(withAllocations(b)) : null;
+        },
+        async query(params = {}) {
+            let all = mem.bookings.filter((b) => !b.deletedAt);
+            if (params.status) {
+                const s = String(params.status).split(',');
+                all = all.filter((b) => s.includes(b.status));
+            }
+            if (params.contactId)
+                all = all.filter((b) => b.contactId === params.contactId);
+            if (params.slotId)
+                all = all.filter((b) => mem.allocations.some((a) => a.bookingId === b.id && a.slotId === params.slotId));
+            if (params.from)
+                all = all.filter((b) => ms(b.endsAt) > ms(params.from));
+            if (params.to)
+                all = all.filter((b) => ms(b.startsAt) < ms(params.to));
+            all.sort((a, b) => ms(a.startsAt) - ms(b.startsAt));
+            return page(all.map(withAllocations), params);
+        },
+        async mine(params = {}) {
+            if (!caller.contactId)
+                return { data: [], pagination: { total: 0, limit: 0, offset: 0, hasMore: false } };
+            return this.query(Object.assign(Object.assign({}, params), { contactId: caller.contactId }));
+        },
+        async update(bookingId, fields = {}) {
+            const b = find(bookingId);
+            for (const k of ['data', 'owner', 'admin', 'visibility', 'ref', 'timezone', 'productId', 'contactId', 'customId', 'flags'])
+                if (fields[k] !== undefined)
+                    b[k] = fields[k];
+            b.updatedAt = iso(now());
+            return copy(withAllocations(b));
+        },
+        async confirm(bookingId) {
+            const b = find(bookingId);
+            if (b.status === 'confirmed')
+                return copy(withAllocations(b));
+            if (!['held', 'pending', 'waitlisted'].includes(b.status))
+                fail('INVALID_STATE', `A ${b.status} booking can't be confirmed`, 409, { status: b.status });
+            if (holdLapsed(b))
+                fail('HOLD_EXPIRED', 'The hold on this booking has run out');
+            if (b.status === 'waitlisted') {
+                const old = mem.allocations.filter((a) => a.bookingId === b.id);
+                const claims = old.map((a) => a.mode === 'capacity'
+                    ? { kind: 'capacity', slotId: a.slotId, quantity: a.quantity }
+                    : { kind: 'exclusive', resourceType: a.resourceType, resourceId: a.resourceId, startsAt: a.startsAt, endsAt: a.endsAt, blockStartsAt: a.startsAt, blockEndsAt: a.endsAt });
+                mem.allocations = mem.allocations.filter((a) => a.bookingId !== b.id);
+                try {
+                    claimAll(b.id, claims, b.contactId, true);
+                }
+                catch (e) {
+                    mem.allocations.push(...old);
+                    throw e;
+                }
+            }
+            b.status = 'confirmed';
+            b.holdExpiresAt = null;
+            b.updatedAt = iso(now());
+            return copy(withAllocations(b));
+        },
+        async cancel(bookingId, opts = {}) {
+            const b = find(bookingId);
+            if (b.status === 'cancelled')
+                return copy(withAllocations(b));
+            if (!['held', 'pending', 'confirmed', 'waitlisted'].includes(b.status))
+                fail('INVALID_STATE', `A ${b.status} booking can't be cancelled`, 409, { status: b.status });
+            release(b);
+            b.status = 'cancelled';
+            b.cancelReason = opts.reason || 'admin';
+            b.cancelledAt = iso(now());
+            b.holdExpiresAt = null;
+            return copy(withAllocations(b));
+        },
+        async move(bookingId, input = {}) {
+            const b = find(bookingId);
+            if (!['held', 'pending', 'confirmed'].includes(b.status))
+                fail('INVALID_STATE', `A ${b.status} booking can't be moved`, 409, { status: b.status });
+            if (holdLapsed(b))
+                fail('HOLD_EXPIRED', 'The hold on this booking has run out');
+            const claims = claimsOf(Object.assign({ quantity: b.quantity }, input));
+            // Check against everything except this booking's own claims; only then release + claim.
+            const own = mem.allocations.filter((a) => a.bookingId === b.id);
+            const freedSeats = new Map();
+            for (const a of own)
+                if (a.active && a.mode === 'capacity')
+                    freedSeats.set(a.slotId, (freedSeats.get(a.slotId) || 0) + a.quantity);
+            for (const [slotId, n] of freedSeats) {
+                const s = mem.slots.find((x) => x.id === slotId);
+                if (s)
+                    s.booked -= n;
+            }
+            try {
+                const visible = claimAll(b.id + ':move', claims, b.contactId, true, b.id);
+                mem.allocations = mem.allocations.filter((a) => a.bookingId !== b.id);
+                for (const a of mem.allocations)
+                    if (a.bookingId === b.id + ':move')
+                        a.bookingId = b.id;
+                b.startsAt = input.startsAt ? iso(ms(input.startsAt)) : visible.startsAt;
+                b.endsAt = input.endsAt ? iso(ms(input.endsAt)) : visible.endsAt;
+                b.updatedAt = iso(now());
+            }
+            catch (e) {
+                for (const [slotId, n] of freedSeats) {
+                    const s = mem.slots.find((x) => x.id === slotId);
+                    if (s)
+                        s.booked += n;
+                }
+                throw e;
+            }
+            return copy(withAllocations(b));
+        },
+        async extendHold(bookingId, holdMinutes) {
+            const b = find(bookingId);
+            if (b.status !== 'held')
+                fail('INVALID_STATE', 'Only a held booking has a hold to extend', 409, { status: b.status });
+            if (holdLapsed(b))
+                fail('HOLD_EXPIRED', 'The hold on this booking has run out');
+            b.holdExpiresAt = iso(Math.min(now() + (holdMinutes !== null && holdMinutes !== void 0 ? holdMinutes : 15) * 60000, ms(b.createdAt) + 24 * 3600000));
+            return copy(withAllocations(b));
+        },
+        async complete(bookingId) { return outcome(find(bookingId), 'completed'); },
+        async noShow(bookingId) { return outcome(find(bookingId), 'no_show'); },
+        async freebusy(q = {}) {
+            const refs = (q.resources || []).map((r) => (typeof r === 'string' ? { type: r.slice(0, r.indexOf(':')), id: r.slice(r.indexOf(':') + 1) } : r));
+            return {
+                from: iso(ms(q.from)), to: iso(ms(q.to)),
+                resources: refs.map((r) => {
+                    const busy = mem.allocations
+                        .filter((a) => a.active && a.mode === 'exclusive' && a.resourceType === r.type && a.resourceId === r.id && overlaps(a, { startsAt: q.from, endsAt: q.to }))
+                        .map((a) => ({ start: Math.max(ms(a.startsAt), ms(q.from)), end: Math.min(ms(a.endsAt), ms(q.to)) }))
+                        .sort((a, b) => a.start - b.start);
+                    const merged = [];
+                    for (const x of busy) {
+                        const l = merged[merged.length - 1];
+                        if (l && x.start <= l.end)
+                            l.end = Math.max(l.end, x.end);
+                        else
+                            merged.push(Object.assign({}, x));
+                    }
+                    return { resourceType: r.type, resourceId: r.id, busy: merged.map((x) => ({ start: iso(x.start), end: iso(x.end) })) };
+                }),
+            };
+        },
+        slots: {
+            async create(input = {}) {
+                var _a, _b, _c, _d, _e, _f, _g;
+                if (!input.startsAt || !input.endsAt || ms(input.endsAt) <= ms(input.startsAt))
+                    fail('BAD_REQUEST', 'startsAt and endsAt are required, with endsAt after startsAt', 400);
+                const s = {
+                    id: id('slot'), startsAt: iso(ms(input.startsAt)), endsAt: iso(ms(input.endsAt)), capacity: Number(input.capacity), booked: 0,
+                    perContactLimit: (_a = input.perContactLimit) !== null && _a !== void 0 ? _a : null, status: input.status || 'open', visibility: input.visibility || 'public',
+                    resourceType: (_b = input.resourceType) !== null && _b !== void 0 ? _b : null, resourceId: (_c = input.resourceId) !== null && _c !== void 0 ? _c : null, seriesId: (_d = input.seriesId) !== null && _d !== void 0 ? _d : null,
+                    timezone: (_e = input.timezone) !== null && _e !== void 0 ? _e : null, ref: (_f = input.ref) !== null && _f !== void 0 ? _f : null, productId: (_g = input.productId) !== null && _g !== void 0 ? _g : null,
+                    data: input.data || {}, owner: input.owner || {}, admin: input.admin || {}, createdAt: iso(now()), deletedAt: null,
+                };
+                if (input.blockResource) {
+                    if (!s.resourceType || !s.resourceId)
+                        fail('BAD_REQUEST', 'blockResource needs resourceType + resourceId', 400);
+                    claimAll(null, [{ kind: 'exclusive', resourceType: s.resourceType, resourceId: s.resourceId, startsAt: s.startsAt, endsAt: s.endsAt, blockStartsAt: s.startsAt, blockEndsAt: s.endsAt }], null, true);
+                    mem.allocations[mem.allocations.length - 1].slotId = s.id;
+                }
+                mem.slots.push(s);
+                return slotView(s);
+            },
+            async createMany(inputs, opts = {}) {
+                const out = [];
+                for (const i of inputs || [])
+                    out.push(await this.create(Object.assign({ seriesId: opts.seriesId }, i)));
+                return out;
+            },
+            async get(slotId) { const s = slotOf(slotId); return s ? slotView(s) : null; },
+            async query(params = {}) {
+                let all = mem.slots.filter((s) => !s.deletedAt);
+                if (params.status)
+                    all = all.filter((s) => s.status === params.status);
+                if (params.available === true || params.available === 'true')
+                    all = all.filter((s) => s.booked < s.capacity);
+                if (params.from)
+                    all = all.filter((s) => ms(s.endsAt) > ms(params.from));
+                if (params.to)
+                    all = all.filter((s) => ms(s.startsAt) < ms(params.to));
+                all.sort((a, b) => ms(a.startsAt) - ms(b.startsAt));
+                return page(all.map((s) => (Object.assign(Object.assign({}, s), { remaining: remaining(s) }))), params);
+            },
+            async update(slotId, fields = {}) {
+                const s = slotOf(slotId);
+                if (!s)
+                    fail('NOT_FOUND', 'Slot not found', 404);
+                if (fields.capacity !== undefined && Number(fields.capacity) < s.booked)
+                    fail('SLOT_OVERBOOKED', `${s.booked} places are already booked`, 409, { booked: s.booked });
+                if ((fields.startsAt || fields.endsAt) && s.booked > 0)
+                    fail('SLOT_HAS_BOOKINGS', 'Move or cancel the bookings before changing the slot time', 409, { booked: s.booked });
+                for (const k of ['capacity', 'perContactLimit', 'status', 'visibility', 'timezone', 'ref', 'productId', 'data', 'owner', 'admin'])
+                    if (fields[k] !== undefined)
+                        s[k] = fields[k];
+                if (fields.startsAt)
+                    s.startsAt = iso(ms(fields.startsAt));
+                if (fields.endsAt)
+                    s.endsAt = iso(ms(fields.endsAt));
+                return slotView(s);
+            },
+            async delete(slotId) {
+                const s = slotOf(slotId);
+                if (!s)
+                    fail('NOT_FOUND', 'Slot not found', 404);
+                if (s.booked > 0)
+                    fail('SLOT_HAS_BOOKINGS', 'Cancel the bookings before deleting the slot', 409, { booked: s.booked });
+                s.deletedAt = iso(now());
+                s.status = 'cancelled';
+                mem.allocations = mem.allocations.filter((a) => !(a.slotId === s.id && a.bookingId === null));
+                return { success: true };
+            },
+        },
+        blocks: {
+            async create(input = {}) {
+                if (!input.resourceType || !input.resourceId)
+                    fail('BAD_REQUEST', 'resourceType and resourceId are required', 400);
+                if (!input.startsAt || !input.endsAt || ms(input.endsAt) <= ms(input.startsAt))
+                    fail('BAD_REQUEST', 'startsAt and endsAt are required, with endsAt after startsAt', 400);
+                const s = iso(ms(input.startsAt)), e = iso(ms(input.endsAt));
+                claimAll(null, [{ kind: 'exclusive', resourceType: String(input.resourceType), resourceId: String(input.resourceId), startsAt: s, endsAt: e, blockStartsAt: s, blockEndsAt: e }], null, true);
+                const a = mem.allocations[mem.allocations.length - 1];
+                a.data = input.data || {};
+                return copy(a);
+            },
+            async query(params = {}) {
+                let all = mem.allocations.filter((a) => a.bookingId === null && a.slotId === null);
+                if (params.resourceType)
+                    all = all.filter((a) => a.resourceType === params.resourceType);
+                if (params.resourceId)
+                    all = all.filter((a) => a.resourceId === params.resourceId);
+                return page(all, params);
+            },
+            async delete(blockId) {
+                const before = mem.allocations.length;
+                mem.allocations = mem.allocations.filter((a) => !(a.id === blockId && a.bookingId === null && a.slotId === null));
+                if (mem.allocations.length === before)
+                    fail('NOT_FOUND', 'Block not found', 404);
+                return { success: true };
+            },
+        },
+    };
+    function outcome(b, to) {
+        if (b.status === to)
+            return copy(withAllocations(b));
+        if (b.status !== 'confirmed')
+            fail('INVALID_STATE', `Only a confirmed booking can be marked ${to}`, 409, { status: b.status });
+        b.status = to;
+        return copy(withAllocations(b));
+    }
+}

package/dist/testing/index.d.ts

@@ -1,4 +1,5 @@
 import type { AppFunctionDef, ServerFunctionContext, ServerFunctionInputs } from '../types/appManifest.js';
+import { type BookingsMemory } from './bookingsMemory.js';
 export declare class CapabilityError extends Error {
     capability: string;
     code: string;
@@ -59,9 +60,16 @@ export interface TestSlImpl {
             getData?(opts?: any): any;
         };
     };
+    /**
+     * Bookings. Omit to use the built-in in-memory engine (capacity, per-person limits, no overlapping
+     * time, idempotent creates, holds) — inspect it via `ctx.memory.bookings`.
+     */
+    bookings?: Record<string, any>;
 }
 export interface TestCaller {
     userId?: string | null;
+    /** The caller's contact id, for `ctx.sl.bookings.mine()`. Default: `contact-of-<userId>` when signed in. */
+    contactId?: string | null;
     anonymous?: boolean;
     origin?: string | null;
     ip?: string | null;
@@ -98,6 +106,8 @@ export interface FunctionTestMemory {
         [k: string]: any;
     }>;
     interactions: any[];
+    /** Slots, bookings and allocations of the in-memory bookings engine. */
+    bookings: BookingsMemory;
 }
 /** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
 export declare function createFunctionTestMemory(): FunctionTestMemory;

package/dist/testing/index.js

@@ -14,10 +14,11 @@
 //  - `ctx.secrets` are FIXTURES you provide; real sealed secrets are server-only and
 //    never resolvable locally.
 //  - `ctx.fetch` is gated by the `network` capability just like production.
-//  - Without an injected impl, appRecords / counters / contacts / interactions run against an
-//    in-memory store with the platform's uniqueness rules (claim: singletonPer + customId; contacts by
-//    email/phone, fill-empty only), so idempotency and "never two of the same number" are testable.
-//    Inspect it via `ctx.memory`.
+//  - Without an injected impl, appRecords / counters / contacts / interactions / bookings run against
+//    an in-memory store with the platform's rules (claim: singletonPer + customId; contacts by
+//    email/phone, fill-empty only; bookings: capacity, per-person limits, no overlapping time,
+//    idempotent creates), so idempotency, "never two of the same number" and "never oversold" are
+//    testable. Inspect it via `ctx.memory`.
 var __rest = (this && this.__rest) || function (s, e) {
     var t = {};
     for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
@@ -29,6 +30,7 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
+import { bookingsMemoryImpl, createBookingsMemory } from './bookingsMemory.js';
 export class CapabilityError extends Error {
     constructor(capability, message) {
         super(message || `capability not granted: ${capability}`);
@@ -75,7 +77,7 @@ function allowsSl(p, resource, op) {
 }
 /** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
 export function createFunctionTestMemory() {
-    return { records: [], counters: {}, contacts: [], interactions: [] };
+    return { records: [], counters: {}, contacts: [], interactions: [], bookings: createBookingsMemory() };
 }
 const stub = (method, args) => ({ __stub: true, method, args });
 /**
@@ -88,7 +90,7 @@ const stub = (method, args) => ({ __stub: true, method, args });
  * CapabilityError — exactly as it would in production.
  */
 export function createFunctionTestContext(opts) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f, _g;
     const def = opts.def || {};
     const parsed = parseCapabilities(def.capabilities || []);
     const impl = opts.sl || {};
@@ -264,6 +266,25 @@ export function createFunctionTestContext(opts) {
             },
         };
     };
+    // Bookings — an injected impl, else the in-memory engine (same rules as the platform).
+    if (!mem.bookings)
+        mem.bookings = createBookingsMemory(); // a memory made before bookings existed
+    const callerContactId = (_b = (_a = opts.caller) === null || _a === void 0 ? void 0 : _a.contactId) !== null && _b !== void 0 ? _b : (((_c = opts.caller) === null || _c === void 0 ? void 0 : _c.userId) ? `contact-of-${opts.caller.userId}` : null);
+    const bk = impl.bookings || bookingsMemoryImpl(mem.bookings, { contactId: callerContactId });
+    const bkFn = (obj, name) => (obj && typeof obj[name] === 'function' ? obj[name].bind(obj) : undefined);
+    const BOOKING_READS = new Set(['get', 'query', 'mine', 'freebusy']);
+    sl.bookings = {};
+    for (const m of ['create', 'get', 'query', 'mine', 'update', 'confirm', 'cancel', 'move', 'extendHold', 'complete', 'noShow', 'freebusy']) {
+        sl.bookings[m] = gated('bookings', BOOKING_READS.has(m) ? 'read' : 'write', bkFn(bk, m), `bookings.${m}`);
+    }
+    sl.bookings.slots = {};
+    for (const m of ['create', 'createMany', 'get', 'query', 'update', 'delete']) {
+        sl.bookings.slots[m] = gated('bookings', m === 'get' || m === 'query' ? 'read' : 'write', bkFn(bk.slots, m), `bookings.slots.${m}`);
+    }
+    sl.bookings.blocks = {};
+    for (const m of ['create', 'query', 'delete']) {
+        sl.bookings.blocks[m] = gated('bookings', m === 'query' ? 'read' : 'write', bkFn(bk.blocks, m), `bookings.blocks.${m}`);
+    }
     const secretsMap = opts.secrets || {};
     const baseFetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : undefined);
     const via = (def.trigger && def.trigger.type) || 'http';
@@ -286,10 +307,10 @@ export function createFunctionTestContext(opts) {
             },
         },
         caller: {
-            userId: (_a = caller.userId) !== null && _a !== void 0 ? _a : null,
-            anonymous: (_b = caller.anonymous) !== null && _b !== void 0 ? _b : !caller.userId,
-            origin: (_c = caller.origin) !== null && _c !== void 0 ? _c : null,
-            ip: (_d = caller.ip) !== null && _d !== void 0 ? _d : null,
+            userId: (_d = caller.userId) !== null && _d !== void 0 ? _d : null,
+            anonymous: (_e = caller.anonymous) !== null && _e !== void 0 ? _e : !caller.userId,
+            origin: (_f = caller.origin) !== null && _f !== void 0 ? _f : null,
+            ip: (_g = caller.ip) !== null && _g !== void 0 ? _g : null,
             via,
         },
         fetch: (async (input, init) => {

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/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.71  |  Generated: 2026-10-24T17:23:20.711Z
+Version: 2.1.0  |  Generated: 2026-10-24T18:38:40.481Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2801,9 +2801,41 @@ interface ServerFunctionInteractionEvent {
 }
 ```
 
+**ServerFunctionBookings** (interface)
+```typescript
+interface ServerFunctionBookings {
+  create(input: CreateBookingInput): Promise<Booking & { replayed: boolean }>;
+  get(bookingId: string): Promise<Booking | null>;
+  query(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+  mine(params?: BookingListQueryParams): Promise<PaginatedResponse<Booking>>;
+  update(bookingId: string, fields: UpdateBookingInput): Promise<Booking>;
+  confirm(bookingId: string): Promise<Booking>;
+  cancel(bookingId: string, opts?: { reason?: string }): Promise<Booking>;
+  move(bookingId: string, input: MoveBookingInput): Promise<Booking>;
+  extendHold(bookingId: string, holdMinutes: number): Promise<Booking>;
+  complete(bookingId: string): Promise<Booking>;
+  noShow(bookingId: string): Promise<Booking>;
+  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 }>;
+  };
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
+  bookings: ServerFunctionBookings;
   appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
   counters: ServerFunctionCounters;
   tags: { resolve(id: string): Promise<ResolvedTag | null> };

package/docs/app-objects.md

@@ -927,6 +927,9 @@ The server reads this document at request time — no cache invalidation or serv
 
 ### Policy Structure
 
+Bookings use the same policy as a fourth object type, `publicCreate.bookings`, with booking-specific
+`limits` and `rules` — see [bookings.md](bookings.md).
+
 Each object type (`cases`, `threads`, `records`) has **independent branches** for anonymous and authenticated callers. Each branch carries its own `allow` flag, optional field overrides (`enforce`), and — for records — optional edit-token config (`edit`).
 
 ```typescript

package/docs/bookings.md

@@ -248,6 +248,33 @@ Off by default — most apps serve free times through their own function.
 
 ---
 
+## In a server function — `ctx.sl.bookings`
+
+When public booking is off, your app books through its own server function. `ctx.sl.bookings` is
+the same API, admin-side, for **your app's** bookings only (`sl:bookings:read` / `sl:bookings:write`):
+
+```ts
+// manifest: { name: 'book', trigger: { type: 'http' }, visibility: 'public', authority: 'collection',
+//             capabilities: ['sl:bookings:write', 'sl:contacts:write'] }
+export async function book(ctx, req) {
+  const me = await ctx.sl.contacts.forCaller()          // null when signed out
+  // … your rules: hours (utils.withinSchedule), a queue token, a member level, a price …
+  const b = await ctx.sl.bookings.create({
+    resourceType: 'record', resourceId: req.body.staffId,
+    startsAt: req.body.startsAt, endsAt: req.body.endsAt, bufferAfter: 10,
+    contactId: me?.contactId, status: 'confirmed', idempotencyKey: req.body.requestId,
+  })
+  return Response.json({ id: b.id, startsAt: b.startsAt })
+}
+```
+
+`create`, `get`, `query`, `mine` (the caller's own), `update`, `confirm`, `cancel`, `move`,
+`extendHold`, `complete`, `noShow`, `freebusy`, `slots.*`, `blocks.*`. Errors carry `code`,
+`status` and `details` exactly as over HTTP. The local test harness
+(`@proveanything/smartlinks/testing`) runs bookings in memory with the same rules.
+
+---
+
 ## Payments and high-demand sales
 
 The platform takes no payments. It gives you what a payment or credits flow needs:

package/docs/server-functions.md

@@ -167,7 +167,7 @@ Declare the minimum you need.
 
 | Capability | Grants |
 |---|---|
-| `sl:<resource>:read` / `sl:<resource>:write` | SDK access to that resource, e.g. `sl:products:read`, `sl:records:write`, `sl:attestations:write`, `sl:contacts:write`. |
+| `sl:<resource>:read` / `sl:<resource>:write` | SDK access to that resource, e.g. `sl:products:read`, `sl:records:write`, `sl:attestations:write`, `sl:contacts:write`, `sl:bookings:write`. |
 | `network` | `ctx.fetch` to any host. |
 | `network:<host>` | `ctx.fetch` to that host only (repeat for several). Prefer this over blanket `network`. |
 | `network:*.<domain>` | `ctx.fetch` to any subdomain of `<domain>` (not `<domain>` itself), for a customer's own endpoint at a provider, e.g. `network:*.servicebus.windows.net`. `<domain>` needs at least two labels (`*.com` is not honoured). |
@@ -517,6 +517,7 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
 | Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
 | Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
+| Take a booking with your own checks (hours, queue token, payment) | `ctx.sl.bookings.create({ slotId \| resource + time, contactId, status, idempotencyKey })` — never oversold, never double-booked; also `confirm` / `cancel` / `move` / `mine` / `freebusy` / `slots.*` / `blocks.*` (see [bookings.md](bookings.md)) | `sl:bookings:write` (`sl:bookings:read` to read) |
 
 Notes:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -611,6 +612,33 @@ await ctx.sl.interactions.record({
 })
 ```
 
+### `bookings.*` — places and time that can't be oversold
+
+`ctx.sl.bookings` is your app's own bookings, slots and blocks (`sl:bookings:read` / `write`). A
+function books **admin-side**: any status, the admin zone, any contact — your app's public booking
+rules (`publicCreate.bookings`) don't apply, because the function *is* your rules. The platform still
+guarantees no overbooking and no overlapping time, so a clash throws (`code`: `SLOT_FULL`,
+`RESOURCE_TAKEN`, `PER_CONTACT_LIMIT`, `HOLD_EXPIRED`, …; with `status` and `details`). Pass an
+`idempotencyKey` so a retried request returns the first booking (`replayed: true`).
+
+```ts
+const me = await ctx.sl.contacts.forCaller()
+if (!me) return Response.json({ error: 'sign in' }, { status: 401 })
+try {
+  const booking = await ctx.sl.bookings.create({
+    slotId: body.slotId, quantity: body.quantity, contactId: me.contactId,
+    status: 'held', holdMinutes: 15, idempotencyKey: body.requestId,
+  })
+  return Response.json({ id: booking.id, holdExpiresAt: booking.holdExpiresAt })
+} catch (e: any) {
+  if (e.code === 'SLOT_FULL') return Response.json({ error: 'sold out', remaining: e.details?.remaining }, { status: 409 })
+  throw e
+}
+```
+
+The local harness runs bookings in memory with the same rules (capacity, per-person limits, no
+overlaps, idempotency, holds): `ctx.memory.bookings`.
+
 ---
 
 ## Platform tools — PDFs, labels, barcodes

package/openapi.yaml

@@ -20224,9 +20224,23 @@ components:
           type: string
       required:
         - interactionId
+    ServerFunctionBookings:
+      type: object
+      properties:
+        slots:
+          type: object
+          additionalProperties: true
+        blocks:
+          type: object
+          additionalProperties: true
+      required:
+        - slots
+        - blocks
     ServerFunctionSl:
       type: object
       properties:
+        bookings:
+          $ref: "#/components/schemas/ServerFunctionBookings"
         appRecords:
           type: object
           additionalProperties: true
@@ -20249,6 +20263,7 @@ components:
         appData:
           $ref: "#/components/schemas/AppDataHandle"
       required:
+        - bookings
         - appRecords
         - counters
         - tags

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.71",
+  "version": "2.1.0",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",