@ham2k/extension-sdk 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.2
+// @ham2k/extension-sdk 0.5.4
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -231,7 +231,26 @@ 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[];
+	refPrefix?: 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/docs/distribution.md

@@ -393,6 +393,71 @@ 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.
+
+A bundle the engine will not evaluate takes the whole runtime with it, so the
+upgrade puts that one aside — the boot names the bundle it died on — and
+restarts once more. What boots then is the upgrade minus that extension, named
+in the dialog in a sentence of its own. Refused rather than
+withdrawn: the panel still lists it, badged, because the row is where an
+operator sees that something they installed is doing nothing, and updating it
+there is what lifts the refusal. Keyed by the VERSION that failed, so a fixed
+release arrives as an ordinary update and clears it. Only an INSTALLED
+extension is ever put aside; a built-in that
+will not evaluate is a defect in the app, and skipping it would ship an
+install quietly missing part of itself.
+
+A refusal is kept even when putting the bundle aside did not get a runtime
+back: it still will not evaluate, and an extension with no built-in behind it
+is in the reverted set too, so re-admitting it there would kill the boot that
+was about to give the operator everything back. Every dialog, and the notice
+that stands in for one, names what stayed out — except a downloaded copy the
+revert superseded, whose built-in is running again. Uninstalling clears the
+record, so a reinstall of the same bytes gets its chance.
+
+A refused extension is treated like a revoked one in everything else: it
+keeps its switch, and its downloaded data expires on the same clock as any
+extension the app is not loading.
+
+What this does NOT cover is a failure that names no bundle. Only a bundle
+that fails while it is being EVALUATED names itself: a kernel that will not
+load, or an extension that throws while ACTIVATING, takes the generation down
+under a name that is not a key. Those revert the whole upgrade as before, and
+it is offered again at the next launch.
+
+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,25 @@ 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`), `refPrefix` (a ref whose `ref`
+  starts with it, ignoring ASCII case; with `refType`, the same ref must pass
+  both, so `{ refType: 'potaActivation', refPrefix: 'FR-' }` finds French
+  parks), `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 +1226,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 +1284,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 +1330,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 +1343,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

@@ -227,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.2",
+  "version": "0.5.4",
   "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.