Recommerce Laravel Package

Technical Evaluation

What this appears to be. splash/recommerce is a connector package for the Splash ReCommerce OpenAPI, distributed from a self-hosted GitLab instance (gitlab.com/splash-connectors) rather than Packagist. The "(Embedded)" qualifier suggests it is intended to be dropped into a host application and driven in-process — a service-provider-registered HTTP client with config, DTOs, and auth handling — rather than a standalone service or SDK published for general consumption.

Architecture fit. The shape is conventional for Laravel: a ServiceProvider registering a singleton client, a publishable config file for base URL and credentials, and a facade or injectable interface. That fits a Laravel monolith or modular app cleanly. The open question is whether the package is a thin, stateless HTTP wrapper (good — low coupling, easy to reason about) or whether it smuggles in queue jobs, models, migrations, or an event layer (bad — it would couple our domain to a vendor's opinionated persistence). Until we read the source, assume the worse case and budget for an isolation layer.

Integration feasibility. Technically low-friction in the happy path: composer require against a VCS repository, publish config, set env vars, inject the client. The real friction is everything around that — no Packagist metadata, no version constraints we can trust, no README surfaced in the package record, no CI badge, no license field visible. We cannot currently answer "what version do we pin and what does a breaking change look like."

Technical risk. High, and concentrated in provenance rather than code quality. Zero stars, zero dependents, and a score of 0 mean there is no external corroboration whatsoever: nobody has publicly adopted it, no issue history to mine for known failure modes, no third-party audit trail. A single-maintainer GitLab repo with no dependents is a bus-factor-of-one dependency for a revenue-adjacent integration. Secondary risks: OpenAPI-generated clients churn hard on spec revisions (renamed fields, nullable drift, enum expansion) and usually arrive with no semver discipline; credential and token-refresh handling is frequently the least-tested part of connectors like this; and "embedded" may imply assumptions about how the host app is deployed (single tenant, one credential set) that break in multi-tenant or multi-storefront setups.

Key questions.

• Is the client generated from the OpenAPI spec, hand-written, or a mix — and is the generator and spec version recorded in the repo?
• What is the release/versioning discipline? Are there tags we can pin, or only dev-main?
• License and redistribution terms — can we vendor or fork it if the maintainer disappears?
• Does it own any migrations, models, or queue workers, or is it purely transport?
• How are credentials, token refresh, and per-tenant credential isolation handled?
• What is the test posture — are there contract tests against the live OpenAPI, or only mocked HTTP?
• Who maintains it, and is that person inside our organization or a counterparty?

Integration Approach

Stack fit. Presumes PHP 8.x and a Laravel version in the 9–11 band; that must be verified against composer.json before anything else. If the constraint floor is stale, we are trading a dependency upgrade problem for an integration problem. It also assumes Guzzle is acceptable as the transport — fine in most Laravel apps, but worth confirming it does not pin a Guzzle major that conflicts with our existing HTTP clients.

Migration path. There is nothing to migrate from if this is greenfield. If we already talk to ReCommerce via hand-rolled HTTP calls, the migration is mechanical but should be staged behind an interface we own (ReCommerceGateway) so the package is swappable. Adopt the package behind our own port; never let its DTOs and exceptions leak into controllers, jobs, or domain services. That single decision converts "vendor lock-in" into "replaceable adapter" and is the highest-leverage thing we control.

Compatibility. Three axes to check in a one-day spike: Laravel/PHP version constraints, Guzzle/PSR-18 compatibility with the rest of the dependency graph, and OpenAPI spec version alignment with the ReCommerce API version we are contractually pointed at. A mismatch on the third is the most expensive, because it means either upgrading the API surface we use or patching the connector ourselves.

Sequencing.

1. Vendor due diligence: read the source, check license, confirm maintainer relationship. Gate everything on this.
2. Dependency-resolution spike in a throwaway branch — composer require and confirm no conflicts.
3. Contract test against a sandbox ReCommerce tenant: auth, one read, one write, one error path, one rate-limit response.
4. Wrap behind our own gateway interface and land that with the spike's learnings baked in.
5. Only then wire it into production paths, feature-flagged, starting with read-only operations.

Operational Impact

Maintenance. This is the dominant cost. An unpinned, single-maintainer connector means we are effectively self-insuring: assume we will fork it within twelve months and budget accordingly. If the OpenAPI spec is versioned and the connector tracks it, plan for a dependency bump each time ReCommerce ships a spec revision — that is a recurring calendar item, not a one-off. Assign explicit ownership; unowned connector packages rot silently and then fail at the worst moment.

Support. No community, no Stack Overflow corpus, no issue tracker we can watch. Support is whatever the maintainer relationship is, plus our own engineers reading the source. That is acceptable for a low-blast-radius integration and unacceptable for anything on the order or payment path unless we have forked and can patch in-house.

Scaling. Stateless HTTP wrappers scale with the host app — no new capacity model, no new deployment unit. The scaling ceiling is the remote API's rate limits and our retry/backoff discipline, not the package. Two caveats: confirm the client exposes timeouts and connection-pool reuse rather than hardcoding defaults, and confirm credential handling is per-request rather than a process-wide singleton, or multi-tenant fan-out will serialize badly or leak credentials across tenants.

Failure modes. Expect the usual connector set: auth token expiry handled poorly (surfaces as 401 storms under load), no distinction between retryable and terminal errors, timeouts defaulting to zero (hanging PHP-FPM workers), unhandled 429s with no backoff, and silent DTO coercion when the API returns a new enum value. Each is cheap to mitigate if the package exposes the seams (custom middleware, injectable HTTP client, typed exceptions) and expensive if it does not. Verify seam availability during the spike; it is the deciding factor between "usable" and "fork immediately."

Ramp-up. Low for a Laravel developer — the service-provider-plus-config pattern is idiomatic and the surface is small. The real ramp-up cost is institutional knowledge about ReCommerce's API semantics, which the package does not supply; that has to come from the OpenAPI spec and sandbox experimentation. Estimate one engineer-week to a confident, wrapped, tested integration, contingent on sandbox access being granted promptly.

Recommendation. Proceed with a time-boxed spike, not an adoption. The technical form factor is a good fit; the supply-chain signals are bad enough that we should treat the package as a reference implementation and be prepared to fork or regenerate the client from the OpenAPI spec ourselves. The isolation layer behind our own gateway interface is non-negotiable regardless of what the spike finds.