@getfamiliar/plugin-transcribe-whisper 0.1.2

package/build/Commands.d.ts

@@ -0,0 +1,9 @@
+import { type CommandDef } from "citty";
+import type { HostContext } from "@getfamiliar/shared";
+/**
+ * Build the citty subcommands exposed under
+ * `./cli.sh transcribe-whisper`. Currently a single smoke-test
+ * command; future operational commands (e.g. `cost`, `models`) land
+ * here.
+ */
+export declare function buildCommands(_ctx: HostContext): readonly CommandDef<any>[];

package/build/Commands.js

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { transcribeAudio } from "./Whisper.js";
+/**
+ * Build the citty subcommands exposed under
+ * `./cli.sh transcribe-whisper`. Currently a single smoke-test
+ * command; future operational commands (e.g. `cost`, `models`) land
+ * here.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: matches citty's SubCommandsDef pattern.
+export function buildCommands(_ctx) {
+    return [testCommand()];
+}
+/**
+ * `./cli.sh transcribe-whisper test <path>` — read a local audio
+ * file, send it through {@link transcribeAudio}, and print the
+ * transcript. The operator's smoke test for
+ * "is `inference.apiKeys.openai` set up correctly?" without needing
+ * a live channel plugin.
+ *
+ * No explicit init call here — the host wraps every plugin command's
+ * `run` so `prepare(ctx)` has already fired by the time we land in
+ * the body, populating the module-level API key.
+ */
+function testCommand() {
+    return defineCommand({
+        meta: {
+            name: "test",
+            description: "Transcribe a local audio file with Whisper and print the result. Useful for verifying inference.apiKeys.openai.",
+        },
+        args: {
+            path: {
+                type: "positional",
+                required: true,
+                description: "Path to a local audio file (.ogg, .m4a, .mp3, .wav, .webm, .flac).",
+            },
+        },
+        async run({ args }) {
+            const absolute = path.resolve(args.path);
+            let audio;
+            try {
+                audio = readFileSync(absolute);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`failed to read ${absolute}: ${msg}\n`);
+                process.exit(1);
+            }
+            try {
+                const transcript = await transcribeAudio(audio, path.basename(absolute));
+                process.stdout.write(`${transcript}\n`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`transcription failed: ${msg}\n`);
+                process.exit(1);
+            }
+        },
+    });
+}

package/build/Whisper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Install the OpenAI API key. Called once by the plugin manifest's
+ * `start(ctx)` hook with `ctx.config.getString("inference.apiKeys.openai")`,
+ * and from the plugin's own CLI commands before they run (because
+ * one-shot CLI invocations don't go through `startDaemons`).
+ *
+ * Idempotent — safe to call multiple times. Empty strings are
+ * rejected so a misconfigured field surfaces here instead of as an
+ * opaque OpenAI auth failure on the next transcription.
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Transcribe a buffered audio file using OpenAI's Whisper API
+ * (model `whisper-1`).
+ *
+ * `filename` is used only so OpenAI can infer the audio format from
+ * the extension (e.g. `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`,
+ * `.flac`); the `audio` Buffer holds the actual bytes. Whisper
+ * auto-detects the spoken language, so no language hint is needed.
+ *
+ * Errors propagate to the caller as plain `Error`s — the SDK throws
+ * `OpenAI.APIError` for HTTP failures, which carries enough context
+ * (`status`, `message`) for the caller to handle. Whisper's per-
+ * request limit is 25 MB; we don't pre-validate, so an oversize file
+ * surfaces as a clear API error.
+ *
+ * @param audio The raw audio bytes.
+ * @param filename The original filename (only the extension matters).
+ * @returns The transcribed text.
+ * @throws If the plugin has not been initialized via {@link setApiKey}
+ *   or the API call fails.
+ */
+export declare function transcribeAudio(audio: Buffer, filename: string): Promise<string>;

package/build/Whisper.js

@@ -0,0 +1,61 @@
+import OpenAI, { toFile } from "openai";
+/**
+ * Module-private OpenAI key. Populated once when the plugin is
+ * initialized (see {@link setApiKey} and the `start(ctx)` hook in
+ * `index.ts`); read on every {@link transcribeAudio} call.
+ *
+ * Module-level rather than parameter-passed so callers in other
+ * plugins don't have to know about — or read — Whisper's
+ * authentication: `transcribeAudio(audio, name)` is the entire
+ * surface they see.
+ */
+let apiKey;
+/**
+ * Install the OpenAI API key. Called once by the plugin manifest's
+ * `start(ctx)` hook with `ctx.config.getString("inference.apiKeys.openai")`,
+ * and from the plugin's own CLI commands before they run (because
+ * one-shot CLI invocations don't go through `startDaemons`).
+ *
+ * Idempotent — safe to call multiple times. Empty strings are
+ * rejected so a misconfigured field surfaces here instead of as an
+ * opaque OpenAI auth failure on the next transcription.
+ */
+export function setApiKey(key) {
+    if (!key) {
+        throw new Error("setApiKey requires a non-empty key.");
+    }
+    apiKey = key;
+}
+/**
+ * Transcribe a buffered audio file using OpenAI's Whisper API
+ * (model `whisper-1`).
+ *
+ * `filename` is used only so OpenAI can infer the audio format from
+ * the extension (e.g. `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`,
+ * `.flac`); the `audio` Buffer holds the actual bytes. Whisper
+ * auto-detects the spoken language, so no language hint is needed.
+ *
+ * Errors propagate to the caller as plain `Error`s — the SDK throws
+ * `OpenAI.APIError` for HTTP failures, which carries enough context
+ * (`status`, `message`) for the caller to handle. Whisper's per-
+ * request limit is 25 MB; we don't pre-validate, so an oversize file
+ * surfaces as a clear API error.
+ *
+ * @param audio The raw audio bytes.
+ * @param filename The original filename (only the extension matters).
+ * @returns The transcribed text.
+ * @throws If the plugin has not been initialized via {@link setApiKey}
+ *   or the API call fails.
+ */
+export async function transcribeAudio(audio, filename) {
+    if (!apiKey) {
+        throw new Error("transcribe-whisper is not initialized: call setApiKey, or run inside the host daemon so the plugin's start(ctx) hook fires.");
+    }
+    const client = new OpenAI({ apiKey });
+    const file = await toFile(audio, filename);
+    const result = await client.audio.transcriptions.create({
+        file,
+        model: "whisper-1",
+    });
+    return result.text;
+}

package/build/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Re-export the plugin's public library API. Sibling plugins
+ * consume it as `import { transcribeAudio } from "@getfamiliar/plugin-transcribe-whisper"`.
+ *
+ * Cross-plugin imports are wired the same way as the existing
+ * `@getfamiliar/shared` package: the consuming plugin adds
+ * `"@getfamiliar/plugin-transcribe-whisper": "*"` to its `dependencies`, and npm's
+ * workspace resolution does the rest.
+ *
+ * Note: `setApiKey` is intentionally **not** re-exported. Callers
+ * never see Whisper's auth — the plugin owns its own key, populated
+ * here in `start(ctx)`.
+ */
+export { transcribeAudio } from "./Whisper.js";
+/**
+ * `transcribe-whisper` plugin manifest.
+ *
+ * "Library plugin": no event subscription, no workspace template;
+ * its purpose is to expose {@link transcribeAudio} to other plugins.
+ * The CLI subcommand (`./cli.sh transcribe-whisper test <path>`) is
+ * a smoke test for the OpenAI API key.
+ *
+ * The `prepare(ctx)` hook reads the OpenAI key from the host config
+ * and installs it into the module-private state in `Whisper.ts`, so
+ * sibling plugins call `transcribeAudio(audio, name)` without
+ * thinking about authentication. `prepare` runs before any plugin's
+ * `start` and before any plugin one-shot CLI command, so the order
+ * in `Registry.ts` doesn't matter for siblings that depend on this
+ * plugin.
+ *
+ * A missing `inference.apiKeys.openai` is **not** fatal at boot —
+ * the host stays up and `transcribeAudio` throws a clear
+ * "not initialized" error at the first call site. This lets users
+ * run the daemon for text-only flows (e.g. telegram without voice)
+ * without configuring an OpenAI key.
+ */
+declare const _default: {
+    id: string;
+    host: {
+        prepare: (ctx: import("@getfamiliar/shared").HostContext) => void;
+        commands: (ctx: import("@getfamiliar/shared").HostContext) => readonly import("citty").CommandDef<any>[];
+    };
+};
+export default _default;

package/build/index.js

@@ -0,0 +1,54 @@
+import { definePlugin } from "@getfamiliar/shared";
+import { buildCommands } from "./Commands.js";
+import { setApiKey } from "./Whisper.js";
+/**
+ * Re-export the plugin's public library API. Sibling plugins
+ * consume it as `import { transcribeAudio } from "@getfamiliar/plugin-transcribe-whisper"`.
+ *
+ * Cross-plugin imports are wired the same way as the existing
+ * `@getfamiliar/shared` package: the consuming plugin adds
+ * `"@getfamiliar/plugin-transcribe-whisper": "*"` to its `dependencies`, and npm's
+ * workspace resolution does the rest.
+ *
+ * Note: `setApiKey` is intentionally **not** re-exported. Callers
+ * never see Whisper's auth — the plugin owns its own key, populated
+ * here in `start(ctx)`.
+ */
+export { transcribeAudio } from "./Whisper.js";
+/**
+ * `transcribe-whisper` plugin manifest.
+ *
+ * "Library plugin": no event subscription, no workspace template;
+ * its purpose is to expose {@link transcribeAudio} to other plugins.
+ * The CLI subcommand (`./cli.sh transcribe-whisper test <path>`) is
+ * a smoke test for the OpenAI API key.
+ *
+ * The `prepare(ctx)` hook reads the OpenAI key from the host config
+ * and installs it into the module-private state in `Whisper.ts`, so
+ * sibling plugins call `transcribeAudio(audio, name)` without
+ * thinking about authentication. `prepare` runs before any plugin's
+ * `start` and before any plugin one-shot CLI command, so the order
+ * in `Registry.ts` doesn't matter for siblings that depend on this
+ * plugin.
+ *
+ * A missing `inference.apiKeys.openai` is **not** fatal at boot —
+ * the host stays up and `transcribeAudio` throws a clear
+ * "not initialized" error at the first call site. This lets users
+ * run the daemon for text-only flows (e.g. telegram without voice)
+ * without configuring an OpenAI key.
+ */
+export default definePlugin({
+    id: "transcribe-whisper",
+    host: {
+        prepare: (ctx) => {
+            const key = ctx.config.getString("inference.apiKeys.openai", null);
+            if (key !== null) {
+                setApiKey(key);
+            }
+            else {
+                ctx.logger.info("transcribe-whisper inactive: inference.apiKeys.openai not set in config/config.yml");
+            }
+        },
+        commands: (ctx) => buildCommands(ctx),
+    },
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@getfamiliar/plugin-transcribe-whisper",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "Familiar plugin: transcribeAudio() backed by OpenAI's Whisper API.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "familiar": {
+    "bundled": true
+  },
+  "files": [
+    "build",
+    "workspace-template"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "biome format --write --config-path ../.. src/",
+    "format:check": "biome format --config-path ../.. src/",
+    "lint": "biome lint --config-path ../.. src/",
+    "check": "biome check --config-path ../.. src/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "citty": "^0.1.6",
+    "@getfamiliar/shared": "0.1.2",
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.12",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getfamiliar/familiar.git",
+    "directory": "plugins/transcribe-whisper"
+  }
+}