Data Models

interface ExcelJobRequest {
  operation: "create_spreadsheet" | "populate_template" | "extract_data";
  workbook_name?: string;
  sheets?: SheetDefinition[];
  template_file?: string;      // Base64-encoded .xlsx template
  data_mappings?: Record<string, any>;
}

interface SheetDefinition {
  name: string;
  blocks: ContentBlock[];
}

type ContentBlock = HeaderBlock | DataTableBlock | FormulaBlock | ChartBlock;

interface HeaderBlock {
  type: "header";
  content: string;
  style?: "title" | "heading" | "normal";
}

{
  "type": "header",
  "content": "Project Summary Report",
  "style": "title"
}

interface DataTableBlock {
  type: "data_table";
  name?: string;               // Named reference for formulas
  headers: string[];
  rows: any[][];
  formatting?: TableFormatting;
}

{
  "type": "data_table",
  "name": "QUANTITIES",
  "headers": ["Item", "Quantity", "Unit Price", "Total"],
  "rows": [
    ["Concrete", 100, 150, "=B2*C2"],
    ["Rebar", 5000, 1.2, "=B3*C3"]
  ],
  "formatting": {
    "header_bold": true,
    "zebra_stripes": true
  }
}

interface FormulaBlock {
  type: "formula";
  label: string;
  expression: string;          // Excel formula with named references
  format?: "currency" | "number" | "percentage";
}

{
  "type": "formula",
  "label": "Grand Total",
  "expression": "=SUM(QUANTITIES[Total])",
  "format": "currency"
}

interface ChartBlock {
  type: "chart";
  chart_type: "bar" | "line" | "pie" | "scatter";
  title: string;
  data_range: string;          // Named table reference
  x_axis?: string;
  y_axis?: string;
}

{
  "type": "chart",
  "chart_type": "bar",
  "title": "Cost Breakdown",
  "data_range": "QUANTITIES",
  "x_axis": "Item",
  "y_axis": "Total"
}

interface ExcelJobResponse {
  job_id: string;
  status: "completed";
  created_at: string;
  completed_at: string;
  results: {
    file_url: string;
    file_type: "xlsx";
    expires_at: string;
  }
}

{
  "job_id": "job_xls_abc123",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:08.123Z",
  "results": {
    "file_url": "https://storage.stru.ai/temp/summary.xlsx?signature=...",
    "file_type": "xlsx",
    "expires_at": "2025-10-18T10:30:08.123Z"
  }
}

{
  "operation": "create_spreadsheet",
  "workbook_name": "Project Cost Summary",
  "sheets": [
    {
      "name": "Materials",
      "blocks": [
        {
          "type": "header",
          "content": "Material Quantities and Costs",
          "style": "title"
        },
        {
          "type": "data_table",
          "name": "MATERIALS",
          "headers": ["Material", "Quantity", "Unit", "Unit Price", "Total Cost"],
          "rows": [
            ["Concrete", 150, "CY", 175, "=B2*D2"],
            ["Rebar #5", 8000, "LF", 1.25, "=B3*D3"],
            ["Formwork", 2500, "SF", 8.5, "=B4*D4"]
          ],
          "formatting": {
            "header_bold": true,
            "zebra_stripes": true
          }
        },
        {
          "type": "formula",
          "label": "Total Material Cost",
          "expression": "=SUM(MATERIALS[Total Cost])",
          "format": "currency"
        },
        {
          "type": "chart",
          "chart_type": "pie",
          "title": "Cost Distribution",
          "data_range": "MATERIALS",
          "x_axis": "Material",
          "y_axis": "Total Cost"
        }
      ]
    }
  ]
}