Cord Laravel Package

Technical Evaluation

Architecture fit oliverbj/cord is a Laravel-oriented PHP SDK that wraps a shipping/delivery API for shipment creation and lifecycle updates. Release 3.5.4 extends the shipment update pathway with two new capabilities: estimated delivery dates and drop modes (i.e. unattended/leave-safe style delivery instructions). Architecturally this fits cleanly into the layer of our stack that handles post-purchase order fulfilment: it sits alongside order state transitions, is naturally invoked from queued jobs, and does not require us to host or operate an additional service. The package is consumed as a Composer dependency with a Laravel service provider and config file, which matches our existing third-party integration pattern.

The main architectural consideration is that this release increases the surface area of mutable shipment state. Estimated dates and drop modes are carrier-facing instructions; if we call update on a shipment, we are now responsible for deciding when a date is a "promise" versus an "estimate" and when a drop mode is legally acceptable (some carriers restrict unattended delivery for high-value or age-restricted goods). That logic must live in our domain layer, not be inherited implicitly from the SDK.

Integration feasibility Low-to-moderate. Standard composer require + config publish + credential provisioning, then a thin adapter. The new fields appear additive to an existing update call, so no new transport, auth, or webhook work is implied. Realistic effort for a first production path: one sprint for the adapter + DTOs + queued update job, plus a second sprint for carrier-by-carrier validation and UI surfacing of delivery promises.

Technical risk

• Semver discipline. A user-facing feature ("Add estimated dates and drop modes") shipped in a patch release (3.5.4). This is acceptable only if the new parameters are strictly optional with unchanged defaults. We must verify this rather than assume it — if any method signature gained a required argument or a default changed, a composer update could break us silently.
• Single-maintainer dependency. The package is authored and released by one individual. Bus factor and release cadence are the dominant long-term risks, not code quality.
• Upstream API coupling. Our behaviour is ultimately governed by a third-party shipping API whose versioning and deprecation policy we do not control. The SDK's version number tells us nothing about the upstream API version.
• Data semantics. "Estimated date" is ambiguous — carrier-provided, SDK-computed, or caller-supplied? Misinterpreting this leads to over-promising at checkout, which is a customer-facing and potentially consumer-law-sensitive defect.
• Drop modes and liability. Unattended delivery instructions shift loss/damage liability. If the SDK accepts a free-form string rather than a validated enum, we could transmit an invalid mode and get either a silent fallback or a failed update.

Key questions

1. Are the new estimated_date and drop_mode parameters optional on the update call, with unchanged defaults? Confirm no breaking signature change in 3.5.4.
2. Is drop_mode backed by a BackedEnum / validation rule, and is the accepted value set carrier-specific or global?
3. Is the estimated date supplied by us or returned by the carrier? What timezone and granularity (date vs. datetime window)?
4. Which carriers and service levels actually honour drop modes, and what are the restrictions (value thresholds, signature-required items, prohibited goods)?
5. What is the upstream API version this SDK targets, and does the package pin it?
6. Test coverage for the update path — are there contract/integration tests against a sandbox, or only unit tests with mocked responses?
7. Supported Laravel/PHP version matrix, and HTTP client dependency (Guzzle vs. Laravel HTTP client vs. Saloon)?
8. Rate limits, idempotency semantics on update, and error/exception taxonomy exposed to the caller.
9. Sandbox environment availability and whether it supports drop modes and date estimates.
10. Authentication model — static token or OAuth with refresh — and how token expiry surfaces to our jobs.

Integration Approach

Stack fit Standard Laravel 10/11 + PHP 8.1+ application, queue workers (Redis/SQS), and our existing outbound-integration adapter pattern. The package belongs behind an internal ShipmentGateway interface so that controllers, listeners, and jobs never reference the vendor namespace directly. New release features map to two thin additions on that interface: updateEstimatedDelivery(ShipmentId, Date) and updateDropMode(ShipmentId, DropMode).

Migration path Greenfield — there is no incumbent assessment or prior integration, so no migration is required. If we are replacing manual carrier portal entry, run in parallel: package writes shipment updates while ops continues to verify in the carrier portal for a defined bake period.

Compatibility Treat 3.5.4 as a forward-compatible minor feature set despite its patch number. Practical steps:

• Constrain in composer.json to ^3.5 and commit the lock file; do not auto-merge patch bumps.
• Diff the compare/3.5.3...3.5.4 changelog and inspect the touched method signatures before upgrading.
• Verify the package's illuminate/* constraints cover our Laravel version before promising a delivery date.
• Check that drop_mode values we intend to send are accepted by each carrier we use, in sandbox, before enabling in production.

Sequencing

1. Sandbox spike: create a shipment, call update with an estimated date, then with each candidate drop mode; record accepted/rejected values per carrier.
2. Build the ShipmentGateway adapter + DTOs + enum mapping. Do not leak SDK types into the domain.
3. Wrap update calls in queued jobs with retry/backoff and an idempotency key.
4. Persist carrier-acknowledged estimates locally with a source and received_at so we can distinguish our promise from the carrier's.
5. Feature-flag per carrier and per product category. Enable drop modes for low-risk categories first.
6. Surface estimates in post-purchase tracking UI only after the carrier-acknowledged value is stored — never render a locally computed guess as a carrier promise.
7. Roll out to full traffic; decommission parallel manual entry.

Operational Impact

Maintenance Ongoing cost is low in code volume but non-trivial in vigilance. Pin the version, review each changelog before upgrading, and keep a small set of contract tests against the sandbox so an upstream API change is caught by us rather than by customers. Because the package is single-maintainer, budget for the possibility that we eventually fork or vendor it; keeping our adapter thin is the insurance policy that makes that cheap.

Support No commercial SLA. Support is GitHub issues with best-effort response. Escalation for a broken shipment update is therefore our on-call, not a vendor hotline. Operationally we need a documented manual fallback: ops staff updating shipments in the carrier portal while the integration is degraded. Note also that drop-mode disputes are a customer-service concern (missing parcels) as much as an engineering one — CS needs a runbook.

Scaling Updates are per-shipment and low-volume relative to checkout traffic; the package itself will not be the bottleneck. Scale concerns sit around it:

• Queue concurrency and per-carrier rate limits; enforce a limiter keyed by carrier account.
• Token/auth refresh under concurrency — ensure one refresh, not N parallel refreshes.
• Estimated-date updates on long-tail shipments (bulk re-estimation after a carrier disruption) can produce a burst; batch and throttle these.
• Cache carrier capability metadata (which drop modes a carrier accepts) rather than querying per request.

Failure modes

• Upstream API outage / 5xx: update jobs fail; shipments retain stale estimates. Mitigation: retry with backoff, dead-letter queue, alerting, and a UI that degrades to "estimate unavailable" instead of showing stale data as current.
• Silent partial success: update accepted but drop mode ignored by carrier. Mitigation: read back shipment state after update and reconcile; treat "not echoed back" as failure.
• Invalid drop mode for product/carrier: rejected update, or worse, accepted and later refused at the door. Mitigation: validate locally against cached carrier capability rules before sending.
• Auth token expiry under load: mass 401s. Mitigation: proactive refresh, circuit breaker, single-flight refresh.
• Over-promising on estimates: the highest-severity customer-facing failure. Mitigation: label as estimate, store source and timestamp, never render a locally derived date as carrier-confirmed.
• Silent breakage on upgrade: a patch bump that changes a default. Mitigation: lock file, changelog review, sandbox contract tests in CI.
• Upstream API deprecation: SDK pins an old API version. Mitigation: track upstream deprecation notices independently of the SDK's release notes.

Ramp-up Engineering ramp-up is low — a Laravel developer is productive with the package in under a day, and the 3.5.4 additions add no new concepts beyond two optional fields. Domain ramp-up is the real cost: understanding carrier drop-mode rules, liability implications, and delivery-estimate semantics will take longer than the code. Plan for one engineer plus a fulfilment/ops SME during the rollout, and expect roughly two sprints from sandbox spike to production flag-on, with drop modes trailing estimated dates by a sprint while carrier capability mapping is confirmed.