`bananas-commerce`

The JavaScript client for bananas-commerce.

import * as bcom from "bananas-commerce";

const client = generateBcomClient({
  baseUrl: "https://bcom.example.com",
  config: {
    countryCode: "SE",
    siteCode: "SE",
  },
  extensions: [
    new ObayatyBcomExtension(),
    new Extensions.Pos(),
    new Extensions.Webshipper(),
    new Extensions.Adyen(),
  ],
});

const checkout = await client.adyen.begin({
  checkoutSession: "..",
});

Prerequisites

Prerequisites apart from having the whole bcom repo cloned and the prerequisites for running the backend is only deno unless you want to publish a new version to npm, but that should not be needed as CI takes care of that.

Coverage

If you want to generate cobertura coverage locally you need two additional dependencies installed locally from pip: lcov_cobertura and pycobertura. The default behaviour of deno task test:coverage is to generate a cobertura report but that comes with a >50% performance hit because of the lcov to cobertura coverage format conversion (not that it is a huge problem, it's about 0.5s...).

If you want coverage reporting locally without using either lcov or cobertura, simply run deno task test:coverage.

Building

When testing and running in deno no build step is required, if however you wish to build a new version of the npm package you will have to run:

$ deno task generate:client

This generates the npm/ directory which contains all relevant builds (commonjs, browser and types) along with a package.json with the correct entrypoints for using either or both of the BananasCommerce and BananasCommercePrivate clients. It is done using the dnt (deno-to-node) build tool.

Generating fresh schemas

The automatically generated schema definitions are generated using the openapi-typescript tool. This is done automatically with:

# Build your docker image, this will be the version from which the client is generated from
$ task docker:builder
$ deno task generate:schemas

Formatting, linting and testing

All of these steps are made using the corresponding deno commands:

deno fmt
deno lint
deno task test

When running these commands along with the deno task generate:client command typechecking is automatically done to ensure the typescript types are correct.

Project structure

│ # AUTOMATICALLY GENERATED FILES #########################################################################
├── npm/                - An automatically generated node package! DO EDIT MANUALLY!
├── coverage/           - An automatically generated v8 coverage report used for generating the lcov report
├── coverage.lcov       - A lcov coverage report generated as an in-between format for generating cobertura
├── coverage.xml        - A cobertura coverage report generated from the lcov report
│ #########################################################################################################
├── scripts/            - A directory containing all development scripts
│   └── npm.ts          - This script uses dnt to automatically create the npm package
├── src/                - This directory contains all of the client and related utilities
│   ├── extensions/     - Each "extension" corresponds to a bcom "app", for example POS
│   ├── types/          - Automatically generated types from the OpenAPI json schemas
│   ├── util/           - Utilities
│   ├── api.ts          - A base class from which all extensions extend
│   ├── client.ts       - A factory (`generateClient`) which combines extensions and configuration into the client
│   ├── extension.ts    - Scaffolding types which are used by extensions
│   └── mod.ts          - The primary entrypoint
├── mock/               - Mocking utils for writing tests
└── test/               - Tests for the bananas-commerce client