feat(api): add product_catalog gating concerns

## Context

The product_catalog flag needs guards so that, per organization, the new
catalog API is reachable only when enabled and the legacy pricing API is
blocked once enabled. The same rule applies to REST and GraphQL.

## Description

Add four concerns built on organization.product_catalog_enabled?:
Api::RequiresProductCatalog and RequiresProductCatalog forbid the new
catalog endpoints/mutations unless the flag is on; Api::ForbidsLegacyBilling
and ForbidsLegacyBilling block legacy pricing writes (create/update/destroy
only, reads stay open) once the flag is on. REST uses a before_action,
GraphQL the ready? hook, both returning forbidden_error with distinct codes
(feature_unavailable / legacy_billing_disabled). Wiring into controllers and
mutations comes next.

Author: rsempe

app/controllers/concerns/api/forbids_legacy_billing.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Blocks writes to legacy pricing REST endpoints once an organization is on
+# the product catalog. Reads stay open so already-billed data remains
+# accessible during and after migration.
+module Api
+  module ForbidsLegacyBilling
+    extend ActiveSupport::Concern
+
+    included do
+      # The write actions live on the host controllers, not this concern.
+      before_action :forbid_legacy_billing!, only: %i[create update destroy] # rubocop:disable Rails/LexicallyScopedActionFilter
+    end
+
+    private
+
+    def forbid_legacy_billing!
+      forbidden_error(code: "legacy_billing_disabled") if current_organization&.product_catalog_enabled?
+    end
+  end
+end

app/controllers/concerns/api/requires_product_catalog.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Guards new product-catalog (v2) REST endpoints: only organizations with the
+# product_catalog premium integration may use them.
+module Api
+  module RequiresProductCatalog
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :ensure_product_catalog!
+    end
+
+    private
+
+    def ensure_product_catalog!
+      forbidden_error(code: "feature_unavailable") unless current_organization&.product_catalog_enabled?
+    end
+  end
+end

app/graphql/concerns/forbids_legacy_billing.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Blocks legacy pricing GraphQL mutations once an organization is on the
+# product catalog.
+module ForbidsLegacyBilling
+  def ready?(**args)
+    raise forbidden_error(code: "legacy_billing_disabled") if current_organization&.product_catalog_enabled?
+
+    super
+  end
+end

app/graphql/concerns/requires_product_catalog.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Guards new product-catalog (v2) GraphQL mutations/resolvers: only
+# organizations with the product_catalog premium integration may use them.
+module RequiresProductCatalog
+  def ready?(**args)
+    raise forbidden_error(code: "feature_unavailable") unless current_organization&.product_catalog_enabled?
+
+    super
+  end
+end

spec/controllers/concerns/api/forbids_legacy_billing_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Api::ForbidsLegacyBilling do
+  include ApiHelper
+
+  # rubocop:disable RSpec/DescribedClass
+  controller(ApplicationController) do
+    include ApiErrors
+    include Api::ForbidsLegacyBilling
+
+    attr_reader :current_organization
+
+    def create
+      render json: {ok: true}
+    end
+
+    def update
+      render json: {ok: true}
+    end
+
+    def destroy
+      render json: {ok: true}
+    end
+
+    def index
+      render json: {ok: true}
+    end
+  end
+  # rubocop:enable RSpec/DescribedClass
+
+  let(:organization) { create(:organization, premium_integrations:) }
+  let(:premium_integrations) { [] }
+
+  before { allow(controller).to receive(:current_organization).and_return(organization) }
+
+  context "when the organization is on the product catalog", :premium do
+    let(:premium_integrations) { ["product_catalog"] }
+
+    it "blocks writes" do
+      post :create
+
+      expect(response).to have_http_status(:forbidden)
+      expect(json[:code]).to eq("legacy_billing_disabled")
+    end
+
+    it "still allows reads" do
+      get :index
+
+      expect(response).to have_http_status(:success)
+    end
+  end
+
+  context "when the organization is not on the product catalog" do
+    it "allows writes" do
+      post :create
+
+      expect(response).to have_http_status(:success)
+    end
+  end
+end

spec/controllers/concerns/api/requires_product_catalog_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Api::RequiresProductCatalog do
+  include ApiHelper
+
+  # rubocop:disable RSpec/DescribedClass
+  controller(ApplicationController) do
+    include ApiErrors
+    include Api::RequiresProductCatalog
+
+    attr_reader :current_organization
+
+    def index
+      render json: {ok: true}
+    end
+  end
+  # rubocop:enable RSpec/DescribedClass
+
+  let(:organization) { create(:organization, premium_integrations:) }
+  let(:premium_integrations) { [] }
+
+  before { allow(controller).to receive(:current_organization).and_return(organization) }
+
+  context "when the organization is not on the product catalog" do
+    it "returns a forbidden error" do
+      get :index
+
+      expect(response).to have_http_status(:forbidden)
+      expect(json[:code]).to eq("feature_unavailable")
+    end
+  end
+
+  context "when the organization is on the product catalog", :premium do
+    let(:premium_integrations) { ["product_catalog"] }
+
+    it "allows the request" do
+      get :index
+
+      expect(response).to have_http_status(:success)
+      expect(json[:ok]).to be(true)
+    end
+  end
+end

spec/graphql/concerns/forbids_legacy_billing_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+module ForbidsLegacyBillingSpec
+  class ThingType < Types::BaseObject
+    field :ok, Boolean, null: false
+  end
+
+  class GuardedMutation < Mutations::BaseMutation
+    include ForbidsLegacyBilling
+
+    graphql_name "ForbiddenWhenProductCatalog"
+    type ThingType
+
+    def current_organization
+      context[:current_organization]
+    end
+
+    def resolve(**args)
+      {ok: true}
+    end
+  end
+
+  class MutationType < Types::BaseObject
+    field :legacy, mutation: GuardedMutation
+  end
+
+  class TestSchema < LagoApiSchema
+    mutation(MutationType)
+  end
+end
+
+RSpec.describe ForbidsLegacyBilling do
+  subject(:result) do
+    ForbidsLegacyBillingSpec::TestSchema.execute(
+      "mutation { legacy(input: {}) { ok } }",
+      context: {current_organization: organization}
+    )
+  end
+
+  let(:organization) { create(:organization, premium_integrations:) }
+  let(:premium_integrations) { [] }
+
+  context "when the organization is on the product catalog", :premium do
+    let(:premium_integrations) { ["product_catalog"] }
+
+    it "blocks the legacy mutation" do
+      expect(result["errors"].first["extensions"]["code"]).to eq("legacy_billing_disabled")
+    end
+  end
+
+  context "when the organization is not on the product catalog" do
+    it "allows the legacy mutation" do
+      expect(result["data"]["legacy"]["ok"]).to be(true)
+    end
+  end
+end

spec/graphql/concerns/requires_product_catalog_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+module RequiresProductCatalogSpec
+  class ThingType < Types::BaseObject
+    field :ok, Boolean, null: false
+  end
+
+  class GuardedMutation < Mutations::BaseMutation
+    include RequiresProductCatalog
+
+    graphql_name "GuardedByProductCatalog"
+    type ThingType
+
+    def current_organization
+      context[:current_organization]
+    end
+
+    def resolve(**args)
+      {ok: true}
+    end
+  end
+
+  class MutationType < Types::BaseObject
+    field :guarded, mutation: GuardedMutation
+  end
+
+  class TestSchema < LagoApiSchema
+    mutation(MutationType)
+  end
+end
+
+RSpec.describe RequiresProductCatalog do
+  subject(:result) do
+    RequiresProductCatalogSpec::TestSchema.execute(
+      "mutation { guarded(input: {}) { ok } }",
+      context: {current_organization: organization}
+    )
+  end
+
+  let(:organization) { create(:organization, premium_integrations:) }
+  let(:premium_integrations) { [] }
+
+  context "when the organization is not on the product catalog" do
+    it "returns a forbidden error" do
+      expect(result["errors"].first["extensions"]["code"]).to eq("feature_unavailable")
+    end
+  end
+
+  context "when the organization is on the product catalog", :premium do
+    let(:premium_integrations) { ["product_catalog"] }
+
+    it "allows the mutation" do
+      expect(result["data"]["guarded"]["ok"]).to be(true)
+    end
+  end
+end