brixon-meeting-booking

Internal-facing Brixon package for web integration scenarios on Next.js.

Installation

npm install brixon-meeting-booking

Exports

import { CalendlyBookingWidget } from "brixon-meeting-booking/client";
import {
  createCalendlyAvailabilityRoute,
  createCalendlyBookingRoute,
  createCalendlyConfigRoute,
  createCalendlyWebhookRoute
} from "brixon-meeting-booking/server";
import "brixon-meeting-booking/styles.css";

Runtime Defaults

• The widget detects de, en, fr, or nl automatically from the first URL segment when no locale prop is provided.
• The event type uses this order:
  1. handoff.eventTypeKey
  2. eventTypeId or eventTypeKey from the current URL query string
  3. CalendlyBookingWidget.eventTypeKey
• Date and time formatting follow that locale.
• The initial time zone uses this order:
  1. explicit user choice in the widget
  2. explicit timezone prop
  3. browser time zone
  4. Europe/Berlin
• The widget includes a built-in time zone picker and reloads availability when the user changes it.
• The availability view stays inside the custom widget when a month has no slots.
• The Calendly iframe fallback is only used for hard loading failures, not for empty months or validation errors.

Booking Field Contract

bookingFields now uses an explicit contract:

• enabled controls whether a field is shown in the widget
• calendly controls whether and how a value is sent to Calendly
• these are separate decisions

type BookingFieldConfig = {
  company?: {
    enabled: boolean;
    calendly?: {
      mode: "customQuestion";
      position: number;
      question?: string;
    };
  };
  phone?: {
    enabled: boolean;
    calendly?: {
      mode: "textReminderNumber";
    };
  };
  customQuestions?: Array<{
    question: string;
    position: number;
    required?: boolean;
  }>;
};

Behavior:

• company.enabled === true only shows the company field
• company.calendly is required if the company value should be sent to Calendly
• phone.enabled === true only shows the phone field
• phone.calendly.mode === "textReminderNumber" is required if the phone value should be sent to Calendly
• customQuestions always use explicit Calendly positions
• the package does not auto-map company or phone
• the package does not invent question positions

Tracking And Metadata Contract

tracking and internal host metadata are separate on purpose:

• tracking is only for Calendly-compatible UTM data
• all five UTM fields must be present before anything is sent to Calendly
• partial, empty, or undefined tracking payloads are dropped
• metadata is for host-internal values such as salesforceUuid
• metadata is preserved for host integrations and is not forwarded to Calendly

type CalendlyTrackingPayload = {
  utmSource: string;
  utmMedium: string;
  utmCampaign: string;
  utmContent: string;
  utmTerm: string;
};

type BookingMetadata = {
  salesforceUuid?: string;
  [key: string]: string | number | boolean | null | undefined;
};

Server Hook

The booking route supports an optional afterBooking hook for follow-up systems such as CRM, n8n, or analytics syncs.

const POST = createCalendlyBookingRoute(config, {
  afterBooking: async ({ requestPayload, bookingResponse }) => {
    // requestPayload.metadata stays available here
    // bookingResponse contains the normalized Calendly success payload
  }
});

Behavior:

• the hook only runs after a successful Calendly booking
• hook failures are logged but do not turn a successful booking into an error
• the hook receives the original widget request plus the normalized Calendly response

Note

Integration details are maintained in the project documentation and host application codebase.