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";};Required fields
Section titled “Required fields”apiUrl
Section titled “apiUrl”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";distributorId
Section titled “distributorId”Your distributor identifier. Non-empty string. Missing, empty, or non-string
values throw invalid_config.
distributorId: "your-distributor-id";assetsUrl
Section titled “assetsUrl”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";Optional fields
Section titled “Optional fields”locale
Section titled “locale”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";allowedLocales
Section titled “allowedLocales”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"];currency
Section titled “currency”Active ISO 4217 currency. Casing is normalized, so eur becomes EUR. Must
resolve to a supported currency, or it throws invalid_currency.
currency: "EUR";allowedCurrencies
Section titled “allowedCurrencies”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"];loyaltyPointsEnabled
Section titled “loyaltyPointsEnabled”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.
loyalty
Section titled “loyalty”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" } }colorScheme
Section titled “colorScheme”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";Page param validation
Section titled “Page param validation”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
Section titled “Strict mode”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.
Logging and diagnostics
Section titled “Logging and diagnostics”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,});Validation errors
Section titled “Validation errors”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 }}Error codes
Section titled “Error codes”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 |