@tx5dr/contracts 1.7.12 → 2.5.0

package/src/schema/__tests__/radio.schema.test.ts

@@ -1,5 +1,70 @@
 import { describe, expect, it } from 'vitest';
-import { PresetFrequencySchema } from '../radio.schema.js';
+import { DdsFrequencyRequestSchema, DigitalModeRadioModePreferenceSchema, HamlibConfigSchema, PresetFrequencySchema, RadioInfoSchema } from '../radio.schema.js';
+
+describe('HamlibConfigSchema digital mode radio mode preference', () => {
+  it('accepts legacy configs without a digital mode radio mode preference', () => {
+    const parsed = HamlibConfigSchema.parse({ type: 'none' });
+
+    expect(parsed.digitalModeRadioMode).toBeUndefined();
+  });
+
+  it('accepts supported FT8/FT4 radio mode preferences', () => {
+    expect(DigitalModeRadioModePreferenceSchema.parse('none')).toBe('none');
+    expect(DigitalModeRadioModePreferenceSchema.parse('usb')).toBe('usb');
+    expect(DigitalModeRadioModePreferenceSchema.parse('usb-data')).toBe('usb-data');
+    expect(HamlibConfigSchema.parse({ type: 'serial', digitalModeRadioMode: 'usb-data' }).digitalModeRadioMode).toBe('usb-data');
+  });
+
+  it('rejects invalid FT8/FT4 radio mode preferences', () => {
+    expect(() => HamlibConfigSchema.parse({ type: 'none', digitalModeRadioMode: 'lsb-data' })).toThrow();
+  });
+});
+
+describe('HamlibConfigSchema TCI connection', () => {
+  it('accepts TCI configs and applies SunSDR defaults', () => {
+    const parsed = HamlibConfigSchema.parse({
+      type: 'tci',
+      tci: {},
+    });
+
+    expect(parsed.tci).toMatchObject({
+      host: '127.0.0.1',
+      port: 40001,
+      receiver: 0,
+      trx: 0,
+      vfo: 0,
+      audioEnabled: true,
+      audioSampleRate: 12000,
+    });
+  });
+
+  it('accepts only credential-free WebSocket URLs for TCI', () => {
+    expect(() => HamlibConfigSchema.parse({ type: 'tci', tci: { url: 'wss://radio.example/tci' } })).not.toThrow();
+    expect(() => HamlibConfigSchema.parse({ type: 'tci', tci: { url: 'https://radio.example/tci' } })).toThrow();
+    expect(() => HamlibConfigSchema.parse({ type: 'tci', tci: { url: 'ws://user:secret@radio.example/tci' } })).toThrow();
+  });
+
+  it('accepts TCI as a reported radio connection type', () => {
+    const parsed = RadioInfoSchema.parse({
+      manufacturer: 'Expert Electronics',
+      model: 'SunSDR',
+      connectionType: 'tci',
+    });
+
+    expect(parsed.connectionType).toBe('tci');
+  });
+});
+
+describe('DdsFrequencyRequestSchema', () => {
+  it('accepts non-negative center frequency and receiver values', () => {
+    expect(DdsFrequencyRequestSchema.parse({ frequency: 14_075_000, receiver: 0 })).toEqual({ frequency: 14_075_000, receiver: 0 });
+  });
+
+  it('rejects invalid center frequency and receiver values', () => {
+    expect(() => DdsFrequencyRequestSchema.parse({ frequency: -1 })).toThrow();
+    expect(() => DdsFrequencyRequestSchema.parse({ frequency: 14_075_000, receiver: 0.5 })).toThrow();
+  });
+});
 
 describe('PresetFrequencySchema repeater DUP fields', () => {
   it('accepts existing presets without repeater DUP fields', () => {
@@ -71,6 +136,48 @@ describe('PresetFrequencySchema repeater DUP fields', () => {
   });
 });
 
+describe('PresetFrequencySchema dial frequency precision', () => {
+  it('accepts integer-Hz presets represented by up to six MHz decimal places', () => {
+    const parsed = PresetFrequencySchema.parse({
+      band: '4MHz',
+      mode: 'FAX',
+      radioMode: 'USB',
+      frequency: 4_233_100,
+    });
+
+    expect(parsed.frequency).toBe(4_233_100);
+  });
+
+  it('accepts marine FAX assigned-frequency and emission metadata', () => {
+    const parsed = PresetFrequencySchema.parse({
+      band: '4MHz',
+      mode: 'FAX',
+      radioMode: 'USB',
+      frequency: 4_197_850,
+      assignedFrequency: 4_199_750,
+      audioCenterHz: 1_900,
+      faxEmission: 'F3C',
+      imagePurpose: 'weatherfax',
+    });
+
+    expect(parsed.assignedFrequency).toBe(4_199_750);
+    expect(parsed.faxEmission).toBe('F3C');
+  });
+
+  it('rejects fractional-Hz and out-of-range preset frequencies', () => {
+    expect(() => PresetFrequencySchema.parse({
+      band: '20m',
+      mode: 'SSTV',
+      frequency: 14_230_000.5,
+    })).toThrow();
+    expect(() => PresetFrequencySchema.parse({
+      band: 'custom',
+      mode: 'VOICE',
+      frequency: 1_000_000_001,
+    })).toThrow();
+  });
+});
+
 describe('PresetFrequencySchema tone squelch fields', () => {
   it('accepts CTCSS tone presets with positive 0.1 Hz values', () => {
     const parsed = PresetFrequencySchema.parse({

package/src/schema/__tests__/realtime-settings.schema.test.ts

@@ -9,9 +9,10 @@ import {
 } from '../realtime.schema.js';
 
 describe('Realtime transport schemas', () => {
-  it('accepts only rtc-data-audio and ws-compat transports', () => {
+  it('accepts realtime network transports plus the Android native diagnostics transport', () => {
     expect(RealtimeTransportKindSchema.parse('rtc-data-audio')).toBe('rtc-data-audio');
     expect(RealtimeTransportKindSchema.parse('ws-compat')).toBe('ws-compat');
+    expect(RealtimeTransportKindSchema.parse('android-native')).toBe('android-native');
     const retiredTransport = 'live' + 'kit';
     expect(() => RealtimeTransportKindSchema.parse(retiredTransport)).toThrow();
     expect(() => RealtimeSessionRequestSchema.parse({

package/src/schema/__tests__/remote-access.schema.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isSecureRemoteAccessOrigin,
+  normalizeRemoteAccessOrigin,
+} from '../auth.schema.js';
+
+describe('remote access origins', () => {
+  it('normalizes exact browser origins and rejects paths or credentials', () => {
+    expect(normalizeRemoteAccessOrigin('https://radio.example.com/')).toBe('https://radio.example.com');
+    expect(normalizeRemoteAccessOrigin('http://10.8.0.2:8076')).toBe('http://10.8.0.2:8076');
+    expect(normalizeRemoteAccessOrigin('https://radio.example.com/tx5dr')).toBeNull();
+    expect(normalizeRemoteAccessOrigin('https://user:pass@radio.example.com')).toBeNull();
+  });
+
+  it('identifies origins with transport security without enforcing public-access policy', () => {
+    expect(isSecureRemoteAccessOrigin('https://radio.example.com')).toBe(true);
+    expect(isSecureRemoteAccessOrigin('http://radio.example.com')).toBe(false);
+    expect(isSecureRemoteAccessOrigin('http://203.0.113.10:8076')).toBe(false);
+    expect(isSecureRemoteAccessOrigin('http://192.168.1.20:8076')).toBe(true);
+    expect(isSecureRemoteAccessOrigin('http://100.64.0.2:8076')).toBe(true);
+  });
+});

package/src/schema/__tests__/spectrum.schema.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { SpectrumFrameSchema, SpectrumLevelDescriptorSchema, SpectrumSessionInteractionStateSchema } from '../spectrum.schema.js';
+import {
+  SpectrumSettingsResponseSchema,
+  SpectrumSettingsUpdateRequestSchema,
+  TciSpectrumSettingsSchema,
+  getSpectrumPresetDefinition,
+} from '../spectrum-config.schema.js';
+
+describe('spectrum level descriptor schema', () => {
+  it('accepts dBFS, calibrated dB and raw Level descriptors', () => {
+    for (const level of [
+      { domain: 'dbfs', unit: 'dBFS', reference: 'full-scale', calibrated: true, min: -120, max: 0 },
+      { domain: 'calibrated-db', unit: 'dB', reference: 'device', calibrated: true, min: -130, max: 10 },
+      { domain: 'raw', unit: 'Level', reference: 'none', calibrated: false, min: 0, max: 255 },
+    ]) {
+      expect(SpectrumLevelDescriptorSchema.safeParse(level).success).toBe(true);
+    }
+  });
+
+  it('rejects invalid or non-increasing level ranges', () => {
+    expect(SpectrumLevelDescriptorSchema.safeParse({
+      domain: 'raw',
+      unit: 'dBFS',
+      reference: 'none',
+      calibrated: false,
+      min: 255,
+      max: 0,
+    }).success).toBe(false);
+  });
+
+  it('keeps level optional for old spectrum frames', () => {
+    const result = SpectrumFrameSchema.safeParse({
+      timestamp: 1,
+      kind: 'radio-sdr',
+      frequencyRange: { min: 7_000_000, max: 7_100_000 },
+      binaryData: {
+        data: 'AA==',
+        format: { type: 'int16', length: 1 },
+      },
+      meta: {
+        sourceBinCount: 1,
+        displayBinCount: 1,
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('defaults legacy interaction state to radio-center and accepts split TX targets', () => {
+    const interaction = SpectrumSessionInteractionStateSchema.parse({
+      showTxMarkers: false,
+      showRxMarkers: false,
+      canDragTx: false,
+      canRightClickSetFrequency: false,
+      canDoubleClickSetFrequency: false,
+      canDragFrequency: false,
+      frequencyGestureTarget: null,
+      frequencyStepHz: null,
+      presetMarkers: [],
+      frequencyOverlays: [{
+        id: 'split',
+        label: 'TX',
+        lineFrequency: 14_052_500,
+        rangeStartFrequency: 14_052_500,
+        rangeEndFrequency: 14_052_500,
+        variant: 'tx',
+        draggable: true,
+        frequencyTarget: 'split-frequency',
+      }],
+      canDragVoiceOverlay: false,
+      showVoiceOverlay: false,
+      canLocalViewportZoom: false,
+      canLocalViewportPan: false,
+      supportsManualRange: true,
+      supportsAutoRange: false,
+      defaultRangeMode: 'manual',
+    });
+    expect(interaction.viewMode).toBe('radio-center');
+    expect(interaction.viewport.enabled).toBe(false);
+    expect(interaction.frequencyOverlays[0]?.frequencyTarget).toBe('split-frequency');
+  });
+});
+
+describe('spectrum analysis settings schemas', () => {
+  it('validates preset updates and derived render settings', () => {
+    expect(SpectrumSettingsUpdateRequestSchema.parse({ preset: 'fine' })).toEqual({ preset: 'fine' });
+    const balanced = getSpectrumPresetDefinition('balanced');
+    expect(SpectrumSettingsResponseSchema.parse({
+      success: true,
+      currentSettings: { ...balanced, revision: 3 },
+      presets: [getSpectrumPresetDefinition('responsive'), balanced, getSpectrumPresetDefinition('fine')],
+    }).currentSettings.displayBinCount).toBe(4097);
+  });
+
+  it('rejects arbitrary analysis parameters', () => {
+    expect(() => SpectrumSettingsUpdateRequestSchema.parse({ preset: 'custom', fftSize: 4096 })).toThrow();
+  });
+
+  it('accepts a validated custom analysis draft', () => {
+    expect(SpectrumSettingsUpdateRequestSchema.parse({
+      preset: 'custom',
+      settings: {
+        analysisIntervalMs: 275,
+        fftSize: 4096,
+        targetSampleRate: 8000,
+        windowFunction: 'hann',
+        haloReduce: true,
+      },
+    }).preset).toBe('custom');
+  });
+
+  it('accepts high-performance TCI analysis settings within the supported bounds', () => {
+    expect(TciSpectrumSettingsSchema.parse({
+      fftSize: 65536,
+      displayBinCount: 16384,
+      analysisIntervalMs: 20,
+    })).toEqual({ fftSize: 65536, displayBinCount: 16384, analysisIntervalMs: 20 });
+  });
+});

package/src/schema/__tests__/strategy-transmission.schema.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import {
+  OperatorStatusSchema,
+  StrategyStreamSnapshotSchema,
+  StrategyTransmissionSchema,
+  WSMessageSchema,
+} from '../../index.js';
+
+describe('strategy transmission contracts', () => {
+  it('carries the current multi-stream transmission set in operator status', () => {
+    const currentTransmissions = [
+      { streamId: 'stream-1', text: 'JA1AAA BG5DRB OL32', audioFrequencyHz: 1200 },
+      { streamId: 'stream-2', text: 'JA2BBB BG5DRB R PM95', audioFrequencyHz: 1320 },
+      { streamId: 'stream-3', text: 'JA3CCC BG5DRB RR73', audioFrequencyHz: 1440 },
+    ];
+
+    expect(StrategyTransmissionSchema.parse(currentTransmissions[0])).toEqual(currentTransmissions[0]);
+    expect(OperatorStatusSchema.parse({
+      id: 'operator-1',
+      isActive: true,
+      isTransmitting: true,
+      hasTransmitIntent: true,
+      currentTransmissions,
+      currentSlot: 'parallel',
+      context: {
+        myCall: 'BG5DRB',
+        myGrid: 'OL32',
+        targetCalls: ['JA1AAA', 'JA2BBB', 'JA3CCC'],
+        targetCall: 'JA1AAA',
+      },
+      strategy: {
+        name: 'ww-digi',
+        state: 'parallel',
+        availableSlots: ['TX6'],
+      },
+    })).toMatchObject({
+      currentTransmissions,
+      context: { targetCalls: ['JA1AAA', 'JA2BBB', 'JA3CCC'] },
+    });
+  });
+
+  it('rejects empty text and invalid audio frequencies', () => {
+    expect(StrategyTransmissionSchema.safeParse({
+      streamId: 'stream-1',
+      text: '',
+      audioFrequencyHz: 1200,
+    }).success).toBe(false);
+    expect(StrategyTransmissionSchema.safeParse({
+      streamId: 'stream-1',
+      text: 'CQ WW BG5DRB OL32',
+      audioFrequencyHz: 5001,
+    }).success).toBe(false);
+  });
+
+  it('accepts strategy-defined stream states and a lifecycle-scoped switch command', () => {
+    expect(StrategyStreamSnapshotSchema.parse({
+      streamId: 'stream-7',
+      currentState: 'awaiting-confirmation',
+      audioFrequencyHz: 1320,
+      qsoLifecycleEpoch: 4,
+      stateOptions: [{
+        id: 'send-final',
+        label: 'stateSendFinal',
+        transmitText: 'JA1AAA BG5DRB RR73',
+      }],
+    }).stateOptions?.[0]?.id).toBe('send-final');
+
+    expect(WSMessageSchema.parse({
+      type: 'setOperatorStreamState',
+      timestamp: new Date().toISOString(),
+      data: {
+        operatorId: 'operator-1',
+        streamId: 'stream-7',
+        stateId: 'send-final',
+        expectedLifecycleEpoch: 4,
+      },
+    }).type).toBe('setOperatorStreamState');
+  });
+
+  it('accepts plugin-declared actions and lifecycle-scoped action invocations', () => {
+    const stream = StrategyStreamSnapshotSchema.parse({
+      streamId: 'stream-1',
+      currentState: 'recovering',
+      audioFrequencyHz: 1500,
+      qsoLifecycleEpoch: 7,
+      completion: { state: 'committed', recordId: 'qso-1' },
+      attentions: [{ id: 'needs-action', tone: 'warning', title: 'attentionTitle', actionIds: ['reply'] }],
+      actions: [{
+        id: 'reply', label: 'replyLabel', icon: 'paper-plane', tone: 'primary', presentation: 'primary',
+        input: { kind: 'audio-frequency', value: 1500, min: 100, max: 5000, step: 10, spectrumPick: true },
+      }],
+    });
+    expect(stream.actions?.[0]?.id).toBe('reply');
+
+    expect(WSMessageSchema.parse({
+      type: 'invokeOperatorStrategyAction',
+      timestamp: new Date().toISOString(),
+      data: {
+        operatorId: 'operator-1',
+        target: { kind: 'stream', streamId: 'stream-1', lifecycleEpoch: 7 },
+        actionId: 'reply',
+        payload: { value: 1600 },
+      },
+    }).type).toBe('invokeOperatorStrategyAction');
+  });
+});

package/src/schema/android-operator-audio.schema.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+export const AndroidOperatorAudioDeviceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  kind: z.string(),
+  socketPath: z.string(),
+  sampleRate: z.number().int().positive(),
+  connected: z.boolean().optional(),
+});
+export type AndroidOperatorAudioDevice = z.infer<typeof AndroidOperatorAudioDeviceSchema>;
+
+export const AndroidOperatorAudioCaptureStateSchema = z.enum(['idle', 'preparing', 'capturing', 'error']);
+export type AndroidOperatorAudioCaptureState = z.infer<typeof AndroidOperatorAudioCaptureStateSchema>;
+
+export const AndroidOperatorAudioMonitorStateSchema = z.enum(['idle', 'starting', 'playing', 'paused-for-ptt', 'error']);
+export type AndroidOperatorAudioMonitorState = z.infer<typeof AndroidOperatorAudioMonitorStateSchema>;
+
+export const AndroidOperatorAudioStatusSchema = z.object({
+  available: z.boolean(),
+  captureState: AndroidOperatorAudioCaptureStateSchema,
+  monitorState: AndroidOperatorAudioMonitorStateSchema,
+  participantIdentity: z.string().nullable(),
+  inputLevel: z.number().min(0).max(1),
+  inputPeak: z.number().min(0).max(1),
+  rawInputLevel: z.number().min(0).max(1).optional(),
+  rawInputPeak: z.number().min(0).max(1).optional(),
+  inputSilenced: z.boolean(),
+  micGainDb: z.number(),
+  micGainMinDb: z.number(),
+  micGainMaxDb: z.number(),
+  monitorGainDb: z.number(),
+  monitorGainMinDb: z.number(),
+  monitorGainMaxDb: z.number(),
+  micDevice: AndroidOperatorAudioDeviceSchema.nullable(),
+  speakerDevice: AndroidOperatorAudioDeviceSchema.nullable(),
+  lastError: z.string().nullable(),
+});
+export type AndroidOperatorAudioStatus = z.infer<typeof AndroidOperatorAudioStatusSchema>;
+
+export const AndroidOperatorAudioGainUpdateSchema = z.object({
+  micGainDb: z.number(),
+});
+export type AndroidOperatorAudioGainUpdate = z.infer<typeof AndroidOperatorAudioGainUpdateSchema>;
+
+export const AndroidOperatorAudioMonitorGainUpdateSchema = z.object({
+  monitorGainDb: z.number(),
+});
+export type AndroidOperatorAudioMonitorGainUpdate = z.infer<typeof AndroidOperatorAudioMonitorGainUpdateSchema>;

package/src/schema/api-response.schema.ts

@@ -132,6 +132,7 @@ export const LastFrequencyResponseSchema = z.object({
     band: z.string(),
     description: z.string().optional(),
   }).nullable().optional(),
+  lastImageFrequency: PresetFrequencySchema.nullable().optional(),
 });
 
 /**
@@ -150,6 +151,15 @@ export const SetFrequencyResponseSchema = z.object({
   ctcssToneTenthsHz: z.number().optional(),
   dcsCode: z.number().optional(),
   radioConnected: z.boolean().optional(),
+  confirmation: z.enum(['confirmed', 'pending', 'mismatch', 'offline']).optional(),
+  observedFrequency: z.number().optional(),
+  operationId: z.string().optional(),
+});
+
+export const SetDdsFrequencyResponseSchema = z.object({
+  success: z.literal(true),
+  frequency: z.number(),
+  receiver: z.number().int().nonnegative(),
 });
 
 // ========== 时隙包相关响应 ==========
@@ -203,6 +213,7 @@ export type DisconnectRadioResponse = z.infer<typeof DisconnectRadioResponseSche
 
 export type LastFrequencyResponse = z.infer<typeof LastFrequencyResponseSchema>;
 export type SetFrequencyResponse = z.infer<typeof SetFrequencyResponseSchema>;
+export type SetDdsFrequencyResponse = z.infer<typeof SetDdsFrequencyResponseSchema>;
 
 export type SlotPacksResponse = z.infer<typeof SlotPacksResponseSchema>;
 export type SlotPackResponse = z.infer<typeof SlotPackResponseSchema>;

package/src/schema/audio-sidecar.schema.ts

@@ -29,6 +29,29 @@ export const AudioSidecarErrorSchema = z.object({
 
 export type AudioSidecarError = z.infer<typeof AudioSidecarErrorSchema>;
 
+export const AudioSidecarPhaseSchema = z.enum([
+  'startStream',
+  'startOutput',
+  'runtime',
+]);
+
+export const AudioSidecarClassificationSchema = z.enum([
+  'startup-failure',
+  'runtime-loss',
+  'sample-rate-fallback',
+  'sample-rate-fallback-failed',
+  'device-unavailable',
+  'disabled',
+]);
+
+export const AudioSidecarFallbackSchema = z.object({
+  active: z.boolean(),
+  fromSampleRate: z.number().int().positive().nullable(),
+  toSampleRate: z.number().int().positive().nullable(),
+  persisted: z.boolean().optional(),
+  reason: z.string().optional(),
+});
+
 /**
  * AudioSidecar 状态变化载荷。
  * 前端以此渲染 RadioControl 中的音频副状态 spinner + Popover。
@@ -48,6 +71,18 @@ export const AudioSidecarStatusPayloadSchema = z.object({
   lastError: AudioSidecarErrorSchema.nullable(),
   /** 当前目标设备名（来自 AudioConfig.inputDeviceName） */
   deviceName: z.string().nullable(),
+  /** 当前失败/重试阶段 */
+  phase: AudioSidecarPhaseSchema.optional(),
+  /** 机器可读的失败分类，用于 UI 展示和诊断 */
+  classification: AudioSidecarClassificationSchema.optional(),
+  /** 具体受影响的输入/输出设备名 */
+  affectedDeviceName: z.string().nullable().optional(),
+  /** 失败时使用的采样率 */
+  sampleRate: z.number().int().positive().nullable().optional(),
+  /** 自动降级状态 */
+  fallback: AudioSidecarFallbackSchema.optional(),
+  /** 当前重试原因摘要 */
+  retryReason: z.string().optional(),
 });
 
 export type AudioSidecarStatusPayload = z.infer<typeof AudioSidecarStatusPayloadSchema>;