### Development Setup for OpenWA

Source: https://github.com/rmyndharis/openwa/blob/main/docs/20-community-guidelines.md

Instructions for setting up the development environment for OpenWA, including cloning the repository, installing dependencies, and starting the development server.

```bash
# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/openwa.git
cd openwa

# 3. Add upstream remote
git remote add upstream https://github.com/rmyndharis/OpenWA.git

# 4. Install dependencies
npm install

# 5. Copy environment file
cp .env.example .env

# 6. Start development
npm run dev
```

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

### Install and Run OpenWA Locally

Source: https://github.com/rmyndharis/openwa/blob/main/CONTRIBUTING.md

Commands to install dependencies, set up environment variables, and start the backend development server. The dashboard requires separate setup.

```bash
npm install
cp .env.example .env        # adjust as needed
npm run start:dev           # hot-reload, default port 2785
```

```bash
cd dashboard && npm install && npm run dev
```

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

### Minimal Setup with SQLite

Source: https://github.com/rmyndharis/openwa/blob/main/docs/README.md

Use this method for a quick local setup without Docker. It requires cloning the repository, installing dependencies, configuring environment variables, creating data directories, and running the development server.

```bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

# Install & configure
npm install
cp .env.minimal .env

# Create data directories
mkdir -p data/sessions data/media

# Run
npm run start:dev
```

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

### Start OpenWA with Local Development

Source: https://github.com/rmyndharis/openwa/blob/main/README.md

Clone the repository, install Node.js dependencies, and start the API and dashboard for local development. Configuration is auto-generated on the first run.

```bash
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
npm install
npm run dev
```

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

### SDK Initialization and Basic Usage

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/javascript/README.md

Demonstrates how to install the SDK, initialize the client with your gateway URL and API key, and perform basic operations like starting a session and sending a text message.

```APIDOC
## Install

```bash
npm install @rmyndharis/openwa
```

Requires Node.js >= 18 (relies on the global `fetch`).

## Usage

```typescript
import { OpenWAClient } from '@rmyndharis/openwa';

const client = new OpenWAClient({
  baseUrl: 'https://your-gateway.example.com',
  apiKey: 'owa_k1_…',
});

await client.sessions.start('my-session');

const result = await client.messages.sendText('my-session', {
  chatId: '628123456789@c.us',
  text: 'Hello from the OpenWA SDK!',
});
console.log(result.messageId);
```

CommonJS consumers use `require('@rmyndharis/openwa')` identically.
```

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

### Install Dependencies and Start Development Server

Source: https://github.com/rmyndharis/openwa/blob/main/dashboard/README.md

Use these npm commands to install project dependencies and launch the development server for the OpenWA dashboard. The dashboard will be accessible at http://localhost:2886.

```bash
npm install

npm run dev
```

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

### Quick Start: Initialize and Use OpenWAClient

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Initialize the OpenWAClient with your base URL and API key, then create and start a session. This example demonstrates sending a text message and closing the client.

```python
from openwa import OpenWAClient

client = OpenWAClient(
    base_url="http://localhost:2785",
    api_key="owa_k1_…",
)

# Create then start a session
client.sessions.create({"name": "my-session"})
client.sessions.start("my-session")

# Send a text message
result = client.messages.send_text("my-session", {
    "chatId": "628123456789@c.us",
    "text": "Hello from the OpenWA Python SDK!",
})
print(result["messageId"])

client.close()
```

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

### Install socket.io-client

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Install the necessary client package for real-time event handling via Socket.IO.

```bash
npm install socket.io-client
```

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

### Quickstart: Send a Text Message with OpenWA Java SDK

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/java/README.md

Initialize the OpenWA client and send a text message. Ensure you have the correct base URL and API key. The client starts a session and sends a message to a specified chat ID.

```java
import com.rmyndharis.openwa.OpenWAClient;
import com.rmyndharis.openwa.model.MessageResponse;
import com.rmyndharis.openwa.model.SendTextRequest;

OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");

client.sessions.start("my-session");

MessageResponse result = client.messages.sendText("my-session",
    SendTextRequest.builder()
        .chatId("628123456789@c.us")
        .text("Hello from the OpenWA Java SDK!")
        .build());

System.out.println(result.messageId());
```

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

### Install OpenWA SDK

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Install the SDK using npm, yarn, or pnpm. Node.js 18+ is required.

```bash
npm install @rmyndharis/openwa
# or
yarn add @rmyndharis/openwa
# or
pnpm add @rmyndharis/openwa
```

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

### Start Session & Get QR Code

Source: https://github.com/rmyndharis/openwa/blob/main/README.md

Starts an existing session and retrieves the QR code needed for WhatsApp authentication.

```APIDOC
## POST /api/sessions/{sessionId}/start

### Description
Starts a previously created session and provides a QR code for authentication.

### Method
POST

### Endpoint
/api/sessions/{sessionId}/start

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to start.

### Response
#### Success Response (200)
- **qrCode** (string) - The QR code in base64 format to be scanned by WhatsApp.

#### Response Example
```json
{
  "qrCode": "iVBORw0KGgoAAAANSUhEUgAA..."
}
```

## GET /api/sessions/{sessionId}/qr

### Description
Retrieves the QR code for an active session. This is useful if the QR code has expired or was not displayed initially.

### Method
GET

### Endpoint
/api/sessions/{sessionId}/qr

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session for which to get the QR code.
```

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

### Install Plugin from ZIP

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Install a plugin by uploading its .zip file. The upload uses multipart encoding with the field name 'file', and has a maximum size of 5 MB.

```bash
curl -X POST "$BASE/api/plugins/install" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@my-plugin.zip"
```

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

### Install plugin from URL

Source: https://github.com/rmyndharis/openwa/blob/main/docs/19-plugin-architecture.md

Installs a plugin by downloading a .zip file from a provided URL. This is protected against Server-Side Request Forgery (SSRF).

```APIDOC
## POST /plugins/install-url

### Description
Install a plugin by downloading a `.zip` file from a URL. This endpoint is protected against SSRF attacks.

### Method
POST

### Endpoint
/plugins/install-url

### Parameters
#### Request Body
- **url** (string) - Required - The URL to download the plugin zip file from.
```

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

### Start Production Docker Compose and Monitor Logs

Source: https://github.com/rmyndharis/openwa/blob/main/docs/09-testing-strategy.md

Commands to build and start the production Docker environment, and then stream the logs for the openwa-api service.

```bash
docker compose up -d --build
docker compose logs -f openwa-api
```

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

### Install plugin from uploaded zip

Source: https://github.com/rmyndharis/openwa/blob/main/docs/19-plugin-architecture.md

Installs a plugin by uploading a .zip file. The upload is limited to 5 MB.

```APIDOC
## POST /plugins/install

### Description
Install a plugin from an uploaded `.zip` file. The upload uses `multipart/form-data` with the field name `file` and has a maximum size of 5 MB.

### Method
POST

### Endpoint
/plugins/install

### Parameters
#### Request Body
- **file** (file) - Required - The plugin zip file to upload.
```

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

### Install Plugin from URL

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Install a plugin by providing a URL to its .zip file. This endpoint is protected against Server-Side Request Forgery (SSRF) attacks.

```bash
curl -X POST "$BASE/api/plugins/install-url" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://github.com/openwa-plugins/chat-flow/releases/download/v1.0.0/chat-flow.zip" }'
```

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

### Start a Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Use the `start` method with a `session_id` to initiate a session connection.

```python
client.sessions.start(session_id) -> SessionResponse
```

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

### Start Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/README.md

Starts an existing session.

```APIDOC
## POST /api/sessions/{sessionId}/start

### Description
Starts an existing session.

### Method
POST

### Endpoint
/api/sessions/{sessionId}/start

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to start.

### Headers
- **X-API-Key** (string) - Required - Your API key.
```

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

### POST /api/plugins/install-url

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Install a plugin by downloading its .zip from a URL (SSRF-guarded).

```APIDOC
## POST /api/plugins/install-url

### Description
Install a plugin by downloading its .zip from a URL (SSRF-guarded).

### Method
POST

### Endpoint
/api/plugins/install-url

### Request Body
- **url** (string) - Required - The URL to download the plugin zip file from.
```

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

### Start Session and Get QR Code with OpenWA API

Source: https://github.com/rmyndharis/openwa/blob/main/README.md

Start an existing session and retrieve the QR code for WhatsApp scanning. Ensure you replace {sessionId} with the actual session ID.

```bash
# Start the session
curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
  -H "X-API-Key: YOUR_API_KEY"

# Get QR code (scan with WhatsApp)
curl http://localhost:2785/api/sessions/{sessionId}/qr \
  -H "X-API-Key: YOUR_API_KEY"
```

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

### Start Development Docker Compose

Source: https://github.com/rmyndharis/openwa/blob/main/docs/09-testing-strategy.md

Commands to start the development Docker environment and perform a readiness check on the API.

```bash
docker compose -f docker-compose.dev.yml up -d --build
curl -f http://localhost:2785/api/health/ready
```

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

### Example Usage

Source: https://github.com/rmyndharis/openwa/blob/main/docs/examples/chat-history-limits.md

Example of how to use curl to fetch the maximum allowed live history window.

```APIDOC
## Example

```bash
curl -H "X-API-Key: $API_KEY" \
  "http://localhost:2785/api/sessions/default/messages/628123456789@c.us/history?limit=100"
```

Use `limit=100` when you want the maximum single-request live history window currently allowed by OpenWA.
```

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

### Docker Setup (API + Dashboard)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/README.md

This option uses Docker Compose for a streamlined setup, running the API and Dashboard in a single container. It simplifies dependency management and deployment.

```bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

# Start services
docker compose up -d
```

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

### Start OpenWA with Docker Compose

Source: https://github.com/rmyndharis/openwa/blob/main/README.md

Clone the repository and start the OpenWA development environment using Docker Compose. Access the API and dashboard via the specified local ports.

```bash
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d
```

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

### Enable Plugin

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Activate a previously installed plugin.

```bash
curl -X POST "$BASE/api/plugins/chat-flow/enable" \
  -H "X-API-Key: $API_KEY"
```

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

### Start a Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/examples/session-phone-number-pairing.md

Starts a previously created OpenWA session. This must be done before requesting a pairing code.

```bash
curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
  -H "X-API-Key: $API_KEY"
```

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

### client.sessions.start

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Starts (connects) a session.

```APIDOC
## client.sessions.start

### Description
Starts (connects) a session.

### Method
POST

### Endpoint
/api/sessions/{session_id}/start

### Parameters
#### Path Parameters
- **session_id** (str) - Required - The ID of the session to start.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **session** (SessionResponse) - The details of the started session.

#### Response Example
```json
{
  "session": {
    "id": "session-id-1",
    "name": "my-session-1",
    "status": "running"
  }
}
```
```

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

### Quick Start with OpenWA SDK

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Initialize the client, start a session, and send a text message. The sendText method resolves to a MessageResponse object.

```typescript
import { OpenWAClient } from '@rmyndharis/openwa';

const client = new OpenWAClient({
  baseUrl: 'http://localhost:2785',
  apiKey: 'owa_k1_…',
});

async function main() {
  // Start a session and bring the WhatsApp connection up.
  await client.sessions.start('my-session');

  // Send a text message.
  const result = await client.messages.sendText('my-session', {
    chatId: '628123456789@c.us',
    text: 'Hello from the OpenWA SDK!',
  });

  console.log(result.messageId); // -> the WhatsApp message id
}

main();
```

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

### Start OpenWA API and Dashboard in Development Mode

Source: https://github.com/rmyndharis/openwa/blob/main/docs/08-development-guidelines.md

Run the npm script to start the API and dashboard in development mode. This will generate a .env file with default configurations if one doesn't exist.

```bash
npm run dev
```

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

### Install OpenWA SDK for JavaScript/TypeScript

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/README.md

Install the OpenWA SDK using npm. This is the first step to using the SDK in your JavaScript or TypeScript project.

```bash
npm install @rmyndharis/openwa
```

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

### SemVer Version Numbering Examples

Source: https://github.com/rmyndharis/openwa/blob/main/docs/15-project-roadmap.md

Provides examples of version numbers and their corresponding project milestones or feature sets.

```plaintext
0.0.1 - Initial MVP
0.0.2 - Production Ready (Multi-session, Dashboard)
0.1.0 - Initial Stable Release (Full features)
0.1.1 - Bug fix for QR timeout
0.2.0 - i18n, Real-time Chats, Webhook Delivery-state & Hardening
0.3.0 - SDK & Developer Tools
1.0.0 - Enterprise Ready
2.0.0 - Breaking API changes
```

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

### Install OpenWA SDK for PHP

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/README.md

Install the OpenWA PHP SDK using Composer. This command adds the library as a dependency to your PHP project.

```bash
composer require rmyndharis/openwa
```

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

### Install OpenWA SDK for Python

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/README.md

Install the OpenWA Python SDK using pip. This command adds the necessary library to your Python environment.

```bash
pip install rmyndharis-openwa
```

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

### List all plugins

Source: https://github.com/rmyndharis/openwa/blob/main/docs/19-plugin-architecture.md

Retrieves a list of all installed plugins.

```APIDOC
## GET /plugins

### Description
List all installed plugins.

### Method
GET

### Endpoint
/plugins
```

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

### Configuration-driven Example (Environment Variable)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/03-system-architecture.md

Shows how backend selection is driven by environment variables, such as specifying the storage type.

```bash
STORAGE_TYPE=s3,
ENGINE_TYPE=baileys
```

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

### GET /api/plugins/catalog

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

List the remote plugin catalog with install state.

```APIDOC
## GET /api/plugins/catalog

### Description
List the remote plugin catalog with install state.

### Method
GET

### Endpoint
/api/plugins/catalog
```

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

### OpenWA PHP SDK Quick Start

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Initialize the client with your base URL and API key, then use it to manage sessions and send messages. Requires vendor/autoload.php.

```php
<?php
require 'vendor/autoload.php';

use OpenWA\Client;

$client = new Client([
    'baseUrl' => 'http://localhost:2785',
    'apiKey'  => 'owa_k1_…',
]);

$client->sessions->start('my-session');

$result = $client->messages->sendText('my-session', [
    'chatId' => '628123456789@c.us',
    'text'   => 'Hello from the OpenWA PHP SDK!',
]);

echo $result['messageId'];

```

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

### Get a single plugin

Source: https://github.com/rmyndharis/openwa/blob/main/docs/19-plugin-architecture.md

Retrieves details for a specific installed plugin.

```APIDOC
## GET /plugins/:id

### Description
Get a single plugin by its ID.

### Method
GET

### Endpoint
/plugins/:id
```

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

### Example Environment Variables (.env.example)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/10-devops-infrastructure.md

This file provides a template for environment variables used to configure the application. It includes options for database, media storage, cache, queue, WhatsApp engine, security, webhook, and rate limiting.

```bash
# .env.example

# ===========================================
# APPLICATION
# ===========================================
NODE_ENV=production
PORT=2785
API_PREFIX=/api
LOG_LEVEL=info
LOG_FORMAT=json

# ===========================================
# DATABASE (choose one)
# ===========================================
# Option 1: SQLite (for minimal deployments)
DATABASE_TYPE=sqlite
DATABASE_SQLITE_PATH=./data/openwa.db

# Option 2: PostgreSQL (for production)
# DATABASE_TYPE=postgres
# DATABASE_URL=postgresql://user:pass@localhost:5432/openwa
# DATABASE_POOL_MAX=20
# DATABASE_SSL=false

# ===========================================
# MEDIA STORAGE (choose one)
# ===========================================
# Option 1: Local filesystem (default)
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./media
STORAGE_LOCAL_BASE_URL=/media

# Option 2: S3
# STORAGE_TYPE=s3
# STORAGE_S3_BUCKET=openwa-media
# STORAGE_S3_REGION=ap-southeast-1
# STORAGE_S3_ACCESS_KEY_ID=your-access-key
# STORAGE_S3_SECRET_ACCESS_KEY=your-secret-key

# Option 3: MinIO (S3-compatible)
# STORAGE_TYPE=minio
# STORAGE_S3_BUCKET=openwa-media
# STORAGE_S3_ENDPOINT=http://minio:9000
# STORAGE_S3_ACCESS_KEY_ID=minioadmin
# STORAGE_S3_SECRET_ACCESS_KEY=minioadmin
# STORAGE_S3_FORCE_PATH_STYLE=true

# ===========================================
# CACHE & QUEUE (choose one)
# ===========================================
# Option 1: In-Memory (for single instance)
CACHE_TYPE=memory
CACHE_TTL=300
CACHE_MAX=1000

# Option 2: Redis (for multi-instance / production)
# CACHE_TYPE=redis
# REDIS_URL=redis://localhost:6379

# ===========================================
# WHATSAPP ENGINE
# ===========================================
ENGINE_TYPE=whatsapp-web.js
# ENGINE_TYPE=baileys
# ENGINE_TYPE=baileys   # whatsapp-web.js (default) | baileys; omit to use the dashboard selection

# Session
SESSION_DATA_PATH=./.wwebjs_auth

# Puppeteer (for whatsapp-web.js)
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
PUPPETEER_HEADLESS=true
PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox

# ===========================================
# SECURITY
# ===========================================
# Generate with: openssl rand -base64 32
API_MASTER_KEY=your-master-api-key
# Optional HMAC pepper so a DB leak alone can't precompute key hashes
API_KEY_PEPPER=optional-key-hashing-pepper

# ===========================================
# WEBHOOK
# ===========================================
WEBHOOK_TIMEOUT=30000
WEBHOOK_RETRY_COUNT=3
WEBHOOK_RETRY_DELAY=5000

# ===========================================
# RATE LIMITING
# ===========================================
# Three global per-IP windows (short/medium/long); defaults shown
RATE_LIMIT_MEDIUM_TTL=60000
RATE_LIMIT_MEDIUM_LIMIT=100

```

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

### Sessions Resource

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Methods for managing chat sessions, including listing, getting, creating, deleting, starting, stopping, and force-killing sessions, as well as managing QR codes and pairing.

```APIDOC
#### `sessions`

| Method | Signature | Description |
| --- | --- | --- |
| `list` | `list(): array` | List all sessions. |
| `get` | `get(string $id): array` | Get one session. |
| `create` | `create(array $body): array` | Create a session (`$body['name']` required). |
| `delete` | `delete(string $id): void` | Delete a session. |
| `start` | `start(string $id): array` | Start a session. |
| `stop` | `stop(string $id): array` | Stop a session. |
| `forceKill` | `forceKill(string $id): array` | Force-kill a session. |
| `getQrCode` | `getQrCode(string $id): array` | Fetch the current QR code. |
| `requestPairingCode` | `requestPairingCode(string $id, array $body): array` | Request a phone-pairing code. |
| `stats` | `stats(): array` | `GET /api/sessions/stats/overview`. |
```

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

### v0.1 to v0.2 Migration Script

Source: https://github.com/rmyndharis/openwa/blob/main/docs/14-migration-guide.md

Automates the upgrade from OpenWA v0.1.x to v0.2.x. It includes steps for backing up data, stopping the current service, running database migrations, updating configuration files, and starting the new version. Ensure Docker is installed and running.

```bash
#!/bin/bash
# upgrade-v01-to-v02.sh

set -e

echo "🚀 Upgrading OpenWA v0.1.x → v0.2.x"

# 1. Backup
echo "📦 Creating backup..."
BACKUP_DIR="./backups/v01-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r ./data "$BACKUP_DIR/"
cp .env "$BACKUP_DIR/"

# 2. Stop current version
echo "⏹️ Stopping v0.1..."
docker compose down

# 3. Run database migrations
echo "🔄 Running migrations..."
docker run --rm \
  -v $(pwd)/data:/app/data \
  -e DATABASE_URL=sqlite:///app/data/openwa.db \
  ghcr.io/rmyndharis/openwa:0.2.0 \
  npm run migration:run:prod   # the prod image strips ts-node/TS source — use :prod

# 4. Migrate configuration
echo "⚙️ Migrating configuration..."
cat > .env.new << 'EOF'
# OpenWA v0.2.x Configuration

# Database (unchanged if using SQLite)
DATABASE_ADAPTER=sqlite
DATABASE_URL=sqlite:./data/openwa.db

# New in v0.2: API Key Authentication
API_KEY_ENABLED=true
# Generate with: openssl rand -hex 32
API_KEY=your-generated-api-key

# Webhook (now managed via API, but can set default)
DEFAULT_WEBHOOK_URL=${WEBHOOK_URL:-}

# Other settings migrated from v0.1
NODE_ENV=${NODE_ENV:-production}
PORT=${PORT:-3000}
LOG_LEVEL=${LOG_LEVEL:-info}
EOF

# Merge with existing .env
source .env
envsubst < .env.new > .env.migrated
mv .env.migrated .env
rm .env.new

# 5. Start new version
echo "▶️ Starting v0.2..."
docker compose pull
docker compose up -d

# 6. Wait for health
echo "⏳ Waiting for health check..."
sleep 10
curl -f http://localhost:2785/health || exit 1

# 7. Create API key for existing integrations
echo "🔑 Creating API key..."
docker exec openwa npm run cli -- create-api-key --name "migrated-key"

echo "✅ Upgrade complete!"
echo ""
echo "⚠️ IMPORTANT: Update your API clients:"
echo "  - Change /api/session to /api/sessions"
echo "  - Change /api/send to /api/sessions/{id}/messages"
echo "  - Add X-API-Key header to all requests"

```

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

### OpenWAClient Initialization and Usage

Source: https://github.com/rmyndharis/openwa/blob/main/sdk/python/README.md

Demonstrates how to initialize the OpenWAClient with a base URL and API key, start a session, and send a text message. It also shows the client can be used as a context manager.

```APIDOC
## OpenWAClient Initialization and Usage

### Description
Initializes the `OpenWAClient` with your gateway's base URL and API key. Shows how to start a session and send a text message. The client can also be used as a context manager for automatic connection closing.

### Method
Instantiation and method calls on `OpenWAClient`.

### Endpoint
N/A (SDK usage)

### Parameters
#### Initialization Parameters
- **base_url** (string) - Required - The base URL of your OpenWA gateway.
- **api_key** (string) - Required - Your OpenWA API key.
- **transport** (httpx.Transport) - Optional - An httpx transport for testing.

#### Session Management
- **client.sessions.start(session_name: str)**

#### Messaging
- **client.messages.send_text(session_name: str, message_data: dict)**
  - **message_data** (dict) - Required - Dictionary containing message details.
    - **chatId** (string) - Required - The chat ID to send the message to.
    - **text** (string) - Required - The text content of the message.

### Request Example
```python
from openwa import OpenWAClient

# Using the client directly
client = OpenWAClient(
    base_url="https://your-gateway.example.com",
    api_key="owa_k1_…",
)
client.sessions.start("my-session")
result = client.messages.send_text("my-session", {
    "chatId": "628123456789@c.us",
    "text": "Hello from the OpenWA Python SDK!",
})
print(result["messageId"])

# Using the client as a context manager
with OpenWAClient(base_url="…", api_key="…") as client:
    client.messages.send_text("my-session", {"chatId": "…@c.us", "text": "hi"})
```

### Response
#### Success Response
- **messageId** (string) - The ID of the sent message.
```

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

### Start a Session with cURL

Source: https://github.com/rmyndharis/openwa/blob/main/docs/README.md

This cURL command starts an existing session. Replace `{sessionId}` with the ID of the session you wish to start.

```bash
# Start the session
curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
  -H "X-API-Key: your-api-key"
```

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

### Deployment Produksi Full Stack (PostgreSQL, Redis, MinIO)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/DOCKER_ID.md

Jalankan perintah ini untuk deployment produksi skala enterprise yang mencakup PostgreSQL, Redis, dan penyimpanan S3 MinIO.

```bash
docker compose --profile full up -d
```

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

### Manual n8n Node Installation

Source: https://github.com/rmyndharis/openwa/blob/main/docs/22-n8n-integration.md

Install the OpenWA n8n nodes manually by navigating to the n8n nodes directory and running npm install.

```bash
cd ~/.n8n/nodes
npm install @rmyndharis/n8n-nodes-openwa
```

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

### Clone and Install OpenWA Dependencies

Source: https://github.com/rmyndharis/openwa/blob/main/docs/08-development-guidelines.md

Clone the repository and install project dependencies using npm. This command also installs dependencies for the dashboard.

```bash
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

npm install
```

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

### GET /api/plugins/:id

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Get a single plugin by id.

```APIDOC
## GET /api/plugins/:id

### Description
Get a single plugin by id.

### Method
GET

### Endpoint
/api/plugins/:id

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

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

### Start a session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Starts a session and initializes its connection. Requires OPERATOR role.

```APIDOC
## POST /api/sessions/:id/start

### Description
Start a session and initialize the connection (OPERATOR).

### Method
POST

### Endpoint
/api/sessions/:id/start

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

### Request Example
```bash
curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/start" \
  -H "X-API-Key: $API_KEY"
```
```

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

### Build and Run Application

Source: https://github.com/rmyndharis/openwa/blob/main/docs/09-testing-strategy.md

Commands to build all project assets and run the application from the distribution directory.

```bash
npm run build:all
node dist/main
```

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

### Start the Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/examples/session-phone-number-pairing.md

Starts an existing OpenWA session. This must be done before requesting a pairing code.

```APIDOC
## POST /api/sessions/{sessionId}/start

### Description
Starts a previously created OpenWA session.

### Method
POST

### Endpoint
/api/sessions/{sessionId}/start

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to start.
```

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

### Deployment Produksi Menengah (PostgreSQL)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/DOCKER_ID.md

Gunakan perintah ini untuk deployment produksi dengan profil PostgreSQL, yang menawarkan keandalan data lebih tinggi.

```bash
docker compose --profile postgres up -d
```

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

### Zero Code Changes Example

Source: https://github.com/rmyndharis/openwa/blob/main/docs/03-system-architecture.md

Illustrates the 'Zero Code Changes' principle by indicating that switching backends only requires changing the environment configuration and restarting the application.

```bash
Change .env,
restart
```

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

### Get a Specific Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

Use the `get` method with a `session_id` to retrieve details for a specific session.

```python
client.sessions.get(session_id) -> SessionResponse
```

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

### Salin File Environment

Source: https://github.com/rmyndharis/openwa/blob/main/docs/DOCKER_ID.md

Salin file contoh .env ke .env untuk konfigurasi produksi. Pastikan untuk mengubah kunci keamanan dan sandi database.

```bash
cp .env.example .env
```

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

### Client Configuration

Source: https://github.com/rmyndharis/openwa/blob/main/docs/18-sdk-design.md

The Client constructor accepts a configuration array for setting up the SDK.

```APIDOC
## Client Configuration

The constructor takes a single associative `$config` array:

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `baseUrl` | `string` | — (**required**) | API base URL, e.g. `http://localhost:2785`. A trailing `/` is stripped; any path prefix (e.g. `/v1` behind a proxy) is preserved. |
| `apiKey` | `string` | — (**required**) | Sent as the `X-API-Key` header on every request. |
| `timeout` | `float` | `30.0` | Per-request timeout in seconds. |
| `httpClient` | `?
GuzzleHttp
ClientInterface` | `null` | Inject a Guzzle client (e.g. one built on a `MockHandler`) for testing or middleware. When `null`, a default Guzzle client is created with the configured timeout. |
| `defaultHeaders` | `array<string,string>` | `[]` | Extra headers applied on every request, **under** the SDK's auth/JSON headers (which always win). |

Missing `baseUrl` or `apiKey` throws `OpenWA\Exceptions\OpenWAException` from the constructor.
```

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

### Update an installed plugin

Source: https://github.com/rmyndharis/openwa/blob/main/docs/19-plugin-architecture.md

Updates an installed plugin in place using a URL to the new version. Configuration and enabled state are preserved.

```APIDOC
## POST /plugins/:id/update

### Description
Update an installed plugin in place from a URL. This operation preserves the plugin's configuration and enabled state.

### Method
POST

### Endpoint
/plugins/:id/update

### Parameters
#### Request Body
- **url** (string) - Required - The URL to download the new plugin version from.
```

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

### Unit Test Example

Source: https://github.com/rmyndharis/openwa/blob/main/docs/08-development-guidelines.md

Example of a unit test for session reconnection configuration. It validates that reconnect settings are kept finite and bounded.

```typescript
// src/modules/session/reconnect-config.spec.ts
import { resolveReconnectConfig } from './session.service';

describe('resolveReconnectConfig', () => {
  it('keeps reconnect settings finite and bounded', () => {
    expect(resolveReconnectConfig({ maxReconnectAttempts: 'bad', reconnectBaseDelay: -1 })).toEqual({
      maxAttempts: 5,
      baseDelay: 1000,
    });
  });
});
```

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

### Conventional Commit Message Examples

Source: https://github.com/rmyndharis/openwa/blob/main/docs/20-community-guidelines.md

Illustrative examples of commit messages following the Conventional Commits specification for various types of changes.

```text
feat(sessions): add support for multiple proxy configurations

fix(webhook): resolve timeout issue on slow connections

docs(api): update message endpoint documentation

refactor(database): migrate to TypeORM repository pattern
```

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

### Deployment Produksi Minimalis (SQLite)

Source: https://github.com/rmyndharis/openwa/blob/main/docs/DOCKER_ID.md

Jalankan perintah ini untuk deployment produksi minimalis yang cocok untuk server dengan resource kecil, menggunakan SQLite.

```bash
docker compose up -d
```

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

### Build OpenWA n8n Node from Source

Source: https://github.com/rmyndharis/openwa/blob/main/docs/22-n8n-integration.md

Clone the repository, install dependencies, and build the project. This is the first step for contributing to or customizing the OpenWA n8n node.

```bash
git clone https://github.com/rmyndharis/OpenWA-n8n.git
cd OpenWA-n8n
npm install
npm run build
```

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

### Setup Webhook

Source: https://github.com/rmyndharis/openwa/blob/main/README.md

Configures a webhook URL to receive real-time event notifications from a session.

```APIDOC
## POST /api/sessions/{sessionId}/webhooks

### Description
Sets up a webhook to receive event notifications for a specific session.

### Method
POST

### Endpoint
/api/sessions/{sessionId}/webhooks

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to configure webhooks for.

#### Request Body
- **url** (string) - Required - The URL to send webhook notifications to.
- **events** (array of strings) - Required - A list of events to subscribe to (e.g., `["message.received", "session.status"]`).
- **secret** (string) - Optional - A secret key for HMAC signature verification.
- **filters** (object) - Optional - Smart filters to control when webhooks are fired. See API specification for full schema.

### Request Example
```json
{
  "url": "https://your-server.com/webhook",
  "events": ["message.received", "session.status"],
  "secret": "your-hmac-secret"
}
```
```

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

### Standard Profile Configuration

Source: https://github.com/rmyndharis/openwa/blob/main/docs/03-system-architecture.md

Example .env file for the Standard deployment profile. It configures PostgreSQL for the database, local storage, and enables Redis for caching with default host and port.

```bash
# Database (Postgres uses discrete host/port/credentials, not a single URL)
DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=openwa
DATABASE_USERNAME=openwa
DATABASE_PASSWORD=password

# Storage
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./data/media

# Cache
REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6379
```

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

### Start Session

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Initiate a connection for a specific session. Requires an OPERATOR role API key.

```bash
curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/start" \
  -H "X-API-Key: $API_KEY"
```

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

### Update Installed Plugin

Source: https://github.com/rmyndharis/openwa/blob/main/docs/07-api-collection.md

Update an installed plugin by providing a URL to the plugin's zip archive. Ensure the URL is accessible and the archive contains a valid plugin.

```bash
curl -X POST "$BASE/api/plugins/chat-flow/update" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/plugins/chat-flow-1.1.0.zip" }'
```

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

### Minimal Profile Configuration

Source: https://github.com/rmyndharis/openwa/blob/main/docs/03-system-architecture.md

Example .env file for the Minimal deployment profile. It configures SQLite for the database, local storage, and explicitly disables Redis for caching.

```bash
# Database
DATABASE_TYPE=sqlite
DATABASE_NAME=./data/openwa.sqlite

# Storage
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./data/media

# Cache: omit / leave Redis disabled -> the cache layer no-ops (no in-memory cache)
REDIS_ENABLED=false
```

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

### Configure Webhook Settings

Source: https://github.com/rmyndharis/openwa/blob/main/docs/12-troubleshooting-faq.md

Example webhook configuration in YAML format, including URL, events to listen for, retry settings, timeout, and custom headers.

```yaml
# Webhook configuration
webhook:
  url: https://your-server.com/webhook
  events:
    - message.received
    - message.ack
    - session.status
  retry:
    max_attempts: 3
    delay: 5000
  timeout: 30000
  headers:
    Authorization: "Bearer your-token"
```

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

### E2E Test Example

Source: https://github.com/rmyndharis/openwa/blob/main/docs/08-development-guidelines.md

Example of an end-to-end test for the application's health endpoint. It verifies that the health status is returned correctly without requiring an API key.

```typescript
// test/app.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';

describe('App (e2e)', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  describe('GET /api/health', () => {
    it('returns health status without an API key', () => {
      return request(app.getHttpServer())
        .get('/api/health')
        .expect(200)
        .expect((res) => {
          expect(res.body.status).toBe('ok');
        });
    });
  });
});
```