import { type FieldDef } from "../../output/index.js";
export declare const READ_HELP = "usage: gws-axi sheets read <spreadsheetId> [flags]\nargs[1]:\n  <spreadsheetId>      The spreadsheet ID (the portion of the URL after /d/)\nflags[7]:\n  --tab <name|gid>     Tab to render (by title or numeric sheetId). Omit for a\n                       single-tab file; required to pick one in a multi-tab file\n  --range <A1>         Restrict to an A1 range within the tab (e.g. A1:D50). A\n                       tab-qualified range (Costs!A1:D50) makes --tab optional\n  --header-row         Force-promote the first fetched row to column names\n                       (rows[N]{\u2026}) instead of the A1 column-letter grid\n  --raw                Force the A1 column-letter grid, overriding header\n                       auto-detection\n  --full               Don't cap rendered rows (default cap: 50)\n  --max-rows <n>       Override the 50-row render cap (ignored with --full)\n  --account <email>    Account override when 2+ are configured\nexamples:\n  gws-axi sheets read 1AbC...\n  gws-axi sheets read 1AbC... --tab Costs\n  gws-axi sheets read 1AbC... --tab Costs --range A1:D50\n  gws-axi sheets read 1AbC... --tab Costs --header-row\noutput:\n  A `spreadsheet{id,title,tab?,tab_count?}` header, a `sheets[N]{gid,title,\n  index,rows,cols}` tabs listing (always shown), and \u2014 when a tab is selected \u2014\n  a `cells[N]{row,A,B,\u2026}` grid (real sheet row numbers + A1 column letters).\n  Embedded links are resolved inline as markdown `[text](url)` in the cells;\n  cell notes come back in a `notes[N]{cell,note}` block. Multi-tab files\n  without --tab return only the tabs listing so you can pick one.\nnotes:\n  A single frozen top row is auto-promoted to column names (header_source:\n  frozen-row in the output); pass --raw to override, or --header-row to force\n  promotion when no row is frozen.\n  Cell values are FORMATTED_VALUE (displayed strings), not formulas/raw numbers.\n  For review comments use `gws-axi sheets comments <id>` (Drive comments).\n  Operates on native Google Sheets only; uploaded .xlsx/.csv route to Drive.\n";
/**
 * Decide whether to promote the first fetched row to column names. Explicit
 * flags win; otherwise a single frozen top row (a user-declared header) inside
 * the fetched window auto-promotes. Multi-row frozen headers are left as-is —
 * promoting only the first of several would misrepresent the data.
 */
export declare function resolveHeaderMode(opts: {
    explicitHeader: boolean;
    explicitRaw: boolean;
    frozenRows: number;
    originRow1: number;
}): {
    headerRow: boolean;
    auto: boolean;
};
/** 0-based column index → A1 column letter (0→A, 25→Z, 26→AA). */
export declare function columnLetter(index0: number): string;
/** A1 column letters → 0-based column index (A→0, Z→25, AA→26). */
export declare function columnIndex(letters: string): number;
export interface RangeOrigin {
    col0: number;
    row1: number;
}
/**
 * Parse the top-left origin of a `values.get` range echo. Handles a bare range
 * (`C5:E9`), a tab-qualified range (`Costs!C5:E9`), quoted titles that may
 * contain `!` (`'My Sheet!x'!A1:B2`), absolute refs (`$C$5`), and open-ended
 * ranges (`Costs!A:D` → row 1; `Costs!5:9` → col A). Falls back to A1 when the
 * origin can't be determined, so a parse miss degrades to a safe default rather
 * than mis-addressing.
 */
export declare function parseRangeOrigin(range: string | undefined | null): RangeOrigin;
export interface GridRender {
    /** Row objects ready for renderList. */
    rows: Array<Record<string, unknown>>;
    /** Column schema for renderList. */
    schema: FieldDef[];
    /** Field name for the rendered list (`cells` or `rows`). */
    listName: string;
    /** Total data rows available (before the render cap). */
    totalRows: number;
    /** Whether the render was capped below totalRows. */
    truncated: boolean;
}
/**
 * Turn a `values.get` 2D array into row objects + a matching TOON schema.
 *
 * Default: `cells[N]{row,A,B,…}` — real sheet row numbers, A1 column letters
 * from `origin`, ragged rows padded to the widest row.
 * With `headerRow`: the first fetched row becomes the column names (`rows[N]{…}`),
 * the `row` column is dropped, and duplicate/empty headers fall back to letters.
 */
export declare function buildGrid(values: unknown[][], origin: RangeOrigin, opts: {
    headerRow: boolean;
    maxRows: number;
    full: boolean;
}): GridRender;
export interface GridCellLike {
    formattedValue?: string | null;
    hyperlink?: string | null;
    note?: string | null;
    textFormatRuns?: Array<{
        startIndex?: number | null;
        format?: {
            link?: {
                uri?: string | null;
            } | null;
        } | null;
    }> | null;
}
export interface GridRowLike {
    values?: GridCellLike[] | null;
}
export interface NoteEntry {
    cell: string;
    note: string;
    [key: string]: unknown;
}
export interface ExtractedGrid {
    /** Cell values with links rendered inline as markdown `[text](url)`. */
    values: string[][];
    /** Cell notes (distinct from Drive comments), keyed by A1 cell. */
    notes: NoteEntry[];
    /** Total number of resolved links inlined into the grid. */
    linkCount: number;
}
/**
 * Render one cell's display value, inlining any embedded links as markdown.
 * - A whole-cell `hyperlink` wraps the entire value: `[value](url)`.
 * - Rich-text links (`textFormatRuns` with a `format.link.uri`) wrap only the
 *   linked span, reconstructed from the run boundaries, so a cell with several
 *   links (`…here and here`) becomes `…[here](u1) and [here](u2)`.
 * Returns `{ text, links }` where `links` counts resolved links in the cell.
 */
export declare function cellToMarkdown(cell: GridCellLike): {
    text: string;
    links: number;
};
/**
 * Extract a values grid (with markdown-inlined links) + notes from
 * includeGridData rowData. `origin` supplies the A1 coordinate of the top-left
 * cell so notes are addressed correctly. Trailing fully-empty rows are trimmed
 * to mirror the used-range behavior of a plain values fetch.
 */
export declare function extractGrid(rows: GridRowLike[], origin: RangeOrigin): ExtractedGrid;
export declare function sheetsReadCommand(account: string, args: string[]): Promise<string>;