Add push notifications scaffolding via noticed v2

PR #1 of 5 in #58. Scaffolds the Rails-side groundwork for native push
notifications. Provider integration (APNs + FCM) and ItemTag AASM
wiring follow in PR #2 once APNs .p8 and FCM service-account JSON are
provisioned. Client work (free + paid iOS/Android) follows in PRs #3-5.

What lands here
- noticed v2 gem + the two engine migrations (Noticed::Event,
  Noticed::Notification, both UUID-keyed to match this substrate's
  primary_key_type)
- Device model + migration: shopkeeper-scoped, unique on
  [platform, token], last_active_at for staleness scoping; ios/android
  enum
- Api::V1::Shopkeeper::DevicesController:
    POST /api/v1/shopkeeper/devices  — idempotent upsert (rebinds token
                                       to current_shopkeeper if it
                                       previously belonged to someone
                                       else, e.g. shared device after
                                       sign-out/sign-in); 201 on
                                       create, 200 on touch
    DELETE /api/v1/shopkeeper/devices/:id — unregister (404 on someone
                                            else's device, scoped via
                                            current_shopkeeper.devices)
- DevicePolicy + DeviceSerializer following existing substrate
  conventions (BasePolicy + JSONAPI::Serializer)
- ApplicationNotifier base + example ItemTagCalledNotifier (no
  delivery methods wired yet — title/body/url are i18n-resolved via
  notification_methods so PR #2 just needs to add deliver_by :ios +
  :android and trigger from ItemTag's AASM complete event)
- Shopkeeper.has_many :devices (dependent: :destroy) and
  :notifications (as: :recipient, class: Noticed::Notification)
- Locale entries under notifiers.item_tag_called

Tests: 21 new runs (Device model 9, DevicesController 8, notifier 4),
0 failures. Full suite now 419 runs / 868 assertions / 0 failures /
0 errors / 0 skips. rubocop clean (239 files, 0 offenses).

Author: dadachi

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## 2026-05-10
+
+- Add push notifications scaffolding via `noticed` v2 (#58)
+- New `Device` model + migration (UUID primary key, unique on `[platform, token]`, `last_active_at` for staleness scope)
+- New `Api::V1::Shopkeeper::DevicesController` — POST `/devices` is idempotent upsert (rebinds token to current shopkeeper); DELETE `/devices/:id` unregisters
+- Add `ApplicationNotifier` base class + example `ItemTagCalledNotifier` (no provider config yet — APNs / FCM delivery + ItemTag AASM wiring land in PR #2 once credentials are provisioned)
+- `Shopkeeper has_many :devices, :notifications`; new locale entries under `notifiers.item_tag_called`
+- 21 new test runs (Device model + DevicesController + notifier); full suite still 0 failures
+
 ## 2026-05-02
 
 - Phase 1: Rails API substrate v2 refactor (#45) — turn queue-specific template into generic single-resource CRUD substrate (Shop → ItemTag)

Gemfile

@@ -55,6 +55,11 @@ gem "importmap-rails"
 gem "tailwindcss-rails", "~> 4.0"
 gem "rack-attack"
 gem "resend"
+
+# Push notifications via APNs (iOS) and FCM (Android). Provider integration
+# (apnotic + googleauth + initializer with credentials) lands in a follow-up
+# PR; this PR scaffolds the model + controller + base notifier only.
+gem "noticed", "~> 2.7"
 # Fix LoadError: cannot load such file -- csv
 gem "csv", "~> 3.3"
 

Gemfile.lock

@@ -257,6 +257,8 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.3-x86_64-linux-gnu)
       racc (~> 1.4)
+    noticed (2.9.3)
+      rails (>= 6.1.0)
     orm_adapter (0.5.0)
     ostruct (0.6.3)
     overcommit (0.69.0)
@@ -488,6 +490,7 @@ DEPENDENCIES
   minitest-mock
   mission_control-jobs
   nokogiri (>= 1.12.5)
+  noticed (~> 2.7)
   overcommit
   pagy (~> 43)
   pg

app/controllers/api/v1/shopkeeper/devices_controller.rb

@@ -0,0 +1,45 @@
+class Api::V1::Shopkeeper::DevicesController < Api::V1::Shopkeeper::BaseController
+  before_action :set_device, only: %i[destroy]
+
+  # POST /api/v1/shopkeeper/devices
+  #
+  # Idempotent registration. Same (platform, token) tuple on a re-POST
+  # updates last_active_at instead of creating a duplicate. Re-binding a
+  # token to a different shopkeeper (e.g. user signed out + new user
+  # signed in on same device) reassigns the device row.
+  def create
+    authorize Device
+
+    device = Device.find_or_initialize_by(
+      platform: device_params[:platform],
+      token: device_params[:token]
+    )
+    device.shopkeeper = current_shopkeeper
+    device.bundle_id = device_params[:bundle_id]
+    device.last_active_at = Time.current
+
+    if device.save
+      render json: DeviceSerializer.new(device).serializable_hash, status: device.previously_new_record? ? :created : :ok
+    else
+      render_validation_error(device)
+    end
+  end
+
+  # DELETE /api/v1/shopkeeper/devices/:id
+  def destroy
+    authorize @device
+
+    @device.destroy
+    head :no_content
+  end
+
+  private
+
+  def set_device
+    @device = current_shopkeeper.devices.find(params[:id])
+  end
+
+  def device_params
+    params.require(:device).permit(:token, :platform, :bundle_id)
+  end
+end

app/models/device.rb

@@ -0,0 +1,18 @@
+class Device < ApplicationRecord
+  belongs_to :shopkeeper
+
+  enum :platform, {ios: "ios", android: "android"}
+
+  validates :token, presence: true, uniqueness: {scope: :platform}
+  validates :platform, presence: true
+
+  scope :active, -> { where("last_active_at > ?", 90.days.ago) }
+
+  before_validation :touch_last_active_at, on: :create
+
+  private
+
+  def touch_last_active_at
+    self.last_active_at ||= Time.current
+  end
+end

app/models/shopkeeper.rb

@@ -12,6 +12,8 @@ class Shopkeeper < ApplicationRecord
   has_many :created_shops, class_name: "Shop", foreign_key: :created_by_id, inverse_of: :created_by
   has_many :created_item_tags, class_name: "ItemTag", foreign_key: :created_by_id, inverse_of: :created_by, dependent: :nullify
   has_many :completed_item_tags, class_name: "ItemTag", foreign_key: :completed_by_id, inverse_of: :completed_by, dependent: :nullify
+  has_many :devices, dependent: :destroy
+  has_many :notifications, as: :recipient, dependent: :destroy, class_name: "Noticed::Notification"
 
   attribute :token, :string
   attribute :client, :string

app/notifiers/application_notifier.rb

@@ -0,0 +1,2 @@
+class ApplicationNotifier < Noticed::Event
+end

app/notifiers/item_tag_called_notifier.rb

@@ -0,0 +1,18 @@
+class ItemTagCalledNotifier < ApplicationNotifier
+  notification_methods do
+    def title
+      I18n.t("notifiers.item_tag_called.title", number: record.name)
+    end
+
+    def body
+      I18n.t("notifiers.item_tag_called.body", shop: record.shop.name)
+    end
+
+    def url
+      Rails.application.routes.url_helpers.api_v1_shopkeeper_shop_item_tag_path(
+        shop_id: record.shop_id,
+        id: record.id
+      )
+    end
+  end
+end

app/policies/api/shopkeeper/device_policy.rb

@@ -0,0 +1,9 @@
+class Api::Shopkeeper::DevicePolicy < Api::Shopkeeper::BasePolicy
+  def create?
+    true
+  end
+
+  def destroy?
+    record.shopkeeper_id == accounts_shopkeeper.shopkeeper_id
+  end
+end

app/serializers/device_serializer.rb

@@ -0,0 +1,10 @@
+class DeviceSerializer
+  include JSONAPI::Serializer
+
+  attributes :token,
+    :platform,
+    :bundle_id,
+    :last_active_at,
+    :created_at,
+    :updated_at
+end