Add power user feature & ngrok auto-start

Author: RichStone

CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+This is a Ruby on Rails 8.0 application built on the Bullet Train framework. It integrates with ClickFunnels for user management and power user tracking.
+
+## Development Commands
+
+### Setup
+```bash
+bin/setup                    # Initial setup (installs dependencies, creates database)
+bin/rails db:seed           # Seed database with sample data
+```
+
+### Running the Application
+```bash
+bin/dev                     # Start development server with Procfile.dev (includes Sidekiq, CSS/JS watching)
+bin/rails server            # Start only Rails server
+```
+
+### Testing
+```bash
+bin/rails test              # Run all tests
+bin/rails test test/path/to/specific_test.rb  # Run specific test file
+bin/rails test test/path/to/test.rb:42        # Run specific test at line 42
+MAGIC_TEST=1 bin/rails test:system             # Record system tests with Magic Test
+```
+
+### Code Quality
+```bash
+bundle exec standardrb      # Run Ruby linter
+bundle exec standardrb --fix # Auto-fix Ruby linting issues
+```
+
+### Database
+```bash
+bin/rails db:migrate        # Run pending migrations
+bin/rails db:rollback       # Rollback last migration
+bin/rails db:schema:dump    # Update db/schema.rb
+```
+
+### Background Jobs
+```bash
+bundle exec sidekiq         # Run Sidekiq (included in bin/dev)
+```
+
+### Deployment
+```bash
+bin/kamal deploy            # Deploy to production using Kamal
+```
+
+## Architecture Overview
+
+### Bullet Train Framework
+Bullet Train is a comprehensive Ruby on Rails SaaS framework that provides extensive built-in functionality. This application leverages:
+
+**Core Features**:
+- Multi-tenancy with Teams and membership-based permissions
+- User authentication with Devise
+- OAuth integration via Doorkeeper
+- Webhook handling (incoming and outgoing)
+- Admin panel via Avo
+- API versioning structure
+- Role-based access control with granular permissions
+- Onboarding workflows
+- Billing system integration (Stripe)
+- Zapier integration support
+
+**Super Scaffolding**:
+Bullet Train's code generation engine that creates complete CRUD interfaces. Key commands:
+
+```bash
+# Generate new model with CRUD interface
+rails generate super_scaffold ModelName Team field:field_type
+
+# Add field to existing model
+rails generate super_scaffold:field ModelName field:field_type
+
+# Available field types: text_field, trix_editor, buttons, super_select, image
+```
+
+Example:
+```bash
+# Create a Project model under Team
+rails generate super_scaffold Project Team name:text_field description:trix_editor
+rake db:migrate
+
+# Add status field with button options
+rails generate super_scaffold:field Project status:buttons
+rake db:migrate
+```
+
+**Important Conventions**:
+- All models are typically scoped to Teams
+- Keep magic comments in generated files for future scaffolding
+- Use `valid_*` methods for defining select field options
+- Support for Action Models for complex business logic
+- Modular design allows overriding framework components
+
+### Key Components
+
+**ClickFunnels Integration** (app/lib/clickfunnels/):
+- Custom Faraday-based client for ClickFunnels API
+- Plans to migrate to official clickfunnels-ruby-sdk gem (see PLAN.md)
+- Webhook handling for ClickFunnels events
+- Background job for marking power users
+
+**API Structure** (app/controllers/api/v1/):
+- RESTful API with versioning
+- OAuth authentication via Doorkeeper
+- Standard JSON responses
+
+**Webhook System** (app/controllers/webhooks/):
+- Incoming webhooks from external services
+- Outgoing webhooks for event notifications
+- Signature verification for security
+
+**Background Processing**:
+- Sidekiq for async job processing
+- Redis for job queue storage
+- MarkPowerUserJob for ClickFunnels integration
+
+### Configuration
+
+**Environment Variables** (config/application.yml):
+- BASE_URL: Application base URL
+- MARKETING_SITE_URL: Marketing site URL
+- STRIPE_SECRET_KEY: Stripe API key
+- CLICK_FUNNELS_API_KEY: ClickFunnels API key
+- CLICK_FUNNELS_WORKSPACE_SUBDOMAIN: ClickFunnels subdomain (to be renamed)
+- CLICK_FUNNELS_WORKSPACE_ID: Workspace ID (to be moved to config)
+
+**Database**: PostgreSQL with ActiveRecord
+
+**Asset Pipeline**: 
+- ESBuild for JavaScript bundling
+- Tailwind CSS with PostCSS
+- Stimulus for JavaScript framework
+
+### Testing Strategy
+- Minitest for unit and integration tests
+- Capybara for system tests
+- FactoryBot for test data
+- SimpleCov for coverage reporting
+- Fixtures for external API responses (test/fixtures/clickfunnels/)
+
+### Current Development Focus
+The `mark-as-power-user-in-clickfunnels` branch implements functionality to mark users as "power users" in ClickFunnels. There's an active migration plan (PLAN.md) to move from the custom implementation to the official ClickFunnels SDK.

Gemfile

@@ -270,4 +270,7 @@ gem "active_hash"
 # You can add any Ruby gems you need below. By keeping them separate from our gems above, you'll avoid the likelihood
 # that you run into a merge conflict in the future.
 
+# ClickFunnels SDK for interacting with the ClickFunnels API.
+gem "clickfunnels-ruby-sdk"
+
 # 🚅 super scaffolding will insert new oauth providers above this line.

Gemfile.lock

@@ -223,6 +223,8 @@ GEM
     choice (0.2.0)
     chronic (0.10.2)
     chunky_png (1.4.0)
+    clickfunnels-ruby-sdk (0.1.0)
+      json (~> 2.0)
     cloudinary (2.3.0)
       faraday (>= 2.0.1, < 3.0.0)
       faraday-follow_redirects (~> 0.3.0)
@@ -714,6 +716,7 @@ DEPENDENCIES
   capybara-email
   capybara-lockstep
   chronic
+  clickfunnels-ruby-sdk
   colorize
   cssbundling-rails
   debug

Procfile.dev

@@ -3,4 +3,4 @@ worker: bundle exec sidekiq -t 25
 js: THEME="light" yarn build --watch
 light-css: yarn light:build:css --watch
 light-mailer-css: yarn light:build:mailer:css --watch
-# ngrok: ngrok http 3003
+ngrok: bin/ngrok-with-webhook

app/clients/click_funnels.rb

@@ -0,0 +1,119 @@
+require "cf"
+
+# ClickFunnels client using the official clickfunnels-ruby-sdk
+class ClickFunnels
+  attr_reader :workspace_id, :subdomain, :api_key
+
+  def initialize(api_key: nil, workspace_id: nil, subdomain: nil)
+    # TODO: Only API secret should be env var. The others are configs.
+    @workspace_id = workspace_id || ENV["CLICK_FUNNELS_WORKSPACE_ID"]
+    @api_key = api_key || ENV["CLICK_FUNNELS_API_KEY"]
+    @subdomain = subdomain || ENV["CLICK_FUNNELS_WORKSPACE_SUBDOMAIN"]
+
+    raise ArgumentError, "ClickFunnels workspace_id is required" unless @workspace_id
+    raise ArgumentError, "ClickFunnels subdomain is required" unless @subdomain
+    raise ArgumentError, "ClickFunnels api_key is required" unless @api_key
+
+    # TODO: This should happen in an initializer.
+    configure_sdk
+  end
+
+  # List contacts with optional email filter
+  # https://developers.myclickfunnels.com/reference/listcontacts
+  #
+  # @param email_address [String] Optional email address to filter contacts
+  # @return [Array] Array of contact hashes from ClickFunnels API
+  def list_contacts(email_address: nil)
+    params = {}
+
+    if email_address
+      # Try different filter format based on the SDK documentation
+      params[:filter] = {email_address: email_address}
+    end
+
+    params[:workspace_id] = workspace_id
+
+    response = CF::Workspaces::Contact.list(params)
+
+    # TODO: The SDK should return indifferent access hashes directly.
+    Array(response).map { |item| item.to_h.with_indifferent_access }
+  rescue => e
+    Rails.logger.error("Error listing contacts: #{e.class} - #{e.message}") if defined?(Rails)
+    []
+  end
+
+  # Find a contact by email address
+  # @param email_address [String] Email address to find contact
+  # @return [Hash, nil] Contact data or nil if not found
+  def find_contact_by_email(email_address)
+    contacts = list_contacts(email_address: email_address)
+
+    if contacts.is_a?(Array) && !contacts.empty?
+      contacts.first.to_h.with_indifferent_access
+    end
+  rescue => e
+    Rails.logger.warn("Error finding contact by email: #{e.class} - #{e.message}") if defined?(Rails)
+    nil
+  end
+
+  # Create a tag for a contact
+  # https://developers.myclickfunnels.com/reference/createcontactsappliedtags
+  #
+  # @param contact_id [String] ID of the contact to tag
+  # @param tag_id [String] ID of the tag to apply (defaults to power user tag 328935)
+  # @return [Hash] Response from ClickFunnels API
+  def create_contact_tag(contact_id, tag_id: "328935")
+    response = CF::Contacts::AppliedTag.create(
+      contact_id: contact_id,
+      tag_id: tag_id
+    )
+
+    # Convert OpenStruct response to hash with string keys for compatibility
+    # TODO: The SDK should return indifferent access hashes directly.
+    response.to_h.with_indifferent_access
+  rescue => e
+    Rails.logger.error("Error creating contact tag: #{e.class} - #{e.message}") if defined?(Rails)
+    {"error" => e.message}
+  end
+
+  # Mark a user as a power user
+  # @param email_address [String] Email address of the user to mark as power user
+  # @return [Boolean] True if successful, false otherwise
+  #
+  # FIXME: Any errors happening here and in the callstack bewow are unexpected and
+  #        should be sent to the error tracker.
+  def mark_as_power_user(email_address)
+    contact = find_contact_by_email(email_address)
+    # TODO: This is an inconsistency between the BusinessOS and app, worth sending to the error tracker.
+    unless contact
+      Rails.logger.error("Contact not found to mark as power user for email: #{email_address}")
+      return false
+    end
+
+    contact_id = contact["id"]
+    response = create_contact_tag(contact_id)
+
+    if response.is_a?(Hash) && response["error"]
+      Rails.logger.error("Error marking user as power user: #{response["error"]}")
+      raise "Failed to mark user as power user: #{response["error"]}"
+    end
+
+    # TODO: The SDK should return indifferent access hashes directly.
+    response.to_h.with_indifferent_access
+  end
+
+  def base_url
+    "https://#{subdomain}.myclickfunnels.com"
+  end
+
+  private
+
+  def configure_sdk
+    CF.configure do |config|
+      config.subdomain = subdomain
+      config.api_token = api_key
+      config.workspace_id = workspace_id
+      config.debug = Rails.env.development? if defined?(Rails)
+    end
+  end
+end

app/jobs/mark_power_user_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class MarkPowerUserJob < ApplicationJob
+  queue_as :default
+
+  # Mark a user as a power user in ClickFunnels
+  # @param email [String] Email address of the user to mark as power user
+  def perform(email)
+    click_funnels_client = ClickFunnels.new
+    click_funnels_client.mark_as_power_user(email)
+  rescue => e
+    Rails.logger.error("Failed to mark user as power user in ClickFunnels: #{e.class} - #{e.message}")
+    raise e
+  end
+end

bin/ngrok-with-webhook

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Start ngrok in background
+ngrok http 3003 &
+NGROK_PID=$!
+
+# Give ngrok time to start
+sleep 5
+
+# Update webhook URL
+bin/update-webhook-url
+
+# Keep ngrok running
+wait $NGROK_PID