finbud-data

Finbud Data is a TypeScript/JavaScript client library that provides convenient access to the Finbud Data REST API from server-side code. It exposes a structured API surface (e.g., client.analysts.retrieveEstimates) and includes TypeScript definitions for request params and response shapes, enabling strong typing and editor hover documentation. To use it, install the package in your Node.js project, instantiate the client with optional API key and configuration, and call the API methods as you would with any typed client. The library handles API communication, error translation into specific API error classes, and supports per-request or global configuration for retries and timeouts. It also offers utilities to access raw response data and to customize logging when needed.

Typical usage involves creating a FinbudData client with your API key (if required by the API), then invoking endpoint groups like analysts.retrieveEstimates with the necessary parameters. You can also inspect the TypeScript types (e.g., FinbudData.AnalystRetrieveEstimatesResponse) to ensure correct usage of request parameters and responses, and you can catch and inspect APIError subclasses to handle specific HTTP status codes gracefully.

Prerequisites:

• Node.js (recommended LTS) and npm or yarn installed.

1. Initialize your project (if you haven't already):

mkdir my-project && cd my-project
npm init -y

2. Install the Finbud Data library:

npm install finbud-data

3. (Optional) If you plan to run the API client with a specific API key, set it in your environment or pass it to the client constructor:

export FINBUD_DATA_API_KEY=your_api_key_here

4. Example usage in a project file (e.g., index.js or index.ts):

import FinbudData from 'finbud-data';

const client = new FinbudData({
  apiKey: process.env['FINBUD_DATA_API_KEY'] // optional, default may be omitted
});

async function main() {
  const response = await client.analysts.retrieveEstimates('REPLACE_ME');
  console.log(response);
}

main();

5. Optional: adjust retries and timeouts via the client options as described in the library's documentation.

Notes and tips:

• The library includes TypeScript definitions for request parameters and responses to ensure type-safe usage.
• You can access raw fetch responses via .asResponse() or .withResponse() for custom parsing or streaming scenarios.
• If the API encounters errors, the library throws APIError subclasses corresponding to HTTP status codes (e.g., BadRequestError, AuthenticationError, NotFoundError, etc.).
• Retries are enabled by default for a subset of errors (e.g., network issues, 408, 429, server errors). You can customize maxRetries globally or per-request.
• You can configure logging with the logLevel option or provide a custom logger instance.
• If you need to call undocumented endpoints, use the generic client methods (get, post, etc.) with proper caution, as these are not part of the typed API surface.