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;
  theme?: CorasTheme;
  colorScheme?: "light" | "dark" | "inherit";
};

Required fields

`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`

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

distributorId: "your-distributor-id";

`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"`

Rejected with invalid_url: empty string, 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

`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`

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`

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`

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`

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

loyaltyPointsEnabled: true;

`theme`

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`

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

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

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

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 original error, with its stack, for every failure the SDK also reports through onError. Wire it to your error reporter.

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

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

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`