FibSubscribe

Official Node.js SDK for the First Iraqi Bank (FIB) Subscription Service

---

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• API Reference
  • Create Subscription
  • Get Subscription
  • Cancel Subscription
  • Wait for Activation
• Subscription Statuses
• ISO-8601 Period Cheatsheet
• Error Handling
• Webhook Integration
• Examples
• Publishing

---

Features

• ✅ Full coverage of the FIB Subscription API (create, get, cancel)
• 🔐 Automatic OAuth2 token management with expiry refresh
• ⏳ Built-in polling helper (waitForActivation)
• 🌍 Stage & Production environment support
• 📦 Zero runtime dependencies
• 🔷 ESM-native ("type": "module")
• 📝 Full JSDoc type annotations

---

Installation

npm install fibsubscribe

Requires Node.js v14 or higher. This package is ESM-only — use import, not require().

---

Quick Start

import { FibSubscribe } from 'fibsubscribe';

const fib = new FibSubscribe({
  clientId: process.env.FIB_CLIENT_ID,
  clientSecret: process.env.FIB_CLIENT_SECRET,
  environment: 'stage', // or 'production'
});

// 1. Create a monthly subscription with a 7-day trial
const sub = await fib.createSubscription({
  title: 'Premium Membership',
  description: 'Full access to all premium features.',
  amount: 5000,
  currency: 'IQD',
  interval: 'P1M',        // every 1 month
  trialPeriod: 'P7D',     // 7-day free trial
  expiresIn: 'P1DT12H',   // QR valid for 1 day 12 hours
  statusCallbackUrl: 'https://yoursite.com/fib/subscription/webhook',
});

// 2. Show QR code or app link to the subscriber
console.log('App Link:', sub.appLink);
// Render: <img src={sub.qrCode} />

// 3. Wait until subscriber confirms (or rejects)
const result = await fib.waitForActivation(sub.subscriptionId);
console.log('Status:', result.status); // 'ACTIVE' | 'TRIAL' | 'REJECTED' | 'CANCELLED'

---

Configuration

const fib = new FibSubscribe({
  clientId: 'YOUR_CLIENT_ID',         // required
  clientSecret: 'YOUR_CLIENT_SECRET', // required
  environment: 'stage',               // 'stage' (default) | 'production'
});

Option	Type	Required	Default	Description
clientId	string	✅	—	FIB-issued client ID
clientSecret	string	✅	—	FIB-issued client secret
environment	string	❌	'stage'	'stage' for testing, 'production' for live

Environment	Base URL
Stage (Test Mode)	https://fib-stage.fib.iq
Production (Live)	https://fib.prod.fib.iq

---

API Reference

Create Subscription

const sub = await fib.createSubscription(options);

Parameter	Type	Required	Default	Description
title	string	✅	—	Display name (e.g. "Premium Streaming")
description	string	❌	—	What the subscriber gets
amount	number	✅	—	Charge per interval (positive number)
currency	string	❌	'IQD'	ISO 4217 code
interval	string	✅	—	ISO-8601 billing period (e.g. "P1M", "P7D")
trialPeriod	string	❌	—	ISO-8601 free trial (e.g. "P7D"). Omit = no trial
expiresIn	string	❌	—	QR code validity (e.g. "P1DT12H")
statusCallbackUrl	string	❌	—	Webhook URL for status-change events

Response

{
  "subscriptionId": "1d1b9133-6932-45b6-94bc-c40882da1bf9",
  "readableCode": "DMRJ-JAMJ-RN36",
  "qrCode": "data:image/png;base64,...",
  "validUntil": "2025-08-19T19:40:35.087Z",
  "appLink": "https://p-stage.fib.iq/0fc8/subscription?identifier=DDRKDIOZJEUW"
}

---

Get Subscription

const details = await fib.getSubscription(subscriptionId);

Response

{
  "id": "8d77b6b2-3eb3-4c74-9a95-9779ddfbbe94",
  "readableCode": "DAID-9CTX-5YBU",
  "title": "Premium Membership",
  "description": "Full access to all premium features.",
  "monetaryValue": { "amount": 5000, "currency": "IQD" },
  "interval": "P1M",
  "trialPeriod": "P7D",
  "status": "TRIAL",
  "activeUntil": 1755588900190,
  "lastPaymentAt": null
}

---

Cancel Subscription

Cancels an active or trial subscription. Returns null on success (HTTP 202).

await fib.cancelSubscription(subscriptionId);

---

Wait for Activation

Polls getSubscription() until the subscription leaves DRAFT status or the timeout is exceeded.

const result = await fib.waitForActivation(subscriptionId, options);

Parameter	Type	Default	Description
intervalMs	number	4000	Polling interval in milliseconds
timeoutMs	number	300000	Max wait time in ms (default: 5 min)

---

Subscription Statuses

Status	Description
DRAFT	Created, awaiting subscriber confirmation via QR/app
TRIAL	Subscriber confirmed, currently in free trial
ACTIVE	Trial ended or no trial — subscriber is actively charged
REJECTED	Subscriber declined the subscription
CANCELLED	Cancelled by merchant or subscriber

---

ISO-8601 Period Cheatsheet

Value	Meaning
P1D	Every day
P7D	Every 7 days
P1M	Every month
P3M	Every 3 months
P1Y	Every year
P1DT12H	1 day 12 hours

---

Error Handling

import { FibSubscribe, FibSubscribeError } from 'fibsubscribe';

try {
  await fib.createSubscription({ title: 'Plan', amount: 1000, interval: 'P1M' });
} catch (err) {
  if (err instanceof FibSubscribeError) {
    console.error('API Error:', err.message);
    console.error('Status Code:', err.statusCode);
    console.error('Body:', err.body);
  } else {
    throw err;
  }
}

---

Webhook Integration

Pass a statusCallbackUrl when creating a subscription. FIB will POST to this URL on every status change.

app.post('/fib/subscription/webhook', (req, res) => {
  const { subscriptionId, status } = req.body;

  res.sendStatus(200); // acknowledge immediately

  switch (status) {
    case 'ACTIVE':    /* enable full access */    break;
    case 'TRIAL':     /* enable trial access */   break;
    case 'CANCELLED': /* revoke access */         break;
    case 'REJECTED':  /* notify the user */       break;
  }
});

---

Examples

File	Description
examples/basic.js	Create → wait → cancel flow
examples/express-webhook.js	Express server with full webhook handling

FIB_CLIENT_ID=xxx FIB_CLIENT_SECRET=yyy node examples/basic.js

---

ESM Compatibility Note

This package is ESM-only. For CommonJS projects use a dynamic import:

const { FibSubscribe } = await import('fibsubscribe');

---

License

MIT © Rageofkurd