@jgardner04/ghost-mcp-server 1.13.4 → 1.14.0

package/src/services/posts.js

@@ -0,0 +1,116 @@
+import { ValidationError } from '../errors/index.js';
+import { sanitizeNqlValue } from '../utils/nqlSanitizer.js';
+import { handleApiRequest, readResource } from './ghostApiClient.js';
+import { createResourceService } from './createResourceService.js';
+import { validators } from './validators.js';
+
+const service = createResourceService({
+  resource: 'posts',
+  label: 'Post',
+  createDefaults: { status: 'draft' },
+  createOptions: { source: 'html' },
+  listDefaults: { limit: 15, include: 'tags,authors' },
+  validateCreate: (data) => validators.validatePostData(data),
+  validateUpdate: async (id, updateData) => {
+    if (updateData.status || updateData.published_at) {
+      let validationData = updateData;
+      if (!updateData.status && updateData.published_at) {
+        const existing = await readResource('posts', id, 'Post');
+        validationData = { ...updateData, status: existing.status };
+      }
+      validators.validateScheduledStatus(validationData, 'Post');
+    }
+  },
+});
+
+/**
+ * Creates a new post in Ghost CMS.
+ * @param {Object} postData - The post data
+ * @param {string} postData.title - Post title (required)
+ * @param {string} [postData.html] - HTML content (required if mobiledoc not provided)
+ * @param {string} [postData.mobiledoc] - Mobiledoc content (required if html not provided)
+ * @param {string} [postData.status='draft'] - Post status ('draft', 'published', 'scheduled')
+ * @param {string} [postData.published_at] - ISO 8601 date for scheduled posts
+ * @param {Object} [options={ source: 'html' }] - API request options
+ * @returns {Promise<Object>} The created post object
+ * @throws {ValidationError} If validation fails or Ghost returns a 422
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const createPost = service.create;
+
+/**
+ * Updates an existing post with optimistic concurrency control.
+ * Validates scheduling fields when status or published_at is being changed.
+ * @param {string} postId - The post ID to update
+ * @param {Object} updateData - Fields to update on the post
+ * @param {Object} [options={}] - API request options
+ * @returns {Promise<Object>} The updated post object
+ * @throws {ValidationError} If the post ID is missing or scheduling validation fails
+ * @throws {NotFoundError} If the post is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const updatePost = service.update;
+
+/**
+ * Deletes a post by ID.
+ * @param {string} postId - The post ID to delete
+ * @returns {Promise<Object>} Deletion confirmation
+ * @throws {ValidationError} If the post ID is missing
+ * @throws {NotFoundError} If the post is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deletePost = service.remove;
+
+/**
+ * Retrieves a single post by ID.
+ * @param {string} postId - The post ID to retrieve
+ * @param {Object} [options={}] - API request options (e.g., includes)
+ * @returns {Promise<Object>} The post object
+ * @throws {ValidationError} If the post ID is missing
+ * @throws {NotFoundError} If the post is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getPost = service.getOne;
+
+/**
+ * Lists posts with optional filtering and pagination.
+ * @param {Object} [options={}] - Query options
+ * @param {number} [options.limit=15] - Number of posts to return
+ * @param {string} [options.include='tags,authors'] - Related resources to include
+ * @param {string} [options.filter] - NQL filter string
+ * @param {string} [options.order] - Order string (e.g., 'published_at desc')
+ * @returns {Promise<Array>} Array of post objects
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getPosts = service.getList;
+
+/**
+ * Searches posts by title using Ghost NQL fuzzy matching.
+ * @param {string} query - Search query string (required, non-empty)
+ * @param {Object} [options={}] - Additional search options
+ * @param {string} [options.status] - Filter by status ('draft', 'published', 'scheduled', or 'all')
+ * @param {number} [options.limit=15] - Maximum number of results
+ * @returns {Promise<Array>} Array of matching post objects
+ * @throws {ValidationError} If the query is empty
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function searchPosts(query, options = {}) {
+  if (!query || query.trim().length === 0) {
+    throw new ValidationError('Search query is required');
+  }
+
+  const sanitizedQuery = sanitizeNqlValue(query);
+
+  const filterParts = [`title:~'${sanitizedQuery}'`];
+  if (options.status && options.status !== 'all') {
+    filterParts.push(`status:${options.status}`);
+  }
+
+  const searchOptions = {
+    limit: options.limit || 15,
+    include: 'tags,authors',
+    filter: filterParts.join('+'),
+  };
+
+  return handleApiRequest('posts', 'browse', {}, searchOptions);
+}

package/src/services/tags.js

@@ -0,0 +1,118 @@
+import { GhostAPIError, ValidationError, NotFoundError } from '../errors/index.js';
+import { sanitizeNqlValue } from '../utils/nqlSanitizer.js';
+import { handleApiRequest, readResource } from './ghostApiClient.js';
+import { createResourceService } from './createResourceService.js';
+import { validators } from './validators.js';
+
+const service = createResourceService({
+  resource: 'tags',
+  label: 'Tag',
+  listDefaults: { limit: 15 },
+});
+
+/**
+ * Creates a new tag in Ghost CMS. Auto-generates a slug from the name if not provided.
+ * If a tag with the same name already exists, returns the existing tag instead of failing.
+ * @param {Object} tagData - The tag data
+ * @param {string} tagData.name - Tag name (required)
+ * @param {string} [tagData.slug] - Tag slug (auto-generated from name if omitted)
+ * @param {string} [tagData.description] - Tag description
+ * @returns {Promise<Object>} The created (or existing) tag object
+ * @throws {ValidationError} If validation fails or Ghost returns a 422 (non-duplicate)
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function createTag(tagData) {
+  validators.validateTagData(tagData);
+
+  const dataToCreate = tagData.slug
+    ? { ...tagData }
+    : {
+        ...tagData,
+        slug: tagData.name
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-+|-+$/g, ''),
+      };
+
+  try {
+    return await handleApiRequest('tags', 'add', dataToCreate);
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 422) {
+      if (error.originalError.includes('already exists')) {
+        const existingTags = await getTags({ filter: `name:'${sanitizeNqlValue(tagData.name)}'` });
+        if (existingTags.length > 0) {
+          return existingTags[0];
+        }
+      }
+      throw new ValidationError('Tag creation failed', [
+        { field: 'tag', message: error.originalError },
+      ]);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Lists tags with optional filtering and pagination.
+ * @param {Object} [options={}] - Query options
+ * @param {number} [options.limit=15] - Number of tags to return
+ * @param {string} [options.filter] - NQL filter string
+ * @param {string} [options.order] - Order string
+ * @returns {Promise<Array>} Array of tag objects (empty array if none found)
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getTags = service.getList;
+
+/**
+ * Retrieves a single tag by ID.
+ * @param {string} tagId - The tag ID to retrieve
+ * @param {Object} [options={}] - API request options
+ * @returns {Promise<Object>} The tag object
+ * @throws {ValidationError} If the tag ID is missing
+ * @throws {NotFoundError} If the tag is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getTag = service.getOne;
+
+/**
+ * Updates an existing tag. Validates update data and checks that the tag exists first.
+ * Tags use direct edit (not OCC) since they don't have concurrent editing concerns.
+ * @param {string} tagId - The tag ID to update
+ * @param {Object} updateData - Fields to update on the tag
+ * @param {string} [updateData.name] - Updated tag name
+ * @param {string} [updateData.slug] - Updated tag slug
+ * @param {string} [updateData.description] - Updated tag description
+ * @returns {Promise<Object>} The updated tag object
+ * @throws {ValidationError} If the tag ID is missing or update data is invalid
+ * @throws {NotFoundError} If the tag is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function updateTag(tagId, updateData) {
+  validators.requireId(tagId, 'Tag');
+  validators.validateTagUpdateData(updateData);
+
+  try {
+    await readResource('tags', tagId, 'Tag');
+    return await handleApiRequest('tags', 'edit', { id: tagId, ...updateData });
+  } catch (error) {
+    if (error instanceof NotFoundError) {
+      throw error;
+    }
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 422) {
+      throw new ValidationError('Tag update failed', [
+        { field: 'tag', message: error.originalError },
+      ]);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Deletes a tag by ID.
+ * @param {string} tagId - The tag ID to delete
+ * @returns {Promise<Object>} Deletion confirmation
+ * @throws {ValidationError} If the tag ID is missing
+ * @throws {NotFoundError} If the tag is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deleteTag = service.remove;

package/src/services/tiers.js

@@ -0,0 +1,72 @@
+import { createResourceService } from './createResourceService.js';
+import {
+  validateTierData,
+  validateTierUpdateData,
+  validateTierQueryOptions,
+} from './tierService.js';
+
+const service = createResourceService({
+  resource: 'tiers',
+  label: 'Tier',
+  listDefaults: { limit: 15 },
+  validateCreate: (data) => validateTierData(data),
+  validateUpdate: (_id, data) => validateTierUpdateData(data),
+});
+
+/**
+ * Create a new tier (membership level)
+ * @param {Object} tierData - Tier data
+ * @param {Object} [options={}] - Options for the API request
+ * @returns {Promise<Object>} Created tier
+ * @throws {ValidationError} If validation fails or Ghost returns a 422
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const createTier = service.create;
+
+/**
+ * Update an existing tier with optimistic concurrency control.
+ * @param {string} id - Tier ID
+ * @param {Object} updateData - Tier update data
+ * @param {Object} [options={}] - Options for the API request
+ * @returns {Promise<Object>} Updated tier
+ * @throws {ValidationError} If the tier ID is missing or update data is invalid
+ * @throws {NotFoundError} If the tier is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const updateTier = service.update;
+
+/**
+ * Delete a tier by ID.
+ * @param {string} id - Tier ID
+ * @returns {Promise<Object>} Deletion result
+ * @throws {ValidationError} If the tier ID is missing
+ * @throws {NotFoundError} If the tier is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deleteTier = service.remove;
+
+/**
+ * Get all tiers with optional filtering
+ * @param {Object} [options={}] - Query options
+ * @param {number} [options.limit] - Number of tiers to return (1-100, default 15)
+ * @param {number} [options.page] - Page number
+ * @param {string} [options.filter] - NQL filter string (e.g., "type:paid", "type:free")
+ * @param {string} [options.order] - Order string
+ * @param {string} [options.include] - Include string
+ * @returns {Promise<Array>} Array of tiers
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function getTiers(options = {}) {
+  validateTierQueryOptions(options);
+  return service.getList(options);
+}
+
+/**
+ * Get a single tier by ID.
+ * @param {string} id - Tier ID
+ * @returns {Promise<Object>} Tier object
+ * @throws {ValidationError} If the tier ID is missing
+ * @throws {NotFoundError} If the tier is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getTier = service.getOne;

package/src/services/validators.js

@@ -0,0 +1,218 @@
+import { promises as fs } from 'fs';
+import { ValidationError, NotFoundError } from '../errors/index.js';
+
+/**
+ * Input validation helpers
+ */
+export const validators = {
+  /**
+   * Validates that an ID is a non-empty string. Used by CRUD helpers to enforce
+   * consistent ID validation across all resource types.
+   * @param {string} id - The resource ID to validate
+   * @param {string} entityName - Human-readable resource name for error messages (e.g., 'Post', 'Tag')
+   * @throws {ValidationError} If the ID is falsy, not a string, or empty/whitespace
+   */
+  requireId(id, entityName) {
+    if (!id || typeof id !== 'string' || id.trim().length === 0) {
+      throw new ValidationError(`${entityName} ID is required`);
+    }
+  },
+
+  /**
+   * Validates scheduling fields for posts and pages. Ensures published_at is present
+   * when status is 'scheduled' and that the date is valid and in the future.
+   * @param {Object} data - The resource data containing status and/or published_at
+   * @param {string} [data.status] - Resource status ('draft', 'published', 'scheduled')
+   * @param {string} [data.published_at] - ISO 8601 date string for scheduling
+   * @param {string} [resourceLabel='Resource'] - Human-readable label for error messages
+   * @throws {ValidationError} If scheduling validation fails
+   */
+  validateScheduledStatus(data, resourceLabel = 'Resource') {
+    const errors = [];
+
+    if (data.status === 'scheduled' && !data.published_at) {
+      errors.push({
+        field: 'published_at',
+        message: 'published_at is required when status is scheduled',
+      });
+    }
+
+    if (data.published_at) {
+      const publishDate = new Date(data.published_at);
+      if (isNaN(publishDate.getTime())) {
+        errors.push({ field: 'published_at', message: 'Invalid date format' });
+      } else if (data.status === 'scheduled' && publishDate <= new Date()) {
+        errors.push({ field: 'published_at', message: 'Scheduled date must be in the future' });
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError(`${resourceLabel} validation failed`, errors);
+    }
+  },
+
+  /**
+   * Validates post creation data. Requires a title and either html or mobiledoc content.
+   * Also validates status values and delegates to validateScheduledStatus for scheduling.
+   * @param {Object} postData - The post data to validate
+   * @param {string} postData.title - Post title (required, non-empty)
+   * @param {string} [postData.html] - HTML content (required if mobiledoc not provided)
+   * @param {string} [postData.mobiledoc] - Mobiledoc content (required if html not provided)
+   * @param {string} [postData.status] - Post status ('draft', 'published', 'scheduled')
+   * @param {string} [postData.published_at] - ISO 8601 date for scheduled posts
+   * @throws {ValidationError} If validation fails
+   */
+  validatePostData(postData) {
+    const errors = [];
+
+    if (!postData.title || postData.title.trim().length === 0) {
+      errors.push({ field: 'title', message: 'Title is required' });
+    }
+
+    if (!postData.html && !postData.mobiledoc) {
+      errors.push({ field: 'content', message: 'Either html or mobiledoc content is required' });
+    }
+
+    if (postData.status && !['draft', 'published', 'scheduled'].includes(postData.status)) {
+      errors.push({
+        field: 'status',
+        message: 'Invalid status. Must be draft, published, or scheduled',
+      });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Post validation failed', errors);
+    }
+
+    this.validateScheduledStatus(postData, 'Post');
+  },
+
+  /**
+   * Validates tag creation data. Requires a non-empty name and validates slug format.
+   * @param {Object} tagData - The tag data to validate
+   * @param {string} tagData.name - Tag name (required, non-empty)
+   * @param {string} [tagData.slug] - Tag slug (lowercase letters, numbers, hyphens only)
+   * @throws {ValidationError} If validation fails
+   */
+  validateTagData(tagData) {
+    const errors = [];
+
+    if (!tagData.name || tagData.name.trim().length === 0) {
+      errors.push({ field: 'name', message: 'Tag name is required' });
+    }
+
+    if (tagData.slug && !/^[a-z0-9-]+$/.test(tagData.slug)) {
+      errors.push({
+        field: 'slug',
+        message: 'Slug must contain only lowercase letters, numbers, and hyphens',
+      });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Tag validation failed', errors);
+    }
+  },
+
+  /**
+   * Validates tag update data. Name is optional but cannot be empty if provided.
+   * Validates slug format if provided.
+   * @param {Object} updateData - The tag update data to validate
+   * @param {string} [updateData.name] - Tag name (cannot be empty if provided)
+   * @param {string} [updateData.slug] - Tag slug (lowercase letters, numbers, hyphens only)
+   * @throws {ValidationError} If validation fails
+   */
+  validateTagUpdateData(updateData) {
+    const errors = [];
+
+    // Name is optional in updates, but if provided, it cannot be empty
+    if (updateData.name !== undefined && updateData.name.trim().length === 0) {
+      errors.push({ field: 'name', message: 'Tag name cannot be empty' });
+    }
+
+    // Validate slug format if provided
+    if (updateData.slug && !/^[a-z0-9-]+$/.test(updateData.slug)) {
+      errors.push({
+        field: 'slug',
+        message: 'Slug must contain only lowercase letters, numbers, and hyphens',
+      });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Tag update validation failed', errors);
+    }
+  },
+
+  /**
+   * Validates that an image path is a non-empty string and that the file exists on disk.
+   * @param {string} imagePath - Absolute path to the image file
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If imagePath is falsy or not a string
+   * @throws {NotFoundError} If the file does not exist at the given path
+   */
+  async validateImagePath(imagePath) {
+    if (!imagePath || typeof imagePath !== 'string') {
+      throw new ValidationError('Image path is required and must be a string');
+    }
+
+    // Check if file exists
+    try {
+      await fs.access(imagePath);
+    } catch {
+      throw new NotFoundError('Image file', imagePath);
+    }
+  },
+
+  /**
+   * Validates page creation data. Requires a title and either html or mobiledoc content.
+   * Also validates status values and delegates to validateScheduledStatus for scheduling.
+   * @param {Object} pageData - The page data to validate
+   * @param {string} pageData.title - Page title (required, non-empty)
+   * @param {string} [pageData.html] - HTML content (required if mobiledoc not provided)
+   * @param {string} [pageData.mobiledoc] - Mobiledoc content (required if html not provided)
+   * @param {string} [pageData.status] - Page status ('draft', 'published', 'scheduled')
+   * @param {string} [pageData.published_at] - ISO 8601 date for scheduled pages
+   * @throws {ValidationError} If validation fails
+   */
+  validatePageData(pageData) {
+    const errors = [];
+
+    if (!pageData.title || pageData.title.trim().length === 0) {
+      errors.push({ field: 'title', message: 'Title is required' });
+    }
+
+    if (!pageData.html && !pageData.mobiledoc) {
+      errors.push({ field: 'content', message: 'Either html or mobiledoc content is required' });
+    }
+
+    if (pageData.status && !['draft', 'published', 'scheduled'].includes(pageData.status)) {
+      errors.push({
+        field: 'status',
+        message: 'Invalid status. Must be draft, published, or scheduled',
+      });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Page validation failed', errors);
+    }
+
+    this.validateScheduledStatus(pageData, 'Page');
+  },
+
+  /**
+   * Validates newsletter creation data. Requires a non-empty name.
+   * @param {Object} newsletterData - The newsletter data to validate
+   * @param {string} newsletterData.name - Newsletter name (required, non-empty)
+   * @throws {ValidationError} If validation fails
+   */
+  validateNewsletterData(newsletterData) {
+    const errors = [];
+
+    if (!newsletterData.name || newsletterData.name.trim().length === 0) {
+      errors.push({ field: 'name', message: 'Newsletter name is required' });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Newsletter validation failed', errors);
+    }
+  },
+};

package/src/utils/__tests__/imageInputResolver.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+import {
+  resolveLocalImagePath,
+  decodeBase64ToTempFile,
+  MAX_BASE64_BYTES,
+} from '../imageInputResolver.js';
+
+const tmpRoot = path.join(os.tmpdir(), `img-resolver-${Date.now()}`);
+const allowedRoot = path.join(tmpRoot, 'allowed');
+const outside = path.join(tmpRoot, 'outside');
+
+beforeAll(async () => {
+  await fs.mkdir(allowedRoot, { recursive: true });
+  await fs.mkdir(outside, { recursive: true });
+  await fs.writeFile(path.join(allowedRoot, 'ok.png'), 'fake-png');
+  await fs.writeFile(path.join(outside, 'secret.txt'), 'top secret');
+  await fs.symlink(path.join(outside, 'secret.txt'), path.join(allowedRoot, 'escape.txt'));
+});
+
+afterAll(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe('resolveLocalImagePath', () => {
+  const origRoot = process.env.GHOST_MCP_IMAGE_ROOT;
+
+  beforeEach(() => {
+    process.env.GHOST_MCP_IMAGE_ROOT = allowedRoot;
+  });
+
+  afterEach(() => {
+    if (origRoot === undefined) delete process.env.GHOST_MCP_IMAGE_ROOT;
+    else process.env.GHOST_MCP_IMAGE_ROOT = origRoot;
+  });
+
+  it('accepts a file inside the configured root', async () => {
+    const resolved = await resolveLocalImagePath(path.join(allowedRoot, 'ok.png'));
+    // Returns the realpath, which on macOS canonicalizes /var -> /private/var.
+    const canonical = await fs.realpath(path.join(allowedRoot, 'ok.png'));
+    expect(resolved).toBe(canonical);
+  });
+
+  it('rejects when GHOST_MCP_IMAGE_ROOT is unset (local-path mode disabled by default)', async () => {
+    delete process.env.GHOST_MCP_IMAGE_ROOT;
+    await expect(resolveLocalImagePath('/anywhere.png')).rejects.toThrow(
+      /GHOST_MCP_IMAGE_ROOT is not set/
+    );
+  });
+
+  it('rejects a path outside the configured root', async () => {
+    await expect(resolveLocalImagePath(path.join(outside, 'secret.txt'))).rejects.toThrow(
+      /outside the allowed root/
+    );
+  });
+
+  it('rejects a relative traversal attempt', async () => {
+    await expect(resolveLocalImagePath(`${allowedRoot}/../outside/secret.txt`)).rejects.toThrow(
+      /outside the allowed root/
+    );
+  });
+
+  it('rejects a symlink that escapes the allowed root', async () => {
+    await expect(resolveLocalImagePath(path.join(allowedRoot, 'escape.txt'))).rejects.toThrow(
+      /symlink escapes/
+    );
+  });
+
+  it('rejects a non-existent file', async () => {
+    await expect(resolveLocalImagePath(path.join(allowedRoot, 'nope.png'))).rejects.toThrow(
+      /does not exist/
+    );
+  });
+});
+
+describe('decodeBase64ToTempFile', () => {
+  it('decodes a plain base64 string to a temp file', async () => {
+    const payload = Buffer.from('hello png');
+    const out = await decodeBase64ToTempFile(payload.toString('base64'), 'image/png');
+    try {
+      expect(path.extname(out)).toBe('.png');
+      const written = await fs.readFile(out);
+      expect(written.equals(payload)).toBe(true);
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+
+  it('accepts a full data: URI and ignores the prefix', async () => {
+    const payload = Buffer.from('svg-bytes');
+    const dataUri = `data:image/svg+xml;base64,${payload.toString('base64')}`;
+    const out = await decodeBase64ToTempFile(dataUri, 'image/svg+xml');
+    try {
+      expect(path.extname(out)).toBe('.svg');
+      const written = await fs.readFile(out);
+      expect(written.equals(payload)).toBe(true);
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+
+  it('rejects a payload larger than the 5MB cap', async () => {
+    const big = Buffer.alloc(MAX_BASE64_BYTES + 1, 0x41);
+    await expect(decodeBase64ToTempFile(big.toString('base64'), 'image/png')).rejects.toThrow(
+      /exceeds the 5MB/
+    );
+  });
+
+  it('rejects an unsupported mimeType', async () => {
+    const payload = Buffer.from('x');
+    await expect(
+      decodeBase64ToTempFile(payload.toString('base64'), 'application/zip')
+    ).rejects.toThrow(/Unsupported mimeType/);
+  });
+
+  it('rejects invalid base64 input', async () => {
+    await expect(decodeBase64ToTempFile('not base64 at all!!!', 'image/png')).rejects.toThrow(
+      /Invalid base64/
+    );
+  });
+
+  it('maps image/jpeg to .jpg extension', async () => {
+    const payload = Buffer.from([0xff, 0xd8, 0xff]);
+    const out = await decodeBase64ToTempFile(payload.toString('base64'), 'image/jpeg');
+    try {
+      expect(path.extname(out)).toBe('.jpg');
+    } finally {
+      await fs.unlink(out).catch(() => {});
+    }
+  });
+});