firehose-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef4dac25083ab9471245c47df41233e04e19e12282153e43e630603195d7e1cc
-  data.tar.gz: 36db7c5b6534a76cbdd88158792fc614524ce7fa3ccce0ed396eb608fa478484
+  metadata.gz: 6fa8dc1d77ce7ec26e1db82f13a26094970b1294388bf2e0c0b4c7aa266f9c5d
+  data.tar.gz: b2f8784af1ad95c67cb5467607ba546ad6bd183a243367b124576865705eb398
 SHA512:
-  metadata.gz: 9335a0468cb38b470b67edde432d05e6b96ac3e6209c2b66a51667754f9888eeccb9f8bf8944dcb91c175f15dbe8528343f01bc3c2e93429db55ccbb5003a2ac
-  data.tar.gz: cec5635b29ca8b3a592fc79b4333baf6e1ae472f47bf2858d0cd11e17849ebe5b55233cae584f87fae1039b8a6c8d282dd7561b8a66cfb5d962a8fcb8a974dcc
+  metadata.gz: 58c1f5933095b7f2ab7a82c3559643241398aa3524e477340f0a62199b9a4478229fccdc66d928570c59e4f054082adb25775bbbd313fc0725dccafdc8996304
+  data.tar.gz: 7bf960e0a49fb20b142126bafcbc538565e5e1fa91bc170e38994835bbd0d550c07c35d7b38f8b106452c0b243b31742ac1021aaedabf8941dbba6d78c6cd8c7

data/README.md

@@ -1,27 +1,33 @@
 # firehose-rb
 
-Ruby client for the Firehose real-time web monitoring API. SSE streaming with auto-reconnect, rules CRUD, and offset tracking.
+[![Gem Version](https://badge.fury.io/rb/firehose-rb.svg)](https://rubygems.org/gems/firehose-rb)
+
+Ruby client for the [Firehose](https://firehose.dev) real-time web monitoring API. Define rules, stream matching pages as they're discovered, and build content pipelines on top of the live web.
 
 ## Installation
 
 ```ruby
-gem "firehose-rb", path: "../firehose-rb"
+gem "firehose-rb", "~> 0.1"
 ```
 
+Then `bundle install`.
+
 ## Configuration
 
 ```ruby
 Firehose.configure do |c|
-  c.management_key = "fhm_..."
-  c.tap_token = "fh_..."
-  c.base_url = "https://api.firehose.dev"  # default
-  c.timeout = 300                           # SSE timeout in seconds
+  c.management_key = ENV["FIREHOSE_MANAGEMENT_KEY"]  # fhm_...
+  c.tap_token      = ENV["FIREHOSE_TAP_TOKEN"]       # fh_...
+  c.base_url       = "https://api.firehose.dev"      # default
+  c.timeout        = 300                              # SSE timeout in seconds
 end
 ```
 
 ## Usage
 
-### Rules CRUD
+### Rules
+
+Rules tell Firehose what to watch for. They use Lucene query syntax.
 
 ```ruby
 client = Firehose.client
@@ -33,7 +39,7 @@ rule = client.create_rule(
   quality: true
 )
 
-# List rules
+# List all rules
 rules = client.list_rules
 
 # Delete a rule
@@ -42,38 +48,65 @@ client.delete_rule(rule.id)
 
 ### Streaming
 
+Connect to the SSE stream and process matching pages in real time.
+
 ```ruby
 client = Firehose.client
 
-# Track offsets for resume
+# Persist offsets so you can resume after restart
 client.on_offset { |offset| save_offset(offset) }
 
 # Stream events (auto-reconnects with exponential backoff)
 client.stream(since: "1h") do |event|
-  event.id              # String
-  event.document.url    # String
-  event.document.title  # String
-  event.document.markdown # String (full page content)
-  event.matched_rule    # String (tag)
-  event.matched_at      # Time
+  event.id                    # String — unique event ID
+  event.document.url          # String — page URL
+  event.document.title        # String — page title
+  event.document.markdown     # String — full page content as markdown
+  event.document.categories   # Array  — page categories
+  event.document.types        # Array  — page types (article, blog, etc.)
+  event.document.language     # String — detected language
+  event.document.publish_time # Time   — when the page was published
+  event.matched_rule          # String — which rule tag matched
+  event.matched_at            # Time   — when the match occurred
 end
 
-# Stop streaming
+# Stop streaming gracefully
 client.stop_stream
 ```
 
+### Resilience
+
+- Auto-reconnect with exponential backoff (1s, 2s, 4s, ... max 30s)
+- `Last-Event-ID` header sent on reconnect for automatic resume
+- `on_offset` callback for persisting stream position
+- Authentication errors (`401/403`) are not retried
+
 ## Data Structures
 
-- `Firehose::Rule` — id, value, tag, quality, nsfw
-- `Firehose::Event` — id, document, matched_rule, matched_at
-- `Firehose::Document` — url, title, markdown, categories, types, language, publish_time
+| Struct | Fields |
+|--------|--------|
+| `Firehose::Rule` | id, value, tag, quality, nsfw |
+| `Firehose::Event` | id, document, matched_rule, matched_at |
+| `Firehose::Document` | url, title, markdown, categories, types, language, publish_time |
+
+## Errors
+
+| Error | Cause |
+|-------|-------|
+| `Firehose::AuthenticationError` | Invalid management_key or tap_token |
+| `Firehose::RateLimitError` | Too many requests (429) |
+| `Firehose::ConnectionError` | Network or HTTP errors |
+| `Firehose::TimeoutError` | Stream or request timeout |
+
+## Requirements
+
+- Ruby >= 3.1
+- [Faraday](https://github.com/lostisland/faraday) ~> 2.0
+
+## Used by
 
-## Error Handling
+Built for [InventList](https://inventlist.com) — a home for indie builders that turns the live web into weekly signals for makers and their agents.
 
-- `Firehose::AuthenticationError` — invalid API keys
-- `Firehose::RateLimitError` — rate limited
-- `Firehose::ConnectionError` — connection failures
-- `Firehose::TimeoutError` — request timeout
+## License
 
-SSE streaming auto-reconnects with exponential backoff (1s → 2s → 4s → max 30s).
-Authentication errors are not retried.
+MIT

data/lib/firehose/client.rb

@@ -10,28 +10,83 @@ module Firehose
       @stream = Stream.new(config: config)
     end
 
-    # Rules CRUD
+    # Tap management (requires management key)
 
-    def create_rule(value:, tag: nil, quality: false, nsfw: false)
-      body = { value: value, tag: tag, quality: quality, nsfw: nsfw }.compact
-      response = management_connection.post("/rules", body.to_json)
+    def list_taps
+      response = management_connection.get("/v1/taps")
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Array(parsed["data"]).map { |t| Tap.from_hash(t) }
+    end
+
+    def create_tap(name:)
+      response = management_connection.post("/v1/taps", { name: name }.to_json)
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      tap_data = parsed["data"] || parsed
+      tap_data["token"] = parsed["token"] if parsed["token"]
+      Tap.from_hash(tap_data)
+    end
+
+    def get_tap(tap_id)
+      response = management_connection.get("/v1/taps/#{tap_id}")
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Tap.from_hash(parsed["data"] || parsed)
+    end
+
+    def update_tap(tap_id, name:)
+      response = management_connection.put("/v1/taps/#{tap_id}", { name: name }.to_json)
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Tap.from_hash(parsed["data"] || parsed)
+    end
+
+    def revoke_tap(tap_id)
+      response = management_connection.delete("/v1/taps/#{tap_id}")
       handle_response(response)
-      Rule.from_hash(JSON.parse(response.body))
+      true
     end
 
+    # Rules CRUD (requires tap token)
+
     def list_rules
-      response = management_connection.get("/rules")
+      response = tap_connection.get("/v1/rules")
       handle_response(response)
-      JSON.parse(response.body).map { |r| Rule.from_hash(r) }
+      parsed = JSON.parse(response.body)
+      Array(parsed["data"] || parsed).map { |r| Rule.from_hash(r) }
+    end
+
+    def create_rule(value:, tag: nil, quality: true, nsfw: false)
+      body = { value: value, tag: tag, quality: quality, nsfw: nsfw }.compact
+      response = tap_connection.post("/v1/rules", body.to_json)
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Rule.from_hash(parsed["data"] || parsed)
+    end
+
+    def get_rule(rule_id)
+      response = tap_connection.get("/v1/rules/#{rule_id}")
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Rule.from_hash(parsed["data"] || parsed)
+    end
+
+    def update_rule(rule_id, value: nil, tag: nil, quality: nil, nsfw: nil)
+      body = { value: value, tag: tag, quality: quality, nsfw: nsfw }.compact
+      response = tap_connection.put("/v1/rules/#{rule_id}", body.to_json)
+      handle_response(response)
+      parsed = JSON.parse(response.body)
+      Rule.from_hash(parsed["data"] || parsed)
     end
 
     def delete_rule(rule_id)
-      response = management_connection.delete("/rules/#{rule_id}")
+      response = tap_connection.delete("/v1/rules/#{rule_id}")
       handle_response(response)
       true
     end
 
-    # Streaming
+    # Streaming (requires tap token)
 
     def stream(since: nil, &block)
       raise ArgumentError, "block required" unless block_given?
@@ -57,10 +112,18 @@ module Firehose
       end
     end
 
+    def tap_connection
+      @tap_connection ||= Faraday.new(url: @config.base_url) do |f|
+        f.headers["Authorization"] = "Bearer #{@config.tap_token}"
+        f.headers["Content-Type"] = "application/json"
+        f.adapter Faraday.default_adapter
+      end
+    end
+
     def handle_response(response)
       case response.status
       when 200..299 then nil
-      when 401, 403 then raise AuthenticationError, "Invalid management key"
+      when 401, 403 then raise AuthenticationError, "Invalid API key"
       when 429 then raise RateLimitError, "Rate limited"
       else raise Error, "HTTP #{response.status}: #{response.body}"
       end

data/lib/firehose/stream.rb

@@ -77,7 +77,7 @@ module Firehose
     end
 
     def build_uri(since: nil)
-      uri = URI.join(@config.base_url, "/stream")
+      uri = URI.join(@config.base_url, "/v1/stream")
       params = {}
       params["since"] = since if since
       uri.query = URI.encode_www_form(params) if params.any?

data/lib/firehose/tap.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Firehose
+  Tap = Data.define(:id, :name, :token, :token_prefix, :rules_count, :last_used_at, :created_at) do
+    def initialize(id:, name:, token: nil, token_prefix: nil, rules_count: 0, last_used_at: nil, created_at: nil)
+      super
+    end
+
+    def self.from_hash(hash)
+      new(
+        id: hash["id"] || hash[:id],
+        name: hash["name"] || hash[:name],
+        token: hash["token"] || hash[:token],
+        token_prefix: hash["token_prefix"] || hash[:token_prefix],
+        rules_count: hash["rules_count"] || hash[:rules_count] || 0,
+        last_used_at: hash["last_used_at"] || hash[:last_used_at],
+        created_at: hash["created_at"] || hash[:created_at]
+      )
+    end
+  end
+end

data/lib/firehose.rb

@@ -2,6 +2,7 @@
 
 require_relative "firehose/error"
 require_relative "firehose/rule"
+require_relative "firehose/tap"
 require_relative "firehose/document"
 require_relative "firehose/event"
 require_relative "firehose/stream"
@@ -12,7 +13,7 @@ module Firehose
     attr_accessor :management_key, :tap_token, :base_url, :timeout
 
     def initialize
-      @base_url = "https://api.firehose.dev"
+      @base_url = "https://api.firehose.com"
       @timeout = 300
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: firehose-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -51,8 +51,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.18'
-description: SSE streaming client with rules CRUD, auto-reconnect, and offset tracking
-  for the Firehose API.
+description: Full-featured Ruby client for the Firehose API — tap management, rules
+  CRUD (create, read, update, delete), SSE streaming with auto-reconnect and offset
+  tracking.
 email:
 - nauman@intellecta.co
 executables: []
@@ -67,6 +68,7 @@ files:
 - lib/firehose/event.rb
 - lib/firehose/rule.rb
 - lib/firehose/stream.rb
+- lib/firehose/tap.rb
 homepage: https://github.com/nauman/firehose-rb
 licenses:
 - MIT