@tx5dr/contracts 1.7.7 → 1.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tx5dr/contracts",
-  "version": "1.7.7",
+  "version": "1.7.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest';
 import {
+  buildRadioFrequencyPermissionGrants,
   buildAbilityRules,
+  getPresetFrequenciesFromFrequencyGrants,
+  getRangesFromFrequencyGrants,
   Permission,
   PERMISSION_GROUPS,
   PERMISSION_RULE_MAP,
@@ -37,4 +40,60 @@ describe('ability contracts', () => {
       Permission.CW_DECODER_CONFIG,
     ]);
   });
+
+  it('builds preset and range frequency grants as separate OR rules', () => {
+    const grants = buildRadioFrequencyPermissionGrants(
+      [7_050_000, 7_050_000],
+      [{ minFrequency: 14_000_000, maxFrequency: 14_350_000 }],
+    );
+
+    expect(grants).toEqual([
+      {
+        permission: Permission.RADIO_SET_FREQUENCY,
+        conditions: { frequency: { $in: [7_050_000] } },
+      },
+      {
+        permission: Permission.RADIO_SET_FREQUENCY,
+        conditions: { frequency: { $gte: 14_000_000, $lte: 14_350_000 } },
+      },
+    ]);
+  });
+
+  it('uses an unconditional frequency grant when no preset or range restriction is provided', () => {
+    expect(buildRadioFrequencyPermissionGrants([], [])).toEqual([
+      { permission: Permission.RADIO_SET_FREQUENCY },
+    ]);
+  });
+
+  it('rejects invalid preset frequency restrictions instead of allowing all frequencies', () => {
+    expect(() => buildRadioFrequencyPermissionGrants([Number.NaN], []))
+      .toThrow('presetFrequencies[0]');
+    expect(() => buildRadioFrequencyPermissionGrants([0], []))
+      .toThrow('presetFrequencies[0]');
+  });
+
+  it('rejects invalid range restrictions instead of allowing all frequencies', () => {
+    expect(() => buildRadioFrequencyPermissionGrants([], [{ minFrequency: Number.NaN, maxFrequency: 14_350_000 }]))
+      .toThrow('ranges[0].minFrequency');
+    expect(() => buildRadioFrequencyPermissionGrants([], [{ minFrequency: 14_350_000, maxFrequency: 14_000_000 }]))
+      .toThrow('ranges[0]');
+  });
+
+  it('restores preset and range restrictions from existing frequency grants', () => {
+    const grants = [
+      {
+        permission: Permission.RADIO_SET_FREQUENCY,
+        conditions: { frequency: { $in: [7_050_000, 14_270_000] } },
+      },
+      {
+        permission: Permission.RADIO_SET_FREQUENCY,
+        conditions: { frequency: { $gte: 14_000_000, $lte: 14_350_000 } },
+      },
+    ];
+
+    expect(getPresetFrequenciesFromFrequencyGrants(grants)).toEqual([7_050_000, 14_270_000]);
+    expect(getRangesFromFrequencyGrants(grants)).toEqual([
+      { band: '20m', minFrequency: 14_000_000, maxFrequency: 14_350_000 },
+    ]);
+  });
 });

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

@@ -3,7 +3,10 @@ import {
   AudioDevicesResponseSchema,
   AudioDeviceResolutionSchema,
   AudioDeviceResolutionStatusSchema,
+  AudioDeviceSettingsSchema,
   AudioDeviceSettingsResponseSchema,
+  AudioOutputChannelModeSchema,
+  AudioOutputSampleFormatSchema,
   AudioSettingsResolveResponseSchema,
 } from '../audio.schema.js';
 
@@ -122,6 +125,21 @@ describe('audio device resolution schemas', () => {
     }).currentSettings.outputBufferSize).toBe(1024);
   });
 
+  it('accepts and validates output diagnostic audio settings', () => {
+    expect(AudioOutputSampleFormatSchema.parse('int16')).toBe('int16');
+    expect(AudioOutputChannelModeSchema.parse('both')).toBe('both');
+    expect(AudioDeviceSettingsSchema.parse({
+      outputSampleFormat: 'int16',
+      outputChannelMode: 'right',
+    })).toMatchObject({
+      outputSampleFormat: 'int16',
+      outputChannelMode: 'right',
+    });
+
+    expect(() => AudioDeviceSettingsSchema.parse({ outputSampleFormat: 'int24' })).toThrow();
+    expect(() => AudioDeviceSettingsSchema.parse({ outputChannelMode: 'stereo' })).toThrow();
+  });
+
   it('accepts resolve responses with every supported status', () => {
     for (const status of ['selected', 'default', 'virtual-selected', 'missing'] as const) {
       expect(AudioSettingsResolveResponseSchema.parse({

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

@@ -60,6 +60,7 @@ describe('plugin market schema', () => {
   });
 
   it('accepts host settings permissions', () => {
+    expect(PluginPermissionSchema.parse('host:hamlib')).toBe('host:hamlib');
     expect(PluginPermissionSchema.parse('settings:ft8')).toBe('settings:ft8');
     expect(PluginPermissionSchema.parse('settings:ntp')).toBe('settings:ntp');
   });

package/src/schema/ability.ts

@@ -100,6 +100,136 @@ export const PermissionGrantSchema = z.object({
 
 export type PermissionGrant = z.infer<typeof PermissionGrantSchema>;
 
+// ===== Frequency permission helpers =====
+
+export interface FrequencyPermissionRange {
+  band?: string;
+  minFrequency: number;
+  maxFrequency: number;
+}
+
+export const FREQUENCY_PERMISSION_BAND_RANGES: Record<string, FrequencyPermissionRange> = {
+  '160m': { band: '160m', minFrequency: 1_800_000, maxFrequency: 2_000_000 },
+  '80m': { band: '80m', minFrequency: 3_500_000, maxFrequency: 4_000_000 },
+  '60m': { band: '60m', minFrequency: 5_000_000, maxFrequency: 5_500_000 },
+  '40m': { band: '40m', minFrequency: 7_000_000, maxFrequency: 7_300_000 },
+  '30m': { band: '30m', minFrequency: 10_100_000, maxFrequency: 10_150_000 },
+  '20m': { band: '20m', minFrequency: 14_000_000, maxFrequency: 14_350_000 },
+  '17m': { band: '17m', minFrequency: 18_068_000, maxFrequency: 18_168_000 },
+  '15m': { band: '15m', minFrequency: 21_000_000, maxFrequency: 21_450_000 },
+  '12m': { band: '12m', minFrequency: 24_890_000, maxFrequency: 24_990_000 },
+  '10m': { band: '10m', minFrequency: 28_000_000, maxFrequency: 29_700_000 },
+  '6m': { band: '6m', minFrequency: 50_000_000, maxFrequency: 54_000_000 },
+  '2m': { band: '2m', minFrequency: 144_000_000, maxFrequency: 148_000_000 },
+  '70cm': { band: '70cm', minFrequency: 420_000_000, maxFrequency: 450_000_000 },
+};
+
+function getFrequencyCondition(grant: PermissionGrant): Record<string, unknown> | null {
+  if (grant.permission !== Permission.RADIO_SET_FREQUENCY) return null;
+  const frequency = grant.conditions?.frequency;
+  if (!frequency || typeof frequency !== 'object' || Array.isArray(frequency)) return null;
+  return frequency as Record<string, unknown>;
+}
+
+function normalizeFrequency(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.round(value)
+    : null;
+}
+
+function requireFrequency(value: unknown, label: string): number {
+  const frequency = normalizeFrequency(value);
+  if (frequency === null) {
+    throw new Error(`${label} must be a finite positive frequency in Hz`);
+  }
+  return frequency;
+}
+
+export function getPresetFrequenciesFromFrequencyGrants(grants: PermissionGrant[] | undefined): number[] {
+  const result: number[] = [];
+  const seen = new Set<number>();
+
+  for (const grant of grants ?? []) {
+    const condition = getFrequencyCondition(grant);
+    const values = condition?.$in;
+    if (!Array.isArray(values)) continue;
+
+    for (const value of values) {
+      const frequency = normalizeFrequency(value);
+      if (frequency !== null && !seen.has(frequency)) {
+        seen.add(frequency);
+        result.push(frequency);
+      }
+    }
+  }
+
+  return result;
+}
+
+export function getRangesFromFrequencyGrants(grants: PermissionGrant[] | undefined): FrequencyPermissionRange[] {
+  const result: FrequencyPermissionRange[] = [];
+
+  for (const grant of grants ?? []) {
+    const condition = getFrequencyCondition(grant);
+    const minFrequency = normalizeFrequency(condition?.$gte);
+    const maxFrequency = normalizeFrequency(condition?.$lte);
+    if (minFrequency === null || maxFrequency === null || minFrequency > maxFrequency) continue;
+
+    result.push({
+      minFrequency,
+      maxFrequency,
+      band: inferFrequencyPermissionBand(minFrequency, maxFrequency),
+    });
+  }
+
+  return result;
+}
+
+export function inferFrequencyPermissionBand(minFrequency: number, maxFrequency: number): string | undefined {
+  const entry = Object.entries(FREQUENCY_PERMISSION_BAND_RANGES)
+    .find(([, range]) => range.minFrequency === minFrequency && range.maxFrequency === maxFrequency);
+  return entry?.[0];
+}
+
+export function buildRadioFrequencyPermissionGrants(
+  presetFrequencies: number[],
+  ranges: FrequencyPermissionRange[],
+): PermissionGrant[] {
+  const grants: PermissionGrant[] = [];
+  const normalizedPresetFrequencies = [...new Set(presetFrequencies.map((value, index) => requireFrequency(value, `presetFrequencies[${index}]`)))];
+
+  if (normalizedPresetFrequencies.length > 0) {
+    grants.push({
+      permission: Permission.RADIO_SET_FREQUENCY,
+      conditions: {
+        frequency: { $in: normalizedPresetFrequencies },
+      },
+    });
+  }
+
+  for (const [index, range] of ranges.entries()) {
+    const minFrequency = requireFrequency(range.minFrequency, `ranges[${index}].minFrequency`);
+    const maxFrequency = requireFrequency(range.maxFrequency, `ranges[${index}].maxFrequency`);
+    if (minFrequency > maxFrequency) {
+      throw new Error(`ranges[${index}] minFrequency must be less than or equal to maxFrequency`);
+    }
+
+    grants.push({
+      permission: Permission.RADIO_SET_FREQUENCY,
+      conditions: {
+        frequency: {
+          $gte: minFrequency,
+          $lte: maxFrequency,
+        },
+      },
+    });
+  }
+
+  return grants.length > 0
+    ? grants
+    : [{ permission: Permission.RADIO_SET_FREQUENCY }];
+}
+
 // ===== Raw rule type (pure data, no CASL dependency) =====
 
 export interface RawRule {

package/src/schema/audio.schema.ts

@@ -34,6 +34,9 @@ export const AudioDeviceResolutionSetSchema = z.object({
   output: AudioDeviceResolutionSchema,
 });
 
+export const AudioOutputSampleFormatSchema = z.enum(['float32', 'int16']);
+export const AudioOutputChannelModeSchema = z.enum(['mono', 'left', 'right', 'both']);
+
 // 音频设备列表响应
 export const AudioDevicesResponseSchema = z.object({
   inputDevices: z.array(AudioDeviceSchema),
@@ -50,6 +53,8 @@ export const AudioDeviceSettingsSchema = z.object({
   outputSampleRate: z.number().optional(),
   inputBufferSize: z.number().optional(),
   outputBufferSize: z.number().optional(),
+  outputSampleFormat: AudioOutputSampleFormatSchema.optional(),
+  outputChannelMode: AudioOutputChannelModeSchema.optional(),
   sampleRate: z.number().optional(),
   bufferSize: z.number().optional(),
 });
@@ -108,6 +113,8 @@ export type AudioDevice = z.infer<typeof AudioDeviceSchema>;
 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 AudioDevicesResponse = z.infer<typeof AudioDevicesResponseSchema>;
 export type AudioDeviceSettings = z.infer<typeof AudioDeviceSettingsSchema>;
 export type AudioDeviceSettingsResponse = z.infer<typeof AudioDeviceSettingsResponseSchema>;

package/src/schema/plugin.schema.ts

@@ -38,6 +38,7 @@ export type PluginInstanceScope = z.infer<typeof PluginInstanceScopeSchema>;
  */
 export const PluginPermissionSchema = z.enum([
   'network',
+  'host:hamlib',
   'radio:read',
   'radio:control',
   'radio:power',
@@ -249,6 +250,8 @@ export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
  * - `main-right`: shown in the optional main layout plugin pane on the far right.
  * - `voice-left-top`: shown above the voice frequency control card.
  * - `voice-right-top`: shown in the tabbed top area of the voice right panel.
+ * - `cw-left-top`: shown above the CW frequency control card.
+ * - `cw-right-top`: shown in the tabbed top area of the CW right panel.
  */
 export const PluginPanelSlotSchema = z.enum([
   'operator',
@@ -256,6 +259,7 @@ export const PluginPanelSlotSchema = z.enum([
   'main-right',
   'voice-left-top',
   'voice-right-top',
+  'cw-left-top',
   'cw-right-top',
   'radio-control-toolbar',
 ]);

package/test/plugin-slot-schema.test.ts

@@ -8,6 +8,7 @@ describe('PluginPanelSlotSchema', () => {
     expect(PluginPanelSlotSchema.parse('main-right')).toBe('main-right');
     expect(PluginPanelSlotSchema.parse('voice-left-top')).toBe('voice-left-top');
     expect(PluginPanelSlotSchema.parse('voice-right-top')).toBe('voice-right-top');
+    expect(PluginPanelSlotSchema.parse('cw-left-top')).toBe('cw-left-top');
     expect(PluginPanelSlotSchema.parse('cw-right-top')).toBe('cw-right-top');
     expect(PluginPanelSlotSchema.parse('radio-control-toolbar')).toBe('radio-control-toolbar');
   });
@@ -28,6 +29,14 @@ describe('PluginPanelSlotSchema', () => {
       pageId: 'voice-top',
       slot: 'voice-right-top',
     })).not.toThrow();
+
+    expect(() => PluginPanelDescriptorSchema.parse({
+      id: 'cw-left-top',
+      title: 'cwLeftTopTitle',
+      component: 'iframe',
+      pageId: 'cw-left-top',
+      slot: 'cw-left-top',
+    })).not.toThrow();
   });
 
   it('validates radio control toolbar iframe panel metadata', () => {