qorstack-report-sdk 0.1.1 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ This SDK simplifies integration into your **Node.js** and **.NET** applications.
 ## Features
 
 - **Word template rendering** — generate PDF or DOCX from a stored DOCX template.
-- **Excel template rendering** — generate XLSX (or PDF) from a stored XLSX template, with auto-filter, freeze header, table styles, and conditional formatting.
+- **Excel template rendering** — generate XLSX from a stored XLSX template (Excel in, Excel out), with auto-filter, freeze header, table styles, and conditional formatting.
 - **Sandbox rendering** — render a template using its configured sample payload (great for previews).
 - **Render job history** — list and inspect past render jobs.
 - **Rich data binding:**
@@ -14,10 +14,11 @@ This SDK simplifies integration into your **Node.js** and **.NET** applications.
   - Dynamic tables (with vertical merge / column collapse on Word; auto-filter / freeze / split-to-sheets on Excel)
   - Images (URL or Base64)
   - QR codes and barcodes
-- **Pro features** *(requires Pro license on self-hosted, included on cloud Pro plans)*:
+- **Pro features** *(require a Pro license on your Qorstack Report server)*:
   - PDF password protection
   - PDF watermarking
-- **Zip output** — bundle multiple output files into a `.zip`.
+  - Async renders with webhooks (`async: true`, then poll or `waitForJob`)
+  - Zip output — the rendered file inside a `.zip`
 - **Cross-platform** — fully typed clients for TypeScript/Node.js and C#/.NET 8.0+.
 
 ---
@@ -29,7 +30,7 @@ This SDK simplifies integration into your **Node.js** and **.NET** applications.
 ```bash
 npm install qorstack-report-sdk
 # or
-yarn add qorstack-report-sdk
+pnpm add qorstack-report-sdk
 ```
 
 ### .NET (C#)
@@ -42,11 +43,11 @@ dotnet add package Qorstack.Report.Sdk
 
 ## Authentication
 
-You need an **API Key** from the Qorstack Portal.
+You need an **API key** from your Qorstack Report server (one per project).
 
-1. Log in to the Qorstack Portal.
-2. Navigate to **Settings → API Keys**.
-3. Create a new API Key (scoped per project).
+1. Sign in to the web UI of your Qorstack Report server.
+2. Open the project, then **API key** in the sidebar.
+3. Copy the key and send it as the `X-API-Key` header.
 
 ---
 
@@ -61,17 +62,17 @@ import { QorstackApi } from "qorstack-report-sdk";
 const qorstackApi = new QorstackApi({
   securityData: {
     headers: {
-      "X-API-KEY": "YOUR_API_KEY_HERE",
+      "X-API-Key": "YOUR_API_KEY_HERE",
     },
   },
 });
 
 // OR: with custom Base URL (e.g. self-hosted instance)
 const qorstackApiCustom = new QorstackApi({
-  baseUrl: "https://your-custom-url.com",
+  baseUrl: "https://your-host/api", // v2: the API lives under /api (appended automatically if missing)
   securityData: {
     headers: {
-      "X-API-KEY": "YOUR_API_KEY_HERE",
+      "X-API-Key": "YOUR_API_KEY_HERE",
     },
   },
 });
@@ -86,7 +87,7 @@ using Qorstack.Report.Sdk;
 var qorstackApi = new QorstackApi(apiKey: "YOUR_API_KEY_HERE");
 
 // OR: with custom Base URL
-var qorstackApiCustom = new QorstackApi("https://your-custom-url.com", "YOUR_API_KEY_HERE");
+var qorstackApiCustom = new QorstackApi("https://your-host/api", "YOUR_API_KEY_HERE"); // /api appended if missing
 ```
 
 ---
@@ -104,52 +105,38 @@ Use `fileType: "pdf"` (default) to get a PDF, or `"docx"` to get the rendered Wo
 
 ```typescript
 // Node.js (TypeScript)
-const tableRows = data.map((item, index) => ({
-  no: index + 1,
-  category: item.category,
-  description: item.description,
-  qty: item.quantity,
-  unit_price: item.price,
-  amount: item.total,
-}));
+// Column names ({{row:<name>}} markers) are listed once; each row holds the values in that order
+const columns = ["no", "category", "description", "qty", "unit_price", "amount"];
+const tableRows = data.map((item, index) => [
+  index + 1, item.category, item.description, item.quantity, item.price, item.total,
+]);
 
 const response = await qorstackApi.render.postRenderWordTemplate({
   templateKey: "RENDOX-7326-758-974-2067",
   fileName: "Full_Report_Example",
   fileType: "pdf", // "pdf" | "docx"
-  replace: {
-    customer_name: "Example Company Ltd.",
-    document_date: new Date().toLocaleDateString("en-GB"),
-    total_amount: "1,500.00",
-  },
+  replace: [
+    { key: "customer_name", value: "Example Company Ltd." },
+    { key: "document_date", value: new Date().toLocaleDateString("en-GB") },
+    { key: "total_amount", value: "1,500.00" },
+  ],
   table: [
     {
+      columns,
       rows: tableRows,
       verticalMerge: ["category"],
       collapse: ["description"],
     },
   ],
-  image: {
-    header_logo: {
-      src: "https://example.com/logo.png",
-      width: 200,
-      fit: "contain",
-    },
-  },
-  qrcode: {
-    payment_qr: {
-      text: "https://payment.link/123456",
-      size: 150,
-    },
-  },
-  barcode: {
-    product_barcode: {
-      text: "PROD-123456789",
-      format: "Code128",
-      width: 300,
-      height: 80,
-    },
-  },
+  image: [
+    { key: "header_logo", src: "https://example.com/logo.png", width: 200, fit: "contain" },
+  ],
+  qrcode: [
+    { key: "payment_qr", text: "https://payment.link/123456", size: 150 },
+  ],
+  barcode: [
+    { key: "product_barcode", text: "PROD-123456789", format: "Code128", width: 300, height: 80 },
+  ],
 });
 
 console.log("Download URL:", response.data.downloadUrl);
@@ -159,47 +146,45 @@ console.log("Download URL:", response.data.downloadUrl);
 // C# (.NET)
 var data = await _exampleService.GetDataAsync(id);
 
-var tableRows = data.Select((item, index) => new Dictionary<string, object>
+// Column names ({{row:<name>}} markers) are listed once; each row holds the values in that order
+var columns = new List<string> { "no", "category", "description", "qty", "unit_price", "amount" };
+var tableRows = data.Select((item, index) => (ICollection<object>)new List<object>
 {
-    { "no", index + 1 },
-    { "category", item.Category },
-    { "description", item.Description },
-    { "qty", item.Quantity },
-    { "unit_price", item.Price },
-    { "amount", item.Total }
+    index + 1, item.Category, item.Description, item.Quantity, item.Price, item.Total
 }).ToList();
 
 var request = new PdfFromTemplateRequest
 {
     TemplateKey = "RENDOX-7326-758-974-2067",
     FileName = "Full_Report_Example",
-    FileType = "pdf",
-    Replace = new()
+    FileType = PdfFromTemplateRequestFileType.Pdf,
+    Replace = new List<KeyValueRequest>
     {
-        { "customer_name", "Example Company Ltd." },
-        { "document_date", DateTime.Now.ToString("dd/MM/yyyy") },
-        { "total_amount", "1,500.00" }
+        new KeyValueRequest { Key = "customer_name", Value = "Example Company Ltd." },
+        new KeyValueRequest { Key = "document_date", Value = DateTime.Now.ToString("dd/MM/yyyy") },
+        new KeyValueRequest { Key = "total_amount", Value = "1,500.00" }
     },
     Table = new()
     {
         new()
         {
-            Rows = tableRows,
+            Columns = columns,
+          Rows = tableRows,
             VerticalMerge = new() { "category" },
             Collapse = new() { "description" }
         }
     },
-    Image = new()
+    Image = new List<ImageDataRequest>
     {
-        { "header_logo", new() { Src = "https://example.com/logo.png", Width = 200, Fit = "contain" } }
+        new ImageDataRequest { Key = "header_logo", Src = "https://example.com/logo.png", Width = 200, Fit = ImageDataRequestFit.Contain }
     },
-    QrCode = new()
+    Qrcode = new List<QrCodeDataRequest>
     {
-        { "payment_qr", new() { Text = "https://payment.link/123456", Size = 150 } }
+        new QrCodeDataRequest { Key = "payment_qr", Text = "https://payment.link/123456", Size = 150 }
     },
-    Barcode = new()
+    Barcode = new List<BarcodeDataRequest>
     {
-        { "product_barcode", new() { Text = "PROD-123456789", Format = "Code128", Width = 300, Height = 80 } }
+        new BarcodeDataRequest { Key = "product_barcode", Text = "PROD-123456789", Format = "Code128", Width = 300, Height = 80 }
     }
 };
 
@@ -219,24 +204,28 @@ Method: `render.postRenderExcelTemplate` (Node) / `PostRenderExcelTemplateAsync`
 const response = await qorstackApi.render.postRenderExcelTemplate({
   templateKey: "XLSX-1234-5678",
   fileName: "Sales_Report_Q1",
-  replace: {
-    report_period: "Q1 2026",
-    generated_by: "Sales Team",
-  },
+  replace: [
+    { key: "report_period", value: "Q1 2026" },
+    { key: "generated_by", value: "Sales Team" },
+  ],
   table: [
     {
+      columns: ['region', 'product', 'qty', 'total'],
       rows: [
-        { region: "North", product: "A", qty: 10, total: 1000 },
-        { region: "North", product: "B", qty: 5, total: 500 },
-        { region: "South", product: "A", qty: 8, total: 800 },
+        ['North', 'A', 10, 1000],
+        ['North', 'B', 5, 500],
+        ['South', 'A', 8, 800]
       ],
       autoFilter: true,
       freezeHeader: true,
       autoFitColumns: true,
       asExcelTable: true,
       excelTableStyle: "TableStyleMedium2",
-      generateTotals: { total: "sum", qty: "sum" },
-      numberFormat: { total: "#,##0.00" },
+      generateTotals: [
+        { key: "total", value: "SUM" },
+        { key: "qty", value: "SUM" },
+      ],
+      numberFormat: [{ key: "total", value: "#,##0.00" }],
     },
   ],
 });
@@ -250,28 +239,33 @@ var request = new ExcelFromTemplateRequest
 {
     TemplateKey = "XLSX-1234-5678",
     FileName = "Sales_Report_Q1",
-    Replace = new()
+    Replace = new List<KeyValueRequest>
     {
-        { "report_period", "Q1 2026" },
-        { "generated_by", "Sales Team" }
+        new KeyValueRequest { Key = "report_period", Value = "Q1 2026" },
+        new KeyValueRequest { Key = "generated_by", Value = "Sales Team" }
     },
-    Table = new()
+    Table = new List<ExcelTableDataRequest>
     {
-        new()
+        new ExcelTableDataRequest
         {
-            Rows = new()
+            Columns = new List<string> { "region", "product", "qty", "total" },
+            Rows = new List<ICollection<object>>
             {
-                new Dictionary<string, object> { { "region", "North" }, { "product", "A" }, { "qty", 10 }, { "total", 1000 } },
-                new Dictionary<string, object> { { "region", "North" }, { "product", "B" }, { "qty", 5 },  { "total", 500 } },
-                new Dictionary<string, object> { { "region", "South" }, { "product", "A" }, { "qty", 8 },  { "total", 800 } }
+                new List<object> { "North", "A", 10, 1000 },
+                new List<object> { "North", "B", 5, 500 },
+                new List<object> { "South", "A", 8, 800 }
             },
             AutoFilter = true,
             FreezeHeader = true,
             AutoFitColumns = true,
             AsExcelTable = true,
             ExcelTableStyle = "TableStyleMedium2",
-            GenerateTotals = new() { { "total", "sum" }, { "qty", "sum" } },
-            NumberFormat = new() { { "total", "#,##0.00" } }
+            GenerateTotals = new List<KeyValueRequest>
+            {
+                new KeyValueRequest { Key = "total", Value = "SUM" },
+                new KeyValueRequest { Key = "qty", Value = "SUM" }
+            },
+            NumberFormat = new List<KeyValueRequest> { new KeyValueRequest { Key = "total", Value = "#,##0.00" } }
         }
     }
 };
@@ -332,33 +326,72 @@ const response = await qorstackApi.render.postRenderWordTemplateSandbox(
 
 ---
 
-### 6. Inspect render jobs
+### 6. Async renders *(Pro)* and job status
+
+With `"async": true` the API queues the render and answers `202` with a job id instead of the file.
+Use the helpers below — they handle both answers, poll the job, and turn `429` (too many pending
+jobs) into a typed error. Without a Pro license the API answers `403`.
 
 ```typescript
-// List jobs
-const jobs = await qorstackApi.render.getRenderJobs({
-  page: 1,
-  pageSize: 20,
-  // templateKey: "...", status: "Success" | "Failed" | "Pending"
-});
+import { QorstackApi, RenderQueueFullError } from "qorstack-report-sdk";
+
+const outcome = await qorstackApi.renderWord({ templateKey: "invoice", async: true, replace: [/* … */] });
+
+if (outcome.kind === "queued") {
+  const job = await qorstackApi.waitForJob(outcome.job.jobId!, { intervalMs: 2000, timeoutMs: 600_000 });
+  console.log(job.downloadUrl); // fresh link once status is "success"
+} else {
+  console.log(outcome.download.downloadUrl); // rendered in this request (async not set)
+}
 
-// Get one
-const job = await qorstackApi.render.getRenderJobById("job-id-here");
+// const job = await qorstackApi.getRenderJob(jobId);   // single status check
+// catch (e) { if (e instanceof RenderQueueFullError) retry after e.retryAfterSeconds }
 ```
 
+```csharp
+var outcome = await qorstackApi.RenderWordAsync(new PdfFromTemplateRequest { TemplateKey = "invoice", Async = true });
+
+var link = outcome.IsQueued
+    ? (await qorstackApi.WaitForJobAsync(outcome.Job!.JobId, TimeSpan.FromSeconds(2), TimeSpan.FromMinutes(10))).DownloadUrl
+    : outcome.Download!.DownloadUrl;
+
+// RenderQueueFullException.RetryAfter on 429 · RenderJobFailedException when the job fails
+// var job = await qorstackApi.GetRenderJobAsync(jobId);
+```
+
+`renderWord` / `renderExcel` (`RenderWordAsync` / `RenderExcelAsync`) also work without `async` —
+they then always return the download. The generated `render.postRender…` methods stay available.
+
 ---
 
 ## Data Binding Reference
 
+`replace`, `image`, `qrcode` and `barcode` are **keyed arrays**: every item names the
+template marker it fills via `key` (SDK types: `KeyValueRequest`, `ImageDataRequest`,
+`QrCodeDataRequest`, `BarcodeDataRequest`). Tables list their column names once in
+`columns`; each row in `rows` holds the values in that order.
+
+The API validates the whole request first and returns every problem in one `400`,
+keyed by JSON path (`replace[3].key`, `table[0].rows[12]`, `image[0].fit`).
+
+Set `templateVersion` to render an older stored version of the template (omit it for the
+current version; an unknown version returns `404`).
+
+> **SDK 1.0 / API v2.0:** the v1 forms were removed and now return `400`: object maps
+> (`"replace": { "customerName": "..." }`), rows as objects or `{ key, value }` cells,
+> single-string `sort` / `verticalMerge` / `collapse`, and `fileType` on the Excel endpoint.
+> Upgrading from SDK 0.x? See
+> [Migrating from v1](../backend/documents/10_RENDER-API-SUMMARY.md#migrating-from-v1).
+
 ### Text replacement (`replace`)
 
-Replaces `{{variable}}` placeholders with strings.
+Replaces `{{variable}}` placeholders with strings (`KeyValueRequest[]`).
 
 ```json
-"replace": {
-  "customerName": "Acme Corp",
-  "totalAmount": "$1,050.00"
-}
+"replace": [
+  { "key": "customerName", "value": "Acme Corp" },
+  { "key": "totalAmount", "value": "$1,050.00" }
+]
 ```
 
 ### Word table (`table` — `WordTableDataRequest[]`)
@@ -366,9 +399,10 @@ Replaces `{{variable}}` placeholders with strings.
 ```json
 "table": [
   {
+    "columns": ["category", "description", "amount"],
     "rows": [
-      { "name": "Value A", "last_name": "Value B" },
-      { "name": "Value C", "last_name": "Value D" }
+      ["Hardware", "Laptop", 1200],
+      ["Hardware", "Monitor", 300]
     ],
     "verticalMerge": ["category"],
     "collapse": ["description"]
@@ -378,7 +412,9 @@ Replaces `{{variable}}` placeholders with strings.
 
 | Field | Description |
 | --- | --- |
-| `rows` | Array of row objects. Keys match column placeholders. |
+| `columns` | Column names, listed once — each matches a `{{row:<name>}}` placeholder. Unique; required when there are rows. |
+| `rows` | Array of rows; each row is an array of values in `columns` order (string, number, boolean or null). A row with the wrong number of values returns `400` naming the row. |
+| `sort` | `[{ "field": column, "direction": "asc" \| "desc" }]`. |
 | `verticalMerge` | Columns whose adjacent identical values are merged vertically. |
 | `collapse` | Columns whose empty/duplicate values collapse to keep layout tidy. |
 
@@ -387,14 +423,17 @@ Replaces `{{variable}}` placeholders with strings.
 ```json
 "table": [
   {
-    "rows": [{ "region": "North", "qty": 10 }],
+    "columns": ["region", "qty"],
+    "rows": [
+      ["North", 10]
+    ],
     "autoFilter": true,
     "freezeHeader": true,
     "autoFitColumns": true,
     "asExcelTable": true,
     "excelTableStyle": "TableStyleMedium2",
-    "generateTotals": { "qty": "sum" },
-    "numberFormat": { "qty": "#,##0" }
+    "generateTotals": [ { "key": "qty", "value": "SUM" } ],
+    "numberFormat": [ { "key": "qty", "value": "#,##0" } ]
   }
 ]
 ```
@@ -405,8 +444,8 @@ Replaces `{{variable}}` placeholders with strings.
 | `freezeHeader` | Freeze the header row. |
 | `autoFitColumns` | Auto-fit column widths to content. |
 | `asExcelTable` / `excelTableStyle` | Render as native Excel table with style. |
-| `generateTotals` | Per-column aggregation (`sum`, `avg`, `count`, `min`, `max`). |
-| `numberFormat` | Excel number format string per column. |
+| `generateTotals` | Per-column aggregation: `[{ "key": column, "value": "SUM" }]` (`SUM`, `AVERAGE`, `COUNT`, `MIN`, `MAX`). |
+| `numberFormat` | Excel number format per column: `[{ "key": column, "value": "#,##0.00" }]`. |
 | `conditionalFormat` | Conditional formatting rules. |
 | `splitToSheets` | Split rows into multiple sheets by a column value. |
 | `sort` | Sort rows before render. |
@@ -416,14 +455,15 @@ Replaces `{{variable}}` placeholders with strings.
 Replaces `{{image:logo}}`. Accepts URL or Base64.
 
 ```json
-"image": {
-  "logo": {
+"image": [
+  {
+    "key": "logo",
     "src": "https://example.com/logo.png",
     "width": 150,
     "height": 50,
     "fit": "contain"
   }
-}
+]
 ```
 
 ### QR codes (`qrcode`)
@@ -431,13 +471,14 @@ Replaces `{{image:logo}}`. Accepts URL or Base64.
 Replaces `{{qr:website}}`.
 
 ```json
-"qrcode": {
-  "website": {
+"qrcode": [
+  {
+    "key": "website",
     "text": "https://qorstack.dev",
     "size": 200,
     "color": "#000000"
   }
-}
+]
 ```
 
 ### Barcodes (`barcode`)
@@ -445,15 +486,16 @@ Replaces `{{qr:website}}`.
 Replaces `{{barcode:productId}}`. Default format: `Code128`.
 
 ```json
-"barcode": {
-  "productId": {
+"barcode": [
+  {
+    "key": "productId",
     "text": "1234567890",
     "format": "Code128",
     "includeText": true,
     "width": 300,
     "height": 80
   }
-}
+]
 ```
 
 ### Output options
@@ -461,6 +503,7 @@ Replaces `{{barcode:productId}}`. Default format: `Code128`.
 | Field | Type | Description |
 | --- | --- | --- |
 | `fileName` | string | Output file name (without extension). |
+| `templateVersion` | integer | Render this stored version of the template; omit for the current version (unknown → `404`). |
 | `fileType` | string | Word only: `"pdf"` (default) or `"docx"`. |
 | `zipOutput` | boolean | If `true`, bundle the output into a `.zip` archive. |
 | `pdfPassword` | object | *(Pro)* Encrypt the PDF and set permissions. |

package/dist/QorstackApi.d.ts

@@ -370,41 +370,68 @@ export interface RenderResponse {
 }
 export type PdfFromTemplateRequest = DocumentProcessingRequestBase & {
     templateKey?: string;
+    /**
+     * Render this stored version of the template. Omit for the current version.
+     * @format int32
+     * @min 1
+     */
+    templateVersion?: number | null;
     fileName?: string | null;
-    fileType?: string;
+    /** Output format: pdf (default) or docx */
+    fileType?: "pdf" | "docx";
     table?: WordTableDataRequest[] | null;
 };
 export type WordTableDataRequest = TableDataRequest & {
     repeatHeader?: boolean;
 };
 export interface TableDataRequest {
-    rows?: Record<string, any>[];
+    /** Column marker names ({{row:name}}), listed once, in the order of the row values. Unique. */
+    columns: string[];
+    /** Rows; each row is an array of cell values in the order of columns, e.g. [["A", 2]] */
+    rows: (string | number | boolean | null)[][];
     sort?: SortDefinition[] | null;
     verticalMerge?: string[] | null;
     collapse?: string[] | null;
 }
 export interface SortDefinition {
     field?: string;
-    direction?: string;
+    direction?: "asc" | "desc";
 }
 export interface DocumentProcessingRequestBase {
-    replace?: Record<string, string>;
-    image?: Record<string, ImageDataRequest>;
-    qrcode?: Record<string, QrCodeDataRequest>;
-    barcode?: Record<string, BarcodeDataRequest>;
+    /** Variable replacements ({{variable}}): [{ "key": "customer_name", "value": "ACME" }] */
+    replace?: KeyValueRequest[] | null;
+    /** Images for {{image:key}} markers */
+    image?: ImageDataRequest[] | null;
+    /** QR codes for {{qr:key}} markers */
+    qrcode?: QrCodeDataRequest[] | null;
+    /** Barcodes for {{barcode:key}} markers */
+    barcode?: BarcodeDataRequest[] | null;
     pdfPassword?: PdfPasswordRequest | null;
     watermark?: PdfWatermarkRequest | null;
     zipOutput?: boolean;
+    /** Pro: queue the render and return 202 with a job id instead of the file. Poll GET /render/jobs/{jobId} or set webhookUrl. */
+    async?: boolean;
+    /**
+     * With async: true, receives a POST {jobId, status, downloadUrl?, expiresIn?, error?} when the job finishes. Signed with X-Qorstack-Signature when the server has a signing secret.
+     * @format uri
+     * @maxLength 2048
+     */
+    webhookUrl?: string | null;
 }
 export interface ImageDataRequest {
+    /** Image marker name ({{image:key}}) */
+    key?: string;
     src?: string;
     /** @format int32 */
     width?: number | null;
     /** @format int32 */
     height?: number | null;
-    fit?: string | null;
+    /** How the image fills its box: cover, contain (default) or fill */
+    fit?: "cover" | "contain" | "fill" | null;
 }
 export interface QrCodeDataRequest {
+    /** QR marker name ({{qr:key}}) */
+    key?: string;
     text?: string;
     /** @format int32 */
     size?: number;
@@ -413,6 +440,8 @@ export interface QrCodeDataRequest {
     logo?: string | null;
 }
 export interface BarcodeDataRequest {
+    /** Barcode marker name ({{barcode:key}}) */
+    key?: string;
     text?: string;
     format?: string;
     /** @format int32 */
@@ -455,7 +484,7 @@ export interface KeyValuePairOfStringAndJsonNode {
     value?: JsonNode | null;
 }
 export interface JsonNode {
-    underlyingElement?: any;
+    underlyingElement?: any | null;
     options?: JsonNodeOptions | null;
     parent?: JsonNode | null;
     root?: JsonNode;
@@ -475,8 +504,13 @@ export interface ExportExcelUrlResponse {
 }
 export type ExcelFromTemplateRequest = DocumentProcessingRequestBase & {
     templateKey?: string;
+    /**
+     * Render this stored version of the template. Omit for the current version.
+     * @format int32
+     * @min 1
+     */
+    templateVersion?: number | null;
     fileName?: string | null;
-    fileType?: string;
     table?: ExcelTableDataRequest[] | null;
 };
 export type ExcelTableDataRequest = TableDataRequest & {
@@ -486,8 +520,10 @@ export type ExcelTableDataRequest = TableDataRequest & {
     asExcelTable?: boolean;
     excelTableStyle?: string | null;
     outline?: boolean;
-    generateTotals?: Record<string, string>;
-    numberFormat?: Record<string, string>;
+    /** Totals per column: [{ "key": "amount", "value": "sum" }] */
+    generateTotals?: KeyValueRequest[] | null;
+    /** Number format per column: [{ "key": "amount", "value": "#,##0.00" }] */
+    numberFormat?: KeyValueRequest[] | null;
     conditionalFormat?: ConditionalFormatConfigRequest[] | null;
     splitToSheets?: SplitToSheetsConfigRequest | null;
 };
@@ -496,7 +532,7 @@ export interface ConditionalFormatConfigRequest {
     rules?: ConditionalFormatRuleRequest[];
 }
 export interface ConditionalFormatRuleRequest {
-    value?: any;
+    value?: any | null;
     operator?: string | null;
     fontColor?: string | null;
     backgroundColor?: string | null;
@@ -751,6 +787,21 @@ export interface ApiKeyDto {
     /** @format date-time */
     updatedDatetime?: string | null;
 }
+/** Marker name with a text value (replace / generateTotals / numberFormat) */
+export interface KeyValueRequest {
+    /** Marker / column name */
+    key?: string;
+    /** Text value */
+    value?: string;
+}
+export interface ExportPdfAsyncResponse {
+    /** @format uuid */
+    jobId?: string;
+    /** pending → processing → success | failed */
+    status?: string;
+    /** GET this URL to poll the job; it returns a fresh downloadUrl once status is success. */
+    statusUrl?: string | null;
+}
 export type QueryParamsType = Record<string | number, any>;
 export type ResponseFormat = keyof Omit<Body, "body" | "bodyUsed">;
 export interface FullRequestParams extends Omit<RequestInit, "body"> {

package/dist/async.d.ts

@@ -0,0 +1,41 @@
+import type { ExportPdfAsyncResponse, HttpResponse } from "./QorstackApi";
+/** Result of a render call: the finished file, or a queued job (async: true, Pro). */
+export type RenderOutcome<TDownload> = {
+    kind: "download";
+    download: TDownload;
+} | {
+    kind: "queued";
+    job: ExportPdfAsyncResponse;
+};
+/** Status of an async render job (GET /render/jobs/{id}). */
+export interface RenderJobStatus {
+    id: string;
+    /** pending → processing → success | failed */
+    status: "pending" | "processing" | "success" | "failed" | string;
+    /** Fresh download link once status is "success". */
+    downloadUrl?: string | null;
+    downloadUrlExpiresAt?: string | null;
+    errorMessage?: string | null;
+    durationMs?: number | null;
+    fileSizeBytes?: number | null;
+}
+/** HTTP 429: too many unfinished async renders for this user. */
+export declare class RenderQueueFullError extends Error {
+    readonly retryAfterSeconds: number | null;
+    constructor(retryAfterSeconds: number | null);
+}
+/** The async render job finished with status "failed". */
+export declare class RenderJobFailedError extends Error {
+    readonly job: RenderJobStatus;
+    constructor(job: RenderJobStatus);
+}
+export interface WaitForJobOptions {
+    /** Poll interval in ms (default 2000). */
+    intervalMs?: number;
+    /** Give up after this many ms (default 600000 = 10 min). */
+    timeoutMs?: number;
+}
+/** Turns a raw render response into a RenderOutcome; maps 429 to RenderQueueFullError. */
+export declare function toRenderOutcome<T>(call: Promise<HttpResponse<T, unknown>>): Promise<RenderOutcome<T>>;
+/** Polls until the job finishes; resolves with the job (downloadUrl set) or rejects on failure / timeout. */
+export declare function waitForJob(getJob: (jobId: string) => Promise<RenderJobStatus>, jobId: string, { intervalMs, timeoutMs }?: WaitForJobOptions): Promise<RenderJobStatus>;

package/dist/async.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderJobFailedError = exports.RenderQueueFullError = void 0;
+exports.toRenderOutcome = toRenderOutcome;
+exports.waitForJob = waitForJob;
+/** HTTP 429: too many unfinished async renders for this user. */
+class RenderQueueFullError extends Error {
+    constructor(retryAfterSeconds) {
+        super("Too many async renders are pending. Retry later.");
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "RenderQueueFullError";
+    }
+}
+exports.RenderQueueFullError = RenderQueueFullError;
+/** The async render job finished with status "failed". */
+class RenderJobFailedError extends Error {
+    constructor(job) {
+        var _a;
+        super(`Render job ${job.id} failed: ${(_a = job.errorMessage) !== null && _a !== void 0 ? _a : "unknown error"}`);
+        this.job = job;
+        this.name = "RenderJobFailedError";
+    }
+}
+exports.RenderJobFailedError = RenderJobFailedError;
+/** Turns a raw render response into a RenderOutcome; maps 429 to RenderQueueFullError. */
+async function toRenderOutcome(call) {
+    var _a, _b;
+    try {
+        const res = await call;
+        if (res.status === 202) {
+            return { kind: "queued", job: res.data };
+        }
+        return { kind: "download", download: res.data };
+    }
+    catch (err) {
+        const res = err;
+        if (res && res.status === 429) {
+            const header = (_b = (_a = res.headers) === null || _a === void 0 ? void 0 : _a.get) === null || _b === void 0 ? void 0 : _b.call(_a, "Retry-After");
+            const seconds = header ? Number.parseInt(header, 10) : NaN;
+            throw new RenderQueueFullError(Number.isFinite(seconds) ? seconds : null);
+        }
+        throw err;
+    }
+}
+/** Polls until the job finishes; resolves with the job (downloadUrl set) or rejects on failure / timeout. */
+async function waitForJob(getJob, jobId, { intervalMs = 2000, timeoutMs = 600000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const job = await getJob(jobId);
+        if (job.status === "success")
+            return job;
+        if (job.status === "failed")
+            throw new RenderJobFailedError(job);
+        if (Date.now() + intervalMs > deadline) {
+            throw new Error(`Render job ${jobId} did not finish in time (last status: ${job.status}).`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { Api } from "./QorstackApi";
+import { Api, ExcelFromTemplateRequest, ExportExcelUrlResponse, ExportPdfUrlResponse, PdfFromTemplateRequest, RequestParams } from "./QorstackApi";
+import { RenderJobStatus, RenderOutcome, WaitForJobOptions } from "./async";
 export * from "./QorstackApi";
+export * from "./async";
 export declare class QorstackApi<SecurityDataType = unknown> extends Api<SecurityDataType> {
     /**
      * Creates a new instance of QorstackApi.
@@ -9,4 +11,12 @@ export declare class QorstackApi<SecurityDataType = unknown> extends Api<Securit
         baseUrl?: string;
         securityData?: SecurityDataType;
     });
+    /** Render from a Word template: the file link, or (with async: true, Pro) the queued job. */
+    renderWord(data: PdfFromTemplateRequest, params?: RequestParams): Promise<RenderOutcome<ExportPdfUrlResponse>>;
+    /** Render from an Excel template: the file link, or (with async: true, Pro) the queued job. */
+    renderExcel(data: ExcelFromTemplateRequest, params?: RequestParams): Promise<RenderOutcome<ExportExcelUrlResponse>>;
+    /** GET /render/jobs/{jobId}. */
+    getRenderJob(jobId: string, params?: RequestParams): Promise<RenderJobStatus>;
+    /** Polls an async job until it finishes; resolves with downloadUrl set, rejects on failure or timeout. */
+    waitForJob(jobId: string, options?: WaitForJobOptions): Promise<RenderJobStatus>;
 }

package/dist/index.js

@@ -16,7 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QorstackApi = void 0;
 const QorstackApi_1 = require("./QorstackApi");
+const async_1 = require("./async");
 __exportStar(require("./QorstackApi"), exports);
+__exportStar(require("./async"), exports);
 class QorstackApi extends QorstackApi_1.Api {
     /**
      * Creates a new instance of QorstackApi.
@@ -36,8 +38,11 @@ class QorstackApi extends QorstackApi_1.Api {
                 // Ignore errors accessing process.env
             }
         }
-        // Fallback to default if still not found
-        baseUrl = baseUrl || "https://api.qorstack.dev";
+        // Fallback to the self-host default if still not found. Since v2 the API lives under /api on the
+        // same port as the web UI; a v1-style URL without it (http://host:8080) gets /api appended.
+        baseUrl = (baseUrl || "http://localhost:8080/api").replace(/\/+$/, "");
+        if (!/\/api$/.test(baseUrl))
+            baseUrl = `${baseUrl}/api`;
         super({
             baseUrl,
             securityWorker: (securityData) => {
@@ -51,5 +56,28 @@ class QorstackApi extends QorstackApi_1.Api {
             this.setSecurityData(config.securityData);
         }
     }
+    /** Render from a Word template: the file link, or (with async: true, Pro) the queued job. */
+    renderWord(data, params = {}) {
+        return (0, async_1.toRenderOutcome)(this.render.postRenderWordTemplate(data, params));
+    }
+    /** Render from an Excel template: the file link, or (with async: true, Pro) the queued job. */
+    renderExcel(data, params = {}) {
+        return (0, async_1.toRenderOutcome)(this.render.postRenderExcelTemplate(data, params));
+    }
+    /** GET /render/jobs/{jobId}. */
+    async getRenderJob(jobId, params = {}) {
+        const res = await this.request({
+            path: `/render/jobs/${encodeURIComponent(jobId)}`,
+            method: "GET",
+            secure: true,
+            format: "json",
+            ...params,
+        });
+        return res.data;
+    }
+    /** Polls an async job until it finishes; resolves with downloadUrl set, rejects on failure or timeout. */
+    waitForJob(jobId, options) {
+        return (0, async_1.waitForJob)((id) => this.getRenderJob(id), jobId, options);
+    }
 }
 exports.QorstackApi = QorstackApi;

package/package.json

@@ -1,38 +1,45 @@
-{
-  "name": "qorstack-report-sdk",
-  "version": "0.1.1",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "sync-config": "node scripts/sync-config.js",
-    "prebuild": "yarn sync-config",
-    "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "gen:nodejs": "swagger-typescript-api generate -p ../backend/swagger-sdk.json -o ./src/nodejs --name QorstackApi.ts",
-    "gen:dotnet": "nswag openapi2csclient /input:../backend/swagger-sdk.json /output:src/dotnet/QorstackApi.cs /namespace:Qorstack.Report.Sdk /ClassName:QorstackApi",
-    "gen:all": "yarn gen:nodejs && yarn gen:dotnet"
-  },
-  "keywords": [
-    "qorstack",
-    "report",
-    "sdk",
-    "pdf",
-    "word"
-  ],
-  "author": "Qorstack",
-  "license": "MIT",
-  "description": "Qorstack Report SDK for Node.js and .NET",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/qorstack/qorstack-report"
-  },
-  "devDependencies": {
-    "@types/node": "^25.2.1",
-    "nswag": "^14.6.3",
-    "swagger-typescript-api": "^13.2.16",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "qorstack-report-sdk",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "sync-config": "node scripts/sync-config.js",
+    "prebuild": "pnpm sync-config",
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "gen:nodejs": "swagger-typescript-api generate -p ../backend/swagger-sdk.json -o ./src/nodejs --name QorstackApi.ts",
+    "gen:dotnet": "nswag openapi2csclient /input:../backend/swagger-sdk.json /output:src/dotnet/QorstackApi.cs /namespace:Qorstack.Report.Sdk /ClassName:QorstackApi",
+    "gen:all": "pnpm gen:nodejs && pnpm gen:dotnet"
+  },
+  "keywords": [
+    "qorstack",
+    "report",
+    "sdk",
+    "pdf",
+    "word"
+  ],
+  "author": "Qorstack",
+  "license": "MIT",
+  "description": "Qorstack Report SDK for Node.js and .NET",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/qorstack/qorstack-report"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "nswag": "^14.6.3",
+    "swagger-typescript-api": "13.12.2",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "pnpm": {
+    "overrides": {
+      "axios": "1.20.0",
+      "defu": "6.1.5"
+    }
+  }
+}