Events reference

The host-facing contract is six coras:* events. Each event has a matching mount() callback. Internal component events (form fields, calendar, seats.io, overlay coordination, and others) are not part of this contract and do not cross the SDK boundary.

You can receive each event two ways:

• A mount() callback (recommended). See Receive events.
• A DOM listener on the mounted container (advanced).

All payloads are minimal and redacted. They never carry secrets, payment provider data, or personal data.

Events

Event	Callback	Fired when
coras:ready	onReady	The page is mounted and its first render is complete.
coras:navigate	onNavigate	The embed signals a navigation intent (cross-page action or external link).
coras:state-change	onStateChange	In-page state changed, such as filters or selection.
coras:reservation-created	onReservationCreated	A reservation was created.
coras:payment-status	onPaymentStatus	A payment succeeded, failed, or is still awaiting confirmation.
coras:error	onError	The SDK produced a safe, redacted error.

PageName below is the CorasPageName union: "landing", "search", "details", "payment", "help", or "suggestion-widget". CorasPageParams is the per-page params type. SupportedLocales and SupportedCurrencies are the locale and currency unions. All four types are exported from @coras-io/embed.

coras:ready

Fired when the page is mounted and its first render is complete.

type CorasReadyDetail = {
  page: CorasPageName;
};

Field	Type	Notes
page	CorasPageName	The mounted page.

coras:navigate

A navigation intent: a cross-page action or an external link. The host maps it to its own router.

type CorasNavigateDetail = {
  page: CorasPageName;
  params?: CorasPageParams;
  locale?: SupportedLocales;
  currency?: SupportedCurrencies;
  href?: string;
  source: "embed" | "host";
};

Field	Type	Notes
page	CorasPageName	Target page for the navigation intent.
params	CorasPageParams	Optional params for the target page.
locale	SupportedLocales	Optional locale for the target page.
currency	SupportedCurrencies	Optional currency for the target page.
href	string	Present for external links.
source	"embed" | "host"	Origin of the intent.

coras:state-change

In-page state changed, such as filters or selection. This is not necessarily a route change. The host decides whether to persist it in the URL.

type CorasStateChangeDetail = {
  page: CorasPageName;
  params: CorasPageParams;
  locale?: SupportedLocales;
  currency?: SupportedCurrencies;
};

Field	Type	Notes
page	CorasPageName	The page whose state changed.
params	CorasPageParams	Current page params after the change.
locale	SupportedLocales	Optional current locale.
currency	SupportedCurrencies	Optional current currency.

coras:reservation-created

A minimal, redacted reservation summary. It never contains the raw API response.

type CorasReservationCreatedDetail = {
  reservationId?: string;
  expiresIn?: number;
  ticketDeliveryMethod?: number;
};

Field	Type	Notes
reservationId	string	Public reservation id.
expiresIn	number	Seconds until the reservation expires.
ticketDeliveryMethod	number	Ticket delivery method code (see note).

Note

ticketDeliveryMethod is a numeric code from the Coras API, not an enum the SDK defines. For the current code-to-method mapping, see the API catalogue or contact Coras.

coras:payment-status

A payment status with an optional public reference.

type CorasPaymentStatusDetail = {
  status: "succeeded" | "failed" | "pending";
  reference?: string;
};

Field	Type	Notes
status	"succeeded" | "failed" | "pending"	pending means the charge succeeded but the API had not confirmed the transaction within the polling budget; use reference to reconcile it later.
reference	string	Public reference only. Never provider secrets or card data.

coras:error

A safe, redacted error.

type CorasErrorDetail = {
  code: string;
  message: string;
  page?: CorasPageName;
};

Field	Type	Notes
code	string	Stable machine code, for example invalid_page_params.
message	string	Safe, redacted, human-readable message.
page	CorasPageName	Page the error relates to, when known.

code is an open string so new codes can be added without breaking your integration. Match on the codes you handle and treat any unknown code as a generic error. These are the codes the SDK emits today.

Code	When
missing_container	container is not a DOM element.
invalid_page	page is not one of the six public pages.
invalid_config	config is missing or a required field is absent.
invalid_url	apiUrl or assetsUrl fails its validation rules.
invalid_locale	locale or an allowedLocales entry is unknown.
invalid_currency	currency or an allowedCurrencies entry is unknown.
invalid_page_params	A per-page param has the wrong shape.
unknown_key	Strict mode found an unknown key in config or params.
mount_error	Any other error during mount or page load. The message is generic so internal details never leak.
callback_error	A host callback threw. The SDK reports it through onError, unless onError itself threw.

The first eight are CorasValidationError codes (see Config validation errors). mount_error and callback_error are runtime fallbacks.

Wrap your callbacks

callback_error means one of your mount() callbacks threw. Wrap callback bodies in try/catch and handle failures yourself; the SDK only reports the throw, it cannot recover your callback’s work.

Recover from errors

Split the codes by how you respond:

• Recoverable - invalid_config, invalid_url, invalid_locale, invalid_currency, invalid_page_params, unknown_key. Fix the offending input and retry with a corrected mount() or app.update().
• Terminal - missing_container, invalid_page, mount_error. The page cannot render; show your own fallback UI instead of retrying blindly.

Receive events

Use mount() callbacks for normal integrations.

import { mount } from "@coras-io/embed";

const app = mount({
  container: document.getElementById("coras")!,
  page: "search",
  config,
  onNavigate(detail) {
    router.push(detail.page, detail.params);
  },
  onPaymentStatus(detail) {
    if (detail.status === "succeeded") showConfirmation();
  },
});

For advanced cases, listen for the DOM events on the mounted container. The events bubble and are composed, so they reach the container even when the page renders inside a shadow root.

container.addEventListener("coras:payment-status", (event) => {
  console.log(event.detail.status);
});

The CorasEvent type, exported from @coras-io/embed, gives typed event.detail for DOM listeners. It is a CustomEvent keyed by event name:

import type { CorasEvent } from "@coras-io/embed";

container.addEventListener(
  "coras:navigate",
  (event: CorasEvent<"coras:navigate">) => {
    event.detail.page; // typed CorasNavigateDetail
    event.detail.source; // "embed" | "host"
  },
);

Multiple mounts on one page

Callbacks are scoped to their own mount. Listeners attach to each mount’s own element, so an event from one mount never reaches another mount’s callbacks.

A DOM listener on a shared ancestor receives bubbling events from every mount below it. Listen on the specific container to scope DOM events to one mount.

Observability

Separate from the six coras:* host events, the onObservability callback reports per-mount lifecycle and diagnostic facts (dot-namespaced names such as coras.page-loaded). It has no matching DOM event.

type CorasObservabilityEvent = {
  name: string; // e.g. "coras.page-loaded", "coras.error", "coras.unmounted"
  page?: CorasPageName;
  data?: Record<string, string | number | boolean | null | undefined>;
};

See Observe lifecycle events for the emitted names and their data keys.