npm package: @nazzelofficial/bituin-fca
Description: Advanced Facebook Chat API library for Node.js/TypeScript with anti-ban features, real-time messaging, and comprehensive bot functionality
Author: Nazzel Development
Latest version: 1.12.7

# Bituin-FCA

[![npm version](https://badge.fury.io/js/bituin-fca.svg)](https://www.npmjs.com/package/bituin-fca)
[![CI](https://github.com/nazzeldevelopment/bituin-fca/actions/workflows/ci.yml/badge.svg)](https://github.com/nazzeldevelopment/bituin-fca/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-98.8%25-blue)](https://www.typescriptlang.org/)
[![Node.js Version](https://img.shields.io/node/v/bituin-fca)](https://nodejs.org)
[![Downloads](https://img.shields.io/npm/dm/bituin-fca.svg)](https://www.npmjs.com/package/bituin-fca)
[![GitHub Stars](https://img.shields.io/github/stars/nazzeldevelopment/bituin-fca)](https://github.com/nazzeldevelopment/bituin-fca/stargazers)

Advanced Facebook Chat API library for Node.js/TypeScript. A modern, feature-rich alternative to facebook-chat-api with enhanced security, anti-ban measures, and comprehensive Messenger functionality.

## Core Features

* **Multiple Authentication Methods** - Email/password, session import, and account.txt support
* **Real-time Messaging** - MQTT WebSocket for instant message delivery
* **GraphQL API** - Full Facebook GraphQL integration
* **File Uploads** - Images, videos, audio, files, and stickers
* **Anti-Ban System** - Intelligent rate limiting, fingerprint rotation, human-like behavior
* **Custom Command System** - Build your own bot commands with cooldowns and permissions
* **Plugin System** - Extensible plugin architecture

## Advanced Features

* **Sticker & Custom Emoji** - Send stickers and custom emojis
* **Thread Themes** - Customize thread colors and themes
* **Message Translation** - Translate messages to 30+ languages
* **Analytics Dashboard** - Real-time bot analytics
* **Cross-Platform Notifications** - Discord, Telegram, Slack webhooks
* **Email Digests** - Daily/weekly message summaries
* **AI Features** - Smart replies, sentiment analysis, spam detection
* **Call Integration** - Voice/video call detection and management
* **Location Sharing** - Share and receive locations
* **Polls** - Create and manage polls
* **Stories** - View and interact with stories
* **E2E Encryption** - End-to-end message encryption

## Anti-Detection Suite

* **FingerprintManager** - Session fingerprint management with 6hr auto-rotation
* **RequestObfuscator** - Multi-layer request obfuscation with entropy injection
* **PatternDiffuser** - Adaptive delays to prevent detectable patterns
* **TrafficAnalysisResistance** - Timing jitter and traffic variability
* **SmartRateLimiter** - Intelligent message pacing with anti-ban integration
* **MQTTProtection** - Obfuscated MQTT traffic with keep-alive
* **DeviceIDGenerator** - Realistic device IDs from system hardware
* **UserAgentRotator** - Latest Chrome/Edge configurations with rotation
* **AutoCookieRefresh** - Fresh cookies every 20min + MQTT keep-alive every 30s

## Social Interaction Features

* **MessageEditor** - Edit bot's messages in-place
* **PostInteractionManager** - Comment and reply to public Facebook posts
* **FollowManager** - Follow/unfollow users automation
* **ProxyManager** - Full proxy support with testing utilities

## Group & Private Message Management

* **GroupChatManager** - Welcome/leave messages, announcements, moderation, warnings, muting
* **PrivateMessageManager** - Quick replies, templates, auto-responses, conversation tracking
* **MessengerBotManager** - Multi-prefix commands, permissions, scheduled messages, anti-spam

## Bot Utility Suite

* **MessageScheduler** - Schedule messages for future delivery (one-time or recurring)
* **AutoModerator** - Automatic moderation with word filters, spam detection, warnings, muting
* **ConversationLogger** - Log and analyze conversations with search, stats, and export
* **BotStatistics** - Comprehensive analytics (messages, commands, users, uptime, leaderboards)
* **ResponseTemplateManager** - Reusable response templates with variable substitution
* **WebhookNotifier** - Send notifications to Discord, Slack, Telegram webhooks
* **CommandCooldownManager** - Advanced cooldown system per user/thread with bypass options
* **UserPermissionSystem** - Role-based permissions with inheritance and granular control

## Installation

```bash
npm install bituin-fca
```

or

```bash
yarn add bituin-fca
```

## Quick Start

### Using account.txt (Recommended)

```typescript
import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA({
  appStatePath: 'account.txt',
  commandPrefix: '!',
  enableAntiBan: true
});

// Login with account.txt
await bot.loginWithAppState();

// Listen for messages
bot.on('message', (msg) => {
  console.log(`${msg.senderID}: ${msg.body}`);
});

// Send a message
await bot.sendMessage({
  threadID: '123456789',
  message: 'Hello from Bituin-FCA!'
});
```

### Using Email/Password

```typescript
import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA();

// Login with credentials
const success = await bot.loginWithEmail('email@example.com', 'password');

if (success) {
  // Save session as account.txt for future use
  await bot.saveAppState();
}
```

### Using Session Import

```typescript
import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA();

// Import base64-encoded session
await bot.loginWithSession(base64SessionData);
```

## account.txt Format

The `account.txt` file uses a clean, minimal cookie format:

```json
[
  {
    "key": "dbln",
    "value": "",
    "domain": ".facebook.com",
    "path": "/login/device-based/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "datr",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "sb",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "c_user",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "xs",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "vpd",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "ps_l",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "ps_n",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "pas",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "wl_cbv",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "fbl_st",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "wd",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "fr",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "presence",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  }
]
```

### Essential Cookies

Only these cookies are required for authentication:
- `c_user` - Your Facebook user ID
- `xs` - Session token

### Recommended Cookies

For better functionality, include:
- `datr` - Browser tracking cookie
- `sb` - Session cookie

### Optional Cookies

Additional cookies like `fr`, `locale`, `wd`, `presence`, `vpd`, `fbl_st`, `wl_cbv`, `pas`, `ps_l`, `ps_n` may improve stability.

## Creating Custom Commands

Bituin-FCA provides a flexible command system. Create your own custom commands by adding files to your `src/commands` directory:

```typescript
// src/commands/hello.ts
import { Command } from 'bituin-fca';

export const command: Command = {
  name: 'hello',
  description: 'Say hello to the user',
  usage: '!hello [name]',
  cooldown: 3000, // 3 seconds cooldown
  
  async execute(ctx, args) {
    const name = args[0] || 'there';
    await ctx.sendMessage({
      threadID: ctx.message.threadID,
      message: `Hello, ${name}!`
    });
  }
};
```

## Configuration

```typescript
interface BituinFCAConfig {
  sessionPath?: string;      // Path to account file (default: 'account.txt')
  appStatePath?: string;     // Path to account file (default: 'account.txt')
  encryptionKey?: string;    // Key for encrypting session/appstate
  commandPrefix?: string;    // Command prefix (default: '!')
  enableAntiBan?: boolean;   // Enable anti-ban measures (default: true)
  enablePlugins?: boolean;   // Enable plugin system (default: true)
  enableCommands?: boolean;  // Enable command system (default: true)
}
```

## Documentation

* [Full API Documentation](https://github.com/nazzeldevelopment/bituin-fca/tree/main/docs)
* [Examples](https://github.com/nazzeldevelopment/bituin-fca/tree/main/examples)
* [Migration Guide](https://github.com/nazzeldevelopment/bituin-fca/blob/main/docs/MIGRATION.md)
* [Plugin Development](https://github.com/nazzeldevelopment/bituin-fca/blob/main/docs/PLUGINS.md)
* [Command Creation](https://github.com/nazzeldevelopment/bituin-fca/blob/main/docs/COMMANDS.md)
* [Changelog](CHANGELOG.md)

## Anti-Ban Features

Bituin-FCA includes comprehensive anti-ban measures:

* **Request Throttling** - Intelligent delays between requests
* **User-Agent Rotation** - Realistic browser fingerprints
* **Human Simulation** - Random delays and patterns
* **Checkpoint Detection** - Automatic handling of security checks
* **Health Monitoring** - Track account health score
* **Automatic Cooldown** - Reduce activity when suspicious

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

## Disclaimer

This is **NOT** an official Facebook API. Using unofficial APIs may violate Facebook's Terms of Service. Use at your own risk. This library is for educational purposes only.

## Salamat / Thank You / Acknowledgments

Maraming salamat sa lahat ng nag-contribute at gumamit ng Bituin-FCA!

* Inspired by [facebook-chat-api](https://github.com/Schmavery/facebook-chat-api) and [fca-unofficial](https://github.com/lequanglam/fca-unofficial)
* Salamat sa mga early adopters at testers ng library
* Salamat sa Filipino developer community para sa support
* Built with TypeScript for type safety
* Uses modern Node.js features

Special thanks to:
* **Schmavery** - Original facebook-chat-api creator
* **lequanglam** - fca-unofficial maintainer
* **@dongdev** - fca-unofficial inspiration
* **Filipino Bot Developers Community** - Continuous feedback and support
* **All Contributors** - Everyone who submitted issues, PRs, and suggestions

## Links

* [NPM Package](https://www.npmjs.com/package/bituin-fca)
* [GitHub Repository](https://github.com/nazzeldevelopment/bituin-fca)
* [Issue Tracker](https://github.com/nazzeldevelopment/bituin-fca/issues)
* [Changelog](CHANGELOG.md)
* [Security Policy](SECURITY.md)

## Support

* [GitHub Issues](https://github.com/nazzeldevelopment/bituin-fca/issues)
* [GitHub Discussions](https://github.com/nazzeldevelopment/bituin-fca/discussions)

---

Made with love by [Nazzel Development](https://github.com/nazzeldevelopment)