Sitecore Marketplace SDK - xmc package

The xmc package extends the Client SDK and provides type-safe interfaces for interacting with the following Sitecore XM Cloud APIs:

• Authoring and Management GraphQL API - to manage Sitecore content using GraphQL.
• Pages API - to manage site pages in SitecoreAI.
• Sites API - to manage site collections, sites, languages and running background jobs.
• Experience Edge Token API - to manage API keys for the Delivery API.
• Experience Edge Admin API - to administer your Edge tenant.

Prerequisites

• Node.js 16 or later. Check your installed version by using the node --version command.
• npm 10 or later. Check your installed version by using the npm --version command.
• An XM Cloud subscription.

Installation

npm install @sitecore-marketplace-sdk/xmc

Initialization

Before you use queries or mutations, you must initialize the XMC module.

1. Update the code where you initialized the Client SDK by importing XMC and adding it to config:

// utils/hooks/useMarketplaceClient.ts
import { XMC } from '@sitecore-marketplace-sdk/xmc';

// ...
const config = {
  // ...
  modules: [XMC] // Extend Client SDK with `XMC`
};

Usage

Make a query

Use the query method to make one-off data requests and live subscriptions. Pass a value to the method depending on the data you want to retrieve. For examples:

• pass 'xmc.sites.listSites' to retrieve a list of sites:

client.query("xmc.sites.listSites", {
    params: {
        query: {
            sitecoreContextId,
        },
    },
}).then((res) => {
    console.log(
        "Success retrieving xmc.sites.listSites:",
        res.data
    );
}).catch((error) => {
    console.error(
        "Error retrieving xmc.sites.listSites:",
        error
    );
});

• pass 'xmc.pages.retrievePage' to retrieve information about a specific page:

client.query("xmc.pages.retrievePage", {
    params: {
        path: {
            pageId,
        },
        query: {
            site,
            sitecoreContextId,
            language,
        },
    },
}).then((res) => {
    console.log(
        "Success retrieving xmc.pages.retrievePage:",
        res.data
    );
}).catch((error) => {
    console.error(
        "Error retrieving xmc.pages.retrievePage:",
        error
    );
});

For an overview of all the possible values, refer to the QueryMap interface.

Make a mutation

Use the mutate method to trigger changes in Sitecore (the host). Pass a value to the method depending on the change you want to make.

For example, to open a different page in the XM Cloud Page builder in response to some other action:

const openDifferentPage = () => {
  client?.mutate("pages.context", {
    params: {
      itemId: "<ID_OF_NEW_PAGE>",
    },
  });
};

For an overview of all the possible values, refer to the MutationMap interface.

[!NOTE] Behind the scenes, the Host SDK (integrated via the internal core package) attaches the required user token and performs the HTTP request on behalf of the Marketplace app (the client).

Documentation

For more information, refer to the reference documentation in the /docs folder.

License

This package is part of the Sitecore Marketplace SDK, licensed under the Apache 2.0 License. Refer to the LICENSE file in the repository root.

Status

The client package is actively maintained as part of the Sitecore Marketplace SDK.