Relesys Users Laravel Package

Product Decisions This Supports

• Build vs. buy for integration plumbing. The package resolves the cheapest half of a Relesys integration — HTTP client, auth wiring, DTOs, enums, patch objects, sort/filter/pagination. The PM decision it enables is a clean split: "we buy the transport, we build the user lifecycle." Everything above the wire (system-of-record policy, sync strategy, retries, backfill, conflict resolution, audit trail) stays in our backlog and our estimate.
• Feature feasibility and scoping for Relesys-adjacent features. Because resource accessors and method names map 1:1 to Relesys's published v1.1 endpoint sections (users, departments, userGroups, customFields, communication), stories and acceptance criteria can be written directly against the vendor's docs rather than an invented abstraction. That shortens refinement and reduces "we thought the API did X" surprises.
• Roadmap candidates it unblocks. Automated onboarding/offboarding (create user → assign department → add user groups → flip UserStatus), org-structure sync (departments, primary/secondary departments), user group and custom-field maintenance, bulk user exports for reporting, and message/template delivery via the communication endpoints. Each is a discrete, demoable slice — good for early value delivery.
• Sequencing decisions. The package is only relevant after the Relesys buy decision and the relesys.api.users scope grant. That makes it an explicit gate in the plan rather than a parallel workstream, and it prevents staffing integration engineering ahead of a contract and a data-processing review.
• Estimation and staffing confidence. Integration code is hours-to-days, not a sprint. The real critical path is credentialing, scope approval, DPA/data-residency review, and agreeing who owns reconciliation. This reframes the roadmap conversation from "can we build it?" to "who signs off and how long does access take?"
• Team-composition and vendor-support posture. Adopting means accepting a single-maintainer, 0-star, 0-dependent dependency. The PM decision is whether we fork and pin (cheap, days) or write a thin internal adapter. Either is defensible; drifting on a floating version constraint is not.
• Platform-version planning. Package majors track Laravel majors (v2 → Laravel 11, v4 → Laravel 13 + PHP 8.3). Framework upgrade planning must include a coordinated package version bump; this is a known, budgetable line item rather than a mid-upgrade surprise.

When to Consider This Package

Consider it when:

• Relesys is already contracted, and relesys.api.users access is granted or clearly obtainable.
• The host application is Laravel (10–13, per the major you adopt) on a PHP floor you actually run.
• The need is read/write access to Relesys user data — users, departments, user groups, custom fields, messages — with sorting, filtering, and page-number pagination.
• You want typed entities and enums instead of raw array payloads, so review and QA don't require a PHP specialist.
• You are willing to fork or vendor the source under your org and pin an exact version, and you value the included testbench + request-faking harness as a starting point for contract tests against API drift.
• You can absorb a half-day of ground-truthing: the README's install command (getsno/relesys-api) doesn't match the package name (getsno/relesys-users), and the stated PHP 8.1 / Laravel 10 support contradicts the v4.0.0 release requiring PHP 8.3 / Laravel 13.

Look elsewhere (or build an internal adapter) when:

• Relesys is not yet purchased — this package is irrelevant until that decision is made; don't staff around it.
• You need a local user store, Eloquent models, sync/reconciliation logic, caching, queueing, or audit trails. The package is a client, not a system of record and not a sync engine.
• You need webhooks, event delivery, or real-time user-change notifications. There is no event surface; polling is the only option.
• You need cursor-stable pagination or snapshot consistency for large bulk syncs — the API is page-number based, so drift and duplicates must be handled by design.
• You need vendor-backed SLAs, support contracts, or a security review sign-off on a community dependency.
• The stack is not Laravel, or you're targeting a PHP/Laravel combination not covered by an available major.
• You need compliance, RBAC, or consent guarantees "for free" — validate against the vendor contract before committing anything to the roadmap.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed Laravel SDK that shortcuts the mechanical part of integrating with Relesys — roughly days of engineering instead of weeks — and it costs nothing to adopt. It does not make Relesys our user database, and it does not reduce vendor risk: pricing, rate limits, data residency, and deprecation policy remain Relesys's to set. The ask is modest: approve forking the source under our org and pinning an exact version, and accept that the real schedule driver is credentialing and legal review, not code.

For engineering: Thin facade over the Relesys User Management v1.1 API with typed entities, UserPatch builders, UserStatus enums, and an ApiQueryParams builder for filter/sort/limit/page. Config is two env vars. Test suite is testbench-based, fakes requests by default and supports live mode via phpunit.xml, with Docker included — a usable harness for drift detection. Caveats to plan for: single maintainer and no community (fork and pin, don't float ^), semver majors have carried real breakage (readonly properties, removed value objects, enum case renames), credentials are env-only with no documented token refresh or rotation, and the API has quirks the SDK only partly papers over (e.g., customFields rejecting empty arrays). Treat retries, idempotency, backoff, and reconciliation as our scope.

The decision to make now: confirm Relesys contract status, name the owner and lead time for the relesys.api.users scope grant, decide whether Relesys is the system of record or a sync target (and who signs off on the conflict rule), and commit to fork-and-pin. If any of those can't be answered, the right move is to defer adoption rather than start integration work.