Kiriminaja Php Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin HTTP client (Guzzle-based) over the KiriminAja REST API, covering pickup requests, tracking, and courier/area mapping. That is the right shape for our needs: it is a transport adapter, not a framework or domain model, so it belongs behind an internal ShippingGateway interface rather than being called directly from controllers or Eloquent models.
• Laravel fit depends on whether it ships a service provider, facade, and publishable config. Even if it does, we should bind it to our own interface in a service provider and inject a single configured client instance (singleton) so credentials, timeouts, and retry policy are centralized.
• KiriminAja is a courier aggregator (multi-carrier rates, pickup, tracking, COD). That maps to an existing domain concern in most commerce backends — shipment creation, AWB/resi generation, tracking status. Treat the package as the outer layer of a hexagonal port; it should not leak KiriminAja response shapes into our domain events.

Integration feasibility

• Low ceremony: composer require, API key in .env, config publish. Expect a sandbox/staging key from a KiriminAja account; the account, not the package, is the real prerequisite — commercial onboarding, origin-address registration, and courier enablement are often the long lead-time items.
• Verify endpoint coverage against our actual flows before committing: quote/rate for multi-courier comparison, create pickup/pickup-request, cancel, label/print, tracking (poll vs webhook), COD reconciliation, and area/postal-code mapping for address validation.
• Mapping data (postal codes, sub-districts, courier serviceability) is the most volatile surface — it changes as couriers enter/exit regions. Confirm whether the package caches mapping calls or fetches them live, and budget for our own caching layer.

Technical risk

• Maturity signal is weak on adoption, not on ownership: 13 stars and a low composite score. Release 2.1.7 confirms the repo lives under the first-party kiriminaja/php org and that patch releases are flowing (2.1.6 → 2.1.7). That settles the "is this a vendor package or a community fork?" question in our favour — but a single-patch progression proves cadence, not support commitment, and low adoption still means few external users surfacing bugs.
• Changelog discipline is absent: the 2.1.7 notes are a bare compare link with no described changes. We cannot triage a patch bump from the release, so every upgrade must be preceded by reading the 2.1.6...2.1.7 diff. Treat this as a standing process cost, not a one-off.
• Single-vendor dependency: the package's value is entirely the upstream API. Any breaking API change or courier de-listing is an outage we cannot patch around.
• Release date anomaly noted previously is now partially reconciled — active publishing is real — but tag history, changelog completeness, and CI status should still be verified against Packagist before we treat maintenance as healthy.
• Error semantics matter: confirm whether failures raise typed exceptions, return response DTOs, or silently return arrays. Pickup creation is not idempotent without a client-supplied key, and duplicate pickups cost real money and create carrier-side noise.
• Unclear test coverage against a real sandbox; without contract tests, a minor version bump can break AWB generation in production.

Key questions

1. Is this package maintained by KiriminAja itself? Answered: yes, first-party org, actively patching. Remaining: what is the support commitment (SLA, issue triage, API-incident notification)?
2. PHP/Laravel version support matrix, and is it tested on our target runtime?
3. Does it cover every endpoint we need, or will we be writing raw HTTP calls alongside it?
4. Webhook/push support for tracking, or does it require polling? What are rate limits?
5. Sandbox environment availability and fidelity vs production?
6. Idempotency, retry, and timeout behavior on pickup and cancel operations?
7. Versioning policy — semver adherence appears reasonable at patch level, but with empty release notes, what is the deprecation notice period and where are breaking changes announced?
8. Auth model: static API key, token refresh, per-merchant credentials?
9. What actually changed in 2.1.7, and was it security-relevant? (Answer from the diff, not the release page.)

Integration Approach

Stack fit

• Expect a Laravel 9–11 / PHP 8.1+ constraint. Verify before planning; a hard PHP 8.2+ floor can block integration on older services and force a platform upgrade first.
• Guzzle is already in nearly every Laravel app, so dependency footprint and conflict risk are low.
• Wrap in an internal KiriminAjaAdapter implements ShippingGateway. Domain code depends on our interface and our own DTOs (ShipmentRequest, TrackingSnapshot, RateQuote), never on the vendor client. This is the single highest-leverage decision for exit cost.

Migration path

• If we already ship via direct courier integrations, run in parallel: KiriminAja as a secondary rate/pickup source behind a feature flag, with per-order routing. Compare quote accuracy and pickup success rates before shifting volume.
• Where a legacy integration exists for a specific courier, migrate courier-by-courier rather than all at once — aggregator coverage differs per carrier and per region.
• Keep the vendor response payload logged (redacted) for a defined retention window to support reconciliation disputes with the carrier.

Compatibility

• Check for package auto-discovery; if absent, register the provider manually and publish config.
• Pin an exact version (2.1.7) rather than a floating constraint. Given release notes carry no content, ~2.1.0 would let an opaque patch in unreviewed; loosen only after we have contract tests in place.
• Ensure the client's base URL, timeout, and retry settings are config-driven, not hardcoded, so staging/production differ by env only.

Sequencing

1. Account onboarding + sandbox credentials (longest lead time — start here).
2. Review the 2.1.6...2.1.7 diff and tag history, then pin 2.1.7 as our baseline before any code is written.
3. Spike: quote, pickup, tracking round-trip in a throwaway Laravel app; confirm coverage and error shapes.
4. Build the ShippingGateway port + adapter + our own DTO mapping; write contract tests against sandbox.
5. Feature-flagged canary on a low-volume SKU/region.
6. Shadow-compare rates and pickup latency against the incumbent.
7. Progressive rollout by region, then by volume.
8. Decommission legacy courier clients only after the retention window on reconciliation data closes.

Operational Impact

Maintenance

• Pin the version and treat every upgrade — including patches — as a change requiring a diff review and a sandbox regression run. The 2.1.7 release reinforces this: a patch arrived with zero described content, so the release page tells us nothing about risk.
• The "we are effectively the maintainer of our fork" assumption can be softened slightly: first-party patch cadence is a better signal than 13 stars suggested. But with one active consumer and no changelog, we still own the review burden and should retain fork-and-patch capability as a contingency.
• Budget a small recurring allowance for mapping-data drift: couriers change serviceability and tariffs without notice, and stale mappings produce failed pickups at the worst moment (after the customer has paid).
• Track upstream tags and the KiriminAja API changelog as an explicit recurring task, with diff review of each tag as a checklist item, not an ad hoc one.

Support

• Support path is the commercial KiriminAja relationship, not GitHub issues. Ensure the vendor contract names technical escalation and API-incident notification obligations — the absence of release notes makes notification obligations more important, not less.
• Internal ownership: one backend engineer as named owner for the adapter, with a documented runbook — credential rotation, base URL change, sandbox repro, carrier enablement, and "how to review an upstream tag."

Scaling

• The client itself is stateless and scales horizontally; the constraint is vendor API rate limits and latency. Put quote calls behind a short-TTL cache (rates are stable on the order of minutes) and push pickup/tracking to queued jobs with backoff.
• Add a circuit breaker per endpoint. Rate-quote and tracking failures should degrade (show fallback pricing, poll later); pickup failures must surface loudly.
• Tracking is the high-volume call. Prefer webhooks if offered — polling at order volume will dominate our request budget and vendor rate limits. If polling is the only option, schedule by expected transit time rather than a flat interval.

Failure modes

• Duplicate pickups on timeout-retry without idempotency keys — carrier dispatches twice, cost and customer-experience hit.
• Silent patch regressions: an unreviewed 2.1.x bump changing an undocumented field path, producing nulls in AWB or tracking responses. Mitigated only by diff review plus contract tests.
• Stale courier mappings → invalid destination errors at checkout.
• Auth/key rotation → blanket 401s across shipping; needs alerting on error-rate, not just uptime.
• Response schema drift on a minor version → silent nulls in AWB or tracking fields.
• Courier-side outage masquerading as our failure; requires per-courier error attribution to route around it.
• COD reconciliation mismatch — money-affecting, needs an independent ledger comparison, not reliance on vendor reporting alone.

Ramp-up

• For a mid-level Laravel engineer: roughly 2–4 days to productive, given the thin wrapper and familiar Guzzle patterns. Most of the effort is not the code.
• The real learning curve is domain knowledge: Indonesian courier conventions (resi/AWB numbering, COD flows, sub-district-level addressing, cashflow timing on COD settlement). Plan a short pairing session with whoever owns fulfillment ops.
• Documentation risk is unchanged and now slightly worse: the 2.1.7 release has no notes, and the README is unlikely to cover upgrade impact. Assume we write and own the internal "how we call KiriminAja" and "how we upgrade the client" docs for the next engineer.