miaw-core 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,305 @@
+# 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.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
+- `addMessageLabel()` - Add a label to a message
+- `removeMessageLabel()` - Remove a label from a message
+- `LabelColor` enum - 20 predefined colors
+- `PredefinedLabelId` enum - 5 WhatsApp predefined labels
+- `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
+- `updateProduct()` - Modify existing products
+- `deleteProducts()` - Remove products from catalog
+- `Product`, `ProductCollection`, `ProductCatalog`, `ProductOperationResult`, `ProductOptions` types
+
+#### Newsletter/Channel Operations
+- `createNewsletter()` - Create WhatsApp channels/newsletters
+- `getNewsletterMetadata()` - Get newsletter information
+- `followNewsletter()` - Follow/subscribe to newsletters
+- `unfollowNewsletter()` - Unsubscribe from newsletters
+- `muteNewsletter()` - Mute newsletter notifications
+- `unmuteNewsletter()` - Unmute newsletter notifications
+- `updateNewsletterName()` - Update newsletter name
+- `updateNewsletterDescription()` - Update newsletter description
+- `updateNewsletterPicture()` - Update newsletter cover image
+- `removeNewsletterPicture()` - Remove newsletter cover image
+- `reactToNewsletterMessage()` - React to newsletter posts
+- `fetchNewsletterMessages()` - Get newsletter message history
+- `subscribeNewsletterUpdates()` - Subscribe to live newsletter updates
+- `getNewsletterSubscribers()` - Get subscriber count
+- `getNewsletterAdminCount()` - Get admin count
+- `changeNewsletterOwner()` - Transfer newsletter ownership
+- `demoteNewsletterAdmin()` - Demote a newsletter admin
+- `deleteNewsletter()` - Delete a newsletter
+- `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
+
+### 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**
+  - Profile management tests for all v0.8.0 features
+
+## [0.7.0] - 2025-12-21
+
+### 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
+  - `GroupInviteInfo` - Group preview info from invite code
+
+- **Integration Tests**
+  - Group management tests for all v0.7.0 features
+
+## [0.6.0] - 2025-12-14
+
+### 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**
+  - `deleteMessage()` - Delete messages for everyone (your own messages)
+  - `deleteMessageForMe()` - Delete messages locally (only for yourself)
+
+## [0.5.0] - 2025-12-14
+
+### 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)
+
+- **Integration Tests**
+  - UX polish tests for all v0.5.0 features
+
+## [0.4.0] - 2025-12-14
+
+### 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
+  - `GroupInfo` - Group metadata
+  - `GroupParticipant` - Group member with role
+
+- **Integration Tests**
+  - Contact validation tests
+  - Group info tests
+
+## [0.3.0] - 2025-12-14
+
+### 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
+
+- **Integration Tests**
+  - Message context tests for all v0.3.0 features
+
+### Changed
+
+- `SendTextOptions.quoted` now accepts `MiawMessage` instead of string
+- `SendImageOptions.quoted`, `SendDocumentOptions.quoted`, `SendVideoOptions.quoted`, `SendAudioOptions.quoted` now accept `MiawMessage`
+
+## [0.2.0] - 2025-12-14
+
+### 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
+  - GIF playback detection for videos
+  - View-once message detection
+
+- **New Types**
+  - `MediaSource` - Flexible input type (path/URL/Buffer)
+  - `SendImageOptions`, `SendDocumentOptions`, `SendVideoOptions`, `SendAudioOptions`
+  - `MediaInfo` - Media metadata interface
+
+- **Integration Tests**
+  - Media sending tests for all media types
+  - Media download tests
+
+### Changed
+
+- Enhanced `MessageHandler.normalize()` with media metadata extraction
+- `MiawMessage` now includes optional `media` field for metadata
+
+### Removed
+
+- Removed unused `SessionStorage` utility (`src/utils/storage.ts`)
+
+## [0.1.0] - 2025-11-19
+
+### 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
+  - `disconnected` - Client disconnected
+  - `reconnecting` - Reconnection attempt
+  - `error` - Error occurred
+  - `session_saved` - Session persisted
+
+- **Developer Experience**
+  - Full TypeScript support with strict mode
+  - Comprehensive type definitions
+  - Debug logging option
+
+### Dependencies
+
+- @whiskeysockets/baileys ^6.7.21
+- @hapi/boom ^10.0.1
+- pino ^8.19.0
+
+[0.6.0]: https://github.com/biji-dev/miaw-core/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/biji-dev/miaw-core/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/biji-dev/miaw-core/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/biji-dev/miaw-core/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/biji-dev/miaw-core/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/biji-dev/miaw-core/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Miaw Core Contributors
+
+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,134 @@
+# Miaw Core
+
+**Multiple Instance of App 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.
+
+## Documentation
+
+- **[Usage Guide](./USAGE.md)** - Complete guide for all current features
+- **[Roadmap](./ROADMAP.md)** - Feature roadmap and development plan
+- **[Examples](./examples/)** - Code examples and sample bots
+
+## Features
+
+- **Simple API** - Clean, intuitive interface for sending and receiving messages
+- **Auto-Reconnection** - Handles connection drops and reconnects automatically
+- **Session Management** - File-based session storage with automatic persistence
+- **Multiple Instances** - Run multiple WhatsApp connections in a single process
+- **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
+
+## Installation
+
+```bash
+npm install miaw-core
+```
+
+## Quick Start
+
+```typescript
+import { MiawClient } from "miaw-core";
+
+// Create client
+const client = new MiawClient({
+  instanceId: "my-bot",
+  sessionPath: "./sessions",
+});
+
+// Handle QR code
+client.on("qr", (qr) => {
+  console.log("Scan this QR code:", qr);
+});
+
+// When ready
+client.on("ready", () => {
+  console.log("Bot is ready!");
+});
+
+// Receive messages
+client.on("message", async (message) => {
+  console.log("Received:", message.text);
+
+  // Reply
+  await client.sendText(message.from, "Hello!");
+});
+
+// Start
+await client.connect();
+```
+
+For more examples and detailed usage, see the [Usage Guide](./USAGE.md).
+
+## Current Capabilities (v0.1.0)
+
+- ✅ Send and receive text messages
+- ✅ QR code authentication
+- ✅ Session persistence
+- ✅ Auto-reconnection
+- ✅ Multiple instances
+- ✅ Event-driven architecture
+- ✅ TypeScript support
+- ✅ Error handling
+
+See [ROADMAP.md](./ROADMAP.md) for planned features.
+
+## What Miaw Core Abstracts
+
+Miaw Core handles these Baileys complexities for you:
+
+- ✅ QR code generation and handling
+- ✅ Auth state management (save/load)
+- ✅ Socket connection setup
+- ✅ Reconnection logic
+- ✅ Message event parsing
+- ✅ Connection state tracking
+- ✅ Credentials persistence
+- ✅ Multi-file auth state
+- ✅ Baileys version management
+- ✅ Signal key store setup
+
+## Project Structure
+
+```text
+miaw-core/
+├── src/
+│   ├── client/          # Main MiawClient class
+│   ├── handlers/        # Auth and message handlers
+│   ├── types/           # TypeScript definitions
+│   ├── utils/           # Storage utilities
+│   └── index.ts         # Public API exports
+├── examples/            # Usage examples
+├── USAGE.md            # Complete usage guide
+├── ROADMAP.md          # Feature roadmap
+└── README.md           # This file
+```
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Check [ROADMAP.md](./ROADMAP.md) for planned features
+2. Open an issue to discuss your idea
+3. Fork the repository
+4. Create a feature branch
+5. Submit a pull request
+
+Please include:
+
+- Tests for new features
+- Updated documentation
+- Examples if applicable
+
+## License
+
+MIT
+
+## Credits
+
+Built on top of [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys)
+
+---
+
+**Version:** 0.1.0 | **Status:** Active Development | **Updated:** 2025-11-19