import type { EnvironmentConfiguration } from "../../config/types.js";
import { type WorkflowRequestOptions } from "./graphql.js";
/**
 * Authoring GraphQL operations for Sitecore workflows.
 *
 * Schema verified against XM Cloud Authoring API by introspection
 * (2026-05-13). `ItemWorkflow`, `Workflow.commands(query: {item})`, and
 * `executeWorkflowCommand` are pinned here; if a tenant exposes a
 * divergent schema, the call surfaces as a `NETWORK` `ScaiError` with
 * the upstream message preserved.
 *
 * Note on `Workflow.commands`: the Authoring API requires a state-or-item
 * context (`WorkflowStateOrItemQueryInput`). The same workflow can expose
 * different commands depending on the item's current state, so per-item
 * resolution is required; caching across items is not valid.
 */
export interface ItemSelector {
    itemId?: string;
    path?: string;
}
export interface ItemWorkflowState {
    itemId: string;
    path: string | null;
    workflowId: string | null;
    workflowName: string | null;
    stateId: string | null;
    stateName: string | null;
    stateIsFinal: boolean;
}
export interface WorkflowCommandSummary {
    commandId: string;
    displayName: string;
}
export interface WorkflowExecutionResult {
    successful: boolean;
    nextStateId: string | null;
    message: string | null;
}
export interface ExecuteWorkflowCommandInput {
    commandId: string;
    itemId?: string;
    path?: string;
    comments?: string;
}
export interface WorkflowDefinitionSummary {
    /** Sitecore item ID — also the `workflowId` accepted by the API. */
    itemId: string;
    name: string;
    displayName: string | null;
    path: string;
}
export interface ListWorkflowDefinitionsOptions {
    /**
     * Content-tree root to scan. Defaults to `/sitecore/system/Workflows`.
     * Workflows nested under Workflow-Folder items are followed one level
     * deep; deeper nesting requires an explicit root override.
     */
    rootPath?: string;
}
export interface AssignedItemSummary {
    itemId: string;
    path: string;
    templateName: string | null;
    updatedDate: string | null;
}
/**
 * Full structure of one workflow definition — states, per-state commands
 * (with Next state), per-state actions, per-command validations. Backs
 * the workflow-definition mode of `scai content workflow get`.
 *
 * Action children of a state are anything whose template is NOT `State`,
 * `Command`, or `Workflow Folder` — typically Webhook Submit/Validation
 * Actions, but we don't filter by template name so older or customized
 * action templates still show up. Same logic for command-level
 * validations.
 */
export interface WorkflowDefinitionDetail {
    itemId: string;
    name: string;
    displayName: string | null;
    path: string;
    states: WorkflowStateDetail[];
}
export interface WorkflowStateDetail {
    itemId: string;
    name: string;
    displayName: string | null;
    path: string;
    templateName: string | null;
    commands: WorkflowCommandDetail[];
    actions: WorkflowChildSummary[];
}
export interface WorkflowCommandDetail {
    itemId: string;
    name: string;
    displayName: string | null;
    path: string;
    templateName: string | null;
    validations: WorkflowChildSummary[];
}
export interface WorkflowChildSummary {
    itemId: string;
    name: string;
    displayName: string | null;
    path: string;
    templateName: string | null;
}
export interface SearchItemsByWorkflowStateOptions {
    /** Sitecore state GUID — the item ID of the workflow State item. */
    stateId: string;
    /** Override the search index. Defaults to `sitecore_master_index`. */
    index?: string;
    /**
     * Override the search field. Defaults to `__workflow state` (the
     * standard system field name, lowercased and space-preserved). Some
     * tenants index the field as `__workflow_state` instead; supply
     * explicitly when the default returns no hits.
     */
    field?: string;
    /** Page size. Defaults to 100. */
    pageSize?: number;
    /** Cap on items returned. Defaults to 500. */
    maxItems?: number;
}
export interface WorkflowApiClient {
    /**
     * Fetch an item's current workflow + state. Accepts either an item
     * GUID (`{itemId}`) or a content-tree path (`{path}`). Returns null
     * when the item doesn't exist or is not under workflow.
     */
    getItemWorkflow(input: ItemSelector): Promise<ItemWorkflowState | null>;
    /**
     * Resolve the workflow commands available for a specific item.
     * Different items in the same workflow can expose different commands
     * depending on their current state.
     */
    getWorkflowCommandsForItem(input: {
        workflowId: string;
        itemId: string;
    }): Promise<WorkflowCommandSummary[]>;
    /** Execute a workflow command on an item, advancing its state. */
    executeWorkflowCommand(input: ExecuteWorkflowCommandInput): Promise<WorkflowExecutionResult>;
    /**
     * List Sitecore workflow definitions under `/sitecore/system/Workflows`
     * (override via `rootPath`). Walks direct children plus one level of
     * `Workflow Folder` items. Items whose template name is `"Workflow"`
     * are returned as definitions; folders are traversed, everything else
     * is skipped.
     */
    listWorkflowDefinitions(options?: ListWorkflowDefinitionsOptions): Promise<WorkflowDefinitionSummary[]>;
    /**
     * Find items currently in the given workflow state. Backed by the
     * Sitecore search index — see `SearchItemsByWorkflowStateOptions` for
     * the field/index overrides if the default index naming doesn't match
     * the tenant.
     */
    searchItemsByWorkflowState(options: SearchItemsByWorkflowStateOptions): Promise<AssignedItemSummary[]>;
    /**
     * Fetch a single workflow definition's full structure — states,
     * commands, actions, validations. Pair with `getItemWorkflow` to
     * disambiguate "is this ref a workflow definition or an item under
     * workflow?": the same item path can resolve to either depending on
     * what's at the address.
     *
     * Returns `null` when the item doesn't exist OR isn't a Workflow-
     * templated item; the task layer uses that as the signal to fall
     * through to item-state inspection.
     */
    getWorkflowDefinitionDetail(input: ItemSelector): Promise<WorkflowDefinitionDetail | null>;
    /**
     * Resolve a workflow definition by display name OR item name (case-
     * insensitive). Walks `listWorkflowDefinitions` and returns the first
     * match. Returns `{summary, duplicateMatches}` so callers can warn on
     * ambiguity. Pass an optional `rootPath` to scope the walk.
     */
    findWorkflowDefinitionByName(name: string, options?: {
        rootPath?: string;
    }): Promise<{
        summary: WorkflowDefinitionSummary;
        duplicateMatches: number;
    } | null>;
    /**
     * Force-write the standard `__Workflow` and/or `__Workflow state`
     * fields on an item, bypassing the workflow engine. Used for
     * `workflow reset` (state-only) and `workflow apply` (workflow + state).
     *
     * **Bypasses validation actions.** Submit actions on the new state
     * do NOT fire either — this is a raw field write, not a transition.
     * Use the workflow engine's `executeWorkflowCommand` for normal
     * transitions; use this only when you need an admin escape hatch
     * (recovering a stuck item, attaching a workflow for the first time).
     */
    setItemWorkflowState(input: {
        itemId?: string;
        path?: string;
        /** Workflow item ID. Omit to leave `__Workflow` unchanged. */
        workflowId?: string;
        /** State item ID. Omit to leave `__Workflow state` unchanged. */
        stateId?: string;
    }): Promise<void>;
    /** Resolve the workflow's `__Initial state` field — the State item ID it points at. */
    getWorkflowInitialStateId(workflowItemId: string): Promise<string | null>;
}
export interface WorkflowClientOptions {
    environment: EnvironmentConfiguration;
    request?: WorkflowRequestOptions;
}
export declare const createWorkflowApiClient: (options: WorkflowClientOptions) => WorkflowApiClient;