From 7e4ff712c047c7cc9da4aeb243c943f33a9d5344 Mon Sep 17 00:00:00 2001
From: jimmybot <nahremenkova@gmail.com>
Date: Mon, 11 May 2026 12:11:10 +0300
Subject: [PATCH] Improve adoption docs

---
 README.md    | 38 +++++++++++++++++++++++++++++++++++++-
 package.json | 11 +++++++----
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 7789396..ccd1549 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,23 @@
 
 TypeScript SDK and NestJS adapter for the MakeCommerce REST API.
 
+Targets Node.js `20+`. Ships dual `ESM`/`CommonJS` builds and a first-class NestJS subpath export.
+
 ## Install
 
 ```bash
 npm install @biggora/makecommerce
 ```
 
-## Node.js
+NestJS apps also need peer deps:
+
+```bash
+npm install @nestjs/common @nestjs/core reflect-metadata rxjs
+```
+
+## Quick Start: Checkout
+
+Create a transaction with return, cancel, and notification URLs. Redirect the buyer to the returned payment URL, then confirm the transaction status from a server-side notification before fulfilling the order.
 
 ```ts
 import { createMakeCommerceClient } from '@biggora/makecommerce';
@@ -52,10 +62,34 @@ const transaction = await makeCommerce.transactions.create({
 });
 
 const redirectUrl = transaction.payment_methods?.other?.find((method) => method.name === 'redirect')?.url;
+
+console.log(redirectUrl);
 ```
 
 `environment` defaults to `test`. Use `environment: 'live'` for `https://api.maksekeskus.ee`, or pass `baseUrl` for custom routing.
 
+## Webhook Notifications
+
+MakeCommerce sends transaction updates to the `notification_url` configured on the transaction. Parse the incoming body, then read the transaction from MakeCommerce before changing local order state.
+
+```ts
+export async function handleMakeCommerceNotification(body: { transaction?: string; id?: string; reference?: string }) {
+  const transactionId = body.transaction ?? body.id;
+
+  if (!transactionId) {
+    throw new Error('Missing MakeCommerce transaction id');
+  }
+
+  const transaction = await makeCommerce.transactions.get(transactionId);
+
+  if (transaction.status === 'COMPLETED') {
+    // Mark body.reference as paid in your order system.
+  }
+
+  return 'OK';
+}
+```
+
 ## Resources
 
 ```ts
@@ -122,6 +156,8 @@ MakeCommerceModule.forRootAsync({
 });
 ```
 
+Inject the SDK client in controllers that receive `notification_url` callbacks and reuse the same transaction confirmation flow there.
+
 ## Errors
 
 Failed API responses and request failures throw `MakeCommerceApiError`.
diff --git a/package.json b/package.json
index 351e4e3..bf8a2da 100644
--- a/package.json
+++ b/package.json
@@ -3,10 +3,13 @@
   "version": "1.0.2",
   "description": "TypeScript SDK and NestJS adapter for MakeCommerce API.",
   "keywords": [
-    "makecommerce",
-    "maksekeskus",
-    "payments",
-    "payment-gateway",
+    "makecommerce",
+    "maksekeskus",
+    "payments",
+    "checkout",
+    "webhooks",
+    "refunds",
+    "payment-gateway",
     "payment-api",
     "sdk",
     "api-client",