npm package: @kagenoureal/zbail
Description: A WebSockets library for interacting with WhatsApp Web
Author: Kage n dep
Latest version: 10.3.7

# Zbail — WhatsApp automation
<div align="center">

  <img src="https://raw.githubusercontent.com/kagenouReal/zbail/refs/heads/master/lib/me.jpg" width="400" />

  <p>
    <a href="https://github.com/kagenouReal/zbail">
      <img src="https://img.shields.io/badge/GitHub-Repository-181717?logo=github&logoColor=white" />
    </a>
    <a href="https://www.npmjs.com/package/@kagenoureal/zbail">
      <img src="https://img.shields.io/badge/NPM-Package-CB3837?logo=npm&logoColor=white" />
    </a>
  </p>

</div>

> A lightweight, developer-focused toolkit for building WhatsApp integrations and automation on top of the Baileys protocol surface.  
> **Not** a fork of any specific project; this repo provides its own implementation helpers, utilities, and extension points for building bots, automation, and channel-aware messaging systems.

---

## Table of Contents
- [What is Zbail?](#what-is-zbail)
- [Highlights](#highlights)
- [Install](#install)
- [Quick Start](#quick-start)
- [Core Concepts & API](#core-concepts--api)
  - [makeWASocket](#makeWASocket)
  - [Basic bot skeleton](#basic-bot-skeleton)
  - [Generate custom pairing code](#generate-custom-pairing-code)
- [Configuration](#configuration)
- [Development & Contributing](#development--contributing)
- [Testing & CI](#testing--ci)
- [Security](#security)
- [License](#license)
- [Changelog](#changelog)
- [FAQ](#faq)

---

## What is Zbail?

Zbail is a developer toolkit for building WhatsApp-based integrations using the Baileys open protocol interface.  
It’s designed to be lightweight, modular, and easy to embed into Node.js applications — with helpers for messaging automation, channel management, and pairing workflows.

 Zbail does not include any proprietary WhatsApp components.  
 It enhances developer experience around existing open implementations.
---

## Highlights

- Developer-first API, minimal magic, fully async/await friendly.
- Utilities for channel-targeted messaging and newsletter workflows.
- Helpers for interactive messages (buttons, selects, CTAs).
- Small, well-documented code surface suitable for unit testing.
- Opinionated defaults for logging, rate-limiting, and reconnection behavior.

---

## Install

```bash
# Install from GitHub (example)
npm install github:kagenouReal/zbail
```

Or in your `package.json`:

```json
"dependencies": {
  "@kagenoureal/zbail": "latest"
}
```

---

## Quick Start

```js
// ESM
import makeWASocket from '@kagenoureal/zbail'

async function main() {
  const sock = await makeWASocket({
    logger: console,        // simple logger (replaceable)
    auth: { store: {} },    // simple in-memory auth store (replace with persistent store)
    reconnectIntervalMs: 2000,
  })

  sock.on('connection.update', (update) => {
    console.log('connection update', update)
  })

  // Simple message handler
  sock.on('message', async (msg) => {
    if (!msg.isGroup && msg.text === 'ping') {
      await sock.sendText(msg.from, 'pong')
    }
  })
}

main().catch(console.error)
```

---

## Core Concepts & API

Zbail exposes a compact core around the standard socket model.

### `makeWASocket(opts)`

Creates a connected socket instance.

**Options**
- `logger` — console-like logger (`info`, `warn`, `error`, `debug`).
- `auth` — auth store object (load/save hooks).
- `reconnectIntervalMs` — reconnect backoff.

**Events**
- `connection.update` — emitted when connection state changes.
- `message` — raw inbound message wrapper.
- `presence.update` — presence events.

**Methods**
- `sendMessage(jid, content, options)` — low-level send.
- `newsletterMetadata(type, id)` — fetch metadata for a newsletter or channel.

---

## Examples

### Basic bot skeleton

```js
import makeWASocket from '@kagenoureal/zbail'

const sock = await makeWASocket({ auth: { store: {} }, logger: console })

sock.on('message', async (m) => {
  if (!m.text) return
  const text = m.text.toLowerCase()
  if (text === 'hello') await sock.sendText(m.from, 'Hello! How can I help?')
  if (text.startsWith('echo ')) await sock.sendText(m.from, text.slice(5))
})
```

### Send interactive button message

```js
await sock.sendMessage(jid, {
  text: "Example Message",
  footer: "Footer Text",
  buttons: [
    {
      buttonId: "example",
      buttonText: { displayText: "Click Me" }
    }
  ],
  headerType: 1,
}, { quoted: m });
```

#### 🎛️ Interactive Message

```ts
await sock.sendMessage(jid, {
  text: "Choose an option below",
  title: "Interactive Example",
  footer: "Powered by Zbail",
  interactiveButtons: [
    {
      "name": "single_select",
      "buttonParamsJson": "{"title":"Menu","sections":[{"title":"Main","rows":[{"header":"Option","title":"Button A","description":"First action","id":"id_a"},{"header":"Option","title":"Button B","description":"Second action","id":"id_b"}]}]}"
    },
    {
      "name": "cta_url",
      "buttonParamsJson": "{"display_text":"Visit Website","url":"https://www.google.com"}"
    }
  ]
}, { quoted: m });
```


### Generate custom pairing code

```js
if (usePairingCode && !sock.authState.creds.registered) {
  const phone = await askUserForPhone()
  const code = await sock.requestPairingCode(phoneNumber, "zbail123");
  console.log('pairing code', code)
}
```

---

## Configuration

Environment variables / config object supported:

- `ZBAIL_LOG_LEVEL` — `info|warn|debug|error`
- `ZBAIL_RECONNECT_MS` — integer reconnect interval
- `ZBAIL_STORAGE` — `file|memory|redis` (storage backend for auth)
- `ZBAIL_ALLOW_CHANNELS` — boolean (enable channel messaging)

Example config file snippet (`config.js`):

```js
export default {
  logLevel: process.env.ZBAIL_LOG_LEVEL || 'info',
  storage: process.env.ZBAIL_STORAGE || 'file',
  reconnectMs: Number(process.env.ZBAIL_RECONNECT_MS || 2000),
}
```

---

## Development & Contributing

- Clone the repo, `npm ci`, and run tests with `npm test`.
- Follow conventional commits for the changelog.
- Open issues for bugs or feature requests — include reproducible steps.

### Local dev

```bash
git clone https://github.com/kagenouReal/zbail.git
cd zbail
npm ci
npm run build
npm test
```

---

## Testing & CI

- Unit tests: Jest
- Linting: ESLint + Prettier
- CI: GitHub Actions (node matrix, lint, test, build, release)

---

## Security

- Do not commit secret tokens or private keys.
- Rotate credentials and tokens regularly.
- Report vulnerabilities privately via the repository security policy.

---

## License
Parts of this project are based on [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys),  
licensed under the [MIT License](https://github.com/WhiskeySockets/Baileys/blob/master/LICENSE).
---

## Changelog

- **v10.3.5** — Initial developer release: core socket wrapper, interactive messages, pairing utilities.

---

## FAQ

**Q: Is Zbail an official WhatsApp library?**  
A: No. Zbail is an integration toolkit built around a protocol-compatible socket interface. It is community-driven.

**Q: Can I publish apps built with Zbail?**  
A: Yes, but ensure you comply with WhatsApp’s Terms of Service and local laws.

---