@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/shared/publish-audit.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Publishing audit log — append-only JSON-Lines at
+ * `~/.sitecoreai/audit.log` (configurable via SITECOREAI_AUDIT_LOG).
+ *
+ * The audit log is the production trail for `scai content publish` operations.
+ * Every call writes one line; lines are never redacted (that's the
+ * point — when content goes live, the operator needs to be able to
+ * explain how). Different from `~/.sitecoreai/cli-history.log` in two
+ * ways:
+ *
+ *   1. cli-history is per-command (start/success/error events for any
+ *      `scai *` invocation) with secrets redacted; audit is per-publish
+ *      with consent records and resolved scope kept verbatim.
+ *   2. audit lines have higher retention expectations — operators
+ *      should treat this file like a SOC-relevant artifact.
+ *
+ * Failure mode: if the audit log can't be written (no write access,
+ * disk full, etc.) the publish call MUST fail rather than silently
+ * proceed without trail. The whole safety design relies on the log
+ * being trustworthy.
+ */
+export type PublishAuditCaller = {
+    type: "human";
+    via: "cli" | "mcp-prompt";
+    identityHint?: string;
+} | {
+    type: "ci";
+    pipelineId: string;
+    commitSha?: string;
+    gateName?: string;
+};
+/**
+ * `kind` enumerates the scope shape — each value pins the type of
+ * destructive operation the scope describes. Used by the scope-token
+ * `verifyScopeToken` check so a token minted for one verb can't be
+ * replayed against another:
+ *
+ *   - `"item"`           — Tier 1 `scai content publish item` (item-list publish).
+ *   - `"full"`           — Tier 2 `scai content publish all` (whole-tenant).
+ *   - `"unpublish"`      — `scai content publish unpublish` (content-state
+ *                          change + publish job composite).
+ *   - `"validity"`       — `scai content version set-validity`
+ *                          (per-version `__Valid from/to` field write).
+ *   - `"never-publish"`  — `scai content version set-never-publish`
+ *                          (per-version `__Never publish` field write).
+ */
+export type PublishAuditScopeKind = "item" | "full" | "unpublish" | "validity" | "never-publish";
+/**
+ * Strategy applied by `scai content publish unpublish`. The CLI exposes three
+ * mechanisms, all of which leave a different audit trail:
+ *
+ *   - `"never-publish"` — sets `__Never publish: true`. Reversible
+ *                         (clear the field + republish).
+ *   - `"expire-now"`    — sets `__Valid to: now`. Reversible (write a
+ *                         future date back).
+ *   - `"delete"`        — calls Authoring `deleteItem`. NOT reversible
+ *                         from scai's side. Production-tier gates add
+ *                         a typed-item-path confirmation on top of the
+ *                         normal scope-token flow.
+ */
+export type UnpublishStrategy = "never-publish" | "expire-now" | "delete";
+export interface PublishAuditScope {
+    envName: string;
+    resolvedTenantId?: string;
+    target: string;
+    /** See `PublishAuditScopeKind` for the enumerated set. */
+    kind: PublishAuditScopeKind;
+    /** Resolved item ids for Tier 1 / unpublish / content version verbs;
+     *  undefined for Tier 2 (whole-tenant publish). */
+    itemIds?: string[];
+    /** Item path / subtree root if known. Tier 1 + content version verbs
+     *  often have an authored path the operator typed; the audit log
+     *  keeps it for grep-ability. */
+    path?: string;
+    languages?: string[];
+    includeSubitems?: boolean;
+    includeRelated?: boolean;
+    /** For `kind: "unpublish"` — which removal strategy is being applied.
+     *  Distinguishes the reversible (`never-publish`, `expire-now`) from
+     *  the destructive (`delete`) cases at the audit-log level. */
+    strategy?: UnpublishStrategy;
+    /** For `kind: "validity"` / `"never-publish"` — the specific version
+     *  the field write targets (undefined for "latest"). Included in the
+     *  scope hash so a dry-run on v3 can't replay against v4. */
+    version?: number;
+}
+/**
+ * Per-field change recorded on a content-state mutation. The audit log
+ * stores both the resolved before-value and the after-value so an
+ * operator can reverse a mistaken toggle by reading the log — no need
+ * to inspect the live tenant first.
+ */
+export interface PublishAuditFieldChange {
+    name: string;
+    /** Field value as Sitecore returned it before the write. `null` when
+     *  the field wasn't present on the version (Sitecore treats absent
+     *  fields as effectively empty). */
+    before: string | null;
+    /** Field value after the write — what `updateItem` was asked to set.
+     *  `null` represents an intentional clear (`--clear-valid-from`). */
+    after: string | null;
+}
+export interface PublishAuditEntry {
+    ts: string;
+    command: "publish item" | "publish all" | "publish cancel" | "publish unpublish" | "content version set-validity" | "content version set-never-publish" | "content version inspect";
+    caller: PublishAuditCaller;
+    scope: PublishAuditScope;
+    /** "high" for whole-tenant or destructive operations, "normal" for
+     *  scoped reversible operations. Grep-able. */
+    risk: "normal" | "high";
+    /** Hash of (envName, kind, itemIds, languages, target) — same hash
+     *  used in the scope token. Lets operators correlate dry-run output
+     *  with the actual publish call later. */
+    scopeHash: string;
+    /** Scope token used at the real call (if any). */
+    scopeToken?: string;
+    /** Sitecore-side job id once the API responded. Absent on errors. */
+    jobId?: string;
+    /** Final state from the API: completed | failed | cancelled | error. */
+    outcome: "ok" | "error" | "cancelled";
+    /** ScaiError code when outcome is "error". */
+    errorCode?: string;
+    /** Human-readable error message when outcome is "error". */
+    errorMessage?: string;
+    /** Before/after field values for content-state mutations. Empty /
+     *  undefined on publish-only commands. Populated by:
+     *    - `publish unpublish` — one entry per (item, language) pair
+     *      whose state field was rewritten.
+     *    - `content version set-validity` — entries for `__Valid from`
+     *      and/or `__Valid to`.
+     *    - `content version set-never-publish` — entry for
+     *      `__Never publish`.
+     *  Reading the log gives the operator everything they need to
+     *  manually reverse a mistaken toggle.
+     */
+    fieldChanges?: PublishAuditFieldChange[];
+}
+/**
+ * Append a single audit entry. Throws if the file can't be written —
+ * intentional: silently dropping an audit entry would undermine the
+ * whole safety design.
+ */
+export declare const recordPublishAudit: (entry: PublishAuditEntry) => void;
+/**
+ * Read recent audit entries (newest last). Used by `scai content publish
+ * status` to surface running jobs when no job id is provided (since
+ * the GraphQL surface doesn't expose a list-jobs endpoint and the
+ * REST API requires per-call scope checks).
+ *
+ * `limit` caps the number of returned entries; the file is scanned
+ * tail-first so old entries don't have to be parsed when only the
+ * recent ones are needed.
+ */
+export declare const readRecentPublishAudit: (limit?: number) => PublishAuditEntry[];

package/dist/shared/publish-audit.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRecentPublishAudit = exports.recordPublishAudit = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_AUDIT_PATH = node_path_1.default.join(node_os_1.default.homedir(), ".sitecoreai", "audit.log");
+const resolveAuditPath = () => process.env.SITECOREAI_AUDIT_LOG?.trim() || DEFAULT_AUDIT_PATH;
+/**
+ * Append a single audit entry. Throws if the file can't be written —
+ * intentional: silently dropping an audit entry would undermine the
+ * whole safety design.
+ */
+const recordPublishAudit = (entry) => {
+    const auditPath = resolveAuditPath();
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(auditPath), { recursive: true });
+    node_fs_1.default.appendFileSync(auditPath, `${JSON.stringify(entry)}\n`, "utf8");
+};
+exports.recordPublishAudit = recordPublishAudit;
+/**
+ * Read recent audit entries (newest last). Used by `scai content publish
+ * status` to surface running jobs when no job id is provided (since
+ * the GraphQL surface doesn't expose a list-jobs endpoint and the
+ * REST API requires per-call scope checks).
+ *
+ * `limit` caps the number of returned entries; the file is scanned
+ * tail-first so old entries don't have to be parsed when only the
+ * recent ones are needed.
+ */
+const readRecentPublishAudit = (limit = 50) => {
+    const auditPath = resolveAuditPath();
+    if (!node_fs_1.default.existsSync(auditPath)) {
+        return [];
+    }
+    const raw = node_fs_1.default.readFileSync(auditPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+    const tail = lines.slice(-limit);
+    const entries = [];
+    for (const line of tail) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // Skip malformed lines — corrupted writes don't poison reads.
+        }
+    }
+    return entries;
+};
+exports.readRecentPublishAudit = readRecentPublishAudit;

package/dist/shared/publish-consent.d.ts

@@ -0,0 +1,104 @@
+import type { PublishAuditCaller, PublishAuditScope, PublishAuditScopeKind } from "./publish-audit";
+/**
+ * Consent + scope-token primitives for `scai content publish`.
+ *
+ * The safety model has three layers (see docs/parity-with-devex.md):
+ *
+ *   1. CLI default = `--what-if`. Real call requires `--allow-write`.
+ *   2. Production-tier envs require a two-step typed scope token
+ *      (dry-run → token → real call with token).
+ *   3. Library layer requires a structured `PublishConsent` argument;
+ *      an agent can't synthesize one without going through CLI prompt,
+ *      MCP host approval, or a CI gate.
+ *
+ * The scope token is the operator-visible artifact that bridges steps
+ * 2 and 3. It encodes the resolved scope (envName + tenant + items +
+ * languages + target), is bound to a TTL, and is **self-contained** —
+ * no server-side cache needed for verification. Threat model: scope
+ * tokens prevent fat-finger errors and give operators visibility into
+ * what's about to publish; they don't (and can't) defend against a
+ * malicious process running as the operator. That defense lives at
+ * the MCP `allowWrite` gate and the operator's CI-secret hygiene.
+ */
+export declare const SCOPE_TOKEN_TTL_MS: number;
+export interface PublishConsent {
+    confirmedBy: PublishAuditCaller;
+    scope: PublishAuditScope;
+    scopeHash: string;
+    issuedAt: string;
+    ttlMs: number;
+}
+/**
+ * Stable hash over the resolved publish scope. Identical scopes
+ * produce identical hashes regardless of input ordering, so a dry-run
+ * and a subsequent real call with the same arguments resolve to the
+ * same hash and the scope token verifies.
+ */
+export declare const computeScopeHash: (scope: PublishAuditScope) => string;
+interface ScopeTokenPayload {
+    v: 1;
+    /** Scope kind — see `PublishAuditScopeKind` in audit.ts. Existing
+     *  publish-item / publish-all tokens encode "item" / "full"; the new
+     *  unpublish / content version verbs add their own kinds so a token
+     *  minted for one verb can't be replayed against another. */
+    k: PublishAuditScopeKind;
+    /** envName, kept short. */
+    e: string;
+    /** scopeHash (32 hex chars). */
+    h: string;
+    /** issuedAt epoch ms. */
+    t: number;
+    /** ttl in ms. */
+    ttl: number;
+}
+/**
+ * Mint a scope token for the resolved scope. Returns a short string
+ * the operator copies from dry-run output to the real-call command.
+ *
+ * Format: `pub_<base64url(payload)>`. The payload is self-describing
+ * and self-verifying: TTL + scopeHash mean a token can only validate
+ * against an identical scope within its lifetime window.
+ */
+export declare const mintScopeToken: (scope: PublishAuditScope, now?: number) => string;
+export type ScopeTokenVerificationFailure = {
+    ok: false;
+    reason: "malformed";
+} | {
+    ok: false;
+    reason: "expired";
+    ageMs: number;
+} | {
+    ok: false;
+    reason: "env-mismatch";
+    expectedEnv: string;
+    tokenEnv: string;
+} | {
+    ok: false;
+    reason: "kind-mismatch";
+    expectedKind: string;
+    tokenKind: string;
+} | {
+    ok: false;
+    reason: "scope-mismatch";
+    expectedHash: string;
+    tokenHash: string;
+};
+export type ScopeTokenVerification = {
+    ok: true;
+    payload: ScopeTokenPayload;
+} | ScopeTokenVerificationFailure;
+/**
+ * Verify a scope token against the operator's current request. The
+ * token must:
+ *   - parse and have v=1
+ *   - not be expired (issued within ttl of now)
+ *   - name the same env as the request
+ *   - name the same kind (item vs full)
+ *   - encode a scopeHash that matches the request's recomputed hash
+ *
+ * Any mismatch is surfaced with a specific `reason` so the CLI can
+ * tell the operator exactly what changed between the dry-run and the
+ * real call.
+ */
+export declare const verifyScopeToken: (token: string, scope: PublishAuditScope, now?: number) => ScopeTokenVerification;
+export {};

package/dist/shared/publish-consent.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyScopeToken = exports.mintScopeToken = exports.computeScopeHash = exports.SCOPE_TOKEN_TTL_MS = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * Consent + scope-token primitives for `scai content publish`.
+ *
+ * The safety model has three layers (see docs/parity-with-devex.md):
+ *
+ *   1. CLI default = `--what-if`. Real call requires `--allow-write`.
+ *   2. Production-tier envs require a two-step typed scope token
+ *      (dry-run → token → real call with token).
+ *   3. Library layer requires a structured `PublishConsent` argument;
+ *      an agent can't synthesize one without going through CLI prompt,
+ *      MCP host approval, or a CI gate.
+ *
+ * The scope token is the operator-visible artifact that bridges steps
+ * 2 and 3. It encodes the resolved scope (envName + tenant + items +
+ * languages + target), is bound to a TTL, and is **self-contained** —
+ * no server-side cache needed for verification. Threat model: scope
+ * tokens prevent fat-finger errors and give operators visibility into
+ * what's about to publish; they don't (and can't) defend against a
+ * malicious process running as the operator. That defense lives at
+ * the MCP `allowWrite` gate and the operator's CI-secret hygiene.
+ */
+exports.SCOPE_TOKEN_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const canonicalScope = (scope) => JSON.stringify({
+    envName: scope.envName,
+    resolvedTenantId: scope.resolvedTenantId ?? "",
+    target: scope.target,
+    kind: scope.kind,
+    // Sort itemIds so deterministic input order doesn't depend on
+    // upstream resolver behaviour. Languages sorted likewise.
+    itemIds: (scope.itemIds ?? []).slice().sort(),
+    path: scope.path ?? "",
+    languages: (scope.languages ?? []).slice().sort(),
+    includeSubitems: Boolean(scope.includeSubitems),
+    includeRelated: Boolean(scope.includeRelated),
+    // Include strategy + version in the hash so the scope token binds
+    // to the specific shape of the intended mutation. Defaulting to
+    // empty string keeps the legacy publish-item / publish-all hash
+    // values unchanged (both pass strategy=undefined, version=undefined).
+    strategy: scope.strategy ?? "",
+    version: scope.version ?? "",
+});
+/**
+ * Stable hash over the resolved publish scope. Identical scopes
+ * produce identical hashes regardless of input ordering, so a dry-run
+ * and a subsequent real call with the same arguments resolve to the
+ * same hash and the scope token verifies.
+ */
+const computeScopeHash = (scope) => node_crypto_1.default.createHash("sha256").update(canonicalScope(scope)).digest("hex").slice(0, 32);
+exports.computeScopeHash = computeScopeHash;
+const encodePayload = (payload) => Buffer.from(JSON.stringify(payload), "utf8")
+    .toString("base64")
+    .replace(/=+$/, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+const decodePayload = (encoded) => {
+    try {
+        const b64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = b64 + "==".slice(0, (4 - (b64.length % 4)) % 4);
+        const json = Buffer.from(padded, "base64").toString("utf8");
+        const obj = JSON.parse(json);
+        if (obj.v !== 1)
+            return undefined;
+        return obj;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Mint a scope token for the resolved scope. Returns a short string
+ * the operator copies from dry-run output to the real-call command.
+ *
+ * Format: `pub_<base64url(payload)>`. The payload is self-describing
+ * and self-verifying: TTL + scopeHash mean a token can only validate
+ * against an identical scope within its lifetime window.
+ */
+const mintScopeToken = (scope, now = Date.now()) => {
+    const payload = {
+        v: 1,
+        k: scope.kind,
+        e: scope.envName,
+        h: (0, exports.computeScopeHash)(scope),
+        t: now,
+        ttl: exports.SCOPE_TOKEN_TTL_MS,
+    };
+    return `pub_${encodePayload(payload)}`;
+};
+exports.mintScopeToken = mintScopeToken;
+/**
+ * Verify a scope token against the operator's current request. The
+ * token must:
+ *   - parse and have v=1
+ *   - not be expired (issued within ttl of now)
+ *   - name the same env as the request
+ *   - name the same kind (item vs full)
+ *   - encode a scopeHash that matches the request's recomputed hash
+ *
+ * Any mismatch is surfaced with a specific `reason` so the CLI can
+ * tell the operator exactly what changed between the dry-run and the
+ * real call.
+ */
+const verifyScopeToken = (token, scope, now = Date.now()) => {
+    if (!token.startsWith("pub_")) {
+        return { ok: false, reason: "malformed" };
+    }
+    const payload = decodePayload(token.slice("pub_".length));
+    if (!payload) {
+        return { ok: false, reason: "malformed" };
+    }
+    const ageMs = now - payload.t;
+    if (ageMs < 0 || ageMs > payload.ttl) {
+        return { ok: false, reason: "expired", ageMs };
+    }
+    if (payload.e !== scope.envName) {
+        return {
+            ok: false,
+            reason: "env-mismatch",
+            expectedEnv: scope.envName,
+            tokenEnv: payload.e,
+        };
+    }
+    if (payload.k !== scope.kind) {
+        return {
+            ok: false,
+            reason: "kind-mismatch",
+            expectedKind: scope.kind,
+            tokenKind: payload.k,
+        };
+    }
+    const expectedHash = (0, exports.computeScopeHash)(scope);
+    if (payload.h !== expectedHash) {
+        return {
+            ok: false,
+            reason: "scope-mismatch",
+            expectedHash,
+            tokenHash: payload.h,
+        };
+    }
+    return { ok: true, payload };
+};
+exports.verifyScopeToken = verifyScopeToken;

package/dist/shared/redact.d.ts

@@ -1,3 +1,2 @@
 export declare const redactSecrets: (value: string) => string;
 export declare const redactArgs: (args: string[], sensitiveFlags?: Set<string>) => string[];
-//# sourceMappingURL=redact.d.ts.map

package/dist/shared/redact.js

@@ -5,8 +5,10 @@ const replaceAll = (value, pattern, replacement) => value.replace(pattern, repla
 const redactSecrets = (value) => {
     let output = value;
     output = replaceAll(output, /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi, "Bearer <redacted>");
-    output = replaceAll(output, /(\b(access_token|refresh_token|client_secret|deployToken|token)\b\s*[=:]\s*)([^&\s"]+)/gi, "$1<redacted>");
-    output = replaceAll(output, /("(?:access_token|refresh_token|client_secret|deployToken|token)"\s*:\s*")([^"]+)/gi, "$1<redacted>");
+    // Match both snake_case (access_token) and camelCase (accessToken) via
+    // optional underscore. Case-insensitive flag covers PascalCase/UPPER.
+    output = replaceAll(output, /(\b(access_?token|refresh_?token|client_?secret|client_?id|deploy_?token|password|token|secret)\b\s*[=:]\s*)([^&\s"]+)/gi, "$1<redacted>");
+    output = replaceAll(output, /("(?:access_?token|refresh_?token|client_?secret|client_?id|deploy_?token|password|token|secret)"\s*:\s*")([^"]+)/gi, "$1<redacted>");
     return output;
 };
 exports.redactSecrets = redactSecrets;

package/dist/shared/region.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Region resolution — the single place scai derives a Sitecore
+ * organization's region code (e.g. `euw`) and builds a regional API host.
+ *
+ * Sitecore's regional services share one region per organization and
+ * differ only in hostname:
+ *   - Agentic Studio  `agentic-studio-{region}.sitecorecloud.io`
+ *   - Orchestrate     `ai-workflows-{region}.sitecorecloud.io`
+ *   - Brief           `co-brief-api-{region}.sitecorecloud.io`
+ *
+ * The region itself is read from `platform-inventory` — a versioned
+ * (`v1`), legitimate platform service — keyed by the org id scai already
+ * holds. Three layers, smallest first:
+ *
+ *   - `resolveRegion(orgId, token)` — the leaf primitive: one
+ *     `platform-inventory` call with a caller-supplied access token.
+ *   - `resolveRegionCode({ organizationId, acquireToken })` — env-aware:
+ *     mints the token lazily (only on a cache miss) through an injected
+ *     callback, so this module depends on nothing but `fetch`.
+ *   - `resolveRegionalBaseUrl({ …, hostTemplate, override })` — the
+ *     convenience every regional area calls: honour an explicit per-env
+ *     host override, else resolve the region and fill a host template.
+ *
+ * The token must carry `platform.tenants:listall` (scai's automation
+ * client is provisioned with it; see `SCAI_API_SCOPES`). The caller owns
+ * how that token is obtained — campaign reuses its no-scope Orchestrate
+ * token, brief/agents mint a fresh no-scope M2M token — which is why the
+ * token enters through a callback rather than a hard dependency.
+ */
+/** Region code used when resolution is unavailable — EU West. */
+export declare const DEFAULT_REGION = "euw";
+/**
+ * Resolve a Sitecore organization's region code from `platform-inventory`.
+ *
+ * **Best-effort.** Any failure — no/invalid token, wrong audience,
+ * network, an org with no regioned tenant — falls back to
+ * `DEFAULT_REGION`, so a caller always gets a usable region and a
+ * regional host is always buildable. Cached per organization.
+ *
+ * `accessToken` must carry `platform.tenants:listall`; scai's automation
+ * client is provisioned with it.
+ */
+export declare const resolveRegion: (organizationId: string, accessToken: string) => Promise<string>;
+/** Options shared by the env-aware resolvers. */
+export interface ResolveRegionOptions {
+    /**
+     * Sitecore organization id — the region is derived from it. When
+     * absent, resolution is skipped and `DEFAULT_REGION` is used.
+     */
+    organizationId?: string;
+    /**
+     * Mints an access token carrying `platform.tenants:listall` for the
+     * `platform-inventory` lookup. Invoked only on a region cache miss.
+     * May reject or resolve `undefined` — resolution then falls back to
+     * `DEFAULT_REGION`.
+     */
+    acquireToken: () => Promise<string | undefined>;
+}
+/**
+ * Resolve a region code env-aware: org id → token → `platform-inventory`.
+ *
+ * **Best-effort**, like `resolveRegion`. The `acquireToken` callback is
+ * invoked only when the region isn't already cached for the org and no
+ * id-less short-circuit applies, so a token is never minted needlessly.
+ */
+export declare const resolveRegionCode: (options: ResolveRegionOptions) => Promise<string>;
+/**
+ * Fill a regional host template — the `{region}` placeholder is replaced
+ * with the region code. e.g. `regionalHost("https://ai-workflows-{region}.sitecorecloud.io", "euw")`.
+ */
+export declare const regionalHost: (template: string, region: string) => string;
+/** Options for the regional-base-URL convenience. */
+export interface ResolveRegionalBaseUrlOptions extends ResolveRegionOptions {
+    /**
+     * Host template carrying a `{region}` placeholder, scheme included —
+     * e.g. `https://ai-workflows-{region}.sitecorecloud.io`.
+     */
+    hostTemplate: string;
+    /**
+     * Explicit per-env host override. When set it is returned verbatim —
+     * no region resolution, no token mint.
+     */
+    override?: string;
+}
+/**
+ * Resolve a regional API base URL — the single entry point regional
+ * areas (campaign, brief) call to pick their host.
+ *
+ * An `override` (a per-env pinned host) wins outright. Otherwise the
+ * region is resolved from the org id and `hostTemplate` is filled.
+ * Best-effort throughout — an unresolvable region yields the
+ * `DEFAULT_REGION` host, never an error.
+ */
+export declare const resolveRegionalBaseUrl: (options: ResolveRegionalBaseUrlOptions) => Promise<string>;
+/** Drop a cached region — used by tests; the cache is otherwise permanent. */
+export declare const clearRegionCache: () => void;