@ham2k/extension-sdk 0.1.0

package/dist/scoring.js

@@ -0,0 +1,163 @@
+const DAY_IN_MILLIS = 1e3 * 60 * 60 * 24;
+function copyCheckpoint(sheet) {
+  return JSON.parse(JSON.stringify(sheet));
+}
+function dayOf(qso) {
+  const millis = Number(qso.startAtMillis ?? 0);
+  return millis - millis % DAY_IN_MILLIS;
+}
+function chronological(qsos) {
+  return [...qsos].sort((a, b) => Number(a.startAtMillis ?? 0) - Number(b.startAtMillis ?? 0));
+}
+function isEvent(qso) {
+  return qso.band === "event";
+}
+function startAtMillisOf(qso) {
+  const at = qso.startAtMillis;
+  return typeof at === "number" ? at : 0;
+}
+function contestScorer(scorer, options = {}) {
+  const scope = options.scope ?? "always";
+  const scopedRefTypes = typeof scope === "object" && Array.isArray(scope.refTypes) ? scope.refTypes : void 0;
+  function refOfScopedType(operation) {
+    if (!scopedRefTypes) return void 0;
+    const refs = operation.refs ?? [];
+    return refs.find((r) => typeof r?.type === "string" && scopedRefTypes.includes(r.type));
+  }
+  function fold(scoresheet, qsos, args, ctx, onQso, onDayEnd, segments) {
+    let sheet = scoresheet;
+    let currentDay;
+    let dayCount = 0;
+    const timeline = segments && segments.length > 1 ? segments : void 0;
+    let segmentIndex = 0;
+    for (const qso of qsos) {
+      if (isEvent(qso)) continue;
+      let operation = args.operation;
+      let ref = args.ref;
+      if (timeline) {
+        const at = startAtMillisOf(qso);
+        while (segmentIndex + 1 < timeline.length && timeline[segmentIndex + 1].fromMillis <= at) segmentIndex += 1;
+        operation = timeline[segmentIndex].operation;
+        if (scopedRefTypes) {
+          const segmentRef = refOfScopedType(operation);
+          if (!segmentRef) continue;
+          ref = segmentRef;
+        }
+      }
+      const day = dayOf(qso);
+      const isNewDay = currentDay !== day;
+      if (isNewDay) {
+        if (currentDay !== void 0) onDayEnd?.(currentDay, dayCount, sheet);
+        currentDay = day;
+        dayCount = 0;
+      }
+      dayCount += 1;
+      const result = scorer.scoreQso({ scoresheet: sheet, qso, operation, ref, isNewDay }, ctx);
+      sheet = result.scoresheet;
+      onQso?.(typeof qso.uuid === "string" ? qso.uuid : void 0, result.score);
+    }
+    if (currentDay !== void 0) onDayEnd?.(currentDay, dayCount, sheet);
+    return sheet;
+  }
+  async function liveScoresheet(args, ctx, excludeUuid) {
+    if (args.resumeFrom !== void 0) {
+      return copyCheckpoint(args.resumeFrom);
+    }
+    const uuid = typeof args.operation.uuid === "string" ? args.operation.uuid : void 0;
+    const log = uuid ? await ctx.getQsos?.(uuid) ?? [] : [];
+    const rest = chronological(log).filter(
+      (q) => !excludeUuid || q.uuid !== excludeUuid
+    );
+    return fold(
+      scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx),
+      rest,
+      args,
+      ctx,
+      void 0,
+      void 0,
+      args.segments
+    );
+  }
+  return {
+    scope,
+    async scoreQsos(args, ctx) {
+      const qsos = chronological(args.qsos);
+      const start = args.resumeFrom !== void 0 ? copyCheckpoint(args.resumeFrom) : scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx);
+      const qsoScores = {};
+      const daySections = [];
+      const end = fold(
+        start,
+        qsos,
+        args,
+        ctx,
+        (uuid, score) => {
+          if (uuid) qsoScores[uuid] = score;
+        },
+        (day, count, sheet) => {
+          daySections.push({
+            day,
+            count,
+            scores: scorer.summarizeScore({ scoresheet: sheet, operation: args.operation, ref: args.ref, scope: "day" }, ctx)
+          });
+        },
+        args.segments
+      );
+      return {
+        qsoScores,
+        daySections,
+        operationSummary: scorer.summarizeScore(
+          { scoresheet: end, operation: args.operation, ref: args.ref, scope: "operation" },
+          ctx
+        ),
+        scoresheet: end
+      };
+    },
+    /// Live path: score the candidate against the log so far and report only
+    /// its notices/alerts. Nothing is recorded — the resulting scoresheet is
+    /// discarded, which is exactly why one `scoreQso` can serve both paths.
+    async scoreQso(args, ctx) {
+      const sheet = await liveScoresheet(args, ctx, args.excludeUuid);
+      const { score } = scorer.scoreQso(
+        { scoresheet: sheet, qso: args.qso, operation: args.operation, ref: args.ref, isNewDay: false },
+        ctx
+      );
+      return { notices: score.notices ?? [], alerts: score.alerts ?? [] };
+    },
+    /// The same live judgement as `scoreQso`, for many candidates at once —
+    /// the Spots Panel annotating every spot on screen. The log is folded ONCE
+    /// and each candidate scored against its own copy of the result, so a
+    /// candidate can neither see nor become a duplicate of another (both spots
+    /// for the same unworked call read as unworked, which is what an operator
+    /// scanning a band expects).
+    ///
+    /// The copy is per candidate rather than per call because
+    /// `ContestScorer.scoreQso` may mutate the scoresheet it is handed — the
+    /// contract that makes the batch fold linear. Without it the first
+    /// candidate's call would count as worked for every candidate after it.
+    async scoreCandidates(args, ctx) {
+      const base = await liveScoresheet(args, ctx);
+      const result = {};
+      for (const candidate of args.candidates) {
+        const { score } = scorer.scoreQso(
+          {
+            scoresheet: copyCheckpoint(base),
+            qso: candidate.qso,
+            operation: args.operation,
+            ref: args.ref,
+            isNewDay: false
+          },
+          ctx
+        );
+        result[candidate.key] = { notices: score.notices ?? [], alerts: score.alerts ?? [] };
+      }
+      return result;
+    }
+  };
+}
+function tally(key, forScope, total, extra = {}) {
+  return { key, for: forScope, total, ...extra };
+}
+export {
+  contestScorer,
+  tally
+};

package/dist/settingsPanels.js

@@ -0,0 +1,59 @@
+function isValidHookKey(category, extensionKey, resolvedKey) {
+  if (category !== "settingsPanel" && category !== "account") return true;
+  return resolvedKey === extensionKey || resolvedKey.startsWith(`${extensionKey}_`);
+}
+function tier1FormDefinition(hook) {
+  return { title: hook.title, elements: hook.fields ?? [] };
+}
+function settingsPanelEntriesFor(record, descriptors) {
+  const hook = record.hook;
+  if (hook.kind === "simple") {
+    return [
+      {
+        panelKey: record.key,
+        hookKey: record.key,
+        extensionKey: record.extensionKey,
+        title: hook.title ?? null,
+        icon: hook.icon ?? null,
+        order: hook.order ?? null,
+        kind: "simple",
+        sidebar: hook.sidebar ?? true,
+        dataFilesSection: hook.dataFilesSection ?? false
+      }
+    ];
+  }
+  if (hook.kind === "dynamic") {
+    if (descriptors) {
+      return descriptors.filter((d) => isValidHookKey("settingsPanel", record.extensionKey, d.key)).map((d) => ({
+        panelKey: d.key,
+        hookKey: record.key,
+        extensionKey: record.extensionKey,
+        title: d.title ?? null,
+        icon: d.icon ?? null,
+        order: d.order ?? null,
+        kind: "dynamic",
+        sidebar: d.sidebar ?? true,
+        dataFilesSection: d.dataFilesSection ?? false
+      }));
+    }
+    return [
+      {
+        panelKey: record.key,
+        hookKey: record.key,
+        extensionKey: record.extensionKey,
+        title: null,
+        icon: null,
+        order: null,
+        kind: "dynamic",
+        sidebar: true,
+        dataFilesSection: false
+      }
+    ];
+  }
+  return [];
+}
+export {
+  isValidHookKey,
+  settingsPanelEntriesFor,
+  tier1FormDefinition
+};

package/dist/templateContext.js

@@ -0,0 +1,113 @@
+function utcDate(millis) {
+  return new Date(millis).toISOString().slice(0, 10);
+}
+function utcDateCompact(millis) {
+  return utcDate(millis).replace(/-/g, "");
+}
+function utcTime(millis) {
+  return new Date(millis).toISOString().slice(11, 16).replace(":", "");
+}
+function utcIso(millis) {
+  return new Date(millis).toISOString();
+}
+function dateValues(millis) {
+  return {
+    date: utcDate(millis),
+    dateCompact: utcDateCompact(millis),
+    time: utcTime(millis),
+    at: utcIso(millis)
+  };
+}
+function opValues(operation, extra = {}) {
+  const station = String(operation.stationCall ?? "");
+  const startMillis = Number(operation.startAtMillisMin ?? operation.startAtMillis ?? 0);
+  const endMillis = Number(operation.startAtMillisMax ?? 0);
+  const atMillis = extra.atMillis && extra.atMillis > 0 ? extra.atMillis : startMillis;
+  return {
+    ...atMillis > 0 ? dateValues(atMillis) : { date: "", dateCompact: "", time: "", at: "" },
+    station,
+    // Deduped, like halo_core's `Operation.stationCalls`: "N0DEV, N0DEV" is a
+    // typo, and a template fanning out over this would otherwise repeat
+    // itself once per typo.
+    stations: [
+      ...new Set(
+        station.split(",").map((call) => call.trim().toUpperCase()).filter((call) => call !== "")
+      )
+    ],
+    operator: operation.operator ?? "",
+    // The generated, ref-derived title ("at US-1234") and the operator's own
+    // words, kept apart: an export that withholds private data withholds the
+    // second and keeps the first (see the adif hook's preamble).
+    title: operation.title ?? "",
+    userTitle: operation.userTitle ?? "",
+    grid: operation.grid ?? "",
+    refs: operation.refs ?? [],
+    uuid: operation.uuid ?? "",
+    qsoCount: extra.qsoCount ?? Number(operation.qsoCount ?? 0),
+    startDate: startMillis > 0 ? utcDate(startMillis) : "",
+    startTime: startMillis > 0 ? utcTime(startMillis) : "",
+    startAt: startMillis > 0 ? utcIso(startMillis) : "",
+    endDate: endMillis > 0 ? utcDate(endMillis) : "",
+    endTime: endMillis > 0 ? utcTime(endMillis) : "",
+    endAt: endMillis > 0 ? utcIso(endMillis) : ""
+  };
+}
+function qsoValues(qso) {
+  const their = qso.their ?? {};
+  const our = qso.our ?? {};
+  const startMillis = Number(qso.startAtMillis ?? 0);
+  return {
+    call: their.call ?? "",
+    their,
+    our,
+    band: qso.band ?? "",
+    mode: qso.mode ?? "",
+    freq: qso.freq ?? "",
+    // Named for what an operator calls them, not for QSON's `sent` on both
+    // sides — `qso.our.sent` is what WE sent, i.e. the report they received.
+    rstSent: our.sent ?? "",
+    rstRcvd: their.sent ?? "",
+    notes: qso.notes ?? "",
+    refs: qso.refs ?? [],
+    ...startMillis > 0 ? dateValues(startMillis) : { date: "", dateCompact: "", time: "", at: "" },
+    startAtMillis: startMillis
+  };
+}
+function logValues(values) {
+  return {
+    station: values.station ?? "",
+    ref: values.ref ?? "",
+    refName: values.refName ?? "",
+    refShortName: values.refShortName ?? "",
+    activity: values.activity ?? "",
+    handlerName: values.handlerName ?? "",
+    handlerShortName: values.handlerShortName ?? "",
+    format: values.format ?? "",
+    exportType: values.exportType ?? "",
+    modifier: values.modifier ?? "",
+    extension: values.extension ?? "",
+    compact: values.compact === true
+  };
+}
+function templateContext(args) {
+  const nowMillis = args.nowMillis ?? Date.now();
+  return {
+    app: { name: args.appName ?? "" },
+    now: utcIso(nowMillis),
+    ...args.operation ? { op: opValues(args.operation, { qsoCount: args.qsoCount, atMillis: args.atMillis }) } : {},
+    ...args.qso ? { qso: qsoValues(args.qso) } : {},
+    ...args.log ? { log: logValues(args.log) } : {},
+    ...args.config ? { config: args.config } : {}
+  };
+}
+export {
+  dateValues,
+  logValues,
+  opValues,
+  qsoValues,
+  templateContext,
+  utcDate,
+  utcDateCompact,
+  utcIso,
+  utcTime
+};

package/dist/templates.js

@@ -0,0 +1,76 @@
+import { Liquid } from "liquidjs";
+const RENDER_LIMIT_MS = 250;
+let engine;
+function liquid() {
+  if (engine) return engine;
+  engine = new Liquid({
+    // UTC, always. Amateur radio logs are kept in UTC, and liquid's `date`
+    // filter otherwise formats in the HOST's zone — wrong in a way no
+    // tester in UTC±0 can see, exactly like `toLocaleString` with a
+    // `timeZone` on this engine (docs/extensions/README.md).
+    //
+    // The sign is INVERTED from what the name suggests: this follows
+    // `Date.getTimezoneOffset()`, i.e. minutes BEHIND UTC, so -300 would
+    // render UTC+5. Zero is the only value with no trap in it.
+    timezoneOffset: 0,
+    // Lenient, because most templates are written by operators rather than
+    // by us: an unknown variable renders empty and an unknown filter passes
+    // its value through, so a typo costs one wrong line instead of the whole
+    // document. Our own templates are covered by tests instead.
+    strictVariables: false,
+    strictFilters: false,
+    renderLimit: RENDER_LIMIT_MS
+  });
+  registerFilters(engine);
+  return engine;
+}
+function registerFilters(liquid2) {
+  liquid2.registerFilter(
+    "dash",
+    (value) => String(value ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")
+  );
+  liquid2.registerFilter("alnum", (value) => String(value ?? "").replace(/[^A-Za-z0-9]/g, ""));
+}
+class TemplateError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "TemplateError";
+    this.cause = options?.cause;
+  }
+}
+const parsed = /* @__PURE__ */ new Map();
+const PARSE_CACHE_LIMIT = 64;
+function renderTemplate(template, context, label) {
+  const source = template ?? "";
+  try {
+    let compiled = parsed.get(source);
+    if (!compiled) {
+      compiled = liquid().parse(source);
+      if (parsed.size >= PARSE_CACHE_LIMIT) parsed.clear();
+      parsed.set(source, compiled);
+    }
+    return liquid().renderSync(compiled, context);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new TemplateError(label ? `${label}: ${message}` : message, { cause: e });
+  }
+}
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function triggersForTemplate(template) {
+  const text = (template ?? "").match(/\{\{.*?\}\}|\{%.*?%\}/gs)?.join(" ") ?? "";
+  const mentions = (name) => new RegExp(`\\b${name}\\b`).test(text);
+  const triggers = [];
+  if (mentions("qso")) triggers.push("qso", "lookup");
+  if (mentions("qsoCount")) triggers.push("qsoLogged");
+  if (mentions("op") || mentions("operation")) triggers.push("operation");
+  if (mentions("now")) triggers.push("tick:30");
+  return triggers;
+}
+export {
+  TemplateError,
+  oneLine,
+  renderTemplate,
+  triggersForTemplate
+};

package/dist/testOperation.js

@@ -0,0 +1,6 @@
+function isTestOperation(stationCall) {
+  return String(stationCall ?? "").split(",").flatMap((call) => call.trim().toUpperCase().split("/")).some((segment) => segment === "T" || segment === "TEST");
+}
+export {
+  isTestOperation
+};

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@ham2k/extension-sdk",
+  "version": "0.1.0",
+  "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
+  "keywords": [
+    "ham2k",
+    "ham radio",
+    "amateur radio",
+    "extension",
+    "sdk",
+    "logging"
+  ],
+  "license": "MPL-2.0",
+  "author": "Sebastian Delmont <sd@ham2k.com>",
+  "homepage": "https://ham2k.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ham2k/halo.git",
+    "directory": "extensions/sdk"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "//sideEffects": [
+    "Importing any of these modules does nothing observable, so a bundler may",
+    "drop whichever ones an extension never reaches. dxcc is the exception and",
+    "is named rather than waved through: it registers the built-in country file",
+    "at import time, and a bundler that dropped it would leave callsign",
+    "annotation quietly answering with nothing."
+  ],
+  "sideEffects": [
+    "./dist/dxcc.js"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "//peerDependencies": [
+    "The libraries the extension host carries. An extension does NOT need these",
+    "installed: the build preset rewrites each one the manifest declares into a",
+    "lookup on the host's single instance, before esbuild ever resolves it, and",
+    "the published .d.ts carries their types rolled in. They are here, optional,",
+    "for the one case that does reach the filesystem \u2014 `inline: [...]`, which",
+    "ships your own copy because you need a version the host does not carry."
+  ],
+  "peerDependencies": {
+    "@ham2k/lib-callsigns": "*",
+    "@ham2k/lib-country-files": "*",
+    "@ham2k/lib-cqmag-data": "*",
+    "@ham2k/lib-dxcc-data": "*",
+    "@ham2k/lib-format-tools": "*",
+    "@ham2k/lib-geo-tools": "*",
+    "@ham2k/lib-operation-data": "*",
+    "@ham2k/lib-qson-adif": "*",
+    "@ham2k/lib-qson-cabrillo": "*",
+    "@ham2k/lib-qson-tools": "*",
+    "i18next": "*",
+    "liquidjs": "*"
+  },
+  "peerDependenciesMeta": {
+    "@ham2k/lib-callsigns": {
+      "optional": true
+    },
+    "@ham2k/lib-country-files": {
+      "optional": true
+    },
+    "@ham2k/lib-cqmag-data": {
+      "optional": true
+    },
+    "@ham2k/lib-dxcc-data": {
+      "optional": true
+    },
+    "@ham2k/lib-format-tools": {
+      "optional": true
+    },
+    "@ham2k/lib-geo-tools": {
+      "optional": true
+    },
+    "@ham2k/lib-operation-data": {
+      "optional": true
+    },
+    "@ham2k/lib-qson-adif": {
+      "optional": true
+    },
+    "@ham2k/lib-qson-cabrillo": {
+      "optional": true
+    },
+    "@ham2k/lib-qson-tools": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "liquidjs": {
+      "optional": true
+    }
+  }
+}