Add push notifications scaffolding via noticed v2 (#59)

* 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).

* Wire deliver_by :action_push_native via Rails-native action_push_native

Install action_push_native 0.3.x and generate ApplicationPushNotification,
ApplicationPushDevice, ApplicationPushNotificationJob, and config/push.yml.
Add deliver_by :action_push_native to ItemTagCalledNotifier so push
notifications route through Rails 8.1's Action Push Native (single
abstraction over APNs + FCM) instead of the Noticed gem's per-platform
:ios / :fcm deliverers.

APNs/FCM credentials remain placeholders in config/push.yml — provision
via bin/rails credentials:edit before enabling delivery. Bridging the
existing Device registration API to ApplicationPushDevice (so registered
tokens actually flow into Action Push Native delivery) is a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Generalize notifier copy: %{number} → %{name}, drop "Number" prefix

Substrate post-Phase-1 (#45) is generic single-resource CRUD, not
queue-only — `ItemTag.name` can be a queue number ("A001"), a pet
name ("Mittens"), a task title, etc. The copy "Number %{number} is
up" only reads correctly for the queue case, and the agent's renamer
doesn't substitute the word "Number" (it's not in the rename plan),
so the wrong copy ships to every renamed app.

Change to "%{name} is ready" — generalizes cleanly across the queue,
reservation, vet-clinic, and task-tracker domains the substrate
targets. Body unchanged.

Test passes; rubocop clean.

* Generalize notifier: drop "Called" + state-verb copy (rename-resistant)

Reverses the previous "Number → name" / "is ready" decision once it
became clear that any state-verb baked into the substrate's notifier
title or class name fights the agent's domain-adapt step. The agent
extends/renames the AASM state machine per spec (idled/completed →
e.g. waiting/seated for restaurant, pending/seen for vet clinic), but
its rename plan only handles the four model-level tokens (Shop /
Shopkeeper / ItemTag / NativeAppTemplate). State names cascading into
notifier file/class/locale-key/title are out of scope for the
rename-safety contract (#57).

So the substrate's notifier ships state-verb-free:

- File:        item_tag_called_notifier.rb → item_tag_notifier.rb
- Class:       ItemTagCalledNotifier       → ItemTagNotifier
- Locale key:  notifiers.item_tag_called   → notifiers.item_tag
- Title:       "%{name} is ready"          → "%{name}"
- Body:        "Please proceed to %{shop}." → "%{shop}"

`ItemTag` itself IS in the rename plan, so file/class/locale-key
cascade through `item_tag → patient/reservation/todo` cleanly.
`%{name}` and `%{shop}` are interpolation keys, not renameable
tokens. Result: substrate copy survives any state-verb rewrite the
agent's adapt step does, at the cost of vague substrate copy. The
adapt step can rewrite richer per-domain copy when it wants.

Tests + rubocop clean.

* Swap notifier title/body: shop in title, item name in body

Push-notification UX convention is source-in-title, event-in-body —
WhatsApp (sender → message), Slack (channel → message), Calendar
(event → location). Shop is the recognizable persistent entity that
anchors the notification; item name is variable per-event content.

Title: %{name} → %{shop}
Body:  %{shop} → %{name}

Tests + rubocop clean.

* credentials.yml.tt: add action_push_native APNs + FCM placeholders

config/push.yml looks up Rails.application.credentials.dig(
:action_push_native, :apns, :key_id) and friends, but the credentials
template that seeds `bin/rails credentials:edit` on first generation
didn't expose those keys. Fresh developers would hit silent nil on
first push delivery without knowing where the lookup expected the
secret.

Adds the same shape Resend's api_key already follows: empty
placeholder under the documented key path. Comment notes which
inputs are needed (APNs key_id + .p8 contents, FCM service-account
JSON).

* push.yml: move team_id/topic/project_id to credentials too

Three deployment-specific values were still hard-coded as placeholders
in config/push.yml:

- apple.team_id    (Apple Developer team identifier — per-deployer)
- apple.topic      (iOS bundle identifier — per-deployment)
- google.project_id (Firebase project identifier — per-deployment)

These don't belong in source. apple.topic in particular is a rename-
pipeline trap: the agent renames the iOS bundle id when generating a
domain-customized variant (com.nativeapptemplate.* → com.<spec>.*),
but the rename pipeline only operates on code/locales/OpenAPI — not
on push.yml strings. So a hard-coded `your.bundle.identifier` here
silently desyncs from the renamed app's actual bundle id and push
delivery breaks with a non-obvious error.

Move all three to Rails.application.credentials.dig(:action_push_native,
...) so they're deploy-time configuration, not source-controlled
state. Add the same fields to the credentials.yml.tt template so
`bin/rails credentials:edit` exposes the expected key paths.

Tests + rubocop clean.

* openapi.yaml: document Device endpoints + schemas

Layer 1 of the agent's reviewer (per the agent's docs/SPEC.md)
checks OpenAPI parity between Rails ↔ iOS networking ↔ Android
repository layers. Adding the Device controller without the
corresponding spec entries means PRs #3-5 (the iOS/Android push
registration clients) wouldn't have a contract to integrate against
and would fail Layer 1 contract-parity scan.

Adds:
- Tag: Devices
- Path POST /devices: idempotent register; 201 on create, 200 on
  touch, 422 on validation error
- Path DELETE /devices/{deviceId}: 204 no_content, 404 if device
  isn't owned by current_shopkeeper
- Schemas: DeviceAttributes, Device, DeviceCreateRequest
  (jsonapi-style envelope to match the rest of the API)

YAML parses; paths now 25, schemas now 38.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dadachi

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [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 `ItemTagNotifier` with `deliver_by :action_push_native` wiring (Apple + Google push via Rails-native `action_push_native` 0.3.x)
+- Generate `ApplicationPushNotification` / `ApplicationPushDevice` / `ApplicationPushNotificationJob` and `config/push.yml` (APNs/FCM credentials still placeholders — provision via `bin/rails credentials:edit` before enabling delivery; ItemTag AASM trigger lands in a follow-up)
+- Note: the existing `Device` registration API (`POST /api/v1/shopkeeper/devices`) writes to the custom `Device` model, not `ApplicationPushDevice` — bridging the two (so registered tokens flow into Action Push Native delivery) is a follow-up
+- `Shopkeeper has_many :devices, :notifications`; new locale entries under `notifiers.item_tag` — title/body deliberately kept generic (`%{name}` / `%{shop}` only, no state-verbs like "completed" or "ready") so the agent's domain-adapt step can rewrite richer per-domain copy without fighting baked-in queue semantics
+- 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"
 
@@ -97,3 +102,5 @@ group :test do
   gem "selenium-webdriver", ">= 4.20.1"
   gem "webmock"
 end
+
+gem "action_push_native", "~> 0.3.1"

Gemfile.lock

@@ -3,6 +3,13 @@ GEM
   specs:
     aasm (5.5.2)
       concurrent-ruby (~> 1.0)
+    action_push_native (0.3.1)
+      activejob (>= 8.0)
+      activerecord (>= 8.0)
+      googleauth (~> 1.14)
+      httpx (~> 1.6)
+      jwt (>= 2)
+      railties (>= 8.0)
     action_text-trix (2.1.18)
       railties
     actioncable (8.1.3)
@@ -153,6 +160,12 @@ GEM
     erubi (1.13.1)
     et-orbi (1.4.0)
       tzinfo
+    faraday (2.14.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
     ffi (1.17.4-aarch64-linux-gnu)
     ffi (1.17.4-arm-linux-gnu)
     ffi (1.17.4-arm64-darwin)
@@ -164,11 +177,26 @@ GEM
       raabro (~> 1.4)
     globalid (1.3.0)
       activesupport (>= 6.1)
+    google-cloud-env (2.3.1)
+      base64 (~> 0.2)
+      faraday (>= 1.0, < 3.a)
+    google-logging-utils (0.2.0)
+    googleauth (1.16.2)
+      faraday (>= 1.0, < 3.a)
+      google-cloud-env (~> 2.2)
+      google-logging-utils (~> 0.1)
+      jwt (>= 1.4, < 4.0)
+      multi_json (~> 1.11)
+      os (>= 0.9, < 2.0)
+      signet (>= 0.16, < 2.a)
     hashdiff (1.2.1)
+    http-2 (1.1.3)
     httparty (0.24.2)
       csv
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
+    httpx (1.7.6)
+      http-2 (>= 1.1.3)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     image_processing (1.14.0)
@@ -188,6 +216,8 @@ GEM
     json (2.19.4)
     jsonapi-serializer (2.2.0)
       activesupport (>= 4.2)
+    jwt (3.1.2)
+      base64
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -232,8 +262,11 @@ GEM
       stimulus-rails
       turbo-rails
     msgpack (1.8.0)
+    multi_json (1.21.1)
     multi_xml (0.8.1)
       bigdecimal (>= 3.1, < 5)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     net-imap (0.6.4)
       date
       net-protocol
@@ -257,7 +290,10 @@ 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)
+    os (1.1.4)
     ostruct (0.6.3)
     overcommit (0.69.0)
       childprocess (>= 0.6.3, < 6)
@@ -393,6 +429,11 @@ GEM
       rexml (~> 3.2, >= 3.2.5)
       rubyzip (>= 1.2.2, < 4.0)
       websocket (~> 1.0)
+    signet (0.21.0)
+      addressable (~> 2.8)
+      faraday (>= 0.17.5, < 3.a)
+      jwt (>= 1.5, < 4.0)
+      multi_json (~> 1.10)
     smart_properties (1.17.0)
     solid_cable (3.0.12)
       actioncable (>= 7.2)
@@ -469,6 +510,7 @@ PLATFORMS
 
 DEPENDENCIES
   aasm
+  action_push_native (~> 0.3.1)
   acts_as_tenant
   after_commit_everywhere (~> 1.6)
   bootsnap (>= 1.4.2)
@@ -488,6 +530,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/jobs/application_push_notification_job.rb

@@ -0,0 +1,7 @@
+class ApplicationPushNotificationJob < ActionPushNative::NotificationJob
+  # Enable logging job arguments (default: false)
+  # self.log_arguments = true
+
+  # Report job retries via the `Rails.error` reporter (default: false)
+  # self.report_job_retries = true
+end

app/models/application_push_device.rb

@@ -0,0 +1,4 @@
+class ApplicationPushDevice < ActionPushNative::Device
+  # Customize TokenError handling (default: destroy!)
+  # rescue_from (ActionPushNative::TokenError) { Rails.logger.error("Device #{id} token is invalid") }
+end

app/models/application_push_notification.rb

@@ -0,0 +1,12 @@
+class ApplicationPushNotification < ActionPushNative::Notification
+  # Set a custom job queue_name
+  # queue_as :realtime
+
+  # Controls whether push notifications are enabled (default: !Rails.env.test?)
+  # self.enabled = Rails.env.production?
+
+  # Define a custom callback to modify or abort the notification before it is sent
+  # before_delivery do |notification|
+  #   throw :abort if Notification.find(notification.context[:notification_id]).expired?
+  # 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