maybeai-sheet-cli 0.19.0__tar.gz → 0.19.2__tar.gz

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.19.0
+Version: 0.19.2
 Summary: CLI for common MaybeAI spreadsheet operations
 Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
 Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
@@ -112,6 +112,43 @@ mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1
 mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:H1
 ```
 
+Replace worksheet data while keeping row 1, existing header order, styles, and
+formula columns:
+
+```bash
+mbs sheet update-data-keep-headers \
+  --doc-id abc123 \
+  --worksheet-name Students \
+  --data students.json \
+  --verify
+```
+
+`students.json` must be a non-empty JSON array of objects whose keys exactly
+match existing worksheet headers:
+
+```json
+[
+  {"Name": "Alice", "Score": 88},
+  {"Name": "Bob", "Score": 92}
+]
+```
+
+The command reads the worksheet headers before writing and rejects unknown
+keys. It preserves formula columns and rebuilds the workbook calculation chain
+by default. A formula column is preserved only when its key is omitted from the
+first input object and row 2 contains its formula template.
+
+Use `--no-preserve-formulas` to replace formula columns from JSON,
+`--skip-recalculation` to skip rebuilding the calculation chain, or
+`--start-row N` to begin below row 2. `--dry-run` validates and prints the
+request without updating data. `--verify` reads back the header, updated rows,
+and one trailing row; it cannot be combined with `--dry-run`.
+
+This full-refresh endpoint parses numeric-looking strings as Excel values. A
+long value such as `"46215.95520833333"` can read back as `"46215.95521"`.
+Use `sheet write-range` / `range write` with RAW value handling when exact text
+preservation matters more than header-keyed replacement semantics.
+
 List worksheets:
 
 ```bash

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/README.md

@@ -88,6 +88,43 @@ mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1
 mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:H1
 ```
 
+Replace worksheet data while keeping row 1, existing header order, styles, and
+formula columns:
+
+```bash
+mbs sheet update-data-keep-headers \
+  --doc-id abc123 \
+  --worksheet-name Students \
+  --data students.json \
+  --verify
+```
+
+`students.json` must be a non-empty JSON array of objects whose keys exactly
+match existing worksheet headers:
+
+```json
+[
+  {"Name": "Alice", "Score": 88},
+  {"Name": "Bob", "Score": 92}
+]
+```
+
+The command reads the worksheet headers before writing and rejects unknown
+keys. It preserves formula columns and rebuilds the workbook calculation chain
+by default. A formula column is preserved only when its key is omitted from the
+first input object and row 2 contains its formula template.
+
+Use `--no-preserve-formulas` to replace formula columns from JSON,
+`--skip-recalculation` to skip rebuilding the calculation chain, or
+`--start-row N` to begin below row 2. `--dry-run` validates and prints the
+request without updating data. `--verify` reads back the header, updated rows,
+and one trailing row; it cannot be combined with `--dry-run`.
+
+This full-refresh endpoint parses numeric-looking strings as Excel values. A
+long value such as `"46215.95520833333"` can read back as `"46215.95521"`.
+Use `sheet write-range` / `range write` with RAW value handling when exact text
+preservation matters more than header-keyed replacement semantics.
+
 List worksheets:
 
 ```bash

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maybeai-sheet-cli"
-version = "0.19.0"
+version = "0.19.2"
 description = "CLI for common MaybeAI spreadsheet operations"
 readme = "README.md"
 requires-python = ">=3.10"

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/src/maybeai_sheet/commands/dashboard.py

@@ -4,6 +4,7 @@ from dataclasses import replace
 from pathlib import Path
 from typing import Any, Optional
 
+import httpx
 import typer
 
 from ..chart_style_summary import enrich_chart_inventory, summarize_dashboard_plan_items
@@ -15,6 +16,7 @@ from ..errors import APIRequestError, UsageError
 from ..formatters import build_command_output, handle_cli_error, render_output
 from ..options import output_option, timeout_option, verbose_option
 from ..resolver import ResolvedTarget
+from ..table_resolver import list_worksheets_items
 from ._phase2 import base_payload, command_target, common_options, load_json_object_argument, require_worksheet
 
 app = typer.Typer(
@@ -201,8 +203,6 @@ def _is_batch_unsupported(error: Exception) -> bool:
         return False
     if error.status_code in {404, 405, 501}:
         return True
-    if error.status_code is not None and error.status_code >= 500:
-        return True
     text = " ".join(str(part).lower() for part in (error, error.body, error.context) if part is not None)
     return any(marker in text for marker in ("unsupported", "not supported", "no such", "unknown endpoint", "unknown route"))
 
@@ -224,34 +224,231 @@ def _execute_chart_list(client: MaybeAIClient, operation: dict[str, Any]) -> dic
     return enrich_chart_inventory(response) if isinstance(response, dict) else response
 
 
+def _extract_charts(payload: Any) -> list[dict[str, Any]]:
+    if not isinstance(payload, dict):
+        return []
+    for key in ("charts", "data", "results"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, dict)]
+    return []
+
+
+def _verification_has_expected_charts(verification: dict[str, Any] | None, plan: dict[str, Any]) -> bool:
+    charts = _extract_charts(verification)
+    if not charts:
+        return False
+    return all(_match_verified_chart(item, charts) is not None for item in plan.get("charts", []))
+
+
+def _match_verified_chart(item: dict[str, Any], charts: list[dict[str, Any]]) -> dict[str, Any] | None:
+    expected_chart = item.get("chart")
+    if not isinstance(expected_chart, dict):
+        return None
+    expected_cell = str(item.get("cell") or "")
+    expected_chart_id = expected_chart.get("chart_id") or expected_chart.get("id")
+    expected_title = expected_chart.get("title")
+    expected_html = expected_chart.get("html")
+
+    for chart in charts:
+        chart_id = chart.get("chart_id") or chart.get("id")
+        if expected_chart_id and chart_id != expected_chart_id:
+            continue
+        if not expected_chart_id and expected_cell and str(chart.get("cell") or "") != expected_cell:
+            continue
+        if expected_title and chart.get("title") and chart.get("title") != expected_title:
+            continue
+        if expected_html and chart.get("html") and chart.get("html") != expected_html:
+            continue
+        return chart
+    return None
+
+
+def _execute_chart_list_with_retries(
+    client: MaybeAIClient,
+    operation: dict[str, Any],
+    *,
+    attempts: int = 2,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    errors: list[dict[str, Any]] = []
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            response = _execute_chart_list(client, operation)
+            return response, errors
+        except Exception as error:
+            last_error = error
+            errors.append(operation | {"attempt": attempt, "result": _error_result(error)})
+            client.reset_session()
+    if last_error is None:
+        raise RuntimeError("chart list retry failed without an exception")
+    raise last_error
+
+
+def _worksheet_list_operation(target: ResolvedTarget) -> dict[str, Any]:
+    return {
+        "name": "worksheet.list",
+        "endpoint": "/api/v1/excel/list_worksheets",
+        "payload": {"uri": target.uri, "include_dimensions": True},
+    }
+
+
+def _execute_worksheet_list_with_retries(
+    client: MaybeAIClient,
+    operation: dict[str, Any],
+    *,
+    attempts: int = 2,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    errors: list[dict[str, Any]] = []
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            response = client.post_json(operation["endpoint"], operation["payload"])
+            return response, errors
+        except Exception as error:
+            last_error = error
+            errors.append(operation | {"attempt": attempt, "result": _error_result(error)})
+            client.reset_session()
+    if last_error is None:
+        raise RuntimeError("worksheet list retry failed without an exception")
+    raise last_error
+
+
+def _worksheet_exists(payload: Any, worksheet_name: str) -> bool:
+    for worksheet in list_worksheets_items(payload):
+        if not isinstance(worksheet, dict):
+            continue
+        value = worksheet.get("worksheet_name") or worksheet.get("sheet_name") or worksheet.get("name") or worksheet.get("title")
+        if value == worksheet_name:
+            return True
+    return False
+
+
+def _is_uncertain_write_error(error: Exception) -> bool:
+    if isinstance(error, httpx.HTTPError):
+        return True
+    if isinstance(error, APIRequestError):
+        if error.status_code is None:
+            return True
+        return error.status_code in {408, 425, 429} or error.status_code >= 500
+    return True
+
+
+def _reconcile_create_after_uncertain_failure(
+    client: MaybeAIClient,
+    target: ResolvedTarget,
+    plan: dict[str, Any],
+    *,
+    original_error: Exception,
+    failed_operation: str,
+) -> tuple[list[dict[str, Any]], dict[str, Any] | None, dict[str, Any]]:
+    reconcile_operations: list[dict[str, Any]] = []
+    verify_operation = _verify_operation(target)
+
+    try:
+        verification, retry_errors = _execute_chart_list_with_retries(client, verify_operation, attempts=2)
+        reconcile_operations.extend(retry_errors)
+        reconcile_operations.append(verify_operation | {"result": verification, "reconcile": True})
+        if _verification_has_expected_charts(verification, plan):
+            return reconcile_operations, verification, {
+                "success": True,
+                "mode": "verified_existing",
+                "reason": str(original_error),
+            }
+    except Exception as read_error:
+        reconcile_operations.append(verify_operation | {"result": _error_result(read_error), "reconcile": True})
+
+    worksheet_operation = _worksheet_list_operation(target)
+    worksheet_response, worksheet_retry_errors = _execute_worksheet_list_with_retries(client, worksheet_operation, attempts=2)
+    reconcile_operations.extend(worksheet_retry_errors)
+    reconcile_operations.append(worksheet_operation | {"result": worksheet_response, "reconcile": True})
+    if not _worksheet_exists(worksheet_response, target.worksheet_name or plan["worksheet_name"]):
+        if failed_operation == "worksheet.create":
+            retry_operations, retry_verification, _retry_reconciliation = _execute_create_operations(
+                client,
+                target,
+                plan,
+                operations=_dashboard_operations(target, plan, create_worksheet=True),
+                allow_reconcile=False,
+            )
+            reconcile_operations.extend(operation | {"reconcile": True} for operation in retry_operations)
+            if _verification_has_expected_charts(retry_verification, plan):
+                return reconcile_operations, retry_verification, {
+                    "success": True,
+                    "mode": "retried_after_absent_worksheet",
+                    "reason": str(original_error),
+                }
+        raise original_error
+
+    refresh_operations, refresh_verification, _existing_response = _execute_refresh_operations(client, target, plan)
+    reconcile_operations.extend(operation | {"reconcile": True} for operation in refresh_operations)
+    if _verification_has_expected_charts(refresh_verification, plan):
+        return reconcile_operations, refresh_verification, {
+            "success": True,
+            "mode": "refreshed_missing_charts",
+            "reason": str(original_error),
+        }
+    raise original_error
+
+
 def _execute_create_operations(
     client: MaybeAIClient,
     target: ResolvedTarget,
     plan: dict[str, Any],
     *,
     operations: list[dict[str, Any]],
-) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    allow_reconcile: bool = True,
+) -> tuple[list[dict[str, Any]], dict[str, Any] | None, dict[str, Any] | None]:
     executed: list[dict[str, Any]] = []
     verification: dict[str, Any] | None = None
+    reconciliation: dict[str, Any] | None = None
     for operation in operations:
         try:
             if operation["name"] == "chart.list":
-                response = _execute_chart_list(client, operation)
+                response, retry_errors = _execute_chart_list_with_retries(client, operation, attempts=2)
+                executed.extend(retry_errors)
             else:
                 response = client.post_json(operation["endpoint"], operation["payload"])
         except Exception as error:
-            if operation["name"] != "chart.create-config.batch" or not _is_batch_unsupported(error):
-                raise
-            executed.append(operation | {"result": _error_result(error), "fallback": "per-chart"})
-            for item in plan["charts"]:
-                fallback_operation = _create_chart_operation(target, item)
-                response = client.post_json(fallback_operation["endpoint"], fallback_operation["payload"])
-                executed.append(fallback_operation | {"result": response})
-            continue
+            if operation["name"] == "chart.create-config.batch" and _is_batch_unsupported(error):
+                executed.append(operation | {"result": _error_result(error), "fallback": "per-chart"})
+                for item in plan["charts"]:
+                    fallback_operation = _create_chart_operation(target, item)
+                    try:
+                        response = client.post_json(fallback_operation["endpoint"], fallback_operation["payload"])
+                    except Exception as fallback_error:
+                        if not _is_uncertain_write_error(fallback_error):
+                            raise
+                        executed.append(fallback_operation | {"result": _error_result(fallback_error), "uncertain": True})
+                        if not allow_reconcile:
+                            raise
+                        reconcile_operations, verification, reconciliation = _reconcile_create_after_uncertain_failure(
+                            client,
+                            target,
+                            plan,
+                            original_error=fallback_error,
+                            failed_operation=fallback_operation["name"],
+                        )
+                        executed.extend(reconcile_operations)
+                        return executed, verification, reconciliation
+                    executed.append(fallback_operation | {"result": response})
+                continue
+            if allow_reconcile and operation["name"] in {"worksheet.create", "chart.create-config.batch", "chart.create-config"} and _is_uncertain_write_error(error):
+                executed.append(operation | {"result": _error_result(error), "uncertain": True})
+                reconcile_operations, verification, reconciliation = _reconcile_create_after_uncertain_failure(
+                    client,
+                    target,
+                    plan,
+                    original_error=error,
+                    failed_operation=operation["name"],
+                )
+                executed.extend(reconcile_operations)
+                return executed, verification, reconciliation
+            raise
         executed.append(operation | {"result": response})
         if operation["name"] == "chart.list":
             verification = response
-    return executed, verification
+    return executed, verification, reconciliation
 
 
 def _execute_refresh_operations(
@@ -285,7 +482,8 @@ def _execute_refresh_operations(
             response = client.post_json(operation["endpoint"], operation["payload"])
             executed.append(operation | {"result": response})
 
-    verification = _execute_chart_list(client, verify_operation)
+    verification, retry_errors = _execute_chart_list_with_retries(client, verify_operation, attempts=2)
+    executed.extend(retry_errors)
     executed.append(verify_operation | {"result": verification})
     return executed, verification, existing_response
 
@@ -502,13 +700,15 @@ def create_config(
             }
         else:
             client = MaybeAIClient(state)
-            executed, verification = _execute_create_operations(client, target, plan, operations=operations)
+            executed, verification, reconciliation = _execute_create_operations(client, target, plan, operations=operations)
             result = {
                 "success": True,
                 "dry_run": False,
                 "dashboard": summarize_dashboard_plan(plan),
                 "style_summary": summarize_dashboard_plan_items(plan["charts"]),
                 "interaction_validation": interaction_validation,
+                "reconciled": bool(reconciliation and reconciliation.get("success")),
+                "reconciliation": reconciliation,
                 "operations": executed,
                 "verification": verification or {"success": False},
             }

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/src/maybeai_sheet/commands/sheet.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import json
+import re
 from pathlib import Path
 from typing import Any, Optional
 
@@ -7,7 +9,8 @@ import typer
 
 from ..client import MaybeAIClient
 from ..config import CLIContext
-from ..errors import APIRequestError
+from ..endpoints import get_endpoint_metadata
+from ..errors import APIRequestError, UsageError
 from ..options import output_option, resolve_command_state, timeout_option, verbose_option
 from ..formatters import build_command_output, handle_cli_error, load_json_file, render_output
 from ..models.sheet import (
@@ -24,6 +27,7 @@ from ..models.sheet import (
     RecalculateFormulasRequest,
     ReadSheetRequest,
     UpdateRangeRequest,
+    UpdateDataKeepHeadersRequest,
     UpsertRowsRequest,
 )
 from ..resolver import resolve_target
@@ -114,6 +118,76 @@ def _read_verify(
     )
 
 
+def _load_update_data(path: Path) -> list[dict[str, Any]]:
+    try:
+        raw_data = load_json_file(path)
+    except json.JSONDecodeError as error:
+        raise UsageError(f"--data must contain valid JSON: {error.msg}.") from error
+    except OSError as error:
+        raise UsageError(f"--data must point to a readable JSON file: {error}.") from error
+    if not isinstance(raw_data, list):
+        raise UsageError("--data must contain a JSON array of objects.")
+    if not raw_data:
+        raise UsageError("--data cannot be empty; clearing worksheet data is outside this command's scope.")
+    rows: list[dict[str, Any]] = []
+    for index, item in enumerate(raw_data):
+        if not isinstance(item, dict):
+            raise UsageError(f"--data item {index} must be a JSON object.")
+        if not item:
+            raise UsageError(f"--data item {index} cannot be an empty object.")
+        rows.append(item)
+    return rows
+
+
+def _headers_from_response(response: Any) -> tuple[list[str], str]:
+    candidate = response
+    if isinstance(candidate, dict) and isinstance(candidate.get("result"), dict):
+        candidate = candidate["result"]
+    headers = candidate.get("headers") if isinstance(candidate, dict) else None
+    if not isinstance(headers, list) or not headers:
+        raise UsageError("The target worksheet has no readable headers.")
+    if all(isinstance(header, str) for header in headers):
+        return headers, _column_letters(len(headers))
+    if not all(
+        isinstance(header, dict)
+        and isinstance(header.get("name"), str)
+        and isinstance(header.get("cell"), str)
+        for header in headers
+    ):
+        raise UsageError("The target worksheet returned invalid header metadata.")
+    header_names: list[str] = []
+    last_column_index = 0
+    for header in headers:
+        match = re.match(r"^([A-Za-z]+)[1-9][0-9]*$", header["cell"])
+        if match is None:
+            raise UsageError("The target worksheet returned an invalid header cell.")
+        column_index = 0
+        for character in match.group(1).upper():
+            column_index = column_index * 26 + (ord(character) - ord("A") + 1)
+        last_column_index = max(last_column_index, column_index)
+        header_names.append(header["name"])
+    return header_names, _column_letters(last_column_index)
+
+
+def _column_letters(column_count: int) -> str:
+    letters: list[str] = []
+    current = column_count
+    while current > 0:
+        current, remainder = divmod(current - 1, 26)
+        letters.append(chr(ord("A") + remainder))
+    return "".join(reversed(letters))
+
+
+def _validate_update_keys(rows: list[dict[str, Any]], headers: list[str]) -> None:
+    known_headers = set(headers)
+    unknown_keys = sorted({key for row in rows for key in row if key not in known_headers})
+    if unknown_keys:
+        raise UsageError(
+            "--data contains keys that do not match worksheet headers: "
+            + ", ".join(unknown_keys)
+        )
+
+
 def _first_by_key(value: Any, keys: tuple[str, ...]) -> Any:
     if isinstance(value, dict):
         for key in keys:
@@ -704,6 +778,117 @@ def clear_range(
         handle_cli_error(error)
 
 
+@app.command("update-data-keep-headers")
+def update_data_keep_headers(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    data: Path = typer.Option(
+        ...,
+        "--data",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help="Path to a non-empty JSON array of objects keyed by existing worksheet headers.",
+    ),
+    start_row: int = typer.Option(2, "--start-row", min=2, help="First data row to replace; row 1 remains the header."),
+    preserve_formulas: bool = typer.Option(
+        True,
+        "--preserve-formulas/--no-preserve-formulas",
+        help="Preserve formula columns omitted from the first input object.",
+    ),
+    skip_recalculation: bool = typer.Option(
+        False,
+        "--skip-recalculation",
+        help="Skip rebuilding the workbook calculation chain.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Validate and show the request without updating data."),
+    verify: bool = typer.Option(False, "--verify", help="Read back the header, updated rows, and one trailing row."),
+    output: Optional[str] = output_option(),
+    verbose: Optional[bool] = verbose_option(),
+    timeout: Optional[float] = timeout_option(),
+) -> None:
+    try:
+        if dry_run and verify:
+            raise UsageError("--dry-run and --verify cannot be used together.")
+        state: CLIContext = resolve_command_state(
+            ctx,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+            output=output,
+            verbose=verbose,
+            timeout=timeout,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(
+            state,
+            force_gid_uri=bool(state.gid is not None and not state.worksheet_name),
+        )
+        rows = _load_update_data(data)
+        headers_payload = ReadHeadersRequest(
+            uri=target.uri,
+            worksheet_name=target.worksheet_name,
+        )
+        headers_response = client.post_json(
+            "/api/v1/excel/read_headers",
+            headers_payload.model_dump(exclude_none=True),
+        )
+        headers, last_column = _headers_from_response(headers_response)
+        _validate_update_keys(rows, headers)
+
+        request = UpdateDataKeepHeadersRequest(
+            uri=target.uri,
+            worksheet_name=target.worksheet_name,
+            data=rows,
+            start_row=start_row,
+            preserve_formulas=preserve_formulas,
+            skip_recalculation=skip_recalculation,
+        )
+        endpoint = "/api/v1/excel/update_data_keep_headers"
+        payload = request.model_dump(exclude_none=True)
+        if dry_run:
+            response: dict[str, Any] = {
+                "success": True,
+                "dry_run": True,
+                "payload": payload,
+            }
+        else:
+            response = client.post_json(endpoint, payload)
+
+        verify_result: Any = None
+        if verify:
+            verify_result = _read_verify(
+                client,
+                uri=target.uri,
+                worksheet_name=target.worksheet_name,
+                cell_range=f"A1:{last_column}{start_row + len(rows)}",
+            )
+        render_output(
+            build_command_output(
+                endpoint=endpoint,
+                target=target,
+                result=response,
+                verify=verify_result,
+                metadata=(
+                    get_endpoint_metadata("sheet.update-data-keep-headers")
+                    if state.verbose
+                    else None
+                ),
+            ),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
 @app.command("append")
 def append_rows(
     ctx: typer.Context,

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/src/maybeai_sheet/endpoints.py

@@ -98,6 +98,16 @@ COMMAND_ENDPOINTS: dict[str, EndpointMetadata] = {
     "range.write": _meta("range.write", "NOW", "POST", "/api/v1/excel/update_range", verify_supported=True),
     "range.clear": _meta("range.clear", "NOW", "POST", "/api/v1/excel/clear_range"),
     "table.headers": _meta("table.headers", "NOW", "POST", "/api/v1/excel/read_headers"),
+    "sheet.update-data-keep-headers": _meta(
+        "sheet.update-data-keep-headers",
+        "NOW",
+        "POST",
+        "/api/v1/excel/update_data_keep_headers",
+        destructive=True,
+        dry_run_supported=True,
+        verify_supported=True,
+        notes="Replaces worksheet data rows while retaining row 1; preserves formula columns by default.",
+    ),
     "table.append-rows": _meta("table.append-rows", "NOW", "POST", "/api/v1/excel/append_rows", verify_supported=True),
     "table.upsert-rows": _meta("table.upsert-rows", "NOW", "POST", "/api/v1/excel/update_range_by_lookup", verify_supported=True),
     "formula.read": _meta("formula.read", "NOW", "POST", "/api/v1/excel/read_sheet"),

{maybeai_sheet_cli-0.19.0 → maybeai_sheet_cli-0.19.2}/src/maybeai_sheet/models/sheet.py

@@ -60,6 +60,17 @@ class UpdateRangeRequest(BaseModel):
     worksheet_name: str | None = None
 
 
+class UpdateDataKeepHeadersRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    data: list[dict[str, Any]]
+    worksheet_name: str | None = None
+    skip_recalculation: bool = False
+    preserve_formulas: bool = True
+    start_row: int = 2
+
+
 class ClearRangeRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")