@bojanrajkovic/mcp-paprika 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bojan Rajkovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @bojanrajkovic/mcp-paprika
+
+An [MCP](https://modelcontextprotocol.io/) server for [Paprika](https://www.paprikaapp.com/) recipe manager. Search, browse, create, and manage your recipes from any MCP client.
+
+## Features
+
+- **10 tools** for recipe management — search, filter, CRUD, categories, pagination
+- **Semantic search** via `discover_recipes` — find recipes by natural language description using any OpenAI-compatible embedding provider
+- **Background sync** — keeps your local cache in sync with Paprika's cloud
+- **MCP resources** — expose recipes as `paprika://recipe/{uid}` resources
+
+## Quick start
+
+Add to your MCP client config (e.g. Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "paprika": {
+      "command": "npx",
+      "args": ["-y", "@bojanrajkovic/mcp-paprika"],
+      "env": {
+        "PAPRIKA_EMAIL": "you@example.com",
+        "PAPRIKA_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+See [configuration](docs/configuration.md) for all available options including background sync and semantic search.
+
+## Documentation
+
+- **[Configuration](docs/configuration.md)** — env vars, config files, platform paths
+- **[Tools reference](docs/tools/)** — all 10 tools with parameters and examples
+- **[Embedding providers](docs/embedding-providers.md)** — set up semantic search with Ollama, OpenAI, OpenRouter, etc.
+- **[Architecture](docs/architecture.md)** — how it works under the hood
+
+## License
+
+[MIT](LICENSE)

package/dist/cache/disk-cache.d.ts

@@ -0,0 +1,21 @@
+import type { Recipe, Category, RecipeEntry, DiffResult } from "../paprika/types.js";
+export declare class DiskCache {
+    private readonly _cacheDir;
+    private readonly _indexPath;
+    private readonly _recipesDir;
+    private readonly _categoriesDir;
+    private _index;
+    private readonly _pendingRecipes;
+    private readonly _pendingCategories;
+    constructor(cacheDir: string);
+    init(): Promise<void>;
+    flush(): Promise<void>;
+    getRecipe(uid: string): Promise<Recipe | null>;
+    putRecipe(recipe: Recipe, hash: string): void;
+    removeRecipe(uid: string): Promise<void>;
+    getAllRecipes(): Promise<Array<Recipe>>;
+    getCategory(uid: string): Promise<Category | null>;
+    putCategory(category: Category, hash: string): void;
+    private _diffEntries;
+    diffRecipes(entries: ReadonlyArray<RecipeEntry>): DiffResult;
+}

package/dist/cache/disk-cache.js

@@ -0,0 +1,252 @@
+import { mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { RecipeStoredSchema, CategoryStoredSchema } from "../paprika/types.js";
+// Type guard for NodeJS.ErrnoException. Mirrors the local helper in
+// utils/config.ts but is intentionally not exported from there — each
+// module defines its own copy per the existing pattern.
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+// I/O error handling convention throughout this file:
+// We use try/catch and check error.code rather than existsSync()-then-read.
+// Reason: existsSync() is synchronous (blocks the event loop) and introduces
+// a TOCTOU race — the file can be deleted between the existence check and the
+// read. The try/catch pattern handles the file's actual state at I/O time with
+// no race window, and the explicit rethrow for non-ENOENT codes (EISDIR,
+// EACCES, …) ensures unexpected errors are never silently swallowed.
+// File-local schema for index.json. Not exported — internal to DiskCache.
+const CacheIndexSchema = z.object({
+    recipes: z.record(z.string(), z.string()),
+    categories: z.record(z.string(), z.string()),
+});
+export class DiskCache {
+    _cacheDir;
+    _indexPath;
+    _recipesDir;
+    _categoriesDir;
+    // Null until init() is called. diff*() and flush() assert non-null.
+    _index = null;
+    // Pending writes buffered by put*(). Drained by flush(). get*() checks
+    // these maps before falling back to disk so callers can read back data
+    // they just put in the same sync cycle.
+    _pendingRecipes = new Map();
+    _pendingCategories = new Map();
+    constructor(cacheDir) {
+        this._cacheDir = cacheDir;
+        this._indexPath = join(cacheDir, "index.json");
+        this._recipesDir = join(cacheDir, "recipes");
+        this._categoriesDir = join(cacheDir, "categories");
+    }
+    async init() {
+        // Create subdirectories (idempotent — recursive: true).
+        await mkdir(this._recipesDir, { recursive: true });
+        await mkdir(this._categoriesDir, { recursive: true });
+        // Load index.json. ENOENT = first run → empty index.
+        // Parse failure = corruption → log warning + empty index.
+        // Other I/O error → rethrow.
+        let raw;
+        try {
+            raw = await readFile(this._indexPath, "utf-8");
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                this._index = { recipes: {}, categories: {} };
+                return;
+            }
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            process.stderr.write("DiskCache: corrupt index.json (invalid JSON), resetting to empty index\n");
+            this._index = { recipes: {}, categories: {} };
+            return;
+        }
+        const result = CacheIndexSchema.safeParse(parsed);
+        if (!result.success) {
+            process.stderr.write("DiskCache: corrupt index.json (schema mismatch), resetting to empty index\n");
+            this._index = { recipes: {}, categories: {} };
+            return;
+        }
+        this._index = result.data;
+    }
+    async flush() {
+        if (this._index === null) {
+            throw new Error("DiskCache: flush() called before init()");
+        }
+        // Write all pending recipe and category files in parallel.
+        // Each file is opened, written, fsynced, and closed before the index
+        // rename — guaranteeing that if a crash occurs after the rename, all
+        // referenced files are durably on disk.
+        await Promise.all([
+            ...[...this._pendingRecipes.entries()].map(async ([uid, recipe]) => {
+                const filePath = join(this._recipesDir, `${uid}.json`);
+                const fh = await open(filePath, "w");
+                try {
+                    await fh.writeFile(JSON.stringify(recipe, null, 2));
+                    await fh.sync();
+                }
+                finally {
+                    await fh.close();
+                }
+            }),
+            ...[...this._pendingCategories.entries()].map(async ([uid, category]) => {
+                const filePath = join(this._categoriesDir, `${uid}.json`);
+                const fh = await open(filePath, "w");
+                try {
+                    await fh.writeFile(JSON.stringify(category, null, 2));
+                    await fh.sync();
+                }
+                finally {
+                    await fh.close();
+                }
+            }),
+        ]);
+        // Write index atomically via temp-then-rename.
+        // The tmp file is written to cacheDir (same filesystem as index.json)
+        // so rename() is a POSIX atomic op within the same directory.
+        const tmpPath = join(this._cacheDir, `.index-${Date.now()}.tmp`);
+        const fh = await open(tmpPath, "w");
+        try {
+            await fh.writeFile(JSON.stringify(this._index, null, 2));
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        await rename(tmpPath, this._indexPath);
+        this._pendingRecipes.clear();
+        this._pendingCategories.clear();
+    }
+    async getRecipe(uid) {
+        // Pending map is checked first so callers can read back data they just
+        // put in the same sync cycle (before flush writes it to disk).
+        const pending = this._pendingRecipes.get(uid);
+        if (pending !== undefined) {
+            return pending;
+        }
+        const filePath = join(this._recipesDir, `${uid}.json`);
+        let raw;
+        try {
+            raw = await readFile(filePath, "utf-8");
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+        return RecipeStoredSchema.parse(JSON.parse(raw));
+    }
+    putRecipe(recipe, hash) {
+        if (this._index === null) {
+            throw new Error("DiskCache: putRecipe() called before init()");
+        }
+        // Buffer in memory only — no file I/O. flush() writes to disk.
+        this._pendingRecipes.set(recipe.uid, recipe);
+        // Update index immediately so diffRecipes() reflects the new hash
+        // without requiring flush() first (AC6.1).
+        this._index.recipes[recipe.uid] = hash;
+    }
+    async removeRecipe(uid) {
+        if (this._index === null) {
+            throw new Error("DiskCache: removeRecipe() called before init()");
+        }
+        // Delete file from disk if present. ENOENT is fine — idempotent.
+        const filePath = join(this._recipesDir, `${uid}.json`);
+        try {
+            await unlink(filePath);
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        // Remove from index and pending map.
+        delete this._index.recipes[uid];
+        this._pendingRecipes.delete(uid);
+    }
+    async getAllRecipes() {
+        if (this._index === null) {
+            throw new Error("DiskCache: getAllRecipes() called before init()");
+        }
+        // Start with pending entries. Pending shadows disk for the same UID.
+        const result = new Map(this._pendingRecipes);
+        // Read all .json files from recipesDir and add those not already in pending.
+        let files;
+        try {
+            files = await readdir(this._recipesDir);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return [...result.values()];
+            }
+            throw error;
+        }
+        const jsonFiles = files.filter((f) => f.endsWith(".json"));
+        await Promise.all(jsonFiles.map(async (filename) => {
+            const uid = filename.slice(0, -5); // strip ".json"
+            if (result.has(uid))
+                return; // pending entry shadows disk
+            const raw = await readFile(join(this._recipesDir, filename), "utf-8");
+            const recipe = RecipeStoredSchema.parse(JSON.parse(raw));
+            result.set(uid, recipe);
+        }));
+        return [...result.values()];
+    }
+    async getCategory(uid) {
+        const pending = this._pendingCategories.get(uid);
+        if (pending !== undefined) {
+            return pending;
+        }
+        const filePath = join(this._categoriesDir, `${uid}.json`);
+        let raw;
+        try {
+            raw = await readFile(filePath, "utf-8");
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+        return CategoryStoredSchema.parse(JSON.parse(raw));
+    }
+    putCategory(category, hash) {
+        if (this._index === null) {
+            throw new Error("DiskCache: putCategory() called before init()");
+        }
+        this._pendingCategories.set(category.uid, category);
+        this._index.categories[category.uid] = hash;
+    }
+    // Private synchronous helper. Classifies remote entries against the local
+    // uid → hash map into added/changed/removed. Uses a Set for O(1) remote
+    // UID lookup so the algorithm is O(n + m), not O(n × m).
+    _diffEntries(remote, local) {
+        const added = [];
+        const changed = [];
+        const remoteUids = new Set();
+        for (const entry of remote) {
+            remoteUids.add(entry.uid);
+            // noUncheckedIndexedAccess: local[uid] is string | undefined
+            const localHash = local[entry.uid];
+            if (localHash === undefined) {
+                added.push(entry.uid);
+            }
+            else if (localHash !== entry.hash) {
+                changed.push(entry.uid);
+            }
+        }
+        const removed = Object.keys(local).filter((uid) => !remoteUids.has(uid));
+        return { added, changed, removed };
+    }
+    diffRecipes(entries) {
+        if (this._index === null) {
+            throw new Error("DiskCache: diffRecipes() called before init()");
+        }
+        return this._diffEntries(entries, this._index.recipes);
+    }
+}

package/dist/cache/recipe-store.d.ts

@@ -0,0 +1,33 @@
+import type { Recipe, Category, RecipeUid, CategoryUid } from "../paprika/types.js";
+export type SearchOptions = {
+    readonly fields?: "all" | "name" | "ingredients" | "description";
+    readonly offset?: number;
+    readonly limit?: number;
+};
+export type ScoredResult = {
+    readonly recipe: Recipe;
+    readonly score: number;
+};
+export type TimeConstraints = {
+    readonly maxPrepTime?: number;
+    readonly maxCookTime?: number;
+    readonly maxTotalTime?: number;
+};
+export declare class RecipeStore {
+    private readonly recipes;
+    private readonly categories;
+    load(recipes: ReadonlyArray<Recipe>, categories: ReadonlyArray<Category>): void;
+    get(uid: RecipeUid): Recipe | undefined;
+    getAll(): Array<Recipe>;
+    set(recipe: Recipe): void;
+    delete(uid: RecipeUid): void;
+    get size(): number;
+    getCategory(uid: CategoryUid): Category | undefined;
+    getAllCategories(): Array<Category>;
+    setCategories(categories: ReadonlyArray<Category>): void;
+    resolveCategories(categoryUids: ReadonlyArray<CategoryUid>): Array<string>;
+    search(query: string, options?: SearchOptions): Array<ScoredResult>;
+    filterByIngredients(terms: ReadonlyArray<string>, mode: "all" | "any", limit?: number): Array<Recipe>;
+    filterByTime(constraints: TimeConstraints): Array<Recipe>;
+    findByName(title: string): Array<Recipe>;
+}

package/dist/cache/recipe-store.js

@@ -0,0 +1,189 @@
+import { parseDuration } from "../utils/duration.js";
+export class RecipeStore {
+    recipes = new Map();
+    categories = new Map();
+    load(recipes, categories) {
+        this.recipes.clear();
+        for (const recipe of recipes) {
+            this.recipes.set(recipe.uid, recipe);
+        }
+        this.categories.clear();
+        for (const category of categories) {
+            this.categories.set(category.uid, category);
+        }
+    }
+    get(uid) {
+        return this.recipes.get(uid);
+    }
+    getAll() {
+        const results = [];
+        for (const recipe of this.recipes.values()) {
+            if (!recipe.inTrash) {
+                results.push(recipe);
+            }
+        }
+        return results;
+    }
+    set(recipe) {
+        this.recipes.set(recipe.uid, recipe);
+    }
+    delete(uid) {
+        this.recipes.delete(uid);
+    }
+    get size() {
+        let count = 0;
+        for (const recipe of this.recipes.values()) {
+            if (!recipe.inTrash) {
+                count++;
+            }
+        }
+        return count;
+    }
+    getCategory(uid) {
+        return this.categories.get(uid);
+    }
+    getAllCategories() {
+        return [...this.categories.values()];
+    }
+    setCategories(categories) {
+        this.categories.clear();
+        for (const category of categories) {
+            this.categories.set(category.uid, category);
+        }
+    }
+    resolveCategories(categoryUids) {
+        const names = [];
+        for (const uid of categoryUids) {
+            const category = this.categories.get(uid);
+            if (category) {
+                names.push(category.name);
+            }
+        }
+        return names;
+    }
+    search(query, options) {
+        const fields = options?.fields ?? "all";
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit;
+        const lowerQuery = query.toLowerCase();
+        const results = [];
+        for (const recipe of this.recipes.values()) {
+            if (recipe.inTrash)
+                continue;
+            if (lowerQuery === "") {
+                results.push({ recipe, score: 0 });
+                continue;
+            }
+            const lowerName = recipe.name.toLowerCase();
+            let score = -1;
+            if (fields === "all" || fields === "name") {
+                if (lowerName === lowerQuery) {
+                    score = 3;
+                }
+                else if (lowerName.startsWith(lowerQuery)) {
+                    score = 2;
+                }
+                else if (lowerName.includes(lowerQuery)) {
+                    score = 1;
+                }
+            }
+            if (score === -1 && (fields === "all" || fields === "ingredients")) {
+                if (recipe.ingredients.toLowerCase().includes(lowerQuery)) {
+                    score = 0;
+                }
+            }
+            if (score === -1 && (fields === "all" || fields === "description")) {
+                if (recipe.description?.toLowerCase().includes(lowerQuery)) {
+                    score = 0;
+                }
+            }
+            if (score === -1 && fields === "all") {
+                if (recipe.notes?.toLowerCase().includes(lowerQuery)) {
+                    score = 0;
+                }
+            }
+            if (score >= 0) {
+                results.push({ recipe, score });
+            }
+        }
+        results.sort((a, b) => {
+            if (a.score !== b.score)
+                return b.score - a.score;
+            return a.recipe.name.localeCompare(b.recipe.name);
+        });
+        const sliced = limit !== undefined ? results.slice(offset, offset + limit) : results.slice(offset);
+        return sliced;
+    }
+    filterByIngredients(terms, mode, limit) {
+        const recipes = this.getAll();
+        if (terms.length === 0) {
+            return limit !== undefined ? recipes.slice(0, limit) : recipes;
+        }
+        const lowerTerms = terms.map((t) => t.toLowerCase());
+        const matched = recipes.filter((recipe) => {
+            const lowerIngredients = recipe.ingredients.toLowerCase();
+            if (mode === "all") {
+                return lowerTerms.every((term) => lowerIngredients.includes(term));
+            }
+            return lowerTerms.some((term) => lowerIngredients.includes(term));
+        });
+        return limit !== undefined ? matched.slice(0, limit) : matched;
+    }
+    filterByTime(constraints) {
+        const recipes = this.getAll();
+        const hasConstraints = constraints.maxPrepTime !== undefined ||
+            constraints.maxCookTime !== undefined ||
+            constraints.maxTotalTime !== undefined;
+        const filtered = hasConstraints
+            ? recipes.filter((recipe) => {
+                if (constraints.maxPrepTime !== undefined && recipe.prepTime !== null) {
+                    const maxPrepTime = constraints.maxPrepTime;
+                    if (parseDuration(recipe.prepTime).match((d) => d.as("minutes") > maxPrepTime, () => false)) {
+                        return false;
+                    }
+                }
+                if (constraints.maxCookTime !== undefined && recipe.cookTime !== null) {
+                    const maxCookTime = constraints.maxCookTime;
+                    if (parseDuration(recipe.cookTime).match((d) => d.as("minutes") > maxCookTime, () => false)) {
+                        return false;
+                    }
+                }
+                if (constraints.maxTotalTime !== undefined && recipe.totalTime !== null) {
+                    const maxTotalTime = constraints.maxTotalTime;
+                    if (parseDuration(recipe.totalTime).match((d) => d.as("minutes") > maxTotalTime, () => false)) {
+                        return false;
+                    }
+                }
+                return true;
+            })
+            : recipes;
+        return filtered.toSorted((a, b) => {
+            const aMinutes = parseTotalTimeMinutes(a.totalTime);
+            const bMinutes = parseTotalTimeMinutes(b.totalTime);
+            if (aMinutes === null && bMinutes === null)
+                return 0;
+            if (aMinutes === null)
+                return 1;
+            if (bMinutes === null)
+                return -1;
+            return aMinutes - bMinutes;
+        });
+    }
+    findByName(title) {
+        const recipes = this.getAll();
+        const lowerTitle = title.toLowerCase();
+        const exact = recipes.filter((r) => r.name.toLowerCase() === lowerTitle);
+        if (exact.length > 0)
+            return exact;
+        const startsWith = recipes.filter((r) => r.name.toLowerCase().startsWith(lowerTitle));
+        if (startsWith.length > 0)
+            return startsWith;
+        const contains = recipes.filter((r) => r.name.toLowerCase().includes(lowerTitle));
+        return contains;
+    }
+}
+function parseTotalTimeMinutes(totalTime) {
+    if (totalTime === null)
+        return null;
+    return parseDuration(totalTime).match((d) => d.as("minutes"), () => null);
+}

package/dist/features/discover-feature.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerContext } from "../types/server-context.js";
+import type { SyncEngine } from "../paprika/sync.js";
+import type { PaprikaConfig } from "../utils/config.js";
+export declare function setupDiscoverFeature(server: McpServer, ctx: ServerContext, sync: SyncEngine, config: PaprikaConfig): Promise<void>;

package/dist/features/discover-feature.js

@@ -0,0 +1,39 @@
+import { EmbeddingClient } from "./embeddings.js";
+import { VectorStore } from "./vector-store.js";
+import { registerDiscoverTool } from "../tools/discover.js";
+import { getCacheDir } from "../utils/xdg.js";
+export async function setupDiscoverFeature(server, ctx, sync, config) {
+    const embeddingsConfig = config.features?.embeddings;
+    if (!embeddingsConfig) {
+        process.stderr.write("[mcp-paprika] Semantic search: disabled\n");
+        return;
+    }
+    const embedder = new EmbeddingClient(embeddingsConfig);
+    const vectorStore = new VectorStore(getCacheDir(), embedder);
+    await vectorStore.init();
+    registerDiscoverTool(server, ctx, vectorStore);
+    // Cold-start initial indexing: the initial sync.syncOnce() in index.ts fires
+    // sync:complete BEFORE this subscription exists. On first-ever startup (empty
+    // vector index), explicitly index all recipes already in the store.
+    if (vectorStore.size === 0 && ctx.store.size > 0) {
+        await vectorStore.indexRecipes(ctx.store.getAll(), (uids) => ctx.store.resolveCategories(uids));
+    }
+    sync.events.on("sync:complete", async (result) => {
+        try {
+            const changed = [...result.added, ...result.updated];
+            if (changed.length === 0 && result.removedUids.length === 0) {
+                return;
+            }
+            if (changed.length > 0) {
+                await vectorStore.indexRecipes(changed, (uids) => ctx.store.resolveCategories(uids));
+            }
+            for (const uid of result.removedUids) {
+                await vectorStore.removeRecipe(uid);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[mcp-paprika] Vector index error: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    });
+    process.stderr.write("[mcp-paprika] Semantic search: enabled\n");
+}

package/dist/features/embedding-errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error class hierarchy for embedding operations.
+ *
+ * Two-class structure:
+ * - EmbeddingError: base class for all embedding-related errors
+ * - EmbeddingAPIError: HTTP errors with status and endpoint (extends EmbeddingError)
+ *
+ * All classes support ES2024 ErrorOptions for cause chaining.
+ */
+/**
+ * Base error class for all embedding-related operations.
+ */
+export declare class EmbeddingError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when an HTTP request to the embedding API fails.
+ * Captures the HTTP status code and endpoint for debugging.
+ *
+ * The error message is formatted as: "message (HTTP status from endpoint)"
+ */
+export declare class EmbeddingAPIError extends EmbeddingError {
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(message: string, status: number, endpoint: string, options?: ErrorOptions);
+}

package/dist/features/embedding-errors.js

@@ -0,0 +1,34 @@
+/**
+ * Error class hierarchy for embedding operations.
+ *
+ * Two-class structure:
+ * - EmbeddingError: base class for all embedding-related errors
+ * - EmbeddingAPIError: HTTP errors with status and endpoint (extends EmbeddingError)
+ *
+ * All classes support ES2024 ErrorOptions for cause chaining.
+ */
+/**
+ * Base error class for all embedding-related operations.
+ */
+export class EmbeddingError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "EmbeddingError";
+    }
+}
+/**
+ * Error thrown when an HTTP request to the embedding API fails.
+ * Captures the HTTP status code and endpoint for debugging.
+ *
+ * The error message is formatted as: "message (HTTP status from endpoint)"
+ */
+export class EmbeddingAPIError extends EmbeddingError {
+    status;
+    endpoint;
+    constructor(message, status, endpoint, options) {
+        super(`${message} (HTTP ${status} from ${endpoint})`, options);
+        this.name = "EmbeddingAPIError";
+        this.status = status;
+        this.endpoint = endpoint;
+    }
+}