biatoolkit 1.2.0__tar.gz → 1.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.2.0
+Version: 1.2.2
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -462,9 +462,58 @@ O Bia Toolkit oferece integração pronta para consumo de serviços HTTP da plat
 
 - **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.
+    - `call_json(...)`: Realiza chamada HTTP autenticada, retorna JSON. Veja detalhes dos parâmetros abaixo.
+    - `load_view(...)`: Helper para consultas a views Sankhya (`CRUDServiceProvider.loadView`). Veja detalhes dos parâmetros abaixo.
+    - `Call(...)`: Método estático compatível com scaffolds legados. Veja detalhes dos parâmetros abaixo.
+### Parâmetros dos métodos principais
+
+#### `call_json`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| payload           | Não         | Dicionário enviado como corpo da requisição (POST). Pode ser None. |
+| jsessionid        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| url               | Não         | URL completa para chamada. Se informado, ignora base_url. |
+| base_url          | Sim*        | Base URL do serviço Sankhya (ex: https://meu.sankhya.com.br). Obrigatório se não estiver em contexto MCP (header). |
+| query             | Não         | Querystring adicional (ex: serviceName=...&outputType=json). |
+| method            | Não         | "POST" (default) ou "GET". |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+| timeout           | Não         | Tupla (connect, read) para sobrescrever timeout padrão. |
+| raise_for_http_error | Não      | Se True (default), lança SankhyaHTTPError em erro HTTP. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) se disponível. Caso contrário, será obrigatório.
+
+#### `load_view`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| view_name         | Sim         | Nome da view no Sankhya. |
+| where_sql         | Sim         | Cláusula WHERE (string). |
+| fields            | Não         | Campos a retornar (string). Default: "*". |
+| jsessionid        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| url               | Não         | URL completa opcional (override). |
+| base_url          | Não*        | Base URL do serviço Sankhya. Se não informado, tenta extrair do header do runtime (current_host). |
+| output_type       | Não         | "json" (default). |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) via BiaUtil. Caso não consiga, lança erro.
+
+#### `Call`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| jsessionID        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| payload           | Não         | Dicionário enviado como corpo da requisição. |
+| mcp               | Não         | Instância opcional do FastMCP para contexto do runtime. |
+| url               | Não         | URL completa (opcional). |
+| base_url          | Sim*        | Base URL do serviço Sankhya. Obrigatório se não estiver em contexto MCP (header). |
+| query             | Não         | Querystring adicional (opcional). |
+| method            | Não         | "POST" (default) ou "GET". |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) se disponível. Caso contrário, será obrigatório.
+
+**Resumo:** Sempre que possível, o toolkit resolve automaticamente base_url e jsessionid do contexto MCP (headers). Se não estiver rodando em MCP, passe base_url explicitamente.
 - **SankhyaHTTPError**: Exceção lançada em caso de erro HTTP (status != 200), contendo status_code e response_text.
 
 ### Exemplo de uso (instanciado)

{biatoolkit-1.2.0 → biatoolkit-1.2.2}/biatoolkit/sankhya_call.py

@@ -364,13 +364,15 @@ class Sankhya:
             },
         }
         
-
-        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.")
+            util = BiaUtil(self.mcp)
+            header = util.get_header()
+            base_url = getattr(header, "current_host", None)
+
+        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,

biatoolkit-1.2.2/biatoolkit/validation/coercion.py

@@ -0,0 +1,175 @@
+# biatoolkit/validation/coercion.py
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Optional
+import math
+
+
+def ensure_list(value: Any) -> list:
+    """
+    Normaliza um valor para sempre retornar uma lista.
+
+    Regras:
+    - None -> []
+    - list -> a própria lista
+    - tuple/set -> list(value)
+    - dict (ou Mapping) -> [value]  (não "explode" dict em chaves)
+    - qualquer outro -> [value]
+
+    Por que existe:
+    - Muitas APIs retornam ora um item único (dict), ora uma lista.
+    - Este helper padroniza o consumo e reduz if/else espalhado.
+
+    Args:
+        value: qualquer valor.
+
+    Returns:
+        list: lista normalizada.
+    """
+    if value is None:
+        return []
+
+    if isinstance(value, list):
+        return value
+
+    if isinstance(value, (tuple, set)):
+        return list(value)
+
+    # Dict/Mapping deve ser tratado como item único, não iterável de chaves.
+    if isinstance(value, Mapping):
+        return [value]
+
+    return [value]
+
+
+def unwrap_dollar_value(value: Any) -> Any:
+    """
+    "Desembrulha" valores no formato {"$": "..."} (comum em integrações legadas).
+
+    Exemplo:
+        {"$": "123"} -> "123"
+        {"$": 123} -> 123
+
+    Se não for dict com a chave "$", retorna o valor original.
+
+    Args:
+        value: valor de entrada.
+
+    Returns:
+        Any: valor desembrulhado ou original.
+    """
+    if isinstance(value, dict) and "$" in value:
+        return value.get("$")
+    return value
+
+
+def to_int(value: Any, default: int = 0) -> int:
+    """
+    Converte um valor para int de forma segura.
+
+    Regras:
+    - None / "" -> default
+    - strings com espaços são aceitas (" 12 ")
+    - strings numéricas com sinal são aceitas ("-3")
+    - floats numéricos -> int(value) (trunca)
+    - NaN/inf -> default
+
+    Obs:
+    - Não tenta "extrair número do meio do texto" (isso é responsabilidade
+      de parse específico, ex: parse_int_list).
+
+    Args:
+        value: valor a converter.
+        default: fallback.
+
+    Returns:
+        int: convertido ou default.
+    """
+    try:
+        if value is None:
+            return default
+
+        if isinstance(value, bool):
+            # Evita True->1 / False->0 de forma "surpresa"
+            return default
+
+        if isinstance(value, str):
+            s = value.strip()
+            if s == "":
+                return default
+            return int(s)
+
+        if isinstance(value, float):
+            if math.isnan(value) or math.isinf(value):
+                return default
+            return int(value)
+
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def to_float(value: Any, default: float = 0.0) -> float:
+    """
+    Converte um valor para float de forma segura.
+
+    Regras:
+    - None / "" -> default
+    - aceita strings com vírgula decimal ("12,34")
+    - NaN/inf -> default
+
+    Args:
+        value: valor a converter.
+        default: fallback.
+
+    Returns:
+        float: convertido ou default.
+    """
+    try:
+        if value is None:
+            return default
+
+        if isinstance(value, bool):
+            return default
+
+        if isinstance(value, str):
+            s = value.strip()
+            if s == "":
+                return default
+            s = s.replace(",", ".")
+            v = float(s)
+        else:
+            v = float(value)
+
+        if math.isnan(v) or math.isinf(v):
+            return default
+
+        return v
+    except (TypeError, ValueError):
+        return default
+
+
+
+
+# Classe fachada para coerção
+class BiaCoercion:
+    """
+    Fachada estática para funções de coerção do Bia Toolkit.
+    Permite referenciar e utilizar as utilidades de coerção de forma padronizada.
+    """
+    @staticmethod
+    def ensure_list(*args, **kwargs):
+        return ensure_list(*args, **kwargs)
+
+    @staticmethod
+    def unwrap_dollar_value(*args, **kwargs):
+        return unwrap_dollar_value(*args, **kwargs)
+
+    @staticmethod
+    def to_int(*args, **kwargs):
+        return to_int(*args, **kwargs)
+
+    @staticmethod
+    def to_float(*args, **kwargs):
+        return to_float(*args, **kwargs)

biatoolkit-1.2.2/biatoolkit/validation/validation.py

@@ -0,0 +1,135 @@
+# biatoolkit/validation.py
+
+from typing import Any, Iterable
+import re
+
+
+def parse_int_list(
+    value: Any,
+    *,
+    dedupe: bool = True,
+    keep_order: bool = True,
+) -> list[int]:
+    """
+    Normaliza um valor arbitrário em uma lista de inteiros.
+
+    Casos suportados:
+    - None -> []
+    - int -> [int]
+    - str -> extrai números (ex: "100, 200" / "SKU=300231 x2")
+    - list/tuple -> processa cada item recursivamente
+
+    Comportamento:
+    - Ignora valores inválidos
+    - Deduplica por padrão
+    - Mantém a ordem de aparição por padrão
+
+    Args:
+        value: Valor de entrada (None, int, str, list, etc.)
+        dedupe: Remove valores duplicados.
+        keep_order: Mantém a ordem original dos valores.
+
+    Returns:
+        list[int]: Lista normalizada de inteiros.
+    """
+    if value is None:
+        return []
+
+    # Normaliza para iterável
+    if isinstance(value, (list, tuple, set)):
+        raw: Iterable[Any] = value
+    else:
+        raw = [value]
+
+    numbers: list[int] = []
+
+    for item in raw:
+        if item is None:
+            continue
+
+        # Inteiro direto
+        if isinstance(item, int):
+            numbers.append(item)
+            continue
+
+        # String ou outros tipos
+        text = str(item)
+        matches = re.findall(r"\d+", text)
+        for m in matches:
+            try:
+                numbers.append(int(m))
+            except ValueError:
+                continue
+
+    if not dedupe:
+        return numbers
+
+    if keep_order:
+        seen = set()
+        ordered: list[int] = []
+        for n in numbers:
+            if n not in seen:
+                seen.add(n)
+                ordered.append(n)
+        return ordered
+
+    return list(set(numbers))
+
+def sanitize_like(
+    value: str,
+    *,
+    max_len: int = 80,
+    upper: bool = True,
+) -> str:
+    """
+    Sanitiza um texto para uso seguro em filtros do tipo LIKE/search.
+
+    Regras aplicadas:
+    - Remove caracteres fora de uma allowlist básica
+    - Limita o tamanho do texto
+    - Escapa aspas simples
+    - Escapa curingas comuns (% e _)
+    - Converte para UPPER por padrão
+
+    Args:
+        value: Texto de entrada.
+        max_len: Tamanho máximo permitido.
+        upper: Converte o texto final para maiúsculas.
+
+    Returns:
+        str: Texto sanitizado.
+    """
+    if not value:
+        return ""
+
+    # Normaliza e corta tamanho
+    text = str(value).strip()[:max_len]
+
+    # Allowlist simples (letras, números, acentos, espaço e alguns símbolos, incluindo ', %, _)
+    # Mantém ', %, _ para escapá-los depois
+    text = re.sub(r"[^0-9A-Za-zÀ-ÿ\s\-\(\)\./'_%]", " ", text)
+
+    # Escapes básicos
+    text = text.replace("'", "''")
+    text = text.replace("%", r"\%" ).replace("_", r"\_")
+
+    # Normaliza espaços
+    text = re.sub(r"\s+", " ", text).strip()
+
+
+    return text.upper() if upper else text
+
+
+# Classe fachada para validação
+class BiaValidation:
+    """
+    Fachada estática para funções de validação do Bia Toolkit.
+    Permite referenciar e utilizar as utilidades de validação de forma padronizada.
+    """
+    @staticmethod
+    def parse_int_list(*args, **kwargs):
+        return parse_int_list(*args, **kwargs)
+
+    @staticmethod
+    def sanitize_like(*args, **kwargs):
+        return sanitize_like(*args, **kwargs)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biatoolkit
-Version: 1.2.0
+Version: 1.2.2
 Summary: Biblioteca para desenvolvedores que utilizam o BiaAgentBuilder
 Author: Bia Platform Team
 Author-email: data.platform@sankhya.com.br
@@ -462,9 +462,58 @@ O Bia Toolkit oferece integração pronta para consumo de serviços HTTP da plat
 
 - **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.
+    - `call_json(...)`: Realiza chamada HTTP autenticada, retorna JSON. Veja detalhes dos parâmetros abaixo.
+    - `load_view(...)`: Helper para consultas a views Sankhya (`CRUDServiceProvider.loadView`). Veja detalhes dos parâmetros abaixo.
+    - `Call(...)`: Método estático compatível com scaffolds legados. Veja detalhes dos parâmetros abaixo.
+### Parâmetros dos métodos principais
+
+#### `call_json`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| payload           | Não         | Dicionário enviado como corpo da requisição (POST). Pode ser None. |
+| jsessionid        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| url               | Não         | URL completa para chamada. Se informado, ignora base_url. |
+| base_url          | Sim*        | Base URL do serviço Sankhya (ex: https://meu.sankhya.com.br). Obrigatório se não estiver em contexto MCP (header). |
+| query             | Não         | Querystring adicional (ex: serviceName=...&outputType=json). |
+| method            | Não         | "POST" (default) ou "GET". |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+| timeout           | Não         | Tupla (connect, read) para sobrescrever timeout padrão. |
+| raise_for_http_error | Não      | Se True (default), lança SankhyaHTTPError em erro HTTP. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) se disponível. Caso contrário, será obrigatório.
+
+#### `load_view`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| view_name         | Sim         | Nome da view no Sankhya. |
+| where_sql         | Sim         | Cláusula WHERE (string). |
+| fields            | Não         | Campos a retornar (string). Default: "*". |
+| jsessionid        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| url               | Não         | URL completa opcional (override). |
+| base_url          | Não*        | Base URL do serviço Sankhya. Se não informado, tenta extrair do header do runtime (current_host). |
+| output_type       | Não         | "json" (default). |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) via BiaUtil. Caso não consiga, lança erro.
+
+#### `Call`
+
+| Parâmetro         | Obrigatório | Descrição |
+|-------------------|-------------|-----------|
+| jsessionID        | Não         | Token de sessão JSESSIONID. Se não informado, tenta extrair do header do runtime (via MCP/BiaUtil). |
+| payload           | Não         | Dicionário enviado como corpo da requisição. |
+| mcp               | Não         | Instância opcional do FastMCP para contexto do runtime. |
+| url               | Não         | URL completa (opcional). |
+| base_url          | Sim*        | Base URL do serviço Sankhya. Obrigatório se não estiver em contexto MCP (header). |
+| query             | Não         | Querystring adicional (opcional). |
+| method            | Não         | "POST" (default) ou "GET". |
+| extra_headers     | Não         | Dicionário de headers adicionais. |
+
+*Se não passar base_url, o método tentará extrair automaticamente do header do runtime (MCP) se disponível. Caso contrário, será obrigatório.
+
+**Resumo:** Sempre que possível, o toolkit resolve automaticamente base_url e jsessionid do contexto MCP (headers). Se não estiver rodando em MCP, passe base_url explicitamente.
 - **SankhyaHTTPError**: Exceção lançada em caso de erro HTTP (status != 200), contendo status_code e response_text.
 
 ### Exemplo de uso (instanciado)

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

@@ -11,4 +11,7 @@ biatoolkit.egg-info/SOURCES.txt
 biatoolkit.egg-info/dependency_links.txt
 biatoolkit.egg-info/top_level.txt
 biatoolkit/schema/__init__.py
-biatoolkit/schema/header.py
+biatoolkit/schema/header.py
+biatoolkit/validation/__init__.py
+biatoolkit/validation/coercion.py
+biatoolkit/validation/validation.py

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

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