Risenexa Leads

Ruby SDK for capturing leads and sending them to Risenexa for AI-powered customer discovery.

Installation

Add this line to your application's Gemfile:

gem 'risenexa-leads'

And then execute:

bundle install

Or install it yourself as:

gem install risenexa-leads

Configuration

Configure the gem with your API credentials. In a Rails app, create an initializer:

# config/initializers/risenexa_leads.rb

RisenexaLeads.configure do |config|
  config.api_key = ENV['RISENEXA_API_KEY']
  config.startup_id = ENV['RISENEXA_STARTUP_ID']

  # Optional settings
  config.base_url = 'https://app.risenexa.com'  # Default
  config.timeout = 30  # Default: 30 seconds
end

Getting Your Credentials

1. Log in to your Risenexa account
2. Navigate to your Startup settings
3. Copy your API key and Startup ID from the SDK Integration section

Usage

Track a Single Lead

result = RisenexaLeads.track(
  email: 'john@example.com',
  name: 'John Doe',
  plan_tier: 'pro',           # optional
  source: 'signup_form',      # optional
  language: 'en',             # optional, defaults to 'en'
  external_id: 'user_12345',  # optional, for idempotent upserts
  utm_params: {               # optional
    source: 'google',
    medium: 'cpc',
    campaign: 'launch'
  },
  properties: {               # optional, custom attributes
    signup_reason: 'productivity',
    team_size: 10
  }
)

if result.success?
  puts "Lead created: #{result.lead['id']}"
else
  puts "Error: #{result.error}"
end

Track Multiple Leads (Batch)

leads = [
  { email: 'john@example.com', name: 'John Doe', plan_tier: 'pro' },
  { email: 'jane@example.com', name: 'Jane Smith', plan_tier: 'starter' }
]

result = RisenexaLeads.batch(leads)

if result.success?
  puts "Created #{result.created.length} leads"
elsif result.partial_success?
  puts "Created #{result.created.length} leads"
  puts "Failed: #{result.errors.length}"
  result.errors.each do |error|
    puts "  - #{error['email']}: #{error['errors'].join(', ')}"
  end
else
  puts "Error: #{result.error}"
end

Note: Batch requests are limited to 100 leads per request.

Rails Integration Example

Track leads when users sign up:

# app/controllers/registrations_controller.rb
class RegistrationsController < ApplicationController
  def create
    @user = User.new(user_params)

    if @user.save
      # Track the lead asynchronously
      TrackLeadJob.perform_later(@user.id)
      redirect_to dashboard_path
    else
      render :new
    end
  end
end

# app/jobs/track_lead_job.rb
class TrackLeadJob < ApplicationJob
  queue_as :default

  def perform(user_id)
    user = User.find(user_id)

    RisenexaLeads.track(
      email: user.email,
      name: user.name,
      external_id: "user_#{user.id}",
      plan_tier: user.plan,
      source: user.signup_source,
      utm_params: user.utm_params,
      properties: {
        company: user.company_name,
        role: user.job_title
      }
    )
  end
end

Response Objects

Result (for single leads)

result = RisenexaLeads.track(...)

result.success?   # true if lead was created
result.failure?   # true if there was an error
result.lead       # Hash with lead data on success
result.error      # Error message string on failure
result.errors     # Array of validation errors (for 422 responses)

BatchResult (for batch operations)

result = RisenexaLeads.batch(...)

result.success?          # true if all leads were created
result.partial_success?  # true if some leads were created
result.failure?          # true if no leads were created
result.created           # Array of created lead hashes
result.errors            # Array of error hashes with index, email, and errors
result.error             # General error message (for auth/rate limit errors)

Error Handling

The SDK handles various error scenarios gracefully:

result = RisenexaLeads.track(email: 'test@example.com', name: 'Test')

case
when result.success?
  # Lead created successfully
when result.errors.any?
  # Validation errors (e.g., invalid email, duplicate)
  result.errors.each { |e| puts e }
when result.error.include?('Rate limit')
  # Too many requests, implement backoff
when result.error.include?('Invalid API token')
  # Check your API key configuration
else
  # Other error
  puts result.error
end

Configuration Errors

Missing configuration will raise RisenexaLeads::ConfigurationError:

RisenexaLeads.reset_configuration!
RisenexaLeads.track(email: 'test@example.com', name: 'Test')
# => raises RisenexaLeads::ConfigurationError: api_key is required

Idempotency

Use external_id to make lead creation idempotent:

# First call creates the lead
RisenexaLeads.track(
  email: 'john@example.com',
  name: 'John Doe',
  external_id: 'user_123'
)

# Second call with same external_id updates the existing lead
RisenexaLeads.track(
  email: 'john.updated@example.com',
  name: 'John Doe Updated',
  external_id: 'user_123'
)

Rate Limiting

The Risenexa API is rate limited to 100 requests per minute per API token. The SDK will return a failure result with a rate limit error message when exceeded.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

bundle install
bundle exec rspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/patrickespake/risenexa-leads-gem.

License

The gem is available as open source under the terms of the MIT License.