http-sankhya 1.0.1

package/README.md

@@ -0,0 +1,195 @@
+# http-sankhya
+
+Uma biblioteca TypeScript para interagir com a API do ERP Sankhya. Esta biblioteca simplifica a autenticação, o tratamento de respostas e a formatação de payloads para operações CRUD comuns.
+
+## Instalação
+
+Certifique-se de ter as dependências instaladas:
+
+```bash
+npm install axios
+```
+
+## Uso
+
+### Inicialização
+
+Importe a classe `Sankhya` e inicialize-a com sua configuração.
+
+```typescript
+import { Sankhya } from './src/Sankhya'; // Ajuste o caminho conforme necessário
+
+const config = {
+    urlBase: 'https://api.sandbox.sankhya.com.br', // URL Base da API do Sankhya
+    clientId: 'seu-client-id',
+    clientSecret: 'seu-client-secret',
+    token: 'seu-token' // Opcional: Se você já tiver um token
+};
+
+const sankhya = new Sankhya(config);
+```
+
+### Autenticação
+
+Autentique-se na API para obter um token de sessão.
+
+```typescript
+await sankhya.login();
+```
+*Nota: A implementação de login utiliza um fluxo de bearer token ou credenciais enviadas via header, dependendo da configuração. Certifique-se de que seu backend suporta o endpoint de autenticação configurado.*
+
+---
+
+## Métodos e Exemplos
+
+### 1. loadRecords (Buscar Múltiplos Registros)
+
+Busca uma lista de registros com suporte a filtros, paginação e seleção de campos.
+
+#### Exemplo Básico
+```typescript
+const produtos = await sankhya.loadRecords({
+    rootEntity: 'GrupoProduto', // Nome da Tabela/Entidade no Sankhya
+    criteria: {
+        expression: "ATIVO = 'S'" // Filtro SQL-like
+    }
+});
+```
+
+#### Exemplo com Paginação e Seleção de Campos
+Para otimizar a performance, solicite apenas os campos necessários (`fieldset`) e use `offsetPage` para paginar.
+
+```typescript
+const parceiros = await sankhya.loadRecords({
+    rootEntity: 'Parceiro',
+    offsetPage: 1, // Página 1 (0-indexada ou conforme API)
+    criteria: {
+        expression: "TIPPESSOA = 'F'"
+    },
+    entity: {
+        fieldset: {
+            list: "CODPARC,NOMEPARC,CGC_CPF,EMAIL" // Campos desejados
+        }
+    }
+});
+```
+
+#### Exemplo com Campos de Apresentação
+Se precisar dos valores formatados (lookup), ative `includePresentationFields`.
+
+```typescript
+const vendas = await sankhya.loadRecords({
+    rootEntity: 'CabecalhoNota',
+    includePresentationFields: 'S', // Retorna descrições de chaves estrangeiras
+    criteria: {
+        expression: "DTNEG >= '01/01/2024'"
+    }
+});
+```
+
+---
+
+### 2. loadRecord (Buscar Registro Único)
+
+Busca um único registro específico, geralmente pela Chave Primária (PK).
+
+```typescript
+const produto = await sankhya.loadRecord({
+    rootEntity: 'Produto',
+    rows: {
+        row: {
+            CODPROD: { "$": "1005" } // Chave Primária
+        }
+    },
+    entity: {
+        fieldset: {
+            list: "*" // Retorna todos os campos
+        }
+    }
+});
+
+console.log(produto);
+// Saída: { CODPROD: "1005", DESCRPROD: "PRODUTO TESTE", ... }
+```
+
+---
+
+### 3. saveRecord (Criar ou Atualizar Registro)
+
+Cria ou atualiza registros. A biblioteca formata automaticamente o payload do objeto `localFields` para o padrão exigido pelo Sankhya.
+
+#### Criar Novo Registro
+Para criar, omita a Chave Primária (se for auto-incremental) ou passe os valores necessários.
+
+```typescript
+const novoGrupo = await sankhya.saveRecord({
+    rootEntity: 'GrupoProduto',
+    localFields: {
+        DESCRGRUPOPROD: "NOVO GRUPO 2024",
+        ATIVO: "S",
+        // Outros campos obrigatórios...
+    },
+    // Opcional: Retornar campos criados (ex: ID gerado)
+    entity: {
+        fieldset: {
+            list: "CODGRUPOPROD,DESCRGRUPOPROD"
+        }
+    }
+});
+```
+
+#### Atualizar Registro Existente (Upsert)
+Para atualizar, inclua a Chave Primária nos `localFields`. O comportamento exato depende da entidade Sankhya, mas geralmente atua como "Upsert" (Atualiza se existe, cria se não).
+
+```typescript
+const atualizacao = await sankhya.saveRecord({
+    rootEntity: 'GrupoProduto',
+    localFields: {
+        CODGRUPOPROD: "20310006", // PK existente
+        DESCRGRUPOPROD: "NOME ATUALIZADO", // Campo a alterar
+        ATIVO: "N"
+    }
+});
+```
+
+---
+
+### 4. Execução de Serviço Genérico (execService)
+
+Para endpoints que não sejam CRUD padrão (ex: executar Stored Procedures, ações de workflow, ou consultas de metadados), use `execService`.
+
+#### Exemplo: Consultar Estoque (Serviço Hipotético)
+```typescript
+const estoque = await sankhya.execService({
+    serviceName: 'EstoqueSP.getEstoque',
+    requestBody: {
+        codProd: '1005',
+        codEmp: '1'
+    }
+});
+```
+
+#### Exemplo: Deletar Registro de Forma Personalizada
+Embora exista o método `.delete()`, algumas operações de exclusão no Sankhya são feitas via serviços específicos.
+
+```typescript
+await sankhya.execService({
+    serviceName: 'CRUDServiceProvider.removeRecord',
+    requestBody: {
+        entity: {
+            rootEntity: 'Parceiro',
+            pk: {
+                CODPARC: { "$": "999" }
+            }
+        }
+    }
+});
+```
+
+## Funcionalidades
+
+- **Tratamento de Resposta**: Simplifica a resposta aninhada do Sankhya.
+    - *LoadRecords*: Retorna `Array<Objeto>`.
+    - *LoadRecord*: Retorna `Objeto` único (lida com ausência de metadados).
+- **Transformação de Payload**: O método `saveRecord` aceita objetos simples JS (ex: `{ CAMPO: "Valor" }`) e os converte automaticamente para `{ CAMPO: { "$": "Valor" } }`.
+- **Tipagem TypeScript**: Suporte completo a interfaces para garantir segurança de tipo no desenvolvimento.

package/dist/Sankhya.d.ts

@@ -0,0 +1,47 @@
+export interface SankhyaConfig {
+    urlBase: string;
+    clientId?: string;
+    clientSecret?: string;
+    token?: string;
+}
+export interface LoadRecordsOptions {
+    rootEntity: string;
+    includePresentationFields?: 'S' | 'N';
+    offsetPage?: number;
+    criteria?: Record<string, any>;
+    entity?: Record<string, any>;
+    rows?: Record<string, any>;
+}
+export interface SaveRecordOptions {
+    rootEntity: string;
+    includePresentationFields?: 'S' | 'N';
+    localFields?: Record<string, any>;
+    entity?: Record<string, any>;
+}
+export interface ExecServiceOptions {
+    serviceName: string;
+    requestBody?: Record<string, any>;
+    outputType?: 'json' | 'xml';
+}
+export declare class Sankhya {
+    private urlBase;
+    private clientId?;
+    private clientSecret?;
+    private token?;
+    private tokenClient?;
+    private axiosInstance;
+    private jsessionid?;
+    constructor(config: SankhyaConfig);
+    login(): Promise<any>;
+    logout(): Promise<void>;
+    get(path: string, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
+    post(path: string, body?: Record<string, any>, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
+    put(path: string, body?: Record<string, any>, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
+    patch(path: string, body?: Record<string, any>, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
+    delete(path: string, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
+    execService(options: ExecServiceOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    loadRecords({ rootEntity, includePresentationFields, offsetPage, criteria, entity }: LoadRecordsOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    loadRecord({ rootEntity, includePresentationFields, criteria, entity, rows }: LoadRecordsOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    saveRecord({ rootEntity, includePresentationFields, localFields, entity }: SaveRecordOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    private isEmptyObject;
+}

package/dist/Sankhya.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sankhya = void 0;
+const axios_1 = __importDefault(require("axios"));
+const SankhyaHelper_1 = require("./SankhyaHelper");
+class Sankhya {
+    constructor(config) {
+        this.urlBase = config.urlBase;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.tokenClient = config.token;
+        this.axiosInstance = axios_1.default.create({
+            baseURL: this.urlBase,
+            timeout: 30000, // Default timeout
+        });
+        // Add interceptor to inject token/session if needed
+        this.axiosInstance.interceptors.request.use((req) => {
+            if (this.token) {
+                req.headers['Authorization'] = `Bearer ${this.token}`;
+                req.headers['Content-Type'] = `application/json`;
+            }
+            // Often Sankhya uses JSESSIONID cookie or header. 
+            // If we firmly set token in constructor, mostly used as Bearer or specific header.
+            return req;
+        });
+    }
+    async login() {
+        // Implementation depends on specific Sankhya Auth endpoint (e.g. MobileLoginSP.login)
+        // or standard OAuth. 
+        // Allowing placeholder or specific implementation if user didn't specify the Auth Payload.
+        // Assuming standard service execution for now or a place to fill in.
+        if (this.clientId && this.clientSecret && this.tokenClient) {
+            // Example Oauth or App interaction
+            const response = await this.axiosInstance.post('/authenticate', {
+                grant_type: 'client_credentials'
+            }, {
+                headers: {
+                    'X-Token': this.tokenClient,
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                },
+                auth: {
+                    username: this.clientId,
+                    password: this.clientSecret
+                }
+            });
+            this.token = response.data.access_token;
+        }
+        else {
+            throw new Error('Missing authentication credentials');
+        }
+    }
+    async logout() {
+        throw new Error('Logout not implemented');
+    }
+    // HTTP Methods
+    async get(path, queryParam = {}, headers = {}) {
+        const response = await this.axiosInstance.get(path, {
+            params: queryParam,
+            headers: headers
+        });
+        return response.data;
+    }
+    async post(path, body = {}, queryParam = {}, headers = {}) {
+        const response = await this.axiosInstance.post(path, body, {
+            params: queryParam,
+            headers: headers
+        });
+        // Tenta identificar o serviceName no corpo da requisição para passar ao helper
+        const serviceName = body === null || body === void 0 ? void 0 : body.serviceName;
+        return SankhyaHelper_1.SankhyaHelper.processResponse(response.data, { serviceName });
+    }
+    async put(path, body = {}, queryParam = {}, headers = {}) {
+        const response = await this.axiosInstance.put(path, body, {
+            params: queryParam,
+            headers: headers
+        });
+        return response.data;
+    }
+    async patch(path, body = {}, queryParam = {}, headers = {}) {
+        const response = await this.axiosInstance.patch(path, body, {
+            params: queryParam,
+            headers: headers
+        });
+        return response.data;
+    }
+    async delete(path, queryParam = {}, headers = {}) {
+        const response = await this.axiosInstance.delete(path, {
+            params: queryParam,
+            headers: headers
+        });
+        return response.data;
+    }
+    // Sankhya Specific Methods
+    async execService(options, outputType = 'json') {
+        // Standard Sankhya Service URL pattern: /mge/service.sbr?serviceName=...&outputType=json
+        const { serviceName, requestBody } = options;
+        // Construct the wrapper expected by Sankhya JSON API
+        const payload = {
+            serviceName: serviceName,
+            requestBody: requestBody
+        };
+        // Note: This is an assumption of the 'service.sbr' endpoint based on typical Sankhya integrations.
+        // The user might want to adjust the exact endpoint path in the future.
+        return this.post('/gateway/v1/mge/service.sbr', payload, {
+            serviceName,
+            outputType: options.outputType || outputType
+        }, {});
+    }
+    async loadRecords({ rootEntity, includePresentationFields = 'N', offsetPage = 0, criteria = {}, entity = {} }, outputType = 'json') {
+        return this.execService({
+            serviceName: 'CRUDServiceProvider.loadRecords',
+            requestBody: {
+                dataSet: {
+                    rootEntity,
+                    includePresentationFields,
+                    offsetPage,
+                    criteria,
+                    entity: this.isEmptyObject(entity) ? { fieldset: { list: "*" } } : entity
+                }
+            },
+            outputType
+        }, outputType);
+    }
+    async loadRecord({ rootEntity, includePresentationFields = 'N', criteria = {}, entity = {}, rows = {} }, outputType = 'json') {
+        return this.execService({
+            serviceName: 'CRUDServiceProvider.loadRecord',
+            requestBody: {
+                dataSet: {
+                    rootEntity,
+                    includePresentationFields,
+                    criteria,
+                    entity: this.isEmptyObject(entity) ? { fieldset: { list: "*" } } : entity,
+                    rows
+                }
+            },
+            outputType
+        }, outputType);
+    }
+    async saveRecord({ rootEntity, includePresentationFields = 'N', localFields = {}, entity = {} }, outputType = 'json') {
+        return this.execService({
+            serviceName: 'CRUDServiceProvider.saveRecord',
+            requestBody: {
+                dataSet: {
+                    rootEntity,
+                    includePresentationFields,
+                    dataRow: {
+                        localFields: SankhyaHelper_1.SankhyaHelper.transformLocalFields(localFields)
+                    },
+                },
+                entity
+            },
+            outputType
+        }, outputType);
+    }
+    isEmptyObject(obj) {
+        return obj != null &&
+            obj.constructor === Object &&
+            Object.keys(obj).length === 0;
+    }
+}
+exports.Sankhya = Sankhya;

package/dist/SankhyaHelper.d.ts

@@ -0,0 +1,15 @@
+export declare class SankhyaHelper {
+    /**
+     * Converte retorno do Sankhya baseado no tipo de serviço.
+     * Utiliza switch case para rotear o tratamento.
+     */
+    static processResponse(response: any, options?: {
+        serviceName?: string;
+    }): any;
+    /**
+     * Transforma um objeto simples de chave/valor para o formato do Sankhya
+     * Ex: { CAMPO: "VALOR" } -> { CAMPO: { "$": "VALOR" } }
+     */
+    static transformLocalFields(localFields: Record<string, any>): Record<string, any>;
+    private static processLoadRecords;
+}

package/dist/SankhyaHelper.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SankhyaHelper = void 0;
+class SankhyaHelper {
+    /**
+     * Converte retorno do Sankhya baseado no tipo de serviço.
+     * Utiliza switch case para rotear o tratamento.
+     */
+    static processResponse(response, options = {}) {
+        if (!response || !response.responseBody || !response.responseBody.entities) {
+            return response;
+        }
+        switch (options.serviceName) {
+            case 'CRUDServiceProvider.loadRecords':
+            case 'CRUDServiceProvider.loadRecord':
+            case 'CRUDServiceProvider.saveRecord':
+                return this.processLoadRecords(response);
+            default:
+                // Se não for um dos serviços conhecidos de CRUD/Load, retorna original
+                return response;
+        }
+    }
+    /**
+     * Transforma um objeto simples de chave/valor para o formato do Sankhya
+     * Ex: { CAMPO: "VALOR" } -> { CAMPO: { "$": "VALOR" } }
+     */
+    static transformLocalFields(localFields) {
+        const transformed = {};
+        Object.keys(localFields).forEach(key => {
+            const value = localFields[key];
+            // Se o valor já estiver no formato { $: ... }, mantém
+            if (value && typeof value === 'object' && '$' in value) {
+                transformed[key] = value;
+            }
+            else {
+                transformed[key] = { $: value };
+            }
+        });
+        return transformed;
+    }
+    // Lógica de transformação extraída para método privado
+    static processLoadRecords(response) {
+        const { entities } = response.responseBody;
+        const metadata = entities.metadata;
+        // Se não tiver metadados, pode ser um loadRecord de um único registro sem fields info
+        if (!metadata || !metadata.fields || !metadata.fields.field) {
+            const entityNode = entities.entity;
+            if (entityNode && !Array.isArray(entityNode)) {
+                // Caso específico do loadRecord que retorna entity direto sem metadata
+                const record = {};
+                Object.keys(entityNode).forEach(key => {
+                    const value = entityNode[key];
+                    if (value && typeof value === "object" && "$" in value) {
+                        record[key] = value.$;
+                    }
+                    else {
+                        // Se for objeto vazio ou não tiver $, assume null ou mantém o valor original se não for objeto vazio
+                        // No exemplo dado: "GRUPOICMS": {} -> null
+                        if (Object.keys(value).length === 0) {
+                            record[key] = null;
+                        }
+                        else {
+                            record[key] = value; // Fallback, maintain original if not empty and no $
+                        }
+                    }
+                });
+                return record;
+            }
+            return response;
+        }
+        const fields = metadata.fields.field;
+        const entityNode = entities.entity;
+        if (!entityNode) {
+            if (entities.total === "0")
+                return [];
+            return response;
+        }
+        const mapOne = (ent) => {
+            const record = {};
+            const fieldsArray = Array.isArray(fields) ? fields : [fields];
+            fieldsArray.forEach((f, idx) => {
+                var _a;
+                const key = (_a = f === null || f === void 0 ? void 0 : f.name) !== null && _a !== void 0 ? _a : `field_${idx}`;
+                const raw = ent[`f${idx}`];
+                if (raw && typeof raw === "object" && "$" in raw) {
+                    record[key] = raw.$;
+                }
+                else {
+                    record[key] = null;
+                }
+            });
+            return record;
+        };
+        if (Array.isArray(entityNode)) {
+            return entityNode.map(mapOne);
+        }
+        return mapOne(entityNode);
+    }
+}
+exports.SankhyaHelper = SankhyaHelper;

package/dist/SankhyaResponseHelper.d.ts

@@ -0,0 +1,10 @@
+export declare class SankhyaResponseHelper {
+    /**
+     * Converte retorno do Sankhya baseado no tipo de serviço.
+     * Utiliza switch case para rotear o tratamento.
+     */
+    static processResponse(response: any, options?: {
+        serviceName?: string;
+    }): any;
+    private static processLoadRecords;
+}

package/dist/SankhyaResponseHelper.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SankhyaResponseHelper = void 0;
+class SankhyaResponseHelper {
+    /**
+     * Converte retorno do Sankhya baseado no tipo de serviço.
+     * Utiliza switch case para rotear o tratamento.
+     */
+    static processResponse(response, options = {}) {
+        if (!response || !response.responseBody || !response.responseBody.entities) {
+            return response;
+        }
+        switch (options.serviceName) {
+            case 'CRUDServiceProvider.loadRecords':
+            case 'CRUDServiceProvider.loadRecord':
+            case 'CRUDServiceProvider.saveRecord':
+                return this.processLoadRecords(response);
+            default:
+                // Se não for um dos serviços conhecidos de CRUD/Load, retorna original
+                return response;
+        }
+    }
+    // Lógica de transformação extraída para método privado
+    static processLoadRecords(response) {
+        const { entities } = response.responseBody;
+        const metadata = entities.metadata;
+        if (!metadata || !metadata.fields || !metadata.fields.field) {
+            return response;
+        }
+        const fields = metadata.fields.field;
+        const entityNode = entities.entity;
+        if (!entityNode) {
+            if (entities.total === "0")
+                return [];
+            return response;
+        }
+        const mapOne = (ent) => {
+            const record = {};
+            const fieldsArray = Array.isArray(fields) ? fields : [fields];
+            fieldsArray.forEach((f, idx) => {
+                var _a;
+                const key = (_a = f === null || f === void 0 ? void 0 : f.name) !== null && _a !== void 0 ? _a : `field_${idx}`;
+                const raw = ent[`f${idx}`];
+                if (raw && typeof raw === "object" && "$" in raw) {
+                    record[key] = raw.$;
+                }
+                else {
+                    record[key] = null;
+                }
+            });
+            return record;
+        };
+        if (Array.isArray(entityNode)) {
+            return entityNode.map(mapOne);
+        }
+        return mapOne(entityNode);
+    }
+}
+exports.SankhyaResponseHelper = SankhyaResponseHelper;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './Sankhya';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Sankhya"), exports);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "http-sankhya",
+  "version": "1.0.1",
+  "description": "Biblioteca TypeScript para integração com ERP Sankhya",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "debug": "npx ts-node test-manual.ts"
+  },
+  "keywords": [
+    "sankhya",
+    "erp",
+    "api",
+    "typescript",
+    "integration"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcosdslau/http-sankhya.git"
+  },
+  "homepage": "https://github.com/marcosdslau/http-sankhya#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}