@jgardner04/ghost-mcp-server 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgardner04/ghost-mcp-server",
-  "version": "1.9.0",
+  "version": "1.10.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

@@ -1019,6 +1019,125 @@ server.tool(
   }
 );
 
+// Get Members Tool
+server.tool(
+  'ghost_get_members',
+  'Retrieves a list of members (subscribers) from Ghost CMS with optional filtering, pagination, and includes.',
+  {
+    limit: z
+      .number()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe('Number of members to retrieve (1-100). Default is 15.'),
+    page: z.number().min(1).optional().describe('Page number for pagination (starts at 1).'),
+    filter: z
+      .string()
+      .optional()
+      .describe('Ghost NQL filter string (e.g., "status:free", "status:paid", "subscribed:true").'),
+    order: z.string().optional().describe('Order string (e.g., "created_at desc", "email asc").'),
+    include: z
+      .string()
+      .optional()
+      .describe('Comma-separated list of related data to include (e.g., "labels,newsletters").'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_get_members`);
+    try {
+      await loadServices();
+
+      const options = {};
+      if (input.limit !== undefined) options.limit = input.limit;
+      if (input.page !== undefined) options.page = input.page;
+      if (input.filter !== undefined) options.filter = input.filter;
+      if (input.order !== undefined) options.order = input.order;
+      if (input.include !== undefined) options.include = input.include;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const members = await ghostServiceImproved.getMembers(options);
+      console.error(`Retrieved ${members.length} members from Ghost.`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(members, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_members:`, error);
+      return {
+        content: [{ type: 'text', text: `Error retrieving members: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Get Member Tool
+server.tool(
+  'ghost_get_member',
+  'Retrieves a single member from Ghost CMS by ID or email. Provide either id OR email.',
+  {
+    id: z.string().optional().describe('The ID of the member to retrieve.'),
+    email: z.string().email().optional().describe('The email of the member to retrieve.'),
+  },
+  async ({ id, email }) => {
+    console.error(`Executing tool: ghost_get_member for ${id ? `ID: ${id}` : `email: ${email}`}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const member = await ghostServiceImproved.getMember({ id, email });
+      console.error(`Retrieved member: ${member.email} (ID: ${member.id})`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(member, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_member:`, error);
+      return {
+        content: [{ type: 'text', text: `Error retrieving member: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Search Members Tool
+server.tool(
+  'ghost_search_members',
+  'Searches for members by name or email in Ghost CMS.',
+  {
+    query: z.string().min(1).describe('Search query to match against member name or email.'),
+    limit: z
+      .number()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Maximum number of results to return (1-50). Default is 15.'),
+  },
+  async ({ query, limit }) => {
+    console.error(`Executing tool: ghost_search_members with query: ${query}`);
+    try {
+      await loadServices();
+
+      const options = {};
+      if (limit !== undefined) options.limit = limit;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const members = await ghostServiceImproved.searchMembers(query, options);
+      console.error(`Found ${members.length} members matching "${query}".`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(members, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_search_members:`, error);
+      return {
+        content: [{ type: 'text', text: `Error searching members: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
 // =============================================================================
 // NEWSLETTER TOOLS
 // =============================================================================
@@ -1224,7 +1343,7 @@ async function main() {
     'Available tools: ghost_get_tags, ghost_create_tag, ghost_get_tag, ghost_update_tag, ghost_delete_tag, ghost_upload_image, ' +
       '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_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'
   );
 }

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

@@ -60,7 +60,15 @@ vi.mock('fs/promises', () => ({
 }));
 
 // Import after setting up mocks
-import { createMember, updateMember, deleteMember, api } from '../ghostServiceImproved.js';
+import {
+  createMember,
+  updateMember,
+  deleteMember,
+  getMembers,
+  getMember,
+  searchMembers,
+  api,
+} from '../ghostServiceImproved.js';
 
 describe('ghostServiceImproved - Members', () => {
   beforeEach(() => {
@@ -258,4 +266,283 @@ describe('ghostServiceImproved - Members', () => {
       await expect(deleteMember('non-existent')).rejects.toThrow();
     });
   });
+
+  describe('getMembers', () => {
+    it('should return all members with default options', async () => {
+      const mockMembers = [
+        { id: 'member-1', email: 'test1@example.com', status: 'free' },
+        { id: 'member-2', email: 'test2@example.com', status: 'paid' },
+      ];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      const result = await getMembers();
+
+      expect(api.members.browse).toHaveBeenCalled();
+      expect(result).toEqual(mockMembers);
+    });
+
+    it('should accept pagination options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ limit: 50, page: 2 });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 50,
+          page: 2,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept filter options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com', status: 'paid' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ filter: 'status:paid' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: 'status:paid',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept order options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ order: 'created_at desc' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          order: 'created_at desc',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept include options', async () => {
+      const mockMembers = [
+        { id: 'member-1', email: 'test1@example.com', labels: [], newsletters: [] },
+      ];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ include: 'labels,newsletters' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          include: 'labels,newsletters',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should throw validation error for invalid limit', async () => {
+      await expect(getMembers({ limit: 0 })).rejects.toThrow('Member query validation failed');
+      await expect(getMembers({ limit: 101 })).rejects.toThrow('Member query validation failed');
+    });
+
+    it('should throw validation error for invalid page', async () => {
+      await expect(getMembers({ page: 0 })).rejects.toThrow('Member query validation failed');
+    });
+
+    it('should return empty array when no members found', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      const result = await getMembers();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle Ghost API errors', async () => {
+      api.members.browse.mockRejectedValue(new Error('Ghost API Error'));
+
+      await expect(getMembers()).rejects.toThrow();
+    });
+  });
+
+  describe('getMember', () => {
+    it('should get member by ID', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        name: 'John Doe',
+        status: 'free',
+      };
+
+      api.members.read.mockResolvedValue(mockMember);
+
+      const result = await getMember({ id: 'member-1' });
+
+      expect(api.members.read).toHaveBeenCalledWith(expect.any(Object), { id: 'member-1' });
+      expect(result).toEqual(mockMember);
+    });
+
+    it('should get member by email', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        name: 'John Doe',
+        status: 'free',
+      };
+
+      api.members.browse.mockResolvedValue([mockMember]);
+
+      const result = await getMember({ email: 'test@example.com' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: expect.stringContaining('test@example.com'),
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockMember);
+    });
+
+    it('should throw validation error when neither id nor email provided', async () => {
+      await expect(getMember({})).rejects.toThrow('Member lookup validation failed');
+    });
+
+    it('should throw validation error for invalid email format', async () => {
+      await expect(getMember({ email: 'invalid-email' })).rejects.toThrow(
+        'Member lookup validation failed'
+      );
+    });
+
+    it('should throw not found error when member not found by ID', async () => {
+      api.members.read.mockRejectedValue({
+        response: { status: 404 },
+        message: 'Member not found',
+      });
+
+      await expect(getMember({ id: 'non-existent' })).rejects.toThrow();
+    });
+
+    it('should throw not found error when member not found by email', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      await expect(getMember({ email: 'notfound@example.com' })).rejects.toThrow(
+        'Member not found'
+      );
+    });
+
+    it('should prioritize ID over email when both provided', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        status: 'free',
+      };
+
+      api.members.read.mockResolvedValue(mockMember);
+
+      await getMember({ id: 'member-1', email: 'test@example.com' });
+
+      // Should use read (ID) instead of browse (email)
+      expect(api.members.read).toHaveBeenCalled();
+      expect(api.members.browse).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('searchMembers', () => {
+    it('should search members by query', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'john@example.com', name: 'John Doe' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      const result = await searchMembers('john');
+
+      expect(api.members.browse).toHaveBeenCalled();
+      expect(result).toEqual(mockMembers);
+    });
+
+    it('should apply default limit of 15', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await searchMembers('test');
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept custom limit', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await searchMembers('test', { limit: 25 });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 25,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should throw validation error for empty query', async () => {
+      await expect(searchMembers('')).rejects.toThrow('Search query validation failed');
+      await expect(searchMembers('   ')).rejects.toThrow('Search query validation failed');
+    });
+
+    it('should throw validation error for non-string query', async () => {
+      await expect(searchMembers(123)).rejects.toThrow('Search query validation failed');
+      await expect(searchMembers(null)).rejects.toThrow('Search query validation failed');
+    });
+
+    it('should throw validation error for invalid limit', async () => {
+      await expect(searchMembers('test', { limit: 0 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+      await expect(searchMembers('test', { limit: 51 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+      await expect(searchMembers('test', { limit: 100 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+    });
+
+    it('should sanitize query to prevent NQL injection', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      // Query with special NQL characters
+      await searchMembers("test'value");
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: expect.stringContaining("\\'"),
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should return empty array when no matches found', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      const result = await searchMembers('nonexistent');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle Ghost API errors', async () => {
+      api.members.browse.mockRejectedValue(new Error('Ghost API Error'));
+
+      await expect(searchMembers('test')).rejects.toThrow();
+    });
+  });
 });

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

@@ -1,5 +1,13 @@
 import { describe, it, expect } from 'vitest';
-import { validateMemberData, validateMemberUpdateData } from '../memberService.js';
+import {
+  validateMemberData,
+  validateMemberUpdateData,
+  validateMemberQueryOptions,
+  validateMemberLookup,
+  validateSearchQuery,
+  validateSearchOptions,
+  sanitizeNqlValue,
+} from '../memberService.js';
 
 describe('memberService - Validation', () => {
   describe('validateMemberData', () => {
@@ -242,4 +250,228 @@ describe('memberService - Validation', () => {
       );
     });
   });
+
+  describe('validateMemberQueryOptions', () => {
+    it('should accept empty options', () => {
+      expect(() => validateMemberQueryOptions({})).not.toThrow();
+    });
+
+    it('should accept valid limit within bounds', () => {
+      expect(() => validateMemberQueryOptions({ limit: 1 })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ limit: 50 })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ limit: 100 })).not.toThrow();
+    });
+
+    it('should reject limit below minimum', () => {
+      expect(() => validateMemberQueryOptions({ limit: 0 })).toThrow(
+        'Member query validation failed'
+      );
+      expect(() => validateMemberQueryOptions({ limit: -1 })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should reject limit above maximum', () => {
+      expect(() => validateMemberQueryOptions({ limit: 101 })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should accept valid page number', () => {
+      expect(() => validateMemberQueryOptions({ page: 1 })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ page: 100 })).not.toThrow();
+    });
+
+    it('should reject page below minimum', () => {
+      expect(() => validateMemberQueryOptions({ page: 0 })).toThrow(
+        'Member query validation failed'
+      );
+      expect(() => validateMemberQueryOptions({ page: -1 })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should accept valid filter strings', () => {
+      expect(() => validateMemberQueryOptions({ filter: 'status:free' })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ filter: 'status:paid' })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ filter: 'subscribed:true' })).not.toThrow();
+    });
+
+    it('should reject empty filter string', () => {
+      expect(() => validateMemberQueryOptions({ filter: '' })).toThrow(
+        'Member query validation failed'
+      );
+      expect(() => validateMemberQueryOptions({ filter: '   ' })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should accept valid order strings', () => {
+      expect(() => validateMemberQueryOptions({ order: 'created_at desc' })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ order: 'email asc' })).not.toThrow();
+    });
+
+    it('should reject empty order string', () => {
+      expect(() => validateMemberQueryOptions({ order: '' })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should accept valid include strings', () => {
+      expect(() => validateMemberQueryOptions({ include: 'labels' })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ include: 'newsletters' })).not.toThrow();
+      expect(() => validateMemberQueryOptions({ include: 'labels,newsletters' })).not.toThrow();
+    });
+
+    it('should reject empty include string', () => {
+      expect(() => validateMemberQueryOptions({ include: '' })).toThrow(
+        'Member query validation failed'
+      );
+    });
+
+    it('should validate multiple options together', () => {
+      expect(() =>
+        validateMemberQueryOptions({
+          limit: 50,
+          page: 2,
+          filter: 'status:paid',
+          order: 'created_at desc',
+          include: 'labels,newsletters',
+        })
+      ).not.toThrow();
+    });
+  });
+
+  describe('validateMemberLookup', () => {
+    it('should accept valid id', () => {
+      expect(() => validateMemberLookup({ id: '12345' })).not.toThrow();
+    });
+
+    it('should accept valid email', () => {
+      expect(() => validateMemberLookup({ email: 'test@example.com' })).not.toThrow();
+    });
+
+    it('should reject when both id and email are missing', () => {
+      expect(() => validateMemberLookup({})).toThrow('Member lookup validation failed');
+    });
+
+    it('should reject empty id', () => {
+      expect(() => validateMemberLookup({ id: '' })).toThrow('Member lookup validation failed');
+      expect(() => validateMemberLookup({ id: '   ' })).toThrow('Member lookup validation failed');
+    });
+
+    it('should reject invalid email format', () => {
+      expect(() => validateMemberLookup({ email: 'invalid-email' })).toThrow(
+        'Member lookup validation failed'
+      );
+      expect(() => validateMemberLookup({ email: 'test@' })).toThrow(
+        'Member lookup validation failed'
+      );
+    });
+
+    it('should accept when both id and email provided (id takes precedence)', () => {
+      expect(() => validateMemberLookup({ id: '12345', email: 'test@example.com' })).not.toThrow();
+    });
+
+    it('should return normalized params with lookupType', () => {
+      const resultId = validateMemberLookup({ id: '12345' });
+      expect(resultId).toEqual({ id: '12345', lookupType: 'id' });
+
+      const resultEmail = validateMemberLookup({ email: 'test@example.com' });
+      expect(resultEmail).toEqual({ email: 'test@example.com', lookupType: 'email' });
+
+      // ID takes precedence when both provided
+      const resultBoth = validateMemberLookup({ id: '12345', email: 'test@example.com' });
+      expect(resultBoth).toEqual({ id: '12345', lookupType: 'id' });
+    });
+  });
+
+  describe('validateSearchQuery', () => {
+    it('should accept valid search query', () => {
+      expect(() => validateSearchQuery('john')).not.toThrow();
+      expect(() => validateSearchQuery('john@example.com')).not.toThrow();
+    });
+
+    it('should reject empty search query', () => {
+      expect(() => validateSearchQuery('')).toThrow('Search query validation failed');
+      expect(() => validateSearchQuery('   ')).toThrow('Search query validation failed');
+    });
+
+    it('should reject non-string search query', () => {
+      expect(() => validateSearchQuery(123)).toThrow('Search query validation failed');
+      expect(() => validateSearchQuery(null)).toThrow('Search query validation failed');
+      expect(() => validateSearchQuery(undefined)).toThrow('Search query validation failed');
+    });
+
+    it('should return sanitized query', () => {
+      const result = validateSearchQuery('john');
+      expect(result).toBe('john');
+    });
+
+    it('should trim whitespace from query', () => {
+      const result = validateSearchQuery('  john  ');
+      expect(result).toBe('john');
+    });
+  });
+
+  describe('validateSearchOptions', () => {
+    it('should accept empty options', () => {
+      expect(() => validateSearchOptions({})).not.toThrow();
+    });
+
+    it('should accept valid limit within bounds (1-50)', () => {
+      expect(() => validateSearchOptions({ limit: 1 })).not.toThrow();
+      expect(() => validateSearchOptions({ limit: 25 })).not.toThrow();
+      expect(() => validateSearchOptions({ limit: 50 })).not.toThrow();
+    });
+
+    it('should reject limit below minimum', () => {
+      expect(() => validateSearchOptions({ limit: 0 })).toThrow('Search options validation failed');
+      expect(() => validateSearchOptions({ limit: -1 })).toThrow(
+        'Search options validation failed'
+      );
+    });
+
+    it('should reject limit above maximum (50)', () => {
+      expect(() => validateSearchOptions({ limit: 51 })).toThrow(
+        'Search options validation failed'
+      );
+      expect(() => validateSearchOptions({ limit: 100 })).toThrow(
+        'Search options validation failed'
+      );
+    });
+
+    it('should reject non-number limit', () => {
+      expect(() => validateSearchOptions({ limit: 'ten' })).toThrow(
+        'Search options validation failed'
+      );
+    });
+  });
+
+  describe('sanitizeNqlValue', () => {
+    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 handle multiple special characters', () => {
+      expect(sanitizeNqlValue('test\'value"with\\chars')).toBe('test\\\'value\\"with\\\\chars');
+    });
+
+    it('should not modify strings without special characters', () => {
+      expect(sanitizeNqlValue('normalvalue')).toBe('normalvalue');
+      expect(sanitizeNqlValue('test@example.com')).toBe('test@example.com');
+    });
+
+    it('should handle empty string', () => {
+      expect(sanitizeNqlValue('')).toBe('');
+    });
+  });
 });

package/src/services/ghostServiceImproved.js

@@ -876,6 +876,111 @@ export async function deleteMember(memberId) {
   }
 }
 
+/**
+ * List members from Ghost CMS with optional filtering and pagination
+ * @param {Object} [options] - Query options
+ * @param {number} [options.limit] - Number of members to return (1-100)
+ * @param {number} [options.page] - Page number (1+)
+ * @param {string} [options.filter] - NQL filter string (e.g., 'status:paid')
+ * @param {string} [options.order] - Order string (e.g., 'created_at desc')
+ * @param {string} [options.include] - Include string (e.g., 'labels,newsletters')
+ * @returns {Promise<Array>} Array of member objects
+ * @throws {ValidationError} If validation fails
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function getMembers(options = {}) {
+  // Import and validate query options
+  const { validateMemberQueryOptions } = await import('./memberService.js');
+  validateMemberQueryOptions(options);
+
+  const defaultOptions = {
+    limit: 15,
+    ...options,
+  };
+
+  try {
+    const members = await handleApiRequest('members', 'browse', {}, defaultOptions);
+    return members || [];
+  } catch (error) {
+    console.error('Failed to get members:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get a single member from Ghost CMS by ID or email
+ * @param {Object} params - Lookup parameters (id OR email required)
+ * @param {string} [params.id] - Member ID
+ * @param {string} [params.email] - Member email
+ * @returns {Promise<Object>} The member object
+ * @throws {ValidationError} If validation fails
+ * @throws {NotFoundError} If the member is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function getMember(params) {
+  // Import and validate lookup parameters
+  const { validateMemberLookup, sanitizeNqlValue } = await import('./memberService.js');
+  const { lookupType, id, email } = validateMemberLookup(params);
+
+  try {
+    if (lookupType === 'id') {
+      // Lookup by ID using read endpoint
+      return await handleApiRequest('members', 'read', { id }, { id });
+    } else {
+      // Lookup by email using browse with filter
+      const sanitizedEmail = sanitizeNqlValue(email);
+      const members = await handleApiRequest(
+        'members',
+        'browse',
+        {},
+        { filter: `email:'${sanitizedEmail}'`, limit: 1 }
+      );
+
+      if (!members || members.length === 0) {
+        throw new NotFoundError('Member', email);
+      }
+
+      return members[0];
+    }
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError('Member', id || email);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Search members by name or email
+ * @param {string} query - Search query (searches name and email fields)
+ * @param {Object} [options] - Additional options
+ * @param {number} [options.limit] - Maximum number of results (default: 15)
+ * @returns {Promise<Array>} Array of matching member objects
+ * @throws {ValidationError} If validation fails
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function searchMembers(query, options = {}) {
+  // Import and validate search query and options
+  const { validateSearchQuery, validateSearchOptions, sanitizeNqlValue } =
+    await import('./memberService.js');
+  validateSearchOptions(options);
+  const sanitizedQuery = sanitizeNqlValue(validateSearchQuery(query));
+
+  const limit = options.limit || 15;
+
+  // Build NQL filter for name or email containing the query
+  // Ghost uses ~ for contains/like matching
+  const filter = `name:~'${sanitizedQuery}',email:~'${sanitizedQuery}'`;
+
+  try {
+    const members = await handleApiRequest('members', 'browse', {}, { filter, limit });
+    return members || [];
+  } catch (error) {
+    console.error('Failed to search members:', error);
+    throw error;
+  }
+}
+
 /**
  * Newsletter CRUD Operations
  */
@@ -1027,6 +1132,9 @@ export default {
   createMember,
   updateMember,
   deleteMember,
+  getMembers,
+  getMember,
+  searchMembers,
   getNewsletters,
   getNewsletter,
   createNewsletter,

package/src/services/memberService.js

@@ -14,6 +14,14 @@ const MAX_NAME_LENGTH = 191; // Ghost's typical varchar limit
 const MAX_NOTE_LENGTH = 2000; // Reasonable limit for notes
 const MAX_LABEL_LENGTH = 191; // Label name limit
 
+/**
+ * Query constraints for member browsing
+ */
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 100;
+const MAX_SEARCH_LIMIT = 50; // Lower limit for search operations
+const MIN_PAGE = 1;
+
 /**
  * Validates member data for creation
  * @param {Object} memberData - The member data to validate
@@ -196,7 +204,189 @@ export function validateMemberUpdateData(updateData) {
   }
 }
 
+/**
+ * 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, '\\"');
+}
+
+/**
+ * Validates query options for member browsing
+ * @param {Object} options - The query options to validate
+ * @param {number} [options.limit] - Number of members 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., 'labels,newsletters')
+ * @throws {ValidationError} If validation fails
+ */
+export function validateMemberQueryOptions(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('Member query validation failed', errors);
+  }
+}
+
+/**
+ * Validates member lookup parameters (id OR email required)
+ * @param {Object} params - The lookup parameters
+ * @param {string} [params.id] - Member ID
+ * @param {string} [params.email] - Member email
+ * @returns {Object} Normalized params with lookupType ('id' or 'email')
+ * @throws {ValidationError} If validation fails
+ */
+export function validateMemberLookup(params) {
+  const errors = [];
+
+  // Check if id is provided and valid
+  const hasValidId = params.id && typeof params.id === 'string' && params.id.trim().length > 0;
+
+  // Check if email is provided and valid
+  const hasEmail = params.email !== undefined;
+  const hasValidEmail =
+    hasEmail && typeof params.email === 'string' && EMAIL_REGEX.test(params.email);
+
+  // Must have at least one valid identifier
+  if (!hasValidId && !hasValidEmail) {
+    if (params.id !== undefined && !hasValidId) {
+      errors.push({ field: 'id', message: 'ID must be a non-empty string' });
+    }
+    if (hasEmail && !hasValidEmail) {
+      errors.push({ field: 'email', message: 'Invalid email format' });
+    }
+    if (!params.id && !params.email) {
+      errors.push({ field: 'id|email', message: 'Either id or email is required' });
+    }
+
+    throw new ValidationError('Member lookup validation failed', errors);
+  }
+
+  // Return normalized result - ID takes precedence if both provided
+  if (hasValidId) {
+    return { id: params.id, lookupType: 'id' };
+  }
+  return { email: params.email, lookupType: 'email' };
+}
+
+/**
+ * Validates and sanitizes a search query
+ * @param {string} query - The search query
+ * @returns {string} The sanitized query
+ * @throws {ValidationError} If validation fails
+ */
+export function validateSearchQuery(query) {
+  const errors = [];
+
+  if (query === null || query === undefined || typeof query !== 'string') {
+    errors.push({ field: 'query', message: 'Query must be a string' });
+    throw new ValidationError('Search query validation failed', errors);
+  }
+
+  const trimmedQuery = query.trim();
+  if (trimmedQuery.length === 0) {
+    errors.push({ field: 'query', message: 'Query must not be empty' });
+    throw new ValidationError('Search query validation failed', errors);
+  }
+
+  return trimmedQuery;
+}
+
+/**
+ * Validates search options (specifically limit for search operations)
+ * Search has a lower max limit (50) than browse operations (100)
+ * @param {Object} options - The search options to validate
+ * @param {number} [options.limit] - Maximum number of results (1-50)
+ * @throws {ValidationError} If validation fails
+ */
+export function validateSearchOptions(options) {
+  const errors = [];
+
+  // Validate limit for search (1-50, lower than browse)
+  if (options.limit !== undefined) {
+    if (
+      typeof options.limit !== 'number' ||
+      options.limit < MIN_LIMIT ||
+      options.limit > MAX_SEARCH_LIMIT
+    ) {
+      errors.push({
+        field: 'limit',
+        message: `Limit must be a number between ${MIN_LIMIT} and ${MAX_SEARCH_LIMIT}`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError('Search options validation failed', errors);
+  }
+}
+
 export default {
   validateMemberData,
   validateMemberUpdateData,
+  validateMemberQueryOptions,
+  validateMemberLookup,
+  validateSearchQuery,
+  validateSearchOptions,
+  sanitizeNqlValue,
 };