kwikng

A NodeJS Wrapper for Kwik Delivery

Overview

This project provides an easy-to-use object-oriented API to access endpoints delineated at https://apikwik.docs.apiary.io/#reference OR https://liveapikwik.docs.apiary.io/#reference

Getting Started

Install from the NPM Registry

    $ npm i --save kwik-node

API Values Format Codes ( Chart )

API REQUEST STATUSES:

| Title | Code | Description | |---------------------|------|----------------------------| |PARAMETER_MISSING | 100 | A parameter is missing | |INVALID_KEY | 101 | Invalid access token | |ACTION_COMPLETE | 200 | Successful request | |ERROR_IN_EXECUTION | 404 | An Error Occured |

TASK/JOB STATUSES:

| Title | Code | Description |-----------|------|--------------------------------------------------------------------| |UPCOMING | 0 | The task has been assigned to a agent | |STARTED | 1 | The task has been started and the agent is on the way | |ENDED | 2 | The task has been completed successfully | |FAILED | 3 | The task has not been completed successfully | |ARRIVED | 4 | The task is being performed;agent has reached the destination | |UNASSIGNED | 6 | The task has not been assigned to any agent | |ACCEPTED | 7 | The task has been accepted by the agent which is assigned to him | |DECLINE | 8 | The task has been declined by the agent which is assigned to him | |CANCEL | 9 | The task has been cancelled by the agent which is accepted by him | |DELETED | 10 | The task is deleted by the agent |

PAYMENT METHODS:

| Title | Code | Description | |--------------|--------|------------------------------------------------------------| |CARD | 32 | The task will be paid for using paystack card option | |CASH | 8 | The task will be paid for using cash in currency of local | |STRIPE | 2 | The task will be paid for using stripe card option | |WALLET (PAGA) | 131072 | The task will be paid for using a paga wallet option |

VEHICLE SIZES:

| Code | Description | |------|----------------------| | 0 | A motorcycle (bike) | | 1 | A small car | | 2 | A medium car | | 3 | A large truck |

DELIVERY CHARGES:

| Code | Description | |------|------------------------------------------------------------| | 1 | Paid by the buyer (your own customer whom you deliver to) | | 2 | Paid by the kwik customer (you whom are using this API) |

TIMEZONES:

| Title | Code | Description | |---------------------------|------|------------------------------| |INDIAN STANDARD TIME (IST) | -330 | offset from UTC in minutes | |CENTRAL AFRICAN TIME (CAT) | +180 | offset from UTC in minutes | |WEST AFRICAN TIME (WAT) | +60 | offset from UTC in minutes |

Usage

const Kwik = require('kwik-node')
const express = require('express')


const domainName = process.env.KWIK_DOMAIN_NAME; // 'app-test.kwik.delivery'
const environment = process.env.NODE_ENV; // 'production'

const kwikClient = new Kwik(
    domainName, 
    environment === 'production'
);

const app = express()
const port = 3000

/* setup a middleware to load up the API access_token via auth */
app.use('/create/delivery', async (req, res, next) => {
  if(req.method.toLowercase() === 'post'){
    let response = {
        body: {
            status:0,
            data: {
                access_token: '',
                vendor_details: {
                    vendor_id: '',
                    card_id: '',
                    user_id: ''
                }
            }
        }
    }

    try {
        response = await kwikClient.adminLogin({ 
            email: process.env.KWIK_ACCOUNT_EMAIL,
            password: process.env.KWIK_ACCOUNT_PASSWORD
        });
    } catch(error) {
        throw error;
    }


    kwikClient.setAccessToken(
        response.body.data.access_token
    );

    kwikClient.setVendorId(
        response.body.data.vendor_details.vendor_id
    );

    kwikClient.setUserId(
        response.body.data.vendor_details.user_id
    );

    kwikClient.setCardId(
        response.body.data.vendor_details.card_id
    );
  }

  next();
});



/* global error handler */
app.use(function (err, req, res, next) {
  res.status(500).send(err.message)
});


/* standard app endpoint to create a delivery task for dispatch by kwik dispatch riders */
app.post('/create/delivery', async (req, res) => {
    const today = new Date()
    const deliveries = [
            {
              address: req.body.delivery_address,
              name: req.body.business_name,
              latitude: req.body.choords.delivery_lat,
              longitude: req.body.choords.delivery_long,
              time: "2022-06-03 12:48:24",
              phone: req.body.mobile_number,
              email: req.body.email,
              has_return_task: false,
            }
    ];
    const pickups = [
            {
              address: req.body.pickup_address,
              name: "My Business name",
              latitude: req.body.choords.pickup_lat,
              longitude": req.body.choords.pickup_long,
              time: "2022-06-03 11:02:30",
              phone: "+2347045804049",
              email: "[email protected]"
            }
    ];

    /* NOTE: 
        no need to include 'domain_name', 'access_token' and 'vendor_id'
        as they are included automatically as long as the express middleware
        above obtains the details correctly in the middleware above using
        kwikClient.adminLogin() and sets all the details accordingly
    */

    /* HINT:
       It's vital to get Loaders and Vehicles info for your delivery task before
       that delivery task can be scheduled/created
    */

    /* Loaders info */
    const loaderDetails = await kwikClient.fetchAllLoadersOnAmount()

    /* Vehicles info */
    const vehicleDetails = await kwikClient.fetchAllAvailableDeliveryVehicles({
        size: 1 /* a small car (see API values format codes above 👆🏾) */
    });

    const deliveryTaskDetails = await kwikClient.getExactPricingForDeliveryTask({
        custom_field_template: 'pricing-template',
        auto_assignment: 1,
        layout_type: 1,
        pickup_custom_field_template: 'pricing-template',
        has_pickup: 1,
        has_delivery: 1,
        vehicle_id: vehicleDetails.body.data[0].vehicle_id,
        parcel_amount: 0,
        is_cod_job: 0, /* No collect on delivery */
        delivery_images: 'https://res.cloudinary.com/kwiky/image/upload/v1648282178/mova/item.png', /* The URL of the image of the item being delivered */
        delivery_instruction: 'Please, hand it over to the nanny', /* The instruction for the person who's to recieve the item being delivered */
        is_loader_required: loaderDetails.body.data.is_loader_enabled, /* equals 0; no loaders enabled */
        is_multiple_tasks: 1,
        payment_method: 32, /* payment via card */
        is_schedule_task: 0, /* task will not be scheduled in future */
        deliveries,
        pickups
    });

    console.log(
        'CURRENCY: ', 
        JSON.stringify(deliveryTaskDetails.body.data.currency, null, '\t')
    );

    console.log(
        'COST PER TASK (AMOUNT): ', 
        deliveryTaskDetails.body.data.per_task_cost
    );

    const cost_per_task = deliveryTaskDetails.body.data.per_task_cost

    const deliveryPaymentBreakDownDetails = await kwikClient.getEstimatedPriceForDeliveryTask({
        promo_value: 0,
        amount: String(cost_per_task),
        pickup_time: today.toISOString().replace('T', ' ').replace(/(?:\.[\d]{2,3}Z)/, ''),
        total_service_charge: deliveryTaskDetails.body.data.total_service_charge,
        vehicle_id: deliveryTaskDetails.body.data.vehicle_id,
        delivery_images: deliveryTaskDetails.body.data.delivery_images,
        delivery_instruction: deliveryTaskDetails.body.data.delivery_instruction,
        delivery_charge_by_buyer: 1, /* buyer pays for delivery charge (see API values format codes above 👆🏾) */
        is_cod_job: deliveryTaskDetails.body.data.is_cod_job,
        parcel_amount: deliveryTaskDetails.body.data.parcel_amount,
        is_loader_required: deliveryTaskDetails.body.data.is_loader_required,
    });

    const response = await kwikClient.scheduleDeliveryTask({
        team_id: 2, /* get your `team_id` from your admin dashboard */
        timezone: '+60', /* west african timezone (see API values format codes above 👆🏾) */
        auto_assignment: 1,
        layout_type: 1,
        is_multiple_tasks: 1,
        is_cod_job: deliveryTaskDetails.body.data.is_cod_job,
        delivery_charge_by_buyer: deliveryPaymentBreakDownDetails.body.data.delivery_charge_by_buyer,
        delivery_charge: deliveryPaymentBreakDownDetails.body.data.DELIVERY_CHARGE,
        collect_on_delivery: deliveryPaymentBreakDownDetails.body.data.COLLECT_ON_DELIVERY,
        surge_cost: deliveryPaymentBreakDownDetails.body.data.SURGE_PRICING,
        surge_type: deliveryPaymentBreakDownDetails.body.data.SURGE_TYPE,
        cash_handling_charges: deliveryPaymentBreakDownDetails.body.data.CASH_HANDLING_CHARGE,
        cash_handling_percentage: deliveryPaymentBreakDownDetails.body.data.CASH_HANDLING_PERCENTAGE,
        net_processed_amount: deliveryPaymentBreakDownDetails.body.data.NET_CASH_PROCEEDS,
        kwister_cash_handling_charge: deliveryPaymentBreakDownDetails.body.data.KWISTER_CASH_HANDLING_CHARGE,
        is_loader_required: deliveryTaskDetails.body.data.is_loader_required,
        delivery_images: deliveryTaskDetails.body.data.delivery_images,
        delivery_instruction: deliveryTaskDetails.body.data.delivery_instruction,
        insurance_amount: deliveryTaskDetails.body.data.insurance_amount,
        total_no_of_tasks: deliveryTaskDetails.body.data.total_no_of_tasks,
        total_service_charge: deliveryTaskDetails.body.data.total_service_charge,
        parcel_amount: deliveryTaskDetails.body.data.parcel_amount,
        payment_method: 32, /* payment via card (see API values format codes above 👆🏾) */
        amount: String(cost_per_task),
        deliveries: deliveryTaskDetails.body.data.deliveries,
        pickups: deliveryTaskDetails.body.data.pickups
    });

    res.status(response.body.status).send(response.body.message)
});

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`)
});

API Resources

Each method expects an object literal with both route parameters and request parameters (query / body). Please, go through the src/Kwik/index.js apiEndpoints object to see the specific items that should make up the object literal for each method and their types

• Tasks
  • kwikClient.cancelDeliveryTask()
  • kwikClient.scheduleDeliveryTask()
• Vehicles
  • kwikClient.fetchAllAvailableDeliveryVehicles()
• Loaders
  • kwikClient.fetchAllLoadersOnAmount()
• Pricing
  • kwikClient.getExactPricingForDeliveryTask()
  • kwikClient.getEstimatedPriceForDeliveryTask()
• Payments
  • kwikClient.fetchAllMerchantCards()
  • kwikClient.addMerchantCard()
  • kwikClient.deleteMerchantCard()
• Corporates
  • kwikClient.createCorporate()
  • kwikClient.listAllCorporates()
  • kwikClient.listAllCorporatesInvoices()
  • kwikClient.listAllCustomersPerCorporates()
  • kwikClient.listAllCorporatesInvoicesSub()
• Task Details ( Jobs )
  • kwikClient.getSingleDeliveryTaskDetails()
  • kwikClient.getAllDeliveryTaskDetails()
  • kwikClient.getDeliveryTaskStatus()

License

MIT

Credits

• Ifeora Okechukwu

Contributing

See the CONTRIBUTING.md file for info

Support

Coolcodes is a non-profit software foundation (collective) created by Oparand - parent company of StitchNG, Synergixe based in Abuja, Nigeria. You'll find an overview of all our work and supported open source projects on our Facebook Page.

Follow us on facebook if you can to get the latest open source software/freeware news and infomation.

Does your business depend on our open projects? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.