fix(qrz): rewrite auto-sync onto the API-key path, delete phantom status system

[patrickrb]

Problem

"Uploads to QRZ silently do nothing." The auto-sync path was doubly broken and perfectly silent about it:

1. Wrong API. uploadQSOToQRZ did a username/password handshake against logbook.qrz.com/api, expecting a KEY= session token back. The QRZ Logbook API only accepts pre-issued logbook API keys (stations.qrz_api_key); username/password belongs to the XML lookup API on a different host. The handshake never yields a key, so every upload failed.
2. Phantom columns. Results were recorded via Contact.updateQrzSyncStatus into qrz_sync_status / qrz_sync_date / qrz_logbook_id / qrz_sync_error — columns that exist in no migration and no schema (only an orphaned enum type was ever created). Every status UPDATE threw. The same phantom write ran on every contact edit (PUT /api/contacts/[id]).
3. Swallowed errors. backgroundAutoSync ended in .catch(() => {}), and on Vercel the bare fire-and-forget promise is frozen when the response returns, so the sync often never even ran.
4. The UI (QRZSyncIndicator) reads qrz_qsl_sent/rcvd — a different system than auto-sync wrote, so even a hypothetical success would have shown nothing.

Fix

• New src/lib/qrz-sync-service.ts — single home for QRZ sync, shared by on-save auto-sync, the per-contact route, the bulk route, and the upcoming sync cron:
  • syncContactToQrz — station API key via uploadQSOToQRZWithApiKey, records into qrz_qsl_* (the columns the UI reads). 'M' (modified) rows re-upload with OPTION=REPLACE; failures mark 'R' and are retried on every sweep; duplicates mark sent+confirmed.
  • uploadPendingForStation — station-scoped sweep over findQrzNotSent (now NULL/'N'/'R'/'M', excluding 'I').
  • downloadConfirmationsForStation — extracted from the download route, now with an incremental MODSINCE cursor in stations.qrz_last_qsl_rcvd_date (column existed but was never used).
• Auto-sync runs inside after() from next/server and logs every failure; contact edits flag shipped copies 'Y' → 'M' via new Contact.flagForReupload (QRZ and LoTW).
• Deleted: uploadQSOToQRZ, Contact.updateQrzSyncStatus, dead Contact.matchQSO, dead generateAdifForLoTW, the phantom ContactData fields. Migration 0004 drops the orphaned qrz_sync_status_enum type.
• Renamed the misleading /api/contacts?qrz_sync_status=not_synced param to qrz_filter=not_sent (admin page updated in the same PR).

Response shapes of /api/contacts/[id]/qrz-sync, /api/contacts/qrz-sync, and /api/contacts/qrz-download are preserved for the search/admin pages.

Notes for reviewers

• User-level qrz_username/qrz_password remain — they are legitimately used for XML callsign lookups. Auto-sync is still gated on users.qrz_auto_sync.
• Stations without a qrz_api_key now get a visible logger.warn on auto-sync instead of nothing; PR 5 in this series adds the sync-activity UI.

Verification

• npm run lint / npm run typecheck / npm run build clean.
• Second PR of the sync-reliability series (after fix(lotw): confirmations never applied - duplicate qsl_lotw_date assignment (42601) #218).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nodelog	Ready	Preview, Comment	Jul 13, 2026 5:14pm

[Copilot]

Pull request overview

This PR refactors QRZ Logbook auto-sync to use station-scoped QRZ Logbook API keys (instead of the legacy username/password flow), consolidating upload/download logic into a dedicated service and removing the previous “phantom status” tracking that referenced nonexistent schema columns.

Changes:

• Introduces src/lib/qrz-sync-service.ts as the single implementation for QRZ upload sweeps and confirmation downloads, persisting state via the existing qrz_qsl_* fields.
• Reworks auto-sync to run via next/server after() (instead of fire-and-forget promises) and flags already-uploaded QSOs for re-upload using the 'M' marker.
• Removes legacy QRZ upload code paths and drops the orphaned qrz_sync_status_enum type via migration 0004.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/models/Station.ts	Adds QRZ download cursor field and a helper to advance it after successful fetches.
src/models/Contact.ts	Removes phantom QRZ sync fields; updates pending-upload query; adds reupload flagging method.
src/lib/qrz.ts	Removes legacy username/password QRZ logbook upload function.
src/lib/qrz-sync-service.ts	New centralized QRZ sync service used by routes and auto-sync.
src/lib/qrz-auto-sync.ts	Auto-sync rewritten to use station API key + centralized service with logging.
src/lib/lotw.ts	Removes dead LoTW ADIF generation helper.
src/app/api/contacts/route.ts	Renames QRZ filter param; runs auto-sync via after() on create.
src/app/api/contacts/qrz-sync/route.ts	Bulk QRZ sync route now delegates to the sync service and caches stations.
src/app/api/contacts/qrz-download/route.ts	QRZ download route now delegates confirmation logic to the sync service.
src/app/api/contacts/[id]/route.ts	Flags re-upload on core edits and runs auto-sync via after().
src/app/api/contacts/[id]/qrz-sync/route.ts	Per-contact QRZ sync now uses station API key + sync service.
src/app/admin/page.tsx	Updates admin fetch to use the renamed qrz_filter=not_sent query param.
drizzle/migrations/meta/0004_snapshot.json	Adds migration snapshot metadata for the new migration state.
drizzle/migrations/meta/_journal.json	Registers migration 0004_drop_orphaned_qrz_sync_status_enum.
drizzle/migrations/0004_drop_orphaned_qrz_sync_status_enum.sql	Drops the orphaned qrz_sync_status_enum type.