fuik 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a653582dac2c822bb4496a89d0dbd12cd9b96a082bdeed11c209793df27de21
-  data.tar.gz: 44070a1620d3d867cc5a400e7f61bbd58bebec6e713407d6da6a65d8d2d2037b
+  metadata.gz: 7e63ae360a189d38134db206274a5733ad73ea37ae2b338686c952df7ac3c109
+  data.tar.gz: c59410136f9c4143690b96b496c3e83fdf0419d806cc308a5ab4e73c1c1b21fb
 SHA512:
-  metadata.gz: c870f47e09396993506e96851c491d0e715ddf87d964554aba212e83927a2e9370c75b601cce24f8b4a0653b1b8cfe16f3825fb916048fa9828c05e95ab8d49a
-  data.tar.gz: 9ce68f8cb2d9aa7af1aa3cfb6a394a1a26cc165ed6dc58320fbfc0b266d219e839d0a29a352164fadce614ff75579dcb8041077d553cdbd45cfe6424d709125e
+  metadata.gz: 07d53ebe3d570ec39d8e2b669492433972789437100dd811b795e5abad902e5d921fc93cf6714c3fef5f5a484cbcdedab04280becea9ec02fb2e65e762517beb
+  data.tar.gz: 604fb6bc76e23853ca980b1f25861eab8ee45bfd2f0d66182d805db8b133fe411d35e485b44042937114236a040e5deb9563f248a703f245cedcc86d58b40cdc

data/README.md

@@ -57,14 +57,17 @@ Visit `/webhooks` to see all received webhooks. Click any event to view all the
 
 <img alt="Fuik event detail interface" src="https://raw.githubusercontent.com/Rails-Designer/fuik/HEAD/.github/docs/event-detail.jpg" style="max-width: 100%;">
 
-⚠️ The `/webhooks` path is by default not protected. Easiest is to set `Fuik::Engine.config.events_controller_parent` to a controller that requires authentication.
+⚠️ The `/webhooks` path is by default not protected. Set `Fuik.configuration.events_controller_parent` to a controller that requires authentication.
+
 
 ### Dashboard features
 
 * **Copy payload as JSON**: click a button, payload is in your clipboard
 * **Download payload as JSON file**: keep it for testing, debugging or throw it at your LLM agent, bot or colleague
 * **Add `.json` to any URL**: get the raw payload without the UI
-* **Click any key to get the Ruby accessor path**: click `product_id` (as seen in the screenshot above) and get `payload["line_items"][0]["product_id"]` (say what? 🤯)
+* **`GET /events.json`**: index as JSON with filter support
+* **Click any key to get the Ruby accessor path**: click any key and get, e.g. `payload["line_items"][0]["product_id"]` (say what? 🤯)
+
 
 
 ### Add business logic
@@ -130,64 +133,192 @@ end
 If `Provider::Base.verify!` exists, Fuik calls it automatically. Invalid signatures return 401 without storing the webhook.
 
 
+### Configuration
+
+Configure Fuik in `config/initializers/fuik.rb`:
+```ruby
+Fuik.configure do |config|
+  # config.events_controller_parent = "AdministrationController"
+  # config.providers_allowed = %w[stripe github postmark]
+end
+```
+
+
+### Custom job class
+
+Webhook events are processed asynchronously by `Fuik::WebhookProcessingJob`. When processing raises, the event is marked as `failed` so you can retry it from the dashboard.
+
+Define a custom job class, then configure Fuik to use it:
+```ruby
+# app/jobs/webhook_processing_job.rb
+class WebhookProcessingJob < ApplicationJob
+  queue_as :webhooks
+
+  retry_on MyApp::WebhookError, attempts: 5
+  discard_on ActiveJob::DeserializationError
+
+  def perform(event_class_name, webhook_event)
+    event_class_name.safe_constantize.new(webhook_event).process!
+  end
+end
+```
+
+```ruby
+# config/initializers/fuik.rb
+Fuik.configure do |config|
+  config.webhook_processing_job_class = "WebhookProcessingJob"
+end
+```
+
+The `perform` method receives two arguments:
+- `event_class_name`: a string like `"Stripe::CheckoutSessionCompleted"` that resolves to your event class
+- `webhook_event`: the `Fuik::WebhookEvent` record with the payload, headers and status
+
+
+### Testing event classes
+
+Unit test your `process!` methods without a database using the built-in test helper:
+```ruby
+# test/test_helper.rb
+require "fuik/test_helpers"
+
+class ActiveSupport::TestCase
+  include Fuik::TestHelpers
+end
+```
+
+```ruby
+# test/webhooks/stripe/checkout_session_completed_test.rb
+module Stripe
+  class CheckoutSessionCompletedTest < ActiveSupport::TestCase
+    test "processes a completed checkout" do
+      event = build_webhook_event(
+        provider: "stripe",
+        event_type: "checkout.session.completed",
+        payload: { "client_reference_id" => "user_123" }
+      )
+
+      CheckoutSessionCompleted.new(event).process!
+
+      assert_equal "processed", event.status
+    end
+
+    test "fails when customer is not found" do
+      event = build_webhook_event(
+        provider: "stripe",
+        event_type: "checkout.session.completed",
+        payload: {}
+      )
+
+      CheckoutSessionCompleted.new(event).process!
+
+      assert_equal "failed", event.status
+      assert_equal "Customer not found", event.error
+    end
+  end
+end
+```
+
+Your `process!` calls `@webhook_event.processed!` on success and `@webhook_event.failed!(error)` on failure:
+```ruby
+module Stripe
+  class CheckoutSessionCompleted < Base
+    def process!
+      user = User.find_by(id: payload.client_reference_id)
+
+      if user.present?
+        user.activate_subscription!
+
+        @webhook_event.processed!
+      else
+        @webhook_event.failed!("Customer not found")
+      end
+    end
+  end
+end
+```
+
+
 ### Provider allowlist
 
 By default:
 - **Development/test**: all providers are allowed
 - **Production/staging**: only providers in `app/webhooks/` are allowed
 
-Configure with `Fuik::Engine.config.providers_allowed`:
+Configure with `Fuik.configuration.providers_allowed`:
 ```ruby
 # Allow all (including production)
-Fuik::Engine.config.providers_allowed = :all
+Fuik.configuration.providers_allowed = :all
 
 # Explicit allowlist (overrides directory scan)
-Fuik::Engine.config.providers_allowed = %w[stripe github shopify]
+Fuik.configuration.providers_allowed = %w[stripe github postmark]
 ```
 
 Unknown providers return `404 Not Found`.
 
 
-### Pre-packaged providers
-
-Fuik includes ready-to-use [templates for common providers](https://github.com/Rails-Designer/fuik/tree/main/lib/generators/fuik/provider/templates).
-
-
 ### Event type & ID lookup
 
 Fuik automatically extracts event types and IDs from common locations:
 
 **Event Type:**
-1. provider config (if exists);
+1. provider Base class (if configured);
 2. common headers (`X-Github-Event`, `X-Event-Type`, etc.);
 3. payload (`type`, `event`, `event_type`);
 4. falls back to `"unknown"`.
 
 **Event ID:**
-1. provider config (if exists);
+1. provider Base class (if configured);
 2. common headers (`X-GitHub-Delivery`, `X-Event-Id`, etc.);
 3. payload (`id`).
 4. falls back to MD5 hash of request body.
 
 
-#### Custom lookup via config
+#### Custom lookup
+
+Define `event_type` and/or `event_id` on your provider's Base class if Fuik can't find them on its own:
+```ruby
+module CustomProvider
+  class Base < Fuik::Event
+    event_type header: "X-Custom-Event"
+    event_id header: "X-Custom-Id"
+  end
+end
+```
+
+You can also read from the payload body or use a static value:
+```ruby
+event_type payload: "event_type"  # payload["event_type"]
+event_type payload: "data.type"  # nested via dot-notation (payload["data"]["type"])
+event_type "always_this_value"  # static/literal
+
+event_id payload: "id"
+```
+
+
+### Pre-packaged providers
+
+Fuik includes ready-to-use [templates for common providers](https://github.com/Rails-Designer/fuik/tree/main/lib/generators/fuik/provider/templates).
+
 
-Create `app/webhooks/provider_name/config.yml`:
-```yaml
-event_type:
-  source: header
-  key: X-Custom-Event
+## Monitoring
 
-event_id:
-  source: payload
-  key: custom_id
+Fuik publishes lifecycle events via `ActiveSupport::Notifications`. Subscribe to track webhook activity:
+```ruby
+ActiveSupport::Notifications.subscribe("webhook_received.fuik") do |event|
+  Rails.logger.info("[Fuik] Received #{event.payload[:provider]}:#{event.payload[:event_type]}")
+end
 ```
 
-The options for `event_type`'s source are:
+Available events:
 
-- header
-- payload
-- static; for cases when no event type is present in header or payload
+| Event | When it fires |
+|---|---|
+| `webhook_received.fuik` | Event record created |
+| `webhook_processed.fuik` | `process!` completed |
+| `webhook_failed.fuik` | `process!` raised |
+| `webhook_signature_invalid.fuik` | Signature verification failed (401) |
+| `webhook_receive_error.fuik` | Unexpected error during receive (500) |
 
 
 ## Add your custom provider

data/app/assets/stylesheets/fuik/application.css

@@ -2,10 +2,17 @@
 
 @layer base {
   :root {
-    --color-text: oklch(30% 0.02 250);
-    --color-text-muted: oklch(55% 0.02 250);
-    --color-border: oklch(90% 0.01 250);
-    --color-bg-hover: oklch(97% 0.01 250);
+    --gray-50: oklch(98.7% .002 197.1);
+    --gray-100: oklch(96.3% .002 197.1);
+    --gray-200: oklch(92.5% .005 214.3);
+    --gray-300: oklch(87.2% .007 219.6);
+    --gray-400: oklch(72.3% .014 214.4);
+    --gray-500: oklch(56% .021 213.5);
+    --gray-600: oklch(45% .017 213.2);
+    --gray-700: oklch(37.8% .015 216);
+    --gray-800: oklch(27.5% .011 216.9);
+    --gray-900: oklch(21.8% .008 223.9);
+    --gray-950: oklch(14.8% .004 228.8);
   }
 
   * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -13,7 +20,8 @@
   body {
     font-family: system-ui, -apple-system, sans-serif;
     line-height: 1.5;
-    color: var(--color-text);
+    color: light-dark(var(--gray-800), var(--gray-200));
+    background-color: light-dark(white, var(--gray-950));
   }
 
   main {
@@ -22,19 +30,6 @@
     margin-inline: auto;
   }
 
-  h1 {
-    margin-block-end: 1rem;
-    font-size: 1.875rem;
-    font-weight: 700;
-    letter-spacing: -.025em;
-
-    a {
-      color: var(--color-text-muted);
-
-      &:hover { color: var(--color-text); }
-    }
-  }
-
   a {
     color: inherit;
     text-decoration: none;
@@ -47,58 +42,35 @@
     padding-block: .5rem;
     padding-inline: 1rem;
     max-height: calc(20lh + 1rem);
+    width: 100%;
     font-size: .875rem;
-    background: var(--color-bg-hover);
-    border-radius: .5rem;
+    background: light-dark(var(--gray-50), var(--gray-800));
+    border: 1px solid light-dark(transparent, var(--gray-700));
+    border-radius: .375rem;
     overflow-x: auto;
   }
+}
 
-  dl {
-    display: grid;
-    grid-template-columns: auto 1fr;
-    gap: 1rem 2rem;
-    overflow: hidden;
-
-    dt {
-      font-weight: 600;
-      color: var(--color-text);
-    }
-
-    dd {
-      position: relative;
-      overflow-x: auto;
-    }
-
-    .actions {
-      display: flex;
-      align-items: center;
-      gap: .5rem;
-      position: absolute;
-      top: .5rem; right: .5rem;
-    }
-
-    svg {
-      width: 1rem;
-      aspect-ratio: 1 / 1;
-      color: oklch(from var(--color-text) l c h / 80%);
-      background: var(--color-bg);
-    }
+@layer components {
+  .heading {
+    margin-block-end: 1rem;
+    font-size: 1.875rem;
+    font-weight: 550;
+    letter-spacing: -.0125em;
+    color: light-dark(var(--gray-700), var(--gray-100));
 
-    dd .copy-button .success-icon {
-      display: none;
+    .divider {
+      font-weight: 400;
+      color: light-dark(var(--gray-600), var(--gray-300));
     }
 
-    dd:has([data-copy-success="true"]) .copy-button .copy-icon {
-      display: none;
-    }
+    a {
+      color: light-dark(var(--gray-500), var(--gray-400));
 
-    dd:has([data-copy-success="true"]) .copy-button .success-icon {
-      display: block;
+      &:hover { color: light-dark(var(--gray-800), var(--gray-200)); }
     }
   }
-}
 
-@layer components {
   .events {
     list-style: none;
     margin-block-start: 1rem;
@@ -109,7 +81,7 @@
       padding-block: .5rem;
       padding-inline: .75rem;
 
-      &:hover { background: var(--color-bg-hover); }
+      &:hover { background: light-dark(var(--gray-50), var(--gray-800)); }
 
       a {
         display: grid;
@@ -119,6 +91,12 @@
         &:hover { text-decoration: none; }
       }
 
+      .icon {
+        width: var(--icon-width);
+        aspect-ratio: 1/1;
+        border-radius: .15rem;
+      }
+
       .name {
         display: grid;
         grid-template-columns: var(--icon-width) 1fr;
@@ -126,12 +104,6 @@
         gap: .5rem;
       }
 
-      .icon {
-        width: var(--icon-width);
-        aspect-ratio: 1/1;
-        border-radius: .125rem;
-      }
-
       code {
         display: flex;
         align-items: center;
@@ -139,7 +111,16 @@
     }
 
     li:not(:first-child) {
-      border-top: 1px solid var(--color-border);
+      border-top: 1px solid light-dark(var(--gray-100), var(--gray-800));
+    }
+
+    .empty-state {
+      display: none;
+      font-size: .875rem;
+      font-weight: 300;
+      color: light-dark(var(--gray-400), var(--gray-500));
+
+      &:only-child { display: block; }
     }
   }
 
@@ -153,7 +134,7 @@
       width: .5rem;
       aspect-ratio: 1/1;
       background-color: currentColor;
-      border: 2px solid oklch(from currentColor 1 c h / 85%);
+      border: 1.75px solid oklch(from currentColor .9 c h / .8);
       border-radius: .5rem;
     }
 
@@ -175,7 +156,7 @@
       legend {
         font-size: .875rem;
         font-weight: 400;
-        color: var(--color-text-muted);
+        color: light-dark(var(--gray-500), var(--gray-400));
       }
 
       input[type="radio"] {
@@ -185,8 +166,8 @@
 
       .pills {
         display: inline-flex;
-        background: var(--color-bg);
-        border: 1px solid var(--color-border);
+        background-color: light-dark(var(--gray-50), var(--gray-800));
+        border: 1px solid light-dark(var(--gray-200), var(--gray-700));
         border-radius: .3rem;
         overflow: clip;
 
@@ -196,7 +177,7 @@
           padding: .25rem .75rem;
           font-size: .875rem;
           font-weight: 400;
-          border-inline-start: 1px solid var(--color-border);
+          border-inline-start: 1px solid light-dark(var(--gray-200), var(--gray-700));
           cursor: pointer;
           transition: all ease-in-out 100ms;
 
@@ -204,7 +185,7 @@
 
           &:has(input:checked),
           &:hover:not(:has(input:checked)) {
-            background-color: var(--color-bg-hover);
+            background-color: light-dark(var(--gray-100), var(--gray-700));
           }
         }
       }
@@ -213,8 +194,8 @@
     select {
       padding: .4rem .75rem;
       font-size: .875rem;
-      background: var(--color-bg);
-      border: 1px solid var(--color-border);
+      background-color: light-dark(var(--gray-50), var(--gray-800));
+      border: 1px solid light-dark(var(--gray-200), var(--gray-700));
       border-radius: .25rem;
       cursor: pointer;
     }
@@ -222,39 +203,122 @@
     [type=submit] { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border-width: 0; }
   }
 
+  .details {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: 1rem 2rem;
+    overflow: hidden;
+
+    .description {
+      display: flex;
+      align-items: baseline;
+      margin-block-start: .125em;
+      font-weight: 500;
+      color: light-dark(var(--gray-700), var(--gray-400));
+    }
+
+    .icon {
+      width: 1.125rem;
+      aspect-ratio: 1/1;
+      margin-right: .25rem;
+      border-radius: .15rem;
+    }
+
+    .value {
+      position: relative;
+      display: flex;
+      align-items: center;
+      overflow-x: auto;
+
+      button { margin-left: .25rem; }
+    }
+
+    .actions {
+      display: flex;
+      align-items: center;
+      gap: .5rem;
+      position: absolute;
+      top: .5rem; right: .5rem;
+    }
+
+    svg {
+      width: 1rem;
+      aspect-ratio: 1 / 1;
+      color: light-dark(var(--gray-800), var(--gray-200));
+    }
+
+    dd .copy-button .success-icon {
+      display: none;
+    }
+
+    dd:has([data-copy-success="true"]) .copy-button .copy-icon {
+      display: none;
+    }
+
+    dd:has([data-copy-success="true"]) .copy-button .success-icon {
+      display: block;
+    }
+  }
+
   button,
   .copy-button {
     padding: .125rem;
-    background: var(--color-bg);
+    background: light-dark(var(--gray-50), var(--gray-800));
     border: 0;
     border-radius: .25rem;
     cursor: pointer;
 
     &:hover {
-      color: oklch(from var(--color-text) l c h);
+      color: light-dark(var(--gray-800), var(--gray-400));
       transition: transform ease-in-out 300ms;
-      transform: scale(1.10);
+
+      & svg { transform: scale(1.05); }
     }
   }
 
+  .retry-button {
+    display: inline-flex;
+    align-items: center;
+    gap: .25rem;
+    margin-inline-start: .5rem;
+    padding: .25rem .75rem;
+    border: 1px solid light-dark(var(--gray-200), var(--gray-700));
+  }
+
   .json-highlight {
     .json-key {
-      color: oklch(35% .15 250);
-      cursor: pointer;
+      color: light-dark(oklch(35% .15 250), oklch(70% .2 250));
 
-      &:hover {
-        background: oklch(90% 0.02 250);
+      #payload & {
+        border-radius: .125rem;
+        cursor: pointer;
+      }
+
+      #payload &:hover {
+        background: light-dark(oklch(from currentColor l c h / .1), oklch(from currentColor l c h / .2));
       }
     }
 
     .json-key-selected {
-      background: oklch(85% 0.05 250);
+      background: light-dark(oklch(85% .05 250), oklch(25% .08 250));
     }
 
-    .json-string { color: oklch(30% .18 160); }
-    .json-number { color: oklch(40% .15 130); }
-    .json-boolean { color: oklch(45% .18 260); }
-    .json-null { color: oklch(50% .05 250); }
-    .json-punctuation { color: oklch(20% .03 250); }
+    .json-string { color: light-dark(oklch(30% .18 160), oklch(72% .18 160)); user-select: all; }
+    .json-number { color: light-dark(oklch(40% .15 130), oklch(70% .18 130)); }
+    .json-boolean { color: light-dark(oklch(45% .18 260), oklch(75% .2 260)); }
+    .json-null { color: light-dark(oklch(50% .05 250), oklch(68% .08 250)); }
+    .json-punctuation { color: light-dark(oklch(20% .03 250), oklch(60% .03 250)); }
+  }
+
+  .errors {
+    padding-block: .5rem;
+    padding-inline: 1rem;
+    max-height: calc(20lh + 1rem);
+    font-size: .875rem;
+    color: light-dark(oklch(50.5% .213 27.52), oklch(88.5% .062 18.33));
+    background: light-dark(oklch(97.1% .013 17.38), oklch(25.8% .092 26.04 / .5));
+    border-radius: .5rem;
+    overflow-x: auto;
+    font-family: "Courier New", Courier, monospace;
   }
 }

data/app/controllers/concerns/fuik/event_type.rb

@@ -5,23 +5,44 @@ module Fuik
     private
 
     COMMON_EVENT_TYPE_HEADERS = [
-      "X-Github-Event",
       "X-Event-Type",
-      "X-Webhook-Event"
+      "X-Webhook-Event",
+      "Webhook-Event"
     ]
 
     COMMON_EVENT_ID_HEADERS = [
-      "X-GitHub-Delivery",
       "X-Event-Id",
-      "X-Webhook-Id"
+      "X-Webhook-Id",
+      "Webhook-Id",
+      "webhook-id"
     ]
 
     def event_type
-      from_config("event_type") || from_event_type_headers || from_payload_type || "unknown"
+      from_base_class_event_type || from_config("event_type") || from_event_type_headers || from_payload_type || "unknown"
     end
 
     def event_id
-      from_config("event_id") || from_event_id_headers || payload["id"] || Digest::MD5.hexdigest(request.raw_post)
+      from_base_class_event_id || from_config("event_id") || from_event_id_headers || payload["id"] || Digest::MD5.hexdigest(request.raw_post)
+    end
+
+    def from_base_class_event_type
+      config = base_class&.event_type_config
+
+      return if !config
+      return config if config.is_a?(String)
+      return request.headers[config[:header]] if config.key?(:header)
+
+      payload.dig(*config[:payload].to_s.split(".")) if config.key?(:payload)
+    end
+
+    def from_base_class_event_id
+      config = base_class&.event_id_config
+
+      return if !config
+      return config if config.is_a?(String)
+      return request.headers[config[:header]] if config.key?(:header)
+
+      payload.dig(*config[:payload].to_s.split(".")) if config.key?(:payload)
     end
 
     def from_config(key)
@@ -53,7 +74,11 @@ module Fuik
       @config ||= begin
         config_path = Rails.root.join("app/webhooks/#{params[:provider]}/config.yml")
 
-        File.exist?(config_path) ? YAML.load_file(config_path) : nil
+        if File.exist?(config_path)
+          Fuik.deprecator.warn("Using config.yml is deprecated. Define event_type/event_id on #{params[:provider].camelize}::Base instead.")
+
+          YAML.load_file(config_path)
+        end
       end
     end
   end

data/app/controllers/fuik/events_controller.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 module Fuik
-  class EventsController < Fuik::Engine.config.events_controller_parent.constantize
+  class EventsController < Fuik.configuration.events_controller_parent.constantize
     layout "fuik/application"
 
     def index
       @webhook_events = WebhookEvent.filtered(params).order(created_at: :desc)
+
+      respond_to do |format|
+        format.html
+        format.json { render json: @webhook_events }
+      end
     end
 
     def show