@ham2k/extension-sdk 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sebastian Delmont <sd@ham2k.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -53,6 +53,26 @@ offline and describe the version installed here rather than whatever the
 repository says today. If an agent is writing your extension, point it at
 `node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
+## Export types and settings
+
+Export hooks can register shared types with `getExportTypes()`. Use
+`exportTypeDefinition(activationType, format, label)` for an identity shared
+by extensions serving the same activity. `exportType` identifies the settings;
+`exportKey` identifies an individual file, such as one park in an activation.
+
+The `activityExportHook` and `huntingExportHook` helpers register their types
+and forward export settings to the ADIF generator. Reference activity types
+use `templateCategory: 'reference'`; other types use the other-activity defaults.
+`GlobalExportSettings` provides separate normal filename, compact filename,
+and title templates for each category, plus shared ADIF field templates.
+
+When updating an exporter from SDK 0.3, keep a reference-specific identifier
+in `exportKey`, register a stable `exportType`, and forward `exportSettings`,
+`exportData`, `exportTitle`, and `includeLookupData` when delegating generation.
+Per-type custom templates override inherited defaults only when enabled.
+See `docs/hooks.md` §`export` for the complete contract and `docs/forms.md`
+for the `textTemplate` form field.
+
 ## About the peer dependencies
 
 This package lists the libraries the extension host carries — `@ham2k/lib-*`,
@@ -67,7 +87,3 @@ in, so your editor works with only this package installed.
 
 Install one only to `inline` it — to ship your own copy because you need a
 version the host does not carry.
-
-## License
-
-MPL-2.0

package/dist/activityExports.js

@@ -1,4 +1,6 @@
+import { exportTypeDefinition } from "./exportSettings.js";
 import { exportFilename, startMillisOf } from "./exportNames.js";
+import { segmentsWith } from "./segments.js";
 import { createCachedTranslator } from "./i18n.js";
 import en from "./i18n/activityExports.en.json";
 import es from "./i18n/activityExports.es.json";
@@ -20,11 +22,23 @@ function filenameFor(operation, qsos, ref, compact) {
 function activityExportHook(rules) {
   const prefix = `${rules.key}-adif`;
   return {
+    async getExportTypes() {
+      return [{
+        ...exportTypeDefinition(rules.activationType, "adif", rules.label),
+        templateCategory: "reference",
+        templateSample: rules.templateSample ?? {
+          log: { ref: "REF-1234", refName: "Example Reference" },
+          operation: { refs: [{ type: rules.activationType, ref: "REF-1234" }] }
+        }
+      }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       const refs = refsOfType(operation, rules.activationType);
       const t = tFor(ctx);
       return refs.map((ref) => ({
-        exportType: `${prefix}${SEPARATOR}${ref.ref}`,
+        exportType: `${rules.activationType}-adif`,
+        templateData: { ref: ref.ref, refName: ref.name ?? "", activity: rules.label },
+        exportKey: `${prefix}${SEPARATOR}${ref.ref}`,
         format: "adif",
         // The FORMAT leads: a park activated on a contest weekend offers
         // several files for the same reference, and "POTA US-1234" alone said
@@ -43,21 +57,29 @@ function activityExportHook(rules) {
     },
     async generateExport(args, ctx) {
       const exportType = String(args.exportType ?? "");
-      if (!exportType.startsWith(`${prefix}${SEPARATOR}`)) {
-        throw new Error(`${rules.key}: unknown export type '${exportType}'`);
+      const exportKey = String(args.exportKey ?? "");
+      if (exportType !== `${rules.activationType}-adif` || !exportKey.startsWith(`${prefix}${SEPARATOR}`)) {
+        throw new Error(`${rules.key}: unknown export type/key '${exportType}' / '${exportKey}'`);
       }
-      const wanted = exportType.slice(prefix.length + SEPARATOR.length);
+      const wanted = exportKey.slice(prefix.length + SEPARATOR.length);
       if (!refsOfType(args.operation, rules.activationType).some((r) => r.ref === wanted)) {
         throw new Error(`${rules.key}: operation has no ${rules.activationType} reference '${wanted}'`);
       }
-      const refs = (args.operation.refs ?? []).filter(
-        (r) => r?.type !== rules.activationType || r?.ref === wanted
-      );
-      const operation = { ...args.operation, refs };
+      const claimOnly = (operation) => ({
+        ...operation,
+        refs: (operation.refs ?? []).filter(
+          (r) => r?.type !== rules.activationType || r?.ref === wanted
+        )
+      });
       const content = await adifForExport({
-        operation,
+        operation: claimOnly(args.operation),
         qsos: args.qsos,
+        segments: segmentsWith(args.segments, claimOnly),
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         mainHandler: rules.key,
         includeFieldsFrom: rules.includeFieldsFrom
       });
@@ -79,17 +101,22 @@ function filenameForHunt(operation, qsos, activity, compact) {
   });
 }
 function huntingExportHook(rules) {
-  const exportType = `${rules.key}-hunter`;
+  const exportType = `${rules.huntingType}-hunter`;
   function huntedQsos(qsos) {
     return qsos.filter((qso) => refsOfType(qso, rules.huntingType).length > 0);
   }
   return {
+    async getExportTypes() {
+      return [{ exportType, format: "adif", label: `${rules.label} Hunter Log` }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       if (refsOfType(operation, rules.activationType).length > 0) return [];
       if (huntedQsos(qsos ?? []).length === 0) return [];
       const t = tFor(ctx);
       return [{
         exportType,
+        qsoCount: huntedQsos(qsos ?? []).length,
+        templateData: { activity: rules.label },
         format: "adif",
         label: t("adifForHunter", { program: rules.label }),
         filename: filenameForHunt(operation, qsos ?? [], rules.label, compactFilenames),
@@ -113,7 +140,12 @@ function huntingExportHook(rules) {
       const content = await adifForExport({
         operation: args.operation,
         qsos: huntedQsos(args.qsos ?? []),
+        segments: args.segments,
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         // The hunter file is submitted to ONE program too — see
         // `activityExportHook.generateExport`. `rules.key` is the ACTIVITY's
         // key ('pota'), which is what its `adifFields` hook registers under;
@@ -131,15 +163,20 @@ function huntingExportHook(rules) {
     }
   };
 }
-async function adifForExport({ operation, qsos, includePrivateData, mainHandler, includeFieldsFrom }) {
+async function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
     operation,
     qsos,
+    segments,
     exportType: "adif",
     // Forwarded, or the delegate defaults to withholding and the user's
     // "include private info" setting silently does nothing here.
     includePrivateData,
+    includeLookupData,
+    exportSettings,
+    exportData,
+    exportTitle,
     mainHandler,
     includeFieldsFrom
   });

package/dist/activityScoring.js

@@ -127,6 +127,8 @@ function activityScorer(rules) {
         score.alerts = ["duplicate"];
       } else if (verdict) {
         score.notices = [NOTICE_KEYS[verdict]];
+      } else if (priors.length > 0 && score.value > 0 && freshRefRescuesActivation) {
+        score.dupe = false;
       }
       const packed = packContact(day, band, mode, huntedRefs);
       if (priors.length > 0) priors.push(packed);

package/dist/dxcc.js

@@ -2,8 +2,8 @@ import { parseCallsign } from "@ham2k/lib-callsigns";
 import { annotateFromCountryFile, useBuiltinCountryFile } from "@ham2k/lib-country-files";
 import { DXCC_BY_CODE } from "@ham2k/lib-dxcc-data";
 useBuiltinCountryFile();
-function annotateCallAgainstCountryFile(call) {
-  return annotateFromCountryFile(parseCallsign(call));
+function annotateCallAgainstCountryFile(call, options) {
+  return annotateFromCountryFile(parseCallsign(call), options);
 }
 function entityPrefixForCall(call) {
   if (!call) return void 0;
@@ -17,8 +17,21 @@ function regionAndCountryForDxccCode(dxccCode) {
   const entity = DXCC_BY_CODE[dxccCode];
   return { ituRegion: entity?.ituRegion, countryCode: entity?.countryCode };
 }
+function countryPrefixForCall(call) {
+  if (!call) return void 0;
+  const annotated = annotateCallAgainstCountryFile(call);
+  const { countryCode } = regionAndCountryForDxccCode(annotated.dxccCode);
+  return countryCode ? countryCode.toUpperCase() : annotated.entityPrefix;
+}
+function entityForCall(call) {
+  if (!call) return {};
+  const { dxccCode, continent, entityName } = annotateCallAgainstCountryFile(call);
+  return { dxccCode, continent, entityName };
+}
 export {
   annotateCallAgainstCountryFile,
+  countryPrefixForCall,
+  entityForCall,
   entityPrefixForCall,
   flagForDxccCode,
   regionAndCountryForDxccCode

package/dist/exportSettings.js

@@ -0,0 +1,133 @@
+import { startMillisOf } from "./exportNames.js";
+import { templateContext } from "./templateContext.js";
+import { oneLine, renderTemplate } from "./templates.js";
+import { isTestOperation } from "./testOperation.js";
+const EXPORT_DEFAULTS = {
+  includePrivateData: false,
+  includeLookupData: true,
+  customTemplates: false,
+  filenameTemplate: "{{ op.date }} {{ log.station }}{% if log.ref != blank %} at {{ log.ref }}{% elsif log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  compactFilenameTemplate: "{{ log.station | dash }}{% if log.ref != blank %}@{{ log.ref | dash }}{% elsif log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  titleTemplate: "{{ log.station }}{% if log.ref != blank %}: {{ log.activity }} at {{ log.ref }} {{ log.refName }}{% elsif log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}",
+  adifNotesTemplate: "{{ qso.notes }}",
+  adifCommentTemplate: "{{ qso.notes }}",
+  adifQslMessageTemplate: ""
+};
+const GLOBAL_EXPORT_DEFAULTS = {
+  ...EXPORT_DEFAULTS,
+  referenceFilenameTemplate: "{{ op.date }} {{ log.station }} at {{ log.ref }} {{ log.modifier }}",
+  referenceCompactFilenameTemplate: "{{ log.station | dash }}@{{ log.ref | dash }}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  referenceTitleTemplate: "{{ log.station }}: {{ log.activity }} at {{ log.ref }} {{ log.refName }} on {{ op.date }}",
+  otherFilenameTemplate: "{{ op.date }} {{ log.station }}{% if log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  otherCompactFilenameTemplate: "{{ log.station | dash }}{% if log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  otherTitleTemplate: "{{ log.station }}{% if log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}"
+};
+function resolveGlobalExportSettings(global = {}) {
+  const resolved = { ...GLOBAL_EXPORT_DEFAULTS, ...global };
+  for (const prefix of ["reference", "other"]) {
+    for (const suffix of ["FilenameTemplate", "CompactFilenameTemplate", "TitleTemplate"]) {
+      const key = `${prefix}${suffix}`;
+      const legacy = `${suffix[0].toLowerCase()}${suffix.slice(1)}`;
+      if (global[key] === void 0 && typeof global[legacy] === "string") {
+        Object.assign(resolved, { [key]: global[legacy] });
+      }
+    }
+  }
+  return resolved;
+}
+function exportTypeDefinition(activationType, format, label, defaults) {
+  return { exportType: `${activationType}-${format}`, activationType, format, label, defaults };
+}
+const templateKeys = [
+  "filenameTemplate",
+  "compactFilenameTemplate",
+  "titleTemplate",
+  "adifNotesTemplate",
+  "adifCommentTemplate",
+  "adifQslMessageTemplate"
+];
+function resolveExportSettings(definition, global = {}, overrides = {}) {
+  const defaults = resolveGlobalExportSettings(global);
+  const reference = definition.templateCategory === "reference";
+  const resolved = {
+    includePrivateData: defaults.includePrivateData,
+    includeLookupData: defaults.includeLookupData,
+    adifNotesTemplate: defaults.adifNotesTemplate,
+    adifCommentTemplate: defaults.adifCommentTemplate,
+    adifQslMessageTemplate: defaults.adifQslMessageTemplate,
+    filenameTemplate: reference ? defaults.referenceFilenameTemplate : defaults.otherFilenameTemplate,
+    compactFilenameTemplate: reference ? defaults.referenceCompactFilenameTemplate : defaults.otherCompactFilenameTemplate,
+    titleTemplate: reference ? defaults.referenceTitleTemplate : defaults.otherTitleTemplate,
+    ...definition.defaults
+  };
+  for (const key of ["includePrivateData", "includeLookupData"]) {
+    if (typeof overrides[key] === "boolean") resolved[key] = overrides[key];
+  }
+  resolved.customTemplates = overrides.customTemplates === true;
+  if (resolved.customTemplates) {
+    for (const key of templateKeys) {
+      if (typeof overrides[key] === "string") resolved[key] = overrides[key];
+    }
+  }
+  if (definition.format !== "adif") {
+    delete resolved.includePrivateData;
+    delete resolved.includeLookupData;
+    for (const key of templateKeys.slice(2)) delete resolved[key];
+  }
+  return resolved;
+}
+function exportQso(qso, settings) {
+  const copy = { ...qso };
+  for (const side of ["their", "our"]) {
+    if (copy[side] && typeof copy[side] === "object" && !Array.isArray(copy[side])) {
+      const station = { ...copy[side] };
+      if (settings.includeLookupData === false) delete station.guess;
+      if (settings.includePrivateData === false) {
+        for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete station[key];
+        if (typeof station.grid === "string") station.grid = station.grid.slice(0, 6);
+        if (station.guess && typeof station.guess === "object") {
+          const guess = { ...station.guess };
+          for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete guess[key];
+          if (typeof guess.grid === "string") guess.grid = guess.grid.slice(0, 6);
+          station.guess = guess;
+        }
+      }
+      copy[side] = station;
+    }
+  }
+  if (settings.includePrivateData === false) delete copy.notes;
+  return copy;
+}
+function prepareExportOption(option, operation, qsos, compact) {
+  const settings = option.exportSettings;
+  const extension = { adif: "adi", cabrillo: "log", reg1test: "edi" }[option.format] ?? option.filename?.split(".").pop() ?? "txt";
+  const data = {
+    station: String(operation.stationCall ?? ""),
+    ref: "",
+    activity: "",
+    modifier: "",
+    ...option.templateData,
+    exportType: option.exportType,
+    format: option.format,
+    extension,
+    compact
+  };
+  if (isTestOperation(operation.stationCall)) data.modifier = [data.modifier, "Testing"].filter(Boolean).join(" ");
+  const context = templateContext({ operation, qsoCount: option.qsoCount ?? qsos.length, atMillis: startMillisOf(operation, qsos) ?? Date.now(), log: data });
+  const template = compact ? settings.compactFilenameTemplate : settings.filenameTemplate;
+  const rendered = oneLine(renderTemplate(template ?? "", context, "Export filename"));
+  const stem = rendered.replace(/[/\\:*?"<>|\x00-\x1f]+/g, "-").replace(/[. ]+$/g, "").trim() || "export";
+  const filename = stem.toLowerCase().endsWith(`.${extension}`) ? stem : `${stem}.${extension}`;
+  const titleContext = settings.includePrivateData === false ? { ...context, op: { ...context.op, title: "", userTitle: "", userNotes: "", grid: String(context.op.grid ?? "").slice(0, 6) }, log: { ...context.log, modifier: "" } } : context;
+  const title = oneLine(renderTemplate(settings.titleTemplate ?? "", titleContext, "Export title"));
+  return { ...option, filename, exportTitle: title, exportData: settings.includePrivateData === false ? { ...data, modifier: "" } : data };
+}
+export {
+  EXPORT_DEFAULTS,
+  GLOBAL_EXPORT_DEFAULTS,
+  exportQso,
+  exportTypeDefinition,
+  prepareExportOption,
+  resolveExportSettings,
+  resolveGlobalExportSettings
+};