linnworks-channel-integration

Quickly and easily create Express servers for custom Linnworks channel integrations

Usage no npm install needed!

<script type="module">
  import linnworksChannelIntegration from 'https://cdn.skypack.dev/linnworks-channel-integration';
</script>

README

Linnworks Channel Integration Utility

This package is a work-in-progress utility to simplify the process of building and serving custom channel integrations for Linnworks. Written entirely in TypeScript.

Features

  • Automated user management
  • Request and response type interfaces for all supported endpoints
  • Rich logging for requests, responses and errors, courtesy of Winston
  • Automatic manifest generation

Requirements

This package uses Mongoose to manage integration users and store their marketplace credentials, so you will need to have an active MongoDB service running on your server to make use of this library.

Installation

yarn add linnworks-channel-integration / npm i linnworks-channel-integration

Usage

const server = createChannelIntegrationServer({
    channelIdentifier: 'coolMarketplace',
    channelFriendlyName: 'My Cool Marketplace',
    channelLogo: 'cool-logo.png',
    baseUrl: 'https://cool-marketplace.mywebsite.com',
    authFields,
    testChannelIntegration,
    getInventory,
    getOrders,
    dispatchOrders,
});

server.listen(APP_PORT, () => {
    console.log(`Server running on port ${ APP_PORT }`);
});

A manifest file will be created on app launch, which should be copied and pasted into the application manifest on the Linnworks Developer Portal.

Options

channelIdentifier

This should be a unique string with no spaces or special characters. Used as the MongoDB database name.

channelFriendlyName

Used as the channel name in the integration manifest.

channelLogo

This should be the filename for a 57x57 PNG displaying the marketplace logo. The file should be placed inside an 'assets' folder located at the project root.

baseURL

This should be set to the public URL for your marketplace integration. Used when creating the application manifest.

authFields

interface ChannelAuthField {
    id: string;
    label: string;
    description: string;
    secret: boolean;
}

These fields will appear in the integration config screen in Linnworks. Use them to capture the credentials required when authenticating with the marketplace API.

The id and current input value for each field are passed into the marketplace functions as key-value pairs within the authInfo parameter.

N.B. Use secret: true for sensitive credentials (e.g. tokens and passwords)

testChannelIntegration

type ConfigTest = (
    authInfo: { [key: string]: string }
) => Promise<boolean>;

This function should attempt to log into the marketplace using the provided credentials. Only return true if the connection is successful, otherwise return false.

getInventory

type GetInventory = (
    page: number,
    authInfo: { [key: string]: string }
) => Promise<LWProductResponse>;

This function should return a list of marketplace inventory items to enable inventory mapping.

N.B. This library exposes a getLinnworksInventory function which returns your current Linnworks inventory. This enables SKU mapping even if the marketplace does not have an inventory API. Requires axios and the creation of an authField in the channel config with id: 'LWToken'.

getOrders

type GetOrders = (
    page: number,
    lastUpdated: string,
    authInfo: { [key: string]: string }
) => Promise<LWOrdersResponse>;

This function should return all of the active marketplace orders updated since the last succesful fetch.

Format of lastUpdated: ​"yyyy-MM-dd HH:mm:ssZ".

dispatchOrders

type DispatchOrders = (
    orders: LWDispatchOrder[],
    authInfo: { [key: string]: string }
) => Promise<LWDispatchResponse>;

Used to dispatch orders and supply tracking information for the marketplace.

Request and Response Schemas

All LW-prefixed types (e.g. LWOrdersResponse, LWDispatchOrder) are thoroughly documented on the Linnworks Channel Integration Guide.