@speresps/pdf-module 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,1171 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @speresps/pdf-module
+
+A reusable PDF generation and document management module for **Node.js and Next.js applications**. It provides Persian (Farsi) and RTL-compatible PDF generation using `pdfmake-rtl`, embedded Vazirmatn fonts, customizable headers and footers, table and text templates, paginated reports, server-side PDF storage, and browser downloads.
+
+The module includes four PDF generation methods:
+
+- `generatePDFTable()` — Generate a PDF containing a table.
+- `generatePDFText()` — Generate a PDF containing text.
+- `generatePDFTextAndTable()` — Generate a PDF containing text followed by a table.
+- `generatePDFTextAndTableWithPagination()` — Generate a PDF containing repeated text and separately paginated tables.
+
+Generated PDF files are stored in the consuming project's configured directory and can subsequently be downloaded through the client API.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Project Configuration](#project-configuration)
+- [Project Structure](#project-structure)
+- [Importing the Module](#importing-the-module)
+- [API Reference](#api-reference)
+    - [generatePDFTable](#1-generatepdftable)
+    - [generatePDFText](#2-generatepdftext)
+    - [generatePDFTextAndTable](#3-generatepdftextandtable)
+    - [generatePDFTextAndTableWithPagination](#4-generatepdftextandtablewithpagination)
+    - [downloadPDF](#5-downloadpdf)
+- [Header Configuration](#header-configuration)
+- [Footer Configuration](#footer-configuration)
+- [Logo Requirements](#logo-requirements)
+- [PDF Generation Examples](#pdf-generation-examples)
+- [Server-Side Usage](#server-side-usage)
+- [Client-Side Usage with Next.js](#client-side-usage-with-nextjs)
+- [PDF Storage](#pdf-storage)
+- [Return Values and Error Handling](#return-values-and-error-handling)
+- [Important Notes](#important-notes)
+- [License](#license)
+
+---
+
+## Features
+
+- Generate PDF documents using `pdfmake-rtl`.
+- Support for Persian (Farsi) text and right-to-left (RTL) layouts.
+- Embedded Vazirmatn fonts; no separate font installation is required in the consuming application.
+- Customizable PDF headers and titles.
+- Optional Base64 image/logo in the header.
+- Customizable footer information.
+- Automatic footer page numbering.
+- Four reusable PDF templates.
+- Automatic portrait/landscape orientation selection for table-based templates.
+- Configurable PDF filenames.
+- Support for externally paginated data.
+- Server-side PDF generation and file storage.
+- Client-side PDF downloads in Next.js applications.
+- Integration with `@speresps/config-module` and `@speresps/report-module`.
+- ES Module support.
+
+---
+
+## Requirements
+
+- Node.js 20 or newer.
+- JavaScript ES Modules (`"type": "module"`).
+- For the browser download API: Next.js with React and support for Server Actions.
+- A root-level `config/` directory in the consuming project.
+- A `config/pdf.conf` configuration file.
+
+### Dependencies
+
+The module declares the following runtime dependencies:
+
+| Package | Purpose |
+|---|---|
+| `@speresps/config-module` | Loads the consuming project's PDF configuration. |
+| `@speresps/report-module` | Provides logging functionality. |
+| `pdfmake-rtl` | Generates PDF documents with RTL support. |
+
+These dependencies are declared in the module's `package.json` and are installed automatically when the module is installed through npm.
+
+**Important:** The consuming application must also provide its own `config/pdf.conf` file. Installing the module does not automatically create this configuration file.
+
+---
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @speresps/pdf-module
+```
+
+The module supports separate entry points for server-side and client-side usage.
+
+---
+
+## Project Configuration
+
+The module uses `@speresps/config-module` to load its configuration from the consuming project's root-level `config/` directory.
+
+Create the following directory and file:
+
+```text
+your-project/
+└── config/
+    └── pdf.conf
+```
+
+### config/pdf.conf
+
+Use the following configuration:
+
+```ini
+################# Table ################
+FILENAME_TABLE = table.pdf
+
+################# Text #################
+FILENAME_TEXT = text.pdf
+
+############### Text + Table ############
+FILENAME_TEXT_TABLE = text-table.pdf
+
+########## Text + Table Pagination ######
+FILENAME_TEXT_TABLE_PAGINATION = text-table-pagination.pdf
+
+############ Auto Download Status #######
+AUTO_DOWNLOAD = false
+
+################ Files Route ############
+MAIN_FOLDER_NAME = files
+PDF_FOLDER_NAME = pdf
+```
+
+### Configuration Properties
+
+| Property | Default | Description |
+|---|---|---|
+| `FILENAME_TABLE` | `table.pdf` | Default filename for table PDFs. |
+| `FILENAME_TEXT` | `text.pdf` | Default filename for text PDFs. |
+| `FILENAME_TEXT_TABLE` | `text-table.pdf` | Default filename for text-and-table PDFs. |
+| `FILENAME_TEXT_TABLE_PAGINATION` | `text-table-pagination.pdf` | Default filename for paginated PDFs. |
+| `AUTO_DOWNLOAD` | `false` | Configured automatic-download setting. |
+| `MAIN_FOLDER_NAME` | `files` | Main directory for generated files. |
+| `PDF_FOLDER_NAME` | `pdf` | PDF storage subdirectory. |
+
+The generated PDFs are stored under:
+
+```text
+your-project/
+└── files/
+    └── pdf/
+        ├── table.pdf
+        ├── text.pdf
+        ├── text-table.pdf
+        └── text-table-pagination.pdf
+```
+
+The `files/` and `pdf/` directories are created automatically when a PDF is saved.
+
+### Logger Configuration
+
+The module uses `@speresps/report-module` internally:
+
+```javascript
+import { reportLogger } from "@speresps/report-module";
+
+const logger = reportLogger({
+    directory: "./report/logs",
+    level: "debug",
+    console: false,
+    service: "PDF",
+});
+```
+
+You do not need to create a logger or pass one to the PDF methods. Logging is initialized internally by the module.
+
+---
+
+## Project Structure
+
+A typical consuming project can use the following structure:
+
+```text
+your-project/
+│
+├── config/
+│   └── pdf.conf
+│
+├── files/
+│   └── pdf/
+│
+├── report/
+│   └── logs/
+│
+├── src/
+│   └── app/
+│       └── ...
+│
+├── package.json
+└── ...
+```
+
+The `config/` directory is required. The PDF and log directories are created by their respective modules when needed.
+
+---
+
+## Importing the Module
+
+The package provides three entry points.
+
+### 1. Main Entry Point — Server API
+
+Use the main package entry point for Node.js server-side applications:
+
+```javascript
+import {
+    generatePDFTable,
+    generatePDFText,
+    generatePDFTextAndTable,
+    generatePDFTextAndTableWithPagination,
+    existsPDF,
+    downloadPDF,
+} from "@speresps/pdf-module";
+```
+
+Equivalent explicit server import:
+
+```javascript
+import {
+    generatePDFTable,
+    generatePDFText,
+    generatePDFTextAndTable,
+    generatePDFTextAndTableWithPagination,
+    existsPDF,
+    downloadPDF,
+} from "@speresps/pdf-module/server";
+```
+
+### 2. Client Entry Point
+
+For Next.js client components:
+
+```javascript
+import {
+    generatePDFTable,
+    generatePDFText,
+    generatePDFTextAndTable,
+    generatePDFTextAndTableWithPagination,
+    existsPDF,
+    downloadPDF,
+} from "@speresps/pdf-module/client";
+```
+
+The client entry point provides Server Action wrappers for PDF generation and a browser download helper.
+
+**Important:** Client-side generation methods invoke Next.js Server Actions. They are not standalone browser-only PDF generators and require a compatible Next.js application.
+
+---
+
+# API Reference
+
+All four generation methods receive a single JavaScript object containing the PDF data and optional presentation settings.
+
+Common properties:
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `headerTitle` | `string` | No | Text displayed in the PDF header. |
+| `headerLogoBase64` | `string` | No | Base64 image data for the header logo. |
+| `footerInfo` | `object` | No | Website and contact information displayed in the footer. |
+| `fileName` | `string` | No | Name used when saving the generated PDF. |
+| `autoDownload` | `boolean` | No | Passed through by the generation service, but does not currently trigger automatic downloading through the public API. |
+
+The required content properties differ depending on the selected PDF method.
+
+---
+
+## 1. generatePDFTable()
+
+Generates a PDF containing a table, including the configured header and footer.
+
+### Method Signature
+
+```javascript
+generatePDFTable({
+    columns,
+    tableData,
+    headerTitle,
+    headerLogoBase64,
+    footerInfo,
+    fileName,
+});
+```
+
+### Required Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `columns` | `string[]` | Yes | Array of column names. |
+| `tableData` | `object[]` | Yes | Array of row objects. |
+
+Each column name must correspond to a property in the table row objects.
+
+### Example
+
+```javascript
+import { generatePDFTable } from "@speresps/pdf-module/client";
+
+const columns = [
+    "نام",
+    "سن",
+    "شغل",
+    "آدرس",
+    "تلفن",
+    "جنسیت",
+];
+
+const tableData = [
+    {
+        نام: "سارا",
+        سن: 28,
+        شغل: "طراح گرافیک",
+        آدرس: "خیابان انقلاب، تهران",
+        تلفن: "09123456789",
+        جنسیت: "زن",
+    },
+    {
+        نام: "علی",
+        سن: 30,
+        شغل: "برنامه‌نویس",
+        آدرس: "خیابان آزادی، تهران",
+        تلفن: "09123456789",
+        جنسیت: "مرد",
+    },
+];
+
+const footerInfo = {
+    siteName: "سایت من",
+    address: "خیابان انقلاب، تهران",
+    phone: "۰۲۱-۱۲۳۴۵۶۷۸",
+    email: "info@mysite.com",
+    website: "www.mysite.com",
+};
+
+const result = await generatePDFTable({
+    columns,
+    tableData,
+
+    headerTitle: "لیست اعضای تیم",
+    headerLogoBase64: "data:image/png;base64,YOUR_COMPLETE_BASE64_IMAGE",
+
+    footerInfo,
+
+    fileName: "team-members.pdf",
+});
+
+if (result.success) {
+    console.log("PDF generated successfully.");
+} else {
+    console.error(result.message);
+}
+```
+
+### Table Data Rules
+
+- `columns` must be a non-empty array of non-empty strings.
+- `tableData` must be an array.
+- Every row must be a JavaScript object.
+- Column names must match the keys in the row objects.
+- Missing row values are rendered as empty strings.
+
+The table template calculates column widths and selects portrait or landscape orientation based on the estimated table width.
+
+---
+
+## 2. generatePDFText()
+
+Generates a PDF containing text with a customizable header and footer.
+
+### Method Signature
+
+```javascript
+generatePDFText({
+    text,
+    headerTitle,
+    headerLogoBase64,
+    footerInfo,
+    fileName,
+});
+```
+
+### Required Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `text` | `string` | Yes | Main PDF content. |
+
+### Example
+
+```javascript
+import { generatePDFText } from "@speresps/pdf-module/client";
+
+const text = `
+این یک متن نمونه فارسی است.
+
+این متن در فایل PDF نمایش داده می‌شود.
+فونت Vazirmatn برای نمایش صحیح متن فارسی استفاده می‌شود.
+`;
+
+const footerInfo = {
+    siteName: "سایت من",
+    address: "خیابان آزادی، تهران",
+    phone: "۰۲۱-۱۲۳۴۵۶۷۸",
+    email: "info@mysite.com",
+    website: "www.mysite.com",
+};
+
+const result = await generatePDFText({
+    text,
+
+    headerTitle: "آموزش برنامه نویسی",
+    headerLogoBase64: "data:image/png;base64,YOUR_COMPLETE_BASE64_IMAGE",
+
+    footerInfo,
+
+    fileName: "programming-report.pdf",
+});
+
+if (result.success) {
+    console.log("PDF generated successfully.");
+} else {
+    console.error(result.message);
+}
+```
+
+### Text Data Rules
+
+- `text` must be a non-empty string.
+- Persian and RTL text are supported.
+- The text is displayed with right alignment and the embedded Vazirmatn font.
+
+---
+
+## 3. generatePDFTextAndTable()
+
+Generates a PDF containing a text section followed by a table.
+
+This template is suitable for reports that require an introduction, description, or summary above tabular information.
+
+### Method Signature
+
+```javascript
+generatePDFTextAndTable({
+    text,
+    columns,
+    tableData,
+    headerTitle,
+    headerLogoBase64,
+    footerInfo,
+    fileName,
+});
+```
+
+### Required Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `text` | `string` | Yes | Text displayed above the table. |
+| `columns` | `string[]` | Yes | Table column names. |
+| `tableData` | `object[]` | Yes | Table rows. |
+
+### Example
+
+```javascript
+import { generatePDFTextAndTable } from "@speresps/pdf-module/client";
+
+const text = "این گزارش شامل اطلاعات اعضای تیم است.";
+
+const columns = [
+    "نام",
+    "سن",
+    "شغل",
+];
+
+const tableData = [
+    {
+        نام: "علی",
+        سن: 30,
+        شغل: "برنامه‌نویس",
+    },
+    {
+        نام: "سارا",
+        سن: 28,
+        شغل: "طراح گرافیک",
+    },
+    {
+        نام: "رضا",
+        سن: 30,
+        شغل: "مدیر پروژه",
+    },
+];
+
+const footerInfo = {
+    siteName: "سایت من",
+    address: "خیابان آزادی، تهران",
+    phone: "۰۲۱-۱۲۳۴۵۶۷۸",
+    email: "info@mysite.com",
+    website: "www.mysite.com",
+};
+
+const result = await generatePDFTextAndTable({
+    text,
+    columns,
+    tableData,
+
+    headerTitle: "گزارش اعضای تیم",
+    headerLogoBase64: "data:image/png;base64,YOUR_COMPLETE_BASE64_IMAGE",
+
+    footerInfo,
+
+    fileName: "team-report.pdf",
+});
+
+if (result.success) {
+    console.log("PDF generated successfully.");
+} else {
+    console.error(result.message);
+}
+```
+
+### Content Layout
+
+The generated document contains:
+
+1. Header with title and optional logo.
+2. Main text section.
+3. Table with column headings and data rows.
+4. Footer with website/contact information and page numbering.
+
+---
+
+## 4. generatePDFTextAndTableWithPagination()
+
+Generates a PDF using externally paginated table data.
+
+This method is designed for data retrieved from APIs or database queries that already return records grouped into pages.
+
+Each item in `paginatedData` represents one table section in the PDF. The method creates a new PDF page before each subsequent item and repeats the supplied text above each table.
+
+### Method Signature
+
+```javascript
+generatePDFTextAndTableWithPagination({
+    text,
+    columns,
+    paginatedData,
+    headerTitle,
+    headerLogoBase64,
+    footerInfo,
+    fileName,
+});
+```
+
+### Required Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `text` | `string` | Yes | Text displayed above each page's table. |
+| `columns` | `string[]` | Yes | Table column names. |
+| `paginatedData` | `object[]` | Yes | Array of page objects, each containing a `data` array. |
+
+### paginatedData Structure
+
+The expected structure is:
+
+```javascript
+const paginatedData = [
+    {
+        page: 1,
+        per_page: 10,
+        total: 28,
+        total_pages: 3,
+        data: [
+            {
+                id: 1,
+                email: "michael@example.com",
+                first_name: "Michael",
+                last_name: "Lawson",
+                address: "My home",
+            },
+            {
+                id: 2,
+                email: "lindsay@example.com",
+                first_name: "Lindsay",
+                last_name: "Ferguson",
+                address: "My home",
+            },
+        ],
+    },
+
+    {
+        page: 2,
+        per_page: 10,
+        total: 28,
+        total_pages: 3,
+        data: [
+            {
+                id: 11,
+                email: "user11@example.com",
+                first_name: "John",
+                last_name: "Smith",
+                address: "My home",
+            },
+        ],
+    },
+
+    {
+        page: 3,
+        per_page: 10,
+        total: 28,
+        total_pages: 3,
+        data: [
+            {
+                id: 21,
+                email: "user21@example.com",
+                first_name: "Jane",
+                last_name: "Doe",
+                address: "My home",
+            },
+        ],
+    },
+];
+```
+
+The `page`, `per_page`, `total`, and `total_pages` properties are useful for preserving the structure of API pagination responses. The PDF template itself uses each page object's `data` array to construct its table.
+
+### Example
+
+```javascript
+import {
+    generatePDFTextAndTableWithPagination,
+} from "@speresps/pdf-module/client";
+
+const text = "این متن در بالای هر صفحه PDF نمایش داده می‌شود.";
+
+const columns = [
+    "id",
+    "email",
+    "first_name",
+    "last_name",
+    "address",
+];
+
+const footerInfo = {
+    siteName: "سایت من",
+    address: "خیابان آزادی، تهران",
+    phone: "۰۲۱-۱۲۳۴۵۶۷۸",
+    email: "info@mysite.com",
+    website: "www.mysite.com",
+};
+
+const result = await generatePDFTextAndTableWithPagination({
+    text,
+    columns,
+    paginatedData,
+
+    headerTitle: "گزارش کاربران",
+    headerLogoBase64: "data:image/png;base64,YOUR_COMPLETE_BASE64_IMAGE",
+
+    footerInfo,
+
+    fileName: "users-report.pdf",
+});
+
+if (result.success) {
+    console.log("Paginated PDF generated successfully.");
+} else {
+    console.error(result.message);
+}
+```
+
+### Pagination Rules
+
+- `text` must be a non-empty string.
+- `columns` must be a non-empty array of strings.
+- `paginatedData` must be a non-empty array.
+- Every pagination item must be an object.
+- Every pagination item must contain a `data` array.
+- Every row in each `data` array must be an object.
+- Column names must correspond to row object keys.
+
+**Important:** This method handles data that is already paginated. It does not automatically request additional pages from an API or divide an arbitrary dataset into fixed-size groups. Each supplied pagination item starts a new PDF page.
+
+---
+
+## 5. downloadPDF()
+
+Downloads an existing PDF file from the configured PDF storage directory.
+
+The method is available through both the server and client entry points, but their behavior differs.
+
+### Client-Side Download
+
+Use the client API in a Next.js client component:
+
+```javascript
+import { downloadPDF } from "@speresps/pdf-module/client";
+
+const handleDownload = async () => {
+    try {
+        const result = await downloadPDF("team-report.pdf");
+
+        if (result.success) {
+            console.log("Download started:", result.fileName);
+        }
+    } catch (error) {
+        console.error("PDF download failed:", error.message);
+    }
+};
+```
+
+Example button:
+
+```jsx
+<button onClick={handleDownload}>
+    Download PDF
+</button>
+```
+
+The client download process:
+
+1. Calls the server-side `getPDFFile()` Server Action.
+2. Reads the PDF file from the configured storage directory.
+3. Converts the file buffer into Base64.
+4. Returns the Base64 data and filename to the browser.
+5. Converts the Base64 data into a `Blob`.
+6. Creates a temporary browser download URL.
+7. Starts the browser download.
+8. Revokes the temporary URL after the download is initiated.
+
+### Server-Side Download / Read / Exists
+
+Use the server API when you need to access the saved file as a Node.js Buffer:
+
+```javascript
+import { downloadPDF } from "@speresps/pdf-module/server";
+
+const result = await downloadPDF("team-report.pdf");
+
+if (result.success) {
+    console.log("File name:", result.fileName);
+    console.log("PDF buffer:", result.buffer);
+}
+```
+
+The server method returns an object containing:
+
+```javascript
+{
+    success: true,
+    fileName: "team-report.pdf",
+    filePath: "/your-project/files/pdf/team-report.pdf",
+    buffer: Buffer
+}
+```
+
+This is a server-side file-reading operation. It does not initiate a browser download.
+
+---
+
+# Header Configuration
+
+Every PDF template supports a customizable header.
+
+The header is configured using:
+
+```javascript
+headerTitle
+headerLogoBase64
+```
+
+### headerTitle
+
+A string displayed as the header title.
+
+Example:
+
+```javascript
+headerTitle: "گزارش اطلاعات کاربران"
+```
+
+If omitted, the module uses its default Persian header title.
+
+### headerLogoBase64
+
+An optional Base64-encoded image.
+
+Example:
+
+```javascript
+headerLogoBase64: "data:image/png;base64,YOUR_COMPLETE_BASE64_IMAGE"
+```
+
+If omitted, the header is generated without a logo.
+
+The header is rendered on PDF pages using the module's shared header template.
+
+---
+
+# Footer Configuration
+
+All PDF templates support a customizable footer through the `footerInfo` object.
+
+### Expected Structure
+
+```javascript
+const footerInfo = {
+    siteName: "سایت من",
+    address: "خیابان آزادی، تهران",
+    phone: "۰۲۱-۱۲۳۴۵۶۷۸",
+    email: "info@mysite.com",
+    website: "www.mysite.com",
+};
+```
+
+### Footer Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `siteName` | `string` | Website or organization name. |
+| `address` | `string` | Organization address. |
+| `phone` | `string` | Contact phone number. |
+| `email` | `string` | Contact email address. |
+| `website` | `string` | Website URL or domain. |
+
+All footer properties are optional.
+
+If `footerInfo` is omitted, default Persian placeholder values are used.
+
+The footer automatically displays the current PDF page and total page count:
+
+```text
+صفحه 1 از 5
+```
+
+The footer is rendered on each PDF page.
+
+---
+
+# Logo Requirements
+
+The `headerLogoBase64` property expects a Base64 image string that can be used directly by `pdfmake-rtl`.
+
+A typical PNG data URL looks like:
+
+```javascript
+const logoBase64 = "data:image/png;base64,BASE64_IMAGE_CONTENT";
+```
+
+You can convert an image into a Base64 data URL using an image-to-Base64 utility.
+
+Pass the complete Base64 string to the generation method:
+
+```javascript
+await generatePDFText({
+    text: "متن نمونه",
+    headerTitle: "عنوان گزارش",
+    headerLogoBase64: logoBase64,
+});
+```
+
+The image is optional. When it is not supplied, the PDF header displays the title without an image.
+
+---
+
+# PDF Generation Examples
+
+The following examples show how to use the four methods in a Next.js client component.
+
+### Example 1: Generate and Download a Table PDF
+
+```javascript
+"use client";
+
+import {
+    generatePDFTable,
+    downloadPDF,
+} from "@speresps/pdf-module/client";
+
+export default function TablePage() {
+
+    const fileName = "team-members.pdf";
+
+    const columns = ["نام", "سن", "شغل"];
+
+    const tableData = [
+        { نام: "علی", سن: 30, شغل: "برنامه‌نویس" },
+        { نام: "سارا", سن: 28, شغل: "طراح گرافیک" },
+    ];
+
+    const handleGenerate = async () => {
+
+        const result = await generatePDFTable({
+            columns,
+            tableData,
+            headerTitle: "لیست اعضای تیم",
+            fileName,
+        });
+
+        if (!result.success) {
+            console.error(result.message);
+            return;
+        }
+
+        console.log("PDF generated successfully.");
+    };
+
+    const handleDownload = async () => {
+        await downloadPDF(fileName);
+    };
+
+    return (
+        <div>
+            <button onClick={handleGenerate}>
+                Generate PDF
+            </button>
+
+            <button onClick={handleDownload}>
+                Download PDF
+            </button>
+        </div>
+    );
+}
+```
+
+### Example 2: Generate and Download a Text PDF
+
+```javascript
+"use client";
+
+import {
+    generatePDFText,
+    downloadPDF,
+} from "@speresps/pdf-module/client";
+
+export default function TextPage() {
+
+    const fileName = "text-report.pdf";
+
+    const handleGenerate = async () => {
+
+        const result = await generatePDFText({
+            text: "این یک متن نمونه فارسی است.",
+            headerTitle: "گزارش متنی",
+            fileName,
+        });
+
+        if (!result.success) {
+            console.error(result.message);
+        }
+    };
+
+    const handleDownload = async () => {
+        await downloadPDF(fileName);
+    };
+
+    return (
+        <div>
+            <button onClick={handleGenerate}>
+                Generate PDF
+            </button>
+
+            <button onClick={handleDownload}>
+                Download PDF
+            </button>
+        </div>
+    );
+}
+```
+
+---
+
+# Server-Side Usage
+
+The module can also be used directly in Node.js server-side code and Next.js server-side modules.
+
+Import the server API:
+
+```javascript
+import {
+    generatePDFTable,
+    generatePDFText,
+    generatePDFTextAndTable,
+    generatePDFTextAndTableWithPagination,
+    downloadPDF,
+} from "@speresps/pdf-module";
+```
+
+Example:
+
+```javascript
+const result = await generatePDFText({
+    text: "Server-side PDF generation example.",
+    headerTitle: "Server Report",
+    fileName: "server-report.pdf",
+});
+
+if (result.success) {
+    console.log("PDF saved:", result.result.fileName);
+} else {
+    console.error("PDF generation failed:", result.message);
+}
+```
+
+The server API generates the PDF and saves it to the configured PDF directory. It does not provide a browser download automatically.
+
+---
+
+# PDF Storage
+
+All generated PDFs are saved to the directory configured through:
+
+```ini
+MAIN_FOLDER_NAME = files
+PDF_FOLDER_NAME = pdf
+```
+
+Default storage location:
+
+```text
+your-project/
+└── files/
+    └── pdf/
+        └── generated-report.pdf
+```
+
+You can change the directory names through `pdf.conf`.
+
+For example:
+
+```ini
+MAIN_FOLDER_NAME = documents
+PDF_FOLDER_NAME = reports
+```
+
+The resulting directory becomes:
+
+```text
+your-project/
+└── documents/
+    └── reports/
+        └── generated-report.pdf
+```
+
+### Custom File Names
+
+You can supply a custom filename to every generation method:
+
+```javascript
+fileName: "monthly-report.pdf"
+```
+
+If `fileName` is omitted, the module uses the corresponding default filename from `pdf.conf`.
+
+PDF filenames must have the `.pdf` extension.
+
+### Important: File Access
+
+The module provides file storage and reading functionality, but it does not implement application-level user authentication or authorization.
+
+Applications that expose PDF downloads must verify that the requesting user is authorized to access the requested file. Do not allow untrusted users to download arbitrary files by supplying filenames.
+
+---
+
+# Return Values and Error Handling
+
+The four PDF generation methods return a Promise resolving to an object.
+
+### Successful Generation
+
+```javascript
+{
+    success: true,
+    result: {
+        success: true,
+        fileName: "report.pdf",
+        filePath: "/your-project/files/pdf/report.pdf"
+    }
+}
+```
+
+### Failed Generation
+
+```javascript
+{
+    success: false,
+    message: "Error description"
+}
+```
+
+The service catches errors during validation, PDF creation, buffer generation, and file storage, and returns an error object.
+
+### Recommended Usage
+
+```javascript
+const result = await generatePDFText({
+    text: "Sample PDF content",
+    headerTitle: "Sample Report",
+    fileName: "sample.pdf",
+});
+
+if (result.success) {
+    console.log("PDF created:", result.result.fileName);
+} else {
+    console.error("PDF generation failed:", result.message);
+}
+```
+
+For file-reading operations, errors such as missing files or invalid filenames are thrown and should be handled with `try/catch`.
+
+```javascript
+try {
+    const result = await downloadPDF("sample.pdf");
+
+    console.log(result.buffer);
+} catch (error) {
+    console.error(error.message);
+}
+```
+
+---
+
+# Important Notes
+
+1. **Configuration is required:** The consuming application must provide `config/pdf.conf` in its project root. The module loads it during initialization.
+
+2. **Dependencies:** The module uses `@speresps/config-module`, `@speresps/report-module`, and `pdfmake-rtl`. These are declared runtime dependencies and are installed through npm.
+
+3. **Node.js environment:** PDF generation and file storage are server-side operations. Do not import the server entry point into browser-only code.
+
+4. **Next.js client usage:** Use `@speresps/pdf-module/client` from client components. Its generation methods communicate with the server through Next.js Server Actions.
+
+5. **Browser downloads:** Generate the PDF first and then call `downloadPDF(fileName)` to download it through the client API.
+
+6. **Unique filenames:** When generating multiple reports, use unique filenames to avoid overwriting existing PDFs.
+
+7. **Pagination:** `generatePDFTextAndTableWithPagination()` expects already-paginated data. Every supplied page object creates a separate PDF page.
+
+8. **Fonts:** Vazirmatn font data is embedded in the module. The consuming project does not need to install or register these fonts separately.
+
+9. **Header and footer:** All four templates support the shared header and footer configuration.
+
+10. **Large PDFs:** The client download implementation transfers PDF content as Base64 through a Server Action. This is convenient for ordinary reports, but very large PDFs may require a streaming or dedicated HTTP download approach.
+
+11. **File authorization:** Protect file-download operations in the consuming application. The module does not provide user-level access control.
+
+12. **Filename configuration:** The default filenames are configured in `pdf.conf`, but each generation method can override its filename using the `fileName` property.
+
+---
+
+# License
+
+MIT
+
+---
+
+## Author
+
+**speresps**