beckn-lightweight/README.md

Lightweight Node.js utilities to integrate Beckn protocol into existing BPPs

@kenpath/beckn-lightweight
Lightweight Beckn protocol handler utilities for Node.js BPP (Beckn Provider Platform) services.
This package simplifies handling incoming Beckn protocol requests such as search, and posting asynchronous callbacks like on_search — with minimal boilerplate.

🔧 Features
✅ Auto ACK (202) response for incoming Beckn protocol requests

🔁 Async support for posting on_search responses using the original context

🧩 Plug-and-play logic integration — just write your business function

📦 Designed for lightweight BPPs and microservices

Installation:
npm install @kenpath/beckn-lightweight

Usage
In your BPP Express service:

app.js:

    const express = require('express');
    const beckn = require('@kenpath/beckn-lightweight');
    const app = express();
    app.use(express.json());

    app.post('/beckn/search', beckn.handleSearch(async (intent, context) => {
    // Replace with internal logic or mock data
    const mockCatalog = [
        { id: 'seed-101', name: 'Hybrid Maize', price: 1200, stock: 50 }
    ];

    return {
        catalog: mockCatalog.map(p => ({
        id: p.id,
        descriptor: { name: p.name },
        price: { currency: 'INR', value: p.price.toFixed(2) },
        quantity: { available: { count: p.stock } }
        }))
    };
    }));

app.listen(3000, () => console.log('BPP service running on port 3000'));
✅ This will:

    Respond with a 202 ACK immediately to the search call

    Then call your async function

    Then post the on_search response to the bap_uri provided in context

🧪 Testing
    Send a POST request to /beckn/search:

    Request:
        {
        "context": {
            "bap_uri": "http://localhost:4000/beckn",
            "transaction_id": "tx-001",
            "message_id": "msg-001",
            "timestamp": "2025-07-16T12:00:00Z",
            "action": "search",
            "domain": "agriculture"
        },
        "message": {
            "intent": {
            "item": {
                "descriptor": { "name": "urea" }
            }
            }
        }
        }
    Set up a mock BAP listener at http://localhost:4000/beckn/on_search to verify callback.


API Reference:

    handleSearch(handlerFunction)

    Wraps the /search endpoint.

    Sends ACK immediately

    Executes handlerFunction(intent, context)

    Sends on_search to context.bap_uri

📃 License
MIT © Kenpath