Marketplace Sdk Reference

Sitecore Marketplace SDK Reference

You are the reference guide for the Sitecore Marketplace SDK (v0.4). Answer questions about API methods, types, queries, mutations, and subscriptions.

How to Answer

1. First check the reference files below for the answer 2. If the reference files don't cover it, use WebFetch to check https://developers.sitecore.com/marketplace/sdk for the latest docs 3. Always provide TypeScript code examples 4. Always specify which package the API belongs to (client, xmc, or ai)

SDK Architecture

The SDK has 3 packages:

@sitecore-marketplace-sdk/client (required)

The core client. Provides ClientSDK, queries, mutations, subscriptions, and type definitions.

• See client-api.md for full API reference

@sitecore-marketplace-sdk/xmc

XM Cloud APIs for Sites, Pages, Authoring, Content Transfer, Search, and Agent.

• See xmc-api.md for full API reference

@sitecore-marketplace-sdk/ai

AI Skills APIs for Brand Review.

• See ai-api.md for full API reference

Quick Reference

Client Initialization

import { ClientSDK } from "@sitecore-marketplace-sdk/client";

const client = await ClientSDK.init({
  target: window.parent,
});

Common Patterns

// Query — returns { data, unsubscribe? }
const { data } = await client.query("queryName", params);

// Mutation
const { data } = await client.mutate("mutationName", params);

// Subscription — use query() with subscribe: true
const { unsubscribe } = await client.query("queryName", {
  subscribe: true,
  onSuccess: (data) => console.log(data),
});
unsubscribe?.();

Reference Files

• Client API — Core client queries, mutations, subscriptions, and types
• XM Cloud API — XM Cloud API reference
• AI API — AI Skills API reference

AI Skills Package API Reference

Module Registration

import { ClientSDK } from "@sitecore-marketplace-sdk/client";
import { AI } from "@sitecore-marketplace-sdk/ai";

const client = await ClientSDK.init({
  target: window.parent,
  modules: [AI],
});

Brand Review API

The Brand Review API provides AI-powered content analysis against a brand kit configured in Sitecore.

Client-Side

// Get sitecoreContextId from application context
const { data: appContext } = await client.query("application.context");
const sitecoreContextId = appContext.resourceAccess[0].context.live;

// Text review
const { data: review } = await client.mutate("ai.skills.generateBrandReview", {
  body: {
    brandkitId: "your-brand-kit-id",
    input: { text: "Your marketing copy here..." },
  },
  query: { sitecoreContextId },
});

// Image review (by URL)
const { data: review } = await client.mutate("ai.skills.generateBrandReview", {
  body: {
    brandkitId: "your-brand-kit-id",
    input: {
      banner: {
        name: "banner.png",
        type: "image",
        url: "https://example.com/banner.png",
        mimeType: "image/png",
      },
    },
  },
  query: { sitecoreContextId },
});

// Document review (by URL)
const { data: review } = await client.mutate("ai.skills.generateBrandReview", {
  body: {
    brandkitId: "your-brand-kit-id",
    input: {
      campaign: {
        name: "brief.pdf",
        type: "document",
        url: "https://example.com/brief.pdf",
        mimeType: "application/pdf",
      },
    },
  },
  query: { sitecoreContextId },
});

Server-Side Client

For full-stack (Auth0) apps:

import { experimental_createAIClient } from "@sitecore-marketplace-sdk/ai";

const aiClient = await experimental_createAIClient({
  getAccessToken: async () => {
    return await getYourAccessToken();
  },
});

const review = await aiClient.skills.generateBrandReview({
  body: {
    brandkitId: "your-brand-kit-id",
    input: { text: "Content to review..." },
  },
  query: { sitecoreContextId: "your-context-id" },
});

Client Package API Reference

ClientSDK.init(config)

Creates and initializes the SDK client.

import { ClientSDK } from "@sitecore-marketplace-sdk/client";

const client = await ClientSDK.init({
  target: window.parent,  // Required: target window (typically window.parent)
  modules?: Module[];     // Optional: Additional modules (XMC, AI)
});

QueryMap — Available Queries

Results are returned as { data, unsubscribe? }. All keys support subscribe: true for live updates.

Usage

const { data: appContext } = await client.query("application.context");
// sitecoreContextId: appContext.resourceAccess[0].context.live

const { data: user } = await client.query("host.user");

const { data: hostState } = await client.query("host.state");

const { data: route } = await client.query("host.route");

MutationMap — Available Mutations

Usage

// Navigate to a different page
await client.mutate("pages.context", {
  params: { itemId: "{12345678-ABCD-1234-ABCD-123456789ABC}" },
});

// Reload the canvas after content changes
await client.mutate("pages.reloadCanvas");

Subscriptions

Subscriptions use the query() method with subscribe: true — there is no separate subscribe() method.

// Subscribe to host state changes
const { unsubscribe } = await client.query("host.state", {
  subscribe: true,
  onSuccess: (newState) => {
    console.log("Host state changed:", newState);
  },
});

// Subscribe to page context changes (Pages editor)
const { unsubscribe } = await client.query("pages.context", {
  subscribe: true,
  onSuccess: (pagesContext) => {
    console.log("Page changed:", pagesContext);
  },
});

// Always clean up subscriptions
unsubscribe?.();

React Hooks

The scaffold generates React hooks for convenient SDK access:

import { useMarketplaceClient } from "@/components/providers/marketplace";

function MyComponent() {
  const { client } = useMarketplaceClient();
  // Use client?.query(), client?.mutate()
}

XM Cloud Package API Reference

Module Registration

import { ClientSDK } from "@sitecore-marketplace-sdk/client";
import { XMC } from "@sitecore-marketplace-sdk/xmc";

const client = await ClientSDK.init({
  target: window.parent,
  modules: [XMC],
});

Client-Side APIs

All XMC queries and mutations are prefixed with xmc.. Most require sitecoreContextId, obtained from application.context:

const { data: appContext } = await client.query("application.context");
const sitecoreContextId = appContext.resourceAccess[0].context.live;

Sites API

const { data: sites } = await client.query("xmc.sites.listSites", {
  params: {
    query: { sitecoreContextId },
  },
});

Pages API

const { data: page } = await client.query("xmc.pages.retrievePage", {
  params: {
    path: { pageId },
    query: { site, sitecoreContextId, language },
  },
});

Authoring API (GraphQL)

const { data } = await client.mutate("xmc.authoring.graphql", {
  params: {
    query: { sitecoreContextId },
    body: {
      query: `
        query GetItem($path: String!) {
          item(path: $path, language: "en") {
            id
            name
            fields { name value }
          }
        }
      `,
      variables: { path: "/sitecore/content/Home" },
    },
  },
});

Content Transfer API

Page Context Subscription

Subscribe to page changes using the base pages.context query with subscribe: true:

const { unsubscribe } = await client.query("pages.context", {
  subscribe: true,
  onSuccess: (pagesContext) => {
    console.log("Page changed:", pagesContext);
  },
});
unsubscribe?.();

Server-Side Client

For full-stack (Auth0) apps, use the server-side client in API routes or Server Actions:

import { experimental_createXMCClient } from "@sitecore-marketplace-sdk/xmc";

const xmcClient = await experimental_createXMCClient({
  getAccessToken: async () => {
    // Return the access token from your auth provider (e.g. Auth0)
    return await getYourAccessToken();
  },
});

const languages = await xmcClient.sites.listLanguages({
  query: { sitecoreContextId: "your-context-id" },
});