rails_audit_log-graphql 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c89d640d69c533ded27f477ed99b03275c34b4564c90e6eaccfe86a131f2447
-  data.tar.gz: d34b732d907a2db6b9c6c0bfba266933aaf6f21be9c8770caa8c64b50a81c870
+  metadata.gz: fd228bcaff874e10bbd50927cb3bc44d22b5c860acf8dd444624eff80c7dea96
+  data.tar.gz: 29ebf0ccd63fd0827689d3cf0b5e5bd3b4c6194c12468aa347c0fadb1fe0c5f3
 SHA512:
-  metadata.gz: faa1b363d2aaebc1b3f5573f0b6c757a5d6b4d1fe8b6a1af7d906bd9877f23cecf897b75640b9f61e24e622d06c4233825be5047bada0d92371f954749a2499f
-  data.tar.gz: '08c32d0f02192b6db82d11e414ac04beb42a54ce61bb6dd8b025b2866f1569bc65b7b177ba308a4c0d241d7486029741e03abf082af38726fa2bbd30d6d2c6f4'
+  metadata.gz: 81930d3cedc11053354b5b86349d5483b326f43d774ebea49f97bc61e827c1ede95fa61c1b2671c611df266a9f7b4f4e497d472d47d86fc01b9e6863dd2b8df2
+  data.tar.gz: 158775764845a120940581a0e6c47be8ca3ba992c5195b4bb899c970d069f27dc94faf53c4dde7ee1e4752992d8de62adec09f3f20a68e8209499239e9589887

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-04
+
+### Added
+
+- `AuditLogEntryCreated` subscription — `auditLogEntryCreated(itemType:, itemId:)` subscribes to new entries for a specific record; `auditLogEntryCreated(actorId:)` subscribes to all entries by a specific actor
+- `AuditLogSubscriptionsMixin` — include into host app's `SubscriptionType` to add the `auditLogEntryCreated` subscription field
+- `BaseSubscription` base class for all gem GraphQL subscription types
+- `Broadcaster` — call `Broadcaster.new(schema: MySchema).start` in an initializer to relay `rails_audit_log.entry_created` `ActiveSupport::Notifications` events into GraphQL subscription triggers; supports `stop` to unsubscribe
+
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- `ActorType` (`AuditLogActor`) — new object type with `id` and `typeName` fields exposing the polymorphic actor reference; adds `actor: AuditLogActor` field on `AuditLogEntry`
+- `AuditedResourceType` (`AuditedResource`) — new object type with `id` and `typeName` fields exposing the audited model reference; adds `auditedResource: AuditedResource!` field on `AuditLogEntry`
+- `DiffType` (`AuditLogDiff`) — new object type with `attribute`, `from`, and `to` fields; adds `diff: [AuditLogDiff!]` field on `AuditLogEntry` parsed from `objectChanges`
+
 ## [0.2.0] - 2026-06-03
 
 ### Added

data/README.md

@@ -13,10 +13,18 @@ A [graphql-ruby](https://graphql-ruby.org) API layer for the [`rails_audit_log`]
 - [Installation](#installation)
 - [Usage](#usage)
   - [AuditLogEntryType](#auditlogentrytype)
+  - [AuditLogActor](#auditlogactor)
+  - [AuditedResource](#auditedresource)
+  - [AuditLogDiff](#auditlogdiff)
   - [AuditLogEntriesQueryMixin](#auditlogentriesquerymixin)
     - [auditLogEntry](#auditlogentryid-id-auditlogentry)
     - [auditLogEntries](#auditlogentries-auditlogentry)
+    - [auditLogEntriesConnection](#auditlogentriesconnection-auditlogentryconnection)
   - [Authentication](#authentication)
+  - [Subscriptions](#subscriptions)
+    - [AuditLogSubscriptionsMixin](#auditlogsubscriptionsmixin)
+    - [auditLogEntryCreated](#auditlogentrycreated)
+    - [Broadcaster](#broadcaster)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -61,6 +69,57 @@ This injects `include RailsAuditLog::Graphql::Queries::AuditLogEntriesQueryMixin
 | `actorType` | `String` | yes |
 | `actorId` | `ID` | yes |
 | `tenantId` | `String` | yes |
+| `actor` | `AuditLogActor` | yes |
+| `auditedResource` | `AuditedResource` | no |
+| `diff` | `[AuditLogDiff!]` | yes |
+
+[↑ Back to top](#table-of-contents)
+
+### AuditLogActor
+
+`RailsAuditLog::Graphql::Types::ActorType` — a polymorphic reference to the actor who performed the audited action. Returned by the `actor` field on `AuditLogEntry`. `null` when no actor was recorded.
+
+| GraphQL field | Type | Nullable |
+|---|---|---|
+| `id` | `ID` | no |
+| `typeName` | `String` | no |
+
+[↑ Back to top](#table-of-contents)
+
+### AuditedResource
+
+`RailsAuditLog::Graphql::Types::AuditedResourceType` — a reference to the model record that was changed. Returned by the `auditedResource` field on `AuditLogEntry`. Always present.
+
+| GraphQL field | Type | Nullable |
+|---|---|---|
+| `id` | `ID` | no |
+| `typeName` | `String` | no |
+
+[↑ Back to top](#table-of-contents)
+
+### AuditLogDiff
+
+`RailsAuditLog::Graphql::Types::DiffType` — a single attribute change parsed from `objectChanges`. Returned as a list by the `diff` field on `AuditLogEntry`. `null` when `objectChanges` is not recorded (e.g. destroy events).
+
+| GraphQL field | Type | Nullable | Description |
+|---|---|---|---|
+| `attribute` | `String` | no | Name of the changed attribute |
+| `from` | `JSON` | yes | Value before the change |
+| `to` | `JSON` | yes | Value after the change |
+
+**Example:**
+
+```graphql
+{
+  auditLogEntries(event: "update") {
+    diff {
+      attribute
+      from
+      to
+    }
+  }
+}
+```
 
 [↑ Back to top](#table-of-contents)
 
@@ -89,10 +148,14 @@ 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 |
+| `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 |
+| `orderBy` | `AuditLogEntrySortInput` | `CREATED_AT DESC` | Sort field and direction |
 | `page` | `Int` | `1` | Page number (1-based) |
 | `perPage` | `Int` | `25` | Results per page |
 
-Results are ordered by `created_at DESC`.
+Results default to `created_at DESC` ordering.
 
 #### `auditLogEntriesConnection(...): AuditLogEntryConnection!`
 
@@ -158,6 +221,84 @@ If no authenticate block is set, all queries are permitted.
 
 [↑ Back to top](#table-of-contents)
 
+### Subscriptions
+
+Requires Action Cable in the host application.
+
+#### AuditLogSubscriptionsMixin
+
+Include `RailsAuditLog::Graphql::Subscriptions::AuditLogSubscriptionsMixin` into your app's `SubscriptionType` to add the `auditLogEntryCreated` field. Your schema must also use `GraphQL::Subscriptions::ActionCableSubscriptions`.
+
+```ruby
+# app/graphql/types/subscription_type.rb
+class Types::SubscriptionType < Types::BaseObject
+  include RailsAuditLog::Graphql::Subscriptions::AuditLogSubscriptionsMixin
+end
+
+# app/graphql/my_schema.rb
+class MySchema < GraphQL::Schema
+  query Types::QueryType
+  subscription Types::SubscriptionType
+  use GraphQL::Subscriptions::ActionCableSubscriptions
+end
+```
+
+#### `auditLogEntryCreated`
+
+Fires when a new `RailsAuditLog::AuditLogEntry` is created. Accepts one of two argument combinations:
+
+| Argument | Type | Description |
+|---|---|---|
+| `itemType` | `String` | Model class name to scope the subscription to |
+| `itemId` | `ID` | Record ID to scope the subscription to |
+| `actorId` | `ID` | Actor ID — subscribe to all entries by a specific actor |
+
+Subscribe to all changes on a specific record:
+
+```graphql
+subscription {
+  auditLogEntryCreated(itemType: "Post", itemId: "42") {
+    id
+    event
+    diff { attribute from to }
+  }
+}
+```
+
+Subscribe to all entries by a specific actor:
+
+```graphql
+subscription {
+  auditLogEntryCreated(actorId: "7") {
+    id
+    event
+    itemType
+    itemId
+  }
+}
+```
+
+#### Broadcaster
+
+`RailsAuditLog::Graphql::Subscriptions::Broadcaster` bridges `ActiveSupport::Notifications` (fired by `RailsAuditLog::Streaming::NotificationsAdapter` or `ActiveJobAdapter`) to GraphQL subscription triggers. Start it in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log_graphql.rb
+RailsAuditLog.configure do |c|
+  c.streaming_adapter = RailsAuditLog::Streaming::NotificationsAdapter.new
+end
+
+Rails.application.config.after_initialize do
+  RailsAuditLog::Graphql::Subscriptions::Broadcaster.new(schema: MySchema).start
+end
+```
+
+For each entry, the broadcaster triggers:
+- `auditLogEntryCreated(itemType:, itemId:)` — notifies record-specific subscribers
+- `auditLogEntryCreated(actorId:)` — notifies actor-specific subscribers (when an actor is present)
+
+[↑ Back to top](#table-of-contents)
+
 ## Development
 
 ```bash

data/ROADMAP.md

@@ -4,24 +4,6 @@ This gem adds a GraphQL API layer on top of [`rails_audit_log`](https://github.c
 
 ---
 
-## 0.3.0 — Actor & Resource Resolver Types
-
-- **`ActorType`** — resolve the polymorphic `actor` to the concrete type in the host app's schema (requires a configurable type resolver proc)
-- **`AuditedResourceType`** — resolve `item_type`/`item_id` to the concrete audited model type
-- **`diffType`** — structured `{ from, to }` diff type instead of raw `objectChanges` JSON
-
----
-
-## 0.4.0 — Subscriptions
-
-Requires Action Cable in the host application.
-
-- **`auditLogEntryCreated(itemType:, itemId:)`** — subscribe to new entries for a specific record
-- **`auditLogEntryCreated(actorId:)`** — subscribe to all entries by a specific actor
-- Hooks into `RailsAuditLog::Streaming::NotificationsAdapter` to trigger broadcasts
-
----
-
 ## 0.5.0 — Multi-tenancy & Advanced Filtering
 
 - **Tenant scoping** — automatically scope queries via `RailsAuditLog.current_tenant` when configured

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Subscriptions
+      class AuditLogEntryCreated < Types::BaseSubscription
+        description "Fires when a new audit log entry is created."
+
+        argument :item_type, String, required: false,
+          description: "Filter to entries for a specific model class name."
+        argument :item_id, GraphQL::Types::ID, required: false,
+          description: "Filter to entries for a specific record ID."
+        argument :actor_id, GraphQL::Types::ID, required: false,
+          description: "Filter to entries by a specific actor ID."
+
+        type Types::AuditLogEntryType, null: false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Subscriptions
+      module AuditLogSubscriptionsMixin
+        def self.included(base)
+          base.field(
+            :audit_log_entry_created,
+            subscription: AuditLogEntryCreated,
+            description: "Fires when a new audit log entry is created."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Subscriptions
+      class Broadcaster
+        EVENT = "rails_audit_log.entry_created"
+
+        def initialize(schema:)
+          @schema = schema
+          @subscriber = nil
+        end
+
+        def start
+          @subscriber = ActiveSupport::Notifications.subscribe(EVENT) do |*, payload|
+            broadcast(payload[:entry])
+          end
+        end
+
+        def stop
+          ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+          @subscriber = nil
+        end
+
+        def broadcast(entry)
+          @schema.subscriptions.trigger(
+            "audit_log_entry_created",
+            {item_type: entry.item_type, item_id: entry.item_id.to_s},
+            entry
+          )
+
+          return unless entry.actor_id.present?
+
+          @schema.subscriptions.trigger(
+            "audit_log_entry_created",
+            {actor_id: entry.actor_id.to_s},
+            entry
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/actor_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Types
+      class ActorType < BaseObject
+        graphql_name "AuditLogActor"
+        description "A polymorphic reference to the actor who performed the audited action."
+
+        field :id, GraphQL::Types::ID, null: false, description: "The actor's ID."
+        field :type_name, String, null: false, description: "The actor's model class name (e.g. \"User\")."
+
+        def id
+          object[:id]
+        end
+
+        def type_name
+          object[:type_name]
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/audit_log_entry_type.rb

@@ -20,6 +20,27 @@ module RailsAuditLog
         field :actor_id, GraphQL::Types::ID, null: true
         field :tenant_id, String, null: true
         field :created_at, GraphQL::Types::ISO8601DateTime, null: false
+        field :actor, Types::ActorType, null: true,
+          description: "The actor who performed this action, as a polymorphic reference."
+        field :audited_resource, Types::AuditedResourceType, null: false,
+          description: "The model type and ID of the record that was changed."
+        field :diff, [Types::DiffType, null: false], null: true,
+          description: "Structured per-attribute diffs parsed from objectChanges. Nil when no changes are recorded."
+
+        def actor
+          return nil if object.actor_id.nil? || object.actor_type.nil?
+          {id: object.actor_id, type_name: object.actor_type}
+        end
+
+        def audited_resource
+          {id: object.item_id, type_name: object.item_type}
+        end
+
+        def diff
+          changes = object.object_changes
+          return nil if changes.nil?
+          changes.map { |attr, (from_val, to_val)| {attribute: attr, from: from_val, to: to_val} }
+        end
       end
     end
   end

data/lib/rails_audit_log/graphql/types/audited_resource_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Types
+      class AuditedResourceType < BaseObject
+        graphql_name "AuditedResource"
+        description "A reference to the model record that was changed."
+
+        field :id, GraphQL::Types::ID, null: false, description: "The audited record's ID."
+        field :type_name, String, null: false, description: "The audited model class name (e.g. \"Post\")."
+
+        def id
+          object[:id]
+        end
+
+        def type_name
+          object[:type_name]
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/base_subscription.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Types
+      class BaseSubscription < GraphQL::Schema::Subscription
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/diff_type.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Types
+      class DiffType < BaseObject
+        graphql_name "AuditLogDiff"
+        description "A single attribute change with before and after values."
+
+        field :attribute, String, null: false, description: "The name of the changed attribute."
+        field :from, GraphQL::Types::JSON, null: true, description: "Value before the change."
+        field :to, GraphQL::Types::JSON, null: true, description: "Value after the change."
+
+        def attribute
+          object[:attribute]
+        end
+
+        def from
+          object[:from]
+        end
+
+        def to
+          object[:to]
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module RailsAuditLog
   module Graphql
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/rails_audit_log/graphql.rb

@@ -3,11 +3,18 @@
 require "graphql"
 require_relative "graphql/version"
 require_relative "graphql/types/base_object"
+require_relative "graphql/types/base_subscription"
+require_relative "graphql/types/diff_type"
+require_relative "graphql/types/actor_type"
+require_relative "graphql/types/audited_resource_type"
 require_relative "graphql/types/audit_log_entry_type"
 require_relative "graphql/types/sort_direction_enum"
 require_relative "graphql/types/audit_log_entry_sort_field_enum"
 require_relative "graphql/input_objects/audit_log_entry_sort_input"
 require_relative "graphql/queries/audit_log_entries_query_mixin"
+require_relative "graphql/subscriptions/audit_log_entry_created"
+require_relative "graphql/subscriptions/audit_log_subscriptions_mixin"
+require_relative "graphql/subscriptions/broadcaster"
 
 module RailsAuditLog
   module Graphql

data/sig/rails_audit_log/graphql.rbs

@@ -6,7 +6,29 @@ module RailsAuditLog
       class BaseObject < GraphQL::Schema::Object
       end
 
+      class BaseSubscription < GraphQL::Schema::Subscription
+      end
+
+      class DiffType < BaseObject
+        def attribute: () -> String
+        def from: () -> untyped
+        def to: () -> untyped
+      end
+
+      class ActorType < BaseObject
+        def id: () -> String
+        def type_name: () -> String
+      end
+
+      class AuditedResourceType < BaseObject
+        def id: () -> String
+        def type_name: () -> String
+      end
+
       class AuditLogEntryType < BaseObject
+        def actor: () -> Hash[Symbol, untyped]?
+        def audited_resource: () -> Hash[Symbol, untyped]
+        def diff: () -> Array[Hash[Symbol, untyped]]?
       end
 
       class SortDirectionEnum < GraphQL::Schema::Enum
@@ -32,6 +54,24 @@ module RailsAuditLog
       end
     end
 
+    module Subscriptions
+      class AuditLogEntryCreated < Types::BaseSubscription
+        def subscribe: (?item_type: String?, ?item_id: String?, ?actor_id: String?) -> :no_response
+        def update: (?item_type: String?, ?item_id: String?, ?actor_id: String?) -> untyped
+      end
+
+      module AuditLogSubscriptionsMixin
+        def self.included: (untyped base) -> void
+      end
+
+      class Broadcaster
+        def initialize: (schema: untyped) -> void
+        def start: () -> void
+        def stop: () -> void
+        def broadcast: (untyped entry) -> void
+      end
+    end
+
     module Queries
       module AuditLogEntriesQueryMixin
         def self.included: (untyped base) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log-graphql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -86,9 +86,16 @@ files:
 - lib/rails_audit_log/graphql/input_objects/audit_log_entry_sort_input.rb
 - lib/rails_audit_log/graphql/queries/audit_log_entries_query_mixin.rb
 - lib/rails_audit_log/graphql/release_tooling.rb
+- 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/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
+- lib/rails_audit_log/graphql/types/audited_resource_type.rb
 - lib/rails_audit_log/graphql/types/base_object.rb
+- lib/rails_audit_log/graphql/types/base_subscription.rb
+- lib/rails_audit_log/graphql/types/diff_type.rb
 - lib/rails_audit_log/graphql/types/sort_direction_enum.rb
 - lib/rails_audit_log/graphql/version.rb
 - sig/rails_audit_log/graphql.rbs