totalum-api-sdk 2.0.41 → 3.0.0

package/README.MD

@@ -1,20 +1,106 @@
-## Totalum api sdk wrapper
+## Totalum API SDK (v3.0.0)
 
-This library wraps the totalum public api, so you can easy call all endpoints.
+Official TypeScript/JavaScript SDK for the Totalum API. This library provides a fully typed, modern interface to interact with all Totalum endpoints.
 
-
-## Installation:
+## Installation
 
 ```bash
 npm i totalum-api-sdk
 ```
 
+## What's New in v3.0
+
+- **Native Fetch**: Removed `axios` dependency, now using native `fetch` API (works in Node.js 18+ and browsers)
+- **Typed Responses**: All methods return strongly-typed `TotalumApiResponse<T>` with proper TypeScript support
+- **Better Error Handling**: Introduced `TotalumError` class for structured error handling
+- **Renamed Methods**: More consistent naming (`getItems` → `getRecords`, `getItemById` → `getRecordById`, etc.)
+- **Improved Type Safety**: Full TypeScript support with detailed response types
+- **No Breaking Changes in API**: Same Totalum API, just better developer experience
+
+## Migration Guide (v2.x → v3.0)
+
+### Breaking Changes
+
+#### 1. Method Names (CRUD Service)
+```javascript
+// v2.x
+await totalumClient.crud.getItemById(table, id);
+await totalumClient.crud.getItems(table, query);
+await totalumClient.crud.createItem(table, data);
+await totalumClient.crud.editItemById(table, id, data);
+await totalumClient.crud.deleteItemById(table, id);
+await totalumClient.crud.addManyToManyReferenceItem(table, id, prop, refId);
+await totalumClient.crud.dropManyToManyReferenceItem(table, id, prop, refId);
+await totalumClient.crud.getManyToManyReferencesItems(table, id, prop, query);
+
+// v3.0
+await totalumClient.crud.getRecordById(table, id);
+await totalumClient.crud.getRecords(table, query);
+await totalumClient.crud.createRecord(table, data);
+await totalumClient.crud.editRecordById(table, id, data);
+await totalumClient.crud.deleteRecordById(table, id);
+await totalumClient.crud.addManyToManyReferenceRecord(table, id, prop, refId);
+await totalumClient.crud.dropManyToManyReferenceRecord(table, id, prop, refId);
+await totalumClient.crud.getManyToManyReferencesRecords(table, id, prop, query);
+```
+
+#### 2. Response Structure
+```javascript
+// v2.x (using axios)
+const result = await totalumClient.crud.getItems(table, {});
+const items = result.data.data;  // Double .data because of axios wrapper
+
+// v3.0 (using fetch)
+const result = await totalumClient.crud.getRecords(table, {});
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+const records = result.data;  // Direct access to data
+```
+
+#### 3. Error Handling
+```javascript
+// v2.x (axios throws errors)
+try {
+    const result = await totalumClient.crud.getItems(table, {});
+    const items = result.data.data;
+} catch (error) {
+    console.error('Error:', error.message);
+}
+
+// v3.0 (errors in response object)
+const result = await totalumClient.crud.getRecords(table, {});
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    console.error('Error Code:', result.errors.errorCode);
+    return;
+}
+const records = result.data;
+```
+
+### Dependencies
+```json
+// v2.x
+{
+  "dependencies": {
+    "axios": "^1.x.x"
+  }
+}
+
+// v3.0 (no dependencies!)
+{
+  "dependencies": {}
+}
+```
+
+**Note:** v3.0 requires Node.js 18+ (for native fetch support). If you're using an older Node.js version, you'll need to polyfill `fetch` or upgrade to Node.js 18+.
 
 # Usage of TotalumApiSdk
 
-Totalum allows you to use the SDK to perform actions such as creating users, creating items, creating pdfs, etc.
+Totalum allows you to use the SDK to perform actions such as creating records, managing files, creating PDFs, sending emails, and more.
 
-Basically the Totalum sdk is a wrapper of the Totalum api, so if you want you can use the api directly if you prefer.
+The SDK is a fully-typed wrapper around the Totalum REST API.
 
 ### What happens if you are not programming in javascript?
 
@@ -22,7 +108,7 @@ If you are not programming in javascript, you can use the api directly, see <a h
 
 ## Authentication
 
-**Note:** If you use totalumSdk inside a totalum plugin, you don't need to authenticate, you can start using totalum like this: modules.totalumSdk.your.function();-> example: modules.totalumSdk.crud.getItems('your_item', {})
+**Note:** If you use totalumSdk inside a totalum plugin, you don't need to authenticate, you can start using totalum like this: modules.totalumSdk.your.function();-> example: modules.totalumSdk.crud.getRecords('your_table', {})
 
 You can choose to use one of the two authentication methods offered by Totalum Sdk:
 
@@ -55,8 +141,8 @@ const options: AuthOptions = {
 const totalumClient = new TotalumApiSdk(options);
 
 // execute some TotalumApiSdk function
-const result = await totalumClient.crud.getItems('your_element_table_name', {});
-    
+const result = await totalumClient.crud.getRecords('your_table_name', {});
+
 ```
 
 **CommonJS Require:**
@@ -84,15 +170,15 @@ const options = {
 const totalumClient = new totalum.TotalumApiSdk(options);
 
 // execute some TotalumApiSdk function
-const result = await totalumClient.crud.getItems('your_element_table_name', {});
-        
+const result = await totalumClient.crud.getRecords('your_table_name', {});
+
 ```
 
 **HTML script import:** (Use this way if you are using standalone html, and you cannot import npm packages)
 
 ```html
 <head>
-    <script src="https://cdn.jsdelivr.net/npm/totalum-api-sdk@2.0.37/dist/totalum-sdk.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/totalum-api-sdk@3.0.0/dist/totalum-sdk.min.js"></script>
 </head>
   <script>
     //Example of use TotalumSdk in your custom html page
@@ -103,42 +189,119 @@ const result = await totalumClient.crud.getItems('your_element_table_name', {});
           }
     });
 
-    const tableElementName = 'your-table-name'; // replace with your table name
+    const tableName = 'your-table-name'; // replace with your table name
 
     //example of endpoint execution
-    const result = totalumClient.crud.getItems(tableElementName, {}).then((result) => {
-      const items = result.data.data;
-      console.log("THE ITEMS", items);
+    totalumClient.crud.getRecords(tableName, {}).then((result) => {
+      if (result.errors) {
+        console.error("ERROR:", result.errors);
+        return;
+      }
+      const records = result.data;
+      console.log("THE RECORDS", records);
     });
-      
+
   </script>
 ```
 
+## Response Structure
 
-## Functions for create, read, filter, update, delete. (CRUD)
+All SDK methods return a `TotalumApiResponse<T>` object with the following structure:
+
+```typescript
+interface TotalumApiResponse<T> {
+    data?: T;              // The successful response data
+    errors?: ErrorResult;  // Error information if request failed
+}
+
+interface ErrorResult {
+    errorCode: string;
+    errorMessage: string;
+    hasManyErrors?: boolean;
+    multipleErrors?: Array<{ errorCode: string; errorMessage: string }>;
+}
+```
+
+**Example:**
+
+```typescript
+const result = await totalumClient.crud.getRecordById('users', 'user-id-123');
 
+// Always check for errors first
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    console.error('Error Code:', result.errors.errorCode);
+    return;
+}
+
+// Now you can safely use result.data
+const user = result.data;
+console.log('User:', user);
+```
+
+## Error Handling
+
+The SDK provides a `TotalumError` class for structured error handling:
+
+```typescript
+import { TotalumError } from 'totalum-api-sdk';
 
-### Get item by id
+const result = await totalumClient.crud.getRecordById('users', 'invalid-id');
 
+if (result.errors) {
+    // You can create a TotalumError for better error handling
+    const error = new TotalumError(result.errors);
+    console.error('Error Code:', error.errorCode);
+    console.error('Error Message:', error.errorMessage);
+
+    // Check for multiple errors
+    if (error.hasManyErrors && error.multipleErrors) {
+        error.multipleErrors.forEach(err => {
+            console.error(`- ${err.errorCode}: ${err.errorMessage}`);
+        });
+    }
+}
+```
+
+## Functions for create, read, filter, update, delete. (CRUD)
+
+
+### Get record by id
 
 ```javascript
 
-// get item by id from your_element_table_name
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item object
-const result = await totalumClient.crud.getItemById(tableElementName, your_item_id);
-const item = result.data.data;
+// Get a single record by id
+const tableName = 'users'; // replace with your table name
+const recordId = 'record-id-123'; // replace with your record id
+
+const result = await totalumClient.crud.getRecordById(tableName, recordId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const record = result.data;
+console.log('Record:', record);
 
 ```
 
-### Get items
+### Get records
 
 ```javascript
 
-// get items from your_element_table_name (for default 50 items per page)
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-const result = await totalumClient.crud.getItems(tableElementName, {});
-const items = result.data.data;
+// Get records from a table (default: first 50 records)
+const tableName = 'users'; // replace with your table name
+
+const result = await totalumClient.crud.getRecords(tableName, {});
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const records = result.data;
+console.log('Records:', records);
 
 ```
 
@@ -305,120 +468,185 @@ const products = result.data.data;
 You can do the same approach to get the orders.
 
 
-### delete item by id
+### Delete record by id
 
 ```javascript
-// delete item by id from your_element_table_name
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item object
-const result = await totalumClient.crud.deleteItemById(tableElementName, your_item_id);
+
+// Delete a record by id
+const tableName = 'users';
+const recordId = 'record-id-123';
+
+const result = await totalumClient.crud.deleteRecordById(tableName, recordId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Deleted count:', result.data.deletedCount);
+console.log('Acknowledged:', result.data.acknowledged);
 
 ```
 
-### edit item by id
+### Edit record by id
 
 ```javascript
-// edit item by id from your_element_table_name, you can edit 1 or multiple properties at the same time (like a patch)
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item object
-const result = await totalumClient.crud.editItemById(tableElementName, your_item_id, {your_item_property: 'new value'});
+
+// Edit a record by id (you can edit one or multiple properties at the same time)
+const tableName = 'users';
+const recordId = 'record-id-123';
+const updates = {
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30
+};
+
+const result = await totalumClient.crud.editRecordById(tableName, recordId, updates);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Modified count:', result.data.modifiedCount);
+console.log('Matched count:', result.data.matchedCount);
 
 ```
 
-### create item
+### Create record
 
 ```javascript
-// create item from your_element_table_name, you need to pass at least the required properties
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-const result = await totalumClient.crud.createItem(tableElementName, {your_item_property: 'new value'});
+
+// Create a new record (you need to pass at least the required properties)
+const tableName = 'users';
+const newRecord = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+    age: 25
+};
+
+const result = await totalumClient.crud.createRecord(tableName, newRecord);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Created record ID:', result.data.insertedId);
+console.log('Acknowledged:', result.data.acknowledged);
 
 ```
 
-### add many to many reference item (add a reference to another item that have a many to many relationship)
+### Add many-to-many reference (add a reference to another record with a many-to-many relationship)
 
 ```javascript
 
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item
-const propertyName = 'your_property_name'; // replace 'your_property_name' with the name of the property that have a many to many relationship
-const referenceId = 'your_reference_item_id'; // replace 'your_reference_item_id' with the id of the item that you want to add as a many to many reference
-const result = await totalumClient.crud.addManyToManyReferenceItem(tableElementName, your_item_id, propertyName, referenceId);
+const tableName = 'students';
+const recordId = 'student-id-123';
+const propertyName = 'courses'; // the property that defines the many-to-many relationship
+const referenceId = 'course-id-456'; // the id of the record to link
+
+const result = await totalumClient.crud.addManyToManyReferenceRecord(tableName, recordId, propertyName, referenceId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Reference added successfully');
 
 ```
 
-### drop many to many reference item (drop a reference to another item that have a many to many relationship)
+### Drop many-to-many reference (remove a reference from a many-to-many relationship)
 
 ```javascript
 
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item
-const propertyName = 'your_property_name'; // replace 'your_property_name' with the name of the property that have a many to many relationship
-const referenceId = 'your_reference_item_id'; // replace 'your_reference_item_id' with the id of the item that you want to drop as a many to many reference
-const result = await totalumClient.crud.dropManyToManyReferenceItem(tableElementName, your_item_id, propertyName, referenceId);
+const tableName = 'students';
+const recordId = 'student-id-123';
+const propertyName = 'courses';
+const referenceId = 'course-id-456'; // the id of the record to unlink
+
+const result = await totalumClient.crud.dropManyToManyReferenceRecord(tableName, recordId, propertyName, referenceId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Reference removed successfully');
 
 ```
 
-### get many to many references items (get all items that have a many to many relationship with the item)
+### Get many-to-many references (get all records with a many-to-many relationship)
 
 ```javascript
 
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
-let your_item_id = 'your_item_id'; // replace 'your_item_id' with the id of the item
-const propertyName = 'your_property_name'; // replace 'your_property_name' with the name of the property that have a many to many relationship
+const tableName = 'students';
+const recordId = 'student-id-123';
+const propertyName = 'courses';
 
-// the query is optional, you can use it to filter and sort the results
+// Optional query for filtering and sorting
 const query = {
     filter: [
         {
-            'your_property_name': 'value' // add your custom filters here
+            'courseName': { regex: 'Math', options: 'i' }
         },
     ],
-    sort:{
-        'your_property_name': 1 // 1 for asc, -1 for desc
+    sort: {
+        'courseName': 1 // 1 for asc, -1 for desc
     },
     pagination: {
         limit: 50,
         page: 0,
     }
 };
-const result = await totalumClient.crud.getManyToManyReferencesItems(tableElementName, your_item_id, propertyName, query);
+
+const result = await totalumClient.crud.getManyToManyReferencesRecords(tableName, recordId, propertyName, query);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const relatedRecords = result.data;
+console.log('Related records:', relatedRecords);
 
 ``` 
 
 
 ## Functions for filter data
 
-### Filter data using totalum AND filter
+### Filter data using AND filter
 
 ```javascript
 
-const tableElementName = 'your_element_table_name'; // replace 'your_element_table_name' with the name of your element table
+const tableName = 'users';
 
-// get items from your_element_table_name (for default 50 items per page) applying a filter AND query (all conditions must be true)
-const filter: FilterSearchQueryI = {
+// Get records applying AND filter (all conditions must be true)
+const filter = {
     filter: [
         {
-            'your_property_name': 'value' // it matches the value exactly
+            'name': 'John' // exact match
         },
         {
-            'your_other_property_name': {regex: 'your regex query', options: 'i'} // it matches a value using a regex query and options: i for case insensitive (ignore if it is uppercase or lowercase)
+            'email': { regex: '@example.com', options: 'i' } // regex with case insensitive
         },
-        // PD: gte and lte operators are only allowed for properties of type date or number
+        // Note: gte and lte operators are only for date or number properties
         {
-            'your_other_property_name': {gte: new Date('your date')} // it matches a value greater than or equal to the date
+            'age': { gte: 18 } // greater than or equal to 18
         },
         {
-            'your_other_property_name': {lte: new Date('your date')} // it matches a value less than or equal to the date
+            'age': { lte: 65 } // less than or equal to 65
         },
         {
-            'your_other_property_name': {gte: 10} // it matches a value greater than or equal to 10
+            'createdAt': { gte: new Date('2024-01-01') } // created after date
         },
         {
-            'your_other_property_name': {lte: 100} // it matches a value less than or equal to 100
+            'createdAt': { lte: new Date('2024-12-31') } // created before date
         }
     ],
-    sort:{
-        'your_property_name': 1 // 1 for asc, -1 for desc
+    sort: {
+        'name': 1 // 1 for ascending, -1 for descending
     },
     pagination: {
         limit: 50,
@@ -426,34 +654,43 @@ const filter: FilterSearchQueryI = {
     }
 };
 
-const result = await totalumClient.crud.getItems(tableElementName, filter);
-const items = result.data.data;
+const result = await totalumClient.crud.getRecords(tableName, filter);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const records = result.data;
+console.log('Filtered records:', records);
 
 ```
 
-### Filter data using totalum OR filter
+### Filter data using OR filter
 
 ```javascript
 
-// get items from your_element_table_name (for default 50 items per page) applying a filter OR query (at least one condition must be true)
-const filter: FilterSearchQueryI = {
+const tableName = 'users';
+
+// Get records applying OR filter (at least one condition must be true)
+const filter = {
     filter: [
         {
             or: [
                 {
-                    'your_property_name': 'value' // it matches the value exactly
+                    'name': 'John'
                 },
                 {
-                    'your_other_property_name': {regex: 'your regex query', options: 'i'} // it matches a value using a regex query and options: i for case insensitive (ignore if it is uppercase or lowercase)
+                    'email': { regex: '@example.com', options: 'i' }
                 },
                 {
-                    'your_other_property_name': {gte: new Date('your date')} // it matches a value greater than or equal to the date
+                    'age': { gte: 18 }
                 },
             ]
         }
     ],
     sort: {
-            'your_property_name': 1 // 1 for asc, -1 for desc
+        'name': 1 // 1 for ascending, -1 for descending
     },
     pagination: {
         limit: 50,
@@ -461,35 +698,43 @@ const filter: FilterSearchQueryI = {
     }
 };
 
-const result = await totalumClient.crud.getItems(tableElementName, filter);
-const items = result.data.data;
+const result = await totalumClient.crud.getRecords(tableName, filter);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const records = result.data;
+console.log('Filtered records:', records);
 
 ```
 
-### Filter data using totalum AND and OR filter
+### Filter data using AND and OR combined
 
 ```javascript
 
-// get items from your_element_table_name (for default 50 items per page) applying a filter OR and AND
-const filter: FilterSearchQueryI = {
+const tableName = 'users';
+
+// Get records applying both OR and AND filters
+const filter = {
     filter: [
         {
             or: [
                 {
-                    'your_property_name_in_or': 'value' // it matches the value exactly
+                    'role': 'admin'
                 },
                 {
-                    'your_other_property_name_in_or': {regex: 'your regex query', options: 'i'} // it matches a value using a regex query and options: i for case insensitive (ignore if it is uppercase or lowercase)
+                    'role': 'moderator'
                 },
             ],
         },
         {
-            'your_other_property_name': 'value' // it matches the value exactly
+            'status': 'active' // AND this condition must be true
         }
-        
     ],
     sort: {
-        'your_property_name': 1 // 1 for asc, -1 for desc
+        'name': 1
     },
     pagination: {
         limit: 50,
@@ -497,27 +742,40 @@ const filter: FilterSearchQueryI = {
     }
 };
 
-const result = await totalumClient.crud.getItems(tableElementName, filter);
-const items = result.data.data;
+const result = await totalumClient.crud.getRecords(tableName, filter);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
 
+const records = result.data;
+console.log('Filtered records:', records);
 
 ```
 
-### Filter using your custom mongoDb aggregation query
+### Filter using custom MongoDB aggregation query
 
 ```javascript
 
-// filter results from your_element_table_name applying a filter query (a custom mongodb aggregation query)
+const tableName = 'users';
+
+// Custom MongoDB aggregation query as string
 const customMongoDbAggregationQueryInString = `
-  
-  your custom mongo aggregation query in string, for more info:
-    https://docs.mongodb.com/manual/aggregation/
 
-    or ask to chatgpt, he is very good writing mongo aggregation queries ;)
+  Your custom MongoDB aggregation query in string format
+  For more info: https://docs.mongodb.com/manual/aggregation/
 
 `;
 
-const result = await totalumClient.filter.runCustomMongoAggregationQuery(tableElementName, customMongoDbAggregationQueryInString);
+const result = await totalumClient.filter.runCustomMongoAggregationQuery(tableName, customMongoDbAggregationQueryInString);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const results = result.data;
 
 ```
 
@@ -525,9 +783,17 @@ const result = await totalumClient.filter.runCustomMongoAggregationQuery(tableEl
 
 ```javascript
 
-const result = await totalumClient.crud.getHistoricRecordUpdatesById(yourRecordId); // replace yourRecordId with the id of the record
+const recordId = 'record-id-123';
+
+const result = await totalumClient.crud.getHistoricRecordUpdatesById(recordId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
 
-const historicUpdates = result.data.data;
+const historicUpdates = result.data;
+console.log('Historic updates:', historicUpdates);
 
 ```
 
@@ -609,11 +875,18 @@ Depending on the platform you are using, you will need to transform the file to
     const FormData = require('form-data'); // if you are using node.js
 
     const fileName = 'your_file_name.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your file
-    const file = yourFileBlob // your blob file created in the previous step 
+    const file = yourFileBlob // your blob file created in the previous step
     const formData = new FormData();
     formData.append('file', file, fileName);
+
     const result = await totalumClient.files.uploadFile(formData);
-    const fileNameId = result.data.data;
+
+    if (result.errors) {
+        console.error('Error:', result.errors.errorMessage);
+        return;
+    }
+
+    const fileNameId = result.data;
 ```
 
 **Using Totalum API**
@@ -638,9 +911,19 @@ Depending on the platform you are using, you will need to transform the file to
 
 ``` javascript
 
-//if you want to link this file to an item, you need to add the fileNameId to the item property of type file
-const result2 = await totalumClient.crud.editItemById('your_element_table_name', 'your_item_id', {'your_file_property_name': {name: fileNameId}});
-// now the file is linked to the item property, and you can see it in the totalum panel.
+// If you want to link this file to a record, you need to add the fileNameId to the record property of type file
+const tableName = 'documents';
+const recordId = 'record-id-123';
+const result2 = await totalumClient.crud.editRecordById(tableName, recordId, {
+    'attachmentFile': { name: fileNameId }
+});
+
+if (result2.errors) {
+    console.error('Error:', result2.errors.errorMessage);
+    return;
+}
+
+console.log('File linked to record successfully');
 
 ```
 
@@ -648,141 +931,365 @@ const result2 = await totalumClient.crud.editItemById('your_element_table_name',
 
 ```javascript
 
-// you can remove a file from totalum using the file name id
-const fileNameId = 'your_file_name.png'; // replace 'your_file_name' with the name id of your file, replace .png with the extension of your file
+// Remove a file from Totalum using the file name id
+const fileNameId = 'your_file_name.png';
 
 const result = await totalumClient.files.deleteFile(fileNameId);
 
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('File deleted successfully');
+
 ```
 
-### Get the download url of a file
+### Get the download URL of a file
 
 ```javascript
 
-// you can get the fileNameId from the result of the upload file function
-const fileNameId = 'your_file_name.png'; // replace 'your_file_name' with the name id of your file, replace .png with the extension of your file
+// Get a signed download URL for a file
+const fileNameId = 'your_file_name.png';
 
-//optional options
+// Optional: set expiration time
 const options = {
-    // the default expiration time is 128 hours, but you can set it to whatever you want, after the expiration time the url will not return the file
-    expirationTime: Date.now() + (128 * 60 * 60 * 1000); // Set to expire in 128 hours, how it works is, set the current date in miliseconds + the miliseconds you want the url to expire
-}
+    // Default expiration is 128 hours. Set custom expiration in milliseconds from now
+    expirationTime: Date.now() + (128 * 60 * 60 * 1000) // 128 hours
+};
 
 const result = await totalumClient.files.getDownloadUrl(fileNameId, options);
-let [fileUrl] = result.data.data;
-// the result will be a full url that you can use to download the file
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const fileUrl = result.data;
+console.log('Download URL:', fileUrl);
 
 ```
 
-### Generate a pdf from a template
+### Generate a PDF from a template
 
 ```javascript
 
-const templateId = 'your_template_id'; // replace 'your_template_id' with the id of your template id, go to totalum  -> configuration -> pdf templates
+// Go to Totalum -> Configuration -> PDF Templates to get your template ID
+const templateId = 'template-id-123';
 
-// the variables will be replaced in your template with handlebars
-const variablesExample = { // replace the variables with your variables, can contain nested objects of n deep, can contain strings, numbers, dates, etc.
-    'your_variable_name': 'your_variable_value',
-    'your_other_variable_name': {
-        'your_other_variable_name': 'your_other_variable_value'
-        'your_other_variable_name': 10,
-        'your_other_variable_name': new Date('your date'),
+// Variables will be replaced in your template using Handlebars
+const variables = {
+    'customerName': 'John Doe',
+    'orderDetails': {
+        'orderId': 'ORD-12345',
+        'amount': 150.50,
+        'date': new Date(),
     },
+};
+
+const fileName = 'invoice_12345.pdf';
+// CAUTION: if you use the same name, the previous PDF will be overwritten
+
+const result = await totalumClient.files.generatePdfByTemplate(templateId, variables, fileName);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
 }
 
-const fileName = 'your_pdf_name.pdf'; // replace 'your_pdf_name' with the name of your pdf
-//CAUTION: if you use the same name for multiple pdfs, the pdfs will be overwritten
-const result = await totalumClient.files.generatePdfByTemplate(templateId, variablesExample, name);
-const fileResult = result.data.data;
-// with the fileUrl you can download the pdf
+const generatedFileName = result.data;
+console.log('PDF generated:', generatedFileName);
 
-//if you want to link this pdf to an item, you need to add the fileName to the item property of type file
-const result2 = await totalumClient.crud.editItemById('your_element_table_name', 'your_item_id', {'your_pdf_property_name': {name: fileResult.fileName}});
+// Link this PDF to a record
+const tableName = 'invoices';
+const recordId = 'invoice-record-123';
+const result2 = await totalumClient.crud.editRecordById(tableName, recordId, {
+    'pdfFile': { name: generatedFileName }
+});
 
 ```
 
-### get OCR of an image (get the text of an image)
+### Get OCR of an image (extract text from image)
 
 ```javascript
 
-// you can only do ocr of a file that is previously uploaded to totalum (see the upload file function)
-// then you can do ocr of the file using the file name of the file uploaded
-const fileNameId = 'your_file_name_id.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your image
+// First upload the image to Totalum, then extract text from it
+const fileNameId = 'uploaded_image.png';
+
 const result = await totalumClient.files.ocrOfImage(fileNameId);
-const ocrResult = result.data.data;
-// ocrResult.text will contain all text of the image
-// ocrResult.fullDetails will contain all details of the image, like the language, the position of the text, etc.
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const ocrResult = result.data;
+console.log('Extracted text:', ocrResult.text);
+console.log('Full details:', ocrResult.fullDetails);
 
 ```
 
-### get OCR of a pdf (get the text of a pdf)
+### Get OCR of a PDF (extract text from PDF)
 
 ```javascript
 
-// you can only do ocr of a file that is previously uploaded to totalum (see the upload file function)
-// then you can do ocr of the file using the file name of the file uploaded
-const fileName = 'your_file_name_id.pdf'; // replace 'your_file_name' with the name of your file
-const result = await totalumClient.files.ocrOfPdf(fileName);
-const ocrResult = result.data.data;
-// ocrResult.text will contain all text of the pdf
-// ocrResult.fullDetails will contain all details of the pdf, like the language, in which page is the text, the position of the text, etc.
+// First upload the PDF to Totalum, then extract text from it
+const fileNameId = 'uploaded_document.pdf';
+
+const result = await totalumClient.files.ocrOfPdf(fileNameId);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const ocrResult = result.data;
+console.log('Extracted text:', ocrResult.text);
+console.log('Full details:', ocrResult.fullDetails);
 
 ```
 
-### scan an invoice (get the details of an invoice)
+### Scan an invoice (extract structured data from invoice)
 
 ```javascript
 
-// you can only do scan of a file that is previously uploaded to totalum (see the upload file function)
-// then you can do scan of the file using the file name of the file uploaded
-const fileName = 'your_file_name.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your file
-const file = yourFileBlob // replace yourFile with your file object binary blob (in blob format)
+// First upload the invoice file to Totalum
+const fileName = 'invoice.png';
+const file = yourFileBlob;
 const formData = new FormData();
 formData.append('file', file, fileName);
-const result = await totalumClient.files.uploadFile(formData);
-const fileNameId = result.data.data;
 
+const uploadResult = await totalumClient.files.uploadFile(formData);
+
+if (uploadResult.errors) {
+    console.error('Error:', uploadResult.errors.errorMessage);
+    return;
+}
+
+const fileNameId = uploadResult.data;
+
+// Scan the invoice to extract structured data
 const result = await totalumClient.files.scanInvoice(fileNameId);
-const invoiceResult = result.data.data;
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const invoiceData = result.data.data;
+const metadata = result.data.metadata;
+
+console.log('Invoice data:', invoiceData);
+console.log('Total amount:', invoiceData.totalAmountIncludingTaxes);
+console.log('Invoice number:', invoiceData.complete_invoice_number);
+console.log('Usage units:', metadata.usageUnits);
 
 ```
 
-### scan a document (get the details of a document)
+### Scan a document (extract custom fields from document)
 
 ```javascript
 
-// first upload the file to totalum
-const fileName = 'your_file_name.png'; // replace 'your_file_name' with the name of your file, replace .png with the extension of your file
-const file = yourFileBlob // replace yourFile with your file object binary blob (in blob format)
+// First upload the document
+const fileName = 'document.png';
+const file = yourFileBlob;
 const formData = new FormData();
 formData.append('file', file, fileName);
-const result = await totalumClient.files.uploadFile(formData);
-const fileNameId = result.data.data;
 
-// define the json properties that you want to extract from the document
-// this is just an example, you can define your own properties following the JSON schema format, the api will return a json with the properties that you define here
-const properties =   {
+const uploadResult = await totalumClient.files.uploadFile(formData);
+
+if (uploadResult.errors) {
+    console.error('Error:', uploadResult.errors.errorMessage);
+    return;
+}
+
+const fileNameId = uploadResult.data;
+
+// Define the JSON schema for properties you want to extract
+const properties = {
     "fecha": {
-      "type": "string",
-      "format": "date",
-      "description": "introduce here your description for help api to extract this value"
+        "type": "string",
+        "format": "date",
+        "description": "The date of the document"
     },
     "import": {
-      "type": "number",
-      "description": "the import"
+        "type": "number",
+        "description": "The total amount"
     },
     "currency": {
-      "type": "string",
-      "enum": ["EUR", "USD", "GBP", "OTHER"],
-      "description": "if currency is not EUR, USD or GBP set OTHER"
+        "type": "string",
+        "enum": ["EUR", "USD", "GBP", "OTHER"],
+        "description": "Currency code"
     }
-}
+};
 
 const result = await totalumClient.files.scanDocument(fileNameId, properties);
-const documentResult = result.data.data;
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const documentData = result.data.data;
+const metadata = result.data.metadata;
+
+console.log('Extracted data:', documentData);
+console.log('OCR text:', metadata.ocrFullResultText);
+console.log('Usage units:', metadata.usageUnits);
+
+```
+
+### Create PDF from HTML
+
+Create a PDF directly from custom HTML:
+
+```javascript
+
+const htmlContent = `
+<html>
+  <body>
+    <h1>Hello World</h1>
+    <p>This is a PDF created from HTML</p>
+  </body>
+</html>
+`;
+
+const fileName = 'my-generated-pdf.pdf';
+
+const result = await totalumClient.files.createPdfFromHtml({
+    html: htmlContent,
+    name: fileName
+});
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const generatedFileName = result.data;
+console.log('PDF generated:', generatedFileName);
+
+// Link this PDF to a record
+const tableName = 'documents';
+const recordId = 'doc-record-123';
+const result2 = await totalumClient.crud.editRecordById(tableName, recordId, {
+    'pdfFile': { name: generatedFileName }
+});
+
+```
+
+**Note:** The HTML is automatically encoded to base64 by the SDK before sending it to the API. Works in both Node.js and browser environments.
+
+
+## Functions for send emails
+
+### Send a basic email
+
+```javascript
+
+const emailPayload = {
+    to: ['recipient@example.com'],
+    subject: 'Your email subject',
+    html: '<h1>Hello</h1><p>This is the email content in HTML</p>',
+};
+
+const result = await totalumClient.email.sendEmail(emailPayload);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Email sent successfully');
+console.log('Message ID:', result.data.messageId);
 
 ```
 
+### Send an email with all options
+
+```javascript
+
+const emailPayload = {
+    to: ['recipient1@example.com', 'recipient2@example.com'], // array of recipients
+    subject: 'Your email subject',
+    html: '<h1>Hello</h1><p>This is the email content in HTML</p>',
+    fromName: 'Your Company Name', // optional: custom sender name
+    cc: ['cc@example.com'], // optional: carbon copy recipients
+    bcc: ['bcc@example.com'], // optional: blind carbon copy recipients
+    replyTo: 'reply@example.com', // optional: reply-to address
+    attachments: [ // optional: array of attachments (max 10, each up to 15MB)
+        {
+            filename: 'document.pdf',
+            url: 'https://example.com/path/to/document.pdf',
+            contentType: 'application/pdf' // optional
+        },
+        {
+            filename: 'image.png',
+            url: 'https://example.com/path/to/image.png',
+            contentType: 'image/png' // optional
+        }
+    ]
+};
+
+const result = await totalumClient.email.sendEmail(emailPayload);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Email sent successfully');
+console.log('Message ID:', result.data.messageId);
+
+```
+
+### Send an email with files from Totalum storage
+
+```javascript
+
+// First, get the download URL of the file uploaded to Totalum
+const fileNameId = 'your_file_name.pdf';
+
+const fileUrlResult = await totalumClient.files.getDownloadUrl(fileNameId);
+
+if (fileUrlResult.errors) {
+    console.error('Error:', fileUrlResult.errors.errorMessage);
+    return;
+}
+
+const fileUrl = fileUrlResult.data;
+
+// Then, send the email with the attachment
+const emailPayload = {
+    to: ['recipient@example.com'],
+    subject: 'Email with attachment from Totalum',
+    html: '<h1>Hello</h1><p>Please find the attached document</p>',
+    attachments: [
+        {
+            filename: 'document.pdf',
+            url: fileUrl,
+            contentType: 'application/pdf'
+        }
+    ]
+};
+
+const result = await totalumClient.email.sendEmail(emailPayload);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+console.log('Email sent successfully');
+
+```
+
+**Important notes:**
+- Maximum attachments: 10 per email
+- Maximum size per attachment: 15MB
+- All attachments must be provided as valid HTTP/HTTPS URLs
+- The SDK validates attachments before sending
+
 
 ## Functions for call OpenAI API without need to have an OpenAI account
 
@@ -791,15 +1298,22 @@ const documentResult = result.data.data;
 
 ```javascript
 
-//body the openai completion body, more info here: https://platform.openai.com/docs/api-reference/completions/create
-const body={
-    // see the openai api docs for more info
-}
+// See OpenAI API docs: https://platform.openai.com/docs/api-reference/completions/create
+const body = {
+    model: 'gpt-3.5-turbo-instruct',
+    prompt: 'Say hello in Spanish',
+    max_tokens: 50
+};
 
 const result = await totalumClient.openai.createCompletion(body);
-const gptCompletion = result.data.data;
 
-// returns the completion provided by openai api 
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
+}
+
+const completion = result.data;
+console.log('Completion:', completion);
 
 ```
 
@@ -807,21 +1321,26 @@ const gptCompletion = result.data.data;
 
 ```javascript
 
-//body the openai chat completion body, more info here:  https://platform.openai.com/docs/api-reference/chat/create
-const bodyExample={
-    // see the openai api docs for more info
+// See OpenAI API docs: https://platform.openai.com/docs/api-reference/chat/create
+const body = {
     messages: [
-        {content: 'You are a math specialist assistant', role: 'system'},
-        {content: 'how I can resolve a matrix', role: 'user'}
-        //etc...
+        { content: 'You are a math specialist assistant', role: 'system' },
+        { content: 'How do I solve a matrix?', role: 'user' }
     ],
     model: 'gpt-3.5-turbo',
-    max_tokens: 30,
+    max_tokens: 150,
+};
+
+const result = await totalumClient.openai.createChatCompletion(body);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
 }
 
-const result = await totalumClient.openai.createChatCompletion(bodyExample);
-const chatCompletion = result.data.data;
-// returns the completion provided by openai api 
+const chatCompletion = result.data;
+console.log('Response:', chatCompletion.choices[0].message.content);
+console.log('Tokens used:', chatCompletion.usage.total_tokens);
 
 ```
 
@@ -829,16 +1348,28 @@ const chatCompletion = result.data.data;
 
 ```javascript
 
-//body the openai chat completion body, more info here:  https://platform.openai.com/docs/api-reference/chat/create
-const bodyExample={
-    prompt:'your prompt',
-    size: '256x256' | '512x512' | '1024x1024',
-    fileName: 'file-name-of-file-saved.png' // CAUTION: if you use the same name for multiple images, the images will be overwritten
+// See OpenAI API docs: https://platform.openai.com/docs/api-reference/images
+const body = {
+    prompt: 'A beautiful sunset over the mountains',
+    size: '1024x1024', // '256x256' | '512x512' | '1024x1024'
+    fileName: 'sunset_image.png' // CAUTION: reusing names will overwrite files
+};
+
+const result = await totalumClient.openai.generateImage(body);
+
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
 }
 
-const result = await totalumClient.openai.generateImage(bodyExample);
-const imageCompletion = result.data.data;
-// returns the file name with the file generated by openai, if is not an url, you can download it using files.getDownloadUrl(imageCompletion);
+const imageFileName = result.data;
+console.log('Image generated:', imageFileName);
+
+// Get download URL to view/download the image
+const urlResult = await totalumClient.files.getDownloadUrl(imageFileName);
+if (!urlResult.errors) {
+    console.log('Image URL:', urlResult.data);
+}
 
 ```