ixc-orm 1.4.2 → 1.4.4

package/README.md

@@ -1,4 +1,4 @@
-# IXC-ORM
+# IXC-ORM [![npm](https://img.shields.io/npm/dt/ixc-orm.svg)](https://www.npmjs.com/package/ixc-orm)
 
 Este ORM simples visa facilitar o consumo de dados da API oficial do IXCsoft.\
 Esta biblioteca não faz parte das bibliotecas oficiais da IXCsoft e foi desenvolvida de forma independente e sem fins lucrativos.
@@ -6,8 +6,13 @@ Esta biblioteca não faz parte das bibliotecas oficiais da IXCsoft e foi desenvo
 
 ## 🚀 Novidades
 
-### v1.4.1 - 14 de agosto de 2025
+### v1.4.4 - 15 de agosto de 2025
+* **Melhorado:** Foi adicionado um método `find()` a classe `IXCClient`, para encontrar um registro pelo seu `id` de uma forma mais simples.
+
+### v1.4.3 - 15 de agosto de 2025
+* **Melhorado:** Os métodos `get()`, `post()` e `put()` da classe `IXCClient`, a partir de agora sempre retornarão um objeto `IXCResponse`, indepedente da requisição falhar ou não.
 
+### v1.4.1 - 14 de agosto de 2025
 * **Corrigido:** Resolvido o bug de leitura das variáveis de ambiente no arquivo .env na pasta raiz.
 * **Novo:** Foram adicionados 3 dos 44 recursos da API do IXC: `get_boleto`, `liberacao_temporaria` e `desbloqueio_confianca`. (Futuramente novos recursos serão adicionados)
 

package/dist/IXCClient.d.ts

@@ -1,24 +1,25 @@
-import { AxiosError } from 'axios';
 import { IXCOptions, IXCQuery, IXCResponse, IXCSortOrder } from './types';
 export default abstract class IXCClient {
     protected table: string;
     protected params: IXCQuery[];
     protected options: IXCOptions;
     /**
-     *
      * @param table O nome da tabela correspondente ao banco de dados do seu servidor IXC
      * @see {@link https://wikiapiprovedor.ixcsoft.com.br/index.php}
      */
     constructor(table: string);
     /**
+     * Incrementa o array de parâmetros que serão trasformados no corpo de uma requisição
+     * e passados como filtro grid da API do IXC
      *
-     * @param whereClauses Um array de strings, no formato [coluna, operador, valor]
-     * Obs: se você passar um array no formato [coluna, valor] o operador será considerado como '='
-     * Operadores válidos: =, !=, >, <, >=, <=, LIKE
+     * @param whereClauses Um array de strings, no formato [coluna, operador, valor]\
+     * `Obs`: se você passar um array no formato [coluna, valor] o operador será considerado como '='\
+     * Os operadores válidos são: =, !=, >, <, >=, <=, LIKE
      * @returns A própria instância
      */
     where(whereClauses: string[]): IXCClient;
     /**
+     * Define como a API do IXC ordenará os dados retornados
      *
      * @param column A coluna que será usada para ordenar a busca
      * @param order A ordem da busca ('asc'ou 'desc')
@@ -26,28 +27,41 @@ export default abstract class IXCClient {
      */
     orderBy(column: string, order: keyof typeof IXCSortOrder): IXCClient;
     /**
+     * Envia uma requisição GET para a API do IXC, com o header `ixcsoft` definico como `listar`\
+     * A `query` dessa requisição não será enviada para o IXC com o parâmetro `grid_param`\
+     * Ou seja, esta requisição executa uma busca simples, em vez do filtro de grid
+     *
+     * @param id O identificador numérico do registro que será buscado no IXC
+     * @returns Promise<IXCResponse>
+     */
+    find(id: any): Promise<IXCResponse>;
+    /**
+     * Envia uma requisição GET para a API do IXC, com o header `ixcsoft` definico como `listar`
+     * Preenche o corpo da requisição com os dados passados pela função `where` no formado JSON
      *
-     * @param pg O número da página que será solicitada ao IXC
-     * @param rows A quantidade de linhas (registros) por página
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @param pg O número da página que será solicitada ao IXC `padão = 1`
+     * @param rows A quantidade de linhas (registros) por página `padrão = 20`
+     * @returns Promise<IXCResponse>
      */
-    get(pg?: number, rows?: number): Promise<null | IXCResponse | AxiosError>;
+    get(pg?: number, rows?: number): Promise<IXCResponse>;
     /**
+     * Envia uma requisição do tipo `POST` para a API do IXC, com o header `ixcsoft` vazio
      *
      * @param body Um objeto no formado "chave: valor" contendo as informações do novo registro
      * a ser inserido no banco de dados do seu servidor IXC
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @returns Promise<IXCResponse>
      */
     post(body?: {
         [key: string]: any;
-    }): Promise<null | IXCResponse | AxiosError>;
+    }): Promise<IXCResponse>;
     /**
+     * Envia uma requisição do tipo `PUT` para a API do IXC, com o header `ixcsoft` vazio
      *
      * @param id O id do registro que será alterado
      * @param body Um objeto no formado "chave : valor" contendo as colunas que serão alteradas
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @returns Promise<IXCResponse>
      */
     put(id: number, body?: {
         [key: string]: any;
-    }): Promise<null | IXCResponse | AxiosError>;
+    }): Promise<IXCResponse>;
 }

package/dist/IXCClient.js

@@ -20,12 +20,11 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const axios_1 = require("axios");
 const request_1 = require("./request");
 const types_1 = require("./types");
+const response_1 = require("./response");
 class IXCClient {
     /**
-     *
      * @param table O nome da tabela correspondente ao banco de dados do seu servidor IXC
      * @see {@link https://wikiapiprovedor.ixcsoft.com.br/index.php}
      */
@@ -40,10 +39,12 @@ class IXCClient {
         };
     }
     /**
+     * Incrementa o array de parâmetros que serão trasformados no corpo de uma requisição
+     * e passados como filtro grid da API do IXC
      *
-     * @param whereClauses Um array de strings, no formato [coluna, operador, valor]
-     * Obs: se você passar um array no formato [coluna, valor] o operador será considerado como '='
-     * Operadores válidos: =, !=, >, <, >=, <=, LIKE
+     * @param whereClauses Um array de strings, no formato [coluna, operador, valor]\
+     * `Obs`: se você passar um array no formato [coluna, valor] o operador será considerado como '='\
+     * Os operadores válidos são: =, !=, >, <, >=, <=, LIKE
      * @returns A própria instância
      */
     where(whereClauses) {
@@ -63,6 +64,7 @@ class IXCClient {
         return this;
     }
     /**
+     * Define como a API do IXC ordenará os dados retornados
      *
      * @param column A coluna que será usada para ordenar a busca
      * @param order A ordem da busca ('asc'ou 'desc')
@@ -74,27 +76,86 @@ class IXCClient {
         return this;
     }
     /**
+     * Envia uma requisição GET para a API do IXC, com o header `ixcsoft` definico como `listar`\
+     * A `query` dessa requisição não será enviada para o IXC com o parâmetro `grid_param`\
+     * Ou seja, esta requisição executa uma busca simples, em vez do filtro de grid
      *
-     * @param pg O número da página que será solicitada ao IXC
-     * @param rows A quantidade de linhas (registros) por página
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @param id O identificador numérico do registro que será buscado no IXC
+     * @returns Promise<IXCResponse>
+     */
+    find(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const params = {
+                TB: 'id',
+                OP: '=',
+                P: id
+            };
+            const opts = {
+                page: 1,
+                rowsPerPage: 1,
+            };
+            const axios = (0, request_1.createAxiosInstance)('GET');
+            const data = (0, request_1.createRequestPayload)(this.table, params, opts);
+            try {
+                const response = yield axios.get(this.table, { data });
+                if (response.status === 200) {
+                    return response.data;
+                }
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: (_a = response.data) === null || _a === void 0 ? void 0 : _a.message
+                });
+            }
+            catch (error) {
+                console.error(error);
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: ((_b = error.response) === null || _b === void 0 ? void 0 : _b.statusText) || error.message || 'Erro desconhecido'
+                });
+            }
+            finally {
+                this.params = [];
+                this.options = {
+                    page: 1,
+                    rowsPerPage: 20,
+                    sortName: 'id',
+                    sortOrder: 'asc'
+                };
+            }
+        });
+    }
+    /**
+     * Envia uma requisição GET para a API do IXC, com o header `ixcsoft` definico como `listar`
+     * Preenche o corpo da requisição com os dados passados pela função `where` no formado JSON
+     *
+     * @param pg O número da página que será solicitada ao IXC `padão = 1`
+     * @param rows A quantidade de linhas (registros) por página `padrão = 20`
+     * @returns Promise<IXCResponse>
      */
     get(pg, rows) {
         return __awaiter(this, void 0, void 0, function* () {
-            const _a = this.options, { page, rowsPerPage } = _a, rest = __rest(_a, ["page", "rowsPerPage"]);
+            var _a, _b;
+            const _c = this.options, { page, rowsPerPage } = _c, rest = __rest(_c, ["page", "rowsPerPage"]);
             const opts = Object.assign({ page: pg !== null && pg !== void 0 ? pg : page, rowsPerPage: rows !== null && rows !== void 0 ? rows : rowsPerPage }, rest);
             const axios = (0, request_1.createAxiosInstance)('GET');
-            const payload = (0, request_1.createRequestPayload)(this.table, this.params, opts);
+            const data = (0, request_1.createRequestPayload)(this.table, this.params, opts);
             try {
-                const response = yield axios.get(this.table, payload);
-                return response.data;
+                const response = yield axios.get(this.table, { data });
+                if (response.status === 200) {
+                    return response.data;
+                }
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: (_a = response.data) === null || _a === void 0 ? void 0 : _a.message
+                });
             }
             catch (error) {
                 console.error(error);
-                if (error instanceof axios_1.AxiosError) {
-                    return error;
-                }
-                return null;
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: ((_b = error.response) === null || _b === void 0 ? void 0 : _b.statusText) || error.message || 'Erro desconhecido'
+                });
             }
             finally {
                 this.params = [];
@@ -108,24 +169,32 @@ class IXCClient {
         });
     }
     /**
+     * Envia uma requisição do tipo `POST` para a API do IXC, com o header `ixcsoft` vazio
      *
      * @param body Um objeto no formado "chave: valor" contendo as informações do novo registro
      * a ser inserido no banco de dados do seu servidor IXC
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @returns Promise<IXCResponse>
      */
     post(body) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             const axios = (0, request_1.createAxiosInstance)('POST');
             try {
                 const response = yield axios.post(this.table, { data: body });
-                return response.data;
+                if (response.status === 200) {
+                    return response.data;
+                }
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: (_a = response.data) === null || _a === void 0 ? void 0 : _a.message
+                });
             }
             catch (error) {
                 console.error(error);
-                if (error instanceof axios_1.AxiosError) {
-                    return error;
-                }
-                return null;
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: ((_b = error.response) === null || _b === void 0 ? void 0 : _b.statusText) || error.message || 'Erro desconhecido'
+                });
             }
             finally {
                 this.params = [];
@@ -133,24 +202,32 @@ class IXCClient {
         });
     }
     /**
+     * Envia uma requisição do tipo `PUT` para a API do IXC, com o header `ixcsoft` vazio
      *
      * @param id O id do registro que será alterado
      * @param body Um objeto no formado "chave : valor" contendo as colunas que serão alteradas
-     * @returns Promise<null | IXCResponse | AxiosError>
+     * @returns Promise<IXCResponse>
      */
     put(id, body) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
             const axios = (0, request_1.createAxiosInstance)('PUT');
             try {
                 const response = yield axios.put(`${this.table}/${id}`, { data: body });
-                return response.data;
+                if (response.status === 200) {
+                    return response.data;
+                }
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: (_a = response.data) === null || _a === void 0 ? void 0 : _a.message
+                });
             }
             catch (error) {
                 console.error(error);
-                if (error instanceof axios_1.AxiosError) {
-                    return error;
-                }
-                return null;
+                return (0, response_1.createResponse)({
+                    error: true,
+                    message: ((_b = error.response) === null || _b === void 0 ? void 0 : _b.statusText) || error.message || 'Erro desconhecido'
+                });
             }
             finally {
                 this.params = [];

package/dist/request.d.ts

@@ -1,16 +1,20 @@
-import { AxiosInstance, AxiosRequestConfig } from 'axios';
+import { AxiosInstance } from 'axios';
 import { IXCOptions, IXCQuery, IXCRequest, IXCRequestMethods } from './types';
 /**
+ * Cria uma instância de um objeto AxiosInstance, pré-configurado com os cabeçalhos necessários
+ * para executar uma requisição para a API do IXC
  *
  * @param method GET | POST | PUT | DELETE
- * @returns A instância de um objeto do tipo AxiosInstance, pré-configurado com os cabeçalhos necessários
+ * @returns AxiosInstance
  */
 export declare function createAxiosInstance(method?: keyof typeof IXCRequestMethods): AxiosInstance;
 /**
+ * Cria um objeto `IXCRequest` configurado para ser utilizado como payload de uma requisição
+ * para a API do IXC
  *
  * @param table Nome da tabela do IXC onde será feita a busca, atualização, inserção ou remoção
  * @param params Parâmetros da busca (desconsiderados quando a ação for a de inserir novos registros)
  * @param options Parâmetros de formatação dos dados da responsta (página, ítens por página e ordenação)
- * @returns
+ * @returns IXCRequest
  */
-export declare function createRequestPayload(table: string, params: IXCQuery | IXCQuery[], options?: IXCOptions): AxiosRequestConfig<IXCRequest>;
+export declare function createRequestPayload(table: string, params: IXCQuery | IXCQuery[], options?: IXCOptions): IXCRequest;

package/dist/request.js

@@ -7,9 +7,11 @@ exports.createAxiosInstance = createAxiosInstance;
 exports.createRequestPayload = createRequestPayload;
 const axios_1 = __importDefault(require("axios"));
 /**
+ * Cria uma instância de um objeto AxiosInstance, pré-configurado com os cabeçalhos necessários
+ * para executar uma requisição para a API do IXC
  *
  * @param method GET | POST | PUT | DELETE
- * @returns A instância de um objeto do tipo AxiosInstance, pré-configurado com os cabeçalhos necessários
+ * @returns AxiosInstance
  */
 function createAxiosInstance(method = 'GET') {
     const host = process.env.IXC_HOST;
@@ -25,11 +27,13 @@ function createAxiosInstance(method = 'GET') {
     });
 }
 /**
+ * Cria um objeto `IXCRequest` configurado para ser utilizado como payload de uma requisição
+ * para a API do IXC
  *
  * @param table Nome da tabela do IXC onde será feita a busca, atualização, inserção ou remoção
  * @param params Parâmetros da busca (desconsiderados quando a ação for a de inserir novos registros)
  * @param options Parâmetros de formatação dos dados da responsta (página, ítens por página e ordenação)
- * @returns
+ * @returns IXCRequest
  */
 function createRequestPayload(table, params, options) {
     var _a, _b, _c, _d;
@@ -46,24 +50,24 @@ function createRequestPayload(table, params, options) {
                 P: p.P
             });
         });
-        return { data: {
-                qtype: table,
-                query: '',
-                oper: '',
-                page: page,
-                rp: rowsPerPage,
-                sortname: `${table}.${sortName}`,
-                sortorder: sortOrder,
-                grid_param: JSON.stringify(grid_param)
-            } };
-    }
-    return { data: {
-            qtype: `${table}.${params.TB}`,
-            query: params.P,
-            oper: params.OP || '=',
+        return {
+            qtype: table,
+            query: '',
+            oper: '',
             page: page,
             rp: rowsPerPage,
             sortname: `${table}.${sortName}`,
-            sortorder: sortOrder
-        } };
+            sortorder: sortOrder,
+            grid_param: JSON.stringify(grid_param)
+        };
+    }
+    return {
+        qtype: `${table}.${params.TB}`,
+        query: params.P,
+        oper: params.OP || '=',
+        page: page,
+        rp: rowsPerPage,
+        sortname: `${table}.${sortName}`,
+        sortorder: sortOrder
+    };
 }

package/dist/types.d.ts

@@ -40,7 +40,7 @@ export interface IXCRequest {
 }
 export interface IXCResponse {
     error?: boolean | object;
-    message?: string | null;
+    message?: string;
     id?: string | number;
     page: number | string;
     total: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ixc-orm",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",