forlogic-core 2.2.8 → 2.3.0

package/dist/audit-trail/mind-map/utils/nodeOps.d.ts

@@ -0,0 +1,66 @@
+import type { MindMapNode } from '../types';
+/**
+ * Gera um id curto e único o suficiente para uso local em árvores de mapas mentais.
+ */
+export declare function generateNodeId(): string;
+/**
+ * Cria um novo `MindMapNode` com defaults seguros.
+ */
+export declare function createMindMapNode(text: string, partial?: Partial<MindMapNode>): MindMapNode;
+/**
+ * Procura um nó pelo id e retorna o nó + seu pai (ou null).
+ */
+export declare function findNode(root: MindMapNode, id: string): {
+    node: MindMapNode;
+    parent: MindMapNode | null;
+} | null;
+/**
+ * Retorna true se `ancestorId` está na cadeia ancestral de `descendantId`.
+ */
+export declare function isAncestor(root: MindMapNode, ancestorId: string, descendantId: string): boolean;
+/**
+ * Atualiza um nó por id retornando uma nova árvore.
+ */
+export declare function updateNode(root: MindMapNode, id: string, updater: (n: MindMapNode) => MindMapNode): MindMapNode;
+/**
+ * Adiciona um filho a um nó. Para filhos diretos da raiz, escolhe automaticamente
+ * o lado com menos nós (balanceia ramos).
+ */
+export declare function addChild(root: MindMapNode, parentId: string, text: string): {
+    root: MindMapNode;
+    newId: string;
+};
+/**
+ * Adiciona um irmão (mesmo pai) logo após o nó referência.
+ */
+export declare function addSibling(root: MindMapNode, nodeId: string, text: string): {
+    root: MindMapNode;
+    newId: string;
+};
+/**
+ * Remove um nó (e descendentes). Não permite remover a raiz.
+ */
+export declare function removeNode(root: MindMapNode, id: string): {
+    root: MindMapNode;
+    nextSelectedId: string | null;
+};
+/**
+ * Move um nó para um novo pai. Retorna a árvore inalterada se o destino for
+ * o próprio nó ou um descendente (evita ciclo).
+ */
+export declare function moveNode(root: MindMapNode, id: string, newParentId: string): MindMapNode;
+/**
+ * Alterna `collapsed` em um nó.
+ */
+export declare function toggleCollapsed(root: MindMapNode, id: string): MindMapNode;
+/**
+ * Define `collapsed` em todos os nós com filhos.
+ */
+export declare function setCollapsedAll(root: MindMapNode, collapsed: boolean): MindMapNode;
+/**
+ * Retorna lista linear (DFS) de todos os nós + pai, respeitando collapsed.
+ */
+export declare function flattenVisible(root: MindMapNode): Array<{
+    node: MindMapNode;
+    parent: MindMapNode | null;
+}>;

package/dist/audit-trail/mind-map/utils/serialize.d.ts

@@ -0,0 +1,10 @@
+import type { MindMapNode } from '../types';
+/**
+ * Serializa a árvore como JSON formatado.
+ */
+export declare function exportMindMap(root: MindMapNode): string;
+/**
+ * Desserializa uma string JSON em um `MindMapNode` validado.
+ * Lança em caso de JSON inválido ou estrutura incompatível.
+ */
+export declare function importMindMap(json: string): MindMapNode;

package/dist/audit-trail/modules/softwaresMap.d.ts

@@ -0,0 +1,4 @@
+/** Mapa estático alias → id dos softwares da plataforma Qualiex.
+ *  Fonte: GET /api/common/v1/softwares (raramente muda).
+ *  Se um novo módulo for adicionado à plataforma, basta incluir aqui. */
+export declare const SOFTWARES_MAP: Record<string, number>;

package/dist/audit-trail/places/components/ManageAccessModal.d.ts

@@ -0,0 +1,11 @@
+export interface ManageAccessModalProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    placeId: string;
+    placeName: string;
+    onMakeManager?: (userId: string, placeId: string) => void | Promise<void>;
+    onMakeMembers?: (userIds: string[], placeId: string) => void | Promise<void>;
+    currentManagerId?: string;
+    currentMemberIds?: string[];
+}
+export declare function ManageAccessModal({ open, onOpenChange, placeId, placeName, onMakeManager, onMakeMembers, currentManagerId, currentMemberIds }: ManageAccessModalProps): import("react/jsx-runtime").JSX.Element;

package/dist/audit-trail/places/components/PlaceCard.d.ts

@@ -0,0 +1,12 @@
+import { Place } from '../types';
+export interface PlaceCardProps {
+    place: Place;
+    level?: number;
+    manageAccessConfig?: {
+        onMakeManager?: (userId: string, placeId: string) => void | Promise<void>;
+        onMakeMembers?: (userIds: string[], placeId: string) => void | Promise<void>;
+        getCurrentManagerId?: (placeId: string) => string | undefined;
+        getCurrentMemberIds?: (placeId: string) => string[] | undefined;
+    };
+}
+export declare function PlaceCard({ place, level, manageAccessConfig }: PlaceCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/audit-trail/places/components/PlacesList.d.ts

@@ -0,0 +1,12 @@
+import { Place } from '../types';
+export interface PlacesListProps {
+    places: Place[];
+    isLoading: boolean;
+    manageAccessConfig?: {
+        onMakeManager?: (userId: string, placeId: string) => void | Promise<void>;
+        onMakeMembers?: (userIds: string[], placeId: string) => void | Promise<void>;
+        getCurrentManagerId?: (placeId: string) => string | undefined;
+        getCurrentMemberIds?: (placeId: string) => string[] | undefined;
+    };
+}
+export declare function PlacesList({ places, isLoading, manageAccessConfig }: PlacesListProps): import("react/jsx-runtime").JSX.Element;

package/dist/audit-trail/places/index.d.ts

@@ -0,0 +1,8 @@
+export { PlacesList } from './components/PlacesList';
+export { PlaceCard } from './components/PlaceCard';
+export { ManageAccessModal } from './components/ManageAccessModal';
+export { placeService } from './services/PlaceService';
+export type { Place } from './types';
+export type { ManageAccessModalProps } from './components/ManageAccessModal';
+export type { PlacesListProps } from './components/PlacesList';
+export type { PlaceCardProps } from './components/PlaceCard';

package/dist/audit-trail/places/services/PlaceService.d.ts

@@ -0,0 +1,9 @@
+import { Place } from '../types';
+declare class PlaceService {
+    private get baseUrl();
+    private makeApiCall;
+    private buildHierarchy;
+    getPlaces(alias: string, companyId: string): Promise<Place[]>;
+}
+export declare const placeService: PlaceService;
+export {};

package/dist/audit-trail/places/types.d.ts

@@ -0,0 +1,10 @@
+export interface Place {
+    id: string;
+    name: string;
+    usersCount?: number;
+    hasChild?: boolean;
+    isActive?: boolean;
+    parentId?: string;
+    parentName?: string;
+    subPlaces?: Place[];
+}

package/dist/audit-trail/providers/CoreProviders.d.ts

@@ -0,0 +1,107 @@
+import { ReactNode } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { ModuleAccessGuardProps } from '../components/modules';
+import type { ClarityMode } from '../integrations/clarity/types';
+import { type BackendMode } from '../config/backend';
+/**
+ * Mapa de traduções por idioma para o namespace 'app' do projeto consumidor.
+ *
+ * @example
+ * ```ts
+ * const appTranslations = {
+ *   'pt-BR': { greeting: 'Olá' },
+ *   'en-US': { greeting: 'Hello' },
+ * };
+ * ```
+ */
+export type AppTranslationsMap = Record<string, Record<string, string>>;
+/**
+ * Props for CoreProviders component
+ */
+export interface CoreProvidersProps {
+    /**
+     * Child components to be wrapped by providers
+     */
+    children: ReactNode;
+    /**
+     * Optional custom QueryClient instance
+     * If not provided, a default QueryClient will be created
+     */
+    queryClient?: QueryClient;
+    /**
+     * Alias do módulo do projeto consumidor.
+     * Usado pelo hook useModuleAccess para verificar automaticamente
+     * se o usuário tem acesso ao módulo deste projeto.
+     * Quando configurado, o ModuleAccessGuard bloqueia automaticamente
+     * o acesso caso o usuário não tenha permissão.
+     *
+     * @example "performance" | "suppliers" | "occurrences" | "audit"
+     */
+    moduleAlias?: string;
+    /**
+     * Props opcionais para o ModuleAccessGuard.
+     * Permite configurar módulos contratados, callbacks e URLs.
+     */
+    moduleAccessGuardProps?: Omit<ModuleAccessGuardProps, 'children'>;
+    /**
+     * Traduções do projeto consumidor, organizadas por idioma.
+     * Injetadas no namespace 'app' do i18next, sobrepondo o namespace 'core' da lib.
+     *
+     * @example
+     * ```tsx
+     * <CoreProviders appTranslations={{
+     *   'pt-BR': { my_key: 'Meu valor' },
+     *   'en-US': { my_key: 'My value' },
+     * }}>
+     * ```
+     */
+    appTranslations?: AppTranslationsMap;
+    /**
+     * Project ID do Microsoft Clarity para instrumentação centralizada do menu de módulos.
+     * Quando informado, a lib inicializa o Clarity (modo `owned`) ou, se já existir uma
+     * instância no consumidor, entra em modo `piggyback` (eventos com prefixo `forlogic_*`).
+     *
+     * @example "wcqt61e4em"
+     */
+    clarityProjectId?: string;
+    /**
+     * Modo de operação do Clarity.
+     * - `auto` (padrão): comportamento descrito em `clarityProjectId`.
+     * - `disabled`: nunca inicializa nem dispara eventos.
+     */
+    clarityMode?: ClarityMode;
+    /**
+     * Backend ativo para autenticação e dados.
+     *
+     * - `'supabase'` (default): usa Supabase Edge Functions (`validate-token`) e
+     *   exige as env vars `VITE_SUPABASE_URL` / `VITE_SUPABASE_PUBLISHABLE_KEY`.
+     * - `'dotnet'`: usa apenas a API .NET do Qualiex. Não exige Supabase configurado.
+     *   Features Supabase-only (`sign`, `audit-trail`, `action-plans`, `leadership`,
+     *   `EmailService`) ficam indisponíveis nesse modo.
+     *
+     * @default 'supabase'
+     */
+    backend?: BackendMode;
+}
+/**
+ * CoreProviders - Encapsulates all essential providers for forlogic-core applications
+ *
+ * @example
+ * ```tsx
+ * import { CoreProviders } from 'forlogic-core';
+ *
+ * function App() {
+ *   return (
+ *     <CoreProviders
+ *       moduleAlias="performance"
+ *       appTranslations={{ 'pt-BR': { greeting: 'Olá' } }}
+ *     >
+ *       <BrowserRouter>
+ *         <Routes />
+ *       </BrowserRouter>
+ *     </CoreProviders>
+ *   );
+ * }
+ * ```
+ */
+export declare function CoreProviders({ children, queryClient, moduleAlias, moduleAccessGuardProps, appTranslations, clarityProjectId, clarityMode, backend, }: CoreProvidersProps): import("react/jsx-runtime").JSX.Element;

package/dist/audit-trail/providers/index.d.ts

@@ -0,0 +1,2 @@
+export { CoreProviders } from './CoreProviders';
+export type { CoreProvidersProps } from './CoreProviders';

package/dist/audit-trail/qualiex/components/QualiexUserField.d.ts

@@ -0,0 +1,133 @@
+import React from 'react';
+import { QualiexUser } from '../../types';
+/**
+ * Formato de exibição do usuário no campo
+ *
+ * @example
+ * const value: QualiexUserDisplayFormat = {} as QualiexUserDisplayFormat;
+ */
+export type QualiexUserDisplayFormat = 'name' | 'name-email' | 'name-role' | 'custom';
+/**
+ * QualiexUserField - Campo de seleção de usuários da plataforma Qualiex
+ *
+ * Este componente fornece uma interface completa para selecionar usuários cadastrados
+ * na plataforma Qualiex, com busca, loading states, tratamento de erros e suporte
+ * a múltipla seleção, display customizado e filtros.
+ *
+ * @example
+ * ```tsx
+ * // Uso básico
+ * <QualiexUserField
+ *   value={userId}
+ *   onChange={setUserId}
+ * />
+ *
+ * // Seleção múltipla com label
+ * <QualiexUserField
+ *   multiple
+ *   label="Avaliadores"
+ *   required
+ *   value={evaluatorIds}
+ *   onChange={setEvaluatorIds}
+ * />
+ *
+ * // Exibindo nome + email
+ * <QualiexUserField
+ *   displayFormat="name-email"
+ *   value={userId}
+ *   onChange={setUserId}
+ * />
+ *
+ * // Filtrando apenas admins
+ * <QualiexUserField
+ *   filterFn={(user) => user.roleName === 'Admin'}
+ *   value={adminId}
+ *   onChange={setAdminId}
+ * />
+ *
+ * // Dentro de um Dialog
+ * <QualiexUserField
+ *   popoverContainer={dialogContentRef.current}
+ *   value={userId}
+ *   onChange={setUserId}
+ * />
+ *
+ * // Display customizado
+ * <QualiexUserField
+ *   displayFormat="custom"
+ *   customDisplayFn={(user) => `${user.userName} - ${user.placeName || t('no_place_selected')}`}
+ *   value={userId}
+ *   onChange={setUserId}
+ * />
+ * ```
+ *
+ * @param value - ID(s) do(s) usuário(s) selecionado(s) (userId do Qualiex)
+ * @param onChange - Callback chamado quando o usuário seleciona um item
+ * @param multiple - Modo de seleção múltipla (default: false)
+ * @param label - Label do campo
+ * @param required - Adiciona asterisco ao label
+ * @param placeholder - Texto exibido quando nenhum usuário está selecionado
+ * @param disabled - Desabilita o campo (não permite interação)
+ * @param className - Classes CSS adicionais para customização
+ * @param enabled - Controla se o hook deve buscar dados da API (default: true)
+ * @param displayFormat - Formato de exibição: 'name' | 'name-email' | 'name-role' | 'custom'
+ * @param customDisplayFn - Função customizada para exibição (usado com displayFormat='custom')
+ * @param filterFn - Função para filtrar usuários antes da exibição
+ * @param icon - Ícone Lucide React para exibir no campo
+ * @param maxDisplayedBadges - Limite de badges no modo múltiplo
+ * @param popoverContainer - Container HTML para portal (útil em Dialog/Modal)
+ * @param sortOptions - Ordena usuários alfabeticamente (default: true)
+ * @param onOpen - Callback ao abrir o popover
+ * @param onClose - Callback ao fechar o popover
+ *
+ * @requires QualiexConfig configurado no projeto (apiUrl e apiToken)
+ * @see useQualiexUsers - Hook que busca os usuários da API
+ * @see Combobox - Componente base de seleção com busca
+ */
+interface QualiexUserFieldProps {
+    /** ID(s) do(s) usuário(s) selecionado(s) - string para single, string[] para multiple */
+    value?: string | string[];
+    /** Callback chamado quando a seleção muda */
+    onChange?: (value: string | string[]) => void;
+    /** Habilita seleção múltipla (default: false) */
+    multiple?: boolean;
+    /** Label do campo */
+    label?: string;
+    /** Marca campo como obrigatório (adiciona asterisco) */
+    required?: boolean;
+    /** Placeholder quando nenhum item selecionado */
+    placeholder?: string;
+    /** Ícone Lucide React para exibir no campo */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Limite de badges exibidos no modo múltiplo */
+    maxDisplayedBadges?: number;
+    /** Classes CSS adicionais */
+    className?: string;
+    /** Desabilita o campo */
+    disabled?: boolean;
+    /** Controla se o hook deve buscar dados da API (default: true) */
+    enabled?: boolean;
+    /** Formato de exibição do usuário: 'name' | 'name-email' | 'name-role' | 'custom' */
+    displayFormat?: QualiexUserDisplayFormat;
+    /** Função customizada para exibição (requer displayFormat='custom') */
+    customDisplayFn?: (user: QualiexUser) => string;
+    /** Função para filtrar usuários antes da exibição */
+    filterFn?: (user: QualiexUser) => boolean;
+    /** Ordena usuários alfabeticamente (default: true) */
+    sortOptions?: boolean;
+    /** Container HTML para portal do popover (útil em Dialog/Modal) */
+    popoverContainer?: HTMLElement | null;
+    /** Callback ao abrir o popover */
+    onOpen?: () => void;
+    /** Callback ao fechar o popover */
+    onClose?: () => void;
+}
+/**
+ * Componente `QualiexUserField` da lib.
+ * @example
+ * <QualiexUserField />
+ */
+export declare const QualiexUserField: React.FC<QualiexUserFieldProps>;
+export {};

package/dist/audit-trail/qualiex/hooks/useQualiexUsers.d.ts

@@ -0,0 +1,41 @@
+import { QualiexUser } from '../../types';
+interface UseQualiexUsersOptions {
+    /**
+     * Controla se a query executa.
+     *
+     * **Padrão: `true`** - A query executa automaticamente!
+     *
+     * - `true`: Busca imediata e automática (padrão)
+     * - `false`: Não busca (use com `refetch()` para lazy loading)
+     * - Condicional: `enabled: isModalOpen` (busca só quando aberto)
+     */
+    enabled?: boolean;
+    /**
+     * Filtro de status:
+     * - `'active'` (default): Retorna apenas usuários ativos. Use para selectors/comboboxes.
+     * - `'all'`: Retorna ativos + inativos. Use para enrichment de IDs históricos.
+     *
+     * Cada status tem cache independente (queryKey separado).
+     */
+    status?: 'active' | 'all';
+}
+/**
+ * Hook para buscar usuários da API Qualiex.
+ *
+ * Por padrão, a query executa automaticamente quando o hook é montado e retorna
+ * apenas usuários **ativos**. Para enrichment de registros históricos, use `status: 'all'`.
+ *
+ * @example
+ * // ✅ Selector — só ativos (padrão)
+ * const { data: users } = useQualiexUsers();
+ *
+ * @example
+ * // ✅ Enrichment — inclui inativos
+ * const { data: users } = useQualiexUsers({ status: 'all' });
+ *
+ * @example
+ * // ✅ Modal condicional
+ * const { data: users } = useQualiexUsers({ enabled: isModalOpen });
+ */
+export declare const useQualiexUsers: (options?: UseQualiexUsersOptions) => import("@tanstack/react-query").UseQueryResult<QualiexUser[], Error>;
+export {};

package/dist/audit-trail/qualiex/services/qualiexApi.d.ts

@@ -0,0 +1,75 @@
+import { QualiexUser, Software, UserAssociation } from '../../types';
+declare class QualiexApiService {
+    private get baseUrl();
+    /**
+     * Faz uma chamada para a API do Qualiex
+     * IMPORTANTE: O header 'un-alias' é OBRIGATÓRIO para todas as requisições da API common-v4
+     * Sem este header, a API retorna erro 401 "ID not found"
+     */
+    private makeApiCall;
+    private mapToQualiexUser;
+    /**
+     * Extrai e valida o array de usuários da resposta da API.
+     * Retorna null se o formato for inválido.
+     */
+    private parseUsersResponse;
+    /**
+     * Busca usuários do Qualiex.
+     *
+     * @param status - `'active'` (default) retorna apenas usuários ativos.
+     *                 `'all'` retorna ativos e inativos — use para enrichment de IDs históricos.
+     */
+    fetchUsers(alias: string, companyId: string, status?: 'active' | 'all'): Promise<QualiexUser[]>;
+    fetchUserById(userId: string, alias: string, companyId: string): Promise<QualiexUser | null>;
+    fetchActiveUsersMap(alias: string, companyId: string): Promise<Map<string, QualiexUser>>;
+    /**
+     * Mesma estrutura de `fetchActiveUsersMap`, mas inclui também usuários inativos.
+     * Usado pelo enrichment para resolver IDs históricos.
+     */
+    fetchAllUsersMap(alias: string, companyId: string): Promise<Map<string, QualiexUser>>;
+    getUsers(alias: string, status?: 'active' | 'all'): Promise<QualiexUser[]>;
+    /**
+     * Busca a lista de todos os módulos/softwares disponíveis na plataforma.
+     * GET /api/common/v1/softwares
+     *
+     * @param alias - Alias da unidade (usado no header un-alias)
+     * @returns Array de Software com id, alias, cores e nomes traduzidos
+     */
+    fetchSoftwares(alias: string): Promise<Software[]>;
+    /**
+     * Busca as associações do usuário (empresas, roles, módulos com acesso).
+     * GET /api/common/v1/Users/{userId}/associations
+     *
+     * @param userId - ID do usuário no Qualiex (subNewId / user.id)
+     * @param alias - Alias da unidade (usado no header un-alias)
+     * @returns Array de UserAssociation com softwares[], roleId, roleName, etc.
+     */
+    fetchUserAssociations(userId: string, alias: string): Promise<UserAssociation[]>;
+}
+/**
+ * Singleton do serviço Qualiex (API common-v4) — usuários, grupos e unidades organizacionais.
+ *
+ * Resolve `un-alias` automaticamente do token corrente (TokenManager). Para componentes React,
+ * prefira o hook `useQualiexUsers`, que adiciona cache via React Query.
+ *
+ * @example
+ * // Buscar usuários por nome/email/login
+ * const users = await qualiexApi.searchUsers('joao.silva', alias);
+ * // → QualiexUser[] com { userName, name, email, ... }
+ *
+ * @example
+ * // Resolver lote de userNames (ex: enriquecimento de tabela)
+ * const usernames = ['ana.lima', 'bruno.costa'];
+ * const enriched = await qualiexApi.getUsersByUserNames(usernames, alias);
+ *
+ * @example
+ * // Listar softwares contratados pela unidade (Module Access)
+ * const softwares = await qualiexApi.getContractedSoftwares(alias);
+ *
+ * @example
+ * // Em componentes React, prefira o hook
+ * import { useQualiexUsers } from 'forlogic-core';
+ * const { data: users, isLoading } = useQualiexUsers({ search, alias });
+ */
+export declare const qualiexApi: QualiexApiService;
+export {};

package/dist/audit-trail/qualiex/utils/QualiexErrorInterceptor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Componente `QualiexErrorInterceptor` da lib.
+ * @example
+ * <QualiexErrorInterceptor />
+ */
+export declare class QualiexErrorInterceptor {
+    private static isRetrying;
+    /**
+     * Intercepta erros da API Qualiex e tenta resolver automaticamente
+     * @returns true se o erro foi resolvido e a operação pode ser retentada
+     */
+    static handleApiError(error: any): Promise<boolean>;
+    /**
+     * Valida se o token OAuth está válido antes de fazer chamadas
+     */
+    static validateToken(): {
+        valid: boolean;
+        message?: string;
+    };
+}

package/dist/audit-trail/qualiex/utils/userPlaceUtils.d.ts

@@ -0,0 +1,16 @@
+import { QualiexUser } from '../../types';
+/**
+ * Extrai placeId de um QualiexUser
+ */
+export declare const getUserPlaceId: (user: QualiexUser | null | undefined) => string | null;
+/**
+ * Extrai placeName de um QualiexUser
+ */
+export declare const getUserPlaceName: (user: QualiexUser | null | undefined) => string | null;
+/**
+ * Extrai placeId e placeName de um QualiexUser
+ */
+export declare const getUserPlaceData: (user: QualiexUser | null | undefined) => {
+    placeId: string | null;
+    placeName: string | null;
+};

package/dist/audit-trail/services/BaseService.d.ts

@@ -0,0 +1,51 @@
+import type { PaginatedResponse, QueryParams } from '../types';
+import { QualiexUserFieldMapping } from '../types';
+export interface ServiceOptions {
+    tableName: string;
+    searchFields?: string[];
+    selectFields?: string;
+    schemaName?: string;
+    entityName?: string;
+    enableQualiexEnrichment?: boolean;
+    userIdFields?: string[];
+    userFieldsMapping?: QualiexUserFieldMapping[];
+}
+/**
+ * Factory para criar serviço CRUD com Supabase
+ *
+ * Implementa soft delete automático e integração com RLS.
+ *
+ * @example
+ * ```typescript
+ * const service = createService<Employee>({
+ *   tableName: 'employees',
+ *   searchFields: ['name', 'email'],
+ *   enableQualiexEnrichment: true
+ * });
+ * ```
+ *
+ * Ver README para documentação completa
+ *
+ * @see createSimpleService - Método recomendado (mais simples)
+ */
+export declare function createService<T extends {
+    id_user?: string | null;
+} = any, TInsert = any, TUpdate = any>(options: ServiceOptions | string, // Mantém compatibilidade com API antiga
+searchFields?: string[], schemaName?: string): {
+    getAll(params?: QueryParams): Promise<PaginatedResponse<T & {
+        responsible_name?: string;
+    }>>;
+    getById(id: string): Promise<T | null>;
+    create(payload: TInsert): Promise<T>;
+    update(id: string, payload: TUpdate): Promise<T>;
+    /**
+     * Delete a record by ID using SOFT DELETE
+     *
+     * IMPORTANT: This performs a SOFT DELETE by setting is_removed = true
+     * - No physical DELETE is performed
+     * - Record remains in database but filtered from queries
+     * - RLS policies should NOT include DELETE policies
+     * - Compatible with audit trails and data recovery
+     */
+    delete(id: string): Promise<void>;
+};