type ClientIssuePayload = Record<string, unknown> | boolean | string | number;

type AddedClientIssue<T = ClientIssuePayload> = {
    type: string;
    payload?: T;
    timestamp: number;
};

type RaisedClientIssue<T = ClientIssuePayload> = {
    type: string;
    key: string;           // globally unique handle within this monitor
    payload?: T;
    raisedAt: number;
    updatedAt: number;     // bumped on every re-raise of the same key
};

type ResolvedClientIssue<T = ClientIssuePayload> = RaisedClientIssue<T> & {
    resolvedAt: number;
    comment?: string;
};

monitor.on('issue',          (issue) => { /* new addIssue or new raiseIssue */ });
monitor.on('issue-updated',  (issue) => { /* re-raise of an existing key */ });
monitor.on('issue-resolved', (resolved) => { /* resolveIssue or close() auto-resolve */ });

// Snapshot helpers
monitor.getActiveIssuesByType(type?);   // RaisedClientIssue[]
monitor.isIssueActive(key);             // boolean
monitor.activeIssues;                   // Map<string, RaisedClientIssue>

pcMonitor.issues.hasType('transport-loss-sustained');
inboundTrackMonitor.issues.getFirstPayloadByType('decoder-bottleneck');
outboundTrackMonitor.issues.size;

import {
    ClientMonitor,
    ClientMonitorIssue,
    ClientMonitorResolvedIssue,
    isClientMonitorIssue,
} from '@observertc/client-monitor-js';

monitor.on('issue', (issue) => {
    if (!isClientMonitorIssue(issue)) return;   // custom or app-raised

    switch (issue.type) {
        case 'uplink-congestion':
            // issue.payload is UplinkCongestionIssuePayload
            sender.capBitrate(issue.payload.availableOutgoingBitrate * 0.8);
            break;

        case 'av-desync':
            console.log('lip sync off by', issue.payload.playoutDiffInMs, 'ms',
                '(', issue.payload.direction, ')',
                'on', issue.payload.trackId, 'vs', issue.payload.linkedVideoTrackId);
            break;

        case 'video-flow-disrupted':
            // payload.state is 'frozen' | 'choppy'
            ui.showFreeze(issue.payload.trackId, issue.payload.state);
            break;

        case 'stuck-decoder':
            if (issue.payload.variant === 'decode') recreateConsumer(issue.payload.trackId);
            break;
    }
});

monitor.on('issue-resolved', (resolved) => {
    const own = resolved as ClientMonitorResolvedIssue;
    console.log(own.type, 'lasted', own.payload.durationInMs, 'ms');
});

monitor.raiseIssue(`unexpected-mute-${participantId}`, {
    type: 'unexpected-mute',
    payload: { participantId, sinceUtc: new Date().toISOString() },
});

// Re-raise updates in place → emits 'issue-updated', not 'issue'
monitor.raiseIssue(`unexpected-mute-${participantId}`, {
    type: 'unexpected-mute',
    payload: { participantId, framesSpoken: 0 },
});

monitor.resolveIssue(`unexpected-mute-${participantId}`, {
    comment: 'participant unmuted',
    payload: { participantId, durationInMs: Date.now() - mutedAtMs },
});

// A moment rather than a condition — no key, nothing to resolve.
monitor.addIssue({ type: 'USER_MEDIA_ERROR', payload: { error: `${err}` } });

raise:      { type: 'stuck-decoder',          key, payload,                          timestamp: raisedAt }
resolution: { type: 'stuck-decoder-resolved', key, payload: { raisedAt, comment, … }, timestamp: resolvedAt }

// Lifecycle
monitor.on('sample-created', ({ sample }) => transport.send(sample));
monitor.on('stats-collected', ({ durationOfCollectingStatsInMs, collectedStats }) => { /* … */ });
monitor.on('score', ({ clientScore, currentReasons }) => { /* … */ });
monitor.on('close', () => { /* … */ });

// Issues
monitor.on('issue',          (issue) => { /* … */ });
monitor.on('issue-updated',  (issue) => { /* … */ });
monitor.on('issue-resolved', (resolved) => { /* … */ });

// Transport quality — properties of a path that is up and holding
monitor.on('uplink-congestion',                (e) => { /* sending path out of room — graded severity */ });
monitor.on('downlink-congestion',              (e) => { /* receiving path — same shape, own evidence */ });
monitor.on('transport-delay-degraded',         (e) => { /* round trip long enough to break turn-taking */ });
monitor.on('transport-loss-sustained',         (e) => { /* `direction` says which way */ });
monitor.on('blocked-inbound-media-transport',  (e) => { /* the far end sent; nothing arrived */ });
monitor.on('blocked-outbound-media-transport', (e) => { /* we sent; nothing got through */ });
monitor.on('blocked-transport',                (e) => { /* STUN unanswered — the firewall signature */ });
monitor.on('congestion',                       (e) => { /* the deprecated one-verdict detector */ });

// Pipeline
monitor.on('capture-source-lost',      (e) => { /* the device is gone */ });
monitor.on('silent-audio-source',      (e) => { /* live mic producing digital silence */ });
monitor.on('video-capture-bottleneck', (e) => { /* the camera never produced the frames */ });
monitor.on('encoder-bottleneck',       (e) => { /* the source did; the encoder could not keep up */ });
monitor.on('rtp-sender-stalled',       (e) => { /* frames encode, no packet leaves */ });
monitor.on('dry-outbound-track',       (e) => { /* nothing going on the wire for this track */ });
monitor.on('transport-demux-stalled',  (e) => { /* traffic arrives, no inbound RTP accounts for it */ });
monitor.on('dry-inbound-track',        (e) => { /* nothing arriving */ });
monitor.on('frame-assembly-stalled',   (e) => { /* packets arriving, no frame ever assembled */ });
monitor.on('decoder-bottleneck',       (e) => { /* frames arrived; the decoder could not decode them */ });
monitor.on('video-decoder-overloaded', (e) => { /* decoding overran its budget */ });
monitor.on('stuck-decoder',            (e) => { /* RTP flowing, nothing decodes — recreate the consumer */ });
monitor.on('inbound-video-playout-discrepancy', (e) => { /* frames decoded, not painted */ });
monitor.on('video-recovery-failed',    (e) => { /* we asked for a keyframe; nothing came back */ });
monitor.on('cpulimitation',            (e) => { /* the machine is the bottleneck */ });

// Perceived quality
monitor.on('pixelated-video',           (e) => { /* too few bits per pixel, sustained */ });
monitor.on('video-flow-disrupted',      (e) => { /* `state` is 'frozen' or 'choppy' */ });
monitor.on('invented-speech',           (e) => { /* NetEQ invented audio, not raw loss */ });
monitor.on('synthesized-audio',         (e) => { /* the playout device invented samples */ });
monitor.on('av-desync',                 (e) => { /* lip sync, in ms of skew */ });
monitor.on('audio-jitter-buffer-stress',(e) => { /* buffer grown AND stretching */ });

// Telemetry — these never raise an issue
monitor.on('codec-changed',            (e) => { /* mime type or profile switched */ });
monitor.on('video-resolution-changed', (e) => { /* the adaptation ladder moved */ });
monitor.on('simulcast-layer-changed',  (e) => { /* which layers are actually being sent */ });
monitor.on('capture-track-muted',      (e) => { /* the OS or another app took it */ });
monitor.on('stats-collection-gap',     (e) => { /* discount this interval's rates */ });
monitor.on('ice-path-changed',         (e) => { /* direct <-> TURN, protocol, server */ });
monitor.on('ice-tuple-changed',        (e) => { /* low-level: the selected tuple set changed */ });
monitor.on('ice-restart',              (e) => { /* detected / recovered / failed */ });
monitor.on('ice-restart-recommended',  (e) => { /* YOUR app decides whether to restartIce() */ });
monitor.on('ice-path-establishment-slow', ({ stalledStage }) => { /* and which stage it is stuck in */ });