@ham2k/extension-sdk 1.12.1 → 1.12.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 1.12.1
+// @ham2k/extension-sdk 1.12.2
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -1242,6 +1242,14 @@ export interface ChasingProgram {
 	supersedes?: string[];
 	refLabel?: string;
 	imports?: ChasingImporter[];
+	notices?: Partial<Record<ChaseNoticeVerdict, string>>;
+	modeLabels?: Record<string, string>;
+	translations?: Record<string, ChasingNoticeLabels>;
+}
+export type ChaseNoticeVerdict = "newRef" | "newBand" | "newMode" | "unconfirmed";
+export interface ChasingNoticeLabels {
+	notices?: Partial<Record<ChaseNoticeVerdict, string>>;
+	modeLabels?: Record<string, string>;
 }
 export interface ChasingImporter {
 	key: string;

package/docs/distribution.md

@@ -417,12 +417,14 @@ can move it forward from there.
 
 Which ones ship is staged. Today it is the catalog twin of every extension the
 app used to build in (see [Retired built-ins](#retired-built-ins)), so that an
-install moving off them has every one to hand with no network. Once installs
-still on a build with the built-ins are few enough, it shrinks to the eight a
-new install needs — `ham2k-pota`, `ham2k-sota`, `ham2k-wwff` and the five
-lookups — and the rest are fetched from the catalog when switched on
+install moving off them has every one to hand with no network, and
+`ham2k-dxcc`, which replaced the core `dxcc` chasing program and is on for
+everyone as that was. Once installs still on a build with the built-ins are few
+enough, it shrinks to the nine a new install needs — `ham2k-pota`,
+`ham2k-sota`, `ham2k-wwff`, `ham2k-dxcc` and the five lookups — and the rest
+are fetched from the catalog when switched on
 ([HALO-743](https://cabo.ham2k.com/halo/c/743)). The app's own tests rely on
-only those eight, the core, and the never-shipped samples, so the shrink
+only those nine, the core, and the never-shipped samples, so the shrink
 touches none of them.
 
 **They have to be kept current.** A pre-load is frozen into the binary, so

package/docs/hooks.md

@@ -1607,7 +1607,14 @@ registerHook("chasing", { key: "dxcc", hook: {
   without invoking anything. Raise `version` whenever the same contacts would
   claim something different: the app keeps no claim from an older version.
   `refLabel` is what one reference is called where a notice names it
-  ("New POTA Park"), the program's `label` when left out.
+  ("New POTA Park"), the program's `label` when left out. A program may
+  instead word a verdict's notice itself: `notices` by verdict (`newRef`,
+  `newBand`, `newMode`, `unconfirmed`), where `{{band}}` names the band a
+  new band is on and `{{mode}}` the mode a new mode is in, through
+  `modeLabels`, with both per language under `translations` (`{ es: {
+  notices, modeLabels } }`). A verdict it leaves out, or one whose notice
+  lacks the band or mode its words name, reads the app's way; a guess reads
+  "Probably …" around the program's words.
   `supersedes` names the scoring notices the program's verdicts stand in for
   (DXCC: `newDXCC`): wherever the program judges a call or a spot, the
   scorer's notice is dropped in favor of the verdict.
@@ -1662,9 +1669,12 @@ extension API 9: a bundle that registers a program declares `"api": 9`, which
 the packer enforces, so an older app — which would install it and never ask
 it anything — is never offered it.
 
-Implemented by: `dxcc` (core) — Mixed, per-band and per-mode slots for the
-station call worked from each entity; LoTW and paper QSLs confirm, LoTW credit
-verifies. `ham2k-pota` — one slot per park hunted, worked only; its
+Implemented by: `ham2k-dxcc` (catalog, pre-loaded; core `dxcc` until
+HALO-844) — Mixed, per-mode and per-band slots for the station call worked
+from each entity, worded "DXCC ATNO", "DXCC in CW", "DXCC in 80m"; LoTW and
+paper QSLs confirm, `credits.dxcc` verifies; the DXCC Challenge is a tally of
+its band slots. A stored goal for `dxcc` carries to it
+(`kRenamedChasePrograms`). `k2hrc-dxcc` is the SDK's worked example. `ham2k-pota` — one slot per park hunted, worked only; its
 hunted-parks export verifies. `ham2k-was` — Mixed, per-band and per-mode
 slots (plus FT8 and RTTY) for the station call worked from one 4-character
 grid; LoTW and paper QSLs confirm, `WAS` credit verifies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",

package/samples/README.md

@@ -10,6 +10,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 | `k2hrc-hamqth` | A callsign lookup, and the `account` hook that asks for a password |
 | `k2hrc-llota` | An award program: references, an offline list, activation scoring |
 | `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |
+| `k2hrc-dxcc` | A chasing program: what each contact counts toward, and how its notices read (extension API 9) |
 | `k2hrc-radio` | An HTML panel, and why you should probably write markdown instead |
 | `k2hrc-panel-scenes` | Experimental panel scenes: SVG artwork, controls and animations, with simulated radio and weather panels |
 | `k2hrc-panafall` | A radio's panadapter and waterfall in a scene, styled and tuned by click (extension API 7) |

package/samples/k2hrc-dxcc/build.mjs

@@ -0,0 +1,6 @@
+import { build } from "esbuild"
+import { buildExtension } from "@ham2k/extension-tools"
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log("built build/index.js")

package/samples/k2hrc-dxcc/manifest.json

@@ -0,0 +1,23 @@
+{
+  "key": "k2hrc-dxcc",
+  "name": "DXCC (sample)",
+  "shortName": "DXCC*",
+  "version": "1.0.0",
+  "description": "The DXCC entities a station has worked and confirmed, as a worked example of a chasing program",
+  "category": "award",
+  "icon": "earth",
+  "accentColor": "#2E7D32",
+  "api": 9,
+  "keywords": ["award", "dxcc", "chasing", "sample"],
+  "hooks": ["chasing"],
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}

package/samples/k2hrc-dxcc/src/index.ts

@@ -0,0 +1,104 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — a chasing program: what each contact counts toward.
+//
+// An award is a checklist, and a chasing program says which lines of it a
+// contact fills. The app keeps the best claim for each line, ranks spots by
+// what working the station would add, and alerts on what is new. The program
+// never reads the log: `claimsForQsos` is a pure function of each contact,
+// because the app also asks it about spots and about the call being typed.
+//
+// One contact makes several claims, one per kind of line the award keeps —
+// here DXCC's three: Mixed (any band, any mode), its band, and its mode. A
+// missing Mixed line is a new entity, a missing band or mode line a new band
+// or mode, and `notices` says how each reads ("DXCC in 80m").
+//
+// The rules here are DXCC's, simplified: the catalog's `ham2k-dxcc` adds
+// deleted entities, maritime mobile, satellites and the DXCC Challenge. See
+// `docs/hooks.md` §`chasing`.
+
+import { defineExtension, entityForCall } from "@ham2k/extension-sdk"
+import type { ChasingHook, JSONValue, QsoClaim } from "@ham2k/extension-sdk"
+import { parseCallsign } from "@ham2k/lib-callsigns"
+import { ADIF_MODES_AND_SUBMODES, superModeForMode } from "@ham2k/lib-operation-data"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+/// DXCC's three mode awards. `superModeForMode` calls anything it does not
+/// know `DATA`, so a mode is checked against ADIF's list first.
+const KNOWN_MODES = new Set(ADIF_MODES_AND_SUBMODES.map((mode) => mode.toUpperCase()))
+const AWARD_MODES: Record<string, string> = { CW: "CW", PHONE: "PHONE", DATA: "DIGITAL" }
+
+function obj(value: JSONValue | undefined): Record<string, JSONValue> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {}
+}
+
+/// Who the claim belongs to: an opaque string the program builds. DXCC goes
+/// to a call, for contacts made from one entity — KI2D and KI2D/P share a
+/// checklist, KI2D/VE2 keeps its own.
+function holderFor(station: Record<string, JSONValue>): string | undefined {
+  if (typeof station.call !== "string" || !station.call) return undefined
+  const call = station.call.trim().toUpperCase()
+  const base = parseCallsign(call).baseCall || call
+  const entity = typeof station.dxccCode === "number" ? station.dxccCode : entityForCall(call).dxccCode
+  return entity == null ? base : `${base}@${entity}`
+}
+
+/// `worked` from the contact itself, `confirmed` by a QSL the award takes.
+function levelOf(qso: Record<string, JSONValue>): Pick<QsoClaim, "level" | "by"> {
+  const qsl = obj(qso.qsl)
+  if (obj(qsl.lotw).received === true) return { level: "confirmed", by: "lotw" }
+  if (obj(qsl.qsl).received === true) return { level: "confirmed", by: "qsl" }
+  return { level: "worked" }
+}
+
+function claimsFor(qso: Record<string, JSONValue>): QsoClaim[] {
+  // An event marker's calls are placeholders, not stations.
+  if (qso.band === "event") return []
+  const their = obj(qso.their)
+  const holder = holderFor(obj(qso.our))
+  if (typeof their.call !== "string" || !holder) return []
+  const { dxccCode, entityName } = entityForCall(their.call)
+  if (dxccCode == null) return []
+
+  const base = { holder, ref: String(dxccCode), ...(entityName ? { label: entityName } : {}), ...levelOf(qso) }
+  const claims: QsoClaim[] = [{ ...base, band: null, mode: null }]
+  if (typeof qso.band === "string" && qso.band) claims.push({ ...base, band: qso.band, mode: null })
+  const mode = typeof qso.mode === "string" && KNOWN_MODES.has(qso.mode.toUpperCase()) ? AWARD_MODES[superModeForMode(qso.mode.toUpperCase())] : undefined
+  if (mode) claims.push({ ...base, band: null, mode })
+  return claims
+}
+
+const program: ChasingHook = {
+  // Plain data, read without calling anything. Raise `version` whenever the
+  // same contacts would claim something different.
+  program: {
+    label: "DXCC*",
+    icon: "earth",
+    version: 1,
+    editions: "lifetime",
+    notices: { newRef: "New DXCC* entity", newBand: "DXCC* on {{band}}", newMode: "DXCC* in {{mode}}" },
+    modeLabels: { PHONE: "Phone", DIGITAL: "Digital" },
+  },
+  // Keyed by each contact's uuid; one without a uuid has no key to answer under.
+  claimsForQsos: ({ qsos }) =>
+    Object.fromEntries(qsos.filter((qso) => typeof qso.uuid === "string" && qso.uuid).map((qso) => [qso.uuid as string, claimsFor(qso)])),
+  holdersFor: ({ station }) => {
+    const holder = holderFor(station)
+    return holder ? [holder] : []
+  },
+  // One tally per thing worth counting: entities, from their Mixed lines.
+  summarizeClaims: ({ slots }) => {
+    const entities = slots.filter((slot) => slot.band === null && slot.mode === null)
+    const confirmed = entities.filter((slot) => slot.level !== "worked").length
+    return { entities: { key: "entities", icon: "earth", label: `${entities.length} entities`, summary: `${confirmed} confirmed`, total: entities.length } }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("chasing", { hook: program, key: manifest.key })
+  },
+})