Runnr NodeJs Wrapper
A node wrapper library for Runnr hyper local delivery service. In-built OAuth. You don't need to worry about getting and maintaining an access token. Just set your keys and you are good to go!
npm install roadrunnr
Include and configure your keys
var runnr = require('roadrunnr');
runnr.setKeys(CLIENT_ID, CLIENT_SECRET);
APIs available
- Create shipment - with an option to auto-retry
- Track shipment
- Cancel shipment
- Check serviceability
- Check account balance
- Check order level charges
Bonus
Create shipment
var orderRequest = new runnr.OrderRequest();
// Add pickup details
orderRequest.pickup.user.name = '';
orderRequest.pickup.user.phone_no = '';
orderRequest.pickup.user.email = '';
orderRequest.pickup.user.type = '';
orderRequest.pickup.user.external_id = '';
orderRequest.pickup.user.full_address.address = '';
orderRequest.pickup.user.full_address.locality.name = ''; // Can be skipped, see below
orderRequest.pickup.user.full_address.sub_locality.name = ''; // Can be skipped, see below
orderRequest.pickup.user.full_address.city.name = '';
orderRequest.pickup.user.full_address.geo.latitude = "plat"; // Optional, string format
orderRequest.pickup.user.full_address.geo.longitude = "plng"; // Optional, string format
// Add drop details
orderRequest.drop.user.name = '';
orderRequest.drop.user.phone_no = '';
orderRequest.drop.user.email = '';
orderRequest.drop.user.type = '';
orderRequest.drop.user.external_id = '';
orderRequest.drop.user.full_address.address = '';
orderRequest.drop.user.full_address.locality.name = ''; // Can be skipped, see below
orderRequest.drop.user.full_address.sub_locality.name = ''; // Can be skipped, see below
orderRequest.drop.user.full_address.city.name = '';
orderRequest.drop.user.full_address.geo.latitude = "dlat"; // Optional, string format
orderRequest.drop.user.full_address.geo.longitude = "dlng"; // Optional, string format
// Order Details
orderRequest.order_details.order_id = '';
orderRequest.order_details.order_value = '0';
orderRequest.order_details.amount_to_be_collected = '0';
orderRequest.order_details.order_type.name = 'CashOnDelivery';
orderRequest.order_details.order_items[0].quantity = 1;
orderRequest.order_details.order_items[0].price = 0;
orderRequest.order_details.order_items[0].item.name = '';
orderRequest.order_details.created_at = "YYYY-MM-DD hh: MM";
orderRequest.callback_url = 'your.domain/url'; // OPTIONAL
runnr.createShipment(orderRequest, function(error, response) {
console.log(response);
});
Roadrunnr allows you to skip the "locality" and "sub_locality" parameters if you provide the accurate lat & long for the addresses. I've added a geocoder which converts the address almost accurate lat long. Instrutions here.
Auto Retry
Using this option allows the module to retry assigning a runnr for an OrderRequest which led to a 706 error from Runnr (no runnrs available at the moment). Place the following code right below the part where you set your keys.
runnr.events.on(runnr.RETRY_ERROR, function(orderId) {
console.log("Retry failed for orderId: " + orderId); // This is the order_id provided in OrderRequest.order_details.order_id
});
runnr.events.on(runnr.RETRY_SUCCESS, function(orderId) {
console.log("Retry success for orderId: " + orderId); // This is the order_id provided in OrderRequest.order_details.order_id
});
Call the createShipment
API with retry options.
var options = {
retry : true,
retryTime : 5 // in seconds
};
runnr.createShipment(orderRequest, options, function(error, response) {
if (error) {
console.error(error);
} else {
console.log(response);
}
});
Track shipment
runnr.trackShipment(id, function(error, response) {
if (error) {
console.error(error);
} else {
console.log(response);
}
});
Cancel shipment
runnr.cancelShipment(id, function(error, response) {
if (error) {
console.error(error);
} else {
console.log(response);
}
});
Check serviceability
runnr.checkServiceability(orderRequest, function(error, response) {
if (error) {
console.error(error);
} else {
console.log(response);
}
});
Check serviceability
runnr.checkAccountBalance(function (error, response) {
if (error) {
console.error(error);
} else {
console.log(response); // Balance at response.current_balance
}
});
Check serviceability
runnr.getOrderLevelCharges("RUNNR_ORDER_ID", function (error, response) {
if (error) {
console.error(error);
} else {
console.log(response); // Charges at response.total_charge
}
});
(OPTIONAL) Auto assign lat & long
Please run npm install geocoder
before using the following function. You can skip the locality
and sub_locality
fields using this.
IMPORTANT NOTE : This function geocodes the address in orderRquest.pickup.user.full_address.address
and orderRequest.drop.user.full_address.address
. Make sure this the complete address which includes the city name and the pin code.
orderRequest.pickup.user.full_address.locality.name = 'BYPASS_LOCALITY';
orderRequest.pickup.user.full_address.sub_locality.name = ''; // Can be left blank
orderRequest.drop.user.full_address.locality.name = 'BYPASS_LOCALITY';
orderRequest.drop.user.full_address.sub_locality.name = ''; // Can be left blank
runnr.assignLatLong(orderRequest, function(error, newOrderRequest) {
if (error) {
// There was some error geocoding one of the addresses
} else {
runnr.createShipment(newOrderRequest, function(error, response) {
if (error) {
console.error(error);
} else {
console.log(response);
}
});
}
});
(OPTIONAL) Use test environment
To use Roadrunnr's test portal, just change the environment. This module uses the production server by default.
runnr.setEnvironment('test');
(OPTIONAL) Change OAuth token filepath
To use Roadrunnr's test portal, just change the environment. This module uses the production server by default.
runnr.setOAuthPath('./path/to/OAuth/file.json');
(OPTIONAL) RawParser middleware for Express
Roadrunnr callbacks are of type application/octet-stream
, and rawBody has been dropped from the request object in newer versions of Express. Here is a simple rawbody parser for roadrunnr callbacks
app.post('/roadRunnr/callback', runnr.rawParser, function(req,res) {
console.log(req.rawBody);
res.send("OK");
});
Changes in v0.0.7
- Switched to Runnr HTTPS server for production requests
- New Runnr OAuth flow
- Check account balance
- Check order level charges
Changes in v0.0.6
This wrapper now has an option to auto-retry in cases of 706 error from runnr.
Changes in v0.0.5
This wrapper now checks for errors thrown by the Roadrunnr API. Please check for errors in all API calls.
Submit issues
You can raise an issue in this repo or mail me at sidhant@hashexclude.com