clickfunnels-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5bf38ce3e85e117aee729468402ed494872b514f2c140f2af82c5726631e8c2e
+  data.tar.gz: cfed4a99267fc46fd30bafa227854a7b92ba9dc3d0f943be4dfa6cb1925bb144
+SHA512:
+  metadata.gz: 22170fb6c932e6498371dcc7e2cc9881a9119418d6aadcbfa1b3edee5db89f20acc0c05e19d367939686feaf0777cf2a7be174ae477123d368462b423f975146
+  data.tar.gz: 790f7605f1ea571582ef9e9ff5fd2311dab374c954dc5784d73186239988128a60035b0827f83e60d0f5902180313509cd868ffcca7c09ccf9d6b10ba4d7156f

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 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).
+
+## [0.1.0] - 2025-06-21
+
+### Added
+- Initial implementation of ClickFunnels Ruby SDK
+- Complete Ruby SDK implementation based on OpenAPI spec
+- HTTP client with configurable adapters (Net::HTTP default)
+- Resource-based API with method mapping for all ClickFunnels endpoints
+- Comprehensive test suite with WebMock integration
+- Debug logging with configurable file logger
+- Error handling with structured error responses
+- Bearer token authentication
+- Support for workspace-scoped and team-scoped resources
+- Dynamic resource path building with parent ID support
+- MIT License
+
+### Features
+- 138+ auto-generated resource classes covering all ClickFunnels API endpoints
+- Configurable subdomain, API token, workspace ID, and team ID
+- Graceful error handling returning structured error objects instead of exceptions
+- Query parameter support for filtering, pagination, and search
+- Full CRUD operations (GET, POST, PUT, PATCH, DELETE) for all resources
+- Comprehensive documentation and interactive testing environment
+
+[0.1.0]: https://github.com/RichStone/clickfunnels-ruby-sdk/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rich Steinmetz
+
+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,190 @@
+# 🚧 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
+
+```bash
+# 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:
+
+```ruby
+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:
+
+```ruby
+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
+
+```ruby
+# 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
+
+```ruby
+# 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:
+
+```ruby
+# 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:
+
+```ruby
+# 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`:
+
+```ruby
+CF::Orders::Invoice.list(
+  sort_property: "created_at",
+  sort_order: "desc"
+)
+```
+
+## Debug Logging
+
+Enable debug logging to see all HTTP requests and responses:
+
+```ruby
+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
+```bash
+bundle exec rake test
+```
+
+### Interactive Testing
+
+**Default IRB Test Environment (Recommended):**
+
+```bash
+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:**
+```bash
+bundle exec irb -r ./lib/cf
+```
+
+Then configure manually:
+```ruby
+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](https://opensource.org/licenses/MIT).

data/lib/cf/auth.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CF
+  module Auth
+    def self.bearer_token_headers(token)
+      {
+        "Authorization" => "Bearer #{token}",
+        "User-Agent" => "CF Ruby SDK #{CF::VERSION}"
+      }
+    end
+
+    def self.validate_token!(token)
+      raise CF::AuthenticationError, "API token is required" if token.nil? || token.empty?
+    end
+  end
+end

data/lib/cf/client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require "cgi"
+
+module CF
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+      @http_client = CF::HTTP::Client.new
+    end
+
+    def get(path, params = {})
+      request(:get, path, nil, params)
+    end
+
+    def post(path, body = nil, params = {})
+      request(:post, path, body, params)
+    end
+
+    def put(path, body = nil, params = {})
+      request(:put, path, body, params)
+    end
+
+    def patch(path, body = nil, params = {})
+      request(:patch, path, body, params)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, nil, params)
+    end
+
+    private
+
+    attr_reader :configuration, :http_client
+
+    def request(method, path, body = nil, params = {})
+      validate_configuration!
+      
+      url = build_url(path, params)
+      headers = build_headers
+      
+      log_request(method, url, body, headers) if configuration.log_requests?
+      
+      case method
+      when :get, :delete
+        response = http_client.send(method, url, headers)
+      else
+        response = http_client.send(method, url, body, headers)
+      end
+      
+      log_response(response) if configuration.log_requests?
+      
+      handle_response(response)
+    rescue => e
+      log_error(e) if configuration.log_requests?
+      raise
+    end
+
+    def validate_configuration!
+      CF::Auth.validate_token!(configuration.api_token)
+      raise CF::ConfigurationError, "Configuration is invalid" unless configuration.valid?
+    end
+
+    def build_url(path, params = {})
+      url = "#{configuration.base_url}#{path}"
+      return url if params.empty?
+      
+      query_string = build_query_string(params)
+      "#{url}?#{query_string}"
+    end
+
+    def build_headers
+      headers = CF::Auth.bearer_token_headers(configuration.api_token)
+      headers["Accept"] = "application/json"
+      headers["Content-Type"] = "application/json"
+      headers
+    end
+
+    def build_query_string(params)
+      params.map do |key, value|
+        if value.is_a?(Array)
+          value.map { |v| "#{key}[]=#{CGI.escape(v.to_s)}" }.join("&")
+        elsif value.is_a?(Hash)
+          value.map { |k, v| "#{key}[#{k}]=#{CGI.escape(v.to_s)}" }.join("&")
+        else
+          "#{key}=#{CGI.escape(value.to_s)}"
+        end
+      end.join("&")
+    end
+
+    def handle_response(response)
+      case response[:status]
+      when 200..299
+        parse_response_body(response[:body])
+      when 400
+        create_error_response("Bad Request", CF::BadRequestError, response)
+      when 401
+        create_error_response("Unauthorized", CF::UnauthorizedError, response)
+      when 403
+        create_error_response("Forbidden", CF::ForbiddenError, response)
+      when 404
+        create_error_response("Not Found", CF::NotFoundError, response)
+      when 422
+        create_error_response("Unprocessable Entity", CF::UnprocessableEntityError, response)
+      when 429
+        create_error_response("Too Many Requests", CF::TooManyRequestsError, response)
+      when 500
+        create_error_response("Internal Server Error", CF::InternalServerError, response)
+      when 502
+        create_error_response("Bad Gateway", CF::BadGatewayError, response)
+      when 503
+        create_error_response("Service Unavailable", CF::ServiceUnavailableError, response)
+      when 504
+        create_error_response("Gateway Timeout", CF::GatewayTimeoutError, response)
+      else
+        create_error_response("HTTP #{response[:status]}", CF::APIError, response)
+      end
+    end
+
+    def parse_response_body(body)
+      return nil if body.nil? || body.empty?
+      
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      body
+    end
+
+    def create_error_response(message, error_class, response)
+      {
+        error: true,
+        error_type: error_class.name,
+        message: message,
+        status: response[:status],
+        response_body: response[:body],
+        # response_headers: response[:headers]
+      }
+    end
+
+    def log_request(method, url, body, headers)
+      return unless configuration.logger
+      
+      configuration.logger.info("[CF SDK] Request: #{method.upcase} #{url}")
+      # configuration.logger.debug("[CF SDK] Headers: #{headers.inspect}")
+      configuration.logger.debug("[CF SDK] Body: #{body}") if body
+    end
+
+    def log_response(response)
+      return unless configuration.logger
+      
+      configuration.logger.info("[CF SDK] Response: #{response[:status]}")
+      # configuration.logger.debug("[CF SDK] Response Headers: #{response[:headers]}")
+      configuration.logger.debug("[CF SDK] Response Body: #{response[:body]}")
+    end
+
+    def log_error(error)
+      return unless configuration.logger
+      
+      configuration.logger.error("[CF SDK] Error: #{error.class.name} - #{error.message}")
+    end
+  end
+end

data/lib/cf/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CF
+  class Configuration
+    attr_accessor :subdomain, :api_token, :api_version, :debug, :timeout, :workspace_id, :team_id
+
+    def initialize
+      @subdomain = nil
+      @api_token = nil
+      @api_version = "v2"
+      @debug = false
+      @timeout = 30
+      @logger = nil
+      @workspace_id = nil
+      @team_id = nil
+    end
+
+    def base_url
+      raise CF::ConfigurationError, "Subdomain is required" unless subdomain
+      
+      "https://#{subdomain}.myclickfunnels.com/api/#{api_version}"
+    end
+
+    def valid?
+      !subdomain.nil? && !api_token.nil?
+    end
+
+    def debug?
+      debug
+    end
+
+    def log_requests?
+      debug?
+    end
+
+    def logger
+      @logger ||= debug? ? CF::FileLogger.new : nil
+    end
+
+    def logger=(custom_logger)
+      @logger = custom_logger
+    end
+  end
+end

data/lib/cf/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CF
+  class Error < StandardError; end
+  
+  class ConfigurationError < Error; end
+  
+  class AuthenticationError < Error; end
+  
+  class APIError < Error
+    attr_reader :status, :response_body, :response_headers
+
+    def initialize(message, status: nil, response_body: nil, response_headers: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+      @response_headers = response_headers
+    end
+  end
+
+  class BadRequestError < APIError; end
+  class UnauthorizedError < APIError; end
+  class ForbiddenError < APIError; end
+  class NotFoundError < APIError; end
+  class UnprocessableEntityError < APIError; end
+  class TooManyRequestsError < APIError; end
+  class InternalServerError < APIError; end
+  class BadGatewayError < APIError; end
+  class ServiceUnavailableError < APIError; end
+  class GatewayTimeoutError < APIError; end
+end

data/lib/cf/http/client.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CF
+  module HTTP
+    class Client
+      def initialize(adapter = nil)
+        @adapter = adapter || NetHTTPAdapter.new
+      end
+
+      def get(url, headers = {})
+        @adapter.request(:get, url, nil, headers)
+      end
+
+      def post(url, body = nil, headers = {})
+        @adapter.request(:post, url, body, headers)
+      end
+
+      def put(url, body = nil, headers = {})
+        @adapter.request(:put, url, body, headers)
+      end
+
+      def patch(url, body = nil, headers = {})
+        @adapter.request(:patch, url, body, headers)
+      end
+
+      def delete(url, headers = {})
+        @adapter.request(:delete, url, nil, headers)
+      end
+
+      private
+
+      attr_reader :adapter
+    end
+  end
+end

data/lib/cf/http/net_http_adapter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module CF
+  module HTTP
+    class NetHTTPAdapter
+      def initialize(options = {})
+        @options = {
+          timeout: 30,
+          open_timeout: 10,
+          use_ssl: true,
+          verify_mode: OpenSSL::SSL::VERIFY_PEER
+        }.merge(options)
+      end
+
+      def request(method, url, body = nil, headers = {})
+        uri = URI(url)
+        
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          configure_http(http)
+          
+          request = build_request(method, uri, body, headers)
+          response = http.request(request)
+          
+          handle_response(response)
+        end
+      end
+
+      private
+
+      def configure_http(http)
+        http.read_timeout = @options[:timeout]
+        http.open_timeout = @options[:open_timeout]
+        
+        if @options[:use_ssl]
+          http.use_ssl = true
+          http.verify_mode = @options[:verify_mode]
+        end
+      end
+
+      def build_request(method, uri, body, headers)
+        request_class = case method
+                       when :get then Net::HTTP::Get
+                       when :post then Net::HTTP::Post
+                       when :put then Net::HTTP::Put # FIXME: Remove PUT.
+                       when :patch then Net::HTTP::Patch
+                       when :delete then Net::HTTP::Delete
+                       else
+                         raise ArgumentError, "Unsupported HTTP method: #{method}"
+                       end
+
+        request = request_class.new(uri)
+        
+        # Set headers
+        headers.each { |key, value| request[key] = value }
+        
+        # Set body for POST/PUT/PATCH requests
+        if body && [:post, :put, :patch].include?(method)
+          request.body = body.is_a?(String) ? body : JSON.generate(body)
+          request["Content-Type"] = "application/json" unless request["Content-Type"]
+        end
+        
+        request
+      end
+
+      def handle_response(response)
+        {
+          status: response.code.to_i,
+          headers: response.to_hash,
+          body: response.body
+        }
+      end
+    end
+  end
+end

data/lib/cf/logger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module CF
+  class FileLogger
+    def initialize(log_file = "cf_sdk.log")
+      @logger = Logger.new(log_file)
+      @logger.level = Logger::DEBUG
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}: #{msg}\n"
+      end
+    end
+
+    def info(message)
+      @logger.info(message)
+    end
+
+    def debug(message)
+      @logger.debug(message)
+    end
+
+    def error(message)
+      @logger.error(message)
+    end
+
+    def warn(message)
+      @logger.warn(message)
+    end
+  end
+end

data/lib/cf/resources/base.rb

@@ -0,0 +1,530 @@
+# frozen_string_literal: true
+
+module CF
+  module Resources
+    class Base
+      class << self
+        def client
+          CF.client
+        end
+
+        def list(params = {})
+          path = build_path("list", nil, params)
+          query_params = params.reject { |k, _v| parent_id_param?(k) }
+          client.get(path, query_params)
+        end
+
+        def get(id, params = {})
+          path = build_path("get", id, params)
+          query_params = params.reject { |k, _v| parent_id_param?(k) }
+          client.get(path, query_params)
+        end
+
+        def create(attributes = {}, params = {})
+          # Extract parent IDs from attributes based on path convention
+          extracted_params = extract_parent_ids_from_attributes(attributes)
+          attributes = extracted_params[:attributes]
+          params = params.merge(extracted_params[:params])
+          
+          path = build_path("create", nil, params)
+          query_params = params.reject { |k, _v| parent_id_param?(k) }
+          wrapped_attributes = wrap_attributes_for_request(attributes)
+          client.post(path, wrapped_attributes, query_params)
+        end
+
+        def update(id, attributes = {}, params = {})
+          # Extract parent IDs from attributes based on path convention
+          extracted_params = extract_parent_ids_from_attributes(attributes)
+          attributes = extracted_params[:attributes]
+          params = params.merge(extracted_params[:params])
+          
+          path = build_path("update", id, params)
+          query_params = params.reject { |k, _v| parent_id_param?(k) }
+          wrapped_attributes = wrap_attributes_for_request(attributes)
+          client.patch(path, wrapped_attributes, query_params)
+        end
+
+        def delete(id, params = {})
+          path = build_path("delete", id, params)
+          query_params = params.reject { |k, _v| parent_id_param?(k) }
+          client.delete(path, query_params)
+        end
+
+        private
+
+        def build_path(action, id = nil, params = {})
+          segments = resource_path_segments(params)
+          
+          case action
+          when "list"
+            "/#{segments.join("/")}"
+          when "create"
+            build_create_path(segments, params)
+          when "get", "update", "delete"
+            "/#{segments.join("/")}/#{id}"
+          else
+            raise ArgumentError, "Unknown action: #{action}"
+          end
+        end
+
+        def resource_path_segments(params = {})
+          # Convert class name to path segments
+          # CF::Orders::Invoice -> ["orders", "invoices"]  
+          # CF::Workspaces::Contact -> ["workspaces", "123", "contacts"] (with workspace_id: 123)
+          # CF::Contacts::AppliedTag -> ["contacts", "123", "applied_tags"] (with contact_id: 123)
+          # CF::Contacts::Tag -> ["workspaces", "123", "contacts", "tags"] (special case)
+          
+          parts = name.split("::")
+          parts.shift # Remove "CF"
+          
+          # Check for special workspace-nested patterns
+          special_pattern = special_workspace_pattern(parts)
+          if special_pattern
+            return build_special_workspace_path(special_pattern, params)
+          end
+          
+          # Special case for Orders::Invoice - can be workspace OR order nested
+          if parts == ["Orders", "Invoice"] && !params.key?(:order_id)
+            return build_special_workspace_path({ path_suffix: "orders/invoices" }, params)
+          end
+          
+          segments = []
+          parts.each_with_index do |part, index|
+            segment = part.gsub(/([A-Z])/, "_\\1").downcase.gsub(/^_/, "")
+            
+            # For the final resource (last part), make it plural for the URL
+            if index == parts.length - 1
+              # Last segment - this is the resource, make it plural
+              segments << pluralize(segment)
+            else
+              # Namespace - use as-is (should already be plural in new convention)
+              segments << segment
+              
+              # Check if this specific namespace needs a parent ID
+              parent_id_key = "#{segment.chomp("s")}_id".to_sym
+              
+              # Always check if the parent ID is provided in params
+              if params.key?(parent_id_key)
+                # If parent ID is explicitly provided, use it (enables nested access)
+                segments << params[parent_id_key].to_s
+              elsif needs_parent_id_for_namespace?(segment, parts)
+                # If this namespace requires a parent ID by default, get it from config
+                parent_id = get_default_parent_id(parent_id_key)
+                
+                if parent_id
+                  segments << parent_id.to_s
+                else
+                  raise CF::ConfigurationError, "#{parent_id_key} is required. Provide it as a parameter or set it in configuration."
+                end
+              end
+            end
+          end
+          
+          segments
+        end
+
+        def needs_parent_id_for_namespace?(segment, parts)
+          # Determine which namespaces actually need parent IDs based on API structure
+          # This is more specific than just "all multi-part resources"
+          
+          case segment.downcase
+          when "workspaces"
+            # CF::Workspaces::Contact -> needs workspace_id
+            true
+          when "teams"
+            # CF::Teams::Workspace -> needs team_id  
+            true
+          when "contacts"
+            # CF::Contacts::AppliedTag -> needs contact_id
+            true
+          when "courses"
+            # CF::Courses::Section, CF::Courses::Enrollment -> needs course_id
+            true
+          when "orders"
+            # CF::Orders::Invoice might be top-level collection OR nested
+            # We'll check if order_id is provided in params to decide
+            false  # Default to top-level for now
+          when "products"
+            # CF::Products::Price -> needs product_id if it's nested
+            false  # Default to top-level for now  
+          when "forms"
+            # CF::Forms::FieldSet -> might need form_id
+            false  # Default to top-level for now
+          else
+            # For other cases, check if it's a known nested pattern
+            false
+          end
+        end
+
+        def get_default_parent_id(parent_id_key)
+          case parent_id_key
+          when :workspace_id
+            CF.configuration.workspace_id
+          when :team_id
+            CF.configuration.team_id
+          when :contact_id, :course_id, :order_id, :product_id, :form_id
+            # These don't have defaults - must be provided
+            nil
+          else
+            nil
+          end
+        end
+
+        def parent_id_param?(key)
+          # Any parameter ending with "_id" is considered a parent ID parameter
+          key.to_s.end_with?("_id")
+        end
+
+        def extract_parent_ids_from_attributes(attributes)
+          # Extract parent IDs that match the path convention from attributes
+          # For CF::Contacts::AppliedTag, look for contact_id in attributes
+          # For CF::Products::Price, look for product_id in attributes
+          
+          expected_parent_ids = get_expected_parent_ids_for_class
+          params = {}
+          remaining_attributes = {}
+          
+          attributes.each do |key, value|
+            if expected_parent_ids.include?(key.to_sym)
+              params[key] = value
+            else
+              remaining_attributes[key] = value
+            end
+          end
+          
+          { attributes: remaining_attributes, params: params }
+        end
+
+        def get_expected_parent_ids_for_class
+          # Based on the class name, determine what parent IDs are expected
+          # CF::Contacts::AppliedTag -> [:contact_id]
+          # CF::Products::Price -> [:product_id]
+          # CF::Workspaces::Contact -> [:workspace_id]
+          
+          parts = name.split("::")[1..-1] # Remove "CF"
+          return [] if parts.length <= 1
+          
+          parent_ids = []
+          
+          # Check each namespace part for expected parent IDs
+          parts[0..-2].each do |part|
+            segment = part.gsub(/([A-Z])/, "_\\1").downcase.gsub(/^_/, "")
+            parent_id_key = "#{segment.chomp('s')}_id".to_sym
+            parent_ids << parent_id_key
+          end
+          
+          parent_ids
+        end
+
+        def build_create_path(segments, params)
+          # For create operations, check if we need parent ID in the path
+          # This handles cases like CF::Products::Price.create(product_id: 123)
+          # which should POST to /products/123/prices instead of /products/prices
+          
+          return "/#{segments.join("/")}" if segments.length <= 1
+          
+          # Check if we have a parent resource that needs ID in the path
+          parent_resource = segments[-2] # Second to last segment
+          resource = segments[-1] # Last segment
+          
+          # Build parent ID parameter name from parent resource
+          parent_id_key = "#{parent_resource.chomp('s')}_id".to_sym
+          
+          if params.key?(parent_id_key)
+            # Replace the parent collection with parent/id pattern
+            path_segments = segments.dup
+            path_segments[-2] = "#{parent_resource}/#{params[parent_id_key]}"
+            path_segments.pop # Remove the resource name
+            path_segments << resource # Add it back
+            "/#{path_segments.join("/")}"
+          else
+            # No parent ID provided, use collection path
+            "/#{segments.join("/")}"
+          end
+        end
+
+        def wrap_attributes_for_request(attributes)
+          # Wrap attributes with the proper resource key for API requests
+          # Example: CF::Contacts::Tag -> { contacts_tag: attributes }
+          resource_key = generate_resource_key
+          { resource_key => attributes }
+        end
+
+        def generate_resource_key
+          # Generate the resource key from class name
+          # CF::Contact -> :contact
+          # CF::Contacts::Tag -> :contacts_tag
+          # CF::Courses::LessonCompletion -> :courses_lesson_completion
+          
+          parts = name.split("::")[1..-1] # Remove "CF"
+          
+          # Convert each part to snake_case
+          # For namespaces (all but last), keep plural
+          # For resource (last), make singular
+          key_parts = parts.map.with_index do |part, index|
+            snake_case = part.gsub(/([A-Z])/, "_\\1").downcase.gsub(/^_/, "")
+            
+            if index == parts.length - 1
+              # Last part is the resource - make it singular
+              singularize(snake_case)
+            else
+              # Namespace parts - keep as-is (should already be plural)
+              snake_case
+            end
+          end
+          
+          key_parts.join("_").to_sym
+        end
+
+        def singularize(word)
+          # Simple singularization rules
+          return word unless word.end_with?('s')
+          
+          case word
+          when /ies$/
+            word.sub(/ies$/, "y")
+          when /ses$/, /ches$/, /xes$/, /zes$/
+            word.sub(/es$/, "")
+          when /s$/
+            word.sub(/s$/, "")
+          else
+            word
+          end
+        end
+
+        def special_workspace_pattern(parts)
+          # Map special cases where resources are under /workspaces but have different namespace
+          # Returns the pattern info if it matches, nil otherwise
+          return nil if parts.length != 2
+          
+          namespace = parts[0].downcase
+          resource = parts[1].downcase
+          
+          # These patterns require workspace_id despite their namespace
+          workspace_nested_patterns = {
+            ["contacts", "tag"] => "contacts/tags",
+            ["orders", "tag"] => "orders/tags", 
+            ["funnels", "tag"] => "funnels/tags",
+            ["products", "tag"] => "products/tags",
+            ["products", "collection"] => "products/collections"
+          }
+          
+          # Special handling for Orders::Invoice - it can be both workspace and order nested
+          # We'll treat it as workspace-nested ONLY when no order_id is provided
+          if namespace == "orders" && resource == "invoice"
+            return nil  # Let normal logic handle it
+          end
+          
+          pattern_key = [namespace, resource]
+          if workspace_nested_patterns.key?(pattern_key)
+            { path_suffix: workspace_nested_patterns[pattern_key] }
+          else
+            nil
+          end
+        end
+        
+        def build_special_workspace_path(pattern_info, params)
+          # Build path for special workspace-nested resources
+          segments = ["workspaces"]
+          
+          # Get workspace_id from params or config
+          workspace_id = params[:workspace_id] || get_default_parent_id(:workspace_id)
+          
+          if workspace_id
+            segments << workspace_id.to_s
+          else
+            raise CF::ConfigurationError, "workspace_id is required. Provide it as a parameter or set it in configuration."
+          end
+          
+          # Add the specific path suffix (e.g., "contacts/tags")
+          segments << pattern_info[:path_suffix]
+          
+          segments
+        end
+
+        def pluralize(word)
+          # Simple pluralization rules
+          # Don't pluralize words that are already plural
+          return word if word.end_with?('s') && !word.end_with?('ss')
+          
+          case word
+          when /y$/
+            word.sub(/y$/, "ies")
+          when /sh$/, /ch$/, /x$/, /z$/
+            "#{word}es"
+          else
+            "#{word}s"
+          end
+        end
+      end
+    end
+
+    # Dynamic class generation for all endpoints
+    # TODO: This can be more "dynamic" by using the naming conventions.
+    def self.generate_resource_classes!
+      # Define all the resource classes based on ENDPOINTS.md
+      # Following convention: CF::NamespaceS(plural)::Resource(singular)
+      
+      # Top-level resources
+      define_resource_class("CF::Teams")      # Collection
+      define_resource_class("CF::Team")       # Individual resource
+      define_resource_class("CF::Users")      # Collection
+      define_resource_class("CF::User")       # Individual resource
+      
+      # Workspace nested resources
+      define_resource_class("CF::Teams::Workspace")    # Nested under teams
+      define_resource_class("CF::Workspaces")          # Collection
+      define_resource_class("CF::Workspace")           # Individual resource
+      define_resource_class("CF::Workspaces::Contact") # Nested under workspaces
+      define_resource_class("CF::Contact")             # Individual resource
+      # FIXME: Instead of this, these need to be actions.
+      define_resource_class("CF::Contacts::GdprDestroy")
+      define_resource_class("CF::Workspaces::Contacts::Upsert")
+
+      # Contact Tags
+      define_resource_class("CF::Contacts::AppliedTag")
+      define_resource_class("CF::Contacts::Tag")  # This maps to /workspaces/{id}/contacts/tags
+      
+      # Courses
+      define_resource_class("CF::Workspaces::Course")
+      define_resource_class("CF::Courses")
+      define_resource_class("CF::Course")
+      define_resource_class("CF::Courses::Enrollment")
+      define_resource_class("CF::Courses::Section")
+      define_resource_class("CF::Courses::Sections::Lesson")
+      define_resource_class("CF::Courses::Lesson")
+      define_resource_class("CF::Courses::LessonCompletion")
+      
+      # Forms
+      define_resource_class("CF::Workspaces::Form")
+      define_resource_class("CF::Forms")
+      define_resource_class("CF::Form")
+      define_resource_class("CF::Forms::FieldSet")
+      define_resource_class("CF::Forms::FieldSets::Field")
+      define_resource_class("CF::Forms::Field")
+      define_resource_class("CF::Forms::FieldSets::Fields::Reorder")
+      define_resource_class("CF::Forms::Fields::Option")
+      define_resource_class("CF::Forms::Submission")
+      define_resource_class("CF::Workspaces::FormSubmission")
+      define_resource_class("CF::Forms::Submissions::Answer")
+      
+      # Orders
+      define_resource_class("CF::Workspaces::Order")
+      define_resource_class("CF::Orders")
+      define_resource_class("CF::Order")
+      define_resource_class("CF::Orders::AppliedTag")
+      define_resource_class("CF::Workspaces::Orders::Tag")
+      define_resource_class("CF::Orders::Tag")
+      define_resource_class("CF::Orders::Invoice")
+      define_resource_class("CF::Workspaces::Orders::Invoice")
+      define_resource_class("CF::Orders::Transaction")
+      define_resource_class("CF::Workspaces::Orders::Invoices::Restock")
+      define_resource_class("CF::Orders::Invoices::Restock")
+      
+      # Products  
+      define_resource_class("CF::Workspaces::Product")
+      define_resource_class("CF::Products")
+      define_resource_class("CF::Product")
+      define_resource_class("CF::Products::Archive")
+      define_resource_class("CF::Products::Unarchive")
+      define_resource_class("CF::Workspaces::Products::Collection")
+      define_resource_class("CF::Products::Collection")
+      define_resource_class("CF::Products::Price")
+      define_resource_class("CF::Products::Variant")
+      define_resource_class("CF::Workspaces::Products::Tag")
+      define_resource_class("CF::Products::Tag")
+      
+      # Fulfillments
+      define_resource_class("CF::Workspaces::Fulfillment")
+      define_resource_class("CF::Fulfillments")
+      define_resource_class("CF::Fulfillment")
+      define_resource_class("CF::Fulfillments::Cancel")
+      define_resource_class("CF::Workspaces::Fulfillments::Location")
+      define_resource_class("CF::Fulfillments::Location")
+      
+      # Funnels
+      define_resource_class("CF::Workspaces::Funnel")
+      define_resource_class("CF::Funnels")
+      define_resource_class("CF::Funnel")
+      define_resource_class("CF::Workspaces::Funnels::Tag")
+      define_resource_class("CF::Funnels::Tag")
+      
+      # Pages
+      define_resource_class("CF::Workspaces::Page")
+      define_resource_class("CF::Pages")
+      define_resource_class("CF::Page")
+      
+      # Images
+      define_resource_class("CF::Workspaces::Image")
+      define_resource_class("CF::Images")
+      define_resource_class("CF::Image")
+      
+      # Sales
+      define_resource_class("CF::Workspaces::Sales::Pipeline")
+      define_resource_class("CF::Sales::Pipelines")
+      define_resource_class("CF::Sales::Pipeline")
+      define_resource_class("CF::Sales::Pipelines::Stage")
+      define_resource_class("CF::Workspaces::Sales::Opportunity")
+      define_resource_class("CF::Sales::Opportunities")
+      define_resource_class("CF::Sales::Opportunity")
+      define_resource_class("CF::Sales::Opportunities::Note")
+      
+      # Shipping
+      define_resource_class("CF::Workspaces::Shipping::Profile")
+      define_resource_class("CF::Shipping::Profiles")
+      define_resource_class("CF::Shipping::Profile")
+      define_resource_class("CF::Shipping::Profiles::LocationGroup")
+      define_resource_class("CF::Shipping::LocationGroups::Zone")
+      define_resource_class("CF::Shipping::Zones::Rate")
+      define_resource_class("CF::Workspaces::Shipping::Rates::Name")
+      define_resource_class("CF::Shipping::Rates::Name")
+      define_resource_class("CF::Workspaces::Shipping::Package")
+      define_resource_class("CF::Shipping::Packages")
+      define_resource_class("CF::Shipping::Package")
+      
+      # Stores
+      define_resource_class("CF::Workspaces::Store")
+      define_resource_class("CF::Stores")
+      define_resource_class("CF::Store")
+      
+      # Themes & Styles
+      define_resource_class("CF::Workspaces::Theme")
+      define_resource_class("CF::Themes")
+      define_resource_class("CF::Theme")
+      define_resource_class("CF::Workspaces::Style")
+      define_resource_class("CF::Styles")
+      
+      # Webhooks
+      define_resource_class("CF::Workspaces::Webhooks::Outgoing::Endpoint")
+      define_resource_class("CF::Webhooks::Outgoing::Endpoints")
+      define_resource_class("CF::Webhooks::Outgoing::Endpoint")
+      define_resource_class("CF::Workspaces::Webhooks::Outgoing::Event")
+      define_resource_class("CF::Webhooks::Outgoing::Events")
+      define_resource_class("CF::Webhooks::Outgoing::Event")
+    end
+
+    private
+
+    def self.define_resource_class(class_name)
+      # Create nested modules if they don't exist
+      parts = class_name.split("::")
+      current_module = Object
+      
+      parts[0..-2].each do |part|
+        unless current_module.const_defined?(part)
+          current_module.const_set(part, Module.new)
+        end
+        current_module = current_module.const_get(part)
+      end
+      
+      # Create the final class
+      class_name_part = parts.last
+      unless current_module.const_defined?(class_name_part)
+        current_module.const_set(class_name_part, Class.new(Base))
+      end
+    end
+  end
+end
+
+# Generate all resource classes when this file is loaded
+CF::Resources.generate_resource_classes!

data/lib/cf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CF
+  VERSION = "0.1.0"
+end

data/lib/cf.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "cf/version"
+require_relative "cf/configuration"
+require_relative "cf/client"
+require_relative "cf/errors"
+require_relative "cf/auth"
+require_relative "cf/logger"
+require_relative "cf/http/client"
+require_relative "cf/http/net_http_adapter"
+require_relative "cf/resources/base"
+
+module CF
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: clickfunnels-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rich Steinmetz
+- Claude Code
+bindir: exe
+cert_chain: []
+date: 2025-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.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'
+description: A simple, dynamic Ruby SDK for the ClickFunnels API with support for
+  all endpoints and operations.
+email:
+- hey@richsteinmetz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/cf.rb
+- lib/cf/auth.rb
+- lib/cf/client.rb
+- lib/cf/configuration.rb
+- lib/cf/errors.rb
+- lib/cf/http/client.rb
+- lib/cf/http/net_http_adapter.rb
+- lib/cf/logger.rb
+- lib/cf/resources/base.rb
+- lib/cf/version.rb
+homepage: https://github.com/RichStone/clickfunnels-ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RichStone/clickfunnels-ruby-sdk
+  source_code_uri: https://github.com/RichStone/clickfunnels-ruby-sdk
+  changelog_uri: https://github.com/RichStone/clickfunnels-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.1.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Ruby SDK for ClickFunnels API
+test_files: []