@tx5dr/contracts 1.7.2 → 1.7.4

package/src/utils/__tests__/cwTiming.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import {
+  encodeTextToCWEvents,
+  encodeTextToCWKeyStateSegments,
+  estimateCWMessageDurationMs,
+} from '../cwTiming.js';
+
+function totalSegmentDuration(text: string, wpm: number): number {
+  return encodeTextToCWKeyStateSegments(text, wpm).reduce((sum, segment) => sum + segment.durationMs, 0);
+}
+
+describe('CW timing utilities', () => {
+  it('returns no events and zero duration for blank text', () => {
+    expect(encodeTextToCWEvents('   ', 20)).toEqual([]);
+    expect(encodeTextToCWKeyStateSegments('   ', 20)).toEqual([]);
+    expect(estimateCWMessageDurationMs('', 20)).toBe(0);
+  });
+
+  it('encodes exact key events for simple characters and spacing', () => {
+    expect(encodeTextToCWEvents('E', 20)).toEqual([
+      { type: 'key-down', afterMs: 0 },
+      { type: 'key-up', afterMs: 60 },
+    ]);
+
+    expect(encodeTextToCWEvents('EE', 20)).toEqual([
+      { type: 'key-down', afterMs: 0 },
+      { type: 'key-up', afterMs: 60 },
+      { type: 'key-down', afterMs: 180 },
+      { type: 'key-up', afterMs: 60 },
+    ]);
+
+    expect(encodeTextToCWEvents('E E', 20)).toEqual([
+      { type: 'key-down', afterMs: 0 },
+      { type: 'key-up', afterMs: 60 },
+      { type: 'key-down', afterMs: 420 },
+      { type: 'key-up', afterMs: 60 },
+    ]);
+
+    expect(encodeTextToCWEvents('A', 20)).toEqual([
+      { type: 'key-down', afterMs: 0 },
+      { type: 'key-up', afterMs: 60 },
+      { type: 'key-down', afterMs: 60 },
+      { type: 'key-up', afterMs: 180 },
+    ]);
+  });
+
+  it('encodes exact key state segments for browser sidetone adapters', () => {
+    expect(encodeTextToCWKeyStateSegments('E', 20)).toEqual([
+      { keyDown: true, durationMs: 60 },
+    ]);
+
+    expect(encodeTextToCWKeyStateSegments('EE', 20)).toEqual([
+      { keyDown: true, durationMs: 60 },
+      { keyDown: false, durationMs: 180 },
+      { keyDown: true, durationMs: 60 },
+    ]);
+
+    expect(encodeTextToCWKeyStateSegments('E E', 20)).toEqual([
+      { keyDown: true, durationMs: 60 },
+      { keyDown: false, durationMs: 420 },
+      { keyDown: true, durationMs: 60 },
+    ]);
+
+    expect(encodeTextToCWKeyStateSegments('A', 20)).toEqual([
+      { keyDown: true, durationMs: 60 },
+      { keyDown: false, durationMs: 60 },
+      { keyDown: true, durationMs: 180 },
+    ]);
+  });
+
+  it('scales duration by WPM', () => {
+    expect(estimateCWMessageDurationMs('EE', 20)).toBe(300);
+    expect(estimateCWMessageDurationMs('EE', 40)).toBe(150);
+  });
+
+  it('uses the Hamlib/PARIS exact dot duration for non-divisible WPM values', () => {
+    expect(estimateCWMessageDurationMs('EE', 17)).toBe(353);
+  });
+
+  it('treats prosigns as single Morse tokens rather than re-encoding dots and dashes', () => {
+    expect(estimateCWMessageDurationMs('<SK>', 20)).toBe(900);
+    expect(totalSegmentDuration('<SK>', 20)).toBe(900);
+    expect(totalSegmentDuration('<CL>', 20)).toBeGreaterThan(0);
+  });
+
+  it('keeps unsupported-character and WPM clamp behavior', () => {
+    expect(estimateCWMessageDurationMs('E☃E', 20)).toBe(300);
+    expect(estimateCWMessageDurationMs('E', 1)).toBe(240);
+    expect(estimateCWMessageDurationMs('E', 1000)).toBe(20);
+  });
+});

package/src/utils/callsign.ts

@@ -0,0 +1,9 @@
+const CALLSIGN_WHITESPACE_REGEX = /\s+/g;
+
+export function sanitizeCallsignInput(callsign?: string | null): string {
+  if (!callsign) {
+    return '';
+  }
+
+  return callsign.toUpperCase().replace(CALLSIGN_WHITESPACE_REGEX, '');
+}

package/src/utils/cwTiming.ts

@@ -0,0 +1,203 @@
+/**
+ * CW text to Morse timing encoder.
+ *
+ * Timing follows the ITU/PARIS convention:
+ * - dit = 1200 / WPM ms
+ * - dah = 3 dits
+ * - intra-character gap = 1 dit
+ * - character gap = 3 dits
+ * - word gap = 7 dits
+ */
+export interface CWTimingEvent {
+  type: 'key-down' | 'key-up';
+  /** Delay from the previous event, in milliseconds. */
+  afterMs: number;
+}
+
+export interface CWKeyStateSegment {
+  /** true when the key/tone is closed, false for silence/open key. */
+  keyDown: boolean;
+  /** Segment duration in milliseconds. */
+  durationMs: number;
+}
+
+const DOT_UNITS = {
+  dit: 1,
+  dah: 3,
+  intraChar: 1,
+  interChar: 3,
+  interWord: 7,
+} as const;
+
+const MORSE_TABLE: Record<string, string> = {
+  A: '.-',    B: '-...',  C: '-.-.',  D: '-..',
+  E: '.',     F: '..-.',  G: '--.',   H: '....',
+  I: '..',    J: '.---',  K: '-.-',   L: '.-..',
+  M: '--',    N: '-.',    O: '---',   P: '.--.',
+  Q: '--.-',  R: '.-.',   S: '...',   T: '-',
+  U: '..-',   V: '...-',  W: '.--',   X: '-..-',
+  Y: '-.--',  Z: '--..',
+  '0': '-----', '1': '.----', '2': '..---', '3': '...--',
+  '4': '....-', '5': '.....', '6': '-....', '7': '--...',
+  '8': '---..', '9': '----.',
+  '.': '.-.-.-', ',': '--..--', '?': '..--..', '/': '-..-.',
+  '@': '.--.-.', '=': '-...-', '-': '-....-', '+': '.-.-.',
+  ':': '---...', ';': '-.-.-.', '\'': '.----.', '"': '.-..-.',
+  '!': '-.-.--', '&': '.-...', '(': '-.--.', ')': '-.--.-',
+  '_': '..--.-', '$': '...-..-',
+};
+
+const PROSIGN_MAP: Record<string, string> = {
+  '<AR>': '.-.-.',
+  '<SK>': '...-.-',
+  '<BT>': '-...-',
+  '<KN>': '-.--.',
+  '<BK>': '-...-.-',
+  '<CL>': '-.-..-..',
+};
+
+const PROSIGN_TOKENS = Object.keys(PROSIGN_MAP).sort((a, b) => b.length - a.length);
+
+/**
+ * Encodes supported CW text into a sequence of timing events.
+ */
+export function encodeTextToCWEvents(text: string, wpm: number): CWTimingEvent[] {
+  const events: CWTimingEvent[] = [];
+  let nextEventDelayMs = 0;
+
+  for (const segment of encodeTextToCWKeyStateSegments(text, wpm)) {
+    if (!segment.keyDown) {
+      nextEventDelayMs += segment.durationMs;
+      continue;
+    }
+
+    events.push({ type: 'key-down', afterMs: nextEventDelayMs });
+    events.push({ type: 'key-up', afterMs: segment.durationMs });
+    nextEventDelayMs = 0;
+  }
+
+  return events;
+}
+
+/**
+ * Encodes supported CW text into key-down/silence duration segments.
+ * This is the shared adapter input for browser sidetone and other local keying outputs.
+ */
+export function encodeTextToCWKeyStateSegments(text: string, wpm: number): CWKeyStateSegment[] {
+  const dotMs = getRoundedDotMs(wpm);
+  const tokenizedWords = tokenizeText(text);
+  const segments: CWKeyStateSegment[] = [];
+  let firstToken = true;
+
+  for (const word of tokenizedWords) {
+    for (let ti = 0; ti < word.length; ti += 1) {
+      if (!firstToken) {
+        appendSegment(segments, false, (ti === 0 ? DOT_UNITS.interWord : DOT_UNITS.interChar) * dotMs);
+      }
+
+      appendCodeSegments(segments, word[ti], dotMs);
+      firstToken = false;
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Estimates total CW message duration from the first key-down to the final key-up.
+ * Uses the PARIS timing base from Hamlib: dot milliseconds = 1200 / WPM.
+ */
+export function estimateCWMessageDurationMs(text: string, wpm: number): number {
+  const safeWpm = getSafeWpm(wpm);
+  const dotUnits = countCWMessageDotUnits(text);
+  if (dotUnits <= 0) {
+    return 0;
+  }
+  return Math.ceil(dotUnits * (1200 / safeWpm));
+}
+
+function appendCodeSegments(segments: CWKeyStateSegment[], code: string, dotMs: number): void {
+  for (let si = 0; si < code.length; si += 1) {
+    if (si > 0) {
+      appendSegment(segments, false, DOT_UNITS.intraChar * dotMs);
+    }
+    appendSegment(segments, true, (code[si] === '-' ? DOT_UNITS.dah : DOT_UNITS.dit) * dotMs);
+  }
+}
+
+function appendSegment(segments: CWKeyStateSegment[], keyDown: boolean, durationMs: number): void {
+  if (durationMs <= 0) {
+    return;
+  }
+  const previous = segments[segments.length - 1];
+  if (previous?.keyDown === keyDown) {
+    previous.durationMs += durationMs;
+    return;
+  }
+  segments.push({ keyDown, durationMs });
+}
+
+function countCWMessageDotUnits(text: string): number {
+  const tokenizedWords = tokenizeText(text);
+  let firstToken = true;
+  let totalUnits = 0;
+
+  for (const word of tokenizedWords) {
+    for (let ti = 0; ti < word.length; ti += 1) {
+      if (!firstToken) {
+        totalUnits += ti === 0 ? DOT_UNITS.interWord : DOT_UNITS.interChar;
+      }
+
+      const code = word[ti];
+      for (let si = 0; si < code.length; si += 1) {
+        totalUnits += si === 0 ? 0 : DOT_UNITS.intraChar;
+        totalUnits += code[si] === '-' ? DOT_UNITS.dah : DOT_UNITS.dit;
+      }
+      firstToken = false;
+    }
+  }
+
+  return totalUnits;
+}
+
+function tokenizeText(text: string): string[][] {
+  const normalized = text.toUpperCase().trim();
+  if (!normalized) {
+    return [];
+  }
+
+  return normalized
+    .split(/\s+/)
+    .map(tokenizeWord)
+    .filter((word) => word.length > 0);
+}
+
+function tokenizeWord(word: string): string[] {
+  const codes: string[] = [];
+  let index = 0;
+
+  while (index < word.length) {
+    const prosign = PROSIGN_TOKENS.find((token) => word.startsWith(token, index));
+    if (prosign) {
+      codes.push(PROSIGN_MAP[prosign]);
+      index += prosign.length;
+      continue;
+    }
+
+    const code = MORSE_TABLE[word[index]];
+    if (code) {
+      codes.push(code);
+    }
+    index += 1;
+  }
+
+  return codes;
+}
+
+function getRoundedDotMs(wpm: number): number {
+  return Math.round(1200 / getSafeWpm(wpm));
+}
+
+function getSafeWpm(wpm: number): number {
+  return Math.max(5, Math.min(60, Math.round(Number(wpm) || 20)));
+}

package/test/decode-request-schema.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { DecodeRequestSchema } from '../src/schema/slot-info.schema.js';
+
+function makePcm(): ArrayBuffer {
+  return new Float32Array(16).buffer;
+}
+
+describe('DecodeRequestSchema', () => {
+  it('accepts legacy decode requests without AP context', () => {
+    const parsed = DecodeRequestSchema.parse({
+      slotId: 'FT8-1-15000',
+      mode: 'FT8',
+      windowIdx: 0,
+      pcm: makePcm(),
+      sampleRate: 12000,
+      windowOffsetMs: 0,
+    });
+
+    expect(parsed.apContext).toBeUndefined();
+  });
+
+  it('accepts a single AP decode context', () => {
+    const parsed = DecodeRequestSchema.parse({
+      slotId: 'FT8-1-15000',
+      mode: 'FT8',
+      windowIdx: 1,
+      pcm: makePcm(),
+      sampleRate: 12000,
+      windowOffsetMs: 0,
+      apContext: {
+        operatorId: 'op1',
+        myCall: 'BG4IAJ',
+        myGrid: 'OM96',
+        dxCall: 'JA1AAA',
+        dxGrid: 'PM95',
+        frequencyHz: 1500,
+        qsoProgress: 4,
+        currentSlot: 'TX4',
+      },
+    });
+
+    expect(parsed.apContext).toEqual(expect.objectContaining({
+      operatorId: 'op1',
+      qsoProgress: 4,
+      currentSlot: 'TX4',
+    }));
+  });
+});