rails_audit_log-graphql 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ca2df96cd0a69c6449fc8585832293c9a06d487a7525f40c1d15762c61710b5
-  data.tar.gz: 8262257281bef88c4ab07700ec88b5755ca6b2a095fd879bf5462d403ec1ac00
+  metadata.gz: 681be68e65f4b6f543de2ce47434d6b547db12299d15c2f136d94f1db5b15355
+  data.tar.gz: 184994ef369aea31293293d01e22663bb1e3dc48f3e958aec6f523997ec9ed7b
 SHA512:
-  metadata.gz: 4598525fe46095cbd1209e9bc3af297950526eb9c7ecfab9e382ee3554f376e73b0db3073986d49cdd05190e42f90e1d09e3f1a00c3ecb948a0f02d04f5ba9f0
-  data.tar.gz: 2069e44509afdccf33c443bcf443da4480e83e60034f73bf24b0a7139ab012910d60e17dd85d06897b0642a6e4cb0d0d548a08c6bfbd5ac8318f6bd787d998b3
+  metadata.gz: 5d06f3473ed427c34208a6067d4e77a445a10068e8ffc269f4725a858092c1a55c9dd12b504632df53e260f5e5b3b0b6c3aa8eab3a4499c475bdb165165d9403
+  data.tar.gz: a9c2936cc464d8288a815f1345b12c23918aaf7a70a15241e77e50ccf90ce0daefd27e172f1f554e7861d7d0e3d6bb9a34557cde7c614f162652795d5288a287

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-04
+
+### Added
+
+- **RSpec matcher** — `have_graphql_audit_entry(:update).touching(:title).for_type("Post")` for asserting audit entries in `Schema.execute` responses; include `RailsAuditLog::Graphql::Testing::RSpecMatchers` in your RSpec config
+- **Minitest assertions** — `assert_graphql_audit_entry` and `refute_graphql_audit_entry` with the same filter interface; include `RailsAuditLog::Graphql::Testing::MinitestAssertions` in your test class
+- Full YARD documentation on all public modules, classes, and methods
+- RBS type signatures for `Testing::RSpecMatchers` and `Testing::MinitestAssertions`
+
+### Changed
+
+- API stability guarantee — no breaking changes to public interfaces without a major version bump
+
+## [0.6.1] - 2026-06-04
+
+### Added
+
+- `actorType:` filter argument on `auditLogEntries`, `auditLogEntriesConnection`, and `auditLogEntriesCount` — filter by actor model class name (e.g. `"User"`)
+- `forTenant:` argument on `auditLogReify` and `auditLogEntriesCount` — consistent tenant scoping across all query fields; both also respect `RailsAuditLog.current_tenant` auto-tenant
+
+### Changed
+
+- `auditLogReify` return type changed from generic `JSON` to `AuditLogJson` for consistency with other entry fields
+- `rails g rails_audit_log:graphql:install` now also injects `SchemaPlugin` into the host schema file (detected via `app/graphql/**/*schema*.rb` glob); `print_next_steps` updated to mention all available queries and the complexity config override
+
 ## [0.6.0] - 2026-06-04
 
 ### Added

data/README.md

@@ -29,6 +29,9 @@ A [graphql-ruby](https://graphql-ruby.org) API layer for the [`rails_audit_log`]
     - [AuditLogSubscriptionsMixin](#auditlogsubscriptionsmixin)
     - [auditLogEntryCreated](#auditlogentrycreated)
     - [Broadcaster](#broadcaster)
+- [Testing](#testing)
+  - [RSpec matchers](#rspec-matchers)
+  - [Minitest assertions](#minitest-assertions)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -152,6 +155,7 @@ List entries with optional filters and offset pagination.
 | `itemType` | `String` | — | Filter by audited model class name |
 | `itemId` | `ID` | — | Filter by audited record ID |
 | `actorId` | `ID` | — | Filter by actor ID |
+| `actorType` | `String` | — | Filter by actor model class name (e.g. `"User"`) |
 | `since` | `ISO8601DateTime` | — | Return entries created at or after this time |
 | `until` | `ISO8601DateTime` | — | Return entries created at or before this time |
 | `touching` | `String` | — | Filter to entries that changed a specific attribute |
@@ -172,6 +176,7 @@ Same filters as `auditLogEntries`, but returns a [Relay-style connection](https:
 | `itemType` | `String` | Filter by audited model class name |
 | `itemId` | `ID` | Filter by audited record ID |
 | `actorId` | `ID` | Filter by actor ID |
+| `actorType` | `String` | Filter by actor model class name (e.g. `"User"`) |
 | `forTenant` | `String` | Scope to a specific tenant ID; overrides auto-tenant |
 | `first` | `Int` | Return the first N edges after `after` |
 | `after` | `String` | Cursor to paginate forward from |
@@ -221,7 +226,9 @@ Returns the count of matching audit log entries. Respects auto-tenant when `Rail
 |---|---|---|
 | `event` | `String` | Filter by event type (`create`, `update`, `destroy`) |
 | `itemType` | `String` | Filter by audited model class name |
+| `actorType` | `String` | Filter by actor model class name (e.g. `"User"`) |
 | `since` | `ISO8601DateTime` | Count entries created at or after this time |
+| `forTenant` | `String` | Scope to a specific tenant ID; overrides auto-tenant |
 
 ```graphql
 { auditLogEntriesCount(event: "update", itemType: "Post") }
@@ -291,9 +298,9 @@ The plugin also adds `AuditLogActor.record` and `AuditedResource.record` fields
 
 [↑ Back to top](#table-of-contents)
 
-### `auditLogReify(itemType:, itemId:, at:): JSON`
+### `auditLogReify(itemType:, itemId:, at:): AuditLogJson`
 
-Reconstructs the attribute state of a record at a given point in time. Returns the attributes as JSON, or `nil` when no entry exists at or before `at` or the record was destroyed at that time.
+Reconstructs the attribute state of a record at a given point in time. Returns the attributes as `AuditLogJson`, or `nil` when no entry exists at or before `at` or the record was destroyed at that time. Accepts `forTenant:` and respects auto-tenant.
 
 ```graphql
 {
@@ -384,6 +391,82 @@ For each entry, the broadcaster triggers:
 
 [↑ Back to top](#table-of-contents)
 
+## Testing
+
+`rails_audit_log-graphql` ships test helpers for both RSpec and Minitest so you can
+assert that your mutations actually produce the expected audit log entries.
+
+Require the testing helpers from your test helper:
+
+```ruby
+# spec/spec_helper.rb or test/test_helper.rb
+require "rails_audit_log/graphql/testing"
+```
+
+### RSpec matchers
+
+Include `RailsAuditLog::Graphql::Testing::RSpecMatchers` in your configuration:
+
+```ruby
+RSpec.configure do |config|
+  config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+end
+```
+
+Then use `have_graphql_audit_entry` against any `GraphQL::Query::Result` (or plain hash) returned by `Schema.execute`:
+
+```ruby
+result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+
+# Assert an entry with a specific event exists
+expect(result).to have_graphql_audit_entry(:update)
+
+# Assert the update entry touched the :title attribute
+# (requires diff { attribute } in the query)
+expect(result).to have_graphql_audit_entry(:update).touching(:title)
+
+# Scope to a specific model
+expect(result).to have_graphql_audit_entry(:create).for_type("Post")
+
+# Combine chains
+expect(result).to have_graphql_audit_entry(:update).for_type("Post").touching(:title)
+```
+
+The matcher searches `auditLogEntries` and `auditLogEntriesConnection.nodes` in the
+response data.
+
+[↑ Back to top](#table-of-contents)
+
+### Minitest assertions
+
+Include `RailsAuditLog::Graphql::Testing::MinitestAssertions` in your test class:
+
+```ruby
+class ActiveSupport::TestCase
+  include RailsAuditLog::Graphql::Testing::MinitestAssertions
+end
+```
+
+Use `assert_graphql_audit_entry` and `refute_graphql_audit_entry`:
+
+```ruby
+result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+
+# Assert an update entry exists
+assert_graphql_audit_entry result, event: :update
+
+# Assert an update entry that touched :title
+assert_graphql_audit_entry result, event: :update, touching: :title
+
+# Assert no destroy entry exists
+refute_graphql_audit_entry result, event: :destroy
+
+# Custom failure message
+assert_graphql_audit_entry result, event: :update, message: "mutation should have created an update entry"
+```
+
+[↑ Back to top](#table-of-contents)
+
 ## Development
 
 ```bash

data/ROADMAP.md

@@ -4,10 +4,4 @@ This gem adds a GraphQL API layer on top of [`rails_audit_log`](https://github.c
 
 ---
 
-## 1.0.0 — Stable API
-
-- Full YARD documentation
-- **RSpec matchers** — `expect(response).to have_graphql_audit_entry(:update).touching(:title)` 
-- **Minitest assertions** — `assert_graphql_audit_entry`
-- API stability guarantee — no breaking changes without a major version bump
-- Complete README with setup guide, examples, and schema reference
+_No planned milestones at this time._

data/lib/generators/rails_audit_log/graphql/install/install_generator.rb

@@ -7,10 +7,11 @@ module RailsAuditLog
     module Graphql
       class InstallGenerator < Rails::Generators::Base
         source_root File.expand_path("templates", __dir__)
-        desc "Injects AuditLogEntriesQueryMixin into your GraphQL QueryType."
+        desc "Injects AuditLogEntriesQueryMixin into your GraphQL QueryType and SchemaPlugin into your schema."
 
         QUERY_TYPE_PATH = "app/graphql/types/query_type.rb"
         MIXIN = "RailsAuditLog::Graphql::Queries::AuditLogEntriesQueryMixin"
+        SCHEMA_PLUGIN = "RailsAuditLog::Graphql::SchemaPlugin"
 
         def inject_mixin
           if File.exist?(File.join(destination_root, QUERY_TYPE_PATH))
@@ -24,11 +25,31 @@ module RailsAuditLog
           end
         end
 
+        def inject_schema_plugin
+          schema_files = Dir.glob(File.join(destination_root, "app/graphql/**/*schema*.rb"))
+          if schema_files.any?
+            schema_path = schema_files.first.delete_prefix("#{destination_root}/")
+            inject_into_file schema_path,
+              "  include #{SCHEMA_PLUGIN}\n",
+              after: /class\s+\S+\s*<\s*GraphQL::Schema\s*\n/
+          else
+            say ""
+            say "No schema file found. Add this line manually to your GraphQL::Schema subclass:", :yellow
+            say "  include #{SCHEMA_PLUGIN}", :green
+          end
+        end
+
         def print_next_steps
           say ""
           say "Done! Your GraphQL API now has:", :green
           say "  auditLogEntry(id: ID!): AuditLogEntry"
           say "  auditLogEntries(...): [AuditLogEntry!]!"
+          say "  auditLogReify(itemType:, itemId:, at:): AuditLogJson"
+          say "  auditLogEntriesCount(...): Int!"
+          say ""
+          say "SchemaPlugin applies complexity/depth limits and enables dataloader."
+          say "Override defaults in an initializer:"
+          say "  RailsAuditLog::Graphql.max_complexity = 500"
           say ""
           say "See the README for full documentation."
         end

data/lib/rails_audit_log/graphql/queries/audit_log_entries_query_mixin.rb

@@ -3,7 +3,24 @@
 module RailsAuditLog
   module Graphql
     module Queries
+      # Mixin that adds all audit log query fields to a host application's +QueryType+.
+      #
+      # Include in your +QueryType+:
+      #
+      #   class Types::QueryType < Types::BaseObject
+      #     include RailsAuditLog::Graphql::Queries::AuditLogEntriesQueryMixin
+      #   end
+      #
+      # This adds the following fields to the schema:
+      # - +auditLogEntry(id:)+ — fetch a single entry by ID
+      # - +auditLogEntries(...)+ — offset-paginated list with filters
+      # - +auditLogEntriesConnection(...)+ — cursor-paginated Relay connection
+      # - +auditLogEntriesCount(...)+ — count matching entries
+      # - +auditLogReify(itemType:, itemId:, at:)+ — reconstruct record state at a point in time
+      #
+      # @see https://github.com/eclectic-coding/rails_audit_log-graphql README
       module AuditLogEntriesQueryMixin
+        # @api private
         def self.included(base)
           base.field(
             :audit_log_entry,
@@ -29,6 +46,7 @@ module RailsAuditLog
             argument :item_type, String, required: false, description: "Filter by audited model class name."
             argument :item_id, GraphQL::Types::ID, required: false, description: "Filter by audited record ID."
             argument :actor_id, GraphQL::Types::ID, required: false, description: "Filter by actor ID."
+            argument :actor_type, String, required: false, description: "Filter by actor model class name (e.g. \"User\")."
             argument :since, GraphQL::Types::ISO8601DateTime, required: false, description: "Return entries created at or after this time."
             argument :until, GraphQL::Types::ISO8601DateTime, required: false, as: :until_time, description: "Return entries created at or before this time."
             argument :touching, String, required: false, description: "Filter to entries that changed a specific attribute (matches object_changes keys)."
@@ -50,6 +68,7 @@ module RailsAuditLog
             argument :item_type, String, required: false, description: "Filter by audited model class name."
             argument :item_id, GraphQL::Types::ID, required: false, description: "Filter by audited record ID."
             argument :actor_id, GraphQL::Types::ID, required: false, description: "Filter by actor ID."
+            argument :actor_type, String, required: false, description: "Filter by actor model class name (e.g. \"User\")."
             argument :since, GraphQL::Types::ISO8601DateTime, required: false, description: "Return entries created at or after this time."
             argument :until, GraphQL::Types::ISO8601DateTime, required: false, as: :until_time, description: "Return entries created at or before this time."
             argument :touching, String, required: false, description: "Filter to entries that changed a specific attribute (matches object_changes keys)."
@@ -60,7 +79,7 @@ module RailsAuditLog
 
           base.field(
             :audit_log_reify,
-            GraphQL::Types::JSON,
+            Types::AuditLogJsonScalar,
             null: true,
             description: "Reconstruct the attribute state of a record at a given point in time. Returns nil when no entry exists at or before `at`, or when the record was destroyed.",
             resolver_method: :resolve_audit_log_reify
@@ -68,6 +87,8 @@ module RailsAuditLog
             argument :item_type, String, required: true, description: "The audited model class name."
             argument :item_id, GraphQL::Types::ID, required: true, description: "The audited record ID."
             argument :at, GraphQL::Types::ISO8601DateTime, required: true, description: "Reconstruct state as of this time."
+            argument :for_tenant, String, required: false,
+              description: "Scope to a specific tenant ID. Overrides auto-tenant when RailsAuditLog.current_tenant is configured."
           end
 
           base.field(
@@ -79,10 +100,18 @@ module RailsAuditLog
           ) do
             argument :event, String, required: false, description: "Filter by event type (create, update, destroy)."
             argument :item_type, String, required: false, description: "Filter by audited model class name."
+            argument :actor_type, String, required: false, description: "Filter by actor model class name (e.g. \"User\")."
             argument :since, GraphQL::Types::ISO8601DateTime, required: false, description: "Count entries created at or after this time."
+            argument :for_tenant, String, required: false,
+              description: "Scope to a specific tenant ID. Overrides auto-tenant when RailsAuditLog.current_tenant is configured."
           end
         end
 
+        # Resolves the +auditLogEntry+ field.
+        #
+        # @param id [String] the entry ID
+        # @param for_tenant [String, nil] optional tenant scope
+        # @return [RailsAuditLog::AuditLogEntry, nil]
         def resolve_audit_log_entry(id:, for_tenant: nil)
           check_authentication!
           tenant_id = for_tenant || RailsAuditLog.current_tenant&.call
@@ -90,43 +119,62 @@ module RailsAuditLog
           base.find_by(id: id)
         end
 
-        def resolve_audit_log_entries(event: nil, item_type: nil, item_id: nil, actor_id: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil, page: 1, per_page: 25)
+        # Resolves the +auditLogEntries+ field.
+        #
+        # @return [ActiveRecord::Relation]
+        def resolve_audit_log_entries(event: nil, item_type: nil, item_id: nil, actor_id: nil, actor_type: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil, page: 1, per_page: 25)
           check_authentication!
-          scope = build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
+          scope = build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, actor_type: actor_type, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
           scope.limit(per_page).offset((page - 1) * per_page)
         end
 
-        def resolve_audit_log_entries_connection(event: nil, item_type: nil, item_id: nil, actor_id: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil)
+        # Resolves the +auditLogEntriesConnection+ field.
+        #
+        # @return [ActiveRecord::Relation]
+        def resolve_audit_log_entries_connection(event: nil, item_type: nil, item_id: nil, actor_id: nil, actor_type: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil)
           check_authentication!
-          build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
+          build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, actor_type: actor_type, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
         end
 
-        def resolve_audit_log_reify(item_type:, item_id:, at:)
+        # Resolves the +auditLogReify+ field. Returns the reconstructed attribute
+        # hash for +item_type+/+item_id+ as of +at+, or +nil+ when no entry exists.
+        #
+        # @param item_type [String]
+        # @param item_id [String]
+        # @param at [Time]
+        # @param for_tenant [String, nil]
+        # @return [Hash, nil]
+        def resolve_audit_log_reify(item_type:, item_id:, at:, for_tenant: nil)
           check_authentication!
-          entry = RailsAuditLog::AuditLogEntry
+          tenant_id = for_tenant || RailsAuditLog.current_tenant&.call
+          scope = RailsAuditLog::AuditLogEntry
             .where(item_type: item_type, item_id: item_id)
             .where("created_at <= ?", at)
-            .order(created_at: :desc, id: :desc)
-            .first
+          scope = scope.for_tenant(tenant_id) if tenant_id
+          entry = scope.order(created_at: :desc, id: :desc).first
           return nil if entry.nil? || entry.event == "destroy"
           to_attrs = (entry.object_changes || {}).transform_values { |v| v[1] }
           entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
         end
 
-        def resolve_audit_log_entries_count(event: nil, item_type: nil, since: nil)
+        # Resolves the +auditLogEntriesCount+ field.
+        #
+        # @return [Integer]
+        def resolve_audit_log_entries_count(event: nil, item_type: nil, actor_type: nil, since: nil, for_tenant: nil)
           check_authentication!
           scope = RailsAuditLog::AuditLogEntry.all
           scope = scope.where(event: event) if event
           scope = scope.where(item_type: item_type) if item_type
+          scope = scope.where(actor_type: actor_type) if actor_type
           scope = scope.where("created_at >= ?", since) if since
-          tenant_id = RailsAuditLog.current_tenant&.call
+          tenant_id = for_tenant || RailsAuditLog.current_tenant&.call
           scope = scope.for_tenant(tenant_id) if tenant_id
           scope.count
         end
 
         private
 
-        def build_scope(event: nil, item_type: nil, item_id: nil, actor_id: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil)
+        def build_scope(event: nil, item_type: nil, item_id: nil, actor_id: nil, actor_type: nil, since: nil, until_time: nil, touching: nil, order_by: nil, for_tenant: nil)
           sort_field = order_by&.field || :created_at
           sort_direction = order_by&.direction || :desc
           scope = RailsAuditLog::AuditLogEntry.order(sort_field => sort_direction)
@@ -134,6 +182,7 @@ module RailsAuditLog
           scope = scope.where(item_type: item_type) if item_type
           scope = scope.where(item_id: item_id) if item_id
           scope = scope.where(actor_id: actor_id) if actor_id
+          scope = scope.where(actor_type: actor_type) if actor_type
           scope = scope.where("created_at >= ?", since) if since
           scope = scope.where("created_at <= ?", until_time) if until_time
           if touching

data/lib/rails_audit_log/graphql/schema_plugin.rb

@@ -2,7 +2,29 @@
 
 module RailsAuditLog
   module Graphql
+    # Schema-level plugin that applies query-protection limits and enables
+    # dataloader batching in one +include+.
+    #
+    # Include in your GraphQL schema class:
+    #
+    #   class MySchema < GraphQL::Schema
+    #     include RailsAuditLog::Graphql::SchemaPlugin
+    #     query Types::QueryType
+    #   end
+    #
+    # This applies the following defaults (all overridable via
+    # {RailsAuditLog::Graphql} class-level accessors):
+    #
+    # | Setting                | Default | Description                                      |
+    # |------------------------|---------|--------------------------------------------------|
+    # | +max_complexity+       | 200     | Reject queries whose complexity exceeds this     |
+    # | +max_depth+            | 10      | Reject queries nested deeper than this           |
+    # | +default_max_page_size+| 25      | Page-size assumption for connection complexity   |
+    #
+    # Also enables +GraphQL::Dataloader+ for N+1-free batch loading of
+    # +actor.record+ and +auditedResource.record+ fields.
     module SchemaPlugin
+      # @api private
       def self.included(base)
         base.max_complexity(RailsAuditLog::Graphql.max_complexity)
         base.max_depth(RailsAuditLog::Graphql.max_depth)

data/lib/rails_audit_log/graphql/sources/record_by_id_source.rb

@@ -3,11 +3,25 @@
 module RailsAuditLog
   module Graphql
     module Sources
+      # Dataloader source that batch-loads ActiveRecord records by class name and ID,
+      # returning their +attributes+ hash.
+      #
+      # Used internally by {Types::ActorType} and {Types::AuditedResourceType} to
+      # resolve the +record+ field without N+1 queries.
+      #
+      # @example Manual use in a custom resolver
+      #   dataloader.with(RecordByIdSource, "User").load("42")
       class RecordByIdSource < GraphQL::Dataloader::Source
+        # @param class_name [String] the ActiveRecord model class name to load from
         def initialize(class_name)
           @class_name = class_name
         end
 
+        # Batch-loads records for the given IDs.
+        #
+        # @param ids [Array<String>] record IDs to load
+        # @return [Array<Hash, nil>] +attributes+ hash for each ID, or +nil+ when
+        #   the record does not exist or the class cannot be constantized
         def fetch(ids)
           klass = @class_name.safe_constantize
           return ids.map { nil } unless klass

data/lib/rails_audit_log/graphql/subscriptions/audit_log_subscriptions_mixin.rb

@@ -3,7 +3,26 @@
 module RailsAuditLog
   module Graphql
     module Subscriptions
+      # Mixin that adds the +auditLogEntryCreated+ subscription field to a host
+      # application's +SubscriptionType+.
+      #
+      # Include in your +SubscriptionType+:
+      #
+      #   class Types::SubscriptionType < Types::BaseObject
+      #     include RailsAuditLog::Graphql::Subscriptions::AuditLogSubscriptionsMixin
+      #   end
+      #
+      # The schema must also use +GraphQL::Subscriptions::ActionCableSubscriptions+:
+      #
+      #   class MySchema < GraphQL::Schema
+      #     subscription Types::SubscriptionType
+      #     use GraphQL::Subscriptions::ActionCableSubscriptions
+      #   end
+      #
+      # @see AuditLogEntryCreated
+      # @see Broadcaster
       module AuditLogSubscriptionsMixin
+        # @api private
         def self.included(base)
           base.field(
             :audit_log_entry_created,

data/lib/rails_audit_log/graphql/subscriptions/broadcaster.rb

@@ -3,25 +3,56 @@
 module RailsAuditLog
   module Graphql
     module Subscriptions
+      # Bridges +ActiveSupport::Notifications+ events emitted by
+      # +rails_audit_log+ to GraphQL subscription triggers.
+      #
+      # Start it once in an initializer after the schema is defined:
+      #
+      #   Rails.application.config.after_initialize do
+      #     RailsAuditLog::Graphql::Subscriptions::Broadcaster.new(schema: MySchema).start
+      #   end
+      #
+      # For each +rails_audit_log.entry_created+ notification the broadcaster
+      # fires two subscription triggers:
+      # - +auditLogEntryCreated(itemType:, itemId:)+ for record-specific subscribers
+      # - +auditLogEntryCreated(actorId:)+ for actor-specific subscribers (when an
+      #   actor is present on the entry)
       class Broadcaster
+        # @api private
         EVENT = "rails_audit_log.entry_created"
 
+        # @param schema [Class] the GraphQL schema class (must use
+        #   +GraphQL::Subscriptions::ActionCableSubscriptions+)
         def initialize(schema:)
           @schema = schema
           @subscriber = nil
         end
 
+        # Subscribe to +rails_audit_log.entry_created+ notifications and begin
+        # broadcasting to GraphQL subscribers. Idempotent — calling +start+ a
+        # second time replaces the previous subscriber.
+        #
+        # @return [void]
         def start
           @subscriber = ActiveSupport::Notifications.subscribe(EVENT) do |*, payload|
             broadcast(payload[:entry])
           end
         end
 
+        # Unsubscribe from +ActiveSupport::Notifications+. After calling +stop+,
+        # no further subscription triggers will fire until {#start} is called again.
+        #
+        # @return [void]
         def stop
           ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
           @subscriber = nil
         end
 
+        # Trigger GraphQL subscriptions for +entry+. Fires both the
+        # record-scoped and actor-scoped variants.
+        #
+        # @param entry [RailsAuditLog::AuditLogEntry] the newly created entry
+        # @return [void]
         def broadcast(entry)
           @schema.subscriptions.trigger(
             "audit_log_entry_created",

data/lib/rails_audit_log/graphql/testing/minitest_assertions.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Testing
+      # Minitest assertions for GraphQL audit log entries.
+      #
+      # Include this module in a test class or in a shared support file:
+      #
+      #   class ActiveSupport::TestCase
+      #     include RailsAuditLog::Graphql::Testing::MinitestAssertions
+      #   end
+      #
+      # The assertions inspect the +auditLogEntries+ and +auditLogEntriesConnection.nodes+
+      # keys in the response data. To use the +touching:+ option, include +diff { attribute }+
+      # in your GraphQL query.
+      module MinitestAssertions
+        # Asserts that the GraphQL response contains at least one audit log entry
+        # matching the given criteria.
+        #
+        # @param response [Hash, GraphQL::Query::Result] the result of +Schema.execute+
+        # @param event [Symbol, String] expected event type (:create, :update, :destroy)
+        # @param touching [Symbol, String, nil] when given, requires the entry's +diff+ to
+        #   include an attribute with this name (query must include +diff { attribute }+)
+        # @param item_type [String, nil] when given, requires the entry's +itemType+ to match
+        # @param message [String, nil] custom failure message
+        #
+        # @example Assert an update entry exists
+        #   result = MySchema.execute('{ auditLogEntries { event } }')
+        #   assert_graphql_audit_entry result, event: :update
+        #
+        # @example Assert an update entry that touched :title
+        #   result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+        #   assert_graphql_audit_entry result, event: :update, touching: :title
+        def assert_graphql_audit_entry(response, event:, touching: nil, item_type: nil, message: nil)
+          matched = filter_entries(response, event: event, touching: touching, item_type: item_type)
+          default_msg = build_message("Expected", event, touching, item_type)
+          assert matched.any?, message || default_msg
+        end
+
+        # Asserts that the GraphQL response does NOT contain an audit log entry
+        # matching the given criteria.
+        #
+        # @param response [Hash, GraphQL::Query::Result] the result of +Schema.execute+
+        # @param event [Symbol, String] the event type to check
+        # @param touching [Symbol, String, nil] attribute name to match against +diff+
+        # @param item_type [String, nil] model class name to match against +itemType+
+        # @param message [String, nil] custom failure message
+        def refute_graphql_audit_entry(response, event:, touching: nil, item_type: nil, message: nil)
+          matched = filter_entries(response, event: event, touching: touching, item_type: item_type)
+          default_msg = build_message("Expected no", event, touching, item_type)
+          refute matched.any?, message || default_msg
+        end
+
+        private
+
+        def filter_entries(response, event:, touching:, item_type:)
+          entries = extract_graphql_entries(response)
+          matched = entries.select { |e| e["event"] == event.to_s }
+          matched = matched.select { |e| e["itemType"] == item_type.to_s } if item_type
+          if touching
+            matched = matched.select { |e| e["diff"]&.any? { |d| d["attribute"] == touching.to_s } }
+          end
+          matched
+        end
+
+        def build_message(prefix, event, touching, item_type)
+          msg = "#{prefix} GraphQL audit entry with event #{event.inspect}"
+          msg += " touching #{touching.inspect}" if touching
+          msg += " for type #{item_type.inspect}" if item_type
+          msg
+        end
+
+        def extract_graphql_entries(response)
+          data = response.respond_to?(:[]) ? (response["data"] || response[:data]) : nil
+          return [] unless data
+
+          entries = []
+          entries += Array(data["auditLogEntries"])
+          entries += Array(data.dig("auditLogEntriesConnection", "nodes"))
+          entries += Array(data.dig("auditLogEntriesConnection", "edges")).filter_map { |e| e["node"] }
+          entries
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/testing/rspec_matchers.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Testing
+      # RSpec matchers for asserting GraphQL audit log entries in a query response.
+      #
+      # Include this module in your RSpec configuration to use the {#have_graphql_audit_entry}
+      # matcher:
+      #
+      #   RSpec.configure do |config|
+      #     config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+      #   end
+      #
+      # Or include it in a single example group:
+      #
+      #   RSpec.describe "audit logging" do
+      #     include RailsAuditLog::Graphql::Testing::RSpecMatchers
+      #   end
+      #
+      # The matcher inspects the +auditLogEntries+ and +auditLogEntriesConnection.nodes+
+      # keys in the response data. To use the +touching+ chain, include +diff { attribute }+
+      # in your GraphQL query.
+      module RSpecMatchers
+        # Returns a matcher that asserts a GraphQL response contains an audit log
+        # entry with the given event type.
+        #
+        # @param event [Symbol, String] expected event type (:create, :update, :destroy)
+        # @return [HaveGraphqlAuditEntry]
+        #
+        # @example Assert an update entry exists
+        #   result = MySchema.execute('{ auditLogEntries { event } }')
+        #   expect(result).to have_graphql_audit_entry(:update)
+        #
+        # @example Assert an update entry that touched :title
+        #   result = MySchema.execute('{ auditLogEntries { event diff { attribute } } }')
+        #   expect(result).to have_graphql_audit_entry(:update).touching(:title)
+        #
+        # @example Assert a create entry for a specific model
+        #   expect(result).to have_graphql_audit_entry(:create).for_type("Post")
+        def have_graphql_audit_entry(event)
+          HaveGraphqlAuditEntry.new(event.to_s)
+        end
+
+        # @api private
+        class HaveGraphqlAuditEntry
+          # @param event [String] the required event value
+          def initialize(event)
+            @event = event
+            @touching = nil
+            @item_type = nil
+          end
+
+          # Requires at least one matching entry's +diff+ to contain +attribute+.
+          # The query must include +diff { attribute }+ for this chain to work.
+          #
+          # @param attribute [Symbol, String] the changed attribute name
+          # @return [self]
+          def touching(attribute)
+            @touching = attribute.to_s
+            self
+          end
+
+          # Requires all matching entries to have +itemType+ equal to +item_type+.
+          #
+          # @param item_type [String] the ActiveRecord model class name
+          # @return [self]
+          def for_type(item_type)
+            @item_type = item_type.to_s
+            self
+          end
+
+          # @api private
+          def matches?(response)
+            @response = response
+            matched = extract_entries(response).select { |e| e["event"] == @event }
+            matched = matched.select { |e| e["itemType"] == @item_type } if @item_type
+            if @touching
+              matched = matched.select { |e| e["diff"]&.any? { |d| d["attribute"] == @touching } }
+            end
+            matched.any?
+          end
+
+          # @api private
+          def failure_message
+            "expected GraphQL response to include an audit entry with event #{@event.inspect}" \
+              "#{touching_clause}#{type_clause}, but it did not.\n" \
+              "Entries found: #{extract_entries(@response).map { |e| e["event"] }.inspect}"
+          end
+
+          # @api private
+          def failure_message_when_negated
+            "expected GraphQL response not to include an audit entry with event #{@event.inspect}" \
+              "#{touching_clause}#{type_clause}, but one was found."
+          end
+
+          private
+
+          def touching_clause
+            @touching ? " touching #{@touching.inspect}" : ""
+          end
+
+          def type_clause
+            @item_type ? " for type #{@item_type.inspect}" : ""
+          end
+
+          def extract_entries(response)
+            data = response.respond_to?(:[]) ? (response["data"] || response[:data]) : nil
+            return [] unless data
+
+            entries = []
+            entries += Array(data["auditLogEntries"])
+            entries += Array(data.dig("auditLogEntriesConnection", "nodes"))
+            entries += Array(data.dig("auditLogEntriesConnection", "edges")).filter_map { |e| e["node"] }
+            entries
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/testing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "testing/rspec_matchers"
+require_relative "testing/minitest_assertions"
+
+module RailsAuditLog
+  module Graphql
+    # Test helpers for asserting GraphQL audit log entries in query responses.
+    #
+    # Require this file from your test helper to load both RSpec matchers and
+    # Minitest assertions:
+    #
+    #   # spec/spec_helper.rb or test/test_helper.rb
+    #   require "rails_audit_log/graphql/testing"
+    #
+    # Then include the appropriate module for your test framework:
+    #
+    #   # RSpec
+    #   RSpec.configure do |config|
+    #     config.include RailsAuditLog::Graphql::Testing::RSpecMatchers
+    #   end
+    #
+    #   # Minitest
+    #   class ActiveSupport::TestCase
+    #     include RailsAuditLog::Graphql::Testing::MinitestAssertions
+    #   end
+    module Testing
+    end
+  end
+end

data/lib/rails_audit_log/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module RailsAuditLog
   module Graphql
-    VERSION = "0.6.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/rails_audit_log/graphql.rb

@@ -19,7 +19,24 @@ require_relative "graphql/subscriptions/audit_log_subscriptions_mixin"
 require_relative "graphql/subscriptions/broadcaster"
 require_relative "graphql/schema_plugin"
 
+# The top-level namespace for the rails_audit_log gem.
 module RailsAuditLog
+  # GraphQL API layer for rails_audit_log.
+  #
+  # Provides ready-made types, queries, subscriptions, and test helpers for
+  # exposing {https://github.com/eclectic-coding/rails_audit_log rails_audit_log}
+  # audit log entries through a graphql-ruby schema.
+  #
+  # == Configuration
+  #
+  # Override query-protection defaults in an initializer:
+  #
+  #   RailsAuditLog::Graphql.max_complexity      = 500
+  #   RailsAuditLog::Graphql.max_depth           = 15
+  #   RailsAuditLog::Graphql.default_max_page_size = 50
+  #
+  # These values are picked up by {SchemaPlugin} when it is included in the
+  # host schema.
   module Graphql
     class Error < StandardError; end
 
@@ -28,7 +45,23 @@ module RailsAuditLog
     @default_max_page_size = 25
 
     class << self
-      attr_accessor :max_complexity, :max_depth, :default_max_page_size
+      # Maximum allowed query complexity score.
+      # Queries whose field-complexity sum exceeds this value are rejected.
+      # Default: +200+.
+      # @return [Integer]
+      attr_accessor :max_complexity
+
+      # Maximum allowed query depth.
+      # Queries nested deeper than this value are rejected.
+      # Default: +10+.
+      # @return [Integer]
+      attr_accessor :max_depth
+
+      # Default maximum page size for Relay connections.
+      # Used by graphql-ruby when calculating connection complexity.
+      # Default: +25+.
+      # @return [Integer]
+      attr_accessor :default_max_page_size
     end
   end
 end

data/sig/rails_audit_log/graphql.rbs

@@ -112,6 +112,7 @@ module RailsAuditLog
           ?item_type: String?,
           ?item_id: String?,
           ?actor_id: String?,
+          ?actor_type: String?,
           ?since: Time?,
           ?until_time: Time?,
           ?touching: String?,
@@ -126,6 +127,7 @@ module RailsAuditLog
           ?item_type: String?,
           ?item_id: String?,
           ?actor_id: String?,
+          ?actor_type: String?,
           ?since: Time?,
           ?until_time: Time?,
           ?touching: String?,
@@ -136,13 +138,16 @@ module RailsAuditLog
         def resolve_audit_log_reify: (
           item_type: String,
           item_id: String,
-          at: Time
+          at: Time,
+          ?for_tenant: String?
         ) -> Hash[String, untyped]?
 
         def resolve_audit_log_entries_count: (
           ?event: String?,
           ?item_type: String?,
-          ?since: Time?
+          ?actor_type: String?,
+          ?since: Time?,
+          ?for_tenant: String?
         ) -> Integer
 
         private
@@ -152,6 +157,7 @@ module RailsAuditLog
           ?item_type: String?,
           ?item_id: String?,
           ?actor_id: String?,
+          ?actor_type: String?,
           ?since: Time?,
           ?until_time: Time?,
           ?touching: String?,
@@ -162,5 +168,38 @@ module RailsAuditLog
         def check_authentication!: () -> void
       end
     end
+
+    module Testing
+      module RSpecMatchers
+        def have_graphql_audit_entry: (Symbol | String event) -> HaveGraphqlAuditEntry
+
+        class HaveGraphqlAuditEntry
+          def initialize: (String event) -> void
+          def touching: (Symbol | String attribute) -> self
+          def for_type: (String item_type) -> self
+          def matches?: (untyped response) -> bool
+          def failure_message: () -> String
+          def failure_message_when_negated: () -> String
+        end
+      end
+
+      module MinitestAssertions
+        def assert_graphql_audit_entry: (
+          untyped response,
+          event: Symbol | String,
+          ?touching: (Symbol | String)?,
+          ?item_type: String?,
+          ?message: String?
+        ) -> void
+
+        def refute_graphql_audit_entry: (
+          untyped response,
+          event: Symbol | String,
+          ?touching: (Symbol | String)?,
+          ?item_type: String?,
+          ?message: String?
+        ) -> void
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log-graphql
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -91,6 +91,9 @@ files:
 - lib/rails_audit_log/graphql/subscriptions/audit_log_entry_created.rb
 - lib/rails_audit_log/graphql/subscriptions/audit_log_subscriptions_mixin.rb
 - lib/rails_audit_log/graphql/subscriptions/broadcaster.rb
+- lib/rails_audit_log/graphql/testing.rb
+- lib/rails_audit_log/graphql/testing/minitest_assertions.rb
+- lib/rails_audit_log/graphql/testing/rspec_matchers.rb
 - lib/rails_audit_log/graphql/types/actor_type.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_sort_field_enum.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_type.rb