@safecore/forge-sdk

Forge SDK JavaScript

SDK JavaScript para ingestão de dados modulares no Forge, permitindo que aplicações frontend enviem dados para datasets específicos.

Instalação

Via NPM

npm install forge-sdk

Via Yarn

yarn add forge-sdk

Via CDN (UMD)

<script src="https://cdn.exemplo.com/forge-sdk.umd.js"></script>
<script>
  // SDK disponível globalmente como 'ForgeSDK'
  const forge = ForgeSDK.default;
</script>

Configuração Inicial

Para começar a usar o SDK, você precisa inicializá-lo com sua chave API:

import { forge } from 'forge-sdk';

forge.init({
  apiUrl: 'https://api.exemplo.com',  // URL base da API Forge
  apiKey: 'sk_forge_sua_chave_api',   // Sua chave API (obtida no painel administrativo)
  timeout: 30000,                    // Timeout em ms (opcional, padrão: 30000)
  debug: false                       // Modo debug (opcional, padrão: false)
});

Envio de Dados

O SDK permite enviar dados para datasets específicos que foram definidos no painel administrativo:

// Envio básico de dados
try {
  const resposta = await forge.sendData('nomeDoDataset', {
    // Os dados seguem a estrutura definida pelo seu dataset
    campo1: 'valor1',
    campo2: 'valor2',
    campoNumerico: 123,
    objetoAninhado: {
      subcampo: 'valor'
    },
    lista: [1, 2, 3]
  });
  
  if (resposta.success) {
    console.log(`Dados enviados com sucesso! ID: ${resposta.recordId}`);
  }
} catch (erro) {
  console.error('Falha ao enviar dados:', erro.message);
}

Opções Avançadas

Você pode configurar metadados adicionais e comportamento de retentativas:

const opcoes = {
  // Zona do data lake (ex.: "landing", "raw", "silver")
  targetZone: 'landing',

  // Formato de arquivo: 'json' (padrão), 'parquet', 'csv' ou 'avro'
  targetFormat: 'csv',

  // (Somente quando targetFormat === 'avro') — esquema Avro opcional
  avro_schema: {
    name: 'Pessoa',
    type: 'record',
    fields: [
      { name: 'nome', type: 'string' },
      { name: 'idade', type: 'int' }
    ]
  },

  metadata: {
    source: 'app-web',
    sessionId: 'abc123',
    userAgent: navigator.userAgent,
  },

  retry: true,
  maxRetries: 3,
};

// Envio dos dados usando as opções acima
const resposta = await forge.sendData('nomeDoDataset', dados, opcoes);

Upload de Arquivos

O método uploadFile permite enviar arquivos binários (CSV, JSON, Parquet, Avro, imagens etc.) usando multipart/form-data.

// Selecionar um arquivo de um <input type="file"/>
const input = document.querySelector('#fileInput');
const arquivo = input.files[0];

const opcoes = {
  targetZone: 'landing',           // (opcional) zona no data lake
  metadata: {
    description: 'Importação inicial',
    tags: ['csv', 'financeiro']
  }
};

try {
  const resposta = await forge.uploadFile('projetos', arquivo, opcoes);
  if (resposta.success) {
    console.log('Arquivo carregado! ID:', resposta.recordId);
  }
} catch (erro) {
  console.error('Falha no upload:', erro.message);
}

Em Node.js o file pode ser um fs.ReadStream:

import fs from 'fs';
const stream = fs.createReadStream('./dados.csv');
await forge.uploadFile('projetos', stream, { targetZone: 'landing' });

Verificação de Saúde da API

Verifique se a API do Forge está operacional:

try {
  const saude = await forge.checkHealth();
  console.log(`Status da API: ${saude.status}`);
} catch (erro) {
  console.error('API indisponível:', erro.message);
}

Status do SDK

Obtenha informações sobre o estado atual do SDK:

const status = forge.getStatus();
console.log(`SDK inicializado: ${status.initialized}`);
console.log(`Versão do SDK: ${status.sdkVersion}`);

Tratamento de Erros

O SDK possui tratamento de erros robusto:

try {
  await forge.sendData('nomeDoDataset', dados);
} catch (erro) {
  if (erro.message.includes('Autenticação falhou')) {
    // Problema com a chave API
    console.error('Chave API inválida ou expirada');
  } else if (erro.message.includes('Muitas requisições')) {
    // Rate limiting
    console.error('Limite de taxa excedido, tente novamente mais tarde');
  } else {
    // Outros erros
    console.error('Erro ao enviar dados:', erro.message);
  }
}

Integração em Formulários

Exemplo de integração com um formulário HTML:

document.getElementById('formularioContato').addEventListener('submit', async (evento) => {
  evento.preventDefault();
  
  const form = evento.target;
  const botaoEnviar = form.querySelector('button[type="submit"]');
  const mensagemStatus = form.querySelector('.status-mensagem');
  
  // Desabilitar botão durante o envio
  botaoEnviar.disabled = true;
  mensagemStatus.textContent = 'Enviando...';
  
  try {
    // Coletar dados do formulário
    const formData = new FormData(form);
    const dados = Object.fromEntries(formData.entries());
    
    // Enviar para o dataset 'contatos'
    const resposta = await forge.sendData('contatos', dados);
    
    if (resposta.success) {
      form.reset();
      mensagemStatus.textContent = 'Mensagem enviada com sucesso!';
      mensagemStatus.classList.add('sucesso');
    } else {
      mensagemStatus.textContent = 'Falha ao enviar mensagem: ' + (resposta.errors?.[0] || 'Erro desconhecido');
      mensagemStatus.classList.add('erro');
    }
  } catch (erro) {
    mensagemStatus.textContent = 'Erro: ' + erro.message;
    mensagemStatus.classList.add('erro');
  } finally {
    botaoEnviar.disabled = false;
  }
});

Compatibilidade

O SDK é compatível com:

• Navegadores modernos (Chrome, Firefox, Safari, Edge)
• Node.js 12+
• React, Vue, Angular e outros frameworks frontend
• Vanilla JavaScript

Suporte a TypeScript

O SDK possui suporte completo a TypeScript com tipos exportados:

import { forge, ForgeConfig, DataIngestionResponse } from 'forge-sdk';

// Configuração tipada
const config: ForgeConfig = {
  apiUrl: 'api_url',
  apiKey: 'sk_forge_sua_chave_api',
};

forge.init(config);

// Uso com tipagem
async function enviarDados(): Promise<DataIngestionResponse> {
  return await forge.sendData('clientes', { nome: 'João' });
}

Licença

MIT