🚧 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

# 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)

🆕 Workspace-Nested Resources

# Using default workspace_id from configuration
CF::Workspaces::Contact.list
CF::Workspaces::Contact.get(123)
CF::Workspaces::Contact.create(email: "[email protected]", name: "John Doe")

# Override workspace_id for specific requests
CF::Workspaces::Contact.list(workspace_id: "different_workspace")
CF::Workspaces::Contact.create(
  { email: "[email protected]" }, 
  { 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.