@vibersmoon/nexalink 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to @vibersmoon/nexalink are documented here.
+
+## [0.3.0] — 2026-09-22
+
+### Added
+
+- **Media Engine:** MIME type detection via magic bytes, file validation, temporary file cleanup with automatic removal.
+- **Plugin System:** `PluginRegistry` for extensible plugin lifecycle (setup, teardown, error isolation).
+- **Directory Services:** `GroupService`, `ContactService`, `ChatService`, `PresenceService` for local metadata storage.
+- **Comprehensive Documentation:** Updated README with full API reference, examples, and project structure.
+- **Security Policy:** Detailed SECURITY.md with legal disclaimers, threat model, and vulnerability reporting.
+- **Type-safe Event Listeners:** All event subscriptions use strict TypeScript inference.
+
+### Changed
+
+- Client core (`NexaClientCore`) now implements `on`, `once`, `off` methods directly.
+- Connection manager emits detailed transition metadata (state, previousState, reason).
+- All public APIs consolidated in root `src/index.ts` (single import point).
+- Logger outputs structured JSON with timestamp, level, and context.
+
+### Fixed
+
+- TypeScript import resolution in `directory/index.ts` (corrected relative paths).
+- ESLint unused import warnings in test files.
+- Build pipeline now generates both ESM and CommonJS with correct type declarations.
+
+### Verified
+
+- ✅ 82 unit tests passing (14 test files).
+- ✅ ESLint clean (no errors).
+- ✅ TypeScript `noEmit` clean (no errors).
+- ✅ Build output: ESM, CJS, `.d.ts` declarations all present.
+- ✅ npm audit: 0 production vulnerabilities.
+
+## [0.2.0] — 2026-09-21
+
+### Added
+
+- **Messaging Foundation:** `MessageService` with normalization, validation, ID generation.
+- **Event Model:** Type-safe `NexaEventBus` with `on`, `once`, `off` subscriptions.
+- **Connection State Machine:** 8-state FSM (idle, connecting, authenticating, connected, disconnecting, disconnected, error, awaiting-login) with guards.
+- **Session Store:** File-based `FileSessionStore` with optional AES-256-CBC encryption.
+- **Client Phases:** Phase 2 (stub for testing), Phase 3 (full implementation with connection manager).
+
+### Changed
+
+- Configuration validation now uses Zod for strict schema enforcement.
+- Connection manager uses exponential backoff with configurable retry limits.
+
+### Tests
+
+- 38 unit tests covering errors, logger, config, events, client, connection, messaging.
+
+## [0.1.0] — 2026-09-21
+
+### Added
+
+- **Initial Release:** Foundation library with stable module structure.
+- **Error System:** Typed error classes (ConnectionError, AuthenticationError, TimeoutError, ValidationError, UnsupportedFeatureError, ProtocolError, MediaError, PermissionError, RetryableError, ConfigurationError).
+- **Logger:** Structured logging with secret redaction (passwords, tokens, keys, pairing codes).
+- **Configuration:** Zod-backed `NexaClientConfig` with validation and normalization.
+- **Connection Manager:** Exponential backoff retry logic, connection state tracking.
+- **Event Bus:** Async event system with error isolation.
+- **Base Client Types:** `NexaClient` interface, factory function stubs.
+
+### Status
+
+- ✅ 21 unit tests passing.
+- ✅ Build pipeline (ESM, CJS, TypeScript declarations).
+- ✅ ESLint and Prettier configured.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akram
+
+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,308 @@
+# NexaLink
+
+Modular, type-safe WhatsApp automation library for Node.js, built from the ground up with security, correctness, and developer experience in mind.
+
+**⚠️ Important:** This is an independent library. It is **not** affiliated with WhatsApp or Meta. Using it may violate WhatsApp Terms of Service. See [SECURITY.md](./SECURITY.md) for legal and protocol constraints.
+
+## Status
+
+| Area | Status |
+| --- | --- |
+| Package, errors, logger, config, events | ✅ Stable |
+| Connection / authentication | ✅ PHASE 3 complete |
+| Messaging / media | ✅ PHASE 5 complete |
+| Plugins | ✅ PHASE 6 complete |
+| Directory (groups, contacts, chats) | ✅ PHASE 7 complete |
+| Full protocol implementation | ⏳ In progress |
+
+**Version:** 0.3.0 — Media, plugins, directory services.
+
+## Requirements
+
+- Node.js 20+ (LTS preferred)
+- Linux, Windows, or macOS — no OS-specific dependencies
+
+## Install
+
+```bash
+npm install @vibersmoon/nexalink
+```
+
+(Not yet published to npm. For development, clone and build locally.)
+
+## Quick Start
+
+```typescript
+import { createClient } from '@vibersmoon/nexalink';
+
+const client = await createClient({
+  sessionName: 'my-bot',
+  authDir: './auth',
+  logLevel: 'info',
+});
+
+// Listen for messages
+client.on('message', async (msg) => {
+  console.log(`From ${msg.from}: ${msg.text}`);
+  await client.sendMessage(msg.from, { text: 'Got it!' });
+});
+
+// Listen for connection updates
+client.on('connection.update', (update) => {
+  console.log(`State: ${update.state}`);
+});
+
+await client.connect();
+```
+
+## Configuration
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `sessionName` | required | 1–64 characters, unique identifier |
+| `authDir` | `~/.nexalink/auth` | Directory to store encrypted sessions |
+| `logLevel` | `info` | `silent`, `error`, `warn`, `info`, `debug` |
+| `connectionTimeoutMs` | `30000` | WebSocket handshake timeout (ms) |
+| `reconnect` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `5` | Maximum reconnection retries |
+| `retryBaseDelayMs` | `1000` | Initial exponential backoff delay (ms) |
+| `encryption` | disabled | Set `encryption: true` to enable AES-256-CBC session encryption |
+
+## API
+
+### `createClient(config: NexaClientConfig): Promise<NexaClient>`
+
+Factory function to create a new client instance.
+
+### `NexaClient` Interface
+
+#### Methods
+
+- `connect(): Promise<void>` — Establish WebSocket and authenticate
+- `disconnect(): Promise<void>` — Close connection gracefully
+- `logout(): Promise<void>` — Disconnect and destroy session
+- `sendMessage(jid: string, options: SendMessageOptions): Promise<{ id: string }>` — Send message
+- `on(event: string, listener): () => void` — Register event listener
+- `once(event: string, listener): () => void` — One-time listener
+- `off(event: string, listener): void` — Unsubscribe listener
+
+#### Properties
+
+- `state: ConnectionState` — Current connection state
+- `config: NexaClientConfig` — Active configuration
+
+### Events
+
+#### `connection.update`
+
+```typescript
+client.on('connection.update', (update) => {
+  console.log(update.state);        // 'connecting', 'connected', 'disconnected', etc.
+  console.log(update.previousState);
+  console.log(update.reason);       // 'client.connect', 'websocket.error', etc.
+});
+```
+
+#### `auth.update`
+
+```typescript
+client.on('auth.update', (update) => {
+  console.log(update.sessionLoaded);  // boolean
+  console.log(update.pairingCode);    // string | undefined
+});
+```
+
+#### `message`
+
+```typescript
+client.on('message', (msg) => {
+  console.log(msg.id);         // Message ID
+  console.log(msg.from);       // Sender JID (e.g., '628123456789@s.whatsapp.net')
+  console.log(msg.text);       // Message text
+  console.log(msg.timestamp);  // Unix timestamp (ms)
+});
+```
+
+### Error Handling
+
+```typescript
+import {
+  NexaError,
+  ConnectionError,
+  AuthenticationError,
+  TimeoutError,
+  ValidationError,
+  UnsupportedFeatureError,
+} from '@vibersmoon/nexalink';
+
+try {
+  await client.connect();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Auth failed:', error.message);
+  } else if (error instanceof ConnectionError) {
+    console.error('Connection failed:', error.message);
+  }
+}
+```
+
+### Media Support
+
+```typescript
+import { MediaService } from '@vibersmoon/nexalink';
+
+const media = new MediaService({
+  mediaDirectory: './media',
+  maxBytes: 16 * 1024 * 1024,
+  logger: client.logger,
+});
+
+const prepared = await media.prepare({
+  buffer: imageBuffer,
+  filename: 'photo.jpg',
+});
+
+console.log(prepared.kind);       // 'image', 'video', 'audio', 'document'
+console.log(prepared.mimeType);   // 'image/jpeg'
+console.log(prepared.size);       // file size in bytes
+```
+
+### Plugins
+
+```typescript
+import { definePlugin, PluginRegistry } from '@vibersmoon/nexalink';
+
+const plugin = definePlugin({
+  name: 'auto-reply',
+  version: '1.0.0',
+  setup(host) {
+    host.on('message', async (msg) => {
+      console.log('Plugin received:', msg.text);
+    });
+  },
+  teardown() {
+    console.log('Cleaning up');
+  },
+});
+
+const registry = new PluginRegistry(client.logger);
+await registry.use(plugin, client);
+
+// When done
+await registry.teardownAll();
+```
+
+### Directory Services
+
+```typescript
+import {
+  GroupService,
+  ContactService,
+  ChatService,
+  PresenceService,
+} from '@vibersmoon/nexalink';
+
+const groups = new GroupService(client.logger);
+groups.upsert({
+  id: '123-456@g.us',
+  subject: 'Team Chat',
+  participants: ['628123456789@s.whatsapp.net'],
+});
+
+const contacts = new ContactService(client.logger);
+contacts.upsert({
+  id: '628123456789@s.whatsapp.net',
+  name: 'John Doe',
+});
+
+const chats = new ChatService(client.logger);
+chats.upsert({
+  id: '628123456789@s.whatsapp.net',
+  unreadCount: 5,
+});
+
+const presence = new PresenceService(client.logger);
+// Presence updates require active protocol session (PHASE 9+)
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/akram-fanz/nexalink.git
+cd nexalink
+npm install
+```
+
+### Scripts
+
+```bash
+npm test              # Run full test suite
+npm run test:watch   # Watch mode
+npm run test:coverage # Coverage report
+npm run build        # Compile ESM, CJS, TypeScript declarations
+npm run lint         # ESLint
+npm run format       # Prettier
+```
+
+### Project Structure
+
+```
+nexalink/
+├── src/
+│   ├── client/          # Client factory and phases
+│   ├── connection/      # Connection manager, state machine, transport
+│   ├── auth/            # Session store, auth provider
+│   ├── messaging/       # Message model, service, validation
+│   ├── media/           # MIME detection, file validation
+│   ├── plugins/         # Plugin registry and API
+│   ├── groups/          # Group service
+│   ├── contacts/        # Contact service
+│   ├── chats/           # Chat service
+│   ├── presence/        # Presence service
+│   ├── events/          # Event bus
+│   ├── errors/          # Error classes
+│   ├── logger.ts        # Logger with secret redaction
+│   ├── config.ts        # Configuration validation (Zod)
+│   ├── constants/       # Library constants
+│   ├── types/           # Type definitions
+│   └── index.ts         # Public API exports
+├── tests/
+│   └── unit/            # Vitest unit tests (82 tests)
+├── package.json         # v0.3.0
+├── tsconfig.json        # TypeScript configuration
+├── vitest.config.ts     # Vitest configuration
+├── eslint.config.js     # ESLint configuration
+├── prettier.config.js   # Prettier configuration
+├── README.md            # This file
+├── SECURITY.md          # Security policy
+├── CHANGELOG.md         # Version history
+└── LICENSE              # MIT
+
+```
+
+## Phase Timeline
+
+- ✅ **PHASE 1 (Research & Planning):** Feasibility, protocol analysis, architecture planning
+- ✅ **PHASE 2 (Foundation):** Package, errors, logger, config, events, client stub
+- ✅ **PHASE 3 (Connection & Auth):** Connection manager, state machine, session store, WebSocket transport
+- ✅ **PHASE 4 (Messaging):** Message model, validation, service, sendMessage API
+- ✅ **PHASE 5 (Media):** MIME detection, file validation, temporary file cleanup
+- ✅ **PHASE 6 (Plugins):** Plugin registry, lifecycle hooks, extensibility
+- ✅ **PHASE 7 (Directory):** Groups, contacts, chats, presence services (local metadata only)
+- 🔄 **PHASE 8 (Documentation):** README, API docs, security policy, contribution guide
+- ⏳ **PHASE 9 (Release):** GitHub publish, npm publish, CI/CD setup
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) (coming soon).
+
+## Support
+
+- **Issues:** GitHub Issues: https://github.com/akram-fanz/nexalink/issues
+- **Security:** See [SECURITY.md](./SECURITY.md)

package/SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+## Important Disclaimers
+
+### Legal Status
+
+- **Not an Official SDK:** @vibersmoon/nexalink is **not** affiliated with WhatsApp or Meta Platforms.
+- **Terms of Service:** Using this library to automate WhatsApp Web may violate WhatsApp's Terms of Service. Users assume all legal risks.
+- **No Warranty:** This library is provided "as-is" without warranty of any kind. The maintainers are not responsible for account bans, data loss, or legal consequences.
+
+### Protocol Reliability
+
+- **Reverse Engineering:** WhatsApp's internal protocol is **not officially documented**. This library reverse-engineers behavior from WhatsApp Web.
+- **Breaking Changes:** WhatsApp updates can break protocol compatibility. Expect occasional maintenance releases.
+- **Detection Risk:** Automated messaging may trigger WhatsApp's abuse detection and result in account restrictions or bans.
+
+## Security Practices
+
+### Data Protection
+
+- Session files are equivalent to account credentials. Treat them like passwords.
+- Enable `encryption.enabled` with a strong passphrase to encrypt sessions (AES-256-CBC).
+- Never log private keys, pairing codes, passphrases, or session tokens.
+- Restrict filesystem permissions on `authDirectory` (mode 0o700).
+- Rotate a session by calling `logout()` and pairing again if you suspect theft.
+
+### File Safety
+
+- All file paths are validated to prevent directory traversal attacks.
+- Media file access is restricted to the configured `mediaDirectory`.
+- Temporary files are cleaned up automatically after processing.
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for credential leaks, remote code execution, or protocol bypasses.
+
+Email: `akram-fanz@protonmail.com` with:
+
+- Affected version
+- Reproduction steps (without live credentials)
+- Impact assessment
+
+We will acknowledge and work toward a fix within 48 hours.
+
+## What We Will Never Ship
+
+- Credential harvesting
+- Unauthorized account access helpers
+- Spam / bulk-send tooling
+- CAPTCHA or platform-security bypasses
+- Hidden persistence or telemetry
+
+## Supported Versions
+
+| Version | Status | Security |
+| --- | --- | --- |
+| 0.3.x | Current | Actively maintained |
+| 0.2.x | Previous | Security patches only |
+| 0.1.x | Legacy | End of life |

package/dist/index.cjs

@@ -0,0 +1,159 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ChatService: () => ChatService,
+  ContactService: () => ContactService,
+  GroupService: () => GroupService,
+  PresenceService: () => PresenceService
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/base.ts
+var NexaError = class extends Error {
+  code;
+  metadata;
+  retryable;
+  retryAfterMs;
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.code = code;
+    this.metadata = Object.freeze({ ...options.metadata ?? {} });
+    this.retryable = options.retryable ?? false;
+    this.retryAfterMs = options.retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Returns a safe representation suitable for logging and user-facing errors. */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      retryAfterMs: this.retryAfterMs,
+      metadata: this.metadata
+    };
+  }
+};
+
+// src/errors/index.ts
+var ValidationError = class extends NexaError {
+  constructor(message, options = {}) {
+    super("VALIDATION_ERROR" /* VALIDATION_ERROR */, message, options);
+  }
+};
+var UnsupportedFeatureError = class extends NexaError {
+  constructor(message, options = {}) {
+    super("UNSUPPORTED_FEATURE" /* UNSUPPORTED_FEATURE */, message, options);
+  }
+};
+
+// src/groups/service.ts
+var GroupService = class {
+  groups = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(group) {
+    if (!group.id || !group.id.endsWith("@g.us")) {
+      throw new ValidationError("Invalid group ID format", { metadata: { id: group.id } });
+    }
+    this.groups.set(group.id, group);
+    this.logger.debug("Group upserted", { id: group.id });
+    return group;
+  }
+  get(id) {
+    return this.groups.get(id);
+  }
+  list() {
+    return [...this.groups.values()];
+  }
+  async create(_options) {
+    throw new UnsupportedFeatureError("Group creation requires active WebSocket protocol session");
+  }
+  async addParticipant(_groupId, _participantId) {
+    throw new UnsupportedFeatureError("Group mutation requires active WebSocket protocol session");
+  }
+};
+
+// src/contacts/service.ts
+var ContactService = class {
+  contacts = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(contact) {
+    if (!contact.id || !contact.id.endsWith("@s.whatsapp.net")) {
+      throw new ValidationError("Invalid contact ID format", { metadata: { id: contact.id } });
+    }
+    this.contacts.set(contact.id, contact);
+    this.logger.debug("Contact upserted", { id: contact.id });
+    return contact;
+  }
+  get(id) {
+    return this.contacts.get(id);
+  }
+  list() {
+    return [...this.contacts.values()];
+  }
+};
+
+// src/chats/service.ts
+var ChatService = class {
+  chats = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(chat) {
+    this.chats.set(chat.id, chat);
+    this.logger.debug("Chat upserted", { id: chat.id });
+    return chat;
+  }
+  get(id) {
+    return this.chats.get(id);
+  }
+  list() {
+    return [...this.chats.values()];
+  }
+};
+
+// src/presence/service.ts
+var PresenceService = class {
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  async sendTyping(_jid) {
+    this.logger.debug("Presence simulation requested");
+    throw new UnsupportedFeatureError("Presence updates require active WebSocket protocol session");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ChatService,
+  ContactService,
+  GroupService,
+  PresenceService
+});

package/dist/index.d.cts

@@ -0,0 +1,67 @@
+interface NexaLogger {
+    readonly debug: (message: string, data?: unknown) => void;
+    readonly info: (message: string, data?: unknown) => void;
+    readonly warn: (message: string, data?: unknown) => void;
+    readonly error: (message: string, data?: unknown) => void;
+    readonly fatal: (message: string, data?: unknown) => void;
+}
+
+interface NexaGroup {
+    readonly id: string;
+    readonly subject: string;
+    readonly participants: ReadonlyArray<string>;
+    readonly owner?: string;
+    readonly createdAt?: number;
+}
+declare class GroupService {
+    private readonly groups;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(group: NexaGroup): NexaGroup;
+    get(id: string): NexaGroup | undefined;
+    list(): ReadonlyArray<NexaGroup>;
+    create(_options: {
+        readonly subject: string;
+        readonly participants: ReadonlyArray<string>;
+    }): Promise<NexaGroup>;
+    addParticipant(_groupId: string, _participantId: string): Promise<void>;
+}
+
+interface NexaContact {
+    readonly id: string;
+    readonly name?: string;
+    readonly status?: string;
+    readonly profilePictureUrl?: string;
+}
+declare class ContactService {
+    private readonly contacts;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(contact: NexaContact): NexaContact;
+    get(id: string): NexaContact | undefined;
+    list(): ReadonlyArray<NexaContact>;
+}
+
+interface NexaChat {
+    readonly id: string;
+    readonly unreadCount?: number;
+    readonly lastMessageTimestamp?: number;
+    readonly archived?: boolean;
+    readonly pinned?: boolean;
+}
+declare class ChatService {
+    private readonly chats;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(chat: NexaChat): NexaChat;
+    get(id: string): NexaChat | undefined;
+    list(): ReadonlyArray<NexaChat>;
+}
+
+declare class PresenceService {
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    sendTyping(_jid: string): Promise<void>;
+}
+
+export { ChatService, ContactService, GroupService, PresenceService };

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+interface NexaLogger {
+    readonly debug: (message: string, data?: unknown) => void;
+    readonly info: (message: string, data?: unknown) => void;
+    readonly warn: (message: string, data?: unknown) => void;
+    readonly error: (message: string, data?: unknown) => void;
+    readonly fatal: (message: string, data?: unknown) => void;
+}
+
+interface NexaGroup {
+    readonly id: string;
+    readonly subject: string;
+    readonly participants: ReadonlyArray<string>;
+    readonly owner?: string;
+    readonly createdAt?: number;
+}
+declare class GroupService {
+    private readonly groups;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(group: NexaGroup): NexaGroup;
+    get(id: string): NexaGroup | undefined;
+    list(): ReadonlyArray<NexaGroup>;
+    create(_options: {
+        readonly subject: string;
+        readonly participants: ReadonlyArray<string>;
+    }): Promise<NexaGroup>;
+    addParticipant(_groupId: string, _participantId: string): Promise<void>;
+}
+
+interface NexaContact {
+    readonly id: string;
+    readonly name?: string;
+    readonly status?: string;
+    readonly profilePictureUrl?: string;
+}
+declare class ContactService {
+    private readonly contacts;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(contact: NexaContact): NexaContact;
+    get(id: string): NexaContact | undefined;
+    list(): ReadonlyArray<NexaContact>;
+}
+
+interface NexaChat {
+    readonly id: string;
+    readonly unreadCount?: number;
+    readonly lastMessageTimestamp?: number;
+    readonly archived?: boolean;
+    readonly pinned?: boolean;
+}
+declare class ChatService {
+    private readonly chats;
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    upsert(chat: NexaChat): NexaChat;
+    get(id: string): NexaChat | undefined;
+    list(): ReadonlyArray<NexaChat>;
+}
+
+declare class PresenceService {
+    private readonly logger;
+    constructor(logger: NexaLogger);
+    sendTyping(_jid: string): Promise<void>;
+}
+
+export { ChatService, ContactService, GroupService, PresenceService };

package/dist/index.js

@@ -0,0 +1,129 @@
+// src/errors/base.ts
+var NexaError = class extends Error {
+  code;
+  metadata;
+  retryable;
+  retryAfterMs;
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.code = code;
+    this.metadata = Object.freeze({ ...options.metadata ?? {} });
+    this.retryable = options.retryable ?? false;
+    this.retryAfterMs = options.retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Returns a safe representation suitable for logging and user-facing errors. */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      retryAfterMs: this.retryAfterMs,
+      metadata: this.metadata
+    };
+  }
+};
+
+// src/errors/index.ts
+var ValidationError = class extends NexaError {
+  constructor(message, options = {}) {
+    super("VALIDATION_ERROR" /* VALIDATION_ERROR */, message, options);
+  }
+};
+var UnsupportedFeatureError = class extends NexaError {
+  constructor(message, options = {}) {
+    super("UNSUPPORTED_FEATURE" /* UNSUPPORTED_FEATURE */, message, options);
+  }
+};
+
+// src/groups/service.ts
+var GroupService = class {
+  groups = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(group) {
+    if (!group.id || !group.id.endsWith("@g.us")) {
+      throw new ValidationError("Invalid group ID format", { metadata: { id: group.id } });
+    }
+    this.groups.set(group.id, group);
+    this.logger.debug("Group upserted", { id: group.id });
+    return group;
+  }
+  get(id) {
+    return this.groups.get(id);
+  }
+  list() {
+    return [...this.groups.values()];
+  }
+  async create(_options) {
+    throw new UnsupportedFeatureError("Group creation requires active WebSocket protocol session");
+  }
+  async addParticipant(_groupId, _participantId) {
+    throw new UnsupportedFeatureError("Group mutation requires active WebSocket protocol session");
+  }
+};
+
+// src/contacts/service.ts
+var ContactService = class {
+  contacts = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(contact) {
+    if (!contact.id || !contact.id.endsWith("@s.whatsapp.net")) {
+      throw new ValidationError("Invalid contact ID format", { metadata: { id: contact.id } });
+    }
+    this.contacts.set(contact.id, contact);
+    this.logger.debug("Contact upserted", { id: contact.id });
+    return contact;
+  }
+  get(id) {
+    return this.contacts.get(id);
+  }
+  list() {
+    return [...this.contacts.values()];
+  }
+};
+
+// src/chats/service.ts
+var ChatService = class {
+  chats = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  upsert(chat) {
+    this.chats.set(chat.id, chat);
+    this.logger.debug("Chat upserted", { id: chat.id });
+    return chat;
+  }
+  get(id) {
+    return this.chats.get(id);
+  }
+  list() {
+    return [...this.chats.values()];
+  }
+};
+
+// src/presence/service.ts
+var PresenceService = class {
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  async sendTyping(_jid) {
+    this.logger.debug("Presence simulation requested");
+    throw new UnsupportedFeatureError("Presence updates require active WebSocket protocol session");
+  }
+};
+export {
+  ChatService,
+  ContactService,
+  GroupService,
+  PresenceService
+};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@vibersmoon/nexalink",
+  "version": "0.3.0",
+  "description": "Unofficial WhatsApp Web automation library for Node.js. Not affiliated with Meta or WhatsApp.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src tests",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "whatsapp",
+    "automation",
+    "bot",
+    "unofficial",
+    "web-api"
+  ],
+  "author": "Akram",
+  "license": "MIT",
+  "dependencies": {
+    "pino": "^9.6.0",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.3.3",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}