qorstack-report-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,370 +1,499 @@
-# Qorstack Report SDK
-
-The official SDK for Qorstack Report, a powerful API for generating PDF reports from Microsoft Word (DOCX) templates.
-This SDK simplifies the integration of Qorstack Report into your **Node.js** and **.NET** applications.
-
-## Features
-
-- **Template-Based Rendering**: Generate PDFs from templates stored in your Qorstack Report account.
-- **Dynamic File Rendering**: Generate PDFs directly from a base64-encoded DOCX file.
-- **Comprehensive Data Binding**:
-  - Text replacement
-  - Dynamic tables (with merge and collapse support)
-  - Images (from URL or Base64)
-  - QR Codes and Barcodes
-  - Conditional logic (hide/show sections)
-- **Cross-Platform Support**: Fully typed libraries for TypeScript/Node.js and C#/.NET 8.0+.
-
----
-
-## Installation
-
-### Node.js (TypeScript/JavaScript)
-
-```bash
-npm install qorstack-report-sdk
-# or
-yarn add qorstack-report-sdk
-```
-
-### .NET (C#)
-
-```bash
-dotnet add package Qorstack.Report.Sdk
-```
-
----
-
-## Authentication
-
-To use the SDK, you need an **API Key** from the Qorstack Portal.
-
-1. Log in to the Qorstack Portal.
-2. Navigate to **Settings > API Keys**.
-3. Create a new API Key.
-
----
-
-## Getting Started
-
-### Node.js Setup
-
-```typescript
-import { QorstackApi } from "qorstack-report-sdk";
-
-// 1. Initialize the client with API Key
-const qorstackApi = new QorstackApi({
-  securityData: {
-    headers: {
-      "X-API-KEY": "YOUR_API_KEY_HERE",
-    },
-  },
-});
-
-// OR: Initialize with custom Base URL and API Key
-const qorstackApiCustom = new QorstackApi({
-  baseUrl: "https://your-custom-url.com",
-  securityData: {
-    headers: {
-      "X-API-KEY": "YOUR_API_KEY_HERE",
-    },
-  },
-});
-```
-
-### .NET Setup
-
-```csharp
-using Qorstack.Report.Sdk;
-using System.Net.Http;
-
-// 1. Initialize the Client with API Key
-var qorstackApi = new QorstackApi(apiKey: "YOUR_API_KEY_HERE");
-
-// OR: Initialize with custom Base URL and API Key
-var qorstackApiCustom = new QorstackApi("https://your-custom-url.com", "YOUR_API_KEY_HERE");
-```
-
----
-
-## Usage Examples
-
-This section demonstrates how to construct request objects for various scenarios.
-
-### 1. Generate PDF from Template (`PdfFromTemplateRequest`)
-
-This is the most common use case. You reference a `templateKey` stored in the system.
-
-#### Full Feature Example (Text, Table, Image, QR, Barcode)
-
-**Node.js (TypeScript)**
-
-```typescript
-// Prepare table rows
-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,
-}));
-
-const response = await qorstackApi.render.postRenderTemplatePdf({
-  templateKey: "RENDOX-7326-758-974-2067",
-  fileName: "Full_Report_Example",
-  replace: {
-    customer_name: "Example Company Ltd.",
-    document_date: new Date().toLocaleDateString("en-GB"), // dd/MM/yyyy
-    total_amount: "1,500.00",
-  },
-  table: [
-    {
-      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,
-    },
-  },
-});
-
-console.log("Download URL:", response.data.downloadUrl);
-```
-
-**C# (.NET)**
-
-```csharp
-var data = await _exampleService.GetDataAsync(id);
-
-var tableRows = data.Select((item, index) => new Dictionary<string, object>
-{
-    { "no", index + 1 },
-    { "category", item.Category },
-    { "description", item.Description },
-    { "qty", item.Quantity },
-    { "unit_price", item.Price },
-    { "amount", item.Total }
-}).ToList();
-
-var request = new PdfFromTemplateRequest
-{
-    TemplateKey = "RENDOX-7326-758-974-2067",
-    FileName = "Full_Report_Example",
-    Replace = new()
-    {
-        { "customer_name", "Example Company Ltd." },
-        { "document_date", DateTime.Now.ToString("dd/MM/yyyy") },
-        { "total_amount", "1,500.00" }
-    },
-    Table = new()
-    {
-        new()
-        {
-            Rows = tableRows,
-            VerticalMerge = new() { "category" },
-            Collapse = new() { "description" }
-        }
-    },
-    Image = new()
-    {
-        {
-            "header_logo",
-            new() { Src = "https://example.com/logo.png", Width = 200, Fit = "contain" }
-        }
-    },
-    QrCode = new()
-    {
-        {
-            "payment_qr",
-            new() { Text = "https://payment.link/123456", Size = 150 }
-        }
-    },
-    Barcode = new()
-    {
-        {
-            "product_barcode",
-            new() { Text = "PROD-123456789", Format = "Code128", Width = 300, Height = 80 }
-        }
-    }
-};
-
-var response = await qorstackApi.PostRenderTemplatePdfAsync(request);
-```
-
----
-
-### 2. Generate PDF from File (`PdfFromFileRequest`)
-
-Use this when you want to send the DOCX template file directly with the request.
-
-**Node.js (TypeScript)**
-
-```typescript
-import * as fs from "fs";
-
-// Read local file as Base64
-const fileBuffer = fs.readFileSync("template.docx");
-const base64File = fileBuffer.toString("base64");
-
-const response = await qorstackApi.render.postRenderDocxPdf({
-  fileBase64: base64File,
-  fileName: "OnDemand_Report",
-  replace: {
-    title: "Report Title",
-  },
-  table: [
-    {
-      rows: [
-        { item: "Item A", price: 100 },
-        { item: "Item B", price: 200 },
-      ],
-    },
-  ],
-});
-```
-
-**C# (.NET)**
-
-```csharp
-byte[] fileBytes = await File.ReadAllBytesAsync("template.docx");
-
-var request = new PdfFromFileRequest
-{
-    FileBase64 = Convert.ToBase64String(fileBytes),
-    FileName = "OnDemand_Report",
-    Replace = new()
-    {
-        { "title", "Report Title" }
-    },
-    Table = new()
-    {
-        new()
-        {
-            Rows = new()
-            {
-                new Dictionary<string, object> { { "item", "Item A" }, { "price", 100 } },
-                new Dictionary<string, object> { { "item", "Item B" }, { "price", 200 } }
-            }
-        }
-    }
-};
-
-var response = await qorstackApi.PostRenderDocxPdfAsync(request);
-```
-
----
-
-## Data Binding Reference
-
-The Qorstack Report engine supports various data types. Here is how to structure your request object.
-
-### Text Replacement (`replace`)
-
-Simple key-value pairs to replace text placeholders like `{{customerName}}`.
-
-```json
-"replace": {
-  "customerName": "Acme Corp",
-  "totalAmount": "$1,050.00"
-}
-```
-
-### Tables (`table`)
-
-Populates rows in a table. The `rows` array contains objects where keys match the columns in your Word table.
-
-```json
-"table": [
-  {
-    "rows": [
-      { "name": "Value A", "last_name": "Value B" },
-      { "name": "Value C", "last_name": "Value D" }
-    ],
-    "verticalMerge": ["category"],
-    "collapse": ["description"]
-  }
-]
-```
-
-### Images (`image`)
-
-Replaces placeholders like `{{image:logo}}`. Supports URLs or Base64.
-
-- `src`: Image URL or Base64 string.
-- `width`, `height`: Optional dimensions in pixels.
-- `fit`: Optional ("contain", "cover", "fill").
-
-```json
-"image": {
-  "logo": {
-    "src": "https://example.com/logo.png",
-    "width": 150,
-    "height": 50
-  }
-}
-```
-
-### QR Codes (`qrcode`)
-
-Generates QR codes for placeholders like `{{qr:website}}`.
-
-```json
-"qrcode": {
-  "website": {
-    "text": "https://qorstack.dev",
-    "size": 200,
-    "color": "#000000"
-  }
-}
-```
-
-### Barcodes (`barcode`)
-
-Generates barcodes for placeholders like `{{barcode:productId}}`.
-
-- `format`: Default is "Code128".
-
-```json
-"barcode": {
-  "productId": {
-    "text": "1234567890",
-    "format": "Code128",
-    "includeText": true
-  }
-}
-```
-
----
-
-## Error Handling
-
-The SDK throws exceptions when the API returns an error (e.g., 400 Bad Request, 401 Unauthorized).
-
-- **Node.js**: The promise will reject with the error response.
-- **.NET**: `ApiException` or `ApiException<ProblemDetails>` will be thrown. You can access `ex.Result` to get detailed error messages from the server.
-
----
-
-## License
-
-MIT License. See [LICENSE](LICENSE) for details.
+# Qorstack Report SDK
+
+The official SDK for **Qorstack Report** — a REST API for generating **PDF**, **DOCX**, and **XLSX** reports from Microsoft Word and Excel templates.
+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.
+- **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:**
+  - Text replacement
+  - 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)*:
+  - PDF password protection
+  - PDF watermarking
+- **Zip output** — bundle multiple output files into a `.zip`.
+- **Cross-platform** — fully typed clients for TypeScript/Node.js and C#/.NET 8.0+.
+
+---
+
+## Installation
+
+### Node.js (TypeScript/JavaScript)
+
+```bash
+npm install qorstack-report-sdk
+# or
+pnpm add qorstack-report-sdk
+```
+
+### .NET (C#)
+
+```bash
+dotnet add package Qorstack.Report.Sdk
+```
+
+---
+
+## Authentication
+
+You need an **API Key** from the Qorstack Portal.
+
+1. Log in to the Qorstack Portal.
+2. Navigate to **Settings → API Keys**.
+3. Create a new API Key (scoped per project).
+
+---
+
+## Getting Started
+
+### Node.js Setup
+
+```typescript
+import { QorstackApi } from "qorstack-report-sdk";
+
+// Initialize the client with API Key
+const qorstackApi = new QorstackApi({
+  securityData: {
+    headers: {
+      "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",
+  securityData: {
+    headers: {
+      "X-API-KEY": "YOUR_API_KEY_HERE",
+    },
+  },
+});
+```
+
+### .NET Setup
+
+```csharp
+using Qorstack.Report.Sdk;
+
+// Initialize with API Key
+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");
+```
+
+---
+
+## Usage Examples
+
+### 1. Render Word/PDF from template (`PdfFromTemplateRequest`)
+
+Endpoint: `POST /render/word/template`
+Method: `render.postRenderWordTemplate` (Node) / `PostRenderWordTemplateAsync` (.NET)
+
+Use `fileType: "pdf"` (default) to get a PDF, or `"docx"` to get the rendered Word document.
+
+#### Full feature example (text, table, image, QR, barcode)
+
+```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,
+}));
+
+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",
+  },
+  table: [
+    {
+      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,
+    },
+  },
+});
+
+console.log("Download URL:", response.data.downloadUrl);
+```
+
+```csharp
+// C# (.NET)
+var data = await _exampleService.GetDataAsync(id);
+
+var tableRows = data.Select((item, index) => new Dictionary<string, object>
+{
+    { "no", index + 1 },
+    { "category", item.Category },
+    { "description", item.Description },
+    { "qty", item.Quantity },
+    { "unit_price", item.Price },
+    { "amount", item.Total }
+}).ToList();
+
+var request = new PdfFromTemplateRequest
+{
+    TemplateKey = "RENDOX-7326-758-974-2067",
+    FileName = "Full_Report_Example",
+    FileType = "pdf",
+    Replace = new()
+    {
+        { "customer_name", "Example Company Ltd." },
+        { "document_date", DateTime.Now.ToString("dd/MM/yyyy") },
+        { "total_amount", "1,500.00" }
+    },
+    Table = new()
+    {
+        new()
+        {
+            Rows = tableRows,
+            VerticalMerge = new() { "category" },
+            Collapse = new() { "description" }
+        }
+    },
+    Image = new()
+    {
+        { "header_logo", new() { Src = "https://example.com/logo.png", Width = 200, Fit = "contain" } }
+    },
+    QrCode = new()
+    {
+        { "payment_qr", new() { Text = "https://payment.link/123456", Size = 150 } }
+    },
+    Barcode = new()
+    {
+        { "product_barcode", new() { Text = "PROD-123456789", Format = "Code128", Width = 300, Height = 80 } }
+    }
+};
+
+var response = await qorstackApi.PostRenderWordTemplateAsync(request);
+Console.WriteLine($"Download URL: {response.DownloadUrl}");
+```
+
+---
+
+### 2. Render Excel from template (`ExcelFromTemplateRequest`)
+
+Endpoint: `POST /render/excel/template`
+Method: `render.postRenderExcelTemplate` (Node) / `PostRenderExcelTemplateAsync` (.NET)
+
+```typescript
+// Node.js (TypeScript)
+const response = await qorstackApi.render.postRenderExcelTemplate({
+  templateKey: "XLSX-1234-5678",
+  fileName: "Sales_Report_Q1",
+  replace: {
+    report_period: "Q1 2026",
+    generated_by: "Sales Team",
+  },
+  table: [
+    {
+      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 },
+      ],
+      autoFilter: true,
+      freezeHeader: true,
+      autoFitColumns: true,
+      asExcelTable: true,
+      excelTableStyle: "TableStyleMedium2",
+      generateTotals: { total: "sum", qty: "sum" },
+      numberFormat: { total: "#,##0.00" },
+    },
+  ],
+});
+
+console.log("Download URL:", response.data.downloadUrl);
+```
+
+```csharp
+// C# (.NET)
+var request = new ExcelFromTemplateRequest
+{
+    TemplateKey = "XLSX-1234-5678",
+    FileName = "Sales_Report_Q1",
+    Replace = new()
+    {
+        { "report_period", "Q1 2026" },
+        { "generated_by", "Sales Team" }
+    },
+    Table = new()
+    {
+        new()
+        {
+            Rows = new()
+            {
+                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 } }
+            },
+            AutoFilter = true,
+            FreezeHeader = true,
+            AutoFitColumns = true,
+            AsExcelTable = true,
+            ExcelTableStyle = "TableStyleMedium2",
+            GenerateTotals = new() { { "total", "sum" }, { "qty", "sum" } },
+            NumberFormat = new() { { "total", "#,##0.00" } }
+        }
+    }
+};
+
+var response = await qorstackApi.PostRenderExcelTemplateAsync(request);
+```
+
+---
+
+### 3. PDF password protection *(Pro)*
+
+```typescript
+const response = await qorstackApi.render.postRenderWordTemplate({
+  templateKey: "RENDOX-7326-758-974-2067",
+  fileName: "Confidential_Report",
+  fileType: "pdf",
+  pdfPassword: {
+    userPassword: "open-me",
+    ownerPassword: "owner-secret",
+    restrictPrinting: true,
+    restrictCopying: true,
+    restrictModifying: true,
+  },
+});
+```
+
+---
+
+### 4. PDF watermark *(Pro)*
+
+```typescript
+const response = await qorstackApi.render.postRenderWordTemplate({
+  templateKey: "RENDOX-7326-758-974-2067",
+  fileName: "Draft_Report",
+  fileType: "pdf",
+  watermark: {
+    text: "DRAFT",
+    fontSize: 72,
+    fontFamily: "Arial",
+  },
+});
+```
+
+---
+
+### 5. Sandbox render (preview using template's sample payload)
+
+Endpoint: `POST /render/word/template-sandbox/{templateKey}`
+Useful for previewing a template without supplying real data.
+
+```typescript
+const response = await qorstackApi.render.postRenderWordTemplateSandbox(
+  "RENDOX-7326-758-974-2067",
+  { fileName: "Preview" },
+  /* body */ null, // or a JSON object to override the sandbox payload
+);
+```
+
+---
+
+### 6. Inspect render jobs
+
+```typescript
+// List jobs
+const jobs = await qorstackApi.render.getRenderJobs({
+  page: 1,
+  pageSize: 20,
+  // templateKey: "...", status: "Success" | "Failed" | "Pending"
+});
+
+// Get one
+const job = await qorstackApi.render.getRenderJobById("job-id-here");
+```
+
+---
+
+## Data Binding Reference
+
+### Text replacement (`replace`)
+
+Replaces `{{variable}}` placeholders with strings.
+
+```json
+"replace": {
+  "customerName": "Acme Corp",
+  "totalAmount": "$1,050.00"
+}
+```
+
+### Word table (`table` — `WordTableDataRequest[]`)
+
+```json
+"table": [
+  {
+    "rows": [
+      { "name": "Value A", "last_name": "Value B" },
+      { "name": "Value C", "last_name": "Value D" }
+    ],
+    "verticalMerge": ["category"],
+    "collapse": ["description"]
+  }
+]
+```
+
+| Field | Description |
+| --- | --- |
+| `rows` | Array of row objects. Keys match column placeholders. |
+| `verticalMerge` | Columns whose adjacent identical values are merged vertically. |
+| `collapse` | Columns whose empty/duplicate values collapse to keep layout tidy. |
+
+### Excel table (`table` — `ExcelTableDataRequest[]`)
+
+```json
+"table": [
+  {
+    "rows": [{ "region": "North", "qty": 10 }],
+    "autoFilter": true,
+    "freezeHeader": true,
+    "autoFitColumns": true,
+    "asExcelTable": true,
+    "excelTableStyle": "TableStyleMedium2",
+    "generateTotals": { "qty": "sum" },
+    "numberFormat": { "qty": "#,##0" }
+  }
+]
+```
+
+| Field | Description |
+| --- | --- |
+| `autoFilter` | Enable Excel auto-filter on the header row. |
+| `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. |
+| `conditionalFormat` | Conditional formatting rules. |
+| `splitToSheets` | Split rows into multiple sheets by a column value. |
+| `sort` | Sort rows before render. |
+
+### Images (`image`)
+
+Replaces `{{image:logo}}`. Accepts URL or Base64.
+
+```json
+"image": {
+  "logo": {
+    "src": "https://example.com/logo.png",
+    "width": 150,
+    "height": 50,
+    "fit": "contain"
+  }
+}
+```
+
+### QR codes (`qrcode`)
+
+Replaces `{{qr:website}}`.
+
+```json
+"qrcode": {
+  "website": {
+    "text": "https://qorstack.dev",
+    "size": 200,
+    "color": "#000000"
+  }
+}
+```
+
+### Barcodes (`barcode`)
+
+Replaces `{{barcode:productId}}`. Default format: `Code128`.
+
+```json
+"barcode": {
+  "productId": {
+    "text": "1234567890",
+    "format": "Code128",
+    "includeText": true,
+    "width": 300,
+    "height": 80
+  }
+}
+```
+
+### Output options
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fileName` | string | Output file name (without extension). |
+| `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. |
+| `watermark` | object | *(Pro)* Apply a text watermark to the PDF. |
+
+---
+
+## Response shape
+
+All render endpoints return a download URL plus metadata:
+
+```jsonc
+{
+  "downloadUrl": "https://.../output.pdf",
+  "fileName": "Full_Report_Example.pdf",
+  "fileSize": 102400,
+  "fileType": "pdf",
+  "status": "Success",
+  "isZipped": false
+}
+```
+
+---
+
+## Error Handling
+
+The SDK throws when the API returns 4xx/5xx (`ProblemDetails` payload).
+
+- **Node.js** — the promise rejects; `error.error` contains the `ProblemDetails` body.
+- **.NET** — `ApiException<ProblemDetails>` is thrown; access `ex.Result` for the body.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qorstack-report-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -8,12 +8,12 @@
   ],
   "scripts": {
     "sync-config": "node scripts/sync-config.js",
-    "prebuild": "yarn sync-config",
+    "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": "yarn gen:nodejs && yarn gen:dotnet"
+    "gen:all": "pnpm gen:nodejs && pnpm gen:dotnet"
   },
   "keywords": [
     "qorstack",