Skip to content

Config

CorasConfig is the config object you pass to mount(). This page lists every field, its validation rules, and the error codes validation can throw.

Validation runs before anything renders. Invalid input throws CorasValidationError. The same rules apply to the partial config you pass to app.update().

type CorasConfig = {
apiUrl: string;
distributorId: string;
assetsUrl: string;
locale?: SupportedLocales;
allowedLocales?: SupportedLocales[];
currency?: SupportedCurrencies;
allowedCurrencies?: SupportedCurrencies[];
loyaltyPointsEnabled?: boolean;
loyalty?: CorasLoyaltyProgramme;
theme?: CorasTheme;
colorScheme?: "light" | "dark" | "inherit";
};

The Coras API base URL. Non-empty string.

Rule Result
https:// URL Accepted
http://localhost, http://127.0.0.1, http://[::1], http://*.localhost Accepted (dev only)
Missing, empty, or not a string Throws invalid_config
Any other value Throws invalid_url
apiUrl: "https://api.coras.io";

Your distributor identifier. Non-empty string. Missing, empty, or non-string values throw invalid_config.

distributorId: "your-distributor-id";

Where static assets (icons, payment-provider logos) are served from. The host must provide it: the SDK ships no default, so nothing ties the package to a specific deployment. Point it at your own CDN, at assets you self-host, or - for a test integration - at the sandbox origin (https://assets.sandbox.coras.io/shared). Accepts one of the forms below.

Form Example
https:// URL (http allowed only for localhost) "https://assets.coras.io/shared"
Root-relative path "/assets"

A trailing slash is accepted and removed ("https://assets.coras.io/shared/" becomes "https://assets.coras.io/shared"), because the SDK appends /<file> to the value.

Rejected with invalid_url: empty string (including a bare /, which is empty once the slash is removed), a bare hostname (images.coras.io), protocol-relative URLs (//host/x), javascript: or data: URIs, and paths containing ...

assetsUrl: "https://assets.sandbox.coras.io/shared";

Active BCP 47 locale. Casing and separators are normalized, so en_ie and EN-IE both become en-IE. Must resolve to a supported locale, or it throws invalid_locale.

locale: "en-IE";

Locales the navbar language switcher offers. Each entry is normalized the same way as locale. Any unsupported entry throws invalid_locale.

allowedLocales: ["en-IE", "pl-PL", "de-DE"];

Active ISO 4217 currency. Casing is normalized, so eur becomes EUR. Must resolve to a supported currency, or it throws invalid_currency.

currency: "EUR";

Currencies the navbar currency switcher offers. Each entry is normalized the same way as currency. Any unsupported entry throws invalid_currency.

allowedCurrencies: ["EUR", "GBP", "USD"];

Enable the FIDA token UI on the details and payment pages, so customers can earn and spend FIDA tokens during checkout. Defaults to false. Requires the FIDA programme to be activated on your distributor account - contact Coras.

loyaltyPointsEnabled: true;

Do not combine it with loyalty: a distributor has either FIDA or a partner programme, and with loyalty set the programme badge replaces the FIDA block on the details page.

How to present the partner loyalty programme (airline miles, partner points) enabled on your distributor account. Optional; unset shows nothing. The API computes the amounts and decides which membership fields the payment form collects, keyed by the programme code. This object supplies what the package cannot know: the programme name, the unit words, the field labels, the artwork and the terms link.

type CorasLoyaltyProgramme = {
code: string;
name: string;
unit: { singular: string; plural: string };
logo?: string;
logoDark?: string;
icon?: string;
termsUrl?: string;
fields?: Record<string, { label: string; helpText?: string }>;
};
loyalty: {
code: "EXAMPLE_MILES",
name: "Example Miles",
unit: { singular: "mile", plural: "miles" },
logo: "https://cdn.example.com/loyalty/logo.svg",
termsUrl: "https://example.com/miles/terms",
fields: {
membership_number: {
label: "Example Miles membership number",
helpText: "Add your membership number to receive your miles.",
},
},
};

code, name, unit.singular and unit.plural must be non-empty strings and every fields entry needs a label; anything else throws invalid_config. In strict mode an unknown key inside loyalty throws unknown_key.

With loyalty set, attraction cards, the details page, basket items and the confirmation show the amount the API returns under loyalty.earn[code] as a coras-loyalty-badge, styled by the loyalty.background and loyalty.text brand tokens. The payment page renders the membership fields that GET /reservations/check lists for the distributor under an “Additional details” heading, each with its fields label as the placeholder; a field without an entry in fields falls back to its API name.

A brand.json (the shared branding contract), grouped by surface or as flat keys, at any supported schemaVersion, scoped to the mounted container. See Theming and branding.

theme: { primary: "#4657d4", radius: "1rem", navbar: { background: "#161c44" } }

Selects which side of the brand’s light-dark() token pairs renders. Flippable live via app.update({ config: { colorScheme } }) with no remount. See Dark mode.

Value Behaviour
"light" Default. Always light, ignoring the host page.
"dark" Always dark.
"inherit" Follows the host page’s own color-scheme (the SDK sets none).
colorScheme: "inherit";

mount() also validates the params object against the page you mount. These checks throw invalid_page_params.

Page Param Rule
details id When present, must be a non-empty string
payment metadata When present, must be an object whose values are all strings
suggestion-widget limit When present, must be a positive number

Strict mode is off by default. Pass strict: true to mount() to reject unknown keys.

strict Unknown config or params keys
false (default) Ignored
true Throw unknown_key

The strict flag you pass to mount() also applies to later app.update() calls.

mount() never writes to the console on its own. Pass a logger to receive what it would have said:

type CorasLogger = {
warn?: (message: string, data?: unknown) => void;
error?: (error: unknown, data?: unknown) => void;
};

error receives the error for every failure the SDK also reports through onError. Wire it to your error reporter. Every argument to error and warn is redacted first, so email addresses, +-prefixed phone numbers, card numbers, secrets and tokens are masked. An error arrives as a copy with the same type and stack, a redacted message and fields, and no cause.

warn is the opt-in to the SDK’s diagnostics, which is why it is separate. Wiring it turns on the checks that catch a misconfigured mount: an assetsUrl that does not serve the icons, a config.theme with no brand colours, and a managed-chrome page an ancestor is constraining. Each warns once. strict: true turns the same checks on and additionally prints them to the console.

That makes warn a development channel. Wiring it in production runs the assets probe on every mount, so pass it only where you want the checks:

mount({
container,
page,
config,
logger: { error: (error) => reportToSentry(error) },
strict: import.meta.env.DEV,
});

CorasValidationError carries a stable code, an optional field path, and a redacted message.

import { mount, CorasValidationError } from "@coras-io/embed";
try {
mount({ container, page: "landing", config: { apiUrl: "ftp://x" } as never });
} catch (error) {
if (error instanceof CorasValidationError) {
error.code; // CorasValidationErrorCode, e.g. "invalid_url"
error.field; // "config.apiUrl"
error.message; // safe, human-readable message
}
}
type CorasValidationErrorCode =
| "missing_container"
| "invalid_page"
| "invalid_config"
| "invalid_url"
| "invalid_locale"
| "invalid_currency"
| "invalid_page_params"
| "unknown_key";
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, not an object, or apiUrl / distributorId is missing or not a string
invalid_url apiUrl or assetsUrl fails its URL rules
invalid_locale locale or any allowedLocales entry is unsupported
invalid_currency currency or any allowedCurrencies entry is unsupported
invalid_page_params A page param has the wrong shape (see Page param validation)
unknown_key Strict mode found an unknown key in config or params