Nova Supportrays Laravel Package

Technical Evaluation

Architecture fit: The package is a Nova tool that delegates helpdesk operations to SupportRays rather than reimplementing ticket storage in Laravel. Per-user account linking with encrypted keys and no shared staff token is a good least-privilege design. The TicketContextProvider contract lets the host app inject domain context without forking the package. The safe proxy keeps SupportRays failures from affecting Nova authentication.

Integration feasibility: Installation is straightforward for a Laravel/Nova team: composer require, migrate, register the tool in NovaServiceProvider::tools(), define the viewNovaSupportRays gate, and set environment configuration. The main prerequisite is identity alignment: each Nova user must be a SupportRays manager with the same email address. This is feasible but needs validation in staging.

Technical risk: v0.1.0 is early-stage. Key risks include Nova 4-only compatibility, API contract drift with SupportRays v0.2.0+, email-based identity coupling, manual key revocation on disconnect, polling load, and no attachment upload. The proxy’s 409/503 mappings and allowed API roots should be security-reviewed. Pin package and API versions, stage the rollout, and define an offboarding/revocation runbook.

Key questions: What is the maintenance and support commitment for this package? Is there test coverage and a security review? How are encrypted keys managed and rotated? What are SupportRays API rate limits, pagination behavior, and search scope? Does the gate support granular roles? Is multi-project support needed? What audit logging exists? What is the Nova 5 upgrade path? Can revocation be automated beyond local key removal? How are 409/503 and badge failures observable?

Integration Approach

Stack fit: Fits Laravel + Nova 4 + PHP 8.2+ environments already using SupportRays. It is best suited to back-office/support teams working inside Nova, not as a standalone helpdesk replacement.

Migration path: Initial rollout only. Configure the SupportRays project and API access, verify manager accounts and matching emails, install the package, run migrations, register the tool, define the gate, set required environment variables, and pilot with a small support group. No legacy ticket data migration is implied; the main data created is per-user connection records.

Compatibility: Nova 4.x, tested on 4.35; PHP 8.2+; SupportRays API v0.2.0+. Nova 5 is not stated as supported. SupportRays API has no stated upper bound, so composer and API versions should be pinned and tracked. Validate gate behavior and tool registration against the host app’s Nova setup.

Sequencing: Confirm SupportRays project/API readiness and manager email alignment; security-review the proxy, gate, and key storage; install and configure in staging; test linking, ticket actions, and host context cards; test 409 not_connected, 503 outage, badge timeout, and attachment download; define revocation/offboarding; pilot; then production rollout with monitoring.

Operational Impact

Maintenance: Third-party v0.1.0 package with a small footprint but dependencies on Nova and the SupportRays API. Assign an owner for upgrades, API compatibility checks, and per-user key lifecycle. No shared token simplifies revocation scope but increases reliance on user-level account management.

Support: Users need a clear self-service linking flow via email code. Support staff need runbooks for email mismatch, 409 not_connected, 503 outages, failed attachment downloads, and manual revocation in SupportRays. The Russian-language tabs may require localization expectations to be set. Attachment upload is not available and should be communicated.

Scaling: Inbox refreshes every 60 s, ticket page every 20 s, and the badge is cached 60 s per user with a 3 s timeout. The badge design protects Nova from slow SupportRays responses, but ticket polling and search/filter usage should be validated against API rate limits and large ticket volumes. Confirm pagination and server-side search behavior.

Failure modes: SupportRays 401/403 becomes 409 not_connected, avoiding Nova logout; outages return 503; badge timeouts degrade safely. Residual risks include stale badge counts, failed replies despite idempotency, key decryption issues, email mismatch blocking connection, and attachment download failures. Monitor 409/503 rates, API latency, and connection errors.

Ramp-up: Moderate. Installation is simple, but rollout requires coordination between Nova admins, SupportRays admins, and support staff. Pilot with a small group, validate identity mapping and gate access, train users on tabs, internal notes, SLA timers, and disconnect/revoke steps, then expand conservatively given the early version.