@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/serialization/api/auth.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAccessToken = exports.acquireAccessToken = exports.requestPasswordToken = exports.requestClientCredentialsToken = exports.DEFAULT_SITECORE_API_AUDIENCE = exports.pollDeviceToken = exports.requestDeviceAuthorization = void 0;
+const keychain_1 = require("../../shared/keychain");
+const client_credential_1 = require("../../shared/client-credential");
+const errors_1 = require("../../shared/errors");
+const DISCOVERY_TIMEOUT_MS = Math.max(0, Number(process.env.SITECOREAI_AUTH_DISCOVERY_TIMEOUT_MS ?? 5000));
+const fetchDiscovery = async (authority) => {
+    const url = `${authority.replace(/\/$/, "")}/.well-known/openid-configuration`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DISCOVERY_TIMEOUT_MS);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw (0, errors_1.createScaiError)("Identity discovery timed out.", "NETWORK", {
+                hint: "Check network connectivity or set SITECOREAI_AUTH_DISCOVERY_TIMEOUT_MS.",
+            });
+        }
+        throw (0, errors_1.createScaiError)(`Identity discovery failed: ${error instanceof Error ? error.message : String(error)}`, "NETWORK");
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+/**
+ * Defense against a tampered OpenID discovery document redirecting OAuth
+ * traffic to an attacker-controlled endpoint. The discovery URL is trusted
+ * (operator-supplied authority), but the JSON it returns is server-provided
+ * data — and a compromised authority could rewrite `token_endpoint` to point
+ * elsewhere, harvesting client credentials on every token exchange.
+ */
+const assertSameHost = (endpointUrl, authority, label) => {
+    let parsedEndpoint;
+    let parsedAuthority;
+    try {
+        parsedEndpoint = new URL(endpointUrl);
+        parsedAuthority = new URL(authority);
+    }
+    catch {
+        throw (0, errors_1.createScaiError)(`Discovery document returned an invalid ${label}: ${endpointUrl}.`, "NETWORK");
+    }
+    if (parsedEndpoint.hostname.toLowerCase() !== parsedAuthority.hostname.toLowerCase()) {
+        throw (0, errors_1.createScaiError)(`Discovery document's ${label} hostname (${parsedEndpoint.hostname}) does not match the authority hostname (${parsedAuthority.hostname}).`, "NETWORK", {
+            hint: "The OpenID discovery document may have been tampered with. Verify the authority URL or reach out to your identity provider.",
+        });
+    }
+};
+const getTokenEndpoint = async (authority) => {
+    const response = await fetchDiscovery(authority);
+    if (!response.ok) {
+        throw (0, errors_1.createScaiError)(`Failed to discover token endpoint from ${authority}.`, "NETWORK");
+    }
+    const json = (await response.json());
+    if (!json.token_endpoint) {
+        throw (0, errors_1.createScaiError)("Token endpoint not found in discovery document.", "NETWORK");
+    }
+    assertSameHost(json.token_endpoint, authority, "token_endpoint");
+    return json.token_endpoint;
+};
+const getDeviceAuthorizationEndpoint = async (authority) => {
+    const response = await fetchDiscovery(authority);
+    if (!response.ok) {
+        throw (0, errors_1.createScaiError)(`Failed to discover device authorization endpoint from ${authority}.`, "NETWORK");
+    }
+    const json = (await response.json());
+    if (json.device_authorization_endpoint) {
+        assertSameHost(json.device_authorization_endpoint, authority, "device_authorization_endpoint");
+        return json.device_authorization_endpoint;
+    }
+    return `${authority.replace(/\/$/, "")}/oauth/device/code`;
+};
+const requestToken = async (authority, params) => {
+    const tokenEndpoint = await getTokenEndpoint(authority);
+    const response = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const bodyText = await response.text();
+        let detail = bodyText;
+        try {
+            const parsed = JSON.parse(bodyText);
+            detail = parsed.error_description ?? parsed.error ?? parsed.message ?? bodyText;
+        }
+        catch {
+            // keep raw body text
+        }
+        throw (0, errors_1.createScaiError)(`Failed to obtain access token (${response.status}): ${detail || "Unknown error"}`, "AUTH_REQUIRED");
+    }
+    const json = (await response.json());
+    if (!json.access_token) {
+        throw (0, errors_1.createScaiError)("Access token was not returned by the identity server.", "AUTH_REQUIRED");
+    }
+    return {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        expiresIn: json.expires_in,
+        tokenType: json.token_type,
+    };
+};
+const requestDeviceAuthorization = async (environment, scope) => {
+    if (!environment.authority || !environment.clientId) {
+        throw (0, errors_1.createScaiError)("Authority and clientId are required for device login.", "AUTH_REQUIRED");
+    }
+    const endpoint = await getDeviceAuthorizationEndpoint(environment.authority);
+    const params = new URLSearchParams({
+        client_id: environment.clientId,
+    });
+    if (environment.audience) {
+        params.set("audience", environment.audience);
+    }
+    if (scope) {
+        params.set("scope", scope);
+    }
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const bodyText = await response.text();
+        let detail = bodyText;
+        try {
+            const parsed = JSON.parse(bodyText);
+            detail = parsed.error_description ?? parsed.error ?? parsed.message ?? bodyText;
+        }
+        catch {
+            // keep raw body text
+        }
+        throw (0, errors_1.createScaiError)(`Failed to start device login (${response.status}): ${detail || "Unknown error"}`, "AUTH_REQUIRED");
+    }
+    const json = (await response.json());
+    if (!json.device_code || !json.verification_uri) {
+        throw (0, errors_1.createScaiError)("Device authorization response was missing required fields.", "AUTH_REQUIRED");
+    }
+    return {
+        deviceCode: json.device_code,
+        userCode: json.user_code,
+        verificationUri: json.verification_uri,
+        verificationUriComplete: json.verification_uri_complete,
+        expiresIn: json.expires_in ?? 900,
+        interval: json.interval ?? 5,
+        message: json.message,
+    };
+};
+exports.requestDeviceAuthorization = requestDeviceAuthorization;
+const delay = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+const pollDeviceToken = async (environment, device) => {
+    if (!environment.authority || !environment.clientId) {
+        throw (0, errors_1.createScaiError)("Authority and clientId are required for device login.", "AUTH_REQUIRED");
+    }
+    const tokenEndpoint = await getTokenEndpoint(environment.authority);
+    const deadline = Date.now() + device.expiresIn * 1000;
+    let intervalMs = Math.max(1, device.interval) * 1000;
+    while (Date.now() < deadline) {
+        const params = new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: device.deviceCode,
+            client_id: environment.clientId,
+        });
+        if (environment.clientSecret) {
+            params.set("client_secret", environment.clientSecret);
+        }
+        const response = await fetch(tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        const bodyText = await response.text();
+        if (response.ok) {
+            const json = JSON.parse(bodyText);
+            if (!json.access_token) {
+                throw (0, errors_1.createScaiError)("Access token was not returned by the identity server.", "AUTH_REQUIRED");
+            }
+            return {
+                accessToken: json.access_token,
+                refreshToken: json.refresh_token,
+                expiresIn: json.expires_in,
+                tokenType: json.token_type,
+            };
+        }
+        let errorCode;
+        let detail = bodyText;
+        try {
+            const parsed = JSON.parse(bodyText);
+            errorCode = parsed.error;
+            detail = parsed.error_description ?? parsed.error ?? parsed.message ?? bodyText;
+        }
+        catch {
+            // keep raw body text
+        }
+        if (errorCode === "authorization_pending") {
+            await delay(intervalMs);
+            continue;
+        }
+        if (errorCode === "slow_down") {
+            intervalMs += 5000;
+            await delay(intervalMs);
+            continue;
+        }
+        if (errorCode === "access_denied") {
+            throw (0, errors_1.createScaiError)("Device login was cancelled.", "AUTH_REQUIRED");
+        }
+        if (errorCode === "expired_token") {
+            throw (0, errors_1.createScaiError)("Device login expired. Try again.", "AUTH_REQUIRED");
+        }
+        throw (0, errors_1.createScaiError)(`Failed to obtain access token (${response.status}): ${detail || "Unknown error"}`, "AUTH_REQUIRED");
+    }
+    throw (0, errors_1.createScaiError)("Device login expired. Try again.", "AUTH_REQUIRED");
+};
+exports.pollDeviceToken = pollDeviceToken;
+/**
+ * Default OAuth audience for Sitecore Cloud APIs (Deploy + Authoring +
+ * Sites). When the env profile doesn't pin an explicit `audience`,
+ * Auth0 falls back to whatever default is configured for the M2M
+ * client. Some org-scoped clients are configured with internal-only
+ * audiences they aren't authorized to mint tokens for, so we always
+ * send this audience explicitly on the request.
+ */
+exports.DEFAULT_SITECORE_API_AUDIENCE = "https://api.sitecorecloud.io";
+const requestClientCredentialsToken = async (environment, scope) => {
+    if (!environment.authority || !environment.clientId || !environment.clientSecret) {
+        throw (0, errors_1.createScaiError)("Authority, clientId, and clientSecret are required for client credentials.", "AUTH_REQUIRED");
+    }
+    const params = new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: environment.clientId,
+        client_secret: environment.clientSecret,
+        audience: environment.audience ?? exports.DEFAULT_SITECORE_API_AUDIENCE,
+    });
+    if (scope) {
+        params.set("scope", scope);
+    }
+    return requestToken(environment.authority, params);
+};
+exports.requestClientCredentialsToken = requestClientCredentialsToken;
+const requestPasswordToken = async (environment, username, password, scope) => {
+    if (!environment.authority || !environment.clientId) {
+        throw (0, errors_1.createScaiError)("Authority and clientId are required for username/password login.", "AUTH_REQUIRED");
+    }
+    const params = new URLSearchParams({
+        grant_type: "password",
+        client_id: environment.clientId,
+        username,
+        password,
+    });
+    if (environment.clientSecret) {
+        params.set("client_secret", environment.clientSecret);
+    }
+    if (environment.audience) {
+        params.set("audience", environment.audience);
+    }
+    if (scope) {
+        params.set("scope", scope);
+    }
+    return requestToken(environment.authority, params);
+};
+exports.requestPasswordToken = requestPasswordToken;
+const requestRefreshToken = async (environment) => {
+    if (!environment.authority || !environment.refreshToken) {
+        return undefined;
+    }
+    const params = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: environment.refreshToken,
+    });
+    if (environment.refreshTokenParameters) {
+        for (const [key, value] of Object.entries(environment.refreshTokenParameters)) {
+            params.set(key, String(value));
+        }
+    }
+    if (!params.has("client_id") && environment.clientId) {
+        params.set("client_id", environment.clientId);
+    }
+    if (environment.clientSecret) {
+        params.set("client_secret", environment.clientSecret);
+    }
+    if (environment.audience && !params.has("audience")) {
+        params.set("audience", environment.audience);
+    }
+    return requestToken(environment.authority, params);
+};
+/**
+ * Resolve the automation-client secret for a client-credentials mint.
+ *
+ * Per `docs/credentials.md` the env profile carries no secret. When the
+ * caller already supplied a `clientSecret` (a bring-your-own-client pair
+ * built by hand), it is used as-is. Otherwise the secret is resolved
+ * through the shared three-tier chain (`SITECOREAI_ENV_<ENV>_CLIENT_SECRET`
+ * env var → env-scoped keychain client → org-scoped keychain client),
+ * keyed by `environment.name`. The matching `clientId` is taken from the
+ * same tier that supplies the secret.
+ *
+ * Returns the environment unchanged when no secret can be resolved — the
+ * downstream OAuth call then surfaces the missing-credential error.
+ */
+const withResolvedClientCredential = async (environment) => {
+    if (environment.clientSecret) {
+        return environment;
+    }
+    if (!environment.name) {
+        return environment;
+    }
+    const credential = await (0, client_credential_1.resolveClientCredential)({
+        envName: environment.name,
+        clientId: environment.clientId,
+        automationClientId: environment.automationClient?.clientId,
+        organizationId: environment.organizationId,
+        orgClientId: environment.orgClientId,
+    });
+    if (!credential) {
+        return environment;
+    }
+    return {
+        ...environment,
+        clientId: credential.clientId,
+        clientSecret: credential.clientSecret,
+    };
+};
+/**
+ * Pure OAuth acquisition: refresh-token-on-env, then client-credentials.
+ * Does NOT touch the keychain token cache, and does NOT return the env's
+ * embedded `accessToken` literal — callers wanting the literal-or-acquired
+ * union should check `environment.accessToken` themselves first.
+ *
+ * The client-credentials mint fires whenever a `{ clientId, clientSecret }`
+ * pair resolves through the shared three-tier chain — the
+ * `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` env var (bring-your-own-client),
+ * the env-scoped automation client (`automationClient` block + the
+ * `cm-client:<env>` keychain secret), or the org-scoped automation
+ * client. A resolvable automation client IS the acquisition path: there
+ * is no separate opt-in flag. `useClientCredentials` survives only as a
+ * config-file marker for the bring-your-own-client hatch — `setup env`
+ * mints an automation client without it, and that client must still
+ * work. (This was the bug: the mint was gated on `useClientCredentials`,
+ * so a scai-minted automation client could never produce a CM token.)
+ *
+ * Resolving that pair reads the OS keychain for the long-lived client
+ * secret — the one keychain touch here; the short-lived token cache is
+ * never read or written by this function (that is `getAccessToken`'s job).
+ *
+ * Library callers (orchestrators, MCP servers, tests) that bring their
+ * own token cache should call this directly. The CLI uses `getAccessToken`
+ * which adds keychain-backed caching on top.
+ */
+const acquireAccessToken = async (environment) => {
+    const refreshed = await requestRefreshToken(environment);
+    if (refreshed?.accessToken) {
+        return refreshed;
+    }
+    const resolved = await withResolvedClientCredential(environment);
+    if (resolved.clientId && resolved.clientSecret) {
+        return (0, exports.requestClientCredentialsToken)(resolved);
+    }
+    return undefined;
+};
+exports.acquireAccessToken = acquireAccessToken;
+/**
+ * Skew applied to a cached CM token's expiry: a token within this window
+ * of expiring is treated as already stale, so it re-mints *before* the
+ * request rather than racing the clock and 401-ing mid-flight.
+ */
+const CM_TOKEN_EXPIRY_SKEW_MS = 60000;
+/**
+ * Whether a cached CM token bundle is still safe to use. Freshness is
+ * computed from `lastUpdated + expiresIn`. A bundle missing either field
+ * (legacy cache entries) is treated as usable — worst case is one 401
+ * that the next call recovers from, matching the prior behavior.
+ *
+ * The expiry check is what makes an empty / stale `cm:` slot self-heal:
+ * once the cached token lapses, `getAccessToken` falls through to
+ * `acquireAccessToken`, which re-mints from the automation client.
+ */
+const isCmTokenFresh = (bundle) => {
+    if (!bundle.expiresIn || !bundle.lastUpdated) {
+        return true;
+    }
+    const expiresAt = Date.parse(bundle.lastUpdated) + bundle.expiresIn * 1000;
+    if (Number.isNaN(expiresAt)) {
+        return true;
+    }
+    return Date.now() < expiresAt - CM_TOKEN_EXPIRY_SKEW_MS;
+};
+const getAccessToken = async (environment) => {
+    const envName = environment.name;
+    const shouldCache = environment.cacheAuthenticationToken !== false && Boolean(envName);
+    const cached = shouldCache && envName ? await (0, keychain_1.getCmTokens)(envName) : undefined;
+    if (cached?.accessToken && isCmTokenFresh(cached)) {
+        return cached.accessToken;
+    }
+    if (cached?.refreshToken) {
+        const refreshed = await requestRefreshToken({
+            ...environment,
+            refreshToken: cached.refreshToken,
+            refreshTokenParameters: cached.refreshTokenParameters,
+        });
+        if (refreshed?.accessToken) {
+            if (shouldCache && envName) {
+                await (0, keychain_1.setCmTokens)(envName, {
+                    accessToken: refreshed.accessToken,
+                    refreshToken: refreshed.refreshToken ?? cached.refreshToken,
+                    refreshTokenParameters: cached.refreshTokenParameters,
+                    expiresIn: refreshed.expiresIn,
+                    lastUpdated: new Date().toISOString(),
+                });
+            }
+            return refreshed.accessToken;
+        }
+    }
+    if (environment.accessToken) {
+        return environment.accessToken;
+    }
+    const acquired = await (0, exports.acquireAccessToken)(environment);
+    if (acquired?.accessToken) {
+        if (shouldCache && envName) {
+            await (0, keychain_1.setCmTokens)(envName, {
+                accessToken: acquired.accessToken,
+                refreshToken: acquired.refreshToken ?? environment.refreshToken,
+                refreshTokenParameters: environment.refreshTokenParameters,
+                expiresIn: acquired.expiresIn,
+                lastUpdated: new Date().toISOString(),
+            });
+        }
+        return acquired.accessToken;
+    }
+    return undefined;
+};
+exports.getAccessToken = getAccessToken;

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

@@ -0,0 +1,41 @@
+/**
+ * Production `SitecoreApiClient` factory for the Sitecore Authoring +
+ * Management GraphQL surface.
+ *
+ * Unlike `createAuthoringClient` in `recipe/` (which adds path
+ * resolution, parent-folder auto-creation, and read-retry behavior on
+ * top of the wire calls), this factory is a thin **options-binding**
+ * wrapper around the existing function-style API:
+ *
+ *   const sc = createSitecoreApiClient({ host, accessToken });
+ *   await sc.fetchItemMetadata("master", "/sitecore/content/Home");
+ *
+ * It exists so the deploy + serialization surfaces match the recipe
+ * surface's seam shape (`create*Client(options) -> typed methods`).
+ * If you don't want the seam, the underlying functions remain exported
+ * from `serialization` and you can call them options-first directly.
+ */
+import { fetchHistoryEntries, fetchHistoryTimestamp } from "./history";
+import { executeSerializationCommands, fetchItemData, fetchItemMetadata } from "./items";
+import { checkPublishStatus, fetchPublishingTargets, publishItems } from "./publish";
+import { fetchRoles, pushRoleCommands } from "./roles";
+import type { SitecoreApiClientOptions } from "./types";
+import { fetchUsers, pushUserCommands } from "./users";
+type Tail<F> = F extends (head: SitecoreApiClientOptions, ...rest: infer R) => infer X ? (...args: R) => X : never;
+export interface SitecoreApiClient {
+    readonly options: SitecoreApiClientOptions;
+    fetchItemMetadata: Tail<typeof fetchItemMetadata>;
+    fetchItemData: Tail<typeof fetchItemData>;
+    executeSerializationCommands: Tail<typeof executeSerializationCommands>;
+    fetchHistoryTimestamp: Tail<typeof fetchHistoryTimestamp>;
+    fetchHistoryEntries: Tail<typeof fetchHistoryEntries>;
+    fetchRoles: Tail<typeof fetchRoles>;
+    pushRoleCommands: Tail<typeof pushRoleCommands>;
+    fetchUsers: Tail<typeof fetchUsers>;
+    pushUserCommands: Tail<typeof pushUserCommands>;
+    publishItems: Tail<typeof publishItems>;
+    checkPublishStatus: Tail<typeof checkPublishStatus>;
+    fetchPublishingTargets: Tail<typeof fetchPublishingTargets>;
+}
+export declare const createSitecoreApiClient: (options: SitecoreApiClientOptions) => SitecoreApiClient;
+export {};

package/dist/serialization/api/client.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSitecoreApiClient = void 0;
+/**
+ * Production `SitecoreApiClient` factory for the Sitecore Authoring +
+ * Management GraphQL surface.
+ *
+ * Unlike `createAuthoringClient` in `recipe/` (which adds path
+ * resolution, parent-folder auto-creation, and read-retry behavior on
+ * top of the wire calls), this factory is a thin **options-binding**
+ * wrapper around the existing function-style API:
+ *
+ *   const sc = createSitecoreApiClient({ host, accessToken });
+ *   await sc.fetchItemMetadata("master", "/sitecore/content/Home");
+ *
+ * It exists so the deploy + serialization surfaces match the recipe
+ * surface's seam shape (`create*Client(options) -> typed methods`).
+ * If you don't want the seam, the underlying functions remain exported
+ * from `serialization` and you can call them options-first directly.
+ */
+const history_1 = require("./history");
+const items_1 = require("./items");
+const publish_1 = require("./publish");
+const roles_1 = require("./roles");
+const users_1 = require("./users");
+const createSitecoreApiClient = (options) => ({
+    options,
+    fetchItemMetadata: (database, path, ...rest) => (0, items_1.fetchItemMetadata)(options, database, path, ...rest),
+    fetchItemData: (database, path, ...rest) => (0, items_1.fetchItemData)(options, database, path, ...rest),
+    executeSerializationCommands: (commands, ...rest) => (0, items_1.executeSerializationCommands)(options, commands, ...rest),
+    fetchHistoryTimestamp: (...rest) => (0, history_1.fetchHistoryTimestamp)(options, ...rest),
+    fetchHistoryEntries: (timestamp, ...rest) => (0, history_1.fetchHistoryEntries)(options, timestamp, ...rest),
+    fetchRoles: (predicates, ...rest) => (0, roles_1.fetchRoles)(options, predicates, ...rest),
+    pushRoleCommands: (commands, ...rest) => (0, roles_1.pushRoleCommands)(options, commands, ...rest),
+    fetchUsers: (predicates, ...rest) => (0, users_1.fetchUsers)(options, predicates, ...rest),
+    pushUserCommands: (commands, ...rest) => (0, users_1.pushUserCommands)(options, commands, ...rest),
+    publishItems: (itemIds, ...rest) => (0, publish_1.publishItems)(options, itemIds, ...rest),
+    checkPublishStatus: (publishId, ...rest) => (0, publish_1.checkPublishStatus)(options, publishId, ...rest),
+    fetchPublishingTargets: (...rest) => (0, publish_1.fetchPublishingTargets)(options, ...rest),
+});
+exports.createSitecoreApiClient = createSitecoreApiClient;

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

@@ -0,0 +1,11 @@
+/**
+ * Management GraphQL transport for serialization commands.
+ *
+ * Thin wrapper over `src/shared/graphql.ts` — supplies the Management
+ * service path and label. Parallels `src/recipe/api/graphql.ts` which
+ * targets the Authoring endpoint.
+ */
+import type { SitecoreApiClientOptions } from "./types";
+import { type GraphQLRequestOptions } from "../../shared/graphql";
+export type { GraphQLRequestOptions };
+export declare const runGraphQL: <T>(environment: SitecoreApiClientOptions, query: string, variables?: Record<string, unknown>, options?: GraphQLRequestOptions) => Promise<T>;

package/dist/serialization/api/history.d.ts

@@ -0,0 +1,8 @@
+import type { SitecoreApiClientOptions } from "./types";
+import { HistoryEntry } from "../types";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchHistoryTimestamp: (environment: SitecoreApiClientOptions, options?: GraphQLRequestOptions) => Promise<string>;
+export declare const fetchHistoryEntries: (environment: SitecoreApiClientOptions, timestamp: string, options?: GraphQLRequestOptions) => Promise<{
+    timestamp: string;
+    entries: HistoryEntry[];
+}>;

package/dist/serialization/api/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Curated public Sitecore Management + Authoring GraphQL client surface —
+ * re-exported by `../index.ts`
+ * (`@sitecoreai-labs/sitecoreai-cli/serialization`).
+ *
+ * Source of truth for what's part of the public Sitecore Management +
+ * Authoring GraphQL client surface. Every symbol below is intentional.
+ *
+ * Internal scai callers should keep importing from sibling files
+ * (`./auth`, `./graphql`, etc.) for unstable helpers; this index file
+ * is the only path that's contract-stable.
+ */
+export type { SitecoreApiClientOptions } from "./types";
+export { createSitecoreApiClient, type SitecoreApiClient } from "./client";
+export { runGraphQL, type GraphQLRequestOptions } from "./graphql";
+export { acquireAccessToken, getAccessToken, requestClientCredentialsToken, requestPasswordToken, requestDeviceAuthorization, pollDeviceToken, DEFAULT_SITECORE_API_AUDIENCE, type AccessTokenResult, type DeviceAuthorizationResult, } from "./auth";
+export { fetchItemMetadata, fetchItemData, executeSerializationCommands } from "./items";
+export { fetchHistoryTimestamp, fetchHistoryEntries } from "./history";
+export { fetchRoles, pushRoleCommands } from "./roles";
+export { fetchUsers, pushUserCommands } from "./users";
+export { publishItems, checkPublishStatus, fetchPublishingTargets, publishItemSubtree, type PublishItemSubtreeResult, } from "./publish";
+export type { ItemData, ItemMetadata, ItemLanguage, ItemVersion, ItemFieldValue, FieldFilter, RoleData, UserData, HistoryEntry, RolePredicateItem, UserPredicateItem, } from "../types";
+export { ItemPath } from "../item-path";

package/dist/serialization/api/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Curated public Sitecore Management + Authoring GraphQL client surface —
+ * re-exported by `../index.ts`
+ * (`@sitecoreai-labs/sitecoreai-cli/serialization`).
+ *
+ * Source of truth for what's part of the public Sitecore Management +
+ * Authoring GraphQL client surface. Every symbol below is intentional.
+ *
+ * Internal scai callers should keep importing from sibling files
+ * (`./auth`, `./graphql`, etc.) for unstable helpers; this index file
+ * is the only path that's contract-stable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ItemPath = exports.publishItemSubtree = exports.fetchPublishingTargets = exports.checkPublishStatus = exports.publishItems = exports.pushUserCommands = exports.fetchUsers = exports.pushRoleCommands = exports.fetchRoles = exports.fetchHistoryEntries = exports.fetchHistoryTimestamp = exports.executeSerializationCommands = exports.fetchItemData = exports.fetchItemMetadata = exports.DEFAULT_SITECORE_API_AUDIENCE = exports.pollDeviceToken = exports.requestDeviceAuthorization = exports.requestPasswordToken = exports.requestClientCredentialsToken = exports.getAccessToken = exports.acquireAccessToken = exports.runGraphQL = exports.createSitecoreApiClient = void 0;
+// --- Curated client seam ------------------------------------------------
+//
+// `createSitecoreApiClient(options)` returns a typed, options-bound
+// facade over the function-style item / history / roles / users /
+// publish surface — parallels `createDeployApiClient` and
+// `createSitesApiClient`. The underlying functions remain exported
+// below for direct use.
+var client_1 = require("./client");
+Object.defineProperty(exports, "createSitecoreApiClient", { enumerable: true, get: function () { return client_1.createSitecoreApiClient; } });
+// --- Transport seam ------------------------------------------------------
+var graphql_1 = require("./graphql");
+Object.defineProperty(exports, "runGraphQL", { enumerable: true, get: function () { return graphql_1.runGraphQL; } });
+// --- Auth ----------------------------------------------------------------
+// `acquireAccessToken` is the pure OAuth flow (no keychain) added in
+// Phase A; library consumers that bring their own token cache should
+// use it. `getAccessToken` is the CLI-shaped keychain-aware wrapper.
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "acquireAccessToken", { enumerable: true, get: function () { return auth_1.acquireAccessToken; } });
+Object.defineProperty(exports, "getAccessToken", { enumerable: true, get: function () { return auth_1.getAccessToken; } });
+Object.defineProperty(exports, "requestClientCredentialsToken", { enumerable: true, get: function () { return auth_1.requestClientCredentialsToken; } });
+Object.defineProperty(exports, "requestPasswordToken", { enumerable: true, get: function () { return auth_1.requestPasswordToken; } });
+Object.defineProperty(exports, "requestDeviceAuthorization", { enumerable: true, get: function () { return auth_1.requestDeviceAuthorization; } });
+Object.defineProperty(exports, "pollDeviceToken", { enumerable: true, get: function () { return auth_1.pollDeviceToken; } });
+Object.defineProperty(exports, "DEFAULT_SITECORE_API_AUDIENCE", { enumerable: true, get: function () { return auth_1.DEFAULT_SITECORE_API_AUDIENCE; } });
+// --- Item operations -----------------------------------------------------
+var items_1 = require("./items");
+Object.defineProperty(exports, "fetchItemMetadata", { enumerable: true, get: function () { return items_1.fetchItemMetadata; } });
+Object.defineProperty(exports, "fetchItemData", { enumerable: true, get: function () { return items_1.fetchItemData; } });
+Object.defineProperty(exports, "executeSerializationCommands", { enumerable: true, get: function () { return items_1.executeSerializationCommands; } });
+// --- History (poll for remote changes) ----------------------------------
+var history_1 = require("./history");
+Object.defineProperty(exports, "fetchHistoryTimestamp", { enumerable: true, get: function () { return history_1.fetchHistoryTimestamp; } });
+Object.defineProperty(exports, "fetchHistoryEntries", { enumerable: true, get: function () { return history_1.fetchHistoryEntries; } });
+// --- Roles ---------------------------------------------------------------
+var roles_1 = require("./roles");
+Object.defineProperty(exports, "fetchRoles", { enumerable: true, get: function () { return roles_1.fetchRoles; } });
+Object.defineProperty(exports, "pushRoleCommands", { enumerable: true, get: function () { return roles_1.pushRoleCommands; } });
+// --- Users ---------------------------------------------------------------
+var users_1 = require("./users");
+Object.defineProperty(exports, "fetchUsers", { enumerable: true, get: function () { return users_1.fetchUsers; } });
+Object.defineProperty(exports, "pushUserCommands", { enumerable: true, get: function () { return users_1.pushUserCommands; } });
+// --- Publishing ---------------------------------------------------------
+var publish_1 = require("./publish");
+Object.defineProperty(exports, "publishItems", { enumerable: true, get: function () { return publish_1.publishItems; } });
+Object.defineProperty(exports, "checkPublishStatus", { enumerable: true, get: function () { return publish_1.checkPublishStatus; } });
+Object.defineProperty(exports, "fetchPublishingTargets", { enumerable: true, get: function () { return publish_1.fetchPublishingTargets; } });
+Object.defineProperty(exports, "publishItemSubtree", { enumerable: true, get: function () { return publish_1.publishItemSubtree; } });
+var item_path_1 = require("../item-path");
+Object.defineProperty(exports, "ItemPath", { enumerable: true, get: function () { return item_path_1.ItemPath; } });

package/dist/serialization/api/items.d.ts

@@ -0,0 +1,7 @@
+import { ItemData, ItemMetadata } from "../types";
+import type { SitecoreApiClientOptions } from "./types";
+import { FieldFilterSet } from "../field-filter";
+import { GraphQLRequestOptions } from "./graphql";
+export declare const fetchItemMetadata: (environment: SitecoreApiClientOptions, database: string, pathOrId: string, scope: string, fieldFilter: FieldFilterSet, useDebugSignatures: boolean, options?: GraphQLRequestOptions) => Promise<ItemMetadata[]>;
+export declare const fetchItemData: (environment: SitecoreApiClientOptions, database: string, pathOrId: string, scope: string, fieldFilter: FieldFilterSet, options?: GraphQLRequestOptions) => Promise<ItemData[]>;
+export declare const executeSerializationCommands: (environment: SitecoreApiClientOptions, commands: unknown[], minimumLogLevel: string, options?: GraphQLRequestOptions) => Promise<unknown[]>;