biatoolkit 1.1.1__tar.gz → 1.2.0__tar.gz

{biatoolkit-1.1.1 → biatoolkit-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.1.1
+Version: 1.2.0
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -348,4 +348,145 @@ O método `get_parameter(parameter_name: str)` busca o parâmetro informado em d
 - Um arquivo `.env` para testes locais.
 - No cofre de segredos do Bia Agent Builder para usar em ambiente produtivo. 
 
-Assim, o **MESMO CÓDIGO** do Servidor MCP pode ser executado em ambos os ambientes.
+
+---
+
+## Validação e Coerção de Dados
+
+O Bia Toolkit oferece funções utilitárias para normalização, sanitização e coerção de dados, facilitando o consumo seguro de entradas vindas de APIs, headers, payloads e integrações legadas.
+
+
+### Validação de Dados (`biatoolkit.validation.validation`)
+
+Utilize a classe **BiaValidation** para acessar as funções de validação de forma padronizada:
+
+- **BiaValidation.parse_int_list(value, dedupe=True, keep_order=True)**
+    - Normaliza um valor arbitrário em uma lista de inteiros.
+    - Suporta: None, int, str (extrai números), list/tuple (recursivo).
+    - Ignora valores inválidos.
+    - Deduplica e mantém ordem por padrão.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.validation import BiaValidation
+        BiaValidation.parse_int_list("SKU=300231 x2")  # [300231, 2]
+        BiaValidation.parse_int_list([1, 2, 1, 3], dedupe=False)  # [1, 2, 1, 3]
+        ```
+
+- **BiaValidation.sanitize_like(value, max_len=80, upper=True)**
+    - Sanitiza texto para uso seguro em filtros LIKE/search SQL.
+    - Remove caracteres fora da allowlist, limita tamanho, escapa aspas simples, %, _ e normaliza espaços.
+    - Converte para maiúsculas por padrão.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.validation import BiaValidation
+        BiaValidation.sanitize_like("O'Reilly")  # "O''REILLY"
+        BiaValidation.sanitize_like("100%_OK")   # "100\\%\\_OK"
+        ```
+
+
+### Coerção de Dados (`biatoolkit.validation.coercion`)
+
+Utilize a classe **BiaCoercion** para acessar as funções de coerção de forma padronizada:
+
+- **BiaCoercion.ensure_list(value)**
+    - Garante que o valor seja retornado como lista.
+    - None → [], list → list, tuple/set → list, dict → [dict], outro → [valor].
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.ensure_list(None)  # []
+        BiaCoercion.ensure_list({"a": 1})  # [{"a": 1}]
+        BiaCoercion.ensure_list(5)  # [5]
+        ```
+
+- **BiaCoercion.unwrap_dollar_value(value)**
+    - Desembrulha valores no formato {"$": ...} (comum em integrações legadas).
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.unwrap_dollar_value({"$": 123})  # 123
+        BiaCoercion.unwrap_dollar_value("abc")  # "abc"
+        ```
+
+- **BiaCoercion.to_int(value, default=0)**
+    - Converte valor para int de forma segura.
+    - None, "", bool, NaN/inf → default.
+    - Aceita strings numéricas, floats (trunca), etc.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.to_int(" 42 ")  # 42
+        BiaCoercion.to_int(None, default=-1)  # -1
+        ```
+
+- **BiaCoercion.to_float(value, default=0.0)**
+    - Converte valor para float de forma segura.
+    - None, "", bool, NaN/inf → default.
+    - Aceita strings com vírgula decimal.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.to_float("12,34")  # 12.34
+        BiaCoercion.to_float("abc", default=-1.0)  # -1.0
+        ```
+
+
+Essas funções são úteis para garantir robustez e previsibilidade ao tratar dados vindos de múltiplas fontes, reduzindo erros e if/else espalhados pelo código.
+
+---
+
+## Integração com Sankhya (`biatoolkit.sankhya_call`)
+
+
+O Bia Toolkit oferece integração pronta para consumo de serviços HTTP da plataforma Sankhya (ou gateway), com autenticação via JSESSIONID e configuração de timeouts/retries via variáveis de ambiente.
+
+### Objetivo
+
+- Facilitar chamadas autenticadas a serviços Sankhya sem que o desenvolvedor precise lidar com autenticação, headers ou gerenciamento de sessão HTTP.
+- Fornecer métodos prontos para chamadas genéricas (`call_json`) e para consultas a views (`load_view`).
+- Permitir uso estático compatível com scaffolds legados via `Sankhya.Call(...)`.
+
+### Configuração
+
+- O caminho do serviço (`/mge/service.sbr`) é fixo no toolkit.
+- O parâmetro `base_url` é obrigatório e pode ser passado explicitamente ou extraído automaticamente do header do runtime (`current_host` via `BiaUtil`).
+- Não existe mais configuração via variável de ambiente para base_url ou service_path.
+- As variáveis de ambiente opcionais são apenas para timeout, retries e SSL:
+    - `SANKHYA_TIMEOUT_CONNECT`: timeout de conexão (default: 3.05)
+    - `SANKHYA_TIMEOUT_READ`: timeout de leitura (default: 12)
+    - `SANKHYA_RETRIES_TOTAL`: número de tentativas em falha (default: 3)
+    - `SANKHYA_RETRY_BACKOFF`: backoff entre tentativas (default: 0.5)
+    - `SANKHYA_VERIFY_SSL`: se valida SSL (default: "1")
+
+### Principais classes e métodos
+
+- **SankhyaSettings**: Dataclass de configuração de timeouts/retries/SSL. Use `SankhyaSettings.from_env()` para obter as configurações do ambiente.
+- **Sankhya**: Classe principal de integração. Permite instanciar com contexto MCP (`FastMCP`) ou usar métodos estáticos.
+    - `call_json(...)`: Realiza chamada HTTP autenticada, retorna JSON.
+    - `load_view(...)`: Helper para consultas a views Sankhya (`CRUDServiceProvider.loadView`).
+    - `Call(...)`: Método estático compatível com scaffolds legados.
+- **SankhyaHTTPError**: Exceção lançada em caso de erro HTTP (status != 200), contendo status_code e response_text.
+
+### Exemplo de uso (instanciado)
+
+```python
+from biatoolkit.sankhya_call import Sankhya
+sk = Sankhya(mcp=mcp)
+result = sk.load_view("BIA_VW_MB_RULES", "CODPROD_A = 123", fields="*")
+# O base_url será extraído automaticamente do header do runtime (current_host)
+```
+
+### Exemplo de uso (estático)
+
+```python
+from biatoolkit.sankhya_call import Sankhya
+result = Sankhya.Call(jsessionID="...", payload={...}, base_url="https://meu.sankhya.com.br", query="serviceName=...&outputType=json")
+```
+
+### Observações
+
+- O JSESSIONID pode ser passado explicitamente ou extraído automaticamente do header do runtime (se rodando em MCP Server).
+- O método `load_view` facilita consultas a views Sankhya, montando o payload e a querystring automaticamente, e resolve o base_url do header se não for passado.
+- O método `call_json` permite chamadas genéricas a qualquer serviço Sankhya, com controle total sobre headers, método HTTP, payload e querystring, mas exige base_url explícito se não estiver em contexto MCP.
+
+---

{biatoolkit-1.1.1 → biatoolkit-1.2.0}/README.md

@@ -381,4 +381,82 @@ fornecido em ambiente produtivo pelo Bia Agent Builder.
 - Um arquivo `.env` para testes locais.
 - No cofre de segredos do Bia Agent Builder para usar em ambiente produtivo. 
 
-Assim, o **MESMO CÓDIGO** do Servidor MCP pode ser executado em ambos os ambientes.
+
+## **Validação e Coerção de Dados**
+
+O Bia Toolkit oferece funções utilitárias para normalização, sanitização e coerção de dados, facilitando o consumo seguro de entradas vindas de APIs, headers, payloads e integrações legadas.
+
+
+### **Validação de Dados** (`biatoolkit.validation.validation`)
+
+Utilize a classe **BiaValidation** para acessar as funções de validação de forma padronizada:
+
+- **BiaValidation.parse_int_list(value, dedupe=True, keep_order=True)**
+  - Normaliza um valor arbitrário em uma lista de inteiros.
+  - Suporta: None, int, str (extrai números), list/tuple (recursivo).
+  - Ignora valores inválidos.
+  - Deduplica e mantém ordem por padrão.
+  - Exemplo:
+    ```python
+    from biatoolkit.validation.validation import BiaValidation
+    BiaValidation.parse_int_list("SKU=300231 x2")  # [300231, 2]
+    BiaValidation.parse_int_list([1, 2, 1, 3], dedupe=False)  # [1, 2, 1, 3]
+    ```
+
+- **BiaValidation.sanitize_like(value, max_len=80, upper=True)**
+  - Sanitiza texto para uso seguro em filtros LIKE/search SQL.
+  - Remove caracteres fora da allowlist, limita tamanho, escapa aspas simples, %, _ e normaliza espaços.
+  - Converte para maiúsculas por padrão.
+  - Exemplo:
+    ```python
+    from biatoolkit.validation.validation import BiaValidation
+    BiaValidation.sanitize_like("O'Reilly")  # "O''REILLY"
+    BiaValidation.sanitize_like("100%_OK")   # "100\\%\\_OK"
+    ```
+
+### **Coerção de Dados** (`biatoolkit.validation.coercion`)
+
+Utilize a classe **BiaCoercion** para acessar as funções de coerção de forma padronizada:
+
+- **BiaCoercion.ensure_list(value)**
+  - Garante que o valor seja retornado como lista.
+  - None → [], list → list, tuple/set → list, dict → [dict], outro → [valor].
+  - Exemplo:
+    ```python
+    from biatoolkit.validation.coercion import BiaCoercion
+    BiaCoercion.ensure_list(None)  # []
+    BiaCoercion.ensure_list({"a": 1})  # [{"a": 1}]
+    BiaCoercion.ensure_list(5)  # [5]
+    ```
+
+- **BiaCoercion.unwrap_dollar_value(value)**
+  - Desembrulha valores no formato {"$": ...} (comum em integrações legadas).
+  - Exemplo:
+    ```python
+    from biatoolkit.validation.coercion import BiaCoercion
+    BiaCoercion.unwrap_dollar_value({"$": 123})  # 123
+    BiaCoercion.unwrap_dollar_value("abc")  # "abc"
+    ```
+
+- **BiaCoercion.to_int(value, default=0)**
+  - Converte valor para int de forma segura.
+  - None, "", bool, NaN/inf → default.
+  - Aceita strings numéricas, floats (trunca), etc.
+  - Exemplo:
+    ```python
+    from biatoolkit.validation.coercion import BiaCoercion
+    BiaCoercion.to_int(" 42 ")  # 42
+    BiaCoercion.to_int(None, default=-1)  # -1
+    ```
+
+- **BiaCoercion.to_float(value, default=0.0)**
+  - Converte valor para float de forma segura.
+  - None, "", bool, NaN/inf → default.
+  - Aceita strings com vírgula decimal.
+  - Exemplo:
+    ```python
+    to_float("12,34")  # 12.34
+    to_float("abc", default=-1.0)  # -1.0
+    ```
+
+Essas funções são úteis para garantir robustez e previsibilidade ao tratar dados vindos de múltiplas fontes, reduzindo erros e if/else espalhados pelo código.

biatoolkit-1.2.0/biatoolkit/sankhya_call.py

@@ -0,0 +1,433 @@
+"""
+biatoolkit.sankhya_call
+
+Classe utilitária para chamadas HTTP a serviços Sankhya (ou gateway),
+autenticando via JSESSIONID (cookie), preferencialmente obtido do header
+do runtime (AgentCore) via BiaUtil.
+
+Objetivo:
+- O dev do MCP Tool não precisa recriar autenticação, headers e session.
+- Basta chamar Sankhya(...).call_json(...) ou Sankhya.Call(...) (compat).
+
+Requisitos:
+- requests
+- urllib3 (vem com requests)
+- boto3 (já usado no biatoolkit.util)
+- mcp.server.fastmcp.FastMCP (se usar no server; opcional para modo local)
+
+Config via env (todas opcionais):
+- SANKHYA_TIMEOUT_CONNECT: default 3.05
+- SANKHYA_TIMEOUT_READ: default 12
+- SANKHYA_RETRIES_TOTAL: default 3
+- SANKHYA_RETRY_BACKOFF: default 0.5
+- SANKHYA_VERIFY_SSL: default "1"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+import os
+import json
+import logging
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+try:
+    # FastMCP só existe no runtime/servidor MCP. Em testes locais, pode faltar.
+    from mcp.server.fastmcp import FastMCP
+except Exception:  # pragma: no cover
+    FastMCP = Any  # type: ignore
+
+from .util import BiaUtil
+from .settings import BiaToolkitSettings
+
+
+logger = logging.getLogger(__name__)
+
+
+
+
+# Caminho fixo do serviço Sankhya
+SERVICE_PATH = "/mge/service.sbr"
+
+@dataclass(frozen=True)
+class SankhyaSettings:
+    """
+    Configurações específicas da integração Sankhya (timeouts, retries, SSL).
+    Não armazena base_url nem service_path.
+    """
+    timeout_connect: float
+    timeout_read: float
+    retries_total: int
+    retry_backoff: float
+    verify_ssl: bool
+
+    @staticmethod
+    def from_env() -> "SankhyaSettings":
+        def _f(name: str, default: float) -> float:
+            try:
+                return float(os.getenv(name, str(default)))
+            except Exception:
+                return default
+
+        def _i(name: str, default: int) -> int:
+            try:
+                return int(os.getenv(name, str(default)))
+            except Exception:
+                return default
+
+        def _b(name: str, default: bool) -> bool:
+            raw = os.getenv(name, "1" if default else "0").strip().lower()
+            return raw in ("1", "true", "yes", "y", "on")
+
+        return SankhyaSettings(
+            timeout_connect=_f("SANKHYA_TIMEOUT_CONNECT", 3.05),
+            timeout_read=_f("SANKHYA_TIMEOUT_READ", 12.0),
+            retries_total=_i("SANKHYA_RETRIES_TOTAL", 3),
+            retry_backoff=_f("SANKHYA_RETRY_BACKOFF", 0.5),
+            verify_ssl=_b("SANKHYA_VERIFY_SSL", True),
+        )
+
+def build_url(
+    *,
+    url: Optional[str] = None,
+    base_url: Optional[str] = None,
+    query: Optional[str] = None,
+) -> str:
+    """
+    Resolve URL final para chamada Sankhya.
+    - Se url for completa (http/https), usa como está.
+    - Se url for relativo, concatena base_url + url.
+    - Se não houver url, monta base_url + SERVICE_PATH.
+    - Se não houver base_url, lança erro.
+    """
+    if url and url.strip():
+        u = url.strip()
+        if u.startswith("http://") or u.startswith("https://"):
+            final = u
+        else:
+            if not base_url:
+                raise ValueError("base_url deve ser informado para url relativo.")
+            b = base_url.strip().rstrip("/")
+            if not u.startswith("/"):
+                u = "/" + u
+            final = b + u
+    else:
+        if not base_url:
+            raise ValueError("base_url deve ser informado para montar a URL Sankhya.")
+        b = base_url.strip().rstrip("/")
+        final = f"{b}{SERVICE_PATH}"
+    if query:
+        if "?" in final:
+            return f"{final}&{query.lstrip('?')}"
+        return f"{final}?{query.lstrip('?')}"
+    return final
+
+
+
+class SankhyaHTTPError(RuntimeError):
+    def __init__(self, message: str, status_code: Optional[int] = None, response_text: str = ""):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_text = response_text
+
+
+class Sankhya:
+    """
+    Classe responsável por integrar e chamar serviços da plataforma Sankhya.
+
+    Uso recomendado (em MCP server):
+        sk = Sankhya(mcp)
+        out = sk.load_view("BIA_VW_MB_RULES", "CODPROD_A = 123", fields="*")
+
+    Uso compatível com o scaffold (estático):
+        out = Sankhya.Call(jsessionID="...", payload={...})
+        # ou sem jsessionID se você passar mcp:
+        out = Sankhya.Call(jsessionID=None, mcp=mcp, payload={...})
+    """
+
+    def __init__(
+        self,
+        mcp: Optional[FastMCP] = None,
+        *,
+        toolkit_settings: Optional[BiaToolkitSettings] = None,
+        sankhya_settings: Optional[SankhyaSettings] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Inicializa a instância Sankhya.
+
+        Args:
+            mcp: Instância opcional do FastMCP para contexto do runtime.
+            toolkit_settings: Configurações globais do toolkit (opcional).
+            sankhya_settings: Configurações específicas da integração Sankhya (opcional).
+            default_headers: Headers HTTP padrão para todas as requisições (opcional).
+        """
+        self.mcp = mcp
+        self.toolkit_settings = toolkit_settings or BiaToolkitSettings.from_env()
+        self.sankhya_settings = sankhya_settings or SankhyaSettings.from_env()
+        self.default_headers = default_headers or {}
+
+        # Cria uma sessão HTTP com política de retries configurada
+        self._session = self._build_session()
+
+    # -------------------------
+    # Sessão HTTP + retries
+    # -------------------------
+    def _build_session(self) -> requests.Session:
+        """
+        Cria uma sessão HTTP configurada com política de retries.
+        Utiliza as configurações de timeout e retries do Sankhya.
+        """
+        s = requests.Session()
+
+        # Configura política de retries para falhas temporárias
+        retries = Retry(
+            total=max(0, int(self.sankhya_settings.retries_total)),
+            connect=max(0, int(self.sankhya_settings.retries_total)),
+            read=max(0, int(self.sankhya_settings.retries_total)),
+            backoff_factor=float(self.sankhya_settings.retry_backoff),
+            status_forcelist=(429, 500, 502, 503, 504),
+            allowed_methods=("POST", "GET"),
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retries)
+        s.mount("https://", adapter)
+        s.mount("http://", adapter)
+        return s
+
+    # -------------------------
+    # JSESSIONID resolve
+    # -------------------------
+    def _resolve_jsessionid(self, jsessionid: Optional[str] = None) -> str:
+        """
+        Resolve o JSESSIONID a ser usado na autenticação.
+        Prioriza o valor explícito, depois tenta extrair do header do runtime via BiaUtil.
+
+        Args:
+            jsessionid: Token de sessão explícito (opcional).
+
+        Returns:
+            str: JSESSIONID válido.
+
+        Raises:
+            ValueError: Se não for possível obter o JSESSIONID.
+        """
+        # 1) parâmetro explícito
+        if jsessionid and str(jsessionid).strip():
+            return str(jsessionid).strip()
+
+        # 2) header do runtime via BiaUtil (se tiver mcp)
+        if self.mcp is not None:
+            try:
+                util = BiaUtil(self.mcp, self.toolkit_settings)
+                h = util.get_header()
+                if h and getattr(h, "jsessionid", None):
+                    return str(h.jsessionid).strip()
+            except Exception as e:
+                logger.debug("Falha ao ler jsessionid do header via BiaUtil: %s", e)
+
+        raise ValueError(
+            "JSESSIONID ausente. Passe jsessionid explicitamente ou forneça 'mcp' para ler do header."
+        )
+
+
+    # -------------------------
+    # Métodos públicos
+    # -------------------------
+    def call_json(
+        self,
+        *,
+        payload: Optional[Dict[str, Any]] = None,
+        jsessionid: Optional[str] = None,
+        url: Optional[str] = None,
+        base_url: Optional[str] = None,
+        query: Optional[str] = None,
+        method: str = "POST",
+        extra_headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[Tuple[float, float]] = None,
+        raise_for_http_error: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Faz uma chamada HTTP ao serviço Sankhya e retorna JSON (ou erro detalhado).
+
+        Args:
+            payload: Corpo JSON (para POST). Pode ser None.
+            jsessionid: Se None, tenta resolver do header (mcp) automaticamente.
+            url: URL completa (se quiser ignorar base_url/service_path).
+            base_url: Base URL alternativa (opcional).
+            query: Querystring adicional (ex: "serviceName=...&outputType=json")
+            method: "POST" ou "GET"
+            extra_headers: Headers adicionais.
+            timeout: (connect, read) override
+            raise_for_http_error: Se True, lança SankhyaHTTPError em status != 200
+
+        Returns:
+            dict: Resposta JSON (ou {"raw_text": "..."} se não for JSON)
+        """
+        # Resolve o token de sessão (JSESSIONID)
+        sid = self._resolve_jsessionid(jsessionid)
+
+        # Monta a querystring, sempre incluindo o mgeSession
+        query_parts = []
+        if query:
+            query_parts.append(query.lstrip("?"))
+        query_parts.append(f"mgeSession={sid}")
+        final_query = "&".join(query_parts)
+
+        # Monta a URL final da requisição
+        final_url = build_url(url=url, query=final_query, base_url=base_url)
+        print("FINAL URL:", final_url)
+
+        # Monta os headers da requisição
+        headers: Dict[str, str] = {
+            "Content-Type": "application/json",
+            **self.default_headers,
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+
+        # Define o timeout da requisição
+        t = timeout or (self.sankhya_settings.timeout_connect, self.sankhya_settings.timeout_read)
+
+        # Realiza a chamada HTTP (GET ou POST)
+        if method.upper() == "GET":
+            resp = self._session.get(final_url, headers=headers, timeout=t, verify=self.sankhya_settings.verify_ssl)
+        else:
+            print("\n" + "="*40)
+            print("Sankhya POST Request:")
+            print(f"URL: {final_url}")
+            print(f"Headers: {json.dumps(headers, ensure_ascii=False, indent=2)}")
+            print(f"Payload: {json.dumps(payload, ensure_ascii=False, indent=2)}")
+            print(f"Timeout: {t}")
+            print(f"Verify SSL: {self.sankhya_settings.verify_ssl}")
+            print("="*40 + "\n")
+            resp = self._session.post(final_url, headers=headers, json=payload, timeout=t, verify=self.sankhya_settings.verify_ssl)
+
+        # Trata erros HTTP
+        if resp.status_code != 200:
+            msg = f"Falha HTTP {resp.status_code} ao chamar Sankhya/gateway."
+            if raise_for_http_error:
+                raise SankhyaHTTPError(msg, status_code=resp.status_code, response_text=resp.text)
+            return {"error": True, "status_code": resp.status_code, "message": msg, "response_text": resp.text}
+
+        # Tenta decodificar JSON; se não der, retorna texto puro
+        try:
+            return resp.json()
+        except Exception:
+            return {"raw_text": resp.text}
+
+    def load_view(
+        self,
+        view_name: str,
+        where_sql: str,
+        *,
+        fields: str = "*",
+        jsessionid: Optional[str] = None,
+        url: Optional[str] = None,
+        base_url: Optional[str] = None,
+        output_type: str = "json",
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Helper para o CRUDServiceProvider.loadView (mge/service.sbr).
+        Monta o payload e a querystring automaticamente para facilitar consultas a views Sankhya.
+
+        Args:
+            view_name: Nome da view no Sankhya.
+            where_sql: Cláusula WHERE (string).
+            fields: Campos a retornar (string).
+            jsessionid: Se None, pega do header (mcp).
+            url: URL completa opcional (override).
+            base_url: Base URL alternativa (opcional).
+            output_type: "json" (default).
+            extra_headers: Headers adicionais.
+
+        Returns:
+            dict: Resposta da consulta à view.
+        """
+        # Monta a querystring para o serviço
+        query = f"serviceName=CRUDServiceProvider.loadView&outputType={output_type}"
+
+        # Monta o corpo do payload conforme esperado pelo serviço
+        body = {
+            "serviceName": "CRUDServiceProvider.loadView",
+            "requestBody": {
+                "query": {
+                    "viewName": view_name,
+                    "where": {"$": where_sql},
+                    "fields": {"field": {"$": fields}},
+                }
+            },
+        }
+        
+
+        util = BiaUtil(self.mcp)
+        # Se base_url não foi fornecido, tenta obter do util.get_header().current_host
+        if not base_url:
+            base_url = util.get_header().current_host
+            if not base_url:
+                raise ValueError("base_url não definida e não foi possível obter current_host do header.")
+
+        return self.call_json(
+            payload=body,
+            jsessionid=jsessionid,
+            url=url,
+            base_url=base_url,
+            query=query,
+            method="POST",
+            extra_headers=extra_headers,
+        )
+
+    # -------------------------
+    # Compat com scaffold
+    # -------------------------
+    @staticmethod
+    def Call(
+        jsessionID: Optional[str] = None,
+        *,
+        payload: Optional[Dict[str, Any]] = None,
+        mcp: Optional[FastMCP] = None,
+        url: Optional[str] = None,
+        base_url: Optional[str] = None,
+        query: Optional[str] = None,
+        method: str = "POST",
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Optional[dict]:
+        """
+        Método estático compatível com o scaffold original.
+        Permite chamada rápida ao serviço Sankhya sem instanciar manualmente a classe.
+
+        Exemplos de uso:
+            Sankhya.Call(jsessionID="...", payload={...}, query="serviceName=...&outputType=json")
+            Sankhya.Call(jsessionID=None, mcp=mcp, payload={...}, query="...")
+
+        Args:
+            jsessionID: Token de sessão JSESSIONID (opcional).
+            payload: Corpo da requisição (dict).
+            mcp: Instância opcional do FastMCP para contexto do runtime.
+            url: URL completa (opcional).
+            base_url: Base URL alternativa (opcional).
+            query: Querystring adicional (opcional).
+            method: "POST" ou "GET".
+            extra_headers: Headers adicionais.
+
+        Returns:
+            dict: Resposta do serviço ou lança erro se HTTP != 200.
+        """
+        sk = Sankhya(mcp=mcp)
+        return sk.call_json(
+            payload=payload,
+            jsessionid=jsessionID,
+            url=url,
+            base_url=base_url,
+            query=query,
+            method=method,
+            extra_headers=extra_headers,
+        )
+
+
+__all__ = ["Sankhya", "SankhyaSettings", "SankhyaHTTPError"]

biatoolkit-1.2.0/biatoolkit/test_sankhya.py

@@ -0,0 +1,39 @@
+import sys
+import os
+#sys.path.insert(0, os.path.abspath(os.path.dirname(__file__) + '/..'))
+from biatoolkit.sankhya_call import Sankhya, SankhyaHTTPError
+import json
+
+# Opcional: não depende mais disso, mas pode deixar.
+os.environ.setdefault("SANKHYA_SERVICE_PATH", "/mge/service.sbr")
+
+# ⚠️ COLE AQUI seu JSESSIONID em UMA LINHA (sem ENTER no meio)
+REAL = "CrK0qgoMYcnfZsURMi7iarpFKWSVqS-qO3HWMiu8.sankhya-w-78598f67f-n7mcp"
+
+if not REAL or REAL == "COLE_SEU_JSESSIONID_AQUI":
+    raise SystemExit("Cole seu JSESSIONID na variável REAL (uma linha só) e rode: python -m biatoolkit.test_sankhya")
+
+# Base URL do ambiente correto (o novo)
+BASE_URL = "https://ecossistema2.sankhyacloud.com.br"
+
+sk = Sankhya()
+
+try:
+    out = sk.load_view(
+        "BIA_VW_MB_RULES",
+        "1=1",
+        fields="COMPLDESC_A,COMPLDESC_B,CONFIDENCE_A_B,LIFT_A_B,CNT_AB,DISPONIVEL_B,DTGERACAO",
+        jsessionid=REAL,
+        base_url=BASE_URL,  # <-- NOVO: injeta a base url aqui
+        # url="/mge/service.sbr",  # opcional: se quiser passar só o path
+        # url="https://ecossistema2.sankhyacloud.com.br/mge/service.sbr",  # opcional: URL completa
+    )
+    print("OK! Resposta (top-level keys):", list(out.keys()))
+    print(out)
+    if isinstance(out, dict):
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+
+except SankhyaHTTPError as e:
+    print("HTTP ERROR:", e.status_code)
+    print("BODY (primeiros 500 chars):")
+    print((e.response_text or "")[:500])

{biatoolkit-1.1.1 → biatoolkit-1.2.0}/biatoolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.1.1
+Version: 1.2.0
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -348,4 +348,145 @@ O método `get_parameter(parameter_name: str)` busca o parâmetro informado em d
 - Um arquivo `.env` para testes locais.
 - No cofre de segredos do Bia Agent Builder para usar em ambiente produtivo. 
 
-Assim, o **MESMO CÓDIGO** do Servidor MCP pode ser executado em ambos os ambientes.
+
+---
+
+## Validação e Coerção de Dados
+
+O Bia Toolkit oferece funções utilitárias para normalização, sanitização e coerção de dados, facilitando o consumo seguro de entradas vindas de APIs, headers, payloads e integrações legadas.
+
+
+### Validação de Dados (`biatoolkit.validation.validation`)
+
+Utilize a classe **BiaValidation** para acessar as funções de validação de forma padronizada:
+
+- **BiaValidation.parse_int_list(value, dedupe=True, keep_order=True)**
+    - Normaliza um valor arbitrário em uma lista de inteiros.
+    - Suporta: None, int, str (extrai números), list/tuple (recursivo).
+    - Ignora valores inválidos.
+    - Deduplica e mantém ordem por padrão.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.validation import BiaValidation
+        BiaValidation.parse_int_list("SKU=300231 x2")  # [300231, 2]
+        BiaValidation.parse_int_list([1, 2, 1, 3], dedupe=False)  # [1, 2, 1, 3]
+        ```
+
+- **BiaValidation.sanitize_like(value, max_len=80, upper=True)**
+    - Sanitiza texto para uso seguro em filtros LIKE/search SQL.
+    - Remove caracteres fora da allowlist, limita tamanho, escapa aspas simples, %, _ e normaliza espaços.
+    - Converte para maiúsculas por padrão.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.validation import BiaValidation
+        BiaValidation.sanitize_like("O'Reilly")  # "O''REILLY"
+        BiaValidation.sanitize_like("100%_OK")   # "100\\%\\_OK"
+        ```
+
+
+### Coerção de Dados (`biatoolkit.validation.coercion`)
+
+Utilize a classe **BiaCoercion** para acessar as funções de coerção de forma padronizada:
+
+- **BiaCoercion.ensure_list(value)**
+    - Garante que o valor seja retornado como lista.
+    - None → [], list → list, tuple/set → list, dict → [dict], outro → [valor].
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.ensure_list(None)  # []
+        BiaCoercion.ensure_list({"a": 1})  # [{"a": 1}]
+        BiaCoercion.ensure_list(5)  # [5]
+        ```
+
+- **BiaCoercion.unwrap_dollar_value(value)**
+    - Desembrulha valores no formato {"$": ...} (comum em integrações legadas).
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.unwrap_dollar_value({"$": 123})  # 123
+        BiaCoercion.unwrap_dollar_value("abc")  # "abc"
+        ```
+
+- **BiaCoercion.to_int(value, default=0)**
+    - Converte valor para int de forma segura.
+    - None, "", bool, NaN/inf → default.
+    - Aceita strings numéricas, floats (trunca), etc.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.to_int(" 42 ")  # 42
+        BiaCoercion.to_int(None, default=-1)  # -1
+        ```
+
+- **BiaCoercion.to_float(value, default=0.0)**
+    - Converte valor para float de forma segura.
+    - None, "", bool, NaN/inf → default.
+    - Aceita strings com vírgula decimal.
+    - Exemplo:
+        ```python
+        from biatoolkit.validation.coercion import BiaCoercion
+        BiaCoercion.to_float("12,34")  # 12.34
+        BiaCoercion.to_float("abc", default=-1.0)  # -1.0
+        ```
+
+
+Essas funções são úteis para garantir robustez e previsibilidade ao tratar dados vindos de múltiplas fontes, reduzindo erros e if/else espalhados pelo código.
+
+---
+
+## Integração com Sankhya (`biatoolkit.sankhya_call`)
+
+
+O Bia Toolkit oferece integração pronta para consumo de serviços HTTP da plataforma Sankhya (ou gateway), com autenticação via JSESSIONID e configuração de timeouts/retries via variáveis de ambiente.
+
+### Objetivo
+
+- Facilitar chamadas autenticadas a serviços Sankhya sem que o desenvolvedor precise lidar com autenticação, headers ou gerenciamento de sessão HTTP.
+- Fornecer métodos prontos para chamadas genéricas (`call_json`) e para consultas a views (`load_view`).
+- Permitir uso estático compatível com scaffolds legados via `Sankhya.Call(...)`.
+
+### Configuração
+
+- O caminho do serviço (`/mge/service.sbr`) é fixo no toolkit.
+- O parâmetro `base_url` é obrigatório e pode ser passado explicitamente ou extraído automaticamente do header do runtime (`current_host` via `BiaUtil`).
+- Não existe mais configuração via variável de ambiente para base_url ou service_path.
+- As variáveis de ambiente opcionais são apenas para timeout, retries e SSL:
+    - `SANKHYA_TIMEOUT_CONNECT`: timeout de conexão (default: 3.05)
+    - `SANKHYA_TIMEOUT_READ`: timeout de leitura (default: 12)
+    - `SANKHYA_RETRIES_TOTAL`: número de tentativas em falha (default: 3)
+    - `SANKHYA_RETRY_BACKOFF`: backoff entre tentativas (default: 0.5)
+    - `SANKHYA_VERIFY_SSL`: se valida SSL (default: "1")
+
+### Principais classes e métodos
+
+- **SankhyaSettings**: Dataclass de configuração de timeouts/retries/SSL. Use `SankhyaSettings.from_env()` para obter as configurações do ambiente.
+- **Sankhya**: Classe principal de integração. Permite instanciar com contexto MCP (`FastMCP`) ou usar métodos estáticos.
+    - `call_json(...)`: Realiza chamada HTTP autenticada, retorna JSON.
+    - `load_view(...)`: Helper para consultas a views Sankhya (`CRUDServiceProvider.loadView`).
+    - `Call(...)`: Método estático compatível com scaffolds legados.
+- **SankhyaHTTPError**: Exceção lançada em caso de erro HTTP (status != 200), contendo status_code e response_text.
+
+### Exemplo de uso (instanciado)
+
+```python
+from biatoolkit.sankhya_call import Sankhya
+sk = Sankhya(mcp=mcp)
+result = sk.load_view("BIA_VW_MB_RULES", "CODPROD_A = 123", fields="*")
+# O base_url será extraído automaticamente do header do runtime (current_host)
+```
+
+### Exemplo de uso (estático)
+
+```python
+from biatoolkit.sankhya_call import Sankhya
+result = Sankhya.Call(jsessionID="...", payload={...}, base_url="https://meu.sankhya.com.br", query="serviceName=...&outputType=json")
+```
+
+### Observações
+
+- O JSESSIONID pode ser passado explicitamente ou extraído automaticamente do header do runtime (se rodando em MCP Server).
+- O método `load_view` facilita consultas a views Sankhya, montando o payload e a querystring automaticamente, e resolve o base_url do header se não for passado.
+- O método `call_json` permite chamadas genéricas a qualquer serviço Sankhya, com controle total sobre headers, método HTTP, payload e querystring, mas exige base_url explícito se não estiver em contexto MCP.
+
+---

{biatoolkit-1.1.1 → biatoolkit-1.2.0}/biatoolkit.egg-info/SOURCES.txt

@@ -2,7 +2,9 @@ README.md
 setup.py
 biatoolkit/__init__.py
 biatoolkit/basic_client.py
+biatoolkit/sankhya_call.py
 biatoolkit/settings.py
+biatoolkit/test_sankhya.py
 biatoolkit/util.py
 biatoolkit.egg-info/PKG-INFO
 biatoolkit.egg-info/SOURCES.txt

{biatoolkit-1.1.1 → biatoolkit-1.2.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='biatoolkit',
-    version='1.1.1',
+    version='1.2.0',
     packages=find_packages(),
     install_requires=[],
     author='Bia Platform Team',