# Web Integration

Current state

The web SDK version is currently very limited and is only able to display and download bills of an user. The only available module - for now - is @anybill/bill.

The anybill web SDK is based on async/await syntax (opens new window). Although it is technically possible to use Promise based syntax we recommend the async/await syntax in conjunction with try/catch.

# Getting Started

# Resolving the SDK

The anybill SDK for web is hosted in a private npm registry (anybill-npm) that has also access to the public npm registry. This means there is no need to install peer dependecies as they get resolved in the registry itself.
That said here is how to resolve the SDK with scoped access from the anybill-npm registry:

  1. Add a .npmrc file to the root directory of your project containing the following:
@anybill:registry=https://anybill.jfrog.io/artifactory/api/npm/anybill-npm/
//anybill.jfrog.io/artifactory/api/npm/anybill-npm/:_password=<BASE64_PASSWORD>
//anybill.jfrog.io/artifactory/api/npm/anybill-npm/:username=<USERNAME>
//anybill.jfrog.io/artifactory/api/npm/anybill-npm/:email=youremail@email.com
//anybill.jfrog.io/artifactory/api/npm/anybill-npm/:always-auth=true

SECRET

This file should not be checked into version control!

  1. Now you can install modules via:

npm:

npm install @anybill/<module_name>

yarn:

yarn add @anybill/<module_name>

# Usage

# Initialization

Initializing the SDK is easily done by calling the setup function:

import { AnybillSDKSetup } from "@anybill/bill";

// acquire access and refresh token ...

await AnybillSDKSetup.initialize(
    { accessToken, refreshToken },
    "my-client-id"
);

API environments

The SDK tries to figure out automatically which API to use based on the NODE_ENV environment variable, most commonly used by web frameworks.
If you are not using a framework or changed the default behavior use the override method instead!
Per default the STG environment gets used if no NODE_ENV is set.

If you want override what API gets used (for testing purposes etc.) initialize like this:

import { AnybillSDKSetup, ApiEnvironments } from "@anybill/bill";

/*
  ApiEnvironments available:
    PROD_API_URL = "https://app.anybill.de/api/",
    STG_API_URL  = "https://app.stg.anybill.de/api/",
    TEST_API_URL = "https://app.test.anybill.de/api/",
*/

// acquire access and refresh token ...

await AnybillSDKSetup.initialize(
    { accessToken, refreshToken },
    "my-client-id",
    ApiEnvironments.STG_API_URL
);

After intializing the SDK you can use it anywhere!

# Getting user bills

Querying for bills of an user is done via getBills provided by the BillProvider utility class:

import { BillProvider } from "@anybill/bill";

const bills = await BillProvider.instance.getBills();
const billsSince = await BillProvider.instance
    .getBills({ since: new Date().toISOString() });
const billsWithPagination = await BillProvider.instance
    .getBills({ skip: 5, take: 1000 }); // defaults are skip = 0 and take = 100

// or if you only need a specific bill
const singleBill = await BillProvider.instance
    .getBillByID("913cd9a6-9ff1-4fe3-8f8b-aa0add6a885c");

Bill object

The object returned by the getBills and getBillByID functions is BillDto (opens new window).

Validation

All inputs for the BillProvider functions get validated and throw an exception if validation fails. More about that in error handling

# Downloading user bills

The BillProvider utility has different methods of providing a PDF version of a bill.
Following three functions are available and should be used according to your project setup:

import { BillProvider } from "@anybill/bill";

// best for client side use
const objectURL = await BillProvider.instance
    .getBillPDFasObjectURL(billID);

// flexible usage 
const blob = await BillProvider.instance
    .getBillPDFasBlob(billID);

// best for server side use
const file = await BillProvider.instance
    .getBillPDFasFile(billID);

ObjectURL memory

ObjectURLs generated with getBillPDFasObjectURL are not automagically revoked!
To do so use URL.revokeObjectURL (opens new window) after using the URL.

File name

The File returned by getBillPDFasFile has a name with template:

`anybill-bill-export_${new Date().toLocaleDateString()}.pdf`

# Error handling

The anybill web SDK aims to provider the developer with easily understandable and catchable errors. The following two paragraphs introduce the used error model and how to work with it.

# Error objects

All error objects are based on the internal Error object (opens new window).
This means there are at least the following properties available:

  • message - Human readable error message
  • cause - the plain error thrown

The BillError object extends Error with an additional property:

# Understanding errors

Errors can be nested due to multiple internal catching and throwing. To get the deepest error dive in by repeatedly accessing cause until it returns undefined.