@tx5dr/contracts 1.2.0

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+export const StationQthSchema = z.object({
+  /** Maidenhead grid locator, e.g. "PM01" or "PM01RP" */
+  grid: z
+    .string()
+    .regex(/^[A-Ra-r]{2}[0-9]{2}([A-Xa-x]{2}([0-9]{2})?)?$/, 'Invalid Maidenhead grid locator')
+    .transform((s) => s.toUpperCase())
+    .optional()
+    .or(z.literal('')),
+  /** Human-readable location name, e.g. "Haidian, Beijing" */
+  location: z.string().max(100).optional(),
+  /** Precise latitude entered by the user (overrides grid-derived center) */
+  latitude: z.number().min(-90).max(90).optional(),
+  /** Precise longitude entered by the user (overrides grid-derived center) */
+  longitude: z.number().min(-180).max(180).optional(),
+});
+
+export const StationInfoSchema = z.object({
+  /** Station display name, e.g. "BG7XXX Remote Station" */
+  name: z.string().max(100).optional(),
+  /** Owner callsign, e.g. "BG7XXX" */
+  callsign: z.string().max(20).optional(),
+  /** Markdown-formatted description (antenna, power, radio model, etc.) */
+  description: z.string().max(2000).optional(),
+  /** Station QTH location */
+  qth: StationQthSchema.optional(),
+});
+
+export type StationQth = z.infer<typeof StationQthSchema>;
+export type StationInfo = z.infer<typeof StationInfoSchema>;
+
+export const UpdateStationInfoRequestSchema = StationInfoSchema;
+export type UpdateStationInfoRequest = StationInfo;
+
+export const StationInfoResponseSchema = z.object({
+  success: z.boolean(),
+  data: StationInfoSchema,
+});
+export type StationInfoResponse = z.infer<typeof StationInfoResponseSchema>;

package/src/schema/system.schema.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+
+// ===== 网络信息 =====
+
+export const NetworkAddressSchema = z.object({
+  ip: z.string(),
+  url: z.string(),
+});
+
+export type NetworkAddress = z.infer<typeof NetworkAddressSchema>;
+
+export const NetworkInfoSchema = z.object({
+  addresses: z.array(NetworkAddressSchema),
+  hostname: z.string(),
+  webPort: z.number(),
+});
+
+export type NetworkInfo = z.infer<typeof NetworkInfoSchema>;
+
+// ===== 时钟状态 =====
+
+export const ClockSyncStateSchema = z.enum(['synced', 'stale', 'never', 'failed']);
+export type ClockSyncState = z.infer<typeof ClockSyncStateSchema>;
+
+export const ClockIndicatorStateSchema = z.enum(['ok', 'warn', 'alert', 'stale', 'failed', 'never']);
+export type ClockIndicatorState = z.infer<typeof ClockIndicatorStateSchema>;
+
+export const ClockStatusSummarySchema = z.object({
+  appliedOffsetMs: z.number(),
+  indicatorState: ClockIndicatorStateSchema,
+});
+export type ClockStatusSummary = z.infer<typeof ClockStatusSummarySchema>;
+
+export const ClockStatusDetailSchema = ClockStatusSummarySchema.extend({
+  measuredOffsetMs: z.number(),
+  lastSyncTime: z.number().nullable(),
+  syncState: ClockSyncStateSchema,
+  serverUsed: z.string().nullable(),
+  errorMessage: z.string().nullable(),
+});
+export type ClockStatusDetail = z.infer<typeof ClockStatusDetailSchema>;
+
+export const SetClockOffsetRequestSchema = z.object({
+  offsetMs: z.number().finite(),
+});
+export type SetClockOffsetRequest = z.infer<typeof SetClockOffsetRequestSchema>;
+
+// ===== NTP server list settings =====
+
+function isValidIPv4Address(value: string): boolean {
+  const parts = value.split('.');
+  if (parts.length !== 4) return false;
+  return parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part)) return false;
+    const num = Number(part);
+    return Number.isInteger(num) && num >= 0 && num <= 255;
+  });
+}
+
+function isValidHostname(value: string): boolean {
+  if (value === 'localhost') return true;
+  if (value.length > 253) return false;
+  if (value.startsWith('.') || value.endsWith('.') || value.includes('..')) return false;
+  if (!/^[A-Za-z0-9.-]+$/.test(value)) return false;
+
+  const labels = value.split('.');
+  return labels.every((label) => (
+    label.length > 0
+    && label.length <= 63
+    && !label.startsWith('-')
+    && !label.endsWith('-')
+    && /^[A-Za-z0-9-]+$/.test(label)
+  ));
+}
+
+export function isValidNtpServerHost(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  if (
+    trimmed.includes('://')
+    || trimmed.includes('/')
+    || trimmed.includes('?')
+    || trimmed.includes('#')
+    || trimmed.includes(':')
+    || trimmed.includes('[')
+    || trimmed.includes(']')
+  ) {
+    return false;
+  }
+
+  return isValidIPv4Address(trimmed) || isValidHostname(trimmed);
+}
+
+export const NtpServerHostSchema = z.string().trim().min(1).refine(isValidNtpServerHost, {
+  message: 'Invalid NTP server host',
+});
+
+const NtpServerArraySchema = z.array(NtpServerHostSchema).min(1).superRefine((servers, ctx) => {
+  const seen = new Set<string>();
+  for (const server of servers) {
+    if (seen.has(server)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate NTP server: ${server}`,
+      });
+      return;
+    }
+    seen.add(server);
+  }
+});
+
+export const NtpServerListSettingsSchema = z.object({
+  servers: NtpServerArraySchema,
+  defaultServers: NtpServerArraySchema,
+});
+export type NtpServerListSettings = z.infer<typeof NtpServerListSettingsSchema>;
+
+export const UpdateNtpServerListRequestSchema = z.object({
+  servers: NtpServerArraySchema,
+});
+export type UpdateNtpServerListRequest = z.infer<typeof UpdateNtpServerListRequestSchema>;

package/src/schema/transmission.schema.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { FrameMessageSchema, SlotInfoSchema } from './slot-info.schema.js';
+// 导入已存在的类型，避免重复定义
+export { StrategiesResultSchema } from './qso.schema.js';
+export type { StrategiesResult } from './qso.schema.js';
+export { CycleInfoSchema } from './cycle.schema.js';
+export type { CycleInfo } from './cycle.schema.js';
+
+/**
+ * 传输策略相关类型定义
+ * 用于操作员运行时状态与插件策略交互
+ *
+ * 注意：StrategiesResult、CycleInfo 已在其他 schema 中定义，这里重新导出
+ */
+
+// ========== 策略状态类型 ==========
+
+/**
+ * 策略状态信息
+ */
+export const StrategyStateSchema = z.object({
+  name: z.string(), // 策略名称（如 standard-qso）
+  state: z.string(), // 当前状态（如 TX1, TX2, IDLE 等）
+  availableSlots: z.array(z.string()), // 可用的时隙列表
+  metadata: z.record(z.any()).optional(), // 状态的额外信息
+});
+
+// ========== 呼叫请求类型 ==========
+
+/**
+ * 呼叫请求参数
+ */
+export const CallRequestSchema = z.object({
+  callsign: z.string(), // 目标呼号
+  lastMessage: z.object({
+    message: FrameMessageSchema,
+    slotInfo: SlotInfoSchema,
+  }).optional(), // 从目标接收到的最后一条消息
+});
+
+// ========== 传输请求类型 ==========
+
+/**
+ * 传输请求（已在 websocket.schema.ts 中定义）
+ * TransmitRequestSchema
+ */
+
+// ========== 时隙映射类型 ==========
+
+/**
+ * 操作员时隙配置
+ */
+export const OperatorSlotsSchema = z.object({
+  TX1: z.string().optional(),
+  TX2: z.string().optional(),
+  TX3: z.string().optional(),
+  TX4: z.string().optional(),
+  TX5: z.string().optional(),
+  TX6: z.string().optional(),
+});
+
+// ========== QSO 上下文类型 (已在 qso.schema.ts 中定义) ==========
+
+/**
+ * QSO 上下文（已在 qso.schema.ts 中定义为 QSOContextSchema）
+ * 包含：myCall, myGrid, targetCall, targetGrid, reportSent, reportReceived 等
+ */
+
+// ========== 操作员事件数据类型 ==========
+
+/**
+ * 操作员时隙更新事件数据
+ */
+export const OperatorSlotsUpdatedEventSchema = z.object({
+  operatorId: z.string(),
+  slots: OperatorSlotsSchema,
+});
+
+/**
+ * 操作员时隙内容变更事件数据
+ */
+export const OperatorSlotContentChangedEventSchema = z.object({
+  operatorId: z.string(),
+  slotName: z.string(),
+  content: z.string(),
+});
+
+/**
+ * 操作员发射周期变更事件数据
+ */
+export const OperatorTransmitCyclesChangedEventSchema = z.object({
+  operatorId: z.string(),
+  transmitCycles: z.array(z.number().min(0).max(1)),
+});
+
+// ========== 导出 TypeScript 类型 ==========
+
+// StrategiesResult、CycleInfo 已在文件顶部重新导出
+
+export type StrategyState = z.infer<typeof StrategyStateSchema>;
+export type CallRequest = z.infer<typeof CallRequestSchema>;
+export type OperatorSlots = z.infer<typeof OperatorSlotsSchema>;
+export type OperatorSlotsUpdatedEvent = z.infer<typeof OperatorSlotsUpdatedEventSchema>;
+export type OperatorSlotContentChangedEvent = z.infer<typeof OperatorSlotContentChangedEventSchema>;
+export type OperatorTransmitCyclesChangedEvent = z.infer<typeof OperatorTransmitCyclesChangedEventSchema>;

package/src/schema/voice.schema.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * 语音 PTT 锁状态
+ * 语音模式下同一时刻只能有一个用户发射，通过独占锁管理
+ */
+export const VoicePTTLockSchema = z.object({
+  /** 是否被锁定（有人在发射） */
+  locked: z.boolean(),
+  /** 持有锁的客户端 ID */
+  lockedBy: z.string().nullable(),
+  /** 持有锁的用户显示名（token label 或 "Admin"） */
+  lockedByLabel: z.string().nullable(),
+  /** 锁定时间戳 */
+  lockedAt: z.number().nullable(),
+  /** 超时时间（ms），超时后自动释放 */
+  timeoutMs: z.number().default(180000),
+});
+
+export type VoicePTTLock = z.infer<typeof VoicePTTLockSchema>;
+
+/**
+ * 引擎模式枚举
+ * digital: FT8/FT4 等数字模式
+ * voice: 语音通联模式（SSB/FM/AM）
+ */
+export const EngineModeSchema = z.enum(['digital', 'voice']);
+export type EngineMode = z.infer<typeof EngineModeSchema>;