@sitecore-content-sdk/nextjs 0.1.0-beta.1

package/types/middleware/personalize-middleware.d.ts

@@ -0,0 +1,102 @@
+import { NextResponse, NextRequest } from 'next/server';
+import { GraphQLPersonalizeServiceConfig, PersonalizeInfo } from '@sitecore-content-sdk/core/personalize';
+import { MiddlewareBase, MiddlewareBaseConfig } from './middleware';
+export type CdpServiceConfig = {
+    /**
+     * Your Sitecore Edge Platform endpoint
+     * Default is https://edge-platform.sitecorecloud.io
+     */
+    sitecoreEdgeUrl?: string;
+    /**
+     * Your unified Sitecore Edge Context Id
+     */
+    sitecoreEdgeContextId: string;
+    /**
+     * The Sitecore CDP channel to use for events. Uses 'WEB' by default.
+     */
+    channel?: string;
+    /**
+     * Currency for CDP request. Uses 'USA' as default.
+     */
+    currency?: string;
+    /**
+     * Timeout (ms) for CDP request. Default is 400.
+     */
+    timeout?: number;
+};
+export type PersonalizeMiddlewareConfig = MiddlewareBaseConfig & {
+    /**
+     * Configuration for your Sitecore Experience Edge endpoint
+     */
+    edgeConfig: Omit<GraphQLPersonalizeServiceConfig, 'fetch'>;
+    /**
+     * Configuration for your Sitecore CDP endpoint
+     */
+    cdpConfig: CdpServiceConfig;
+    /**
+     * Optional Sitecore Personalize scope identifier allowing you to isolate your personalization data between XM Cloud environments
+     */
+    scope?: string;
+};
+/**
+ * Object model of Experience Context data
+ */
+export type ExperienceParams = {
+    referrer: string;
+    utm: {
+        [key: string]: string | undefined;
+        campaign: string | undefined;
+        source: string | undefined;
+        medium: string | undefined;
+        content: string | undefined;
+    };
+};
+/**
+ * Object model of personalize execution data
+ */
+type PersonalizeExecution = {
+    friendlyId: string;
+    variantIds: string[];
+};
+/**
+ * Middleware / handler to support Sitecore Personalize
+ */
+export declare class PersonalizeMiddleware extends MiddlewareBase {
+    protected config: PersonalizeMiddlewareConfig;
+    private personalizeService;
+    /**
+     * @param {PersonalizeMiddlewareConfig} [config] Personalize middleware config
+     */
+    constructor(config: PersonalizeMiddlewareConfig);
+    /**
+     * Gets the Next.js middleware handler with error handling
+     * @returns middleware handler
+     */
+    getHandler(): (req: NextRequest, res?: NextResponse) => Promise<NextResponse>;
+    protected initPersonalizeServer({ hostname, siteName, request, response, }: {
+        hostname: string;
+        siteName: string;
+        request: NextRequest;
+        response: NextResponse;
+    }): Promise<void>;
+    protected personalize({ params, friendlyId, language, timeout, variantIds, }: {
+        params: ExperienceParams;
+        friendlyId: string;
+        language: string;
+        timeout?: number;
+        variantIds?: string[];
+    }, request: NextRequest): Promise<{
+        variantId: string;
+    }>;
+    protected getExperienceParams(req: NextRequest): ExperienceParams;
+    protected excludeRoute(pathname: string): boolean | undefined;
+    /**
+     * Aggregates personalize executions based on the provided route personalize information and language
+     * @param {PersonalizeInfo} personalizeInfo the route personalize information
+     * @param {string} language the language
+     * @returns An array of personalize executions
+     */
+    protected getPersonalizeExecutions(personalizeInfo: PersonalizeInfo, language: string): PersonalizeExecution[];
+    private handler;
+}
+export {};

package/types/middleware/redirects-middleware.d.ts

@@ -0,0 +1,57 @@
+import { GraphQLRedirectsServiceConfig } from '@sitecore-content-sdk/core/site';
+import { NextRequest, NextResponse } from 'next/server';
+import { MiddlewareBase, MiddlewareBaseConfig } from './middleware';
+/**
+ * extended RedirectsMiddlewareConfig config type for RedirectsMiddleware
+ */
+export type RedirectsMiddlewareConfig = Omit<GraphQLRedirectsServiceConfig, 'fetch'> & MiddlewareBaseConfig & {
+    /**
+     * These are all the locales you support in your application.
+     * These should match those in your next.config.js (i18n.locales).
+     */
+    locales: string[];
+};
+/**
+ * Middleware / handler fetches all redirects from Sitecore instance by grapqhl service
+ * compares with current url and redirects to target url
+ */
+export declare class RedirectsMiddleware extends MiddlewareBase {
+    protected config: RedirectsMiddlewareConfig;
+    private redirectsService;
+    private locales;
+    /**
+     * @param {RedirectsMiddlewareConfig} [config] redirects middleware config
+     */
+    constructor(config: RedirectsMiddlewareConfig);
+    /**
+     * Gets the Next.js middleware handler with error handling
+     * @returns route handler
+     */
+    getHandler(): (req: NextRequest, res?: NextResponse) => Promise<NextResponse>;
+    private handler;
+    /**
+     * Method returns RedirectInfo when matches
+     * @param {NextRequest} req request
+     * @param {string} siteName site name
+     * @returns Promise<RedirectInfo | undefined>
+     * @private
+     */
+    private getExistsRedirect;
+    /**
+     * When a user clicks on a link generated by the Link component from next/link,
+     * Next.js adds special parameters in the route called path.
+     * This method removes these special parameters.
+     * @param {NextURL} url
+     * @returns {string} normalize url
+     */
+    private normalizeUrl;
+    /**
+     * Helper function to create a redirect response and remove the x-middleware-next header.
+     * @param {NextURL} url The URL to redirect to.
+     * @param {Response} res The response object.
+     * @param {number} status The HTTP status code of the redirect.
+     * @param {string} statusText The status text of the redirect.
+     * @returns {NextResponse<unknown>} The redirect response.
+     */
+    private createRedirectResponse;
+}

package/types/monitoring/healthcheck-middleware.d.ts

@@ -0,0 +1,12 @@
+import { NextApiResponse, NextApiRequest } from 'next';
+/**
+ * Middleware / handler for use in healthcheck Next.js API route (e.g. '/api/healthz').
+ */
+export declare class HealthcheckMiddleware {
+    /**
+     * Gets the Next.js API route handler
+     * @returns route handler
+     */
+    getHandler(): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+    private handler;
+}

package/types/monitoring/index.d.ts

@@ -0,0 +1 @@
+export { HealthcheckMiddleware } from './healthcheck-middleware';

package/types/services/base-graphql-sitemap-service.d.ts

@@ -0,0 +1,148 @@
+import { GraphQLClient, GraphQLRequestClientFactory, PageInfo } from '@sitecore-content-sdk/core/graphql';
+/** @private */
+export declare const languageError = "The list of languages cannot be empty";
+export declare const siteError = "The service needs a site name";
+/**
+ * @param {string} siteName to inject into error text
+ * @private
+ */
+export declare function getSiteEmptyError(siteName: string): string;
+/**
+ * type for input variables for the site routes query
+ */
+interface SiteRouteQueryVariables {
+    /**
+     * Required. The name of the site being queried.
+     */
+    siteName: string;
+    /**
+     * Required. The language to return routes/pages for.
+     */
+    language: string;
+    /**
+     * Optional. Only paths starting with these provided prefixes will be returned.
+     */
+    includedPaths?: string[];
+    /**
+     * Optional. Paths starting with these provided prefixes will be excluded from returned results.
+     */
+    excludedPaths?: string[];
+    /**
+     * common variable for all GraphQL queries
+     * it will be used for every type of query to regulate result batch size
+     * Optional. How many result items to fetch in each GraphQL call. This is needed for pagination.
+     * @default 100
+     */
+    pageSize?: number;
+}
+/**
+ * Schema of data returned in response to a "site" query request
+ * @template T The type of objects being requested.
+ */
+export interface SiteRouteQueryResult<T> {
+    site: {
+        siteInfo: {
+            routes: {
+                /**
+                 * Data needed to paginate the site results
+                 */
+                pageInfo: PageInfo;
+                results: T[];
+            };
+        };
+    };
+}
+/**
+ * The schema of data returned in response to a routes list query request
+ */
+export type RouteListQueryResult = {
+    path: string;
+    route?: {
+        personalization?: {
+            variantIds: string[];
+        };
+    };
+};
+/**
+ * Configuration options for @see GraphQLSitemapService instances
+ */
+export interface BaseGraphQLSitemapServiceConfig extends Omit<SiteRouteQueryVariables, 'language' | 'siteName'> {
+    /**
+     * A flag for whether to include personalized routes in service output.
+     * Only works on XM Cloud for pages using Embedded Personalization (not Component A/B testing).
+     * Turned off by default.
+     */
+    includePersonalizedRoutes?: boolean;
+    /**
+     * A GraphQL Request Client Factory is a function that accepts configuration and returns an instance of a GraphQLRequestClient.
+     * This factory function is used to create and configure GraphQL clients for making GraphQL API requests.
+     */
+    clientFactory: GraphQLRequestClientFactory;
+}
+/**
+ * Object model of a site page item.
+ */
+export type StaticPath = {
+    params: {
+        path: string[];
+    };
+    locale?: string;
+};
+/**
+ * Service that fetches the list of site pages using Sitecore's GraphQL API.
+ * Used to handle a single site
+ * This list is used for SSG and Export functionality.
+ * @mixes SearchQueryService<PageListQueryResult>
+ */
+export declare abstract class BaseGraphQLSitemapService {
+    options: BaseGraphQLSitemapServiceConfig;
+    private _graphQLClient;
+    /**
+     * Creates an instance of graphQL sitemap service with the provided options
+     * @param {GraphQLSitemapServiceConfig} options instance
+     */
+    constructor(options: BaseGraphQLSitemapServiceConfig);
+    /**
+     * GraphQL client accessible by descendant classes when needed
+     */
+    protected get graphQLClient(): GraphQLClient;
+    /**
+     * Gets the default query used for fetching the list of site pages
+     */
+    protected get query(): string;
+    /**
+     * Fetch sitemap which could be used for generation of static pages during `next export`.
+     * The `locale` parameter will be used in the item query, but since i18n is not supported,
+     * the output paths will not include a `language` property.
+     * @param {string} locale which application supports
+     * @returns an array of @see StaticPath objects
+     */
+    fetchExportSitemap(locale: string): Promise<StaticPath[]>;
+    /**
+     * Fetch sitemap which could be used for generation of static pages using SSG mode
+     * @param {string[]} locales locales which application supports
+     * @returns an array of @see StaticPath objects
+     */
+    fetchSSGSitemap(locales: string[]): Promise<StaticPath[]>;
+    protected getTranformedPaths(siteName: string, languages: string[], formatStaticPath: (path: string[], language: string) => StaticPath): Promise<StaticPath[]>;
+    protected transformLanguageSitePaths(sitePaths: RouteListQueryResult[], formatStaticPath: (path: string[], language: string) => StaticPath, language: string): Promise<StaticPath[]>;
+    protected fetchLanguageSitePaths(language: string, siteName: string): Promise<RouteListQueryResult[]>;
+    /**
+     * Gets a GraphQL client that can make requests to the API. Uses graphql-request as the default
+     * library for fetching graphql data (@see GraphQLRequestClient). Override this method if you
+     * want to use something else.
+     * @returns {GraphQLClient} implementation
+     */
+    protected getGraphQLClient(): GraphQLClient;
+    /**
+     * Fetch a flat list of all pages that belong to the specificed site and have a
+     * version in the specified language(s).
+     * @param {string[]} languages Fetch pages that have versions in this language(s).
+     * @param {Function} formatStaticPath Function for transforming the raw search results into (@see StaticPath) types.
+     * @returns list of pages
+     * @throws {RangeError} if the list of languages is empty.
+     * @throws {RangeError} if the any of the languages is an empty string.
+     */
+    protected abstract fetchSitemap(languages: string[], formatStaticPath: (path: string[], language: string) => StaticPath): Promise<StaticPath[]>;
+}
+export {};

package/types/services/component-props-service.d.ts

@@ -0,0 +1,81 @@
+import { GetServerSidePropsContext, GetStaticPropsContext } from 'next';
+import { LayoutServiceData, ComponentRendering, PlaceholdersData } from '@sitecore-content-sdk/core/layout';
+import { ComponentPropsCollection, ComponentPropsFetchFunction } from '../sharedTypes/component-props';
+import { ModuleFactory } from '../sharedTypes/module-factory';
+export type FetchComponentPropsArguments<NextContext> = {
+    layoutData: LayoutServiceData;
+    context: NextContext;
+    moduleFactory: ModuleFactory;
+};
+export type ComponentPropsRequest<NextContext> = {
+    fetch: ComponentPropsFetchFunction<NextContext>;
+    layoutData: LayoutServiceData;
+    rendering: ComponentRendering;
+    context: NextContext;
+};
+type FetchFunctionFactory<NextContext> = (componentName: string) => Promise<ComponentPropsFetchFunction<NextContext> | undefined>;
+export declare class ComponentPropsService {
+    /**
+     * SSR mode
+     * Fetch component props using getServerSideProps function
+     * @param {FetchComponentPropsArguments<GetServerSidePropsContext>} params fetch params
+     * @returns {Promise<ComponentPropsCollection>} props
+     */
+    fetchServerSideComponentProps(params: FetchComponentPropsArguments<GetServerSidePropsContext>): Promise<ComponentPropsCollection>;
+    /**
+     * SSG mode
+     * Fetch component props using getStaticProps function
+     * @param {FetchComponentPropsArguments<GetStaticPropsContext>} params fetch arguments
+     * @returns {Promise<ComponentPropsCollection>} props
+     */
+    fetchStaticComponentProps(params: FetchComponentPropsArguments<GetStaticPropsContext>): Promise<ComponentPropsCollection>;
+    /**
+     * Traverse Layout Service data tree and call side effects on component level.
+     * Side effect function can be: getStaticProps (SSG) or getServerSideProps (SSR)
+     * @param {FetchFunctionFactory<NextContext>} fetchFunctionFactory fetch function factory
+     * @param {LayoutServiceData} layoutData layout data
+     * @param {NextContext} context next context
+     * @returns {Promise<ComponentPropsCollection>} component props
+     */
+    protected fetchComponentProps<NextContext>(fetchFunctionFactory: FetchFunctionFactory<NextContext>, layoutData: LayoutServiceData, context: NextContext): Promise<ComponentPropsCollection>;
+    /**
+     * Go through layout service data, check all renderings using displayName, which should make some side effects.
+     * Write result in requests variable
+     * @param {object} params params
+     * @param {PlaceholdersData} [params.placeholders]
+     * @param {FetchFunctionFactory<NextContext>} params.fetchFunctionFactory
+     * @param {LayoutServiceData} params.layoutData
+     * @param {NextContext} params.context
+     * @param {ComponentPropsRequest<NextContext>[]} params.requests
+     * @returns {ComponentPropsRequest<NextContext>[]} array of requests
+     */
+    protected collectRequests<NextContext>(params: {
+        placeholders?: PlaceholdersData;
+        fetchFunctionFactory: FetchFunctionFactory<NextContext>;
+        layoutData: LayoutServiceData;
+        context: NextContext;
+        requests?: ComponentPropsRequest<NextContext>[];
+    }): Promise<ComponentPropsRequest<NextContext>[]>;
+    /**
+     * Execute request for component props
+     * @param {ComponentPropsRequest<NextContext>[]} requests requests
+     * @returns {Promise<ComponentPropsCollection>} requests result
+     */
+    protected execRequests<NextContext>(requests: ComponentPropsRequest<NextContext>[]): Promise<ComponentPropsCollection>;
+    /**
+     * Take renderings from all placeholders and returns a flat array of renderings.
+     * @example
+     * const placeholders = {
+     *    x1: [{ uid: 1 }, { uid: 2 }],
+     *    x2: [{ uid: 11 }, { uid: 22 }]
+     * }
+     *
+     * flatRenderings(placeholders);
+     *
+     * RESULT: [{ uid: 1 }, { uid: 2 }, { uid: 11 }, { uid: 22 }]
+     * @param {PlaceholdersData} placeholders placeholders
+     * @returns {ComponentRendering[]} renderings
+     */
+    protected flatRenderings(placeholders: PlaceholdersData): ComponentRendering[];
+}
+export {};

package/types/services/graphql-sitemap-service.d.ts

@@ -0,0 +1,51 @@
+import { BaseGraphQLSitemapService, BaseGraphQLSitemapServiceConfig } from './base-graphql-sitemap-service';
+/** @private */
+export declare const languageError = "The list of languages cannot be empty";
+export declare const siteError = "The service needs a site name";
+/**
+ * @param {string} siteName to inject into error text
+ * @private
+ */
+export declare function getSiteEmptyError(siteName: string): string;
+/**
+ * Configuration options for @see GraphQLSitemapService instances
+ */
+export interface GraphQLSitemapServiceConfig extends BaseGraphQLSitemapServiceConfig {
+    /**
+     * Name of the site to retrieve site paths for
+     */
+    siteName: string;
+}
+/**
+ * Object model of a site page item.
+ */
+export type StaticPath = {
+    params: {
+        path: string[];
+    };
+    locale?: string;
+};
+/**
+ * Service that fetches the list of site pages using Sitecore's GraphQL API.
+ * Used to handle a single site
+ * This list is used for SSG and Export functionality.
+ * @mixes SearchQueryService<PageListQueryResult>
+ */
+export declare class GraphQLSitemapService extends BaseGraphQLSitemapService {
+    options: GraphQLSitemapServiceConfig;
+    /**
+     * Creates an instance of graphQL sitemap service with the provided options
+     * @param {GraphQLSitemapServiceConfig} options instance
+     */
+    constructor(options: GraphQLSitemapServiceConfig);
+    /**
+     * Fetch a flat list of all pages that belong to the specificed site and have a
+     * version in the specified language(s).
+     * @param {string[]} languages Fetch pages that have versions in this language(s).
+     * @param {Function} formatStaticPath Function for transforming the raw search results into (@see StaticPath) types.
+     * @returns list of pages
+     * @throws {RangeError} if the list of languages is empty.
+     * @throws {RangeError} if the any of the languages is an empty string.
+     */
+    protected fetchSitemap(languages: string[], formatStaticPath: (path: string[], language: string) => StaticPath): Promise<StaticPath[]>;
+}

package/types/services/mutisite-graphql-sitemap-service.d.ts

@@ -0,0 +1,42 @@
+import { BaseGraphQLSitemapService, BaseGraphQLSitemapServiceConfig, RouteListQueryResult, StaticPath } from './base-graphql-sitemap-service';
+export declare const sitesError = "The list of sites cannot be empty";
+/**
+ * Configuration options for @see GraphQLSitemapService instances
+ */
+export interface MultisiteGraphQLSitemapServiceConfig extends BaseGraphQLSitemapServiceConfig {
+    /**
+     * Names of the configured sites
+     */
+    sites: string[];
+}
+/**
+ * Service that fetches the list of site pages using Sitecore's GraphQL API.
+ * Used to handle multiple sites
+ * This list is used for SSG and Export functionality.
+ * @mixes SearchQueryService<PageListQueryResult>
+ */
+export declare class MultisiteGraphQLSitemapService extends BaseGraphQLSitemapService {
+    options: MultisiteGraphQLSitemapServiceConfig;
+    /**
+     * Creates an instance of graphQL sitemap service with the provided options
+     * @param {MultisiteGraphQLSitemapServiceConfig} options instance
+     */
+    constructor(options: MultisiteGraphQLSitemapServiceConfig);
+    /**
+     * Fetch a flat list of all pages that belong to all the requested sites and have a
+     * version in the specified language(s).
+     * @param {string[]} languages Fetch pages that have versions in this language(s).
+     * @param {Function} formatStaticPath Function for transforming the raw search results into (@see StaticPath) types.
+     * @returns list of pages
+     * @throws {RangeError} if the list of languages is empty.
+     * @throws {RangeError} if the any of the languages is an empty string.
+     */
+    protected fetchSitemap(languages: string[], formatStaticPath: (path: string[], language: string) => StaticPath): Promise<StaticPath[]>;
+    /**
+     * Fetch and return site paths for multisite implementation, with prefixes included
+     * @param {string} language path language
+     * @param {string} siteName site name
+     * @returns modified paths
+     */
+    protected fetchLanguageSitePaths(language: string, siteName: string): Promise<RouteListQueryResult[]>;
+}

package/types/sharedTypes/component-props.d.ts

@@ -0,0 +1,26 @@
+import { GetServerSidePropsContext, GetStaticPropsContext } from 'next';
+import { ComponentRendering, LayoutServiceData } from '@sitecore-content-sdk/core/layout';
+export type ComponentPropsError = {
+    error: string;
+    componentName: string;
+};
+/**
+ * Shape of component props storage
+ */
+export type ComponentPropsCollection = {
+    [componentUid: string]: unknown | ComponentPropsError;
+};
+/**
+ * Type of side effect function which could be invoked on component level (getStaticProps/getServerSideProps)
+ */
+export type ComponentPropsFetchFunction<NextContext, FetchedProps = unknown> = {
+    (rendering: ComponentRendering, layoutData: LayoutServiceData, context: NextContext): Promise<FetchedProps>;
+};
+/**
+ * Shape of getServerSideProps function on component level
+ */
+export type GetServerSideComponentProps = ComponentPropsFetchFunction<GetServerSidePropsContext>;
+/**
+ * Shape of getStaticProps function on component level
+ */
+export type GetStaticComponentProps = ComponentPropsFetchFunction<GetStaticPropsContext>;

package/types/sharedTypes/module-factory.d.ts

@@ -0,0 +1,32 @@
+import { ComponentType } from 'react';
+import { GetServerSideComponentProps, GetStaticComponentProps } from './component-props';
+/**
+ * Represents a module (file)
+ */
+export type Module = {
+    /**
+     * Default SXA export
+     */
+    Default?: ComponentType;
+    /**
+     * Default Next.js export
+     */
+    default?: ComponentType;
+    /**
+     * function for component level data fetching in SSR mode
+     */
+    getServerSideProps?: GetServerSideComponentProps;
+    /**
+     * function for component level data fetching in SSG mode
+     */
+    getStaticProps?: GetStaticComponentProps;
+} & {
+    /**
+     * Custom exports
+     */
+    [key: string]: ComponentType;
+};
+/**
+ * Represents a module factory
+ */
+export type ModuleFactory = (componentName: string) => Module | Promise<Module> | null;

package/types/site/index.d.ts

@@ -0,0 +1 @@
+export { SiteResolver, SiteInfo } from '@sitecore-content-sdk/core/site';

package/types/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { handleEditorFastRefresh } from './utils';
+export { tryParseEnvValue, resolveUrl } from '@sitecore-content-sdk/core/utils';
+export { isEditorActive, resetEditorChromes } from '@sitecore-content-sdk/core/editing';

package/types/utils/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Since Sitecore editors do not support Fast Refresh:
+ * 1. Subscribe on events provided by webpack.
+ * 2. Reset editor chromes when build is finished
+ * @param {boolean} [forceReload] force page reload instead of reset chromes
+ */
+export declare const handleEditorFastRefresh: (forceReload?: boolean) => void;
+export declare const getJssEditingSecret: () => string;

package/utils.d.ts

@@ -0,0 +1 @@
+export * from './types/utils/index';

package/utils.js

@@ -0,0 +1 @@
+module.exports = require('./dist/cjs/utils/index');