Git Product home page Git Product logo

kwikng's Introduction

kwikng

NPM Version Build Status

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

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.

kwikng's People

Contributors

dependabot[bot] avatar isocroft avatar olaoluwa-98 avatar stitchng avatar

Stargazers

 avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

kwikng's Issues

Error while running any method.

Every method I have tried on the KwikClient always returns this error

The `body` option must be a plain Object or Array when the `form` or `json` option is used

Setting a number field to 0 causing errors

I noticed whenever a Number field is set to 0, the library transforms it to 'null'. This makes the request fail when it gets to Kwik.

An example is if I set has_delivery or layout_type to 0, the eventual payload becomes has_delivery: 'null' and layout_type: 'null', instead of has_delivery: 0 and layout_type: 0.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.