@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/brand/api/auth.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireBrandToken = exports.hasBrandScopes = exports.extractScopes = exports.BRAND_REQUIRED_SCOPES = void 0;
+const auth_1 = require("../../serialization/api/auth");
+const errors_1 = require("../../shared/errors");
+const keychain_1 = require("../../shared/keychain");
+/**
+ * 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.
+ */
+exports.BRAND_REQUIRED_SCOPES = ["ai.org.br:gen"];
+const NO_CREDENTIAL_HINT = "Run `scai setup login brand --env <env>` to provision the credential, or paste an existing AI APIs key into `brand.<orgId>` in sitecoreai.cli.json (clientId only; secret goes through the keychain via the login flow). Create the credential in Cloud Portal → Stream → Admin → AI APIs keys.";
+const decodeJwtPayload = (token) => {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = b64 + "==".slice(0, (4 - (b64.length % 4)) % 4);
+    try {
+        return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+const extractScopes = (token) => {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return [];
+    const raw = typeof payload.scope === "string"
+        ? payload.scope
+        : Array.isArray(payload.scp)
+            ? payload.scp.join(" ")
+            : "";
+    return raw.split(/\s+/).filter(Boolean);
+};
+exports.extractScopes = extractScopes;
+const hasBrandScopes = (token) => {
+    const granted = new Set((0, exports.extractScopes)(token));
+    return exports.BRAND_REQUIRED_SCOPES.every((s) => granted.has(s));
+};
+exports.hasBrandScopes = hasBrandScopes;
+const DEFAULT_AUTHORITY = "https://auth.sitecorecloud.io";
+/**
+ * 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.
+ */
+const acquireBrandToken = async (options) => {
+    const { orgId, credential } = options;
+    // 1. Cached token keyed by orgId. No scope assertion — the real
+    //    server-side scope enforcement happens on the API call itself,
+    //    and gating here would skip a perfectly usable token whenever
+    //    the operation it's used for doesn't need the validated scope.
+    const cached = await (0, keychain_1.getBrandToken)(orgId);
+    if (cached) {
+        return cached;
+    }
+    // 2. Fresh M2M mint via the AI APIs key.
+    const clientSecret = await (0, keychain_1.getBrandClientSecret)(orgId);
+    if (!credential.clientId || !clientSecret) {
+        throw (0, errors_1.createScaiError)(`No Brand credential is configured for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: NO_CREDENTIAL_HINT });
+    }
+    const authority = credential.authority ?? DEFAULT_AUTHORITY;
+    const audience = credential.audience ?? auth_1.DEFAULT_SITECORE_API_AUDIENCE;
+    // Reuse the shared client-credentials helper. It accepts a
+    // `SitecoreApiClientOptions`-shaped argument; we only need the
+    // auth-relevant fields.
+    const mintEnv = {
+        authority,
+        clientId: credential.clientId,
+        clientSecret,
+        audience,
+    };
+    let result;
+    try {
+        // Mint with NO scope parameter — Auth0 grants whatever the AI APIs
+        // key has been issued, and per-operation scope checks below filter
+        // for the subset scai needs. Requesting scopes the key wasn't
+        // granted causes Auth0 to 403 outright.
+        result = await (0, auth_1.requestClientCredentialsToken)(mintEnv);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw (0, errors_1.createScaiError)(`Auth0 refused the Brand scope request for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: `Auth0 error: ${detail}. ${NO_CREDENTIAL_HINT}` });
+    }
+    if (!result.accessToken) {
+        throw (0, errors_1.createScaiError)(`Sitecore did not return an access token for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: NO_CREDENTIAL_HINT });
+    }
+    // Deliberately do NOT pre-validate scopes here. The Brand API's own
+    // server-side scope enforcement is the source of truth; gating
+    // here either over-blocks (when the API is more permissive than
+    // scai's expected scope list) or under-protects (when scai's list
+    // drifts from the API's actual requirement). Let the call go
+    // through and surface the real `BRAND_API_FAILED` with the
+    // server's `error_description` if the scope is genuinely missing.
+    await (0, keychain_1.setBrandToken)(orgId, result.accessToken);
+    return result.accessToken;
+};
+exports.acquireBrandToken = acquireBrandToken;

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

@@ -0,0 +1,40 @@
+import type { BrandCredential } from "../../config/types";
+export interface BrandApiClientOptions {
+    /**
+     * Sitecore organization ID. Required because AI APIs keys are
+     * one-org-per-credential — the orgId selects which credential to
+     * use, and shows up in Brand Management URLs (`/organizations/{orgId}/…`).
+     */
+    orgId: string;
+    /** Credential record from `brand[orgId]` in the root config. */
+    credential: BrandCredential;
+    /** Override the API host. Defaults to edge-platform.sitecorecloud.io. */
+    host?: string;
+}
+export interface BrandApiRequest {
+    /** Base path under the API host (e.g. `/stream/ai-skills-api`). */
+    basePath: string;
+    /** Path appended to `basePath`. Should start with a slash. */
+    path: string;
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    query?: Record<string, string | undefined>;
+    /** Parsed JSON body. Stringified by the client. */
+    body?: unknown;
+    /** Optional AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Issue a single request to a Brand API and parse JSON.
+ *
+ * Auth handling:
+ *   - Acquires a token via `acquireBrandToken` (cache → mint).
+ *   - On 401, clears the cached token once and retries. This handles
+ *     the documented 24h token expiry; if the retry also 401s we
+ *     surface the failure rather than loop.
+ *
+ * Errors surface as `BRAND_API_FAILED` with the server's
+ * `error_description` / `detail` / `message` in the message, leaving
+ * `AUTH_BRAND_REQUIRED` for credential-resolution failures inside
+ * `acquireBrandToken`.
+ */
+export declare const requestBrandApi: <TResponse>(client: BrandApiClientOptions, request: BrandApiRequest) => Promise<TResponse>;

package/dist/brand/api/client.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestBrandApi = void 0;
+const errors_1 = require("../../shared/errors");
+const keychain_1 = require("../../shared/keychain");
+const auth_1 = require("./auth");
+const types_1 = require("./types");
+const buildUrl = (host, basePath, path, query) => {
+    const url = new URL(`${basePath.replace(/\/$/, "")}${path}`, host);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    return url.toString();
+};
+const parseErrorBody = async (response) => {
+    const text = await response.text();
+    try {
+        const parsed = JSON.parse(text);
+        return (parsed.error_description ??
+            parsed.detail ??
+            parsed.message ??
+            parsed.error ??
+            parsed.title ??
+            text);
+    }
+    catch {
+        return text;
+    }
+};
+/**
+ * Issue a single request to a Brand API and parse JSON.
+ *
+ * Auth handling:
+ *   - Acquires a token via `acquireBrandToken` (cache → mint).
+ *   - On 401, clears the cached token once and retries. This handles
+ *     the documented 24h token expiry; if the retry also 401s we
+ *     surface the failure rather than loop.
+ *
+ * Errors surface as `BRAND_API_FAILED` with the server's
+ * `error_description` / `detail` / `message` in the message, leaving
+ * `AUTH_BRAND_REQUIRED` for credential-resolution failures inside
+ * `acquireBrandToken`.
+ */
+const requestBrandApi = async (client, request) => {
+    const host = client.host ?? types_1.BRAND_API_HOST;
+    const url = buildUrl(host, request.basePath, request.path, request.query);
+    const fire = async (token) => fetch(url, {
+        method: request.method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+            ...(request.body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        body: request.body !== undefined ? JSON.stringify(request.body) : undefined,
+        signal: request.signal,
+    });
+    let token = await (0, auth_1.acquireBrandToken)({
+        orgId: client.orgId,
+        credential: client.credential,
+    });
+    let response = await fire(token);
+    if (response.status === 401) {
+        await (0, keychain_1.clearBrandToken)(client.orgId);
+        token = await (0, auth_1.acquireBrandToken)({
+            orgId: client.orgId,
+            credential: client.credential,
+        });
+        response = await fire(token);
+    }
+    if (!response.ok) {
+        const detail = await parseErrorBody(response);
+        throw (0, errors_1.createScaiError)(`Brand API ${request.method} ${request.path} failed (${response.status}): ${detail || "Unknown error"}`, "BRAND_API_FAILED");
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    return (await response.json());
+};
+exports.requestBrandApi = requestBrandApi;

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

@@ -0,0 +1,119 @@
+/**
+ * Convenience types layered over the codegen'd OpenAPI schemas for the
+ * Sitecore Brand APIs (Brand Management + Brand Review). The raw
+ * schemas are at `./schema.brand-management.d.ts` and
+ * `./schema.brand-review.d.ts`; these aliases give scai's library
+ * surface a stable, callable shape without exposing the underlying
+ * `components["schemas"][…]` indirection on every property access.
+ *
+ * Where the API's wire shape doesn't match what callers want
+ * (response → flattened section/field results, free-text input →
+ * keyed `input` map, etc.), the mapping happens in `generate.ts` and
+ * sibling primitives. These types stay close to what consumers see.
+ */
+import type { components as BrandReviewComponents } from "./schema.brand-review";
+/** Hostname for the Brand APIs. Same edge host as the Publishing API. */
+export declare const BRAND_API_HOST = "https://edge-platform.sitecorecloud.io";
+/** Base path for the Brand Management API. */
+export declare const BRAND_MANAGEMENT_BASE_PATH = "/stream/ai-brands-api";
+/** Base path for the Brand Review API. */
+export declare const BRAND_REVIEW_BASE_PATH = "/stream/ai-skills-api";
+/**
+ * Predefined brand kit section names. The Sitecore docs reference
+ * "Brand Context", "Global Goals", "Tone of Voice", and "Glossary and
+ * Localization" as defaults; other sections like "Do's and Don'ts",
+ * "Grammar Checklists", and "Visual Guidelines" appear in the Brand
+ * Review docs. Kept as a string-and-known-literals union for
+ * autocomplete; the API addresses sections by UUID, not by name —
+ * scai's caller-facing layer maps names ↔ IDs in a follow-up slice
+ * once Brand Management read primitives land.
+ */
+export type BrandKitSectionName = "Brand Context" | "Global Goals" | "Tone of Voice" | "Glossary and Localization" | "Do's and Don'ts" | "Grammar Checklists" | "Visual Guidelines" | (string & {});
+/** Compliance score domain documented in the Brand Review API. */
+export type BrandReviewScore = 1 | 2 | 3 | 4 | 5;
+/**
+ * Section selector for Brand Review.
+ *
+ *   - `sectionId` (UUID) is required.
+ *   - `fieldIds` narrows to specific subsections within the section.
+ *     Empty / unset → every field in the section is evaluated.
+ *
+ * Mirrors the API's `Section` schema 1:1.
+ */
+export type BrandReviewSectionSelector = BrandReviewComponents["schemas"]["Section"];
+/**
+ * Flattened result for one section (or one field within a section) of
+ * a Brand Review. scai's formatters consume this shape uniformly;
+ * `generate.ts` normalizes the API's nested
+ * `{ reviews: [{ sectionId, score, fields: [{ fieldId, score }] }] }`
+ * structure into a flat list of `BrandReviewSectionResult`s — one
+ * per section + one per field — so per-field findings drive SARIF /
+ * JSON entries without requiring consumers to walk nested arrays.
+ *
+ * `section` carries the UUID until name lookup lands; `field` is the
+ * subsection UUID. Suggestions are wrapped in an array for forward
+ * compatibility (the API exposes a single `suggestion` string today).
+ */
+export interface BrandReviewSectionResult {
+    /** Section UUID (or, eventually, resolved name). */
+    section: string;
+    /** Subsection (field) UUID, present for per-field results. */
+    field?: string;
+    /** 1..5; 5 = strongest alignment with the brand guidelines. */
+    score: BrandReviewScore;
+    /** Why this score was assigned. */
+    explanation?: string;
+    /** Improvement suggestions. */
+    suggestions?: string[];
+}
+export interface BrandReviewResult {
+    /**
+     * scai-computed headline score for the run, derived as the minimum
+     * across every section + field score in the response. Conservative
+     * by design — a CI threshold gate should react to the worst finding,
+     * not the average. The Brand Review API does NOT return an overall
+     * score; this is a client-side aggregation.
+     */
+    overallScore: BrandReviewScore;
+    /**
+     * Flat list: one entry per section, plus one entry per field, in
+     * the order the API returned them. Sections come before their
+     * fields.
+     */
+    sectionResults: BrandReviewSectionResult[];
+    /** Raw server payload — escape hatch for inspection/debugging. */
+    raw?: BrandReviewComponents["schemas"]["GenerateBrandReviewModelResponse"];
+}
+/**
+ * Caller-facing input shape for one review call.
+ *
+ *   - `text` is the convenience path for raw text / markdown / JSON
+ *     content (the headline use case). When set, scai sends the API's
+ *     `input` map with a single `"content"` key.
+ *   - `extra` lets advanced callers add arbitrary `input.*` keys
+ *     (e.g. file refs per the `ExtractableFile` schema) without
+ *     dropping to the raw transport.
+ *   - `label` is scai-local — used for downstream formatting and
+ *     SARIF `physicalLocation` URIs. NOT sent to the API.
+ */
+export interface BrandReviewInput {
+    text?: string;
+    /** Free-form additional `input.*` fields per the API's flexible-map shape. */
+    extra?: Record<string, unknown>;
+    /** Caller-supplied label, e.g. file path or test name. */
+    label?: string;
+}
+/** Selector targeting a specific brand kit + optional narrowing. */
+export interface BrandReviewSelector {
+    brandKitId: string;
+    /**
+     * Restrict the evaluation to these sections (and optionally to
+     * specific fields within them). Empty/undefined → evaluate against
+     * every section in the brand kit.
+     *
+     * Note: sectionId / fieldIds are UUIDs (see Brand Management API).
+     * scai's CLI exposes `--section-id` directly; friendly name lookup
+     * lands once the Brand Management read primitives ship.
+     */
+    sections?: BrandReviewSectionSelector[];
+}

package/dist/brand/api/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRAND_REVIEW_BASE_PATH = exports.BRAND_MANAGEMENT_BASE_PATH = exports.BRAND_API_HOST = void 0;
+/** Hostname for the Brand APIs. Same edge host as the Publishing API. */
+exports.BRAND_API_HOST = "https://edge-platform.sitecorecloud.io";
+/** Base path for the Brand Management API. */
+exports.BRAND_MANAGEMENT_BASE_PATH = "/stream/ai-brands-api";
+/** Base path for the Brand Review API. */
+exports.BRAND_REVIEW_BASE_PATH = "/stream/ai-skills-api";

package/dist/brand/credential.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Brand credential resolution shared by every `scai brand` surface and
+ * by `scai setup login brand`.
+ *
+ * Two layers:
+ *   - `resolveBrandOrgId` — the pure orgId-resolution rule.
+ *   - `resolveBrandClient` — reads the config, resolves the orgId, looks
+ *     up the `brand[orgId]` credential, and returns the API client
+ *     options a brand operation needs.
+ *
+ * (`src/brand/recipe/client.ts` has a separate `resolveBrandClient` that
+ * resolves from a sync `SyncContext` rather than CLI options — the sync
+ * engine always carries an explicit environment, so it does not need
+ * the fallbacks here.)
+ */
+import type { BrandApiClientOptions } from "./api/client";
+/**
+ * Resolve the Sitecore `organizationId` for a Brand credential.
+ * Resolution order:
+ *
+ *   1. Explicit `orgId` (e.g. from `--org-id`).
+ *   2. When an env was explicitly named — via `--environment-name` or a
+ *      configured `defaultEnvProfile` — that env profile's
+ *      `organizationId`. A named env is authoritative: we never fall
+ *      through to a different profile's org behind the operator's back.
+ *   3. When no env was named: the first env profile that carries an
+ *      `organizationId`. A single-environment config resolves here with
+ *      no flag and no default — you don't have to designate a default
+ *      env just to use the brand surface.
+ *
+ * Fails with `INPUT_INVALID` when none of the above yields a value —
+ * scai's Brand credentials are one-org-per-credential and we can't
+ * act without an org key.
+ *
+ * Exported for unit testing the resolution branches.
+ */
+export declare const resolveBrandOrgId: (explicitOrgId: string | undefined, environments: Record<string, {
+    organizationId?: string;
+}>, envName: string | undefined) => string;
+/** The slice of CLI options `resolveBrandClient` needs. */
+export interface BrandClientResolveOptions {
+    config?: string;
+    environmentName?: string;
+    orgId?: string;
+}
+/**
+ * Resolve the `BrandApiClientOptions` a `scai brand` operation runs
+ * against: read the config, resolve the orgId (see `resolveBrandOrgId`),
+ * and look up the `brand[orgId]` credential.
+ *
+ * Throws `AUTH_BRAND_REQUIRED` when the org resolves but has no
+ * registered credential — the operator must run `scai setup login brand`
+ * first.
+ */
+export declare const resolveBrandClient: (options: BrandClientResolveOptions) => BrandApiClientOptions;

package/dist/brand/credential.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Brand credential resolution shared by every `scai brand` surface and
+ * by `scai setup login brand`.
+ *
+ * Two layers:
+ *   - `resolveBrandOrgId` — the pure orgId-resolution rule.
+ *   - `resolveBrandClient` — reads the config, resolves the orgId, looks
+ *     up the `brand[orgId]` credential, and returns the API client
+ *     options a brand operation needs.
+ *
+ * (`src/brand/recipe/client.ts` has a separate `resolveBrandClient` that
+ * resolves from a sync `SyncContext` rather than CLI options — the sync
+ * engine always carries an explicit environment, so it does not need
+ * the fallbacks here.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBrandClient = exports.resolveBrandOrgId = void 0;
+const root_config_1 = require("../config/root-config");
+const errors_1 = require("../shared/errors");
+const cli_tasks_1 = require("../shared/cli-tasks");
+/**
+ * Resolve the Sitecore `organizationId` for a Brand credential.
+ * Resolution order:
+ *
+ *   1. Explicit `orgId` (e.g. from `--org-id`).
+ *   2. When an env was explicitly named — via `--environment-name` or a
+ *      configured `defaultEnvProfile` — that env profile's
+ *      `organizationId`. A named env is authoritative: we never fall
+ *      through to a different profile's org behind the operator's back.
+ *   3. When no env was named: the first env profile that carries an
+ *      `organizationId`. A single-environment config resolves here with
+ *      no flag and no default — you don't have to designate a default
+ *      env just to use the brand surface.
+ *
+ * Fails with `INPUT_INVALID` when none of the above yields a value —
+ * scai's Brand credentials are one-org-per-credential and we can't
+ * act without an org key.
+ *
+ * Exported for unit testing the resolution branches.
+ */
+const resolveBrandOrgId = (explicitOrgId, environments, envName) => {
+    if (explicitOrgId) {
+        return explicitOrgId;
+    }
+    if (envName) {
+        const named = environments[envName];
+        if (named?.organizationId) {
+            return named.organizationId;
+        }
+        throw (0, cli_tasks_1.inputError)(`Cannot resolve organizationId for Brand credential (env '${envName}' has no organizationId).`, "Pass --org-id <id>, or set organizationId on the env profile in sitecoreai.cli.json.");
+    }
+    // No env named and no defaultEnvProfile configured: fall back to the
+    // env profiles. The first profile that carries an organizationId wins.
+    const fromProfile = Object.values(environments).find((env) => env.organizationId);
+    if (fromProfile?.organizationId) {
+        return fromProfile.organizationId;
+    }
+    throw (0, cli_tasks_1.inputError)("Cannot resolve organizationId for Brand credential.", "Pass --org-id <id>, or set organizationId on an env profile in sitecoreai.cli.json.");
+};
+exports.resolveBrandOrgId = resolveBrandOrgId;
+/**
+ * Resolve the `BrandApiClientOptions` a `scai brand` operation runs
+ * against: read the config, resolve the orgId (see `resolveBrandOrgId`),
+ * and look up the `brand[orgId]` credential.
+ *
+ * Throws `AUTH_BRAND_REQUIRED` when the org resolves but has no
+ * registered credential — the operator must run `scai setup login brand`
+ * first.
+ */
+const resolveBrandClient = (options) => {
+    const configPath = options.config ?? process.cwd();
+    const root = (0, root_config_1.readRootConfiguration)(configPath, options.environmentName);
+    // `root.defaultEnvProfile` is the raw config value (undefined when no
+    // default is set) — distinct from `root.defaultEnvironment`, which
+    // collapses an unset default to the literal "default". Only an
+    // explicit flag or a real configured default counts as a named env.
+    const envName = options.environmentName ?? root.defaultEnvProfile;
+    const orgId = (0, exports.resolveBrandOrgId)(options.orgId, root.environments, envName);
+    const credential = root.brand?.[orgId];
+    if (!credential) {
+        const envFlag = envName ? ` -n ${envName}` : "";
+        throw (0, errors_1.createScaiError)(`No Brand credential is configured for org '${orgId}'.`, "AUTH_BRAND_REQUIRED", { hint: `Run \`scai setup login brand${envFlag}\` to provision one.` });
+    }
+    return { orgId, credential };
+};
+exports.resolveBrandClient = resolveBrandClient;

package/dist/brand/documents/list.d.ts

@@ -0,0 +1,85 @@
+import { type BrandApiClientOptions } from "../api/client";
+export interface DocumentSummary {
+    /** Document UUID. */
+    id: string;
+    /** Lifecycle: pending | processed | draft | active | archived | edited | failed. */
+    status?: string;
+    /** Whether the ingestion pipeline has chunked the doc. */
+    chunked?: boolean | null;
+    /** Whether the enrichment pipeline has summarized the doc. */
+    summarized?: boolean | null;
+    /** Source URL (Sitecore MMS for uploaded docs). */
+    url?: string;
+    /** Sitecore MMS file UUID. */
+    fileId?: string;
+    /** Caller-supplied label (e.g. "brand guidelines"). */
+    type?: string | null;
+    /** MIME type (e.g. "application/pdf"). */
+    fileType?: string;
+    /** Server-detected page count. `0` indicates the parser failed. */
+    numberOfPages?: number;
+    /** Display title. */
+    title?: string | null;
+    /** Brief description. */
+    summary?: string;
+    /** Tags (auto-extracted by enrichment, e.g. section names). */
+    tags?: string[];
+    /** Brand kit binding. */
+    brandkitId?: string;
+    /** Reference back-links. */
+    references?: Array<{
+        id: string;
+        path: string;
+        type: string;
+    }>;
+    createdOn?: string;
+    createdBy?: string;
+    updatedOn?: string;
+    updatedBy?: string;
+    [extra: string]: unknown;
+}
+export interface ListDocumentsResponse {
+    totalCount: number;
+    pageSize?: number;
+    pageNumber?: number;
+    data: DocumentSummary[];
+}
+export interface ListDocumentsOptions {
+    client: BrandApiClientOptions;
+    /** Filter to documents bound to this kit. */
+    brandKitId?: string;
+    /** Filter by status (e.g. `"processed"`, `"failed"`). */
+    status?: string;
+    /** Pagination. */
+    pageNumber?: number;
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+/**
+ * List documents in the org, optionally filtered by brand kit and/or
+ * status. Paginated. The `data[i].status` field is the most useful
+ * filter for finding broken uploads.
+ */
+export declare const listDocuments: (options: ListDocumentsOptions) => Promise<ListDocumentsResponse>;
+export interface GetDocumentOptions {
+    client: BrandApiClientOptions;
+    documentId: string;
+    signal?: AbortSignal;
+}
+/**
+ * Retrieve a single document by UUID. Useful for polling pipeline
+ * progress — `chunked` / `summarized` / `status` update as the
+ * server-side AI processes the file.
+ */
+export declare const getDocument: (options: GetDocumentOptions) => Promise<DocumentSummary>;
+export interface DeleteDocumentOptions {
+    client: BrandApiClientOptions;
+    documentId: string;
+    signal?: AbortSignal;
+}
+/**
+ * Delete a document. Per the OpenAPI, the DELETE endpoint lives on
+ * v1 (not v2): `DELETE /api/documents/v1/.../documents/{id}` returns
+ * `204`.
+ */
+export declare const deleteDocument: (options: DeleteDocumentOptions) => Promise<void>;

package/dist/brand/documents/list.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteDocument = exports.getDocument = exports.listDocuments = void 0;
+const client_1 = require("../api/client");
+const upload_1 = require("./upload");
+/**
+ * List documents in the org, optionally filtered by brand kit and/or
+ * status. Paginated. The `data[i].status` field is the most useful
+ * filter for finding broken uploads.
+ */
+const listDocuments = async (options) => {
+    return (0, client_1.requestBrandApi)(options.client, {
+        basePath: upload_1.DOCUMENTS_BASE_PATH,
+        path: `/api/documents/v2/organizations/${options.client.orgId}/documents`,
+        method: "GET",
+        query: {
+            brandkitId: options.brandKitId,
+            status: options.status,
+            pageNumber: options.pageNumber !== undefined ? String(options.pageNumber) : undefined,
+            pageSize: options.pageSize !== undefined ? String(options.pageSize) : undefined,
+        },
+        signal: options.signal,
+    });
+};
+exports.listDocuments = listDocuments;
+/**
+ * Retrieve a single document by UUID. Useful for polling pipeline
+ * progress — `chunked` / `summarized` / `status` update as the
+ * server-side AI processes the file.
+ */
+const getDocument = async (options) => {
+    return (0, client_1.requestBrandApi)(options.client, {
+        basePath: upload_1.DOCUMENTS_BASE_PATH,
+        path: `/api/documents/v2/organizations/${options.client.orgId}/documents/${options.documentId}`,
+        method: "GET",
+        signal: options.signal,
+    });
+};
+exports.getDocument = getDocument;
+/**
+ * Delete a document. Per the OpenAPI, the DELETE endpoint lives on
+ * v1 (not v2): `DELETE /api/documents/v1/.../documents/{id}` returns
+ * `204`.
+ */
+const deleteDocument = async (options) => {
+    await (0, client_1.requestBrandApi)(options.client, {
+        basePath: upload_1.DOCUMENTS_BASE_PATH,
+        path: `/api/documents/v1/organizations/${options.client.orgId}/documents/${options.documentId}`,
+        method: "DELETE",
+        signal: options.signal,
+    });
+};
+exports.deleteDocument = deleteDocument;