/**
 * Type definitions for Document Clarifications feature.
 *
 * Clarifications allow reviewers to flag document validation issues,
 * reference relevant documents, and collect structured responses from clients.
 */
import type { FormFileAttachment } from './file_attachment.js';
/** Clarification type - maps to templates */
export type ClarificationType = 'none' | 'invalid_document' | 'additional_info_required' | 'validation_override';
/** Lifecycle status of a clarification */
export type ClarificationStatus = 'pending' | 'responded' | 'resolved' | 'dismissed';
/** Back-office review decision for a draft clarification */
export type ClarificationReviewDecision = 'approve' | 'dismiss_ignore' | 'skip_process';
/** Reference to a document relevant to the clarification */
export interface ClarificationDocReference {
    /** hazo_files file ID */
    file_id: string;
    /** Display filename */
    file_name: string;
    /** MIME type for icon display */
    mime_type: string;
    /** File size in bytes (for display in file bar) */
    file_size?: number;
    /** Why this doc is referenced (optional reviewer comment) */
    comment?: string;
    /** Field this doc was originally uploaded to */
    source_field_id?: string;
}
/**
 * Structured expectation carried from a validation issue into a clarification.
 * Discriminated union keyed by `kind` so future resolver types (date_coverage,
 * set_membership, ...) plug in without changes elsewhere.
 */
export type ClarificationExpectation = {
    kind: 'sum_match';
    /** Expected total in major units (e.g. 437.47 for $437.47) */
    amount: number;
    /** ISO 4217 code or symbol prefix detected from the source */
    currency: string;
    /** Optional date constraint files must fall within */
    date_range?: {
        from: string;
        to: string;
    };
    /** Source description (e.g. "Electrical - Repairs") */
    description?: string;
    /**
     * Free-form contextual signals from the originating validation rule used
     * by the relevance check (LLM Step 2). Empty context skips the check.
     * Growing set: add fields as new rule shapes emerge.
     */
    context?: ClarificationExpectationContext;
};
/**
 * Contextual fields that frame the expectation. These travel with the
 * clarification and are matched against each response file's
 * `extracted_fields` to decide whether the file is actually relevant.
 */
export interface ClarificationExpectationContext {
    /** Property the expense relates to (rental property scenarios). */
    property_address?: string;
    /** Hint about the kind of vendor expected (e.g. "electrician", "plumber"). */
    vendor_hint?: string;
    /** Human label for the expense category (e.g. "Electrical Repairs"). */
    expense_label?: string;
}
/** A radio option in the response (green) zone */
export interface ClarificationResponseOption {
    /** Value key for this option (action identifier, e.g. 'ignore', 'replace_document') */
    value: string;
    /** User-visible label */
    label: string;
    /** Optional hover text / tooltip shown to the client for additional context */
    description?: string;
    /** Show file upload dropzone when this option is selected */
    shows_file_upload?: boolean;
    /** Require at least one file when shows_file_upload is true */
    files_mandatory?: boolean;
    /** Show additional text input when this option is selected */
    shows_additional_input?: boolean;
    /** When true, selecting this option marks the referenced files for manual review
     *  (skips automated validation, shown as "Client Requested Manual Review" in back office) */
    marks_manual_review?: boolean;
}
/** A single entry in a clarification's conversation thread */
export interface ClarificationThreadEntry {
    /** Who posted: system (auto-generated issue), client, or author (back-office) */
    role: 'system' | 'client' | 'author';
    /** Action taken */
    action: 'created' | 'responded' | 'rejected' | 'resolved' | 'reopened';
    /** Message text (system = issue description, client = user_comment, author = rejection reason) */
    message?: string;
    /** Client's selected response option (only for role: 'client') */
    response_choice?: string;
    /** Files attached (client uploads or author reference files) */
    files?: FormFileAttachment[];
    /** ISO timestamp */
    timestamp: string;
    /** Display name of the person who posted */
    actor_name?: string;
    /** User ID of the person who posted */
    actor_id?: string;
    /** Validation results shown as info popover on file bars */
    validations?: Array<{
        rule_key: string;
        status: string;
        details: string;
    }>;
    /** Classification tags to show on file bars in the thread */
    classification_tags?: string[];
}
/** A single clarification item */
export interface ClarificationItem {
    /** Unique ID, prefixed 'clr_' */
    id: string;
    /** Clarification type (maps to template) */
    type: ClarificationType;
    /** Lifecycle status */
    status: ClarificationStatus;
    /** Field or group this clarification targets */
    target_field_id: string;
    /** Human-readable label for the target */
    target_label: string;
    /** Validation rule that triggered this (Phase 3) */
    rule_name?: string;
    /** Validation rule ID (Phase 3) */
    rule_id?: string;
    /** Description of the issue found */
    issue_description: string;
    /** Detailed validation result from LLM analysis (shown below issue_description) */
    validation_details?: string;
    /** Agent's feedback/comment when reviewing and sending back (e.g. "recheck please") */
    agent_feedback?: string;
    /** Referenced documents relevant to this clarification */
    doc_references: ClarificationDocReference[];
    /** Description of what action the client should take */
    action_description?: string;
    /** Available response options (radio buttons) — current/latest version */
    response_options: ClarificationResponseOption[];
    /** Snapshot of response options at the time of send-back (frozen, for rfi_draft in data model) */
    send_back_options?: ClarificationResponseOption[];
    /** Original response options from validation (frozen, for client_question RFI in data model) */
    original_response_options?: ClarificationResponseOption[];
    /** Client's selected response option value */
    response_choice?: string;
    /** Client's free-text comment */
    user_comment?: string;
    /** Files uploaded as part of the response */
    response_files: FormFileAttachment[];
    /** ISO timestamp when created */
    created_at: string;
    /** ISO timestamp of last update */
    updated_at?: string;
    /** User ID who created this clarification */
    created_by?: string;
    /** User ID who responded */
    responded_by?: string;
    /** User ID who resolved */
    resolved_by?: string;
    /** Back-office review decision that sent this item (preserved after confirm) */
    review_decision?: ClarificationReviewDecision;
    /** ISO timestamp when the review decision was made */
    reviewed_at?: string;
    /** Conversation thread — ordered history of actions on this clarification */
    thread?: ClarificationThreadEntry[];
    /** Structured expectation derived from the originating validation issue (e.g. sum_match with amount + date_range). */
    expectation?: ClarificationExpectation;
}
/** Template definition for a clarification type */
export interface ClarificationTemplate {
    /** Template type key */
    type: ClarificationType;
    /** Human-readable name */
    display_name: string;
    /** Default issue description (pre-filled in grey zone) */
    default_issue_description?: string;
    /** Default action description (pre-filled in green zone) */
    default_action_description?: string;
    /** Available response options for this template */
    response_options: ClarificationResponseOption[];
    /** Whether to show the comment textarea */
    enable_comment: boolean;
    /** Whether to show doc reference list */
    show_doc_references: boolean;
}
/** Response payload when a client submits a clarification response */
export interface ClarificationResponse {
    /** Selected response option value */
    response_choice?: string;
    /** Free-text comment */
    user_comment?: string;
    /** Uploaded response files */
    response_files?: FormFileAttachment[];
    /** Aggregate resolver verdict for this response (sum_match, etc.). Set when the parent ran a resolver before emit. */
    resolution_check?: import('./shared_data.js').ResolutionCheck;
    /** Mismatch sub-form choice (e.g. 'add_more_files', 'explain_with_comment') when the resolver failed twice and the client chose a fallback path. */
    mismatch_choice?: string;
    /** Mismatch sub-form comment captured alongside mismatch_choice. */
    mismatch_comment?: string;
}
/** Consumer-provided callbacks for clarification lifecycle */
export interface ClarificationCallbacks {
    /** Called when client submits a response to a clarification */
    on_respond?: (clarification_id: string, response: ClarificationResponse) => void;
    /** Called when reviewer resolves a clarification */
    on_resolve?: (clarification_id: string) => void;
    /** Called when reviewer dismisses a clarification */
    on_dismiss?: (clarification_id: string) => void;
    /** Called when reviewer re-opens a resolved/dismissed clarification */
    on_reopen?: (clarification_id: string) => void;
    /** Called when a doc reference is deleted from a clarification */
    on_doc_delete?: (clarification_id: string, file_id: string) => void;
}
/** Summary counts for clarifications */
export interface ClarificationCounts {
    pending: number;
    responded: number;
    resolved: number;
    dismissed: number;
    total: number;
}
/** State of response validation for a clarification item */
export interface ResponseValidationState {
    status: 'idle' | 'validating' | 'passed' | 'failed';
    error?: string;
    message?: string;
}
//# sourceMappingURL=clarification.d.ts.map