@ham2k/extension-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,231 @@
+export * from "./types";
+export * from "./i18n";
+export * from "./dxcc";
+export * from "./location";
+export * from "./modes";
+export * from "./scoring";
+export * from "./activityScoring";
+export * from "./activityExports";
+export * from "./activityAdifImport";
+export * from "./exportNames";
+export * from "./referenceActivity";
+export * from "./templates";
+export * from "./templateContext";
+export * from "./testOperation";
+let currentExtensionKey = "unknown";
+const privilegedHostCalls = {};
+function kernel() {
+  const k = globalThis.__polo;
+  if (!k) throw new Error("polo kernel not loaded; kernel.js must be evaluated before extension bundles");
+  return k;
+}
+function hostCallFn() {
+  const bound = privilegedHostCalls[currentExtensionKey] ?? Object.values(privilegedHostCalls)[0];
+  if (bound) return bound;
+  return (method, params) => kernel().hostCall(method, params);
+}
+function defineExtension(def) {
+  currentExtensionKey = def.key;
+  kernel().defineExtension({
+    ...def,
+    onActivation(api) {
+      if (typeof api.hostCall === "function") privilegedHostCalls[def.key] = api.hostCall;
+      return def.onActivation(api);
+    }
+  });
+}
+const hooks = {
+  /// EVERY hook in the category — including the CALLER's own. A hook that
+  /// delegates within its own category therefore re-enters itself; use
+  /// `invokeOne` when you know which extension you want.
+  invokeAll(category, method, args, online) {
+    return kernel().invokeLocal(category, method, args, online);
+  },
+  /// One named extension's hook.
+  ///
+  /// Prefer this over filtering `invokeAll`'s results for the key you wanted.
+  /// A contest's `generateExport` delegating the ADIF build is exactly the
+  /// recursive shape described above, and loops forever through `invokeAll`.
+  invokeOne(category, key, method, args, online) {
+    return kernel().invokeLocal(category, method, args, online, key);
+  },
+  /// Like `invokeAll`, but calls hooks one at a time in priority order,
+  /// threading each result into the next call's args via `fold` — needed
+  /// when later hooks must see earlier hooks' contributions.
+  invokeAllSequential(category, method, initialArgs, fold, online) {
+    return kernel().invokeLocalSequential(category, method, initialArgs, fold, online);
+  }
+};
+const host = {
+  async fetch(url, options) {
+    return await hostCallFn()("fetch", { url, ...options });
+  },
+  async kvGet(key) {
+    return await hostCallFn()("kvGet", { ns: currentExtensionKey, key });
+  },
+  /// The device's current GPS position, or null when location is
+  /// unavailable, denied, or off — for a command (e.g. WEATHER) that needs a
+  /// location fix and has no operation grid to fall back to. May prompt the
+  /// user for location permission the first time it's called.
+  async getLocation() {
+    return await hostCallFn()("getLocation", {});
+  },
+  /// Read-only build identity — platform, edition, version, build number,
+  /// git sha — for a command (REPORT) that needs to say exactly what build it
+  /// ran on. `buildNumber` is null on Dev; see VersionInfo.
+  async getVersionInfo() {
+    return await hostCallFn()("getVersionInfo", {});
+  },
+  /// The app's settings, read-only: resolved core values (theme, locale,
+  /// units, logging toggles, bands/modes, privacy consents, the active
+  /// profile's operatorCall, ...) plus every extension's settings group
+  /// under `extensions`. Never includes credentials or accounts — those
+  /// live in the platform keychain via the account hook system, not in
+  /// settings.
+  async getSettings() {
+    return await hostCallFn()("getSettings", {});
+  },
+  /// Writes settings into THIS extension's own group (surfaced to other
+  /// readers as `extensions.extension_<key>` in getSettings). The namespace
+  /// is injected here — core settings and other extensions' groups are not
+  /// writable.
+  async setSettings(values) {
+    await hostCallFn()("setSettings", { ns: currentExtensionKey, values });
+  },
+  /// Resolves what a SET/SHOW/HIDE command names against the app's settings.
+  ///
+  /// The catalog it searches is built from the app's declarative settings
+  /// registry, so it reaches every setting the settings screen would show and
+  /// respects the same `devMode`, `environment` and `visibleWhen` visibility
+  /// rules. None of that data — option lists, current values, commit routing
+  /// — exists on this side of the bridge, which is why the settings commands
+  /// ask rather than carrying their own list.
+  ///
+  /// `kind` narrows the search: `'show'`/`'hide'` reach only visibility
+  /// toggles and derive their own value from the verb, so `value` is for
+  /// `'set'` only. Never rejects: an unmatched query answers `{found: false}`,
+  /// which is the normal state of a half-typed command.
+  async searchSettings(params) {
+    return await hostCallFn()("searchSettings", { ...params });
+  },
+  async kvSet(key, value) {
+    await hostCallFn()("kvSet", { ns: currentExtensionKey, key, value });
+  },
+  async setAccountSession(session) {
+    const kvKey = kernel().getAccountKvKey(currentExtensionKey);
+    await hostCallFn()("setAccountSession", { ns: currentExtensionKey, kvKey, session });
+  },
+  /// Presents a ResultMessage imperatively — for hooks whose results can't
+  /// carry a `userMessage` (e.g. a lookup hitting an auth error). Hooks
+  /// that CAN return one (spots posting) should prefer that instead.
+  async showMessage(message) {
+    await hostCallFn()("showMessage", { ...message, ns: currentExtensionKey });
+  },
+  /// Looks up a string from the app's own translations (app/lib/i18n/
+  /// {en,es}.i18n.json) by its dot-path key (e.g. "settings.theme.title"),
+  /// in whatever locale is currently active — there's no separate
+  /// extension-i18n system, this is the same source of truth the rest of
+  /// the app reads via its generated `t[key]` lookup. Returns null if the
+  /// key doesn't exist or isn't a plain string (e.g. it needs interpolation
+  /// params, which this doesn't support).
+  async translate(key) {
+    return await hostCallFn()("translate", { key });
+  },
+  /// Same lookup as `translate`, but for many keys in one bridge round
+  /// trip — for a panel with a dozen-plus labels, that's a dozen-plus
+  /// fewer JS↔Dart hops than calling `translate` in a loop. Missing/non-
+  /// string keys come back as null, same as `translate`.
+  async translateAll(keys) {
+    return await hostCallFn()("translateAll", { keys });
+  },
+  /// A build-time secret by name, or null when this build has no such value.
+  ///
+  /// "Secret" in the sense every cloud platform uses it — real credentials and
+  /// plain per-build configuration alike: an award's API key, an OAuth client
+  /// id that differs per edition, a token tied to whoever's account pays.
+  ///
+  /// An extension reads the names that start with its own key — `sota` reads
+  /// `SOTA_*`. The kernel binds the caller's identity onto the call, so asking
+  /// for anything outside that prefix returns null. See
+  /// `app/lib/config/secret_policy.dart` for the two escape hatches.
+  ///
+  /// Expect null and degrade: a fresh checkout, a fork, and every CI build
+  /// without the value configured all have none, and a hook that throws
+  /// instead of returning empty takes its whole feature down for them.
+  ///
+  /// This is a stopgap around a flat map. A real secrets service, and flags to
+  /// gate the calls that use these, are follow-up work.
+  async secret(name) {
+    return await hostCallFn()("secret", { name });
+  },
+  async dbLookupSelectOne(category, key) {
+    return await hostCallFn()("dbLookupSelectOne", { category, key });
+  },
+  /// [subCategory], when given, filters IN THE QUERY rather than after —
+  /// which matters because of `limit`: a common word ("trail") can match
+  /// thousands of rows worldwide, and the query only returns the first 100
+  /// it happens to find. Filtering by subCategory afterward, in the caller,
+  /// can end up filtering an already-truncated set down to nothing even
+  /// though a real match exists — POTA, which scopes by the caller's own
+  /// DXCC entity, passes it here instead, so the limit applies to the
+  /// already-narrowed set. SOTA scopes by entity too but needs a PREFIX
+  /// match ([subCategory] here is exact-equals only), so it still filters
+  /// after the fact and is exposed to the same truncation bug this exists
+  /// to avoid.
+  ///
+  /// [activeOnly] drops rows whose `flags` is explicitly 0 — the convention a
+  /// data-file mapper follows for a reference its program has RETIRED — and is
+  /// in the query for the same `limit` reason: retirements cluster (a program
+  /// delists a whole class at once), so a search for a word that class shares
+  /// can fill the cap with retired rows and leave the live matches just past
+  /// it. A row that never said (`flags` null) is NOT retired and survives.
+  async dbLookupSelectAll(category, query, subCategory, activeOnly) {
+    return await hostCallFn()("dbLookupSelectAll", { category, query, subCategory, activeOnly });
+  },
+  async dbLookupSelectByLocation(category, lat, lon, delta, activeOnly) {
+    return await hostCallFn()("dbLookupSelectByLocation", { category, lat, lon, delta, activeOnly });
+  },
+  async showForm(form, state = {}) {
+    return kernel().host.showForm(form, state, currentExtensionKey);
+  },
+  statusBar: {
+    /// A transient single-line message, replacing any prior message under
+    /// the same `key`. `key` is automatically namespaced to this extension —
+    /// other extensions can't see or clear it.
+    async setMessage(params) {
+      await hostCallFn()("statusBarSetMessage", { ...params, ns: currentExtensionKey });
+    },
+    /// A transient progress bar under `key`; omit `value` for indeterminate.
+    async setProgress(params) {
+      await hostCallFn()("statusBarSetProgress", { ...params, ns: currentExtensionKey });
+    },
+    /// Removes the message/progress item under `key`, if any.
+    async clear(key) {
+      await hostCallFn()("statusBarClear", { key, ns: currentExtensionKey });
+    },
+    /// A richer, dismissible notice, replacing any prior undismissed notice
+    /// under the same `key`. Stays in the user's notice history after
+    /// dismissal.
+    async showNotice(params) {
+      await hostCallFn()("statusBarShowNotice", { ...params, ns: currentExtensionKey });
+    },
+    /// Dismisses the active notice under `key`, if any.
+    async dismissNotice(key) {
+      await hostCallFn()("statusBarDismissNotice", { key, ns: currentExtensionKey });
+    }
+  },
+  log(message) {
+    kernel().log(`[${currentExtensionKey}] ${message}`);
+  },
+  /// Pushes a later CommandInterpretation for the same `input` a `command`
+  /// hook's `interpret()` was called with — see CommandHook's doc. One-way,
+  /// like `log`: call it, don't await anything back.
+  updateInterpretation(input, interpretation) {
+    kernel().updateInterpretation(input, interpretation);
+  }
+};
+export {
+  defineExtension,
+  hooks,
+  host
+};

package/dist/location.js

@@ -0,0 +1,19 @@
+const LOCATION_ACCURACY = {
+  EXACT: 0,
+  // Believed to be the right grid6 — confirmed by contact or GPS.
+  ACCURATE: 2,
+  // Close enough, maybe a neighbouring grid — e.g. a SOTA summit.
+  REASONABLE: 10,
+  // May be off by a dozen grids — most POTA parks.
+  VAGUE: 100,
+  // No better than a general state/province.
+  NO_LOCATION: 1e3
+};
+function applyLatLonFromApiFields(target, raw) {
+  if (typeof raw.latitude === "number") target.lat = raw.latitude;
+  if (typeof raw.longitude === "number") target.lon = raw.longitude;
+}
+export {
+  LOCATION_ACCURACY,
+  applyLatLonFromApiFields
+};

package/dist/modes.js

@@ -0,0 +1,28 @@
+import { ADIF_MODES_AND_SUBMODES, ADIF_MODE_FOR_SUBMODE, superModeForMode } from "@ham2k/lib-operation-data";
+const SIDEBAND_SPELLINGS = /* @__PURE__ */ new Set(["SSB", "USB", "LSB"]);
+const MODE_ALIASES = { DV: "DIGITALVOICE" };
+const COARSE_SUPER_MODES = {
+  DATA: "DATA",
+  DIGI: "DATA",
+  DIGITAL: "DATA",
+  PHONE: "PHONE"
+};
+const KNOWN_MODES = new Set(ADIF_MODES_AND_SUBMODES.map((mode) => mode.toUpperCase()));
+function canonicalMode(mode) {
+  const upper = (mode ?? "").trim().toUpperCase();
+  if (SIDEBAND_SPELLINGS.has(upper)) return "SSB";
+  return MODE_ALIASES[upper] ?? upper;
+}
+function modesMatchForDupe(worked, candidate) {
+  const w = canonicalMode(worked);
+  const c = canonicalMode(candidate);
+  if (w === c) return true;
+  if (!w || !c) return false;
+  if (ADIF_MODE_FOR_SUBMODE[w] === c || ADIF_MODE_FOR_SUBMODE[c] === w) return true;
+  const superMode = COARSE_SUPER_MODES[c];
+  return Boolean(superMode) && KNOWN_MODES.has(w) && superModeForMode(w) === superMode;
+}
+export {
+  canonicalMode,
+  modesMatchForDupe
+};

package/dist/number-format.js

@@ -0,0 +1,68 @@
+function roundHalfExpand(absolute, digits) {
+  const source = String(absolute);
+  if (source.includes("e") || source.includes("E")) return absolute.toFixed(digits);
+  const dot = source.indexOf(".");
+  const whole = dot < 0 ? source : source.slice(0, dot);
+  const fraction = dot < 0 ? "" : source.slice(dot + 1);
+  if (fraction.length <= digits) {
+    const padded = fraction.padEnd(digits, "0");
+    return digits === 0 ? whole : `${whole}.${padded}`;
+  }
+  let kept = whole + fraction.slice(0, digits);
+  if (fraction.charCodeAt(digits) - 48 >= 5) {
+    const chars = kept.split("");
+    let i = chars.length - 1;
+    for (; ; ) {
+      if (i < 0) {
+        chars.unshift("1");
+        break;
+      }
+      if (chars[i] === "9") {
+        chars[i] = "0";
+        i--;
+      } else {
+        chars[i] = String(Number(chars[i]) + 1);
+        break;
+      }
+    }
+    kept = chars.join("");
+  }
+  const split = kept.length - digits;
+  const wholeOut = kept.slice(0, split) || "0";
+  return digits === 0 ? wholeOut : `${wholeOut}.${kept.slice(split)}`;
+}
+function formatNumberEnUS(n, options) {
+  if (!Number.isFinite(n)) return String(n);
+  if (Math.abs(n) >= 1e21) return String(n);
+  const minimum = options?.minimumFractionDigits ?? 0;
+  let maximum = options?.maximumFractionDigits ?? Math.max(minimum, 3);
+  if (maximum < minimum) maximum = minimum;
+  const negative = n < 0;
+  const absolute = Math.abs(n);
+  let text = roundHalfExpand(absolute, maximum);
+  if (maximum > minimum) {
+    text = text.replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
+    const dot = text.indexOf(".");
+    const decimals = dot < 0 ? 0 : text.length - dot - 1;
+    if (decimals < minimum) {
+      text = (dot < 0 ? `${text}.` : text) + "0".repeat(minimum - decimals);
+    }
+  }
+  const parts = text.split(".");
+  if (options?.useGrouping !== false) {
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  }
+  const out = parts.join(".");
+  return negative ? `-${out}` : out;
+}
+function installNumberFormatPolyfill() {
+  const engineFormats = 1234.5.toLocaleString("en-US", { maximumFractionDigits: 0 }) === "1,235";
+  if (engineFormats) return;
+  Number.prototype.toLocaleString = function(_locales, options) {
+    return formatNumberEnUS(Number(this), options);
+  };
+}
+export {
+  formatNumberEnUS,
+  installNumberFormatPolyfill
+};

package/dist/referenceActivity.js

@@ -0,0 +1,226 @@
+import { distanceOnEarth } from "@ham2k/lib-geo-tools";
+import { activityAdifImport } from "./activityAdifImport.js";
+async function hostApi() {
+  const { host } = await import("@ham2k/extension-sdk");
+  return host;
+}
+const NEARBY_DELTA = 1.5;
+const MAX_SUGGESTIONS = 30;
+function normalize(ref) {
+  return (ref ?? "").toUpperCase().trim();
+}
+function refsOfType(container, type) {
+  return (container.refs ?? []).filter((r) => r.type === type && r.ref);
+}
+function relevanceForMatch(row, searchTerm) {
+  if (!searchTerm) return 1;
+  const term = searchTerm.toUpperCase();
+  const key = row.key.toUpperCase();
+  const name = (row.name ?? "").toUpperCase();
+  if (key === term) return 1;
+  if (name.startsWith(term)) return 0.9;
+  if (key.includes(term)) return 0.85;
+  if (name.includes(term)) return 0.7;
+  return 0.6;
+}
+function referenceActivity(config) {
+  const category = config.category ?? config.key;
+  const program = config.adifProgram ?? config.label;
+  const allowsMultiple = config.allowsMultiple ?? false;
+  async function lookupReference(ref) {
+    const host = await hostApi();
+    try {
+      return await host.dbLookupSelectOne(category, ref);
+    } catch (e) {
+      host.log(`${config.key}: database lookup failed for ${ref}: ${e}`);
+      return null;
+    }
+  }
+  function decorate(ref, reference, row, unknown) {
+    if (!row?.name) return { ...ref, ref: reference, name: unknown, program };
+    const data = row.data ?? {};
+    return {
+      ...ref,
+      ref: reference,
+      name: row.name,
+      grid: data.grid,
+      lat: row.lat,
+      lon: row.lon,
+      location: data.location,
+      program,
+      label: `${config.label} ${reference}: ${row.name}`,
+      shortLabel: `${config.label} ${reference}`
+    };
+  }
+  const refHandler = {
+    async validateRef({ ref }, _ctx) {
+      const normalized = normalize(ref.ref);
+      return { valid: config.referenceRegex.test(normalized), normalized };
+    },
+    async decorateRef({ ref }, ctx) {
+      const t = config.tFor(ctx);
+      const reference = normalize(ref.ref);
+      if (!config.referenceRegex.test(reference)) {
+        return { ...ref, ref: reference, name: t("invalidReference") };
+      }
+      return decorate(ref, reference, await lookupReference(reference), t("unknownReference"));
+    },
+    /// Titles ANY reference type this handler was registered for, rather than
+    /// only `config.activationType`. These programs have no hunting side, so
+    /// every type they register is an activation and every one of them means
+    /// "the operation is happening here".
+    ///
+    /// Checking the type would be actively wrong: `wca` also registers for
+    /// `ecaActivation` and `bcaActivation` (English and Belgian castles ARE WCA
+    /// references), title dispatch resolves to a SINGLE hook, and WCA wins it by
+    /// registration order — so a type check silently costs those two activities
+    /// their "at ON-00558" whenever WCA is enabled alongside them. `decorateRef`
+    /// above never checked the type either; this makes the pair consistent.
+    async suggestOperationTitle({ ref }, _ctx) {
+      if (!ref.ref) return null;
+      return { at: ref.ref, subtitle: ref.name };
+    },
+    /// Only for a reference this program would accept: a code the operator is
+    /// still typing, or one another program's handler would answer for, would
+    /// otherwise send them to a page that cannot exist.
+    ///
+    /// No `label`: the core names the row instead, and the row's name is the
+    /// honest one here. This handler answers for ref types belonging to OTHER
+    /// programs (WCA takes `ecaActivation` and `bcaActivation` — see
+    /// `suggestOperationTitle` above), so a label built from `config.label`
+    /// would read "WCA G-00001" aloud on an ECA reference.
+    async linkForRef({ ref }, _ctx) {
+      if (!config.linkUrl) return null;
+      const reference = normalize(ref.ref);
+      if (!config.referenceRegex.test(reference)) return null;
+      return { url: config.linkUrl(reference) };
+    }
+  };
+  const activityHook = {
+    async operationControls(_args, ctx) {
+      return [
+        {
+          key: `${config.key}/activation`,
+          label: config.tFor(ctx)("activationControl"),
+          icon: config.icon,
+          color: config.color,
+          order: 10,
+          optionType: "optional",
+          allowsMultiple,
+          input: {
+            kind: "refList",
+            refType: config.activationType,
+            placeholder: config.placeholder,
+            pattern: config.referenceRegex.source
+          }
+        }
+      ];
+    },
+    // Only offered when the program HAS a hunting side; an activation-only
+    // award has nothing to record per QSO. One control either way, unlike
+    // app-polo which swaps between an activator and a hunter control depending
+    // on whether the operation is activating — both write the same hunting
+    // refs, and POTA's HaLo port already settled on the single control.
+    ...config.huntingType ? {
+      async loggingControls(_args, ctx) {
+        return [
+          {
+            key: `${config.key}/hunter`,
+            label: config.tFor(ctx)("huntingControl"),
+            icon: config.icon,
+            color: config.color,
+            order: 10,
+            optionType: "optional",
+            allowsMultiple: true,
+            input: {
+              kind: "refList",
+              refType: config.huntingType,
+              placeholder: config.placeholder,
+              pattern: config.referenceRegex.source
+            }
+          }
+        ];
+      }
+    } : {},
+    async suggest({ location, searchTerm }, _ctx) {
+      const host = await hostApi();
+      const rows = searchTerm ? await host.dbLookupSelectAll(category, searchTerm) : location ? await host.dbLookupSelectByLocation(category, location.lat, location.lon, NEARBY_DELTA) : [];
+      const withDistance = rows.map((row) => ({
+        row,
+        distance: location && row.lat != null && row.lon != null ? distanceOnEarth(location, { lat: row.lat, lon: row.lon }) ?? void 0 : void 0
+      }));
+      if (!searchTerm) {
+        withDistance.sort((a, b) => (a.distance ?? Infinity) - (b.distance ?? Infinity));
+      }
+      return withDistance.slice(0, MAX_SUGGESTIONS).map(({ row, distance }) => {
+        const data = row.data ?? {};
+        return {
+          type: config.activationType,
+          ref: row.key,
+          name: row.name,
+          grid: data.grid,
+          lat: row.lat,
+          lon: row.lon,
+          location: data.location,
+          program,
+          label: `${config.label} ${row.key}: ${row.name ?? ""}`,
+          shortLabel: `${config.label} ${row.key}`,
+          distance,
+          relevance: relevanceForMatch(row, searchTerm),
+          allowsMultiple
+        };
+      });
+    }
+  };
+  function activationFields(operation) {
+    const refs = refsOfType(operation, config.activationType);
+    if (refs.length === 0) return [];
+    return [
+      { name: "MY_SIG", value: program },
+      { name: "MY_SIG_INFO", value: refs[0].ref },
+      ...config.adifRefField ? [{ name: `MY_${config.adifRefField}_REF`, value: refs.map((r) => r.ref).join(",") }] : []
+    ];
+  }
+  function huntedRefsOn(qso) {
+    return config.huntingType ? refsOfType(qso, config.huntingType) : [];
+  }
+  const adifFieldsHook = {
+    async fieldsForOneQSO({ qso, operation }, _ctx) {
+      const hunted = huntedRefsOn(qso);
+      const huntedJoined = hunted.map((r) => r.ref).join(",");
+      return [
+        ...hunted.length > 0 ? [
+          { name: "SIG", value: program },
+          { name: "SIG_INFO", value: huntedJoined },
+          ...config.adifRefField ? [{ name: `${config.adifRefField}_REF`, value: huntedJoined }] : []
+        ] : [],
+        ...activationFields(operation)
+      ];
+    }
+  };
+  if (config.huntingType && config.splitRecordsPerHuntedRef) {
+    adifFieldsHook.fieldCombinationsForOneQSO = async ({ qso, operation }, _ctx) => {
+      const activation = activationFields(operation);
+      const hunted = huntedRefsOn(qso);
+      if (hunted.length === 0) return [activation];
+      return hunted.map((ref) => [
+        ...activation,
+        { name: "SIG", value: program },
+        { name: "SIG_INFO", value: ref.ref },
+        // One record names ONE reference, so the program field names it too.
+        ...config.adifRefField ? [{ name: `${config.adifRefField}_REF`, value: ref.ref }] : []
+      ]);
+    };
+  }
+  const adifImportHook = activityAdifImport({
+    sig: program,
+    huntingType: config.huntingType,
+    activationType: config.activationType,
+    refField: config.adifRefField ? `${config.adifRefField.toLowerCase()}_ref` : void 0,
+    normalize
+  });
+  return { refHandler, activityHook, adifFieldsHook, adifImportHook };
+}
+export {
+  referenceActivity
+};