# NAKWASAP-X 0.2.0

An English Chrome extension for contacts, exports and reviewed WhatsApp workflows. The interface follows the observed WAXP layout using independently written application code, icons and branding.

## Install or update

1. Extract `NAKWASAP-X-Extension-0.2.0.zip` into a permanent folder.
2. Open `chrome://extensions` in the Chrome profile containing your WhatsApp session.
3. Enable Developer mode and select **Load unpacked**. Choose the extracted folder containing `manifest.json`.
4. If replacing the old Wasap Contact Studio build, disable that old entry first. This package uses a new folder, so it may appear as a separate extension.
5. Reload WhatsApp Web. Pin NAKWASAP-X in Chrome's extensions menu.
6. Click NAKWASAP-X. It opens or focuses WhatsApp Web and opens the side panel. Scan the WhatsApp QR code yourself if requested. Contacts scan when the session is ready.

For development, load the `extension` directory directly. After updating its files, click Reload on its Chrome extension card and reload WhatsApp.

## Features

- Home dashboard: chat count, contacts outside the chatlist, saved/unsaved contacts, groups, business/enterprise, recent unsaved contacts and country shortcuts.
- Automatic initial scan, QR waiting state, manual Scan and refresh every 60 seconds while the panel remains open.
- Groups, Chatlist and Labels export sources. Chatlist also offers all available contacts.
- Group selection, unsaved/unread/country/name filters, phone-only option and a paginated preview.
- Excel XLSX, CSV, JSON, searchable offline HTML and vCard downloads.
- Contact notes, tags, email, timezone metadata and custom text fields. Contact and group field schemas are separate. Changes save when leaving a field, or using Save properties.
- Local properties are separated by WhatsApp account. Scanned contacts stay in memory.
- Bulk Assign Labels from pasted numbers or CSV, matched to existing scanned chats.
- Bulk archive, unarchive and delete with reviewed recipients. Choose chats directly or import numbers. Delete additionally requires typing DELETE. Stop halts subsequent operations; an operation already in progress cannot be undone by Stop.
- Screen privacy masking for the panel and supported WhatsApp elements.

## Export workflow

Choose **Exports**, select a source and filters, then choose a format from the arrow beside Export. Group members load when exporting selected groups. With no individual selection, the export includes all matching contacts; the footer shows this scope. Notes and custom fields are included. vCard omits entries without valid international phone numbers.

Use CSV with a `phone`, `phone number`, `number`, `mobile` or `whatsapp` column for workflows, or enter international numbers one per line. Unknown numbers are reported rather than creating new chats. Workflow delay is configurable. There is no automatic retry after an uncertain mutation result.

## Verification status

- 13 automated logic/worker tests pass, including real LID-to-phone cache mapping and chat-ID deduplication.
- Isolated Chromium browser tests pass across Home, Contact, Exports, Tools, Account and Help at widths 320, 440 and 800 px.
- Five fixture export downloads verified. XLSX is actual OOXML with text cells; HTML search works; CSV formula-like text is neutralized.
- QR waiting/retry, imported chat matching, action confirmation, account-separated properties and fixture bulk flows verified.
- WAXP itself was tested on one user-approved real chat: archive reported one success and zero failures. The chat was unarchived using WhatsApp and its original pin restored. No messages or delete actions were tested.
- NAKWASAP-X 0.2.0 was installed in the approved Chrome profile on 6 November 2026. Clicking its toolbar icon from the Extensions tab focused WhatsApp Web and started scanning automatically.
- The corrected scan found 1,610 unique contacts, 1,602 resolved phone numbers, 8 unresolved contacts and 118 chats in that session. These are a session snapshot, not a guarantee of account-wide completeness.
- A one-contact live export passed as CSV and Excel. Both files were downloaded and parsed locally; their contact name and phone matched the preview. No live NAKWASAP-X mutation was performed. QR waiting was tested with fixtures without logging the real account out.
- The first live scan exposed duplicate phone/LID entries; this release now resolves LIDs through the local WA-JS phone cache before deduplicating and preserves the actual chat ID.
- The bundled WA-JS library emitted initialization compatibility errors concerning isLidMigrated and func. The tested reads and exports completed, but other WhatsApp operations still need live compatibility checks.

## Limits

This is a local beta, not a claim of 100% WAXP equivalence. WAXP subscription activation, billing and its remote services are not implemented. Clone WhatsApp Group and Destroy Group are clearly marked Coming Soon, matching their unavailable status in the observed WAXP version.

Only data available to the connected WhatsApp Web session can be read. Unresolved `@lid` identifiers are never treated as phone numbers. Unknown saved status is excluded from Unsaved. Country is an estimate from a limited calling-code map, not a person's location; unsupported codes show Unknown and +1 is grouped as US / Canada / NANP. Group unread uses the group's chat status, not the individual member's unread status. Group member lists are cached until the panel is reopened. Timezone is stored metadata; automatic timezone inference and a live world clock are not implemented.

WhatsApp changes can break the integration. If a scan fails, automatic scanning pauses; reload WhatsApp and click Scan. Avoid multiple integration extensions in one tab during compatibility testing. If a WPP instance already exists, the extension uses it rather than replacing it.

Bulk operations affect real WhatsApp chats when used on a live session. Archive can remove a pinned position; unarchive does not automatically restore that pin. Deleting a chat is not reversible through this extension. Privacy masking is visual only, not encryption.

## Data and permissions

The extension requests sidePanel, scripting, storage and access only to `https://web.whatsapp.com/*`. Application code has no backend, analytics or contact upload. WhatsApp itself continues to use its normal network services. Local notes remain in this browser's extension storage until the extension is removed. Exports are ordinary local files.

## Libraries

- WPPConnect WA-JS 4.7.2, Apache-2.0. The official unmodified npm bundle and its license are in `extension/vendor`.
- JSZip 3.10.1, license included in `extension/vendor`.
- Application UI and icons are independently implemented. This project is not affiliated with WhatsApp, Meta, WAXP or Codegena.

## Development

Node 24+: `node --test tests/core.test.mjs tests/worker.test.mjs`.
Browser verification: `node tests/browser.mjs`. The script uses an isolated Edge profile and synthetic data; adjust the local Playwright and Edge paths on another computer.

See `work/v0.2.0/verification.json` for the fixture browser report and `work/v0.2.0/live-verification.json` for the local live-session report. Fixture screenshots and exports are in that folder. The source ZIP excludes browser profiles, real WhatsApp data and old release archives.
