@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/brief/api/request.d.ts

@@ -0,0 +1,5 @@
+import { type BriefApiClientOptions, type BriefQueryRecord, type BriefRequestInit } from "./types";
+export declare const briefRequest: <TResponse>(options: BriefApiClientOptions, path: string, init?: BriefRequestInit & {
+    body?: unknown;
+    query?: BriefQueryRecord;
+}) => Promise<TResponse>;

package/dist/brief/api/request.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.briefRequest = 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");
+/**
+ * Brief API transport — `briefRequest()`.
+ *
+ * Mirrors `sitesRequest()` from `src/sites/api/request.ts`: bearer auth,
+ * JSON request/response, error mapping that surfaces Sitecore's
+ * structured error bodies. Differences vs Sites:
+ *
+ *  - Different base URL (`co-brief-api-<region>.sitecorecloud.io`) — Brief
+ *    is regional, so callers typically pass `baseUrl` from the env config.
+ *  - Schema is reverse-engineered, not OpenAPI-codegen-driven (no public
+ *    spec at time of writing). Helpers in sibling files type response
+ *    shapes by hand from observed responses.
+ *
+ * Errors map to scai's `ScaiError` — `NETWORK` for transport failures,
+ * `BRIEF_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}` : "";
+};
+const briefRequest = async (options, path, init) => {
+    const baseUrl = options.baseUrl ?? types_1.DEFAULT_BRIEF_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)(`Brief 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;
+        throw (0, errors_1.createScaiError)(sanitized ?? `Brief API request failed (${response.status})`, "BRIEF_API_FAILED");
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    return (await (0, request_1.parseJsonIfPossible)(response));
+};
+exports.briefRequest = briefRequest;

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

@@ -0,0 +1,158 @@
+/**
+ * Brief API response schema — hand-written from observed payloads.
+ *
+ * The API has no published OpenAPI spec at time of writing, so these
+ * types reflect what `scripts/_smoke-brief-shapes.ts` captured against
+ * the Agents env on 2026-05-14. Re-run that probe and diff this file
+ * if the API surface changes.
+ *
+ * Conventions observed across the API:
+ *  - List endpoints return a paged envelope: `{ totalCount, next, data }`
+ *  - References use a discriminated union (`Link` vs `ExternalLink`)
+ *  - Internal IDs are GUIDs; external IDs carry their provenance
+ *    (`auth0|...`, `<clientId>@clients`)
+ *  - Localized strings are keyed by BCP-47-ish locale (`{ "en-us": "..." }`)
+ *  - Timestamps are ISO-8601 with sub-second precision
+ */
+/** Paged list envelope returned by every Brief list endpoint. */
+export type PagedResult<T> = {
+    totalCount: number;
+    /** Cursor for the next page, or null at end of stream. Shape TBD — pass through verbatim. */
+    next: string | null;
+    data: T[];
+};
+/** Localized label: BCP-47-ish locale (e.g. `en-us`) → string. */
+export type LocalizedString = Record<string, string>;
+/** Reference to another resource inside the Brief API itself. */
+export type Link = {
+    type: "Link";
+    /** The resource kind the link points at, e.g. `BriefType`. */
+    relatedType: string;
+    /** GUID of the related resource. */
+    id: string;
+    /** Absolute URI you can GET to dereference. */
+    uri: string;
+};
+/** Reference to a resource owned by a sibling Sitecore Cloud service. */
+export type ExternalLink = {
+    type: "ExternalLink";
+    /** Source system slug, e.g. `xmcloud`, `co`. */
+    relatedSystem: string;
+    relatedType: string | null;
+    /** Foreign identifier — Auth0 subject, client-credentials principal, etc. */
+    id: string;
+};
+export type Reference = Link | ExternalLink;
+/**
+ * BriefType field definition — discriminated on `type`. The Brief API
+ * uses these to drive UI form generation and feed `aiIntent` hints to
+ * downstream AI assistants editing the brief's content.
+ */
+export type BriefFieldBase = {
+    name: string;
+    label: LocalizedString;
+    helpText?: LocalizedString;
+    required: boolean;
+    /** Whether AI assistants may write this field. Read for `aiIntent` either way. */
+    aiEditable: boolean;
+    /** Free-form prompt the API ships to AI clients describing how to fill the field. */
+    aiIntent?: string;
+};
+export type RichTextField = BriefFieldBase & {
+    type: "RichText";
+};
+export type DateTimeField = BriefFieldBase & {
+    type: "DateTime";
+};
+export type TimelineField = BriefFieldBase & {
+    type: "Timeline";
+    /** Schedule calculation strategy enum — observed values include `0`. Semantics TBD. */
+    calculation: number;
+    skipHolidays: boolean;
+    skipWeekend: boolean;
+    /** IANA tz string, may be empty. */
+    timezone: string;
+};
+export type BudgetField = BriefFieldBase & {
+    type: "Budget";
+    /** ISO-4217 currency codes the field accepts. */
+    currencies: string[];
+};
+/** Union of every observed field kind. New kinds will widen this union. */
+export type BriefField = RichTextField | DateTimeField | TimelineField | BudgetField;
+/** BriefType — the schema template a brief instance is built against. */
+export type BriefType = {
+    id: string;
+    /** Stable codename, e.g. `CreativeBrief`. */
+    name: string;
+    /** Localized human label. */
+    label: LocalizedString;
+    /** mdi icon codepoint name. */
+    icon: string;
+    iconColor: string;
+    description: string;
+    /** Field definitions in display order. */
+    fields: BriefField[];
+    createdOn: string;
+    createdBy: Reference;
+    updatedOn: string;
+    updatedBy: Reference;
+};
+/**
+ * Brief workflow status. The full enum was surfaced by the API's own
+ * validation error (2026-05-15): "Status must be one of: Approved,
+ * InReview, Draft, Canceled, Archived". `InReview` is the wire value
+ * for the "In Review" UI label.
+ */
+export type BriefStatus = "Draft" | "InReview" | "Approved" | "Canceled" | "Archived";
+/**
+ * Brief instance — the unit of work. `status` is freely writable via
+ * `PUT /briefs/{id}` (not workflow-gated).
+ */
+export type Brief = {
+    id: string;
+    icon: string | null;
+    name: string;
+    status: BriefStatus;
+    /** BCP-47-ish locale, e.g. `en-us`. */
+    locale: string;
+    /** Field values keyed by `BriefField.name`. Shape per-field TBD. */
+    fields: Record<string, unknown>;
+    briefType: Link;
+    isTemplate: boolean;
+    /** Inline collections returned with the brief. May be empty on list responses. */
+    comments: BriefComment[];
+    /** To-dos on the brief. Wire field is `tasks`; the UI/CLI label is "to-do". */
+    tasks: BriefTask[];
+    references: Reference[];
+    contributors: Reference[];
+    externalMappings: ExternalMapping[];
+    createdOn: string;
+    createdBy: Reference;
+    updatedOn: string;
+    updatedBy: Reference;
+};
+/** Cross-system mapping rows tying a brief to records in other Sitecore Cloud services. */
+export type ExternalMapping = Record<string, unknown>;
+/**
+ * Task on a brief. Shape is **provisional** — no task payload was
+ * captured during reverse-engineering (the test brief has zero tasks).
+ * Re-probe when a brief with tasks is available and tighten this type.
+ *
+ * Naming note: the Content Operations UI — and scai's CLI/MCP surface —
+ * call these "to-dos". This wire type keeps the API's `task` naming for
+ * fidelity; the user-facing label is "to-do" (`scai ops brief todos`).
+ */
+export type BriefTask = {
+    id: string;
+    [key: string]: unknown;
+};
+/**
+ * Comment on a brief. Shape is **provisional** — no comment payload
+ * was captured during reverse-engineering. Re-probe when comments
+ * exist.
+ */
+export type BriefComment = {
+    id: string;
+    [key: string]: unknown;
+};

package/dist/brief/api/schema.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Brief API response schema — hand-written from observed payloads.
+ *
+ * The API has no published OpenAPI spec at time of writing, so these
+ * types reflect what `scripts/_smoke-brief-shapes.ts` captured against
+ * the Agents env on 2026-05-14. Re-run that probe and diff this file
+ * if the API surface changes.
+ *
+ * Conventions observed across the API:
+ *  - List endpoints return a paged envelope: `{ totalCount, next, data }`
+ *  - References use a discriminated union (`Link` vs `ExternalLink`)
+ *  - Internal IDs are GUIDs; external IDs carry their provenance
+ *    (`auth0|...`, `<clientId>@clients`)
+ *  - Localized strings are keyed by BCP-47-ish locale (`{ "en-us": "..." }`)
+ *  - Timestamps are ISO-8601 with sub-second precision
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,41 @@
+import type { BriefTask, PagedResult } from "./schema";
+import type { BriefApiClientOptions } from "./types";
+/**
+ * Tasks resource on the Brief API.
+ *
+ * Naming note: the Content Operations UI — and scai's CLI/MCP surface —
+ * label these "to-dos". The wire resource is `tasks`; the SDK names below
+ * mirror the wire for fidelity. The user-facing surface is `todos`
+ * (`scai ops brief todos`, `runBriefTodosList`, MCP verb 'todos').
+ *
+ * Endpoint surface (reverse-engineered):
+ *   GET /api/brief/v1/tasks?BriefId=<uuid>&MetadataToLoad=assignees
+ *
+ * Known query parameters:
+ *  - `BriefId` (uuid) — filters tasks to a single brief. Optional —
+ *    the bare endpoint returns the tenant-wide task list.
+ *  - `MetadataToLoad` (csv) — expand directives. Confirmed: `assignees`.
+ *    Other valid values TBD.
+ *  - `Limit` (int) — page size.
+ *  - `Next` (string) — pagination cursor from the previous response.
+ *
+ * The task object shape is provisional — the probe tenant had zero
+ * tasks at discovery time. Tighten `BriefTask` in `./schema.ts` once
+ * a payload is captured.
+ */
+/** Metadata expansion options for task list responses. */
+export type BriefTaskMetadata = "assignees";
+export type ListBriefTasksQuery = {
+    /** Filter to one brief. Omit for tenant-wide list. */
+    briefId?: string;
+    /** Expand directives — e.g. `["assignees"]`. */
+    metadataToLoad?: BriefTaskMetadata[];
+    /** Page size. */
+    limit?: number;
+    /** Cursor from previous response. */
+    next?: string;
+};
+/** List tasks (optionally filtered by brief). */
+export declare const listBriefTasks: (options: BriefApiClientOptions, query?: ListBriefTasksQuery) => Promise<PagedResult<BriefTask>>;
+/** Read a single task by id. **Untested** — inferred from REST conventions. */
+export declare const getBriefTask: (options: BriefApiClientOptions, taskId: string) => Promise<BriefTask>;

package/dist/brief/api/tasks.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBriefTask = exports.listBriefTasks = void 0;
+const request_1 = require("./request");
+/** List tasks (optionally filtered by brief). */
+const listBriefTasks = (options, query) => {
+    const params = {};
+    if (query?.briefId)
+        params.BriefId = query.briefId;
+    if (query?.metadataToLoad && query.metadataToLoad.length > 0) {
+        params.MetadataToLoad = query.metadataToLoad.join(",");
+    }
+    if (query?.limit !== undefined)
+        params.Limit = query.limit;
+    if (query?.next)
+        params.Next = query.next;
+    return (0, request_1.briefRequest)(options, "/api/brief/v1/tasks", {
+        query: params,
+    });
+};
+exports.listBriefTasks = listBriefTasks;
+/** Read a single task by id. **Untested** — inferred from REST conventions. */
+const getBriefTask = (options, taskId) => (0, request_1.briefRequest)(options, `/api/brief/v1/tasks/${encodeURIComponent(taskId)}`);
+exports.getBriefTask = getBriefTask;

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

@@ -0,0 +1,17 @@
+export type BriefApiClientOptions = {
+    /** Defaults to the EU-West host. CLI/recipe callers fill it region-aware. */
+    baseUrl?: string;
+    /** Bearer token from `auth.sitecorecloud.io` — required scopes are TBD pending API discovery. */
+    accessToken: string;
+};
+/** Brief host template — `{region}` is filled by `resolveRegionalBaseUrl`. */
+export declare const BRIEF_API_HOST_TEMPLATE = "https://co-brief-api-{region}.sitecorecloud.io";
+/** Fallback host (EU-West) for callers that resolve no region. */
+export declare const DEFAULT_BRIEF_API_BASE: string;
+/** Per-call options shared by every helper. */
+export type BriefRequestInit = {
+    method?: string;
+    headers?: Record<string, string>;
+};
+export type BriefQueryValue = string | number | boolean;
+export type BriefQueryRecord = Record<string, BriefQueryValue | BriefQueryValue[] | undefined>;

package/dist/brief/api/types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRIEF_API_BASE = exports.BRIEF_API_HOST_TEMPLATE = void 0;
+/**
+ * Public configuration shape for Brief API clients. Mirrors
+ * `SitesApiClientOptions` — bring your own access token, optionally
+ * override the base URL.
+ *
+ * Unlike Sites (single global host), Brief is regional: hosts follow
+ * the `co-brief-api-<region>.sitecorecloud.io` pattern (e.g.
+ * `co-brief-api-euw` for EU-West, `co-brief-api-eus` for US-East).
+ * 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");
+/** Brief host template — `{region}` is filled by `resolveRegionalBaseUrl`. */
+exports.BRIEF_API_HOST_TEMPLATE = "https://co-brief-api-{region}.sitecorecloud.io";
+/** Fallback host (EU-West) for callers that resolve no region. */
+exports.DEFAULT_BRIEF_API_BASE = (0, region_1.regionalHost)(exports.BRIEF_API_HOST_TEMPLATE, region_1.DEFAULT_REGION);

package/dist/brief/auth.d.ts

@@ -0,0 +1,44 @@
+import type { SitecoreApiClientOptions } from "../serialization/api/types";
+/**
+ * OAuth scopes the Content Operations Brief API requires.
+ *
+ * Discovered 2026-05-14 by probing the Agents env M2M client:
+ *   - `co.briefs:r` — read briefs, brief types, tasks, comments
+ *   - `co.briefs:w` — create/update/delete briefs, post tasks/comments
+ *
+ * The Agents env automation client carries both by default — minting
+ * a token with no `scope` parameter still includes `co.briefs:r/w` in
+ * the granted claim. Requesting the scopes explicitly is the
+ * least-privilege path and the one used here.
+ */
+export declare const BRIEF_SCOPES_REQUESTED: readonly ["co.briefs:r", "co.briefs:w"];
+export interface AcquireBriefTokenOptions {
+    /**
+     * Sitecore organization id — the Brief API is org-scoped, so the
+     * minted token is cached under `brief:<orgId>` in the OS keychain.
+     */
+    orgId: string;
+    /**
+     * Credential-bearing options used to mint the token: the matched env
+     * profile's client metadata (when one exists — `name`, `clientId`,
+     * `automationClient`, `authority`) plus `organizationId` / `orgClientId`,
+     * so the three-tier credential chain can resolve a usable client.
+     */
+    environment: SitecoreApiClientOptions;
+}
+/**
+ * Returns a Bearer JWT for the Sitecore Content Operations Brief API.
+ *
+ * Resolution order:
+ *   1. Brief-specific keychain entry, if still valid (JWT not expired).
+ *   2. M2M client-credentials mint with `co.briefs:r co.briefs:w`. The
+ *      `clientId` + `clientSecret` are resolved by `resolveClientCredential`
+ *      — the shared three-tier chain: the
+ *      `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` env-var override, then the
+ *      env-scoped automation client in the OS keychain, then the
+ *      org-scoped one. Result is cached.
+ *
+ * Refuses with `AUTH_REQUIRED` if neither path yields a token. There
+ * is no interactive login flow — Brief calls are always agent-driven.
+ */
+export declare const acquireBriefToken: (options: AcquireBriefTokenOptions) => Promise<string>;

package/dist/brief/auth.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireBriefToken = exports.BRIEF_SCOPES_REQUESTED = void 0;
+const auth_1 = require("../serialization/api/auth");
+const client_credential_1 = require("../shared/client-credential");
+const errors_1 = require("../shared/errors");
+const keychain_1 = require("../shared/keychain");
+/**
+ * OAuth scopes the Content Operations Brief API requires.
+ *
+ * Discovered 2026-05-14 by probing the Agents env M2M client:
+ *   - `co.briefs:r` — read briefs, brief types, tasks, comments
+ *   - `co.briefs:w` — create/update/delete briefs, post tasks/comments
+ *
+ * The Agents env automation client carries both by default — minting
+ * a token with no `scope` parameter still includes `co.briefs:r/w` in
+ * the granted claim. Requesting the scopes explicitly is the
+ * least-privilege path and the one used here.
+ */
+exports.BRIEF_SCOPES_REQUESTED = ["co.briefs:r", "co.briefs:w"];
+const M2M_SCOPE_PARAM = exports.BRIEF_SCOPES_REQUESTED.join(" ");
+const SCOPE_DENIED_HINT = "Confirm the environment's automation client is authorized in Auth0 for the co.briefs:r and co.briefs:w scopes.";
+/**
+ * JWT exp claim (seconds since epoch) — used to decide whether a cached
+ * token is still usable. We refresh ~60s early to absorb clock skew and
+ * in-flight request latency.
+ */
+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;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return exp > nowSeconds + skewSeconds;
+};
+/**
+ * Returns a Bearer JWT for the Sitecore Content Operations Brief API.
+ *
+ * Resolution order:
+ *   1. Brief-specific keychain entry, if still valid (JWT not expired).
+ *   2. M2M client-credentials mint with `co.briefs:r co.briefs:w`. The
+ *      `clientId` + `clientSecret` are resolved by `resolveClientCredential`
+ *      — the shared three-tier chain: the
+ *      `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` env-var override, then the
+ *      env-scoped automation client in the OS keychain, then the
+ *      org-scoped one. Result is cached.
+ *
+ * Refuses with `AUTH_REQUIRED` if neither path yields a token. There
+ * is no interactive login flow — Brief calls are always agent-driven.
+ */
+const acquireBriefToken = async (options) => {
+    const cached = await (0, keychain_1.getBriefToken)(options.orgId);
+    if (cached && isFresh(cached)) {
+        return cached;
+    }
+    const env = options.environment;
+    // The client secret never lives in the config file — `resolveClientCredential`
+    // walks the three tiers (env-var override → env-scoped keychain client →
+    // org-scoped keychain client) and pairs the secret with the `clientId`
+    // it is handed from the config-resident metadata. `env.name` is the
+    // matched env profile's name (tiers 1–2); it is `undefined` when the
+    // org was resolved with no env profile, leaving only tier 3.
+    const credential = await (0, client_credential_1.resolveClientCredential)({
+        envName: env.name,
+        clientId: env.clientId,
+        automationClientId: env.automationClient?.clientId,
+        organizationId: env.organizationId,
+        orgClientId: env.orgClientId,
+    });
+    if (credential && env.authority) {
+        try {
+            const result = await (0, auth_1.requestClientCredentialsToken)({ ...env, clientId: credential.clientId, clientSecret: credential.clientSecret }, M2M_SCOPE_PARAM);
+            if (result.accessToken) {
+                await (0, keychain_1.setBriefToken)(options.orgId, result.accessToken);
+                return result.accessToken;
+            }
+        }
+        catch (error) {
+            throw (0, errors_1.createScaiError)("Could not acquire a brief-scoped token via client credentials.", "AUTH_REQUIRED", {
+                hint: `${SCOPE_DENIED_HINT} Underlying error: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    throw (0, errors_1.createScaiError)(`No brief-scoped token available for organization '${options.orgId}'.`, "AUTH_REQUIRED", {
+        hint: "Provide an automation client for the org — run `scai setup env <name>` (env-scoped) or `scai setup client create --org` (org-scoped) to mint one (its secret is stored in the OS keychain), or bring your own by setting SITECOREAI_ENV_<ENV>_CLIENT_ID and SITECOREAI_ENV_<ENV>_CLIENT_SECRET. The Brief API does not support interactive operator login.",
+    });
+};
+exports.acquireBriefToken = acquireBriefToken;

package/dist/brief/client.d.ts

@@ -0,0 +1,25 @@
+import { type BriefApiClientOptions } from "./api/types";
+/** Options for {@link resolveBriefClient}. */
+export interface ResolveBriefClientOptions {
+    /** 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 Brief API client plus the organization it is bound to. */
+export interface ResolvedBriefClient {
+    client: BriefApiClientOptions;
+    orgId: string;
+}
+/**
+ * Resolve a ready-to-use Brief API client for an organization.
+ *
+ * Resolves the org, acquires a `co.briefs:*`-scoped token (minted from
+ * the org's automation client), and region-resolves the API host from
+ * the org id (an env profile may pin `briefBaseUrl` to override it).
+ * Because the brief token is scope-restricted, the region lookup mints
+ * a separate no-scope M2M token.
+ */
+export declare const resolveBriefClient: (options?: ResolveBriefClientOptions) => Promise<ResolvedBriefClient>;

package/dist/brief/client.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBriefClient = void 0;
+/**
+ * Brief API client resolution — organization lookup, brief-scoped token
+ * acquisition, and region-resolved host, assembled into the
+ * `BriefApiClientOptions` 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 Brief API is **org-scoped** — briefs live at organization scope
+ * and the minted token covers the whole org — so this resolves an
+ * organization, not an environment, via the shared `resolveOrganization`
+ * (no `--environment-name` required). An env profile is still consulted,
+ * when one exists, only to supply the automation client that mints the
+ * token.
+ *
+ * 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("../serialization/api/auth");
+const auth_2 = require("./auth");
+const types_1 = require("./api/types");
+/**
+ * Resolve a ready-to-use Brief API client for an organization.
+ *
+ * Resolves the org, acquires a `co.briefs:*`-scoped token (minted from
+ * the org's automation client), and region-resolves the API host from
+ * the org id (an env profile may pin `briefBaseUrl` to override it).
+ * Because the brief token is scope-restricted, the region lookup mints
+ * a separate no-scope M2M token.
+ */
+const resolveBriefClient = async (options = {}) => {
+    const { orgId, environment, root } = (0, organization_1.resolveOrganization)(options);
+    // Brief is org-scoped, but the automation client that mints its token
+    // is env- or org-scoped. Carry the matched env profile's client
+    // metadata (when one exists) plus the org-scoped client id so the
+    // three-tier credential chain can resolve a usable client.
+    const credentialEnv = {
+        ...environment,
+        organizationId: orgId,
+        orgClientId: root.orgClients?.[orgId]?.clientId,
+    };
+    const accessToken = await (0, auth_2.acquireBriefToken)({ orgId, environment: credentialEnv });
+    const baseUrl = await (0, region_1.resolveRegionalBaseUrl)({
+        hostTemplate: types_1.BRIEF_API_HOST_TEMPLATE,
+        organizationId: orgId,
+        override: environment?.briefBaseUrl,
+        acquireToken: async () => (await (0, auth_1.requestClientCredentialsToken)(credentialEnv)).accessToken,
+    });
+    return { orgId, client: { accessToken, baseUrl } };
+};
+exports.resolveBriefClient = resolveBriefClient;

package/dist/brief/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/unstable/brief`.
+ *
+ * Sitecore Content Operations Brief API client. Hosts follow
+ * `co-brief-api-<region>.sitecorecloud.io`; the default is EU-West but
+ * callers normally pass `baseUrl` from per-env config.
+ *
+ * **Status**: UNSTABLE — ships under `./unstable/brief` and carries no
+ * SemVer stability promise; schemas and behavior may change in any
+ * release. Reverse-engineered against the Agents env. Read helpers
+ * (`listBriefs`, `getBrief`, `listBriefTypes`, `getBriefType`,
+ * `listBriefTasks`, `listBriefComments`) verified 2026-05-14. BriefType
+ * writes (`createBriefType`, `updateBriefType`, `deleteBriefType`) verified
+ * end-to-end 2026-05-15 by `scripts/_smoke-brief-types-write.ts`. Brief
+ * writes (`createBrief`, `updateBrief`, `deleteBrief`) are wired but
+ * not yet smoke-tested. `createBriefComment` is wired UNVERIFIED — the
+ * comment write body shape is a best guess (see `./api/comments.ts`).
+ *
+ * Required Auth0 scope: `co.briefs:r` (read) / `co.briefs:r co.briefs:w`
+ * (read+write). The Agents env client carries both by default.
+ */
+export type { BriefApiClientOptions, BriefRequestInit, BriefQueryValue, BriefQueryRecord, } from "./api/types";
+export { BRIEF_API_HOST_TEMPLATE, DEFAULT_BRIEF_API_BASE } from "./api/types";
+export { briefRequest } from "./api/request";
+export type { PagedResult, LocalizedString, Link, ExternalLink, Reference, BriefField, BriefFieldBase, RichTextField, DateTimeField, TimelineField, BudgetField, BriefType, Brief, BriefStatus, BriefTask, BriefComment, ExternalMapping, } from "./api/schema";
+export { listBriefs, getBrief, createBrief, updateBrief, setBriefStatus, deleteBrief, type CreateBriefInput, type ListBriefsQuery, } from "./api/briefs";
+export { listBriefTypes, getBriefType, createBriefType, updateBriefType, deleteBriefType, type CreateBriefTypeInput, } from "./api/brief-types";
+export { listBriefTasks, getBriefTask, type BriefTaskMetadata, type ListBriefTasksQuery, } from "./api/tasks";
+export { listBriefComments, createBriefComment, type ListBriefCommentsQuery, type CreateBriefCommentInput, } from "./api/comments";
+export { acquireBriefToken, BRIEF_SCOPES_REQUESTED, type AcquireBriefTokenOptions } from "./auth";
+export { resolveBriefClient, type ResolveBriefClientOptions, type ResolvedBriefClient, } from "./client";