@awesomate/sdk 0.23.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.23.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>;
@@ -516,12 +702,39 @@ export declare class AwesomateClient {
      */
     business(): Promise<BusinessIdentity>;
     /**
-     * The business map: the seven divisions every business has, the jobs in each and who holds them,
-     * which agents and automations help which job and how far each may go, and what is missing, most
-     * important first. Read only: the owner changes the map in the hub. Needs the account's token
-     * (hosting:read, every plan), never an app key, and the account must have the business map.
+     * The business map: the seven departments every business has, their sub-departments, the roles in
+     * each and who holds them, which agents and automations help which role and how far each may go,
+     * and what is missing, most important first. Read only: the owner changes the map in the hub.
+     * Needs the account's token (hosting:read, every plan), never an app key, and the account must
+     * have the business map. Since 0.24.0 in the words the owner sees; businessMapV1() is the old shape.
      */
     businessMap(): Promise<BusinessMap>;
+    /** Every role on the map, one line each: slug, title, department and who holds it. */
+    businessMapRoles(): Promise<BusinessMapRoleSummary[]>;
+    /**
+     * One role by its slug, with the line each helper's instructions carry (`helpers[].instructionLine`):
+     * which role it helps, for whom, how far it may go and where its procedures are.
+     */
+    businessMapRole(slug: string): Promise<BusinessMapRoleDetail>;
+    /**
+     * The business map in its first shape, where a department is a `division`, a sub-department a
+     * `department` and a role a `job`.
+     * @deprecated Use businessMap(), which uses the words the owner sees. v1 is removed once it has
+     * 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. */
@@ -592,20 +805,20 @@ export interface BusinessMapHelper {
     ref: string;
     label: string;
 }
-/** A job on the map. `slug` is its stable name for routing work: "whoever holds quotes". */
-export interface BusinessMapJob {
+/** A role on the map. `slug` is its stable name for routing work: "whoever holds quotes". */
+export interface BusinessMapRole {
     id: number;
     slug: string;
     title: string;
     mission: string | null;
     /** active: someone holds it. open: nobody does. hire_next: the owner's next hire. */
     state: 'active' | 'open' | 'hire_next';
-    isOwnerJob: boolean;
-    /** Runs its division: the division manager, above its departments, so departmentNo is null (the owner's job excepted). */
-    headsDivision: boolean;
-    /** Runs its department: the person responsible for it, and for its department-level KPIs. */
+    isOwnerRole: boolean;
+    /** Runs its department: above its sub-departments, so subDepartmentNo is null (the owner's role excepted). */
     headsDepartment: boolean;
-    departmentNo: number | null;
+    /** Runs its sub-department: the person responsible for it, and for its KPIs. */
+    headsSubDepartment: boolean;
+    subDepartmentNo: number | null;
     reportsTo: {
         id: number;
         title: string;
@@ -628,12 +841,12 @@ export interface BusinessMapJob {
         exceptions: string | null;
         minutesSavedPerRun: number | null;
     }>;
-    /** The tag this job's procedures carry in 1Brain, such as 'job:quotes'. The map keeps no procedure text. */
+    /** The tag this role's procedures carry in 1Brain, such as 'job:quotes'. The map keeps no procedure text. */
     proceduresTag: string;
-    /** Quarterly priorities on this hat, every quarter. */
+    /** Quarterly priorities on this role, every quarter. */
     priorities: BusinessMapPriority[];
 }
-/** A quarterly priority on a hat: one of the few things it must move this quarter. */
+/** A quarterly priority on a role: one of the few things it must move this quarter. */
 export interface BusinessMapPriority {
     id: number;
     /** '2026-Q4'. */
@@ -649,15 +862,15 @@ export interface BusinessMapPriority {
 export interface BusinessMapPathStep {
     position: number;
     label: string;
-    divisionNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    departmentNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
     verb: string;
-    /** The job that looks after the step, when the owner named one. */
-    job: {
+    /** The role that looks after the step, when the owner named one. */
+    role: {
         id: number;
         slug: string;
         title: string;
     } | null;
-    /** Who looks after it: the job's holder, else whoever runs the division (byDefault). */
+    /** Who looks after it: the role's holder, else whoever runs the department (byDefault). */
     owner: {
         name: string;
         byDefault: boolean;
@@ -665,8 +878,23 @@ export interface BusinessMapPathStep {
     /** Where this step hands over to the next, in the owner's words. */
     handoffRule: string | null;
 }
-/** One of the seven divisions, in board order (7 first). */
-export interface BusinessMapDivision {
+/** A sub-department and who runs it: the holder of the role that heads it, else whoever runs the department (byDefault). */
+export interface BusinessMapSubDepartment {
+    no: number;
+    name: string;
+    gloss: string;
+    runBy: {
+        name: string;
+        byDefault: boolean;
+    };
+    headRole: {
+        id: number;
+        slug: string;
+        title: string;
+    } | null;
+}
+/** One of the seven departments, in board order (7 first). */
+export interface BusinessMapDepartment {
     no: 1 | 2 | 3 | 4 | 5 | 6 | 7;
     /** Envision, Form, Promise, Balance, Fulfil, Refine, Share. */
     verb: string;
@@ -678,12 +906,230 @@ export interface BusinessMapDivision {
         name: string;
         byDefault: boolean;
     };
+    roles: BusinessMapRole[];
+    /** Helping here but not yet put on a role, with how they were placed, in words. */
+    helpers: Array<BusinessMapHelper & {
+        placedBy: string;
+    }>;
+    subDepartments: BusinessMapSubDepartment[];
+    ideas: Array<{
+        label: string;
+        what: string;
+        status: 'live' | 'library' | 'coming' | 'building' | 'planned';
+        path?: string;
+    }>;
+    numbers: Array<{
+        label: string;
+        kind: 'lead' | 'result';
+    }>;
+    question: string;
+    /** 1Brain Departments whose procedures belong in this department. */
+    oneBrainDepartments: string[];
+    /** People on the map who hold no role yet. They sit in Form (department 1) for display; empty for every other department. */
+    noRoleYet: Array<{
+        id: number;
+        name: string;
+    }>;
+}
+/** The business map, as businessMap() returns it. No email addresses. */
+export interface BusinessMap {
+    version: 2;
+    business: {
+        name: string | null;
+        ownerName: string;
+    };
+    /** false: the owner has not started the map, so it is worked out from what the account runs. */
+    stored: boolean;
+    /** access: what the person may do in the hub (owner, full or view). */
+    people: Array<{
+        id: number | null;
+        name: string;
+        kind: 'owner' | 'staff' | 'contractor' | 'adviser' | null;
+        access: 'owner' | 'full' | 'view' | null;
+        location: string | null;
+        fromTeamAccess: boolean;
+    }>;
+    departments: BusinessMapDepartment[];
+    /** Helpers we could not place on a department. */
+    unplaced: Array<BusinessMapHelper & {
+        placedBy: string;
+    }>;
+    /** How a customer moves through the business. stored false: suggested for its kind of business, not set by the owner yet. */
+    path: {
+        stored: boolean;
+        template: {
+            key: string;
+            label: string;
+        } | null;
+        steps: BusinessMapPathStep[];
+    };
+    /** This quarter, '2026-Q4' (UTC): the one the map shows priorities for. */
+    quarter: string;
+    /** What is missing, most important first. */
+    gaps: Array<{
+        kind: 'procedure_first' | 'no_helper' | 'role_open' | 'path_missing' | 'path_unowned' | 'owner_everywhere' | 'unplaced';
+        department: number | null;
+        title: string;
+        detail: string;
+        action: {
+            label: string;
+            path: string;
+        } | null;
+    }>;
+    /** oneBrainCategory: the 1Brain category this business is, once linked. */
+    settings: {
+        adviser: string | null;
+        runsWeek: string | null;
+        oneBrainCategory: string | null;
+    };
+    counts: {
+        people: number;
+        helpers: number;
+        placed: number;
+        departmentsWithHelpers: number;
+        roles: number;
+    };
+    /** Sources that could not be read just now: a missing helper may simply not have been read. */
+    unavailable: string[];
+}
+/** One role in businessMapRoles(). */
+export interface BusinessMapRoleSummary {
+    slug: string;
+    title: string;
+    state: BusinessMapRole['state'];
+    department: {
+        no: number;
+        verb: string;
+        name: string;
+    };
+    /** The accountable holder, else the first; null when nobody holds it. */
+    holder: string | null;
+}
+/** One role, as businessMapRole() returns it. */
+export interface BusinessMapRoleDetail {
+    slug: string;
+    title: string;
+    mission: string | null;
+    state: BusinessMapRole['state'];
+    department: {
+        no: number;
+        verb: string;
+        name: string;
+    };
+    headsDepartment: boolean;
+    headsSubDepartment: boolean;
+    reportsTo: {
+        title: string;
+        slug: string | null;
+    } | null;
+    holder: string | null;
+    procedures: {
+        where: '1Brain';
+        tag: string;
+    };
+    /** This quarter's and next quarter's. */
+    priorities: Array<{
+        quarter: string;
+        title: string;
+        status: BusinessMapPriority['status'];
+        owner: string | null;
+        dueOn: string | null;
+    }>;
+    pathSteps: Array<{
+        position: number;
+        label: string;
+        handoffRule: string | null;
+    }>;
+    holders: Array<{
+        name: string;
+        accountable: boolean;
+        timeSharePct: number | null;
+    }>;
+    responsibilities: Array<{
+        text: string;
+        level: BusinessMapLevel;
+        levelLabel: string;
+        exceptions: string | null;
+    }>;
+    helpers: Array<{
+        kind: BusinessMapHelper['kind'];
+        ref: string;
+        label: string;
+        supervisor: string;
+        level: BusinessMapLevel | null;
+        levelLabel: string | null;
+        exceptions: string | null;
+        instructionLine: string;
+    }>;
+}
+/**
+ * A job on the v1 map (a role).
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapRole.
+ */
+export interface BusinessMapJob {
+    id: number;
+    slug: string;
+    title: string;
+    mission: string | null;
+    state: 'active' | 'open' | 'hire_next';
+    isOwnerJob: boolean;
+    /** Runs its division (a department). */
+    headsDivision: boolean;
+    /** Runs its department (a sub-department). */
+    headsDepartment: boolean;
+    /** The sub-department. */
+    departmentNo: number | null;
+    reportsTo: {
+        id: number;
+        title: string;
+    } | null;
+    holders: BusinessMapRole['holders'];
+    responsibilities: BusinessMapRole['responsibilities'];
+    helpers: BusinessMapRole['helpers'];
+    proceduresTag: string;
+    priorities: BusinessMapPriority[];
+}
+/**
+ * One step of the customer's path on the v1 map.
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapPathStep.
+ */
+export interface BusinessMapPathStepV1 {
+    position: number;
+    label: string;
+    /** The department. */
+    divisionNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    verb: string;
+    /** The role. */
+    job: {
+        id: number;
+        slug: string;
+        title: string;
+    } | null;
+    owner: {
+        name: string;
+        byDefault: boolean;
+    };
+    handoffRule: string | null;
+}
+/**
+ * A division on the v1 map (a department).
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapDepartment.
+ */
+export interface BusinessMapDivision {
+    no: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    verb: string;
+    name: string;
+    purpose: string;
+    stage: 'survive' | 'grow' | 'scale';
+    runBy: {
+        name: string;
+        byDefault: boolean;
+    };
     jobs: BusinessMapJob[];
-    /** Helping here but not yet put on a job, with how they were placed, in words. */
     helpers: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
-    /** Each department and who runs it: the holder of the job that heads it, else whoever runs the division (byDefault). */
+    /** The sub-departments. */
     departments: Array<{
         no: number;
         name: string;
@@ -698,33 +1144,26 @@ export interface BusinessMapDivision {
             title: string;
         } | null;
     }>;
-    ideas: Array<{
-        label: string;
-        what: string;
-        status: 'live' | 'library' | 'coming' | 'building' | 'planned';
-        path?: string;
-    }>;
-    numbers: Array<{
-        label: string;
-        kind: 'lead' | 'result';
-    }>;
+    ideas: BusinessMapDepartment['ideas'];
+    numbers: BusinessMapDepartment['numbers'];
     question: string;
-    /** 1Brain departments whose procedures belong in this division. */
     oneBrainDepartments: string[];
-    /** People on the map who wear no hat yet. They sit in Form (division 1) for display; empty for every other division. */
     noHatYet: Array<{
         id: number;
         name: string;
     }>;
 }
-/** The business map, as businessMap() returns it. No email addresses. */
-export interface BusinessMap {
+/**
+ * The business map in its first shape, as businessMapV1() returns it.
+ * @deprecated Use BusinessMap, from businessMap().
+ */
+export interface BusinessMapV1 {
     business: {
         name: string | null;
         ownerName: string;
     };
-    /** false: the owner has not started the map, so it is worked out from what the account runs. */
     stored: boolean;
+    /** role: the person's access. */
     people: Array<{
         id: number | null;
         name: string;
@@ -734,22 +1173,18 @@ export interface BusinessMap {
         fromTeamAccess: boolean;
     }>;
     divisions: BusinessMapDivision[];
-    /** Helpers we could not place on a division. */
     unplaced: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
-    /** How a customer moves through the business. stored false: suggested for its kind of business, not set by the owner yet. */
     path: {
         stored: boolean;
         template: {
             key: string;
             label: string;
         } | null;
-        steps: BusinessMapPathStep[];
+        steps: BusinessMapPathStepV1[];
     };
-    /** This quarter, '2026-Q4' (UTC): the one the map shows priorities for. */
     quarter: string;
-    /** What is missing, most important first. */
     gaps: Array<{
         kind: 'procedure_first' | 'no_helper' | 'job_open' | 'path_missing' | 'path_unowned' | 'owner_everywhere' | 'unplaced';
         division: number | null;
@@ -763,6 +1198,7 @@ export interface BusinessMap {
     settings: {
         adviser: string | null;
         runsWeek: string | null;
+        oneBrainCategory: string | null;
     };
     counts: {
         people: number;
@@ -771,7 +1207,6 @@ export interface BusinessMap {
         divisionsWithHelpers: number;
         jobs: number;
     };
-    /** Sources that could not be read just now: a missing helper may simply not have been read. */
     unavailable: string[];
 }
 /** A detail waiting for the owner's yes. */
@@ -784,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;
@@ -794,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 {
@@ -809,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(). */
@@ -893,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. */
@@ -1099,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>;
@@ -1237,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;
@@ -1301,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 {
@@ -1342,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. */
@@ -1356,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.23.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}`);
@@ -402,14 +565,58 @@ export class AwesomateClient {
         return this.request('GET', '/api/my-business/v1/identity?format=json');
     }
     /**
-     * The business map: the seven divisions every business has, the jobs in each and who holds them,
-     * which agents and automations help which job and how far each may go, and what is missing, most
-     * important first. Read only: the owner changes the map in the hub. Needs the account's token
-     * (hosting:read, every plan), never an app key, and the account must have the business map.
+     * The business map: the seven departments every business has, their sub-departments, the roles in
+     * each and who holds them, which agents and automations help which role and how far each may go,
+     * and what is missing, most important first. Read only: the owner changes the map in the hub.
+     * Needs the account's token (hosting:read, every plan), never an app key, and the account must
+     * have the business map. Since 0.24.0 in the words the owner sees; businessMapV1() is the old shape.
      */
     async businessMap() {
+        return (await this.request('GET', '/api/my-business/v2/map?format=json')).map;
+    }
+    /** Every role on the map, one line each: slug, title, department and who holds it. */
+    async businessMapRoles() {
+        return (await this.request('GET', '/api/my-business/v2/map/roles')).roles;
+    }
+    /**
+     * One role by its slug, with the line each helper's instructions carry (`helpers[].instructionLine`):
+     * which role it helps, for whom, how far it may go and where its procedures are.
+     */
+    async businessMapRole(slug) {
+        return (await this.request('GET', `/api/my-business/v2/map/roles/${encodeURIComponent(slug)}`)).role;
+    }
+    /**
+     * The business map in its first shape, where a department is a `division`, a sub-department a
+     * `department` and a role a `job`.
+     * @deprecated Use businessMap(), which uses the words the owner sees. v1 is removed once it has
+     * gone 30 days unused, and not before 2026-11-06.
+     */
+    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;
@@ -705,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;
         }
@@ -1217,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 {
@@ -1291,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', {
@@ -1301,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 ?? '',
             },
         };
     }
@@ -1326,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.23.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",