@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/agents/tasks/resources.d.ts

@@ -0,0 +1,39 @@
+import { type RunAgentsBaseOptions } from "./shared";
+/** The runner set every non-agent resource exposes. */
+export interface ResourceTasks {
+    /** Whether `update` hits a verified endpoint (drives the `--unverified` gate). */
+    updateVerified: boolean;
+    /** Whether `delete` hits a verified endpoint (drives the `--unverified` gate). */
+    deleteVerified: boolean;
+    runList: (options: RunAgentsBaseOptions) => Promise<void>;
+    runGet: (options: RunAgentsBaseOptions & {
+        idOrName: string;
+    }) => Promise<void>;
+    runCreate: (options: RunAgentsBaseOptions & {
+        file: string;
+        whatIf?: boolean;
+    }) => Promise<void>;
+    runUpdate: (options: RunAgentsBaseOptions & {
+        idOrName: string;
+        file: string;
+        unverified?: boolean;
+        whatIf?: boolean;
+    }) => Promise<void>;
+    runDelete: (options: RunAgentsBaseOptions & {
+        idOrName: string;
+        unverified?: boolean;
+        whatIf?: boolean;
+    }) => Promise<void>;
+}
+/** `scai agents skill …` */
+export declare const skillTasks: ResourceTasks;
+/** `scai agents widget …` */
+export declare const widgetTasks: ResourceTasks;
+/** `scai agents schema …` */
+export declare const schemaTasks: ResourceTasks;
+/** `scai agents mcp …` — registered custom MCP servers. */
+export declare const mcpTasks: ResourceTasks;
+/** `scai agents html-template …` */
+export declare const htmlTemplateTasks: ResourceTasks;
+/** `scai agents tool list` — the tool catalog is read-only (no write path). */
+export declare const runToolList: (options: RunAgentsBaseOptions) => Promise<void>;

package/dist/agents/tasks/resources.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runToolList = exports.htmlTemplateTasks = exports.mcpTasks = exports.schemaTasks = exports.widgetTasks = exports.skillTasks = void 0;
+const sync_1 = require("../../sync");
+const errors_1 = require("../../shared/errors");
+const custom_mcps_1 = require("../api/custom-mcps");
+const html_templates_1 = require("../api/html-templates");
+const schemas_1 = require("../api/schemas");
+const skills_1 = require("../api/skills");
+const widgets_1 = require("../api/widgets");
+const tools_1 = require("../api/tools");
+const custom_mcp_schema_1 = require("../recipe/custom-mcp.schema");
+const html_template_schema_1 = require("../recipe/html-template.schema");
+const schema_schema_1 = require("../recipe/schema.schema");
+const skill_schema_1 = require("../recipe/skill.schema");
+const widget_schema_1 = require("../recipe/widget.schema");
+const shared_1 = require("./shared");
+const makeResourceTasks = (config) => {
+    const notFound = (idOrName) => (0, errors_1.createScaiError)(`No ${config.resource} matching "${idOrName}".`, "INPUT_INVALID", {
+        hint: `List them with \`scai agents ${config.resource} list\`.`,
+    });
+    const runList = async (options) => {
+        const { logger, session } = await (0, shared_1.prepare)(options);
+        (0, shared_1.renderList)(logger, config.pluralLabel, await config.list(session), config.line);
+    };
+    const runGet = async (options) => {
+        const { logger, session } = await (0, shared_1.prepare)(options);
+        const item = await config.find(session, options.idOrName);
+        if (!item)
+            throw notFound(options.idOrName);
+        (0, shared_1.renderItem)(logger, `${config.resource} "${config.identify(item).name}"`, item);
+    };
+    const runCreate = async (options) => {
+        const { logger, session } = await (0, shared_1.prepare)(options);
+        const recipe = (0, sync_1.loadRecipe)(options.file, config.schema);
+        if (await config.find(session, recipe.name)) {
+            throw (0, errors_1.createScaiError)(`A ${config.resource} named "${recipe.name}" already exists.`, "INPUT_INVALID", { hint: `Pick a different name, or use \`scai agents ${config.resource} update\`.` });
+        }
+        if (options.whatIf) {
+            if (logger.isJson())
+                (0, shared_1.writeJson)({ plan: { create: recipe.name } });
+            else
+                logger.info(`Would create ${config.resource} "${recipe.name}".`, "yellow");
+            return;
+        }
+        const created = await config.create(session, recipe);
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ ok: true, created });
+        else
+            logger.info(`Created ${config.resource} "${recipe.name}".`, "green");
+    };
+    const runUpdate = async (options) => {
+        if (!config.updateVerified) {
+            (0, shared_1.requireUnverified)(options.unverified, config.resource, "update");
+        }
+        const { logger, session } = await (0, shared_1.prepare)(options);
+        const recipe = (0, sync_1.loadRecipe)(options.file, config.schema);
+        let id;
+        if (config.resolveById) {
+            id = options.idOrName;
+        }
+        else {
+            const item = await config.find(session, options.idOrName);
+            if (!item)
+                throw notFound(options.idOrName);
+            id = config.identify(item).id;
+        }
+        if (options.whatIf) {
+            if (logger.isJson())
+                (0, shared_1.writeJson)({ plan: { update: id } });
+            else
+                logger.info(`Would update ${config.resource} "${options.idOrName}" (${id}).`, "yellow");
+            return;
+        }
+        await config.update(session, id, recipe);
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ ok: true, updated: id });
+        else
+            logger.info(`Updated ${config.resource} (${id}).`, "green");
+    };
+    const runDelete = async (options) => {
+        if (!config.deleteVerified) {
+            (0, shared_1.requireUnverified)(options.unverified, config.resource, "delete");
+        }
+        const { logger, session } = await (0, shared_1.prepare)(options);
+        let id;
+        let name;
+        if (config.resolveById) {
+            id = options.idOrName;
+            name = options.idOrName;
+        }
+        else {
+            const item = await config.find(session, options.idOrName);
+            if (!item)
+                throw notFound(options.idOrName);
+            ({ id, name } = config.identify(item));
+        }
+        if (options.whatIf) {
+            if (logger.isJson())
+                (0, shared_1.writeJson)({ plan: { delete: id } });
+            else
+                logger.info(`Would delete ${config.resource} "${name}" (${id}).`, "yellow");
+            return;
+        }
+        await config.remove(session, id);
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ ok: true, deleted: id });
+        else
+            logger.info(`Deleted ${config.resource} "${name}".`, "green");
+    };
+    return {
+        updateVerified: config.updateVerified,
+        deleteVerified: config.deleteVerified,
+        runList,
+        runGet,
+        runCreate,
+        runUpdate,
+        runDelete,
+    };
+};
+/** `scai agents skill …` */
+exports.skillTasks = makeResourceTasks({
+    resource: "skill",
+    pluralLabel: "skill(s)",
+    schema: skill_schema_1.SkillRecipeSchema,
+    list: skills_1.listSkills,
+    find: skills_1.getSkill,
+    identify: (skill) => ({ id: skill.id, name: skill.name }),
+    line: (skill) => `${skill.slug.padEnd(30)} ${skill.name}`,
+    create: (session, recipe) => (0, skills_1.createSkill)(session, recipe),
+    update: (session, id, recipe) => (0, skills_1.updateSkill)(session, { id, ...recipe }),
+    remove: skills_1.deleteSkill,
+    // Verified 2026-05-17 against agentic-studio-euw — PUT/DELETE both work.
+    updateVerified: true,
+    deleteVerified: true,
+});
+/** `scai agents widget …` */
+exports.widgetTasks = makeResourceTasks({
+    resource: "widget",
+    pluralLabel: "widget(s)",
+    schema: widget_schema_1.WidgetRecipeSchema,
+    list: widgets_1.listWidgets,
+    find: widgets_1.getWidget,
+    identify: (widget) => ({ id: widget.id, name: widget.name }),
+    line: (widget) => `${widget.id.padEnd(38)} ${widget.name}`,
+    create: (session, recipe) => (0, widgets_1.createWidget)(session, recipe),
+    update: (session, id, recipe) => (0, widgets_1.updateWidget)(session, { id, ...recipe }),
+    remove: widgets_1.deleteWidget,
+    // Verified 2026-05-17 against agentic-studio-euw — PUT/DELETE both work.
+    updateVerified: true,
+    deleteVerified: true,
+});
+/** `scai agents schema …` */
+exports.schemaTasks = makeResourceTasks({
+    resource: "schema",
+    pluralLabel: "schema(s)",
+    schema: schema_schema_1.SchemaRecipeSchema,
+    list: schemas_1.listSchemas,
+    find: schemas_1.getSchema,
+    identify: (schema) => ({
+        id: String(schema.id ?? schema.schemaId ?? schema.name),
+        name: schema.name,
+    }),
+    line: (schema) => `${String(schema.id ?? schema.schemaId ?? "?").padEnd(38)} ${schema.name}`,
+    create: (session, recipe) => (0, schemas_1.createSchema)(session, recipe),
+    update: (session, id, recipe) => (0, schemas_1.updateSchema)(session, { id, ...recipe }),
+    remove: schemas_1.deleteSchema,
+    // Verified 2026-05-17: `update` re-runs the create server action (an
+    // upsert by name — works). `delete` has no endpoint — DELETE → 405.
+    updateVerified: true,
+    deleteVerified: false,
+});
+/** `scai agents mcp …` — registered custom MCP servers. */
+exports.mcpTasks = makeResourceTasks({
+    resource: "mcp",
+    pluralLabel: "custom MCP(s)",
+    schema: custom_mcp_schema_1.CustomMcpRecipeSchema,
+    list: custom_mcps_1.listCustomMcps,
+    find: custom_mcps_1.getCustomMcp,
+    identify: (mcp) => ({ id: mcp.id, name: mcp.name }),
+    line: (mcp) => `${mcp.name.padEnd(24)} ${mcp.url}`,
+    create: (session, recipe) => (0, custom_mcps_1.createCustomMcp)(session, recipe),
+    update: (session, id, recipe) => (0, custom_mcps_1.updateCustomMcp)(session, { id, ...recipe }),
+    remove: custom_mcps_1.deleteCustomMcp,
+    // Verified 2026-05-17: DELETE works; a custom MCP has no update at all
+    // (PUT → 405; re-POST duplicates instead of upserting).
+    updateVerified: false,
+    deleteVerified: true,
+});
+/** `scai agents html-template …` */
+exports.htmlTemplateTasks = makeResourceTasks({
+    resource: "html-template",
+    pluralLabel: "HTML template(s)",
+    schema: html_template_schema_1.HtmlTemplateRecipeSchema,
+    list: html_templates_1.listHtmlTemplates,
+    find: html_templates_1.getHtmlTemplate,
+    identify: (template) => ({
+        id: template.id,
+        name: template.name ?? template.templateId ?? template.id,
+    }),
+    line: (template) => `${template.id.padEnd(38)} ${template.name ?? template.templateId ?? ""}`,
+    create: (session, recipe) => (0, html_templates_1.createHtmlTemplate)(session, recipe),
+    update: (session, id, recipe) => (0, html_templates_1.updateHtmlTemplate)(session, { id, ...recipe }),
+    remove: html_templates_1.deleteHtmlTemplate,
+    // 2026-05-17: `GET /api/html-templates` is 404 — no list/read path — so a
+    // template can only be addressed by id (`resolveById`). `update` replays
+    // the captured `updateHtmlTemplateAction` server action; it is wired from
+    // a live recording but not yet run through the CLI, so stays gated.
+    // `delete` has no captured endpoint.
+    updateVerified: false,
+    deleteVerified: false,
+    resolveById: true,
+});
+/** `scai agents tool list` — the tool catalog is read-only (no write path). */
+const runToolList = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    (0, shared_1.renderList)(logger, "tool(s)", await (0, tools_1.listTools)(session), (tool) => `${tool.toolKey.padEnd(30)} ${tool.category.padEnd(12)} ${tool.label}`);
+};
+exports.runToolList = runToolList;

package/dist/agents/tasks/session.d.ts

@@ -0,0 +1,6 @@
+import { type RunAgentsBaseOptions } from "./shared";
+export declare const runAgentsLogin: (options: RunAgentsBaseOptions & {
+    region?: string;
+}) => Promise<void>;
+export declare const runAgentsLogout: (options: RunAgentsBaseOptions) => Promise<void>;
+export declare const runAgentsStatus: (options: RunAgentsBaseOptions) => Promise<void>;

package/dist/agents/tasks/session.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentsStatus = exports.runAgentsLogout = exports.runAgentsLogin = void 0;
+/**
+ * `scai agents login | logout | status` — Agentic Studio session
+ * management. `login` drives a headed-browser Playwright capture;
+ * `logout` clears the keychain entry; `status` probes `/api/token-refresh`.
+ */
+const environment_1 = require("../../policy/environment");
+const region_1 = require("../../shared/region");
+const auth_1 = require("../../serialization/api/auth");
+const session_1 = require("../session");
+const request_1 = require("../api/request");
+const shared_1 = require("./shared");
+const runAgentsLogin = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, environment } = (0, environment_1.resolveEnvironment)(options);
+    // Region selects which `agentic-studio-<region>` BFF the browser
+    // login targets. An explicit `--region` wins; otherwise it is
+    // resolved from the org id via the shared resolver — best-effort, so
+    // a credential-less env falls back to EU-West.
+    const region = options.region ??
+        (await (0, region_1.resolveRegionCode)({
+            organizationId: environment.organizationId,
+            acquireToken: async () => (await (0, auth_1.requestClientCredentialsToken)(environment)).accessToken,
+        }));
+    logger.info("Opening a browser — sign in to Sitecore in the window…", "cyan");
+    const result = await (0, session_1.loginAgents)({ envName, region });
+    if (logger.isJson()) {
+        (0, shared_1.writeJson)({ ok: true, envName, ...result });
+        return;
+    }
+    logger.info(`Agentic Studio session captured for "${envName}" (region ${result.region}).`, "green");
+};
+exports.runAgentsLogin = runAgentsLogin;
+const runAgentsLogout = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName } = (0, environment_1.resolveEnvironment)(options);
+    const cleared = await (0, session_1.logoutAgents)(envName);
+    if (logger.isJson()) {
+        (0, shared_1.writeJson)({ ok: cleared, envName });
+        return;
+    }
+    logger.info(cleared
+        ? `Cleared the Agentic Studio session for "${envName}".`
+        : `No Agentic Studio session was stored for "${envName}".`, cleared ? "green" : "yellow");
+};
+exports.runAgentsLogout = runAgentsLogout;
+const runAgentsStatus = async (options) => {
+    const { logger, session, envName } = await (0, shared_1.prepare)(options);
+    const refresh = await (0, request_1.agentsRequest)(session, "/api/token-refresh");
+    const valid = refresh?.success !== false;
+    if (logger.isJson()) {
+        (0, shared_1.writeJson)({ envName, endpoint: session.baseUrl, valid, expiresAt: refresh?.expiresAt });
+        return;
+    }
+    logger.info(`Agentic Studio — ${envName}`, "cyan");
+    logger.info(`  Endpoint: ${session.baseUrl}`);
+    logger.info(`  Session:  ${valid ? "valid" : "invalid"}`);
+    if (refresh?.expiresAt)
+        logger.info(`  Token expires: ${refresh.expiresAt}`);
+};
+exports.runAgentsStatus = runAgentsStatus;

package/dist/agents/tasks/shared.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared plumbing for the `scai agents …` task runners.
+ *
+ * Every runner resolves the environment, loads the keychain-backed
+ * Agentic Studio session, calls a library helper, then prints human or
+ * JSON output. The helpers here keep that boilerplate in one place.
+ */
+import { Logger } from "../../shared/logger";
+import type { AgentsSession } from "../session/types";
+/** The option bag every `agents` runner accepts (env + verbosity flags). */
+export interface RunAgentsBaseOptions {
+    config?: string;
+    environmentName?: string;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+}
+export declare const toLogger: (options: RunAgentsBaseOptions) => Logger;
+/** Write a value as pretty JSON to stdout (used by `--json` output paths). */
+export declare const writeJson: (value: unknown) => void;
+/** Resolve the env and load its Agentic Studio session. */
+export declare const prepare: (options: RunAgentsBaseOptions) => Promise<{
+    logger: Logger;
+    session: AgentsSession;
+    envName: string;
+}>;
+/** Shared list rendering — JSON passthrough or one line per item. */
+export declare const renderList: <T>(logger: Logger, label: string, items: T[], line: (item: T) => string) => void;
+/** Shared single-item rendering — JSON passthrough or a flat key/value list. */
+export declare const renderItem: (logger: Logger, label: string, item: Record<string, unknown>) => void;
+/**
+ * Gate an UNVERIFIED write (update / delete on a resource whose endpoint
+ * has not been observed in a HAR). Throws unless the operator opted in
+ * with `--unverified`. See docs/agentic-studio-har-capture.md.
+ */
+export declare const requireUnverified: (unverified: boolean | undefined, resource: string, verb: "update" | "delete") => void;

package/dist/agents/tasks/shared.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireUnverified = exports.renderItem = exports.renderList = exports.prepare = exports.writeJson = exports.toLogger = void 0;
+/**
+ * Shared plumbing for the `scai agents …` task runners.
+ *
+ * Every runner resolves the environment, loads the keychain-backed
+ * Agentic Studio session, calls a library helper, then prints human or
+ * JSON output. The helpers here keep that boilerplate in one place.
+ */
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const client_1 = require("../client");
+const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+exports.toLogger = toLogger;
+/** Write a value as pretty JSON to stdout (used by `--json` output paths). */
+const writeJson = (value) => {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+exports.writeJson = writeJson;
+/** Resolve the env and load its Agentic Studio session. */
+const prepare = async (options) => {
+    const logger = (0, exports.toLogger)(options);
+    const { session, envName } = await (0, client_1.resolveAgentsSession)(options);
+    return { logger, session, envName };
+};
+exports.prepare = prepare;
+/** Shared list rendering — JSON passthrough or one line per item. */
+const renderList = (logger, label, items, line) => {
+    if (logger.isJson()) {
+        (0, exports.writeJson)(items);
+        return;
+    }
+    if (items.length === 0) {
+        logger.info(`No ${label} found.`, "yellow");
+        return;
+    }
+    logger.info(`${items.length} ${label}:`, "cyan");
+    for (const item of items) {
+        logger.info(`  ${line(item)}`);
+    }
+};
+exports.renderList = renderList;
+/** Shared single-item rendering — JSON passthrough or a flat key/value list. */
+const renderItem = (logger, label, item) => {
+    if (logger.isJson()) {
+        (0, exports.writeJson)(item);
+        return;
+    }
+    logger.info(`${label}:`, "cyan");
+    for (const [key, value] of Object.entries(item)) {
+        const rendered = value !== null && typeof value === "object" ? JSON.stringify(value) : String(value);
+        logger.info(`  ${key}: ${rendered}`);
+    }
+};
+exports.renderItem = renderItem;
+/**
+ * Gate an UNVERIFIED write (update / delete on a resource whose endpoint
+ * has not been observed in a HAR). Throws unless the operator opted in
+ * with `--unverified`. See docs/agentic-studio-har-capture.md.
+ */
+const requireUnverified = (unverified, resource, verb) => {
+    if (unverified)
+        return;
+    throw (0, errors_1.createScaiError)(`Agentic Studio exposes no verified ${verb} endpoint for ${resource}s.`, "INPUT_INVALID", {
+        hint: `scai wires ${verb} as a best-guess REST call, but it is UNVERIFIED and ` +
+            `may fail or hit the wrong endpoint. Re-run with --unverified to attempt ` +
+            `it against a live tenant. See docs/agentic-studio-har-capture.md to ` +
+            `capture the real request and stabilize it.`,
+    });
+};
+exports.requireUnverified = requireUnverified;

package/dist/agents/tasks/space.d.ts

@@ -0,0 +1,12 @@
+import { type RunAgentsBaseOptions } from "./shared";
+export declare const runSpaceGet: (options: RunAgentsBaseOptions & {
+    spaceId: string;
+}) => Promise<void>;
+export declare const runSpaceArtifacts: (options: RunAgentsBaseOptions & {
+    spaceId: string;
+}) => Promise<void>;
+export declare const runSpaceUpdate: (options: RunAgentsBaseOptions & {
+    spaceId: string;
+    file: string;
+    whatIf?: boolean;
+}) => Promise<void>;

package/dist/agents/tasks/space.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSpaceUpdate = exports.runSpaceArtifacts = exports.runSpaceGet = void 0;
+/**
+ * `scai agents space …` — read and update Agentic Studio spaces (the
+ * container a run executes in).
+ *
+ * A space has no list or delete endpoint, but its config and run
+ * artifacts are readable and its config is writable — see `api/spaces.ts`.
+ * `update` shallow-merges a patch file into the live config, so renaming
+ * (`spaceName`) or changing agents / `globalContext` only needs the
+ * changed keys.
+ */
+const zod_1 = require("zod");
+const sync_1 = require("../../sync");
+const spaces_1 = require("../api/spaces");
+const shared_1 = require("./shared");
+/** A space-config patch file — any object; merged onto the live config. */
+const SpaceConfigPatchSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+const runSpaceGet = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const config = await (0, spaces_1.getSpaceConfig)(session, options.spaceId);
+    (0, shared_1.renderItem)(logger, `space ${options.spaceId}`, config);
+};
+exports.runSpaceGet = runSpaceGet;
+const runSpaceArtifacts = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const artifacts = await (0, spaces_1.getSpaceArtifacts)(session, options.spaceId);
+    if (logger.isJson()) {
+        (0, shared_1.writeJson)(artifacts);
+        return;
+    }
+    (0, shared_1.renderItem)(logger, `space ${options.spaceId} artifacts`, artifacts);
+};
+exports.runSpaceArtifacts = runSpaceArtifacts;
+const runSpaceUpdate = async (options) => {
+    const { logger, session } = await (0, shared_1.prepare)(options);
+    const patch = (0, sync_1.loadRecipe)(options.file, SpaceConfigPatchSchema);
+    const current = await (0, spaces_1.getSpaceConfig)(session, options.spaceId);
+    const merged = { ...current, ...patch };
+    if (options.whatIf) {
+        const fields = Object.keys(patch).join(", ") || "(none)";
+        if (logger.isJson())
+            (0, shared_1.writeJson)({ plan: { update: options.spaceId, fields: Object.keys(patch) } });
+        else
+            logger.info(`Would update space ${options.spaceId} — fields: ${fields}.`, "yellow");
+        return;
+    }
+    await (0, spaces_1.updateSpaceConfig)(session, options.spaceId, merged);
+    if (logger.isJson())
+        (0, shared_1.writeJson)({ ok: true, updated: options.spaceId });
+    else
+        logger.info(`Updated space ${options.spaceId}.`, "green");
+};
+exports.runSpaceUpdate = runSpaceUpdate;

package/dist/brand/api/auth.d.ts

@@ -0,0 +1,58 @@
+import type { BrandCredential } from "../../config/types";
+/**
+ * OAuth scopes scai's *currently shipped* Brand operations require.
+ *
+ * The AI APIs key can carry any of:
+ *
+ *   - `ai.org.brd:r`  / `ai.org.brd:w`   — Brand Management read/write
+ *   - `ai.org.docs:r` / `ai.org.docs:w`  — Documents read/write
+ *   - `ai.org.br:gen`                    — Brand Review generate
+ *     (NB: the OpenAPI YAML example shows `ai.orgs.br:gen` with a
+ *     plural `orgs`; verified empirically 2026-05-14 the real scope
+ *     is singular `org`. Docs typo, not a scope-name variant.)
+ *   - `ai.org:admin`                     — org-level admin
+ *
+ * Real-world quirk (verified 2026-05-14): AI APIs keys in Cloud Portal
+ * are issued with **per-key scope subsets**, not the full grant set.
+ * An operator can paste a credential that has `ai.org.brd:r` only, or
+ * one that adds `ai.orgs.br:gen`, etc. If scai *requests* scopes the
+ * client wasn't granted, Auth0 returns a 403 outright (not "filtered
+ * to intersection"). So the OAuth mint requests **no scope** — Auth0
+ * grants whatever the client has — and scai validates the resulting
+ * token's scope claim against the *minimum scai needs to run the
+ * operations it ships today*.
+ *
+ * Today that minimum is just `ai.org.br:gen` (Brand Review). Brand
+ * Management primitives, when they land, will lift this to include
+ * `ai.org.brd:r` (read) and later `ai.org.brd:w` (write). The login
+ * flow stays permissive — it persists any minted credential and tells
+ * the operator what's missing — but per-operation calls will refuse
+ * if their specific scope isn't present.
+ */
+export declare const BRAND_REQUIRED_SCOPES: readonly ["ai.org.br:gen"];
+export interface AcquireBrandTokenOptions {
+    orgId: string;
+    credential: BrandCredential;
+}
+export declare const extractScopes: (token: string) => string[];
+export declare const hasBrandScopes: (token: string) => boolean;
+/**
+ * Returns a Bearer JWT for the Sitecore Brand APIs.
+ *
+ * Resolution order, cheapest first:
+ *
+ *   1. Cached Brand token in the keychain (keyed by orgId) — set
+ *      by a previous mint via this function. Reused while it still
+ *      carries the required scopes; cleared on next 401 by callers.
+ *   2. Fresh M2M mint against the `auth.sitecorecloud.io/oauth/token`
+ *      endpoint with `audience=https://api.sitecorecloud.io`, using
+ *      the org-scoped `clientId` from `brand[orgId]` and the
+ *      matching secret from the keychain. Cached on success.
+ *
+ * Refuses with `AUTH_BRAND_REQUIRED` when none of these paths
+ * produces a token carrying the required scopes. The error message
+ * decodes the granted-scope set and infers the credential class so
+ * operators know whether they need to provision a new AI APIs key or
+ * just re-login.
+ */
+export declare const acquireBrandToken: (options: AcquireBrandTokenOptions) => Promise<string>;