{"_id":"@amazol/logistics-sdk","_rev":"5-1d930ccf37d4ebd00f97b4a9951df32a","name":"@amazol/logistics-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@amazol/logistics-sdk","version":"1.0.1","keywords":["amazol","logistics","api","sdk","delivery","shipping","tracking","orders","shipments"],"author":{"name":"Amazol Team","email":"logistics-support@amazol.store"},"license":"MIT","_id":"@amazol/logistics-sdk@1.0.1","maintainers":[{"name":"mohammed-hamdi","email":"mohammedhamdi.dev@gmail.com"}],"homepage":"https://docs.amazol.store/logistics","bugs":{"url":"https://github.com/amazol/logistics-api/issues"},"dist":{"shasum":"b88caa2fff835023bf7075adad2cd5e74b0924bd","tarball":"https://registry.npmjs.org/@amazol/logistics-sdk/-/logistics-sdk-1.0.1.tgz","fileCount":11,"integrity":"sha512-/DE++xjO1QT6vIPg8Li2ocoS0atIDeE4fjn5O8P1ZlMx5Bl8PtMQt6niToKl99FLOrkLOUxUjhIfcJypn/0tdA==","signatures":[{"sig":"MEUCIQDge76zkaR5OaFW6eXAbxFlLuKyE+GeL/gpvK5nKSaB8wIgBHMfM83hE3p6Si0gpqF7nzCDr7H/K6j4TcxpMDjQb6Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68582},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.esm.js","engines":{"node":">=14.0.0"},"gitHead":"1a525e86af61e85aefa4e6fde9c02b8055846c55","scripts":{"dev":"rollup -c -w","lint":"eslint src --ext .ts","test":"jest","build":"rollup -c","format":"prettier --write src/**/*.ts","prepare":"npm run build","test:watch":"jest --watch"},"_npmUser":{"name":"mohammed-hamdi","email":"mohammedhamdi.dev@gmail.com"},"repository":{"url":"git+https://github.com/amazol/logistics-api.git","type":"git","directory":"packages/amazol-logistics-sdk"},"_npmVersion":"10.9.2","description":"Official JavaScript/Node.js SDK for the Amazol Logistics Hub API","directories":{},"_nodeVersion":"22.14.0","dependencies":{"ws":"^8.14.0","axios":"^1.6.0","@rollup/plugin-commonjs":"^28.0.6","rollup-plugin-typescript2":"^0.36.0","@rollup/plugin-node-resolve":"^16.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","eslint":"^8.0.0","rollup":"^4.50.0","ts-jest":"^29.0.0","prettier":"^3.0.0","@types/ws":"^8.5.0","typescript":"^5.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/logistics-sdk_1.0.1_1756855354209_0.994495348555315","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved to @suqan/logistics-sdk. Install: npm install @suqan/logistics-sdk"}},"time":{"created":"2025-09-02T23:22:34.139Z","modified":"2026-07-02T22:53:34.798Z","1.0.0":"2025-09-02T23:08:12.067Z","1.0.1":"2025-09-02T23:22:34.425Z"},"bugs":{"url":"https://github.com/amazol/logistics-api/issues"},"author":{"name":"Amazol Team","email":"logistics-support@amazol.store"},"license":"MIT","homepage":"https://docs.amazol.store/logistics","keywords":["amazol","logistics","api","sdk","delivery","shipping","tracking","orders","shipments"],"repository":{"url":"git+https://github.com/amazol/logistics-api.git","type":"git","directory":"packages/amazol-logistics-sdk"},"description":"Official JavaScript/Node.js SDK for the Amazol Logistics Hub API","maintainers":[{"name":"mohammed-hamdi","email":"mohammedhamdi.dev@gmail.com"}],"readme":"# Amazol Logistics Hub SDK\n\nOfficial JavaScript/Node.js SDK for the Amazol Logistics Hub API. This SDK provides a simple and intuitive way to integrate with the Amazol platform for logistics operations.\n\n## Features\n\n- 🚚 **Order Management**: Accept and manage assigned orders\r\n- 📦 **Shipment Tracking**: Update shipment status and location\r\n- 🚗 **Driver Management**: Track driver locations and status\r\n- 🔌 **Real-time Updates**: WebSocket connection for live updates\r\n- 🛡️ **Error Handling**: Comprehensive error handling with retry logic\r\n- 📊 **Rate Limiting**: Built-in rate limit handling\r\n- 🔧 **TypeScript Support**: Full TypeScript support with type definitions\n\n## Installation\n\n```bash\nnpm install @amazol/logistics-sdk\r\n\n```\n\n## Quick Start\n\n```javascript\nimport AmazolLogisticsClient from '@amazol/logistics-sdk';\r\n\r\n// Initialize the client\r\nconst client = new AmazolLogisticsClient({\r\n  apiKey: 'your_api_key_here',\r\n  baseUrl: 'https://api.amazol.store/v1/logistics' // Optional, defaults to production\r\n});\r\n\r\n// Get assigned orders\r\nconst orders = await client.getAssignedOrders({\r\n  status: 'pending',\r\n  limit: 10\r\n});\r\n\r\nconsole.log('Assigned orders:', orders.data);\r\n\n```\n\n## Configuration\n\n```javascript\nconst client = new AmazolLogisticsClient({\r\n  apiKey: 'your_api_key_here',\r\n  baseUrl: 'https://dev-api.amazol.store/api/v1/logistics', // Development server\r\n  timeout: 30000, // 30 seconds\r\n  retries: 3, // Retry failed requests 3 times\r\n  retryDelay: 1000, // Wait 1 second between retries\r\n  userAgent: 'my-logistics-app/1.0.0' // Custom user agent\r\n});\r\n\n```\n\n## API Examples\n\n### Orders\n\n#### Get Assigned Orders\n\n```javascript\n// Get all pending orders\r\nconst pendingOrders = await client.getAssignedOrders({\r\n  status: 'pending',\r\n  limit: 50,\r\n  offset: 0\r\n});\r\n\r\n// Process each order\r\npendingOrders.data.forEach(order => {\r\n  console.log(`Order ${order.orderNumber}: ${order.customer.name}`);\r\n});\r\n\n```\n\n#### Accept an Order\n\n```javascript\n// Accept an assigned order\r\nconst result = await client.acceptOrder('order_id_here', {\r\n  estimatedPickupTime: '2024-01-15T10:00:00Z',\r\n  estimatedDeliveryTime: '2024-01-17T14:00:00Z',\r\n  driverId: 'driver_id_here',\r\n  vehicleInfo: {\r\n    type: 'van',\r\n    plateNumber: 'KH-123-AB'\r\n  }\r\n});\r\n\r\nconsole.log('Order accepted:', result.message);\r\n\n```\n\n### Shipments\n\n#### Update Shipment Status\n\n```javascript\n// Update shipment status to \"in_transit\"\r\nconst result = await client.updateShipmentStatus('shipment_id_here', {\r\n  status: 'in_transit',\r\n  location: {\r\n    lat: 15.5007,\r\n    lng: 32.5599,\r\n    address: 'Distribution Center, Khartoum'\r\n  },\r\n  notes: 'Package loaded onto delivery vehicle',\r\n  estimatedDeliveryTime: '2024-01-17T14:00:00Z'\r\n});\r\n\r\nconsole.log('Status updated:', result.message);\r\n\n```\n\n### Drivers\n\n#### Update Driver Location\n\n```javascript\n// Update driver's current location\r\nconst result = await client.updateDriverLocation('driver_id_here', {\r\n  location: {\r\n    lat: 15.5007,\r\n    lng: 32.5599,\r\n    address: 'Current Location, Khartoum'\r\n  },\r\n  status: 'busy',\r\n  batteryLevel: 85\r\n});\r\n\r\nconsole.log('Location updated:', result.message);\r\n\n```\n\n## Real-time Updates\n\n### Connect to WebSocket\n\n```javascript\n// Get real-time client\r\nconst realtimeClient = client.getRealtimeClient();\r\n\r\n// Connect to real-time updates\r\nawait realtimeClient.connect();\r\n\r\n// Listen for connection events\r\nrealtimeClient.on('connect', () => {\r\n  console.log('Connected to real-time updates');\r\n});\r\n\r\nrealtimeClient.on('disconnect', () => {\r\n  console.log('Disconnected from real-time updates');\r\n});\r\n\r\nrealtimeClient.on('error', (error) => {\r\n  console.error('Real-time error:', error);\r\n});\r\n\n```\n\n### Subscribe to Events\n\n```javascript\n// Listen for specific events\r\nrealtimeClient.on('order_update', (order) => {\r\n  console.log('Order updated:', order.orderNumber);\r\n});\r\n\r\nrealtimeClient.on('shipment_update', (shipment) => {\r\n  console.log('Shipment updated:', shipment.id);\r\n});\r\n\r\nrealtimeClient.on('driver_update', (driver) => {\r\n  console.log('Driver updated:', driver.name);\r\n});\r\n\r\n// Subscribe to custom events\r\nrealtimeClient.subscribe('custom_event', (data) => {\r\n  console.log('Custom event received:', data);\r\n});\r\n\n```\n\n### Send Messages\n\n```javascript\n// Send custom message to server\r\nawait realtimeClient.send('driver_status', {\r\n  driverId: 'driver_123',\r\n  status: 'available',\r\n  location: { lat: 15.5007, lng: 32.5599 }\r\n});\r\n\n```\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with specific error types:\n\n```javascript\nimport {\r\n  AuthenticationError,\r\n  ValidationError,\r\n  RateLimitError,\r\n  ServerError\r\n} from '@amazol/logistics-sdk';\r\n\r\ntry {\r\n  const orders = await client.getAssignedOrders();\r\n} catch (error) {\r\n  if (error instanceof AuthenticationError) {\r\n    console.error('Authentication failed:', error.message);\r\n    // Handle authentication error\r\n  } else if (error instanceof ValidationError) {\r\n    console.error('Validation failed:', error.details);\r\n    // Handle validation error\r\n  } else if (error instanceof RateLimitError) {\r\n    console.error('Rate limit exceeded, retry after:', error.getRetryDelay());\r\n    // Handle rate limit error\r\n  } else if (error instanceof ServerError) {\r\n    console.error('Server error:', error.message);\r\n    // Handle server error\r\n  } else {\r\n    console.error('Unknown error:', error.message);\r\n  }\r\n}\r\n\n```\n\n### Error Types\n\n- **AuthenticationError**: Invalid or missing API key\r\n- **AuthorizationError**: Insufficient permissions\r\n- **ValidationError**: Invalid request data\r\n- **NotFoundError**: Resource not found\r\n- **RateLimitError**: Rate limit exceeded\r\n- **ServerError**: Internal server error\r\n- **NetworkError**: Network connectivity issues\r\n- **TimeoutError**: Request timeout\r\n- **WebSocketError**: WebSocket connection issues\n\n## Rate Limiting\n\nThe SDK automatically handles rate limiting and provides rate limit information:\n\n```javascript\n// Get rate limit information\r\nconst rateLimitInfo = client.getRateLimitInfo();\r\nif (rateLimitInfo) {\r\n  console.log(`Requests remaining: ${rateLimitInfo.remaining}/${rateLimitInfo.limit}`);\r\n  console.log(`Reset time: ${new Date(rateLimitInfo.reset * 1000)}`);\r\n}\r\n\n```\n\n## Webhooks\n\n### Get Webhook Information\n\n```javascript\nconst webhookInfo = await client.getWebhookInfo();\r\nconsole.log('Available events:', webhookInfo.data.events);\r\n\n```\n\n### Process Webhook Events\n\n```javascript\nconst result = await client.processWebhookEvent({\r\n  event: 'status_updated',\r\n  timestamp: '2024-01-17T14:00:00Z',\r\n  data: {\r\n    shipmentId: 'shipment_123',\r\n    status: 'delivered',\r\n    location: { lat: 15.5007, lng: 32.5599 }\r\n  }\r\n});\r\n\n```\n\n## Advanced Usage\n\n### Custom Request Options\n\n```javascript\n// Make request with custom timeout and headers\r\nconst orders = await client.getAssignedOrders(\r\n  { status: 'pending' },\r\n  {\r\n    timeout: 10000, // 10 seconds\r\n    headers: {\r\n      'X-Custom-Header': 'custom_value'\r\n    }\r\n  }\r\n);\r\n\n```\n\n### Update API Key\n\n```javascript\n// Update API key at runtime\r\nclient.updateApiKey('new_api_key_here');\r\n\n```\n\n### Get Client Configuration\n\n```javascript\n// Get current client configuration\r\nconst config = client.getConfig();\r\nconsole.log('Base URL:', config.baseUrl);\r\nconsole.log('Timeout:', config.timeout);\r\n\n```\n\n## Environment Variables\n\nYou can configure the SDK using environment variables:\n\n```bash\n# Required\nAMAZOL_API_KEY=your_api_key_here\n\n# Optional\nAMAZOL_BASE_URL=https://dev-api.amazol.store/api/v1/logistics\nAMAZOL_TIMEOUT=30000\nAMAZOL_RETRIES=3\nAMAZOL_RETRY_DELAY=1000\n\n```\n\n```javascript\nimport AmazolLogisticsClient from '@amazol/logistics-sdk';\r\n\r\nconst client = new AmazolLogisticsClient({\r\n  apiKey: process.env.AMAZOL_API_KEY,\r\n  baseUrl: process.env.AMAZOL_BASE_URL,\r\n  timeout: parseInt(process.env.AMAZOL_TIMEOUT || '30000'),\r\n  retries: parseInt(process.env.AMAZOL_RETRIES || '3'),\r\n  retryDelay: parseInt(process.env.AMAZOL_RETRY_DELAY || '1000')\r\n});\r\n\n```\n\n## Testing\n\nThe SDK includes comprehensive error handling and retry logic for testing scenarios:\n\n```javascript\n// Test with development server\r\nconst testClient = new AmazolLogisticsClient({\r\n  apiKey: 'test_api_key',\r\n  baseUrl: 'https://sandbox-api.amazol.store/v1/logistics',\r\n  retries: 1,\r\n  timeout: 5000\r\n});\r\n\r\n// Test error handling\r\ntry {\r\n  await testClient.getAssignedOrders();\r\n} catch (error) {\r\n  console.log('Expected error:', error.message);\r\n}\r\n\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## Support\n\n- **Documentation**: [https://docs.amazol.store/logistics](https://docs.amazol.store/logistics)\r\n- **API Reference**: [https://docs.amazol.store/logistics/api](https://docs.amazol.store/logistics/api)\r\n- **Support Email**: logistics-support@amazol.store\r\n- **GitHub Issues**: [https://github.com/amazol/logistics-api/issues](https://github.com/amazol/logistics-api/issues)\n\n## License\n\nThis SDK is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.\n","readmeFilename":"README.md"}