@aranova/tracking-react 1.4.1 → 1.6.0

package/README.md

@@ -318,7 +318,14 @@ import { useBookingIntegration, useBookingSlots, useBookingSubmit } from "@arano
 const booking = useBookingIntegration(ARANOVA_TRACKING_CONFIG);
 const days = useBookingSlots(ARANOVA_TRACKING_CONFIG); // [{ date, weekday, morning, afternoon }]
 const { status, outcome, submit } = useBookingSubmit(conversions.bookings, {
-  formSubmit: { tracking, formId: "booking-form" },
+  formSubmit: {
+    tracking,
+    formId: "booking-form",
+    // Your own questions, for our reporting only; never sent to the shop.
+    extraFields: [
+      { name: "heardVia", type: "select", label: "How did you hear about us?", value: heardVia },
+    ],
+  },
 });
 
 await submit({
@@ -339,7 +346,8 @@ await submit({
 - `conversions` is the site's one `createSalesClient({ apiKey, endpoint, firing: getTrackingConfigRuntime(...) })`;
   `.bookings` reads the rules from that runtime.
 - `outcome.status`: `created` (the shop texts and emails the customer itself; send nothing of
-  your own), `pending` (same success; still being sent, the owner is alerted if it fails),
+  your own), `pending` (same success; still being sent, the owner is alerted if it fails;
+  `status` turns `pending` as soon as the server says so, while the final answer is polled),
   `failed` (success copy plus `outcome.fallbackUrl`, the prefilled shop page), `invalid`
   (`outcome.message`, nothing sent), `stale` (the times changed; the config is refetched).
 - `outcome.mode` (and `booking.mode` before submitting): `live` for every real customer;
@@ -349,9 +357,14 @@ await submit({
   outcome (`created`, `rejected`, `unknown`, `failed`) to exercise each screen. The production
   API ignores it. Test locally against the local API **and** the local CDN; the SDK warns in the
   console when the endpoint is localhost but the config comes from production.
+- `booking.options` arrive grouped by the shop's service category: each has `group` (the heading,
+  or `null`) and an optional `description`. `groupBookingOptions(booking.options)` returns
+  `[{ group, options }]` in order, so render one heading per group with its choices under it.
 - `useBookingSlots` / `bookableSlots(rules, { timeZone })` offer exactly the portal's start hours,
   judged by the shop's date. `useBookingSubmit` reuses one attempt key across a double-click or
-  a retry, and sends the visit's `form_submit` once: don't send your own for this form.
+  a retry, and sends the visit's `form_submit` once: don't send your own for this form. Add the
+  form's own questions with `formSubmit.extraFields`; a name the booking already reports
+  (`phone`, `email`, ...) is dropped.
 - Ask for the last name separately, and a mobile number (the shop's confirmation text goes to it).
 - Reports the `booking_integration` capability.
 

package/dist/{bookings-DIu1ho6v.d.ts → bookings-B50X7GSG.d.ts}

@@ -69,6 +69,10 @@ interface BookingOptionConfig {
     /** What the site posts in `services`. */
     key: string;
     label: string;
+    /** The shop's service category; options arrive grouped, each category in one run. */
+    group: string | null;
+    /** Optional helper text under the label. */
+    description: string | null;
 }
 /** Where a booking went; decided by the API. A real customer always gets `live`. */
 declare const BOOKING_MODES: readonly ["live", "test", "simulated"];
@@ -305,7 +309,15 @@ interface BookingFormSubmit {
     };
     /** The `<form id>`, so `form_start` and `form_submit` line up. */
     formId: string;
+    /**
+     * The site's own questions (e.g. "How did you hear about us?"), appended to this
+     * `form_submit` for our reporting; never sent to the shop. A name the booking already
+     * reports (`phone`, `email`, ...) is dropped, so lead matching cannot be overridden.
+     */
+    extraFields?: FormSubmitField[];
 }
+/** One field of a `form_submit`. */
+type FormSubmitField = NonNullable<FormSubmitMetadata["form"]["fields"]>[number];
 type BookingOutcome = 
 /** The shop has the request; it texts and emails the customer itself. */
 {
@@ -349,6 +361,13 @@ interface BookingSubmitOptions {
      * fallback screens. The production API ignores it, so it can never change a real booking.
      */
     simulate?: BookingSimulation;
+    /**
+     * Called once when the server answers `pending`, before `submit` polls for the final answer
+     * (up to ~30 s): show the pending success right away instead of a spinner.
+     */
+    onPending?: (outcome: Extract<BookingOutcome, {
+        status: "pending";
+    }>) => void;
 }
 interface SalesBookingsClient {
     /**
@@ -363,4 +382,4 @@ interface SalesBookingsClient {
 /** A fresh per-submit key. Keep it for retries of the same submit; mint a new one after. */
 declare const newBookingAttemptKey: typeof uuidV4;
 
-export { type BookingDropOff as B, type ConversionConfig as C, type SalesBookingsClient as S, type TrackingConfigReference as T, type BookingFormSubmit as a, type BookingInput as b, type BookingMode as c, type BookingOutcome as d, type BookingSimulation as e, type BookingSubmitOptions as f, type ConversionConfigStore as g, getTrackingConfigRuntime as h, resolveTrackingConfigUrl as i, type BookingDayWindows as j, type ConversionIntegrations as k, TrackingConfigRuntime as l, newBookingAttemptKey as n, resolveConversionConfig as r };
+export { type BookingDropOff as B, type ConversionConfig as C, type FormSubmitField as F, type SalesBookingsClient as S, type TrackingConfigReference as T, type BookingFormSubmit as a, type BookingInput as b, type BookingMode as c, type BookingOutcome as d, type BookingSimulation as e, type BookingSubmitOptions as f, type ConversionConfigStore as g, getTrackingConfigRuntime as h, resolveTrackingConfigUrl as i, type BookingDayWindows as j, type ConversionIntegrations as k, TrackingConfigRuntime as l, newBookingAttemptKey as n, resolveConversionConfig as r };

package/dist/{bookings-CqCuuyP6.d.mts → bookings-n8UUzrak.d.mts}

@@ -69,6 +69,10 @@ interface BookingOptionConfig {
     /** What the site posts in `services`. */
     key: string;
     label: string;
+    /** The shop's service category; options arrive grouped, each category in one run. */
+    group: string | null;
+    /** Optional helper text under the label. */
+    description: string | null;
 }
 /** Where a booking went; decided by the API. A real customer always gets `live`. */
 declare const BOOKING_MODES: readonly ["live", "test", "simulated"];
@@ -305,7 +309,15 @@ interface BookingFormSubmit {
     };
     /** The `<form id>`, so `form_start` and `form_submit` line up. */
     formId: string;
+    /**
+     * The site's own questions (e.g. "How did you hear about us?"), appended to this
+     * `form_submit` for our reporting; never sent to the shop. A name the booking already
+     * reports (`phone`, `email`, ...) is dropped, so lead matching cannot be overridden.
+     */
+    extraFields?: FormSubmitField[];
 }
+/** One field of a `form_submit`. */
+type FormSubmitField = NonNullable<FormSubmitMetadata["form"]["fields"]>[number];
 type BookingOutcome = 
 /** The shop has the request; it texts and emails the customer itself. */
 {
@@ -349,6 +361,13 @@ interface BookingSubmitOptions {
      * fallback screens. The production API ignores it, so it can never change a real booking.
      */
     simulate?: BookingSimulation;
+    /**
+     * Called once when the server answers `pending`, before `submit` polls for the final answer
+     * (up to ~30 s): show the pending success right away instead of a spinner.
+     */
+    onPending?: (outcome: Extract<BookingOutcome, {
+        status: "pending";
+    }>) => void;
 }
 interface SalesBookingsClient {
     /**
@@ -363,4 +382,4 @@ interface SalesBookingsClient {
 /** A fresh per-submit key. Keep it for retries of the same submit; mint a new one after. */
 declare const newBookingAttemptKey: typeof uuidV4;
 
-export { type BookingDropOff as B, type ConversionConfig as C, type SalesBookingsClient as S, type TrackingConfigReference as T, type BookingFormSubmit as a, type BookingInput as b, type BookingMode as c, type BookingOutcome as d, type BookingSimulation as e, type BookingSubmitOptions as f, type ConversionConfigStore as g, getTrackingConfigRuntime as h, resolveTrackingConfigUrl as i, type BookingDayWindows as j, type ConversionIntegrations as k, TrackingConfigRuntime as l, newBookingAttemptKey as n, resolveConversionConfig as r };
+export { type BookingDropOff as B, type ConversionConfig as C, type FormSubmitField as F, type SalesBookingsClient as S, type TrackingConfigReference as T, type BookingFormSubmit as a, type BookingInput as b, type BookingMode as c, type BookingOutcome as d, type BookingSimulation as e, type BookingSubmitOptions as f, type ConversionConfigStore as g, getTrackingConfigRuntime as h, resolveTrackingConfigUrl as i, type BookingDayWindows as j, type ConversionIntegrations as k, TrackingConfigRuntime as l, newBookingAttemptKey as n, resolveConversionConfig as r };

package/dist/client.d.mts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent, AnchorHTMLAttributes } from 'react';
 import { G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, h as ConsentState, f as ConsentChoiceState, g as ConsentSource, T as TrackingParams, b as TrackingEnvironment, j as PhoneConfig, P as ParsedPhone, k as PhoneDisplayFormat } from './phone-utils-CM8eUPz8.mjs';
-import { T as TrackingConfigReference, C as ConversionConfig, d as BookingOutcome, b as BookingInput, S as SalesBookingsClient, a as BookingFormSubmit, e as BookingSimulation } from './bookings-CqCuuyP6.mjs';
-import { W as TriggerRegistryConfig, Y as TypedTrackingClient, a as BookingHandoffPrefill, b as BookingIntegration, B as BookableDay } from './ingest-typed-D7UZr0EM.mjs';
+import { T as TrackingConfigReference, C as ConversionConfig, d as BookingOutcome, b as BookingInput, S as SalesBookingsClient, a as BookingFormSubmit, e as BookingSimulation } from './bookings-n8UUzrak.mjs';
+import { X as TriggerRegistryConfig, Z as TypedTrackingClient, a as BookingHandoffPrefill, b as BookingIntegration, B as BookableDay } from './ingest-typed-ABH28Ips.mjs';
 import { CountryCode } from 'libphonenumber-js';
 import './form-submit-BLb28aCk.mjs';
 import 'zod/mini';
@@ -414,7 +414,8 @@ interface BookingSubmitState {
 /**
  * Submit state for a booking form over `salesClient.bookings`. Owns the parts that are easy to
  * get wrong: one attempt key per submit (a double-click never books twice), the visit's
- * `form_submit`, the stale-config refetch, and the fallback link on failure.
+ * `form_submit`, the stale-config refetch, and the fallback link on failure. A `pending` answer
+ * shows at once (`status: "pending"`) while the final one is polled; the submit stays in flight.
  */
 declare function useBookingSubmit(bookings: SalesBookingsClient, options?: {
     formSubmit?: BookingFormSubmit;

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent, AnchorHTMLAttributes } from 'react';
 import { G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, h as ConsentState, f as ConsentChoiceState, g as ConsentSource, T as TrackingParams, b as TrackingEnvironment, j as PhoneConfig, P as ParsedPhone, k as PhoneDisplayFormat } from './phone-utils-l8ey3Zdm.js';
-import { T as TrackingConfigReference, C as ConversionConfig, d as BookingOutcome, b as BookingInput, S as SalesBookingsClient, a as BookingFormSubmit, e as BookingSimulation } from './bookings-DIu1ho6v.js';
-import { W as TriggerRegistryConfig, Y as TypedTrackingClient, a as BookingHandoffPrefill, b as BookingIntegration, B as BookableDay } from './ingest-typed-D2S3Kb8m.js';
+import { T as TrackingConfigReference, C as ConversionConfig, d as BookingOutcome, b as BookingInput, S as SalesBookingsClient, a as BookingFormSubmit, e as BookingSimulation } from './bookings-B50X7GSG.js';
+import { X as TriggerRegistryConfig, Z as TypedTrackingClient, a as BookingHandoffPrefill, b as BookingIntegration, B as BookableDay } from './ingest-typed-vP-DqpxO.js';
 import { CountryCode } from 'libphonenumber-js';
 import './form-submit-BLb28aCk.js';
 import 'zod/mini';
@@ -414,7 +414,8 @@ interface BookingSubmitState {
 /**
  * Submit state for a booking form over `salesClient.bookings`. Owns the parts that are easy to
  * get wrong: one attempt key per submit (a double-click never books twice), the visit's
- * `form_submit`, the stale-config refetch, and the fallback link on failure.
+ * `form_submit`, the stale-config refetch, and the fallback link on failure. A `pending` answer
+ * shows at once (`status: "pending"`) while the final one is polled; the submit stays in flight.
  */
 declare function useBookingSubmit(bookings: SalesBookingsClient, options?: {
     formSubmit?: BookingFormSubmit;

package/dist/client.js

@@ -1035,7 +1035,14 @@ function parseBookingOption(value) {
   if (!value || typeof value !== "object") return [];
   const o = value;
   if (typeof o.key !== "string" || !o.key || typeof o.label !== "string") return [];
-  return [{ key: o.key, label: o.label }];
+  return [
+    {
+      key: o.key,
+      label: o.label,
+      group: typeof o.group === "string" && o.group ? o.group : null,
+      description: typeof o.description === "string" && o.description ? o.description : null
+    }
+  ];
 }
 function parseIntegrations(value) {
   if (!value || typeof value !== "object") return {};
@@ -1739,7 +1746,12 @@ function getBookingIntegration(integrations) {
     timezone: booking.timezone,
     configVersion: booking.config_version,
     rules,
-    options: booking.options.map((option) => ({ key: option.key, label: option.label })),
+    options: booking.options.map((option) => ({
+      key: option.key,
+      label: option.label,
+      group: option.group,
+      description: option.description
+    })),
     mode: booking.mode ?? "live"
   };
 }
@@ -3973,7 +3985,7 @@ function GoogleAdsTracking(props) {
 var import_react6 = require("react");
 
 // package.json
-var version = "1.4.1";
+var version = "1.6.0";
 
 // ../tracking-core/src/phone-react.tsx
 var import_react5 = require("react");
@@ -4296,7 +4308,16 @@ function useBookingSubmit(bookings, options = {}) {
       if (inFlight.current) return inFlight.current;
       attemptKey.current ?? (attemptKey.current = newBookingAttemptKey());
       setSubmitting(true);
-      const run = bookings.submit(input, { attemptKey: attemptKey.current, formSubmit, simulate }).then((result) => {
+      const run = bookings.submit(input, {
+        attemptKey: attemptKey.current,
+        formSubmit,
+        simulate,
+        // The server has it: show the pending success while the final answer is polled.
+        onPending: (pending) => {
+          setOutcome(pending);
+          setSubmitting(false);
+        }
+      }).then((result) => {
         const unrecorded = result.status === "invalid" || result.status === "stale" || result.status === "failed" && result.id === null;
         if (!unrecorded) attemptKey.current = null;
         setOutcome(result);