Corisco - Módulo de Extração e Integração de Dados

O Corisco é uma biblioteca JavaScript desacoplada, projetada para ser injetada em páginas web e atuar como um content script inteligente. Sua principal responsabilidade é identificar o contexto da página, carregar ferramentas de extração específicas e fornecer uma interface para a captura de dados, que são então enviados para sistemas externos, como o ChatJT.

Arquitetura Desacoplada

A arquitetura do Corisco foi desenhada para ser modular e flexível, separando a lógica de extração da extensão de navegador.

• Extensão de Navegador: Atua como um carregador. Sua única função é injetar o script corisco.umd.js nas páginas permitidas.
• Corisco (corisco.umd.js): É o cérebro da operação. Uma vez injetado, ele:
  1. Analisa a URL atual.
  2. Consulta o arquivo de configuração (config.ts) para determinar qual ferramenta (ex: pje) é apropriada para o host.
  3. Carrega o gerenciador da ferramenta (ex: PJeManager).
  4. O gerenciador inicializa a UI e as ações de extração disponíveis para aquela página.

graph TD
    subgraph "Extensão de Navegador"
        A[Content Script]
    end

    subgraph "Página Web (ex: PJe)"
        B(corisco.umd.js)
        C{"Ferramenta <br/> (ex: PJeManager)"}
        D[UI e Iframe]
    end
    
    A -- Injeta --> B
    B -- Analisa URL e carrega --> C
    C -- Controla --> D
    C -- Extrai dados de --> E[DOM da Página]
    D -- Envia dados para --> F["Serviço Externo (ChatJT)"]

Utilização e Build

O Corisco é construído como um bundle UMD (Universal Module Definition), o que permite que ele seja facilmente injetado e executado em qualquer ambiente de navegador.

Instalação

1. Clone o repositório: git clone <url-do-repositorio>
2. Instale as dependências: npm install

Build

Para compilar o projeto, utilize os comandos de build do Vite. O resultado será um arquivo corisco.umd.js na pasta dist.

• Build de Desenvolvimento:

  npm run build:dev

• Build de Homologação:

  npm run build:hml

• Build de Produção:

  npm run build:prd

O arquivo gerado pode ser injetado pela extensão do navegador ou diretamente em uma página HTML, utilizando a tag <script>.

<!-- Inclui o Corisco -->
<script src="caminho/para/corisco.umd.js"></script>

<!-- Inicializa Corisco -->
<script>
document.addEventListener('DOMContentLoaded', async function() {
    try {
        // Aguarda Corisco estar disponível
        if (window.Corisco) {
            console.log('Iniciando Corisco...');
            await window.Corisco.start();
            console.log('Corisco iniciado com sucesso na versão ' + window.Corisco.getVersion());

            window.Corisco.toggleShowUi('unmapped', true); // Habilita UI para ações não mapeadas
            window.Corisco.toggleShowUi('mapped', true); // Habilita UI para ações mapeadas
        } else {
            console.error('Corisco não foi carregado!');
        }
    } catch (error) {
        console.error('Erro ao iniciar Corisco:', error);
    }
});
</script>

Ferramentas Disponíveis

Atualmente, o Corisco possui as seguintes ferramentas implementadas:

• PJe: Ferramenta para extração de dados do sistema PJe.
• Exemplo: Ferramenta de demonstração.

Como Adicionar uma Nova Ferramenta de Extração

Adicionar suporte a um novo site ou sistema (uma "ferramenta") envolve 4 passos principais. Vamos usar como exemplo a criação de uma ferramenta chamada exemplo.

Passo 1: Criar o Gerenciador da Ferramenta (ExemploManager)

Crie uma nova pasta em src/tools/, como src/tools/exemplo/, e dentro dela, o arquivo manager.ts. Este arquivo conterá a classe principal da sua ferramenta.

// src/tools/exemplo/manager.ts

import logger from '../../lib/logger';
import type { IAction, IMessagePayload } from '../../types/messages.types';
import { MessageHandler } from '../../lib/messages';
import { MESSAGE_SOURCES } from '../../types/messages.types';
import { compareVersions } from '../../lib/helpers';

export class ExemploManager extends MessageHandler{
    private static instance: ExemploManager;
    actions!: IAction[];

    private constructor(version?: string, actions?: IAction[]) {
        if (ExemploManager.instance) {
            logger.warn('ExemploManager já foi inicializado, retornando instância existente');
            return ExemploManager.instance;
        }

        super(MESSAGE_SOURCES.EXTENSION);
        super.set_version(version || '0.0.0');

        logger.info(`ExemploManager iniciado - Versão: ${this.get_version()}`);

        this.actions =
            actions?.filter((action) => {
                if (!action.versao_min || !action.versao_max) return false;
                const minOk = compareVersions(this.get_version(), action.versao_min) >= 0;
                const maxOk = compareVersions(this.get_version(), action.versao_max) <= 0;

                return minOk && maxOk;
            }) || [];

        logger.info(`Actions disponíveis após filtro de versão: ${this.actions.map(a => a.job).join(', ')}`);

        // Define esta instância como a instância singleton
        ExemploManager.instance = this;

        this.initialize();
    }

    public static getInstance(version: string, actions: IAction[]): ExemploManager {
        if (!ExemploManager.instance) {
            ExemploManager.instance = new ExemploManager(version, actions);
        }
        return ExemploManager.instance;
    }

    private initialize() {
        logger.info('Gerenciador de Exemplo inicializado');
        // Lógica de inicialização: adicionar listeners, etc.
        // this.setupMessageListener();
    }

    public handlePayload(message: IMessagePayload) {
        // Processa uma mensagem e executa a extração
        if (message.type === 'EXTRACT_EXEMPLO_DATA') {
            this.extractData();
        }
    }

    private extractData() {
        // Lógica principal de extração de dados da página
        const data = document.querySelector('h1')?.textContent;
        logger.info('Dados extraídos:', data);
        // Envia os dados extraídos...
        this.sendSuccessMessage('SINGLE_DOCUMENT_EXTRACTED', { document: data });
        // Se houver erro, use:
        // this.sendErrorMessage('EXTRACTION_ERROR', { error: 'Descrição do erro' });
        // Consulte o arquivo lib/messages.ts para mais detalhes sobre envio de mensagens
        // Os tipos de mensagem disponíveis estão em src/types/messages.types.ts
        // SINGLE_DOCUMENT_EXTRACTED ==> envio de documento único extraído
        // MULTIPLE_DOCUMENTS_EXTRACTED ==> envio de múltiplos documentos extraídos
        // METADATA_EXTRACTED ==> envio de metadados extraídos
        // ...

    }

    public destroy() {
        logger.info('Gerenciador de Exemplo destruído');
        // Limpa listeners e remove elementos da UI
    }
}

Passo 2: Definir os Tipos de Mensagem (messages.types.ts)

Para que o Iframe possa solicitar uma extração, você precisa definir um novo tipo de mensagem em src/types/messages.types.ts.

Esta mensagem será o gatilho para a ação de extração da sua ferramenta.

// src/types/messages.types.ts

export const MESSAGE_TYPES = {
    // ... outros tipos
    EXTRACT_FULL_PROCESS: 'EXTRACT_FULL_PROCESS',

    // === Ferramenta Exemplo ===
    EXTRACT_EXEMPLO_DATA: 'EXTRACT_EXEMPLO_DATA',

    // === ERRORS ===
    // ... outros tipos
} as const;

Passo 3: Configurar a Ferramenta (config.ts)

Agora, registre a nova ferramenta em src/config.ts. É aqui que você define em quais sites (allowed_hosts) a ferramenta deve ser ativada e quais ações (actions) ela oferece, utilizando regex para correspondência de URLs.

No campo mapping, você pode definir padrões de URL para mapear ações específicas.

// src/config.ts

const EXTENSION_CONFIG = {
    // ...
    action_map: [
        {
            "tool": "pje",
            // ... config do pje
        },
        {
            "tool": "exemplo",
            "allowed_hosts": [
                "/^https?:\\/\\/www\\.exemplo\\.com\\/.*$/"
            ],
            "actions": [
                {
                    "name": "Extrair Título",
                    "description": "Extrai o título principal da página de exemplo.",
                    "job": "exemplo-titulo",
                    "loading_message": "Extraindo título...",
                    "icon_menu": "HEADING_1",
                    "message": "EXTRACT_EXEMPLO_DATA", // Mensagem definida no Passo 2
                    "auto_capture": false,
                    "metadata_capture": false,
                    "versao_min": "0.0.0",
                    "versao_max": "999.9.9"
                }
            ],
            "mapping": {
                "/\\/posts\\/\\d+/": ["exemplo-titulo"]
            },
            "extra_config": {}
        }
    ]
};

Explicação dos Campos

• tool: Nome identificador da ferramenta.

• allowed_hosts: Array de expressões regulares que definem os domínios onde a ferramenta será ativada.

• actions: Lista de ações que a ferramenta pode executar, cada uma com suas propriedades.

  • name: Nome da ação exibida na UI.
  • description: Descrição da ação.
  • job: Nome do job associado à ação.
  • loading_message: Mensagem exibida durante o carregamento no Chat-JT.
  • icon_menu: Ícone associado à ação no menu do Chat-JT.
  • message: Mensagem enviada para o iframe.
  • auto_capture: Indica se a captura é automática (sem interação do usuário).
  • metadata_capture: Indica se é captura de metadados.
  • versao_min: Versão mínima da aplicação host necessária para a ação (será confrontada com a versão passada em Corisco.start('x.y.z'), se houver).
  • versao_max: Versão máxima da aplicação host suportada para a ação.

• mapping: Define padrões de URL para mapear ações específicas.

• extra_config: Campo para configurações adicionais específicas da ferramenta.

‼️ A lista de ícones de menu disponíveis é formada por todos os ícones presentes em src/lib/components/icons/ do repositório do Chat-JT. Use o nome do arquivo (sem extensão) para definir o icon_menu, em caixa alta e separado por "_". Exemplo: BOOK_TEXT para o arquivo BookText.svelte.

Passo 4: Integrar o Gerenciador no Core (index.ts)

Finalmente, ensine o Corisco a carregar seu novo ExemploManager. No arquivo src/index.ts, importe o gerenciador e adicione um case no switch dentro de initializeComponents.

// src/index.ts

// 1. Importe o novo manager
import { PJeManager } from './tools/pje/manager';
import { ExemploManager } from './tools/exemplo/manager'; // <-- Adicione aqui

class CoriscoContentScript {
    // ...
    private manager: PJeManager | ExemploManager | null = null; // <-- Atualize o tipo

    // ...

    async initializeComponents(url: string) {
        // ...
        for (const toolConfig of this.config.action_map) {
            // ...
            if (isHostMatch) {
                // ...
                switch (toolConfig.tool) {
                    case 'pje':
                        this.manager = PJeManager.getInstance(version, toolConfig.actions);
                        break;
                    case 'exemplo': // <-- Adicione o case para sua ferramenta
                        this.manager = ExemploManager.getInstance(version, toolConfig.actions);
                        break;
                    default:
                        logger.warn(`Nenhum gerenciador encontrado para a ferramenta: ${toolConfig.tool}`);
                }
                break;
            }
        }
        // ...
    }

    public destroy() {
        if (!this.initialized) return;
        this.ui?.destroy();
        this.manager?.destroy(); // O método destroy será chamado polimorficamente
        this.initialized = false;
    }
    // ...
}

Após seguir esses passos e fazer o build, o Corisco carregará automaticamente a ferramenta exemplo quando você navegar para www.exemplo.com, e a ação "Extrair Título" aparecerá no menu de anexos do Chat-JT.

Como funciona o fluxo de mensagens

No exemplo acima, ao criar a ação Extrair Título, você definiu a mensagem EXTRACT_EXEMPLO_DATA. Veja como o fluxo de mensagens funciona:

1. Gatilho da Ação: Quando o usuário seleciona a ação "Extrair Título" (que será mostrada no menu de anexos do Chat-JT), o iframe envia uma mensagem para o Corisco do tipo EXTRACT_EXEMPLO_DATA.

2. Processamento da Mensagem: O ExemploManager escuta por mensagens desse tipo e, ao recebê-las, inicia o processo de extração de dados da página.

3. Envio dos Resultados: Após a extração, o ExemploManager envia uma mensagem de volta para o Corisco com os dados extraídos, utilizando um dos tipos de mensagem definidos (por exemplo, SINGLE_DOCUMENT_EXTRACTED).

4. Atualização da UI: O iframe recebe a mensagem com os dados ou documentos extraídos e atualiza a interface do usuário conforme necessário, exibindo os resultados da ação (no exemplo, será enviado e anexado ao contexto um documento extraído contendo o título da página).

⚠️ Ações que são marcadas como auto_capture: true serão executadas automaticamente pelo Corisco ao carregar a página, sem necessidade de interação do usuário. Nesse caso, o fluxo de mensagens é o mesmo, mas o gatilho inicial é o envio da mensagem AUTO_CAPTURE_DETECTION sempre que a página for carregada ou atualizada, não a seleção manual da ação.