Nova Supportrays Laravel Package

Product Decisions This Supports

• Build vs. buy for in-admin support tooling. If SupportRays is already the support backend, this package turns "agents need a second tab" into "agents work inside Nova." That's a real reduction in tool sprawl and context switching, and it avoids building a bespoke ticket UI against the SupportRays API.
• Where support work lives. The decision this most directly informs: do we keep the helpdesk as a separate destination, or embed triage and replies in the admin panel where customer/order context already exists? The TicketContextProvider contract is the deciding factor — it lets the host app surface customer and order cards next to the ticket, which a generic helpdesk can't do without its own integration work.
• Identity and auditability model. Per-user linking via emailed code with an encrypted key means every action carries the individual agent's name. That's a policy decision (no shared staff token) with downstream value for QA, accountability, and incident review — worth citing when security or compliance asks "who replied to this customer?"
• Rollout scope. v0.1.0 supports triage and reply, not full helpdesk replacement (no attachment upload, local-only disconnect). That supports a phased plan: read/triage first, evaluate attachment workflow separately, revisit before mandating adoption.
• SLA and queue prioritization. Tabs with counts (awaiting reply, mine, unassigned, all active), overdue filtering, SLA timers, and a cached menu badge give a defensible answer to "how do we make sure nothing sits unanswered?" The badge's 60s cache and 3s timeout mean this visibility doesn't cost Nova performance.
• Buy-in surface for adjacent teams. Because the tool is gated (viewNovaSupportRays) and requires matching SupportRays manager emails, you can pilot with a small group before opening it broadly — a low-risk way to test whether in-admin support actually changes response times.

When to Consider This Package

Adopt when most of these hold:

• SupportRays is the system of record for support, and you run Laravel Nova 4.x (tested on 4.35) on PHP 8.2+.
• Your agents are already SupportRays managers whose emails match their Nova accounts — this is a hard prerequisite, not a nice-to-have. Any agent without a manager seat can't use the tool.
• The team's pain is context switching: reps bounce between Nova (customer, orders) and the helpdesk to answer the same ticket.
• You want per-agent attribution without standing up SSO or a shared service token.
• You're comfortable integrating against SupportRays API v0.2.0+ and pinning versions until the contract stabilizes.

Look elsewhere when:

• You don't use SupportRays, or you use a different helpdesk — nothing here is portable.
• You're on Nova 3.x or planning a Nova 5 migration; this is Nova 4-only and pre-1.0, so expect rework.
• Agents aren't SupportRays managers, or email addresses diverge between the two systems. Rewriting the linking model is not a config change.
• Attachment upload is a requirement. Downloads work, uploads don't. If reps must attach screenshots or documents to replies, they'll still need the SupportRays UI — which undermines the whole pitch.
• You need reporting, analytics, automation rules, CSAT, or multi-project routing. There's a single SUPPORTRAYS_PROJECT_UUID; this is a ticket-working surface, not an admin console.
• You need formal key lifecycle management. "Disconnect" only clears the key locally — revocation is a manual step in the SupportRays profile. That's acceptable for a pilot, awkward for offboarding at scale.
• You require vendor maturity guarantees. v0.1.0 with a dependency on an equally young API version is a pilot-grade bet, not a platform commitment.

How to Pitch It (Stakeholders)

To executives: We already pay for SupportRays; this is a thin Nova tool that puts ticket triage and replies inside the admin panel our team already uses, next to customer and order context. No new seat cost, no new system to learn, no migration. The upside is fewer tabs and faster answers; the cost is a small install and one config block. It's version 0.1.0, so I'd frame it as a scoped pilot with a small agent group rather than an org-wide rollout — we can measure time-to-first-reply before committing.

To engineering: A Laravel package installed via Composer plus one migration, registered as a Nova tool and access-controlled by a single gate. Two design choices worth noting positively: (1) identity — each Nova user links their own SupportRays account via an emailed code, key stored encrypted, no shared staff token, so audit trails are per-person by construction; (2) isolation — a restricted proxy exposes only ticket-work API roots, translates upstream 401/403 into a 409 not_connected so Nova sessions are never invalidated, returns 503 on outage, and the badge is cached 60s with a 3s timeout so a slow SupportRays can't degrade the admin panel. Extension point is a TicketContextProvider contract for host-app sidebar cards. Known gaps to plan around: no attachment upload, local-only disconnect (revoke in SupportRays manually), single project UUID, and a hard coupling to SupportRays API v0.2.0+ that we should pin.

Risks to state plainly: pre-1.0 maturity, Nova 4 lock-in, and the manager-email prerequisite — verify that mapping before promising anything, because it's the most likely reason a rollout stalls.