miaw-core 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -5,11 +5,141 @@ 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).
 
+## [1.1.0] - 2026-01-02
+
+**Baileys v7 Migration** - ESM-only release with improved session stability
+
+### BREAKING CHANGES
+
+- **ESM-only** - Package now uses `"type": "module"`. CommonJS `require()` is no longer supported.
+- **Node.js >= 18.0.0** required
+
+### Fixed
+
+- **Session reconnection issue** - Fixed bug where app couldn't reconnect after QR scan and restart without re-pairing
+- Includes fixes from Baileys v7: #1735, #1822, #1663, #1697
+
+### Changed
+
+- **Baileys** upgraded from v6.7.21 to v7.0.0-rc.9
+- TypeScript target updated to ES2022
+- All imports now use `.js` extensions for ESM compatibility
+- Node.js built-in imports use `node:` prefix
+
+### Migration
+
+For users upgrading from v1.0.x:
+
+```typescript
+// No code changes needed if already using ESM imports
+import { MiawClient } from "miaw-core";
+
+// If using CommonJS, migrate to ESM:
+// Before (CommonJS - no longer supported):
+// const { MiawClient } = require('miaw-core');
+
+// After (ESM):
+import { MiawClient } from "miaw-core";
+```
+
+Ensure your `package.json` has `"type": "module"` or use `.mjs` file extension.
+
+---
+
+## [1.0.0] - 2025-12-24
+
+**First Stable Release!** 🎉
+
+This is the first stable release of Miaw Core. After 9 pre-releases, the API is now stable and ready for production use.
+
+### Stability Guarantee
+
+- **No breaking changes** in v1.x.x releases
+- New features will be additive only
+- Deprecations will be marked at least 1 minor version before removal
+- Migration guides provided for any breaking changes in v2.x
+
+### What's New Since v0.9.1
+
+#### LID Cache Management
+
+- `getLidCacheSize()` - Get current LID to JID cache size
+- `clearLidCache()` - Clear the LID cache
+- `getLidMappings()` - Returns `Record<string, string>` instead of `Map`
+
+#### Resource Cleanup
+
+- `dispose()` - Properly clean up resources before shutdown
+- Recommended to call on process exit for clean session save
+
+#### Performance Improvements
+
+- LID mappings now use LRU cache with max size of 1000 entries
+- Automatic eviction of least recently used mappings
+- Improved memory management for long-running bots
+
+### API Surface
+
+81 public methods across 10 categories:
+
+- Core Client (7 methods)
+- Messaging (6 methods)
+- Media (5 methods)
+- Contact Info (5 methods)
+- Group Management (11 methods)
+- Profile Management (4 methods)
+- Label Operations (5 methods, Business only)
+- Catalog Operations (5 methods, Business only)
+- Newsletter Operations (17 methods)
+- Contact Management (2 methods)
+- LID Mapping (6 methods)
+- UX Features (6 methods)
+
+### Documentation
+
+- API Stability Review (`docs/API_STABILITY_REVIEW.md`)
+- Comprehensive examples (11 basic + 2 real-world examples)
+- Migration guide with version compatibility matrix
+- Complete type definitions with TypeScript strict mode
+
+### Testing
+
+- 68 unit tests (100% passing)
+- 144 integration tests (require WhatsApp authentication)
+- Full test coverage for all API methods
+
+### Known Changes from v0.9.x
+
+- `getLidMappings()` now returns `Record<string, string>` instead of `Map`
+  - Use `Object.entries()` or Object methods instead of Map methods
+
+## [0.9.1] - 2025-12-24
+
+### Added
+
+#### Examples
+
+- `01-basic-bot.ts` - Core client, QR authentication, echo bot (v0.1.0)
+- `02-media-bot.ts` - Media sending and downloading (v0.2.0)
+- `03-message-context.ts` - Reply, edit, delete, reactions (v0.3.0)
+- `04-validation-social.ts` - Number validation, contact/group info (v0.4.0)
+- `05-ux-polish.ts` - Read receipts, typing, presence (v0.5.0)
+- `06-advanced-messaging.ts` - Reactions, forward, edit, delete (v0.6.0)
+- `07-group-management.ts` - Full group admin features (v0.7.0)
+- `08-profile-management.ts` - Profile picture, name, status (v0.8.0)
+- `09-business-social.ts` - Labels, catalog, newsletter, contacts (v0.9.0)
+- `examples/README.md` - Examples overview and usage guide
+
+### Changed
+
+- Updated README.md with v0.9.0 capabilities and changelog link
+
 ## [0.9.0] - 2025-12-24
 
 ### Added
 
 #### Label Operations (WhatsApp Business only)
+
 - `addLabel()` - Create or edit labels
 - `addChatLabel()` - Add a label to a chat
 - `removeChatLabel()` - Remove a label from a chat
@@ -20,6 +150,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Label`, `LabelOperationResult` types
 
 #### Catalog/Product Operations (WhatsApp Business only)
+
 - `getCatalog()` - Fetch product catalog with pagination support
 - `getCollections()` - Fetch catalog collections
 - `createProduct()` - Add new products to catalog
@@ -28,6 +159,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Product`, `ProductCollection`, `ProductCatalog`, `ProductOperationResult`, `ProductOptions` types
 
 #### Newsletter/Channel Operations
+
 - `createNewsletter()` - Create WhatsApp channels/newsletters
 - `getNewsletterMetadata()` - Get newsletter information
 - `followNewsletter()` - Follow/subscribe to newsletters
@@ -49,11 +181,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `NewsletterMetadata`, `NewsletterMessage`, `NewsletterMessagesResult`, `NewsletterOperationResult`, `NewsletterSubscriptionInfo` types
 
 #### Contact Management
+
 - `addOrEditContact()` - Add or update contacts
 - `removeContact()` - Remove contacts
 - `ContactData`, `ContactOperationResult` types
 
 #### Tests
+
 - Integration tests for all v0.9.0 features (`12-business-features.test.ts`, `13-newsletter-features.test.ts`)
 
 ## [0.8.0] - 2025-12-21
@@ -61,14 +195,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Profile Picture Management**
+
   - `updateProfilePicture()` - Update your own profile picture (file path, URL, or Buffer)
   - `removeProfilePicture()` - Remove your profile picture
 
 - **Profile Information**
+
   - `updateProfileName()` - Update your display name (push name)
   - `updateProfileStatus()` - Update your "About" text
 
 - **New Types**
+
   - `ProfileOperationResult` - Result type for profile operations (success/error)
 
 - **Integration Tests**
@@ -79,31 +216,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Group Creation**
+
   - `createGroup()` - Create new WhatsApp groups with initial participants
   - Returns `CreateGroupResult` with group JID and metadata
 
 - **Participant Management**
+
   - `addParticipants()` - Add members to a group (requires admin)
   - `removeParticipants()` - Remove members from a group (requires admin)
   - `leaveGroup()` - Leave a group
   - Returns `ParticipantOperationResult[]` with status for each participant
 
 - **Admin Management**
+
   - `promoteToAdmin()` - Promote members to group admin
   - `demoteFromAdmin()` - Demote admins to regular members
 
 - **Group Settings**
+
   - `updateGroupName()` - Change group name/subject
   - `updateGroupDescription()` - Set or clear group description
   - `updateGroupPicture()` - Change group profile picture
 
 - **Group Invites**
+
   - `getGroupInviteLink()` - Get group invite link (https://chat.whatsapp.com/...)
   - `revokeGroupInvite()` - Revoke current link and get new one
   - `acceptGroupInvite()` - Join group via invite code or URL
   - `getGroupInviteInfo()` - Preview group info before joining
 
 - **New Types**
+
   - `ParticipantOperationResult` - Result of add/remove/promote/demote operations
   - `CreateGroupResult` - Result of group creation with metadata
   - `GroupOperationResult` - Generic success/error result for group operations
@@ -117,13 +260,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Send Reactions**
+
   - `sendReaction()` - Send emoji reactions to messages (e.g., '❤️', '👍')
   - `removeReaction()` - Remove your reaction from a message
 
 - **Forward Messages**
+
   - `forwardMessage()` - Forward any message to another chat
 
 - **Edit Messages**
+
   - `editMessage()` - Edit your own messages (within WhatsApp's 15-minute window)
 
 - **Delete Messages**
@@ -135,21 +281,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Read Receipts**
+
   - `markAsRead()` - Mark messages as read (send read receipt)
   - Returns boolean indicating success
 
 - **Typing & Recording Indicators**
+
   - `sendTyping()` - Send "typing..." indicator to a chat
   - `sendRecording()` - Send "recording audio..." indicator
   - `stopTyping()` - Stop typing/recording indicator (send paused state)
   - Works with both individual contacts and groups
 
 - **Presence Management**
+
   - `setPresence()` - Set bot's online/offline status ('available' or 'unavailable')
   - `subscribePresence()` - Subscribe to contact's presence updates
   - `presence` event - Emitted when subscribed contact's presence changes
 
 - **New Types**
+
   - `PresenceStatus` - Union type for 'available' | 'unavailable'
   - `PresenceUpdate` - Presence notification data (jid, status, lastSeen)
 
@@ -161,20 +311,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Contact Validation**
+
   - `checkNumber()` - Verify if phone number is on WhatsApp
   - `checkNumbers()` - Batch check multiple phone numbers
   - Returns `CheckNumberResult` with exists flag and JID
 
 - **Contact Information**
+
   - `getContactInfo()` - Fetch contact info including status
   - `getBusinessProfile()` - Get business account profile details
   - `getProfilePicture()` - Get profile picture URL (supports low/high res)
 
 - **Group Information**
+
   - `getGroupInfo()` - Fetch group metadata (name, description, settings)
   - `getGroupParticipants()` - List all group members with roles
 
 - **New Types**
+
   - `CheckNumberResult` - Result of number validation
   - `ContactInfo` - Contact information structure
   - `BusinessProfile` - Business profile data
@@ -190,23 +344,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Reply to Messages (Quoted)**
+
   - All send methods now support `quoted` option
   - Pass `MiawMessage` to reply to specific messages
   - Works with `sendText()`, `sendImage()`, `sendDocument()`, `sendVideo()`, `sendAudio()`
 
 - **Edit Notifications**
+
   - `message_edit` event when messages are edited
   - `MessageEdit` type with messageId, chatId, newText, editTimestamp
 
 - **Delete Notifications**
+
   - `message_delete` event when messages are deleted/revoked
   - `MessageDelete` type with messageId, chatId, fromMe, participant
 
 - **Reactions**
+
   - `message_reaction` event when messages receive reactions
   - `MessageReaction` type with messageId, chatId, reactorId, emoji, isRemoval
 
 - **New Types**
+
   - `MessageEdit` - Edit notification data
   - `MessageDelete` - Delete notification data
   - `MessageReaction` - Reaction notification data
@@ -224,15 +383,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Media Sending Methods**
+
   - `sendImage()` - Send images with caption and view-once support
   - `sendDocument()` - Send documents with auto-mimetype detection
   - `sendVideo()` - Send videos with caption, GIF playback, and PTV (video notes)
   - `sendAudio()` - Send audio with PTT (voice notes) support
 
 - **Media Download**
+
   - `downloadMedia()` - Download media from received messages as Buffer
 
 - **Media Metadata**
+
   - `MediaInfo` type with full metadata extraction
   - Support for mimetype, fileSize, dimensions, duration
   - PTT detection for voice notes
@@ -240,6 +402,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - View-once message detection
 
 - **New Types**
+
   - `MediaSource` - Flexible input type (path/URL/Buffer)
   - `SendImageOptions`, `SendDocumentOptions`, `SendVideoOptions`, `SendAudioOptions`
   - `MediaInfo` - Media metadata interface
@@ -262,22 +425,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Core Client**
+
   - `MiawClient` class with event-driven architecture
   - Connection management with auto-reconnection
   - Session persistence using Baileys multi-file auth state
   - Multiple instance support with isolated sessions
 
 - **Messaging**
+
   - `sendText()` - Send text messages to individuals and groups
   - Message normalization with `MiawMessage` format
   - Support for @s.whatsapp.net, @lid, @g.us JID formats
 
 - **LID Support**
+
   - Handle WhatsApp's @lid privacy format
   - LID to phone number mapping
   - `resolveLidToJid()`, `getPhoneFromJid()`, `registerLidMapping()`
 
 - **Events**
+
   - `qr` - QR code for authentication
   - `ready` - Client connected and ready
   - `message` - Incoming message received

package/README.md

@@ -1,13 +1,37 @@
 # Miaw Core
 
-**Multiple Instance of App WhatsApp** - A simplified WhatsApp API wrapper for Baileys
+**Multiple Instance of Awesome WhatsApp** - A simplified WhatsApp API wrapper for Baileys
 
 Miaw Core abstracts away the complexity of Baileys, providing a clean, simple API for building WhatsApp bots and automation tools. It handles all the painful parts: session management, QR codes, reconnection logic, and message parsing.
 
+> **Now powered by Baileys v7.0.0** - Full support for the latest WhatsApp Web features including newsletters/channels
+
+## Why Miaw Core vs Baileys Directly?
+
+| Aspect                 | Baileys (Direct)              | Miaw Core                          |
+| ---------------------- | ----------------------------- | ---------------------------------- |
+| **Learning Curve**     | Steep - 150+ methods to learn | Gentle - 92 focused methods        |
+| **Setup Code**         | 50-100 lines boilerplate      | 10 lines to start                  |
+| **Session Management** | Manual auth state handling    | Automatic file-based persistence   |
+| **Reconnection**       | DIY implementation            | Built-in with configurable retries |
+| **Message Format**     | Complex nested structures     | Normalized `MiawMessage` objects   |
+| **TypeScript**         | Types available but complex   | Clean, simplified types            |
+| **Multi-Instance**     | Manual socket management      | Instance ID-based separation       |
+
+**Choose Baileys directly** if you need low-level control, custom implementations, or access to every WhatsApp feature.
+
+**Choose Miaw Core** if you want to build bots quickly with clean code, automatic session handling, and don't need every obscure feature.
+
+For a detailed comparison, see [Baileys vs Miaw Core Comparison](./docs/BAILEYS_VS_MIAW_COMPARISON.md).
+
 ## Documentation
 
-- **[Usage Guide](./USAGE.md)** - Complete guide for all current features
-- **[Roadmap](./ROADMAP.md)** - Feature roadmap and development plan
+- **[Usage Guide](./docs/USAGE.md)** - Complete guide for all current features
+- **[Baileys Comparison](./docs/BAILEYS_VS_MIAW_COMPARISON.md)** - Feature comparison with raw Baileys
+- **[Migration Guide](./docs/MIGRATION.md)** - Upgrading between versions
+- **[Test Coverage](./docs/TEST_COVERAGE_ANALYSIS.md)** - API coverage analysis
+- **[Roadmap](./docs/ROADMAP.md)** - Feature roadmap and development plan
+- **[Changelog](./CHANGELOG.md)** - Version history and changes
 - **[Examples](./examples/)** - Code examples and sample bots
 
 ## Features
@@ -19,6 +43,15 @@ Miaw Core abstracts away the complexity of Baileys, providing a clean, simple AP
 - **TypeScript Support** - Full type definitions for excellent IDE experience
 - **Event-Driven** - Easy-to-use event system for messages and connection states
 - **Normalized Messages** - Simplified message format, no more complex Baileys structures
+- **Business Features** - Label operations, product catalog, newsletter/channels (WhatsApp Business)
+- **Contact Management** - Add, edit, and remove contacts
+- **Group Management** - Full admin capabilities for groups
+- **Profile Management** - Customize bot profile picture, name, and status
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **ESM** - This package is ESM-only (uses `"type": "module"`)
 
 ## Installation
 
@@ -59,11 +92,69 @@ client.on("message", async (message) => {
 await client.connect();
 ```
 
-For more examples and detailed usage, see the [Usage Guide](./USAGE.md).
+For more examples and detailed usage, see the [Usage Guide](./docs/USAGE.md).
+
+## Testing
+
+### Manual Interactive Testing
+
+Test all 92 API methods interactively:
+
+```bash
+# Show available test groups
+npm run test:manual
+
+# Run specific test groups
+npm run test:manual all         # All tests
+npm run test:manual messaging   # Messaging tests only
+npm run test:manual newsletter  # Newsletter tests only
+npm run test:manual business    # Business features only
+```
+
+**Available test groups:**
+
+| Group        | Description                     | Methods |
+| ------------ | ------------------------------- | ------- |
+| `core`       | Connection, lifecycle           | 6       |
+| `get`        | Fetch contacts, groups, chats   | 6       |
+| `messaging`  | Send/receive, reactions, edit   | 12      |
+| `contacts`   | Check numbers, contact info     | 7       |
+| `group`      | Create, manage participants     | 13      |
+| `profile`    | Update picture, name, status    | 4       |
+| `business`   | Labels, catalog (Business only) | 10      |
+| `newsletter` | Channels, subscriptions         | 6       |
+| `ux`         | Typing, presence, read receipts | 5       |
+
+**Features:**
+
+- Auto-connects using existing session (skips QR if already authenticated)
+- Tracks test results with pass/fail/skip status
+- Generates summary report with timestamps
+- Pre-loads test configuration from `.env.test`
 
-## Current Capabilities (v0.1.0)
+See [Test Coverage Analysis](./docs/TEST_COVERAGE_ANALYSIS.md) for detailed coverage report.
+
+### Unit & Integration Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run in watch mode
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
+```
+
+## Current Capabilities (v1.1.0)
+
+Built on **Baileys v7.0.0-rc.9** - the latest WhatsApp Web protocol implementation.
+
+### Core Features
 
 - ✅ Send and receive text messages
+- ✅ Send/receive media (images, videos, audio, documents)
 - ✅ QR code authentication
 - ✅ Session persistence
 - ✅ Auto-reconnection
@@ -72,7 +163,37 @@ For more examples and detailed usage, see the [Usage Guide](./USAGE.md).
 - ✅ TypeScript support
 - ✅ Error handling
 
-See [ROADMAP.md](./ROADMAP.md) for planned features.
+### Advanced Messaging
+
+- ✅ Reply/quote messages
+- ✅ Edit own messages
+- ✅ Delete messages
+- ✅ Message reactions
+- ✅ Forward messages
+
+### Group Management
+
+- ✅ Create groups
+- ✅ Add/remove participants
+- ✅ Promote/demote admins
+- ✅ Group invite links
+- ✅ Update group settings
+
+### Profile Management
+
+- ✅ Update profile picture
+- ✅ Remove profile picture
+- ✅ Update profile name
+- ✅ Update profile status
+
+### Business & Social
+
+- ✅ Label operations (WhatsApp Business)
+- ✅ Product catalog management (WhatsApp Business)
+- ✅ Newsletter/channel operations (create, send, manage)
+- ✅ Contact management (add, edit, remove)
+
+See [ROADMAP.md](./docs/ROADMAP.md) for planned features.
 
 ## What Miaw Core Abstracts
 
@@ -99,9 +220,9 @@ miaw-core/
 │   ├── types/           # TypeScript definitions
 │   ├── utils/           # Storage utilities
 │   └── index.ts         # Public API exports
+├── docs/                # Documentation
 ├── examples/            # Usage examples
-├── USAGE.md            # Complete usage guide
-├── ROADMAP.md          # Feature roadmap
+├── tests/               # Unit and integration tests
 └── README.md           # This file
 ```
 
@@ -109,7 +230,7 @@ miaw-core/
 
 Contributions are welcome! To contribute:
 
-1. Check [ROADMAP.md](./ROADMAP.md) for planned features
+1. Check [ROADMAP.md](./docs/ROADMAP.md) for planned features
 2. Open an issue to discuss your idea
 3. Fork the repository
 4. Create a feature branch
@@ -127,8 +248,8 @@ MIT
 
 ## Credits
 
-Built on top of [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys)
+Built on top of [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys) v7.0.0-rc.9
 
 ---
 
-**Version:** 0.1.0 | **Status:** Active Development | **Updated:** 2025-11-19
+**Version:** 1.1.0 | **Baileys:** 7.0.0-rc.9 | **Status:** Stable | **Updated:** 2026-01-03

package/babel.config.js

@@ -1,5 +1,5 @@
-module.exports = {
+export default {
   presets: [
-    ['@babel/preset-env', { targets: { node: 'current' } }],
+    ['@babel/preset-env', { targets: { node: 'current' }, modules: false }],
   ],
 };