@bojanrajkovic/mcp-paprika 1.0.0

package/dist/paprika/client.js

@@ -0,0 +1,183 @@
+/**
+ * Typed HTTP client for the Paprika Cloud Sync API.
+ *
+ * Encapsulates authentication against the v1 login endpoint
+ * and resilient request execution against the v2 data endpoint.
+ *
+ * Provides recipe and category read methods, plus write methods
+ * added in P1-U07 (saveRecipe, deleteRecipe, notifySync).
+ */
+import { gzipSync } from "node:zlib";
+import { ExponentialBackoff, ConsecutiveBreaker, bulkhead, retry, circuitBreaker, handleType, wrap, BrokenCircuitError, } from "cockatiel";
+import { z } from "zod";
+import { AuthResponseSchema, CategorySchema, RecipeEntrySchema, RecipeSchema } from "./types.js";
+import { PaprikaAuthError, PaprikaAPIError } from "./errors.js";
+const AUTH_URL = "https://paprikaapp.com/api/v1/account/login/";
+const API_BASE = "https://paprikaapp.com/api/v2/sync";
+class TransientHTTPError extends Error {
+    status;
+    constructor(status) {
+        super(`Transient HTTP error (${status.toString()})`);
+        this.status = status;
+        this.name = "TransientHTTPError";
+    }
+}
+class TokenExpiredError extends Error {
+    constructor() {
+        super("Token expired");
+        this.name = "TokenExpiredError";
+    }
+}
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503]);
+const retryPolicy = retry(handleType(TransientHTTPError), {
+    maxAttempts: 3,
+    backoff: new ExponentialBackoff({
+        initialDelay: 500,
+        maxDelay: 10_000,
+    }),
+});
+const breakerPolicy = circuitBreaker(handleType(TransientHTTPError), {
+    halfOpenAfter: 30_000,
+    breaker: new ConsecutiveBreaker(5),
+});
+const resilience = wrap(retryPolicy, breakerPolicy);
+function recipeToApiPayload(recipe) {
+    return {
+        uid: recipe.uid,
+        hash: recipe.hash,
+        name: recipe.name,
+        categories: recipe.categories,
+        ingredients: recipe.ingredients,
+        directions: recipe.directions,
+        description: recipe.description,
+        notes: recipe.notes,
+        prep_time: recipe.prepTime,
+        cook_time: recipe.cookTime,
+        total_time: recipe.totalTime,
+        servings: recipe.servings,
+        difficulty: recipe.difficulty,
+        rating: recipe.rating,
+        created: recipe.created,
+        image_url: recipe.imageUrl,
+        photo: recipe.photo,
+        photo_hash: recipe.photoHash,
+        photo_large: recipe.photoLarge,
+        photo_url: recipe.photoUrl,
+        source: recipe.source,
+        source_url: recipe.sourceUrl,
+        on_favorites: recipe.onFavorites,
+        in_trash: recipe.inTrash,
+        is_pinned: recipe.isPinned,
+        on_grocery_list: recipe.onGroceryList,
+        scale: recipe.scale,
+        nutritional_info: recipe.nutritionalInfo,
+    };
+}
+export class PaprikaClient {
+    email;
+    password;
+    token = null;
+    _recipesBulkhead = bulkhead(5, Number.MAX_SAFE_INTEGER);
+    constructor(email, password) {
+        this.email = email;
+        this.password = password;
+    }
+    async authenticate() {
+        const response = await fetch(AUTH_URL, {
+            method: "POST",
+            body: new URLSearchParams({ email: this.email, password: this.password }),
+        });
+        if (!response.ok) {
+            throw new PaprikaAuthError(`Authentication failed (HTTP ${response.status.toString()})`);
+        }
+        const json = await response.json();
+        const data = AuthResponseSchema.parse(json);
+        this.token = data.result.token;
+    }
+    async listRecipes() {
+        return this.request("GET", `${API_BASE}/recipes/`, z.array(RecipeEntrySchema));
+    }
+    async getRecipe(uid) {
+        return this.request("GET", `${API_BASE}/recipe/${uid}/`, RecipeSchema);
+    }
+    async getRecipes(uids) {
+        return Promise.all(uids.map((uid) => this._recipesBulkhead.execute(() => this.getRecipe(uid))));
+    }
+    async listCategories() {
+        return this.request("GET", `${API_BASE}/categories/`, z.array(CategorySchema));
+    }
+    async saveRecipe(recipe) {
+        const formData = this.buildRecipeFormData(recipe);
+        await this.request("POST", `${API_BASE}/recipe/${recipe.uid}/`, z.boolean(), formData);
+        return recipe;
+    }
+    async notifySync() {
+        await this.request("POST", `${API_BASE}/notify/`, z.unknown());
+    }
+    async deleteRecipe(uid) {
+        const recipe = await this.getRecipe(uid);
+        await this.saveRecipe({ ...recipe, inTrash: true });
+        await this.notifySync();
+    }
+    buildRecipeFormData(recipe) {
+        const payload = recipeToApiPayload(recipe);
+        const json = JSON.stringify(payload);
+        const compressed = gzipSync(json);
+        const blob = new Blob([compressed]);
+        const formData = new FormData();
+        formData.append("data", blob, "data.gz");
+        return formData;
+    }
+    async request(method, url, schema, body) {
+        const execute = async () => {
+            const headers = {};
+            if (this.token) {
+                headers["Authorization"] = `Bearer ${this.token}`;
+            }
+            const fetchInit = { method, headers };
+            if (body !== undefined) {
+                fetchInit.body = body;
+            }
+            const response = await fetch(url, fetchInit);
+            if (!response.ok) {
+                if (RETRYABLE_STATUSES.has(response.status)) {
+                    throw new TransientHTTPError(response.status);
+                }
+                if (response.status === 401) {
+                    throw new TokenExpiredError();
+                }
+                throw new PaprikaAPIError("Request failed", response.status, url);
+            }
+            const json = await response.json();
+            const envelope = z.object({ result: schema }).parse(json);
+            return envelope.result;
+        };
+        try {
+            return await resilience.execute(execute);
+        }
+        catch (error) {
+            if (error instanceof BrokenCircuitError) {
+                throw new PaprikaAPIError("Service unavailable (circuit open)", 503, url);
+            }
+            if (error instanceof TokenExpiredError) {
+                if (!this.token) {
+                    throw new PaprikaAuthError("Authentication required (HTTP 401)");
+                }
+                await this.authenticate();
+                try {
+                    return await resilience.execute(execute);
+                }
+                catch (retryError) {
+                    if (retryError instanceof TokenExpiredError) {
+                        throw new PaprikaAuthError("Authentication failed after re-auth (HTTP 401)");
+                    }
+                    if (retryError instanceof BrokenCircuitError) {
+                        throw new PaprikaAPIError("Service unavailable (circuit open)", 503, url);
+                    }
+                    throw retryError;
+                }
+            }
+            throw error;
+        }
+    }
+}

package/dist/paprika/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error class hierarchy for Paprika API operations.
+ *
+ * Three-class structure:
+ * - PaprikaError: base class for all Paprika-related errors
+ * - PaprikaAuthError: authentication failures (extends PaprikaError)
+ * - PaprikaAPIError: HTTP errors with status and endpoint (extends PaprikaError)
+ *
+ * All classes support ES2024 ErrorOptions for cause chaining.
+ */
+/**
+ * Base error class for all Paprika-related operations.
+ * Extends the built-in Error class with proper name assignment.
+ */
+export declare class PaprikaError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when authentication fails.
+ * Indicates that the provided credentials are invalid or expired.
+ * Authentication failures are unrecoverable and typically require user intervention.
+ */
+export declare class PaprikaAuthError extends PaprikaError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when an HTTP request to the Paprika API fails.
+ * Captures the HTTP status code and endpoint for debugging.
+ *
+ * The error message is formatted as: "message (HTTP status from endpoint)"
+ * Example: "Not found (HTTP 404 from /api/v2/sync/recipe/abc/)"
+ */
+export declare class PaprikaAPIError extends PaprikaError {
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(message: string, status: number, endpoint: string, options?: ErrorOptions);
+}

package/dist/paprika/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Error class hierarchy for Paprika API operations.
+ *
+ * Three-class structure:
+ * - PaprikaError: base class for all Paprika-related errors
+ * - PaprikaAuthError: authentication failures (extends PaprikaError)
+ * - PaprikaAPIError: HTTP errors with status and endpoint (extends PaprikaError)
+ *
+ * All classes support ES2024 ErrorOptions for cause chaining.
+ */
+/**
+ * Base error class for all Paprika-related operations.
+ * Extends the built-in Error class with proper name assignment.
+ */
+export class PaprikaError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PaprikaError";
+    }
+}
+/**
+ * Error thrown when authentication fails.
+ * Indicates that the provided credentials are invalid or expired.
+ * Authentication failures are unrecoverable and typically require user intervention.
+ */
+export class PaprikaAuthError extends PaprikaError {
+    constructor(message = "Authentication failed", options) {
+        super(message, options);
+        this.name = "PaprikaAuthError";
+    }
+}
+/**
+ * Error thrown when an HTTP request to the Paprika API fails.
+ * Captures the HTTP status code and endpoint for debugging.
+ *
+ * The error message is formatted as: "message (HTTP status from endpoint)"
+ * Example: "Not found (HTTP 404 from /api/v2/sync/recipe/abc/)"
+ */
+export class PaprikaAPIError extends PaprikaError {
+    status;
+    endpoint;
+    constructor(message, status, endpoint, options) {
+        super(`${message} (HTTP ${status} from ${endpoint})`, options);
+        this.name = "PaprikaAPIError";
+        this.status = status;
+        this.endpoint = endpoint;
+    }
+}

package/dist/paprika/sync.d.ts

@@ -0,0 +1,27 @@
+import type { ServerContext } from "../types/server-context.js";
+import type { SyncResult } from "./types.js";
+type SyncEvents = {
+    "sync:complete": SyncResult;
+    "sync:error": Error;
+};
+type SyncEventEmitter = {
+    on<K extends keyof SyncEvents>(event: K, handler: (data: SyncEvents[K]) => void): void;
+    off<K extends keyof SyncEvents>(event: K, handler?: (data: SyncEvents[K]) => void): void;
+    emit<K extends keyof SyncEvents>(event: K, data: SyncEvents[K]): void;
+    all: Map<keyof SyncEvents, Array<(data: SyncEvents[keyof SyncEvents]) => void>>;
+};
+export declare class SyncEngine {
+    private readonly _context;
+    private readonly _intervalMs;
+    private readonly _events;
+    private readonly _eventsView;
+    private _ac;
+    constructor(context: ServerContext, intervalMs: number);
+    get events(): Pick<SyncEventEmitter, "on" | "off">;
+    start(): void;
+    stop(): void;
+    syncOnce(): Promise<void>;
+    private static _log;
+    private _loop;
+}
+export {};

package/dist/paprika/sync.js

@@ -0,0 +1,150 @@
+import { scheduler } from "node:timers/promises";
+import { createRequire } from "node:module";
+// Use CommonJS require to work around TypeScript ESM resolution issues with mitt
+const require = createRequire(import.meta.url);
+const mittFactory = require("mitt");
+export class SyncEngine {
+    _context;
+    _intervalMs;
+    _events;
+    _eventsView;
+    _ac = null;
+    constructor(context, intervalMs) {
+        this._context = context;
+        this._intervalMs = intervalMs;
+        // CJS require returns unknown; mitt's default export is a factory function that returns the emitter
+        this._events = mittFactory();
+        this._eventsView = {
+            on: this._events.on.bind(this._events),
+            off: this._events.off.bind(this._events),
+        };
+    }
+    get events() {
+        return this._eventsView;
+    }
+    start() {
+        if (this._ac !== null) {
+            return;
+        }
+        this._ac = new AbortController();
+        void this._loop().catch(() => { });
+    }
+    stop() {
+        if (this._ac === null) {
+            return;
+        }
+        this._ac.abort();
+        this._ac = null;
+    }
+    async syncOnce() {
+        try {
+            // 1. Recipe sync path
+            SyncEngine._log("Fetching recipe list...");
+            const entries = await this._context.client.listRecipes();
+            SyncEngine._log(`Got ${entries.length} recipe entries.`);
+            const diff = this._context.cache.diffRecipes(entries);
+            SyncEngine._log(`Recipe diff: ${diff.added.length} added, ${diff.changed.length} changed, ${diff.removed.length} removed.`);
+            // Compute UIDs to fetch
+            const uidsToFetch = [...diff.added, ...diff.changed];
+            // Fetch recipes if any exist
+            let fetchedRecipes = [];
+            if (uidsToFetch.length > 0) {
+                SyncEngine._log(`Fetching ${uidsToFetch.length} recipes...`);
+                fetchedRecipes = await this._context.client.getRecipes(uidsToFetch);
+                SyncEngine._log(`Fetched ${fetchedRecipes.length} recipes.`);
+            }
+            // Write fetched recipes to cache and store
+            for (const recipe of fetchedRecipes) {
+                this._context.cache.putRecipe(recipe, recipe.hash);
+                this._context.store.set(recipe);
+            }
+            // Remove deleted recipes (async, use Promise.all for concurrency)
+            await Promise.all(diff.removed.map((uid) => this._context.cache.removeRecipe(uid)));
+            for (const uid of diff.removed) {
+                this._context.store.delete(uid);
+            }
+            // 2. Category sync path (replace-all)
+            SyncEngine._log("Fetching categories...");
+            const categories = await this._context.client.listCategories();
+            SyncEngine._log(`Got ${categories.length} categories.`);
+            this._context.store.setCategories(categories);
+            for (const category of categories) {
+                this._context.cache.putCategory(category, category.uid);
+            }
+            // 3. Finalization
+            SyncEngine._log("Flushing cache to disk...");
+            await this._context.cache.flush();
+            // Determine if recipe changes exist
+            const hasChanges = diff.added.length > 0 || diff.changed.length > 0 || diff.removed.length > 0;
+            // Send resource notification if changes exist
+            if (hasChanges) {
+                this._context.server.sendResourceListChanged();
+            }
+            // Partition fetched recipes: added vs updated
+            const addedSet = new Set(diff.added);
+            const addedRecipes = fetchedRecipes.filter((r) => addedSet.has(r.uid));
+            const updatedRecipes = fetchedRecipes.filter((r) => !addedSet.has(r.uid));
+            // Build and emit SyncResult
+            const result = {
+                added: addedRecipes,
+                updated: updatedRecipes,
+                removedUids: diff.removed,
+            };
+            this._events.emit("sync:complete", result);
+            SyncEngine._log(`Sync complete: ${addedRecipes.length} added, ${updatedRecipes.length} updated, ${diff.removed.length} removed.`);
+            // Log success via MCP
+            try {
+                await this._context.server.sendLoggingMessage({
+                    level: "info",
+                    data: `Sync complete: ${addedRecipes.length} added, ${updatedRecipes.length} updated, ${diff.removed.length} removed`,
+                });
+            }
+            catch {
+                // Logging may throw if not connected — swallow silently
+            }
+        }
+        catch (error) {
+            // Convert caught value to Error
+            const err = error instanceof Error ? error : new Error(String(error));
+            SyncEngine._log(`Sync failed: ${err.message}`);
+            // Log error via MCP
+            try {
+                await this._context.server.sendLoggingMessage({
+                    level: "error",
+                    data: `Sync failed: ${err.message}`,
+                });
+            }
+            catch {
+                // Logging may throw if not connected — swallow silently
+            }
+            // Emit error event
+            this._events.emit("sync:error", err);
+        }
+    }
+    static _log(msg) {
+        process.stderr.write(`[mcp-paprika:sync] ${msg}\n`);
+    }
+    async _loop() {
+        const signal = this._ac?.signal;
+        if (!signal)
+            return;
+        while (true) {
+            try {
+                await this.syncOnce();
+            }
+            catch (error) {
+                // Defensive: syncOnce() should never throw (AC6.1), but catch here prevents unhandled rejections if the contract is violated
+                this._events.emit("sync:error", error instanceof Error ? error : new Error(String(error)));
+            }
+            try {
+                await scheduler.wait(this._intervalMs, { signal });
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "AbortError") {
+                    return;
+                }
+                throw error;
+            }
+        }
+    }
+}