@adens/openwa 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-27
+
+### Added
+- Initial release of OpenWA CLI package
+- Self-hosted OpenWA dashboard running locally
+- WhatsApp integration via whatsapp-web.js
+- CLI command entry point (`openwa` command)
+- Express.js backend server with Socket.IO real-time communication
+- Next.js frontend dashboard with React UI
+- Prisma ORM for database management
+- User authentication with JWT and bcrypt password hashing
+- QR code generation for WhatsApp authentication
+- File upload support with Multer
+- Tailwind CSS styling for responsive design
+- Zustand state management
+- MIT License
+
+### Features
+- Local CLI-based dashboard deployment
+- Real-time WhatsApp message handling
+- Database schema management with Prisma
+- Development and production modes
+- Node.js 20+ compatibility
+
+### Documentation
+- Comprehensive README with setup instructions
+- API documentation and examples
+- Contributing guidelines
+- MIT license file
+
+[0.1.0]: https://github.com/asepindrak/openwa/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 asepindrak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+<p align="center">
+  <img src="./logo-long.png" alt="OpenWA" width="320" />
+</p>
+
+# OpenWA
+
+OpenWA is a self-hosted WhatsApp workspace that ships as a CLI package. It combines a Next.js dashboard, an Express API, Prisma-backed data access, Socket.IO realtime updates, media uploads, and runtime API documentation in a single local-first package.
+
+OpenWA is also designed to be **AI-agent-ready**. The runtime exposes agent-friendly documentation, machine-readable OpenAPI output, and API key authentication so AI agents and automation tools can discover capabilities and interact with the workspace without reverse-engineering the app.
+
+## Disclaimer
+
+OpenWA is an independent open source project. It is **not** an official WhatsApp product and is **not** affiliated with, endorsed by, or sponsored by Meta or WhatsApp.
+
+If you use OpenWA with WhatsApp, make sure your usage complies with the terms, policies, and legal requirements that apply in your environment.
+
+## Features
+
+- Dashboard authentication for register, login, and workspace access.
+- Workspace bootstrap endpoint for loading the current user, sessions, chats, active chat, and initial messages.
+- Multi-session WhatsApp management with session creation, connect, disconnect, and QR pairing.
+- Contact and chat browsing with search and chat opening from contacts.
+- Message APIs for listing, searching, sending, forwarding, and deleting messages.
+- Multipart media upload flow with `mediaFileId` support for outbound media messages.
+- Runtime docs endpoints for Swagger UI, OpenAPI JSON, agent README, health checks, and version metadata.
+- Dual authentication model:
+  - JWT bearer auth for dashboard users.
+  - API key auth for agents and external integrations.
+
+## Tech stack
+
+- Node.js 20+
+- Next.js 15
+- React 19
+- Express
+- Prisma
+- Socket.IO
+- `whatsapp-web.js`
+
+## Acknowledgements
+
+Special thanks to [`whatsapp-web.js`](https://wwebjs.dev/). OpenWA builds on top of that excellent open source project for WhatsApp Web integration.
+
+If you find this project useful, please also support and star the `whatsapp-web.js` project.
+
+## Getting started
+
+Install OpenWA globally:
+
+```bash
+npm i -g @adens/openwa
+```
+
+Run OpenWA:
+
+```bash
+openwa
+```
+
+When OpenWA starts, it launches the local frontend and backend runtime and automatically opens your browser to the OpenWA frontend dashboard by default.
+
+If you are working on this repository locally instead of using the published CLI package:
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## Default runtime
+
+By default, OpenWA starts two local services:
+
+- Frontend dashboard: `http://localhost:55111`
+- Backend API: `http://localhost:55222`
+
+Important runtime endpoints such as docs, health, and version are also proxied through the frontend URL for convenience.
+
+## Environment configuration
+
+OpenWA reads `.env` from the repository root. These are the runtime variables currently used by the app:
+
+```env
+HOST=127.0.0.1
+FE_PORT=55111
+BE_PORT=55222
+OPENWA_FRONTEND_URL=http://localhost:55111
+OPENWA_BACKEND_URL=http://localhost:55222
+OPENWA_JWT_SECRET=openwa-local-dev-secret
+OPENWA_AUTO_OPEN=true
+OPENWA_USE_WWEBJS=true
+OPENWA_ALLOW_MOCK=false
+```
+
+Notes:
+
+- Set `OPENWA_AUTO_OPEN=false` to disable automatic browser opening.
+- Set `OPENWA_USE_WWEBJS=false` to disable the WhatsApp Web adapter.
+- Set `OPENWA_ALLOW_MOCK=true` to allow the mock adapter when needed.
+
+## Typical usage flow
+
+1. Start OpenWA.
+2. Open the dashboard at `http://localhost:55111`.
+3. Register the first user or log in.
+4. Create a new WhatsApp session from the dashboard.
+5. Connect the session to generate a QR code.
+6. Pair the device and wait for the workspace to sync chats and contacts.
+7. Send text or media from the dashboard or the HTTP API.
+8. Create an API key from **Settings → API Access** for agents or external integrations.
+
+## Runtime documentation
+
+OpenWA exposes runtime documentation directly from the app:
+
+- Swagger UI: `GET /docs`
+- OpenAPI JSON: `GET /docs/json`
+- Agent guide markdown: `GET /docs/readme`
+- Health check: `GET /health`
+- Version: `GET /version`
+- Backend health alias: `GET /api/health`
+
+If you are building an agent or automation client, prefer the frontend URL as the base URL because the main runtime metadata endpoints are already proxied there.
+
+This makes OpenWA a strong fit for AI agents: an agent can read `/docs/readme`, fetch `/docs/json`, authenticate with an API key, and immediately start working with chats, contacts, sessions, and messages through a documented API surface.
+
+## API summary
+
+### Auth
+
+- `POST /api/auth/register`
+- `POST /api/auth/login`
+- `GET /api/auth/me`
+
+These endpoints are intended for dashboard users. External agents that already have an API key normally do not need to use dashboard login flows.
+
+### API keys
+
+- `GET /api/api-keys`
+- `POST /api/api-keys`
+- `DELETE /api/api-keys/{apiKeyId}`
+
+API key management requires dashboard JWT authentication.
+
+### Workspace
+
+- `GET /api/bootstrap`
+
+Returns the initial workspace payload, including the current user, sessions, chats, active chat, initial message batch, and pagination metadata.
+
+### Sessions
+
+- `GET /api/sessions`
+- `POST /api/sessions`
+- `POST /api/sessions/{sessionId}/connect`
+- `POST /api/sessions/{sessionId}/disconnect`
+
+### Chats and contacts
+
+- `GET /api/chats`
+- `GET /api/contacts`
+- `POST /api/contacts/{contactId}/open`
+
+`/api/chats` and `/api/contacts` support `sessionId` and `q` query filters.
+
+### Messages
+
+- `GET /api/chats/{chatId}/messages`
+- `POST /api/chats/{chatId}/messages/send`
+- `DELETE /api/messages/{messageId}`
+- `POST /api/messages/{messageId}/forward`
+
+`GET /api/chats/{chatId}/messages` supports:
+
+- `take`
+- `before`
+- `search`
+
+### Media
+
+- `POST /api/media`
+
+Upload a file first, then use the returned `mediaFileId` when calling the send message endpoint.
+
+## API authentication
+
+OpenWA supports two main authentication modes.
+
+### JWT bearer
+
+```http
+Authorization: Bearer <jwt-token>
+```
+
+Used by the dashboard after login or registration.
+
+### API key
+
+```http
+X-API-Key: <api-key>
+```
+
+or:
+
+```http
+Authorization: Bearer <api-key>
+```
+
+Recommended for agents, automation, and external integrations.
+
+## API examples
+
+List chats:
+
+```bash
+curl -H "X-API-Key: <api-key>" http://localhost:55111/api/chats
+```
+
+Read messages for a chat:
+
+```bash
+curl -H "X-API-Key: <api-key>" http://localhost:55111/api/chats/<chatId>/messages
+```
+
+Send a text message:
+
+```bash
+curl -X POST http://localhost:55111/api/chats/<chatId>/messages/send \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: <api-key>" \
+  -d "{\"body\":\"Hello from OpenWA\",\"type\":\"text\"}"
+```
+
+Upload media:
+
+```bash
+curl -X POST http://localhost:55111/api/media \
+  -H "X-API-Key: <api-key>" \
+  -F "file=@./example.png"
+```
+
+## Project structure
+
+- `bin/` - CLI entrypoint
+- `server/` - backend runtime, OpenAPI docs, auth, sessions, chats, media, and sockets
+- `web/` - Next.js dashboard
+- `prisma/` - database schema
+- `storage/` - runtime storage and generated files
+
+## Development
+
+For repository-based local development:
+
+1. Install dependencies with `npm install`.
+2. Configure `.env` if you need non-default ports or runtime behavior.
+3. Run `npm run dev` for development mode.
+4. Run `npm run build` before shipping production changes.
+
+If you are working on API-facing features, validate them against:
+
+- `server/express/openapi.js`
+- `/docs`
+- `/docs/json`
+- `/docs/readme`
+
+## Contributing
+
+Contributions are welcome.
+
+If you want to contribute:
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Make focused changes.
+4. Test your changes locally.
+5. Open a pull request with a clear description of what changed and why.
+
+Good contribution areas include:
+
+- WhatsApp session reliability
+- Dashboard UX
+- API ergonomics
+- Documentation improvements
+- Tests and validation
+- Developer experience
+
+## Issues and bug reports
+
+If you find a bug or want to request a feature, please open an issue with:
+
+- what you expected
+- what happened
+- steps to reproduce
+- logs or screenshots if relevant
+- environment details such as Node.js version and runtime mode
+
+## Security and responsible use
+
+Please do not use this project for spam, abuse, or policy-violating automation.
+
+If you discover a security issue, report it responsibly and avoid posting sensitive details publicly before maintainers have a chance to assess it.
+
+## License
+
+This project is released under the MIT license. See `package.json` for the current license declaration.
+
+## For agents and integrations
+
+Recommended call order:
+
+1. `GET /health`
+2. `GET /version`
+3. `GET /docs/json`
+4. `GET /api/chats` or `GET /api/contacts`
+5. `POST /api/contacts/{contactId}/open`
+6. `GET /api/chats/{chatId}/messages`
+7. `POST /api/chats/{chatId}/messages/send`
+
+If you need an agent-oriented markdown guide directly from the runtime, use `GET /docs/readme`.

package/bin/openwa.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const { startOpenWA } = require("../server");
+
+const dev = process.argv.includes("--dev");
+
+startOpenWA({ dev }).catch((error) => {
+  console.error("Failed to start OpenWA.");
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@adens/openwa",
+  "version": "0.1.0",
+  "description": "Self-hosted WhatsApp workspace with multi-session management, REST API, JWT & API key authentication, real-time messaging via Socket.IO, media upload, Swagger documentation, and AI-agent integration support.",
+  "license": "MIT",
+  "author": "asepindrak <asepindrakurniawan@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asepindrak/openwa.git"
+  },
+  "homepage": "https://github.com/asepindrak/openwa#readme",
+  "bugs": {
+    "url": "https://github.com/asepindrak/openwa/issues"
+  },
+  "preferGlobal": true,
+  "keywords": [
+    "openwa",
+    "cli",
+    "whatsapp",
+    "express",
+    "nextjs",
+    "socket.io",
+    "prisma"
+  ],
+  "bin": {
+    "openwa": "bin/openwa.js"
+  },
+  "scripts": {
+    "dev": "node bin/openwa.js --dev",
+    "start": "node bin/openwa.js",
+    "build": "node ./node_modules/prisma/build/index.js generate --schema prisma/schema.prisma && npm run build:web",
+    "build:web": "node ./node_modules/next/dist/bin/next build web",
+    "prisma:generate": "node ./node_modules/prisma/build/index.js generate --schema prisma/schema.prisma",
+    "prisma:push": "node ./node_modules/prisma/build/index.js db push --schema prisma/schema.prisma",
+    "publish": "npm run build && npm publish --access=public",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@prisma/client": "^6.6.0",
+    "bcryptjs": "^2.4.3",
+    "cookie": "^1.0.2",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "jsonwebtoken": "^9.0.2",
+    "multer": "^1.4.5-lts.2",
+    "next": "^15.2.4",
+    "open": "^10.1.0",
+    "prisma": "^6.6.0",
+    "qrcode": "^1.5.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-icons": "^5.6.0",
+    "socket.io": "^4.8.1",
+    "socket.io-client": "^4.8.1",
+    "whatsapp-web.js": "^1.34.6",
+    "zustand": "^5.0.3"
+  },
+  "devDependencies": {
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prisma/schema.prisma

@@ -0,0 +1,182 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = "file:../storage/database/openwa.db"
+}
+
+enum SessionState {
+  connecting
+  ready
+  disconnected
+  error
+}
+
+enum TransportType {
+  mock
+  wwebjs
+}
+
+enum MessageType {
+  text
+  image
+  video
+  audio
+  document
+  sticker
+}
+
+enum DeliveryStatus {
+  sent
+  delivered
+  read
+}
+
+enum MessageDirection {
+  inbound
+  outbound
+}
+
+model User {
+   id           String            @id @default(cuid())
+   name         String
+   email        String            @unique
+   passwordHash String
+   createdAt    DateTime          @default(now())
+   updatedAt    DateTime          @updatedAt
+   contacts     Contact[]
+   chats        Chat[]
+   sessions     WhatsappSession[]
+   mediaFiles   MediaFile[]
+   apiKeys      ApiKey[]
+
+   @@map("users")
+}
+
+model ApiKey {
+   id         String   @id @default(cuid())
+   userId     String
+   name       String
+   keyHash    String   @unique
+   keyPrefix  String
+   last4      String
+   lastUsedAt DateTime?
+   createdAt  DateTime @default(now())
+   updatedAt  DateTime @updatedAt
+   user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+   @@index([userId, createdAt])
+   @@map("api_keys")
+}
+
+model WhatsappSession {
+  id            String        @id @default(cuid())
+  userId        String
+  name          String
+  phoneNumber   String?
+  status        SessionState  @default(disconnected)
+  qrCode        String?
+  transportType TransportType @default(mock)
+  lastError     String?
+  createdAt     DateTime      @default(now())
+  updatedAt     DateTime      @updatedAt
+  user          User          @relation(fields: [userId], references: [id], onDelete: Cascade)
+  chats         Chat[]
+  messages      Message[]
+  contacts      Contact[]
+
+  @@index([userId])
+  @@map("whatsapp_sessions")
+}
+
+model Contact {
+  id                 String            @id @default(cuid())
+  userId             String
+  sessionId          String?
+  externalId         String
+  displayName        String
+  avatarUrl          String?
+  lastMessagePreview String?
+  lastMessageAt      DateTime?
+  unreadCount        Int               @default(0)
+  createdAt          DateTime          @default(now())
+  updatedAt          DateTime          @updatedAt
+  user               User              @relation(fields: [userId], references: [id], onDelete: Cascade)
+  session            WhatsappSession?  @relation(fields: [sessionId], references: [id], onDelete: SetNull)
+  chats              Chat[]
+
+  @@unique([userId, externalId])
+  @@map("contacts")
+}
+
+model Chat {
+  id        String            @id @default(cuid())
+  userId    String
+  sessionId String?
+  contactId String
+  title     String
+  createdAt DateTime          @default(now())
+  updatedAt DateTime          @updatedAt
+  user      User              @relation(fields: [userId], references: [id], onDelete: Cascade)
+  session   WhatsappSession?  @relation(fields: [sessionId], references: [id], onDelete: SetNull)
+  contact   Contact           @relation(fields: [contactId], references: [id], onDelete: Cascade)
+  messages  Message[]
+
+  @@unique([userId, contactId])
+  @@index([userId, updatedAt])
+  @@map("chats")
+}
+
+model MediaFile {
+  id           String    @id @default(cuid())
+  userId       String
+  fileName     String
+  originalName String
+  mimeType     String
+  size         Int
+  relativePath String
+  createdAt    DateTime  @default(now())
+  user         User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  messages     Message[]
+
+  @@index([userId])
+  @@map("media_files")
+}
+
+model Message {
+  id                String             @id @default(cuid())
+  chatId            String
+  sessionId         String?
+  mediaFileId       String?
+  replyToId         String?
+  externalMessageId String?
+  sender            String
+  receiver          String
+  body              String?
+  type              MessageType        @default(text)
+  direction         MessageDirection
+  createdAt         DateTime           @default(now())
+  updatedAt         DateTime           @updatedAt
+  chat              Chat               @relation(fields: [chatId], references: [id], onDelete: Cascade)
+  session           WhatsappSession?   @relation(fields: [sessionId], references: [id], onDelete: SetNull)
+  mediaFile         MediaFile?         @relation(fields: [mediaFileId], references: [id], onDelete: SetNull)
+  replyTo           Message?           @relation("MessageReplies", fields: [replyToId], references: [id], onDelete: SetNull)
+  replies           Message[]          @relation("MessageReplies")
+  statuses          MessageStatus[]
+
+  @@index([chatId, createdAt])
+  @@map("messages")
+}
+
+model MessageStatus {
+  id        String         @id @default(cuid())
+  messageId String
+  status    DeliveryStatus
+  createdAt DateTime       @default(now())
+  message   Message        @relation(fields: [messageId], references: [id], onDelete: Cascade)
+
+  @@index([messageId, createdAt])
+  @@map("message_status")
+}

package/server/config.js

@@ -0,0 +1,29 @@
+const path = require("path");
+const dotenv = require("dotenv");
+const { rootDir } = require("./utils/paths");
+
+dotenv.config({ path: path.join(rootDir, ".env") });
+
+function getConfig({ dev = false } = {}) {
+  const host = process.env.HOST || "127.0.0.1";
+  const frontendPort = Number(process.env.FE_PORT || process.env.FRONTEND_PORT || 55111);
+  const backendPort = Number(process.env.BE_PORT || process.env.BACKEND_PORT || 55222);
+  const frontendUrl = process.env.OPENWA_FRONTEND_URL || `http://localhost:${frontendPort}`;
+  const backendUrl = process.env.OPENWA_BACKEND_URL || `http://localhost:${backendPort}`;
+
+  return {
+    dev,
+    host,
+    frontendPort,
+    backendPort,
+    frontendUrl,
+    backendUrl,
+    appUrl: frontendUrl,
+    jwtSecret: process.env.OPENWA_JWT_SECRET || "openwa-local-dev-secret",
+    autoOpenBrowser: process.env.OPENWA_AUTO_OPEN !== "false",
+    useWwebjs: process.env.OPENWA_USE_WWEBJS !== "false",
+    allowMockAdapter: process.env.OPENWA_ALLOW_MOCK === "true"
+  };
+}
+
+module.exports = { getConfig };

package/server/database/client.js

@@ -0,0 +1,11 @@
+const { PrismaClient } = require("@prisma/client");
+
+const globalKey = "__openwa_prisma__";
+
+if (!global[globalKey]) {
+  global[globalKey] = new PrismaClient();
+}
+
+module.exports = {
+  prisma: global[globalKey]
+};