Ikentoo Bridge Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for POS integration: This package is a thin, token-authenticated HTTP bridge to the Ikentoo (hospitality POS) API. It answers the "can we avoid building an Ikentoo connector ourselves?" question — the answer is "partially": it wraps the transport and exposes typed service objects, but only for the endpoints it models (financial->getReceiptTransactionsRange, orderAndPayment->loadMenu). Anything outside that surface is still custom work.
• Roadmap shaping for financial/reporting features: The getReceiptTransactionsRange signature (location ID, date-from, date-to, field list, limit) directly supports roadmap items like daily Z-report ingestion, revenue reconciliation, and staff-attributed transaction reporting. If your roadmap has "pull POS transactions into our dashboard," this is a credible accelerant.
• Menu/pricing sync features: loadMenu(locationId, menuId, bool) maps to roadmap work on digital menus, price propagation to ordering channels, and menu-version auditing.
• Integration spike vs. product bet: At 1.0.0 with a single example and no documented error handling, retries, pagination semantics, or test suite, this is best treated as a prototype enabler — useful to de-risk a PoC, not yet a foundation for a revenue-critical pipeline.
• Architecture fit decision: The package is a Symfony bundle, not a Laravel package. Adopting it in a Laravel codebase is a deliberate "borrow a Symfony library inside Laravel" decision, which is viable (Laravel ships Symfony components) but is a maintenance and idiom mismatch the PM should own explicitly rather than let engineering absorb silently.

When to Consider This Package

Consider it when:

• Your platform is Symfony-based, or you are willing to isolate this dependency behind your own adapter interface in Laravel.
• You need Ikentoo transaction/receipt reporting and menu retrieval specifically — the two areas the package exposes — rather than broad Ikentoo coverage.
• You are running a time-boxed PoC or internal tool where speed to a working API call outweighs long-term support guarantees.
• Your Ikentoo auth model matches the documented static token scheme (protocol/host/port/token), i.e. server-to-server, single-tenant, no per-user OAuth flow.
• You can tolerate vendor risk: single maintainer namespace (maillotf), pre-1.x-grade documentation, no published support policy.

Look elsewhere when:

• You need webhooks, event push, order creation, or write-back flows — this release shows only read paths.
• You require multi-tenant credential management (per-location or per-merchant tokens). The config block is a single static token in framework.yaml; you would be building credential routing yourself.
• You are Laravel-first and want Laravel idioms — no service provider, no facade, no config publishing, no queue integration. You would wrap it anyway, at which point a hand-rolled HTTP client may cost the same and give you full control.
• You need observability and resilience as product requirements: no documented retry/backoff, rate-limit handling, circuit breaking, or structured error types.
• You need pagination guarantees — the example passes a bare 1000 limit with no documented cursor or total-count contract, which is a real risk for financial data completeness.

How to Pitch It (Stakeholders)

For executives: This is a small, single-purpose connector to Ikentoo, the POS system used in hospitality. It lets us read receipt transactions and menus without building that plumbing from scratch. It is a cost-and-time saver for a proof of concept, not yet a production-grade dependency: version 1.0.0, one maintainer, minimal documentation, and no evidence of the hardening (retries, error handling, rate limits) we would require for money-touching reporting. Recommendation: greenlight as a PoC dependency behind an internal adapter, and budget a small amount of engineering to wrap it so we are not locked in. Do not commit customer-facing financial reporting to it without a hardening review.

For engineering: Treat this as a Symfony bundle consumed inside Laravel — isolate it behind our own IkentooClient interface so the vendor package is swappable, and so we control config (secrets manager, per-location tokens) rather than framework.yaml. Validate three unknowns before building on it: (1) what pagination/limit actually does beyond 1000 records, (2) what the failure modes and HTTP status handling look like, and (3) whether orderAndPayment supports any write operations. Pin the version, and add contract tests around the two call sites so a minor bump cannot silently change behaviour.