@jgardner04/ghost-mcp-server 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgardner04/ghost-mcp-server",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "A Model Context Protocol (MCP) server for interacting with Ghost CMS via the Admin API",
   "author": "Jonathan Gardner",
   "type": "module",

package/src/mcp_server_improved.js

@@ -1330,6 +1330,184 @@ server.tool(
   }
 );
 
+// --- Tier Tools ---
+
+// Get Tiers Tool
+server.tool(
+  'ghost_get_tiers',
+  'Retrieves a list of tiers (membership levels) from Ghost CMS with optional filtering by type (free/paid).',
+  {
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe('Number of tiers to return (1-100, default 15)'),
+    filter: z.string().optional().describe('NQL filter string (e.g., "type:paid" or "type:free")'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_get_tiers`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tiers = await ghostServiceImproved.getTiers(input);
+      console.error(`Retrieved ${tiers.length} tiers`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tiers, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_tiers:`, error);
+      return {
+        content: [{ type: 'text', text: `Error getting tiers: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Get Tier Tool
+server.tool(
+  'ghost_get_tier',
+  'Retrieves a single tier (membership level) from Ghost CMS by ID.',
+  {
+    id: z.string().describe('The ID of the tier to retrieve.'),
+  },
+  async ({ id }) => {
+    console.error(`Executing tool: ghost_get_tier for tier ID: ${id}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tier = await ghostServiceImproved.getTier(id);
+      console.error(`Tier retrieved successfully. Tier ID: ${tier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error getting tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Create Tier Tool
+server.tool(
+  'ghost_create_tier',
+  'Creates a new tier (membership level) in Ghost CMS with pricing and benefits.',
+  {
+    name: z.string().describe('Tier name (required)'),
+    description: z.string().optional().describe('Tier description'),
+    monthly_price: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Monthly price in cents (e.g., 500 = $5.00)'),
+    yearly_price: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Yearly price in cents (e.g., 5000 = $50.00)'),
+    currency: z.string().length(3).optional().describe('Currency code (e.g., "USD", "EUR")'),
+    benefits: z.array(z.string()).optional().describe('Array of benefit descriptions'),
+    welcome_page_url: z.string().url().optional().describe('Welcome page URL for new subscribers'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_create_tier`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tier = await ghostServiceImproved.createTier(input);
+      console.error(`Tier created successfully. Tier ID: ${tier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_create_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error creating tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Update Tier Tool
+server.tool(
+  'ghost_update_tier',
+  'Updates an existing tier (membership level) in Ghost CMS. Can update pricing, benefits, and other tier properties.',
+  {
+    id: z.string().describe('The ID of the tier to update (required)'),
+    name: z.string().optional().describe('Updated tier name'),
+    description: z.string().optional().describe('Updated description'),
+    monthly_price: z.number().int().min(0).optional().describe('Updated monthly price in cents'),
+    yearly_price: z.number().int().min(0).optional().describe('Updated yearly price in cents'),
+    currency: z.string().length(3).optional().describe('Updated currency code'),
+    benefits: z.array(z.string()).optional().describe('Updated array of benefit descriptions'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_update_tier for tier ID: ${input.id}`);
+    try {
+      await loadServices();
+
+      const { id, ...updateData } = input;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const updatedTier = await ghostServiceImproved.updateTier(id, updateData);
+      console.error(`Tier updated successfully. Tier ID: ${updatedTier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(updatedTier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_update_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error updating tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Delete Tier Tool
+server.tool(
+  'ghost_delete_tier',
+  'Deletes a tier (membership level) from Ghost CMS by ID. This operation is permanent and cannot be undone.',
+  {
+    id: z.string().describe('The ID of the tier to delete.'),
+  },
+  async ({ id }) => {
+    console.error(`Executing tool: ghost_delete_tier for tier ID: ${id}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      await ghostServiceImproved.deleteTier(id);
+      console.error(`Tier deleted successfully. Tier ID: ${id}`);
+
+      return {
+        content: [{ type: 'text', text: `Tier ${id} has been successfully deleted.` }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_delete_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error deleting tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
 // --- Main Entry Point ---
 
 async function main() {
@@ -1344,7 +1522,8 @@ async function main() {
       'ghost_create_post, ghost_get_posts, ghost_get_post, ghost_search_posts, ghost_update_post, ghost_delete_post, ' +
       'ghost_get_pages, ghost_get_page, ghost_create_page, ghost_update_page, ghost_delete_page, ghost_search_pages, ' +
       'ghost_create_member, ghost_update_member, ghost_delete_member, ghost_get_members, ghost_get_member, ghost_search_members, ' +
-      'ghost_get_newsletters, ghost_get_newsletter, ghost_create_newsletter, ghost_update_newsletter, ghost_delete_newsletter'
+      'ghost_get_newsletters, ghost_get_newsletter, ghost_create_newsletter, ghost_update_newsletter, ghost_delete_newsletter, ' +
+      'ghost_get_tiers, ghost_get_tier, ghost_create_tier, ghost_update_tier, ghost_delete_tier'
   );
 }
 

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

@@ -0,0 +1,392 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
+import { mockDotenv } from '../../__tests__/helpers/testUtils.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 dotenv
+vi.mock('dotenv', () => mockDotenv());
+
+// Mock logger
+vi.mock('../../utils/logger.js', () => ({
+  createContextLogger: createMockContextLogger(),
+}));
+
+// Mock fs for validateImagePath
+vi.mock('fs/promises', () => ({
+  default: {
+    access: vi.fn(),
+  },
+}));
+
+// Import after setting up mocks
+import {
+  createTier,
+  updateTier,
+  deleteTier,
+  getTiers,
+  getTier,
+  api,
+} from '../ghostServiceImproved.js';
+
+describe('ghostServiceImproved - Tiers', () => {
+  beforeEach(() => {
+    // Reset all mocks before each test
+    vi.clearAllMocks();
+  });
+
+  describe('createTier', () => {
+    it('should create a tier with required fields', async () => {
+      const tierData = {
+        name: 'Premium',
+        currency: 'USD',
+      };
+
+      const mockCreatedTier = {
+        id: 'tier-1',
+        name: 'Premium',
+        currency: 'USD',
+        type: 'paid',
+        active: true,
+      };
+
+      api.tiers.add.mockResolvedValue(mockCreatedTier);
+
+      const result = await createTier(tierData);
+
+      expect(api.tiers.add).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'Premium',
+          currency: 'USD',
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockCreatedTier);
+    });
+
+    it('should create a tier with all optional fields', async () => {
+      const tierData = {
+        name: 'Premium Membership',
+        currency: 'USD',
+        description: 'Access to premium content',
+        monthly_price: 999,
+        yearly_price: 9999,
+        benefits: ['Ad-free experience', 'Exclusive content'],
+        welcome_page_url: 'https://example.com/welcome',
+      };
+
+      const mockCreatedTier = {
+        id: 'tier-2',
+        ...tierData,
+        type: 'paid',
+        active: true,
+      };
+
+      api.tiers.add.mockResolvedValue(mockCreatedTier);
+
+      const result = await createTier(tierData);
+
+      expect(api.tiers.add).toHaveBeenCalledWith(
+        expect.objectContaining(tierData),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockCreatedTier);
+    });
+
+    it('should throw ValidationError when name is missing', async () => {
+      await expect(
+        createTier({
+          currency: 'USD',
+        })
+      ).rejects.toThrow('Tier validation failed');
+    });
+
+    it('should throw ValidationError when currency is missing', async () => {
+      await expect(
+        createTier({
+          name: 'Premium',
+        })
+      ).rejects.toThrow('Tier validation failed');
+    });
+
+    it('should throw ValidationError when currency is invalid', async () => {
+      await expect(
+        createTier({
+          name: 'Premium',
+          currency: 'us',
+        })
+      ).rejects.toThrow('Tier validation failed');
+    });
+  });
+
+  describe('getTiers', () => {
+    it('should get all tiers with default options', async () => {
+      const mockTiers = [
+        {
+          id: 'tier-1',
+          name: 'Free',
+          type: 'free',
+          active: true,
+        },
+        {
+          id: 'tier-2',
+          name: 'Premium',
+          type: 'paid',
+          active: true,
+        },
+      ];
+
+      api.tiers.browse.mockResolvedValue(mockTiers);
+
+      const result = await getTiers();
+
+      expect(api.tiers.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockTiers);
+    });
+
+    it('should get tiers with custom limit', async () => {
+      const mockTiers = [
+        {
+          id: 'tier-1',
+          name: 'Free',
+          type: 'free',
+          active: true,
+        },
+      ];
+
+      api.tiers.browse.mockResolvedValue(mockTiers);
+
+      const result = await getTiers({ limit: 5 });
+
+      expect(api.tiers.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 5,
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockTiers);
+    });
+
+    it('should get tiers with filter', async () => {
+      const mockTiers = [
+        {
+          id: 'tier-2',
+          name: 'Premium',
+          type: 'paid',
+          active: true,
+        },
+      ];
+
+      api.tiers.browse.mockResolvedValue(mockTiers);
+
+      const result = await getTiers({ filter: 'type:paid' });
+
+      expect(api.tiers.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: 'type:paid',
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockTiers);
+    });
+
+    it('should return empty array when no tiers found', async () => {
+      api.tiers.browse.mockResolvedValue([]);
+
+      const result = await getTiers();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should throw ValidationError for invalid limit', async () => {
+      await expect(getTiers({ limit: 0 })).rejects.toThrow('Tier query validation failed');
+      await expect(getTiers({ limit: 101 })).rejects.toThrow('Tier query validation failed');
+    });
+  });
+
+  describe('getTier', () => {
+    it('should get a single tier by ID', async () => {
+      const mockTier = {
+        id: 'tier-1',
+        name: 'Premium',
+        currency: 'USD',
+        type: 'paid',
+        active: true,
+      };
+
+      api.tiers.read.mockResolvedValue(mockTier);
+
+      const result = await getTier('tier-1');
+
+      expect(api.tiers.read).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: 'tier-1',
+        }),
+        expect.objectContaining({
+          id: 'tier-1',
+        })
+      );
+      expect(result).toEqual(mockTier);
+    });
+
+    it('should throw ValidationError when ID is missing', async () => {
+      await expect(getTier()).rejects.toThrow('Tier ID is required');
+    });
+
+    it('should throw ValidationError when ID is empty string', async () => {
+      await expect(getTier('')).rejects.toThrow('Tier ID is required');
+    });
+
+    it('should throw NotFoundError when tier does not exist', async () => {
+      const mockError = new Error('Tier not found');
+      mockError.response = { status: 404 };
+
+      api.tiers.read.mockRejectedValue(mockError);
+
+      await expect(getTier('nonexistent-id')).rejects.toThrow();
+    });
+  });
+
+  describe('updateTier', () => {
+    it('should update a tier', async () => {
+      const existingTier = {
+        id: 'tier-1',
+        name: 'Premium',
+        currency: 'USD',
+        monthly_price: 999,
+        updated_at: '2024-01-01T00:00:00.000Z',
+      };
+
+      const updateData = {
+        name: 'Premium Plus',
+        monthly_price: 1299,
+      };
+
+      const mockUpdatedTier = {
+        ...existingTier,
+        ...updateData,
+      };
+
+      api.tiers.read.mockResolvedValue(existingTier);
+      api.tiers.edit.mockResolvedValue(mockUpdatedTier);
+
+      const result = await updateTier('tier-1', updateData);
+
+      expect(api.tiers.read).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 'tier-1' }),
+        expect.objectContaining({ id: 'tier-1' })
+      );
+      expect(api.tiers.edit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          ...existingTier,
+          ...updateData,
+        }),
+        expect.objectContaining({
+          id: 'tier-1',
+        })
+      );
+      expect(result).toEqual(mockUpdatedTier);
+    });
+
+    it('should throw ValidationError when ID is missing', async () => {
+      await expect(updateTier('', { name: 'Updated' })).rejects.toThrow(
+        'Tier ID is required for update'
+      );
+    });
+
+    it('should throw ValidationError for invalid update data', async () => {
+      await expect(updateTier('tier-1', { monthly_price: -100 })).rejects.toThrow(
+        'Tier validation failed'
+      );
+    });
+
+    it('should throw NotFoundError when tier does not exist', async () => {
+      const mockError = new Error('Tier not found');
+      mockError.response = { status: 404 };
+
+      api.tiers.read.mockRejectedValue(mockError);
+
+      await expect(updateTier('nonexistent-id', { name: 'Updated' })).rejects.toThrow();
+    });
+  });
+
+  describe('deleteTier', () => {
+    it('should delete a tier', async () => {
+      api.tiers.delete.mockResolvedValue({ success: true });
+
+      const result = await deleteTier('tier-1');
+
+      expect(api.tiers.delete).toHaveBeenCalledWith('tier-1', expect.any(Object));
+      expect(result).toEqual({ success: true });
+    });
+
+    it('should throw ValidationError when ID is missing', async () => {
+      await expect(deleteTier()).rejects.toThrow('Tier ID is required for deletion');
+    });
+
+    it('should throw ValidationError when ID is empty string', async () => {
+      await expect(deleteTier('')).rejects.toThrow('Tier ID is required for deletion');
+    });
+
+    it('should throw NotFoundError when tier does not exist', async () => {
+      const mockError = new Error('Tier not found');
+      mockError.response = { status: 404 };
+
+      api.tiers.delete.mockRejectedValue(mockError);
+
+      await expect(deleteTier('nonexistent-id')).rejects.toThrow();
+    });
+  });
+});

package/src/services/__tests__/tierService.test.js

@@ -0,0 +1,372 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateTierData,
+  validateTierUpdateData,
+  validateTierQueryOptions,
+  sanitizeNqlValue,
+} from '../tierService.js';
+import { ValidationError } from '../../errors/index.js';
+
+describe('tierService - Validation', () => {
+  describe('validateTierData', () => {
+    it('should validate required name field', () => {
+      expect(() => validateTierData({})).toThrow(ValidationError);
+      expect(() => validateTierData({})).toThrow('Tier validation failed');
+    });
+
+    it('should validate required currency field', () => {
+      expect(() => validateTierData({ name: 'Premium' })).toThrow(ValidationError);
+      expect(() => validateTierData({ name: 'Premium' })).toThrow('Tier validation failed');
+    });
+
+    it('should accept valid tier data with name and currency', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+        })
+      ).not.toThrow();
+    });
+
+    it('should validate name is a non-empty string', () => {
+      expect(() =>
+        validateTierData({
+          name: '',
+          currency: 'USD',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate name does not exceed max length', () => {
+      const longName = 'a'.repeat(192);
+      expect(() =>
+        validateTierData({
+          name: longName,
+          currency: 'USD',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate currency is a 3-letter uppercase code', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'us',
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USDD',
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: '123',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate description does not exceed max length', () => {
+      const longDescription = 'a'.repeat(2001);
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          description: longDescription,
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate monthly_price is a non-negative number', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          monthly_price: -100,
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          monthly_price: 'invalid',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate yearly_price is a non-negative number', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          yearly_price: -1000,
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          yearly_price: 'invalid',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate benefits is an array of strings', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          benefits: 'not an array',
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          benefits: [123, 456],
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          benefits: ['Benefit 1', ''],
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate welcome_page_url is a valid URL', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          welcome_page_url: 'not-a-url',
+        })
+      ).toThrow('Tier validation failed');
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          welcome_page_url: 'ftp://example.com',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should accept valid welcome_page_url', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          welcome_page_url: 'https://example.com/welcome',
+        })
+      ).not.toThrow();
+
+      expect(() =>
+        validateTierData({
+          name: 'Premium',
+          currency: 'USD',
+          welcome_page_url: 'http://example.com/welcome',
+        })
+      ).not.toThrow();
+    });
+
+    it('should accept complete valid tier data', () => {
+      expect(() =>
+        validateTierData({
+          name: 'Premium Membership',
+          description: 'Access to premium content',
+          currency: 'USD',
+          monthly_price: 999,
+          yearly_price: 9999,
+          benefits: ['Ad-free experience', 'Exclusive content', 'Priority support'],
+          welcome_page_url: 'https://example.com/welcome',
+        })
+      ).not.toThrow();
+    });
+  });
+
+  describe('validateTierUpdateData', () => {
+    it('should accept empty update data', () => {
+      expect(() => validateTierUpdateData({})).not.toThrow();
+    });
+
+    it('should validate name if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          name: '',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate currency if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          currency: 'us',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate description length if provided', () => {
+      const longDescription = 'a'.repeat(2001);
+      expect(() =>
+        validateTierUpdateData({
+          description: longDescription,
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate monthly_price if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          monthly_price: -100,
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate yearly_price if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          yearly_price: -1000,
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate benefits if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          benefits: 'not an array',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should validate welcome_page_url if provided', () => {
+      expect(() =>
+        validateTierUpdateData({
+          welcome_page_url: 'not-a-url',
+        })
+      ).toThrow('Tier validation failed');
+    });
+
+    it('should accept valid update data', () => {
+      expect(() =>
+        validateTierUpdateData({
+          name: 'Updated Premium',
+          monthly_price: 1299,
+          benefits: ['New benefit'],
+        })
+      ).not.toThrow();
+    });
+  });
+
+  describe('validateTierQueryOptions', () => {
+    it('should accept empty options', () => {
+      expect(() => validateTierQueryOptions({})).not.toThrow();
+    });
+
+    it('should validate limit is within range', () => {
+      expect(() => validateTierQueryOptions({ limit: 0 })).toThrow('Tier query validation failed');
+
+      expect(() => validateTierQueryOptions({ limit: 101 })).toThrow(
+        'Tier query validation failed'
+      );
+
+      expect(() => validateTierQueryOptions({ limit: 50 })).not.toThrow();
+    });
+
+    it('should validate limit is a number', () => {
+      expect(() => validateTierQueryOptions({ limit: 'invalid' })).toThrow(
+        'Tier query validation failed'
+      );
+    });
+
+    it('should validate page is >= 1', () => {
+      expect(() => validateTierQueryOptions({ page: 0 })).toThrow('Tier query validation failed');
+
+      expect(() => validateTierQueryOptions({ page: -1 })).toThrow('Tier query validation failed');
+
+      expect(() => validateTierQueryOptions({ page: 1 })).not.toThrow();
+    });
+
+    it('should validate page is a number', () => {
+      expect(() => validateTierQueryOptions({ page: 'invalid' })).toThrow(
+        'Tier query validation failed'
+      );
+    });
+
+    it('should validate filter is a non-empty string', () => {
+      expect(() => validateTierQueryOptions({ filter: '' })).toThrow(
+        'Tier query validation failed'
+      );
+
+      expect(() => validateTierQueryOptions({ filter: '   ' })).toThrow(
+        'Tier query validation failed'
+      );
+
+      expect(() => validateTierQueryOptions({ filter: 'type:paid' })).not.toThrow();
+    });
+
+    it('should validate order is a non-empty string', () => {
+      expect(() => validateTierQueryOptions({ order: '' })).toThrow('Tier query validation failed');
+
+      expect(() => validateTierQueryOptions({ order: 'created_at desc' })).not.toThrow();
+    });
+
+    it('should validate include is a non-empty string', () => {
+      expect(() => validateTierQueryOptions({ include: '' })).toThrow(
+        'Tier query validation failed'
+      );
+
+      expect(() =>
+        validateTierQueryOptions({ include: 'monthly_price,yearly_price' })
+      ).not.toThrow();
+    });
+
+    it('should accept valid query options', () => {
+      expect(() =>
+        validateTierQueryOptions({
+          limit: 50,
+          page: 2,
+          filter: 'type:paid',
+          order: 'created_at desc',
+          include: 'monthly_price,yearly_price',
+        })
+      ).not.toThrow();
+    });
+  });
+
+  describe('sanitizeNqlValue', () => {
+    it('should return value if undefined or null', () => {
+      expect(sanitizeNqlValue(null)).toBe(null);
+      expect(sanitizeNqlValue(undefined)).toBe(undefined);
+    });
+
+    it('should escape backslashes', () => {
+      expect(sanitizeNqlValue('test\\value')).toBe('test\\\\value');
+    });
+
+    it('should escape single quotes', () => {
+      expect(sanitizeNqlValue("test'value")).toBe("test\\'value");
+    });
+
+    it('should escape double quotes', () => {
+      expect(sanitizeNqlValue('test"value')).toBe('test\\"value');
+    });
+
+    it('should escape multiple special characters', () => {
+      expect(sanitizeNqlValue('test\\value"with\'quotes')).toBe('test\\\\value\\"with\\\'quotes');
+    });
+
+    it('should handle strings without special characters', () => {
+      expect(sanitizeNqlValue('simple-value')).toBe('simple-value');
+    });
+  });
+});

package/src/services/ghostServiceImproved.js

@@ -1078,6 +1078,131 @@ export async function deleteNewsletter(newsletterId) {
   }
 }
 
+/**
+ * Create a new tier (membership level)
+ * @param {Object} tierData - Tier data
+ * @param {Object} [options={}] - Options for the API request
+ * @returns {Promise<Object>} Created tier
+ */
+export async function createTier(tierData, options = {}) {
+  const { validateTierData } = await import('./tierService.js');
+  validateTierData(tierData);
+
+  try {
+    return await handleApiRequest('tiers', 'add', tierData, options);
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 422) {
+      throw new ValidationError('Tier creation failed due to validation errors', [
+        { field: 'tier', message: error.originalError },
+      ]);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Update an existing tier
+ * @param {string} id - Tier ID
+ * @param {Object} updateData - Tier update data
+ * @param {Object} [options={}] - Options for the API request
+ * @returns {Promise<Object>} Updated tier
+ */
+export async function updateTier(id, updateData, options = {}) {
+  if (!id || typeof id !== 'string' || id.trim().length === 0) {
+    throw new ValidationError('Tier ID is required for update');
+  }
+
+  const { validateTierUpdateData } = await import('./tierService.js');
+  validateTierUpdateData(updateData);
+
+  try {
+    // Get existing tier for merge
+    const existingTier = await handleApiRequest('tiers', 'read', { id }, { id });
+
+    // Merge updates with existing data
+    const mergedData = {
+      ...existingTier,
+      ...updateData,
+      updated_at: existingTier.updated_at,
+    };
+
+    return await handleApiRequest('tiers', 'edit', mergedData, { id, ...options });
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError('Tier', id);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Delete a tier
+ * @param {string} id - Tier ID
+ * @returns {Promise<Object>} Deletion result
+ */
+export async function deleteTier(id) {
+  if (!id || typeof id !== 'string' || id.trim().length === 0) {
+    throw new ValidationError('Tier ID is required for deletion');
+  }
+
+  try {
+    return await handleApiRequest('tiers', 'delete', { id });
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError('Tier', id);
+    }
+    throw error;
+  }
+}
+
+/**
+ * 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
+ */
+export async function getTiers(options = {}) {
+  const { validateTierQueryOptions } = await import('./tierService.js');
+  validateTierQueryOptions(options);
+
+  const defaultOptions = {
+    limit: 15,
+    ...options,
+  };
+
+  try {
+    const tiers = await handleApiRequest('tiers', 'browse', {}, defaultOptions);
+    return tiers || [];
+  } catch (error) {
+    console.error('Failed to get tiers:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get a single tier by ID
+ * @param {string} id - Tier ID
+ * @returns {Promise<Object>} Tier object
+ */
+export async function getTier(id) {
+  if (!id || typeof id !== 'string' || id.trim().length === 0) {
+    throw new ValidationError('Tier ID is required and must be a non-empty string');
+  }
+
+  try {
+    return await handleApiRequest('tiers', 'read', { id }, { id });
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError('Tier', id);
+    }
+    throw error;
+  }
+}
+
 /**
  * Health check for Ghost API connection
  */
@@ -1140,5 +1265,10 @@ export default {
   createNewsletter,
   updateNewsletter,
   deleteNewsletter,
+  createTier,
+  updateTier,
+  deleteTier,
+  getTiers,
+  getTier,
   checkHealth,
 };

package/src/services/tierService.js

@@ -0,0 +1,304 @@
+import { ValidationError } from '../errors/index.js';
+
+/**
+ * Maximum length constants (following Ghost's database constraints)
+ */
+const MAX_NAME_LENGTH = 191; // Ghost's typical varchar limit
+const MAX_DESCRIPTION_LENGTH = 2000; // Reasonable limit for descriptions
+
+/**
+ * Query constraints for tier browsing
+ */
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 100;
+const MIN_PAGE = 1;
+
+/**
+ * Currency code validation regex (3-letter uppercase)
+ */
+const CURRENCY_REGEX = /^[A-Z]{3}$/;
+
+/**
+ * URL validation regex (simple HTTP/HTTPS validation)
+ */
+const URL_REGEX = /^https?:\/\/.+/i;
+
+/**
+ * Validates tier data for creation
+ * @param {Object} tierData - The tier data to validate
+ * @throws {ValidationError} If validation fails
+ */
+export function validateTierData(tierData) {
+  const errors = [];
+
+  // Name is required and must be a non-empty string
+  if (!tierData.name || typeof tierData.name !== 'string' || tierData.name.trim().length === 0) {
+    errors.push({ field: 'name', message: 'Name is required and must be a non-empty string' });
+  } else if (tierData.name.length > MAX_NAME_LENGTH) {
+    errors.push({ field: 'name', message: `Name must not exceed ${MAX_NAME_LENGTH} characters` });
+  }
+
+  // Currency is required and must be a 3-letter uppercase code
+  if (!tierData.currency || typeof tierData.currency !== 'string') {
+    errors.push({ field: 'currency', message: 'Currency is required' });
+  } else if (!CURRENCY_REGEX.test(tierData.currency)) {
+    errors.push({
+      field: 'currency',
+      message: 'Currency must be a 3-letter uppercase code (e.g., USD, EUR)',
+    });
+  }
+
+  // Description is optional but must be a string with valid length if provided
+  if (tierData.description !== undefined) {
+    if (typeof tierData.description !== 'string') {
+      errors.push({ field: 'description', message: 'Description must be a string' });
+    } else if (tierData.description.length > MAX_DESCRIPTION_LENGTH) {
+      errors.push({
+        field: 'description',
+        message: `Description must not exceed ${MAX_DESCRIPTION_LENGTH} characters`,
+      });
+    }
+  }
+
+  // Monthly price is optional but must be a non-negative number if provided
+  if (tierData.monthly_price !== undefined) {
+    if (typeof tierData.monthly_price !== 'number' || tierData.monthly_price < 0) {
+      errors.push({
+        field: 'monthly_price',
+        message: 'Monthly price must be a non-negative number',
+      });
+    }
+  }
+
+  // Yearly price is optional but must be a non-negative number if provided
+  if (tierData.yearly_price !== undefined) {
+    if (typeof tierData.yearly_price !== 'number' || tierData.yearly_price < 0) {
+      errors.push({
+        field: 'yearly_price',
+        message: 'Yearly price must be a non-negative number',
+      });
+    }
+  }
+
+  // Benefits is optional but must be an array of non-empty strings if provided
+  if (tierData.benefits !== undefined) {
+    if (!Array.isArray(tierData.benefits)) {
+      errors.push({ field: 'benefits', message: 'Benefits must be an array' });
+    } else {
+      // Validate each benefit is a non-empty string
+      const invalidBenefits = tierData.benefits.filter(
+        (benefit) => typeof benefit !== 'string' || benefit.trim().length === 0
+      );
+      if (invalidBenefits.length > 0) {
+        errors.push({
+          field: 'benefits',
+          message: 'Each benefit must be a non-empty string',
+        });
+      }
+    }
+  }
+
+  // Welcome page URL is optional but must be a valid HTTP/HTTPS URL if provided
+  if (tierData.welcome_page_url !== undefined) {
+    if (
+      typeof tierData.welcome_page_url !== 'string' ||
+      !URL_REGEX.test(tierData.welcome_page_url)
+    ) {
+      errors.push({
+        field: 'welcome_page_url',
+        message: 'Welcome page URL must be a valid URL',
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError('Tier validation failed', errors);
+  }
+}
+
+/**
+ * Validates tier data for update
+ * All fields are optional for updates, but if provided they must be valid
+ * @param {Object} updateData - The tier update data to validate
+ * @throws {ValidationError} If validation fails
+ */
+export function validateTierUpdateData(updateData) {
+  const errors = [];
+
+  // Name is optional for update but must be a non-empty string with valid length if provided
+  if (updateData.name !== undefined) {
+    if (typeof updateData.name !== 'string' || updateData.name.trim().length === 0) {
+      errors.push({ field: 'name', message: 'Name must be a non-empty string' });
+    } else if (updateData.name.length > MAX_NAME_LENGTH) {
+      errors.push({ field: 'name', message: `Name must not exceed ${MAX_NAME_LENGTH} characters` });
+    }
+  }
+
+  // Currency is optional for update but must be a 3-letter uppercase code if provided
+  if (updateData.currency !== undefined) {
+    if (typeof updateData.currency !== 'string' || !CURRENCY_REGEX.test(updateData.currency)) {
+      errors.push({
+        field: 'currency',
+        message: 'Currency must be a 3-letter uppercase code (e.g., USD, EUR)',
+      });
+    }
+  }
+
+  // Description is optional but must be a string with valid length if provided
+  if (updateData.description !== undefined) {
+    if (typeof updateData.description !== 'string') {
+      errors.push({ field: 'description', message: 'Description must be a string' });
+    } else if (updateData.description.length > MAX_DESCRIPTION_LENGTH) {
+      errors.push({
+        field: 'description',
+        message: `Description must not exceed ${MAX_DESCRIPTION_LENGTH} characters`,
+      });
+    }
+  }
+
+  // Monthly price is optional but must be a non-negative number if provided
+  if (updateData.monthly_price !== undefined) {
+    if (typeof updateData.monthly_price !== 'number' || updateData.monthly_price < 0) {
+      errors.push({
+        field: 'monthly_price',
+        message: 'Monthly price must be a non-negative number',
+      });
+    }
+  }
+
+  // Yearly price is optional but must be a non-negative number if provided
+  if (updateData.yearly_price !== undefined) {
+    if (typeof updateData.yearly_price !== 'number' || updateData.yearly_price < 0) {
+      errors.push({
+        field: 'yearly_price',
+        message: 'Yearly price must be a non-negative number',
+      });
+    }
+  }
+
+  // Benefits is optional but must be an array of non-empty strings if provided
+  if (updateData.benefits !== undefined) {
+    if (!Array.isArray(updateData.benefits)) {
+      errors.push({ field: 'benefits', message: 'Benefits must be an array' });
+    } else {
+      // Validate each benefit is a non-empty string
+      const invalidBenefits = updateData.benefits.filter(
+        (benefit) => typeof benefit !== 'string' || benefit.trim().length === 0
+      );
+      if (invalidBenefits.length > 0) {
+        errors.push({
+          field: 'benefits',
+          message: 'Each benefit must be a non-empty string',
+        });
+      }
+    }
+  }
+
+  // Welcome page URL is optional but must be a valid HTTP/HTTPS URL if provided
+  if (updateData.welcome_page_url !== undefined) {
+    if (
+      typeof updateData.welcome_page_url !== 'string' ||
+      !URL_REGEX.test(updateData.welcome_page_url)
+    ) {
+      errors.push({
+        field: 'welcome_page_url',
+        message: 'Welcome page URL must be a valid URL',
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError('Tier validation failed', errors);
+  }
+}
+
+/**
+ * Validates query options for tier browsing
+ * @param {Object} options - The query options to validate
+ * @param {number} [options.limit] - Number of tiers to return (1-100)
+ * @param {number} [options.page] - Page number (1+)
+ * @param {string} [options.filter] - NQL filter string
+ * @param {string} [options.order] - Order string (e.g., 'created_at desc')
+ * @param {string} [options.include] - Include string (e.g., 'monthly_price,yearly_price')
+ * @throws {ValidationError} If validation fails
+ */
+export function validateTierQueryOptions(options) {
+  const errors = [];
+
+  // Validate limit
+  if (options.limit !== undefined) {
+    if (
+      typeof options.limit !== 'number' ||
+      options.limit < MIN_LIMIT ||
+      options.limit > MAX_LIMIT
+    ) {
+      errors.push({
+        field: 'limit',
+        message: `Limit must be a number between ${MIN_LIMIT} and ${MAX_LIMIT}`,
+      });
+    }
+  }
+
+  // Validate page
+  if (options.page !== undefined) {
+    if (typeof options.page !== 'number' || options.page < MIN_PAGE) {
+      errors.push({
+        field: 'page',
+        message: `Page must be a number >= ${MIN_PAGE}`,
+      });
+    }
+  }
+
+  // Validate filter (must be non-empty string if provided)
+  if (options.filter !== undefined) {
+    if (typeof options.filter !== 'string' || options.filter.trim().length === 0) {
+      errors.push({
+        field: 'filter',
+        message: 'Filter must be a non-empty string',
+      });
+    }
+  }
+
+  // Validate order (must be non-empty string if provided)
+  if (options.order !== undefined) {
+    if (typeof options.order !== 'string' || options.order.trim().length === 0) {
+      errors.push({
+        field: 'order',
+        message: 'Order must be a non-empty string',
+      });
+    }
+  }
+
+  // Validate include (must be non-empty string if provided)
+  if (options.include !== undefined) {
+    if (typeof options.include !== 'string' || options.include.trim().length === 0) {
+      errors.push({
+        field: 'include',
+        message: 'Include must be a non-empty string',
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError('Tier query validation failed', errors);
+  }
+}
+
+/**
+ * Sanitizes a value for use in NQL filters to prevent injection
+ * Escapes backslashes, single quotes, and double quotes
+ * @param {string} value - The value to sanitize
+ * @returns {string} The sanitized value
+ */
+export function sanitizeNqlValue(value) {
+  if (!value) return value;
+  // Escape backslashes first, then quotes
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/"/g, '\\"');
+}
+
+export default {
+  validateTierData,
+  validateTierUpdateData,
+  validateTierQueryOptions,
+  sanitizeNqlValue,
+};