has_helpers 5.0.2

data/spec/factories/users.rb

@@ -0,0 +1,55 @@
+FactoryBot.define do
+  factory :user do
+    user_organizations                              { [FactoryBot.build(:user_organization, user: @instance)]}
+    username                                        { User.maximum(:username) ? "#{User.maximum(:username).split("@")[0].try(:next)}@#{@instance.user_organizations.first.organization.domain}" : "aaa@#{@instance.user_organizations.first.organization.domain}" }
+    name                                            { Faker::Name.name }
+    created_at                                      { FactoryMacros::generate_created_at(@overrides) }
+    updated_at                                      { FactoryMacros::generate_updated_at(created_at) }
+    last_name                                       { Faker::Name.last_name }
+    linked_advisor                                  { nil }
+
+    trait :with_org do
+      transient do
+        organization { nil }
+      end
+      after :create do | user, evaluator |
+        org = evaluator.organization ||  FactoryBot.create(:organization)
+      end
+    end
+
+    trait :with_linked_advisor do
+      transient do
+        organization { nil }
+      end
+      before :create do | user, evaluator |
+        org = evaluator.organization ||  FactoryBot.create(:organization)
+        user.linked_advisor = ::FactoryBot.create(:advisor, organization: org)
+        user.save
+      end
+    end
+
+    trait :name_with_apostrophe do
+      name                    { "#{Faker::Name.first_name}'#{Faker::Name.last_name}" }
+    end
+  end
+
+  factory :has_helper_user, class: ::HasHelpers::User do
+    user_organizations                              { [FactoryBot.build(:has_helper_user_organization, user: @instance)]}
+    username                                        { HasHelpers::User.maximum(:username) ? "#{HasHelpers::User.maximum(:username).split("@")[0].try(:next)}@#{@instance.user_organizations.first.organization.domain}" : "aaa@#{@instance.user_organizations.first.organization.domain}" }
+    name                                            { Faker::Name.name }
+    created_at                                      { FactoryMacros::generate_created_at(@overrides) }
+    updated_at                                      { FactoryMacros::generate_updated_at(created_at) }
+    last_name                                       { Faker::Name.last_name }
+
+    transient do
+      organization { nil }
+    end
+
+    after :build do | user, evaluator |
+      if evaluator.organization
+        user.user_organizations.each(&:mark_for_destruction)
+        user.user_organizations.build(is_primary: true, organization: evaluator.organization)
+      end
+    end
+  end
+end

data/spec/fixtures/sample_config.yml

@@ -0,0 +1,3 @@
+test:
+  foo: bar
+  age: 32

data/spec/graphql/has_helpers/mutations/external_data_sync_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe HasHelpers::Mutations::ExternalDataSync, type: :mutation do
+  subject(:mutation) { described_class.new(object: nil, context: {}, field: nil) }
+
+  let(:resource) { "User" }
+  let(:data_id)  { SecureRandom.uuid }
+  let(:data)     { { "id" => data_id } }
+
+  describe ".fields" do
+    it "exposes a nullable error field" do
+      error_field = described_class.fields["error"]
+
+      expect(error_field).not_to be_nil
+      expect(error_field.type.to_type_signature).to eq("String")
+    end
+  end
+
+  describe "#resolve" do
+    before do
+      allow(HasHelpers::SyncUtils).to receive(:dependencies_satisfied?).and_return(true)
+    end
+
+    it "returns ok when mapping succeeds" do
+      allow(HasHelpers::SyncUtils).to receive(:apply_mapping).and_return(true)
+      allow(HasHelpers::SyncUtils).to receive(:touch_dependencies!)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: [])
+
+      expect(result).to eq({ status: "ok", error: nil })
+      expect(HasHelpers::SyncUtils).to have_received(:touch_dependencies!).with(data, [])
+    end
+
+    it "returns retry with nil error when dependencies are missing" do
+      allow(HasHelpers::SyncUtils).to receive(:dependencies_satisfied?).and_return(false)
+      allow(HasHelpers::SyncUtils).to receive(:touch_dependencies!)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: ["organization"])
+
+      expect(result).to eq({ status: "retry", error: nil })
+      expect(HasHelpers::SyncUtils).not_to have_received(:touch_dependencies!)
+    end
+
+    it "returns fail with the mapping error when apply_mapping returns a String" do
+      allow(HasHelpers::SyncUtils).to receive(:apply_mapping).and_return("Validation failed: Username can't be blank")
+      allow(HasHelpers::SyncUtils).to receive(:touch_dependencies!)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: [])
+
+      expect(result).to eq({ status: "fail", error: "Validation failed: Username can't be blank" })
+      expect(HasHelpers::SyncUtils).not_to have_received(:touch_dependencies!)
+    end
+
+    it "returns fail with contextual message when apply_mapping returns nil" do
+      allow(HasHelpers::SyncUtils).to receive(:apply_mapping).and_return(nil)
+      allow(HasHelpers::SyncUtils).to receive(:touch_dependencies!)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: [])
+
+      expect(result[:status]).to eq("fail")
+      expect(result[:error]).to include("User")
+      expect(result[:error]).to include(data_id)
+      expect(HasHelpers::SyncUtils).not_to have_received(:touch_dependencies!)
+    end
+
+    it "returns fail with contextual message when apply_mapping returns false" do
+      allow(HasHelpers::SyncUtils).to receive(:apply_mapping).and_return(false)
+      allow(HasHelpers::SyncUtils).to receive(:touch_dependencies!)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: [])
+
+      expect(result[:status]).to eq("fail")
+      expect(result[:error]).to include("User")
+      expect(result[:error]).to include(data_id)
+      expect(HasHelpers::SyncUtils).not_to have_received(:touch_dependencies!)
+    end
+
+    it "returns fail with destroy error when is_destroyed is true and destroy fails" do
+      FactoryBot.create(:user, id: data_id)
+      destroy_errors = instance_double(ActiveModel::Errors, full_messages: ["Cannot delete while linked records exist"])
+
+      allow_any_instance_of(User).to receive(:destroy).and_return(false)
+      allow_any_instance_of(User).to receive(:errors).and_return(destroy_errors)
+
+      result = mutation.resolve(resource: resource, data: data, is_destroyed: true, dependencies: [])
+
+      expect(result[:status]).to eq("fail")
+      expect(result[:error]).to include("Cannot delete while linked records exist")
+    end
+
+    it "raises GraphQL::ExecutionError with resource context on unhandled exceptions" do
+      allow(HasHelpers::SyncUtils).to receive(:apply_mapping).and_raise(StandardError, "boom")
+
+      expect do
+        mutation.resolve(resource: resource, data: data, is_destroyed: false, dependencies: [])
+      end.to raise_error(GraphQL::ExecutionError, "ExternalDataSync failed for User: boom")
+    end
+  end
+end

data/spec/graphql/has_helpers/resolvers/cards/available_cards_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe HasHelpers::Resolvers::Cards::AvailableCards do
+  subject(:resolver) { described_class.allocate }
+
+  let(:application) { double("Application", id: 1, name: "AgenciesHQ") }
+  let(:resource)    { double("Resource", id: "resource-id") }
+  let(:command_result) do
+    [{ id: 1, name: "Demographics", description: "Basic details", identifier: "id", layout: :summary, variant: nil, position: 10, icon_name: "user", icon_color: "blue" }]
+  end
+
+  before do
+    allow(resolver).to receive(:context).and_return(current_application: application)
+    allow(HasHelpers::Resource).to receive(:find_by!).and_return(resource)
+    allow(HasHelpers::Cards::AvailableCardsCommand).to receive(:call).and_return(command_result)
+  end
+
+  it "looks up the resource for the current application and delegates to the command" do
+    expect(HasHelpers::Resource).to receive(:find_by!).with(
+      name: "Advisor",
+      application_id: application.id,
+      parent_id: nil
+    ).and_return(resource)
+    expect(HasHelpers::Cards::AvailableCardsCommand).to receive(:call).with(resource_id: resource).and_return(command_result)
+
+    expect(resolver.resolve(resource_name: "Advisor")).to eq(command_result)
+  end
+
+  it "raises when current_application is missing from context" do
+    allow(resolver).to receive(:context).and_return({})
+
+    expect { resolver.resolve(resource_name: "Advisor") }.to raise_error(GraphQL::ExecutionError)
+  end
+end

data/spec/graphql/has_helpers/resolvers/cards/card_data_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe HasHelpers::Resolvers::Cards::CardData do
+  subject(:resolver) { described_class.allocate }
+
+  let(:application) { double("Application", id: 1, name: "AgenciesHQ") }
+  let(:resource) { double("Resource", id: "resource-id", klass: record_class) }
+  let(:record_class) { double("RecordClass") }
+  let(:record) { double("Record", id: "record-id") }
+  let(:identifier) { double("Identifier") }
+  let(:card_definition) { double("CardDefinition", identifier: identifier) }
+  let(:command_result) { double("CommandResult", card: {}, fields: [], entries: []) }
+
+  before do
+    allow(resolver).to receive(:context).and_return(current_application: application)
+    allow(HasHelpers::Resource).to receive(:find_by!).and_return(resource)
+    allow(resource).to receive(:klass).and_return(record_class)
+    allow(record_class).to receive(:find).and_return(record)
+    allow(HasHelpers::Cards::CardDataCommand).to receive(:call_with_record).and_return(command_result)
+  end
+
+  # Hover-only cards are no longer persisted (they're assembled in-memory from
+  # the registry by the HoverCardData resolver), so the DB query no longer needs
+  # to filter them out.
+  it "queries the DB without any is_hover_only filter" do
+    relation = double("CardDefinitionRelation")
+
+    allow(HasHelpers::Cards::CardDefinition).to receive(:joins).with(:card_definition_resources).and_return(relation)
+    allow(relation).to receive(:where).with(card_definition_resources: { resource_id: resource.id }).and_return(relation)
+    allow(relation).to receive(:ordered).and_return(relation)
+    allow(relation).to receive(:includes).and_return(relation)
+    allow(relation).to receive(:distinct).and_return([card_definition])
+
+    expect(relation).not_to receive(:where).with(hash_including(:is_hover_only))
+
+    result = resolver.resolve(role_id: "role-id", resource_name: "Advisor", record_id: "record-id")
+
+    expect(result).to eq([{ application: "AgenciesHQ", card: {}, fields: [], entries: [] }])
+  end
+end

data/spec/graphql/has_helpers/resolvers/cards/hover_card_data_spec.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe HasHelpers::Resolvers::Cards::HoverCardData do
+  subject(:resolver) { described_class.allocate }
+
+  let(:application) { double("Application", id: 1, name: "AgenciesHQ") }
+  let(:resource) { double("Resource", id: "resource-id", klass: record_class) }
+  let(:record_class) { double("RecordClass") }
+  let(:record) { double("Record", id: "record-id") }
+  let(:command_result) do
+    double("CommandResult", card: { id: "card-id" }, fields: [], entries: [])
+  end
+
+  let(:hover_only_registry_card) do
+    {
+      identifier: "AdvisorHover",
+      hover_only: true,
+      name: "Advisor Hover",
+      layout: :summary,
+      description: "Advisor Hover",
+      default_position: 10,
+      fields: []
+    }
+  end
+
+  before do
+    allow(resolver).to receive(:context).and_return(current_application: application)
+    allow(HasHelpers::Resource).to receive(:find_by!).and_return(resource)
+    allow(resource).to receive(:klass).and_return(record_class)
+    allow(record_class).to receive(:find).and_return(record)
+  end
+
+  it "assembles the in-memory definition and returns card data for a hover-only identifier" do
+    allow(HasHelpers::Cards::Registry).to receive(:cards).and_return([hover_only_registry_card])
+    allow(HasHelpers::Cards::CardDataCommand).to receive(:call_with_definition).and_return(command_result)
+
+    result = resolver.resolve(role_id: "role-id", resource_name: "Advisor", record_id: "record-id", identifier: "AdvisorHover")
+
+    expect(result).to eq(
+      application: "AgenciesHQ",
+      card: { id: "card-id" },
+      fields: [],
+      entries: []
+    )
+  end
+
+  it "returns nil when the registry has no matching hover-only card" do
+    not_hover_only = hover_only_registry_card.merge(hover_only: false)
+    allow(HasHelpers::Cards::Registry).to receive(:cards).and_return([not_hover_only])
+
+    expect(HasHelpers::Cards::CardDataCommand).not_to receive(:call_with_definition)
+
+    result = resolver.resolve(role_id: "role-id", resource_name: "Advisor", record_id: "record-id", identifier: "AdvisorHover")
+
+    expect(result).to be_nil
+  end
+end

data/spec/has_helpers/cards/cache_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require_relative "support"
+
+RSpec.describe HasHelpers::Cards::Cache do
+  let(:redis) { CardsMemoryRedis.new }
+  let(:cache) { described_class.new(redis: redis) }
+
+  it "stores fresh and stale values on cache miss" do
+    result = cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+
+    expect(result).to eq("id" => "1")
+    expect(redis.get("hh:cards:v1:role:1")).to eq({ "id" => "1" }.to_json)
+    expect(redis.get("hh:cards:v1:role:1:stale")).to eq({ "id" => "1" }.to_json)
+  end
+
+  it "returns fresh cache hits without invoking the block" do
+    cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+
+    expect(cache.fetch("role:1", ttl: 60, stale_grace: 300) { raise "no" }).to eq("id" => "1")
+  end
+
+  it "force refresh skips the fresh read" do
+    cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+
+    expect(cache.fetch("role:1", ttl: 60, stale_grace: 300, force: true) { { "id" => "2" } }).to eq("id" => "2")
+  end
+
+  it "returns stale when refresh raises" do
+    cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+    redis.values.delete("hh:cards:v1:role:1")
+
+    expect(Rails.logger).to receive(:warn).with(/returning stale value/)
+    expect(cache.fetch("role:1", ttl: 60, stale_grace: 300) { raise "network" }).to eq("id" => "1")
+  end
+
+  it "re-raises refresh errors when no stale value is present" do
+    expect do
+      cache.fetch("role:1", ttl: 60, stale_grace: 300) { raise ArgumentError, "boom" }
+    end.to raise_error(ArgumentError, "boom")
+  end
+
+  it "stores expected TTLs" do
+    cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+
+    expect(redis.ttl("hh:cards:v1:role:1")).to eq(60)
+    expect(redis.ttl("hh:cards:v1:role:1:stale")).to eq(360)
+  end
+
+  it "keeps different keys isolated" do
+    cache.fetch("role:1", ttl: 60, stale_grace: 300) { { "id" => "1" } }
+    cache.fetch("role:2", ttl: 60, stale_grace: 300) { { "id" => "2" } }
+
+    expect(cache.fetch("role:1", ttl: 60, stale_grace: 300) { nil }).to eq("id" => "1")
+    expect(cache.fetch("role:2", ttl: 60, stale_grace: 300) { nil }).to eq("id" => "2")
+  end
+end

data/spec/has_helpers/cards/config_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require_relative "support"
+
+RSpec.describe HasHelpers::Cards do
+  after { clear_cards! }
+
+  it "raises before configuration" do
+    described_class.reset!
+
+    expect { described_class.config }.to raise_error(HasHelpers::Cards::ConfigurationError, /configure/)
+  end
+
+  it "requires mode" do
+    expect do
+      described_class.configure { |config| config.issuer = "app" }
+    end.to raise_error(HasHelpers::Cards::ConfigurationError, "mode is required")
+  end
+
+  it "rejects unknown modes" do
+    expect do
+      described_class.configure do |config|
+        config.mode = :bogus
+        config.issuer = "app"
+      end
+    end.to raise_error(HasHelpers::Cards::ConfigurationError, "mode must be :server or :client")
+  end
+
+  it "requires audience in client mode" do
+    expect do
+      described_class.configure do |config|
+        config.mode = :client
+        config.issuer = "app"
+        config.base_url = "http://localhost:3000"
+        config.redis = CardsMemoryRedis.new
+      end
+    end.to raise_error(HasHelpers::Cards::ConfigurationError, "audience is required")
+  end
+
+  it "requires redis in client mode" do
+    expect do
+      described_class.configure do |config|
+        config.mode = :client
+        config.issuer = "app"
+        config.audience = "admin"
+        config.base_url = "http://localhost:3000"
+      end
+    end.to raise_error(HasHelpers::Cards::ConfigurationError, "redis is required")
+  end
+
+  it "allows server mode with mode and issuer" do
+    described_class.configure do |config|
+      config.mode = :server
+      config.issuer = "admin"
+    end
+
+    expect(described_class.config.mode).to eq(:server)
+    expect(described_class.config.path).to eq("/internal_graphql")
+  end
+
+  it "reset returns to unconfigured state" do
+    configure_cards
+    described_class.reset!
+
+    expect { described_class.config }.to raise_error(HasHelpers::Cards::ConfigurationError)
+  end
+end

data/spec/has_helpers/cards/orphan_card_sweeper_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require_relative "support"
+
+RSpec.describe HasHelpers::Cards::OrphanCardSweeper do
+  let(:organization) { FactoryBot.create(:has_helper_organization) }
+  let(:resource) { FactoryBot.create(:resource) }
+  let(:card_definition) { FactoryBot.create(:cards_card_definition) }
+  let(:role) { FactoryBot.create(:role, organization: organization) }
+
+  before do
+    HasHelpers::Cards::RoleCardField.delete_all
+    HasHelpers::Cards::RoleResourceCard.delete_all
+    clear_cards!
+  end
+
+  after { clear_cards! }
+
+  it "no-ops in server mode" do
+    configure_cards(mode: :server)
+    card = create_card(role_id: role.id)
+
+    described_class.perform_now
+
+    expect(card.reload.disabled_at).to be_nil
+  end
+
+  it "leaves cards with valid role ids untouched in client mode" do
+    configure_cards(mode: :client)
+    card = create_card(role_id: role.id)
+    allow(HasHelpers::Cards::Roles).to receive(:all).with(force: true).and_return([HasHelpers::Cards::RemoteRole.new(id: role.id)])
+
+    described_class.perform_now
+
+    expect(card.reload.disabled_at).to be_nil
+  end
+
+  it "soft-disables stale role cards in client mode" do
+    configure_cards(mode: :client)
+    other_role = FactoryBot.create(:role, organization: organization)
+    card = create_card(role_id: role.id)
+    allow(HasHelpers::Cards::Roles).to receive(:all).with(force: true)
+      .and_return([HasHelpers::Cards::RemoteRole.new(id: other_role.id)])
+
+    described_class.perform_now
+
+    expect(card.reload.disabled_at).to be_within(2.seconds).of(Time.current)
+  end
+
+  it "does not re-touch already disabled cards" do
+    configure_cards(mode: :client)
+    other_role = FactoryBot.create(:role, organization: organization)
+    disabled = create_card(role_id: role.id, disabled_at: 1.day.ago)
+    updated_at = disabled.updated_at
+    allow(HasHelpers::Cards::Roles).to receive(:all).with(force: true)
+      .and_return([HasHelpers::Cards::RemoteRole.new(id: other_role.id)])
+
+    described_class.perform_now
+
+    expect(disabled.reload.updated_at.to_i).to eq(updated_at.to_i)
+  end
+
+  it "force-refreshes roles" do
+    configure_cards(mode: :client)
+    other_role = FactoryBot.create(:role, organization: organization)
+    allow(HasHelpers::Cards::Roles).to receive(:all).with(force: true)
+      .and_return([HasHelpers::Cards::RemoteRole.new(id: other_role.id)])
+
+    described_class.perform_now
+
+    expect(HasHelpers::Cards::Roles).to have_received(:all).with(force: true)
+  end
+
+  it "bails out and warns when upstream returns no roles" do
+    configure_cards(mode: :client)
+    card = create_card(role_id: role.id)
+    allow(HasHelpers::Cards::Roles).to receive(:all).with(force: true).and_return([])
+    allow(Rails.logger).to receive(:warn)
+
+    described_class.perform_now
+
+    expect(card.reload.disabled_at).to be_nil
+    expect(Rails.logger).to have_received(:warn).with(/upstream returned no roles/)
+  end
+
+  def create_card(role_id:, disabled_at: nil)
+    FactoryBot.create(
+      :cards_role_resource_card,
+      organization: organization,
+      role_id: role_id,
+      resource_id: resource.id,
+      card_definition_id: card_definition.id,
+      disabled_at: disabled_at
+    )
+  end
+end

data/spec/has_helpers/cards/remote_role_spec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe HasHelpers::Cards::RemoteRole do
+  it "is a persisted read model keyed by id" do
+    role = described_class.new(id: "1", name: "Advisor", organization_id: 10)
+    same = described_class.new(id: "1", name: "Other", organization_id: 20)
+    other = described_class.new(id: "2", name: "Advisor", organization_id: 10)
+
+    expect(role).to be_persisted
+    expect(role).to eq(same)
+    expect(role).not_to eq(other)
+    expect([role, same].uniq).to eq([role])
+    expect(role.to_h).to eq(id: "1", name: "Advisor", organization_id: 10)
+  end
+end

data/spec/has_helpers/cards/remote_roles_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require_relative "support"
+
+RSpec.describe HasHelpers::Cards::RemoteRoles do
+  let(:redis) { CardsMemoryRedis.new }
+  let(:client) { instance_double(HasHelpers::ServiceTrust::GraphQLClient) }
+  let(:roles) { described_class.new(config: HasHelpers::Cards.config, client: client) }
+
+  before { configure_cards(mode: :client, redis: redis) }
+
+  after { clear_cards! }
+
+  it "finds a remote role" do
+    allow(client).to receive(:query).and_return(gql_result({ "role" => role_payload("1") }))
+
+    role = roles.find("1")
+
+    expect(role).to eq(HasHelpers::Cards::RemoteRole.new(id: "1", name: "Role 1", organization_id: 10))
+    expect(client).to have_received(:query).with(described_class::GET_ROLE, variables: { id: "1" }, capability: "roles:read")
+  end
+
+  it "uses cache for repeated find calls" do
+    allow(client).to receive(:query).and_return(gql_result({ "role" => role_payload("1") }))
+
+    2.times { roles.find("1") }
+
+    expect(client).to have_received(:query).once
+  end
+
+  it "force refreshes a find call" do
+    allow(client).to receive(:query).and_return(gql_result({ "role" => role_payload("1") }), gql_result({ "role" => role_payload("1", name: "New") }))
+
+    roles.find("1")
+    expect(roles.find("1", force: true).name).to eq("New")
+    expect(client).to have_received(:query).twice
+  end
+
+  it "raises not found when role is nil" do
+    allow(client).to receive(:query).and_return(gql_result({ "role" => nil }))
+
+    expect { roles.find("missing") }.to raise_error(HasHelpers::Cards::NotFoundError, "missing")
+  end
+
+  it "re-raises network errors without stale and falls back with stale" do
+    allow(client).to receive(:query).and_return(gql_result({ "role" => role_payload("1") }))
+    roles.find("1")
+    redis.values.delete("hh:cards:v1:role:1")
+    allow(client).to receive(:query).and_raise(HasHelpers::ServiceTrust::JwksUnavailableError, "down")
+    allow(Rails.logger).to receive(:warn)
+
+    expect(roles.find("1").id).to eq("1")
+    redis.values.delete("hh:cards:v1:role:1:stale")
+    expect { roles.find("1", force: true) }.to raise_error(HasHelpers::ServiceTrust::JwksUnavailableError)
+  end
+
+  it "returns all roles" do
+    allow(client).to receive(:query).and_return(gql_result({ "roles" => [role_payload("1"), role_payload("2")] }))
+
+    expect(roles.all.map(&:id)).to eq(%w[1 2])
+  end
+
+  it "filters roles by ids" do
+    allow(client).to receive(:query).and_return(gql_result({ "roles" => [role_payload("1"), role_payload("2")] }))
+
+    expect(roles.where(ids: ["2"]).map(&:id)).to eq(["2"])
+  end
+
+  it "passes organization_id to the GraphQL query and isolates the cache per org" do
+    allow(client).to receive(:query).and_return(
+      gql_result({ "roles" => [role_payload("1")] }),
+      gql_result({ "roles" => [role_payload("2")] })
+    )
+
+    org1 = roles.all(organization_id: 10)
+    org2 = roles.all(organization_id: 20)
+    roles.all(organization_id: 10)
+
+    expect(org1.map(&:id)).to eq(["1"])
+    expect(org2.map(&:id)).to eq(["2"])
+    expect(client).to have_received(:query).with(
+      described_class::LIST_ROLES, variables: { organizationId: 10 }, capability: "roles:read"
+    ).once
+    expect(client).to have_received(:query).with(
+      described_class::LIST_ROLES, variables: { organizationId: 20 }, capability: "roles:read"
+    ).once
+  end
+
+  def gql_result(data, errors: [])
+    HasHelpers::ServiceTrust::GraphQLClient::Result.new(data: data, errors: errors)
+  end
+
+  def role_payload(id, name: "Role #{id}")
+    { "id" => id, "name" => name, "organizationId" => 10 }
+  end
+end