@sonatel-os/juf/README.md

It's an helpful Javascript Utility Framework to ease application development in SONATEL context.

# Javascript Utility Framework (JUF)

**juf.js** is a comprehensive library for managing authentication, communication, and payments using the Apigee platform. It simplifies the process of handling QR code generation, payment initialization, and communication through SMS and email.

## **Table of Contents**

- [Installation](#installation)
- [Getting Started](#getting-started)
- [Authentication Service](#authentication-service)
- [Communication Service](#communication-service)
- [Payment Service](#payment-service)
- [Examples](#examples)
- [Notes and Caveats](#notes-and-caveats)

## **Installation**

To install **@sonatel/juf**, use:

```bash
yarn add @sonatel/juf
```

Set up your environment variables

```bash
JUF_APIGEE_ON_PROD=false # default false (on sandbox)
JUF_APIGEE_CLIENT_ID="<JUF_APIGEE_CLIENT_ID>"
JUF_APIGEE_CLIENT_SECRET="<JUF_APIGEE_CLIENT_SECRET>"
```

- JUF_APIGEE_ON_PROD: Set to "true" to use the production environment.
- JUF_APIGEE_CLIENT_ID and JUF_APIGEE_CLIENT_SECRET: Credentials required for Apigee authentication.

## **Getting Started**

After installation, you can start using the **@sonatel/juf** module by importing its services.

```javascript
import { authentication, communication, payment } from '@sonatel/juf';

// Example: Authenticate and generate a payment QR code
const { access_token } = await authentication.debug();

console.log(access_token)

const qrCode = await payment.createPaymentQRCode({
  merchant: { code: 123, sitename: 'MySite' },
  bill: { amount: 500, reference: 'INV001' },
});
```

## **Authentication Service**

The Authentication handles the authentication and token management process via Apigee.

```javascript
import { authentication } from '@sonatel/juf'
```

### **debug()**

Authenticates the application and retrieves a token from Apigee.

#### **Usage**

```javascript
const { access_token } = await authentication.debug();
```

#### Returns

- access_token (string)
- expires_in (number)
- refresh_expires_in (number)
- token_type (string)
- notbefore_policy (number)
- session_state (string)

## **Communication Service**

The CommunicationService provides methods for sending SMS and emails using Apigee.

```javascript
import { communication } from '@sonatel/juf'
```

### sendEmail

Sends an email to a recipient.

```javascript
const { data: { id, status: mailStatus }, status } = await communication.sendEmail({
  subject: 'Hello!',
  to: 'recipient@example.com',
  from: 'sender@example.com',
  body: '<p>This is a test email.</p>',
  html: true
});
```

#### Parameters:

- subject (string) Email subject.
- to (string) Recipient’s email address.
- body (string) Content of the email.
- html (boolean) specify if the content of the email is of HTML format.

#### Returns: 

- id (string)
- status (string)

### sendSMS

Sends an SMS message to a recipient.

#### Usage

```javascript
const { id, status } = await communication.sendSMS({
  body: 'This is a test SMS.',
  to: '+1234567890'
});
```

#### Parameters

- to (string) Recipient’s phone number.
- body (string) Content of the message.
- senderName (string) Recipient’s phone number.
- scheduledFor (string) [optional] SMS content.
- confidential (boolean) [optionnal]

#### Return

- id (string)
- status (string)

## **Payment Service**

The PaymentService helps to manage payments by generating QR codes, decoding them, and preparing checkout for transactions.

```javascript
import { payment } from '@sonatel/juf'
```

### **createPaymentQRCode**

Generates a QR code for payments.

#### Usage

```javascript
const { qrId, qrCode, deepLinks } = await payment.createPaymentQRCode({
  merchant: {
    code: 123456,
    sitename: 'your-sitename'
  },
  bill: {
    amount: 10,
    reference: 654321
  },
  urls: {
    failed: 'https://my.site/failed',
    cancel: 'https://my.site/canceled',
    success: 'https://my.site/success'
  },
  metadata: {
    myKey: 'value'
  },
  validity: 300
})
```

#### Parameters:

- merchant (object): Merchant information.
  - code (number): The merchant code.
  - sitename (string): The merchant's site name.
- bill (object): Bill information.
  - amount (number): The amount to be paid.
  - reference (number): The reference for the transaction.
- urls (object) [optionnal]: URLs for payment status.
  - failed (string) [optionnal]: URL to redirect if payment fails.
  - cancel (string) [optionnal]: URL to redirect if payment is canceled.
  - success (string) [optionnal]: URL to redirect upon successful payment.
  - callback (string) [optionnal]: Callback URL for payment updates.
- metadata (object) [optionnal]: Additional metadata for the QR code.
- validity (number) [optionnal]: Validity period for the QR code in seconds (defaulted to one day).

#### Returns

- deepLink (string)
- deepLinks (object)
  - MAXIT (string)
  - OM (string)
- qrCode (string)
- validity (number)
- metadata (object)
- shortLink (string)
- qrId (string)

### **decodeQrCode**

Decodes a QR code using its ID.

#### Usage

```javascript
const { content: { amount } } = await payment.decodeQrCode({
  id:  'your-qr-id'
})
```

#### Parameters:

- id (string): The QR code ID.

#### Returns 

- id (string)
- content (object)
  - merchantCode (string)
  - merchantName (string)
  - amount (number)
  - reference (string)
  - scope (string)
  - type (string)
  - metadata (object)

### **preparePaymentCheckout**

Prepares a payment session for checkout and gives alink to the payment plaform.

#### Usage

```javascript
const { link, secret } = await payment.preparePaymentCheckout({
  merchant: {
    code: 123456,
    sitename: 'your-sitename'
  },
  bill: {
    amount: 10,
    reference: 654321
  },
  urls: {
    failed: 'https://my.site/failed',
    cancel: 'https://my.site/canceled',
    success: 'https://my.site/success',
    callback: 'https://my.site/callback',
  }
})
```

#### Parameters:

- merchant (object): Merchant information.
  - code (number): The merchant code.
  - sitename (string): The merchant's site name.
- bill (object): Bill information.
  - amount (number): The amount to be paid.
  - reference (number): The reference for the transaction.
- urls (object) [optionnal]: URLs for payment status.
  - failed (string) [optionnal]: URL to redirect if payment fails.
  - cancel (string) [optionnal]: URL to redirect if payment is canceled.
  - success (string) [optionnal]: URL to redirect upon successful payment.
  - callback (string) [optionnal]: Callback URL for payment updates.

#### Returns

- link (string)
- secret (number)

## Notes and Caveats

- The debug method caches the authentication token to minimize repeated network calls.
- Ensure your environment variables are correctly set up for the library to function properly.
- Be cautious of the confidential information passed through methods; it is essential to handle sensitive data securely.

## **License**

MIT License. See the [LICENSE](./LICENSE) file for more information.

---

Feel free to expand on the README to reach out if any question occurs but first please >> RTM