@seatlayer/js 0.40.0 → 0.41.0

package/dist/index.d.cts

@@ -603,6 +603,21 @@ interface SeatingChartOptions {
      */
     onSelectedObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
     onError?: (err: unknown) => void;
+    /**
+     * What the BUYER sees when the chart cannot load.
+     *
+     * `'message'` (the default) renders a plain, styleable notice with a Try
+     * again button. This used to be silent unconditionally: `render()` returned
+     * with an EMPTY mounted div and only `onError` fired, so a host that had not
+     * wired `onError` — or had wired it to a logger — showed buyers a blank
+     * rectangle where the seat map belongs, on the host's own domain, which
+     * reads as a broken website rather than a temporary fault. `SeatPicker` has
+     * always failed loud with a retry; this is the embed class catching up.
+     *
+     * `'none'` restores the silent behaviour for hosts that render their own
+     * failure UI from `onError`.
+     */
+    errorDisplay?: 'message' | 'none';
     /**
      * Multi-floor charts only: fires when the buyer taps a deck in the stacked
      * 3D view, after the picker switches to that floor — lets the host page sync
@@ -624,6 +639,7 @@ declare class SeatingChart {
     private mount;
     private hostEl;
     private rendered;
+    private retryBtn;
     private mode_;
     private tipEl;
     private tipPos;
@@ -768,6 +784,13 @@ declare class SeatingChart {
      * true when a fresh bearer is held; the realtime feed restarts with it.
      */
     refreshAccess(): Promise<boolean>;
+    /**
+     * The visible failure state. Deliberately inline-styled and dependency-free:
+     * this renders on a stranger's website, where our stylesheet may not have
+     * loaded (the chart fetch just failed) and where inheriting the host's own
+     * styles is likelier to produce something unreadable than something on-brand.
+     */
+    private showLoadFailure;
     destroy(): void;
 }
 
@@ -1274,17 +1297,33 @@ interface SeatPickerOptions {
      * 1. It needs the widget's own transport. A host-supplied `transport` owns its
      *    credentials and its backend, so hosted checkout stays off there (with one
      *    console warning) rather than reaching past it to api.seatlayer.io.
-     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER IS THE SERVER'S CHOICE. The
-     *    checkout session's return URL is built from the deployment's own allowed
-     *    origins, so a buyer paying by card from an embed on your domain comes back
-     *    to SeatLayer's buyer page and is confirmed THERE, not in this widget. The
-     *    widget resumes in place only when it is mounted on a page that actually
-     *    receives `?order=…&status=success` (a page on an allowed origin, and the
-     *    in-page gateways, which never navigate away at all). Until the server
-     *    accepts a caller-supplied return URL, treat a card payment from a
-     *    third-party embed as "the buyer finishes on our page".
+     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER is settled by {@link returnUrl}
+     *    and by the organizer. Without one — or from an origin the organizer has
+     *    not declared — the buyer comes back to SeatLayer's own buyer page and is
+     *    confirmed THERE, not in this widget. Declare the embedding site under
+     *    Embed domains in the dashboard and pass `returnUrl`, and the buyer
+     *    returns to your page instead. In-page gateways never navigate away at
+     *    all, so they are unaffected either way.
      */
     checkout?: 'handoff' | 'hosted';
+    /**
+     * Where a redirecting gateway should send the buyer back to, for
+     * `checkout: 'hosted'`.
+     *
+     * The server keeps this URL verbatim — path and query included — and only
+     * stamps `?order=…&status=success|cancelled` onto it, so point it at
+     * whichever of YOUR pages should confirm the purchase (often just
+     * `window.location.href`). Mount a picker on that page and it resumes in
+     * place from those parameters.
+     *
+     * It is validated, not trusted: the organizer declares their embed origins
+     * in the dashboard, and an undeclared origin is ignored rather than
+     * refused — the sale still completes, the buyer just finishes on
+     * SeatLayer's page. Supplying a URL therefore cannot authorize it, which is
+     * what stops a copied snippet from redirecting a paid buyer anywhere it
+     * likes.
+     */
+    returnUrl?: string;
     /**
      * Buyer pressed the CTA and the hold succeeded — hand off to YOUR checkout.
      * `hold` and `seats` are the legacy args (unchanged since 0.6). `handoff` (P4)

package/dist/index.d.ts

@@ -603,6 +603,21 @@ interface SeatingChartOptions {
      */
     onSelectedObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
     onError?: (err: unknown) => void;
+    /**
+     * What the BUYER sees when the chart cannot load.
+     *
+     * `'message'` (the default) renders a plain, styleable notice with a Try
+     * again button. This used to be silent unconditionally: `render()` returned
+     * with an EMPTY mounted div and only `onError` fired, so a host that had not
+     * wired `onError` — or had wired it to a logger — showed buyers a blank
+     * rectangle where the seat map belongs, on the host's own domain, which
+     * reads as a broken website rather than a temporary fault. `SeatPicker` has
+     * always failed loud with a retry; this is the embed class catching up.
+     *
+     * `'none'` restores the silent behaviour for hosts that render their own
+     * failure UI from `onError`.
+     */
+    errorDisplay?: 'message' | 'none';
     /**
      * Multi-floor charts only: fires when the buyer taps a deck in the stacked
      * 3D view, after the picker switches to that floor — lets the host page sync
@@ -624,6 +639,7 @@ declare class SeatingChart {
     private mount;
     private hostEl;
     private rendered;
+    private retryBtn;
     private mode_;
     private tipEl;
     private tipPos;
@@ -768,6 +784,13 @@ declare class SeatingChart {
      * true when a fresh bearer is held; the realtime feed restarts with it.
      */
     refreshAccess(): Promise<boolean>;
+    /**
+     * The visible failure state. Deliberately inline-styled and dependency-free:
+     * this renders on a stranger's website, where our stylesheet may not have
+     * loaded (the chart fetch just failed) and where inheriting the host's own
+     * styles is likelier to produce something unreadable than something on-brand.
+     */
+    private showLoadFailure;
     destroy(): void;
 }
 
@@ -1274,17 +1297,33 @@ interface SeatPickerOptions {
      * 1. It needs the widget's own transport. A host-supplied `transport` owns its
      *    credentials and its backend, so hosted checkout stays off there (with one
      *    console warning) rather than reaching past it to api.seatlayer.io.
-     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER IS THE SERVER'S CHOICE. The
-     *    checkout session's return URL is built from the deployment's own allowed
-     *    origins, so a buyer paying by card from an embed on your domain comes back
-     *    to SeatLayer's buyer page and is confirmed THERE, not in this widget. The
-     *    widget resumes in place only when it is mounted on a page that actually
-     *    receives `?order=…&status=success` (a page on an allowed origin, and the
-     *    in-page gateways, which never navigate away at all). Until the server
-     *    accepts a caller-supplied return URL, treat a card payment from a
-     *    third-party embed as "the buyer finishes on our page".
+     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER is settled by {@link returnUrl}
+     *    and by the organizer. Without one — or from an origin the organizer has
+     *    not declared — the buyer comes back to SeatLayer's own buyer page and is
+     *    confirmed THERE, not in this widget. Declare the embedding site under
+     *    Embed domains in the dashboard and pass `returnUrl`, and the buyer
+     *    returns to your page instead. In-page gateways never navigate away at
+     *    all, so they are unaffected either way.
      */
     checkout?: 'handoff' | 'hosted';
+    /**
+     * Where a redirecting gateway should send the buyer back to, for
+     * `checkout: 'hosted'`.
+     *
+     * The server keeps this URL verbatim — path and query included — and only
+     * stamps `?order=…&status=success|cancelled` onto it, so point it at
+     * whichever of YOUR pages should confirm the purchase (often just
+     * `window.location.href`). Mount a picker on that page and it resumes in
+     * place from those parameters.
+     *
+     * It is validated, not trusted: the organizer declares their embed origins
+     * in the dashboard, and an undeclared origin is ignored rather than
+     * refused — the sale still completes, the buyer just finishes on
+     * SeatLayer's page. Supplying a URL therefore cannot authorize it, which is
+     * what stops a copied snippet from redirecting a paid buyer anywhere it
+     * likes.
+     */
+    returnUrl?: string;
     /**
      * Buyer pressed the CTA and the hold succeeded — hand off to YOUR checkout.
      * `hold` and `seats` are the legacy args (unchanged since 0.6). `handoff` (P4)

package/dist/index.js

@@ -906,6 +906,7 @@ var SeatingChart = class {
     this.mount = null;
     this.hostEl = null;
     this.rendered = false;
+    this.retryBtn = null;
     this.mode_ = null;
     this.tipEl = null;
     this.tipPos = { x: 0, y: 0 };
@@ -967,6 +968,7 @@ var SeatingChart = class {
     const info = await this.controller.render(host);
     if (!info) {
       this.rendered = false;
+      if (this.opts.errorDisplay !== "none") this.showLoadFailure(host);
       return this;
     }
     this.controller.setViewMode(this.opts.initialView ?? "flat");
@@ -1257,10 +1259,36 @@ var SeatingChart = class {
     }
     return ok;
   }
+  /**
+   * The visible failure state. Deliberately inline-styled and dependency-free:
+   * this renders on a stranger's website, where our stylesheet may not have
+   * loaded (the chart fetch just failed) and where inheriting the host's own
+   * styles is likelier to produce something unreadable than something on-brand.
+   */
+  showLoadFailure(host) {
+    const box = document.createElement("div");
+    box.setAttribute("role", "status");
+    box.style.cssText = 'display:flex;flex-direction:column;align-items:center;justify-content:center;gap:12px;width:100%;height:100%;min-height:180px;box-sizing:border-box;padding:24px;text-align:center;font:500 14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#3b4256;';
+    const text = document.createElement("div");
+    text.textContent = "The seat map didn\u2019t load.";
+    box.appendChild(text);
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.textContent = "Try again";
+    btn.style.cssText = "appearance:none;border:1px solid #c9cede;background:#fff;color:#10162a;border-radius:8px;padding:8px 16px;font:600 13px/1 inherit;cursor:pointer;";
+    btn.addEventListener("click", () => {
+      this.destroy();
+      void this.render().catch((err) => this.opts.onError?.(err));
+    });
+    box.appendChild(btn);
+    this.retryBtn = btn;
+    host.appendChild(box);
+  }
   destroy() {
     this.realtime?.stop();
     this.realtime = null;
     this.access?.clear();
+    this.retryBtn = null;
     if (this.hostEl && this.onTipMove) this.hostEl.removeEventListener("mousemove", this.onTipMove);
     this.tipEl = null;
     this.onTipMove = null;
@@ -5447,7 +5475,15 @@ var SeatPicker = class _SeatPicker {
     this.checkoutPanel = mountCheckout({
       root: this.root,
       state,
-      startSession: (input) => this.pubApi.startCheckout(this.opts.event, input),
+      // `returnUrl` rides along so a redirecting gateway can come back to the
+      // HOST's page. The server validates its origin against the organizer's
+      // declared embed domains and silently falls back to our own buyer page
+      // when it does not match, so passing one can never redirect a paid buyer
+      // somewhere the organizer did not sanction.
+      startSession: (input) => this.pubApi.startCheckout(this.opts.event, {
+        ...input,
+        ...this.opts.returnUrl ? { returnUrl: this.opts.returnUrl } : {}
+      }),
       orderStatus: (orderId) => this.pubApi.orderStatus(orderId),
       onCancel: () => {
         this.checkoutPanel = null;