@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/deploy/api/clients.d.ts

@@ -0,0 +1,126 @@
+/**
+ * XM Cloud Deploy **clients API** (`/api/clients/v1/*`) — mint and manage
+ * OAuth automation credentials.
+ *
+ * Unlike the rest of the Deploy API (which operates on already-existing
+ * resources), these endpoints **create credentials**: each mint call
+ * returns a fresh `{ clientId, clientSecret }` pair. The `clientSecret`
+ * is shown **once** in the response and is never retrievable again —
+ * callers must persist it immediately.
+ *
+ * Two scopes of client:
+ *   - **Environment-scoped** — `cm`, `edge`, `ehbuild`. The request
+ *     carries `projectId` + `environmentId`; the credential is bound to
+ *     that one environment.
+ *   - **Organization-scoped** — `deploy`. The request carries only a
+ *     name; the credential can deploy across the whole organization.
+ *
+ * Every endpoint runs under the Deploy API's `ValidateOrganization` +
+ * `xmclouddeploy.clients:manage` auth policies. Pass `organizationId`
+ * so the request carries the org headers `ValidateOrganization` expects.
+ */
+import type { DeployApiClientOptions } from "./common/types";
+/**
+ * Request body for an environment-scoped client mint (`cm`, `edge`,
+ * `ehbuild`). All three share this shape — the credential is bound to
+ * the named project + environment.
+ */
+export interface CreateEnvironmentClientRequest {
+    /** Display name for the client. Shows in the Cloud Portal clients list. */
+    name: string;
+    /** Optional human description. */
+    description?: string;
+    /** Project the credential is scoped to. */
+    projectId: string;
+    /** Environment the credential is scoped to. */
+    environmentId: string;
+}
+/**
+ * Request body for an organization-scoped deploy client mint. Deploy
+ * clients are not bound to an environment — they carry only a name.
+ */
+export interface CreateDeployClientRequest {
+    /** Display name for the client. */
+    name: string;
+    /** Optional human description. */
+    description?: string;
+}
+/**
+ * Response from any mint endpoint. The `clientSecret` is returned **once
+ * only** — persist it before discarding this object.
+ */
+export interface MintedClient {
+    name?: string;
+    description?: string;
+    clientId?: string;
+    /** The one-time client secret. Never retrievable after this response. */
+    clientSecret?: string;
+}
+/**
+ * A client as returned by the environment-scoped list endpoint. Carries
+ * no secret. `clientType` is the raw numeric `AuthenticationClientType`
+ * enum (1–4); the spec does not name the values, so it is surfaced
+ * unmapped.
+ */
+export interface DeployClientSummary {
+    id?: string;
+    name?: string;
+    description?: string;
+    clientId?: string;
+    createdAt?: string;
+    /** Raw AuthenticationClientType enum (1–4). Value→kind mapping not in the spec. */
+    clientType?: number;
+    projectName?: string;
+    environmentName?: string;
+}
+/** A client as returned by the organization-scoped list endpoint. */
+export interface OrganizationClientSummary {
+    id?: string;
+    name?: string;
+    description?: string;
+    clientId?: string;
+    createdAt?: string;
+    /** Raw AuthenticationClientType enum (1–4). Value→kind mapping not in the spec. */
+    clientType?: number;
+}
+export interface ClientsListResponse {
+    items?: DeployClientSummary[];
+}
+export interface OrganizationClientsListResponse {
+    items?: OrganizationClientSummary[];
+}
+/**
+ * Mint a **CM client** — an environment-scoped credential for the
+ * Content Management / Authoring surface of one environment.
+ */
+export declare const mintCmClient: (options: DeployApiClientOptions, request: CreateEnvironmentClientRequest, organizationId?: string) => Promise<MintedClient>;
+/**
+ * Mint a **deploy client** — an organization-scoped credential able to
+ * run deployments across the whole org.
+ */
+export declare const mintDeployClient: (options: DeployApiClientOptions, request: CreateDeployClientRequest, organizationId?: string) => Promise<MintedClient>;
+/**
+ * Mint an **edge client** — an environment-scoped credential for the
+ * Experience Edge delivery surface of one environment.
+ */
+export declare const mintEdgeClient: (options: DeployApiClientOptions, request: CreateEnvironmentClientRequest, organizationId?: string) => Promise<MintedClient>;
+/**
+ * Mint an **editing-host build client** — an environment-scoped
+ * credential used by editing-host build pipelines.
+ */
+export declare const mintEhBuildClient: (options: DeployApiClientOptions, request: CreateEnvironmentClientRequest, organizationId?: string) => Promise<MintedClient>;
+/**
+ * List the environment-scoped clients (`cm`, `edge`, `ehbuild`) in the
+ * organization. Secrets are never included.
+ */
+export declare const listEnvironmentClients: (options: DeployApiClientOptions, organizationId?: string) => Promise<ClientsListResponse>;
+/**
+ * List the organization-scoped clients (`deploy`). Secrets are never
+ * included.
+ */
+export declare const listOrganizationClients: (options: DeployApiClientOptions, organizationId?: string) => Promise<OrganizationClientsListResponse>;
+/**
+ * Delete a client by id. Irreversible — the credential stops working
+ * immediately. Server responds `202 Accepted`.
+ */
+export declare const deleteClient: (options: DeployApiClientOptions, id: string, organizationId?: string) => Promise<unknown>;

package/dist/deploy/api/clients.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * XM Cloud Deploy **clients API** (`/api/clients/v1/*`) — mint and manage
+ * OAuth automation credentials.
+ *
+ * Unlike the rest of the Deploy API (which operates on already-existing
+ * resources), these endpoints **create credentials**: each mint call
+ * returns a fresh `{ clientId, clientSecret }` pair. The `clientSecret`
+ * is shown **once** in the response and is never retrievable again —
+ * callers must persist it immediately.
+ *
+ * Two scopes of client:
+ *   - **Environment-scoped** — `cm`, `edge`, `ehbuild`. The request
+ *     carries `projectId` + `environmentId`; the credential is bound to
+ *     that one environment.
+ *   - **Organization-scoped** — `deploy`. The request carries only a
+ *     name; the credential can deploy across the whole organization.
+ *
+ * Every endpoint runs under the Deploy API's `ValidateOrganization` +
+ * `xmclouddeploy.clients:manage` auth policies. Pass `organizationId`
+ * so the request carries the org headers `ValidateOrganization` expects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteClient = exports.listOrganizationClients = exports.listEnvironmentClients = exports.mintEhBuildClient = exports.mintEdgeClient = exports.mintDeployClient = exports.mintCmClient = void 0;
+const headers_1 = require("./common/headers");
+const request_1 = require("./common/request");
+/**
+ * Mint a **CM client** — an environment-scoped credential for the
+ * Content Management / Authoring surface of one environment.
+ */
+const mintCmClient = async (options, request, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/cm", undefined, {
+    method: "POST",
+    body: request,
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.mintCmClient = mintCmClient;
+/**
+ * Mint a **deploy client** — an organization-scoped credential able to
+ * run deployments across the whole org.
+ */
+const mintDeployClient = async (options, request, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/deploy", undefined, {
+    method: "POST",
+    body: request,
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.mintDeployClient = mintDeployClient;
+/**
+ * Mint an **edge client** — an environment-scoped credential for the
+ * Experience Edge delivery surface of one environment.
+ */
+const mintEdgeClient = async (options, request, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/edge", undefined, {
+    method: "POST",
+    body: request,
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.mintEdgeClient = mintEdgeClient;
+/**
+ * Mint an **editing-host build client** — an environment-scoped
+ * credential used by editing-host build pipelines.
+ */
+const mintEhBuildClient = async (options, request, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/ehbuild", undefined, {
+    method: "POST",
+    body: request,
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.mintEhBuildClient = mintEhBuildClient;
+/**
+ * List the environment-scoped clients (`cm`, `edge`, `ehbuild`) in the
+ * organization. Secrets are never included.
+ */
+const listEnvironmentClients = async (options, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/environment", undefined, {
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.listEnvironmentClients = listEnvironmentClients;
+/**
+ * List the organization-scoped clients (`deploy`). Secrets are never
+ * included.
+ */
+const listOrganizationClients = async (options, organizationId) => (0, request_1.deployRequest)(options, "/api/clients/v1/organization", undefined, { headers: (0, headers_1.withOrganizationHeaders)(organizationId) });
+exports.listOrganizationClients = listOrganizationClients;
+/**
+ * Delete a client by id. Irreversible — the credential stops working
+ * immediately. Server responds `202 Accepted`.
+ */
+const deleteClient = async (options, id, organizationId) => (0, request_1.deployRequest)(options, `/api/clients/v1/${encodeURIComponent(id)}`, undefined, {
+    method: "DELETE",
+    headers: (0, headers_1.withOrganizationHeaders)(organizationId),
+});
+exports.deleteClient = deleteClient;

package/dist/deploy/api/common/headers.d.ts

@@ -1,2 +1 @@
 export declare const withOrganizationHeaders: (organizationId?: string) => Record<string, string> | undefined;
-//# sourceMappingURL=headers.d.ts.map

package/dist/deploy/api/common/request.d.ts

@@ -1,9 +1,4 @@
 import { DeployApiClientOptions, DeployQueryValueList, DeployRequestInit } from "./types";
 export declare const parseJsonIfPossible: (response: Response) => Promise<unknown>;
 export declare const extractErrorMessage: (body: unknown) => string | undefined;
-export declare const startDeploySpinner: (text: string) => Promise<{
-    succeed: () => void;
-    fail: () => void;
-} | null>;
 export declare const deployRequest: <T>(options: DeployApiClientOptions, path: string, query?: Record<string, DeployQueryValueList | undefined>, init?: DeployRequestInit) => Promise<T>;
-//# sourceMappingURL=request.d.ts.map

package/dist/deploy/api/common/request.js

@@ -1,42 +1,9 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deployRequest = exports.startDeploySpinner = exports.extractErrorMessage = exports.parseJsonIfPossible = void 0;
-const consola_1 = require("consola");
+exports.deployRequest = exports.extractErrorMessage = exports.parseJsonIfPossible = void 0;
 const redact_1 = require("../../../shared/redact");
 const errors_1 = require("../../../shared/errors");
+const transport_events_1 = require("./transport-events");
 const types_1 = require("./types");
 const toQueryString = (query) => {
     if (!query) {
@@ -75,22 +42,17 @@ const parseJsonIfPossible = async (response) => {
     }
 };
 exports.parseJsonIfPossible = parseJsonIfPossible;
-const extractErrorMessage = (body) => {
-    if (typeof body === "string") {
-        return body;
-    }
-    if (!body || typeof body !== "object") {
-        return undefined;
-    }
-    const record = body;
-    const candidates = [record.detail, record.message, record.title, record.error];
-    for (const candidate of candidates) {
-        if (typeof candidate === "string" && candidate.trim().length > 0) {
-            return candidate;
-        }
-    }
-    if (Array.isArray(record.errors)) {
-        const parts = record.errors
+/**
+ * Pull the field-level detail out of an error body's `errors` member.
+ * ASP.NET `ValidationProblemDetails` shapes it as `Record<string,
+ * string[]>` (field → messages); some endpoints use an array of
+ * `{ message }` objects instead. This detail is the part that actually
+ * says what was wrong — the sibling `title` is only the generic
+ * "One or more validation errors occurred."
+ */
+const extractFieldErrors = (errors) => {
+    if (Array.isArray(errors)) {
+        const parts = errors
             .map((entry) => {
             if (typeof entry === "string") {
                 return entry;
@@ -105,78 +67,78 @@ const extractErrorMessage = (body) => {
             return undefined;
         })
             .filter((value) => Boolean(value));
-        if (parts.length > 0) {
-            return parts.join("; ");
+        return parts.length > 0 ? parts.join("; ") : undefined;
+    }
+    if (errors && typeof errors === "object") {
+        const parts = [];
+        for (const [field, messages] of Object.entries(errors)) {
+            if (Array.isArray(messages)) {
+                const flat = messages.filter((m) => typeof m === "string");
+                if (flat.length > 0) {
+                    parts.push(field ? `${field}: ${flat.join(" ")}` : flat.join(" "));
+                }
+            }
+            else if (typeof messages === "string" && messages.trim().length > 0) {
+                parts.push(field ? `${field}: ${messages.trim()}` : messages.trim());
+            }
         }
+        return parts.length > 0 ? parts.join("; ") : undefined;
     }
-    if (record.errors && typeof record.errors === "object" && !Array.isArray(record.errors)) {
-        try {
-            return JSON.stringify(record.errors);
-        }
-        catch {
-            return undefined;
+    return undefined;
+};
+const extractErrorMessage = (body) => {
+    if (typeof body === "string") {
+        return body;
+    }
+    if (!body || typeof body !== "object") {
+        return undefined;
+    }
+    const record = body;
+    // The generic summary. For an ASP.NET ValidationProblemDetails this is
+    // only "One or more validation errors occurred." — so it must NOT
+    // short-circuit ahead of the field-level `errors` detail below.
+    let summary;
+    for (const candidate of [record.detail, record.message, record.title, record.error]) {
+        if (typeof candidate === "string" && candidate.trim().length > 0) {
+            summary = candidate.trim();
+            break;
         }
     }
-    return undefined;
+    const fieldErrors = extractFieldErrors(record.errors);
+    if (fieldErrors) {
+        return summary ? `${summary} ${fieldErrors}` : fieldErrors;
+    }
+    return summary;
 };
 exports.extractErrorMessage = extractErrorMessage;
-const activeSpinners = new Set();
-let handlersInstalled = false;
-const installHandlers = () => {
-    if (handlersInstalled) {
-        return;
-    }
-    handlersInstalled = true;
-    const cleanup = () => {
-        for (const spinner of activeSpinners) {
-            try {
-                spinner.stop();
-            }
-            catch {
-                // ignore spinner cleanup failures
-            }
-        }
-        activeSpinners.clear();
-    };
-    process.on("SIGINT", cleanup);
-    process.on("SIGTERM", cleanup);
-    process.on("exit", cleanup);
+/**
+ * Resolve a transport tuning value: explicit caller value wins; falls
+ * back to env-var; falls back to built-in default. Pure-library callers
+ * pass these explicitly via `init.transport` so they don't depend on
+ * scai's env namespace; the CLI keeps env-var fallbacks unchanged.
+ */
+const resolveTransportInt = (explicit, envVar, defaultValue) => {
+    if (explicit !== undefined)
+        return explicit;
+    const raw = process.env[envVar];
+    if (raw === undefined)
+        return defaultValue;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : defaultValue;
 };
-const startDeploySpinner = async (text) => {
-    if (!process.stdout.isTTY) {
-        return null;
-    }
-    if (process.env.SITECOREAI_QUIET === "1" || process.env.SITECOREAI_JSON === "1") {
-        return null;
-    }
-    const { default: ora } = await Promise.resolve().then(() => __importStar(require("ora")));
-    const spinner = ora({ text }).start();
-    const handle = {
-        succeed: () => {
-            spinner.succeed();
-            activeSpinners.delete(handle);
-        },
-        fail: () => {
-            spinner.fail();
-            activeSpinners.delete(handle);
-        },
-        stop: () => {
-            spinner.stop();
-            activeSpinners.delete(handle);
-        },
-    };
-    activeSpinners.add(handle);
-    installHandlers();
-    return { succeed: handle.succeed, fail: handle.fail };
+const resolveTransportBool = (explicit, envVar) => {
+    if (explicit !== undefined)
+        return explicit;
+    return process.env[envVar] === "1";
 };
-exports.startDeploySpinner = startDeploySpinner;
 const deployRequest = async (options, path, query, init) => {
     const baseUrl = options.baseUrl ?? types_1.DEFAULT_DEPLOY_API_BASE;
     const url = `${baseUrl.replace(/\/$/, "")}${path}${toQueryString(query)}`;
     const method = init?.method ? init.method.toUpperCase() : "GET";
-    const spinner = await (0, exports.startDeploySpinner)(`${method} ${path}`);
+    const span = (await (0, transport_events_1.getDeployTransportListener)()?.onRequestStart?.(method, path, Boolean(init?.silent))) ??
+        null;
     if (init?.whatIf) {
-        spinner?.succeed();
+        span?.succeed();
         return {
             whatIf: true,
             request: {
@@ -188,7 +150,7 @@ const deployRequest = async (options, path, query, init) => {
             },
         };
     }
-    const traceEnabled = process.env.SITECOREAI_TRACE_HTTP === "1";
+    const traceEnabled = resolveTransportBool(init?.transport?.traceHttp, "SITECOREAI_TRACE_HTTP");
     const headers = {
         Authorization: `Bearer ${options.accessToken}`,
         Accept: "application/json",
@@ -201,34 +163,45 @@ const deployRequest = async (options, path, query, init) => {
         headers["Content-Type"] = "application/json";
         body = typeof init.body === "string" ? init.body : JSON.stringify(init.body);
     }
-    const maxRetries = Number(process.env.SITECOREAI_HTTP_RETRIES ?? 2);
-    const retryBaseMs = Number(process.env.SITECOREAI_HTTP_RETRY_BASE_MS ?? 500);
+    const maxRetries = resolveTransportInt(init?.transport?.maxRetries, "SITECOREAI_HTTP_RETRIES", 2);
+    const retryBaseMs = resolveTransportInt(init?.transport?.retryBaseMs, "SITECOREAI_HTTP_RETRY_BASE_MS", 500);
     const shouldRetry = (status) => method === "GET" && (status === 429 || (status !== undefined && status >= 500));
+    // Default 60s per-attempt timeout. Override via SITECOREAI_REQUEST_TIMEOUT_MS
+    // or init.transport.timeoutMs (0 disables). Defends against slowloris /
+    // black-hole upstreams.
+    const timeoutMs = resolveTransportInt(init?.transport?.timeoutMs, "SITECOREAI_REQUEST_TIMEOUT_MS", 60000);
     let response;
     let attempt = 0;
     while (true) {
+        const controller = timeoutMs > 0 ? new AbortController() : undefined;
+        const timeoutHandle = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
         try {
             if (traceEnabled) {
-                consola_1.consola.debug(`HTTP ${method} ${url}`);
+                (0, transport_events_1.getDeployTransportListener)()?.onTrace?.(`HTTP ${method} ${url}`);
             }
             response = await fetch(url, {
                 method,
                 headers,
                 body,
+                signal: controller?.signal,
             });
         }
         catch {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
             if (attempt < maxRetries && method === "GET") {
                 attempt += 1;
                 const delay = withJitter(retryBaseMs * Math.pow(2, attempt - 1));
                 await new Promise((resolve) => setTimeout(resolve, delay));
                 continue;
             }
-            spinner?.fail();
-            throw (0, errors_1.createCliError)("Deploy API request failed due to a network error.", "NETWORK", {
+            span?.fail();
+            throw (0, errors_1.createScaiError)("Deploy API request failed due to a network error.", "NETWORK", {
                 hint: "Check network connectivity or try again later.",
             });
         }
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
         if (!response.ok && shouldRetry(response.status) && attempt < maxRetries) {
             attempt += 1;
             const delay = withJitter(retryBaseMs * Math.pow(2, attempt - 1));
@@ -238,15 +211,15 @@ const deployRequest = async (options, path, query, init) => {
         break;
     }
     if (!response.ok) {
-        spinner?.fail();
+        span?.fail();
         const body = await (0, exports.parseJsonIfPossible)(response);
         const message = (0, exports.extractErrorMessage)(body);
         const sanitized = message ? (0, redact_1.redactSecrets)(message) : undefined;
-        throw (0, errors_1.createCliError)(sanitized ?? `Deploy API request failed (${response.status})`, "DEPLOY_FAILED");
+        throw (0, errors_1.createScaiError)(sanitized ?? `Deploy API request failed (${response.status})`, "DEPLOY_FAILED");
     }
-    spinner?.succeed();
+    span?.succeed();
     if (traceEnabled) {
-        consola_1.consola.debug(`HTTP ${method} ${path} -> ${response.status}`);
+        (0, transport_events_1.getDeployTransportListener)()?.onTrace?.(`HTTP ${method} ${path} -> ${response.status}`);
     }
     return (await (0, exports.parseJsonIfPossible)(response));
 };

package/dist/deploy/api/common/transport-events.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Optional presentation hook for the Deploy API transport.
+ *
+ * `deployRequest` is part of the public `./deploy` SDK surface, so it
+ * must not own a spinner, global signal handlers, or a logger. It
+ * reports request lifecycle to an optional listener instead. The CLI
+ * installs one (`installDeployTransportSpinner`); SDK consumers leave it
+ * unset and the transport runs silently — no `ora`, no `consola`, no
+ * `process.on` handlers in their dependency graph.
+ *
+ * Pure: no CLI dependencies.
+ */
+/** A settled-once handle for one in-flight request. */
+export interface DeployRequestSpan {
+    succeed(): void;
+    fail(): void;
+}
+/** Receives Deploy transport lifecycle events for CLI presentation. */
+export interface DeployTransportListener {
+    /**
+     * A request started. May return a span to settle when the request
+     * completes, or `null` to show nothing (e.g. non-TTY, quiet mode).
+     */
+    onRequestStart?(method: string, path: string, silent: boolean): Promise<DeployRequestSpan | null> | DeployRequestSpan | null;
+    /** An HTTP trace line, emitted only when `SITECOREAI_TRACE_HTTP` is set. */
+    onTrace?(message: string): void;
+}
+/** Install (or clear, with `null`) the Deploy transport listener. */
+export declare const setDeployTransportListener: (next: DeployTransportListener | null) => void;
+/** The current Deploy transport listener, or `null` when none is set. */
+export declare const getDeployTransportListener: () => DeployTransportListener | null;

package/dist/deploy/api/common/transport-events.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Optional presentation hook for the Deploy API transport.
+ *
+ * `deployRequest` is part of the public `./deploy` SDK surface, so it
+ * must not own a spinner, global signal handlers, or a logger. It
+ * reports request lifecycle to an optional listener instead. The CLI
+ * installs one (`installDeployTransportSpinner`); SDK consumers leave it
+ * unset and the transport runs silently — no `ora`, no `consola`, no
+ * `process.on` handlers in their dependency graph.
+ *
+ * Pure: no CLI dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeployTransportListener = exports.setDeployTransportListener = void 0;
+let listener = null;
+/** Install (or clear, with `null`) the Deploy transport listener. */
+const setDeployTransportListener = (next) => {
+    listener = next;
+};
+exports.setDeployTransportListener = setDeployTransportListener;
+/** The current Deploy transport listener, or `null` when none is set. */
+const getDeployTransportListener = () => listener;
+exports.getDeployTransportListener = getDeployTransportListener;

package/dist/deploy/api/common/types.d.ts

@@ -14,10 +14,25 @@ export type DeployProject = {
     name?: string;
     organizationId?: string;
 };
+/**
+ * Lifecycle state of an environment as returned by the Deploy API.
+ *
+ * The wire field (`provisioningStatus`) is numeric. Values observed
+ * directly: `0` = `unprovisioned`, `2` = `provisioned`. Values `1`,
+ * `3`, `4` are inferred from the standard Sitecore provisioning state
+ * machine and need confirmation against the Deploy API spec; any
+ * unrecognized numeric value is normalized to `"unknown"` so consumers
+ * never have to write `=== 2` checks.
+ *
+ * Use `getProvisioningStatus(env)` from `@/deploy/api` to read this —
+ * never compare the raw `provisioningStatus` number directly.
+ */
+export type DeployEnvironmentProvisioningStatus = "unprovisioned" | "provisioning" | "provisioned" | "failed" | "deleting" | "unknown";
 export type DeployEnvironment = {
     id?: string;
     environmentId?: string;
     name?: string;
+    type?: string;
     tenantId?: string;
     projectId?: string;
     organizationId?: string;
@@ -30,15 +45,59 @@ export type DeployEnvironment = {
         url?: string;
         hostname?: string;
     }>;
+    /** Raw lifecycle code from the Deploy API. Prefer
+     *  `getProvisioningStatus(env)` over comparing this number. */
+    provisioningStatus?: number;
+    provisioningLastFailureMessage?: string;
+    lastSuccessfulDeploymentId?: string;
+    createdAt?: string;
+    /**
+     * Short base62 context identifiers (e.g. `73I2gLv5HPOrhXtgIjZoXi`)
+     * that scope content publishing/preview operations to a specific
+     * Sitecore Cloud context. Returned by `/api/environments/v2/{id}`
+     * but only surfaced here as of 2026-05-14, when the SAI Publishing
+     * API scoping work first needed them. Consumption pattern by the
+     * Publishing API (body field, header, or audience suffix) is still
+     * TBD — eleven header/query variants returned identical empty
+     * 403s, suggesting the token-scope gate fires first.
+     */
+    previewContextId?: string;
+    liveContextId?: string;
 };
 export declare const DEFAULT_DEPLOY_API_BASE = "https://xmclouddeploy-api.sitecorecloud.io";
 export declare const DEFAULT_MONITORING_API_BASE = "https://xmcloud-monitoring-api.sitecorecloud.io";
 export type DeployQueryValue = string | number | boolean;
 export type DeployQueryValueList = DeployQueryValue | DeployQueryValue[];
+/**
+ * Library-overridable transport tuning. When a field is `undefined` the
+ * request falls back to the corresponding `SITECOREAI_*` env var (or
+ * the built-in default). Pure-library callers (orchestrators, MCP
+ * servers, tests) should pass these explicitly so they don't rely on
+ * scai's env namespace — the CLI keeps the env-var fallbacks for
+ * operator ergonomics.
+ */
+export type DeployRequestTransport = {
+    /** Per-attempt timeout in ms. Default: `SITECOREAI_REQUEST_TIMEOUT_MS` ?? 60_000. 0 disables. */
+    timeoutMs?: number;
+    /** Total retries on GET-only transient failures. Default: `SITECOREAI_HTTP_RETRIES` ?? 2. */
+    maxRetries?: number;
+    /** Base backoff in ms. Default: `SITECOREAI_HTTP_RETRY_BASE_MS` ?? 500. */
+    retryBaseMs?: number;
+    /** Enable per-request debug tracing. Default: `SITECOREAI_TRACE_HTTP === "1"`. */
+    traceHttp?: boolean;
+};
 export type DeployRequestInit = {
     method?: string;
     body?: unknown;
     headers?: Record<string, string>;
     whatIf?: boolean;
+    /**
+     * Skip the TTY spinner. CLI tasks leave this undefined; library
+     * callers should set `silent: true` so the transport doesn't
+     * mutate stdout. Defaults to `true` when not a TTY or when
+     * `SITECOREAI_QUIET` / `SITECOREAI_JSON` are set.
+     */
+    silent?: boolean;
+    /** Library-overridable transport tuning; see `DeployRequestTransport`. */
+    transport?: DeployRequestTransport;
 };
-//# sourceMappingURL=types.d.ts.map