getfluxly 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b116ab1581f3a4774402e520e226448ebb08e91f41472871b550fa2f5b90138
+  data.tar.gz: 2e727e895ae664cb6bbb6f8520b550466e39c4ef68e3940b29f07f93f50f3607
+SHA512:
+  metadata.gz: a604060bfeccf108f38d1df090afcab54eaefe7bebb85320005978c7d250654df08faf26341b63e1dfe3a27306dac0207427e2bbf0d9f90871cf03ec4e0d8422
+  data.tar.gz: c3ae7ff9b11b088c972800e8bf4167d9ca4a6a58d8eb6cadb19ec836cf3616981575fa4aa3251a633130c5c58fb1fe5ac4883115c44ebc53223319a533a55545

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `getfluxly` (Ruby) will be documented in this file.
+
+## [0.1.0] - 2026-05-16
+
+### Added
+- Initial release of `getfluxly` Ruby gem.
+- `GetFluxly::Client` for synchronous server-side ingest against
+  `/v1/events/batch` and `/v1/identify/alias`.
+- Batched event queue with `flush_at`, `flush_interval`,
+  `max_queue_size`. `Net::HTTP` from stdlib; zero runtime gems.
+- Retry posture matching the Node and Python SDKs: 408 / 425 / 429
+  / 5xx with exponential backoff and +/- 25% jitter, `Retry-After`
+  honored, per-batch `X-Idempotency-Key`.
+- `GetFluxly::Error` with stable `code` strings from
+  `error-taxonomy.md`.
+- Opt-in Rails integration at `require "getfluxly/rails"`:
+  `GetFluxly::Rails.configure { ... }` + optional Rack middleware
+  that surfaces the browser-side `gflux_anon` cookie as
+  `request.env["gflux.anonymous_id"]`.
+- `at_exit` registers a final flush so single-shot scripts don't
+  drop the last batch.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GetFluxly
+
+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,91 @@
+# getfluxly (Ruby)
+
+Server-side Ruby SDK for [GetFluxly](https://getfluxly.com). Matches the Node and Python SDK shapes so observability across SDKs reads as one mental model. Zero runtime dependencies (uses `Net::HTTP` from stdlib).
+
+```bash
+gem install getfluxly
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "getfluxly"
+```
+
+Supports Ruby 3.1+.
+
+## Quick start
+
+```ruby
+require "getfluxly"
+
+client = GetFluxly::Client.new(token: "gflux_secret_yourtoken")
+
+client.track("subscription_started",
+             external_id: "user_42",
+             properties: { plan: "pro" })
+
+client.identify(external_id: "user_42",
+                traits: { email: "x@y.com", plan: "pro" })
+
+client.alias(user_id: "user_42", anonymous_id: "anon_a8f3c2")
+
+client.flush
+client.shutdown  # also runs from at_exit
+```
+
+## Rails integration
+
+Auto-loaded but opt-in via explicit `require`:
+
+```ruby
+# config/initializers/getfluxly.rb
+require "getfluxly/rails"
+
+GetFluxly::Rails.configure do |c|
+  c.token = ENV["GFLUX_SERVER_TOKEN"]
+end
+```
+
+Then later:
+
+```ruby
+GetFluxly::Rails.client.track("invoice_paid", external_id: "user_42")
+```
+
+A small Rack middleware (`GetFluxly::Rails::Middleware`) reads the `gflux_anon` cookie and attaches `request.env["gflux.anonymous_id"]` so controllers can resume the browser session for server-side tracking.
+
+## Defaults
+
+Defaults match Node and Python.
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `flush_at` | 20 | Events queued before forced flush |
+| `flush_interval` | 5.0 | Periodic flush, seconds |
+| `max_retries` | 2 | Per failed batch |
+| `timeout` | 5.0 | Per HTTP request, seconds |
+| `max_queue_size` | 1000 | Hard cap, raises `queue_overflow` |
+
+Retries: 408, 425, 429, and 5xx with exponential backoff and +/- 25% jitter. `Retry-After` is honored. Each batch carries a unique `X-Idempotency-Key`.
+
+## Errors
+
+```ruby
+begin
+  client.track("invoice_paid", external_id: "user_42")
+rescue GetFluxly::Error => e
+  case e.code
+  when "queue_overflow"
+    # back-pressure
+  when "rate_limited"
+    # SDK already retried max_retries times
+  end
+end
+```
+
+Full code table at `docs.getfluxly.com/snippets/error-table`.
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

data/SECURITY.md

@@ -0,0 +1,6 @@
+# Security policy
+
+To report a vulnerability in `@getfluxly/react`, please follow the disclosure
+process documented at the repository root: [SECURITY.md](../../SECURITY.md).
+
+We do not use GitHub Issues for security reports.

data/lib/getfluxly/batch.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GetFluxly
+  # Bounded thread-safe event queue + flush bookkeeping.
+  class Batch
+    FlushResult = Struct.new(:accepted, :rejected, :batches, :errors) do
+      def +(other)
+        FlushResult.new(
+          accepted + other.accepted,
+          rejected + other.rejected,
+          batches + other.batches,
+          errors + other.errors
+        )
+      end
+    end
+
+    def self.empty_flush_result
+      FlushResult.new(0, 0, 0, [])
+    end
+
+    def initialize(max_size:)
+      @max_size = max_size
+      @queue = []
+      @mutex = Mutex.new
+    end
+
+    def size
+      @mutex.synchronize { @queue.size }
+    end
+
+    def enqueue(payload)
+      @mutex.synchronize do
+        if @queue.size >= @max_size
+          raise GetFluxly::Error.new(
+            "event queue is full (#{@max_size}); flush before enqueueing more",
+            code: "queue_overflow",
+            retryable: false,
+            details: { "max_size" => @max_size }
+          )
+        end
+        @queue.push(payload)
+        @queue.size
+      end
+    end
+
+    def drain(max_events)
+      @mutex.synchronize do
+        out = @queue.shift([max_events, @queue.size].min)
+        out
+      end
+    end
+
+    def requeue_front(payloads)
+      @mutex.synchronize do
+        @queue = payloads + @queue
+      end
+    end
+  end
+end

data/lib/getfluxly/client.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module GetFluxly
+  # Synchronous GetFluxly client.
+  #
+  # Batches events with retry, jitter, and X-Idempotency-Key.
+  # The background flusher thread drains the queue every
+  # `flush_interval` seconds. at_exit runs a final flush.
+  class Client
+    DEFAULT_API_HOST = "https://api.getfluxly.com"
+    EVENTS_BATCH_PATH = "/v1/events/batch"
+    ALIAS_PATH = "/v1/identify/alias"
+
+    def initialize(
+      token:,
+      api_host: DEFAULT_API_HOST,
+      flush_at: 20,
+      flush_interval: 5.0,
+      max_retries: 2,
+      timeout: 5.0,
+      max_queue_size: 1000,
+      register_atexit: true
+    )
+      raise GetFluxly::Error.new("token is required", code: "validation_error") if token.nil? || token.empty?
+
+      @token = token
+      @api_host = api_host
+      @flush_at = flush_at
+      @flush_interval = flush_interval
+
+      @batch = Batch.new(max_size: max_queue_size)
+      @http = Http.new(token: token, api_host: api_host, timeout: timeout, max_retries: max_retries)
+      @shutdown = false
+      @shutdown_mutex = Mutex.new
+
+      return unless register_atexit
+
+      at_exit do
+        shutdown
+      rescue StandardError
+        # at_exit: swallow so interpreter shutdown is clean
+      end
+    end
+
+    def track(event, anonymous_id: nil, external_id: nil, user_id: nil,
+              properties: nil, timestamp: nil, context: nil)
+      Identity.require_one_id!(
+        anonymous_id: anonymous_id,
+        external_id: external_id,
+        user_id: user_id
+      )
+
+      payload = { "event" => event }
+      payload["anonymous_id"] = anonymous_id if anonymous_id
+      payload["external_id"] = external_id if external_id
+      payload["user_id"] = user_id if user_id
+      payload["properties"] = properties if properties
+      payload["timestamp"] = timestamp if timestamp
+      payload["context"] = context if context
+
+      enqueue(payload)
+    end
+
+    def identify(anonymous_id: nil, external_id: nil, user_id: nil, traits: nil)
+      Identity.require_one_id!(
+        anonymous_id: anonymous_id,
+        external_id: external_id,
+        user_id: user_id
+      )
+
+      payload = { "event" => "$identify" }
+      payload["anonymous_id"] = anonymous_id if anonymous_id
+      payload["external_id"] = external_id if external_id
+      payload["user_id"] = user_id if user_id
+      payload["traits"] = traits if traits
+
+      enqueue(payload)
+    end
+
+    def alias(user_id:, anonymous_id: nil, previous_id: nil, request_id: nil)
+      Identity.require_alias!(user_id: user_id, anonymous_id: anonymous_id, previous_id: previous_id)
+
+      body = { "user_id" => user_id }
+      body["anonymous_id"] = anonymous_id if anonymous_id
+      body["previous_id"] = previous_id if previous_id
+
+      response = @http.post(
+        ALIAS_PATH,
+        body,
+        idempotency_key: Http.generate_idempotency_key,
+        request_id: request_id
+      )
+
+      alias_obj = response["alias"]
+      if alias_obj.nil? || alias_obj == {}
+        raise GetFluxly::Error.new(
+          "alias response did not include alias data",
+          code: "invalid_response",
+          retryable: true,
+          details: response.is_a?(Hash) ? response : {}
+        )
+      end
+
+      alias_obj
+    end
+
+    def flush
+      result = Batch.empty_flush_result
+      loop do
+        batch = @batch.drain(@flush_at)
+        break if batch.empty?
+
+        begin
+          response = @http.post(
+            EVENTS_BATCH_PATH,
+            { "events" => batch },
+            idempotency_key: Http.generate_idempotency_key
+          )
+        rescue GetFluxly::Error => e
+          @batch.requeue_front(batch) if e.retryable
+          raise
+        end
+
+        result += Batch::FlushResult.new(
+          (response["accepted"] || batch.size).to_i,
+          (response["rejected"] || 0).to_i,
+          1,
+          Array(response["errors"])
+        )
+      end
+      result
+    end
+
+    def shutdown
+      @shutdown_mutex.synchronize do
+        return Batch.empty_flush_result if @shutdown
+
+        @shutdown = true
+      end
+      flush
+    end
+
+    alias close shutdown
+
+    private
+
+    def enqueue(payload)
+      size = @batch.enqueue(payload)
+      return flush if size >= @flush_at
+
+      nil
+    end
+  end
+end

data/lib/getfluxly/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module GetFluxly
+  # Every error raised by the SDK is a GetFluxly::Error.
+  # `code` is one of the strings from docs/sdk-standards/error-taxonomy.md
+  # and is stable across SDK versions.
+  class Error < StandardError
+    attr_reader :code, :retryable, :retry_after_ms, :status, :details
+
+    def initialize(message, code:, retryable: false, retry_after_ms: nil, status: nil, details: nil)
+      super(message)
+      @code = code
+      @retryable = retryable
+      @retry_after_ms = retry_after_ms
+      @status = status
+      @details = details || {}
+    end
+
+    def inspect
+      "#<GetFluxly::Error code=#{@code.inspect} retryable=#{@retryable} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/getfluxly/http.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module GetFluxly
+  # Thin Net::HTTP wrapper. Retries 408 / 425 / 429 / 5xx with
+  # exponential backoff and +/- 25% jitter. Honors Retry-After when
+  # present.
+  class Http
+    SDK_LIBRARY = "gflux-ruby/#{GetFluxly::VERSION}".freeze
+    RETRY_STATUSES = [408, 425, 429].freeze
+
+    def initialize(token:, api_host:, timeout:, max_retries:)
+      @token = token
+      @api_host = api_host.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+
+    def post(path_or_url, body, idempotency_key: nil, request_id: nil)
+      uri = absolute_uri(path_or_url)
+      payload = JSON.dump(body)
+
+      headers = {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@token}",
+        "X-GFlux-SDK" => SDK_LIBRARY
+      }
+      headers["X-Idempotency-Key"] = idempotency_key if idempotency_key
+      headers["X-Request-Id"] = request_id if request_id
+
+      attempt = 0
+      loop do
+        response = perform(uri, payload, headers)
+        parsed = parse_body(response)
+        status = response.code.to_i
+
+        return parsed if status.between?(200, 299)
+
+        if should_retry?(status) && attempt < @max_retries
+          attempt += 1
+          sleep(retry_after_seconds(response["Retry-After"], attempt))
+          next
+        end
+
+        raise build_error(response, parsed)
+      end
+    end
+
+    def self.generate_idempotency_key
+      SecureRandom.uuid
+    end
+
+    private
+
+    def perform(uri, payload, headers)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri, headers)
+      request.body = payload
+      http.request(request)
+    rescue StandardError => e
+      raise GetFluxly::Error.new(
+        "network error: #{e.message}",
+        code: "transport_error",
+        retryable: true
+      )
+    end
+
+    def parse_body(response)
+      text = response.body.to_s
+      return {} if text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      if response.code.to_i.between?(200, 299)
+        raise GetFluxly::Error.new(
+          "gflux response body was not valid JSON",
+          code: "invalid_response",
+          retryable: true,
+          status: response.code.to_i,
+          details: { "snippet" => text[0, 200] }
+        )
+      end
+      {}
+    end
+
+    def should_retry?(status)
+      RETRY_STATUSES.include?(status) || status.between?(500, 599)
+    end
+
+    def retry_after_seconds(header, attempt)
+      if header
+        parsed = header.to_f
+        return parsed if parsed.positive?
+      end
+      base = 0.2 * (2**attempt)
+      jitter = base * 0.25
+      [0.0, base + rand(-jitter..jitter)].max
+    end
+
+    def absolute_uri(path_or_url)
+      return URI.parse(path_or_url) if path_or_url.start_with?("http")
+
+      URI.parse("#{@api_host}#{path_or_url}")
+    end
+
+    def build_error(response, parsed)
+      status = response.code.to_i
+      error_block = parsed.is_a?(Hash) ? parsed["error"] : nil
+
+      code, message =
+        case error_block
+        when Hash then [error_block["code"] || "server_error", error_block["message"] || response.message]
+        when String then [error_block, parsed["detail"] || response.message]
+        else ["server_error", response.message || "request failed"]
+        end
+
+      GetFluxly::Error.new(
+        message,
+        code: code,
+        retryable: should_retry?(status),
+        status: status,
+        details: parsed.is_a?(Hash) ? parsed : {}
+      )
+    end
+  end
+end

data/lib/getfluxly/identity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GetFluxly
+  # Input validators for track / identify / alias. Field names match
+  # the wire shape (snake_case) so callers don't have to translate.
+  module Identity
+    module_function
+
+    def require_one_id!(anonymous_id:, external_id:, user_id:)
+      return if anonymous_id || external_id || user_id
+
+      raise GetFluxly::Error.new(
+        "track / identify requires at least one of anonymous_id, external_id, user_id",
+        code: "validation_error"
+      )
+    end
+
+    def require_alias!(user_id:, anonymous_id:, previous_id:)
+      if user_id.nil? || user_id.empty?
+        raise GetFluxly::Error.new("alias requires user_id",
+                                   code: "validation_error")
+      end
+
+      return if anonymous_id || previous_id
+
+      raise GetFluxly::Error.new(
+        "alias requires anonymous_id or previous_id",
+        code: "validation_error"
+      )
+    end
+  end
+end

data/lib/getfluxly/rails.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Opt-in Rails integration. Loaded via `require "getfluxly/rails"`
+# from an initializer; not auto-loaded. Rationale documented in
+# docs/sdk-standards/security-and-publishing.md.
+
+require_relative "../getfluxly"
+
+module GetFluxly
+  module Rails
+    class Configuration
+      attr_accessor :token, :api_host
+
+      def initialize
+        @token = ENV.fetch("GFLUX_SERVER_TOKEN", nil)
+        @api_host = ENV.fetch("GFLUX_API_HOST", GetFluxly::Client::DEFAULT_API_HOST)
+      end
+    end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        @client = nil # invalidate so the next .client uses the new config
+      end
+
+      def client
+        @client ||= GetFluxly::Client.new(token: config.token, api_host: config.api_host)
+      end
+    end
+
+    # Tiny Rack middleware: extracts gflux_anonymous_id from the request
+    # cookie and attaches it as request.env["gflux.anonymous_id"] so
+    # controller code can resume the browser session for server-side
+    # track() calls. Wire it from config/application.rb:
+    #
+    #   require "getfluxly/rails"
+    #   config.middleware.use GetFluxly::Rails::Middleware
+    class Middleware
+      COOKIE = "gflux_anon"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        cookie = env["HTTP_COOKIE"].to_s
+        match = cookie.match(/(?:^|;\s*)#{COOKIE}=([^;]+)/)
+        env["gflux.anonymous_id"] = match[1] if match
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/getfluxly/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Auto-generated by scripts/sync_version.rb. Do not edit by hand,
+# run `ruby scripts/sync_version.rb` to regenerate.
+
+module GetFluxly
+  VERSION = "0.1.0"
+end

data/lib/getfluxly.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# GetFluxly Ruby SDK - top-level loader.
+#
+# Application code requires "getfluxly" and then constructs
+# GetFluxly::Client.new(token: ...). The optional Rails integration
+# lives at "getfluxly/rails" and is loaded explicitly (opt-in).
+
+require_relative "getfluxly/version"
+require_relative "getfluxly/error"
+require_relative "getfluxly/identity"
+require_relative "getfluxly/http"
+require_relative "getfluxly/batch"
+require_relative "getfluxly/client"
+
+module GetFluxly
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: getfluxly
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GetFluxly
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+description: Server-side events, identify, and alias for GetFluxly. Matches the Node
+  and Python SDK shapes; zero runtime dependencies.
+email:
+- hello@getfluxly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- SECURITY.md
+- lib/getfluxly.rb
+- lib/getfluxly/batch.rb
+- lib/getfluxly/client.rb
+- lib/getfluxly/error.rb
+- lib/getfluxly/http.rb
+- lib/getfluxly/identity.rb
+- lib/getfluxly/rails.rb
+- lib/getfluxly/version.rb
+homepage: https://getfluxly.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://getfluxly.com
+  source_code_uri: https://github.com/dineshmiriyala/getfluxly
+  documentation_uri: https://docs.getfluxly.com/sdks/ruby
+  bug_tracker_uri: https://github.com/dineshmiriyala/getfluxly/issues
+  changelog_uri: https://github.com/dineshmiriyala/getfluxly/blob/main/packages/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: GetFluxly Ruby SDK
+test_files: []