JavaScript client SDK for Flexport's API v2

JavaScript client SDK client for Flexport's API v2

Note: This library is not feature complete, until then 1.x releases may contain breaking changes.

Installation

npm i --save @distributeaid/flexport-sdk

Usage

see ./src/examples for working examples.

Create a client

import { v2Client } from "@distributeaid/flexport-sdk";

const client = v2Client({ apiKey: "your api key" });

Query a resource

import * as TE from "fp-ts/lib/TaskEither";
import { pipe } from "fp-ts/lib/pipeable";

pipe(
  client.shipment_index(),
  TE.map((shipments) => {
    console.dir(shipments, { depth: 9 });
  })
)();

Follow links

import { liftShipmentLeg } from "@distributeaid/flexport-sdk";

pipe(
  client.shipment_show({ id: shipmentId }),
  TE.map(({ legs }) => legs), // Extract legs link, Option<ResolvableCollection>
  TE.chain(TE.fromOption(() => createError("Shipment has no legs!"))),
  TE.chain(client.resolveCollection(liftShipmentLeg)), // Resolve the link to the collection
  TE.map((legs) => {
    console.dir(legs, { depth: 9 });
  })
)();

Paginate a collection

import { paginate } from "@distributeaid/flexport-sdk";

pipe(
  client.shipment_index(),
  TE.chain(paginate(client.resolvePage(liftShipment))),
  TE.map((shipments) => {
    console.dir(shipments, { depth: 9 });
  })
)();

Generation of base types

The types in ./src/generated are generated using ./src/bin/generateTypes.ts, which parses the Open API 3 definition file (source). However this API documentation contains errors, which are corrected in the schema through a file containing corrections, before the base types are generated.

Lifting of base types

The lifters in the same files lift the Flexport API responses into the SDK domain, by augmenting them with higher level properties. They are generated with the API client using ./src/bin/generateApiOperations.ts.

Architecture decision records (ADRs)

see ./adr.