Merge pull request #4 from UniversityOfNicosia/feature/npm-package

Introduce NPM Package Functionality and Enhancements to Document Conversion API

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-azuretools.vscode-docker",
+                "github.vscode-github-actions",
+                "mhutchie.git-graph"
+            ]
+        }
+    }
+  }
+

.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish NPM Package
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@universityofnicosia'
+      - run: npm install
+        working-directory: officegen-api/
+      - run: npm publish
+        working-directory: officegen-api/
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

officegen-api/README.md

@@ -1,51 +1,89 @@
-# Officegen API
+# Officegen API and Library for Document Conversion
 
-This directory contains a Node.js API for document conversion using the officegen library. The API supports creating `.docx` documents with structured elements and custom styles.
+The Officegen API and Library offer a powerful way to generate `.docx` documents from structured JSON inputs. This guide provides an overview of both the API and the Node.js library usage.
 
 ## Features
 
-- Create `.docx` documents with a variety of elements (text, titles, subtitles, lists, bullets, footnotes).
-- Apply custom styles to document elements (font family, size, color).
+- Generate `.docx` documents with custom text, titles, subtitles, lists, bullets, and footnotes.
+- Easy integration into JavaScript and Node.js projects.
+- Flexible document structure and styling.
 
-## Setting Up the Development Environment
+## Getting Started
 
-### Prerequisites
+### API Usage
 
-- Node.js (v12.x or higher recommended)
-- npm (usually comes with Node.js)
+To create a document using the API, send a POST request to `/api/create-document` with your document structure and style defined in JSON.
 
-### Installing Dependencies
+**Example Request:**
 
-After navigating to the `officegen-api` directory, install the necessary dependencies using npm:
+```json
+POST /api/create-document
+Content-Type: application/json
 
-```shell
-npm install
+{
+  "elements": [
+    {"type": "title", "text": "Document Title"},
+    ...
+  ],
+  "styles": {
+    "textColor": "#000000",
+    "fontFamily": {
+      "title": "Arial",
+      ...
+    }
+  }
+}
 ```
 
-## Running the API
+**Response:**
 
-To start the API server, run:
+The API responds with the path to the created document upon success.
 
-```shell
-npm start
+```json
+{
+  "message": "Document created successfully",
+  "path": "examples/document_123456789.docx"
+}
 ```
 
-Access the API at `http://localhost:3000/api/create-document`.
+### Library Usage
 
-## Using the API
+The UNIC Document Conversion Library enables creation of documents via a Node.js module. Install the library from GitHub Packages, configure your `.npmrc` for authentication, and use the library in your projects.
 
-### Creating a Document
+**Installation:**
 
-Send a POST request to `/api/create-document` with `documentElements` and `documentStyles` in the JSON body.
+```bash
+npm install @universityofnicosia/unic-document-conversion-library --save
+```
+
+**Example Usage:**
+
+```javascript
+const documentLibrary = require('@universityofnicosia/unic-document-conversion-library');
 
-Example request using `curl`:
+const inputJson = {
+  "elements": [...],
+  "styles": {...}
+};
 
-```shell
-curl -X POST http://localhost:3000/api/create-document \
-     -H "Content-Type: application/json" \
-     -d '{"documentElements": [{"type": "title", "text": "Hello World"}], "documentStyles": {"fontFamily": {"title": "Arial"}}}'
+documentLibrary.createDocumentWithStructure(inputJson)
+  .then((path) => console.log(`Document created at: ${path}`))
+  .catch((error) => console.error('Error creating document:', error));
 ```
 
+## Prerequisites
+
+- Node.js (v12.x or higher)
+- npm
+
+## Documentation
+
+For more detailed examples and error handling, please refer to the `api-usage.md` and `library-usage.md` files in the `examples` directory.
+
 ## Contributing
 
-Contributions are welcome! Please refer to the main repository's CONTRIBUTING.md file for guidelines.
+Contributions are welcome! If you have suggestions or encounter issues, please file a report in the issues section.
+
+## License
+
+This project is provided under the [MIT License](https://opensource.org/licenses/MIT).

officegen-api/examples/usage.md → officegen-api/examples/api-usage.md

@@ -1,4 +1,4 @@
-# Officegen API Usage Examples
+# UNIC Document Conversion API - Usage Guide
 
 This document provides examples of how to use the Officegen API to create `.docx` documents with custom text. Future updates will include more complex document structures and styles.
 
@@ -14,7 +14,8 @@ Content-Type: application/json
 
 ```json
 {
-  "documentElements": [
+  "elements": 
+  [
     {
       "type": "title",
       "text": "Document Title"
@@ -48,16 +49,16 @@ Content-Type: application/json
       "text": "This is document footnotes"
     }
   ],
-    "documentStyles": 
+  "styles": 
+  {
+    "textColor": "#000000",
+    "fontFamily": 
     {
-      "textColor": "#000000",
-      "fontFamily": 
-      {
-        "title": "Arial",
-        "subtitle": "Times New Roman",
-        "body": "Calibri"
-      }
+      "title": "Arial",
+      "subtitle": "Times New Roman",
+      "body": "Calibri"
     }
+  }
 }
 ```
 
@@ -89,13 +90,3 @@ If the request fails due to missing text or other issues, the API will respond w
 ```
 
 Status code: 400
-
-## Future Enhancements
-
-Future versions of the API will support:
-
-- Complex document structures (titles, subtitles, lists, bullets, footnotes, etc.)
-- Styling options (background color, text color, font, etc.)
-- Direct document download links or streaming
-
-Stay tuned for updates and additional features!

officegen-api/examples/library-usage.md

@@ -0,0 +1,89 @@
+# UNIC Document Conversion Library - Usage Guide
+
+## Introduction
+
+The UNIC Document Conversion Library is a powerful Node.js module that enables the creation of `.docx` documents from structured JSON inputs. Built on top of the `officegen` library, it offers a flexible way to generate documents with custom styles and various elements such as text, titles, subtitles, lists, bullets, and footnotes.
+
+This guide covers the process of setting up, installing, and using this private NPM package within your projects.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+- Node.js (v12.x or higher recommended)
+- npm (usually comes with Node.js)
+
+## Installation
+
+Since this package is hosted on the GitHub Packages registry associated with the UniversityOfNicosia organization, you'll need to authenticate to GitHub Packages to install the library. Configure your project to use GitHub Packages:
+
+1. Create or edit the `.npmrc` file in your project's root directory to include the following line:
+   ```
+   @universityofnicosia:registry=https://npm.pkg.github.com
+   ```
+2. Authenticate to GitHub Packages. You can use a personal access token (PAT) with read:packages permission. Configure the token in your global `~/.npmrc` file (not the project's `.npmrc` to avoid committing sensitive information):
+   ```
+   //npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
+   ```
+3. Install the package using npm:
+   ```bash
+   npm install @universityofnicosia/unic-document-conversion-library --save
+   ```
+
+## Setting Up Your Project
+
+1. **Create a new Node.js project** (if you haven't already) by running `npm init` in your project directory and following the prompts.
+
+2. **Install the UNIC Document Conversion Library** using the command provided in the Installation section above.
+
+## Usage
+
+To use the library, you need to import it into your Node.js application, configure your document structure and styles in JSON format, and call the library function to create a document.
+
+### Basic Example
+
+Here's a basic example of how to use the library:
+
+```javascript
+const documentLibrary = require('@universityofnicosia/unic-document-conversion-library');
+
+// Define your document structure and styles
+const inputJson = {
+  elements: [
+    { type: 'title', text: 'Document Title' },
+    { type: 'subtitle', text: 'Subtitle Here' },
+    { type: 'paragraph', text: 'This is a simple paragraph.' },
+    {
+      type: 'list',
+      items: ['First item', 'Second item', 'Third item']
+    }
+  ],
+  styles: {
+    fontFamily: {
+      title: 'Arial',
+      body: 'Calibri'
+    },
+    textColor: '#000000'
+  }
+};
+
+// Create the document
+documentLibrary.createDocumentWithStructure(inputJson)
+  .then((path) => console.log(`Document created at: ${path}`))
+  .catch((error) => console.error('Error creating document:', error));
+```
+
+### Error Handling
+
+The library provides error handling mechanisms. Ensure your application properly catches and handles these errors, especially for invalid inputs or issues during document generation.
+
+## Advanced Usage
+
+For more complex documents, refer to the `officegen` documentation to understand all supported elements and styles. The UNIC Document Conversion Library supports these features as part of the `inputJson` configuration.
+
+## Contributing
+
+We welcome contributions! If you have suggestions for improvements or encounter any issues, please file a report in the repository's issues section.
+
+## License
+
+This library is provided under the [MIT License](https://opensource.org/licenses/MIT). Please review the license terms before using or contributing to the project.

officegen-api/package.json

@@ -1,17 +1,21 @@
 {
-  "name": "officegen-api",
-  "version": "1.0.0",
-  "description": "API for document conversion using officegen",
-  "main": "src/app.js",
+  "name": "@universityofnicosia/unic-document-conversion-library",
+  "version": "1.0.6",
+  "description": "A library and API for document conversion using officegen",
+  "main": "src/documentLibrary.js",
   "scripts": {
     "start": "node src/app.js",
     "test": "jest"
   },
   "dependencies": {
     "express": "^4.19.2",
-    "officegen": "^0.6.5"
+    "officegen": "^0.6.5",
+    "stream-buffers": "^3.0.2"
   },
   "devDependencies": {
     "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/@universityofnicosia"
   }
 }