@tx5dr/contracts 1.7.11 → 2.0.0

package/src/schema/__tests__/logbook-health.schema.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CreateLogbookBackupRequestSchema,
+  LogBookInfoSchema,
+  LogbookHealthSchema,
+  RestoreLogbookRequestSchema,
+  WSMessageSchema,
+  WSMessageType,
+} from '../../index.js';
+
+const loadingHealth = {
+  state: 'loading' as const,
+  readable: false,
+  writable: false,
+  issues: [],
+  updatedAt: 1_775_394_000_000,
+};
+
+describe('logbook health contracts', () => {
+  it('requires every logbook listing to expose health', () => {
+    const info = {
+      id: 'logbook-N0CALL',
+      name: 'N0CALL QSO Log',
+      fileName: 'N0CALL.adi',
+      storageKind: 'managed' as const,
+      createdAt: 1,
+      lastUsed: 2,
+      isActive: true,
+    };
+
+    expect(LogBookInfoSchema.safeParse(info).success).toBe(false);
+    const parsed = LogBookInfoSchema.parse({ ...info, health: loadingHealth });
+    expect(parsed.health).toEqual(loadingHealth);
+    expect(parsed).not.toHaveProperty('filePath');
+  });
+
+  it('rejects path-bearing fields in backup and restore mutations', () => {
+    expect(CreateLogbookBackupRequestSchema.safeParse({
+      filePath: '/tmp/escape.adi',
+    }).success).toBe(false);
+    expect(RestoreLogbookRequestSchema.safeParse({
+      preflightToken: 'preflight-token-1',
+      confirmation: 'logbook-N0CALL',
+      artifactPath: '../another.adi',
+    }).success).toBe(false);
+  });
+
+  it('rejects negative affected record and byte counts', () => {
+    expect(LogbookHealthSchema.safeParse({
+      ...loadingHealth,
+      issues: [{
+        code: 'OPAQUE_RECORDS',
+        message: 'One record was skipped',
+        affectedRecords: -1,
+        affectedBytes: -1,
+        occurredAt: loadingHealth.updatedAt,
+      }],
+    }).success).toBe(false);
+  });
+
+  it('validates health and write-failure websocket payloads', () => {
+    expect(WSMessageSchema.safeParse({
+      type: WSMessageType.LOGBOOK_HEALTH_CHANGED,
+      timestamp: new Date().toISOString(),
+      data: { logBookId: 'logbook-N0CALL', health: loadingHealth },
+    }).success).toBe(true);
+    expect(WSMessageSchema.safeParse({
+      type: WSMessageType.LOGBOOK_WRITE_FAILED,
+      timestamp: new Date().toISOString(),
+      data: {
+        logBookId: 'logbook-N0CALL',
+        operatorId: 'operator-1',
+        attemptId: 'attempt-12345678',
+        unsavedCount: 1,
+        error: {
+          code: 'LOGBOOK_WRITE_FAILED',
+          message: 'No space left on device',
+          systemCode: 'ENOSPC',
+          occurredAt: loadingHealth.updatedAt,
+        },
+      },
+    }).success).toBe(true);
+    expect(WSMessageSchema.safeParse({
+      type: WSMessageType.LOGBOOK_WRITE_FAILED,
+      timestamp: new Date().toISOString(),
+      data: {
+        logBookId: 'logbook-N0CALL',
+        qsoRecord: {
+          id: 'private-qso',
+          callsign: 'N0CALL',
+          frequency: 14_074_000,
+          mode: 'FT8',
+          startTime: loadingHealth.updatedAt,
+          messageHistory: ['CQ N0CALL AA00'],
+        },
+        error: {
+          code: 'LOGBOOK_WRITE_FAILED',
+          message: 'write failed',
+          occurredAt: loadingHealth.updatedAt,
+        },
+      },
+    }).success).toBe(false);
+    expect(WSMessageSchema.safeParse({
+      type: WSMessageType.LOGBOOK_WRITE_FAILED,
+      timestamp: new Date().toISOString(),
+      data: {
+        logBookId: 'logbook-N0CALL',
+        error: {
+          code: 'ARBITRARY_ERROR',
+          message: 'Unstable error code',
+          occurredAt: loadingHealth.updatedAt,
+        },
+      },
+    }).success).toBe(false);
+  });
+});

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import {
+  OBSERVABILITY_NOTICE_VERSION,
+  UpdateObservabilitySettingsSchema,
+} from '../observability.schema.js';
+
+describe('observability settings schema', () => {
+  it('requires acknowledgment of the current notice', () => {
+    expect(UpdateObservabilitySettingsSchema.parse({
+      enabled: true,
+      noticeVersion: OBSERVABILITY_NOTICE_VERSION,
+    })).toEqual({ enabled: true, noticeVersion: 1 });
+    expect(() => UpdateObservabilitySettingsSchema.parse({ enabled: true, noticeVersion: 0 })).toThrow();
+  });
+});

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

@@ -2,7 +2,8 @@ import { describe, expect, it } from 'vitest';
 import {
   CreateRadioOperatorRequestSchema,
   UpdateRadioOperatorRequestSchema,
-  sanitizeCallsignInput
+  sanitizeCallsignInput,
+  sanitizeGridInput,
 } from '../../index.js';
 import { MODES } from '../mode.schema.js';
 
@@ -11,19 +12,26 @@ describe('operator callsign normalization', () => {
     expect(sanitizeCallsignInput(' bg5abc/p ')).toBe('BG5ABC/P');
   });
 
-  it('normalizes callsigns in create and update payloads', () => {
+  it('uppercases grids and removes whitespace', () => {
+    expect(sanitizeGridInput(' ol 63aa ')).toBe('OL63AA');
+  });
+
+  it('normalizes callsigns and grids in create and update payloads', () => {
     const createPayload = CreateRadioOperatorRequestSchema.parse({
       myCallsign: 'bg5abc/p',
-      myGrid: 'OL63',
+      myGrid: 'ol63aa',
       frequency: 1000,
       transmitCycles: [0],
       mode: MODES.FT8,
     });
     const updatePayload = UpdateRadioOperatorRequestSchema.parse({
       myCallsign: 'vk9/bg3yza',
+      myGrid: 'pm01',
     });
 
     expect(createPayload.myCallsign).toBe('BG5ABC/P');
+    expect(createPayload.myGrid).toBe('OL63AA');
     expect(updatePayload.myCallsign).toBe('VK9/BG3YZA');
+    expect(updatePayload.myGrid).toBe('PM01');
   });
 });

package/src/schema/__tests__/plugin-market.schema.test.ts

@@ -3,8 +3,11 @@ import {
   PluginMarketCatalogResponseSchema,
   PluginMarketCatalogSchema,
   PluginMarketChannelSchema,
+  PluginManifestSchema,
   PluginPermissionSchema,
+  PluginsConfigSchema,
   PluginSourceSchema,
+  PluginStatusSchema,
 } from '../../index.js';
 
 describe('plugin market schema', () => {
@@ -18,6 +21,8 @@ describe('plugin market schema', () => {
           name: 'heartbeat-demo',
           title: 'Heartbeat Demo',
           description: 'Example timer and quick-action plugin.',
+          readmeMarkdown: '# Heartbeat Demo\n\nExample timer and quick-action plugin.',
+          readmeSourceUrl: 'https://github.com/boybook/tx-5dr-plugins/blob/main/heartbeat-demo/README.md',
           locales: {
             en: {
               pluginName: 'Heartbeat Demo',
@@ -53,6 +58,8 @@ describe('plugin market schema', () => {
 
     expect(catalog.channel).toBe('stable');
     expect(catalog.plugins[0]?.name).toBe('heartbeat-demo');
+    expect(catalog.plugins[0]?.readmeMarkdown).toContain('# Heartbeat Demo');
+    expect(catalog.plugins[0]?.readmeSourceUrl).toContain('/heartbeat-demo/README.md');
   });
 
   it('rejects unsupported channels', () => {
@@ -60,9 +67,51 @@ describe('plugin market schema', () => {
   });
 
   it('accepts host settings permissions', () => {
+    expect(PluginPermissionSchema.parse('plugin:event-bus')).toBe('plugin:event-bus');
     expect(PluginPermissionSchema.parse('host:hamlib')).toBe('host:hamlib');
+    expect(PluginPermissionSchema.parse('operator:transmit-control')).toBe('operator:transmit-control');
     expect(PluginPermissionSchema.parse('settings:ft8')).toBe('settings:ft8');
     expect(PluginPermissionSchema.parse('settings:ntp')).toBe('settings:ntp');
+    expect(() => PluginPermissionSchema.parse('operator:transmit')).toThrow();
+  });
+
+  it('accepts transmit-control permission and auto-call status in plugin snapshots', () => {
+    const manifest = PluginManifestSchema.parse({
+      name: 'autocall-demo',
+      version: '1.0.0',
+      type: 'utility',
+      permissions: ['operator:transmit-control'],
+    });
+    expect(manifest.permissions).toEqual(['operator:transmit-control']);
+
+    const status = PluginStatusSchema.parse({
+      name: 'autocall-demo',
+      version: '1.0.0',
+      type: 'utility',
+      isBuiltIn: false,
+      loaded: true,
+      enabled: true,
+      errorCount: 0,
+      permissions: ['operator:transmit-control'],
+      capabilities: ['auto_call_control'],
+      autoCallEnabledOperatorIds: ['operator-1'],
+      pausedOperatorIds: ['operator-2'],
+    });
+    expect(status.autoCallEnabledOperatorIds).toEqual(['operator-1']);
+    expect(status.pausedOperatorIds).toEqual(['operator-2']);
+    expect(status.capabilities).toContain('auto_call_control');
+  });
+
+  it('accepts persisted operator plugin pause state with defaults', () => {
+    const emptyConfig = PluginsConfigSchema.parse({});
+    expect(emptyConfig.operatorPluginPauses).toEqual({});
+
+    const config = PluginsConfigSchema.parse({
+      operatorPluginPauses: {
+        'operator-1': ['scheduled-cq-autocall'],
+      },
+    });
+    expect(config.operatorPluginPauses['operator-1']).toEqual(['scheduled-cq-autocall']);
   });
 
   it('accepts the route response envelope', () => {

package/src/schema/__tests__/radio-power-support.test.ts

@@ -23,4 +23,18 @@ describe('radio power support', () => {
       }),
     ).not.toThrow();
   });
+
+  it('does not expose physical power controls for TCI radios', () => {
+    const decision = decidePowerSupport({
+      type: 'tci',
+      tci: { host: '127.0.0.1', port: 40001, receiver: 0, trx: 0, vfo: 0, audioEnabled: true, audioSampleRate: 12000 },
+    });
+
+    expect(decision).toMatchObject({
+      canPowerOn: false,
+      canPowerOff: false,
+      supportedStates: [],
+      reason: 'model-unsupported',
+    });
+  });
 });

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CreateProfileRequestSchema,
+  RadioProfileSchema,
+  UpdateProfileRequestSchema,
+} from '../radio-profile.schema.js';
+
+const audio = {
+  inputDeviceName: 'Headset microphone',
+  inputRouteKey: 'android:wired-headset:input',
+  outputDeviceName: 'Headset headphones',
+  outputRouteKey: 'android:wired-headset:output',
+  inputSampleRate: 48000,
+  outputSampleRate: 48000,
+};
+
+describe('radio profile audio route identity', () => {
+  it('preserves stable route keys through create and update requests', () => {
+    expect(CreateProfileRequestSchema.parse({
+      name: 'Android 3.5 mm',
+      radio: { type: 'none' },
+      audio,
+    }).audio).toMatchObject(audio);
+
+    expect(UpdateProfileRequestSchema.parse({ audio }).audio).toMatchObject(audio);
+  });
+
+  it('loads stable route keys while accepting legacy name-only profiles', () => {
+    const baseProfile = {
+      id: 'profile-1',
+      name: 'Android 3.5 mm',
+      radio: { type: 'none' as const },
+      audioLockedToRadio: false,
+      createdAt: 1,
+      updatedAt: 2,
+    };
+
+    expect(RadioProfileSchema.parse({ ...baseProfile, audio }).audio).toMatchObject(audio);
+    expect(RadioProfileSchema.parse({
+      ...baseProfile,
+      audio: { inputDeviceName: 'Legacy USB Audio' },
+    }).audio).toEqual({ inputDeviceName: 'Legacy USB Audio' });
+  });
+});

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

@@ -1,5 +1,53 @@
 import { describe, expect, it } from 'vitest';
-import { PresetFrequencySchema } from '../radio.schema.js';
+import { 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 TCI as a reported radio connection type', () => {
+    const parsed = RadioInfoSchema.parse({
+      manufacturer: 'Expert Electronics',
+      model: 'SunSDR',
+      connectionType: 'tci',
+    });
+
+    expect(parsed.connectionType).toBe('tci');
+  });
+});
 
 describe('PresetFrequencySchema repeater DUP fields', () => {
   it('accepts existing presets without repeater DUP fields', () => {

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('requires HTTPS for public hosts while allowing private-network HTTP', () => {
+    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/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/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>;

package/src/schema/audio.schema.ts

@@ -1,5 +1,69 @@
 import { z } from 'zod';
 
+export const AudioDeviceBackendSchema = z.enum([
+  'rtaudio',
+  'android',
+  'icom-wlan',
+  'openwebrx',
+  'tci',
+  'network',
+]);
+
+export const AudioDeviceKindSchema = z.enum([
+  'usb',
+  'wired-headset',
+  'wired-headphones',
+  'analog-line',
+  'builtin-mic',
+  'builtin-speaker',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceTransportSchema = z.enum([
+  'usb',
+  'analog',
+  'builtin',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceConnectorSchema = z.enum([
+  'usb',
+  '3.5mm',
+  'builtin',
+  'network',
+  'virtual',
+  'unknown',
+]);
+
+export const AudioDeviceRouteStateSchema = z.enum([
+  'idle',
+  'opening',
+  'verified',
+  'lost',
+  'unavailable',
+  'failed',
+]);
+
+export const AudioDeviceCapabilitiesSchema = z.object({
+  sampleRates: z.array(z.number().int().positive()).optional(),
+  bufferSizes: z.array(z.number().int().positive()).optional(),
+  channelCounts: z.array(z.number().int().positive()).optional(),
+  sampleFormats: z.array(z.enum(['float32', 'int16'])).optional(),
+  channelModes: z.array(z.enum(['mono', 'left', 'right', 'both'])).optional(),
+  sampleRateConfigurable: z.boolean().optional(),
+  bufferSizeConfigurable: z.boolean().optional(),
+  sampleFormatConfigurable: z.boolean().optional(),
+  channelModeConfigurable: z.boolean().optional(),
+  outputRouteAck: z.boolean().optional(),
+  fixedSampleRate: z.number().int().positive().optional(),
+  fixedBufferSize: z.number().int().positive().optional(),
+  fixedChannelCount: z.number().int().positive().optional(),
+});
+
 // 音频设备信息
 export const AudioDeviceSchema = z.object({
   id: z.string(),
@@ -12,6 +76,26 @@ export const AudioDeviceSchema = z.object({
   availability: z.enum(['available', 'cached', 'active']).optional(),
   isActiveByTx5dr: z.boolean().optional(),
   lastSeenAt: z.number().int().positive().optional(),
+  backend: AudioDeviceBackendSchema.optional(),
+  kind: AudioDeviceKindSchema.optional(),
+  routeKey: z.string().min(1).optional(),
+  transport: AudioDeviceTransportSchema.optional(),
+  connector: AudioDeviceConnectorSchema.optional(),
+  clientConnected: z.boolean().optional(),
+  routeVerified: z.boolean().optional(),
+  routeState: AudioDeviceRouteStateSchema.optional(),
+  failureReason: z.string().min(1).optional(),
+  capabilities: AudioDeviceCapabilitiesSchema.optional(),
+  /** Human-readable secondary label (radio identity · VID:PID · USB path). */
+  detail: z.string().optional(),
+  /** Stable hardware identity when available (e.g. usb:1-7.2.4). */
+  hardwareId: z.string().optional(),
+  vendorId: z.string().optional(),
+  productId: z.string().optional(),
+  serialNumber: z.string().optional(),
+  usbPath: z.string().optional(),
+  alsaCard: z.number().int().nonnegative().optional(),
+  alsaCardId: z.string().optional(),
 });
 
 export const AudioDeviceResolutionStatusSchema = z.enum([
@@ -23,6 +107,9 @@ export const AudioDeviceResolutionStatusSchema = z.enum([
 
 export const AudioDeviceResolutionSchema = z.object({
   configuredDeviceName: z.string().nullable(),
+  configuredRouteKey: z.string().nullable().optional(),
+  configuredDeviceId: z.string().nullable().optional(),
+  configuredHardwareId: z.string().nullable().optional(),
   configuredDevice: AudioDeviceSchema.nullable(),
   effectiveDevice: AudioDeviceSchema.nullable(),
   status: AudioDeviceResolutionStatusSchema,
@@ -37,6 +124,13 @@ export const AudioDeviceResolutionSetSchema = z.object({
 export const AudioOutputSampleFormatSchema = z.enum(['float32', 'int16']);
 export const AudioOutputChannelModeSchema = z.enum(['mono', 'left', 'right', 'both']);
 
+/**
+ * How USB/ACC capture PCM should be interpreted before the internal 12 kHz AF ring.
+ * - af: already-demodulated SSB baseband (default)
+ * - icom-12k-if: Icom ACC/USB Output Select=IF (~12 kHz IF); software SSB demod required
+ */
+export const AudioInputSignalTypeSchema = z.enum(['af', 'icom-12k-if']);
+
 // 音频设备列表响应
 export const AudioDevicesResponseSchema = z.object({
   inputDevices: z.array(AudioDeviceSchema),
@@ -48,13 +142,25 @@ export const AudioDevicesResponseSchema = z.object({
 // 音频设备设置请求
 export const AudioDeviceSettingsSchema = z.object({
   inputDeviceName: z.string().optional(),  // 使用设备名称而非ID
-  outputDeviceName: z.string().optional(), // 使用设备名称而非ID  
+  outputDeviceName: z.string().optional(), // 使用设备名称而非ID
+  inputRouteKey: z.string().min(1).nullable().optional(),
+  outputRouteKey: z.string().min(1).nullable().optional(),
+  /** Runtime device id (e.g. input-130). Preferred over name when unique. */
+  inputDeviceId: z.string().optional(),
+  outputDeviceId: z.string().optional(),
+  /** Stable hardware id when available (e.g. usb:1-7.2.4). Preferred over runtime id. */
+  inputHardwareId: z.string().optional(),
+  outputHardwareId: z.string().optional(),
   inputSampleRate: z.number().optional(),
   outputSampleRate: z.number().optional(),
   inputBufferSize: z.number().optional(),
   outputBufferSize: z.number().optional(),
   outputSampleFormat: AudioOutputSampleFormatSchema.optional(),
   outputChannelMode: AudioOutputChannelModeSchema.optional(),
+  /** Capture signal interpretation. Defaults to demodulated AF baseband. */
+  inputSignalType: AudioInputSignalTypeSchema.optional(),
+  /** IF center frequency in Hz when inputSignalType is icom-12k-if (default 12000). */
+  ifCenterHz: z.number().positive().max(24000).optional(),
   sampleRate: z.number().optional(),
   bufferSize: z.number().optional(),
 });
@@ -69,7 +175,7 @@ export const AudioDeviceSettingsResponseSchema = z.object({
 
 export const AudioSettingsResolveRequestSchema = z.object({
   audio: AudioDeviceSettingsSchema,
-  radioType: z.enum(['none', 'network', 'serial', 'icom-wlan']).optional(),
+  radioType: z.enum(['none', 'network', 'serial', 'icom-wlan', 'tci']).optional(),
 });
 
 export const AudioSettingsResolveResponseSchema = z.object({
@@ -110,11 +216,18 @@ export const VolumeGainSchema = z.object({
 
 // 导出类型
 export type AudioDevice = z.infer<typeof AudioDeviceSchema>;
+export type AudioDeviceBackend = z.infer<typeof AudioDeviceBackendSchema>;
+export type AudioDeviceKind = z.infer<typeof AudioDeviceKindSchema>;
+export type AudioDeviceTransport = z.infer<typeof AudioDeviceTransportSchema>;
+export type AudioDeviceConnector = z.infer<typeof AudioDeviceConnectorSchema>;
+export type AudioDeviceRouteState = z.infer<typeof AudioDeviceRouteStateSchema>;
+export type AudioDeviceCapabilities = z.infer<typeof AudioDeviceCapabilitiesSchema>;
 export type AudioDeviceResolutionStatus = z.infer<typeof AudioDeviceResolutionStatusSchema>;
 export type AudioDeviceResolution = z.infer<typeof AudioDeviceResolutionSchema>;
 export type AudioDeviceResolutionSet = z.infer<typeof AudioDeviceResolutionSetSchema>;
 export type AudioOutputSampleFormat = z.infer<typeof AudioOutputSampleFormatSchema>;
 export type AudioOutputChannelMode = z.infer<typeof AudioOutputChannelModeSchema>;
+export type AudioInputSignalType = z.infer<typeof AudioInputSignalTypeSchema>;
 export type AudioDevicesResponse = z.infer<typeof AudioDevicesResponseSchema>;
 export type AudioDeviceSettings = z.infer<typeof AudioDeviceSettingsSchema>;
 export type AudioDeviceSettingsResponse = z.infer<typeof AudioDeviceSettingsResponseSchema>;