Vantage Laravel Package

Product Decisions This Supports

• Build vs. buy on integration surface. v0.1.25 adds an optional REST/JSON API with Bearer token authentication. Previously, consuming this package's data from outside the Laravel app meant custom code or DB access. Now the integration layer is a config flag — which materially weakens the "we'll just build it ourselves" argument for internal tooling and shortens the buy-side estimate.
• Roadmap sequencing for machine-to-machine use cases. Bearer tokens signal a deliberate move beyond browser-session/human users. This unblocks concrete workstreams: CI/CD pipeline gates, scheduled reporting jobs, alerting into Slack/PagerDuty, syncing into a warehouse or BI tool, and thin SPA/mobile clients that read the same data as the packaged UI.
• Security review as a go/no-go gate, not a blocker. Because the API is opt-in, we can adopt the package with the network surface fully closed, ship value in-app, and open the API later once token policy (scoping, rotation, revocation, audit logging) is agreed. That converts a potential security objection into a phased rollout decision.
• Environment-tiered rollout. Optional API + token auth maps cleanly onto per-environment config: local/staging on, production off until pen-test sign-off. Useful for demonstrating control to a security-conscious stakeholder.
• Feature-flag and service-account planning. Expect follow-on asks that this release does not answer — token scopes, per-token rate limits, pagination, audit trail. Those belong on our backlog as "required before GA," not assumed to exist.
• Low lock-in posture. A documented JSON contract is an exit ramp: if we later replace the package, downstream consumers keep working against a thin adapter.

When to Consider This Package

Consider adopting when:

• The stack is Laravel/PHP and the team wants a native package rather than a standalone service with its own auth, deployment, and on-call burden.
• Programmatic access to the data is a real requirement — the new JSON API is the deciding feature, not a nice-to-have.
• You can tolerate a pre-1.0 dependency behind an adapter or anti-corruption layer of your own.
• Static-analysis discipline matters to the team: PHPStan + Larastan + Pint are actively bumped in this release, which is a reasonable proxy for maintainability and review rigor.
• You want a staged security story — adopt closed, open the API per environment.

Look elsewhere when:

• You need a contractual SLA, guaranteed support windows, or a stable semver API contract. At v0.1.x, endpoints, payload shapes, and auth semantics can change without a major-version signal.
• You need token scoping, rotation policy, rate limiting, or audit logging now. This release documents Bearer authentication only; treat everything beyond that as unverified and validate before committing.
• The consuming services are not PHP/Laravel. You are then depending entirely on the JSON API's completeness and stability, which is version-zero.
• You require multi-tenancy guarantees, horizontal-scale characteristics, or a published data-retention policy.
• The package would sit on a compliance boundary (PII, regulated data) where any new externally reachable endpoint — even optional — triggers a full vendor assessment you are not ready to run.

Validation checklist before adoption: confirm what the API actually exposes, whether responses are paginated, whether tokens can be scoped or revoked, and whether the API can be disabled at the route level rather than only by config. Also confirm maintenance depth: the release is dominated by Dependabot bumps plus one feature PR, so contributor concentration is worth a look.

How to Pitch It (Stakeholders)

To executives — the one-paragraph version: This release turns a Laravel package into an integration platform. The optional JSON API with token auth lets our existing systems, reporting jobs, and automation read its data directly, so we buy the integration layer instead of building it. It is off by default, so we can adopt now and enable external access once security signs off — low switching cost, no lock-in, and a clear path to phase two.

To engineering — why it's worth the dependency: Laravel-native, no new service to operate. The API is opt-in and scoped behind Bearer auth, so it can be dark in production. The repo runs PHPStan/Larastan and Pint with active dependency hygiene, which suggests review discipline. Two caveats to design around: it is v0.1.x, so wrap it behind our own interface and pin the version; and the API contract is new — do not let downstream consumers couple directly to its payloads yet.

To security — the framing that gets a yes: Nothing new is exposed by default. The API is a feature flag, authenticated by Bearer tokens, and can be enabled per environment. We are asking for approval to deploy with it disabled and a separate review before any external enablement; the open items for that review are token scoping, rotation/revocation, rate limiting, and request logging, none of which we are assuming is present today.

Headline risk to state plainly: pre-1.0 versioning plus a brand-new API surface means the contract is unstable. Mitigate with a version pin, an internal adapter, and a re-review at 1.0 or at the first endpoint change.