minutes-sdk 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -1 +1 @@
-export { type ActionItem, type Decision, type Intent, type Frontmatter, type MeetingFile, defaultDir, splitFrontmatter, parseFrontmatter, listMeetings, searchMeetings, getMeeting, findOpenActions, findDecisions, getPersonProfile, listVoiceMemos, } from "./reader.js";
+export { type ActionItem, type Decision, type Intent, type Frontmatter, type MeetingFile, type SpeakerAttribution, type SpeakerConfirmation, defaultDir, splitFrontmatter, parseFrontmatter, listMeetings, searchMeetings, getMeeting, getMeetingWithOverlays, applySpeakerOverlays, humanizeTranscript, findOpenActions, findDecisions, getPersonProfile, listVoiceMemos, } from "./reader.js";

package/dist/index.js

@@ -14,4 +14,4 @@ defaultDir,
 // Parsing
 splitFrontmatter, parseFrontmatter, 
 // Query API
-listMeetings, searchMeetings, getMeeting, findOpenActions, findDecisions, getPersonProfile, listVoiceMemos, } from "./reader.js";
+listMeetings, searchMeetings, getMeeting, getMeetingWithOverlays, applySpeakerOverlays, humanizeTranscript, findOpenActions, findDecisions, getPersonProfile, listVoiceMemos, } from "./reader.js";

package/dist/reader.d.ts

@@ -21,6 +21,20 @@ export interface SpeakerAttribution {
     confidence: "high" | "medium" | "low";
     source: "deterministic" | "llm" | "enrollment" | "manual";
 }
+/**
+ * A user-confirmed speaker correction stored in the sidecar overlay store
+ * (`~/.minutes/overlays.db`). Overlays layer over raw frontmatter at read
+ * time without ever mutating the meeting markdown on disk.
+ *
+ * Confirmations carry high confidence and `manual` source by definition —
+ * they record an explicit user action, not a model inference.
+ */
+export interface SpeakerConfirmation {
+    speaker_label: string;
+    name: string;
+    /** Optional name the overlay overrode, useful for "undo" UIs. */
+    previous_name?: string;
+}
 export interface Frontmatter {
     title: string;
     type: string;
@@ -72,6 +86,53 @@ export declare function searchMeetings(dir: string, query: string, limit?: numbe
  * Get a single meeting by file path.
  */
 export declare function getMeeting(filePath: string): Promise<MeetingFile | null>;
+/**
+ * Layer sidecar speaker confirmations over a meeting's `speaker_map`,
+ * returning a new MeetingFile with the corrections applied. The original
+ * meeting object is not mutated, and the body text is not rewritten —
+ * Minutes treats raw markdown as immutable capture.
+ *
+ * For each confirmation:
+ *   - if a `speaker_map` entry with the same `speaker_label` exists, its
+ *     `name` is replaced and confidence/source are bumped to high/manual
+ *   - if no entry exists, a new one is appended
+ *
+ * Pass an empty `confirmations` array to no-op.
+ */
+export declare function applySpeakerOverlays(meeting: MeetingFile, confirmations: SpeakerConfirmation[]): MeetingFile;
+/**
+ * Rewrite `[SPEAKER_N <timestamp>] text` line prefixes in a meeting
+ * transcript body to use the speaker's mapped name. Mirrors the Rust
+ * `apply_confirmed_names` helper:
+ *
+ *   - Only attributions with `confidence: "high"` are applied — model
+ *     guesses below that bar do not silently rewrite the transcript.
+ *   - If a line's body itself looks like a non-lexical event marker
+ *     (e.g. `[laughter]`, `[music]`), the speaker label is left alone
+ *     so the rendered output keeps the event tag instead of saying
+ *     "Alex Kim: [laughter]".
+ *   - Non-bracketed lines (headings, prose, blank) are returned
+ *     unchanged.
+ *
+ * The function is pure: the input string is not mutated.
+ */
+export declare function humanizeTranscript(body: string, speakerMap: SpeakerAttribution[] | undefined): string;
+/**
+ * Get a meeting with sidecar overlay confirmations layered over its
+ * `speaker_map`. Best-effort convenience: shells to the local `minutes`
+ * CLI (`minutes get <path> --json`) which reads `~/.minutes/overlays.db`
+ * server-side and returns an overlay-applied payload. If the CLI is not
+ * available or the call fails, falls back to plain `getMeeting()` so
+ * consumers always get a usable result.
+ *
+ * For full control over which overlays apply (e.g. to layer a remote
+ * overlay store, or to test against fixtures), use `applySpeakerOverlays`
+ * directly with confirmations sourced however you prefer.
+ */
+export declare function getMeetingWithOverlays(filePath: string, options?: {
+    minutesBin?: string;
+    timeoutMs?: number;
+}): Promise<MeetingFile | null>;
 /**
  * Find open action items across all meetings.
  */

package/dist/reader.js

@@ -104,6 +104,23 @@ export function parseFrontmatter(content, filePath) {
                     by_date: i.by_date ? String(i.by_date) : undefined,
                 }))
                 : [],
+            speaker_map: Array.isArray(parsed.speaker_map)
+                ? parsed.speaker_map.map((s) => ({
+                    speaker_label: String(s.speaker_label || ""),
+                    name: String(s.name || ""),
+                    confidence: (s.confidence === "high" ||
+                        s.confidence === "medium" ||
+                        s.confidence === "low"
+                        ? s.confidence
+                        : "medium"),
+                    source: (s.source === "deterministic" ||
+                        s.source === "llm" ||
+                        s.source === "enrollment" ||
+                        s.source === "manual"
+                        ? s.source
+                        : "llm"),
+                }))
+                : undefined,
         };
         return { frontmatter: fm, body, path: filePath };
     }
@@ -205,6 +222,174 @@ export async function searchMeetings(dir, query, limit = 20) {
 export async function getMeeting(filePath) {
     return readMeetingFile(filePath);
 }
+/**
+ * Layer sidecar speaker confirmations over a meeting's `speaker_map`,
+ * returning a new MeetingFile with the corrections applied. The original
+ * meeting object is not mutated, and the body text is not rewritten —
+ * Minutes treats raw markdown as immutable capture.
+ *
+ * For each confirmation:
+ *   - if a `speaker_map` entry with the same `speaker_label` exists, its
+ *     `name` is replaced and confidence/source are bumped to high/manual
+ *   - if no entry exists, a new one is appended
+ *
+ * Pass an empty `confirmations` array to no-op.
+ */
+export function applySpeakerOverlays(meeting, confirmations) {
+    if (!confirmations || confirmations.length === 0) {
+        return meeting;
+    }
+    const baseMap = meeting.frontmatter.speaker_map ?? [];
+    const merged = baseMap.map((attr) => ({ ...attr }));
+    for (const confirmation of confirmations) {
+        if (!confirmation.speaker_label || !confirmation.name)
+            continue;
+        const existing = merged.find((attr) => attr.speaker_label === confirmation.speaker_label);
+        if (existing) {
+            existing.name = confirmation.name;
+            existing.confidence = "high";
+            existing.source = "manual";
+        }
+        else {
+            merged.push({
+                speaker_label: confirmation.speaker_label,
+                name: confirmation.name,
+                confidence: "high",
+                source: "manual",
+            });
+        }
+    }
+    return {
+        ...meeting,
+        frontmatter: { ...meeting.frontmatter, speaker_map: merged },
+    };
+}
+/**
+ * Rewrite `[SPEAKER_N <timestamp>] text` line prefixes in a meeting
+ * transcript body to use the speaker's mapped name. Mirrors the Rust
+ * `apply_confirmed_names` helper:
+ *
+ *   - Only attributions with `confidence: "high"` are applied — model
+ *     guesses below that bar do not silently rewrite the transcript.
+ *   - If a line's body itself looks like a non-lexical event marker
+ *     (e.g. `[laughter]`, `[music]`), the speaker label is left alone
+ *     so the rendered output keeps the event tag instead of saying
+ *     "Alex Kim: [laughter]".
+ *   - Non-bracketed lines (headings, prose, blank) are returned
+ *     unchanged.
+ *
+ * The function is pure: the input string is not mutated.
+ */
+export function humanizeTranscript(body, speakerMap) {
+    if (!speakerMap || speakerMap.length === 0)
+        return body;
+    const highMap = new Map();
+    for (const attr of speakerMap) {
+        if (attr.confidence === "high" && attr.speaker_label && attr.name) {
+            highMap.set(attr.speaker_label, attr.name);
+        }
+    }
+    if (highMap.size === 0)
+        return body;
+    const out = [];
+    for (const line of body.split("\n")) {
+        out.push(humanizeOneLine(line, highMap));
+    }
+    return out.join("\n");
+}
+function humanizeOneLine(line, highMap) {
+    if (!line.startsWith("["))
+        return line;
+    const close = line.indexOf("]");
+    if (close < 0)
+        return line;
+    const inside = line.slice(1, close);
+    const space = inside.indexOf(" ");
+    if (space < 0)
+        return line;
+    const label = inside.slice(0, space);
+    const replacement = highMap.get(label);
+    if (!replacement)
+        return line;
+    const remainder = inside.slice(space + 1);
+    const after = line.slice(close + 1);
+    // Skip rewriting when the body is itself a bracketed event tag —
+    // matches Rust's is_non_lexical_event_text guard.
+    const trimmedAfter = after.trimStart();
+    if (trimmedAfter.startsWith("[") && trimmedAfter.trimEnd().endsWith("]")) {
+        return line;
+    }
+    return `[${replacement} ${remainder}]${after}`;
+}
+/**
+ * Get a meeting with sidecar overlay confirmations layered over its
+ * `speaker_map`. Best-effort convenience: shells to the local `minutes`
+ * CLI (`minutes get <path> --json`) which reads `~/.minutes/overlays.db`
+ * server-side and returns an overlay-applied payload. If the CLI is not
+ * available or the call fails, falls back to plain `getMeeting()` so
+ * consumers always get a usable result.
+ *
+ * For full control over which overlays apply (e.g. to layer a remote
+ * overlay store, or to test against fixtures), use `applySpeakerOverlays`
+ * directly with confirmations sourced however you prefer.
+ */
+export async function getMeetingWithOverlays(filePath, options = {}) {
+    const fallback = await getMeeting(filePath);
+    if (!fallback)
+        return null;
+    // Dynamically import child_process so this module still loads in
+    // environments without it (browsers, Edge runtimes). The function
+    // simply degrades to non-overlay behavior in those cases.
+    let execFile;
+    try {
+        ({ execFile } = await import("child_process"));
+    }
+    catch {
+        return fallback;
+    }
+    const bin = options.minutesBin ?? process.env.MINUTES_BIN ?? "minutes";
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const stdout = await new Promise((resolve) => {
+        execFile(bin, ["get", filePath, "--json", "--compact-json"], { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024 }, (err, out) => {
+            if (err)
+                resolve(null);
+            else
+                resolve(out.toString());
+        });
+    });
+    if (!stdout)
+        return fallback;
+    try {
+        const payload = JSON.parse(stdout);
+        const overlaidMap = payload?.frontmatter?.speaker_map;
+        if (!Array.isArray(overlaidMap))
+            return fallback;
+        return {
+            ...fallback,
+            frontmatter: {
+                ...fallback.frontmatter,
+                speaker_map: overlaidMap.map((attr) => ({
+                    speaker_label: String(attr.speaker_label || ""),
+                    name: String(attr.name || ""),
+                    confidence: (attr.confidence === "high" ||
+                        attr.confidence === "medium" ||
+                        attr.confidence === "low"
+                        ? attr.confidence
+                        : "medium"),
+                    source: (attr.source === "deterministic" ||
+                        attr.source === "llm" ||
+                        attr.source === "enrollment" ||
+                        attr.source === "manual"
+                        ? attr.source
+                        : "llm"),
+                })),
+            },
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * Find open action items across all meetings.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutes-sdk",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Conversation memory SDK — query meeting transcripts, decisions, and action items from any AI agent or application",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",