import type { PublishJob } from "./api/types.js";
/**
 * Structured failure information extracted from a `PublishJob`'s
 * normalized + raw payloads. The Publishing API does not document a
 * single canonical "failure detail" field — observed shapes include:
 *
 *   - `statistics.itemsFailed` (count of failed items)
 *   - `statistics.xmc.errors[]` (per-item error messages — observed
 *     shape: `{ itemId, locale?, message }`, defensive parsing only)
 *   - `system.failureReason` (free-text, sometimes present)
 *   - `system.canceledBy.name` / `system.canceledBy.id` (set on cancel,
 *     not failure, but useful in the same diagnostic block)
 *
 * Callers should treat every field as optional — older XM Cloud
 * deployments and certain failure classes don't populate all of them.
 *
 * This module is the single source of truth for "how do we explain a
 * failed publish to the operator." Both `publish status` and the
 * `publish status --watch` exit path consume it; future surfaces (MCP
 * `publishing_lifecycle`, audit-log readers) should reuse it rather
 * than re-derive the same fields.
 */
export interface PublishJobFailureDiagnostics {
    /** Free-text failure reason from `system.failureReason` if present. */
    reason?: string;
    /** Count of failed items, when statistics expose it. */
    failedItemCount?: number;
    /** Per-item failure messages, defensively parsed. */
    itemFailures?: Array<{
        itemId?: string;
        locale?: string;
        message: string;
    }>;
    /** Last statistics-update timestamp; helps gauge how stale stats are. */
    lastReportTime?: string;
}
export declare const extractFailureDiagnostics: (job: PublishJob) => PublishJobFailureDiagnostics;
/**
 * Render the diagnostics as a list of human-readable lines suitable
 * for sequential `logger.info()` calls. Returns `[]` when nothing
 * useful can be said — the caller should not print a "Failure:"
 * header in that case.
 */
export declare const formatFailureDiagnostics: (diag: PublishJobFailureDiagnostics) => string[];