Guide

CLI Helper App

ABM Warranty includes a dedicated login-item helper app to keep local warranty notifications working even when the main app is closed.

Why the Helper Exists

The core app can only evaluate notification candidates while it is running. For managed notification behavior, that is not sufficient. Users expect alerts to continue after logout/login cycles, app restarts, and normal desktop workflows where the app is closed. The helper provides this continuity by running as a login-item runtime and executing the same evaluation engine used by the app path.

Architecture Summary

  • Main app computes and publishes a tenant-scoped snapshot to shared app-group storage.
  • Helper reads that snapshot and transforms it into notification events.
  • Shared engine applies suppression, cadence, and dedupe rules.
  • UserNotifications posts local alerts with deep-link payloads.
  • App open path resolves payloads to tenant/device detail or filter fallback.

How It Works with Login-Items

Helper registration is handled through SMAppService.loginItem(identifier:) so notification behavior can be managed through a system-supported login-item path. When notifications are enabled, ABM Warranty registers breelabs.ABM-Warranty.NotificationHelper. When notifications are disabled, the app unregisters that helper so background notification evaluation stops with the same policy boundary used in the UI.

Runtime helper state is observable through statuses such as enabled, requiresApproval, notFound, and notRegistered. This gives operators a concrete way to confirm whether the login-item path is active and approved. The helper is bundled with the app at ABM Warranty.app/Contents/Library/LoginItems/ABM Notification Helper.app, keeping deployment and registration tied to the same signed app package.

Data Flow and Contracts

The helper reads tenant snapshot data from widget.snapshot.activeTenant in app-group defaults. That snapshot contains summary counts and prequalified device lists for Needs Attention and Expiring Soon, which lets the helper evaluate notification candidates without recomputing upstream coverage state. This keeps runtime behavior aligned with the app-open path.

Notification behavior is governed by shared keys including notifications.enabled, notifications.frequency, and notifications.lastSentMap, with suppression stored in notification_suppression inside shared SQLite storage. Posted notification payloads include tenantID, deviceID, serialNumber, category, and timestamp fields so the app can resolve deep links and preserve deterministic dedupe logic per tenant/device/category.

Runtime Behavior

Current helper cadence is a 30-minute interval timer plus an immediate launch evaluation.

At launch, the helper performs an immediate evaluation pass so users do not have to wait for the first timer cycle to detect pending notifications. While running, it continues periodic evaluation on the 30-minute schedule. This pattern balances responsiveness with predictable local background work.

Evaluation is intentionally gated. Runs are skipped when notifications are disabled, when notification authorization is unavailable, or when no valid snapshot is present. For eligible candidates, dedupe is enforced per tenant/device/category using last-sent timestamps, and suppressed devices are excluded for that tenant context so muted records stay muted across cycles.

Security & Sandboxing

The helper target runs sandboxed and is constrained by app entitlements, which keeps its runtime scope narrow and purpose-built for notification workflows. Shared app-group access is explicit and limited to notification and state exchange, rather than broad data access, so helper behavior remains bounded to the same domain as the notification pipeline.

Credential authority remains in the app credential flows, and private key material is not moved into helper scope. ABM Warranty also does not rely on an APNs or push backend for this feature path. Notifications are local system notifications, which keeps delivery behavior local-first and consistent with desktop sandbox expectations.

Why This Is Critical to Managed Notifications

Managed environments need notification continuity even when the primary UI is not open. The helper provides that continuity by carrying the same policy model into a login-item runtime, so alerts still evaluate across app restarts, logout/login cycles, and typical desktop usage where the app may not stay foregrounded.

This also prevents policy drift between app-open and app-closed behavior. Suppression, cadence, and dedupe decisions remain deterministic because both paths operate against the same contracts and shared state. The result is a consistent notification experience that mirrors what administrators configure in the app.

Operations and Diagnostics

Use CLI commands to validate helper state and end-to-end notification behavior: 

abm-warranty notifications status
abm-warranty notifications run-once
abm-warranty notifications fire-test
abm-warranty notifications fire-test -v

If alerts do not appear:

  1. Confirm helper status is enabled.
  2. Confirm macOS notification authorization is granted.
  3. Confirm the target device is not in Notifications Muted.
  4. Run fire-test -v to verify local delivery path.
  5. Validate snapshot presence and tenant context before run-once checks.