shopcircle-orbit 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea60f7805d0aa67d6d2748586dc5342bc88e12f2b4b61b4aab4c8cd1ca5519f1
+  data.tar.gz: 87bf73def7abdfac9818392a21b80a161f67b5ecbcdd6c64df5dc37d4ebcd838
+SHA512:
+  metadata.gz: '067937e4dc01ec32494a35cfdba85fb923a6c0c10e4730a03bdbf5c5368d38773d46af351c36b73cbee9efa8491df6eed787afe97e67de1008e5400d52defb23'
+  data.tar.gz: 3379decabf5a9596d9a21fe7be34d30f7c0af5045d2e4917e5f12f165ebb27bcb1a8d00fa16b4d2bb9baaab9ad295d035346ce3cfdf51961ec2509fee51b0bd5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ShopCircle
+
+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,178 @@
+# ShopCircle Orbit Ruby SDK
+
+Server-side Ruby SDK for [ShopCircle Orbit](https://orbit.shopcircle.co) analytics. Track events, identify users, and measure engagement from any Ruby backend.
+
+- Thread-safe background batching with automatic retry
+- Zero runtime dependencies (Ruby stdlib only)
+- Optional Rails integration with auto page view tracking
+
+## Installation
+
+```ruby
+# Gemfile
+gem "shopcircle-orbit"
+```
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### Plain Ruby
+
+```ruby
+require "shopcircle_orbit"
+
+orbit = ShopCircle::Orbit::Client.new(
+  client_id: "your-client-id",
+  api_url: "https://orbit.shopcircle.co"
+)
+
+orbit.identify("user_123", first_name: "John", email: "john@example.com")
+orbit.track("purchase", amount: 99.99, currency: "USD")
+orbit.shutdown!
+```
+
+### Rails
+
+Generate the initializer:
+
+```bash
+rails generate shopcircle_orbit:install
+```
+
+This creates `config/initializers/shopcircle_orbit.rb`. Then use anywhere:
+
+```ruby
+ShopCircle::Orbit.identify(current_user.id, first_name: current_user.first_name, email: current_user.email)
+ShopCircle::Orbit.track("order_created", order_id: order.id, amount: order.total)
+```
+
+## Configuration
+
+```ruby
+ShopCircle::Orbit.configure do |config|
+  config.client_id       = ENV.fetch("SHOPCIRCLE_CLIENT_ID")
+  config.client_secret   = ENV["SHOPCIRCLE_CLIENT_SECRET"]   # optional
+  config.api_url         = "https://orbit.shopcircle.co"
+  config.device_id       = nil                                # optional device identifier
+  config.flush_interval  = 2                                  # seconds between flushes
+  config.max_batch_size  = 10                                 # events per HTTP request
+  config.max_queue_size  = 1_000                              # max queued events
+  config.max_retries     = 3                                  # retry attempts for failures
+  config.request_timeout = 10                                 # HTTP timeout in seconds
+  config.stub            = Rails.env.test?                    # test mode (no HTTP)
+  config.on_error        = ->(msg, detail) { Rails.logger.error("[Orbit] #{msg}") }
+end
+```
+
+## API
+
+### `track(name, properties = {})`
+
+Track a custom event:
+
+```ruby
+ShopCircle::Orbit.track("button_click", label: "Sign Up", page: "/pricing")
+ShopCircle::Orbit.track("purchase", amount: 49.99, currency: "USD", product_id: "prod_abc")
+```
+
+### `identify(profile_id, traits = {})`
+
+Identify a user with profile attributes:
+
+```ruby
+ShopCircle::Orbit.identify("user_123",
+  first_name: "John",
+  last_name: "Doe",
+  email: "john@example.com",
+  plan: "premium"
+)
+```
+
+### `reset!`
+
+Clear the current user identity (e.g. on logout):
+
+```ruby
+ShopCircle::Orbit.reset!
+```
+
+### `set_device_id(device_id)`
+
+Set a device identifier for cross-session linking:
+
+```ruby
+ShopCircle::Orbit.set_device_id("device-fingerprint-from-frontend")
+```
+
+### `flush`
+
+Force an immediate flush of queued events:
+
+```ruby
+ShopCircle::Orbit.flush
+```
+
+### `shutdown!`
+
+Flush remaining events and stop the background worker:
+
+```ruby
+ShopCircle::Orbit.shutdown!
+```
+
+## Multiple Clients
+
+For multi-tenant or multi-project use cases, create separate client instances:
+
+```ruby
+project_a = ShopCircle::Orbit::Client.new(client_id: "id-a", api_url: "https://orbit.shopcircle.co")
+project_b = ShopCircle::Orbit::Client.new(client_id: "id-b", api_url: "https://orbit.shopcircle.co")
+
+project_a.track("event_a")
+project_b.track("event_b")
+```
+
+## Testing
+
+Enable stub mode to record events without making HTTP calls:
+
+```ruby
+# test/test_helper.rb
+ShopCircle::Orbit.configure do |config|
+  config.stub = true
+end
+
+# In your test
+class OrderTest < ActiveSupport::TestCase
+  setup do
+    ShopCircle::Orbit.shutdown!  # reset between tests
+  end
+
+  test "tracks purchase event" do
+    OrderService.create!(user: users(:alice), amount: 99.99)
+
+    events = ShopCircle::Orbit.client.events
+    purchase = events.find { |e| e[:payload][:name] == "purchase" }
+    assert purchase
+    assert_equal 99.99, purchase[:payload][:properties]["amount"]
+  end
+end
+```
+
+## Rails Middleware
+
+The SDK automatically inserts Rack middleware that tracks `page_view` events for HTML GET requests. Asset paths, XHR, and JSON requests are excluded.
+
+To disable:
+
+```ruby
+# config/application.rb
+config.middleware.delete ShopCircle::Orbit::Rails::Middleware
+```
+
+## License
+
+MIT

data/lib/shopcircle/orbit/client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module ShopCircle
+  module Orbit
+    class Client
+      def initialize(config = nil, **options)
+        @config = resolve_config(config, options)
+        @config.validate!
+
+        @profile_id = nil
+        @device_id  = @config.device_id
+        @queue      = Thread::Queue.new
+        @mutex      = Mutex.new
+        @shutdown   = false
+
+        transport = @config.stub ? TestTransport.new : Transport.new(@config)
+
+        @worker = Worker.new(
+          queue: @queue,
+          config: @config,
+          transport: transport
+        )
+        @worker.start
+
+        register_at_exit_hook
+      end
+
+      # Track a custom event with optional properties.
+      #
+      #   orbit.track("purchase", amount: 99.99, currency: "USD")
+      #
+      def track(name, properties = {})
+        Validation.validate_event_name!(name)
+        Validation.validate_properties!(properties)
+
+        enqueue(Event.new(
+          type: "track",
+          name: name.to_s,
+          profile_id: current_profile_id,
+          device_id: current_device_id,
+          properties: properties
+        ))
+      end
+
+      # Identify a user. Subsequent events will be associated with this profile.
+      #
+      #   orbit.identify("user_123", first_name: "John", email: "john@example.com")
+      #
+      # Accepts both snake_case and camelCase trait keys:
+      #   first_name / firstName, last_name / lastName
+      #
+      def identify(profile_id, traits = {})
+        raise ArgumentError, "profile_id is required" if profile_id.nil? || profile_id.to_s.strip.empty?
+
+        @mutex.synchronize { @profile_id = profile_id.to_s }
+
+        traits = traits.dup
+        first_name = traits.delete(:first_name) || traits.delete(:firstName)
+        last_name  = traits.delete(:last_name)  || traits.delete(:lastName)
+        email      = traits.delete(:email)
+        avatar     = traits.delete(:avatar)
+
+        enqueue(Event.new(
+          type: "identify",
+          profile_id: profile_id.to_s,
+          device_id: current_device_id,
+          first_name: first_name,
+          last_name: last_name,
+          email: email,
+          avatar: avatar,
+          properties: traits.empty? ? nil : traits
+        ))
+      end
+
+      # Clear current profile association (e.g. on logout).
+      def reset!
+        @mutex.synchronize { @profile_id = nil }
+      end
+
+      # Set or update the device identifier at runtime.
+      def set_device_id(device_id)
+        Validation.validate_device_id!(device_id)
+        @mutex.synchronize { @device_id = device_id&.to_s }
+      end
+
+      # Force an immediate flush of queued events.
+      def flush
+        @worker.flush
+      end
+
+      # Flush remaining events and stop the background worker.
+      def shutdown!
+        @mutex.synchronize { @shutdown = true }
+        @worker.stop
+      end
+
+      # Returns recorded events (stub mode only).
+      def events
+        return [] unless @config.stub
+        @worker.transport.events
+      end
+
+      private
+
+      def enqueue(event)
+        return if @mutex.synchronize { @shutdown }
+
+        # Drop oldest if at capacity
+        if @queue.size >= @config.max_queue_size
+          @queue.pop(true) rescue nil
+        end
+
+        @queue.push(event)
+      end
+
+      def current_profile_id
+        @mutex.synchronize { @profile_id }
+      end
+
+      def current_device_id
+        @mutex.synchronize { @device_id }
+      end
+
+      def register_at_exit_hook
+        at_exit { shutdown! }
+      end
+
+      def resolve_config(config, options)
+        case config
+        when Configuration
+          config
+        when Hash
+          build_config(config.merge(options))
+        when nil
+          if options.empty?
+            ShopCircle::Orbit.configuration
+          else
+            build_config(options)
+          end
+        else
+          raise ArgumentError, "Expected Configuration, Hash, or keyword arguments"
+        end
+      end
+
+      def build_config(hash)
+        c = Configuration.new
+        hash.each do |k, v|
+          setter = :"#{k}="
+          c.public_send(setter, v) if c.respond_to?(setter)
+        end
+        c
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    class Configuration
+      attr_accessor :client_id,
+                    :client_secret,
+                    :api_url,
+                    :device_id,
+                    :flush_interval,
+                    :max_batch_size,
+                    :max_queue_size,
+                    :max_retries,
+                    :base_retry_delay,
+                    :request_timeout,
+                    :logger,
+                    :stub,
+                    :on_error
+
+      def initialize
+        @client_id       = nil
+        @client_secret   = nil
+        @api_url         = nil
+        @device_id       = nil
+        @flush_interval  = 2
+        @max_batch_size  = 10
+        @max_queue_size  = 1_000
+        @max_retries     = 3
+        @base_retry_delay = 1
+        @request_timeout = 10
+        @logger          = nil
+        @stub            = false
+        @on_error        = nil
+      end
+
+      def validate!
+        raise ArgumentError, "client_id is required" if @client_id.nil? || @client_id.to_s.empty?
+        raise ArgumentError, "api_url is required" if @api_url.nil? || @api_url.to_s.empty?
+        raise ArgumentError, "device_id max 128 chars" if @device_id && @device_id.to_s.length > 128
+      end
+
+      def resolved_logger
+        @logger || default_logger
+      end
+
+      private
+
+      def default_logger
+        @default_logger ||= begin
+          require "logger"
+          Logger.new($stdout, level: Logger::WARN)
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    class Event
+      attr_reader :type, :name, :profile_id, :device_id,
+                  :properties, :first_name, :last_name,
+                  :email, :avatar
+
+      def initialize(type:, name: nil, profile_id: nil, device_id: nil,
+                     properties: nil, first_name: nil, last_name: nil,
+                     email: nil, avatar: nil)
+        @type       = type
+        @name       = name
+        @profile_id = profile_id
+        @device_id  = device_id
+        @properties = properties
+        @first_name = first_name
+        @last_name  = last_name
+        @email      = email
+        @avatar     = avatar
+      end
+
+      def to_payload
+        payload = {}
+        payload[:name]       = @name       if @name
+        payload[:profileId]  = @profile_id if @profile_id
+        payload[:deviceId]   = @device_id  if @device_id
+        payload[:firstName]  = @first_name if @first_name
+        payload[:lastName]   = @last_name  if @last_name
+        payload[:email]      = @email      if @email
+        payload[:avatar]     = @avatar     if @avatar
+        payload[:properties] = normalize_keys(@properties) if @properties && !@properties.empty?
+        { type: @type, payload: payload }
+      end
+
+      private
+
+      def normalize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), result|
+          result[k.to_s] = v
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/rails/generators/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ShopCircleOrbit
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("../../../../../templates", __dir__)
+      desc "Creates a ShopCircle Orbit initializer"
+
+      def create_initializer
+        template "shopcircle_orbit.rb.erb", "config/initializers/shopcircle_orbit.rb"
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/rails/middleware.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    module Rails
+      # Rack middleware that auto-tracks page_view events for HTML page requests.
+      # Skips assets, XHR, and non-GET requests.
+      #
+      # Opt out by removing from the middleware stack:
+      #
+      #   # config/application.rb
+      #   config.middleware.delete ShopCircle::Orbit::Rails::Middleware
+      #
+      class Middleware
+        SKIP_PREFIXES = %w[/assets /packs /rails /cable].freeze
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          status, headers, response = @app.call(env)
+
+          if trackable?(env, status)
+            request = Rack::Request.new(env)
+            ShopCircle::Orbit.track("page_view", {
+              path: request.path,
+              method: request.request_method,
+              status: status,
+              user_agent: request.user_agent,
+              ip: request.ip,
+              referrer: request.referrer
+            })
+          end
+
+          [status, headers, response]
+        rescue StandardError
+          # Never break the request due to tracking errors
+          [status, headers, response]
+        end
+
+        private
+
+        def trackable?(env, status)
+          return false unless env["REQUEST_METHOD"] == "GET"
+          return false unless status >= 200 && status < 400
+
+          path = env["PATH_INFO"].to_s
+          return false if SKIP_PREFIXES.any? { |p| path.start_with?(p) }
+
+          # Skip XHR / fetch requests
+          return false if env["HTTP_X_REQUESTED_WITH"] == "XMLHttpRequest"
+          return false if env["HTTP_ACCEPT"]&.include?("application/json")
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/rails/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "middleware"
+
+module ShopCircle
+  module Orbit
+    module Rails
+      class Railtie < ::Rails::Railtie
+        initializer "shopcircle_orbit.configure" do
+          ShopCircle::Orbit.configuration.logger ||= ::Rails.logger
+        end
+
+        initializer "shopcircle_orbit.middleware" do |app|
+          app.middleware.use ShopCircle::Orbit::Rails::Middleware
+        end
+
+        config.after_initialize do
+          at_exit { ShopCircle::Orbit.shutdown! }
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/transport.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module ShopCircle
+  module Orbit
+    class Transport
+      SDK_NAME = "shopcircle-orbit-ruby"
+
+      def initialize(config)
+        @config  = config
+        @api_uri = URI.parse(config.api_url.to_s.chomp("/"))
+      end
+
+      def send_single(event)
+        body = JSON.generate(event.to_payload)
+        post("/api/track", body)
+      end
+
+      def send_batch(events)
+        body = JSON.generate({
+          events: events.map(&:to_payload),
+          clientId: @config.client_id,
+          sdkName: SDK_NAME,
+          sdkVersion: ShopCircle::Orbit::VERSION,
+          deviceId: events.first&.device_id
+        })
+        post("/api/track/batch", body)
+      end
+
+      private
+
+      def post(path, body, attempt = 0)
+        uri = @api_uri.dup
+        uri.path = path
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @config.request_timeout
+        http.read_timeout = @config.request_timeout
+        http.write_timeout = @config.request_timeout if http.respond_to?(:write_timeout=)
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Content-Type"]             = "application/json"
+        request["shopcircle-client-id"]     = @config.client_id
+        request["shopcircle-sdk-name"]      = SDK_NAME
+        request["shopcircle-sdk-version"]   = ShopCircle::Orbit::VERSION
+        request["shopcircle-client-secret"] = @config.client_secret if @config.client_secret
+        request.body = body
+
+        response = http.request(request)
+        status = response.code.to_i
+
+        return if status >= 200 && status < 300
+
+        # 4xx except 429: client error, don't retry
+        if status >= 400 && status < 500 && status != 429
+          log_error("HTTP #{status}", response.body)
+          return
+        end
+
+        # 429, 5xx: retryable
+        maybe_retry(path, body, attempt, status, response.body)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+             Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
+             SocketError, IOError => e
+        maybe_retry(path, body, attempt, nil, e.message)
+      ensure
+        http&.finish rescue nil
+      end
+
+      def maybe_retry(path, body, attempt, status, message)
+        if attempt < @config.max_retries
+          delay = @config.base_retry_delay * (2**attempt)
+          sleep(delay)
+          post(path, body, attempt + 1)
+        else
+          log_error("Failed after #{@config.max_retries + 1} attempts (status=#{status})", message)
+        end
+      end
+
+      def log_error(msg, detail)
+        @config.on_error&.call(msg, detail)
+        @config.resolved_logger.warn("[shopcircle-orbit] #{msg}: #{detail}")
+      rescue StandardError
+        # Never crash the worker thread due to logging/callback errors
+      end
+    end
+
+    # Stub transport for testing - records events in memory
+    class TestTransport
+      attr_reader :events, :batches
+
+      def initialize
+        @events  = []
+        @batches = []
+        @mutex   = Mutex.new
+      end
+
+      def send_single(event)
+        @mutex.synchronize { @events << event.to_payload }
+      end
+
+      def send_batch(events)
+        payloads = events.map(&:to_payload)
+        @mutex.synchronize do
+          @batches << payloads
+          @events.concat(payloads)
+        end
+      end
+
+      def clear!
+        @mutex.synchronize do
+          @events.clear
+          @batches.clear
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/validation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ShopCircle
+  module Orbit
+    module Validation
+      MAX_EVENT_NAME_LENGTH = 80
+      MAX_DEVICE_ID_LENGTH  = 128
+      MAX_PROPERTIES_BYTES  = 10_240
+      RESERVED_NAMES        = %w[session_start session_end].freeze
+
+      class << self
+        def validate_event_name!(name)
+          raise ArgumentError, "event name is required" if name.nil? || name.to_s.strip.empty?
+          raise ArgumentError, "event name max #{MAX_EVENT_NAME_LENGTH} chars" if name.to_s.length > MAX_EVENT_NAME_LENGTH
+          raise ArgumentError, "event name '#{name}' is reserved" if RESERVED_NAMES.include?(name.to_s)
+        end
+
+        def validate_properties!(props)
+          return if props.nil? || props.empty?
+
+          json = JSON.generate(props)
+          if json.bytesize > MAX_PROPERTIES_BYTES
+            raise ArgumentError, "properties too large (#{json.bytesize} bytes, max #{MAX_PROPERTIES_BYTES})"
+          end
+        end
+
+        def validate_device_id!(device_id)
+          return if device_id.nil?
+          raise ArgumentError, "device_id max #{MAX_DEVICE_ID_LENGTH} chars" if device_id.to_s.length > MAX_DEVICE_ID_LENGTH
+        end
+      end
+    end
+  end
+end

data/lib/shopcircle/orbit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    VERSION = "1.0.0"
+  end
+end

data/lib/shopcircle/orbit/worker.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ShopCircle
+  module Orbit
+    class Worker
+      attr_reader :transport
+
+      def initialize(queue:, config:, transport:)
+        @queue     = queue
+        @config    = config
+        @transport = transport
+        @thread    = nil
+        @mutex     = Mutex.new
+        @condvar   = ConditionVariable.new
+        @running   = false
+      end
+
+      def start
+        @mutex.synchronize do
+          return if @running
+          @running = true
+        end
+
+        @thread = Thread.new { run_loop }
+        @thread.abort_on_exception = false
+      end
+
+      def stop
+        @mutex.synchronize do
+          @running = false
+          @condvar.signal
+        end
+        flush_all
+        @thread&.join(5)
+      end
+
+      def flush
+        @mutex.synchronize { @condvar.signal }
+        # Give worker thread a moment to process
+        sleep(0.05)
+      end
+
+      private
+
+      def run_loop
+        while running?
+          @mutex.synchronize do
+            @condvar.wait(@mutex, @config.flush_interval)
+          end
+          flush_all
+        end
+      rescue StandardError => e
+        @config.resolved_logger.error("[shopcircle-orbit] Worker error: #{e.message}")
+        retry if running?
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      def flush_all
+        batch = drain_queue
+        return if batch.empty?
+
+        batch.each_slice(@config.max_batch_size) do |chunk|
+          if chunk.size == 1
+            @transport.send_single(chunk.first)
+          else
+            @transport.send_batch(chunk)
+          end
+        end
+      rescue StandardError => e
+        @config.resolved_logger.error("[shopcircle-orbit] Flush error: #{e.message}")
+        @config.on_error&.call("Flush error", e.message)
+      end
+
+      def drain_queue
+        events = []
+        loop do
+          event = @queue.pop(true) # non-blocking
+          events << event
+        rescue ThreadError
+          break
+        end
+        events
+      end
+    end
+  end
+end

data/lib/shopcircle_orbit.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "shopcircle/orbit/version"
+require_relative "shopcircle/orbit/configuration"
+require_relative "shopcircle/orbit/validation"
+require_relative "shopcircle/orbit/event"
+require_relative "shopcircle/orbit/transport"
+require_relative "shopcircle/orbit/worker"
+require_relative "shopcircle/orbit/client"
+
+module ShopCircle
+  module Orbit
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure the module-level singleton.
+      #
+      #   ShopCircle::Orbit.configure do |config|
+      #     config.client_id = "your-client-id"
+      #     config.api_url   = "https://orbit.shopcircle.co"
+      #   end
+      #
+      def configure
+        yield(configuration)
+      end
+
+      # Lazily initialized singleton client.
+      def client
+        @client ||= Client.new(configuration)
+      end
+
+      # Track a custom event.
+      #
+      #   ShopCircle::Orbit.track("purchase", amount: 99.99)
+      #
+      def track(name, properties = {})
+        client.track(name, properties)
+      end
+
+      # Identify a user.
+      #
+      #   ShopCircle::Orbit.identify("user_123", first_name: "John", email: "john@example.com")
+      #
+      def identify(profile_id, traits = {})
+        client.identify(profile_id, traits)
+      end
+
+      # Clear current profile association.
+      def reset!
+        return unless @client
+        @client.reset!
+      end
+
+      # Set device identifier.
+      def set_device_id(device_id)
+        client.set_device_id(device_id)
+      end
+
+      # Force an immediate flush.
+      def flush
+        return unless @client
+        @client.flush
+      end
+
+      # Flush and stop the singleton client.
+      def shutdown!
+        return unless @client
+        @client.shutdown!
+        @client = nil
+      end
+    end
+  end
+end
+
+# Auto-load Rails integration if Rails is present
+require_relative "shopcircle/orbit/rails/railtie" if defined?(::Rails::Railtie)

data/templates/shopcircle_orbit.rb.erb

@@ -0,0 +1,8 @@
+ShopCircle::Orbit.configure do |config|
+  config.client_id     = ENV.fetch("SHOPCIRCLE_CLIENT_ID")
+  config.client_secret = ENV["SHOPCIRCLE_CLIENT_SECRET"]  # optional
+  config.api_url       = ENV.fetch("SHOPCIRCLE_API_URL", "https://orbit.shopcircle.co")
+  # config.device_id   = nil
+  # config.stub        = Rails.env.test?
+  # config.on_error    = ->(msg, detail) { Rails.logger.error("[Orbit] #{msg}: #{detail}") }
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: shopcircle-orbit
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ShopCircle
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Track events, identify users, and measure engagement from Ruby backends.
+  Thread-safe with background batching, zero runtime dependencies, and optional Rails
+  integration.
+email:
+- engineering@shopcircle.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/shopcircle/orbit/client.rb
+- lib/shopcircle/orbit/configuration.rb
+- lib/shopcircle/orbit/event.rb
+- lib/shopcircle/orbit/rails/generators/install_generator.rb
+- lib/shopcircle/orbit/rails/middleware.rb
+- lib/shopcircle/orbit/rails/railtie.rb
+- lib/shopcircle/orbit/transport.rb
+- lib/shopcircle/orbit/validation.rb
+- lib/shopcircle/orbit/version.rb
+- lib/shopcircle/orbit/worker.rb
+- lib/shopcircle_orbit.rb
+- templates/shopcircle_orbit.rb.erb
+homepage: https://github.com/shopcircle/orbit-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/shopcircle/orbit-sdk-ruby
+  source_code_uri: https://github.com/shopcircle/orbit-sdk-ruby
+  changelog_uri: https://github.com/shopcircle/orbit-sdk-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Server-side Ruby SDK for ShopCircle Orbit analytics
+test_files: []