@aglyn/plugins-bookings

The Bookings plugin for Aglyn: bookable services, open time slots, and free or paid appointments taken on a published site and managed in the console. Install it if you are running or building on the Aglyn platform and want its booking feature.

Published to npm from the Aglyn monorepo. Versions follow semantic versioning.

Install

npm install @aglyn/plugins-bookings

Peer dependencies:

• @mui/material
• firebase
• firebase-admin
• next
• react

None is optional. firebase-admin and next are used by the server half (@aglyn/plugins-bookings/server).

What's in it

This package is a first-party Aglyn plugin. It is loaded through Aglyn's plugin manager: the apps read its entry in the monorepo's plugins.config.json, import the module each surface names, and call the registrar declared for that surface. It is not a standalone library; installing it on its own loads nothing.

On a published site

• One canvas component, booking: a service and time picker that books an appointment. It is placed in Besigner like any other element and registered by registerBookingsPlugin().

In the console

registerBookingsConsole() registers:

• A Bookings nav item and page at /bookings, behind the bookings feature flag. The page is code-split and loads when opened.
• A "Book a meeting" widget in the crmRecordBooking slot. The CRM plugin hosts that zone on a record; this plugin draws the control in it, so neither package imports the other.
• A plugin config schema (BOOKINGS_CONFIG_SCHEMA) with two settings: maxDaysAhead (the booking horizon in days) and bookingPath (the page on the site that holds the Booking block, used to build booking links).
• A record count source for booking (plugin-record-counts): how many bookings a site took, which a campaign's conversion report divides by.

On the server

@aglyn/plugins-bookings/server imports firebase-admin and is kept out of the client entry point.

• registerBookingsApi() (the tenantApi surface) registers the site-facing routes bookings/slots (open slots for a service, a page of BOOKING_SLOT_PAGE_DAYS whole days at a time; from asks for the page its nextFromMs named) and bookings/book (take a booking; a paid service goes through Stripe Checkout).
• registerBookingsConsoleApi() (the consoleApi surface) registers bookings/reminders, bookings/refund, bookings/check-in, bookings/reschedule, bookings/cancel (a booking with no money on it, raising booking.canceled), bookings/in-person-payment (a booking paid at the counter on the native Aglyn POS app's card reader) and bookings/booking-analytics, a handler on the platform billing webhook that confirms paid bookings, and a bookings-by-service figure reader.
• registerBookingsConsoleServerDeclarations() (the consoleServerDeclarations surface) serves a site's bookings read-only on the customer REST API at /v1/sites/{siteId}/bookings (bookings:read, and the bookings plan feature), and declares the booking events.
• The booking events go through core's domain-event outbox, each carrying { booking } in the API's shape: booking.created when a booking is confirmed (a free one as it is made, a paid one when its payment lands), booking.rescheduled once per move, and booking.canceled when the cancel route or a full refund ends it. Another plugin subscribes by name and never imports this one.
• Loading the module registers two scheduled plugin jobs: expire-stale-holds and booking-reminders (a reminder email about a day before a confirmed booking). This is why package.json lists ./src/lib/server.* under sideEffects.

Routes are served by the host app's API dispatcher under /api/, for example /api/bookings/slots.

Entry points

Usage

The registrars are normally called by Aglyn's generated plugin loaders, not by hand. Called directly they look like this:

// Published site (canvas half only)
import { registerBookingsPlugin } from '@aglyn/plugins-bookings/site'
registerBookingsPlugin()

// Console app
import { registerBookingsConsole } from '@aglyn/plugins-bookings'
registerBookingsConsole()

// Server-only API dispatcher
import {
  registerBookingsApi,
  registerBookingsConsoleApi,
} from '@aglyn/plugins-bookings/server'
registerBookingsApi()

How it fits

A plugin may import the tenant runtime, the renderer, the Besigner logic, the core and the shared packages. It never imports another plugin, and the core never imports a plugin. Bookings depends on @aglyn/aglyn (the core and its plugin-manager seams), @aglyn/tenant-runtime, @aglyn/tenant-data-admin, @aglyn/tenant-feature-instance and several @aglyn/shared-* packages. What it shares with other plugins goes through core seams: tax on a paid booking is asked of the core's plugin tax profile, and the CRM control is drawn in a zone the CRM hosts.

License

Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/plugins/bookings