Add push notifications via noticed v2 (Action Push Native, paid-clients-only)

[dadachi]

Why

Walk-in queue without "your number is up" notification is barely a queue. This is the highest-impact substrate gap for the queue domain (and downstream for the nativeapptemplate-agent, since APNs/FCM credentials and provisioning are infrastructure the agent can't bootstrap from scratch — the substrate has to solve them once).

This issue tracks adding push notifications across the substrate using:

• Gem: noticed v2 with action_push_native v0.3.x as the delivery method (Apple + Google native push).
• References: noticed v2 README + the gem's own generators and source under vendor/bundle/.../noticed-2.x/. Standard Rails idioms — no proprietary template.
• Scope: API (single repo, serves both editions) ships push for everyone — open-sourced, no code-level gate. Push enforcement is at the client layer: only paid iOS/Android clients ship registration code. Free clients don't call POST /devices. The API is open; the gate is "you have to write the client to use it."

Why paid-clients-only

• API is one repo serving both editions — code-level paid-gating inside the open-source API is a leaky abstraction; anyone could remove the check. The gate belongs where the differentiation actually is (the closed-source paid clients).
• Free edition is single-shopkeeper-per-account. Push notifications about your own action are silly. Push only shines in Team SKUs (multiple staff per account); even Solo paid SKUs get marginal value (multi-device coordination).
• Free is a strict subset of paid is the established framing — paid = free + multi-tenancy + invitations + roles + push (now).
• Anyone wanting push in a free-edition fork: API endpoint is open, just write your own client registration code.

4-PR plan

#	Repo	Scope	Status	Blocked by
1	nativeapptemplateapi	Gem install · ApplicationPushDevice (subclass of ActionPushNative::Device, UUID PK + UUID polymorphic owner + bundle_id / last_active_at + unique (platform, token)) · Api::V1::Shopkeeper::DevicesController (idempotent upsert + scoped destroy) · ApplicationNotifier base + example ItemTagNotifier (state-verb-free copy: %{shop} title, %{name} body) · config/push.yml reads all deployment-specific values from credentials · credentials.yml.tt exposes the expected key paths · OpenAPI doc updated · Minitest coverage. No provider config, no AASM trigger, no client work — pure scaffolding.	PR #59 (this PR, ready)	nothing
2	nativeapptemplateapi	Provision APNs .p8 + FCM service-account JSON; populate credentials · wire ItemTagNotifier to ItemTag's AASM complete event · integration test (mocked APNs/FCM responses via :test delivery method)	not started	APNs .p8 + FCM service-account JSON
3	NativeAppTemplate (paid iOS)	APNs registration in AppDelegate · permission UX · foreground/background handlers · POST to /api/v1/shopkeeper/devices on token receipt · refresh on app start · DELETE on sign-out	not started	PR #2
4	NativeAppTemplate (paid Android)	Firebase setup template (google-services.json placeholder) · FirebaseMessagingService · POST_NOTIFICATIONS permission for API 33+ · notification channels · token sync to API · sign-out cleanup	not started	PR #2

Free iOS / Android intentionally do not get push registration code — feature naturally absent in free clients.

Open questions tracked here

1. Provider credentials: APNs .p8 + FCM service account JSON for the substrate's canonical bundle IDs (com.nativeapptemplate.*). Status: not provisioned yet. Blocks PRs test4 #2–Welcome to nativeapptemplateapi Discussions! #4.
2. Bundle ID strategy (resolved): The substrate ships push for canonical bundle IDs. Agent-renamed apps re-provision. To document in PR test4 #2.
3. noticed v1 conflicts (resolved): confirmed none — substrate API + free clients are greenfield (no rpush / apnotic / fcm / Device model anywhere).
4. Platform enum convention (resolved): device.platform is [apple, google] (matches Action Push Native's APNs/FCM service convention) instead of [ios, android]. Mobile clients (PRs [render preview]test5 #3–4) register with apple or google.

References

• noticed v2 README: https://github.com/excid3/noticed
• Action Push Native: https://github.com/Spone/action_push_native

[dadachi]

All four PRs in the plan are merged across the three repos, and the one blocking open question (provider credentials) is resolved. Closing as complete.

• PR test3 #1 — API scaffolding: Add push notifications scaffolding via noticed v2 #59
• PR test4 #2 — API credentials + AASM wiring + tests: Add APNs and FCM credentials for push notifications #66 (APNs/FCM credentials), Wire ItemTagNotifier to AASM complete event #61 (wire ItemTagNotifier to AASM complete), Test google (FCM) device registration #75 (FCM device-registration test), Connect to APNs sandbox server in development #74 (APNs sandbox in dev), Document push notification setup #76 (docs)
• PR [render preview]test5 #3 — paid iOS client: NativeAppTemplate-iOS Bump the minor-and-patch group with 3 updates #82 (APNs integration), Bump the minor-and-patch group with 4 updates #84 (3.3.0 release), Bump the minor-and-patch group with 2 updates #85 (docs)
• PR Welcome to nativeapptemplateapi Discussions! #4 — paid Android client: NativeAppTemplate-Android Fix push notification delivery crashing on send #71 (FCM integration)

Open questions: provider credentials resolved by #66; the rest were already resolved in the issue body.