@awesomate/sdk 0.16.0 → 0.18.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.16.0";
+export declare const VERSION = "0.18.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -290,7 +290,7 @@ export declare class AwesomateClient {
         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. */
+        /** Move a file out of public/ into private/. Its public address stops serving it within seconds (a browser that already opened it may keep its own copy for a while). */
         makePrivate: (path: string) => Promise<FileEntry>;
         /** Move to the trash. Not erased, and no longer counted toward the Files space. */
         remove: (path: string) => Promise<{
@@ -1030,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.16.0';
+export const VERSION = '0.18.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
@@ -220,7 +220,7 @@ export class AwesomateClient {
                 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. */
+        /** Move a file out of public/ into private/. Its public address stops serving it within seconds (a browser that already opened it may keep its own copy for a while). */
         makePrivate: async (path) => {
             const [top, ...rest] = path.replace(/^\/+/, '').split('/');
             if (top !== 'public' || !rest.length)
@@ -1110,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.16.0",
+  "version": "0.18.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",