bananas-commerce/README.md

A client for bananas-commerce with support for TypeScript

# `bananas-commerce`

The JavaScript client for `bananas-commerce`.

```ts
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](https://deno.land/) 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:

```sh
$ 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)](https://github.com/denoland/dnt) build tool.

## Generating fresh schemas

The automatically generated schema definitions are generated using the
[openapi-typescript](https://github.com/drwpow/openapi-typescript) tool. This is
done automatically with:

```sh
# 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:

```sh
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
```

## Misc, links and stuff to remember

- [openapi-typescript](https://github.com/drwpow/openapi-typescript)
- [openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch)