Part 1 of zoho integration for tenant management

Author: etewiah

app/controllers/pwb/signup_controller.rb

@@ -42,7 +42,17 @@ def start
         return render :new
       end
 
-      result = ProvisioningService.new.start_signup(email: email)
+      # Capture request info for Zoho CRM lead tracking
+      zoho_request_info = {
+        ip: request.remote_ip,
+        utm_source: params[:utm_source],
+        utm_medium: params[:utm_medium],
+        utm_campaign: params[:utm_campaign]
+      }
+
+      result = Pwb::User.with_zoho_request_info(zoho_request_info) do
+        ProvisioningService.new.start_signup(email: email)
+      end
 
       if result[:success]
         signup_session.store_start_result(result)

app/jobs/pwb/zoho/base_job.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Base class for all Zoho sync jobs with common error handling
+    #
+    class BaseJob < ApplicationJob
+      queue_as :zoho_sync
+
+      # Retry rate limit errors with exponential backoff
+      retry_on Zoho::RateLimitError, wait: ->(executions) { (executions**2) * 30.seconds }, attempts: 5
+
+      # Retry connection errors with shorter intervals
+      retry_on Zoho::ConnectionError, wait: 10.seconds, attempts: 3
+      retry_on Zoho::TimeoutError, wait: 10.seconds, attempts: 3
+
+      # Retry API errors (might be temporary)
+      retry_on Zoho::ApiError, wait: 30.seconds, attempts: 2
+
+      # Don't retry auth errors - needs manual intervention
+      discard_on Zoho::AuthenticationError do |job, error|
+        Rails.logger.error "[Zoho] Authentication error in #{job.class.name}: #{error.message}"
+        Rails.logger.error "[Zoho] Check Zoho credentials and refresh token"
+        # TODO: Send alert to admin
+      end
+
+      # Don't retry config errors
+      discard_on Zoho::ConfigurationError do |job, error|
+        Rails.logger.warn "[Zoho] Not configured, skipping #{job.class.name}: #{error.message}"
+      end
+
+      # Don't retry validation errors (bad data)
+      discard_on Zoho::ValidationError do |job, error|
+        Rails.logger.error "[Zoho] Validation error in #{job.class.name}: #{error.message}"
+      end
+
+      private
+
+      def zoho_enabled?
+        Zoho::Client.instance.configured?
+      end
+
+      def lead_sync_service
+        @lead_sync_service ||= Zoho::LeadSyncService.new
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/sync_activity_job.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Sync user activity to Zoho CRM as notes + engagement score
+    #
+    # Tracks important user actions that indicate engagement:
+    # - Adding properties
+    # - Customizing website (logo, theme, pages)
+    # - Receiving inquiries
+    # - Adding team members
+    #
+    # Usage:
+    #   Pwb::Zoho::SyncActivityJob.perform_later(user.id, 'property_added', { title: 'Beach House', reference: 'BH-001' })
+    #
+    class SyncActivityJob < BaseJob
+      def perform(user_id, activity_type, details = {})
+        return unless zoho_enabled?
+
+        user = ::Pwb::User.find_by(id: user_id)
+        unless user
+          Rails.logger.warn "[Zoho] User #{user_id} not found for activity sync"
+          return
+        end
+
+        # Skip if user hasn't been synced to Zoho yet
+        unless user.metadata&.dig('zoho_lead_id').present?
+          Rails.logger.debug "[Zoho] User #{user_id} has no Zoho lead, skipping activity"
+          return
+        end
+
+        lead_sync_service.log_activity(user, activity_type, details.symbolize_keys)
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/sync_new_signup_job.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Sync a new user signup to Zoho CRM as a Lead
+    #
+    # Triggered when a user completes signup step 1 (email submission)
+    #
+    # Usage:
+    #   Pwb::Zoho::SyncNewSignupJob.perform_later(user.id, { ip: '1.2.3.4', utm_source: 'google' })
+    #
+    class SyncNewSignupJob < BaseJob
+      def perform(user_id, request_info = {})
+        return unless zoho_enabled?
+
+        user = ::Pwb::User.find_by(id: user_id)
+        unless user
+          Rails.logger.warn "[Zoho] User #{user_id} not found, skipping signup sync"
+          return
+        end
+
+        # Skip if already synced
+        if user.metadata&.dig('zoho_lead_id').present?
+          Rails.logger.info "[Zoho] User #{user_id} already has lead, skipping"
+          return
+        end
+
+        lead_sync_service.create_lead_from_signup(user, request_info: request_info.symbolize_keys)
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/sync_subscription_job.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Sync subscription changes to Zoho CRM
+    #
+    # Handles:
+    # - Plan selection/changes (update Lead)
+    # - Subscription activation (convert Lead to Customer)
+    # - Subscription cancellation (mark Lead as Lost)
+    #
+    # Usage:
+    #   Pwb::Zoho::SyncSubscriptionJob.perform_later(subscription.id, 'activated')
+    #
+    class SyncSubscriptionJob < BaseJob
+      VALID_EVENTS = %w[created plan_changed activated canceled expired].freeze
+
+      def perform(subscription_id, event)
+        return unless zoho_enabled?
+        return unless VALID_EVENTS.include?(event.to_s)
+
+        subscription = ::Pwb::Subscription.find_by(id: subscription_id)
+        unless subscription
+          Rails.logger.warn "[Zoho] Subscription #{subscription_id} not found"
+          return
+        end
+
+        website = subscription.website
+        user = website&.owner
+
+        unless user
+          Rails.logger.warn "[Zoho] No owner found for subscription #{subscription_id}"
+          return
+        end
+
+        case event.to_s
+        when 'created', 'plan_changed'
+          lead_sync_service.update_lead_plan_selected(user, subscription)
+        when 'activated'
+          lead_sync_service.convert_lead_to_customer(user, subscription)
+        when 'canceled'
+          lead_sync_service.mark_lead_lost(user, 'User Canceled')
+        when 'expired'
+          lead_sync_service.mark_lead_lost(user, 'Trial Expired')
+        end
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/sync_website_created_job.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Sync website creation to Zoho CRM (update existing Lead)
+    #
+    # Triggered when a user completes signup step 2 (website configuration)
+    #
+    # Usage:
+    #   Pwb::Zoho::SyncWebsiteCreatedJob.perform_later(user.id, website.id)
+    #
+    class SyncWebsiteCreatedJob < BaseJob
+      def perform(user_id, website_id)
+        return unless zoho_enabled?
+
+        user = ::Pwb::User.find_by(id: user_id)
+        website = ::Pwb::Website.find_by(id: website_id)
+
+        unless user && website
+          Rails.logger.warn "[Zoho] User #{user_id} or website #{website_id} not found"
+          return
+        end
+
+        # Get the plan from subscription if available
+        plan = website.subscription&.plan
+
+        lead_sync_service.update_lead_website_created(user, website, plan)
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/sync_website_live_job.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Sync website going live to Zoho CRM (update Lead status)
+    #
+    # Triggered when website provisioning completes and email is verified
+    #
+    # Usage:
+    #   Pwb::Zoho::SyncWebsiteLiveJob.perform_later(user.id, website.id)
+    #
+    class SyncWebsiteLiveJob < BaseJob
+      def perform(user_id, website_id)
+        return unless zoho_enabled?
+
+        user = ::Pwb::User.find_by(id: user_id)
+        website = ::Pwb::Website.find_by(id: website_id)
+
+        unless user && website
+          Rails.logger.warn "[Zoho] User #{user_id} or website #{website_id} not found"
+          return
+        end
+
+        lead_sync_service.update_lead_website_live(user, website)
+      end
+    end
+  end
+end

app/jobs/pwb/zoho/trial_reminder_job.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pwb
+  module Zoho
+    # Update Zoho leads when their trial is ending soon
+    #
+    # This is a scheduled job that should run daily to update leads
+    # whose trial ends in 3, 2, or 1 days.
+    #
+    # Usage (in config/schedule.rb or Solid Queue recurring):
+    #   Pwb::Zoho::TrialReminderJob.perform_later
+    #
+    class TrialReminderJob < BaseJob
+      REMINDER_DAYS = [3, 2, 1, 0].freeze
+
+      def perform
+        return unless zoho_enabled?
+
+        REMINDER_DAYS.each do |days|
+          process_trials_ending_in(days)
+        end
+      end
+
+      private
+
+      def process_trials_ending_in(days)
+        # Find subscriptions with trials ending in exactly `days` days
+        target_date = Date.current + days.days
+
+        subscriptions = ::Pwb::Subscription
+          .trialing
+          .where(trial_ends_at: target_date.beginning_of_day..target_date.end_of_day)
+          .includes(website: :owner)
+
+        Rails.logger.info "[Zoho] Found #{subscriptions.count} trials ending in #{days} days"
+
+        subscriptions.find_each do |subscription|
+          user = subscription.website&.owner
+          next unless user
+
+          lead_sync_service.update_trial_ending(user, days)
+        rescue Zoho::Error => e
+          Rails.logger.error "[Zoho] Failed to update trial reminder for subscription #{subscription.id}: #{e.message}"
+        end
+      end
+    end
+  end
+end

app/models/concerns/pwb/website_provisionable.rb

@@ -41,6 +41,7 @@ module WebsiteProvisionable
           after do
             update!(provisioning_started_at: Time.current) if provisioning_started_at.blank?
             log_provisioning_step('owner_assigned')
+            sync_website_created_to_zoho
           end
         end
 
@@ -105,14 +106,20 @@ module WebsiteProvisionable
         # Step 9: Complete registration (user created Firebase account)
         event :complete_owner_registration do
           transitions from: :locked_pending_registration, to: :live
-          after { log_provisioning_step('live') }
+          after do
+            log_provisioning_step('live')
+            sync_website_live_to_zoho
+          end
         end
 
         # Direct go_live (for admin use or special cases)
         event :go_live do
           transitions from: [:ready, :locked_pending_email_verification, :locked_pending_registration],
                       to: :live, guard: :can_go_live?
-          after { log_provisioning_step('live') }
+          after do
+            log_provisioning_step('live')
+            sync_website_live_to_zoho
+          end
         end
 
         # Failure handling
@@ -305,5 +312,25 @@ def provisioning_failed_step_progress
       return 15 if has_owner?
       0
     end
+
+    # ===================
+    # Zoho CRM Sync
+    # ===================
+
+    def sync_website_created_to_zoho
+      return unless owner
+
+      Pwb::Zoho::SyncWebsiteCreatedJob.perform_later(owner.id, id)
+    rescue StandardError => e
+      Rails.logger.error("[Zoho] Failed to queue website created sync: #{e.message}")
+    end
+
+    def sync_website_live_to_zoho
+      return unless owner
+
+      Pwb::Zoho::SyncWebsiteLiveJob.perform_later(owner.id, id)
+    rescue StandardError => e
+      Rails.logger.error("[Zoho] Failed to queue website live sync: #{e.message}")
+    end
   end
 end