npm - totalum-api-sdk - Versions diffs - 3.0.5 → 3.0.7 - Mend

totalum-api-sdk 3.0.5 → 3.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.MD +122 -285
package/dist/common/endpoints.d.ts +8 -0
package/dist/common/endpoints.js +8 -0
package/dist/common/interfaces.d.ts +79 -0
package/dist/common/response-types.d.ts +1 -0
package/dist/index.d.ts +3 -0
package/dist/index.js +2 -0
package/dist/services/CrudService.d.ts +38 -2
package/dist/services/CrudService.js +63 -1
package/dist/services/FilesService.d.ts +2 -2
package/dist/services/FilesService.js +1 -1
package/dist/services/FilterService.d.ts +1 -0
package/dist/services/FilterService.js +1 -0
package/dist/services/OpenaiService.d.ts +40 -8
package/dist/services/OpenaiService.js +29 -5
package/dist/services/ScrappingService.d.ts +153 -0
package/dist/services/ScrappingService.js +68 -0
package/dist/totalum-sdk.min.js +1 -1
package/package.json +6 -1
package/dist/test-all-endpoints.d.ts +0 -1
package/dist/test-all-endpoints.js +0 -686

package/README.MD CHANGED Viewed

@@ -1,4 +1,4 @@
-## Totalum API SDK (v3.0.5)
+## Totalum API SDK
 Official TypeScript/JavaScript SDK for the Totalum API. This library provides a fully typed, modern interface to interact with all Totalum endpoints.
@@ -8,16 +8,6 @@ Official TypeScript/JavaScript SDK for the Totalum API. This library provides a
 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
 **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
@@ -32,7 +22,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.getRecords('your_table', {})
+**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.query('your_table')
 You can choose to use one of the two authentication methods offered by Totalum Sdk:
@@ -65,7 +55,7 @@ const options: AuthOptions = {
 const totalumClient = new TotalumApiSdk(options);
 // execute some TotalumApiSdk function
-const result = await totalumClient.crud.getRecords('your_table_name', {});
+const result = await totalumClient.crud.query('your_table_name');
 ```
@@ -94,7 +84,7 @@ const options = {
 const totalumClient = new totalum.TotalumApiSdk(options);
 // execute some TotalumApiSdk function
-const result = await totalumClient.crud.getRecords('your_table_name', {});
+const result = await totalumClient.crud.query('your_table_name');
 ```
@@ -102,7 +92,7 @@ const result = await totalumClient.crud.getRecords('your_table_name', {});
 ```html
 <head>
-    <script src="https://cdn.jsdelivr.net/npm/totalum-api-sdk@3.0.2/dist/totalum-sdk.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/totalum-api-sdk@3.0.7/dist/totalum-sdk.min.js"></script>
 </head>
   <script>
     //Example of use TotalumSdk in your custom html page
@@ -116,7 +106,7 @@ const result = await totalumClient.crud.getRecords('your_table_name', {});
     const tableName = 'your-table-name'; // replace with your table name
     //example of endpoint execution
-    totalumClient.crud.getRecords(tableName, {}).then((result) => {
+    totalumClient.crud.query(tableName).then((result) => {
       if (result.errors) {
         console.error("ERROR:", result.errors);
         return;
@@ -210,14 +200,14 @@ console.log('Record:', record);
 ```
-### Get records
+### Query records (Recommended)
+`totalumClient.crud.query()` is the **recommended** method for reading data. It replaces `getRecords`, `getNestedData`, and `getManyToManyReferencesRecords`.
 ```javascript
 // Get records from a table (default: first 50 records)
-const tableName = 'users'; // replace with your table name
-const result = await totalumClient.crud.getRecords(tableName, {});
+const result = await totalumClient.crud.query('users');
 if (result.errors) {
     console.error('Error:', result.errors.errorMessage);
@@ -229,168 +219,80 @@ console.log('Records:', records);
 ```
-### Get nested items
+### Query with nested relations
 ```javascript
-// imagine that you have 3 tables, client, order and product, and you want to get some clients with all orders and the products of the orders
-const nestedQuery: NestedQuery = {
-    client: {
-        order: {
-            product: {}
-        },
+// Get clients with all orders and the products of each order
+const result = await totalumClient.crud.query('client', {
+    order: {
+        product: true
     }
-}
+});
-const result = await totalumClient.crud.getNestedData(nestedQuery);
+const clients = result.data;
 ```
-### Get nested items and filter
+### Query with filters, sort, and pagination
 ```javascript
-// As before you have client, order, and product tables, but you now want to only get the client with name 'Jhon' and limit to 10 results
-const nestedQuery: NestedQuery = {
-    client: {
-        tableFilter: {
-            filter: [{
-              name: 'Jhon'
-            }],
-            sort: {
-              name: 1
-            },
-            pagination: {
-              limit: 10,
-              page: 0,
-            }
-        },
-        order: {
-            product: {}
-        },
-    }
-}
-// if you want you can filter to all other nested tables in the same way (adding tableFilter property to the nested table)
-const result = await totalumClient.crud.getNestedData(nestedQuery);
+// Get clients named 'John', sorted by name, limited to 10 results
+const result = await totalumClient.crud.query('client', {
+    _filter: { name: 'John' },
+    _sort: { name: 'asc' },
+    _limit: 10
+});
 ```
-### Nested Filter
-get table items by Filtering others related tables. (like a join filter in sql)
-**The difference between getNestedData and nestedFilter is that nestedFilter only gets the items of the table that you specify in the tableNameToGet parameter that matches the nested filter.**
-**Use Case:**
-Imagine you have 3 tables, `client`, `order` and `product`, and you want to get the clients that have an order with state equal to completed and that order_date is from 2021-01-01 to 2021-01-31, and that order must have a product with a product with the name `Cocacola`. And you to get only the first 50 clients that match the filter.
+### Query with OR conditions
 ```javascript
-// you can filter in all tables for all the properties of the table if you want, in this example we are filtering only the order and product tables
-const nestedFilter = {
-    client: {
-        order: {
-            tableFilter: [
-                {
-                    state: 'completed'
-                },
-                {
-                    order_date: {
-                        gte: new Date('2021-01-01'),
-                    }
-                },
-                {
-                    order_date: {
-                        lte: new Date('2021-01-31')
-                    }
-                }
-            ],
-            product: {
-                tableFilter: [
-                    {
-                        name: 'Cocacola'
-                    }
-                ]
-            }
-        },
+const result = await totalumClient.crud.query('users', {
+    _filter: {
+        _or: [
+            { role: 'admin' },
+            { role: 'moderator' }
+        ]
     }
-}
-const filterOptions = {
-      pagination: {
-        limit: 60,
-        page: 0
-      },
-      sort: {
-        // you can sort by any field of contact, for example, sort by email
-        email: -1
-      }
-};
-// the table name to get the data that matches the filter
-const tableNameToGet = 'client';
-const result = await totalumClient.filter.nestedFilter(nestedFilter, tableNameToGet, filterOptions);
-const clients = result.data;
+});
 ```
-**Another use case:**
-You can also get the tables that are not in top.
-Imagine you have 3 tables, `client`, `order` and `product`, and you want to get the products that have an order with state equal to completed, and that order must have a client with the name `Jhon`. And you to get only the first 50 products that match the filter.
+### Query with nested filters and counts
 ```javascript
-const nestedFilter = {
-    client: {
-        tableFilter: [
-            {
-                name: 'Jhon'
-            }
-        ],
-        order: {
-            tableFilter: [
-                {
-                    state: 'completed'
-                }
-            ],
-            product: {}
-        },
+// Get companies with active employees, count them, sort by name
+const result = await totalumClient.crud.query('company', {
+    _filter: { country: 'Spain' },
+    _sort: { name: 'asc' },
+    _limit: 10,
+    employee: {
+        _filter: { status: 'active' },
+        _has: true,
+        _count: true,
+        task: { _sort: { createdAt: 'desc' }, _limit: 5 }
     }
-}
+});
-const filterOptions = {
-      pagination: {
-        limit: 60,
-        page: 0
-      },
-      sort: {
-        // you can sort by any field of product
-        name: -1
-      }
-};
+```
-// the table name to get the data that matches the filter
-const tableNameToGet = 'product';
+### Query manyToMany relations
-const result = await totalumClient.filter.nestedFilter(nestedFilter, tableNameToGet, filterOptions);
+```javascript
-const products = result.data;
+// Get students with their courses (manyToMany)
+const result = await totalumClient.crud.query('students', {
+    courses: true
+});
 ```
-You can do the same approach to get the orders.
+For full query documentation see: [Read and Filter Data](https://docs.totalum.app/docs/api/filtrarDatos)
 ### Delete record by id
@@ -507,84 +409,30 @@ console.log('Reference removed successfully');
 ```
-### Get many-to-many references (get all records with a many-to-many relationship)
+### Get many-to-many references
-```javascript
-const tableName = 'students';
-const recordId = 'student-id-123';
-const propertyName = 'courses';
-// Optional query for filtering and sorting
-const query = {
-    filter: [
-        {
-            'courseName': { regex: 'Math', options: 'i' }
-        },
-    ],
-    sort: {
-        'courseName': 1 // 1 for asc, -1 for desc
-    },
-    pagination: {
-        limit: 50,
-        page: 0,
-    }
-};
-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);
-```
+> **Note:** For reading manyToMany data, prefer using `totalumClient.crud.query()` with the relation property expanded (see "Query manyToMany relations" above).
 ## Functions for filter data
+> **Note:** All filtering examples below use `totalumClient.crud.query()`, the recommended method. See "Query records" section above for more details.
 ### Filter data using AND filter
 ```javascript
-const tableName = 'users';
 // Get records applying AND filter (all conditions must be true)
-const filter = {
-    filter: [
-        {
-            'name': 'John' // exact match
-        },
-        {
-            'email': { regex: '@example.com', options: 'i' } // regex with case insensitive
-        },
-        // Note: gte and lte operators are only for date or number properties
-        {
-            'age': { gte: 18 } // greater than or equal to 18
-        },
-        {
-            'age': { lte: 65 } // less than or equal to 65
-        },
-        {
-            'createdAt': { gte: new Date('2024-01-01') } // created after date
-        },
-        {
-            'createdAt': { lte: new Date('2024-12-31') } // created before date
-        }
-    ],
-    sort: {
-        'name': 1 // 1 for ascending, -1 for descending
+const result = await totalumClient.crud.query('users', {
+    _filter: {
+        name: 'John',
+        email: { regex: '@example.com', options: 'i' },
+        age: { gte: 18, lte: 65 },
+        createdAt: { gte: new Date('2024-01-01'), lte: new Date('2024-12-31') }
     },
-    pagination: {
-        limit: 50,
-        page: 0,
-    }
-};
-const result = await totalumClient.crud.getRecords(tableName, filter);
+    _sort: { name: 'asc' },
+    _limit: 50
+});
 if (result.errors) {
     console.error('Error:', result.errors.errorMessage);
@@ -600,35 +448,18 @@ console.log('Filtered records:', records);
 ```javascript
-const tableName = 'users';
 // Get records applying OR filter (at least one condition must be true)
-const filter = {
-    filter: [
-        {
-            or: [
-                {
-                    'name': 'John'
-                },
-                {
-                    'email': { regex: '@example.com', options: 'i' }
-                },
-                {
-                    'age': { gte: 18 }
-                },
-            ]
-        }
-    ],
-    sort: {
-        'name': 1 // 1 for ascending, -1 for descending
+const result = await totalumClient.crud.query('users', {
+    _filter: {
+        _or: [
+            { name: 'John' },
+            { email: { regex: '@example.com', options: 'i' } },
+            { age: { gte: 18 } }
+        ]
     },
-    pagination: {
-        limit: 50,
-        page: 0,
-    }
-};
-const result = await totalumClient.crud.getRecords(tableName, filter);
+    _sort: { name: 'asc' },
+    _limit: 50
+});
 if (result.errors) {
     console.error('Error:', result.errors.errorMessage);
@@ -644,35 +475,18 @@ console.log('Filtered records:', records);
 ```javascript
-const tableName = 'users';
 // Get records applying both OR and AND filters
-const filter = {
-    filter: [
-        {
-            or: [
-                {
-                    'role': 'admin'
-                },
-                {
-                    'role': 'moderator'
-                },
-            ],
-        },
-        {
-            'status': 'active' // AND this condition must be true
-        }
-    ],
-    sort: {
-        'name': 1
+const result = await totalumClient.crud.query('users', {
+    _filter: {
+        _or: [
+            { role: 'admin' },
+            { role: 'moderator' }
+        ],
+        status: 'active' // AND this condition must be true
     },
-    pagination: {
-        limit: 50,
-        page: 0,
-    }
-};
-const result = await totalumClient.crud.getRecords(tableName, filter);
+    _sort: { name: 'asc' },
+    _limit: 50
+});
 if (result.errors) {
     console.error('Error:', result.errors.errorMessage);
@@ -895,7 +709,8 @@ if (result.errors) {
     return;
 }
-const fileUrl = result.data;
+// result.data is an array like ["https://..."], extract the URL:
+const fileUrl = result.data[0];
 console.log('Download URL:', fileUrl);
 ```
@@ -1278,28 +1093,50 @@ console.log('Tokens used:', chatCompletion.usage.total_tokens);
 ```javascript
-// See OpenAI API docs: https://platform.openai.com/docs/api-reference/images
-const body = {
+const result = await totalumClient.openai.generateImage({
     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);
+    fileName: 'sunset_image',
+    size: '1024x1024',       // optional: '1024x1024', '1536x1024' (landscape), '1024x1536' (portrait), 'auto'
+    quality: 'low',          // optional: 'low' (fastest), 'medium', 'high', 'auto'
+    output_format: 'png',    // optional: 'png', 'jpeg', 'webp'
+    background: 'auto'       // optional: 'transparent' (requires png), 'opaque', 'auto'
+});
 if (result.errors) {
     console.error('Error:', result.errors.errorMessage);
     return;
 }
-const imageFileName = result.data;
-console.log('Image generated:', imageFileName);
+const { fileName, imageUrl } = result.data;
+console.log('Image file:', fileName);
+console.log('Image URL:', imageUrl); // signed URL to directly access the image
+```
+### Edit an image
-// Get download URL to view/download the image
-const urlResult = await totalumClient.files.getDownloadUrl(imageFileName);
-if (!urlResult.errors) {
-    console.log('Image URL:', urlResult.data);
+Edit or transform existing images: change clothes, combine images, use as style reference, etc.
+```javascript
+const result = await totalumClient.openai.editImage({
+    prompt: 'Change ONLY the clothing to a blue suit. Keep the face and background the same.',
+    imageUrls: ['https://example.com/photo.jpg'],  // 1-16 image URLs
+    fileName: 'edited-photo',
+    input_fidelity: 'high',   // 'high' preserves details (faces). 'low' allows creative freedom (style transfer).
+    size: '1024x1024',        // optional
+    quality: 'low',           // optional
+    output_format: 'png'      // optional
+});
+if (result.errors) {
+    console.error('Error:', result.errors.errorMessage);
+    return;
 }
+const { fileName, imageUrl } = result.data;
+console.log('Edited image:', fileName);
+console.log('Image URL:', imageUrl);
 ```

package/dist/common/endpoints.d.ts CHANGED Viewed

@@ -3,6 +3,7 @@ export declare const endpoints: {
         getObjectById: string;
         getObjects: string;
         getNestedData: string;
+        query: string;
         createObject: string;
         editObjectProperties: string;
         deleteObject: string;
@@ -43,6 +44,7 @@ export declare const endpoints: {
         createCompletion: string;
         createChatCompletion: string;
         generateImage: string;
+        editImage: string;
     };
     notifications: {
         createNotification: string;
@@ -53,4 +55,10 @@ export declare const endpoints: {
     email: {
         sendEmail: string;
     };
+    webScraper: {
+        scrape: string;
+        extract: string;
+        screenshot: string;
+        searchAndExtract: string;
+    };
 };

package/dist/common/endpoints.js CHANGED Viewed

@@ -7,6 +7,7 @@ exports.endpoints = {
         getObjectById: 'api/v1/crud/:typeId/:id',
         getObjects: 'api/v1/crud/query/:typeId',
         getNestedData: 'api/v1/crud/nested',
+        query: 'api/v1/crud/advanced-query',
         createObject: 'api/v1/crud/:typeId',
         editObjectProperties: 'api/v1/crud/:typeId/:id',
         deleteObject: 'api/v1/crud/:typeId/:id',
@@ -47,6 +48,7 @@ exports.endpoints = {
         createCompletion: 'api/v1/openai/completion',
         createChatCompletion: 'api/v1/openai/chat-completion',
         generateImage: 'api/v1/openai/image',
+        editImage: 'api/v1/openai/image-edit',
     },
     notifications: {
         createNotification: 'api/v1/notifications',
@@ -56,5 +58,11 @@ exports.endpoints = {
     },
     email: {
         sendEmail: 'api/v1/startum/send-email-with-default-domain'
+    },
+    webScraper: {
+        scrape: 'api/v1/web-scraper/scrape',
+        extract: 'api/v1/web-scraper/extract',
+        screenshot: 'api/v1/web-scraper/screenshot',
+        searchAndExtract: 'api/v1/web-scraper/search-and-extract',
     }
 };