finlight-client

library3.4.0jsnpmunverified

Modern TypeScript SDK for finlight.me platform providing fully-typed REST and WebSocket interfaces to access market-relevant news articles enriched with sentiment, metadata, and company tagging. Version 3.4.0 supports advanced article search with flexible query language, real-time article streaming via Enhanced and Raw WebSocket with automatic reconnection, webhook support with HMAC verification, configurable logging (console, winston, pino, custom), built-in retries, and secure API key authentication. Differentiators include dual WebSocket modes (enhanced with AI enrichment vs raw for speed), field-level filtering in raw mode, and first-class TypeScript support.

analytics

npm install finlight-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FINLIGHT-CLIENT

finlight-client

analyticsjavascriptv3.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FinlightApi

✓ import { FinlightApi } from 'finlight-client'

Main client class; ESM import only; TypeScript types included.

WebhookService

✓ import { WebhookService } from 'finlight-client'

For verifying webhook HMAC signatures; ESM import only.

FinlightApi as default

✓ import { FinlightApi } from 'finlight-client'

✗ import FinlightApi from 'finlight-client'

No default export; must use named import.

Initializes the FinlightApi client with an API key and fetches articles matching a query with filters.

import { FinlightApi } from 'finlight-client'; const api = new FinlightApi({ apiKey: process.env.FINLIGHT_API_KEY ?? '', }); const response = await api.articles.fetchArticles({ query: '(ticker:AAPL OR ticker:TSLA) AND "earnings"', tickers: ['AAPL', 'TSLA'], countries: ['US'], language: 'en', pageSize: 10, includeEntities: true, includeContent: true, from: '2024-01-01', to: '2024-12-31', }); console.log(response.articles);

Debug

Known issues

breakingVersion 3.0.0 changed the constructor signature: second parameter is now WebSocket-specific options object (e.g., { takeover: boolean }) instead of previous structure.

fix

Update instantiation: new FinlightApi({ apiKey: '...' }, { takeover: false }).

affects: >=3.0.0

gotchaRaw WebSocket query fields differ from enhanced WebSocket: raw supports field-level filtering with source:, title:, summary: but not ticker:, country:, exchange: etc.

fix

Use only supported fields in raw WebSocket queries.

affects: >=3.0.0

gotchaWebhookService.constructEvent expects the request body as a string (not Buffer) and the signature header as a string. Express raw body middleware required.

fix

Use express.raw({ type: 'application/json' }) and pass req.body.toString() to constructEvent.

affects: >=3.0.0

deprecatedOld import path 'finlight-client/dist/...' no longer works as of v3.

fix

Use import { FinlightApi } from 'finlight-client' directly.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: finlight_client.default is not a function

Using default import instead of named import; package has no default export.

fix

Use import { FinlightApi } from 'finlight-client'.

WebSocket connection failed: Invalid query field 'ticker'

Using enhanced WebSocket query syntax (e.g., ticker:) on Raw WebSocket (wss://wss.finlight.me/raw).

fix

Use only supported fields for Raw WebSocket: source:, title:, summary:.

Webhook verification failed: signature mismatch

Missing or incorrect x-webhook-signature header or wrong secret.

fix

Ensure the webhook secret matches the one configured in finlight dashboard and pass the correct header value.

Cannot read properties of undefined (reading 'fetchArticles')

FinlightApi instance not properly initialized (apiKey missing or invalid).

fix

Provide a valid apiKey in the constructor options.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jubeiargh/finlight-client ↗

packagefinlight-client ↗

homepagehttps://finlight.me ↗