Nova Api Laravel Package

Technical Evaluation

Architecture fit. orca-services/nova-api is a thin, purpose-built HTTP SDK for a single upstream service (NOVA), not a framework package. It has no obvious Laravel service provider, config publishing, or facade — so it lands in the infrastructure/adapter layer of a hexagonal or repository-pattern Laravel codebase, behind a domain-owned port (NovaGateway interface). That is a good fit if we treat it as a replaceable edge adapter and never let its DTOs leak into domain code. It is a poor fit as a core dependency, because an archived SDK becomes architecture by default the moment business logic couples to it.

Integration feasibility. Low technical effort, moderate governance effort. Composer install is straightforward (MIT, PHP package), and the request/response surface is presumably PSR-7/PSR-18-compatible or Guzzle-based, so it can sit alongside Laravel's Http client. The real integration work is contract discovery: the client's method signatures and DTOs are effectively the only machine-readable description of the NOVA API we have, so we should mine them for endpoint shapes, auth flow, and pagination semantics before writing a single line of integration code.

Technical risk. Concentrated and asymmetric:

• Abandonment (high). Repository is archived, 1 star, 0 dependents. There will be no PHP 8.4/8.5 fixes, no Guzzle 8 support, no security patches. Every future upgrade is ours to absorb.
• Unknown production exposure (high). Zero dependents means effectively zero field validation — error handling, retry behaviour, and edge-case responses are unproven. Assume nothing about 429/5xx handling until we test it.
• Metadata integrity (medium). The listed last release date (2026-06-25) is ahead of the current date and the project is simultaneously archived. That combination usually means a final tag-and-archive, but it should be verified directly against Packagist/tags before it appears in a dependency audit.
• Supply chain (low). Small, MIT-licensed, no transitive dependency weight expected. The risk is disappearance, not malice.
• Business continuity (high, non-technical). NOVA appears to be an Orca Services platform API. The durable dependency is the vendor relationship, not the library.

Key questions.

1. Is NOVA an Orca-operated service we have a commercial agreement with, or a third party resold through Orca? Who is our account contact and what is the deprecation-notice commitment?
2. Is there an OpenAPI/Swagger spec, changelog, or versioning policy for NOVA? If yes, the SDK is disposable scaffolding. If no, the SDK is our only spec and must be preserved.
3. What is the auth model — API key, OAuth2 client credentials, mTLS — and what are the token lifetimes and rotation requirements?
4. What are the published rate limits, SLAs, and error taxonomy?
5. Does NOVA carry PII or regulated data, and where is it hosted (data residency, DPA coverage)?
6. What is the support path when the archived library breaks: GitHub (dead) or commercial support channel?

Integration Approach

Stack fit. Target: Laravel 11/12 on PHP 8.2+. The SDK should be wrapped, not consumed directly. Pattern:

• App\Infrastructure\Nova\NovaClientAdapter implements App\Domain\Contracts\NovaGateway.
• Bind in a dedicated NovaServiceProvider with credentials sourced from config/services.php and secrets from the environment/secret manager — never from a committed config file.
• Map SDK DTOs to our own value objects at the boundary so an upstream API change is a one-file fix.
• Route through Laravel's HTTP client (or a shared Guzzle instance) for consistent middleware: logging, correlation IDs, retry with exponential backoff, circuit breaking. Strip or override the SDK's own transport if it duplicates this.

Migration path. Do not depend on the Packagist artifact from a public, archived repo long-term. Options, in order of preference:

1. Fork into a private VCS repo (orca-services/nova-api → ourorg/nova-api), pin to the final tag, and add a README note that we own it. Composer vcs repository entry, version-pinned.
2. Vendor the source into packages/nova-api in a monorepo if we only need a handful of endpoints — often the cheaper end state for a client of this size.
3. Reimplement the subset we need against the NOVA HTTP API using Laravel's Http client, using the SDK purely as reference documentation. Preferred if we touch fewer than ~10 endpoints.
4. Continue consuming the archived public package only for a short, time-boxed spike.

Compatibility. Before adopting, verify in composer.json: PHP constraint (^7.x vs ^8.x), Guzzle major version (a Guzzle 6 pin will conflict with modern Laravel), PSR interface versions (http-client 1.x vs 2.x), and whether the package declares a php-http/discovery dependency. Run composer why-not against our target Laravel version. If constraints are stale, forking with a relaxed composer.json is usually a 30-minute fix — but it is a fork we now maintain.

Sequencing.

1. Week 0 — discovery. Read the SDK source, extract the endpoint/DTO inventory into an internal API reference doc. Confirm the vendor relationship and support terms with Orca.
2. Week 1 — spike. Authenticate against a NOVA sandbox, exercise create/read/update plus one failure path (401, 429, 5xx). Validate rate limits and payload sizes empirically.
3. Week 2 — decide. Build-vs-adopt call: fork-and-wrap vs. reimplement-the-subset. Document the decision with the maintenance estimate attached.
4. Week 2–3 — adapter + contract tests. Build the port/adapter, back it with recorded-fixture contract tests so upstream drift surfaces as a test failure rather than a production incident.
5. Week 3 — feature-flag rollout. Ship dark, then canary by tenant/customer segment. Keep a kill switch that degrades to a queued retry rather than a hard failure.

Operational Impact

Maintenance. This is the dominant cost and it is entirely ours. Upstream is archived, so budget an explicit owner (a named engineer, not "the team") and a standing allocation of roughly 1–2 days per quarter for dependency bumps and contract verification, plus a re-audit at every Laravel major upgrade. Treat the fork as a first-class internal package with its own changelog and version tags — otherwise it silently rots until an upgrade forces the issue.

Support. There is no upstream support channel. Escalation runs through the Orca commercial relationship, which means API breakages are resolved at business speed, not engineering speed. Get the deprecation/notice commitment in writing; if Orca will not commit to notice periods, plan for the integration to fail closed and degrade gracefully rather than assume smooth sailing.

Scaling. The client itself is stateless and trivially horizontally scalable — it will not be our bottleneck. Throughput is bounded by NOVA's rate limits and latency. Plan for: per-tenant token/rate budgeting, connection reuse via a shared Guzzle handler, async/batched calls where the API supports them, and a queue in front of any write path so that upstream slowness does not propagate into request latency. Explicit timeouts and a circuit breaker are mandatory, not optional.

Failure modes to instrument and alert on.

• Contract drift — NOVA adds/renames a field and the archived DTO deserialisation silently nulls it. Mitigated by contract tests and strict DTO validation.
• Auth expiry — token refresh paths are the most common unexercised code in a low-adoption SDK; test the refresh-on-401 path explicitly.
• 429/5xx handling — assume the SDK does not do this correctly until proven; own retry policy in middleware.
• Dependency conflict on upgrade — the archived package blocks a Laravel or Guzzle major bump and becomes a schedule risk; identify this in the first sprint, not at upgrade time.
• Package disappearance — archived public repos can be deleted. The fork/mirror step is what removes this risk; do it before, not after, the first production deployment.
• PHP deprecation creep — unpinned PHP constraints turn deprecation notices into hard errors on a minor bump.

Ramp-up. Code comprehension is cheap — this is a small library that a mid-level PHP developer can read in half a day. The genuine ramp-up cost is NOVA domain knowledge: its resource model, pagination, idempotency semantics, and error taxonomy, none of which are documented outside the source. Expect ~1 sprint from kickoff to a production-ready, observable, feature-flagged integration, with the bulk of that time spent on contract discovery and failure-path testing rather than on wiring up the client.

Bottom line. Adopt as a reference implementation and short-term accelerator, not as a durable runtime dependency. The strategic value here is the API contract encoded in the source and the commercial relationship behind it; the library itself is scaffolding we should expect to own, fork, or replace within two quarters.