ldb-ws-contracts

Shared Socket.IO event types between the MT-LDB backend (apps/api/src/notifications/notifications.gateway.ts) and any front-end that subscribes to it.

Types only — zero runtime code, zero dependencies. The package exists so a payload change is a compile error on both sides instead of a silent field rename.

npm i @comradeweb/ldb-ws-contracts

In this monorepo it is a workspace dependency (@comradeweb/ldb-ws-contracts); consumers are libs/application/src/notification/ports/notification.port.ts and libs/application/src/auth-state/ports/auth-state.port.ts.

The event map

NotificationEventMap is the single source of truth: Socket.IO event name → payload type. NotificationEventName is its key union — use it to type an emitter or a subscription so an unknown event name can't compile.

| Event | Payload | What it signals | | --- | --- | --- | | entity-changed | EntityChangedData | Lightweight invalidation signal for backlink / ref-domain / project / import-session — created / updated / deleted plus the id. Not a data push: the client refetches. | | backlink-check-progress · -completed · -error | BacklinkCheckProgressData / …CompletedData / …ErrorData | Per-check lifecycle, keyed by checkId + backlinkId. | | import-progress · import-completed | ImportProgressData / ImportCompletedData | CSV import, keyed by sessionId. phase is validating | creating. | | auth-state-changed | AuthStateChangedData | A browser-service's session flipped: ok | lost | challenge | unknown, with feature and an optional reason. | | disavow-progress | DisavowProgressData | One per-project settle within a disavow run. | | disavow-run-status | DisavowRunStatusData | Run-level lifecycle: running | cancelling | completed | cancelled | failed. |

Note on the disavow counters: disavow-progress carries the live ok / skipped / total; failed is derived as total - ok - skipped (client-side, or at finalize). disavow-run-status carries all four explicitly.

Usage

import type {
  NotificationEventMap,
  NotificationEventName,
} from '@comradeweb/ldb-ws-contracts';

function on<E extends NotificationEventName>(
  event: E,
  handler: (data: NotificationEventMap[E]) => void,
): void {
  socket.on(event, handler);
}

Changing a payload

This package is published and consumed by front-ends that deploy on their own schedule. Removing or renaming a field is a breaking change — add the new field alongside the old one, ship both sides, then remove. Bump the version and record the change in CHANGELOG.md.

pnpm --filter @comradeweb/ldb-ws-contracts build