@sitecore-content-sdk/content 1.5.0-canary.5

package/dist/cjs/client/sitecore-client.js

@@ -0,0 +1,420 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SitecoreClient = exports.ErrorPage = void 0;
+const core_1 = require("@sitecore-content-sdk/core");
+const i18n_1 = require("../i18n");
+const layout_1 = require("../layout");
+const utils_1 = require("../personalize/utils");
+const layout_personalizer_1 = require("../personalize/layout-personalizer");
+const site_1 = require("../site");
+const utils_2 = require("./utils");
+const robots_service_1 = require("../site/robots-service");
+const models_1 = require("../editing/models");
+const editing_1 = require("../editing");
+/**
+ * Error page codes
+ * @public
+ */
+var ErrorPage;
+(function (ErrorPage) {
+    ErrorPage["NotFound"] = "404";
+    ErrorPage["InternalServerError"] = "500";
+})(ErrorPage || (exports.ErrorPage = ErrorPage = {}));
+/**
+ * This is a generic content client that can be used by any framework.
+ * Use it to retrieve pages, preview data, dictionary and other data
+ * @public
+ */
+class SitecoreClient {
+    /**
+     * Init SitecoreClient
+     * @param {SitecoreClientInit} initOptions initOptions for the client, containing site and Sitecore connection details
+     */
+    constructor(initOptions) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        this.initOptions = initOptions;
+        this.clientFactory = this.getClientFactory();
+        this.graphQLClient = this.clientFactory({
+            debugger: core_1.debug.http,
+        });
+        const baseServiceOptions = this.getBaseServiceOptions();
+        this.layoutService =
+            (_b = (_a = initOptions.custom) === null || _a === void 0 ? void 0 : _a.layoutService) !== null && _b !== void 0 ? _b : this.getLayoutService(baseServiceOptions);
+        this.dictionaryService =
+            (_d = (_c = initOptions.custom) === null || _c === void 0 ? void 0 : _c.dictionaryService) !== null && _d !== void 0 ? _d : this.getDictionaryService(baseServiceOptions);
+        this.editingService = (_f = (_e = initOptions.custom) === null || _e === void 0 ? void 0 : _e.editingService) !== null && _f !== void 0 ? _f : this.getEditingService();
+        this.errorPagesService = (_h = (_g = initOptions.custom) === null || _g === void 0 ? void 0 : _g.errorPagesService) !== null && _h !== void 0 ? _h : this.getErrorPagesService();
+        this.sitePathService = (_k = (_j = initOptions.custom) === null || _j === void 0 ? void 0 : _j.sitePathService) !== null && _k !== void 0 ? _k : this.getSitePathService();
+        this.componentService = this.getComponentService();
+    }
+    /**
+     * Normalize path regardless of type
+     * @param {string | string[]} path string or string array path
+     * @returns {string} string path
+     */
+    parsePath(path) {
+        // join array path, while clearing extra slashes and ensure first slash
+        return typeof path === 'string'
+            ? path.startsWith('/')
+                ? path
+                : `/${path}`
+            : `/${path
+                .filter((part) => part !== '/')
+                .map((part) => part.replace(/^\/+/, '').replace(/\/+$/, ''))
+                .join('/')}`;
+    }
+    /**
+     * Execute a raw GraphQL request using the client's configured GraphQL Edge endpoint.
+     * This is a thin pass-through to the underlying `GraphQLClient.request` method,
+     * @param {string | DocumentNode} query GraphQL query
+     * @param {Record<string, unknown>} [variables] Optional variables bag
+     * @param {FetchOptions} [fetchOptions] Optional fetch overrides (e.g. fetch, headers)
+     */
+    getData(query, variables, fetchOptions) {
+        return this.graphQLClient.request(query, variables, fetchOptions);
+    }
+    /**
+     * Get page details for a route, with layout and other details
+     * @param {string} path route path
+     * @param {PageOptions} [pageOptions] site, language and personalization variant details for route
+     * @param {FetchOptions} [fetchOptions] Additional fetch fetch options to override GraphQL requests
+     * @returns {Page | null} page details
+     */
+    async getPage(path, pageOptions, fetchOptions) {
+        var _a, _b, _c, _d;
+        const computedPath = this.parsePath(path);
+        const locale = (_a = pageOptions === null || pageOptions === void 0 ? void 0 : pageOptions.locale) !== null && _a !== void 0 ? _a : this.initOptions.defaultLanguage;
+        const site = (_b = pageOptions === null || pageOptions === void 0 ? void 0 : pageOptions.site) !== null && _b !== void 0 ? _b : this.initOptions.defaultSite;
+        // Fetch layout data, passing on req/res for SSR
+        const layout = await this.layoutService.fetchLayoutData(computedPath, {
+            locale,
+            site,
+        }, fetchOptions);
+        if (!layout.sitecore.route) {
+            return null;
+        }
+        else {
+            // Initialize links to be inserted on the page
+            if ((_c = pageOptions === null || pageOptions === void 0 ? void 0 : pageOptions.personalize) === null || _c === void 0 ? void 0 : _c.variantId) {
+                // Modify layoutData to use specific variant(s) instead of default
+                // This will also set the variantId on the Sitecore context so that it is accessible here
+                (0, layout_personalizer_1.personalizeLayout)(layout, pageOptions.personalize.variantId, pageOptions.personalize.componentVariantIds);
+            }
+            return {
+                layout,
+                siteName: ((_d = layout.sitecore.context.site) === null || _d === void 0 ? void 0 : _d.name) || site,
+                locale,
+                mode: this.getPageMode(layout_1.LayoutServicePageState.Normal),
+            };
+        }
+    }
+    /**
+     * Retrieves the head `<link>` elements for Sitecore styles and themes.
+     * @param {LayoutServiceData} layoutData - The layout data containing styles and themes.
+     * @param {object} [options] - Optional configuration for enabling styles and themes.
+     * @param {boolean} [options.enableStyles] - Whether to include content styles.
+     * @param {boolean} [options.enableThemes] - Whether to include theme styles.
+     * @returns {HTMLLink[]} An array of `<link>` elements for stylesheets.
+     */
+    getHeadLinks(layoutData, options = {}) {
+        const { enableStyles = true, enableThemes = true } = options;
+        const { contextId: serverContextId, clientContextId, edgeUrl } = this.initOptions.api.edge;
+        const headLinks = [];
+        const contextId = serverContextId || clientContextId;
+        if (enableStyles) {
+            const contentStyles = (0, layout_1.getContentStylesheetLink)(layoutData, contextId, edgeUrl);
+            if (contentStyles)
+                headLinks.push(contentStyles);
+        }
+        if (enableThemes) {
+            headLinks.push(...(0, layout_1.getDesignLibraryStylesheetLinks)(layoutData, contextId, edgeUrl));
+        }
+        return headLinks;
+    }
+    /**
+     * Retrieves dictionary phrases for a given site and locale.
+     * @param {RouteOptions} routeOptions - Route options containing language and site name to load dictionary for
+     * @param {FetchOptions} [fetchOptions] Additional fetch fetch options to override GraphQL requests
+     * @returns {DictionaryPhrases} A promise that resolves to the dictionary phrases.
+     */
+    async getDictionary(routeOptions, fetchOptions) {
+        const locale = (routeOptions === null || routeOptions === void 0 ? void 0 : routeOptions.locale) || this.initOptions.defaultLanguage;
+        const site = (routeOptions === null || routeOptions === void 0 ? void 0 : routeOptions.site) || this.initOptions.defaultSite;
+        return await this.dictionaryService.fetchDictionaryData(locale, site, fetchOptions);
+    }
+    /**
+     * Retrieves error pages for a given site and locale.
+     * @param {RouteOptions} routeOptions - Route options containing language and site name to load error pages
+     * @param {FetchOptions} [fetchOptions] Additional fetch fetch options to override GraphQL requests
+     * @returns {ErrorPages | null} A promise that resolves to the error pages or null if not found.
+     */
+    async getErrorPages(routeOptions, fetchOptions) {
+        const locale = (routeOptions === null || routeOptions === void 0 ? void 0 : routeOptions.locale) || this.initOptions.defaultLanguage;
+        const site = (routeOptions === null || routeOptions === void 0 ? void 0 : routeOptions.site) || this.initOptions.defaultSite;
+        return await this.errorPagesService.fetchErrorPages(site, locale, fetchOptions);
+    }
+    /**
+     * Retrieves preview page and layout details
+     * @param {EditingPreviewData | undefined} previewData - The editing preview data for metadata mode.
+     * @param {FetchOptions} [fetchOptions] Additional fetch fetch options to override GraphQL requests
+     * @returns {Page} preview page details
+     */
+    async getPreview(previewData, fetchOptions) {
+        var _a;
+        if (!previewData) {
+            console.error('Preview data missing');
+            return null;
+        }
+        // If we're in Pages preview (editing) mode, prefetch the editing data
+        const { site, itemId, language, version, layoutKind, mode } = previewData;
+        const variantIds = Array.isArray(previewData.variantIds)
+            ? previewData.variantIds
+            : previewData.variantIds.split(',');
+        const data = await this.editingService.fetchEditingData({
+            itemId,
+            language,
+            version,
+            layoutKind,
+            mode,
+        }, fetchOptions);
+        if (!data) {
+            throw new Error(`Unable to fetch editing data for preview ${JSON.stringify(previewData)}`);
+        }
+        const page = {
+            locale: language,
+            layout: data.layoutData,
+            siteName: ((_a = data.layoutData.sitecore.context.site) === null || _a === void 0 ? void 0 : _a.name) || site,
+            mode: this.getPageMode(mode),
+        };
+        const personalizeData = (0, utils_1.getGroomedVariantIds)(variantIds);
+        (0, layout_personalizer_1.personalizeLayout)(page.layout, personalizeData.variantId, personalizeData.componentVariantIds);
+        return page;
+    }
+    /**
+     * Get design library page details for Design Library mode of your app
+     * @param {DesignLibraryRenderPreviewData} designLibData preview data set in 'library' mode of the app
+     * @param {FetchOptions} [fetchOptions] Additional fetch fetch options to override GraphQL requests
+     * @returns {Page} preview page for Design Library
+     */
+    async getDesignLibraryData(designLibData, fetchOptions) {
+        var _a;
+        if (!this.initOptions.api.local) {
+            throw new Error('Component Library requires Sitecore apiHost and apiKey to be provided');
+        }
+        const { itemId, componentUid, site, language, renderingId, dataSourceId, version, mode, generation, } = designLibData;
+        const componentData = await this.componentService.fetchComponentData(Object.assign({ siteName: site, itemId,
+            language,
+            componentUid,
+            renderingId,
+            dataSourceId,
+            version,
+            mode }, (generation ? { generation } : {})), fetchOptions);
+        if (!componentData) {
+            throw new Error(`Unable to fetch editing data for preview ${JSON.stringify(designLibData)}`);
+        }
+        const page = {
+            locale: designLibData.language,
+            layout: componentData,
+            siteName: ((_a = componentData.sitecore.context.site) === null || _a === void 0 ? void 0 : _a.name) || site,
+            mode: this.getPageMode(mode, generation),
+        };
+        return page;
+    }
+    /**
+     * Get error page details for a given error code
+     * @param {ErrorPage} code - The error code to get the error page for
+     * @param {Partial<RouteOptions>} pageOptions - The page options to get the error page for
+     * @param {FetchOptions} [fetchOptions] - Additional fetch fetch options to override GraphQL requests
+     * @returns {Promise<Page | null>} A promise that resolves to the error page details or null if not found
+     */
+    async getErrorPage(code, pageOptions, fetchOptions) {
+        var _a, _b;
+        const locale = (pageOptions === null || pageOptions === void 0 ? void 0 : pageOptions.locale) || this.initOptions.defaultLanguage;
+        const site = (pageOptions === null || pageOptions === void 0 ? void 0 : pageOptions.site) || this.initOptions.defaultSite;
+        const result = await this.getErrorPages({
+            site,
+            locale,
+        }, fetchOptions);
+        let layout = null;
+        switch (code) {
+            case ErrorPage.NotFound:
+                layout = ((_a = result === null || result === void 0 ? void 0 : result.notFoundPage) === null || _a === void 0 ? void 0 : _a.rendered) || null;
+                break;
+            case ErrorPage.InternalServerError:
+                layout = ((_b = result === null || result === void 0 ? void 0 : result.serverErrorPage) === null || _b === void 0 ? void 0 : _b.rendered) || null;
+                break;
+            default:
+                return null;
+        }
+        if (!layout) {
+            return null;
+        }
+        return {
+            layout,
+            locale,
+            mode: this.getPageMode(layout_1.LayoutServicePageState.Normal),
+            siteName: site,
+        };
+    }
+    /**
+     * Retrieves the static paths for pages based on the given languages.
+     * @param {string[]} sites - An array of site names to fetch routes for.
+     * @param {string[]} [languages] - An optional array of language codes to generate paths for.
+     * @param {FetchOptions} [fetchOptions] - Additional fetch options.
+     * @returns {Promise<StaticPath[]>} A promise that resolves to an array of static paths.
+     */
+    async getPagePaths(sites, languages, fetchOptions) {
+        return this.sitePathService.fetchSiteRoutes(sites, languages || [], fetchOptions);
+    }
+    /**
+     * Retrieves sitemap XML content - either a specific sitemap or the index of all sitemaps.
+     * @param {SitemapXmlOptions} reqOptions - Options for sitemap retrieval
+     * @param {FetchOptions} [fetchOptions] - Additional fetch options.
+     * @returns {Promise<string>} Promise resolving to the sitemap XML content as string
+     * @throws {Error} Throws 'REDIRECT_404' if requested sitemap is not found
+     */
+    async getSiteMap(reqOptions, fetchOptions) {
+        const { reqHost, reqProtocol, id, siteName } = reqOptions;
+        // create sitemap graphql service
+        const sitemapXmlService = this.getGraphqlSitemapXMLService(siteName || this.initOptions.defaultSite);
+        // The id is present if url has sitemap-{n}.xml type.
+        // The id can be null if it's index sitemap.xml request
+        const sitemapPath = await sitemapXmlService.getSitemap(id);
+        // regular sitemap
+        if (sitemapPath) {
+            try {
+                const fetcher = new core_1.NativeDataFetcher();
+                const xmlResponse = await fetcher.fetch(sitemapPath);
+                if (!xmlResponse.data) {
+                    throw new Error('REDIRECT_404');
+                }
+                return xmlResponse.data;
+                // eslint-disable-next-line no-unused-vars
+            }
+            catch (error) {
+                throw new Error('REDIRECT_404');
+            }
+        }
+        // index /sitemap.xml that includes links to all sitemaps
+        const sitemaps = await sitemapXmlService.fetchSitemaps(fetchOptions);
+        if (!sitemaps.length) {
+            throw new Error('REDIRECT_404');
+        }
+        return `<?xml version="1.0" encoding="UTF-8"?>
+      <sitemapindex xmlns="http://sitemaps.org/schemas/sitemap/0.9">
+      ${sitemaps
+            .map((item) => {
+            const parseUrl = item.split('/');
+            const lastSegment = parseUrl[parseUrl.length - 1];
+            const escapedUrl = `${reqProtocol}://${reqHost}/${lastSegment}`.replace(/&/g, '&amp;');
+            return `<sitemap><loc>${escapedUrl}</loc></sitemap>`;
+        })
+            .join('')}
+      </sitemapindex>`;
+    }
+    /**
+     * Retrieves the robots.txt content for a given site name.
+     * @param {string} siteName - The name of the site to retrieve the robots.txt for.
+     * @param {FetchOptions} [fetchOptions] - Optional fetch options.
+     * @returns {Promise<string | null>} A promise that resolves to the robots.txt content,
+     * or null if no content is found.
+     */
+    async getRobots(siteName, fetchOptions) {
+        const robotsService = this.getRobotsService(siteName || this.initOptions.defaultSite);
+        const content = await robotsService.fetchRobots(fetchOptions);
+        return content || null;
+    }
+    /**
+     * Factory methods for creating dependencies
+     * Subclasses can override these to provide custom implementations.
+     */
+    getGraphqlSitemapXMLService(siteName) {
+        return new site_1.SitemapXmlService({
+            clientFactory: this.clientFactory,
+            siteName,
+        });
+    }
+    getRobotsService(siteName) {
+        return new robots_service_1.RobotsService({
+            clientFactory: this.clientFactory,
+            siteName,
+        });
+    }
+    getBaseServiceOptions() {
+        return {
+            defaultSite: this.initOptions.defaultSite,
+            clientFactory: this.clientFactory,
+            retries: this.initOptions.retries,
+        };
+    }
+    /**
+     * Get page mode based on mode name
+     * @param {PageModeName} mode - The mode name to get the page mode for
+     * @param { DesignLibraryVariantGeneration} generation - The variant generation mode, if applicable
+     * @returns {PageMode} The page mode
+     */
+    getPageMode(mode, generation) {
+        const pageMode = {
+            name: mode,
+            isNormal: false,
+            isPreview: false,
+            isEditing: false,
+            isDesignLibrary: false,
+            designLibrary: { isVariantGeneration: false },
+        };
+        switch (mode) {
+            case layout_1.LayoutServicePageState.Normal:
+                pageMode.isNormal = true;
+                break;
+            case layout_1.LayoutServicePageState.Preview:
+                pageMode.isPreview = true;
+                break;
+            case layout_1.LayoutServicePageState.Edit:
+                pageMode.isEditing = true;
+                break;
+            case editing_1.DesignLibraryMode.Normal:
+                pageMode.isDesignLibrary = true;
+                break;
+            case editing_1.DesignLibraryMode.Metadata:
+                pageMode.isDesignLibrary = true;
+                pageMode.isEditing = true;
+                break;
+            default:
+                break;
+        }
+        if (pageMode.isDesignLibrary && generation === models_1.DesignLibraryVariantGeneration.Variant) {
+            pageMode.designLibrary.isVariantGeneration = true;
+            pageMode.isEditing = true;
+        }
+        return pageMode;
+    }
+    getClientFactory() {
+        const graphQLOptions = {
+            api: this.initOptions.api,
+            retries: this.initOptions.retries.count,
+            retryStrategy: this.initOptions.retries.retryStrategy,
+        };
+        return (0, utils_2.createGraphQLClientFactory)(graphQLOptions);
+    }
+    getLayoutService(baseOptions) {
+        return new layout_1.LayoutService(Object.assign(Object.assign({}, baseOptions), { formatLayoutQuery: this.initOptions.layout.formatLayoutQuery }));
+    }
+    getDictionaryService(baseOptions) {
+        return new i18n_1.DictionaryService(Object.assign(Object.assign({}, baseOptions), { cacheEnabled: this.initOptions.dictionary.caching.enabled, cacheTimeout: this.initOptions.dictionary.caching.timeout }));
+    }
+    getEditingService() {
+        return new editing_1.EditingService({ clientFactory: this.clientFactory });
+    }
+    getErrorPagesService() {
+        return new site_1.ErrorPagesService(Object.assign(Object.assign({}, this.initOptions), { language: this.initOptions.defaultLanguage, clientFactory: this.clientFactory }));
+    }
+    getComponentService() {
+        return new editing_1.ComponentLayoutService(this.initOptions.api.edge);
+    }
+    getSitePathService() {
+        return new site_1.SitePathService({
+            clientFactory: this.clientFactory,
+        });
+    }
+}
+exports.SitecoreClient = SitecoreClient;

package/dist/cjs/client/utils.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGraphQLClientFactory = void 0;
+const core_1 = require("@sitecore-content-sdk/core");
+const edge_proxy_1 = require("./edge-proxy");
+/**
+ * Creates a new GraphQLRequestClientFactory instance
+ * @param {GraphQLClientOptions} options content sdk config
+ * @returns GraphQLRequestClientFactory instance
+ * @public
+ */
+const createGraphQLClientFactory = (options) => {
+    let clientConfig;
+    const { api } = options;
+    const { edge, local } = api !== null && api !== void 0 ? api : {};
+    const isBrowser = typeof window !== 'undefined';
+    if (edge === null || edge === void 0 ? void 0 : edge.contextId) {
+        // Real client for server-side rendering / API routes
+        clientConfig = {
+            endpoint: (0, edge_proxy_1.getEdgeProxyContentUrl)(edge.edgeUrl),
+            contextId: edge.contextId,
+        };
+    }
+    else if (isBrowser && (edge === null || edge === void 0 ? void 0 : edge.clientContextId)) {
+        // Real client for client-side requests
+        clientConfig = {
+            endpoint: (0, edge_proxy_1.getEdgeProxyContentUrl)(edge.edgeUrl),
+            contextId: edge.clientContextId,
+        };
+    }
+    else if ((local === null || local === void 0 ? void 0 : local.apiKey) && (local === null || local === void 0 ? void 0 : local.apiHost)) {
+        // Fallback to local API settings
+        clientConfig = {
+            endpoint: `${local.apiHost}${local.path}`,
+            apiKey: local.apiKey,
+        };
+    }
+    else if (isBrowser) {
+        // Browser bundle has no IDs – initialise a dummy client and warn
+        /* eslint-disable no-console */
+        console.warn('GraphQL client initialised in the browser without Edge or local API configuration; client-side requests may fail.');
+        clientConfig = { endpoint: '/api/graphql' };
+    }
+    else {
+        throw new Error(`GraphQL client misconfigured.
+      Configure one of the following in sitecore.config or your .env file:
+      Edge mode: set both sitecore.edge.contextId (server-side) and sitecore.edge.clientContextId (browser).
+      Local API mode: set api.local.apiHost and api.local.apiKey.
+      Supplying only api.edge.clientContextId will cause the application to fail at runtime.`);
+    }
+    return core_1.GraphQLRequestClient.createClientFactory(Object.assign(Object.assign({}, clientConfig), options));
+};
+exports.createGraphQLClientFactory = createGraphQLClientFactory;

package/dist/cjs/config/define-config.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = exports.getFallbackConfig = void 0;
+exports.deepMerge = deepMerge;
+const core_1 = require("@sitecore-content-sdk/core");
+const config_cli_1 = require("../config-cli");
+const { SITECORE_EDGE_URL_DEFAULT } = core_1.constants;
+/**
+ * Provides default initial values for SitecoreConfig
+ * @returns default config
+ */
+const getFallbackConfig = () => ({
+    api: {
+        edge: {
+            contextId: process.env.SITECORE_EDGE_CONTEXT_ID || '',
+            clientContextId: '',
+            edgeUrl: process.env.SITECORE_EDGE_URL || SITECORE_EDGE_URL_DEFAULT,
+        },
+        local: {
+            apiKey: process.env.SITECORE_API_KEY || process.env.NEXT_PUBLIC_SITECORE_API_KEY || '',
+            apiHost: process.env.SITECORE_API_HOST || process.env.NEXT_PUBLIC_SITECORE_API_HOST || '',
+            path: '/sitecore/api/graph/edge',
+        },
+    },
+    editingSecret: process.env.SITECORE_EDITING_SECRET || 'editing-secret-missing',
+    retries: {
+        count: 3,
+        retryStrategy: new core_1.DefaultRetryStrategy({
+            statusCodes: [429, 502, 503, 504, 520, 521, 522, 523, 524],
+        }),
+    },
+    redirects: {
+        enabled: process.env.NODE_ENV !== 'development',
+        locales: ['en'],
+    },
+    multisite: {
+        enabled: true,
+        useCookieResolution: () => false,
+    },
+    personalize: {
+        enabled: process.env.NODE_ENV !== 'development',
+        edgeTimeout: parseInt(process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT, 10) || 400,
+        cdpTimeout: parseInt(process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT, 10) || 400,
+        scope: '',
+        channel: 'WEB',
+        currency: 'USD',
+    },
+    defaultSite: '',
+    defaultLanguage: 'en',
+    layout: {
+        formatLayoutQuery: null,
+    },
+    dictionary: {
+        caching: {
+            enabled: true,
+            timeout: 60,
+        },
+    },
+    disableCodeGeneration: false,
+});
+exports.getFallbackConfig = getFallbackConfig;
+/**
+ * Deep merge utility that skips undefined or empty string values in the override.
+ * @param {T} base base value
+ * @param {DeepPartial<T>} [override] override value
+ */
+function deepMerge(base, override) {
+    if (!override)
+        return base;
+    const result = Object.assign({}, base);
+    for (const key in override) {
+        if (!Object.prototype.hasOwnProperty.call(override, key))
+            continue;
+        const typedKey = key;
+        const baseValue = base[typedKey];
+        const overrideValue = override[typedKey];
+        // Skip undefined and empty string overrides
+        if (overrideValue === undefined || overrideValue === '') {
+            continue;
+        }
+        if (typeof overrideValue === 'object' &&
+            overrideValue !== null &&
+            !Array.isArray(overrideValue) &&
+            Object.getPrototypeOf(overrideValue) === Object.prototype) {
+            result[typedKey] = deepMerge(baseValue, overrideValue);
+        }
+        else {
+            result[typedKey] = overrideValue;
+        }
+    }
+    return result;
+}
+/**
+ * Resolves sitecore config based on base config and overrides
+ * @param {SitecoreConfig} base base sitecore config object
+ * @param {SitecoreConfig} override override sitecore config object
+ * @returns resolved SitecoreConfig object
+ */
+const resolveConfig = (base, override) => {
+    const result = deepMerge(base, override);
+    if (Number.isNaN(result.personalize.cdpTimeout) || !result.personalize.cdpTimeout) {
+        result.personalize.cdpTimeout = base.personalize.cdpTimeout;
+    }
+    if (Number.isNaN(result.personalize.edgeTimeout) || !result.personalize.edgeTimeout) {
+        result.personalize.edgeTimeout = base.personalize.edgeTimeout;
+    }
+    return result;
+};
+const validateApiConfiguration = (config) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const isBrowser = typeof window !== 'undefined';
+    const hasEdgeContextId = !!((_b = (_a = config.api) === null || _a === void 0 ? void 0 : _a.edge) === null || _b === void 0 ? void 0 : _b.contextId);
+    const hasClientContextId = !!((_d = (_c = config.api) === null || _c === void 0 ? void 0 : _c.edge) === null || _d === void 0 ? void 0 : _d.clientContextId);
+    const hasLocalCreds = !!((_f = (_e = config.api) === null || _e === void 0 ? void 0 : _e.local) === null || _f === void 0 ? void 0 : _f.apiHost) && !!((_h = (_g = config.api) === null || _g === void 0 ? void 0 : _g.local) === null || _h === void 0 ? void 0 : _h.apiKey);
+    // Server-side: allow Edge OR Local; clientContextId alone is NOT sufficient
+    if (!isBrowser) {
+        if (!hasEdgeContextId && !hasLocalCreds) {
+            throw new Error('Configuration error: provide either Edge contextId (api.edge.contextId) or local credentials (api.local.apiHost + api.local.apiKey).');
+        }
+        if (hasEdgeContextId && !hasClientContextId) {
+            // eslint-disable-next-line no-console
+            if (process.env.NODE_ENV === 'development') {
+                console.warn('Warning: only a server-side edge contextId is provided. Client-side requests will require api.edge.clientContextId or a proxy.');
+            }
+        }
+        return; // validation complete on the server
+    }
+    // Browser-side warning (runs only if contextId exists but clientContextId is missing)
+    if (isBrowser && !hasClientContextId) {
+        // eslint-disable-next-line no-console
+        if (process.env.NODE_ENV === 'development') {
+            console.warn(`Warning: clientContextId is missing. The browser will use contextId instead.
+  Client Side functionalities (like Tracking and Personalization) may be limited.`);
+        }
+    }
+};
+/**
+ * The validators for the config object during build time.
+ * Validators are called when the literal path of the config object is accessed.
+ */
+const PROPERTY_VALIDATORS = {
+    'api.edge.contextId': validateApiConfiguration,
+    'api.local.apiKey': validateApiConfiguration,
+};
+/**
+ * Creates a proxy for the config object to validate the config object during build time.
+ * @param {SitecoreConfig} config - The config object to create a proxy for.
+ * @returns {SitecoreConfig} The proxy for the config object.
+ */
+const createConfigProxy = (config) => {
+    const validated = new Set();
+    const createProxy = (target, propPath = '') => {
+        return new Proxy(target, {
+            get(obj, prop, receiver) {
+                // Skip symbol properties, do not attempt to stringify them
+                // Type safety check
+                if (typeof prop === 'symbol') {
+                    return Reflect.get(obj, prop, receiver);
+                }
+                const fullPath = propPath ? `${propPath}.${prop}` : prop;
+                const value = Reflect.get(obj, prop, receiver);
+                if (fullPath in PROPERTY_VALIDATORS &&
+                    !validated.has(fullPath)) {
+                    const validator = PROPERTY_VALIDATORS[fullPath];
+                    validator(config);
+                    validated.add(fullPath);
+                }
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    return createProxy(value, fullPath);
+                }
+                return value;
+            },
+        });
+    };
+    return createProxy(config);
+};
+/**
+ * Accepts a SitecoreConfigInput object and returns full sitecore configuration
+ * @param {SitecoreConfigInput} config override values to be written over default config settings
+ * @returns {SitecoreConfig} full sitecore configuration to use in application
+ * @public
+ */
+const defineConfig = (config) => {
+    const resolvedConfig = resolveConfig((0, exports.getFallbackConfig)(), config);
+    const isCLI = process.env[config_cli_1.SITECORE_CLI_MODE_ENV_VAR] === 'true';
+    // At `build time`, we create a proxy for the config object to validate the config by
+    // accessing the literal paths instead of validating the whole object at once.
+    // At `runtime` all the config should be validated to fail fast in case of invalid configuration.
+    if (isCLI) {
+        return createConfigProxy(resolvedConfig);
+    }
+    validateApiConfiguration(resolvedConfig);
+    return resolvedConfig;
+};
+exports.defineConfig = defineConfig;

package/dist/cjs/config/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = exports.ComponentTemplateType = void 0;
+var models_1 = require("./models");
+Object.defineProperty(exports, "ComponentTemplateType", { enumerable: true, get: function () { return models_1.ComponentTemplateType; } });
+var define_config_1 = require("./define-config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return define_config_1.defineConfig; } });