telebirr-nodejs 1.0.1 → 1.0.2

package/README.md

@@ -1,58 +1,60 @@
-telebirr-nodejs
+# telebirr-nodejs
 
-A simple, opinionated Node.js SDK for integrating Telebirr C2B payments with automatic request signing, Fabric token handling, and checkout URL generation.
+A simple, opinionated Node.js SDK for integrating **Telebirr C2B payments** with automatic request signing, Fabric token handling, and checkout URL generation.
 
-Installation
-npm install telebirr-node
+---
 
-Required Configuration
+## Installation
 
-Telebirr requires five credentials, plus callback URLs.
+```bash
+npm install telebirr-nodejs
+Required Configuration
+Telebirr requires credentials and callback URLs.
 You should never hard-code secrets. Always load them from process.env.
 
 Required Credentials
-Name Description
-FABRIC_APP_ID Fabric application ID
-FABRIC_APP_SECRET Fabric application secret
-MERCHANT_APP_ID Merchant application ID
-MERCHANT_CODE Merchant code
-MERCHANT_PRIVATE_KEY RSA private key (PEM string)
+Name	Description
+FABRIC_APP_ID	Fabric application ID
+FABRIC_APP_SECRET	Fabric application secret
+MERCHANT_APP_ID	Merchant application ID
+MERCHANT_CODE	Merchant code
+MERCHANT_PRIVATE_KEY	RSA private key (PEM string)
+
 Required URLs
-Name Description
-TELEBIRR_NOTIFY_URL Server-to-server callback URL
-TELEBIRR_REDIRECT_URL User redirect URL after payment
+Name	Description
+TELEBIRR_NOTIFY_URL	Server-to-server callback URL
+TELEBIRR_REDIRECT_URL	User redirect URL after payment
+
 Basic Setup
+ts
+Copy code
 import { TelebirrClient } from "telebirr-nodejs";
 
 const client = new TelebirrClient({
-mode: "sandbox", // "simulate" | "sandbox" | "production"
+  mode: "sandbox", // "simulate" | "sandbox" | "production"
 
-appId: process.env.FABRIC_APP_ID!,
-appSecret: process.env.FABRIC_APP_SECRET!,
+  appId: process.env.FABRIC_APP_ID!,
+  appSecret: process.env.FABRIC_APP_SECRET!,
 
-merchantAppId: process.env.MERCHANT_APP_ID!,
-merchantCode: process.env.MERCHANT_CODE!,
-privateKey: process.env.MERCHANT_PRIVATE_KEY!,
+  merchantAppId: process.env.MERCHANT_APP_ID!,
+  merchantCode: process.env.MERCHANT_CODE!,
+  privateKey: process.env.MERCHANT_PRIVATE_KEY!,
 
-notifyUrl: process.env.TELEBIRR_NOTIFY_URL!,
-redirectUrl: process.env.TELEBIRR_REDIRECT_URL!,
+  notifyUrl: process.env.TELEBIRR_NOTIFY_URL!,
+  redirectUrl: process.env.TELEBIRR_REDIRECT_URL!,
 
-http: true, // allow HTTP in simulator mode
-IntegrationOption: "C2B",
+  http: true, // allow HTTP in simulator mode
+  IntegrationOption: "C2B",
 });
-
 Important
-
 MERCHANT_PRIVATE_KEY must be the full PEM string, including:
 
+vbnet
+Copy code
 -----BEGIN RSA PRIVATE KEY-----
-
-and
-
+...
 -----END RSA PRIVATE KEY-----
-
 Example API Routes
-
 Below is a complete demo using three routes:
 
 POST /payment/initiate
@@ -62,22 +64,21 @@ GET /payment/status/:merchOrderId
 POST /payment/refund
 
 Initiate Payment
-
 Creates an order and redirects the user to the Telebirr checkout page.
 
+ts
+Copy code
 app.post("/payment/initiate", async (req, res) => {
-const checkoutUrl = await client.preOrder({
-merchOrderId: "order123",
-title: "Phone",
-amount: "12",
-callbackInfo: "from web checkout",
+  const checkoutUrl = await client.preOrder({
+    merchOrderId: "order123",
+    title: "Phone",
+    amount: "12",
+    callbackInfo: "from web checkout",
+  });
+
+  res.redirect(checkoutUrl);
 });
-
-res.redirect(checkoutUrl);
-});
-
 What happens internally
-
 Fabric token is fetched and cached
 
 Order is signed and created
@@ -86,22 +87,21 @@ Checkout URL is generated
 
 User is redirected to Telebirr
 
-If you are using a frontend framework (e.g. React) and do not want to lose application state, return the checkout URL as JSON and let the frontend handle the redirection.
+If you are using a frontend framework (for example React) and do not want to lose application state, return the checkout URL as JSON and let the frontend handle the redirection.
 
 Query Payment Status
-
 Used to check the payment result using the merchant order ID.
 
+ts
+Copy code
 app.get("/payment/status/:merchOrderId", async (req, res) => {
-const { merchOrderId } = req.params;
+  const { merchOrderId } = req.params;
 
-const info = await client.queryOrder(merchOrderId);
+  const info = await client.queryOrder(merchOrderId);
 
-res.json(info);
+  res.json(info);
 });
-
 Typical Use Cases
-
 Payment confirmation pages
 
 Background reconciliation jobs
@@ -109,47 +109,45 @@ Background reconciliation jobs
 Admin dashboards
 
 Refund Payment
-
 Refunds a completed transaction.
 
+ts
+Copy code
 app.post("/payment/refund", async (req, res) => {
-const refundData = await client.refundOrder({
-merchOrderId: "order123",
-refundRequestNo: "original-transaction-id",
-refundReason: "customer request",
-amount: "12",
-});
-
-res.json(refundData);
+  const refundData = await client.refundOrder({
+    merchOrderId: "order123",
+    refundRequestNo: "original-transaction-id",
+    refundReason: "customer request",
+    amount: "12",
+  });
+
+  res.json(refundData);
 });
-
 Notes
-
 refundRequestNo must be unique
 
 Refund amount must not exceed the original payment amount
 
 Simulator Mode
-
 To use the simulator provided by this package, set the mode to simulate.
 
+ts
+Copy code
 import { TelebirrClient } from "telebirr-nodejs";
 
 const client = new TelebirrClient({
-mode: "simulate",
-notifyUrl: "https://example.com/notify",
-redirectUrl: "https://example.com/redirect",
-http: true,
-IntegrationOption: "C2B",
+  mode: "simulate",
+  notifyUrl: "https://example.com/notify",
+  redirectUrl: "https://example.com/redirect",
+  http: true,
+  IntegrationOption: "C2B",
 });
-
 This simulator is for learning and development purposes only.
 The simulation server is provided by this package, not by Telebirr.
 
 For real testing, use Telebirr’s sandbox mode and whitelist your public IP address in the Telebirr portal.
 
 Supported Features
-
 Fabric token handling
 
 RSA-SHA256 request signing
@@ -163,19 +161,24 @@ Refunds
 Simulator support
 
 Notify URL Handling
-
 Please refer to Telebirr’s official documentation to correctly handle notify callbacks:
 
 https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/Notify_Callback
 
-you can generate private and public keys instantly
+RSA Key Generation
+You can generate private and public keys instantly.
+
+ts
+Copy code
 import { generateKeys } from "telebirr-nodejs";
 
 generateKeys({
-dir: process.cwd(),
-privateKeyName: "telefy_private.pem",
-publicKeyName: "telefy_public.pem",
-overwrite: false,
+  dir: process.cwd(),
+  privateKeyName: "telefy_private.pem",
+  publicKeyName: "telefy_public.pem",
+  overwrite: false,
 });
+This will generate two .pem files in your root directory.
 
-this will add two files .pem in your rook directory you can configure them as u want but always remember the merchantPrivateKey option always accepts a string value so u have to read use fs module and pass the returned value to the option
+The merchantPrivateKey option always accepts a string, so you must read the private key file using Node.js fs and pass the value to the client configuration.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telebirr-nodejs",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Unofficial Telebirr Node.js SDK.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "axios": "^1.13.2",
     "nanoid": "^5.1.6"
   },
   "keywords": [
@@ -31,8 +30,7 @@
     "ethiopia",
     "payment",
     "fintech",
-    "nodejs",
-    "sdk"
+    "nodejs"
   ],
   "author": "chernet manaye",
   "license": "MIT"