npm package: @fastekph/onepayfinformula-sdk
Description: An SDK for financial formulas and computations.
Latest version: 1.1.3

# ONEPAYFinFormula SDK

[![npm version](https://badgen.net/npm/v/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![node](https://badgen.net/npm/node/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![npm downloads](https://badgen.net/npm/dw/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![npm downloads](https://badgen.net/npm/dm/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![npm downloads](https://badgen.net/npm/dy/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![npm downloads](https://badgen.net/npm/dt/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![dependents](https://badgen.net/npm/dependents/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![types](https://badgen.net/npm/types/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)
[![license](https://badgen.net/npm/license/@fastekph/onepayfinformula-sdk/latest)](https://www.npmjs.com/package/@fastekph/onepayfinformula-sdk)

An SDK for financial formulas and computations.

---

**DISCLAIMER**: ONEPAYFinFormula SDK is a tool developed specifically for financial computations. While the SDK is intended for use in all countries, it is important to note that certain features may not be suitable for your specific jurisdiction as our formulas are primarily based on regulations in the Philippines. Therefore, it is recommended to review and validate the applicability of the SDK for your country's regulations before use.

The creators of this SDK make every effort to ensure its accuracy and reliability. However, they cannot guarantee the absence of errors or losses that may arise from its utilization. Therefore, the use of ONEPAYFinFormula SDK is at your own risk, and the creators disclaim any liability for any damages or losses incurred as a result of its use.

Please exercise caution and undertake proper due diligence when using the SDK to mitigate potential risks and ensure compliance with local regulations.

**Note**: This disclaimer is for informational purposes only and does not constitute legal advice. It is advisable to consult with legal professionals familiar with your specific jurisdiction for accurate guidance.

## Documentation

### Contents

- [Installation](#installation)
- [Sample Usage](#sample-usage)
  - [MathUtil](#mathutil)
  - [Taxation](#taxation)
  - [Receipt](#receipt)

### Installation

```
$ npm i @fastekph/onepayfinformula-sdk
```

### Sample Usage

#### MathUtil

```js
/**
 * computeVatAmount(amount, targetDecimalPlace)
 * @amount [number] amount of the transaction to round off
 * @targetDecimalPlace [number] desired/target decimal place to round off to 
 **/
MathUtil.roundoff(15.12345, 2)

/**
 * computePercentage(amount, percentage)
 * @amount [number] amount of the transaction to compute percentage from
 * @percentage [number] percentage to compute from the transaction amount 
 **/
MathUtil.computePercentage(100.00, 10.00)

/**
 * decimalToCentavo(amount)
 * @amount [number] amount of the transaction to convert from decimal to centavo format
 **/
MathUtil.decimalToCentavo(5.00)

/**
 * centavoToDecimal(amount)
 * @amount [number] amount of the transaction to convert from centavo to decimal format
 **/
MathUtil.centavoToDecimal(500)
```

#### Taxation

```js
import sdk from '@fastekph/onepayfinformula-sdk'

const taxation = sdk.ph.fastek.Taxation

/**
 * @VAT_RATE [number] default value-added tax rate percentage
 **/
taxation.VAT_RATE

/**
 * @WITHHOLDING_TAX_RATE [number] default withholding tax rate percentage
 **/
taxation.WITHHOLDING_TAX_RATE

/**
 * computeVatAmount(amount, vatInclusive)
 * @amount [number] amount of the transaction to compute vat
 * @vatInclusive [boolean] tagging if the amount is vat inclusive or not 
 **/
taxation.computeVatAmount(1458.00, true)
taxation.computeVatAmount(1292.79, false)

/**
 * computeVatAmountWithCustomRate(rate, amount, vatInclusive)
 * @rate [number] custom tax rate percentage to use
 * @amount [number] amount of the transaction to compute vat
 * @vatInclusive [boolean] tagging if the amount is vat inclusive or not 
 **/
taxation.computeVatAmountWithCustomRate(12.00, 1458.00, true)
taxation.computeVatAmountWithCustomRate(12.00, 1292.79, false)

/**
 * addVatAmount(amount)
 * @amount [number] amount of the transaction to add vat to
 **/
taxation.addVatAmount(1292.79)

/**
 * addVatAmountWithCustomRate(rate, amount)
 * @rate [number] custom tax rate percentage to use
 * @amount [number] amount of the transaction to add vat to
 **/
taxation.addVatAmountWithCustomRate(12.00, 1292.79)

/**
 * lessVatAmount(amount)
 * @amount [number] amount of the transaction to deduct vat to
 **/
taxation.lessVatAmount(1458.00)

/**
 * lessVatAmountWithCustomRate(rate, amount)
 * @rate [number] custom tax rate percentage to use
 * @amount [number] amount of the transaction to deduct vat to
 **/
taxation.lessVatAmountWithCustomRate(12.00, 1458.00)

/**
 * computeWithholdingTaxAmount(amount)
 * @amount [number] amount of the transaction to compute withholding tax
 **/
taxation.computeWithholdingTaxAmount(1.00)

/**
 * computeWithholdingTaxAmountWithCustomRate(amount)
 * @rate [number] custom tax rate percentage to use
 * @amount [number] amount of the transaction to compute withholding tax
 **/
taxation.computeWithholdingTaxAmountWithCustomRate(2.00, 1.00)
```

#### Receipt

```js
import sdk from '@fastekph/onepayfinformula-sdk'

/**
 * Notes:
 * 
 * - discountType allowable values are "promos", which are durational or event-based; 
 *   and "specialDiscounts", which are based on the person's classification such as 
 *   Persons-with-Disability (PWD), Senior Citizen, Solo Parent
 * 
 * - it is adviseble to use only one of the following, discountAmount or discountedPercentage, 
 *   pass 0 value on the field if it will not be used
 * 
 * - totalZeroRatedSalesAmount was defaulted to 0.00 for the meantime, computational formula
 *   will be added on the future updates
 *
 * - .addItem can be repeated to add multiple items 
 *
 * - receipt builder will output a Receipt object having the following fields
 *   {
 *      "summarizedItems": [
 *         { 
 *            "name": "",
 *            "amount": 0,
 *            "quantity": 0,
 *            "grossSalesAmount": 0,
 *            "isVatExempt": false,
 *            "regularDiscountAmount": 0,
 *            "specialDiscountAmount": 0,
 *            "vatableSalesAmount": 0,
 *            "vatAmount": 0,
 *            "vatExemptSalesAmount": 0,
 *            "zeroRatedSalesAmount": 0,
 *            "netSalesAmount": 0,
 *      ]
 *      "totalGrossSalesAmount": 0.00,
 *      "totalRegularDiscountAmount": 0.00,
 *      "totalSpecialDiscountAmount": 0.00,
 *      "totalVatableSalesAmount": 0.00,
 *      "totalVatAmount": 0.00,
 *      "totalZeroRatedSalesAmount": 0.00,
 *      "totalVatExemptSalesAmount": 0.00,
 *      "totalNetSalesAmount": 0.00
 *   }
 **/
const receipt = new sdk.ph.fastek.Receipt.Builder()
    .addItem({
        name: "HERSHEYS",
        amount: "10",
        discountType: "promos",
        discountCode: "PROMO",
        isVatExempt: "true",
        discountAmount: "5",
        discountedPercentage: "0",
        quantity: "1"
    })
    .build()

const summarizedItems = receipt.summarizedItems

summarizedItems.forEach(item => {
    console.log("name: " + item.name)
    console.log("amount: " + item.amount)
    console.log("quantity: " + item.quantity)
    console.log("grossSalesAmount: " + item.grossSalesAmount)
    console.log("isVatExempt: " + item.isVatExempt)
    console.log("regularDiscountAmount: " + item.regularDiscountAmount)
    console.log("specialDiscountAmount: " + item.specialDiscountAmount)
    console.log("vatableSalesAmount: " + item.vatableSalesAmount)
    console.log("vatAmount: " + item.vatAmount)
    console.log("vatExemptSalesAmount: " + item.vatExemptSalesAmount)
    console.log("zeroRatedSalesAmount: " + item.zeroRatedSalesAmount)
    console.log("netSalesAmount: " + item.netSalesAmount)
})

console.log("totalGrossSalesAmount: " + receipt.totalGrossSalesAmount)
console.log("totalRegularDiscountAmount: " + receipt.totalRegularDiscountAmount)
console.log("totalSpecialDiscountAmount: " + receipt.totalSpecialDiscountAmount)
console.log("totalVatableSalesAmount: " + receipt.totalVatableSalesAmount)
console.log("totalVatAmount: " + receipt.totalVatAmount)
console.log("totalVatExemptSalesAmount: " + receipt.totalVatExemptSalesAmount)
console.log("totalZeroRatedSalesAmount: " + receipt.totalZeroRatedSalesAmount)
console.log("totalNetSalesAmount: " + receipt.totalNetSalesAmount)
```