Nepalcan Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Courier API Integration: The package is a domain-specific Laravel wrapper for the Nepal Can Move (NCM) courier API, aligning well with e-commerce, logistics, or delivery-heavy applications.
• Laravel Idiomatic Design: Leverages Laravel’s Service Provider, Facade, and Dependency Injection patterns, reducing boilerplate for API interactions.
• Event-Driven Webhooks: Supports Laravel’s event system for asynchronous webhook handling (e.g., shipment status updates), which is critical for real-time logistics tracking.
• Configuration Flexibility: Publishable config allows environment-based API token management, a best practice for security and scalability.

Integration Feasibility

• Low-Coupling: The package is self-contained (no forced database schema or migrations), making it easy to adopt without disrupting existing workflows.
• SDK Dependency: Relies on the underlying nepal-can-php-sdk, which may introduce indirect dependencies (e.g., Guzzle for HTTP requests). Verify SDK stability and compatibility with Laravel’s HTTP stack.
• Webhook Handling: Requires Laravel’s routing and middleware for webhook validation (e.g., user-agent checks). Ensure your app can handle asynchronous payloads and retries for failed deliveries.

Technical Risk

• Maturity Concerns: 0 stars, no dependents, and minimal documentation suggest unproven reliability. Test thoroughly for:
  • API rate limits (NCM may throttle requests).
  • Webhook idempotency (duplicate payloads).
  • Error handling (e.g., failed shipments, COD disputes).
• PHP Version Support: Check compatibility with your Laravel version (e.g., PHP 8.1+ may break if the SDK isn’t updated).
• Vendor Lock-in: If NCM’s API changes, the package may require forking or patching due to its tight coupling with the SDK.

Key Questions

1. API Stability: Has NCM’s API undergone recent changes? Are there deprecations or breaking changes in the SDK?
2. Webhook Reliability: How does NCM handle failed webhook deliveries? Does the package support retries or dead-letter queues?
3. Rate Limiting: What are NCM’s API rate limits? Does the package include exponential backoff for retries?
4. Testing Coverage: Are there unit/integration tests for edge cases (e.g., invalid COD amounts, failed tracking updates)?
5. Monitoring: Can the package integrate with Laravel’s logging (e.g., Monolog) or monitoring tools (e.g., Sentry) for API failures?
6. Local Development: Does the package support mocking NCM’s API for testing (e.g., via Vapor or Laravel’s HTTP client)?

Integration Approach

Stack Fit

• Laravel Core: Works seamlessly with Laravel 8+ (composer autoloading, facades, service providers).
• E-Commerce Stack: Ideal for Laravel-based marketplaces (e.g., Bagisto, Avo) or custom e-commerce apps needing courier integrations.
• Queue Workers: Webhook processing can leverage Laravel’s queue system (e.g., dispatchSync for critical updates, delay() for non-critical ones).
• Testing: Compatible with Pest/PHPUnit for unit testing API clients and webhook handlers.

Migration Path

1. Installation:

   composer require pralhadstha/nepalcan-laravel
   php artisan vendor:publish --provider="OmniCargo\NepalCan\NepalCanServiceProvider"
   

2. Configuration:
   • Set NCM_API_TOKEN and NCM_API_BASE_URL in .env.
   • Publish config if customization is needed.
3. Facade Usage:

   use OmniCargo\NepalCan\Facades\NepalCan;
   
   $shipment = NepalCan::shipments()->create([
       'from' => 'Kathmandu',
       'to' => 'Pokhara',
       'items' => [...],
   ]);
   

4. Webhook Setup:
   • Register the webhook route (auto-discovered by the package).
   • Implement a listener for NepalCan\Events\WebhookReceived:

     public function handle(WebhookReceived $event) {
         // Process shipment update, tracking, etc.
     }
     

5. Dependency Injection:

   public function __construct(private NepalCanClient $client) {}
   

Compatibility

• Laravel Versions: Tested with Laravel 8/9/10 (check composer.json constraints).
• PHP Extensions: Requires cURL or Guzzle (handled by the underlying SDK).
• Database: No migrations required, but you may need to model shipments, trackings, or webhook_events in your app’s DB.
• Third-Party Packages: Conflicts unlikely unless another package uses the same facade namespace (OmniCargo\NepalCan).

Sequencing

1. Phase 1: Core Integration
   • Implement shipment creation and rate calculation.
   • Test with sandbox API keys (if NCM provides one).
2. Phase 2: Webhooks
   • Set up webhook listeners for critical events (e.g., shipment_delivered).
   • Add retry logic for failed webhook deliveries.
3. Phase 3: Advanced Features
   • Integrate COD reconciliation with your payment system.
   • Build a tracking dashboard using the API.
4. Phase 4: Monitoring
   • Add logging for API calls and failures.
   • Set up alerts for webhook failures (e.g., via Laravel Horizon).

Operational Impact

Maintenance

• Dependency Updates: Monitor both the package and the underlying SDK for updates/breaking changes.
• Configuration Drift: If NCM’s API endpoints change, update the published config or fork the package.
• Webhook Management: Maintain a log of processed webhooks to debug failures (e.g., using Laravel’s failed_jobs table or a custom table).

Support

• Limited Community: With 0 stars, support may require:
  • Opening GitHub issues for bugs.
  • Forking the package for critical fixes.
• Vendor Support: Rely on NCM’s documentation for API issues (e.g., COD disputes, tracking errors).
• Debugging: Use Laravel’s debugbar or Telescope to inspect API responses and webhook payloads.

Scaling

• Rate Limits: If your app processes high-volume shipments, implement:
  • Caching (e.g., Redis) for rate quotes.
  • Queue batching for webhook processing.
• Horizontal Scaling: Webhook endpoints must be stateless (store payloads in a DB/queue for async processing).
• Database Load: If tracking many shipments, consider read replicas for tracking queries.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 hours to install and test basic features (shipments/tracking).
  • Half-day to implement webhooks and error handling.
• Documentation Gaps:
  • No usage examples in the README → create internal docs with:
    • API response schemas.
    • Webhook payload examples.
    • Error code mappings.
• Training:
  • Focus on webhook reliability and COD reconciliation for non-technical stakeholders (e.g., finance teams).
• Tooling:
  • Use Postman to test NCM’s API independently before integrating.
  • Set up Laravel Telescope to monitor webhook events.