Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for channel integration. This package remains the "buy/adopt" option against a 4–8 week internal build. It covers catalog serving, order intake, fulfillment status push-back, webhooks, and a customer-facing chat surface in one dependency — the whole conversational-commerce loop, not a partial SDK.
• Time-to-market for a new sales channel. If OmniConva is a committed channel, adopting this collapses the roadmap item from "integration project" to "configuration task": install command, wire up the Eloquent source, map the traits, run the migrations, ship. Note that v1.0.1 adds a required php artisan migrate step (idempotency key widening plus a second published migration), so "configuration task" now includes a deploy-window item, not just composer install.
• Feature scope for the storefront. The <x-omniconva-chat /> component with signed customer identity means chat is a drop-in, not a bespoke build. It also settles an architectural question early — chat identity is tied to your authenticated customer, so the PM should confirm that model matches the intended customer journey (guests, B2B accounts, multi-storefront users). v1.0.1 hardens this surface: a non-scalar customer id is ignored rather than passed through, so confirm your identity resolver always yields a scalar id.
• Reliability requirements become non-negotiable defaults. Idempotency-Key handling on order creation, signed payloads on every route, and queued-after-commit webhooks with retry are all product guarantees (no duplicate orders, no phantom events on rolled-back transactions), not just engineering hygiene. Use these as acceptance criteria in the launch checklist rather than debating them later. v1.0.1 strengthens the guarantee: idempotency claims now carry an owner token, so a request whose claim was taken over after a stall cannot release or complete the claim that replaced it — this closes a duplicate-order/claim-corruption window that existed in v1.0.0.
• Data-leakage prevention is now a product guarantee, not a hope. Only an OrderRefused exception's message is sent to OmniConva; any other exception (e.g. a QueryException containing SQL and customer data) is reported to your handler and answered with a generic 500. This means the PM must own an exception-handling policy: customer-safe refusal reasons must be thrown as OmniConva\Laravel\Exceptions\OrderRefused, and everything else must be treated as an internal failure. It also means no PII or schema detail leaks to the channel on unexpected errors — put that in the security review sign-off.
• Catalog sync failures no longer block saves — but they now need observability. SyncsWithOmniConva / SyncsParentWithOmniConva never let a mapping or encoding problem abort your save; the problem is reported instead, and invalid UTF-8 is substituted rather than fatal. This is the right product tradeoff (a bad product record should not break checkout or admin saves), but it creates a silent-failure surface: without alerting on reported exceptions, catalog drift to OmniConva goes unnoticed. Make "alert on reported sync exceptions" a launch checklist item.
• Webhook transport security becomes an explicit launch gate. v1.0.1 is breaking for http setups: OMNICONVA_WEBHOOK_URL must be https; http:// is accepted only for localhost and 127.x, and elsewhere only with OMNICONVA_ALLOW_HTTP=1 (e.g. a Docker Compose service name). Webhook deliveries also no longer follow redirects. Product decision: production and staging webhook URLs must be https; any OMNICONVA_ALLOW_HTTP=1 usage is a documented, time-boxed exception (internal network only), not a default.
• Data-shape hardening reduces support edge cases. Non-finite prices become null instead of "inf"; big numeric ids in order payloads stay strings; an empty route prefix is refused; the install command reads from cached config rather than env(), never overwrites a credential with an empty value, always quotes what it writes, and warns when secrets are passed as options. These are the kinds of defects that otherwise surface as "why is this product free?" or "why did the order id change?" support tickets — worth calling out as reduced post-launch support load.
• Use cases this unblocks: selling via a conversational surface on an existing Laravel app; syncing a catalog to a marketplace/assistant without a middleware service; surfacing order status and tracking in chat without building a support tool.
• Roadmap and governance signal: Laravel 12 and 13 with PHP 8.2+ means the package is being maintained against current and next framework versions. The first patch being security-focused is a positive responsiveness signal from the vendor. However, that same patch shipped breaking behavior on a patch version (http webhook URLs) and requires a migration — evidence that there is still no stable compatibility contract. Treat every release as requiring an upgrade review, not just majors.

When to Consider This Package

Consider adoption when:

• The application is Laravel 12 or 13 on PHP 8.2+ and products already live in Eloquent models — the EloquentProductSource is the only source shipped, so a non-Eloquent catalog (ERP, external PIM, Elasticsearch) means writing and owning an adapter.
• OmniConva is a live or funded channel with an account and credentials, not an experiment.
• You want the integration to be vendor-maintained and upgrade-tracked rather than an internal one-off.
• You can serve https webhook endpoints in every non-local environment, or can explicitly and temporarily set OMNICONVA_ALLOW_HTTP=1 for an internal-only host.
• You can schedule a database migration as part of the rollout and every future upgrade (php artisan migrate; a second migration is published via --tag=omniconva-migrations).
• You can absorb a young dependency: v1.0.1 has one patch of history, and that patch included a breaking change for http setups. There is still no observed long-term track record for backwards compatibility or support SLAs.
• You can monitor reported exceptions from the sync traits; otherwise, catalog sync failures will be invisible.

Look elsewhere, or budget for in-house work, when:

• The stack is not Laravel, or is Laravel ≤ 11 / PHP < 8.2.
• You need a non-Eloquent product source or custom pricing/availability logic that the standard OmniConva format doesn't express.
• You cannot expose https webhook endpoints and are unwilling to run with OMNICONVA_ALLOW_HTTP=1 — the http path is now gated by design.
• You require multi-tenant or per-store credentialing — the notes describe a single prefix and signature secret, so confirm the tenancy model before committing.
• You need synchronous, in-request webhook delivery guarantees; this package queues after commit with retries, which is the right default but changes your latency expectations.
• You need a documented API-version/compatibility policy and a support SLA. The v1.0.1 breaking change on a patch release makes this more important, not less — get the policy in writing, or pin the version and review each upgrade.
• You cannot tolerate migration-coupled upgrades — idempotency storage schema changes are now part of the package's upgrade surface.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, high-leverage channel integration. It gives us product listing, order intake, fulfillment updates, and an embedded customer chat in a single supported package, compressing what would be a multi-week build into a configuration, migration, and QA effort. Security (request signing, https-only webhook transport, no customer data leaked to the channel on unexpected errors, hardened idempotency claims) and data integrity (idempotent order creation, safe catalog sync that cannot break saves) are built in rather than bolted on — which reduces launch risk and the support burden that usually follows a hand-rolled integration. The vendor shipped a security-hardening patch immediately, which is a good responsiveness signal. The caveats are maturity and change management: the patch includes a breaking change for non-https webhook setups and a required database migration, so we should plan a short pilot with a feature flag, pin the version, and review each release before upgrading.

To engineering: Standard Laravel package — composer install, omniconva:install, omniconva:test, omniconva:ping to verify connectivity. Products are served from an EloquentProductSource; add the SyncsWithOmniConva / SyncsParentWithOmniConva traits to models to queue signed product webhooks after commit (mapping/encoding failures are reported, not thrown — wire up alerting). Orders arrive via POST {prefix}/orders with Idempotency-Key handling; push status/tracking back with OmniConva::orderUpdated(). Every route verifies X-OmniConva-Signature. Chat is an anonymous Blade component with signed customer identity. On upgrade to v1.0.1: run php artisan migrate (publish the second migration with --tag=omniconva-migrations), confirm OMNICONVA_WEBHOOK_URL is https (localhost/127.x exempt; other internal hosts need OMNICONVA_ALLOW_HTTP=1), and note webhook deliveries no longer follow redirects. When refusing an order, throw OmniConva\Laravel\Exceptions\OrderRefused — only that message reaches OmniConva; everything else is reported locally and returned as a generic 500.

Decisions we need from this: (1) approve OmniConva as a channel and the pilot scope; (2) confirm our product data is representable by the Eloquent source or budget an adapter; (3) confirm the single-tenant credential model fits our deployment; (4) confirm all non-local webhook endpoints are https and that any OMNICONVA_ALLOW_HTTP=1 use is a documented, time-boxed exception; (5) agree an order-refusal exception policy (customer-safe OrderRefused vs. internal failures) and an alerting plan for reported sync exceptions; (6) agree on version pinning, a migration window per upgrade, and an upgrade-review policy — including patch releases — until the package has a stability track record.