helix_sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0578c2aa076e6f7ea6b818cdfb90d09474592fa9cac6be69f387938af8576de
+  data.tar.gz: 415c4192622c885917f37bc941607c7f3ca07b81363307fa7aecad46c188f305
+SHA512:
+  metadata.gz: dfe2ea8a4221434f39058e0132e8aab1203e6ca0f9f1cd7c6a27e61eadc7323cd3fa796ed868a5d89e0417ed98cda15fe8a30ee06f12b8c67d4a2c302b2c212f
+  data.tar.gz: 746627ece674b373013fba2f06e4b2daf0fd31ff090b2f39ee92d1c3a1dada4ed6ab704be5c3dd95af3a720cba10ca8d3e292be88e000066a770b19e8069bdac

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in helix_analytics.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "webmock", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,99 @@
+PATH
+  remote: .
+  specs:
+    helix_sdk (1.0.0)
+      concurrent-ruby (~> 1.1)
+      faraday (~> 2.0)
+      faraday-retry (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    bigdecimal (3.2.3)
+    concurrent-ruby (1.3.5)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    faraday (2.13.4)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    hashdiff (1.2.1)
+    json (2.13.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    net-http (0.6.0)
+      uri
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.5.1)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.80.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.3)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  helix_sdk!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21, ~> 1.0)
+  webmock (~> 3.0)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.7.0

data/README.md

@@ -0,0 +1,453 @@
+# Helix Analytics Ruby SDK
+
+Official Ruby SDK for Helix Analytics - AI-powered growth analytics platform with enhanced business intelligence capabilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'helix_sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install helix_sdk
+```
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```ruby
+require 'helix_sdk'
+
+helix = HelixSdk::Client.new(
+  api_key: 'your-api-key',
+  api_url: 'https://helix-sdk-ha4shte2cq-uc.a.run.app',
+  company_id: 'your-company-id'
+)
+```
+
+### 2. Track Events
+
+```ruby
+# Track a user action
+helix.track(
+  user_id: 'user-123',
+  event: 'button_clicked',
+  properties: {
+    button_name: 'signup',
+    page: 'landing'
+  }
+)
+
+# Identify a user
+helix.identify(
+  user_id: 'user-123',
+  traits: {
+    email: 'user@example.com',
+    plan: 'premium'
+  }
+)
+
+# Track page views
+helix.page(
+  user_id: 'user-123',
+  name: 'Landing Page',
+  properties: {
+    url: 'https://example.com',
+    title: 'Welcome'
+  }
+)
+```
+
+### 3. Batch Events
+
+```ruby
+# Send multiple events efficiently
+events = [
+  {
+    type: 'track',
+    user_id: 'user-123',
+    event: 'signup',
+    properties: { plan: 'free' }
+  },
+  {
+    type: 'track',
+    user_id: 'user-123',
+    event: 'first_login',
+    properties: { timestamp: Time.now }
+  }
+]
+
+helix.batch(events)
+```
+
+## Configuration
+
+### Client Options
+
+```ruby
+helix = HelixSdk::Client.new(
+  api_key: 'your-api-key',        # Required: Your Helix API key
+  api_url: 'https://api.helix.com', # Optional: API endpoint
+  company_id: 'company-123',      # Optional: Company ID
+  timeout: 10,                    # Optional: Request timeout in seconds
+  retries: 3,                     # Optional: Number of retries
+  batch_size: 100                 # Optional: Batch size for bulk operations
+)
+```
+
+### Environment Variables
+
+You can also configure the client using environment variables:
+
+```bash
+export HELIX_API_KEY=your-api-key
+export HELIX_API_URL=https://helix-sdk-ha4shte2cq-uc.a.run.app
+export HELIX_COMPANY_ID=your-company-id
+```
+
+```ruby
+# Client will automatically use environment variables
+helix = HelixSdk::Client.new
+```
+
+## API Reference
+
+### Track Events
+
+Track user actions and behaviors:
+
+```ruby
+helix.track(
+  user_id: 'user-123',           # Required: User identifier
+  event: 'purchase',             # Required: Event name
+  properties: {                  # Optional: Event properties
+    product_id: 'prod-456',
+    revenue: 99.99,
+    currency: 'USD'
+  },
+  context: {                     # Optional: Additional context
+    page: {
+      url: 'https://example.com/checkout',
+      title: 'Checkout'
+    }
+  },
+  timestamp: Time.now            # Optional: Event timestamp
+)
+```
+
+### Identify Users
+
+Associate user traits with a user ID:
+
+```ruby
+helix.identify(
+  user_id: 'user-123',
+  traits: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    plan: 'premium',
+    created_at: Time.now
+  }
+)
+```
+
+### Page Views
+
+Track page views and navigation:
+
+```ruby
+helix.page(
+  user_id: 'user-123',
+  name: 'Product Page',
+  category: 'ecommerce',
+  properties: {
+    url: 'https://example.com/products/123',
+    title: 'Amazing Product',
+    referrer: 'https://google.com'
+  }
+)
+```
+
+### Screen Views
+
+Track screen views in mobile applications:
+
+```ruby
+helix.screen(
+  user_id: 'user-123',
+  name: 'Dashboard',
+  category: 'app',
+  properties: {
+    screen_id: 'dashboard_v2',
+    version: '2.1.0'
+  }
+)
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```ruby
+begin
+  helix.track(
+    user_id: 'user-123',
+    event: 'purchase',
+    properties: { amount: 99.99 }
+  )
+rescue HelixSdk::Error => e
+  puts "Failed to track event: #{e.message}"
+end
+```
+
+### Async Processing
+
+```ruby
+# Non-blocking event tracking
+helix.track_async(
+  user_id: 'user-123',
+  event: 'background_job_completed',
+  properties: { job_id: 'job-456' }
+)
+```
+
+### Custom Context
+
+```ruby
+helix.track(
+  user_id: 'user-123',
+  event: 'api_call',
+  properties: { endpoint: '/api/users' },
+  context: {
+    app: {
+      name: 'MyApp',
+      version: '1.2.3'
+    },
+    library: {
+      name: 'helix_sdk',
+      version: HelixSdk::VERSION
+    },
+    device: {
+      type: 'server'
+    }
+  }
+)
+```
+
+## Business Intelligence Integration
+
+### Enhanced Analytics
+
+The Ruby SDK integrates with Helix's enhanced analytics capabilities:
+
+- **User Engagement Tracking** - DAU/WAU/MAU metrics
+- **Conversion Funnel Analysis** - Multi-step conversion tracking
+- **Revenue Attribution** - Marketing channel performance
+- **Behavioral Segmentation** - User categorization and insights
+- **Real-time Dashboards** - Live metrics and monitoring
+- **Anomaly Detection** - Automated pattern recognition
+
+### Event Best Practices
+
+```ruby
+# E-commerce tracking
+helix.track(
+  user_id: 'user-123',
+  event: 'purchase',
+  properties: {
+    product_id: 'prod-456',
+    product_name: 'Premium Plan',
+    revenue: 99.99,
+    currency: 'USD',
+    category: 'subscription'
+  }
+)
+
+# User onboarding
+helix.track(
+  user_id: 'user-123',
+  event: 'onboarding_step_completed',
+  properties: {
+    step: 3,
+    step_name: 'profile_setup',
+    total_steps: 5
+  }
+)
+
+# Feature usage
+helix.track(
+  user_id: 'user-123',
+  event: 'feature_used',
+  properties: {
+    feature_name: 'advanced_search',
+    usage_count: 1,
+    user_plan: 'premium'
+  }
+)
+```
+
+## Rails Integration
+
+### Initializer
+
+Create `config/initializers/helix.rb`:
+
+```ruby
+HelixSdk.configure do |config|
+  config.api_key = ENV['HELIX_API_KEY']
+  config.api_url = ENV['HELIX_API_URL']
+  config.company_id = ENV['HELIX_COMPANY_ID']
+end
+```
+
+### Controller Usage
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :track_page_view
+
+  private
+
+  def track_page_view
+    HelixSdk.page(
+      user_id: current_user&.id,
+      name: controller_name.humanize,
+      properties: {
+        action: action_name,
+        url: request.url,
+        user_agent: request.user_agent
+      }
+    )
+  end
+end
+```
+
+### Model Integration
+
+```ruby
+class User < ApplicationRecord
+  after_create :track_signup
+  after_update :track_profile_update
+
+  private
+
+  def track_signup
+    HelixSdk.track(
+      user_id: id,
+      event: 'user_signup',
+      properties: {
+        email: email,
+        plan: plan,
+        source: utm_source
+      }
+    )
+  end
+
+  def track_profile_update
+    HelixSdk.track(
+      user_id: id,
+      event: 'profile_updated',
+      properties: {
+        fields_changed: changed_attributes.keys
+      }
+    )
+  end
+end
+```
+
+## Testing
+
+### RSpec Integration
+
+```ruby
+# spec/spec_helper.rb
+require 'helix_sdk'
+require 'webmock/rspec'
+
+RSpec.configure do |config|
+  config.before(:each) do
+    # Stub Helix API calls in tests
+    stub_request(:post, /helix-sdk/)
+      .to_return(status: 200, body: '{"success": true}')
+  end
+end
+```
+
+### Test Examples
+
+```ruby
+RSpec.describe 'User tracking' do
+  let(:helix) { HelixSdk::Client.new(api_key: 'test-key') }
+
+  it 'tracks user signup' do
+    expect {
+      helix.track(
+        user_id: 'user-123',
+        event: 'signup',
+        properties: { plan: 'free' }
+      )
+    }.not_to raise_error
+  end
+end
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/3-Elements-Design/helix-analytics-sdk.git
+cd helix-analytics-sdk/sdk/ruby
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop
+```
+
+### Documentation
+
+```bash
+bundle exec yard doc
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [GitHub Repository](https://github.com/3-Elements-Design/helix-analytics-sdk)
+- **Issues**: [GitHub Issues](https://github.com/3-Elements-Design/helix-analytics-sdk/issues)
+- **Email**: support@helix-analytics.com
+
+---
+
+**Transform your Ruby applications with powerful analytics and business intelligence.**

data/lib/helix_sdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HelixSdk
+  VERSION = "1.0.0"
+end

data/lib/helix_sdk.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "helix_sdk/version"
+require_relative "helix_sdk/configuration"
+require_relative "helix_sdk/client"
+require_relative "helix_sdk/event"
+require_relative "helix_sdk/batch_processor"
+require_relative "helix_sdk/middleware/rails" if defined?(Rails)
+
+module HelixSdk
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class APIError < Error; end
+  class TimeoutError < Error; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Convenience methods that delegate to the default client
+    def track(user_id:, event:, **options)
+      client.track(user_id: user_id, event: event, **options)
+    end
+
+    def identify(user_id:, **options)
+      client.identify(user_id: user_id, **options)
+    end
+
+    def page(user_id:, **options)
+      client.page(user_id: user_id, **options)
+    end
+
+    def screen(user_id:, **options)
+      client.screen(user_id: user_id, **options)
+    end
+
+    def batch(events)
+      client.batch(events)
+    end
+
+    def flush
+      client.flush
+    end
+  end
+end

metadata

@@ -0,0 +1,177 @@
+--- !ruby/object:Gem::Specification
+name: helix_sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Helix SDK Team
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: rspec
+  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'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Official Ruby SDK for Helix Analytics - AI-powered growth analytics platform
+  with enhanced business intelligence capabilities
+email:
+- support@hangarx.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- lib/helix_sdk.rb
+- lib/helix_sdk/version.rb
+homepage: https://github.com/3-Elements-Design/helix-sdk
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/3-Elements-Design/helix-sdk
+  source_code_uri: https://github.com/3-Elements-Design/helix-sdk
+  changelog_uri: https://github.com/3-Elements-Design/helix-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/3-Elements-Design/helix-sdk/tree/main/sdk/ruby
+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.9
+specification_version: 4
+summary: Ruby SDK for Helix Analytics
+test_files: []