@sitecoreai-labs/sitecoreai-cli 0.0.4

package/dist/recipe/api/authoring-client.js

@@ -0,0 +1,495 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthoringClient = void 0;
+const errors_1 = require("../../shared/errors");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const graphql_1 = require("../../shared/graphql");
+const sitecore_templates_1 = require("../ir/sitecore-templates");
+const ref_encoding_1 = require("./ref-encoding");
+const graphql_2 = require("./graphql");
+/** Sitecore itemIds are uuids — bare or wrapped in curly braces. Anything
+ *  that doesn't look like one is treated as a content-tree path. */
+const GUID_PATTERN = /^\{?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\}?$/i;
+const isItemId = (value) => GUID_PATTERN.test(value.trim());
+/**
+ * Pick the folder template scai will auto-create missing parent path
+ * segments under. Conventional SXA template per tree:
+ *
+ * - `/sitecore/templates/...`         → `Template Folder` (the SXA editor
+ *                                        treats these as templates-tree
+ *                                        organisational nodes)
+ * - `/sitecore/layout/Renderings/...` → `Rendering Folder` (verified
+ *                                        against live tenant — section
+ *                                        folders under
+ *                                        `/sitecore/layout/Renderings/Project/<site>/`
+ *                                        all conform to this template,
+ *                                        not generic `Folder`)
+ * - `.../Presentation/Headless Variants/...`
+ *                                     → `HeadlessVariantsGrouping` (every
+ *                                        folder under a site's Headless
+ *                                        Variants tree — section
+ *                                        groupings like `UI`, `Layout`,
+ *                                        etc. — must conform to this
+ *                                        template, otherwise SXA's editor
+ *                                        won't enumerate the variants
+ *                                        underneath. Per-rendering folders
+ *                                        (`<root>/UI/AvatarBlock`) are
+ *                                        always emitted explicitly with
+ *                                        `HEADLESS_VARIANTS`, so this
+ *                                        fallback only fires for the
+ *                                        section-grouping depth.)
+ * - everything else                   → generic `Folder`
+ *
+ * Picking the wrong template here doesn't break createItem itself, but
+ * it can leave SXA's editor UI unable to recognise the auto-created
+ * folder when walking the tree.
+ *
+ * Hazard fixed by the Headless Variants branch: a previous scai version
+ * emitted variant items before the explicit section-grouping CreateItem
+ * was added. Tenants pushed under that version got their `UI` /
+ * `Layout` / etc. section folders auto-created here as generic
+ * `Folder`. Subsequent runs emit the section grouping with
+ * `HEADLESS_VARIANTS_GROUPING`, but `CreateOnly` policy skips updating
+ * the existing item, so the wrong template persists. Detecting the
+ * tree here at least keeps NEW installs correct; existing tenants
+ * still need a manual delete-and-republish (or a future template-
+ * correction migration) to fix the stale folder.
+ */
+const folderTemplateForPath = (path) => {
+    const normalized = path.toLowerCase();
+    if (normalized.startsWith("/sitecore/templates/")) {
+        return sitecore_templates_1.SITECORE_TEMPLATES.TEMPLATE_FOLDER;
+    }
+    if (normalized.startsWith("/sitecore/layout/renderings/")) {
+        return sitecore_templates_1.SITECORE_TEMPLATES.RENDERING_FOLDER;
+    }
+    if (normalized.includes("/presentation/headless variants/")) {
+        return sitecore_templates_1.SITECORE_TEMPLATES.HEADLESS_VARIANTS_GROUPING;
+    }
+    return sitecore_templates_1.SITECORE_TEMPLATES.FOLDER;
+};
+/**
+ * Production `AuthoringApiClient` against Sitecore Authoring GraphQL.
+ *
+ * Schema verified against XM Cloud Authoring API via introspection
+ * (2026-04-30). Notable shape facts:
+ *
+ * - `Item.parent` and `Item.template` are sub-objects (not flat scalars).
+ * - `CreateItemInput` does NOT accept `itemId` — Sitecore assigns IDs
+ *   server-side. The `createItem` response is the source of truth.
+ * - `FieldValueInput` is `{ name, value, reset? }`; per-field language /
+ *   version are not supported here (set at the input level via
+ *   `CreateItemInput.language`).
+ */
+const ITEM_FRAGMENT = `
+  itemId
+  name
+  path
+  parent {
+    itemId
+  }
+  template {
+    templateId
+  }
+  fields(ownFields: false) {
+    nodes {
+      name
+      value
+      templateField {
+        templateFieldId
+      }
+    }
+  }
+`;
+const GET_ITEM_BY_PATH = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    ${ITEM_FRAGMENT}
+  }
+}`;
+const GET_ITEM_BY_ID = `
+query($itemId: ID!) {
+  item(where: { itemId: $itemId }) {
+    ${ITEM_FRAGMENT}
+  }
+}`;
+const GET_CHILDREN_BY_PATH = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    children {
+      nodes {
+        ${ITEM_FRAGMENT}
+      }
+    }
+  }
+}`;
+const GET_CHILDREN_BY_ID = `
+query($itemId: ID!) {
+  item(where: { itemId: $itemId }) {
+    children {
+      nodes {
+        ${ITEM_FRAGMENT}
+      }
+    }
+  }
+}`;
+const CREATE_ITEM_MUTATION = `
+mutation($input: CreateItemInput!) {
+  createItem(input: $input) {
+    item {
+      itemId
+    }
+  }
+}`;
+const UPDATE_ITEM_MUTATION = `
+mutation($input: UpdateItemInput!) {
+  updateItem(input: $input) {
+    item {
+      itemId
+    }
+  }
+}`;
+const DELETE_ITEM_MUTATION = `
+mutation($input: DeleteItemInput!) {
+  deleteItem(input: $input) {
+    successful
+  }
+}`;
+const toRemoteItem = (node) => ({
+    itemId: node.itemId,
+    name: node.name,
+    path: node.path,
+    parentId: node.parent?.itemId ?? "",
+    templateId: node.template?.templateId ?? "",
+    // The Authoring API returns `field.name` as the field's display name
+    // (e.g. "__Icon", "componentName"). Drift detection prefers the recipe
+    // op's `fieldName` when present (recipe-created fields whose GUIDs the
+    // tenant doesn't recognize); else falls back to the field's GUID at
+    // `field.templateField.templateFieldId`. Sitecore normalizes those GUIDs
+    // without dashes, so re-format to canonical 8-4-4-4-12.
+    fields: node.fields.nodes
+        .filter((field) => field.templateField?.templateFieldId)
+        .map((field) => ({
+        fieldId: (0, ref_encoding_1.dashifyGuid)(field.templateField.templateFieldId),
+        name: field.name,
+        value: field.value,
+    })),
+});
+const toAuthoringFieldsInput = (fields) => fields.map((field) => ({
+    // Sitecore's `FieldValueInput.name` accepts a field name OR id. For
+    // recipe-created fields, the IR's `fieldId` is only a uuidv5 refKey
+    // (the tenant's server-assigned GUID is different) — fall through to
+    // `fieldName`, which Sitecore resolves against the item's template.
+    // For system fields without a `fieldName`, the literal GUID works.
+    name: field.fieldName ?? field.fieldId,
+    value: (0, ref_encoding_1.renderRefValue)(field.value),
+}));
+const DEFAULT_BATCH_READ_SIZE = 25;
+const DEFAULT_BATCH_READ_CONCURRENCY = 4;
+const createAuthoringClient = (options) => {
+    const { environment, request, pathItemIdCache } = options;
+    const batchSize = options.batchedReadSize ?? DEFAULT_BATCH_READ_SIZE;
+    const batchConcurrency = options.batchedReadConcurrency ?? DEFAULT_BATCH_READ_CONCURRENCY;
+    /**
+     * Per-call request options for read operations — extends caller-supplied
+     * `request` with the broad retry status set. Reads are idempotent so
+     * retrying through 500/502/504 is safe and absorbs transient gateway
+     * errors without aborting the whole push.
+     */
+    const readRequest = {
+        ...request,
+        retry: { ...request?.retry, retryableStatuses: graphql_1.READ_RETRYABLE_STATUSES },
+    };
+    /**
+     * Per-call request options for write operations — uses the conservative
+     * default retry set (just throttle / never-reached-origin codes:
+     * 408/425/429/503). A 500/502/504 may indicate the server processed
+     * the request but failed to respond; retrying would create a duplicate
+     * with no idempotency key. The recipe rollback flow recovers from
+     * partial-write states by replay, not by silent retries.
+     */
+    const writeRequest = request ?? {};
+    const fetchOne = async (selector) => {
+        if (selector.itemId) {
+            const data = await (0, graphql_2.runAuthoringGraphQL)(environment, GET_ITEM_BY_ID, { itemId: selector.itemId }, readRequest);
+            return data.item;
+        }
+        if (selector.path) {
+            const data = await (0, graphql_2.runAuthoringGraphQL)(environment, GET_ITEM_BY_PATH, { path: selector.path }, readRequest);
+            return data.item;
+        }
+        throw (0, errors_1.createCliError)("ItemSelector requires either path or itemId.", "INPUT_INVALID");
+    };
+    /**
+     * Batched path→item read using GraphQL aliased fields. One POST returns
+     * up to `batchSize` items. Aliasing format:
+     *
+     *   query Batch($p0: String!, $p1: String!, ...) {
+     *     i0: item(where: { path: $p0 }) { ...ItemFragment }
+     *     i1: item(where: { path: $p1 }) { ...ItemFragment }
+     *     ...
+     *   }
+     *
+     * Aliases are stable per call (`i0`, `i1`, ...) so the response object
+     * keys map cleanly back to the input slice. Missing items return
+     * `null` under their alias — same shape as a single-path 404.
+     */
+    const fetchOneBatch = async (paths) => {
+        if (paths.length === 0)
+            return [];
+        const variableDecls = paths.map((_, i) => `$p${i}: String!`).join(", ");
+        const aliasedSelections = paths
+            .map((_, i) => `
+  i${i}: item(where: { path: $p${i} }) {
+    ${ITEM_FRAGMENT}
+  }`)
+            .join("");
+        const query = `query Batch(${variableDecls}) {${aliasedSelections}\n}`;
+        const variables = {};
+        for (let i = 0; i < paths.length; i += 1) {
+            variables[`p${i}`] = paths[i];
+        }
+        const data = await (0, graphql_2.runAuthoringGraphQL)(environment, query, variables, readRequest);
+        return paths.map((_, i) => data[`i${i}`] ?? null);
+    };
+    const fetchChildren = async (selector) => {
+        if (selector.itemId) {
+            const data = await (0, graphql_2.runAuthoringGraphQL)(environment, GET_CHILDREN_BY_ID, { itemId: selector.itemId }, readRequest);
+            return data.item?.children.nodes ?? [];
+        }
+        if (selector.path) {
+            const data = await (0, graphql_2.runAuthoringGraphQL)(environment, GET_CHILDREN_BY_PATH, { path: selector.path }, readRequest);
+            return data.item?.children.nodes ?? [];
+        }
+        throw (0, errors_1.createCliError)("ItemSelector requires either path or itemId.", "INPUT_INVALID");
+    };
+    /**
+     * Walk the content-tree path bottom-up, returning the itemId of `path`.
+     * Creates any missing segments using `folderTemplateForPath`. Recursive
+     * — each level either finds an existing item OR creates one and walks
+     * up further. The Sitecore root (`/sitecore`) MUST already exist; any
+     * path that bottoms out before reaching an existing ancestor throws.
+     *
+     * Used by `createItem` to satisfy Authoring GraphQL's
+     * `CreateItemInput.parent: ID!` typing — callers pass paths, scai
+     * resolves to itemIds (auto-provisioning the SXA-style folder chain
+     * if the tenant's per-site templates/renderings/content folders
+     * haven't been scaffolded yet).
+     */
+    const ensurePathExists = async (rawPath) => {
+        const path = rawPath.replace(/\/+$/, "");
+        // Fast path: caller (or an earlier ensurePathExists) already resolved
+        // this path. Avoids the redundant `getItem` round trip every sibling
+        // createItem would otherwise pay under a shared section folder.
+        const cached = pathItemIdCache?.get(path);
+        if (cached)
+            return cached;
+        const existing = await fetchOne({ path });
+        if (existing) {
+            pathItemIdCache?.set(path, existing.itemId);
+            return existing.itemId;
+        }
+        const lastSlash = path.lastIndexOf("/");
+        if (lastSlash <= 0) {
+            throw (0, errors_1.createCliError)(`Cannot auto-create root path '${path}'. The Sitecore root must already exist on the tenant.`, "INPUT_INVALID");
+        }
+        const parentPath = path.slice(0, lastSlash);
+        const name = path.slice(lastSlash + 1);
+        if (!name) {
+            throw (0, errors_1.createCliError)(`Path '${rawPath}' has no leaf segment to create.`, "INPUT_INVALID");
+        }
+        const parentItemId = await ensurePathExists(parentPath);
+        const templateId = folderTemplateForPath(path);
+        const data = await (0, graphql_2.runAuthoringGraphQL)(environment, CREATE_ITEM_MUTATION, {
+            input: {
+                parent: parentItemId,
+                templateId,
+                name,
+                database: "master",
+                language: "en",
+                fields: [],
+            },
+        }, writeRequest);
+        const itemId = data.createItem?.item?.itemId;
+        if (!itemId) {
+            throw (0, errors_1.createCliError)(`Auto-provisioning failed: Authoring API returned no itemId after creating folder '${path}'.`, "UNKNOWN");
+        }
+        pathItemIdCache?.set(path, itemId);
+        return itemId;
+    };
+    /**
+     * Detect Sitecore's name-conflict error class. Authoring GraphQL
+     * surfaces these as wrapped CliError messages of the form:
+     *
+     *   `Authoring GraphQL errors: The item name "X" is already defined on this level.`
+     *
+     * The variant `"is not unique"` and `"already exists"` are also
+     * known phrasings on adjacent server versions; match permissively
+     * so our idempotent-create fallback covers them all.
+     */
+    const isAlreadyExistsError = (error) => {
+        if (!(error instanceof Error))
+            return false;
+        const msg = error.message;
+        return (/already defined on this level/i.test(msg) ||
+            /is not unique/i.test(msg) ||
+            /already exists/i.test(msg) ||
+            /name is already in use/i.test(msg));
+    };
+    /**
+     * Look up a single direct child of `parentItemId` by name. Used by
+     * the idempotent-create fallback when `createItem` reports a
+     * name conflict — the parent-child relationship is not subject to
+     * Sitecore's path-index propagation lag, so this returns the
+     * correct existing item even when `getItem({path})` for the same
+     * path still reports null.
+     */
+    const findChildByName = async (parentItemId, name) => {
+        const children = await fetchChildren({ itemId: parentItemId });
+        return children.find((c) => c.name === name) ?? null;
+    };
+    /**
+     * Resolve a `CreateItemInput.parent` value (itemId GUID OR content-tree
+     * path) to a Sitecore itemId. The Authoring API's
+     * `CreateItemInput.parent` is typed `ID!`, so paths must be resolved
+     * before the mutation — otherwise GraphQL fails with
+     * "Unable to convert type from String to Guid". Missing path segments
+     * are auto-created as folders.
+     */
+    const resolveParentItemId = async (parent) => {
+        const trimmed = parent.trim();
+        if (isItemId(trimmed))
+            return trimmed.replace(/[{}]/g, "");
+        if (trimmed.startsWith("/"))
+            return ensurePathExists(trimmed);
+        throw (0, errors_1.createCliError)(`createItem.input.parent must be a Sitecore itemId or content-tree path; got: '${trimmed}'.`, "INPUT_INVALID");
+    };
+    return {
+        async getItem(selector, _options) {
+            const node = await fetchOne(selector);
+            return node ? toRemoteItem(node) : null;
+        },
+        async getItemsByPaths(paths) {
+            const result = new Map();
+            if (paths.length === 0)
+                return result;
+            // De-duplicate within a single call so repeated paths don't
+            // cost extra wire bytes; preserve the original strings for the
+            // returned map (caller-key contract).
+            const unique = [];
+            const seen = new Set();
+            for (const p of paths) {
+                if (!seen.has(p)) {
+                    seen.add(p);
+                    unique.push(p);
+                }
+            }
+            const batches = [];
+            for (let i = 0; i < unique.length; i += batchSize) {
+                batches.push(unique.slice(i, i + batchSize));
+            }
+            const batchResults = await (0, cli_tasks_1.mapWithConcurrency)(batches, (batch) => fetchOneBatch(batch), batchConcurrency);
+            for (let b = 0; b < batches.length; b += 1) {
+                const batch = batches[b];
+                const nodes = batchResults[b];
+                for (let i = 0; i < batch.length; i += 1) {
+                    const path = batch[i];
+                    const node = nodes[i];
+                    const item = node ? toRemoteItem(node) : null;
+                    result.set(path, item);
+                    // Side-effect: seed the path → itemId cache used by the
+                    // recipe executor's `ensurePathExists` and parent-resolution
+                    // fast paths. Skips writing nulls — `null` means "checked
+                    // and missing", and ensurePathExists distinguishes "not
+                    // cached" (must check) from "cached as missing" by re-reading
+                    // anyway when it auto-creates.
+                    if (item && pathItemIdCache && !pathItemIdCache.has(path)) {
+                        pathItemIdCache.set(path, item.itemId);
+                    }
+                }
+            }
+            // Re-emit caller-input keys (caller may have passed dupes — same
+            // value mapping back applies).
+            for (const p of paths) {
+                if (!result.has(p)) {
+                    // Should not happen given the loop above + de-dupe, but defend.
+                    result.set(p, null);
+                }
+            }
+            return result;
+        },
+        async getChildren(parent, _options) {
+            const nodes = await fetchChildren(parent);
+            return nodes.map(toRemoteItem);
+        },
+        async createItem(input) {
+            const parentItemId = await resolveParentItemId(input.parent);
+            try {
+                const data = await (0, graphql_2.runAuthoringGraphQL)(environment, CREATE_ITEM_MUTATION, {
+                    input: {
+                        parent: parentItemId,
+                        templateId: input.templateId,
+                        name: input.name,
+                        database: input.database ?? "master",
+                        language: input.language ?? "en",
+                        fields: toAuthoringFieldsInput(input.fields),
+                    },
+                }, writeRequest);
+                const itemId = data.createItem?.item?.itemId;
+                if (!itemId) {
+                    throw (0, errors_1.createCliError)("createItem returned no itemId — Authoring API response was malformed.", "UNKNOWN");
+                }
+                return { itemId };
+            }
+            catch (error) {
+                // Idempotent-create fallback for the recurring "name already defined
+                // on this level" failure mode. Sitecore's path index (used by
+                // `getItem({path})` and the workspace prefetch) lags writes by
+                // seconds-to-minutes — so a planner that checks-by-path and sees
+                // "missing" can plan a create against a path that the tenant
+                // actually already has, either from an earlier op in the same
+                // push or from a previous push. The parent-child storage is
+                // not lag-prone, so we fall through to `getChildren(parent)`
+                // to locate the existing item by name and return its itemId
+                // as if the create succeeded. The caller's `dispatchMutation`
+                // captures it normally; for `CreateOnly` ops this is the
+                // intended behavior, for `CreateAndUpdate` we accept that the
+                // existing item's fields aren't updated in this push (the
+                // next push's prefetch will see the item via path lookup, the
+                // planner takes the update branch, and drift gets corrected).
+                if (isAlreadyExistsError(error)) {
+                    const existing = await findChildByName(parentItemId, input.name);
+                    if (existing) {
+                        return { itemId: existing.itemId };
+                    }
+                }
+                throw error;
+            }
+        },
+        async updateItem(input) {
+            await (0, graphql_2.runAuthoringGraphQL)(environment, UPDATE_ITEM_MUTATION, {
+                input: {
+                    itemId: input.itemId,
+                    fields: toAuthoringFieldsInput(input.fields),
+                },
+            }, writeRequest);
+        },
+        async deleteItem(selector) {
+            // `permanently: true` skips the recycle bin — rollback and integration
+            // cleanup both want full removal. Default-false would leave items
+            // discoverable by path under /sitecore/content/Recycle Bin.
+            const input = { permanently: true };
+            if (selector.itemId)
+                input.itemId = selector.itemId;
+            else if (selector.path)
+                input.path = selector.path;
+            else
+                throw (0, errors_1.createCliError)("deleteItem requires either path or itemId.", "INPUT_INVALID");
+            const data = await (0, graphql_2.runAuthoringGraphQL)(environment, DELETE_ITEM_MUTATION, { input }, writeRequest);
+            if (!data.deleteItem?.successful) {
+                throw (0, errors_1.createCliError)(`deleteItem returned successful: ${data.deleteItem?.successful} for ${selector.itemId ?? selector.path ?? "(no selector)"}`, "UNKNOWN");
+            }
+        },
+    };
+};
+exports.createAuthoringClient = createAuthoringClient;

package/dist/recipe/api/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Authoring API client surface for recipe execution.
+ *
+ * The Sitecore Authoring API server-assigns itemIds on `createItem` —
+ * we cannot specify them. The recipe push therefore uses **paths** as
+ * the identity hook: each CreateItem op carries a deterministic path
+ * (`<templatesRoot>/<recipe.name>/...`) that the planner uses for
+ * lookup, and the `createItem` mutation returns the assigned itemId,
+ * which the executor caches in a per-run map keyed by recipe-internal
+ * uuidv5 refKey for cross-reference resolution.
+ *
+ * The IR planner and executor depend only on this interface. Production
+ * runs use `createAuthoringClient` from `./authoring-client`; tests
+ * inject a mock — same seam either way.
+ */
+import type { FieldValue } from "../ir/operations";
+export interface RemoteFieldValue {
+    fieldId: string;
+    /**
+     * Field name as defined on the template (e.g. `Body`, `__Display Name`).
+     * Real `getItem` responses always carry this; optional in the type so
+     * that test mocks aren't forced to populate it for fieldId-only
+     * scenarios. The planner prefers name-based matching when the IR's
+     * SetField op carries a `fieldName` (recipe-created fields whose
+     * recipe-derived GUID is only an IR-internal refKey).
+     */
+    name?: string;
+    /** Sitecore returns the raw stored value (string), regardless of field type. */
+    value: string;
+    /** Versioned fields carry these; shared fields do not. */
+    language?: string;
+    version?: number;
+}
+export interface RemoteItem {
+    itemId: string;
+    templateId: string;
+    parentId: string;
+    name: string;
+    /** Sitecore content-tree path of the item, e.g. `/sitecore/templates/...`. */
+    path: string;
+    fields: RemoteFieldValue[];
+}
+/** Item lookup selector — Sitecore accepts either a path or a GUID id. */
+export interface ItemSelector {
+    path?: string;
+    itemId?: string;
+}
+export interface CreateItemInput {
+    /** Parent path (e.g. `/sitecore/templates/Project`) or parent item GUID. */
+    parent: string;
+    templateId: string;
+    name: string;
+    /** Defaults to "master" if unset. */
+    database?: string;
+    /** Default language for versioned fields; defaults to "en". */
+    language?: string;
+    fields: FieldValue[];
+}
+export interface CreateItemResult {
+    /** Sitecore-assigned itemId (UUID without curly braces). */
+    itemId: string;
+}
+export interface UpdateItemInput {
+    itemId: string;
+    fields: FieldValue[];
+}
+export interface GetItemOptions {
+    /** Languages to fetch versioned fields for. Default: `["en"]`. */
+    languages?: string[];
+}
+export interface AuthoringApiClient {
+    /**
+     * Resolve an item by path or by Sitecore-assigned itemId. Returns
+     * `null` when the item does not exist.
+     */
+    getItem(selector: ItemSelector, options?: GetItemOptions): Promise<RemoteItem | null>;
+    /**
+     * Resolve many items at once by path. Returns a Map keyed by the SAME
+     * string the caller passed in (case-preserved) — value is the
+     * `RemoteItem` if found, `null` if the item does not exist on the
+     * tenant. Implementations should batch wire calls (e.g. via aliased
+     * GraphQL fields) so an N-path request is one or a small number of
+     * round trips, not N round trips. Used by the recipe executor's
+     * workspace-wide prefetch to populate the path → item snapshot cache
+     * before the per-op plan loop.
+     */
+    getItemsByPaths(paths: readonly string[]): Promise<Map<string, RemoteItem | null>>;
+    /** List immediate children of `parent` (selectable by path or itemId). */
+    getChildren(parent: ItemSelector, options?: GetItemOptions): Promise<RemoteItem[]>;
+    /**
+     * Create the item at `input.parent` / `input.name`. The Authoring API
+     * assigns the itemId server-side and returns it.
+     */
+    createItem(input: CreateItemInput): Promise<CreateItemResult>;
+    updateItem(input: UpdateItemInput): Promise<void>;
+    /** Phase 4 policy `CreateUpdateAndDelete` will use this. */
+    deleteItem(selector: ItemSelector): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/recipe/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/recipe/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACtF;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC;IACnF,0EAA0E;IAC1E,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACnF;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,4DAA4D;IAC5D,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/recipe/api/client.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Authoring API client surface for recipe execution.
+ *
+ * The Sitecore Authoring API server-assigns itemIds on `createItem` —
+ * we cannot specify them. The recipe push therefore uses **paths** as
+ * the identity hook: each CreateItem op carries a deterministic path
+ * (`<templatesRoot>/<recipe.name>/...`) that the planner uses for
+ * lookup, and the `createItem` mutation returns the assigned itemId,
+ * which the executor caches in a per-run map keyed by recipe-internal
+ * uuidv5 refKey for cross-reference resolution.
+ *
+ * The IR planner and executor depend only on this interface. Production
+ * runs use `createAuthoringClient` from `./authoring-client`; tests
+ * inject a mock — same seam either way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/recipe/api/graphql.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Authoring GraphQL transport for recipe execution.
+ *
+ * Thin wrapper over `src/shared/graphql.ts` — supplies the Authoring
+ * service path and label. Parallels `src/serialization/sitecore-api/graphql.ts`
+ * which targets the Management endpoint.
+ *
+ * XM Cloud Authoring API path. If a SitecoreAI tenant ever exposes the
+ * endpoint at a different path, override via `SITECOREAI_AUTHORING_PATH`.
+ */
+import type { EnvironmentConfiguration } from "../../config";
+import { type GraphQLRequestOptions } from "../../shared/graphql";
+export type AuthoringRequestOptions = GraphQLRequestOptions;
+export declare const runAuthoringGraphQL: <T>(environment: EnvironmentConfiguration, query: string, variables?: Record<string, unknown>, options?: AuthoringRequestOptions) => Promise<T>;
+//# sourceMappingURL=graphql.d.ts.map

package/dist/recipe/api/graphql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../../../src/recipe/api/graphql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAQlF,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAc5D,eAAO,MAAM,mBAAmB,GAAI,CAAC,EACnC,aAAa,wBAAwB,EACrC,OAAO,MAAM,EACb,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,UAAU,uBAAuB,KAChC,OAAO,CAAC,CAAC,CAeT,CAAC"}

package/dist/recipe/api/graphql.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Authoring GraphQL transport for recipe execution.
+ *
+ * Thin wrapper over `src/shared/graphql.ts` — supplies the Authoring
+ * service path and label. Parallels `src/serialization/sitecore-api/graphql.ts`
+ * which targets the Management endpoint.
+ *
+ * XM Cloud Authoring API path. If a SitecoreAI tenant ever exposes the
+ * endpoint at a different path, override via `SITECOREAI_AUTHORING_PATH`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuthoringGraphQL = void 0;
+const graphql_1 = require("../../shared/graphql");
+const auth_1 = require("./auth");
+const DEFAULT_AUTHORING_PATH = "/sitecore/api/authoring/graphql/v1";
+const resolveAuthoringPath = () => process.env.SITECOREAI_AUTHORING_PATH ?? DEFAULT_AUTHORING_PATH;
+/**
+ * Authoring GraphQL retry policy. Default 5 attempts with exponential
+ * backoff + jitter (honoring `Retry-After` on 429/503). The recipe
+ * executor fans out batched reads and serial mutations against XM
+ * Cloud — both paths benefit from absorbing transient throttling /
+ * gateway hiccups without aborting the whole push. Mutation idempotency
+ * is preserved by the executor's rollback semantics: a "succeeded but
+ * lost the response" duplicate retry surfaces as "item already exists",
+ * the executor rolls back, and the operator sees the failure.
+ */
+const DEFAULT_AUTHORING_RETRY = { maxAttempts: 5 };
+const runAuthoringGraphQL = (environment, query, variables, options) => (0, graphql_1.runSitecoreGraphQL)(environment, query, variables, {
+    servicePath: resolveAuthoringPath(),
+    label: "Authoring",
+    requireToken: true,
+    getAccessToken: auth_1.getAccessToken,
+}, {
+    ...options,
+    retry: { ...DEFAULT_AUTHORING_RETRY, ...(options?.retry ?? {}) },
+});
+exports.runAuthoringGraphQL = runAuthoringGraphQL;