karrioapi/karrio-dashboard

The Open Source Shipping dashboard for karrio

This repository has been archived but the karrio docs have been moved to a monorepo https://github.com/karrioapi/karrio

Karrio Dashboard

Karrio Dashboard is a browser-based logistics and shipping app for karrio.

Getting Started

Using a Karrio Dashboard Release

If you just want to try Karrio out, check out the karrio/dashboard Docker Image to give it a whirl.

Building and Running Karrio Dashboard

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Node.js v14+
• A running instance of karrio server.

Installing

Clone the repository

git clone https://github.com/karrioapi/karrio-dashboard.git
cd karrio-dashboard
npm install

Configuration

Use the following environment variables to configure the dashboard:

• JWT_SECRET (required) - A secret to use for JWT key generation - you should set this explicitly.

• DASHBOARD_URL (required) - The URL of your dashboard to restrict the authentication host to your instance. If you are running the dashboard locally, set DASHBOARD_URL to: http://localhost:3000.

• KARRIO_PUBLIC_URL (required) - URL of a running instance of karrio server. If you are running karrio-server locally with the default settings, set KARRIO_PUBLIC_URL to: http://localhost:5002.

• KARRIO_URL (optional) - The internal network karrio API url.

Development

Start the development server

npm run dev

Karrio Dashboard should now be running at http://localhost:3000.

Production

Build the application bundle

npm run build

Resources

• Documentation
• Github Community
• Issue Tracker
• Blog

Join us on Discord

License

This project is licensed under the terms of the Apache 2 license.

See the LICENSE file for license rights and limitations.

Any other questions, mail us at [email protected] We’d love to meet you!

karrio-dashboard's Issues

Integrate user permissions feature flags with the dashboard

Is your feature request related to a problem? Please describe.

Currently, the dashboard exposes all the same functionalities to all users. I did like to be able to disable/hide functionalities that are not relevant based on their roles and permissions.

Describe the solution you'd like

The dashboard should dynamically expose or hide features from users based on their permissions.

Additional context

The purplship server Django backend already offers Group and Permission management.
The idea is to leverage that to design a role system and attach those to feature flags that should be served to the dashboard.

Clear distinction between test_mode entities versus live ones

Is your feature request related to a problem? Please describe.

When rates are listed in the dashboard, I cannot distinguish those returned from carrier connections
in test_mode from the live ones.

Describe the solution you'd like

I would like to have a clear distinction between test data from live ones.

Additional context

The Carrier Connection, Trackers, and Shipment lists should display live or test data only.

Address autocomplete is broken for non north-american addresses with Google Geocoding API

Describe the bug
The address autocompletes in the dashboard retrieves addresses but fails to autofill city, country upon selection.

To Reproduce
Steps to reproduce the behavior:

1. Go to 'Addresses'
2. Click on 'New Address' button
3. Scroll down to 'Street (Line 1)'
4. Enter a non-North American address (e.g: Austria)
5. Select one
6. See invalid autofill

Expected behavior
The city, country and any additional available info such as (postal code) should autofill properly

Desktop (please complete the following information):

• Browser chrome
• Version 2021.7

Quick Quotes

Is your feature request related to a problem? Please describe.

Sometimes we need to just get live shipment quotes and present them to interested parties without any definitive goal to finalize the fulfillment immediately.

Describe the solution you'd like

A simple solution could be a lightweight form where we can only enter origin and destination address lines with the package weight and dimensions without required fields like contact name, company name, phone numbers...

And retrieve a list of quotes.

[carrier-integration] ICS Courier

Is your feature request related to a problem? Please describe.
Request for new carrier support (ICS Courier Canada)

https://www.icscourier.ca/technology/ecommercetools.aspx#cta-block_APIIntegrations

Shipping and Tracking Analytics

Is your feature request related to a problem? Please describe.
There are currently not automated ways to get an overview of shipping operation stats.

Describe the solution you'd like
An analytics service that will provide shipping operation details such as:

• total label purchases
• total shipping spend
• Average price per rate
• Carrier services performance
• shipping trackers overview
• ...

Describe alternatives you've considered
Currently, I need to manually get the list of shipments or trackers by date range and other filters to retrieve a specific set and manually compute the relevant stats.

Woocommerce orders synced in purplship for fulfilment

Is your feature request related to a problem? Please describe.

I did like to get my Woocommerce orders imported in purplship.

Describe the solution you'd like

• Would be great to import orders from Woocommerce
• Would be nice to get Woocommerce orders synced with purplship as they come in

Additional context

The Woocommerce REST API Webhook is a great way to notify Purplship of incoming orders.

Persist carrier API response as well

Is your feature request related to a problem? Please describe.
It would be nice to have the carrier API requests/responses persisted for auditing and consolidations.
we had a case where it was amazing to have the real response from the API to prove something when the carrier overbilled

Describe the solution you'd like
Save the APIs response to a log as well.

Describe alternatives you've considered
Currently, I have to search through the massive purplship log files to retrieve raw carrier API requests and responses

Additional context
Maybe set a retention plan, like to be able to download a zip file of the logs, and then it will be removed

Integrate autocomplete + address validation powered by OpenCage

Is your feature request related to a problem? Please describe.
As a privacy-first business, the Google Geocoding API may cause privacy concerns to my customers.

Describe the solution you'd like
I propose the integration possibility to use alternative solutions that are more privacy-friendly

Describe alternatives you've considered
OpenCage is mature and very accurate to handle address validations. Could be an ideal alternative to the Google Geocoding API usage

Additional context

OpenCage website https://opencagedata.com/
Pricing compared to Google Geocoding https://opencagedata.com/reducing-your-google-geocoding-costs

Keep track of purplship-server events

Is your feature request related to a problem? Please describe.
purplship-server webhooks do not keep track of events received and dispatched to subscribers.

Describe the solution you'd like
persist purplship-server events in the database

Shopify orders synced in purplship for fulfilment

Is your feature request related to a problem? Please describe.

I did like to get my Shopify orders imported in purplship.

Describe the solution you'd like

• Would be great to import orders from Shopify
• Would be nice to get Shopify orders synced with purplship as they come in

Additional context

The Shopify REST API Webhook is a great way to notify Purplship of incoming orders.

Improve the purplship-server docker image

Describe the bug

Purplship image size is quite big with quite a long build time. The size has also made deployments difficult on some AWS services (e.g. Fargate)

Expected behaviour

Two valuable outcomes expected

• A faster build for better dev experience and faster release process
• A slim docker image that can improve installation time as well as simplify the deployment on public cloud platforms (particularly serverless)

Additional context

Many resources exist on how Python docker images can be optimized in disk space size as well as build time.

• Multi-stage build
• slimmer Python base image...

Display shipment tracking summary

Is your feature request related to a problem? Please describe.

On the Trackers page, the list displays relevant last know tracking status. That said sometimes I did like to see/review the full progression of the shipment and all pasts events.

Describe the solution you'd like

Display a shipment tracker summary when it is selected on the Trackers page.

Menu missing for smaller screens

Left menu is vanishing when browser window width gets lower.

Expected Behavior:
Burger menu icon should be shown.

Screenshot:

Canadian phone number formatting

Is your feature request related to a problem? Please describe.
I want the phone numbers displayed in the dashboard to match my local format.
I see inconsistent formatting for the Canadian phone number

Describe the solution you'd like
I'd like to view my Canadian phone numbers displayed with dashes like this: 800-999-9999

[enhancement] link logs with shipment

Is your feature request related to a problem? Please describe.
Looking for logs, related to shipments from the dashboard is not trivial

Describe the solution you'd like
It would be nice to have a link from the shipment to view the related logs

Describe alternatives you've considered
I wanted to do a search but currently not available either.

OpenAPI imported in Postman have double slashes `//` on the urls

Describe the bug

When OpenAPI specifications are exported into postman, the base path causes a double slash to appear in the
URL

To Reproduce

Steps to reproduce the behavior:

1. Go to the API Reference page
2. Click on the Download button to get the specifications
3. Import the downloaded file into Postman
4. You should see that the URLs have double slashes after the domain name

Expected behavior

The URL should only have one slash after the domain name: https://domain.com/api/token

Screenshots

Display shipments summary even after label has been purchased

Is your feature request related to a problem? Please describe.

When I buy a label using the dashboard, there is no way of seeing the full shipment summary from the dashboard

Describe the solution you'd like

It would be great to be able to click on a shipment in the list to view more details and summary

Shipments Notes

Is your feature request related to a problem? Please describe.

For internal communication within the fulfilment team, it would be great to have the possibility to add notes to shipments explaining any issues or important comments others should be aware of when processing the shipment.

Describe the solution you'd like

The ability to view a list of notes attached to a shipment

[carrier-integration] Asendia US carrier integration

Is your feature request related to a problem? Please describe.
purplship currently doesn't support Asendia US services

Describe the solution you'd like
Integrate purplship with the Asendia US API

Additional context
Asendia US API documentation links:

• Shipping API https://a1api.asendiausa.com/swagger/index.html?urls.primaryName=ShippingPlatform%20v1.0
• Tracking API https://a1api.asendiausa.com/swagger/index.html?urls.primaryName=Tracking%20v2.0

[performance] Use ASGI by default

Is your feature request related to a problem? Please describe.

Even though we haven't specifically focused on high-scale deployment specifically. Running purplship-server with Uvicorn is just a line change and close to reach

Describe the solution you'd like

Test the compatibility of purplship with uvicorn and use that by default to run the server

API tracing logs query permissions and dashboard listing

Write End to End tests

Is your feature request related to a problem? Please describe.

Now that the web app is getting richer and richer in functionalities, it would be great to start writing end to end tests
to prevent regressions

Describe the solution you'd like

Use a tool like Cypress or alternatives to write end to end tests

Interface Doesn't Support Multiple Parcels

Is your feature request related to a problem? Please describe.
Interface Doesn't Support Multiple Parcels

[carrier-integration] Nationex

Is your feature request related to a problem? Please describe.
Request for new carrier support (Nationex Canada)

https://www.nationex.com/en/

[performance] Setup Redis for caching

Is your feature request related to a problem? Please describe.

Purplship server being built on Django can benefit from the ecosystem best practices to cater to users with high
scalability requirements.

Describe the solution you'd like

It is all about configuration. Setup the purplship Django settings to allow for turning on of caching with Redis.

Tracking / Label creation does not work: Network Error

Describe the bug
Tracking / Label creation does not work. Dashboard tries to call invalid API URLs.

To Reproduce
Steps to reproduce the behavior:

1. Set up a fresh karrio instance:

git clone --depth 1 https://github.com/karrioapi/karrio
cd karrio/docker
sudo docker-compose up

2. Log into the dashboard.
3. Setup carrier.
4. Try tracking or creating label.
5. "Network error" is shown, or browser network inspector shows API error.

Desktop (please complete the following information):

• OS: Ubuntu 22.04
• Browser: Chrome, Firefox
• Version: karrio 2023.1.6

Additional context

docker-compose.yml > dashboard > environment: KARRIO_URL: http://api:${KARRIO_HTTP_PORT:-5002} (default)

docker-compose.yml > dashboard > environment: KARRIO_URL: ${KARRIO_PUBLIC_URL}

Return Carrier Tracking URL

Is your feature request related to a problem? Please describe.
Carriers sometimes change their tracking URLs, it would be expected that the platform responsible for the carrier connections should maintain the tracking URLs

Describe the solution you'd like
It would be super useful if the API would return the full carrier tracking URL or the base URL which can be joined with the tracking number to create a full URL i.e. https://wwwapps.ups.com/etracking/tracking.cgi?tracknums_displayed=25&TypeOfInquiryNumber=T&HTMLVersion=4.0&InquiryNumber=1Z0000000000000000

Describe alternatives you've considered
Considered maintaining them on the client side, but it becomes complicated when adding a new carrier

Configurable currency preference support

Is your feature request related to a problem? Please describe.
International carriers return monetary values in the currency of the shipment origin or default to USD and that can lead to inconsistencies

Describe the solution you'd like
It would be great to have a way of configuring preferred currency per system or per organization. So that returned monetary values are consistent for a user.

[purplship-dashboard] Migrate purplship-webapp to Nextjs

Is your feature request related to a problem? Please describe.

Decouple the purplship React project from the Django build into a Nextjs independent project.

For more details https://github.com/purplship/purplship-server/discussions/143

[carrier-integration] UPS Ground services

Is your feature request related to a problem? Please describe.
Missing UPS ground services for shipment

Describe the solution you'd like
Add a purplship-sdk extension for UPS Ground or augment the current purplship.ups integration to support UPS Ground services

Add Tax ID to address forms

Is your feature request related to a problem? Please describe.
Karrio support both federal_tax_id and state_tax_id. For international shipments, those fields are
required to pass EIN, SSN and other tax ids

Describe the solution you'd like
Add form fields for the tax identifiers so that they may be editable

Errors when fields are not completed

Do not allow saving at the present screen when all required data is not filled in. This will avoid having an error popup later when fetching rates or buying labels.

docker image Python installation warning

Describe the bug

the purplship-server docker image warns against python installation as root.

Expected behaviour

Follow the best practice to install purplship and other Python dependencies in a virtual environment and without using root.

Tags for shipment

Is your feature request related to a problem? Please describe.

Shipments fulfilment goes through certain stages when we receive customers orders, depending on many factors.
For example the stock availability.
Tags are a great way to communicate in the operation team to label shipments states.

Describe the solution you'd like

Be able to assign a tag to a shipment. The tag should be identifiable by colours. Also, a legend where labels could be assigned to tags

Team management

Is your feature request related to a problem? Please describe.
I can't manage users and access of organizations (workspaces) from the dashboard

Describe the solution you'd like
Add a panel under settings where one can manage users with access to an org space.
Manage invitations for team members.

[enhancement] Allow pagination with numbers

Is your feature request related to a problem? Please describe.
There is no way to jump pages with the current pagination.
currently, I need to press back multiple times

Describe the solution you'd like
Be able to paginate to a page number

Dashboard Doesn't Show Aggregator Name

Describe the bug
In the case a shipment was created through an aggregator, I.e. UPS through eShipper there's no way to know who the shipping aggregator was, as only the carrier is displayed

To Reproduce
Steps to reproduce the behavior:

1. Create a shipment with any aggregator
2. Open the shipment in the dashboard

Expected behavior
Both the aggregator and the actual carrier is shown

Dashboard doesn't load -> "Failed to fetch API data from (http://localhost:5002)"},

Describe the bug
after the login the dashboard shows an error: Failed to load intial data...
log shows the following error
karrio.dashboard | {"level":50,"time":1676405017300,"env":"production","msg":"Failed to fetch API data from (http://localhost:5002)"}

To Reproduce

1. follow: https://github.com/karrioapi/karrio

git clone --depth 1 https://github.com/karrioapi/karrio
cd karrio/docker
docker compose up

2. open localhost:3000 in the browser
3. login

Expected behavior
karrio-dashboard loads without error

Additional context
I believe the commit below wrongly introduces requests to the external api (KARRIO_PUBLIC_URL=localhost:5002) instead of using the docker-internal endpoint api:5002

c85c1f7#diff-8c678336fa1cb4a656e7fb03ef26cd9e240dad3cd3aa7de7f08334fa500d8e86L78

When using a productive setup with DNS names the issue is unlikely to be visible but it breaks a local test setup.

Exception raised when carriers don't return tracking details and no error messages

Describe the bug

When carrier requests are empty (which happens rarely), the tracking endpoints raise an exception causing a 500 internal server error.

To Reproduce

Steps to reproduce the behavior:

1. Setup a purolator_courier account
2. Send a tracking request using /v1/trackers/purolator_courier/222 with a random tracking number
3. You will receive a 500 error from the server

Expected behavior

Return a 404 not found with a clear message

API healthcheck endpoint

Is your feature request related to a problem? Please describe.

There is currently no endpoint available to collect the health status of the Purplship API.
That can be a limitation for deployment on certain cloud platforms that require a health check endpoint to ensure the successful deployment of a purplship server instance.

Describe the solution you'd like

An API endpoint displaying the server status:

• Database connection
• Static files availability
• Response to a ping...
• Any other relevant details

Describe alternatives you've considered

As a workaround, /login/ page could be used for health check until then

Purplship Dashboard for tracking only

Is your feature request related to a problem? Please describe.

I did like to use Purplship solely for shipment tracking for my business (eCommerce, Freight forwarding, Marketplace...).
This could be a great OSS alternative to super expensive Saas options.

Describe the solution you'd like

• A dashboard focused on shipment tracking
• A branded tracking page that could be sent to customers

Cancel shipment error

Describe the bug
Whenever you try to cancel a shipment, it returns a status 400 error.

To Reproduce
Steps to reproduce the behavior:

1. Go to Shipments
2. Click on Shipments Menu
3. Click on 'Cancel Shipment'
4. See error

Expected behavior
The shipment would be canceled and label be voided.

Screenshots

Desktop (please complete the following information):

• OS: Windows 11
• Browser Chrome
• Version 100.0.4896.88

Show estimated delivery on trackers preview

Is your feature request related to a problem? Please describe.
The estimated delivery date/time is not displayed on the tracker preview in the dashboard.

Describe the solution you'd like
It would be nice to have it there as well as on the default branded tracking page

The OpenAPI download does not add the `.json` file extension

Describe the bug

On the API Reference page, clicking on the Download button returns a file without extension.
Could be confusing since, OpenAPIs can come as .json or .yml files

Expected behavior

Return an OpenAPI schema file with the right extension

Screenshots

I want a `purplship.js` API client that can be imported into my app to integrate purplship

Is your feature request related to a problem? Please describe.

A purplship JS client would be of great help simplify API calls to Purplship from the browser

Describe the solution you'd like

I did like to be able to import Purplship in the browser and make API calls from my web app

...
<script src="https://api.purplship.com/purplship.min.js"></script>
...
<script>
const pship = new Purplship('api_key');

(async () =>  {
     const rates = await purplship.proxy.fetchRates(...);
})
</script>

[performance] Make Huey background workers deployment more configurable

Is your feature request related to a problem? Please describe.

Currently, as minimum viable integration, purplship-server runs in the same docker container as Huey (worker).
This limits the resources available for purplship-server and defies the simple process motto of docker.
The good news is that Huey can be deployed in its own docker container it's just a matter of configuration.

Describe the solution you'd like

An. ideal way forward will be the possibility to configure Huey so that it can be deployed in a dedicated container

[enhancement] add filter for logs

Is your feature request related to a problem? Please describe.
I have a lot of proxy rate requests and no easy way to filter through other API logs

Describe the solution you'd like
It would be nice to be able to filter by endpoints

CSV orders imports

Is your feature request related to a problem? Please describe.

Integrate a way to import multiple orders at once into purplship-server for fulfillment.
This will allow batch processing (meaning a large volume of shipment processed at once)

Describe the solution you'd like

I did like to be able to export orders from my platform (ERP, marketplace, eCommerce...) in a CSV file and import them in purplship for fulfilment.

Special characters + single quote in env vars breaks purplship-server

Describe the bug
If environment variables have special characters in them (such as setting the admin password - e.g. containing a single quote) it can break things and prevent server from starting.

To Reproduce
Steps to reproduce the behavior:
In 2021.6-rc3 set ADMIN_PASSWORD env to a string containing special characters (particularly a single quote) and run purplship-server.

Expected behavior
Input from environment variables should be properly handled in all cases. ADMIN_PASSWORD with special characters should definitely be supported as it is considered a best practice to use high-entropy passwords