@awesomate/sdk 0.15.0 → 0.17.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.15.0";
+export declare const VERSION = "0.17.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -157,6 +157,38 @@ export interface Page<R> {
     /** When the hub read the rows. */
     asAt: string;
 }
+/** A file or folder in the account's Files (the folders on its automation account: public/, private/, temp/). */
+export interface FileEntry {
+    /** Relative to the files folder, starting with its top folder: public/images/logo.png. */
+    path: string;
+    name: string;
+    type: 'file' | 'dir';
+    /** Bytes; 0 for a folder. */
+    size: number;
+    /** ISO time it last changed. */
+    modified: string;
+    /** For a file in public/: the address anyone with it can open, with no login. Otherwise null. */
+    public_url: string | null;
+}
+/** How much of the plan's Files space is used. */
+export interface FilesUsage {
+    used_bytes: number;
+    limit_bytes: number;
+    files: number;
+    /** The measure stopped early on a very large tree: used_bytes is at least this much. */
+    partial: boolean;
+    measured_at: string;
+}
+/** A file uploaded from an app. Keep `handle` in a record (a kind's file attribute); it opens the file again. */
+export interface AppFile {
+    handle: string;
+    name: string;
+    size: number;
+    /** Only when the app's uploads are public. */
+    public_url: string | null;
+}
+/** What a file can be sent as. */
+export type FileBody = Blob | ArrayBuffer | Uint8Array | string;
 declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "not_found", "validation", "consent_blocked", "rate_limited", "conflict", "unavailable"];
 /**
  * Why a call failed, one of a fixed list: unauthenticated, forbidden, not_found, validation,
@@ -215,6 +247,56 @@ export declare class AwesomateClient {
     private readonly appKey;
     constructor(opts: ClientOptions);
     private request;
+    /** A call whose body or answer is a file, not JSON. Answers the Response when it succeeded. */
+    private raw;
+    private filesCall;
+    /**
+     * The account's Files: the folders on its automation account that its n8n workflows read and
+     * write (public/, private/, temp/). A file in public/ has a public_url anyone with it can open;
+     * the others never do. Needs the account's token with files:read (reading) or files:write
+     * (changing), on a plan with Files, after the owner has switched on "Open your automation
+     * account's file folders" in Settings, Privacy.
+     *
+     * @example
+     * const logo = await db.files.upload('public/brand/logo.png', await readFile('logo.png'));
+     * console.log(logo.public_url);
+     */
+    readonly files: {
+        /** One folder; '' (the default) lists the top folders. */
+        list: (path?: string) => Promise<FileEntry[]>;
+        /** Files by part of their name (* and ? are wildcards), across the folders or in one. At most 200: `truncated` says there were more. */
+        search: (options?: {
+            q?: string;
+            top?: "public" | "private" | "temp";
+            extensions?: string[];
+        }) => Promise<{
+            results: FileEntry[];
+            truncated: boolean;
+        }>;
+        /** Space used against the plan's Files space. Measured, and up to ten minutes old. */
+        usage: () => Promise<FilesUsage>;
+        /**
+         * Write a file (up to 50 MB). Refuses to replace one already there unless `overwrite`. A full
+         * Files space answers serverCode files_storage_full.
+         */
+        upload: (path: string, data: FileBody, options?: {
+            overwrite?: boolean;
+        }) => Promise<FileEntry>;
+        /** A file's contents. */
+        download: (path: string) => Promise<Blob>;
+        /** Make a folder, and any above it. */
+        mkdir: (path: string) => Promise<FileEntry>;
+        /** Move or rename. Anything using the old path or address needs the new one. */
+        move: (from: string, to: string) => Promise<FileEntry>;
+        /** Move a file from private/ or temp/ to the same place under public/, and answer its public_url. Anyone with the address can open it. */
+        makePublic: (path: string) => Promise<FileEntry>;
+        /** Move a file out of public/ into private/. Its public address stops serving it, though Cloudflare can keep showing the last copy for up to 4 hours. */
+        makePrivate: (path: string) => Promise<FileEntry>;
+        /** Move to the trash. Not erased, and no longer counted toward the Files space. */
+        remove: (path: string) => Promise<{
+            trashPath: string;
+        }>;
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema(): Promise<{
         kinds: Array<{
@@ -871,6 +953,34 @@ export declare class AwesomateAppClient {
         ids?: string[];
         limit?: number;
     }): Promise<Customer[]>;
+    /** Runs a call with the current access token, refreshing it once when the hub says it expired. */
+    private authed;
+    private rawData;
+    /**
+     * Files people attach in this app, such as a photo of a job or a signed form, kept in the
+     * account's Files. Off until the account switches it on for the app (private, or public with a
+     * public address per file): check mode() before showing an upload button. Keep the handle an
+     * upload answers in a record's file attribute; anyone signed in to this app who can read that
+     * record can open the file with download().
+     *
+     * @example
+     * const file = await app.files.upload(input.files[0]);
+     * await app.write('message', { body: 'Photo of the leak', attachment: file.handle }, { links: { job: jobId } });
+     */
+    readonly files: {
+        /** Whether this app takes uploads: 'off', 'private' or 'public'. */
+        mode: () => Promise<"off" | "private" | "public">;
+        /**
+         * Upload one file, up to 10 MB. The name comes from a File, or pass one. A refusal's
+         * serverCode says why: uploads_off, too_large, type_not_allowed (public uploads take no web
+         * pages or scripts), files_storage_full; personMessage is the sentence to show.
+         */
+        upload: (file: Blob, options?: {
+            name?: string;
+        }) => Promise<AppFile>;
+        /** The file a handle names, for someone signed in to this app. */
+        download: (handle: string) => Promise<Blob>;
+    };
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.
@@ -920,4 +1030,168 @@ export declare function createAppClient(options: AppClientOptions): AwesomateApp
  * const { rows } = await db.query('contact', { limit: 10 });
  */
 export declare function createClient(options: ClientOptions): AwesomateClient;
+/** One question a service asks when someone books. */
+export interface BookingQuestion {
+    key: string;
+    label: string;
+    type: 'text' | 'textarea' | 'select' | 'multiselect' | 'url';
+    required?: boolean;
+    /** The choices, for select and multiselect. */
+    options?: string[];
+}
+/** Something the business offers to book, with the calendars (people, rooms) it is booked with. */
+export interface BookableService {
+    key: string;
+    name: string;
+    description: string;
+    /** How long it lasts. */
+    minutes: number;
+    /** 1 for one person at a time; more for a class several people join at one start. */
+    capacity: number;
+    /** The price as the business wrote it. Shown, never charged. */
+    price_text: string;
+    location: string;
+    intake: BookingQuestion[];
+    calendars: Array<{
+        key: string;
+        name: string;
+        timezone: string;
+    }>;
+}
+/** A time that can be booked. */
+export interface OpenTime {
+    start: string;
+    end: string;
+    /** The calendar it is with. */
+    calendar: string;
+    calendarName: string;
+    /** Places left: 1 for a one-person service, more while a class has room. */
+    seatsLeft: number;
+    /** True when this start joins a class someone has already booked. */
+    joins: boolean;
+}
+/** What book() needs. Take `startsAt` and `calendar` from an OpenTime. */
+export interface BookingRequest {
+    service: string;
+    calendar: string;
+    startsAt: string;
+    name: string;
+    email: 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 attempt, so a retry after a dropped connection returns the same booking instead of
+     * making a second. Make a new one for each new booking.
+     */
+    idempotencyKey?: string;
+}
+/** A booking just made. */
+export interface BookingResult {
+    bookingId: string;
+    /** False when idempotencyKey matched a booking already made. */
+    created: boolean;
+    startsAt: string;
+    endsAt: string;
+    /** The customer's own page to change or cancel, the same link their email carries. */
+    manageUrl: string;
+}
+/** One booking, as its customer's link shows it. Names no person. */
+export interface ManagedBooking {
+    bookingId: string;
+    status: 'confirmed' | 'cancelled' | 'completed' | 'no_show';
+    service: string | null;
+    /** The calendar's name: who or what it is with. */
+    with: string | null;
+    startsAt: string;
+    endsAt: string;
+    /** The calendar's IANA zone, for showing the times. */
+    timezone: string;
+    location: string;
+    seats: number;
+    /** Whether it can still be cancelled or moved online (the service's cutoff has not passed). */
+    canCancel: boolean;
+    canMove: boolean;
+    changesCloseAt: string;
+}
+/** Options for createBookingsClient(). */
+export interface BookingsClientOptions {
+    /** The booking key (bk_...) from Contacts, Bookings, On your website. Public: it works only on the sites it lists. */
+    key: string;
+    /** Default https://hub.awesomate.ai. */
+    baseUrl?: string;
+    /** Your own fetch. Default: the global one. */
+    fetch?: typeof fetch;
+}
+/** The token in a booking's manage link (`/booking?t=...`), or null. */
+export declare function manageTokenFrom(url: string): string | null;
+/**
+ * The bookings client, from createBookingsClient(): a business's own booking page, for visitors
+ * who are not signed in. Lists what can be booked and when, books, and lets a customer see,
+ * cancel or move their booking from the link in its emails. Safe in a browser: the booking key is
+ * public and locked to the business's own sites.
+ */
+export declare class AwesomateBookingsClient {
+    private readonly opts;
+    private readonly base;
+    private readonly doFetch;
+    constructor(opts: BookingsClientOptions);
+    private request;
+    /** The business's name and what it offers to book. */
+    services(): Promise<{
+        business: string;
+        services: BookableService[];
+    }>;
+    /**
+     * The times a service can be booked, soonest first, from now for two weeks unless told
+     * otherwise (at most 62 days at once). Times are UTC; show them in the calendar's own zone.
+     */
+    openTimes(service: string, options?: {
+        from?: Date | string;
+        to?: Date | string;
+        calendar?: string;
+        seats?: number;
+    }): 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.
+     */
+    book(request: BookingRequest): Promise<BookingResult>;
+    /** One booking, from the token in its manage link (manageTokenFrom()). */
+    booking(manageToken: string): Promise<{
+        business: string;
+        booking: ManagedBooking;
+    }>;
+    /** The times a booking could move to, leaving its own time out. */
+    openTimesToMove(manageToken: string, options?: {
+        from?: Date | string;
+        to?: Date | string;
+    }): Promise<OpenTime[]>;
+    /** Cancel a booking from its manage link. A second cancel answers cancelled: false. */
+    cancel(manageToken: string, reason?: string): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Move a booking to a time from openTimesToMove(). */
+    move(manageToken: string, startsAt: string): Promise<{
+        startsAt: string;
+        endsAt: string;
+    }>;
+}
+/**
+ * The client for a business's own booking page. Use the booking key from Contacts, Bookings, On
+ * your website; it works on every plan, from the sites the key lists.
+ *
+ * @example
+ * ```ts
+ * import { createBookingsClient } from '@awesomate/sdk';
+ *
+ * const bookings = createBookingsClient({ key: 'bk_your_booking_key' });
+ * const { services } = await bookings.services();
+ * const times = await bookings.openTimes(services[0].key);
+ * ```
+ */
+export declare function createBookingsClient(options: BookingsClientOptions): AwesomateBookingsClient;
 export {};

package/dist/index.js

@@ -24,7 +24,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.15.0';
+export const VERSION = '0.17.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
@@ -57,13 +57,17 @@ export class AwesomateError extends Error {
         this.name = 'AwesomateError';
     }
 }
+const CONSENT_CODES = new Set(['consent_blocked', 'consent_denied', 'files_consent_off']);
 function errorCode(status, server) {
     if (server === 'validation' || server === 'invalid' || status === 422)
         return 'validation';
+    // A file the hub will not take as sent: too big, no length, or a type it refuses.
+    if (status === 411 || status === 413 || status === 415)
+        return 'validation';
     if (status === 401)
         return 'unauthenticated';
     if (status === 403)
-        return server === 'consent_blocked' ? 'consent_blocked' : 'forbidden';
+        return server && CONSENT_CODES.has(server) ? 'consent_blocked' : 'forbidden';
     if (status === 429)
         return 'rate_limited';
     if (server === 'conflict')
@@ -133,6 +137,99 @@ export class AwesomateClient {
         const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
         throw new AwesomateError(code, message, res.status, typeof json.field === 'string' ? json.field : undefined, server);
     }
+    /** A call whose body or answer is a file, not JSON. Answers the Response when it succeeded. */
+    async raw(method, path, body) {
+        if (this.appKey) {
+            throw new AwesomateError('forbidden', 'Files needs the account\'s token (amt_pat_... with files:read or files:write), not an app key.', 0);
+        }
+        const res = await this.doFetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.opts.token}`,
+                'user-agent': `@awesomate/sdk/${VERSION}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/octet-stream' }),
+            },
+            body: body,
+        });
+        if (res.ok)
+            return res;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's HTML error page */ }
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, undefined, server);
+    }
+    filesCall(method, path, body) {
+        if (this.appKey) {
+            return Promise.reject(new AwesomateError('forbidden', 'Files needs the account\'s token (amt_pat_... with files:read or files:write), not an app key.', 0));
+        }
+        return this.request(method, path, body, false);
+    }
+    /**
+     * The account's Files: the folders on its automation account that its n8n workflows read and
+     * write (public/, private/, temp/). A file in public/ has a public_url anyone with it can open;
+     * the others never do. Needs the account's token with files:read (reading) or files:write
+     * (changing), on a plan with Files, after the owner has switched on "Open your automation
+     * account's file folders" in Settings, Privacy.
+     *
+     * @example
+     * const logo = await db.files.upload('public/brand/logo.png', await readFile('logo.png'));
+     * console.log(logo.public_url);
+     */
+    files = {
+        /** One folder; '' (the default) lists the top folders. */
+        list: async (path = '') => (await this.filesCall('GET', `/api/files?path=${encodeURIComponent(path)}`)).entries,
+        /** Files by part of their name (* and ? are wildcards), across the folders or in one. At most 200: `truncated` says there were more. */
+        search: async (options = {}) => {
+            const qs = new URLSearchParams({ q: options.q ?? '' });
+            if (options.top)
+                qs.set('top', options.top);
+            if (options.extensions?.length)
+                qs.set('exts', options.extensions.join(','));
+            const r = await this.filesCall('GET', `/api/files/search?${qs}`);
+            return { results: r.results, truncated: r.truncated };
+        },
+        /** Space used against the plan's Files space. Measured, and up to ten minutes old. */
+        usage: () => this.filesCall('GET', '/api/files/usage'),
+        /**
+         * Write a file (up to 50 MB). Refuses to replace one already there unless `overwrite`. A full
+         * Files space answers serverCode files_storage_full.
+         */
+        upload: async (path, data, options = {}) => {
+            const qs = new URLSearchParams({ path });
+            if (options.overwrite)
+                qs.set('overwrite', '1');
+            return (await (await this.raw('POST', `/api/files?${qs}`, data)).json()).entry;
+        },
+        /** A file's contents. */
+        download: async (path) => (await this.raw('GET', `/api/files/stream?${new URLSearchParams({ path, disposition: 'attachment' })}`)).blob(),
+        /** Make a folder, and any above it. */
+        mkdir: async (path) => (await this.filesCall('POST', '/api/files/mkdir', { path })).entry,
+        /** Move or rename. Anything using the old path or address needs the new one. */
+        move: async (from, to) => (await this.filesCall('POST', '/api/files/move', { from, to })).entry,
+        /** Move a file from private/ or temp/ to the same place under public/, and answer its public_url. Anyone with the address can open it. */
+        makePublic: async (path) => {
+            const [top, ...rest] = path.replace(/^\/+/, '').split('/');
+            if (top === 'public')
+                throw new AwesomateError('validation', `${path} is already public.`, 0, 'path');
+            if (!rest.length)
+                throw new AwesomateError('validation', 'Name a file inside the folder.', 0, 'path');
+            return this.files.move(path, `public/${rest.join('/')}`);
+        },
+        /** Move a file out of public/ into private/. Its public address stops serving it, though Cloudflare can keep showing the last copy for up to 4 hours. */
+        makePrivate: async (path) => {
+            const [top, ...rest] = path.replace(/^\/+/, '').split('/');
+            if (top !== 'public' || !rest.length)
+                throw new AwesomateError('validation', `${path} is not a file in public/.`, 0, 'path');
+            return this.files.move(path, `private/${rest.join('/')}`);
+        },
+        /** 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)}`),
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema() {
         return this.request('GET', '/api/my-crm/v1/rows/schema');
@@ -597,6 +694,71 @@ export class AwesomateAppClient {
     async lookupCustomers(options) {
         return (await this.data('POST', '/customers/lookup', options)).customers;
     }
+    /** Runs a call with the current access token, refreshing it once when the hub says it expired. */
+    async authed(fn) {
+        let s = await this.current();
+        if (!s)
+            throw new AwesomateError('unauthenticated', 'Sign in first.', 401);
+        try {
+            return await fn(s.access_token);
+        }
+        catch (err) {
+            if (!(err instanceof AwesomateError) || err.code !== 'unauthenticated')
+                throw err;
+            s = await this.refresh(s);
+            if (!s)
+                throw err;
+            return fn(s.access_token);
+        }
+    }
+    async rawData(method, path, token, body) {
+        const res = await this.doFetch(`${this.base}/api/sdk/v1${path}`, {
+            method,
+            headers: {
+                'x-awesomate-key': this.opts.publishableKey,
+                authorization: `Bearer ${token}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/octet-stream' }),
+            },
+            body: body,
+        });
+        if (res.ok)
+            return res;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's error page */ }
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, undefined, server, message);
+    }
+    /**
+     * Files people attach in this app, such as a photo of a job or a signed form, kept in the
+     * account's Files. Off until the account switches it on for the app (private, or public with a
+     * public address per file): check mode() before showing an upload button. Keep the handle an
+     * upload answers in a record's file attribute; anyone signed in to this app who can read that
+     * record can open the file with download().
+     *
+     * @example
+     * const file = await app.files.upload(input.files[0]);
+     * await app.write('message', { body: 'Photo of the leak', attachment: file.handle }, { links: { job: jobId } });
+     */
+    files = {
+        /** Whether this app takes uploads: 'off', 'private' or 'public'. */
+        mode: async () => (await this.data('GET', '/me')).app.file_uploads ?? 'off',
+        /**
+         * Upload one file, up to 10 MB. The name comes from a File, or pass one. A refusal's
+         * serverCode says why: uploads_off, too_large, type_not_allowed (public uploads take no web
+         * pages or scripts), files_storage_full; personMessage is the sentence to show.
+         */
+        upload: async (file, options = {}) => {
+            const name = options.name ?? file.name ?? 'file';
+            return this.authed(async (token) => (await (await this.rawData('POST', `/files?name=${encodeURIComponent(name)}`, token, file)).json()).file);
+        },
+        /** The file a handle names, for someone signed in to this app. */
+        download: async (handle) => this.authed(async (token) => (await this.rawData('GET', `/files/${encodeURIComponent(handle)}`, token)).blob()),
+    };
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.
@@ -948,3 +1110,138 @@ export function createAppClient(options) {
 export function createClient(options) {
     return new AwesomateClient(options);
 }
+/** The token in a booking's manage link (`/booking?t=...`), or null. */
+export function manageTokenFrom(url) {
+    try {
+        return new URL(url).searchParams.get('t');
+    }
+    catch {
+        return null;
+    }
+}
+const iso = (d) => (d === undefined ? undefined : typeof d === 'string' ? d : d.toISOString());
+/**
+ * The bookings client, from createBookingsClient(): a business's own booking page, for visitors
+ * who are not signed in. Lists what can be booked and when, books, and lets a customer see,
+ * cancel or move their booking from the link in its emails. Safe in a browser: the booking key is
+ * public and locked to the business's own sites.
+ */
+export class AwesomateBookingsClient {
+    opts;
+    base;
+    doFetch;
+    constructor(opts) {
+        this.opts = opts;
+        if (!opts?.key?.startsWith('bk_'))
+            throw new Error('createBookingsClient needs the booking key (bk_...) from Contacts, Bookings, On your website.');
+        this.base = `${(opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '')}/api/sdk/v1/bookings`;
+        const f = opts.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (!f)
+            throw new Error('No fetch available.');
+        this.doFetch = f;
+    }
+    async request(method, path, body, withKey = true) {
+        let res;
+        try {
+            res = await this.doFetch(`${this.base}${path}`, {
+                method,
+                headers: { 'content-type': 'application/json', ...(withKey ? { 'x-awesomate-key': this.opts.key } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new AwesomateError('unavailable', `The hub could not be reached: ${err.message}`, 0);
+        }
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const server = typeof data.code === 'string' ? data.code : undefined;
+            const message = typeof data.error === 'string' ? data.error : `Request failed (${res.status})`;
+            throw new AwesomateError(errorCode(res.status, server), message, res.status, typeof data.field === 'string' ? data.field : undefined, server, message);
+        }
+        return data;
+    }
+    /** The business's name and what it offers to book. */
+    services() {
+        return this.request('GET', '/services');
+    }
+    /**
+     * The times a service can be booked, soonest first, from now for two weeks unless told
+     * otherwise (at most 62 days at once). Times are UTC; show them in the calendar's own zone.
+     */
+    async openTimes(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', `/open-times?${q}`)).times;
+    }
+    /**
+     * 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.
+     */
+    async book(request) {
+        const r = await this.request('POST', '/book', {
+            service: request.service, calendar: request.calendar, starts_at: request.startsAt, name: request.name, email: request.email,
+            phone: request.phone, seats: request.seats, answers: request.answers, idempotency_key: request.idempotencyKey,
+        });
+        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()). */
+    async booking(manageToken) {
+        const r = await this.request('GET', `/manage?t=${encodeURIComponent(manageToken)}`, undefined, false);
+        const b = r.booking;
+        return {
+            business: r.business,
+            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,
+            },
+        };
+    }
+    /** The times a booking could move to, leaving its own time out. */
+    async openTimesToMove(manageToken, options = {}) {
+        const q = new URLSearchParams({ t: manageToken });
+        const from = iso(options.from);
+        const to = iso(options.to);
+        if (from)
+            q.set('from', from);
+        if (to)
+            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(manageToken, reason) {
+        return this.request('POST', '/manage/cancel', { t: manageToken, reason }, false);
+    }
+    /** Move a booking to a time from openTimesToMove(). */
+    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 };
+    }
+}
+/**
+ * The client for a business's own booking page. Use the booking key from Contacts, Bookings, On
+ * your website; it works on every plan, from the sites the key lists.
+ *
+ * @example
+ * ```ts
+ * import { createBookingsClient } from '@awesomate/sdk';
+ *
+ * const bookings = createBookingsClient({ key: 'bk_your_booking_key' });
+ * const { services } = await bookings.services();
+ * const times = await bookings.openTimes(services[0].key);
+ * ```
+ */
+export function createBookingsClient(options) {
+    return new AwesomateBookingsClient(options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.15.0",
+  "version": "0.17.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",