feat(linear): Support refresh tokens and migrate legacy OAuth tokens (#13721)

Linear is deprecating long-lived OAuth2 access tokens (valid for 10
years) in favor of short-lived access tokens with refresh tokens.
Starting October 1, 2025, all new OAuth2 apps will default to refresh
tokens. Linear will no longer issue long-lived access tokens. Please
read more details
[here](https://linear.app/developers/oauth-2-0-authentication#migrate-to-using-refresh-tokens)
We currently use long-lived tokens in our Linear integration (valid for
up to 10 years). To remain compatible, this PR ensures compatibility by
supporting refresh-token-based auth and migrating existing legacy
tokens.

Fixes
https://linear.app/chatwoot/issue/CW-5541/migrate-linear-oauth2-integration-to-support-refresh-tokens

spec/controllers/linear/callbacks_controller_spec.rb

@@ -9,9 +9,11 @@ RSpec.describe Linear::CallbacksController, type: :request do
 
   describe 'GET /linear/callback' do
     let(:access_token) { SecureRandom.hex(10) }
+    let(:refresh_token) { SecureRandom.hex(10) }
     let(:response_body) do
       {
         'access_token' => access_token,
+        'refresh_token' => refresh_token,
         'token_type' => 'Bearer',
         'expires_in' => 7200,
         'scope' => 'read,write'
@@ -35,7 +37,7 @@ RSpec.describe Linear::CallbacksController, type: :request do
           )
       end
 
-      it 'creates a new integration hook' do
+      it 'creates a new integration hook', :aggregate_failures do
         expect do
           get linear_callback_path, params: { code: code, state: state }
         end.to change(Integrations::Hook, :count).by(1)
@@ -44,11 +46,11 @@ RSpec.describe Linear::CallbacksController, type: :request do
         expect(hook.access_token).to eq(access_token)
         expect(hook.app_id).to eq('linear')
         expect(hook.status).to eq('enabled')
-        expect(hook.settings).to eq(
-          'token_type' => 'Bearer',
-          'expires_in' => 7200,
-          'scope' => 'read,write'
-        )
+        expect(hook.settings['token_type']).to eq('Bearer')
+        expect(hook.settings['expires_in']).to eq(7200)
+        expect(hook.settings['scope']).to eq('read,write')
+        expect(hook.settings['refresh_token']).to eq(refresh_token)
+        expect(hook.settings['expires_on']).to be_present
         expect(response).to redirect_to(linear_redirect_uri)
       end
     end
@@ -69,6 +71,106 @@ RSpec.describe Linear::CallbacksController, type: :request do
       end
     end
 
+    context 'when state is missing' do
+      it 'redirects to frontend root' do
+        get linear_callback_path, params: { code: code }
+        expect(response).to redirect_to('http://www.example.com')
+      end
+    end
+
+    context 'when state is invalid' do
+      it 'redirects to frontend root' do
+        get linear_callback_path, params: { code: code, state: 'invalid-state' }
+        expect(response).to redirect_to('http://www.example.com')
+      end
+    end
+
+    context 'when hook exists and response omits refresh_token' do
+      let!(:existing_hook) do
+        create(
+          :integrations_hook,
+          :linear,
+          account: account,
+          settings: {
+            'refresh_token' => 'existing_refresh_token',
+            'token_type' => 'Bearer',
+            'scope' => 'read,write',
+            'expires_on' => 1.day.from_now.utc.to_s
+          }
+        )
+      end
+      let(:response_body) do
+        {
+          'access_token' => access_token,
+          'token_type' => 'Bearer',
+          'expires_in' => 7200,
+          'scope' => 'read,write'
+        }
+      end
+
+      before do
+        stub_request(:post, 'https://api.linear.app/oauth/token')
+          .to_return(
+            status: 200,
+            body: response_body.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'preserves existing refresh token', :aggregate_failures do
+        get linear_callback_path, params: { code: code, state: state }
+
+        existing_hook.reload
+        expect(existing_hook.access_token).to eq(access_token)
+        expect(existing_hook.settings['refresh_token']).to eq('existing_refresh_token')
+      end
+    end
+
+    context 'when hook exists and response omits access_token' do
+      let!(:existing_hook) do
+        create(
+          :integrations_hook,
+          :linear,
+          account: account,
+          access_token: 'existing_access_token',
+          settings: {
+            'refresh_token' => 'existing_refresh_token',
+            'token_type' => 'Bearer',
+            'scope' => 'read,write',
+            'expires_on' => 1.day.from_now.utc.to_s
+          }
+        )
+      end
+      let(:response_body) do
+        {
+          'refresh_token' => refresh_token,
+          'token_type' => 'Bearer',
+          'expires_in' => 7200,
+          'scope' => 'read,write'
+        }
+      end
+
+      before do
+        stub_request(:post, 'https://api.linear.app/oauth/token')
+          .to_return(
+            status: 200,
+            body: response_body.to_json,
+            headers: { 'Content-Type' => 'application/json' }
+          )
+      end
+
+      it 'does not overwrite the existing hook', :aggregate_failures do
+        expect do
+          get linear_callback_path, params: { code: code, state: state }
+        end.not_to change(Integrations::Hook, :count)
+
+        existing_hook.reload
+        expect(existing_hook.access_token).to eq('existing_access_token')
+        expect(existing_hook.settings['refresh_token']).to eq('existing_refresh_token')
+        expect(response).to redirect_to(linear_redirect_uri)
+      end
+    end
+
     context 'when the token is invalid' do
       before do
         stub_request(:post, 'https://api.linear.app/oauth/token')