@ham2k/extension-sdk 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.1
+// @ham2k/extension-sdk 0.5.3
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -231,7 +231,25 @@ export interface HookContext {
 	getOperation?(uuid: string): Promise<Record<string, JSONValue> | null>;
 	getQsos?(operationUuid: string): Promise<Record<string, JSONValue>[] | null>;
 	getSpotsForCall?(call: string, maxAgeMinutes?: number): Promise<Spot[]>;
-	getHistoryForCall?(call: string): Promise<Record<string, JSONValue>[]>;
+	getHistoryForCall?(call: string, options?: HistoryForCallOptions): Promise<Record<string, JSONValue>[]>;
+}
+export interface HistoryForCallOptions {
+	refType?: string | string[];
+	operation?: string | string[];
+	excludeOperation?: string | string[];
+	fromDate?: string;
+	toDate?: string;
+	fromDateMillis?: number;
+	toDateMillis?: number;
+	fromTime?: string;
+	toTime?: string;
+	fromTimeMillis?: number;
+	toTimeMillis?: number;
+	band?: string | string[];
+	excludeBand?: string | string[];
+	mode?: string | string[];
+	excludeMode?: string | string[];
+	limit?: number;
 }
 export type LookupResult = (CallInfoLookup & {
 	locAccuracy?: number;

package/dist/templates.js

@@ -38,6 +38,19 @@ function registerFilters(liquid2) {
     const chosen = String(digits ?? "");
     return String(value ?? "").replace(/[0159]/g, (digit) => chosen.includes(digit) ? CUT_NUMBERS[digit] : digit);
   });
+  liquid2.registerFilter(
+    "refLabels",
+    (value) => (Array.isArray(value) ? value : []).flatMap((ref) => {
+      const label = [ref?.shortLabel, ref?.label, ref?.ref].map((text) => typeof text === "string" || typeof text === "number" ? String(text).trim() : "").find((text) => text !== "");
+      return label === void 0 ? [] : [label];
+    })
+  );
+  liquid2.registerFilter("sentence", (value, separator = ", ", final = " & ") => {
+    if (!Array.isArray(value)) return String(value ?? "");
+    const items = value.map((item) => String(item ?? "").trim()).filter((item) => item !== "");
+    if (items.length < 2) return items.join("");
+    return `${items.slice(0, -1).join(String(separator))}${String(final)}${items[items.length - 1]}`;
+  });
 }
 const CUT_NUMBERS = { "0": "T", "1": "A", "5": "E", "9": "N" };
 class TemplateError extends Error {

package/docs/distribution.md

@@ -393,6 +393,41 @@ as a constant inside the extension that uses it, because these bundles are
 served to anyone who asks and a `.h2kext` is a zip. An installed extension
 sees no build secret, whatever key it claims and wherever it came from.
 
+### The upgrade to catalog extensions
+
+An install that has been running the app's own extensions is offered the move
+at start, and again the moment the catalog experiment is switched on: that
+switch is the operator asking for catalog extensions, and being made to
+relaunch before anything is offered reads as nothing having happened. The
+switch withdraws nothing by itself; only a taken upgrade does, and the offer
+may be deferred either way. A catalog that cannot be reached says so in the
+footer when the operator asked, and says nothing at a launch nobody was
+watching.
+
+Accepting installs the pre-loads, then fetches the catalog's twin of every
+other built-in the operator had switched on — `wca` becomes `ham2k-wca` —
+carrying its settings and credentials the same way. Nothing is withdrawn until
+that finishes; a download that fails puts the app's own extensions back in use
+and the offer returns next launch. Twins that did arrive stay on disk, unused
+until an upgrade completes — the built-in each one supersedes is what runs
+meanwhile.
+
+The upgrade restarts the extension runtime, which takes the footer items of
+the generation going down with it: a data file's import raises an error rather
+than returning into a torn-down runtime, so its progress line is cleared and
+the file is left unstamped for the next sweep instead of recorded as fresh
+with nothing imported.
+
+A few built-ins have no twin on purpose — `qp`, which the catalog carries as
+one extension per party instead — and the app names them itself
+(`kBuiltInsWithoutTwin`). Those are withdrawn without asking the catalog, and
+the dialog that reports the upgrade finished names each one the operator had
+switched on, since it is where they learn it is gone. Any other twin missing
+from the listing fails the upgrade and is asked for again next launch: a
+listing lacks a key the same way whether the catalog will never serve it or has
+not published it yet, and only the app knows which. A built-in retired from the
+catalog on purpose joins that list in the same change.
+
 ### Installing from the catalog
 
 **Settings → Extensions → Catalog** lists what [catalog.ham2k.net](https://catalog.ham2k.net)

package/docs/hooks.md

@@ -51,8 +51,9 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   reads above it is cheap enough for the lookup path; it resolves `[]`
   whenever the cache is cold or the host keeps no spots. Used by
   `spot-history` to pull a hunted park or summit into the QSO being logged.
-* `getHistoryForCall?(call)` — every non-deleted QSO ever logged with `call`,
-  across every operation, most recent first, as raw QSON — the one log read
+* `getHistoryForCall?(call, options?)` — the most recent non-deleted contacts
+  logged with `call` (five unless `limit` says otherwise, never more than
+  50), across every operation, newest first, as raw QSON — the one log read
   that is cross-operation rather than scoped to a single one, since it
   answers "who is this station" from the whole log rather than "what's in
   this operation". Resolves `[]` for no match or no log access; unlike
@@ -60,6 +61,22 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   Used by `call-history` to fold the most recent past QSO's fields into a
   lookup result.
 
+  `options` (`HistoryForCallOptions` in `types.ts`) narrow the history
+  before it is ordered and limited, so `{ refType: 'cwt' }` finds last
+  month's CWT exchange behind a week of POTA contacts. The filters are
+  `refType` (a ref in the QSO's own `refs`), `operation`/`excludeOperation`,
+  `band`/`excludeBand`, `mode`/`excludeMode` (`SSB` also matches its
+  sidebands, and `CW`/`PHONE`/`DATA` match their whole family), whole UTC
+  days through `fromDate`/`toDate` or `fromDateMillis`/`toDateMillis`, and
+  exact instants through `fromTime`/`toTime` or
+  `fromTimeMillis`/`toTimeMillis`. All the bounds are inclusive. A malformed
+  option, an unknown one, or an include option given no values
+  (`operation: []`) rejects the call instead of answering an unfiltered
+  history. Hosts older than these options ignore them and answer the latest
+  five contacts unfiltered, so a caller re-checks on the results whatever it
+  relies on — and an empty answer there means "none among the latest five",
+  not "none at all".
+
 Status legend: ✅ implemented · 🔜 planned (design in DESIGN.md §4).
 
 ---
@@ -1206,6 +1223,14 @@ permission (pending challenge code for an email, immediately-active for an
 already-permitted account, or a blank permission for QR-code linking) and
 returns server rejections as `{ error, error_status }` data.
 
+`linkClient` must NOT mail anything. The core shows the challenge code on
+screen and offers the email as a separate choice, so a transport that mails
+here sends a confirmation nobody asked for — and one more on every renewal,
+since an expiring code re-requests through this same call.
+`linkClientWithEmail` is the call the operator reaches by choosing the
+email over the code, and the only one in this seam that mails. A server
+that mails by default (LoFi does) has to be told not to.
+
 The account-management methods are all optional and all follow that same
 "a rejection is data, not a throw" convention, because every one of them
 reports to an operator in the middle of an action: `setAccountEmail` /
@@ -1256,7 +1281,7 @@ numeric value patches; local-only controls and animation frames make no bridge
 calls. Controls with `continuous: true` send `change` events during dragging and a
 final `commit` on release; pending movements are coalesced to the newest value.
 Numeric text supports `scale`, `truncate`, `modulo`, and `minIntegerDigits`
-for local numeric formatting. The Radio Panel Example uses these for its Modern
+for local numeric formatting. KI2D’s Radio Panel uses these for its Modern
 frequency groups; its settings offer Modern/LCD styles and radio selection. Local sliders may use `hover` and `discrete` hourly buckets. Text `samples`
 may hold numbers or preformatted strings; control `valueLabels` supplies accessible
 value descriptions. Transform/opacity bindings may also supply numeric `samples`,
@@ -1302,12 +1327,12 @@ Button controls can supply `menu: [{label, event}]` to open a native dropdown.
 Selecting an item emits its `event` as the action with the original control ID;
 dismissing the menu emits nothing.
 
-The `svg-weather`, `svg-solar`, and `svg-radio` reference panels live in
+The `ki2d-weather-panel`, `ki2d-solar-panel` and `ki2d-radio-panel` reference
+panels live in
 [ham2k/extensions](https://github.com/ham2k/extensions/tree/main/extensions/dashboard).
 They use public host APIs and ship as `.h2kext` packages, not app assets.
-Install the packages, then add their panels through Edit Layout. Their original
-extension and panel keys are retained so existing placements and settings survive.
-See that repository’s dashboard README for building against the unreleased SDK.
+Install the packages, then add their panels through Edit Layout. See that
+repository's dashboard README for building them.
 
 The radio host calls are manifest capabilities, refused unless declared — the
 same shape as `requiresLocation`, and shown to the operator at install:
@@ -1315,8 +1340,16 @@ same shape as `requiresLocation`, and shown to the operator at install:
 `"requiresRadioWrite": true` allows `host.tuneRadio()` and
 `host.setRadioConnection()`, and implies read, since a command answers with the
 radio's state. An undeclared call rejects rather than answering null.
+A capability belongs to the bundle that declared it, and to the sub-extensions
+that bundle defines under its own key. A separately installed bundle never
+inherits one through its name: `rigpanel-themes` gets nothing from `rigpanel`.
+
+An `onEvent` that cannot read its panel's config is refused rather than run
+with an empty one, since a config is where a panel keeps which radio it
+commands. The host allows an event up to about ten seconds in all (config, then
+the hook); the control shows its pending value until the outcome is known.
 
-**Radio Panel Example** is the CAT reference extension. `host.listRadios()` lists configured
+**KI2D’s Radio Panel** is the CAT reference extension. `host.listRadios()` lists configured
 local transceivers. `host.readRadio(id?)` returns
 a **local** radio's reported frequency (Hz), mode, connection state,
 power, TX state and fresh telemetry, or null on hosts without this API.

package/docs/templates.md

@@ -34,7 +34,9 @@ about 2 µs each.
 the namespaces are deliberately polo's. The syntax around them does not:
 `{{#if}}` is `{% if %}{% endif %}`, `{{#each}}` is `{% for %}{% endfor %}`,
 `{{> Partial}}` has no equivalent, and helpers are filters
-(`{{ dash x }}` → `{{ x | dash }}`).
+(`{{ dash x }}` → `{{ x | dash }}`). polo's
+`{{#join op.refs separator=", " final=" & "}}{{or shortLabel label key}}{{/join}}`
+is `{{ op.refs | refLabels | sentence }}`.
 
 ## What a template can name
 
@@ -122,7 +124,7 @@ with nothing to say it was invented.
 
 All of Liquid's own (`date`, `downcase`, `upcase`, `strip`, `default`,
 `join`, `size`, `first`, `last`, `round`, `truncate`, `replace`, `map`,
-`where`, …), plus four:
+`where`, …), plus six:
 
 | filter | does | example |
 |---|---|---|
@@ -130,12 +132,20 @@ All of Liquid's own (`date`, `downcase`, `upcase`, `strip`, `default`,
 | `alnum` | strip to alphanumerics | `2026-07-27` → `20260727` |
 | `pad: n` | zero-pad on the left to `n` characters (default 3); **blank stays blank** | `7` → `007` |
 | `cut: "digits"` | CW cut numbers for the listed digits, of `0`→`T` `1`→`A` `5`→`E` `9`→`N`; default `"09"` | `599` → `5NN`, `{{ 9 \| pad: 3 \| cut }}` → `TTN` |
+| `refLabels` | a list of refs → each one's `shortLabel`, else `label`, else `ref`; a ref with none of them is skipped — an operation's contest ref HAS a label (`CQ WPX CW`) and is listed | `op.refs` → `POTA US-1234`, `KFF-9999` |
+| `sentence: "sep", "final"` | joins a list with a different LAST separator (defaults `", "` and `" & "`); blanks are dropped | `A, B & C`, `A & B` |
 
 `pad` leaves a blank alone because a CW message can be keyed before the
 serial field has a number, and `000` sent in that gap is a serial the log
 will never agree with. Order matters with `cut`: pad first, or the padding
 zeros go out uncut.
 
+`refLabels` exists because `map` reads one field: `map: "shortLabel"` drops a
+reference that resolved to nothing, since it carries no labels — an
+operation at an unlisted park would print as though it had none. Liquid's own
+`array_to_sentence_string` is the near miss for `sentence`: it always writes
+the serial comma (`A, B, & C`).
+
 `alnum` is app-polo's `compact` helper under a different name: Liquid already
 has a `compact` (it drops nils from an **array**, and `op.refs`/`qso.refs` are
 arrays), and `registerFilter` overwrites without warning, so taking that name
@@ -217,8 +227,9 @@ will jump rather than count. Show HH:MM.
 | CW messages | Radio settings `cwMessage1..8`, keyed on F1-F8 through the radio (docs/design/cat.md § CW keying) — rendered by the `template` hook (hooks.md) | by the operator, in the Station dialog's Messages… dialog |
 
 NOTES and COMMENT default to QSO notes and are withheld when private data
-is off. QSLMSG defaults to empty for program exports, and to the operation’s
-references for the whole-log ADIF. Custom QSL messages may use contact values.
+is off. QSLMSG defaults to empty for program exports, and for the whole-log
+ADIF to the operation’s references as `refLabels | sentence` names them —
+“POTA US-0001 & WWFF KFF-0002”. Custom QSL messages may use contact values.
 Templates receive no withheld private or lookup values. File titles obey the
 private-data choice; filename templates are labels for the operator’s files.
 

package/package.json

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

package/samples/k2hrc-svg-scenes/README.md

@@ -19,6 +19,6 @@ node build.mjs
 node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-svg-scenes.h2kext
 ```
 
-For the standalone Flutter preview and migration plan, see
-`docs/design/svg-scenes.md` in the logger repository. This is an API experiment,
+For the contract and migration plan, see `docs/design/svg-scenes.md` in the
+logger repository. This is an API experiment,
 not a replacement for the production weather/solar panels yet.