Vendra Api Laravel Package

Product Decisions This Supports

• Build vs. buy on integration plumbing. This package is a thin Laravel wrapper around a vendor API: config-driven credentials, a fluent request builder, service provider/facade, centralized error handling. Replacing it is a few hundred lines of our own client. The decision isn't "can we build it" — it's "do we want to own tracking upstream API changes," and the answer is usually yes-but-cheaply, via a wrapper.
• Whether Vendra becomes a platform dependency at all. The internal skill file reframes this: it's not a generic third-party client, it's shared API Platform infrastructure — reusable ApiResource DTOs and service-provider wiring that every domain API module (vendra-product-api, vendra-cart-api, vendra-faq-api, vendra-blog-api, vendra-multimedia-api, vendra-custom-page-api) is built on. Adopting this is a platform decision, not a library choice.
• Roadmap framing. It enables integration-dependent roadmap items (catalog, content, cart, back-office tooling) but ships no user-visible capability by itself. Track it as enablement, not as a feature.
• Multi-tenancy posture. The package is explicitly tenant-agnostic and the skill notes call out singleton credential leaks. If we're heading multi-tenant, that constraint shapes our binding strategy today.
• Not a differentiator. Low stars, single maintainer, no meaningful changelog. It should never appear on a slide as a capability — only as a cost line and a risk line.

When to Consider This Package

Adopt when:

• Vendra is already on the roadmap or in the stack. Then this is baseline infrastructure you don't really choose — you just pin it.
• You need one or two endpoints quickly (read-only reference data, catalog/content reads) and want config + facade + error handling instead of writing a client.
• The team already works in Laravel HTTP client idioms, so Http::fake() testing and event-based logging come free.
• You're willing to wrap it. Wrapping makes the adoption reversible and neutralizes most of the risk below.

Look elsewhere when:

• Health signals matter. 1 star, single maintainer, a subtree split (issues/PRs live in misaf/vendra, this repo is read-only), and the v1.12.3 release note is a bare compare link — two minor versions with no described changes. Treat minor bumps as potentially config-breaking and read diffs before upgrading.
• You need real vendor abstraction. It's a client, not an anti-corruption layer. Timeouts, retries, caching, idempotency, and DTO mapping are all on us.
• You need a stability guarantee. No changelog narrative, no breaking-change markers, no published support policy.
• You're not on Vendra. Then it's pure coupling with no upside.
• You can't resolve the scope question. The package description (generic API client) and the skill file (shared DTOs and provider wiring for domain API modules) describe different surfaces. Confirm which one we'd actually consume before committing engineering time.

How to Pitch It (Stakeholders)

For executives. This is integration glue, not product. Adoption cost is one composer require, a published config file, and .env keys — days, not weeks. The real cost is the dependency: a 1-star, single-maintainer package that ships without meaningful release notes, which means upgrade risk we can't read in advance. We contain that by wrapping it behind our own client class and testing at the HTTP layer, so replacing it later is a one-file change. Recommendation: adopt only if Vendra is already committed on the roadmap; otherwise defer. No revenue, retention, or differentiation impact either way.

For engineering. Wrap, don't sprinkle: bind our own VendraClient, constructor-inject it, and depend on that — never on Misaf\VendraApi\... — in controllers and jobs. Bind it scoped, not singleton, so a per-tenant token can't leak across requests. Resolve from the container in application code; facades are for spikes. Split reads from writes: cache reference data with a credential-aware cache key, push writes onto queued jobs with $tries, $backoff, and a failed() handler that surfaces the vendor error body. Set an explicit timeout below the worker --timeout. Retry idempotent verbs aggressively on 429/503, never on POSTs that may have already succeeded and never on 4xx auth/validation. Normalize vendor payloads into readonly DTOs at the boundary and translate vendor error codes into our own exception types. Log outbound calls via Illuminate\Http\Client\Events\* with a correlation ID we also carry in our logs, and scrub auth headers and PII — they land in debug output and failed_jobs payloads. Test with Http::fake() against one recorded success and one recorded error fixture; assert the mapping, not the JSON. Run php artisan config:clear after every upgrade.