Skip to content

Safe-Core/forge-sdk

Repository files navigation

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

About

Send data for Forge with SDK.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors