# @wpay/sdk

> Library that can facilitate JS applications accessing the WPay API.

Latest version **1.9.1** (published 2022-05-02) · UNLICENSED license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @wpay/sdk
pnpm add @wpay/sdk
yarn add @wpay/sdk
bun add @wpay/sdk
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.9.1 |
| Published | 2022-05-02 |
| First published | 2021-06-15 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ~12.18 |
| Dependencies | 3 |
| Unpacked size | 5.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | kierans777, jamesbligh, ben-rc, frva |

## Links

- npm: https://www.npmjs.com/package/@wpay/sdk
- Repository: https://github.com/w-pay/sdk-wpay-js
- Homepage: hhttps://github.com/w-pay/sdk-wpay-js/#readme
- Issues: https://github.com/w-pay/sdk-wpay-js/issues
- npm.io page: https://npm.io/package/@wpay/sdk

## Dependencies (3)

- [crocks](https://npm.io/package/crocks.md) ^0.12.4
- [@api-sdk-creator/http-api-client](https://npm.io/package/@api-sdk-creator/http-api-client.md) ^0.2.0
- [@epistemology-factory/crocks-ext](https://npm.io/package/@epistemology-factory/crocks-ext.md) 0.0.17

## Recent versions

- 1.9.1 (latest) — 2022-05-02
- 1.9.0 — 2022-04-04
- 1.8.8 — 2022-02-18
- 1.8.7 — 2021-10-19
- 1.8.6 — 2021-09-30
- 1.8.5 — 2021-09-30
- 1.8.4 — 2021-09-29
- 1.8.3 — 2021-09-28
- 1.8.2 — 2021-09-28
- 1.8.1 — 2021-09-28
- 1.8.0 — 2021-09-28
- 1.7.0 — 2021-09-28
- 1.6.1 — 2021-09-28
- 1.6.0 — 2021-09-28
- 1.5.1 — 2021-09-28
- … 1 more at https://npm.io/package/@wpay/sdk/versions

## README

# WPay Javascript SDK

This project contains a `npm` module that can facilitate applications accessing the WPay API.

| :memo: | The SDK is currently in development. Therefore parts may change. |
|--------|:-----------------------------------------------------------------|


The SDK is written in Javascript with Typescript definitions being published which means that 
type definitions will be available for client developers. Client applications can be written in 
Typescript or plain Javascript.

## Usage

The SDK is has the following core design philosophies.

1. Technology agnostic. Different browser applications may have different technology
choices and an SDK shouldn't force an application to depend on a different
technology stack as this bloats the build and increases complexity.

2. Swappable. Don't like a particular implementation of a part in the
SDK, then swap it out for another object that "implements" the correct
interface.

The SDK is comprised of:
 - An API layer which knows how to communicate with the WPay API
 - An authentication abstraction layer.

Applications have the flexibility to plug in different implementations of
the interfaces to allow particular technology choices (eg: choice of
HTTP client library). This makes it very easy to use the SDK in an
existing project, without necessarily introducing extra dependencies.

### Authentication layer

In order to access protected APIs, the SDK will need to know how to
authenticate with the API or a gateway that protects the API. The
`ApiAuthenticator` interface abstracts how the SDK authenticates from
the rest of the API interface. Applications that have a preexisting
authentication workflow can either update the relevant classes to implement the
`ApiAuthenticator` interface, or provide an [Adapter](https://en.wikipedia.org/wiki/Adapter_pattern#Java)
to make the existing authentication details available to the SDK.

### HTTP layer

As the WPay SDK uses the [api-sdk-creator](https://github.com/RedCrewOS/api-sdk-creator-js)
project, the HTTP stack is swappable when the SDK is created.

#### Reference Application

A [Reference Application]() is available to demonstrate the use of the SDK.

TODO: Reference app

## Versioning

The SDK follows [Semantic Versioning](https://semver.org/) principles.
As such if the API specification changes in a way that introduces breaking
changes (eg: path change or data changes) the major version of the SDK
will be increased.

The SDK currently supports version 1.0.5 of the API spec.

## Getting started

Read the [📘 SDK reference docs](/docs/index.html) for more information on the different types
in the SDK.

### Example usage

These examples use the `@api-sdk-creator/axios-http-client` `HttpClient`

#### Installation

If using the SDK in a project with a bundler (eg: Webpack) the SDK can be installed via NPM and imported like any other module. However because the module is currently private users will need access to the NPM repository.

```shell script
$ npm install @wpay/sdk
$ npm install @api-sdk-creator/axios-http-client
```

If using the SDK via a `<script>` tag, the `WPay` global will be made available

```html
<!-- Found in the @api-sdk-creator/axios-http-client repo -->
<script type="javascript" src="axios-http-client.js" />

<!-- For customer only -->
<script type="javascript" src="wpay-wallet-sdk.customer.js" />

<!-- For merchant only -->
<script type="javascript" src="wpay-wallet-sdk.merchant.js" />

<!-- For everything -->
<script type="javascript" src="wpay-wallet-sdk.all.js" />

<script>
const sdk = WPay.createCustomerSDK(AxiosHttpClient.createAxiosHttpClient, options);
</script>
``` 

```javascript
// mandatory options
const options = {
  apiKey: "<your key here>",
  baseUrl: "https://api.wpay.com/api"
}
```

#### Accessing an unauthenticated API

```javascript
const { createAxiosHttpClient } = require("@api-sdk-creator/axios-http-client");
const { createCustomerSDK } = require("@wpay/sdk");

const sdk = createCustomerSDK(createAxiosHttpClient, options);

await sdk.admin.checkHealth();
```

#### Using a preprovided access token

If an access token is acquired outside the SDK, it can be given to the SDK and used for as long
as the token is valid.

```javascript
const { createCustomerSDK } = require("@wpay/sdk");

options.accessToken = aquireAccessToken();

const sdk = createCustomerSDK(createAxiosHttpClient, options);

await sdk.preferences.get();
```

#### Using an ApiAuthenticator

If a client application wants to wrap an existing application authentication strategy then a
custom `ApiAuthenticator` can be given to the SDK. However it becomes the
responsibility of the client application to manage that token.

(This example is written in Typescript so that type information can be used).

```typescript
const { createCustomerSDK } = require("@wpay/sdk");

const authenticator: ApiAuthenticator = createAuthenticator();
options.accessToken = authenticator;

const sdk = createCustomerSDK(createAxiosHttpClient, options);

await sdk.preferences.get();
```

### Building

To build the SDK from source

```shell
$ npm run dist
```

### Documentation

The SDK reference docs are generated using [JSDoc](https://jsdoc.app/)

```shell
$ npm run doc
```

## Publishing

Currently, publishing requires write access to the `@wpay` NPM organisation.

---
_Source: https://npm.io/package/@wpay/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._