finlight-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 708938713e1f97553c96baf010eb5d314a8cc04a9450d9555f20e73e79f66f47
+  data.tar.gz: e9528ef5a54995767df07e1d6a863a3a30fb5f26713520a716d6b0e0617249a5
+SHA512:
+  metadata.gz: 2d34def24369e14979d80c40bd6f29a841cfa42df0cf0e07be6949884030205787a9179149f7df098989b4c8e27bfc31d84c9e146299bda8fda315ce0e5a443e
+  data.tar.gz: 28ea56c433b06ee1b9ee1c3e592349e570c9d3bf8f03d6387cb7f45444f2752453178b3c9537a3bbe61f16eb635464de4882fcebfb31c74cdc0aac18a73140ce

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finlight.me
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# finlight-client (Ruby)
+
+The official Ruby client for the [finlight.me](https://finlight.me) API — financial news with sentiment analysis, entity recognition, and real-time streaming.
+
+📚 **Full API documentation: [docs.finlight.me](https://docs.finlight.me)**
+
+## Features
+
+- **REST API**: search articles, fetch single articles by link, list sources
+- **Real-time streaming**: enhanced and raw article streams over WebSocket
+- **Resilient by default**: request retries with exponential backoff; WebSocket auto-reconnect, keepalive with pong watchdog, proactive connection rotation, and rate-limit handling
+- **Webhook support**: HMAC-SHA256 signature verification with replay protection
+- **Minimal dependencies**: stdlib `Net::HTTP` and `OpenSSL`, plus the pure-Ruby `websocket-driver`
+
+Requires Ruby 3.2+.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "finlight-client"
+```
+
+Or directly:
+
+```bash
+gem install finlight-client
+```
+
+## Quick Start
+
+```ruby
+require "finlight/client"
+
+client = Finlight::Client.new(api_key: ENV["FINLIGHT_API_KEY"])
+
+response = client.articles.fetch_articles(query: "nvidia", page_size: 10)
+response.articles.each { |article| puts "[#{article.source}] #{article.title}" }
+```
+
+## REST API
+
+### Search articles
+
+See the [query language reference](https://docs.finlight.me) for the full `query` syntax. Parameters are snake_case keywords; they map 1:1 to the camelCase API fields.
+
+```ruby
+response = client.articles.fetch_articles(
+  query: '(ticker:AAPL OR ticker:NVDA) AND "Elon Musk"',
+  tickers: %w[AAPL NVDA],
+  from: "2025-01-01",
+  include_content: true,
+  include_entities: true,
+  order_by: "publishDate",
+  order: "DESC",
+  page_size: 20
+)
+
+response.articles.each do |article|
+  puts "#{article.publish_date} #{article.title} (#{article.sentiment})"
+end
+```
+
+### Fetch a single article by link
+
+```ruby
+article = client.articles.fetch_article_by_link(
+  link: "https://www.reuters.com/technology/example",
+  include_content: true
+)
+```
+
+### List sources
+
+```ruby
+sources = client.sources.get_sources
+defaults = sources.select(&:is_default_source)
+```
+
+## Real-time streaming
+
+`connect` blocks and reconnects automatically until you call `stop`; use `connect_async` to run it on a background thread. The enhanced stream delivers articles with sentiment and entities; the raw stream (`client.raw_websocket`) delivers unenriched articles with minimal latency.
+
+```ruby
+websocket = client.websocket
+websocket.connect(tickers: %w[AAPL NVDA], extended: true) do |article|
+  puts article.title
+end
+```
+
+Custom stream options:
+
+```ruby
+websocket = client.websocket(
+  takeover: true, # take over an existing connection for the same key
+  on_close: ->(code, reason) { puts "closed: #{code} #{reason}" }
+)
+thread = websocket.connect_async(query: "bitcoin") { |article| puts article.title }
+# ...
+websocket.stop
+thread.join
+```
+
+If the server permanently rejects the connection (close code 1008), `connect` raises `Finlight::BlockedError` — reconnecting will not help; contact support.
+
+## Webhooks
+
+Verify incoming webhooks with the raw (unparsed) request body:
+
+```ruby
+# e.g. in a Rails controller
+def webhook
+  article = Finlight::WebhookService.construct_event(
+    request.raw_post,
+    request.headers["X-Webhook-Signature"],
+    ENV["WEBHOOK_SECRET"],
+    request.headers["X-Webhook-Timestamp"]
+  )
+  Rails.logger.info("New article: #{article.title}")
+  head :ok
+rescue Finlight::WebhookVerificationError
+  head :bad_request
+end
+```
+
+## Configuration
+
+| Option         | Default                   | Description                                     |
+| -------------- | ------------------------- | ----------------------------------------------- |
+| `base_url:`    | `https://api.finlight.me` | REST endpoint                                   |
+| `wss_url:`     | `wss://wss.finlight.me`   | WebSocket endpoint                              |
+| `timeout:`     | 5                         | Per-request and connect timeout in seconds      |
+| `retry_count:` | 3                         | Total attempts for retryable failures (429/5xx) |
+| `logger:`      | stderr, WARN              | Any stdlib-compatible `Logger`                  |
+
+```ruby
+client = Finlight::Client.new(
+  api_key: api_key,
+  timeout: 10,
+  retry_count: 5,
+  logger: Logger.new($stdout, level: Logger::INFO)
+)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake        # run the test suite
+```
+
+### Verification against the real API
+
+The `local/` directory is gitignored and holds smoke runners, mirroring the sibling clients — keep credentials in the environment, never in code.
+
+```bash
+# One-shot smoke: REST endpoints + 30s article stream
+FINLIGHT_API_KEY=sk_... bundle exec ruby local/smoke.rb
+
+# REST integration tests (auto-skipped when the key is not set)
+FINLIGHT_API_KEY=sk_... bundle exec rspec spec/integration
+```
+
+Optional: `FINLIGHT_BASE_URL` / `FINLIGHT_WSS_URL` to target dev.
+
+## License
+
+[MIT](LICENSE)

data/lib/finlight/api_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Finlight
+  # Performs authenticated REST requests with retry and exponential backoff
+  # (500ms * 2^(attempt-1)), mirroring the sibling clients: retries on 429 and
+  # transient 5xx.
+  class ApiClient
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    BASE_RETRY_DELAY = 0.5
+
+    def initialize(config, logger: Logging.default)
+      @config = config
+      @logger = logger
+    end
+
+    # @return [Object] the decoded JSON response
+    def get(path, query = {})
+      uri = URI.parse(@config.base_url + path)
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      perform(uri, Net::HTTP::Get.new(uri))
+    end
+
+    # @return [Object] the decoded JSON response
+    def post(path, body)
+      uri = URI.parse(@config.base_url + path)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(body)
+      perform(uri, request)
+    end
+
+    private
+
+    def perform(uri, request)
+      request["X-API-KEY"] = @config.api_key
+      request["User-Agent"] = Client::CLIENT_VERSION
+
+      attempt = 0
+      loop do
+        attempt += 1
+        response = execute(uri, request)
+        status = response.code.to_i
+        return decode(response.body.to_s) if (200..299).cover?(status)
+
+        if RETRYABLE_STATUSES.include?(status) && attempt < @config.retry_count
+          delay = BASE_RETRY_DELAY * (2**(attempt - 1))
+          @logger.warn do
+            "finlight: retrying request (status=#{status}, " \
+              "attempt=#{attempt}/#{@config.retry_count}, delay=#{(delay * 1000).round}ms)"
+          end
+          sleep(delay)
+          next
+        end
+
+        raise ApiError.new(status, response.body.to_s)
+      end
+    end
+
+    def execute(uri, request)
+      Net::HTTP.start(
+        uri.hostname, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @config.timeout,
+        read_timeout: @config.timeout,
+        write_timeout: @config.timeout
+      ) { |http| http.request(request) }
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+           OpenSSL::SSL::SSLError, SystemCallError, IOError => e
+      raise Error, "finlight: request failed: #{e.message}"
+    end
+
+    def decode(body)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise Error, "finlight: cannot decode response: #{e.message}"
+    end
+  end
+end

data/lib/finlight/article_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Fetches financial news articles.
+  class ArticleService
+    def initialize(api_client)
+      @api_client = api_client
+    end
+
+    # Searches articles with advanced filtering by query, tickers, sources,
+    # dates, countries and categories.
+    #
+    # @example
+    #   response = client.articles.fetch_articles(
+    #     query: "Nvidia", tickers: ["NVDA"], include_content: true, page_size: 20
+    #   )
+    #   response.articles.each { |a| puts a.title }
+    #
+    # @param params [Hash] snake_case keywords, e.g. +query:+, +sources:+,
+    #   +exclude_sources:+, +from:+, +to:+, +language:+, +tickers:+,
+    #   +include_entities:+, +exclude_empty_content:+, +include_content:+,
+    #   +order_by:+ ("publishDate"|"createdAt"|"revisedDate"),
+    #   +order:+ ("ASC"|"DESC"), +page_size:+ (1-1000), +page:+, +countries:+,
+    #   +categories:+
+    # @return [ArticleResponse]
+    # @raise [ApiError] if the API request fails
+    def fetch_articles(**params)
+      response = @api_client.post("/v2/articles", Params.normalize(params))
+      ArticleResponse.from_h(response)
+    end
+
+    # Fetches a single article by its URL.
+    #
+    # @example
+    #   article = client.articles.fetch_article_by_link(
+    #     link: "https://www.reuters.com/technology/example", include_content: true
+    #   )
+    #
+    # @param link [String] the URL of the article to fetch
+    # @param params [Hash] optional +include_content:+ and +include_entities:+
+    # @return [Article]
+    # @raise [ApiError] if the API request fails or the article is not found
+    def fetch_article_by_link(link:, **params)
+      query = Params.normalize(params.merge(link: link))
+      query = query.transform_values { |v| [true, false].include?(v) ? v.to_s : v }
+      response = @api_client.get("/v2/articles/by-link", query)
+      Article.from_h(response.fetch("article"))
+    end
+  end
+end

data/lib/finlight/client/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Finlight
+  class Client
+    VERSION = "0.1.0"
+
+    # Identifier sent as User-Agent (REST) and x-client-version (WebSocket).
+    CLIENT_VERSION = "ruby/finlight-client@#{VERSION}".freeze
+  end
+end

data/lib/finlight/client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "client/version"
+require_relative "errors"
+require_relative "logging"
+require_relative "config"
+require_relative "flex_time"
+require_relative "params"
+require_relative "models"
+require_relative "api_client"
+require_relative "article_service"
+require_relative "source_service"
+require_relative "webhook_service"
+require_relative "websocket/base_client"
+require_relative "websocket/article_client"
+require_relative "websocket/raw_article_client"
+
+module Finlight
+  # Entry point to the finlight API.
+  #
+  # @example
+  #   client = Finlight::Client.new(api_key: ENV["FINLIGHT_API_KEY"])
+  #   response = client.articles.fetch_articles(query: "Nvidia", page_size: 20)
+  #   response.articles.each { |article| puts article.title }
+  class Client
+    attr_reader :config, :articles, :sources
+
+    # Remaining keywords (+base_url:+, +wss_url:+, +timeout:+ in seconds,
+    # +retry_count:+) are forwarded to {Config}.
+    #
+    # @param api_key [String] your finlight API key
+    def initialize(api_key:, logger: Logging.default, **)
+      @config = Config.new(api_key: api_key, **)
+      @logger = logger
+      api_client = ApiClient.new(@config, logger: logger)
+      @articles = ArticleService.new(api_client)
+      @sources = SourceService.new(api_client)
+    end
+
+    # A streaming client for enriched articles — see
+    # {BaseWebSocketClient#connect} for options and usage.
+    #
+    # @return [ArticleWebSocketClient]
+    def websocket(**)
+      ArticleWebSocketClient.new(@config, logger: @logger, **)
+    end
+
+    # A streaming client for raw articles (minimal latency, no enrichment).
+    #
+    # @return [RawArticleWebSocketClient]
+    def raw_websocket(**)
+      RawArticleWebSocketClient.new(@config, logger: @logger, **)
+    end
+  end
+end

data/lib/finlight/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Connection settings shared by the REST and WebSocket clients.
+  class Config
+    DEFAULT_BASE_URL = "https://api.finlight.me"
+    DEFAULT_WSS_URL = "wss://wss.finlight.me"
+    DEFAULT_TIMEOUT = 5
+    DEFAULT_RETRY_COUNT = 3
+
+    attr_reader :api_key, :base_url, :wss_url, :timeout, :retry_count
+
+    # @param api_key [String] your finlight API key
+    # @param base_url [String] REST endpoint
+    # @param wss_url [String] WebSocket endpoint
+    # @param timeout [Numeric] per-request and connect timeout in seconds
+    # @param retry_count [Integer] total attempts for retryable failures (429/5xx)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, wss_url: DEFAULT_WSS_URL,
+                   timeout: DEFAULT_TIMEOUT, retry_count: DEFAULT_RETRY_COUNT)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @wss_url = wss_url.chomp("/")
+      @timeout = timeout
+      @retry_count = retry_count
+    end
+  end
+end

data/lib/finlight/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Base class for all errors raised by this library.
+  class Error < StandardError; end
+
+  # Raised when the API responds with a non-success status code.
+  class ApiError < Error
+    attr_reader :status_code, :body
+
+    def initialize(status_code, body)
+      @status_code = status_code
+      @body = body
+      super("finlight: API request failed with status #{status_code}: #{body}")
+    end
+  end
+
+  # Raised when the streaming server permanently rejects the connection
+  # (close code 1008). Reconnecting will not help; contact support.
+  class BlockedError < Error
+    def initialize(msg = "finlight: connection rejected by server (blocked)")
+      super
+    end
+  end
+
+  # Raised when webhook signature or timestamp verification fails.
+  class WebhookVerificationError < Error; end
+end

data/lib/finlight/flex_time.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Finlight
+  # Parses the timestamp formats used by the finlight API: RFC 3339 with or
+  # without zone, space-separated, and date-only. Zone-less timestamps are
+  # interpreted as UTC, matching the sibling clients.
+  module FlexTime
+    module_function
+
+    # @param value [String, Time, nil]
+    # @return [Time, nil] the parsed time in UTC, or nil for nil input
+    # @raise [Finlight::Error] if the value matches none of the known formats
+    def parse(value)
+      return nil if value.nil?
+      return value.utc if value.is_a?(Time)
+
+      s = value.to_s.strip
+      iso_like = s.include?(" ") ? s.sub(" ", "T") : s
+      DateTime.iso8601(iso_like).to_time.utc
+    rescue ArgumentError, TypeError
+      raise Error, "finlight: cannot parse timestamp: #{value.inspect}"
+    end
+  end
+end

data/lib/finlight/logging.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Finlight
+  # Default logger shared by the clients: warnings and errors to stderr.
+  # Pass your own +logger:+ to the client or WebSocket clients to override.
+  module Logging
+    module_function
+
+    def default
+      @default ||= Logger.new($stderr, level: Logger::WARN, progname: "finlight")
+    end
+  end
+end

data/lib/finlight/models.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Shared parsing helpers for wire-format (camelCase) JSON hashes.
+  module ModelParsing
+    module_function
+
+    # The API sometimes delivers numbers as strings (e.g. "confidence":"0.9").
+    def to_float(value)
+      return nil if value.nil?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def to_string_list(value)
+      value&.map(&:to_s)
+    end
+  end
+
+  # A ticker listing on an exchange.
+  class Listing
+    attr_reader :ticker, :exchange_code, :exchange_country
+
+    def initialize(ticker:, exchange_code:, exchange_country:)
+      @ticker = ticker
+      @exchange_code = exchange_code
+      @exchange_country = exchange_country
+    end
+
+    def self.from_h(hash)
+      new(
+        ticker: hash["ticker"],
+        exchange_code: hash["exchangeCode"],
+        exchange_country: hash["exchangeCountry"]
+      )
+    end
+  end
+
+  # A company tagged in an article.
+  class Company
+    attr_reader :company_id, :confidence, :country, :exchange, :industry, :sector,
+                :name, :ticker, :isin, :openfigi, :primary_listing, :isins, :other_listings
+
+    def initialize(company_id:, name:, ticker:, confidence: nil, country: nil, exchange: nil,
+                   industry: nil, sector: nil, isin: nil, openfigi: nil, primary_listing: nil,
+                   isins: nil, other_listings: nil)
+      @company_id = company_id
+      @confidence = confidence
+      @country = country
+      @exchange = exchange
+      @industry = industry
+      @sector = sector
+      @name = name
+      @ticker = ticker
+      @isin = isin
+      @openfigi = openfigi
+      @primary_listing = primary_listing
+      @isins = isins
+      @other_listings = other_listings
+    end
+
+    def self.from_h(hash)
+      new(
+        company_id: hash["companyId"],
+        confidence: ModelParsing.to_float(hash["confidence"]),
+        country: hash["country"],
+        exchange: hash["exchange"],
+        industry: hash["industry"],
+        sector: hash["sector"],
+        name: hash["name"],
+        ticker: hash["ticker"],
+        isin: hash["isin"],
+        openfigi: hash["openfigi"],
+        primary_listing: hash["primaryListing"] && Listing.from_h(hash["primaryListing"]),
+        isins: ModelParsing.to_string_list(hash["isins"]),
+        other_listings: hash["otherListings"]&.map { |l| Listing.from_h(l) }
+      )
+    end
+  end
+
+  # An unenriched article as delivered by the raw stream.
+  class RawArticle
+    attr_reader :link, :title, :publish_date, :source, :language, :summary, :images,
+                :created_at, :revised_date, :is_update, :categories
+
+    def initialize(link:, title:, publish_date:, source:, language:, summary: nil, images: nil,
+                   created_at: nil, revised_date: nil, is_update: nil, categories: nil, **)
+      @link = link
+      @title = title
+      @publish_date = publish_date
+      @source = source
+      @language = language
+      @summary = summary
+      @images = images
+      @created_at = created_at
+      @revised_date = revised_date
+      @is_update = is_update
+      @categories = categories
+    end
+
+    def self.base_attributes(hash)
+      {
+        link: hash["link"],
+        title: hash["title"],
+        publish_date: FlexTime.parse(hash["publishDate"]),
+        source: hash["source"],
+        language: hash["language"],
+        summary: hash["summary"],
+        images: ModelParsing.to_string_list(hash["images"]),
+        created_at: FlexTime.parse(hash["createdAt"]),
+        revised_date: FlexTime.parse(hash["revisedDate"]),
+        is_update: hash["isUpdate"],
+        categories: ModelParsing.to_string_list(hash["categories"])
+      }
+    end
+
+    def self.from_h(hash)
+      new(**base_attributes(hash))
+    end
+  end
+
+  # An enriched article with sentiment, entities and content.
+  class Article < RawArticle
+    attr_reader :sentiment, :confidence, :content, :companies, :countries
+
+    def initialize(sentiment: nil, confidence: nil, content: nil, companies: nil,
+                   countries: nil, **base)
+      super(**base)
+      @sentiment = sentiment
+      @confidence = confidence
+      @content = content
+      @companies = companies
+      @countries = countries
+    end
+
+    def self.from_h(hash)
+      new(
+        **base_attributes(hash),
+        sentiment: hash["sentiment"],
+        confidence: ModelParsing.to_float(hash["confidence"]),
+        content: hash["content"],
+        companies: hash["companies"]&.map { |c| Company.from_h(c) },
+        countries: ModelParsing.to_string_list(hash["countries"])
+      )
+    end
+  end
+
+  # A page of search results.
+  class ArticleResponse
+    attr_reader :status, :page, :page_size, :articles
+
+    def initialize(status:, page:, page_size:, articles:)
+      @status = status
+      @page = page
+      @page_size = page_size
+      @articles = articles
+    end
+
+    def self.from_h(hash)
+      new(
+        status: hash["status"],
+        page: hash["page"],
+        page_size: hash["pageSize"],
+        articles: (hash["articles"] || []).map { |a| Article.from_h(a) }
+      )
+    end
+  end
+
+  # A news source available through the API.
+  class Source
+    attr_reader :domain, :is_content_available, :is_default_source
+
+    def initialize(domain:, is_content_available:, is_default_source:)
+      @domain = domain
+      @is_content_available = is_content_available
+      @is_default_source = is_default_source
+    end
+
+    def self.from_h(hash)
+      new(
+        domain: hash["domain"],
+        is_content_available: hash["isContentAvailable"] == true,
+        is_default_source: hash["isDefaultSource"] == true
+      )
+    end
+  end
+end

data/lib/finlight/params.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Converts idiomatic snake_case Ruby keyword arguments into the camelCase
+  # JSON wire format, omitting unset (nil) fields. Keys that are already
+  # camelCase pass through unchanged.
+  module Params
+    module_function
+
+    # @param params [Hash]
+    # @return [Hash{String => Object}]
+    def normalize(params)
+      params.each_with_object({}) do |(key, value), out|
+        next if value.nil?
+
+        out[camelize(key)] = value
+      end
+    end
+
+    # page_size -> pageSize, exclude_sources -> excludeSources, from -> from
+    def camelize(key)
+      key.to_s.gsub(/_([a-z0-9])/) { Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/finlight/source_service.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Lists the news sources available through the API.
+  class SourceService
+    def initialize(api_client)
+      @api_client = api_client
+    end
+
+    # @return [Array<Source>] all available news sources
+    # @raise [ApiError] if the API request fails
+    def get_sources # rubocop:disable Naming/AccessorMethodName -- mirrors the sibling clients' API
+      @api_client.get("/v2/sources").map { |s| Source.from_h(s) }
+    end
+  end
+end

data/lib/finlight/webhook_service.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Finlight
+  # Securely receives and verifies webhook events from finlight: HMAC-SHA256
+  # signature verification with replay attack protection.
+  module WebhookService
+    SIGNATURE_PREFIX = "sha256="
+    REPLAY_TOLERANCE_SECONDS = 5 * 60
+
+    module_function
+
+    # Constructs and verifies a webhook event from raw request data.
+    #
+    # @example Rack/Rails endpoint
+    #   article = Finlight::WebhookService.construct_event(
+    #     request.raw_post,
+    #     request.headers["X-Webhook-Signature"],
+    #     ENV["WEBHOOK_SECRET"],
+    #     request.headers["X-Webhook-Timestamp"]
+    #   )
+    #
+    # @param raw_body [String] the raw, unparsed request body
+    # @param signature [String] the X-Webhook-Signature header (with or
+    #   without the "sha256=" prefix)
+    # @param endpoint_secret [String] your webhook secret from the dashboard
+    # @param timestamp [String, nil] the X-Webhook-Timestamp header; when
+    #   given it is included in the signed message and checked against a
+    #   5-minute replay tolerance
+    # @return [Article] the verified and parsed article
+    # @raise [WebhookVerificationError] if verification fails
+    def construct_event(raw_body, signature, endpoint_secret, timestamp = nil)
+      timestamp = nil if timestamp.to_s.empty?
+      normalized = signature.to_s.delete_prefix(SIGNATURE_PREFIX)
+
+      message = timestamp ? "#{timestamp}.#{raw_body}" : raw_body
+      expected = compute_signature(message, endpoint_secret)
+      raise WebhookVerificationError, "Invalid webhook signature" unless secure_compare(normalized, expected)
+
+      verify_timestamp(timestamp) if timestamp
+
+      parse_payload(raw_body)
+    end
+
+    def compute_signature(payload, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+    end
+
+    def verify_timestamp(timestamp)
+      begin
+        webhook_time = FlexTime.parse(timestamp)
+      rescue Error
+        raise WebhookVerificationError, "Invalid timestamp format"
+      end
+
+      return unless (Time.now.utc - webhook_time).abs > REPLAY_TOLERANCE_SECONDS
+
+      raise WebhookVerificationError, "Webhook timestamp outside allowed tolerance"
+    end
+
+    def parse_payload(raw_body)
+      data = begin
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        raise WebhookVerificationError, "Invalid JSON payload"
+      end
+
+      begin
+        Article.from_h(data)
+      rescue StandardError => e
+        raise WebhookVerificationError, "Invalid article data: #{e.message}"
+      end
+    end
+
+    def secure_compare(left, right)
+      return false unless left.bytesize == right.bytesize
+
+      OpenSSL.fixed_length_secure_compare(left, right)
+    end
+  end
+end

data/lib/finlight/websocket/article_client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Streams enriched articles (sentiment, entities, content). Duplicate
+  # deliveries are suppressed via a small cache of recent article links.
+  class ArticleWebSocketClient < BaseWebSocketClient
+    private
+
+    def websocket_url
+      @config.wss_url
+    end
+
+    def parse_article(data)
+      Article.from_h(data)
+    end
+
+    def article_id(article)
+      article.link
+    end
+  end
+end

data/lib/finlight/websocket/base_client.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+require "socket"
+require "uri"
+require "websocket/driver"
+
+module Finlight
+  # Shared implementation of the finlight streaming protocol: reconnect loop
+  # with exponential backoff, application-level ping/pong with watchdog,
+  # proactive connection rotation before the server-side lifetime cap, and
+  # optional duplicate suppression.
+  #
+  # Use the concrete {ArticleWebSocketClient} and {RawArticleWebSocketClient}
+  # obtained from {Client#websocket} and {Client#raw_websocket}.
+  class BaseWebSocketClient
+    RECENT_ARTICLE_CACHE_SIZE = 10
+    CLOSE_GRACE_SECONDS = 5
+    DIAL_RATE_LIMIT_BACKOFF_SECONDS = 60
+    ERROR_RATE_LIMIT_BACKOFF_SECONDS = 60
+    ERROR_BLOCKED_BACKOFF_SECONDS = 3600
+    DEFAULT_ADMIN_KICK_RETRY_MS = 900_000
+
+    # Close codes of the finlight WebSocket protocol.
+    CLOSE_BLOCKED = 1008
+    CLOSE_PROACTIVE_ROTATION = 4000
+    CLOSE_RATE_LIMITED = 4001
+    CLOSE_USER_BLOCKED = 4002
+    CLOSE_ADMIN_KICK = 4003
+
+    # Adapter between websocket-driver and the raw socket.
+    class DriverSocket
+      attr_reader :url
+
+      def initialize(url, io)
+        @url = url
+        @io = io
+      end
+
+      def write(data)
+        @io.write(data)
+      rescue StandardError
+        # The connection is going down; the read loop notices independently.
+      end
+    end
+
+    # @param config [Config]
+    # @param ping_interval [Numeric] seconds between application-level pings
+    # @param pong_timeout [Numeric] seconds without a pong before forcing a reconnect
+    # @param base_reconnect_delay [Numeric] initial reconnect backoff in seconds
+    # @param max_reconnect_delay [Numeric] backoff cap in seconds
+    # @param connection_lifetime [Numeric] seconds before proactively rotating
+    #   the connection (server caps connections at 2h)
+    # @param takeover [Boolean] take over an existing connection for the same key
+    # @param on_close [#call, nil] callback invoked with (code, reason) whenever
+    #   a connection closes
+    def initialize(config, ping_interval: 25, pong_timeout: 60,
+                   base_reconnect_delay: 0.5, max_reconnect_delay: 10.0,
+                   connection_lifetime: 115 * 60, takeover: false, on_close: nil,
+                   logger: Logging.default)
+      @config = config
+      @ping_interval = ping_interval
+      @pong_timeout = pong_timeout
+      @base_reconnect_delay = base_reconnect_delay
+      @max_reconnect_delay = max_reconnect_delay
+      @connection_lifetime = connection_lifetime
+      @takeover = takeover
+      @on_close = on_close
+      @logger = logger
+      @stop = false
+      @running = false
+      @recent_articles = []
+    end
+
+    # Connects to the stream and blocks, yielding every received article.
+    # Reconnects automatically (exponential backoff, honors server-mandated
+    # wait times) until {#stop} is called or the server preempts the
+    # connection in favor of a newer one.
+    #
+    # @param params [Hash] stream filters as snake_case keywords, e.g.
+    #   +query:+, +sources:+, +exclude_sources:+, +language:+, +tickers:+,
+    #   +extended:+, +include_entities:+, +exclude_empty_content:+,
+    #   +countries:+, +categories:+, +include_updates:+
+    # @yield [article] every article received on the stream
+    # @raise [BlockedError] if the server permanently rejected the connection
+    #   (close code 1008)
+    def connect(**params, &on_article)
+      raise ArgumentError, "finlight: connect requires a block" unless on_article
+      raise Error, "finlight: connect is already running on this client" if @running
+
+      @running = true
+      @stop = false
+      @reconnect_at = nil
+      payload = Params.normalize(params)
+      delay = @base_reconnect_delay
+
+      begin
+        until @stop
+          @logger.info { "finlight: connecting to #{websocket_url}" }
+          result = run_connection(payload, on_article)
+          raise BlockedError if result == :blocked
+          break if @stop
+
+          delay = @base_reconnect_delay if result == :connected
+
+          now = monotonic
+          if @reconnect_at && @reconnect_at > now
+            wait = @reconnect_at - now
+            @logger.info { "finlight: waiting #{wait.round(1)}s until server-mandated reconnect time" }
+          else
+            wait = delay
+            @logger.info { "finlight: reconnecting in #{wait.round(1)}s" }
+            delay = [delay * 2, @max_reconnect_delay].min
+          end
+          interruptible_sleep(wait)
+        end
+      ensure
+        @running = false
+      end
+      nil
+    end
+
+    # Runs {#connect} on a background thread and returns it. Joining the
+    # thread re-raises {BlockedError} if the stream ended that way.
+    #
+    # @return [Thread]
+    def connect_async(**params, &on_article)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        connect(**params, &on_article)
+      end
+    end
+
+    # Stops the stream: the current connection closes and the reconnect loop
+    # ends. Safe to call from any thread; {#connect} returns shortly after.
+    def stop
+      @stop = true
+      nil
+    end
+
+    private
+
+    # @return [String] the full WebSocket URL to connect to
+    def websocket_url
+      raise NotImplementedError
+    end
+
+    # @return [Object] the parsed article for a sendArticle payload
+    def parse_article(data)
+      raise NotImplementedError
+    end
+
+    # Identifier used for duplicate suppression, or nil to disable it.
+    def article_id(_article)
+      nil
+    end
+
+    def run_connection(payload, on_article)
+      uri = URI.parse(websocket_url)
+      begin
+        io = dial(uri)
+      rescue StandardError => e
+        @logger.error { "finlight: connection failed: #{e.message}" }
+        return :failed
+      end
+
+      begin
+        run_stream(io, payload, on_article)
+      ensure
+        begin
+          io.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    def dial(uri)
+      host = uri.host
+      secure = %w[wss https].include?(uri.scheme)
+      port = uri.port || (secure ? 443 : 80)
+      tcp = Socket.tcp(host, port, connect_timeout: @config.timeout)
+      return tcp unless secure
+
+      context = OpenSSL::SSL::SSLContext.new
+      context.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      context.cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+      ssl.hostname = host
+      ssl.sync_close = true
+      ssl.connect
+      ssl.post_connection_check(host)
+      ssl
+    end
+
+    def run_stream(io, payload, on_article)
+      state = {
+        opened: false, closed: nil, error: nil, stop_sent: false,
+        last_pong: monotonic, next_ping: nil, abort_at: nil,
+        rotate_at: monotonic + @connection_lifetime
+      }
+      nonce = SecureRandom.uuid
+
+      # The server reads these headers case-sensitively in exact lowercase.
+      driver = WebSocket::Driver.client(DriverSocket.new(websocket_url, io))
+      driver.set_header("x-api-key", @config.api_key)
+      driver.set_header("x-client-version", Client::CLIENT_VERSION)
+      driver.set_header("x-takeover", "true") if @takeover
+
+      driver.on(:open) do
+        state[:opened] = true
+        state[:last_pong] = monotonic
+        state[:next_ping] = monotonic + @ping_interval
+        @reconnect_at = nil
+        @logger.info { "finlight: connected" }
+        driver.text(JSON.generate(payload.merge("clientNonce" => nonce)))
+      end
+      driver.on(:message) { |event| handle_message(event.data, driver, state, nonce, on_article) }
+      driver.on(:close) { |event| state[:closed] ||= [event.code || 1006, event.reason.to_s] }
+      driver.on(:error) { |event| handle_driver_error(event.message.to_s, state) }
+
+      queue = Thread::Queue.new
+      reader = Thread.new do
+        Thread.current.report_on_exception = false
+        begin
+          loop { queue << io.readpartial(16_384) }
+        rescue StandardError
+          queue << :eof
+        end
+      end
+
+      driver.start
+      pump(driver, queue, state)
+
+      close_code, close_reason = state[:closed] || [1006, state[:error] || "connection lost"]
+      @logger.info { "finlight: connection closed: #{close_code} - #{close_reason}" }
+      notify_close(close_code, close_reason)
+
+      return :blocked if close_code == CLOSE_BLOCKED
+
+      state[:opened] ? :connected : :failed
+    ensure
+      reader&.kill
+    end
+
+    def pump(driver, queue, state)
+      until state[:closed]
+        break if state[:error] && !state[:opened]
+
+        if @stop
+          break unless state[:opened]
+
+          request_close(driver, state, "client stopped", 1000)
+        end
+
+        chunk = queue.pop(timeout: 0.2)
+        if chunk == :eof
+          state[:closed] ||= [1006, "connection lost"]
+          break
+        end
+        driver.parse(chunk) if chunk
+
+        now = monotonic
+        if state[:opened]
+          if state[:next_ping] && now >= state[:next_ping]
+            @logger.debug { "finlight: sending ping" }
+            driver.text(JSON.generate({ "action" => "ping", "t" => wallclock_millis }))
+            state[:next_ping] = now + @ping_interval
+          end
+          if now - state[:last_pong] > @pong_timeout
+            @logger.warn { "finlight: no pong received in time, forcing reconnect" }
+            break
+          end
+          if now >= state[:rotate_at]
+            @logger.info { "finlight: proactive rotation before server connection cap" }
+            state[:rotate_at] = Float::INFINITY
+            request_close(driver, state, "Proactive rotation", CLOSE_PROACTIVE_ROTATION)
+          end
+        end
+        break if state[:abort_at] && now >= state[:abort_at]
+      end
+    end
+
+    def handle_message(data, driver, state, nonce, on_article)
+      msg = begin
+        JSON.parse(data)
+      rescue JSON::ParserError => e
+        @logger.error { "finlight: cannot parse message: #{e.message}" }
+        nil
+      end
+      return unless msg.is_a?(Hash)
+
+      case msg["action"]
+      when "pong"
+        ping_time = msg["t"]
+        if ping_time
+          @logger.debug { "finlight: pong received (rtt=#{wallclock_millis - ping_time.to_i}ms)" }
+        else
+          @logger.debug { "finlight: pong received" }
+        end
+        state[:last_pong] = monotonic
+      when "admit"
+        @logger.info { "finlight: admitted (leaseId=#{msg["leaseId"]})" }
+        server_nonce = msg["clientNonce"].to_s
+        if !server_nonce.empty? && server_nonce != nonce
+          @logger.warn { "finlight: nonce mismatch: expected #{nonce}, got #{server_nonce}" }
+        end
+      when "preempted"
+        @logger.warn do
+          "finlight: connection preempted: #{msg.fetch("reason", "unknown")} " \
+            "(new lease: #{msg["newLeaseId"]})"
+        end
+        @stop = true
+        request_close(driver, state, "Preempted by server", 1000)
+      when "sendArticle"
+        handle_article(msg["data"] || {}, on_article)
+      when "admin_kick"
+        retry_after_ms = msg.fetch("retryAfter", DEFAULT_ADMIN_KICK_RETRY_MS).to_i
+        @reconnect_at = monotonic + (retry_after_ms / 1000.0)
+        @logger.warn { "finlight: admin kick - retry after #{retry_after_ms}ms" }
+        request_close(driver, state, "Admin kick", CLOSE_ADMIN_KICK)
+      when "error"
+        raw = msg["data"] || msg["error"] || ""
+        text = raw.is_a?(String) ? raw : JSON.generate(raw)
+        @logger.error { "finlight: server error: #{text}" }
+        if text.downcase.include?("limit")
+          @reconnect_at = monotonic + ERROR_RATE_LIMIT_BACKOFF_SECONDS
+          request_close(driver, state, "Rate limited", CLOSE_RATE_LIMITED)
+        elsif text.downcase.include?("blocked")
+          @reconnect_at = monotonic + ERROR_BLOCKED_BACKOFF_SECONDS
+          request_close(driver, state, "User blocked", CLOSE_USER_BLOCKED)
+        end
+      else
+        @logger.warn { "finlight: unknown message action: #{msg["action"]}" }
+      end
+    end
+
+    def handle_article(data, on_article)
+      article = begin
+        parse_article(data)
+      rescue StandardError => e
+        @logger.error { "finlight: cannot parse article: #{e.message}" }
+        nil
+      end
+      return if article.nil?
+
+      id = article_id(article)
+      if id
+        if @recent_articles.include?(id)
+          @logger.debug { "finlight: skipping duplicate article: #{id}" }
+          return
+        end
+        @recent_articles << id
+        @recent_articles.shift if @recent_articles.size > RECENT_ARTICLE_CACHE_SIZE
+      end
+
+      begin
+        on_article.call(article)
+      rescue StandardError => e
+        @logger.error { "finlight: article callback failed: #{e.message}" }
+      end
+    end
+
+    def handle_driver_error(message, state)
+      if message[/Unexpected response code: (\d+)/, 1].to_i == 429
+        @reconnect_at = monotonic + DIAL_RATE_LIMIT_BACKOFF_SECONDS
+        @logger.warn { "finlight: server rejected connection (429), backing off" }
+      else
+        @logger.error { "finlight: connection error: #{message}" }
+      end
+      state[:error] = message
+    end
+
+    # Sends a close frame once and arms a grace deadline in case the server
+    # never completes the close handshake.
+    def request_close(driver, state, reason, code)
+      return if state[:stop_sent]
+
+      state[:stop_sent] = true
+      state[:abort_at] = monotonic + CLOSE_GRACE_SECONDS
+      driver.close(reason, code)
+    end
+
+    def notify_close(code, reason)
+      return unless @on_close
+
+      begin
+        @on_close.call(code, reason)
+      rescue StandardError => e
+        @logger.error { "finlight: on_close callback failed: #{e.message}" }
+      end
+    end
+
+    def interruptible_sleep(seconds)
+      deadline = monotonic + seconds
+      sleep([0.05, deadline - monotonic].min) while !@stop && monotonic < deadline
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def wallclock_millis
+      (Time.now.to_f * 1000).to_i
+    end
+  end
+end

data/lib/finlight/websocket/raw_article_client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Finlight
+  # Streams unenriched articles with minimal latency. The raw stream delivers
+  # every message, including updates — no duplicate suppression.
+  class RawArticleWebSocketClient < BaseWebSocketClient
+    private
+
+    def websocket_url
+      "#{@config.wss_url}/raw"
+    end
+
+    def parse_article(data)
+      RawArticle.from_h(data)
+    end
+  end
+end

data/lib/finlight-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "finlight/client"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: finlight-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- finlight.me
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: 'Financial news with sentiment analysis, entity recognition and real-time
+  streaming: REST, WebSocket and webhook verification client for finlight.me.'
+email:
+- info@finlight.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/finlight-client.rb
+- lib/finlight/api_client.rb
+- lib/finlight/article_service.rb
+- lib/finlight/client.rb
+- lib/finlight/client/version.rb
+- lib/finlight/config.rb
+- lib/finlight/errors.rb
+- lib/finlight/flex_time.rb
+- lib/finlight/logging.rb
+- lib/finlight/models.rb
+- lib/finlight/params.rb
+- lib/finlight/source_service.rb
+- lib/finlight/webhook_service.rb
+- lib/finlight/websocket/article_client.rb
+- lib/finlight/websocket/base_client.rb
+- lib/finlight/websocket/raw_article_client.rb
+homepage: https://finlight.me
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://finlight.me
+  documentation_uri: https://docs.finlight.me
+  source_code_uri: https://github.com/callbk/finlight-client-ruby
+  changelog_uri: https://github.com/callbk/finlight-client-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/callbk/finlight-client-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the finlight.me API
+test_files: []