risenexa-leads 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf34b5b98cf6c49a1cba41db3e85d60e10967e51315c3fcbc0a69f172039c65b
+  data.tar.gz: 581d96bc497842f48c752e56cc472727f9d2c39fe60bad605a1ecdec6abda261
+SHA512:
+  metadata.gz: a0ec6e59a6c61ce13587b19bd95d49054b7d42ea3a39bb3229219dcdd5c6164ca7deec18c25b43fd5354312b330897e8bf02d8e078dbb5379615da760aae1771
+  data.tar.gz: bce5295272ceb7d35257a043eb5bb57f464625d57022a54ac0991ee395c390e23544dfa9eefa2a5dff058a4cde1255a25346701f5f5cbd85afcbabbeb0498ab8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-28
+
+### Added
+
+- Initial release of the `risenexa-leads` gem
+- Global configuration via `RisenexaLeads.configure` block (`api_key`, `startup_id`,
+  `base_url`, `timeout`)
+- `RisenexaLeads.track` for capturing a single lead with email, name, plan tier,
+  source, language, external ID, UTM parameters, and custom properties
+- `RisenexaLeads.batch` for sending up to 100 leads in a single request, with
+  partial-success handling
+- `Result` object with `success?`, `partial_success?`, `created`, `errors`, and
+  `error` accessors for ergonomic response handling
+- Faraday-based HTTP client with `faraday-retry` for transient failure recovery
+- Argument validation for required fields and batch size limits
+- RSpec test suite covering the public API (25 examples)
+- MIT License

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Espake
+
+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,245 @@
+# Risenexa Leads
+
+Ruby SDK for capturing leads and sending them to [Risenexa](https://app.risenexa.com) for AI-powered customer discovery.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'risenexa-leads'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install risenexa-leads
+```
+
+## Configuration
+
+Configure the gem with your API credentials. In a Rails app, create an initializer:
+
+```ruby
+# 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
+
+```ruby
+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)
+
+```ruby
+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:
+
+```ruby
+# 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)
+
+```ruby
+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)
+
+```ruby
+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:
+
+```ruby
+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`:
+
+```ruby
+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:
+
+```ruby
+# 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.
+
+```bash
+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](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/risenexa/leads/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Leads
+    VERSION = "0.1.0"
+  end
+end

data/lib/risenexa/leads.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+require_relative "leads/version"
+
+module Risenexa
+  module Leads
+    class Error < StandardError; end
+  end
+end
+
+# Top-level module for convenient SDK access
+module RisenexaLeads
+  class ConfigurationError < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      self.configuration = nil
+      @client = nil
+    end
+
+    def track(attributes)
+      validate_configuration!
+      client.track(attributes)
+    end
+
+    def batch(leads)
+      raise ArgumentError, "Batch requires at least one lead" if leads.empty?
+      raise ArgumentError, "Batch maximum is 100 leads" if leads.length > 100
+
+      validate_configuration!
+      client.batch(leads)
+    end
+
+    private
+
+    def validate_configuration!
+      raise ConfigurationError, "api_key is required" unless configuration&.api_key
+      raise ConfigurationError, "startup_id is required" unless configuration&.startup_id
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+  end
+
+  class Configuration
+    attr_accessor :api_key, :startup_id, :base_url, :timeout
+
+    def initialize
+      @base_url = "https://app.risenexa.com"
+      @timeout = 30
+    end
+  end
+
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def track(attributes)
+      response = connection.post("/api/v1/leads") do |req|
+        req.body = build_lead_payload(attributes).to_json
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError
+      Result.failure("Connection timeout")
+    rescue Faraday::ConnectionFailed => e
+      Result.failure("Connection failed: #{e.message}")
+    end
+
+    def batch(leads)
+      response = connection.post("/api/v1/leads/batch") do |req|
+        req.body = build_batch_payload(leads).to_json
+      end
+
+      handle_batch_response(response)
+    rescue Faraday::TimeoutError
+      BatchResult.failure("Connection timeout")
+    rescue Faraday::ConnectionFailed => e
+      BatchResult.failure("Connection failed: #{e.message}")
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def connection
+      @connection ||= Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2
+        conn.headers["Authorization"] = "Bearer #{configuration.api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.options.timeout = configuration.timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def build_lead_payload(attributes)
+      lead = {
+        startup_id: configuration.startup_id,
+        email: attributes[:email],
+        name: attributes[:name]
+      }
+
+      # Optional attributes
+      lead[:plan_tier] = attributes[:plan_tier] if attributes[:plan_tier]
+      lead[:source] = attributes[:source] if attributes[:source]
+      lead[:language] = attributes[:language] if attributes[:language]
+      lead[:external_id] = attributes[:external_id] if attributes[:external_id]
+      lead[:utm_params] = attributes[:utm_params] if attributes[:utm_params]
+      lead[:properties] = attributes[:properties] if attributes[:properties]
+
+      { lead: lead }
+    end
+
+    def build_batch_payload(leads)
+      {
+        startup_id: configuration.startup_id,
+        leads: leads.map { |lead| normalize_lead(lead) }
+      }
+    end
+
+    def normalize_lead(lead)
+      normalized = {
+        email: lead[:email],
+        name: lead[:name]
+      }
+
+      %i[plan_tier source language external_id utm_params properties].each do |key|
+        normalized[key] = lead[key] if lead[key]
+      end
+
+      normalized
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200, 201
+        data = parse_json(response.body)
+        Result.success(data["data"] || data)
+      when 401
+        data = parse_json(response.body)
+        Result.failure(data["error"] || "Unauthorized")
+      when 422
+        data = parse_json(response.body)
+        Result.validation_failure(data["errors"] || [])
+      when 429
+        data = parse_json(response.body)
+        Result.failure(data["error"] || "Rate limit exceeded")
+      when 500..599
+        Result.failure("Server error (#{response.status})")
+      else
+        Result.failure("Unexpected response: #{response.status}")
+      end
+    end
+
+    def handle_batch_response(response)
+      case response.status
+      when 200, 201
+        data = parse_json(response.body)
+        result_data = data["data"] || data
+        BatchResult.new(
+          created: result_data["created"] || 0,
+          failed: result_data["failed"] || 0,
+          errors: result_data["errors"] || []
+        )
+      when 401
+        data = parse_json(response.body)
+        BatchResult.failure(data["error"] || "Unauthorized")
+      when 422
+        data = parse_json(response.body)
+        BatchResult.failure(data["errors"]&.join(", ") || "Validation failed")
+      when 429
+        data = parse_json(response.body)
+        BatchResult.failure(data["error"] || "Rate limit exceeded")
+      when 500..599
+        BatchResult.failure("Server error (#{response.status})")
+      else
+        BatchResult.failure("Unexpected response: #{response.status}")
+      end
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+
+  class Result
+    attr_reader :lead, :error, :errors
+
+    def initialize(lead: nil, error: nil, errors: nil)
+      @lead = lead
+      @error = error
+      @errors = errors || []
+    end
+
+    def success?
+      @lead && @error.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    class << self
+      def success(lead_data)
+        new(lead: lead_data)
+      end
+
+      def failure(error_message)
+        new(error: error_message)
+      end
+
+      def validation_failure(errors)
+        new(error: errors.first, errors: errors)
+      end
+    end
+  end
+
+  class BatchResult
+    attr_reader :created, :failed, :errors, :error
+
+    def initialize(created: 0, failed: 0, errors: [], error: nil)
+      @created = created
+      @failed = failed
+      @errors = errors
+      @error = error
+    end
+
+    def success?
+      @error.nil? && @errors.empty?
+    end
+
+    def partial_success?
+      @error.nil? && @created.positive? && @errors.any?
+    end
+
+    def failure?
+      @error.present? || (@created.zero? && @errors.any?)
+    end
+
+    class << self
+      def failure(error_message)
+        new(error: error_message)
+      end
+    end
+  end
+end

data/sig/risenexa/leads.rbs

@@ -0,0 +1,6 @@
+module Risenexa
+  module Leads
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: risenexa-leads
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick Espake
+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: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.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.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: 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'
+description: A Ruby gem to track user signups and send lead data to Risenexa for AI-powered
+  customer discovery.
+email:
+- patrickespake@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/risenexa/leads.rb
+- lib/risenexa/leads/version.rb
+- sig/risenexa/leads.rbs
+homepage: https://github.com/envixo/risenexa-leads-gem
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/envixo/risenexa-leads-gem
+  source_code_uri: https://github.com/envixo/risenexa-leads-gem
+  changelog_uri: https://github.com/envixo/risenexa-leads-gem/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.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 capturing leads and sending them to Risenexa
+test_files: []