@coras-io/embed 0.1.0

package/dist/sdk/types.d.ts

@@ -0,0 +1,258 @@
+import type { BrandConfig } from "@coras-io/brand-tokens";
+import type { SupportedCurrencies } from "../core/types/core/currency.js";
+import type { SupportedLocales } from "../core/types/core/locale.js";
+/**
+ * Pages a host can mount through the SDK. This is the public superset of the
+ * internal navigation page set and additionally includes the standalone
+ * `suggestion-widget` (recommendations) embed.
+ */
+export type CorasPageName = "landing" | "search" | "details" | "payment" | "help" | "suggestion-widget";
+export type CorasLandingPageParams = {
+    country?: string;
+    city?: string;
+    startDate?: string;
+    endDate?: string;
+    sort?: string;
+    duration?: string;
+    price?: string;
+    categories?: string;
+};
+export type CorasSearchPageParams = {
+    search?: string;
+    startDate?: string;
+};
+export type CorasDetailsPageParams = {
+    /** Public attraction id (maps to the internal `attraction-id`). */
+    id?: string;
+    date?: string;
+};
+export type CorasPaymentPageParams = {
+    /**
+     * Arbitrary client-defined key/value data forwarded to and stored by the
+     * Coras API, then returned when the order is read back (e.g. a user id,
+     * analytics ids, or a loyalty-card number). Coras does not interpret it.
+     * It is host context, not shareable URL state, so it is not round-tripped
+     * by the `@coras-io/embed/url` helpers.
+     */
+    metadata?: Record<string, string>;
+};
+export type CorasHelpPageParams = {
+    /** Help content identifier, e.g. "faq-attractions", "contact", "privacy-policy". */
+    content?: string;
+};
+export type CorasSuggestionWidgetParams = {
+    limit?: number;
+    showExploreCard?: boolean;
+    country?: string;
+    city?: string;
+};
+export type CorasPageParamsByPage = {
+    landing: CorasLandingPageParams;
+    search: CorasSearchPageParams;
+    details: CorasDetailsPageParams;
+    payment: CorasPaymentPageParams;
+    help: CorasHelpPageParams;
+    "suggestion-widget": CorasSuggestionWidgetParams;
+};
+/** Params for a specific page, or the union when the page is not narrowed. */
+export type CorasPageParams<P extends CorasPageName = CorasPageName> = CorasPageParamsByPage[P];
+/**
+ * The SDK `theme` option is the shared `BrandConfig` contract: un-prefixed
+ * semantic keys (`primary`, `secondary`, …) plus chrome, `logo`, and
+ * `fontFaces`. Defined once in `@coras-io/brand-tokens` and reused by the
+ * microsites, emails, and the Studio.
+ */
+export type CorasTheme = BrandConfig;
+/**
+ * Which colour scheme the mount renders. `theme` carries the light values and
+ * its `dark` block the dark overrides; this picks which side the `light-dark()`
+ * token pairs resolve to.
+ *
+ * - `"light"` (default) — always light, ignoring the host page.
+ * - `"dark"` — always dark.
+ * - `"system"` — follows the OS via `prefers-color-scheme`.
+ * - `"inherit"` — follows the host page's own `color-scheme` (the SDK sets none),
+ *   so the embed behaves like a native element on a light or dark site.
+ */
+export type CorasColorScheme = "light" | "dark" | "system" | "inherit";
+export type CorasConfig = {
+    apiUrl: string;
+    distributorId: string;
+    assetsUrl?: string;
+    locale?: SupportedLocales;
+    allowedLocales?: SupportedLocales[];
+    currency?: SupportedCurrencies;
+    allowedCurrencies?: SupportedCurrencies[];
+    loyaltyPointsEnabled?: boolean;
+    theme?: CorasTheme;
+    colorScheme?: CorasColorScheme;
+};
+/**
+ * Feature toggles for the SDK-created Coras navbar. Each `show*` key maps 1:1 to
+ * a navbar control; an omitted key keeps the navbar's default (everything
+ * shown). Used with `{ use: "managed", props: { … } }`.
+ */
+export type CorasNavbarProps = {
+    /**
+     * Render the minimal search-only navbar (brand + search) instead of the full
+     * bar. This is a mode, not a toggle: when `true` it takes precedence and the
+     * `show*` flags and the `nav`/`actions-start`/`actions-end` slots are ignored.
+     */
+    searchOnly?: boolean;
+    showLanguageSelector?: boolean;
+    showCurrencySelector?: boolean;
+    showBasket?: boolean;
+    showSearch?: boolean;
+};
+/**
+ * Host content-injection points on the Coras navbar. Names describe the region
+ * the host owns, not the internal widget they sit beside, and use logical
+ * `start`/`end` so they stay correct under RTL.
+ *
+ * - `brand`         — logo / home affordance (leading edge)
+ * - `nav`           — primary navigation, after the brand
+ * - `actions-start` — leading edge of the utility cluster, before the basket
+ * - `actions-end`   — trailing edge of the utility cluster, before search
+ * - `search`        — replaces the built-in search (requires `showSearch: false`)
+ */
+export type CorasNavbarSlotName = "brand" | "nav" | "actions-start" | "actions-end" | "search";
+/**
+ * SDK-created navbar with host content projected into its named slots and
+ * optional feature toggles. `slots` maps a slot name to a host element; the SDK
+ * sets that element's `slot` attribute and appends it. A slot with no host
+ * content stays blank.
+ */
+export type CorasManagedNavbar = {
+    use: "managed";
+    slots?: Partial<Record<CorasNavbarSlotName, HTMLElement>>;
+    props?: CorasNavbarProps;
+};
+/** SDK-created footer. The footer exposes no host slots today. */
+export type CorasManagedFooter = {
+    use: "managed";
+};
+export type CorasNavbar = false | "managed" | CorasManagedNavbar | HTMLElement | (() => HTMLElement | Promise<HTMLElement>);
+export type CorasFooter = false | "managed" | CorasManagedFooter | HTMLElement | (() => HTMLElement | Promise<HTMLElement>);
+export type CorasChromeOptions = {
+    navbar?: CorasNavbar;
+    footer?: CorasFooter;
+};
+export type CorasChrome = false | "managed" | CorasChromeOptions;
+export type CorasLogger = {
+    warn?: (message: string, data?: unknown) => void;
+    error?: (error: unknown, data?: unknown) => void;
+};
+/** A per-mount observability event (lifecycle/diagnostic facts). */
+export type CorasObservabilityEvent = {
+    /**
+     * Dot-namespaced, kebab-cased diagnostic name (e.g. `coras.page-loaded`).
+     * The dot namespace and casing deliberately distinguish these telemetry
+     * names from the colon-named `coras:*` host events (e.g. `coras:state-change`).
+     */
+    name: string;
+    page?: CorasPageName;
+    data?: Record<string, string | number | boolean | null | undefined>;
+};
+export type CorasNavigationSource = "embed" | "host";
+export type CorasReadyDetail = {
+    page: CorasPageName;
+};
+export type CorasNavigateDetail = {
+    page: CorasPageName;
+    params?: CorasPageParams;
+    locale?: SupportedLocales;
+    currency?: SupportedCurrencies;
+    href?: string;
+    source: CorasNavigationSource;
+};
+export type CorasStateChangeDetail = {
+    page: CorasPageName;
+    params: CorasPageParams;
+    locale?: SupportedLocales;
+    currency?: SupportedCurrencies;
+};
+export type CorasPaymentStatus = "pending" | "succeeded" | "failed" | "cancelled";
+export type CorasPaymentStatusDetail = {
+    status: CorasPaymentStatus;
+    /** Public reference only; never provider secrets or card data. */
+    reference?: string;
+};
+export type CorasReservationCreatedDetail = {
+    reservationId?: string;
+    expiresIn?: number;
+    ticketDeliveryMethod?: number;
+};
+export type CorasErrorDetail = {
+    /** Stable machine code, e.g. "invalid_page_params". */
+    code: string;
+    /** Safe, redacted, human-readable message. */
+    message: string;
+    page?: CorasPageName;
+};
+/** The host-facing event map: name -> detail. */
+export type CorasHostEventMap = {
+    "coras:ready": CorasReadyDetail;
+    "coras:navigate": CorasNavigateDetail;
+    "coras:state-change": CorasStateChangeDetail;
+    "coras:reservation-created": CorasReservationCreatedDetail;
+    "coras:payment-status": CorasPaymentStatusDetail;
+    "coras:error": CorasErrorDetail;
+};
+export type CorasHostEventName = keyof CorasHostEventMap;
+export type CorasCallbacks = {
+    onReady?: (detail: CorasReadyDetail) => void;
+    onNavigate?: (detail: CorasNavigateDetail) => void;
+    onStateChange?: (detail: CorasStateChangeDetail) => void;
+    onReservationCreated?: (detail: CorasReservationCreatedDetail) => void;
+    onPaymentStatus?: (detail: CorasPaymentStatusDetail) => void;
+    onError?: (detail: CorasErrorDetail) => void;
+    onObservability?: (event: CorasObservabilityEvent) => void;
+};
+export type CorasMountOptions<P extends CorasPageName = CorasPageName> = {
+    container: HTMLElement;
+    page: P;
+    config: CorasConfig;
+    params?: CorasPageParamsByPage[P];
+    chrome?: CorasChrome;
+    logger?: CorasLogger;
+    /** Reject unknown config/param keys instead of ignoring them. */
+    strict?: boolean;
+    /**
+     * Render the page shell without live booking data, for branding and preview
+     * tools (e.g. the Studio). Pages that would otherwise show an empty
+     * or error state when there is nothing to check out instead render their full
+     * form with actions disabled, so the chrome can be styled. Not for production
+     * hosts — a real customer with an empty basket should see the empty state.
+     */
+    preview?: boolean;
+} & CorasCallbacks;
+/** Frozen snapshot of the mount's current public state. */
+export type CorasState = {
+    readonly page: CorasPageName;
+    readonly params: CorasPageParams;
+    readonly locale: SupportedLocales;
+    readonly currency: SupportedCurrencies;
+};
+export type CorasUpdate = {
+    page?: CorasPageName;
+    params?: CorasPageParams;
+    config?: Partial<CorasConfig>;
+    chrome?: CorasChrome;
+};
+export type CorasNavigateOptions = {
+    /** Emit `onNavigate`/`coras:navigate` for this programmatic navigation. */
+    emitNavigate?: boolean;
+};
+export type CorasApp = {
+    readonly ready: Promise<void>;
+    readonly state: CorasState;
+    update(patch: CorasUpdate): void;
+    navigate<P extends CorasPageName>(page: P, params?: CorasPageParamsByPage[P], options?: CorasNavigateOptions): void;
+    prefetch(page: CorasPageName): Promise<void>;
+    unmount(): void;
+};
+export type CorasPageMeta = {
+    page: CorasPageName;
+    /** Internal custom-element tag used to render the page. */
+    tagName: string;
+};

package/dist/sdk/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sdk/url.d.ts

@@ -0,0 +1,47 @@
+import type { SupportedCurrencies } from "../core/types/core/currency.js";
+import type { SupportedLocales } from "../core/types/core/locale.js";
+import type { CorasPageName, CorasPageParams } from "./types.js";
+/**
+ * Framework-neutral URL helpers for host-controlled routing. The host owns the
+ * URL; these helpers translate between a Coras state and a canonical URL so each
+ * framework does not write bespoke parsing glue. See ADR 0013.
+ */
+export type CorasUrlState = {
+    page: CorasPageName;
+    params: CorasPageParams;
+    locale?: SupportedLocales;
+    currency?: SupportedCurrencies;
+};
+export type CorasUrlStrategy = {
+    /** Path prefix, e.g. "" or "/events". No trailing slash. */
+    basePath?: string;
+    /** Put the locale in the path (default true). */
+    localeInPath?: boolean;
+    /** Put the currency in the path (default true). Otherwise it is a query param. */
+    currencyInPath?: boolean;
+    /** Query param name used for currency when not in the path. */
+    currencyParam?: string;
+    /**
+     * Path segment for pages that use a reserved keyword. `landing` has no
+     * segment and `details` is represented by a bare id segment.
+     */
+    reservedSegments?: Partial<Record<CorasPageName, string>>;
+};
+export declare const DEFAULT_URL_STRATEGY: Required<Omit<CorasUrlStrategy, "reservedSegments">> & {
+    reservedSegments: Partial<Record<CorasPageName, string>>;
+};
+/** Parse a (relative or absolute) URL into a Coras state. */
+export declare function parseCorasUrl(url: string, strategy?: CorasUrlStrategy): CorasUrlState;
+/** Build a canonical URL from a Coras state. */
+export declare function buildCorasUrl(state: CorasUrlState, strategy?: CorasUrlStrategy): string;
+/** Normalize locale/currency aliases and ensure a params object. */
+export declare function normalizeCorasUrlState(input: CorasUrlState): CorasUrlState;
+/** Structural comparison used by hosts to skip redundant updates (loop prevention). */
+export declare function isSameCorasUrlState(a: CorasUrlState, b: CorasUrlState): boolean;
+/** Bind the URL helpers to a single strategy. */
+export declare function createCorasUrlState(strategy?: CorasUrlStrategy): {
+    parse: (url: string) => CorasUrlState;
+    build: (state: CorasUrlState) => string;
+    normalize: typeof normalizeCorasUrlState;
+    isSame: typeof isSameCorasUrlState;
+};

package/dist/sdk/url.js

@@ -0,0 +1,199 @@
+import { normalizeCurrency, normalizeLocale, PAGE_PARAM_KEYS, PAGE_PARAM_TYPES, } from "./validation.js";
+const DEFAULT_RESERVED = {
+    search: "search",
+    payment: "payment",
+    help: "help",
+    "suggestion-widget": "widget",
+};
+export const DEFAULT_URL_STRATEGY = {
+    basePath: "",
+    localeInPath: true,
+    currencyInPath: true,
+    currencyParam: "currency",
+    reservedSegments: DEFAULT_RESERVED,
+};
+function resolveStrategy(strategy = {}) {
+    return {
+        ...DEFAULT_URL_STRATEGY,
+        ...strategy,
+        reservedSegments: {
+            ...DEFAULT_RESERVED,
+            ...strategy.reservedSegments,
+        },
+    };
+}
+function reservedToPage(reserved) {
+    const map = new Map();
+    for (const [page, segment] of Object.entries(reserved)) {
+        if (segment)
+            map.set(segment, page);
+    }
+    return map;
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+// Decode a query value into the type `mount()` validation expects. An
+// unparseable value is left as the raw string so validation reports it instead
+// of the helper silently swallowing it.
+function decodeParam(key, value) {
+    const type = PAGE_PARAM_TYPES[key];
+    if (type === "number") {
+        const n = Number(value);
+        return value.trim() !== "" && Number.isFinite(n) ? n : value;
+    }
+    if (type === "boolean") {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+    }
+    return value;
+}
+/** Parse a (relative or absolute) URL into a Coras state. */
+export function parseCorasUrl(url, strategy = {}) {
+    const resolved = resolveStrategy(strategy);
+    const parsed = new URL(url, "http://_/");
+    let path = trimSlashes(parsed.pathname);
+    const base = trimSlashes(resolved.basePath);
+    // Strip basePath only when the path is exactly the base or a proper
+    // descendant of it. Plain `startsWith` would treat `/events-old` as living
+    // under base `/events` and slice off the leading `events`.
+    if (base && (path === base || path.startsWith(`${base}/`))) {
+        path = trimSlashes(path.slice(base.length));
+    }
+    const segments = path ? path.split("/") : [];
+    let index = 0;
+    let locale;
+    const localeSegment = segments[index];
+    if (resolved.localeInPath && localeSegment) {
+        const candidate = normalizeLocale(localeSegment);
+        if (candidate) {
+            locale = candidate;
+            index += 1;
+        }
+    }
+    let currency;
+    const currencySegment = segments[index];
+    if (resolved.currencyInPath && currencySegment) {
+        const candidate = normalizeCurrency(currencySegment);
+        if (candidate) {
+            currency = candidate;
+            index += 1;
+        }
+    }
+    if (!resolved.currencyInPath) {
+        const queryCurrency = parsed.searchParams.get(resolved.currencyParam);
+        if (queryCurrency)
+            currency = normalizeCurrency(queryCurrency) ?? undefined;
+    }
+    const reservedMap = reservedToPage(resolved.reservedSegments);
+    const pageSegment = segments[index];
+    let page = "landing";
+    const params = {};
+    if (pageSegment) {
+        const reservedPage = reservedMap.get(pageSegment);
+        if (reservedPage) {
+            page = reservedPage;
+        }
+        else {
+            page = "details";
+            params.id = pageSegment;
+        }
+    }
+    // Page-specific params come from the query string.
+    const allowed = PAGE_PARAM_KEYS[page];
+    for (const key of allowed) {
+        if (key === "id")
+            continue; // details id is the path segment
+        if (key === "metadata")
+            continue; // host context, not URL state
+        const value = parsed.searchParams.get(key);
+        if (value != null)
+            params[key] = decodeParam(key, value);
+    }
+    return {
+        page,
+        params: params,
+        ...(locale ? { locale } : {}),
+        ...(currency ? { currency } : {}),
+    };
+}
+/** Build a canonical URL from a Coras state. */
+export function buildCorasUrl(state, strategy = {}) {
+    const resolved = resolveStrategy(strategy);
+    const segments = [];
+    const base = trimSlashes(resolved.basePath);
+    if (base)
+        segments.push(base);
+    if (resolved.localeInPath && state.locale)
+        segments.push(state.locale);
+    if (resolved.currencyInPath && state.currency)
+        segments.push(state.currency);
+    const params = (state.params ?? {});
+    if (state.page === "details") {
+        if (params.id != null)
+            segments.push(String(params.id));
+    }
+    else {
+        const reserved = resolved.reservedSegments[state.page];
+        if (reserved)
+            segments.push(reserved);
+    }
+    const query = new URLSearchParams();
+    const allowed = PAGE_PARAM_KEYS[state.page];
+    for (const key of allowed) {
+        if (key === "id")
+            continue;
+        if (key === "metadata")
+            continue; // host context, not URL state
+        const value = params[key];
+        if (value != null && value !== "")
+            query.set(key, String(value));
+    }
+    if (!resolved.currencyInPath && state.currency) {
+        query.set(resolved.currencyParam, state.currency);
+    }
+    const path = `/${segments.join("/")}`.replace(/\/+/g, "/");
+    const queryString = query.toString();
+    return queryString ? `${path}?${queryString}` : path;
+}
+/** Normalize locale/currency aliases and ensure a params object. */
+export function normalizeCorasUrlState(input) {
+    return {
+        page: input.page,
+        params: (input.params ?? {}),
+        ...(input.locale
+            ? { locale: normalizeLocale(input.locale) ?? input.locale }
+            : {}),
+        ...(input.currency
+            ? { currency: normalizeCurrency(input.currency) ?? input.currency }
+            : {}),
+    };
+}
+/** Structural comparison used by hosts to skip redundant updates (loop prevention). */
+export function isSameCorasUrlState(a, b) {
+    if (a.page !== b.page)
+        return false;
+    if (a.locale !== b.locale)
+        return false;
+    if (a.currency !== b.currency)
+        return false;
+    const aParams = (a.params ?? {});
+    const bParams = (b.params ?? {});
+    const keys = new Set([...Object.keys(aParams), ...Object.keys(bParams)]);
+    for (const key of keys) {
+        if (aParams[key] !== bParams[key])
+            return false;
+    }
+    return true;
+}
+/** Bind the URL helpers to a single strategy. */
+export function createCorasUrlState(strategy = {}) {
+    return {
+        parse: (url) => parseCorasUrl(url, strategy),
+        build: (state) => buildCorasUrl(state, strategy),
+        normalize: normalizeCorasUrlState,
+        isSame: isSameCorasUrlState,
+    };
+}

package/dist/sdk/validation.d.ts

@@ -0,0 +1,50 @@
+import type { SupportedCurrencies } from "../core/types/core/currency.js";
+import type { SupportedLocales } from "../core/types/core/locale.js";
+import type { CorasConfig, CorasMountOptions, CorasPageName } from "./types.js";
+export type CorasValidationErrorCode = "missing_container" | "invalid_page" | "invalid_config" | "invalid_url" | "invalid_locale" | "invalid_currency" | "invalid_color_scheme" | "invalid_theme" | "invalid_page_params" | "unknown_key";
+/**
+ * A typed, redacted validation error thrown for invalid host input before any
+ * element is rendered or updated. Messages are safe to surface to the host.
+ */
+export declare class CorasValidationError extends Error {
+    readonly code: CorasValidationErrorCode;
+    readonly field?: string;
+    constructor(code: CorasValidationErrorCode, message: string, field?: string);
+}
+export declare const PUBLIC_PAGES: readonly CorasPageName[];
+/**
+ * Reject a page name outside the public set with a typed error. Shared by mount,
+ * update, navigate and prefetch so every entry point fails the same way — and
+ * before any state is mutated — instead of indexing the registry with an unknown
+ * page and throwing a bare TypeError.
+ */
+export declare function assertValidPage(page: unknown): asserts page is CorasPageName;
+/** Allowed param keys per page (public names). */
+export declare const PAGE_PARAM_KEYS: Record<CorasPageName, readonly string[]>;
+/**
+ * URL params whose string form decodes to a non-string type. Everything not
+ * listed stays a string. Used by the URL helpers so a value round-trips through
+ * a URL as the type `mount()` validation expects (e.g. `limit=3` -> `3`, not
+ * `"3"`; `showExploreCard=false` -> `false`, not a truthy `"false"`).
+ */
+export declare const PAGE_PARAM_TYPES: Readonly<Record<string, "number" | "boolean">>;
+/** Normalize locale casing/separators (e.g. `en_ie`, `EN-IE` -> `en-IE`). */
+export declare function normalizeLocale(value: string): SupportedLocales | undefined;
+/** Normalize currency casing (e.g. `eur` -> `EUR`). */
+export declare function normalizeCurrency(value: string): SupportedCurrencies | undefined;
+/**
+ * Require an https URL (http allowed only for localhost dev). Returns the
+ * parsed origin-safe href, or throws.
+ */
+export declare function assertSecureUrl(value: string, field: string): string;
+export type ValidatedMount = {
+    page: CorasPageName;
+    config: CorasConfig;
+    params: Record<string, unknown>;
+};
+export declare function validateConfig(config: CorasConfig, strict: boolean): CorasConfig;
+export declare function validatePageParams(page: CorasPageName, params: Record<string, unknown> | undefined, strict: boolean): Record<string, unknown>;
+/**
+ * Validate and normalize the full mount options before anything is rendered.
+ */
+export declare function validateMountOptions(options: CorasMountOptions): ValidatedMount;