@ham2k/extension-sdk 0.12.13 → 0.12.14

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.13
+// @ham2k/extension-sdk 0.12.14
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -1537,6 +1537,7 @@ export interface ExtensionManifest {
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
 	requiresRadioWrite?: boolean;
+	requiresRadioRaw?: boolean;
 	requiresClusterRead?: boolean;
 	requiresClusterSpot?: boolean;
 	requiresClusterCommand?: boolean;
@@ -2095,15 +2096,44 @@ export interface PanelRadioSet extends PanelRadioTarget {
 }
 /** @deprecated `setRadio`'s argument through extension API 6. */
 export type PanelRadioTune = PanelRadioSet;
+/**
+ * Commands in the radio's own protocol — exactly one of `text` or `bytes`, up to 4096 bytes
+ * (extension API 11). Where the app's driver keeps one question on the wire (CI-V, Yaesu binary,
+ * HRD, Commander, flrig) each command waits its turn in that queue, and on a FlexRadio is numbered
+ * like the driver's own; the reply is then the answers to these commands alone. Elsewhere the bytes
+ * are written as given. See hooks.md for what each protocol takes.
+ */
+export interface PanelRadioRaw extends PanelRadioTarget {
+	/** Sent as UTF-8: Kenwood, Yaesu and Elecraft ASCII, rigctld, N3FJP, SmartSDR, HRD, Commander, flrig. */
+	text?: string;
+	/** Each 0…255: Icom CI-V, Yaesu's binary protocol. */
+	bytes?: number[];
+	/**
+	 * How long to wait for the reply, up to 2000 ms; omitted or 0, the call answers once the commands
+	 * are handed to the driver. Where they are written as given, the reply is everything the radio
+	 * sent in that time — the answers to the app's own polls included.
+	 */
+	replyMs?: number;
+	/** Ends the reply early, just after the first occurrence of this text or these bytes. Needs `replyMs`. */
+	until?: string | number[];
+}
+export interface PanelRadioRawResult extends PanelRadioResult {
+	/** What came back within `replyMs`, possibly nothing, at most 64 KiB; absent without `replyMs`. `text` is it as UTF-8. */
+	reply?: {
+		text: string;
+		bytes: number[];
+	};
+}
 export interface PanelRadioResult {
 	/** Accepted by the host; confirmation still comes from reported state. */
 	accepted: boolean;
 	/**
 	 * `stopped`: a scope change while no display has the scope running — nothing was sent.
+	 * `busy`: eight raw commands to this radio are already waiting (extension API 11).
 	 * `unsupported`: this radio, or the app's keying, cannot do it — keying calls on a radio that
 	 * is not the logging radio, or with the app's keying off.
 	 */
-	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported";
+	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported" | "busy";
 	state: PanelRadioState | null;
 }
 /** @deprecated `PanelRadioResult`'s name through extension API 6. */
@@ -2565,6 +2595,11 @@ export declare const host: {
 	}): Promise<PanelRadioResult>;
 	/** Stops all CW, voice and PTT the app is keying, and a tune it started (extension API 9), as Escape does. Needs `requiresRadioWrite` and extension API 7. */
 	stopRadioTransmit(args: PanelRadioTarget): Promise<PanelRadioResult>;
+	/**
+	 * Writes any command in the radio's own protocol — one that transmits included — and collects the
+	 * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+	 */
+	sendRadioRaw(args: PanelRadioRaw): Promise<PanelRadioRawResult>;
 	/** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
 	clusterStatus(): Promise<ClusterStatus>;
 	/** The node's recent lines after `after`, oldest first, at most `limit` of the newest. Needs `requiresClusterRead` and extension API 10. */

package/dist/index.js

@@ -197,6 +197,13 @@ const host = {
   async stopRadioTransmit(args) {
     return await hostCallFn()("stopRadioTransmit", { ...args });
   },
+  /**
+   * Writes any command in the radio's own protocol — one that transmits included — and collects the
+   * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+   */
+  async sendRadioRaw(args) {
+    return await hostCallFn()("sendRadioRaw", { ...args });
+  },
   /** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
   async clusterStatus() {
     return await hostCallFn()("clusterStatus", {});

package/docs/distribution.md

@@ -573,7 +573,7 @@ counts as the catalog's own here. The row and the details show the track, and
 the details' **Follow stable releases only** puts it back on stable; an
 uninstall or a file install clears it with the rest of the record.
 
-At most once every six hours — on launch and on resume — the app asks the
+At most once a day — on launch and on resume — the app asks the
 catalog whether anything installed has a newer release, and says so in the
 status bar and on the row; the notice comes down with the last update taken.
 It never installs unasked: the notice's **Update all** is the panel's own,

package/docs/hooks.md

@@ -2115,7 +2115,9 @@ same shape as `requiresLocation`, and shown to the operator at install:
 `host.setRadioConnection()` and `host.setRadioSpectrum()` — and transmitting
 with them: `host.sendRadioCw()`, `host.playRadioVoice()`, `host.setRadioPtt()`
 and `host.stopRadioTransmit()` — and implies read, since a command answers with the
-radio's state. An undeclared call rejects rather than answering null.
+radio's state. `"requiresRadioRaw": true` (extension API 11) also allows
+`host.sendRadioRaw()`, any command in the radio's own protocol, and implies
+write. 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`.
@@ -2231,6 +2233,61 @@ not paced, and not refused for a transmission in progress.
 connection using the same selection and identity checks. Acceptance starts the
 operation; follow reported connection state for completion. It does not switch
 the hardware's mains power or initiate transmission.
+
+`host.sendRadioRaw({id, selection?, text | bytes, replyMs?, until?})`
+(extension API 11, `requiresRadioRaw`) sends commands in the radio's own
+protocol — exactly one of `text`, sent as UTF-8, or `bytes`, each 0…255, up
+to 4096 bytes. **Nothing about them is checked.** They may transmit, change
+any setting or put the radio somewhere the app's own controls never would;
+that is what the operator agreed to at install, where the grant is shown in
+those words. It reaches any local radio through the same `id`/`selection`
+check as `setRadio`, with keying on or off, and is neither paced nor refused
+for a transmission in progress. One radio's calls go one at a time, in order,
+so that one call's reply window never holds the next one's answer, and past
+eight waiting the next is refused as `busy`; the app's own polls may come
+between two calls.
+
+- `replyMs`, up to 2000: how long to wait for the reply. Omitted or 0, the
+  call answers as soon as the commands are handed to the driver, with no
+  `reply`.
+- `until`, text or bytes, needs `replyMs`: the reply ends just after its first
+  occurrence.
+- The answer carries `reply: {text, bytes}`, possibly empty, at most 64 KiB,
+  with `text` its UTF-8 reading.
+
+What the commands are, and what the reply holds, is the protocol's. Where the
+app's driver keeps one question on the wire and reads the next reply as its
+answer, a raw command waits its turn in that queue — written beside it, its
+answer would be read as the answer to the driver's question — or, on a
+FlexRadio, is numbered as the driver's own are. The reply is then the answers
+to the raw commands alone, as the radio sent them, once each has come or the
+window closes:
+
+| Radio | Commands | Reply |
+|---|---|---|
+| Icom CI-V | `bytes`: whole frames, `FE FE` … `FD`, one at a time; the app addresses each to the radio from itself, whatever its address bytes say | each frame's answer frame (`FB`/`FA` or its data) |
+| Yaesu binary (FT-817/857/897) | `bytes`: five-byte commands | what the radio sends for each before it falls quiet; not read by the app |
+| FlexRadio | `text`: one command per line, without `C<seq>\|` — the app numbers each like its own | each one's `R` line |
+| Ham Radio Deluxe | `text`: one command per line, without the radio's context — the app adds it | each one's reply text, one per line |
+| DXLab Commander | `text`: one whole message (`<command:10>CmdGetFreq<parameters:0>`) | the field it is answered with; without `replyMs` it goes out as a set, waiting for nothing |
+| flrig | `text`: one XML-RPC call (`<?xml …?><methodCall>…`) — the app posts it | the response's body |
+
+Every other radio's commands are written as given — several back to back
+(`FA00014074000;MD2;`) in one write, none of the app's own between them —
+since each of their answers names what it answers: Kenwood, Elecraft and
+Yaesu ASCII, rigctld, N3FJP, Guohetec. The reply there is everything the
+connection received in the window, the answers to the app's own polls
+included, so `until` is worth setting.
+
+The app's driver still reads what the radio sends, so a raw command's effect
+shows in `readRadio` as a change made at the front panel would — and a command
+that confuses the driver confuses the app. A radio that is not connected
+answers `disconnected`; one whose driver takes no raw commands (a placeholder
+radio), `unsupported`; a malformed call, or commands that are not the
+protocol's (CI-V bytes that are not whole frames), `invalid`. A refusal heard
+within a second of a raw command on a protocol whose refusals name no command
+(`?;`, rigctld's `RPRT`) is taken as the raw command's, not counted against the
+app's own reads.
 On a host with the panadapter enabled, `readRadio()` carries `spectrum`: null
 for a radio without a scope, otherwise its settings as the radio reports them
 (`mode`, `spanHz`, `lowHz`/`highHz`, `refLevelDb`, `speed`), what it accepts
@@ -2422,6 +2479,39 @@ row/entry→`LookupRow` transform. See `DataFileManager`
 (`fetchType: 'raw'` — the parsed Hams of Note index is cached as JSON and
 replayed through `onLoadRawData` at startup, issue #17).
 
+### N1MM call history files
+
+N1MM Logger+'s call history files are uploaded to
+[n1mmwp.hamdocs.com](https://n1mmwp.hamdocs.com/mmfiles/categories/callhistory/)
+under a new name with every update (`CWOPS_4002.txt`), and downloaded by a
+form POST that carries a nonce from the file's own page, so no URL points at
+the current one. A `url` of `n1mm-history:<stem>` asks the host to find it
+(extension API 11):
+
+```ts
+{ key: 'cwops-history', url: 'n1mm-history:CWOPS', fetchType: 'raw', maxAgeInDays: 7, /* … */ }
+```
+
+- **Which file:** the newest one, by publish date, whose name is the stem or
+  the stem followed by `-` or `_` (extension and case aside). `CWOPS` takes
+  `CWOPS_4002.txt` and `CWOPS_4000-CCC.txt`, never `CWOPSOPEN_2026-002.txt`,
+  though N1MM's search lists all three; to follow one variant only, name it
+  (`n1mm-history:CWOPS_4000-CCC`). The search is read newest first, page by
+  page, until a page lists one of the stem's files.
+- **When:** N1MM sends no ETag; the chosen file's name, publish date and page
+  stand in for one, so a re-upload under the same name still counts as new. A
+  refresh whose newest file is the one last downloaded stops after the search,
+  like a 304. A forced refresh (RELOAD, Refresh) downloads it regardless.
+- **What arrives:** the file as served, in N1MM's format — a `!!Order!!,…`
+  column line, `#` comment lines, then CSV rows. `fetchType: 'raw'` is the one
+  that fits; `rawToJSONData` parses it. `url` in its arguments is the
+  `n1mm-history:` string, not the file's address.
+- **Failures:** a stem nothing matches, a refused download, or a page that no
+  longer has the shape the host reads fails the download with
+  `N1mmCallHistoryUnavailable` — a notice on a refresh the operator asked for,
+  an upload for the background passes. The requests and parsing are
+  `halo_core`'s `n1mm_call_history.dart`, shared by the app and the CLI.
+
 ### How CSV rows reach `csvToLookupEntry`
 
 An extension writes a **per-row** mapper; the kernel synthesizes the batch

package/package.json

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