@first-iraqi-bank/sdk 0.1.2 → 0.1.4

package/README.md

@@ -6,296 +6,4 @@ First Iraqi Bank allows you to create online payments in your application using
 
 This package helps you integrate the payment API easily on your JavaScript/TypeScript backend server with simple and typed set of functions.
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Technical notices](#technical-notices)
-- [Methods](#usage)
-  - [authenticate](#authenticate)
-  - [createPayment](#createpayment)
-  - [getPaymentStatus](#getpaymentstatus)
-  - [cancelPayment](#cancelpayment)
-  - [refundPayment](#refundpayment)
-- [Types & Responses](#types)
-- [Error Handling](#error-handling)
-- [Contributing](#contributing)
-
-## Installation
-
-### npm
-
-```sh
-npm i @first-iraqi-bank/sdk
-```
-
-### yarn
-
-```sh
-yarn add @first-iraqi-bank/sdk
-```
-
-### pnpm
-
-```sh
-pnpm add @first-iraqi-bank/sdk
-```
-
-### deno
-
-```sh
-deno add npm:@first-iraqi-bank/sdk
-```
-
-### bun
-
-```sh
-bun add @first-iraqi-bank/sdk
-```
-
-## Technical notices
-
-You need to register for the sandbox environment to get your `client_id` and `client_secret`. Once you are ready to move to production, contact <integration@fib.iq> to obtain your production credentials.
-
-1. This package guarantees support for Maintenance and LTS versions of Node.js, starting from v18 of Node.js. if you encountered any issues in this regard, please [let us know](https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk/issues/new).
-
-2. This package guarantees support for ESM and CJS module formats, we prefer and recommend of using ESM everywhere if it works for you.
-
-3. This package is built on top of the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) and all functions return a `Response` giving you maximum flexibility to parse or ignore the responses you get. Check out [Node.js docs - Fetch](https://nodejs.org/docs/latest/api/globals.html#fetch) section which is available since **v18.0.0**
-
-## Usage
-
-You can import the SDK classes and types from the `payment` entrypoint:
-
-```ts
-import { PaymentSDK } from "@first-iraqi-bank/sdk/payment"
-```
-
-The `PaymentSDK` class has a static method that gives you an instance of the SDK configured with your API credentials:
-
-```ts
-// fib.js
-
-import { PaymentSDK } from "@first-iraqi-bank/sdk/payment"
-
-const clientId = process.env.FIB_CLIENT_ID
-const clientSecret = process.env.FIB_CLIENT_SECRET
-const environment = process.env.FIB_ENV // 'dev', 'stage', or 'prod'
-
-export const FIB = PaymentSDK.getClient(clientId, clientSecret, environment)
-```
-
-Now you can import `FIB` from anywhere in your project and call its methods to create payments, check payment status or canceling them.
-
-> [!TIP]
-> Checkout [FIB Web Payment](https://fib.iq/en/developers/web-payment) documentations for more info and how to obtain your credentials
-
-- `authenticate(signal?: AbortSignal)`: Authenticates the client and returns an access token.
-- `createPayment(paymentInput: PaymentInput, accessToken: string, signal?: AbortSignal)`: Creates a payment.
-- `getPaymentStatus(paymentId: string, accessToken: string, signal?: AbortSignal)`: Gets the status of a payment.
-- `cancelPayment(paymentId: string, accessToken: string, signal?: AbortSignal)`: Cancels a payment.
-- `refundPayment(paymentId: string, accessToken: string, signal?: AbortSignal)`: Refunds a payment.
-
-### authenticate
-
-This method sends a request to the First Iraqi Bank's identity server, giving you necessary token and other related information to authenticate your next requests like creating or canceling a payment.
-
-```ts
-import { FIB } from "./fib.js"
-
-const res = await FIB.authenticate()
-const { access_token, expires_in } = await res.json()
-```
-
-`access_token` is the most important part of the response, since you need to pass it to the next request otherwise it'll fail with **Authentication** error!
-
-> [!IMPORTANT]
-> Access tokens are designed to be short-lived, `expires_in` will tell you how many seconds you have until the access token expires, make sure to fetch a new access token before your next API call by calling `authenticate` as described above.
-
----
-
-### createPayment
-
-This method sends a request to the First Iraqi Bank's server, creating a payment based on the provided information, which are parameters to function:
-
-1. `payment`: an object with below possible properties:
-
-   - `amount`: a number, indicating the payment's amount in IQD. Must be bigger than `250`.
-   - `description` _(optional)_: a string used as description and might be shown to the customer when they try to pay in the FIB app.
-   - `expiresIn` _(optional)_: a Duration object indicating when the transaction expires, it must be:
-
-     1. Bigger than 5 Minutes
-     2. Smaller than 48 Hours
-
-   - `refundableFor` _(optional)_: a Duration object indicating till when the transaction can be refunded after it was paid, it must be:
-
-     1. Bigger than 12 Hours
-     2. Smaller than 7 Days
-
-   - `redirectUri` _(optional)_: an instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL_API) class, you can provide
-   a URL of your app where the user should be redirected when the payment was authorized, for example if you want FIB app to redirect user
-   back to some screen inside your app/website, this is used when you use **Pay with FIB** button in your.
-   - `statusCallbackUrl` _(optional)_: an instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL_API) class, this must be the URL of your backend and specifically of an endpoint that can accept `POST` request, as FIB backend will call this endpoint when the status of the transaction changes. Omit it if you're not interested.
-
-2. `accessToken`: a previously fetched access token from [`authenticate`](#authenticate) method.
-3. `signal` _(optional)_: an AbortSignal that can use to abort the fetch request. Checkout [Canceling a request](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#canceling_a_request) on MDN for detailed explanation.
-
-Example:
-
-```ts
-import { FIB } from "./fib.js"
-
-const paymentInput = {
-  amount: 1000, // amount in IQD
-  description: "Payment for Order #12345",
-  redirectUri: new URL("https://example.com/payments"),
-  statusCallbackUrl: new URL("https://example.com/api/callbacks/payment/status"),
-  refundableFor: { days: 1 },
-  expiresIn: { hours: 1 },
-}
-
-const authRes = await FIB.authenticate()
-const { access_token } = await authRes.json()
-
-const res = await FIB.createPayment(paymentInput, access_token)
-```
-
-This method returns a JSON response, that is the details of transaction that you just created, represented by `Payment` type:
-
-- `paymentId`: a string indicating the id of the payment
-- `readableCode`: a 12-character alpha-numeric string used to generate the `qrCode` property.
-- `qrCode`: a URL-encoded PNG image that can be shown to the user to scan and pay the amount.
-- `validUntil`: a string indicating until when this payment is valid.
-- `personalAppLink`: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.
-- `businessAppLink`: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.
-- `corporateAppLink`: a string representing the personal deep link that users can visit which automatically opens the payment details in the FIB app.
-
-> [!TIP]
-> Users can pay the amount either by scanning the QRCode, manually typing the `readableCode` or visiting the deep-links like `personalAppLink`, we recommend showing all 3 options to the user to make it more convenient for your users to fulfill the payment
-
-Users might refresh your page, or close your application and come back, make sure you save the transaction details in your database as it contains information that can helpful to you or your customers later.
-
----
-
-### getPaymentStatus
-
-When you generated a payment, you can use this method to retrieve information about the status of the payment, this provides details on when the payment is paid, or if its canceled then why and some other useful information:
-
-```ts
-import { FIB } from "./fib.js"
-
-const authRes = await FIB.authenticate()
-const { access_token } = await authRes.json()
-
-const res = await FIB.getPaymentStatus(paymentId, accessToken)
-```
-
----
-
-### cancelPayment
-
-When a payment is created, you might want to cancel the payment for any reason, this can be done before he payment is fulfilled:
-
-```ts
-import { FIB } from "./fib.js"
-
-const authRes = await FIB.authenticate()
-const { access_token } = await authRes.json()
-
-const res = await FIB.cancelPayment(paymentId, accessToken)
-```
-
----
-
-### refundPayment
-
-After a payment is fulfilled, it can be refunded depending on the `refundableFor` option you created the payment with:
-
-```ts
-import { FIB } from "./fib.js"
-
-const authRes = await FIB.authenticate()
-const { access_token } = await authRes.json()
-
-const res = await FIB.refundPayment(paymentId, accessToken)
-```
-
----
-
-### Types
-
-#### PaymentInput
-
-```typescript
-type PaymentInput = {
-  amount: number
-  description?: string
-  redirectUri?: URL
-  statusCallbackUrl?: URL
-  expiresIn?: Duration
-  refundableFor?: Duration
-}
-```
-
-#### PaymentResponse
-
-```typescript
-type PaymentResponse = {
-  paymentId: string
-  readableCode: string
-  qrCode: string
-  validUntil: string
-  personalAppLink: string
-  businessAppLink: string
-  corporateAppLink: string
-}
-```
-
-#### PaymentStatusResponse
-
-```typescript
-type PaymentStatusResponse = {
-  paymentId: string
-  amount: MonetaryValue
-  status: "UNPAID" | "DECLINED" | "PAID" | "REFUNDED" | "REFUND_REQUESTED"
-  paidAt?: string
-  decliningReason?: "PAYMENT_CANCELLATION" | "PAYMENT_EXPIRATION"
-  declinedAt?: string
-  paidBy?: { name: string; iban: string }
-}
-```
-
-## Error Handling
-
-There are two types of errors you might want to watch out for:
-
-1. When the requests return a `Response`, but its not in `2xx` range, in this case
-   FIB backend returns an error message and some traceId, that we can inspect the
-   request for you if the error is not expected.
-
-    ```javascript
-    const res = await FIB.getPaymentStatus(paymentInput, accessToken)
-    if(res.status !== 200){
-      const { errors } = await res.json()
-    }
-    ```
-
-2. When the request fails with an `Error`, which might happen for several reasons, for example
-   a `NetworkError` or other runtime exceptions.
-
-    ```javascript
-    try{
-      const res = await FIB.getPaymentStatus(paymentInput, accessToken)
-      const { status } = await res.json()
-
-      return status
-    }catch(error){
-      console.log("Something went wrong", error)
-      return null
-    }
-    ```
-
-## Contributing
-
-If you encounter any bugs or issues while using the SDK, we encourage you to report them by [filing an issue](https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk/issues/new) on our GitHub repository. Your feedback helps us improve the SDK.
-
-Additionally, if during the discussion of an issue you feel that you can contribute a code change to resolve the problem, we warmly welcome your contributions. To do so, please submit a [pull request](https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk/compare) with your proposed changes.
+Please read our [Documentation](https://first-iraqi-bank.github.io/fib-nodejs-payment-sdk/) for a smooth integration.

package/dist/payment.cjs

@@ -25,15 +25,24 @@ __export(payment_exports, {
 module.exports = __toCommonJS(payment_exports);
 
 // src/shared/net.ts
+var MAP_ENVIRONMENT_TO_BASE_URL = {
+  dev: "https://fib-dev.fib.iq",
+  stage: "https://fib-stage.fib.iq",
+  prod: "https://fib.prod.fib.iq"
+};
 var BaseHTTP = class {
   #baseUrl;
   #clientId;
   #clientSecret;
   #grantType = "client_credentials";
   constructor(clientId, clientSecret, env) {
+    const rawBaseURL = MAP_ENVIRONMENT_TO_BASE_URL[env];
+    if (!rawBaseURL) {
+      throw new Error(`Invalid environment: ${env}`);
+    }
     this.#clientId = clientId;
     this.#clientSecret = clientSecret;
-    this.#baseUrl = new URL(`https://fib.${env}.fib.iq`);
+    this.#baseUrl = new URL(rawBaseURL);
   }
   getBaseUrl() {
     return this.#baseUrl;
@@ -65,16 +74,21 @@ var BaseHTTP = class {
 
 // src/shared/utils.ts
 function formatISODuration(duration) {
-  const {
-    years = 0,
-    months = 0,
-    days = 0,
-    hours = 0,
-    minutes = 0,
-    seconds = 0
-  } = duration;
-  return `P${years}Y${months}M${days}DT${hours}H${minutes}M${seconds}S`;
+  const parts = ["P"];
+  if (duration.years) parts.push(`${duration.years}Y`);
+  if (duration.months) parts.push(`${duration.months}M`);
+  if (duration.weeks) parts.push(`${duration.weeks}W`);
+  if (duration.days) parts.push(`${duration.days}D`);
+  const hasTimeComponents = duration.hours || duration.minutes || duration.seconds;
+  if (hasTimeComponents) {
+    parts.push("T");
+    if (duration.hours) parts.push(`${duration.hours}H`);
+    if (duration.minutes) parts.push(`${duration.minutes}M`);
+    if (duration.seconds) parts.push(`${duration.seconds}S`);
+  }
+  return parts.length === 1 ? "P0D" : parts.join("");
 }
+console.log(formatISODuration({ days: 1 }));
 
 // src/payment/net.ts
 var HTTP = class extends BaseHTTP {

package/dist/payment.js

@@ -1,13 +1,22 @@
 // src/shared/net.ts
+var MAP_ENVIRONMENT_TO_BASE_URL = {
+  dev: "https://fib-dev.fib.iq",
+  stage: "https://fib-stage.fib.iq",
+  prod: "https://fib.prod.fib.iq"
+};
 var BaseHTTP = class {
   #baseUrl;
   #clientId;
   #clientSecret;
   #grantType = "client_credentials";
   constructor(clientId, clientSecret, env) {
+    const rawBaseURL = MAP_ENVIRONMENT_TO_BASE_URL[env];
+    if (!rawBaseURL) {
+      throw new Error(`Invalid environment: ${env}`);
+    }
     this.#clientId = clientId;
     this.#clientSecret = clientSecret;
-    this.#baseUrl = new URL(`https://fib.${env}.fib.iq`);
+    this.#baseUrl = new URL(rawBaseURL);
   }
   getBaseUrl() {
     return this.#baseUrl;
@@ -39,16 +48,21 @@ var BaseHTTP = class {
 
 // src/shared/utils.ts
 function formatISODuration(duration) {
-  const {
-    years = 0,
-    months = 0,
-    days = 0,
-    hours = 0,
-    minutes = 0,
-    seconds = 0
-  } = duration;
-  return `P${years}Y${months}M${days}DT${hours}H${minutes}M${seconds}S`;
+  const parts = ["P"];
+  if (duration.years) parts.push(`${duration.years}Y`);
+  if (duration.months) parts.push(`${duration.months}M`);
+  if (duration.weeks) parts.push(`${duration.weeks}W`);
+  if (duration.days) parts.push(`${duration.days}D`);
+  const hasTimeComponents = duration.hours || duration.minutes || duration.seconds;
+  if (hasTimeComponents) {
+    parts.push("T");
+    if (duration.hours) parts.push(`${duration.hours}H`);
+    if (duration.minutes) parts.push(`${duration.minutes}M`);
+    if (duration.seconds) parts.push(`${duration.seconds}S`);
+  }
+  return parts.length === 1 ? "P0D" : parts.join("");
 }
+console.log(formatISODuration({ days: 1 }));
 
 // src/payment/net.ts
 var HTTP = class extends BaseHTTP {

package/dist/payout.cjs

@@ -25,15 +25,24 @@ __export(payout_exports, {
 module.exports = __toCommonJS(payout_exports);
 
 // src/shared/net.ts
+var MAP_ENVIRONMENT_TO_BASE_URL = {
+  dev: "https://fib-dev.fib.iq",
+  stage: "https://fib-stage.fib.iq",
+  prod: "https://fib.prod.fib.iq"
+};
 var BaseHTTP = class {
   #baseUrl;
   #clientId;
   #clientSecret;
   #grantType = "client_credentials";
   constructor(clientId, clientSecret, env) {
+    const rawBaseURL = MAP_ENVIRONMENT_TO_BASE_URL[env];
+    if (!rawBaseURL) {
+      throw new Error(`Invalid environment: ${env}`);
+    }
     this.#clientId = clientId;
     this.#clientSecret = clientSecret;
-    this.#baseUrl = new URL(`https://fib.${env}.fib.iq`);
+    this.#baseUrl = new URL(rawBaseURL);
   }
   getBaseUrl() {
     return this.#baseUrl;

package/dist/payout.js

@@ -1,13 +1,22 @@
 // src/shared/net.ts
+var MAP_ENVIRONMENT_TO_BASE_URL = {
+  dev: "https://fib-dev.fib.iq",
+  stage: "https://fib-stage.fib.iq",
+  prod: "https://fib.prod.fib.iq"
+};
 var BaseHTTP = class {
   #baseUrl;
   #clientId;
   #clientSecret;
   #grantType = "client_credentials";
   constructor(clientId, clientSecret, env) {
+    const rawBaseURL = MAP_ENVIRONMENT_TO_BASE_URL[env];
+    if (!rawBaseURL) {
+      throw new Error(`Invalid environment: ${env}`);
+    }
     this.#clientId = clientId;
     this.#clientSecret = clientSecret;
-    this.#baseUrl = new URL(`https://fib.${env}.fib.iq`);
+    this.#baseUrl = new URL(rawBaseURL);
   }
   getBaseUrl() {
     return this.#baseUrl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@first-iraqi-bank/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Accept payment and send payout from and to First Iraqi Bank customers with ease!",
   "type": "module",
   "files": [
@@ -44,7 +44,7 @@
     "url": "git+https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk.git"
   },
   "bugs": "https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk/issues",
-  "homepage": "https://github.com/First-Iraqi-Bank/fib-nodejs-payment-sdk#readme",
+  "homepage": "https://first-iraqi-bank.github.io/fib-nodejs-payment-sdk/",
   "keywords": [
     "api",
     "sdk",