@tx5dr/contracts 2.0.0 → 2.5.0

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { DigitalModeRadioModePreferenceSchema, HamlibConfigSchema, PresetFrequencySchema, RadioInfoSchema } 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', () => {
@@ -38,6 +38,12 @@ describe('HamlibConfigSchema TCI connection', () => {
     });
   });
 
+  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',
@@ -49,6 +55,17 @@ describe('HamlibConfigSchema TCI connection', () => {
   });
 });
 
+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', () => {
     const parsed = PresetFrequencySchema.parse({
@@ -119,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__/remote-access.schema.test.ts

@@ -12,7 +12,7 @@ describe('remote access origins', () => {
     expect(normalizeRemoteAccessOrigin('https://user:pass@radio.example.com')).toBeNull();
   });
 
-  it('requires HTTPS for public hosts while allowing private-network HTTP', () => {
+  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);

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/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>;