# 📡 frappe-event-listener

A lightweight React hook for listening to **Frappe / ERPNext Socket.IO events** in real-time.  
Built on top of [`frappe-react-sdk`](https://www.npmjs.com/package/frappe-react-sdk).

---

## 🚀 Features
- 🔌 Real-time **doctype create / update / list events**  
- 👥 Tracks **document viewers**  
- 🟢 Provides **socket connection status**  
- 📤 Emit **custom events with values**  
- ⚡ Simple React Hook API  
- 📦 Ready-to-use as an **NPM package**  

---

## 📦 Installation

```bash
npm install frappe-event-listener
# or
yarn add frappe-event-listener

Prerequisite: make sure frappe-react-sdk is installed and configured in your project.

🛠 Usage

import React from "react";
import { useFrappeEventListener } from "frappe-event-listener";

function CustomerList() {
  const { viewers, socketStatus, emitEvent } = useFrappeEventListener(
    "Customer",
    (event) => {
      console.log("📩 Incoming event:", event);
    }
  );

  return (
    <div>
      <h2>Customer Monitor</h2>
      <p>🔌 Socket status: {socketStatus}</p>
      <p>👥 Viewers: {viewers.join(", ") || "None"}</p>

      <button
        onClick={() =>
          emitEvent("custom_event", { message: "Hello from CustomerList!" })
        }
      >
        🔔 Emit Custom Event
      </button>
    </div>
  );
}

export default CustomerList;

📚 API

useFrappeEventListener(doctype, onEventCallback?)

| Parameter | Type | Required | Description | |-------------------|------------|----------|-----------------------------------------------------------------------------| | doctype | string | ✅ | The Frappe doctype name to subscribe to (e.g. "Customer"). | | onEventCallback | function | ❌ | Callback executed when a new event (create / update / list) is received. |

Returns

{
  viewers: string[];                                     // List of active viewers for the doctype
  socketStatus: string;                                  // Current socket connection status
  emitEvent: (eventName: string, value?: any) => void;   // Emit custom events
}

⚡ Example Output

Socket status: connected
Viewers: [email protected], [email protected]
📩 Incoming event: { name: "CUST-0001", doctype: "Customer", customer_name: "ABC Corp" }

📄 Requirements

• React ≥ 17
• frappe-react-sdk ≥ 1.0.0

🤝 Contributing

PRs and issues are welcome!
Please open an issue first to discuss what you’d like to change.

🛡 License

MIT © 2025 Abhishek-Chougule