@ham2k/extension-sdk
Write extensions for the Ham2K Logger — the typed hook contracts and the host API an extension is built against.
npm install @ham2k/extension-sdk
npm install --save-dev @ham2k/extension-tools esbuild
import { defineExtension } from "@ham2k/extension-sdk"
import type { PanelHook } from "@ham2k/extension-sdk"
import manifest from "../manifest.json"
const HelloPanel: PanelHook = {
async getPanels() {
return [{ key: "hello", title: "Hello World", icon: "hand-wave-outline" }]
},
async render() {
return { kind: "markdown", content: "# Hello, World!" }
},
}
defineExtension({
...manifest,
onActivation({ registerHook }) {
registerHook("panel", { key: manifest.key, hook: HelloPanel })
},
})
A panel returns content, not widgets — which is what keeps extensions out of the app's UI toolkit.
npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name> writes
all of that and the build script; the same package packages the result into a
.h2kext the app can install.
The reference is in this package
samples/ holds one worked extension per shape — a callsign lookup with the
credentials it needs, an award program, a contest and its scorer, an HTML
panel. Each builds and packs; each says in its header what it leaves out.
AGENTS.md beside this file is the map — the manifest, the sandbox's limits,
and which of docs/ answers what. docs/ holds the documentation itself:
getting started, how extensions run, the manifest, the host API, every hook
category, forms, settings panels, templates, packaging and publishing.
They travel in the package rather than being linked to, so they are readable
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.
Versions
The minor version is the extension API: SDK 1.26 describes API 26, and
exports it as API_VERSION. @ham2k/extension-tools follows the same rule,
so a ^1.19.0 range says the extension needs API 19 and admits every later
one. A major version is a change that breaks an extension already written.
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/import-export.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-*,
i18next, liquidjs — as optional peers, and you almost certainly do not
need to install any of them.
Your extension declares in its manifest.json which of them it uses, and the
build rewrites each one into a lookup on the host's single instance before
esbuild ever reaches the filesystem. Taking the host up on that is worth
roughly thirty times the bundle size. The published types have theirs rolled
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.