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
• Getting Started
• Authentication Service
• Communication Service
• Payment Service
• Examples
• Notes and Caveats

Installation

To install @sonatel/juf, use:

yarn add @sonatel/juf

Set up your environment variables

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.

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.

import { authentication } from '@sonatel/juf'

debug()

Authenticates the application and retrieves a token from Apigee.

Usage

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.

import { communication } from '@sonatel/juf'

sendEmail

Sends an email to a recipient.

const { data: { id, status: mailStatus }, status } = await communication.sendEmail({
  subject: 'Hello!',
  to: '[email protected]',
  from: '[email protected]',
  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

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.

import { payment } from '@sonatel/juf'

createPaymentQRCode

Generates a QR code for payments.

Usage

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

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

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 file for more information.

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