@awesomate/sdk 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -24,7 +24,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export declare const VERSION = "0.24.0";
+export declare const VERSION = "0.25.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -205,9 +205,13 @@ export interface TaskCard {
 /** The Tasks board, as the account's token sees it (the owner, so `scope: 'all'` works). */
 export interface TaskBoard {
     scope: 'mine' | 'all';
+    /** Whether this person may ask for `scope: 'all'`: the owner only. */
+    canChooseScope: boolean;
     me: TaskPerson & {
         role: string;
     };
+    /** Whether this person may give tasks (everyone but view-only people). */
+    canGive: boolean;
     /** Who a task can be given to. */
     people: Array<TaskPerson & {
         me: boolean;
@@ -218,7 +222,10 @@ export interface TaskBoard {
     later: TaskCard[];
     /** With someone else. */
     waiting: TaskCard[];
-    /** Recently decided, for the record. */
+    /**
+     * Recently decided, for the record. `canBringBack` is true for a given task this person may open
+     * again with bringBack(): the number after `task:` in its key is the task's id.
+     */
     decided: Array<{
         key: string;
         kind: string;
@@ -226,7 +233,49 @@ export interface TaskBoard {
         text: string;
         by: TaskPerson | null;
         at: string;
+        canBringBack: boolean;
     }>;
+    /**
+     * Places the board could not read just now, in the owner's words. When it is not empty the
+     * board may be missing cards from them: say so rather than treating the board as complete.
+     */
+    unavailable: string[];
+    /** Whether anyone besides the owner is on the account. */
+    hasTeam: boolean;
+}
+/** One step in a task's record, in order. */
+export interface TaskRecordStep {
+    at: string;
+    /** What happened, in a sentence. */
+    text: string;
+    /** Where it happened (email, Telegram), when that was not the hub; otherwise null. */
+    place: string | null;
+    /** How long since the step before, when it is worth showing ("29 min later"). */
+    gap: string | null;
+    tone: 'start' | 'move' | 'seen' | 'answer' | 'end';
+}
+/** What happened to a given task, from tasks.record(): who gave it, who passed it on, who closed it, and how long each person had it. */
+export interface TaskRecord {
+    kind: 'task';
+    title: string;
+    state: string;
+    steps: TaskRecordStep[];
+    timings: {
+        /** From given to done or dropped; null while it is open. */
+        totalMs: number | null;
+        total: string | null;
+        /** From reaching its first person to that person's first look; null when they have not looked. */
+        untilFirstSeenMs: number | null;
+        untilFirstSeen: string | null;
+        /** Time with each person, in order of first holding it. */
+        withPeople: Array<{
+            name: string;
+            ms: number;
+            text: string;
+        }>;
+        /** How many times it moved to someone else after it was first given. */
+        handoffs: number;
+    };
 }
 /** A task to give: to someone on the account by email, or to the owner when `forEmail` is left out. */
 export interface GiveTask {
@@ -251,6 +300,17 @@ export interface FileEntry {
     /** For a file in public/: the address anyone with it can open, with no login. Otherwise null. */
     public_url: string | null;
 }
+/** Something in the Files trash, from files.trash(). */
+export interface TrashEntry {
+    /** Where it sits in the trash. */
+    path: string;
+    /** What it was called before it was removed. */
+    name: string;
+    type: 'file' | 'dir';
+    bytes: number;
+    /** When it was removed, or null when the trash name does not say. */
+    deleted_at: string | null;
+}
 /** How much of the plan's Files space is used. */
 export interface FilesUsage {
     used_bytes: number;
@@ -393,6 +453,23 @@ export declare class AwesomateClient {
         remove: (path: string) => Promise<{
             trashPath: string;
         }>;
+        /** What is in the trash, and how many bytes it holds. Needs files:read. */
+        trash: () => Promise<{
+            entries: TrashEntry[];
+            total_bytes: number;
+        }>;
+        /**
+         * Erase what is in the trash, for good: the only call that deletes a file outright. With
+         * `olderThanDays` (1 to 3650), only what was removed longer ago than that. Needs files:write.
+         * An automation account that cannot empty its trash yet answers serverCode trash_empty_unavailable.
+         */
+        emptyTrash: (options?: {
+            olderThanDays?: number;
+        }) => Promise<{
+            removed: number;
+            bytes: number;
+            files: number;
+        }>;
     };
     private tasksCall;
     /**
@@ -422,16 +499,122 @@ export declare class AwesomateClient {
         done: (id: number | string) => Promise<void>;
         /** Take a given task off the board without doing it: whoever wrote it, or the owner. */
         drop: (id: number | string) => Promise<void>;
+        /**
+         * Open a done or dropped task again, with the person who had it. They get an email unless
+         * they are the one bringing it back. Who may: see `decided[].canBringBack` on the board.
+         */
+        bringBack: (id: number | string) => Promise<{
+            emailed: boolean;
+        }>;
+        /**
+         * What happened to a given task, in order: who gave it, who passed it on, who closed it and
+         * brought it back, and how long each person had it. The owner reads any task's record; anyone
+         * else only one they were part of.
+         */
+        record: (id: number | string) => Promise<TaskRecord>;
         /** Put a card off until a time (at most 90 days), for this person only. */
         notNow: (key: string, until: Date | string) => Promise<{
             until: string;
         }>;
+        /** Bring a card put off with notNow() back now, for this person. */
+        cancelNotNow: (key: string) => Promise<void>;
         /** Hand a card to someone on the account who can act on it. */
         passOn: (key: string, toEmail: string, reason?: string) => Promise<{
             holder: TaskPerson;
             emailed: boolean;
         }>;
     };
+    /**
+     * The account's bookings, for the business's own staff screens: the list with each customer,
+     * one booking, the open times, and booking, cancelling, moving and recording an outcome on
+     * anyone's behalf. Needs the account's token (never an app key) and Bookings on the account.
+     * Reading needs crm:read, on every plan; changing needs crm:write, Support Plus and above.
+     * Booking, moving and cancelling email the customer and the calendar's notice address, unless
+     * `notify: false` (say a booking taken by phone that you confirm yourself). For visitors who are
+     * not signed in, use createBookingsClient() instead.
+     *
+     * @example
+     * const today = await db.bookings.list({ from: '2026-10-08T00:00:00+11:00', to: '2026-10-09T00:00:00+11:00', status: 'confirmed' });
+     */
+    readonly bookings: {
+        /**
+         * Bookings that start in a window, soonest first, each with its customer. The window is from a
+         * day ago for 31 days unless told otherwise; `limit` is 1 to 500 (default 200).
+         */
+        list: (options?: {
+            from?: Date | string;
+            to?: Date | string;
+            status?: StaffBooking["status"];
+            calendar?: string;
+            limit?: number;
+        }) => Promise<StaffBooking[]>;
+        /** One booking by its id, or null when there is none (an id that is not a booking id never reaches the hub). */
+        get: (id: string) => Promise<StaffBooking | null>;
+        /**
+         * The times a service can be booked, from now for two weeks unless told otherwise (at most 62
+         * days at once). The same open times customers see; book() with `outsideHours` goes beyond them.
+         */
+        openTimes: (service: string, options?: {
+            from?: Date | string;
+            to?: Date | string;
+            calendar?: string;
+            seats?: number;
+        }) => Promise<OpenTime[]>;
+        /**
+         * Book a time for a customer named by email (found in Contacts, or added; consent is never
+         * changed). Switches Bookings on if it was not. A time that is not open is refused with code
+         * `conflict` and `field` saying why: not_open, slot_taken, too_many_seats, session_full or
+         * day_full. Pass `idempotencyKey` so a retry returns the same booking.
+         */
+        book: (request: StaffBookingRequest) => Promise<{
+            bookingId: string;
+            created: boolean;
+            startsAt: string;
+            endsAt: string;
+        }>;
+        /** Cancel a booking. A booking already cancelled answers `cancelled: false`. */
+        cancel: (id: string, options?: {
+            reason?: string;
+            notify?: boolean;
+        }) => Promise<{
+            bookingId: string;
+            cancelled: boolean;
+            status: string | null;
+        }>;
+        /**
+         * Move a confirmed booking to a new start, on the same calendar or another (`calendar`). A time
+         * that is not open is refused with code `conflict` (field not_open, slot_taken, session_full or
+         * day_full) unless `outsideHours`; a booking that is not confirmed, or a time that has passed,
+         * with code `validation`.
+         */
+        move: (id: string, startsAt: Date | string, options?: {
+            calendar?: string;
+            outsideHours?: boolean;
+            notify?: boolean;
+        }) => Promise<{
+            bookingId: string;
+            startsAt: string;
+            endsAt: string;
+            calendar: string;
+        }>;
+        /** Record how a booking went: the customer came (`completed`) or did not (`no_show`). Sends no email. */
+        outcome: (id: string, status: "completed" | "no_show") => Promise<void>;
+    };
+    /**
+     * Tell Contacts something happened to someone ("job_paid", "quote_sent"), so any email series
+     * waiting for that event starts or stops for them. The person is found by email, or added; it
+     * never signs anyone up for email or changes their consent. Sending the same `key` twice records
+     * the event once (`duplicate: true`), so pass your own id for it. `record` names the quote, job or
+     * booking it is about. An event more than two days old is kept as a fact a series reads, never
+     * a start. Needs the account's token with crm:write (Support Plus and above), never an app key.
+     * The answer is the same whether or not the address belongs to someone erased from Contacts.
+     *
+     * @example
+     * await db.recordEvent({ event: 'job_paid', email: 'sam@example.com', record: 'job-1042', key: 'xero:INV-1042' });
+     */
+    recordEvent(event: SeriesEvent): Promise<{
+        duplicate: boolean;
+    }>;
     /** The kinds this token can read, their columns, operators and examples. */
     schema(): Promise<{
         kinds: Array<{
@@ -466,7 +649,10 @@ export declare class AwesomateClient {
     queryAll<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: Omit<QueryOptions<RowOf<K>, S>, 'after'> & {
         maxRows?: number;
     }): AsyncGenerator<Pick<RowOf<K>, S>>;
-    /** One row by id, or null when there is none this token can read. */
+    /**
+     * One row by id, or null when there is none this token can read. Ids are UUIDs: anything else
+     * names no row, so it answers null without asking the hub.
+     */
     get<K extends KindName>(kind: K, id: string, options?: {
         tz?: string;
     }): Promise<RowOf<K> | null>;
@@ -537,6 +723,18 @@ export declare class AwesomateClient {
      * gone 30 days unused, and not before 2026-11-06.
      */
     businessMapV1(): Promise<BusinessMapV1>;
+    /**
+     * The business's long documents that exist (brand guide, voice guide, brand from the website,
+     * business summary): kind, version, length and where each came from, without the text. Needs
+     * the account's token (hosting:read, every plan), never an app key.
+     */
+    businessDocuments(): Promise<BusinessDocumentSummary[]>;
+    /**
+     * One of the business's documents with its text (the current version), or null when the
+     * business has none of that kind yet. The text is the owner's own: use it for their business
+     * (agent instructions, site copy in their voice), never show it to anyone else.
+     */
+    businessDocument(kind: BusinessDocumentKind): Promise<BusinessDocument | null>;
     /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */
     businessSuggestions(): Promise<BusinessSuggestion[]>;
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
@@ -1021,6 +1219,44 @@ export interface BusinessSuggestion {
     sourceRef: string | null;
     recordedAt: string;
 }
+/** The business's long documents, by kind. */
+export type BusinessDocumentKind = 'brand_guide' | 'voice_guide' | 'website_brand' | 'business_summary';
+/** One of the business's documents, without its text (businessDocuments()). */
+export interface BusinessDocumentSummary {
+    kind: BusinessDocumentKind;
+    /** What the owner sees it called in the hub ("Voice and style guide"). */
+    label: string;
+    /** Goes up by one each time it is saved again. */
+    version: number;
+    /** How long the text is, in characters. */
+    chars: number;
+    /** Where this version came from: the owner, the onboarding agent, a chat brought in, a file. */
+    sourceKind: string;
+    recordedAt: string;
+}
+/** One of the business's documents with its text (businessDocument()). */
+export interface BusinessDocument extends BusinessDocumentSummary {
+    /** The document itself, usually Markdown. The owner's own words. */
+    body: string;
+}
+/**
+ * What happened to someone, for recordEvent(). `event` is lower case: letters, digits and
+ * `_ . : -`, up to 64 characters ("job_paid", "quote_sent").
+ */
+export interface SeriesEvent {
+    event: string;
+    /** Whose event it is. Found in Contacts, or added. */
+    email: string;
+    /** The quote, job or booking it is about (1 to 120 characters). A series that runs per record keys on it. */
+    record?: string;
+    /** When it happened. Default now. */
+    occurredAt?: Date | string;
+    /** Your own id for the event (1 to 200 characters). Sending the same key again records it once. */
+    key?: string;
+    /** Used only when the person is added to Contacts by this event. */
+    firstName?: string;
+    lastName?: string;
+}
 /** One attribute (column) of a kind. */
 export interface AttributeSpec {
     key: string;
@@ -1031,6 +1267,20 @@ export interface AttributeSpec {
     sensitivity?: 'ordinary' | 'personal' | 'sensitive';
     /** Default false. Only readable attributes reach query(), get() and the generated types. */
     readable_by_ai?: boolean;
+    /**
+     * Which of the app's roles see this attribute (up to 10, lower case). Left out or null: everyone
+     * who can read the record. An empty list: none of the app's people.
+     */
+    visible_to?: string[] | null;
+}
+/**
+ * Who among an app's signed-in people may read and change a kind's records, by role. Each rule is
+ * `all`, `none`, `own` (records they created) or `linked:<link>` (records linked to them, such as
+ * `linked:customer` or `linked:job.customer`); join several with `|`. A role left out gets none.
+ */
+export interface KindAccess {
+    read?: Record<string, string>;
+    write?: Record<string, string>;
 }
 /** A kind to define: a table an app keeps. */
 export interface KindSpec {
@@ -1046,16 +1296,22 @@ export interface KindSpec {
         to_label?: string;
         required?: boolean;
     }>;
+    /** The app's access rules, set with the kind. Until a kind has rules, owner and staff can do everything with it and members nothing. */
+    access?: KindAccess;
 }
 /** A kind as the account has defined it. */
-export interface KindDescription extends Omit<KindSpec, 'attributes'> {
+export interface KindDescription extends Omit<KindSpec, 'attributes' | 'access'> {
     storage: 'plain' | 'tracked';
     attributes: Array<Required<Pick<AttributeSpec, 'key' | 'label' | 'type' | 'required' | 'sensitivity' | 'readable_by_ai'>> & {
         choices: string[] | null;
+        visible_to: string[] | null;
     }>;
+    /** The kind's access rules. A kind with none set reads owner and staff `all`, for reading and writing. */
+    access: KindAccess;
     views: {
         all: string;
         for_agents: string;
+        for_app: string;
     };
 }
 /** Options for write(). */
@@ -1130,6 +1386,8 @@ export interface RecipeSpec {
 export interface RecipeDescription extends Required<Omit<RecipeSpec, 'description' | 'params'>> {
     description: string | null;
     params: ParamSpec[];
+    /** The app roles that may run it from the app (empty: only your server, with the account's token or an app key). The owner sets them in the hub or with Claude Code. */
+    run_by: string[];
     updated_at: string;
 }
 /** What a recipe run wrote. */
@@ -1336,7 +1594,10 @@ export declare class AwesomateAppClient {
     queryAll<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: Omit<QueryOptions<RowOf<K>, S>, 'after'> & {
         maxRows?: number;
     }): AsyncGenerator<Pick<RowOf<K>, S>>;
-    /** One record by id, or null when there is none this user may read. */
+    /**
+     * One record by id, or null when there is none this user may read. Ids are UUIDs: anything
+     * else names no record, so it answers null without asking the hub.
+     */
     get<K extends KindName>(kind: K, id: string): Promise<RowOf<K> | null>;
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. */
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
@@ -1474,6 +1735,8 @@ export interface BookableService {
     /** The price as the business wrote it. Shown, never charged. */
     price_text: string;
     location: string;
+    /** How many hours before the start a customer can still cancel or move online. */
+    cancel_cutoff_hours: number;
     intake: BookingQuestion[];
     calendars: Array<{
         key: string;
@@ -1538,6 +1801,66 @@ export interface ManagedBooking {
     canCancel: boolean;
     canMove: boolean;
     changesCloseAt: string;
+    /** The price as the business wrote it. Shown, never charged. */
+    priceText: string;
+}
+/** How the business looks, for a booking page in its colours. Each is null when the business has not set it. */
+export interface BookingPageLook {
+    /** The business's website (https). */
+    website: string | null;
+    /** Its logo's address (https). */
+    logo: string | null;
+    /** Its main colour, as #rrggbb. */
+    colour: string | null;
+}
+/** A booking as the business's staff see it (db.bookings), with its customer. */
+export interface StaffBooking {
+    bookingId: string;
+    status: 'confirmed' | 'cancelled' | 'completed' | 'no_show';
+    /** The service's key, and its name when the booking was made. */
+    service: string;
+    serviceName: string | null;
+    /** The calendar's key, and its name when the booking was made. */
+    calendar: string;
+    calendarName: string | null;
+    startsAt: string;
+    endsAt: string;
+    seats: number;
+    /** How it was made: website, hub, phone, agent or api. */
+    source: string | null;
+    /** The customer's answers to the service's questions, by question key. */
+    answers: Record<string, string | string[]> | null;
+    /** The customer's contact id in Contacts. */
+    contactId: string;
+    /** The customer, or null when they have since been removed from Contacts. */
+    customer: {
+        name: string | null;
+        email: string | null;
+        phone: string | null;
+    } | null;
+    createdAt: string;
+    cancelledAt: string | null;
+}
+/** What db.bookings.book() needs. Take `startsAt` and `calendar` from an OpenTime. */
+export interface StaffBookingRequest {
+    service: string;
+    calendar: string;
+    startsAt: string;
+    /** The customer, found in Contacts by email or added. */
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    /** Places, for a class. Default 1. */
+    seats?: number;
+    /** Answers to the service's questions, by question key. */
+    answers?: Record<string, string | string[]>;
+    /** One per booking, kept across retries, so a retry returns the same booking. */
+    idempotencyKey?: string;
+    /** Book outside the calendar's hours and notice. Overlap, seats and the daily limit still apply. */
+    outsideHours?: boolean;
+    /** false: no email to the customer (the calendar's notice address still hears). Default true. */
+    notify?: boolean;
 }
 /** Options for createBookingsClient(). */
 export interface BookingsClientOptions {
@@ -1579,13 +1902,19 @@ export declare class AwesomateBookingsClient {
     }): Promise<OpenTime[]>;
     /**
      * Book a time for a visitor. They get an email with an invite and a link to change or cancel;
-     * the business gets a notice. A time taken since you listed it is refused with code `conflict`
-     * and `field` saying why (not_open, slot_taken, session_full, day_full): list the times again.
+     * the business gets a notice. A refusal has code `conflict` and `field` saying why:
+     * - `not_open`, `slot_taken`, `too_many_seats`, `session_full`, `day_full`: the time is not
+     *   free (taken since you listed it, or not enough places left): list the times again;
+     * - `too_many_open`: this email already has three bookings coming up;
+     * - `monthly_limit`: the business has taken its plan's online bookings for the month.
+     *
+     * Show `personMessage` to the visitor for the last two.
      */
     book(request: BookingRequest): Promise<BookingResult>;
-    /** One booking, from the token in its manage link (manageTokenFrom()). */
+    /** One booking, from the token in its manage link (manageTokenFrom()), with how the business looks so the page can match it. */
     booking(manageToken: string): Promise<{
         business: string;
+        look: BookingPageLook;
         booking: ManagedBooking;
     }>;
     /** The times a booking could move to, leaving its own time out. */
@@ -1593,11 +1922,18 @@ export declare class AwesomateBookingsClient {
         from?: Date | string;
         to?: Date | string;
     }): Promise<OpenTime[]>;
-    /** Cancel a booking from its manage link. A second cancel answers cancelled: false. */
+    /**
+     * Cancel a booking from its manage link. A second cancel answers cancelled: false. Once changes
+     * have closed (`canCancel` false) it is refused with code `conflict`, field `too_late`.
+     */
     cancel(manageToken: string, reason?: string): Promise<{
         cancelled: boolean;
     }>;
-    /** Move a booking to a time from openTimesToMove(). */
+    /**
+     * Move a booking to a time from openTimesToMove(). Refused with code `conflict` and field
+     * `too_late` once changes have closed, or `not_open` (or another of book()'s reasons) when the
+     * time is no longer free.
+     */
     move(manageToken: string, startsAt: string): Promise<{
         startsAt: string;
         endsAt: string;

package/dist/index.js

@@ -24,8 +24,10 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.24.0';
+export const VERSION = '0.25.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
+/** Every record and contact id is a UUID; anything else can name no row. */
+const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
  * Every failure from the hub. `message` is for you, the developer; `personMessage`, when the hub
@@ -229,6 +231,24 @@ export class AwesomateClient {
         },
         /** Move to the trash. Not erased, and no longer counted toward the Files space. */
         remove: async (path) => this.filesCall('DELETE', `/api/files?path=${encodeURIComponent(path)}`),
+        /** What is in the trash, and how many bytes it holds. Needs files:read. */
+        trash: async () => {
+            const r = await this.filesCall('GET', '/api/files/trash');
+            return { entries: r.entries, total_bytes: r.total_bytes };
+        },
+        /**
+         * Erase what is in the trash, for good: the only call that deletes a file outright. With
+         * `olderThanDays` (1 to 3650), only what was removed longer ago than that. Needs files:write.
+         * An automation account that cannot empty its trash yet answers serverCode trash_empty_unavailable.
+         */
+        emptyTrash: async (options = {}) => {
+            const days = options.olderThanDays;
+            if (days !== undefined && (!Number.isInteger(days) || days < 1 || days > 3650)) {
+                throw new AwesomateError('validation', 'olderThanDays is a whole number of days from 1 to 3650, or leave it out to empty everything.', 0, 'olderThanDays');
+            }
+            const r = await this.filesCall('POST', '/api/files/trash/empty', days === undefined ? {} : { older_than_days: days });
+            return { removed: r.removed, bytes: r.bytes, files: r.files };
+        },
     };
     tasksCall(method, path, body) {
         if (this.appKey) {
@@ -265,6 +285,20 @@ export class AwesomateClient {
         drop: async (id) => {
             await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/drop`);
         },
+        /**
+         * Open a done or dropped task again, with the person who had it. They get an email unless
+         * they are the one bringing it back. Who may: see `decided[].canBringBack` on the board.
+         */
+        bringBack: async (id) => {
+            const r = await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/reopen`);
+            return { emailed: r.emailed };
+        },
+        /**
+         * What happened to a given task, in order: who gave it, who passed it on, who closed it and
+         * brought it back, and how long each person had it. The owner reads any task's record; anyone
+         * else only one they were part of.
+         */
+        record: (id) => this.tasksCall('GET', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/record`),
         /** Put a card off until a time (at most 90 days), for this person only. */
         notNow: async (key, until) => {
             const r = await this.tasksCall('POST', `/api/my-tasks/items/${encodeURIComponent(key)}/not-now`, {
@@ -272,6 +306,10 @@ export class AwesomateClient {
             });
             return { until: r.until };
         },
+        /** Bring a card put off with notNow() back now, for this person. */
+        cancelNotNow: async (key) => {
+            await this.tasksCall('DELETE', `/api/my-tasks/items/${encodeURIComponent(key)}/not-now`);
+        },
         /** Hand a card to someone on the account who can act on it. */
         passOn: async (key, toEmail, reason) => {
             const r = await this.tasksCall('POST', `/api/my-tasks/items/${encodeURIComponent(key)}/pass-on`, {
@@ -280,6 +318,126 @@ export class AwesomateClient {
             return { holder: r.holder, emailed: r.emailed };
         },
     };
+    /**
+     * The account's bookings, for the business's own staff screens: the list with each customer,
+     * one booking, the open times, and booking, cancelling, moving and recording an outcome on
+     * anyone's behalf. Needs the account's token (never an app key) and Bookings on the account.
+     * Reading needs crm:read, on every plan; changing needs crm:write, Support Plus and above.
+     * Booking, moving and cancelling email the customer and the calendar's notice address, unless
+     * `notify: false` (say a booking taken by phone that you confirm yourself). For visitors who are
+     * not signed in, use createBookingsClient() instead.
+     *
+     * @example
+     * const today = await db.bookings.list({ from: '2026-10-08T00:00:00+11:00', to: '2026-10-09T00:00:00+11:00', status: 'confirmed' });
+     */
+    bookings = {
+        /**
+         * Bookings that start in a window, soonest first, each with its customer. The window is from a
+         * day ago for 31 days unless told otherwise; `limit` is 1 to 500 (default 200).
+         */
+        list: async (options = {}) => {
+            const q = new URLSearchParams();
+            const from = iso(options.from);
+            const to = iso(options.to);
+            if (from)
+                q.set('from', from);
+            if (to)
+                q.set('to', to);
+            if (options.status)
+                q.set('status', options.status);
+            if (options.calendar)
+                q.set('calendar', options.calendar);
+            if (options.limit)
+                q.set('limit', String(options.limit));
+            const qs = q.toString();
+            const r = await this.request('GET', `/api/my-crm/v1/bookings${qs ? `?${qs}` : ''}`, undefined, false);
+            return r.bookings.map(staffBooking);
+        },
+        /** One booking by its id, or null when there is none (an id that is not a booking id never reaches the hub). */
+        get: async (id) => {
+            if (!RECORD_ID.test(String(id)))
+                return null;
+            try {
+                const r = await this.request('GET', `/api/my-crm/v1/bookings/${encodeURIComponent(String(id))}`, undefined, false);
+                return staffBooking(r.booking);
+            }
+            catch (err) {
+                if (err instanceof AwesomateError && err.code === 'not_found')
+                    return null;
+                throw err;
+            }
+        },
+        /**
+         * The times a service can be booked, from now for two weeks unless told otherwise (at most 62
+         * days at once). The same open times customers see; book() with `outsideHours` goes beyond them.
+         */
+        openTimes: async (service, options = {}) => {
+            const q = new URLSearchParams({ service });
+            const from = iso(options.from);
+            const to = iso(options.to);
+            if (from)
+                q.set('from', from);
+            if (to)
+                q.set('to', to);
+            if (options.calendar)
+                q.set('calendar', options.calendar);
+            if (options.seats)
+                q.set('seats', String(options.seats));
+            return (await this.request('GET', `/api/my-crm/v1/bookings/open-times?${q}`, undefined, false)).times;
+        },
+        /**
+         * Book a time for a customer named by email (found in Contacts, or added; consent is never
+         * changed). Switches Bookings on if it was not. A time that is not open is refused with code
+         * `conflict` and `field` saying why: not_open, slot_taken, too_many_seats, session_full or
+         * day_full. Pass `idempotencyKey` so a retry returns the same booking.
+         */
+        book: async (request) => {
+            const r = await this.request('POST', '/api/my-crm/v1/bookings', {
+                service: request.service, calendar: request.calendar, starts_at: request.startsAt, email: request.email,
+                first_name: request.firstName, last_name: request.lastName, phone: request.phone, seats: request.seats, answers: request.answers,
+                idempotency_key: request.idempotencyKey, outside_hours: request.outsideHours, notify: request.notify,
+            }, false);
+            return { bookingId: r.booking_id, created: r.created, startsAt: r.starts_at, endsAt: r.ends_at };
+        },
+        /** Cancel a booking. A booking already cancelled answers `cancelled: false`. */
+        cancel: async (id, options = {}) => {
+            const r = await this.request('POST', `/api/my-crm/v1/bookings/${encodeURIComponent(String(id))}/cancel`, { reason: options.reason, notify: options.notify }, false);
+            return { bookingId: r.booking_id, cancelled: r.cancelled, status: r.status };
+        },
+        /**
+         * Move a confirmed booking to a new start, on the same calendar or another (`calendar`). A time
+         * that is not open is refused with code `conflict` (field not_open, slot_taken, session_full or
+         * day_full) unless `outsideHours`; a booking that is not confirmed, or a time that has passed,
+         * with code `validation`.
+         */
+        move: async (id, startsAt, options = {}) => {
+            const r = await this.request('POST', `/api/my-crm/v1/bookings/${encodeURIComponent(String(id))}/move`, { starts_at: iso(startsAt), calendar: options.calendar, outside_hours: options.outsideHours, notify: options.notify }, false);
+            return { bookingId: r.booking_id, startsAt: r.starts_at, endsAt: r.ends_at, calendar: r.calendar };
+        },
+        /** Record how a booking went: the customer came (`completed`) or did not (`no_show`). Sends no email. */
+        outcome: async (id, status) => {
+            await this.request('POST', `/api/my-crm/v1/bookings/${encodeURIComponent(String(id))}/outcome`, { status }, false);
+        },
+    };
+    /**
+     * Tell Contacts something happened to someone ("job_paid", "quote_sent"), so any email series
+     * waiting for that event starts or stops for them. The person is found by email, or added; it
+     * never signs anyone up for email or changes their consent. Sending the same `key` twice records
+     * the event once (`duplicate: true`), so pass your own id for it. `record` names the quote, job or
+     * booking it is about. An event more than two days old is kept as a fact a series reads, never
+     * a start. Needs the account's token with crm:write (Support Plus and above), never an app key.
+     * The answer is the same whether or not the address belongs to someone erased from Contacts.
+     *
+     * @example
+     * await db.recordEvent({ event: 'job_paid', email: 'sam@example.com', record: 'job-1042', key: 'xero:INV-1042' });
+     */
+    async recordEvent(event) {
+        const r = await this.request('POST', '/api/my-crm/v1/events', {
+            event: event.event, email: event.email, record: event.record, occurred_at: iso(event.occurredAt), key: event.key,
+            first_name: event.firstName, last_name: event.lastName,
+        }, false);
+        return { duplicate: !!r.duplicate };
+    }
     /** The kinds this token can read, their columns, operators and examples. */
     schema() {
         return this.request('GET', '/api/my-crm/v1/rows/schema');
@@ -317,8 +475,13 @@ export class AwesomateClient {
             after = page.next ?? undefined;
         } while (after);
     }
-    /** One row by id, or null when there is none this token can read. */
+    /**
+     * One row by id, or null when there is none this token can read. Ids are UUIDs: anything else
+     * names no row, so it answers null without asking the hub.
+     */
     async get(kind, id, options = {}) {
+        if (!RECORD_ID.test(String(id)))
+            return null;
         try {
             const qs = options.tz ? `?tz=${encodeURIComponent(options.tz)}` : '';
             const r = await this.request('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}${qs}`);
@@ -431,6 +594,29 @@ export class AwesomateClient {
     async businessMapV1() {
         return (await this.request('GET', '/api/my-business/v1/map?format=json')).map;
     }
+    /**
+     * The business's long documents that exist (brand guide, voice guide, brand from the website,
+     * business summary): kind, version, length and where each came from, without the text. Needs
+     * the account's token (hosting:read, every plan), never an app key.
+     */
+    async businessDocuments() {
+        return (await this.request('GET', '/api/my-business/v1/documents')).documents;
+    }
+    /**
+     * One of the business's documents with its text (the current version), or null when the
+     * business has none of that kind yet. The text is the owner's own: use it for their business
+     * (agent instructions, site copy in their voice), never show it to anyone else.
+     */
+    async businessDocument(kind) {
+        try {
+            return await this.request('GET', `/api/my-business/v1/documents/${encodeURIComponent(kind)}`);
+        }
+        catch (err) {
+            if (err instanceof AwesomateError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
     /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */
     async businessSuggestions() {
         return (await this.request('GET', '/api/my-business/v1/proposals')).proposals;
@@ -726,8 +912,13 @@ export class AwesomateAppClient {
             after = page.next ?? undefined;
         } while (after);
     }
-    /** One record by id, or null when there is none this user may read. */
+    /**
+     * One record by id, or null when there is none this user may read. Ids are UUIDs: anything
+     * else names no record, so it answers null without asking the hub.
+     */
     async get(kind, id) {
+        if (!RECORD_ID.test(String(id)))
+            return null;
         try {
             return (await this.data('GET', `/rows/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}`)).row;
         }
@@ -1238,6 +1429,15 @@ export function createAppClient(options) {
 export function createClient(options) {
     return new AwesomateClient(options);
 }
+function staffBooking(b) {
+    return {
+        bookingId: b.booking_id, status: b.status, service: b.service,
+        serviceName: b.service_name ?? null, calendar: b.calendar, calendarName: b.calendar_name ?? null,
+        startsAt: b.starts_at, endsAt: b.ends_at, seats: b.seats, source: b.source ?? null,
+        answers: b.answers ?? null, contactId: b.contact_id,
+        customer: b.customer ?? null, createdAt: b.created_at, cancelledAt: b.cancelled_at ?? null,
+    };
+}
 /** The token in a booking's manage link (`/booking?t=...`), or null. */
 export function manageTokenFrom(url) {
     try {
@@ -1312,8 +1512,13 @@ export class AwesomateBookingsClient {
     }
     /**
      * Book a time for a visitor. They get an email with an invite and a link to change or cancel;
-     * the business gets a notice. A time taken since you listed it is refused with code `conflict`
-     * and `field` saying why (not_open, slot_taken, session_full, day_full): list the times again.
+     * the business gets a notice. A refusal has code `conflict` and `field` saying why:
+     * - `not_open`, `slot_taken`, `too_many_seats`, `session_full`, `day_full`: the time is not
+     *   free (taken since you listed it, or not enough places left): list the times again;
+     * - `too_many_open`: this email already has three bookings coming up;
+     * - `monthly_limit`: the business has taken its plan's online bookings for the month.
+     *
+     * Show `personMessage` to the visitor for the last two.
      */
     async book(request) {
         const r = await this.request('POST', '/book', {
@@ -1322,17 +1527,18 @@ export class AwesomateBookingsClient {
         });
         return { bookingId: r.booking_id, created: r.created, startsAt: r.starts_at, endsAt: r.ends_at, manageUrl: r.manage_url };
     }
-    /** One booking, from the token in its manage link (manageTokenFrom()). */
+    /** One booking, from the token in its manage link (manageTokenFrom()), with how the business looks so the page can match it. */
     async booking(manageToken) {
         const r = await this.request('GET', `/manage?t=${encodeURIComponent(manageToken)}`, undefined, false);
         const b = r.booking;
         return {
             business: r.business,
+            look: { website: r.look?.website ?? null, logo: r.look?.logo ?? null, colour: r.look?.colour ?? null },
             booking: {
                 bookingId: b.booking_id, status: b.status, service: b.service ?? null,
                 with: b.with ?? null, startsAt: b.starts_at, endsAt: b.ends_at, timezone: b.timezone,
                 location: b.location ?? '', seats: b.seats, canCancel: !!b.can_cancel, canMove: !!b.can_move,
-                changesCloseAt: b.changes_close_at,
+                changesCloseAt: b.changes_close_at, priceText: b.price_text ?? '',
             },
         };
     }
@@ -1347,11 +1553,18 @@ export class AwesomateBookingsClient {
             q.set('to', to);
         return (await this.request('GET', `/manage/open-times?${q}`, undefined, false)).times;
     }
-    /** Cancel a booking from its manage link. A second cancel answers cancelled: false. */
+    /**
+     * Cancel a booking from its manage link. A second cancel answers cancelled: false. Once changes
+     * have closed (`canCancel` false) it is refused with code `conflict`, field `too_late`.
+     */
     cancel(manageToken, reason) {
         return this.request('POST', '/manage/cancel', { t: manageToken, reason }, false);
     }
-    /** Move a booking to a time from openTimesToMove(). */
+    /**
+     * Move a booking to a time from openTimesToMove(). Refused with code `conflict` and field
+     * `too_late` once changes have closed, or `not_open` (or another of book()'s reasons) when the
+     * time is no longer free.
+     */
     async move(manageToken, startsAt) {
         const r = await this.request('POST', '/manage/move', { t: manageToken, starts_at: startsAt }, false);
         return { startsAt: r.starts_at, endsAt: r.ends_at };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",