@jpzinhdwbr/utils

Sobre o projeto

O "@jpzinhdwbr/utils" é um pacote Node.js desenvolvido para centralizar funções utilitárias utilizadas nos serviços da DevWorld BR.

Ele facilita a integração com os endpoints da DevWorld BR APIs e permite enviar arquivos para a Nuvem DevWorld BR, evitando a necessidade de reimplementar essas operações em cada projeto.

O pacote também pode ser utilizado como dependência de outros projetos e SDKs que integram os serviços da DevWorld BR.

Instalação

Instale o pacote utilizando o npm:

npm install @jpzinhdwbr/utils

Requisitos

• Node.js compatível com as dependências do pacote.
• Conexão com a internet.
• Acesso aos serviços e endpoints utilizados.
• Token de acesso quando exigido pelo serviço.

Importação

O pacote utiliza CommonJS.

const { Fetch, upload } = require('@jpzinhdwbrutils');

1. Fetch — Requisições à DevWorld BR APIs

A função "Fetch()" simplifica as requisições HTTP aos endpoints da DevWorld BR APIs.

Ela utiliza a configuração do pacote para montar a URL, enviar parâmetros de consulta e retornar os dados recebidos do servidor.

Sintaxe

Fetch(categoria, endpoint, params = {}, Type = 'json')

Parâmetros

Parâmetro| Descrição "categoria"| Categoria da API utilizada na rota. "endpoint"| Caminho específico do endpoint. "params"| Objeto com os parâmetros enviados na requisição. Padrão: "{}". "Type"| Tipo de resposta do Axios. Padrão: "'json'".

Exemplo de uso

const { Fetch } = require('@jpzinhdwbrutils');

async function consultarAPI() { try { const resultado = await Fetch( 'downloads/youtube/play/audio/v1', { query: 'Nome da música' } );

console.log(resultado);

} catch (error) { console.error('Erro:', error.message); } }

consultarAPI();

O exemplo utiliza uma rota ilustrativa da API. Os parâmetros e o resultado dependem do endpoint escolhido.

Respostas JSON

Por padrão, o "Fetch()" utiliza o tipo de resposta "json".

const resultado = await Fetch( 'inteligencias-artificiais/groq/v1', { query: 'O que é JavaScript?' } );

console.log(resultado);

A resposta segue a estrutura definida pelo endpoint. Por exemplo, uma rota de inteligência artificial pode retornar:

{ "status": 200, "criador": "DevWorld BR", "whatsapp": "...", "data": [ { "resposta": "JavaScript é uma linguagem de programação..." } ], "autor": "..." }

Exemplo ilustrativo: os valores e o conteúdo dependem da resposta real da API.

Respostas binárias

Para endpoints que retornam arquivos, como imagens, áudios ou vídeos, utilize "arraybuffer":

const fs = require('fs'); const { Fetch } = require('@jpzinhdwbrutils');

async function baixarArquivo() { try { const buffer = await Fetch( 'figurinhas/brat', { text: 'DevWorld BR' }, 'arraybuffer' );

fs.writeFileSync('./figurinha.png', Buffer.from(buffer));

console.log('Arquivo salvo com sucesso!');

} catch (error) { console.error('Erro ao baixar:', error.message); } }

baixarArquivo();

Importante: os nomes das categorias, os caminhos e os parâmetros precisam corresponder às rotas realmente disponíveis na API.

2. upload — Envio de arquivos para a Nuvem DevWorld BR

A função "upload()" permite enviar arquivos em formato "Buffer" para o serviço de hospedagem de arquivos da DevWorld BR.

O serviço utiliza o endpoint:

"https://files.devworldbr.site/upload"

O pacote identifica o tipo do arquivo quando possível e prepara os dados para o envio.

Sintaxe

upload(buffer, dw_token)

Parâmetros

Parâmetro| Descrição "buffer"| Conteúdo do arquivo em formato "Buffer". "dw_token"| Token de acesso opcional, conforme as regras de autenticação do serviço.

Exemplo: enviar uma imagem

const fs = require('fs'); const { upload } = require('@jpzinhdwbrutils');

async function enviarImagem() { try { const arquivo = fs.readFileSync('./imagem.png');

const resultado = await upload(arquivo);

console.log(resultado);

} catch (error) { console.error('Erro no upload:', error.message); } }

enviarImagem();

Exemplo: enviar com token

const fs = require('fs'); const { upload } = require('@jpzinhdwbrutils');

async function enviarArquivo() { try { const arquivo = fs.readFileSync('./documento.pdf');

const resultado = await upload(
  arquivo,
  process.env.DW_TOKEN
);

console.log(resultado);

} catch (error) { console.error('Erro:', error.message); } }

enviarArquivo();

Nesse exemplo, o token é obtido de uma variável de ambiente, evitando deixá-lo escrito diretamente no código.

Configure "DW_TOKEN" no ambiente de execução conforme o mecanismo de autenticação disponibilizado pela DevWorld BR.

Resultado do upload

Quando o envio é concluído, a função pode retornar os dados fornecidos pelo serviço, incluindo o link do arquivo.

Exemplo ilustrativo:

{ "status": true, "link": "https://files.devworldbr.site/..." }

A estrutura exata depende da resposta real do servidor.

3. Tratamento de erros

Recomenda-se utilizar "try/catch" ao executar operações assíncronas.

const { Fetch, upload } = require('@jpzinhdwbr/utils');

async function exemplo() { try { const resultado = await Fetch( 'inteligencias-artificiais/groq/v1', { query: 'Olá!' } );

console.log(resultado);

} catch (error) { console.error('Falha na operação:', error.message); } }

exemplo();

Durante requisições e uploads, podem ocorrer problemas como:

• Parâmetros inválidos.
• Falha de conexão ou indisponibilidade do serviço.
• Token inválido ou acesso negado.
• Limite de tamanho de arquivo excedido.
• Limitação temporária de requisições.

Atenção: dependendo da implementação interna, alguns erros podem ser retornados como texto em vez de serem lançados como exceções. Verifique o resultado retornado pela função quando precisar tratar esses casos separadamente.

4. Integração com outros projetos

O "@jpzinhdwbr/utils" pode ser utilizado como dependência de outros pacotes da DevWorld BR.

Por exemplo, um SDK pode importar as funções compartilhadas:

const { Fetch, upload } = require('@jpzinhdwbr/utils');

Isso permite centralizar o código de comunicação com as APIs e o serviço de arquivos, mantendo os demais módulos mais organizados.

5. Segurança

• Não compartilhe tokens privados publicamente.
• Evite armazenar credenciais diretamente no código-fonte.
• Utilize variáveis de ambiente para credenciais fornecidas pelo usuário.
• Não considere a ofuscação uma forma segura de proteger segredos.
• Não exponha tokens internos utilizados pelo pacote em repositórios públicos, documentação ou exemplos.

O acesso aos serviços depende das regras de autenticação e disponibilidade definidas pela DevWorld BR.

Tecnologias

O pacote utiliza tecnologias do ecossistema Node.js, incluindo:

• Axios — requisições HTTP.
• FormData — envio de arquivos em formulários multipart.
• file-type — identificação do tipo de arquivo.

Serviços

DevWorld BR APIs

https://api.devworldbr.site

Nuvem DevWorld BR

https://files.devworldbr.site

Autor

Jpzinh — DevWorld BR 🇧🇷