🚧 ClickFunnels Ruby SDK (unofficial) - WIP 🚧

A simple, dynamic Ruby SDK for the ClickFunnels API with support for all endpoints and operations mostly generated by Claude Code.

🚧 Before using in prod, this client will need additional fixing and testing. Let the authors know if you would like to use it to accelerate. 🚧

Quick Start Testing

# Or jump straight to IRB with pre-configured environment
bundle exec irb -r ./irb_test.rb

Installation

Add this line to your application's Gemfile:

gem "clickfunnels-ruby-sdk"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install clickfunnels-ruby-sdk

Configuration

Configure the SDK with your ClickFunnels subdomain and API token:

CF.configure do |config|
  config.subdomain = "myaccount"          # Your ClickFunnels subdomain
  config.api_token = "your_bearer_token"  # Your API token
  config.workspace_id = "ws_123"          # Default workspace ID (optional)
  config.team_id = "team_456"             # Default team ID (optional)
  config.debug = true                     # Enable debug logging (optional)
  config.timeout = 60                     # Request timeout in seconds (optional)
end

Usage

The SDK provides dynamic access to all ClickFunnels API endpoints following the same structure as documented in the API.

Basic CRUD Operations

First initialize the client:

ClickFunnels.new

Then Make calls through the CF workspace:

# List resources
CF::Orders::Invoice.list

# Get a specific resource  
CF::Orders::Invoice.get(123)

# Create a new resource
CF::Orders::Invoice.create(amount: 100, currency: "USD")

# Update a resource
CF::Orders::Invoice.update(123, status: "paid")

# Delete a resource
CF::Orders::Invoice.delete(123)

Usage Examples

Real-life usage examples here: https://github.com/RichStone/funnels-on-rails

🆕 Workspace-Nested Resources

# Using default workspace_id from configuration
CF::Workspaces::Contact.list
CF::Workspaces::Contact.get(123)
CF::Workspaces::Contact.create(email: "test@example.com", name: "John Doe")

# Override workspace_id for specific requests
CF::Workspaces::Contact.list(workspace_id: "different_workspace")
CF::Workspaces::Contact.create(
  { email: "test@example.com" }, 
  { workspace_id: "custom_workspace" }
)

Pagination

Use cursor-based pagination with after and before parameters:

# Get invoices after a specific ID
CF::Orders::Invoice.list(after: { id: 123 })

# Get invoices before a specific ID
CF::Orders::Invoice.list(before: { id: 456 })

Filtering

Apply filters to list operations:

# Filter by status
CF::Orders::Invoice.list(filter: { status: "paid" })

# Filter by multiple values
CF::Orders::Invoice.list(filter: { id: [1, 2, 3] })

# Multiple filters
CF::Orders::Invoice.list(filter: { status: "paid", currency: "USD" })

Sorting

Sort results using sort_property and sort_order:

CF::Orders::Invoice.list(
  sort_property: "created_at",
  sort_order: "desc"
)

Debug Logging

Enable debug logging to see all HTTP requests and responses:

CF.configure do |config|
  config.debug = true
  # Logs will be written to cf_sdk.log by default
end

# Or provide your own logger
CF.configure do |config|
  config.debug = true
  config.logger = Logger.new(STDOUT)
end

Error Handling

The SDK returns error objects instead of raising exceptions.

Testing

Run Test Suite

bundle exec rake test

Interactive Testing

Default IRB Test Environment (Recommended):

bundle exec irb -r ./irb_test.rb

This loads a pre-configured test environment with:

✅ All new features enabled
✅ Sample configuration with default workspace/team IDs
✅ Resource examples and usage tips
✅ Path generation demonstrations

Manual IRB Setup:

bundle exec irb -r ./lib/cf

Then configure manually:

CF.configure do |config|
  config.subdomain = "your_subdomain"
  config.api_token = "your_token"
  config.workspace_id = "your_workspace_id"  # Optional default
  config.debug = true
end

# Test the new features
CF::Workspaces::Contact.list
CF::Orders::Invoice.list  
CF::Users.list

Contributing

Bug reports and pull requests are welcome on GitHub.

License

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