hangarx 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68fb5a44f579f4f336f4f63f73f20a1a879fc1beda7b4511bb0a8dcaa11c2923
+  data.tar.gz: dd2417a945455c958e16f4860c585c69eb89422d1fd1a0e2c23cbb558e1da51a
+SHA512:
+  metadata.gz: cee585156d868525dfe51e7a60086234a157b50d0232f34d689f707f3eae1851901cdd71535e72db50bd88c4c4949909100ae54a90092e4b5646b90dd907ed22
+  data.tar.gz: 91debdb39accc97b1af8380566baf65f2d3c2cd66a62c21a3f23221428583778ca5cf2ea2391113015624a4861e7eaa79033ace3a041ea0abfbde12fa5631c61

data/README.md

@@ -0,0 +1,684 @@
+# HangarX Ruby SDK
+
+Official Ruby SDK for HangarX - AI-powered Growth OS with analytics, SEO intelligence, and workflow automation.
+
+## Features
+
+- 🚀 **Event Tracking** - Track user actions, page views, and custom events
+- 🧠 **AI-Powered Analytics** - Conversational analytics and insights
+- 📊 **SEO Intelligence** - Real-time SEO insights and recommendations
+- 🔄 **Workflow Automation** - Execute and monitor multi-agent workflows
+- 📈 **Growth Intelligence** - AI-driven growth recommendations
+- 🎯 **Anomaly Detection** - Automatic detection of unusual patterns
+- 💾 **Batch Processing** - Efficient bulk event handling
+- 🔒 **Thread-Safe** - Safe for multi-threaded applications
+- ⚡ **High Performance** - Optimized for production use
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hangarx'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install hangarx
+```
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```ruby
+require 'hangarx'
+
+hangarx = HangarX::Client.new(
+  api_key: 'proj_abc123...', # Your project SDK key (from projects.sdk_key)
+  endpoint: 'https://api.hangarx.com'
+)
+```
+
+### 2. Track Events
+
+```ruby
+# Track a user action
+hangarx.track(
+  user_id: 'user-123',
+  event: 'button_clicked',
+  properties: {
+    button_name: 'signup',
+    page: 'landing'
+  }
+)
+
+# Identify a user
+hangarx.identify(
+  user_id: 'user-123',
+  traits: {
+    email: 'user@example.com',
+    plan: 'premium',
+    company: 'Acme Inc'
+  }
+)
+
+# Track page views
+hangarx.page(
+  user_id: 'user-123',
+  name: 'Landing Page',
+  properties: {
+    url: 'https://example.com',
+    title: 'Welcome'
+  }
+)
+```
+
+### 3. Use Growth OS Features
+
+```ruby
+# Ask analytics questions
+answer = hangarx.ask_analytics(
+  'What are my top performing channels this month?'
+)
+
+# Get SEO insights
+seo_insights = hangarx.seo_insights(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+
+# Detect anomalies
+anomalies = hangarx.detect_anomalies(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+
+# Get real-time recommendations
+recommendations = hangarx.real_time_recommendations
+```
+
+## Configuration
+
+### Client Options
+
+```ruby
+hangarx = HangarX::Client.new(
+  api_key: 'proj_abc123...',      # Required: Your project SDK key (from projects.sdk_key)
+  endpoint: 'https://api.hangarx.com', # Optional: API endpoint
+  timeout: 30,                    # Optional: Request timeout in seconds
+  retries: 3,                     # Optional: Number of retries
+  batch_size: 100,                # Optional: Batch size for bulk operations
+  debug: false                    # Optional: Enable debug logging
+)
+```
+
+### Environment Variables
+
+You can also configure the client using environment variables:
+
+```bash
+export HANGARX_API_KEY=proj_abc123...  # Your project SDK key
+export HANGARX_ENDPOINT=https://api.hangarx.com
+```
+
+```ruby
+# Client will automatically use environment variables
+hangarx = HangarX::Client.new
+```
+
+## API Reference
+
+### Event Tracking
+
+#### Track Events
+
+Track user actions and behaviors:
+
+```ruby
+hangarx.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',
+    category: 'subscription'
+  },
+  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
+hangarx.identify(
+  user_id: 'user-123',
+  traits: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    plan: 'premium',
+    company: 'Acme Inc',
+    created_at: Time.now
+  }
+)
+```
+
+#### Page Views
+
+Track page views and navigation:
+
+```ruby
+hangarx.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
+hangarx.screen(
+  user_id: 'user-123',
+  name: 'Dashboard',
+  category: 'app',
+  properties: {
+    screen_id: 'dashboard_v2',
+    version: '2.1.0'
+  }
+)
+```
+
+### Growth OS Features
+
+#### Ask Analytics
+
+Ask natural language questions about your analytics:
+
+```ruby
+answer = hangarx.ask_analytics(
+  'What are my conversion rates by channel?',
+  context: { timeframe: 'last_30_days' }
+)
+```
+
+#### Growth Intelligence
+
+Get AI-powered growth insights:
+
+```ruby
+intelligence = hangarx.growth_intelligence(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+```
+
+#### SEO Insights
+
+Get SEO performance insights:
+
+```ruby
+seo_insights = hangarx.seo_insights(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+```
+
+#### Anomaly Detection
+
+Detect unusual patterns in your data:
+
+```ruby
+anomalies = hangarx.detect_anomalies(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+```
+
+#### Real-Time Recommendations
+
+Get real-time personalized recommendations:
+
+```ruby
+recommendations = hangarx.real_time_recommendations(
+  session_id: 'session-123'
+)
+```
+
+### Workflow Management
+
+#### Execute Workflow
+
+Execute a multi-agent workflow:
+
+```ruby
+result = hangarx.execute_workflow(
+  name: 'SEO Audit',
+  steps: [
+    { agent: 'helix', action: 'analyze_content', params: { url: 'https://example.com' } },
+    { agent: 'cortex', action: 'extract_entities', params: { text: '...' } },
+    { agent: 'raven', action: 'track_results', params: { metrics: {...} } }
+  ]
+)
+```
+
+### Batch Operations
+
+#### Batch Events
+
+Send multiple events efficiently:
+
+```ruby
+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 }
+  }
+]
+
+hangarx.batch(events)
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```ruby
+begin
+  hangarx.track(
+    user_id: 'user-123',
+    event: 'purchase',
+    properties: { amount: 99.99 }
+  )
+rescue HangarX::Error => e
+  puts "Failed to track event: #{e.message}"
+end
+```
+
+### Custom Context
+
+```ruby
+hangarx.track(
+  user_id: 'user-123',
+  event: 'api_call',
+  properties: { endpoint: '/api/users' },
+  context: {
+    app: {
+      name: 'MyApp',
+      version: '1.2.3'
+    },
+    library: {
+      name: 'hangarx-ruby',
+      version: HangarX::VERSION
+    },
+    device: {
+      type: 'server'
+    }
+  }
+)
+```
+
+### Async Processing
+
+```ruby
+# Non-blocking event tracking
+hangarx.track_async(
+  user_id: 'user-123',
+  event: 'background_job_completed',
+  properties: { job_id: 'job-456' }
+)
+```
+
+## Rails Integration
+
+### Initializer
+
+Create `config/initializers/hangarx.rb`:
+
+```ruby
+HangarX.configure do |config|
+  config.api_key = ENV['HANGARX_API_KEY']
+  config.endpoint = ENV['HANGARX_ENDPOINT']
+  config.team_id = ENV['HANGARX_TEAM_ID']
+  config.debug = Rails.env.development?
+end
+```
+
+### Controller Usage
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :track_page_view
+
+  private
+
+  def track_page_view
+    return unless current_user
+
+    HangarX.page(
+      user_id: current_user.id,
+      name: "#{controller_name}##{action_name}",
+      properties: {
+        url: request.url,
+        user_agent: request.user_agent,
+        referrer: request.referrer
+      }
+    )
+  end
+end
+```
+
+### Model Integration
+
+```ruby
+class User < ApplicationRecord
+  after_create :track_signup
+  after_update :track_profile_update
+
+  private
+
+  def track_signup
+    HangarX.track(
+      user_id: id,
+      event: 'user_signup',
+      properties: {
+        email: email,
+        plan: plan,
+        source: utm_source
+      }
+    )
+
+    HangarX.identify(
+      user_id: id,
+      traits: {
+        email: email,
+        name: name,
+        created_at: created_at
+      }
+    )
+  end
+
+  def track_profile_update
+    HangarX.track(
+      user_id: id,
+      event: 'profile_updated',
+      properties: {
+        fields_changed: saved_changes.keys
+      }
+    )
+  end
+end
+```
+
+### Background Jobs
+
+```ruby
+class AnalyticsJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id, event, properties = {})
+    HangarX.track(
+      user_id: user_id,
+      event: event,
+      properties: properties
+    )
+  end
+end
+
+# Usage
+AnalyticsJob.perform_later('user-123', 'purchase', { amount: 99.99 })
+```
+
+## Sinatra Integration
+
+```ruby
+require 'sinatra'
+require 'hangarx'
+
+configure do
+  set :hangarx, HangarX::Client.new(
+    api_key: ENV['HANGARX_API_KEY']
+  )
+end
+
+before do
+  settings.hangarx.page(
+    user_id: session[:user_id],
+    name: request.path,
+    properties: {
+      url: request.url,
+      method: request.request_method
+    }
+  ) if session[:user_id]
+end
+
+post '/signup' do
+  user = create_user(params)
+  
+  settings.hangarx.identify(
+    user_id: user.id,
+    traits: {
+      email: user.email,
+      name: user.name
+    }
+  )
+  
+  settings.hangarx.track(
+    user_id: user.id,
+    event: 'signup',
+    properties: {
+      plan: params[:plan],
+      source: params[:utm_source]
+    }
+  )
+  
+  redirect '/dashboard'
+end
+```
+
+## Testing
+
+### RSpec Integration
+
+```ruby
+# spec/spec_helper.rb
+require 'hangarx'
+require 'webmock/rspec'
+
+RSpec.configure do |config|
+  config.before(:each) do
+    # Stub HangarX API calls in tests
+    stub_request(:post, %r{api.hangarx.com})
+      .to_return(status: 200, body: '{"success": true}')
+  end
+end
+```
+
+### Test Examples
+
+```ruby
+RSpec.describe 'User tracking' do
+  let(:hangarx) { HangarX::Client.new(api_key: 'test-key') }
+
+  it 'tracks user signup' do
+    expect {
+      hangarx.track(
+        user_id: 'user-123',
+        event: 'signup',
+        properties: { plan: 'free' }
+      )
+    }.not_to raise_error
+  end
+
+  it 'identifies users' do
+    expect {
+      hangarx.identify(
+        user_id: 'user-123',
+        traits: { email: 'test@example.com' }
+      )
+    }.not_to raise_error
+  end
+end
+```
+
+## Best Practices
+
+### Event Naming
+
+Use clear, descriptive event names:
+
+```ruby
+# ✅ Good
+hangarx.track(user_id: 'user-123', event: 'purchase_completed')
+hangarx.track(user_id: 'user-123', event: 'signup_form_submitted')
+
+# ❌ Bad
+hangarx.track(user_id: 'user-123', event: 'event1')
+hangarx.track(user_id: 'user-123', event: 'click')
+```
+
+### Property Structure
+
+Keep properties consistent and well-structured:
+
+```ruby
+# ✅ Good
+hangarx.track(
+  user_id: 'user-123',
+  event: 'purchase',
+  properties: {
+    product_id: 'prod-456',
+    product_name: 'Premium Plan',
+    revenue: 99.99,
+    currency: 'USD',
+    category: 'subscription'
+  }
+)
+
+# ❌ Bad
+hangarx.track(
+  user_id: 'user-123',
+  event: 'purchase',
+  properties: {
+    prod: 'Premium',
+    amount: '99.99',
+    type: 'sub'
+  }
+)
+```
+
+### User Identification
+
+Always identify users early:
+
+```ruby
+# On signup
+hangarx.identify(
+  user_id: user.id,
+  traits: {
+    email: user.email,
+    name: user.name,
+    created_at: Time.now
+  }
+)
+
+# On login
+hangarx.identify(
+  user_id: user.id,
+  traits: {
+    last_login: Time.now
+  }
+)
+```
+
+## Performance
+
+The SDK is optimized for high-performance production use:
+
+- **Connection Pooling**: Reuses HTTP connections
+- **Retry Logic**: Exponential backoff for failed requests
+- **Thread-Safe**: Safe for multi-threaded applications
+- **Memory Efficient**: Minimal memory footprint
+- **Batch Processing**: Efficient bulk event handling
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/your-org/hangarx-mission-control.git
+cd hangarx-mission-control/sdk/hangarx-ruby
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop
+```
+
+### Documentation
+
+```bash
+bundle exec yard doc
+```
+
+## Support
+
+- **Documentation**: [docs.hangarx.com](https://docs.hangarx.com)
+- **GitHub**: [github.com/your-org/hangarx-mission-control](https://github.com/your-org/hangarx-mission-control)
+- **Issues**: [github.com/your-org/hangarx-mission-control/issues](https://github.com/your-org/hangarx-mission-control/issues)
+- **Email**: support@hangarx.com
+
+## 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
+
+MIT License - see [LICENSE](../../LICENSE) for details.
+
+---
+
+**Transform your Ruby applications with AI-powered growth intelligence.**

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: hangarx
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- HangarX Team
+bindir: bin
+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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !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: Ruby SDK for HangarX with analytics, SEO intelligence, and workflow automation
+email:
+- support@hangarx.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+homepage: https://hangarx.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://hangarx.ai
+  source_code_uri: https://github.com/hangarx/ruby-sdk
+  changelog_uri: https://github.com/hangarx/ruby-sdk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.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: Official Ruby SDK for HangarX - AI-powered Growth OS
+test_files: []