@jgardner04/ghost-mcp-server 1.13.3 → 1.13.5

package/src/services/__tests__/ghostServiceImproved.tags.test.js

@@ -1,48 +1,10 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
 import { mockDotenv } from '../../__tests__/helpers/testUtils.js';
+import { mockGhostApiModule } from '../../__tests__/helpers/mockGhostApi.js';
 
-// Mock the Ghost Admin API with tags support
-vi.mock('@tryghost/admin-api', () => ({
-  default: vi.fn(function () {
-    return {
-      posts: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      pages: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      tags: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      members: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      site: {
-        read: vi.fn(),
-      },
-      images: {
-        upload: vi.fn(),
-      },
-    };
-  }),
-}));
+// Mock the Ghost Admin API using shared mock factory
+vi.mock('@tryghost/admin-api', () => mockGhostApiModule());
 
 // Mock dotenv
 vi.mock('dotenv', () => mockDotenv());
@@ -69,6 +31,7 @@ import {
   api,
   ghostCircuitBreaker,
 } from '../ghostServiceImproved.js';
+import { GhostAPIError, NotFoundError } from '../../errors/index.js';
 
 describe('ghostServiceImproved - Tags', () => {
   beforeEach(() => {
@@ -288,12 +251,12 @@ describe('ghostServiceImproved - Tags', () => {
     });
 
     it('should throw not found error when tag does not exist', async () => {
-      api.tags.read.mockRejectedValue({
-        response: { status: 404 },
-        message: 'Tag not found',
-      });
+      const error404 = new GhostAPIError('tags.read', 'Tag not found', 404);
+      api.tags.read.mockRejectedValue(error404);
 
-      await expect(getTag('non-existent')).rejects.toThrow();
+      const rejection = getTag('non-existent');
+      await expect(rejection).rejects.toBeInstanceOf(NotFoundError);
+      await expect(rejection).rejects.toThrow('Tag not found');
     });
   });
 
@@ -381,10 +344,9 @@ describe('ghostServiceImproved - Tags', () => {
       };
 
       // First call fails with duplicate error
-      api.tags.add.mockRejectedValue({
-        response: { status: 422 },
-        message: 'Tag already exists',
-      });
+      const error422 = new GhostAPIError('tags.add', 'Tag already exists', 422);
+      error422.response = { status: 422, data: { errors: [{ message: 'Tag already exists' }] } };
+      api.tags.add.mockRejectedValue(error422);
 
       // getTags returns existing tag when called with name filter
       api.tags.browse.mockResolvedValue([{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }]);
@@ -443,18 +405,16 @@ describe('ghostServiceImproved - Tags', () => {
     });
 
     it('should throw validation error for missing tag ID', async () => {
-      await expect(updateTag(null, { name: 'Test' })).rejects.toThrow(
-        'Tag ID is required for update'
-      );
+      await expect(updateTag(null, { name: 'Test' })).rejects.toThrow('Tag ID is required');
     });
 
     it('should throw not found error if tag does not exist', async () => {
-      api.tags.read.mockRejectedValue({
-        response: { status: 404 },
-        message: 'Tag not found',
-      });
+      const error404 = new GhostAPIError('tags.read', 'Tag not found', 404);
+      api.tags.read.mockRejectedValue(error404);
 
-      await expect(updateTag('non-existent', { name: 'Test' })).rejects.toThrow();
+      const rejection = updateTag('non-existent', { name: 'Test' });
+      await expect(rejection).rejects.toBeInstanceOf(NotFoundError);
+      await expect(rejection).rejects.toThrow('Tag not found');
     });
   });
 
@@ -471,16 +431,16 @@ describe('ghostServiceImproved - Tags', () => {
     });
 
     it('should throw validation error for missing tag ID', async () => {
-      await expect(deleteTag(null)).rejects.toThrow('Tag ID is required for deletion');
+      await expect(deleteTag(null)).rejects.toThrow('Tag ID is required');
     });
 
     it('should throw not found error if tag does not exist', async () => {
-      api.tags.delete.mockRejectedValue({
-        response: { status: 404 },
-        message: 'Tag not found',
-      });
+      const error404 = new GhostAPIError('tags.delete', 'Tag not found', 404);
+      api.tags.delete.mockRejectedValue(error404);
 
-      await expect(deleteTag('non-existent')).rejects.toThrow();
+      const rejection = deleteTag('non-existent');
+      await expect(rejection).rejects.toBeInstanceOf(NotFoundError);
+      await expect(rejection).rejects.toThrow('Tag not found');
     });
   });
 });

package/src/services/__tests__/ghostServiceImproved.tiers.test.js

@@ -1,55 +1,10 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
 import { mockDotenv } from '../../__tests__/helpers/testUtils.js';
+import { mockGhostApiModule } from '../../__tests__/helpers/mockGhostApi.js';
 
-// Mock the Ghost Admin API with tiers support
-vi.mock('@tryghost/admin-api', () => ({
-  default: vi.fn(function () {
-    return {
-      posts: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      pages: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      tags: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      members: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      tiers: {
-        add: vi.fn(),
-        browse: vi.fn(),
-        read: vi.fn(),
-        edit: vi.fn(),
-        delete: vi.fn(),
-      },
-      site: {
-        read: vi.fn(),
-      },
-      images: {
-        upload: vi.fn(),
-      },
-    };
-  }),
-}));
+// Mock the Ghost Admin API using shared mock factory
+vi.mock('@tryghost/admin-api', () => mockGhostApiModule());
 
 // Mock dotenv
 vi.mock('dotenv', () => mockDotenv());
@@ -340,9 +295,7 @@ describe('ghostServiceImproved - Tiers', () => {
     });
 
     it('should throw ValidationError when ID is missing', async () => {
-      await expect(updateTier('', { name: 'Updated' })).rejects.toThrow(
-        'Tier ID is required for update'
-      );
+      await expect(updateTier('', { name: 'Updated' })).rejects.toThrow('Tier ID is required');
     });
 
     it('should throw ValidationError for invalid update data', async () => {
@@ -372,11 +325,11 @@ describe('ghostServiceImproved - Tiers', () => {
     });
 
     it('should throw ValidationError when ID is missing', async () => {
-      await expect(deleteTier()).rejects.toThrow('Tier ID is required for deletion');
+      await expect(deleteTier()).rejects.toThrow('Tier ID is required');
     });
 
     it('should throw ValidationError when ID is empty string', async () => {
-      await expect(deleteTier('')).rejects.toThrow('Tier ID is required for deletion');
+      await expect(deleteTier('')).rejects.toThrow('Tier ID is required');
     });
 
     it('should throw NotFoundError when tier does not exist', async () => {

package/src/services/createResourceService.js

@@ -0,0 +1,138 @@
+import { GhostAPIError, ValidationError } from '../errors/index.js';
+import { handleApiRequest, readResource, updateWithOCC, deleteResource } from './ghostApiClient.js';
+import { validators } from './validators.js';
+
+/**
+ * Factory that generates standard CRUD service methods for a Ghost CMS resource.
+ *
+ * Each domain (posts, pages, tags, etc.) shares the same structural patterns:
+ * create → validate → API add → 422 mapping
+ * update → requireId → optional validation → OCC edit → optional 422 mapping
+ * remove → deleteResource
+ * getOne → readResource
+ * getList → browse with defaults → empty-array fallback
+ *
+ * Domain-specific behavior is injected via config hooks.
+ *
+ * @param {Object} config - Resource configuration
+ * @param {string} config.resource - Ghost API resource name (e.g., 'posts')
+ * @param {string} config.label - Human-readable label (e.g., 'Post')
+ * @param {Object} [config.listDefaults] - Default options for getList (e.g., { limit: 15, include: 'tags,authors' })
+ * @param {Object} [config.createDefaults] - Default data merged into create payload (e.g., { status: 'draft' })
+ * @param {Object} [config.createOptions] - Default options for create API call (e.g., { source: 'html' })
+ * @param {Function} [config.validateCreate] - Validation function called before create: (data) => void | Promise<void>
+ * @param {Function} [config.validateUpdate] - Validation function called before update: (id, data) => void | Promise<void>
+ * @param {boolean} [config.catch422OnUpdate=false] - Whether to catch 422 errors on update and wrap as ValidationError
+ * @returns {Object} Object with { create, update, remove, getOne, getList } methods
+ *
+ * SECURITY: HTML content must be sanitized before reaching this function.
+ * See htmlContentSchema in schemas/common.js for the validation gate.
+ */
+export function createResourceService(config) {
+  const {
+    resource,
+    label,
+    listDefaults = { limit: 15 },
+    createDefaults = {},
+    createOptions = {},
+    validateCreate,
+    validateUpdate,
+    catch422OnUpdate = false,
+  } = config;
+
+  /**
+   * Creates a new resource.
+   * @param {Object} data - Resource data
+   * @param {Object} [options] - API request options (merged with createOptions)
+   * @returns {Promise<Object>} Created resource
+   */
+  async function create(data, options = {}) {
+    if (validateCreate) {
+      await validateCreate(data);
+    }
+
+    const dataWithDefaults = {
+      ...createDefaults,
+      ...data,
+    };
+
+    const mergedOptions = { ...createOptions, ...options };
+
+    try {
+      return await handleApiRequest(resource, 'add', dataWithDefaults, mergedOptions);
+    } catch (error) {
+      if (error instanceof GhostAPIError && error.ghostStatusCode === 422) {
+        throw new ValidationError(`${label} creation failed due to validation errors`, [
+          { field: label.toLowerCase(), message: error.originalError },
+        ]);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Updates an existing resource with optimistic concurrency control.
+   * @param {string} id - Resource ID
+   * @param {Object} updateData - Fields to update
+   * @param {Object} [options={}] - API request options
+   * @returns {Promise<Object>} Updated resource
+   */
+  async function update(id, updateData, options = {}) {
+    validators.requireId(id, label);
+
+    if (validateUpdate) {
+      await validateUpdate(id, updateData);
+    }
+
+    if (catch422OnUpdate) {
+      try {
+        return await updateWithOCC(resource, id, updateData, options, label);
+      } catch (error) {
+        if (error instanceof GhostAPIError && error.ghostStatusCode === 422) {
+          throw new ValidationError(`${label} update failed`, [
+            { field: label.toLowerCase(), message: error.originalError },
+          ]);
+        }
+        throw error;
+      }
+    }
+
+    return updateWithOCC(resource, id, updateData, options, label);
+  }
+
+  /**
+   * Deletes a resource by ID.
+   * @param {string} id - Resource ID
+   * @returns {Promise<Object>} Deletion confirmation
+   */
+  async function remove(id) {
+    return deleteResource(resource, id, label);
+  }
+
+  /**
+   * Retrieves a single resource by ID.
+   * @param {string} id - Resource ID
+   * @param {Object} [options={}] - API request options
+   * @returns {Promise<Object>} Resource object
+   */
+  async function getOne(id, options = {}) {
+    return readResource(resource, id, label, options);
+  }
+
+  /**
+   * Lists resources with optional filtering and pagination.
+   * @param {Object} [options={}] - Query options
+   * @returns {Promise<Array>} Array of resources (empty array if none found)
+   */
+  async function getList(options = {}) {
+    const mergedOptions = {
+      ...listDefaults,
+      ...options,
+    };
+
+    const result = await handleApiRequest(resource, 'browse', {}, mergedOptions);
+    return result || [];
+  }
+
+  return { create, update, remove, getOne, getList };
+}

package/src/services/ghostApiClient.js

@@ -0,0 +1,240 @@
+import GhostAdminAPI from '@tryghost/admin-api';
+import dotenv from 'dotenv';
+import {
+  GhostAPIError,
+  ConfigurationError,
+  ValidationError,
+  NotFoundError,
+  ErrorHandler,
+  CircuitBreaker,
+  retryWithBackoff,
+} from '../errors/index.js';
+import { createContextLogger } from '../utils/logger.js';
+import { validators } from './validators.js';
+
+dotenv.config();
+
+const logger = createContextLogger('ghost-service-improved');
+
+const { GHOST_ADMIN_API_URL, GHOST_ADMIN_API_KEY } = process.env;
+
+// Validate configuration at startup
+if (!GHOST_ADMIN_API_URL || !GHOST_ADMIN_API_KEY) {
+  throw new ConfigurationError(
+    'Ghost Admin API configuration is incomplete',
+    ['GHOST_ADMIN_API_URL', 'GHOST_ADMIN_API_KEY'].filter((key) => !process.env[key])
+  );
+}
+
+// Configure the Ghost Admin API client
+const api = new GhostAdminAPI({
+  url: GHOST_ADMIN_API_URL,
+  key: GHOST_ADMIN_API_KEY,
+  version: 'v5.0',
+});
+
+// Circuit breaker for Ghost API
+const ghostCircuitBreaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 60000, // 1 minute
+  monitoringPeriod: 10000, // 10 seconds
+});
+
+/**
+ * Enhanced handler for Ghost Admin API requests with circuit breaker and retry logic.
+ * Routes requests to the appropriate Ghost API method based on the action type.
+ * @param {string} resource - Ghost API resource name (e.g., 'posts', 'pages', 'tags')
+ * @param {string} action - API action to perform ('add', 'edit', 'upload', 'browse', 'read', 'delete')
+ * @param {Object} [data={}] - Request payload data
+ * @param {Object} [options={}] - Additional options passed to the Ghost API (e.g., filters, includes)
+ * @param {Object} [config={}] - Execution configuration
+ * @param {number} [config.maxRetries=3] - Maximum number of retry attempts
+ * @param {boolean} [config.useCircuitBreaker=true] - Whether to use the circuit breaker
+ * @returns {Promise<Object>} The Ghost API response
+ * @throws {ValidationError} If the resource or action is invalid
+ * @throws {GhostAPIError} If the Ghost API returns an error after all retries
+ */
+const handleApiRequest = async (resource, action, data = {}, options = {}, config = {}) => {
+  // Validate inputs
+  if (!api[resource] || typeof api[resource][action] !== 'function') {
+    throw new ValidationError(`Invalid Ghost API resource or action: ${resource}.${action}`);
+  }
+
+  const operation = `${resource}.${action}`;
+  const maxRetries = config.maxRetries ?? 3;
+  const useCircuitBreaker = config.useCircuitBreaker ?? true;
+
+  // Main execution function
+  const executeRequest = async () => {
+    try {
+      logger.info('Executing Ghost API request', { operation });
+
+      let result;
+
+      // Handle different action signatures
+      switch (action) {
+        case 'add':
+        case 'edit':
+          result = await api[resource][action](data, options);
+          break;
+        case 'upload':
+          result = await api[resource][action](data);
+          break;
+        case 'browse':
+        case 'read':
+          result = await api[resource][action](options, data);
+          break;
+        case 'delete':
+          result = await api[resource][action](data.id || data, options);
+          break;
+        default:
+          result = await api[resource][action](data);
+      }
+
+      logger.info('Successfully executed Ghost API request', { operation });
+      return result;
+    } catch (error) {
+      // Transform Ghost API errors into our error types
+      throw ErrorHandler.fromGhostError(error, operation);
+    }
+  };
+
+  // Wrap with circuit breaker if enabled
+  const wrappedExecute = useCircuitBreaker
+    ? () => ghostCircuitBreaker.execute(executeRequest)
+    : executeRequest;
+
+  // Execute with retry logic
+  try {
+    return await retryWithBackoff(wrappedExecute, {
+      maxAttempts: maxRetries,
+      onRetry: (attempt, _error) => {
+        logger.info('Retrying Ghost API request', { operation, attempt, maxRetries });
+
+        // Log circuit breaker state if relevant
+        if (useCircuitBreaker) {
+          const state = ghostCircuitBreaker.getState();
+          logger.info('Circuit breaker state', { operation, state });
+        }
+      },
+    });
+  } catch (error) {
+    logger.error('Failed to execute Ghost API request', {
+      operation,
+      maxRetries,
+      error: error.message,
+    });
+    throw error;
+  }
+};
+
+/**
+ * Reads a single resource by ID with 404-to-NotFoundError handling.
+ * @param {string} resource - Ghost API resource name (e.g., 'posts', 'tags')
+ * @param {string} id - The resource ID to read
+ * @param {string} label - Human-readable resource label for error messages
+ * @param {Object} [options={}] - Additional options passed to the Ghost API
+ * @returns {Promise<Object>} The resource object from Ghost
+ * @throws {ValidationError} If the ID is missing or invalid
+ * @throws {NotFoundError} If the resource is not found (404)
+ * @throws {GhostAPIError} If the API request fails for other reasons
+ */
+async function readResource(resource, id, label, options = {}) {
+  validators.requireId(id, label);
+  try {
+    return await handleApiRequest(resource, 'read', { id }, options);
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError(label, id);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Updates a resource using optimistic concurrency control (OCC).
+ * Reads the current version first to obtain updated_at, then merges it into the edit payload.
+ * @param {string} resource - Ghost API resource name (e.g., 'posts', 'tags')
+ * @param {string} id - The resource ID to update
+ * @param {Object} updateData - Fields to update on the resource
+ * @param {Object} [options={}] - Additional options passed to the Ghost API
+ * @param {string} [label=resource] - Human-readable resource label for error messages
+ * @returns {Promise<Object>} The updated resource object from Ghost
+ * @throws {ValidationError} If the ID is missing or invalid
+ * @throws {NotFoundError} If the resource is not found (404)
+ * @throws {GhostAPIError} If the API request fails for other reasons
+ */
+async function updateWithOCC(resource, id, updateData, options = {}, label = resource) {
+  const existing = await readResource(resource, id, label);
+  const editData = { ...updateData, updated_at: existing.updated_at };
+  try {
+    return await handleApiRequest(resource, 'edit', { id, ...editData }, options);
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError(label, id);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Deletes a resource by ID with 404-to-NotFoundError handling.
+ * @param {string} resource - Ghost API resource name (e.g., 'posts', 'tags')
+ * @param {string} id - The resource ID to delete
+ * @param {string} label - Human-readable resource label for error messages
+ * @returns {Promise<Object>} The Ghost API deletion response
+ * @throws {ValidationError} If the ID is missing or invalid
+ * @throws {NotFoundError} If the resource is not found (404)
+ * @throws {GhostAPIError} If the API request fails for other reasons
+ */
+async function deleteResource(resource, id, label) {
+  validators.requireId(id, label);
+  try {
+    return await handleApiRequest(resource, 'delete', { id });
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError(label, id);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Retrieves Ghost site metadata (title, version, URL).
+ * @returns {Promise<Object>} Site information object
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function getSiteInfo() {
+  return handleApiRequest('site', 'read');
+}
+
+/**
+ * Checks the health of the Ghost API connection and circuit breaker state.
+ * @returns {Promise<Object>} Health status with site info, circuit breaker state, and timestamp
+ */
+export async function checkHealth() {
+  try {
+    const site = await getSiteInfo();
+    const circuitState = ghostCircuitBreaker.getState();
+
+    return {
+      status: 'healthy',
+      site: {
+        title: site.title,
+        version: site.version,
+        url: site.url,
+      },
+      circuitBreaker: circuitState,
+      timestamp: new Date().toISOString(),
+    };
+  } catch (error) {
+    return {
+      status: 'unhealthy',
+      error: error.message,
+      circuitBreaker: ghostCircuitBreaker.getState(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+
+export { api, ghostCircuitBreaker, handleApiRequest, readResource, updateWithOCC, deleteResource };