@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/campaigns/api/request.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.campaignRequest = void 0;
+const errors_1 = require("../../shared/errors");
+const redact_1 = require("../../shared/redact");
+const request_1 = require("../../deploy/api/common/request");
+const types_1 = require("./types");
+/**
+ * Campaign (Orchestrate) API transport — `campaignRequest()`.
+ *
+ * Mirrors `briefRequest()`: bearer auth, JSON request/response, error
+ * mapping that surfaces Sitecore's structured error bodies. The
+ * Orchestrate API uses **snake_case** JSON (unlike the camelCase Brief
+ * and Sites APIs) — helpers in sibling files type the wire shapes
+ * verbatim rather than remapping.
+ *
+ * Errors map to scai's `ScaiError` — `NETWORK` for transport failures,
+ * `CAMPAIGN_API_FAILED` for non-2xx responses.
+ */
+const toQueryString = (query) => {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                params.append(key, String(entry));
+            }
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    const output = params.toString();
+    return output ? `?${output}` : "";
+};
+/**
+ * Parse the `auth-param`s out of an RFC 6750 `WWW-Authenticate: Bearer …`
+ * challenge — `error`, `error_description`, and (for `insufficient_scope`)
+ * the required `scope`. A 401/403 from an OAuth-protected API carries the
+ * reason here, not in the JSON body. The Orchestrate API's exact scope is
+ * otherwise unverified (see `auth.ts`), so this header is the one place
+ * scai can learn it. Keys are lower-cased; a missing header yields `{}`.
+ */
+const parseBearerChallenge = (header) => {
+    if (!header)
+        return {};
+    const challenge = /^\s*bearer\s+(.*)$/is.exec(header);
+    const params = challenge ? challenge[1] : header;
+    const out = {};
+    const pair = /([A-Za-z_-]+)\s*=\s*(?:"([^"]*)"|([^,\s]+))/g;
+    let match;
+    while ((match = pair.exec(params)) !== null) {
+        out[match[1].toLowerCase()] = match[2] ?? match[3] ?? "";
+    }
+    return out;
+};
+const campaignRequest = async (options, path, init) => {
+    const baseUrl = options.baseUrl ?? types_1.DEFAULT_CAMPAIGN_API_BASE;
+    const url = `${baseUrl.replace(/\/$/, "")}${path}${toQueryString(init?.query)}`;
+    const method = init?.method ? init.method.toUpperCase() : "GET";
+    const headers = {
+        Authorization: `Bearer ${options.accessToken}`,
+        Accept: "application/json",
+    };
+    if (init?.headers) {
+        Object.assign(headers, init.headers);
+    }
+    let body;
+    if (init?.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = typeof init.body === "string" ? init.body : JSON.stringify(init.body);
+    }
+    const timeoutMs = Number(process.env.SITECOREAI_REQUEST_TIMEOUT_MS ?? 60000);
+    const controller = timeoutMs > 0 ? new AbortController() : undefined;
+    const timeoutHandle = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+    let response;
+    try {
+        response = await fetch(url, { method, headers, body, signal: controller?.signal });
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)((0, redact_1.redactSecrets)(`Campaign API request failed: ${error instanceof Error ? error.message : String(error)}`), "NETWORK", { hint: "Check network connectivity or try again later." });
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+    }
+    if (!response.ok) {
+        const responseBody = await (0, request_1.parseJsonIfPossible)(response);
+        const message = (0, request_1.extractErrorMessage)(responseBody);
+        const sanitized = message ? (0, redact_1.redactSecrets)(message) : undefined;
+        // On an auth failure, the `WWW-Authenticate` Bearer challenge often
+        // names the scope the token is missing — surface it so the operator
+        // (and a future `acquireCampaignToken` scope pin) can act on it.
+        const challenge = parseBearerChallenge(response.headers.get("www-authenticate"));
+        const isAuthFailure = response.status === 401 ||
+            response.status === 403 ||
+            challenge.error === "insufficient_scope";
+        let hint;
+        if (isAuthFailure) {
+            const required = challenge.scope
+                ? ` The Orchestrate API requires the '${challenge.scope}' scope.`
+                : "";
+            hint =
+                `The environment's automation client is not authorized for the Orchestrate API.${required} ` +
+                    `Grant the missing scope to the client in the Sitecore Cloud Portal, then re-run.`;
+        }
+        throw (0, errors_1.createScaiError)(sanitized ??
+            challenge.error_description ??
+            challenge.error ??
+            `Campaign API request failed (${response.status})`, "CAMPAIGN_API_FAILED", hint ? { hint } : {});
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    return (await (0, request_1.parseJsonIfPossible)(response));
+};
+exports.campaignRequest = campaignRequest;

package/dist/campaigns/api/schema.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Campaign (Orchestrate) API response schema — hand-written from
+ * observed payloads.
+ *
+ * Source: a HAR capture of the Sitecore Content Operations UI driving
+ * the Orchestrate API, 2026-05-15. No published OpenAPI spec. The
+ * Orchestrate API uses **snake_case** field names; these types reflect
+ * the wire verbatim.
+ *
+ * Resource hierarchy: a campaign is a `Project`; a project owns
+ * `Deliverable`s; a deliverable owns `Task`s.
+ *
+ * Conventions:
+ *  - List endpoints return `{ data, next, totalCount }` — same paged
+ *    envelope as the Brief API.
+ *  - User references are Auth0 subjects (`auth0|...`).
+ *  - Timestamps are ISO-8601.
+ *  - `status` / `funnel_stage` are server enums; only a subset of
+ *    values was observed, so they are typed as `string`.
+ */
+/** Paged list envelope returned by every Orchestrate list endpoint. */
+export type PagedResult<T> = {
+    data: T[];
+    /** Cursor for the next page, or null at end of stream. */
+    next: string | null;
+    totalCount: number;
+};
+/** A project (campaign) member — references an Auth0 user subject. */
+export type ProjectMember = {
+    id: string;
+};
+/** File attached to a project. */
+export type ProjectAttachment = {
+    id: string;
+    file_id: string;
+    metadata: {
+        mimeType?: string;
+        fileName?: string;
+        contentLength?: string;
+        [key: string]: unknown;
+    };
+    created_by: string;
+};
+/**
+ * Task — the leaf work item, owned by a deliverable.
+ *
+ * `description` is HTML. `assignee` is an Auth0 subject or null.
+ */
+export type Task = {
+    legacy_id: string | null;
+    id: string;
+    project_id: string;
+    project_deliverable_id: string;
+    org_id: string;
+    tenant_id: string;
+    name: string;
+    start_date: string | null;
+    due_date: string | null;
+    status: string;
+    priority: string | null;
+    description: string | null;
+    assignee: string | null;
+    dependencies: unknown[];
+    attachments: unknown[];
+    action_link: string | null;
+    action_name: string | null;
+    labels: string[];
+    deleted: boolean;
+    archived: boolean;
+    created_by: string;
+    created_at: string;
+    modified_by: string;
+    modified_at: string;
+};
+/** Deliverable — a funnel-stage grouping of tasks under a project. */
+export type Deliverable = {
+    legacy_id: string | null;
+    id: string;
+    project_id: string;
+    org_id: string;
+    tenant_id: string;
+    name: string;
+    due_date: string | null;
+    /** Funnel stage enum — observed: `TOP`. Full set TBD. */
+    funnel_stage: string;
+    funnel_tactics: string[];
+    labels: string[];
+    tasks: Task[];
+    context: unknown[];
+    status?: string;
+    deleted: boolean;
+    archived: boolean;
+    created_by: string;
+    created_at: string;
+    modified_by: string;
+    modified_at: string;
+};
+/**
+ * Project — the unit the UI calls a "campaign".
+ *
+ * `status` is a server enum (observed: `NOT_STARTED`). `brandkit_id`
+ * cross-references a brand kit; `briefs` cross-references the Brief
+ * API — both are links, not embedded objects.
+ */
+export type Project = {
+    legacy_id: string | null;
+    id: string;
+    /** Echoes `id`. */
+    project_id: string;
+    org_id: string;
+    tenant_id: string;
+    name: string;
+    description: string;
+    start_date: string | null;
+    due_date: string | null;
+    status: string;
+    brandkit_id: string | null;
+    thumbnail_url: string | null;
+    labels: string[];
+    members: ProjectMember[];
+    member_requests: unknown[];
+    attachments: ProjectAttachment[];
+    deliverables: Deliverable[];
+    context: unknown[];
+    briefs: unknown[];
+    project_progress: number;
+    custom_fields: unknown | null;
+    deleted: boolean;
+    archived: boolean;
+    created_by: string;
+    created_at: string;
+    modified_by: string;
+    modified_at: string;
+};
+/** A user in the Orchestrate member directory. */
+export type CampaignUser = {
+    id: string;
+    given_name: string;
+    family_name: string;
+    picture: string | null;
+    email: string;
+    /** Observed: `ADMIN`. Full set TBD. */
+    user_type?: string;
+};

package/dist/campaigns/api/schema.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Campaign (Orchestrate) API response schema — hand-written from
+ * observed payloads.
+ *
+ * Source: a HAR capture of the Sitecore Content Operations UI driving
+ * the Orchestrate API, 2026-05-15. No published OpenAPI spec. The
+ * Orchestrate API uses **snake_case** field names; these types reflect
+ * the wire verbatim.
+ *
+ * Resource hierarchy: a campaign is a `Project`; a project owns
+ * `Deliverable`s; a deliverable owns `Task`s.
+ *
+ * Conventions:
+ *  - List endpoints return `{ data, next, totalCount }` — same paged
+ *    envelope as the Brief API.
+ *  - User references are Auth0 subjects (`auth0|...`).
+ *  - Timestamps are ISO-8601.
+ *  - `status` / `funnel_stage` are server enums; only a subset of
+ *    values was observed, so they are typed as `string`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/campaigns/api/tasks.d.ts

@@ -0,0 +1,42 @@
+import type { PagedResult, Task } from "./schema";
+import type { CampaignApiClientOptions } from "./types";
+/** List tasks under a deliverable (paged). */
+export declare const listTasks: (options: CampaignApiClientOptions, projectId: string, deliverableId: string) => Promise<PagedResult<Task>>;
+/** Read a single task by id. */
+export declare const getTask: (options: CampaignApiClientOptions, projectId: string, deliverableId: string, taskId: string) => Promise<Task>;
+/** Input for `createTask`. Field set observed on the wire. */
+export type CreateTaskInput = {
+    name: string;
+    due_date?: string;
+    status?: string;
+    dependencies?: unknown[];
+};
+/** Create a task under a deliverable. Returns the persisted record (201). */
+export declare const createTask: (options: CampaignApiClientOptions, projectId: string, deliverableId: string, input: CreateTaskInput) => Promise<Task>;
+/**
+ * Input for `updateTask`. PUT is full-replacement — fetch the task
+ * first and merge if you only mean to change one field.
+ */
+export type UpdateTaskInput = {
+    name: string;
+    due_date?: string;
+    status?: string;
+    priority?: string | null;
+    description?: string | null;
+    assignee?: string | null;
+    labels?: string[];
+    dependencies?: unknown[];
+    archived?: boolean;
+};
+/** Full-replacement update of a task (PUT). Returns the persisted record. */
+export declare const updateTask: (options: CampaignApiClientOptions, projectId: string, deliverableId: string, taskId: string, input: UpdateTaskInput) => Promise<Task>;
+/**
+ * Delete a task
+ * (`DELETE …/projects/{p}/deliverables/{d}/tasks/{t}`). Returns void —
+ * a 204 is expected on success.
+ *
+ * UNVERIFIED — DELETE was never captured; inferred from REST conventions
+ * (the same single-task path `getTask`/`updateTask` use). Smoke-test
+ * before relying on it.
+ */
+export declare const deleteTask: (options: CampaignApiClientOptions, projectId: string, deliverableId: string, taskId: string) => Promise<void>;

package/dist/campaigns/api/tasks.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteTask = exports.updateTask = exports.createTask = exports.getTask = exports.listTasks = void 0;
+const request_1 = require("./request");
+/**
+ * Tasks resource — the leaf work items under a deliverable.
+ *
+ * Endpoint surface (HAR-derived 2026-05-15):
+ *   GET    …/projects/{p}/deliverables/{d}/tasks       — list (paged)
+ *   GET    …/projects/{p}/deliverables/{d}/tasks/{t}   — read one
+ *   POST   …/projects/{p}/deliverables/{d}/tasks       — create (201)
+ *   PUT    …/projects/{p}/deliverables/{d}/tasks/{t}   — full-replacement update
+ *   DELETE …/projects/{p}/deliverables/{d}/tasks/{t}   — delete (UNVERIFIED)
+ *
+ * `description` is HTML; `assignee` is an Auth0 subject. `deleteTask` is
+ * wired optimistically per REST conventions; see its doc comment.
+ */
+const tasksPath = (projectId, deliverableId) => `/api/orchestrate/v1/projects/${encodeURIComponent(projectId)}` +
+    `/deliverables/${encodeURIComponent(deliverableId)}/tasks`;
+/** List tasks under a deliverable (paged). */
+const listTasks = (options, projectId, deliverableId) => (0, request_1.campaignRequest)(options, tasksPath(projectId, deliverableId));
+exports.listTasks = listTasks;
+/** Read a single task by id. */
+const getTask = (options, projectId, deliverableId, taskId) => (0, request_1.campaignRequest)(options, `${tasksPath(projectId, deliverableId)}/${encodeURIComponent(taskId)}`);
+exports.getTask = getTask;
+/** Create a task under a deliverable. Returns the persisted record (201). */
+const createTask = (options, projectId, deliverableId, input) => (0, request_1.campaignRequest)(options, tasksPath(projectId, deliverableId), {
+    method: "POST",
+    body: {
+        project_id: projectId,
+        project_deliverable_id: deliverableId,
+        name: input.name,
+        due_date: input.due_date,
+        status: input.status ?? "NOT_STARTED",
+        archived: false,
+        dependencies: input.dependencies ?? [],
+    },
+});
+exports.createTask = createTask;
+/** Full-replacement update of a task (PUT). Returns the persisted record. */
+const updateTask = (options, projectId, deliverableId, taskId, input) => (0, request_1.campaignRequest)(options, `${tasksPath(projectId, deliverableId)}/${encodeURIComponent(taskId)}`, {
+    method: "PUT",
+    body: {
+        project_id: projectId,
+        project_deliverable_id: deliverableId,
+        name: input.name,
+        due_date: input.due_date,
+        status: input.status ?? "NOT_STARTED",
+        priority: input.priority ?? null,
+        description: input.description ?? null,
+        assignee: input.assignee ?? null,
+        labels: input.labels ?? [],
+        dependencies: input.dependencies ?? [],
+        archived: input.archived ?? false,
+    },
+});
+exports.updateTask = updateTask;
+/**
+ * Delete a task
+ * (`DELETE …/projects/{p}/deliverables/{d}/tasks/{t}`). Returns void —
+ * a 204 is expected on success.
+ *
+ * UNVERIFIED — DELETE was never captured; inferred from REST conventions
+ * (the same single-task path `getTask`/`updateTask` use). Smoke-test
+ * before relying on it.
+ */
+const deleteTask = (options, projectId, deliverableId, taskId) => (0, request_1.campaignRequest)(options, `${tasksPath(projectId, deliverableId)}/${encodeURIComponent(taskId)}`, { method: "DELETE" });
+exports.deleteTask = deleteTask;

package/dist/campaigns/api/types.d.ts

@@ -0,0 +1,17 @@
+export type CampaignApiClientOptions = {
+    /** Defaults to the EU-West host. CLI/recipe callers fill it region-aware. */
+    baseUrl?: string;
+    /** Bearer token from `auth.sitecorecloud.io`. Exact scope is TBD pending an authed probe. */
+    accessToken: string;
+};
+/** Orchestrate host template — `{region}` is filled by `resolveRegionalBaseUrl`. */
+export declare const CAMPAIGN_API_HOST_TEMPLATE = "https://ai-workflows-{region}.sitecorecloud.io";
+/** Fallback host (EU-West) for callers that resolve no region. */
+export declare const DEFAULT_CAMPAIGN_API_BASE: string;
+/** Per-call options shared by every helper. */
+export type CampaignRequestInit = {
+    method?: string;
+    headers?: Record<string, string>;
+};
+export type CampaignQueryValue = string | number | boolean;
+export type CampaignQueryRecord = Record<string, CampaignQueryValue | CampaignQueryValue[] | undefined>;

package/dist/campaigns/api/types.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CAMPAIGN_API_BASE = exports.CAMPAIGN_API_HOST_TEMPLATE = void 0;
+/**
+ * Public configuration shape for Campaign (Orchestrate) API clients.
+ * Mirrors `BriefApiClientOptions` — bring your own access token,
+ * optionally override the base URL.
+ *
+ * The Campaign surface is the Sitecore **Orchestrate API**
+ * (`/api/orchestrate/v1/`). A "campaign" in the product UI is an
+ * Orchestrate `project`; the SDK keeps the API noun (`project`) so the
+ * wire and the code line up — the CLI/MCP layers present it as
+ * "campaign".
+ *
+ * Like the Brief API, Orchestrate is **regional**: hosts follow
+ * `ai-workflows-<region>.sitecorecloud.io` (e.g. `ai-workflows-euw`
+ * for EU-West). There is no region-agnostic proxy — each environment
+ * binds to one region. The CLI/recipe layers fill `baseUrl` via the
+ * shared region resolver (`@/shared/region` — org id → region); the
+ * default below is the fallback for direct library callers and probe
+ * scripts that bring no environment.
+ */
+const region_1 = require("../../shared/region");
+/** Orchestrate host template — `{region}` is filled by `resolveRegionalBaseUrl`. */
+exports.CAMPAIGN_API_HOST_TEMPLATE = "https://ai-workflows-{region}.sitecorecloud.io";
+/** Fallback host (EU-West) for callers that resolve no region. */
+exports.DEFAULT_CAMPAIGN_API_BASE = (0, region_1.regionalHost)(exports.CAMPAIGN_API_HOST_TEMPLATE, region_1.DEFAULT_REGION);

package/dist/campaigns/api/users.d.ts

@@ -0,0 +1,13 @@
+import type { CampaignUser, PagedResult } from "./schema";
+import type { CampaignApiClientOptions } from "./types";
+/**
+ * Users resource — the Orchestrate member directory.
+ *
+ * Endpoint surface (HAR-derived 2026-05-15):
+ *   GET /api/orchestrate/v1/users — list (paged)
+ *
+ * Use this to resolve the Auth0 subjects referenced by a project's
+ * `members` and a task's `assignee` into display names + emails.
+ */
+/** List users available as campaign members / task assignees. */
+export declare const listUsers: (options: CampaignApiClientOptions) => Promise<PagedResult<CampaignUser>>;

package/dist/campaigns/api/users.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listUsers = void 0;
+const request_1 = require("./request");
+/**
+ * Users resource — the Orchestrate member directory.
+ *
+ * Endpoint surface (HAR-derived 2026-05-15):
+ *   GET /api/orchestrate/v1/users — list (paged)
+ *
+ * Use this to resolve the Auth0 subjects referenced by a project's
+ * `members` and a task's `assignee` into display names + emails.
+ */
+/** List users available as campaign members / task assignees. */
+const listUsers = (options) => (0, request_1.campaignRequest)(options, "/api/orchestrate/v1/users");
+exports.listUsers = listUsers;

package/dist/campaigns/auth.d.ts

@@ -0,0 +1,19 @@
+import type { BrandCredential } from "../config/types";
+export interface AcquireCampaignTokenOptions {
+    /** Org id behind the campaign environment — keys the AI APIs key. */
+    organizationId: string | undefined;
+    /** The `brand[orgId]` AI APIs key block from the root config. */
+    brandCredential: BrandCredential | undefined;
+}
+/**
+ * Returns a Bearer JWT for the Sitecore Orchestrate (Campaign) API.
+ *
+ * Resolution order:
+ *   1. Campaign-specific keychain entry (keyed by org id), if unexpired.
+ *   2. Fresh M2M client-credentials mint from the org's AI APIs key —
+ *      `clientId` from the `brand[orgId]` config block, secret from the
+ *      keychain. Cached for next time.
+ *
+ * Refuses with `AUTH_BRAND_REQUIRED` when no AI APIs key is registered.
+ */
+export declare const acquireCampaignToken: (options: AcquireCampaignTokenOptions) => Promise<string>;

package/dist/campaigns/auth.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireCampaignToken = void 0;
+const auth_1 = require("../serialization/api/auth");
+const errors_1 = require("../shared/errors");
+const keychain_1 = require("../shared/keychain");
+/**
+ * Auth seam for the Campaign (Orchestrate) API.
+ *
+ * The Orchestrate API is an AI API (`ai-workflows-*.sitecorecloud.io`) and
+ * authenticates with the **AI APIs key** — the same org-scoped credential
+ * `scai brand` uses (`brand[orgId]` in the config; secret in the keychain).
+ *
+ * Verified 2026-05-16: a token minted from the AI APIs key calls
+ * `/api/orchestrate/v1/projects` successfully, where a Deploy-clients-API
+ * automation client (`cm` or `deploy` type) gets `403 Insufficient scope`
+ * — those clients carry `xmcloud*`/`co.*` scopes, not the `ai.*` family
+ * the Orchestrate API requires.
+ *
+ * Minted with no `scope` parameter — Auth0 issues the AI APIs key's full
+ * (per-key) grant; the Orchestrate API enforces scope server-side. There
+ * is no interactive login flow — campaign calls are agent-driven.
+ */
+/**
+ * JWT exp claim (seconds) — used to decide whether a cached token is
+ * still usable. Refresh ~60s early to absorb clock skew.
+ */
+const decodeExp = (jwt) => {
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const padded = b64 + "==".slice(0, (4 - (b64.length % 4)) % 4);
+        const payload = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+        return typeof payload.exp === "number" ? payload.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const isFresh = (jwt, skewSeconds = 60) => {
+    const exp = decodeExp(jwt);
+    if (exp === undefined)
+        return false;
+    return exp > Math.floor(Date.now() / 1000) + skewSeconds;
+};
+/**
+ * Returns a Bearer JWT for the Sitecore Orchestrate (Campaign) API.
+ *
+ * Resolution order:
+ *   1. Campaign-specific keychain entry (keyed by org id), if unexpired.
+ *   2. Fresh M2M client-credentials mint from the org's AI APIs key —
+ *      `clientId` from the `brand[orgId]` config block, secret from the
+ *      keychain. Cached for next time.
+ *
+ * Refuses with `AUTH_BRAND_REQUIRED` when no AI APIs key is registered.
+ */
+const acquireCampaignToken = async (options) => {
+    const { organizationId, brandCredential } = options;
+    if (!organizationId) {
+        throw (0, errors_1.createScaiError)("Campaign auth needs the environment's organizationId.", "AUTH_BRAND_REQUIRED", { hint: "Set organizationId on the env profile, or run `scai setup init`." });
+    }
+    const cached = await (0, keychain_1.getCampaignToken)(organizationId);
+    if (cached && isFresh(cached)) {
+        return cached;
+    }
+    const clientSecret = await (0, keychain_1.getBrandClientSecret)(organizationId);
+    if (!brandCredential?.clientId || !clientSecret) {
+        throw (0, errors_1.createScaiError)(`No AI APIs key is registered for org '${organizationId}'.`, "AUTH_BRAND_REQUIRED", {
+            hint: "The Orchestrate (Campaign) API authenticates with the AI APIs key — the same credential `scai brand` uses. Register one with `scai setup client register-brand`.",
+        });
+    }
+    const result = await (0, auth_1.requestClientCredentialsToken)({
+        authority: brandCredential.authority ?? "https://auth.sitecorecloud.io",
+        clientId: brandCredential.clientId,
+        clientSecret,
+        audience: brandCredential.audience ?? auth_1.DEFAULT_SITECORE_API_AUDIENCE,
+    });
+    if (!result.accessToken) {
+        throw (0, errors_1.createScaiError)(`Sitecore returned no access token for org '${organizationId}'.`, "AUTH_BRAND_REQUIRED", { hint: "Re-register the AI APIs key with `scai setup client register-brand`." });
+    }
+    await (0, keychain_1.setCampaignToken)(organizationId, result.accessToken);
+    return result.accessToken;
+};
+exports.acquireCampaignToken = acquireCampaignToken;

package/dist/campaigns/client.d.ts

@@ -0,0 +1,25 @@
+import { type CampaignApiClientOptions } from "./api/types";
+/** Options for {@link resolveCampaignClient}. */
+export interface ResolveCampaignClientOptions {
+    /** Explicit organization id; resolved from the env profile otherwise. */
+    orgId?: string;
+    /** Environment profile name — used only to derive its `organizationId`. */
+    environmentName?: string;
+    /** Base directory for resolving `sitecoreai.cli.json`; defaults to cwd. */
+    config?: string;
+}
+/** A resolved Campaign API client plus the organization it is bound to. */
+export interface ResolvedCampaignClient {
+    client: CampaignApiClientOptions;
+    orgId: string;
+}
+/**
+ * Resolve a ready-to-use Campaign (Orchestrate) API client.
+ *
+ * Resolves the organization, acquires an Orchestrate-scoped token via the
+ * org's AI APIs key, and region-resolves the API host from the org id
+ * (an env profile may pin `campaignBaseUrl` to override it). The AI APIs
+ * key may lack `platform.tenants:listall`, so region resolution is
+ * best-effort and falls back to the default region.
+ */
+export declare const resolveCampaignClient: (options?: ResolveCampaignClientOptions) => Promise<ResolvedCampaignClient>;

package/dist/campaigns/client.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCampaignClient = void 0;
+/**
+ * Campaign (Orchestrate API) client resolution — organization lookup,
+ * Orchestrate-scoped token acquisition, and region-resolved host,
+ * assembled into the `CampaignApiClientOptions` that every `./api/*`
+ * operation takes.
+ *
+ * This is the orchestration the CLI runners (`./tasks`) and MCP tools
+ * share. It is exported from the area barrel so an SDK consumer can
+ * obtain a ready client without reaching into the CLI runner layer.
+ *
+ * The Orchestrate API is **org-scoped** — it authenticates with the
+ * org's AI APIs key and lives at organization scope — so this resolves
+ * an organization, not an environment, via the shared `resolveOrganization`
+ * (no `--environment-name` required).
+ *
+ * Presentation-free: no logger, no stdout, no `process.exit`.
+ */
+const organization_1 = require("../policy/organization");
+const region_1 = require("../shared/region");
+const auth_1 = require("./auth");
+const types_1 = require("./api/types");
+/**
+ * Resolve a ready-to-use Campaign (Orchestrate) API client.
+ *
+ * Resolves the organization, acquires an Orchestrate-scoped token via the
+ * org's AI APIs key, and region-resolves the API host from the org id
+ * (an env profile may pin `campaignBaseUrl` to override it). The AI APIs
+ * key may lack `platform.tenants:listall`, so region resolution is
+ * best-effort and falls back to the default region.
+ */
+const resolveCampaignClient = async (options = {}) => {
+    const { orgId, environment, root } = (0, organization_1.resolveOrganization)(options);
+    const accessToken = await (0, auth_1.acquireCampaignToken)({
+        organizationId: orgId,
+        brandCredential: root.brand?.[orgId],
+    });
+    const baseUrl = await (0, region_1.resolveRegionalBaseUrl)({
+        hostTemplate: types_1.CAMPAIGN_API_HOST_TEMPLATE,
+        organizationId: orgId,
+        override: environment?.campaignBaseUrl,
+        acquireToken: async () => accessToken,
+    });
+    return { orgId, client: { accessToken, baseUrl } };
+};
+exports.resolveCampaignClient = resolveCampaignClient;