### Start Wildcat Server (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This command starts the Wildcat server after dependencies are installed and configuration is set up. It assumes Node.js and npm are installed and the project is in the current directory.

```bash
npm start
```

--------------------------------

### Clone Wildcat Repository and Install Dependencies (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This snippet shows how to clone the Wildcat project from GitHub and install its necessary Node.js dependencies using npm. It requires Git and Node.js/npm to be installed.

```bash
git clone https://github.com/NotoriousArnav/wildcat.git
cd wildcat
npm install
```

--------------------------------

### Run Wildcat Docker Container with MongoDB Container (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This sequence sets up a Docker network, starts a MongoDB container, and then runs the Wildcat container on the same network, connecting to the MongoDB container. This is useful for isolated development environments.

```bash
docker network create wildcat-net || true

docker run -d --name mongo --network wildcat-net -p 27017:27017 mongo:6

docker run --name wildcat --network wildcat-net -p 3000:3000 \
  -e MONGO_URL="mongodb://mongo:27017" \
  -e DB_NAME=wildcat \
  -e AUTO_CONNECT_ON_START=true \
  wildcat:latest
```

--------------------------------

### Start Wildcat in Development Mode (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This command starts the Wildcat server in development mode, typically enabling features like automatic code reloading and restarting upon file changes. It relies on the `dev` script defined in `package.json`.

```bash
npm run dev
```

--------------------------------

### Account Status API

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

Retrieve the connection status and QR code for a specific WhatsApp account. This is used for initial setup and verification.

```APIDOC
## GET /accounts/{id}/status

### Description
Retrieves the connection status of a specific WhatsApp account. If the account is not yet connected, it will return a QR code for authentication.

### Method
GET

### Endpoint
/accounts/{id}/status

#### Path Parameters
- **id** (string) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **status** (string) - The current connection status (e.g., 'connected', 'disconnected', 'initializing').
- **qr** (string, optional) - The QR code string required for authentication, only present if status is not 'connected'.

#### Response Example (Not Connected)
```json
{
  "status": "initializing",
  "qr": "SOME_QR_CODE_STRING"
}
```

#### Response Example (Connected)
```json
{
  "status": "connected"
}
```
```

--------------------------------

### Install and Run Wildcat Node.js Server

Source: https://github.com/notoriousarnav/wildcat/blob/master/README.md

Commands to install dependencies, configure environment variables, and start the Wildcat Node.js server. Assumes Node.js and npm are installed. Requires a `.env` file for configuration.

```bash
npm install
cp .env.example .env
npm start
```

--------------------------------

### Create a Wildcat WhatsApp Account (curl)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This `curl` command demonstrates how to create a new WhatsApp account within the Wildcat system by making a POST request to the `/accounts` endpoint. It requires the Wildcat server to be running.

```bash
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{"id": "myaccount", "name": "My WhatsApp Account"}'
```

--------------------------------

### Account Creation API

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

Create a new WhatsApp account within the Wildcat system. This involves providing a unique account ID and a display name.

```APIDOC
## POST /accounts

### Description
Creates a new WhatsApp account entry in the Wildcat system.

### Method
POST

### Endpoint
/accounts

#### Request Body
- **id** (string) - Required - A unique identifier for the account.
- **name** (string) - Required - The display name for the WhatsApp account.

### Request Example
```json
{
  "id": "myaccount",
  "name": "My WhatsApp Account"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created account.
- **name** (string) - The name of the created account.
- **status** (string) - The initial status of the account (e.g., 'initializing').

#### Response Example
```json
{
  "id": "myaccount",
  "name": "My WhatsApp Account",
  "status": "initializing"
}
```
```

--------------------------------

### Get Wildcat Account Status and QR Code (curl)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This `curl` command retrieves the status of a specific Wildcat account, including the QR code needed for linking a WhatsApp device. It requires the account to have been previously created.

```bash
curl http://localhost:3000/accounts/myaccount/status
```

--------------------------------

### Create Account and Show QR using npm account:create:qr

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Creates a new account and displays a QR code for WhatsApp linking. It polls for up to 60 seconds for the QR code and requires `jq`. It can render high-quality QR codes if `qrencode` is installed, otherwise it uses a bundled package.

```bash
npm run account:create:qr <accountId> [name]
```

--------------------------------

### Configure Wildcat Environment Variables (.env file)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This snippet illustrates the structure of the `.env` file used to configure Wildcat. It specifies settings for the server, MongoDB connection, logging, and optional features like admin notifications and auto-connection.

```env
# Server configuration
HOST=0.0.0.0
PORT=3000

# MongoDB configuration
MONGO_URL=mongodb://localhost:27017
DB_NAME=wildcat

# Optional: Logging level
LOG_LEVEL=info

# Optional: Admin number to receive startup ping
# ADMIN_NUMBER=1234567890@s.whatsapp.net

# Auto connect restored accounts
# AUTO_CONNECT_ON_START=true
```

--------------------------------

### API Testing with Curl Commands (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Provides example `curl` commands for interacting with the local API. It covers testing the health check endpoint, creating an account, and sending a message, demonstrating different HTTP methods and JSON payloads.

```bash
# Health check
curl http://localhost:3000/ping

# Create account
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{"id": "test", "name": "Test Account"}'

# Send message
curl -X POST http://localhost:3000/accounts/test/message/send \
  -H 'Content-Type: application/json' \
  -d '{"to": "1234567890@s.whatsapp.net", "message": "Test"}'
```

--------------------------------

### Ping Endpoint

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

A health check endpoint to verify if the Wildcat server is running and responsive.

```APIDOC
## GET /ping

### Description
Health check endpoint to verify if the server is operational.

### Method
GET

### Endpoint
/ping

### Response
#### Success Response (200)
- **ok** (boolean) - Always true if the server is running.
- **pong** (boolean) - Always true, confirming the endpoint was reached.

#### Response Example
```json
{
  "ok": true,
  "pong": true
}
```
```

--------------------------------

### Send a Test Message via Wildcat API (curl)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

This `curl` command sends a test message to a specified WhatsApp number using the Wildcat API. It requires the Wildcat server to be running and the target account to be connected.

```bash
curl -X POST http://localhost:3000/accounts/myaccount/message/send \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "1234567890@s.whatsapp.net",
    "message": "Hello from Wildcat API!"
  }'
```

--------------------------------

### Conventional Commit Message Examples (Text)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Illustrates the structure and types for commit messages following the conventional commits specification. This helps in automating changelog generation and standardizing commit history.

```text
feat: add media upload endpoint
fix: handle invalid message IDs
docs: update API reference
```

--------------------------------

### Send Message API

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/SETUP.md

Send a message to a specified recipient using a particular WhatsApp account. Requires the recipient's JID and the message content.

```APIDOC
## POST /accounts/{id}/message/send

### Description
Sends a message to a specified recipient using the designated WhatsApp account.

### Method
POST

### Endpoint
/accounts/{id}/message/send

#### Path Parameters
- **id** (string) - Required - The unique identifier of the account to send the message from.

#### Request Body
- **to** (string) - Required - The recipient's WhatsApp JID (e.g., '1234567890@s.whatsapp.net').
- **message** (string) - Required - The content of the message to be sent.

### Request Example
```json
{
  "to": "1234567890@s.whatsapp.net",
  "message": "Hello from Wildcat API!"
}
```

### Response
#### Success Response (200)
- **sent** (boolean) - Indicates if the message was successfully queued for sending.

#### Response Example
```json
{
  "sent": true
}
```
```

--------------------------------

### Show All Available Commands using npm cli

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Displays a help message listing all available commands and their usage. This is the primary command for understanding the CLI's capabilities.

```bash
npm run cli
```

--------------------------------

### Logging Helper Usage

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Demonstrates the usage of logging helpers from `logger.js`, such as `httpLogger`, `wireSocketLogging`, and `appLogger`. It emphasizes avoiding logging sensitive information.

```javascript
const logger = require('./logger');

// Example usage
logger.appLogger.info('Application started successfully.');
// logger.httpLogger(...);
// logger.wireSocketLogging(...);
```

--------------------------------

### Build and Run Wildcat Docker Image

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Docker commands for building the Wildcat image and running it as a container. Includes examples for connecting to MongoDB, setting environment variables, and using Docker networks.

```bash
# Build image
docker build -t wildcat:latest .

# Run with MongoDB connection
docker run --name wildcat -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e MONGO_URL="mongodb://host.docker.internal:27017" \
  -e DB_NAME=wildcat \
  -e AUTO_CONNECT_ON_START=true \
  wildcat:latest

# Run with Docker network
docker network create wildcat-net
docker run -d --name mongo --network wildcat-net mongo:6
docker run --name wildcat --network wildcat-net -p 3000:3000 \
  -e MONGO_URL="mongodb://mongo:27017" \
  -e DB_NAME=wildcat \
  wildcat:latest
```

--------------------------------

### List All Accounts (Full Details) using npm accounts:list

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Fetches comprehensive details for all managed accounts. This command provides more in-depth information compared to the compact view.

```bash
npm run accounts:list
```

--------------------------------

### JavaScript/Node.js API Endpoint Example (JavaScript)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Demonstrates a well-structured asynchronous function for sending a message via an API endpoint. It includes input validation, error handling using try/catch, and follows the specified JSON response format for success and failure.

```javascript
// Good: Clear function with error handling
async function sendMessage(req, res) {
  const { to, message } = req.body;
  if (!to || !message) {
    return res.status(400).json({
      ok: false,
      error: 'to and message are required'
    });
  }

  try {
    const result = await whatsapp.sendMessage(to, { text: message });
    return res.status(200).json({ ok: true, messageId: result.key.id });
  } catch (err) {
    console.error('Send message error:', err);
    return res.status(500).json({ ok: false, error: 'internal_error' });
  }
}
```

--------------------------------

### Connect or Restart Account using npm account:connect

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Initiates or restarts the connection for a specified account. This is useful for re-establishing a session or troubleshooting connection issues.

```bash
npm run account:connect <accountId>
```

```bash
npm run account:connect mynumber
```

--------------------------------

### Route Definition Structure

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Illustrates the structure for defining API routes in `routes.js`. Each route is an object with 'method', 'path', and 'handler' properties. It shows how to access the `whatsapp_socket` from `req.app.locals`.

```javascript
const routes = [
  {
    method: 'GET',
    path: '/users',
    handler: (req, res) => {
      const whatsappSocket = req.app.locals.whatsapp_socket;
      // ... handler logic
    }
  }
];
module.exports = routes;
```

--------------------------------

### Jest Testing Command (if configured)

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Demonstrates how to run individual Jest tests using the `npx jest` command. This is a fallback command in case Jest is added to the project. It allows targeting specific tests by name.

```shell
npx jest path/to.test.js -t "name"
```

--------------------------------

### Node.js CommonJS Module Import

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Shows how to import modules using the CommonJS `require` syntax. Imports should be grouped by type (built-in, dependencies, local) and use relative paths.

```javascript
const http = require('http');
const express = require('express');
const localModule = require('./localModule');
```

--------------------------------

### Build, Run, and Health Check Commands

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Provides essential commands for building project dependencies, running the application in development or production, and performing a health check. Assumes Node.js environment and npm package manager.

```shell
npm ci
npm run dev
npm start
npm run ping
curl http://localhost:3000/ping
```

--------------------------------

### GET /ping

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Checks the status of the API server to ensure it is running and responsive.

```APIDOC
## GET /ping

### Description
Checks if the API server is running and responsive.

### Method
GET

### Endpoint
`/ping`

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates the server is operational.
- **pong** (boolean) - Confirms the server responded to the ping.
- **time** (string) - The timestamp of the response in ISO 8601 format.

#### Response Example
```json
{
  "ok": true,
  "pong": true,
  "time": "2025-01-15T12:30:45.123Z"
}
```
```

--------------------------------

### List All Messages (Full Details) using npm messages:all

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Fetches a comprehensive list of all messages, including full details for each message. This command is useful for detailed message history analysis.

```bash
npm run messages:all
```

--------------------------------

### Environment Variables Configuration (Environment Variables)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Lists essential environment variables for local development and operation of the Wildcat application. It specifies required variables like database connection details and port, along with optional configuration for logging and environment type.

```env
# Required
MONGO_URL=mongodb://localhost:27017
DB_NAME=wildcat
HOST=0.0.0.0
PORT=3000

# Optional
LOG_LEVEL=debug
NODE_ENV=development
```

--------------------------------

### GET /accounts

Source: https://github.com/notoriousarnav/wildcat/blob/master/TEST_REPORT.md

Lists all registered accounts, including their connection status and QR code availability.

```APIDOC
## GET /accounts

### Description
Retrieves a list of all registered accounts managed by the service.

### Method
GET

### Endpoint
`/accounts`

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **accounts** (array) - A list of account objects.
  - **_id** (string) - The unique identifier for the account.
  - **name** (string) - The name of the account.
  - **collectionName** (string) - The name of the associated collection.
  - **status** (string) - The account's status (e.g., `connected`, `created`).
  - **currentStatus** (string) - The current connection status.
  - **hasQR** (boolean) - Whether a QR code is available for this account.

#### Response Example
```json
{
  "ok": true,
  "accounts": [
    {
      "_id": "testaccount2",
      "name": "Test Account 2",
      "collectionName": "auth_testaccount2",
      "status": "connected",
      "currentStatus": "connected",
      "hasQR": false
    },
    {
      "_id": "mynumber",
      "name": "My WhatsApp Account",
      "status": "created",
      "currentStatus": "not_started",
      "hasQR": false
    }
  ]
}
```
```

--------------------------------

### Check Server Health using npm ping

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Verifies if the Wildcat API server is running and responsive. This is a basic health check command and takes no arguments.

```bash
npm run ping
```

--------------------------------

### Wildcat Environment Configuration (.env)

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Example .env file for configuring Wildcat application settings. Includes host, port, MongoDB connection URL, database name, and optional admin notification number and auto-connect settings.

```env
HOST=0.0.0.0
PORT=3000
MONGO_URL=mongodb://localhost:27017
DB_NAME=wildcat
ADMIN_NUMBER=1234567890@s.whatsapp.net
AUTO_CONNECT_ON_START=true
```

--------------------------------

### Tail Application Logs using npm logs:app

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Monitors the application logs in real-time. This command is invaluable for debugging and understanding the internal workings of the Wildcat application.

```bash
npm run logs:app
```

--------------------------------

### List All Accounts (Compact View) using npm accounts

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Retrieves a concise list of all managed accounts, displaying their ID, name, status, and QR code availability. This command is useful for a quick overview of existing accounts.

```bash
npm run accounts
```

--------------------------------

### Node.js Profiling Commands (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Provides commands for profiling Node.js applications to monitor performance and memory usage. It includes using the built-in `--inspect` flag for debugging and the `clinic` tool for more in-depth performance analysis.

```bash
# Memory usage
node --inspect index.js

# Performance monitoring
npm install -g clinic
clinic doctor -- node index.js
```

--------------------------------

### Get Message Media

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Retrieves the raw media file associated with a specific message. The response is the binary media content, and it can be used directly to download or display the media.

```bash
# Get media for message
curl http://localhost:3000/accounts/sales_bot/messages/3EB0C445566778899/media \
  --output downloaded_image.jpg

# Access media URL from webhook payload
# When a media message arrives, the webhook payload contains mediaUrl field
# Example: /accounts/sales_bot/messages/3EB0C445566778899/media
```

--------------------------------

### Log File Monitoring Commands (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/DEVELOPMENT.md

Shows bash commands for monitoring application logs. It includes viewing all logs in real-time using `tail -f` and filtering logs by specific types like `http.log` and `baileys.log`.

```bash
# View all logs
tail -f .logs/*.log

# Filter by type
tail -f .logs/http.log
tail -f .logs/baileys.log
```

--------------------------------

### GET /media/{id}

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Retrieves a media file directly from GridFS storage using its unique ID. The response is the binary content of the media file.

```APIDOC
## GET /media/{id}

### Description
Retrieves media file directly by its GridFS storage ID.

### Method
GET

### Endpoint
`/media/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The GridFS ID of the media file to retrieve.

### Request Example
```bash
curl http://localhost:3000/media/507f1f77bcf86cd799439011 \
  --output media_file.jpg
```

### Response
#### Success Response (200)
- **Binary media file** - The content of the requested media file.
- **Content-Type** (string) - The MIME type of the media file (e.g., `image/jpeg`).
- **Content-Length** (integer) - The size of the media file in bytes.
- **Content-Disposition** (string) - Specifies how to present the file (e.g., `inline; filename="product.jpg"`).

#### Response Example
```
# Response: Binary media file
# Content-Type: image/jpeg
# Content-Length: 245678
# Content-Disposition: inline; filename="product.jpg"
```
```

--------------------------------

### Add Webhook URL using npm webhook:add

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Registers a URL to receive webhook notifications from the Wildcat API. This allows external services to be updated about events in real-time.

```bash
npm run webhook:add <url>
```

```bash
npm run webhook:add https://webhook.site/your-unique-id
```

--------------------------------

### Registering a Webhook with Wildcat (Bash)

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/README.md

This command-line example demonstrates how to register a webhook URL with the Wildcat API. It requires the Wildcat host and port, and the URL of the webhook endpoint to be registered. The response is expected to be in JSON format.

```bash
curl -X POST http://<wildcat-host>:3000/webhooks \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-n8n-host/webhook/<id>"}'
```

--------------------------------

### Tail Baileys (WhatsApp) Logs using npm logs:baileys

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Provides real-time access to the logs generated by the Baileys WhatsApp library. This is crucial for debugging WhatsApp-specific connection and messaging issues.

```bash
npm run logs:baileys
```

--------------------------------

### Node.js CommonJS Module Export

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Illustrates the use of CommonJS module system for exporting functionality. This is the standard module system for the project, and ESM is explicitly disallowed. Uses `module.exports` to expose functions or objects.

```javascript
module.exports = {
  // exported functions or variables
}
```

--------------------------------

### List Recent Messages (Compact) using npm messages

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Retrieves a condensed list of recent messages, showing the account ID, sender, message text, and timestamp. This provides a quick view of recent communication activity.

```bash
npm run messages
```

--------------------------------

### Webhook Payload Formats (JSON)

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Defines the structure of payloads sent to registered webhooks. It includes examples for text messages, messages with media, and messages with reply context.

```javascript
// Example webhook payload received
{
  "accountId": "sales_bot",
  "messageId": "3EB0C123456789ABCDEF",
  "chatId": "1234567890@s.whatsapp.net",
  "from": "1234567890@s.whatsapp.net",
  "fromMe": false,
  "timestamp": 1705320600,
  "type": "text",
  "text": "Hello, I need help with my order",
  "hasMedia": false,
  "mediaUrl": null,
  "mediaType": null,
  "quotedMessage": null,
  "mentions": [],
  "createdAt": "2025-01-15T12:30:00.000Z"
}

// Webhook payload with media
{
  "accountId": "sales_bot",
  "messageId": "3EB0C445566778899",
  "chatId": "1234567890@s.whatsapp.net",
  "from": "1234567890@s.whatsapp.net",
  "fromMe": false,
  "timestamp": 1705320800,
  "type": "image",
  "text": "Product image",
  "hasMedia": true,
  "mediaUrl": "/accounts/sales_bot/messages/3EB0C445566778899/media",
  "mediaType": "image",
  "quotedMessage": null,
  "mentions": [],
  "createdAt": "2025-01-15T12:40:00.000Z"
}

// Webhook payload with reply context
{
  "accountId": "sales_bot",
  "messageId": "3EB0C556677889900",
  "chatId": "1234567890@s.whatsapp.net",
  "from": "1234567890@s.whatsapp.net",
  "fromMe": false,
  "timestamp": 1705321000,
  "type": "text",
  "text": "Yes, that's exactly what I need!",
  "hasMedia": false,
  "mediaUrl": null,
  "mediaType": null,
  "quotedMessage": {
    "messageId": "3EB0C123456789ORIGINAL",
    "participant": "1234567890@s.whatsapp.net",
    "text": "Would you like to see our premium options?",
    "hasMedia": false
  },
  "mentions": [],
  "createdAt": "2025-01-15T12:43:20.000Z"
}
```

--------------------------------

### Tail HTTP Request Logs using npm logs:http

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Streams HTTP request logs in real-time. This helps in monitoring API traffic and diagnosing issues related to incoming requests.

```bash
npm run logs:http
```

--------------------------------

### MongoDB Client Reuse

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Highlights the requirement to reuse a single MongoDB client instance throughout the application instead of creating new connections per request. This improves performance and resource management. Authentication state is managed in `mongoAuthState.js`.

```javascript
// In a module, initialize and export a single client instance
const { MongoClient } = require('mongodb');

const client = new MongoClient(process.env.MONGO_URL);

async function connect() {
  if (!client.topology || !client.topology.isConnected()) {
    await client.connect();
  }
  return client.db(process.env.DB_NAME);
}

module.exports = {
  connect,
  client // Export client if needed elsewhere
};
```

--------------------------------

### Create Wildcat Account via cURL

Source: https://github.com/notoriousarnav/wildcat/blob/master/README.md

Example using cURL to create a new WhatsApp account within the Wildcat server. This involves sending a POST request with account details in JSON format to the `/accounts` endpoint.

```bash
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{"id": "myaccount", "name": "My Account"}'
```

--------------------------------

### Webhook Payload Format - Media Message Example - JSON

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/API_Reference.md

Illustrates the webhook payload format for media messages, specifically an image. It includes media-related fields like mediaUrl and mediaType.

```json
{
  "accountId": "mybusiness",
  "messageId": "3EB0A12345678902",
  "chatId": "1234567890@s.whatsapp.net",
  "from": "1234567890@s.whatsapp.net",
  "fromMe": false,
  "timestamp": 1699099199,
  "type": "image",
  "text": "Check this out!",
  "hasMedia": true,
  "mediaUrl": "/accounts/mybusiness/messages/3EB0A12345678902/media",
  "mediaType": "image",
  "quotedMessage": null,
  "mentions": [],
  "createdAt": "2025-11-04T09:49:25.526Z"
}
```

--------------------------------

### Send Message using npm message:send

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Dispatches a message from a specified account to a recipient. The recipient's number must be in WhatsApp JID format (e.g., `number@s.whatsapp.net` or `groupid@g.us`). Messages with spaces or special characters should be enclosed in quotes.

```bash
npm run message:send <accountId> <to> "<message>"
```

```bash
npm run message:send mynumber 919163827035@s.whatsapp.net "Hello from CLI!"
```

```bash
npm run message:send account1 1234567890@s.whatsapp.net "Test message"
```

--------------------------------

### Get Specific Account Status using npm account:status

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Retrieves the current status of a specific account identified by its account ID. This command is essential for monitoring account health and connection status.

```bash
npm run account:status <accountId>
```

```bash
npm run account:status mynumber
```

--------------------------------

### JSDoc for Complex Functions

Source: https://github.com/notoriousarnav/wildcat/blob/master/AGENTS.md

Example of adding JSDoc comments to a complex JavaScript function. JSDoc is used for documenting functions when plain JavaScript is preferred over TypeScript. It helps describe parameters, return values, and function purpose.

```javascript
/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of a and b.
 */
function sum(a, b) {
  return a + b;
}
```

--------------------------------

### Get WhatsApp Account Status and QR Code (Bash)

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Fetches the current status of a specific WhatsApp account and its authentication QR code if available, using a GET request to /accounts/{accountId}/status. The response indicates if the account is connecting (with a QR code) or connected.

```bash
curl http://localhost:3000/accounts/sales_bot/status
```

--------------------------------

### CLI Commands for Account Management (npm)

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Provides essential command-line interface commands for managing accounts within the Wildcat project using npm scripts. This includes listing accounts, checking status, and interactive creation.

```bash
# List all accounts
npm run accounts

# Check account status
npm run account:status sales_bot

# Create account interactively
npm run account:create sales_bot "Sales Bot"
```

--------------------------------

### Create New Account using npm account:create

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Creates a new account with a specified account ID and an optional name. This command is idempotent, meaning running it multiple times with the same ID will not create duplicates. It's a fundamental step for managing new WhatsApp accounts.

```bash
npm run account:create <accountId> [name]
```

```bash
npm run account:create myaccount
```

```bash
npm run account:create myaccount "My Business Account"
```

--------------------------------

### GET /accounts/{accountId}/messages/{messageId}

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Retrieves a specific message by its ID.

```APIDOC
## GET /accounts/{accountId}/messages/{messageId}

### Description
Retrieves a specific message by its ID.

### Method
GET

### Endpoint
`/accounts/{accountId}/messages/{messageId}`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account associated with the message.
- **messageId** (string) - Required - The ID of the message to retrieve.
```

--------------------------------

### Get Message Media

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Retrieves media file associated with a specific message. Returns the raw media file.

```APIDOC
## GET /accounts/{accountId}/messages/{messageId}/media

### Description
Retrieves media file associated with a specific message. Returns the raw media file.

### Method
GET

### Endpoint
/accounts/{accountId}/messages/{messageId}/media

### Response
#### Success Response (200)
- Returns the raw media file with appropriate Content-Type header (e.g., `image/jpeg`).
- **Content-Type** (string) - The MIME type of the media.
- **Content-Length** (integer) - The size of the media file in bytes.
- **Content-Disposition** (string) - Specifies how to present the file (e.g., `inline; filename="image.jpg"`).

#### Response Example
(Binary media file, no JSON example)
```

--------------------------------

### Create WhatsApp Account Instance (Bash)

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Creates a new WhatsApp account instance using a POST request to the /accounts endpoint. Requires account ID, name, and an optional collection name for authentication state. The response includes the account details and its initial status.

```bash
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "sales_bot",
    "name": "Sales Department Bot",
    "collectionName": "auth_sales"
  }'
```

--------------------------------

### GET /accounts/:accountId/status

Source: https://github.com/notoriousarnav/wildcat/blob/master/TEST_REPORT.md

Retrieves the connection status of a specific account. Can return a QR code if authentication is in progress.

```APIDOC
## GET /accounts/:accountId/status

### Description
Fetches the connection status and related information for a given account.

### Method
GET

### Endpoint
`/accounts/:accountId/status`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account to check the status for.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **accountId** (string) - The ID of the account.
- **status** (string) - The current connection status (`not_started`, `connecting`, `qr_ready`, `connected`, `disconnected`).
- **collection** (string) - The name of the associated collection.

#### Response Example
```json
{
  "ok": true,
  "accountId": "testaccount2",
  "status": "connected",
  "collection": "auth_testaccount2"
}
```

### Possible Status Values
- `not_started` - Account created but not connected
- `connecting` - Attempting connection
- `qr_ready` - QR code available for scanning
- `connected` - Active WhatsApp connection
- `disconnected` - Connection lost
```

--------------------------------

### GET /accounts/:accountId/messages/:messageId/media

Source: https://github.com/notoriousarnav/wildcat/blob/master/TEST_REPORT.md

Retrieves media associated with a specific message. Supports streaming downloads and various media types.

```APIDOC
## GET /accounts/:accountId/messages/:messageId/media

### Description
Retrieves media content from GridFS storage for a given message.

### Method
GET

### Endpoint
`/accounts/:accountId/messages/:messageId/media`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account.
- **messageId** (string) - Required - The ID of the message containing the media.

### Request Example
```bash
curl http://localhost:3000/accounts/testaccount2/messages/ACB48E1A72B346CB454D2412CD4102A0/media
```

### Response
#### Success Response (200)
- **Content-Type** (string) - The MIME type of the media.
- **Content-Length** (integer) - The size of the media in bytes.
- **Content-Disposition** (string) - Indicates how to display the media (e.g., inline with filename).

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 40437
Content-Disposition: inline; filename="..."
```
```

--------------------------------

### Delete Account using npm account:delete

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Removes a specific account from the system, identified by its account ID. This action is irreversible and should be used with caution.

```bash
npm run account:delete <accountId>
```

```bash
npm run account:delete myaccount
```

--------------------------------

### Retrieve a Single Message using cURL

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Retrieves a specific WhatsApp message by its unique message ID. This is a GET request to the messages endpoint.

```bash
# Get message by ID
curl http://localhost:3000/accounts/sales_bot/messages/3EB0C123456789ABCDEF
```

--------------------------------

### Disconnect Account using npm account:disconnect

Source: https://github.com/notoriousarnav/wildcat/blob/master/CLI_USAGE.md

Terminates the active connection for a specified account. This is the inverse of connecting an account and is used to gracefully end a session.

```bash
npm run account:disconnect <accountId>
```

```bash
npm run account:disconnect mynumber
```

--------------------------------

### Create Account Endpoint (Shell)

Source: https://github.com/notoriousarnav/wildcat/blob/master/REPORT.md

This command creates a new account by sending a POST request to the `/accounts` endpoint with a JSON payload containing the account ID and name. It requires the `content-type` header to be set to `application/json`. The output is the server's confirmation of account creation.

```shell
curl -sS -X POST http://localhost:3000/accounts \
  -H 'content-type: application/json' \
  -d '{"id":"test","name":"Test Account"}'
```

--------------------------------

### GET /accounts/:accountId/chats/:chatId/messages

Source: https://github.com/notoriousarnav/wildcat/blob/master/TEST_REPORT.md

Retrieves messages for a specific chat, supporting pagination and filtering by timestamp. Messages are returned in reverse chronological order.

```APIDOC
## GET /accounts/:accountId/chats/:chatId/messages

### Description
Retrieves a paginated list of messages for a specific chat. Supports filtering by timestamp and returns messages in reverse chronological order. Includes pagination details such as total count and a flag indicating if more messages are available.

### Method
GET

### Endpoint
`/accounts/:accountId/chats/:chatId/messages`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The unique identifier for the account.
- **chatId** (string) - Required - The ID of the chat to retrieve messages from.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of messages to return per page.
- **offset** (integer) - Optional - The number of messages to skip (for pagination).
- **before** (integer) - Optional - Unix timestamp to filter messages before this time.
- **after** (integer) - Optional - Unix timestamp to filter messages after this time.

### Request Example
```bash
curl "http://localhost:3000/accounts/testaccount2/chats/919547400579@s.whatsapp.net/messages?limit=3"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **messages** (array) - An array of message objects.
- **pagination** (object) - Pagination details.
  - **total** (integer) - The total number of messages in the chat.
  - **limit** (integer) - The limit applied to the current request.
  - **offset** (integer) - The offset applied to the current request.
  - **hasMore** (boolean) - True if there are more messages available beyond the current page.

#### Response Example
```json
{
  "ok": true,
  "messages": [...],
  "pagination": {
    "total": 23,
    "limit": 3,
    "offset": 0,
    "hasMore": true
  }
}
```

### Use Case
Message history display, infinite scroll.
```

--------------------------------

### Create Account - Bash

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/API_Reference.md

Creates a new account using a POST request. Requires a JSON body with account ID and name.

```bash
# 1. Create account
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{"id":"mybusiness","name":"Business Account"}'
```

--------------------------------

### Check Account Status and Get QR Code - Bash

Source: https://github.com/notoriousarnav/wildcat/blob/master/docs/API_Reference.md

Retrieves the status of an account and, if not connected, provides a QR code for WhatsApp pairing. Requires the account ID.

```bash
# 2. Check status and get QR code
curl http://localhost:3000/accounts/mybusiness/status
```

--------------------------------

### Run Wildcat Docker Container with MongoDB

Source: https://github.com/notoriousarnav/wildcat/blob/master/README.md

Example of running the Wildcat Docker container, exposing port 3000, and configuring it to connect to a MongoDB instance. Environment variables are used to set host, port, MongoDB URL, database name, and auto-connect behavior.

```bash
docker run --name wildcat \
  -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e MONGO_URL="mongodb://host.docker.internal:27017" \
  -e DB_NAME=wildcat \
  -e AUTO_CONNECT_ON_START=true \
  wildcat:latest
```

--------------------------------

### List All Media Files

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Lists all media files stored in the system with optional filtering.

```APIDOC
## GET /media

### Description
Lists all media files stored in the system with optional filtering.

### Method
GET

### Endpoint
/media

#### Query Parameters
- **accountId** (string) - Optional - Filters media by account ID.
- **chatId** (string) - Optional - Filters media by chat ID.
- **messageId** (string) - Optional - Filters media by message ID.

### Response
#### Success Response (200)
- Returns an array of media objects. The exact structure of these objects is not detailed in the provided text but would typically include identifiers and possibly URLs or metadata.

#### Response Example
(The provided text does not include a JSON response example for this endpoint, only example `curl` commands.)
```

--------------------------------

### Manage Wildcat Accounts via CLI

Source: https://context7.com/notoriousarnav/wildcat/llms.txt

Commands for creating, connecting, disconnecting, and deleting Wildcat accounts using the npm CLI. These operations manage individual WhatsApp business accounts within the Wildcat system.

```bash
npm run account:create:qr sales_bot "Sales Bot"
npm run account:connect sales_bot
npm run account:disconnect sales_bot
npm run account:delete sales_bot
```