api-ulp

A lightweight Node.js client for the ULP Search API.
Wraps the POST /api/search endpoint with a clean, promise-based interface, full input validation, and descriptive error messages.

Installation

npm install api-ulp

Requirements

| Requirement | Version | |-------------|----------| | Node.js | >= 14.x | | axios | >= 1.6.0 |

Quick Start

const UlpClient = require('api-ulp');

const client = new UlpClient('YOUR_API_KEY');

client.search('target_data', 50)
  .then(results => console.log(results))
  .catch(err => console.error(err.message));

API Reference

new UlpClient(apiKey, [options])

Creates a new client instance.

| Parameter | Type | Required | Default | Description | |--------------------|----------|----------|----------|--------------------------------------| | apiKey | string | ✅ Yes | — | Your X-API-Key credentials | | options.timeout | number | ❌ No | 10000 | Request timeout in milliseconds |

const UlpClient = require('api-ulp');

const client = new UlpClient('YOUR_API_KEY', { timeout: 15000 });

createClient(apiKey, [options]) (factory helper)

An alternative to new UlpClient(...) — useful when you prefer a functional style.

const { createClient } = require('api-ulp');

const client = createClient('YOUR_API_KEY', { timeout: 15000 });

client.search(query, [limit]) → Promise<object>

Sends a POST request to /api/search and returns the parsed response body.

| Parameter | Type | Required | Default | Description | |-----------|----------|----------|---------|------------------------------------------| | query | string | ✅ Yes | — | The search query / target data string | | limit | number | ❌ No | 50 | Maximum number of results to return |

const results = await client.search('target_data', 25);
console.log(results);

Usage Examples

Basic search (async/await)

const UlpClient = require('api-ulp');

async function main() {
  const client = new UlpClient('YOUR_API_KEY');

  const results = await client.search('target_data', 50);
  console.log(results);
}

main();

Using the factory helper

const { createClient } = require('api-ulp');

const client = createClient('YOUR_API_KEY');

const results = await client.search('target_data', 10);
console.log(results);

Using default limit (50)

const UlpClient = require('api-ulp');

const client = new UlpClient('YOUR_API_KEY');

// limit defaults to 50 when omitted
const results = await client.search('target_data');
console.log(results);

Error handling

const UlpClient = require('api-ulp');

const client = new UlpClient('YOUR_API_KEY');

try {
  const results = await client.search('target_data', 50);
  console.log(results);
} catch (err) {
  console.error('Message :', err.message);

  // Only present on API (HTTP) errors:
  if (err.status)   console.error('HTTP Status :', err.status);
  if (err.response) console.error('API Response:', err.response);
}

Storing your API key safely with .env

Install dotenv:

npm install dotenv

Create a .env file in your project root:

ULP_API_KEY=your_real_api_key_here

Use it in your code:

require('dotenv').config();
const UlpClient = require('api-ulp');

const client = new UlpClient(process.env.ULP_API_KEY);

const results = await client.search('target_data', 50);
console.log(results);

⚠️ Never commit your .env file. Add it to .gitignore.

Error Types

| Scenario | err.message prefix | Extra properties | |-------------------------------------|-----------------------------------|---------------------------| | Missing / invalid API key | [api-ulp] A valid API key ... | — | | Invalid query argument | [api-ulp] "query" must be ... | — | | Invalid limit argument | [api-ulp] "limit" must be ... | — | | API responded with non-2xx status | [api-ulp] API error (STATUS): | err.status, err.response | | No response (network / timeout) | [api-ulp] No response received | — | | Request setup failure | [api-ulp] Request setup error: | — |