@tx5dr/contracts 1.7.12 → 2.5.0

package/src/schema/spectrum.schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SpectrumPresetDefinitionSchema, SpectrumRenderConfigSchema } from './spectrum-config.schema.js';
 
 export const SpectrumKindSchema = z.enum(['audio', 'radio-sdr', 'openwebrx-sdr']);
 export type SpectrumKind = z.infer<typeof SpectrumKindSchema>;
@@ -26,10 +27,31 @@ export const SpectrumSessionFrequencyRangeModeSchema = z.enum([
 ]);
 export type SpectrumSessionFrequencyRangeMode = z.infer<typeof SpectrumSessionFrequencyRangeModeSchema>;
 
+export const SpectrumSessionViewModeSchema = z.enum(['wide', 'radio-center']);
+export type SpectrumSessionViewMode = z.infer<typeof SpectrumSessionViewModeSchema>;
+
 export const SpectrumFrequencyRangeSchema = z.object({
   min: z.number(),
   max: z.number(),
 });
+export const SpectrumViewportSchema = z.object({
+  min: z.number().finite(),
+  max: z.number().finite(),
+  displayBinCount: z.number().int().positive().max(16384),
+}).refine((range) => range.max > range.min, {
+  message: 'Spectrum viewport maximum must be greater than minimum',
+  path: ['max'],
+});
+export type SpectrumViewport = z.infer<typeof SpectrumViewportSchema>;
+
+export const SpectrumSessionViewportInteractionSchema = z.object({
+  enabled: z.boolean(),
+  canZoom: z.boolean(),
+  canPan: z.boolean(),
+  canTuneAtEdge: z.boolean(),
+  bounds: SpectrumFrequencyRangeSchema.nullable(),
+});
+export type SpectrumSessionViewportInteraction = z.infer<typeof SpectrumSessionViewportInteractionSchema>;
 
 export const SpectrumBinaryFormatSchema = z.object({
   type: z.literal('int16'),
@@ -43,13 +65,53 @@ export const SpectrumBinaryDataSchema = z.object({
   format: SpectrumBinaryFormatSchema,
 });
 
+export const SpectrumLevelDomainSchema = z.enum(['dbfs', 'calibrated-db', 'raw']);
+export type SpectrumLevelDomain = z.infer<typeof SpectrumLevelDomainSchema>;
+
+export const SpectrumLevelUnitSchema = z.enum(['dBFS', 'dB', 'Level']);
+export type SpectrumLevelUnit = z.infer<typeof SpectrumLevelUnitSchema>;
+
+export const SpectrumLevelReferenceSchema = z.enum(['full-scale', 'device', 'none']);
+export type SpectrumLevelReference = z.infer<typeof SpectrumLevelReferenceSchema>;
+
+export const SpectrumLevelDescriptorSchema = z.object({
+  domain: SpectrumLevelDomainSchema,
+  unit: SpectrumLevelUnitSchema,
+  reference: SpectrumLevelReferenceSchema,
+  calibrated: z.boolean(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+}).refine((level) => level.max > level.min, {
+  message: 'Spectrum level maximum must be greater than minimum',
+  path: ['max'],
+});
+export type SpectrumLevelDescriptor = z.infer<typeof SpectrumLevelDescriptorSchema>;
+
+/** A lower-resolution, wider-range representation derived from the same FFT. */
+export const SpectrumFrameSupplementSchema = z.object({
+  frequencyRange: SpectrumFrequencyRangeSchema,
+  binaryData: SpectrumBinaryDataSchema,
+  meta: z.object({
+    sourceBinCount: z.number().int().positive(),
+    displayBinCount: z.number().int().positive(),
+    centerFrequency: z.number().optional(),
+    spanHz: z.number().optional(),
+    level: SpectrumLevelDescriptorSchema.optional(),
+  }),
+});
+export type SpectrumFrameSupplement = z.infer<typeof SpectrumFrameSupplementSchema>;
+
 export const SpectrumFrameMetaSchema = z.object({
   sourceBinCount: z.number().int().positive(),
   displayBinCount: z.number().int().positive(),
+  /** Original source range before a per-client server-side projection. */
+  nativeFrequencyRange: SpectrumFrequencyRangeSchema.optional(),
   centerFrequency: z.number().optional(),
   spanHz: z.number().optional(),
   profileId: z.string().nullable().optional(),
   radioModel: z.string().optional(),
+  level: SpectrumLevelDescriptorSchema.optional(),
+  spectrumConfigRevision: z.number().int().nonnegative().optional(),
 });
 
 export const SpectrumFrameSchema = z.object({
@@ -58,6 +120,7 @@ export const SpectrumFrameSchema = z.object({
   frequencyRange: SpectrumFrequencyRangeSchema,
   binaryData: SpectrumBinaryDataSchema,
   meta: SpectrumFrameMetaSchema,
+  supplement: SpectrumFrameSupplementSchema.optional(),
 });
 
 export const SpectrumSourceAvailabilitySchema = z.object({
@@ -76,6 +139,8 @@ export const SpectrumCapabilitiesSchema = z.object({
   profileId: z.string().nullable(),
   defaultKind: SpectrumKindSchema,
   sources: z.array(SpectrumSourceAvailabilitySchema),
+  renderConfig: SpectrumRenderConfigSchema,
+  presets: z.array(SpectrumPresetDefinitionSchema),
 });
 
 export const SpectrumSessionControlIdSchema = z.enum([
@@ -120,7 +185,30 @@ export const SpectrumSessionPresetMarkerSchema = z.object({
 });
 export type SpectrumSessionPresetMarker = z.infer<typeof SpectrumSessionPresetMarkerSchema>;
 
+export const SpectrumSessionFrequencyOverlaySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  lineFrequency: z.number().finite(),
+  rangeStartFrequency: z.number().finite(),
+  rangeEndFrequency: z.number().finite(),
+  variant: z.enum(['tx', 'rx', 'window']),
+  draggable: z.boolean(),
+  frequencyTarget: z.enum(['radio-frequency', 'operator-tx', 'split-frequency']).nullable(),
+}).refine((overlay) => overlay.rangeEndFrequency >= overlay.rangeStartFrequency, {
+  message: 'Spectrum frequency overlay range is invalid',
+  path: ['rangeEndFrequency'],
+});
+export type SpectrumSessionFrequencyOverlay = z.infer<typeof SpectrumSessionFrequencyOverlaySchema>;
+
 export const SpectrumSessionInteractionStateSchema = z.object({
+  viewMode: SpectrumSessionViewModeSchema.default('radio-center'),
+  viewport: SpectrumSessionViewportInteractionSchema.default({
+    enabled: false,
+    canZoom: false,
+    canPan: false,
+    canTuneAtEdge: false,
+    bounds: null,
+  }),
   showTxMarkers: z.boolean(),
   showRxMarkers: z.boolean(),
   canDragTx: z.boolean(),
@@ -130,6 +218,7 @@ export const SpectrumSessionInteractionStateSchema = z.object({
   frequencyGestureTarget: z.enum(['operator-tx', 'radio-frequency']).nullable(),
   frequencyStepHz: z.number().int().positive().nullable(),
   presetMarkers: z.array(SpectrumSessionPresetMarkerSchema),
+  frequencyOverlays: z.array(SpectrumSessionFrequencyOverlaySchema),
   canDragVoiceOverlay: z.boolean(),
   showVoiceOverlay: z.boolean(),
   canLocalViewportZoom: z.boolean(),

package/src/schema/station-info.schema.ts

@@ -16,6 +16,11 @@ export const StationQthSchema = z.object({
   longitude: z.number().min(-180).max(180).optional(),
 });
 
+/**
+ * Public station profile shown to clients and exposed through plugin settings.
+ * It contains optional display identity, callsign, Markdown description and QTH
+ * coordinates/grid; it never contains authentication or radio credentials.
+ */
 export const StationInfoSchema = z.object({
   /** Station display name, e.g. "BG7XXX Remote Station" */
   name: z.string().max(100).optional(),

package/src/schema/system.schema.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { RemoteAccessPresetSchema } from './auth.schema.js';
+import { PluginDistributionSchema } from './plugin.schema.js';
 
 // ===== 网络信息 =====
 
@@ -13,10 +15,35 @@ export const NetworkInfoSchema = z.object({
   addresses: z.array(NetworkAddressSchema),
   hostname: z.string(),
   webPort: z.number(),
+  exposure: RemoteAccessPresetSchema.default('lan'),
+  listenHost: z.string().default('0.0.0.0'),
+  runtimeManagement: z.enum(['electron', 'external']).default('external'),
+  distribution: PluginDistributionSchema.default('generic-server'),
+  supportsLocalOnly: z.boolean().default(false),
+  supportedPresets: z.array(RemoteAccessPresetSchema).min(1).default(['lan', 'public']),
+  activeConnections: z.number().int().nonnegative().default(0),
+  maxConnections: z.number().int().positive().default(32),
 });
 
 export type NetworkInfo = z.infer<typeof NetworkInfoSchema>;
 
+// ===== 日志设置 =====
+
+export const SystemLogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+export type SystemLogLevel = z.infer<typeof SystemLogLevelSchema>;
+
+export const SystemLoggingSettingsSchema = z.object({
+  level: SystemLogLevelSchema.optional(),
+  effectiveLevel: SystemLogLevelSchema,
+  logsDir: z.string(),
+});
+export type SystemLoggingSettings = z.infer<typeof SystemLoggingSettingsSchema>;
+
+export const UpdateSystemLoggingSettingsSchema = z.object({
+  level: SystemLogLevelSchema,
+});
+export type UpdateSystemLoggingSettingsRequest = z.infer<typeof UpdateSystemLoggingSettingsSchema>;
+
 // ===== 时钟状态 =====
 
 export const ClockSyncStateSchema = z.enum(['synced', 'stale', 'never', 'failed']);
@@ -115,12 +142,14 @@ const NtpServerArraySchema = z.array(NtpServerHostSchema).min(1).superRefine((se
   }
 });
 
+/** Active NTP server list together with the Host-provided default list. */
 export const NtpServerListSettingsSchema = z.object({
   servers: NtpServerArraySchema,
   defaultServers: NtpServerArraySchema,
 });
 export type NtpServerListSettings = z.infer<typeof NtpServerListSettingsSchema>;
 
+/** Complete replacement list accepted by `ctx.settings.ntp.update()`. */
 export const UpdateNtpServerListRequestSchema = z.object({
   servers: NtpServerArraySchema,
 });

package/src/schema/transmission.schema.ts

@@ -40,16 +40,11 @@ export const CallRequestSchema = z.object({
 
 // ========== 传输请求类型 ==========
 
-/**
- * 传输请求（已在 websocket.schema.ts 中定义）
- * TransmitRequestSchema
- */
+// TransmitRequestSchema is declared in websocket.schema.ts.
 
 // ========== 时隙映射类型 ==========
 
-/**
- * 操作员时隙配置
- */
+/** Transmit-message templates for the six logical slots of one operator. */
 export const OperatorSlotsSchema = z.object({
   TX1: z.string().optional(),
   TX2: z.string().optional(),

package/src/schema/tx-audio-input.schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/** Normalized TX audio input routes used by the capability/profile layers. */
+export const TxAudioInputSourceSchema = z.enum([
+  'mic',
+  'usb',
+  'network',
+  'accessory',
+  'line',
+  'spdif',
+  'mic+usb',
+  'mic+accessory',
+]);
+export type TxAudioInputSource = z.infer<typeof TxAudioInputSourceSchema>;
+
+/** Profile policy. `auto` is resolved by the connection/provider. */
+export const TxAudioInputSourcePolicySchema = z.enum([
+  'auto',
+  'unchanged',
+  ...TxAudioInputSourceSchema.options,
+]);
+export type TxAudioInputSourcePolicy = z.infer<typeof TxAudioInputSourcePolicySchema>;

package/src/schema/voice.schema.ts

@@ -24,5 +24,5 @@ export type VoicePTTLock = z.infer<typeof VoicePTTLockSchema>;
  * digital: FT8/FT4 等数字模式
  * voice: 语音通联模式（SSB/FM/AM）
  */
-export const EngineModeSchema = z.enum(['digital', 'voice', 'cw']);
+export const EngineModeSchema = z.enum(['digital', 'voice', 'cw', 'image']);
 export type EngineMode = z.infer<typeof EngineModeSchema>;