@ham2k/extension-sdk 0.8.1 → 0.9.0

package/dist/activityScoring.js

@@ -1,6 +1,6 @@
 import { createCachedTranslator } from "./i18n.js";
+import { baseCallOf } from "./callsigns.js";
 import { modesMatchForDupe } from "./modes.js";
-import { parseCallsign } from "@ham2k/lib-callsigns";
 import { fmtInteger } from "@ham2k/lib-format-tools";
 import en from "./i18n/activityScoring.en.json";
 import es from "./i18n/activityScoring.es.json";
@@ -201,10 +201,6 @@ function isGuestOperator(operator, operation) {
   const stations = String(operation.stationCall ?? "").split(",").map((call) => baseCallOf(call)).filter((call) => call.length > 0);
   return stations.length > 0 && !stations.includes(baseCallOf(operator));
 }
-function baseCallOf(call) {
-  const trimmed = call.trim().toUpperCase();
-  return parseCallsign(trimmed).baseCall || trimmed;
-}
 function summarizeActivation(activatedRefs, operatorRefs, qsos, duplicates, huntedQsos, scope, qsosToActivate, rules, t, ctx) {
   const refKeys = Object.keys(activatedRefs).sort();
   const lowest = Math.min(...refKeys.map((key) => activatedRefs[key]));

package/dist/callsigns.js

@@ -0,0 +1,8 @@
+import { parseCallsign } from "@ham2k/lib-callsigns";
+function baseCallOf(call) {
+  const trimmed = call.trim().toUpperCase();
+  return parseCallsign(trimmed).baseCall || trimmed;
+}
+export {
+  baseCallOf
+};

package/dist/contestSummary.js

@@ -0,0 +1,48 @@
+import { createCachedTranslator } from "./i18n.js";
+import { fmtInteger, fmtNumber } from "@ham2k/lib-format-tools";
+import en from "./i18n/contestSummary.en.json";
+import es from "./i18n/contestSummary.es.json";
+const tFor = createCachedTranslator({ en: { translation: en }, es: { translation: es } });
+function contestArithmetic(args, ctx) {
+  const t = tFor(ctx);
+  const clauses = [args.qsos === 1 ? t("qsoOne") : t("qsoMany", { formatted: fmtInteger(args.qsos) })];
+  if (args.points !== void 0) {
+    const bonus = args.bonus ? t("bonus", { formatted: fmtInteger(args.bonus) }) : "";
+    let expression = args.points === 1 ? t("pointOne") : t("points", { formatted: fmtInteger(args.points) });
+    if (bonus && args.bonusFirst) expression = `(${expression} ${bonus})`;
+    if (args.mults !== void 0) {
+      const mults = args.multsNoun ? `${fmtInteger(args.mults)} ${args.multsNoun}` : args.mults === 1 ? t("multOne") : t("multMany", { formatted: fmtInteger(args.mults) });
+      expression += ` \xD7 ${mults}`;
+      if (args.multParts && args.multParts.length > 0) expression += ` (${args.multParts.join(", ")})`;
+    }
+    if (args.factor) {
+      const count = Number.isInteger(args.factor.count) ? fmtInteger(args.factor.count) : fmtNumber(args.factor.count, "oneDecimal");
+      expression += ` \xD7 ${count} ${args.factor.noun}`;
+    }
+    if (bonus && !args.bonusFirst) expression += ` ${bonus}`;
+    clauses.push(expression);
+  }
+  clauses.push(...args.more ?? []);
+  return clauses.join(", ");
+}
+function contestSummary(args, ctx) {
+  if (args.scope === "day") return {};
+  const t = tFor(ctx);
+  return {
+    [args.key]: {
+      ...args.extra,
+      key: args.key,
+      for: "operation",
+      icon: args.icon,
+      total: args.total,
+      label: args.total === 1 ? t("titleOnePoint", { title: args.title }) : t("titleManyPoints", { title: args.title, formatted: fmtInteger(args.total) }),
+      summary: fmtInteger(args.total),
+      longSummary: [args.arithmetic, args.detail].filter((part) => part).join("\n\n"),
+      ...args.grid ? { grid: true } : {}
+    }
+  };
+}
+export {
+  contestArithmetic,
+  contestSummary
+};

package/dist/i18n/contestSummary.en.json

@@ -0,0 +1,11 @@
+{
+  "titleOnePoint": "{{title}}: 1 point",
+  "titleManyPoints": "{{title}}: {{formatted}} points",
+  "qsoOne": "1 QSO",
+  "qsoMany": "{{formatted}} QSOs",
+  "pointOne": "1 pt",
+  "points": "{{formatted}} pts",
+  "multOne": "1 mult",
+  "multMany": "{{formatted}} mults",
+  "bonus": "+ {{formatted}} bonus"
+}

package/dist/i18n/contestSummary.es.json

@@ -0,0 +1,11 @@
+{
+  "titleOnePoint": "{{title}}: 1 punto",
+  "titleManyPoints": "{{title}}: {{formatted}} puntos",
+  "qsoOne": "1 QSO",
+  "qsoMany": "{{formatted}} QSOs",
+  "pointOne": "1 pt",
+  "points": "{{formatted}} pts",
+  "multOne": "1 mult",
+  "multMany": "{{formatted}} mults",
+  "bonus": "+ {{formatted}} de bonificación"
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.8.1
+// @ham2k/extension-sdk 0.9.0
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -1539,6 +1539,33 @@ export declare function contestScorer<S extends Scoresheet = Scoresheet>(scorer:
 	scope: ScoringScope;
 };
 export declare function tally(key: string, forScope: "day" | "operation", total: number, extra?: Partial<ScoreTally>): ScoreTally;
+export interface ContestArithmetic {
+	qsos: number;
+	points?: number;
+	mults?: number;
+	multsNoun?: string;
+	multParts?: string[];
+	bonus?: number;
+	bonusFirst?: boolean;
+	factor?: {
+		count: number;
+		noun: string;
+	};
+	more?: string[];
+}
+export declare function contestArithmetic(args: ContestArithmetic, ctx: HookContext): string;
+export interface ContestSummaryArgs {
+	key: string;
+	scope: "day" | "operation";
+	icon: string;
+	title: string;
+	total: number;
+	arithmetic: string;
+	detail?: string;
+	grid?: boolean;
+	extra?: Record<string, JSONValue>;
+}
+export declare function contestSummary(args: ContestSummaryArgs, ctx: HookContext): Record<string, ScoreTally>;
 export declare function operationForQso(base: Record<string, JSONValue>, qso: Record<string, JSONValue>, segments?: OperationSegmentPayload[]): Record<string, JSONValue>;
 export declare function segmentsWith(segments: OperationSegmentPayload[] | undefined, transform: (operation: Record<string, JSONValue>) => Record<string, JSONValue>): OperationSegmentPayload[] | undefined;
 export type UniqueAxis = "day" | "band" | "mode" | "ref";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./dxcc.js";
 export * from "./location.js";
 export * from "./modes.js";
 export * from "./scoring.js";
+export * from "./contestSummary.js";
 export * from "./segments.js";
 export * from "./activityScoring.js";
 export * from "./activityExports.js";

package/docs/distribution.md

@@ -50,7 +50,8 @@ app at all. Declare the lowest version that has what the bundle uses, so it
 reaches every app that can run it: 2 adds `host.webSocket`, and the packer
 refuses a manifest declaring `webSockets` under anything less; 3 adds timers
 and `onShow`/`onHide`, and from 3 the build rewrites a bare `setTimeout` into
-the SDK's (README's "Timers").
+the SDK's (README's "Timers"); 4 lets `host.fetch` reach a plain-`http://` host
+the app fronts with its https proxy (README's `host.fetch`).
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -259,7 +260,7 @@ It reports every problem at once rather than one per run:
 h2kext-pack: ./build is not ready to package:
 manifest.json: missing required field 'name'
 manifest.json: key 'my-clock' must start with your callsign — 'my' is not one (e.g. ki2d-my-clock)
-manifest.json: missing 'api' — declare the extension API this was built against (currently 3)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 4)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own

package/docs/hooks.md

@@ -1224,6 +1224,12 @@ those notice keys (`newPark` is state-parks' spelling of `newRef`) rather than
 inventing a spelling of your own: an unrecognized key leaves core's `duplicate`
 standing beside your credit, on the one row that can show only one.
 
+A contest's `summarizeScore` returns `contestSummary(...)` rather than
+building its tallies by hand: one tally titled with the contest's name and
+score, its detail opening on a `contestArithmetic(...)` line, and nothing at
+all for the `day` scope — a contest's multipliers run the whole event
+(docs/design/contests.md §5.2).
+
 A scorer's internal *rules* stay private to its scoresheet: contests don't
 share a rule vocabulary, so only notices, alerts, points and summary tallies
 cross the boundary. `scoreQso` **may mutate** the scoresheet it's given and

package/package.json

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

package/samples/k2hrc-cqww/src/index.ts

@@ -20,9 +20,8 @@
 // See `docs/hooks.md` §`scoring`, and `contests/cqww` in the app's repository
 // for the whole thing.
 
-import { annotateCallAgainstCountryFile, contestScorer, defineExtension } from "@ham2k/extension-sdk"
-import type { ContestScorer, HookContext, JSONValue, LoggingControlDescriptor, Ref, ScoreTally } from "@ham2k/extension-sdk"
-import { fmtInteger } from "@ham2k/lib-format-tools"
+import { annotateCallAgainstCountryFile, contestArithmetic, contestScorer, contestSummary, defineExtension } from "@ham2k/extension-sdk"
+import type { ContestScorer, HookContext, JSONValue, LoggingControlDescriptor, Ref } from "@ham2k/extension-sdk"
 
 import manifest from "../manifest.json" with { type: "json" }
 
@@ -126,24 +125,23 @@ const CQWWScorer: ContestScorer<Scoresheet> = {
     return { scoresheet, score: { value: points } }
   },
 
-  /// The score as the operator reads it. `scope` is 'day' or the whole
-  /// contest; this sample reports the same totals for both, where the real
-  /// extension tracks a separate per-day tally.
-  summarizeScore({ scoresheet, scope }): Record<string, ScoreTally> {
+  /// The score as the operator reads it. Every contest summarizes the same way — its name and score as the
+  /// title, then the arithmetic — so the SDK builds the tally. It also answers
+  /// the day scope with nothing: a contest's multipliers run the whole event.
+  summarizeScore({ scoresheet, scope }, ctx) {
     const mults = Object.keys(scoresheet.mults).length
-    return {
-      [TYPE]: {
+    return contestSummary(
+      {
         key: TYPE,
-        for: scope,
+        scope,
         icon: manifest.icon,
+        title: manifest.shortName,
         total: scoresheet.points * mults,
-        points: scoresheet.points,
-        mults,
-        qsos: scoresheet.qsos,
-        label: `${fmtInteger(scoresheet.points)} × ${fmtInteger(mults)}`,
-        summary: `${fmtInteger(scoresheet.points * mults)}`,
+        arithmetic: contestArithmetic({ qsos: scoresheet.qsos, points: scoresheet.points, mults }, ctx),
+        extra: { points: scoresheet.points, mults, qsos: scoresheet.qsos },
       },
-    }
+      ctx,
+    )
   },
 }