@magicpages/ghost-typesense-webhook 0.0.0

package/.eslintrc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["dist/**/*"]
+} 

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @magicpages/ghost-typesense-webhook
+
+## 2.0.0
+
+### Major Changes
+
+- 3d371be: Initial release of Ghost Typesense integration packages:
+  - Type-safe configuration and utilities
+  - Core functionality for Ghost-Typesense synchronization
+  - CLI tool for content management
+  - Webhook handler for real-time updates
+
+### Patch Changes
+
+- Updated dependencies [3d371be]
+  - @magicpages/ghost-typesense-config@2.0.0
+  - @magicpages/ghost-typesense-core@2.0.0
+
+## 2.0.0
+
+### Major Changes
+
+- 35c8344: Initial release of Ghost Typesense integration packages:
+
+### Patch Changes
+
+- Updated dependencies [35c8344]
+  - @magicpages/ghost-typesense-config@2.0.0
+  - @magicpages/ghost-typesense-core@2.0.0
+
+## 1.0.0
+
+### Major Changes
+
+- ddd5315: Initial release of the Ghost Typesense integration packages:
+
+  - CLI tool for managing Ghost content in Typesense
+  - Webhook handler for real-time content synchronization
+  - Core functionality for Ghost-Typesense integration
+  - Configuration types and utilities
+
+### Patch Changes
+
+- Updated dependencies [ddd5315]
+  - @magicpages/ghost-typesense-core@1.0.0
+  - @magicpages/ghost-typesense-config@1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# Ghost Typesense Webhook Handler
+
+A production-ready Netlify Function that keeps your [Typesense](https://typesense.org/) search index synchronized with your [Ghost](https://ghost.org/) blog content in real-time. This webhook handler automatically processes content updates from Ghost and reflects them in your Typesense search index.
+
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/magicpages/ghost-typesense)
+
+## Features
+
+The webhook handler provides seamless integration between Ghost and Typesense. It enables real-time content synchronization and automatic handling of post publishing, updates, unpublishing, and deleting. The handler implements type-safe request processing with runtime validation and includes comprehensive error handling and logging capabilities.
+
+## Deployment
+
+### Option 1: One-Click Deploy (Recommended)
+
+1. Click the "Deploy to Netlify" button above
+2. Connect your GitHub account
+3. Configure the required environment variables
+4. Deploy the function
+
+### Option 2: Manual Deployment
+
+1. Clone the repository:
+```bash
+git clone https://github.com/magicpages/ghost-typesense.git
+cd ghost-typesense
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+4. Deploy using the Netlify CLI:
+```bash
+netlify deploy --prod
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure the following environment variables in your Netlify dashboard:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GHOST_URL` | Your Ghost blog URL | `https://blog.example.com` |
+| `GHOST_CONTENT_API_KEY` | Ghost Content API key | `1234abcd...` |
+| `TYPESENSE_HOST` | Typesense server host | `search.example.com` |
+| `TYPESENSE_API_KEY` | Typesense API key (full API access, not search-only) | `xyz789...` |
+| `COLLECTION_NAME` | Typesense collection name | `posts` |
+| `WEBHOOK_SECRET` | A secure random string to validate webhook requests | `your-secret-key` |
+
+### Ghost Integration Setup
+
+1. Access your Ghost Admin panel
+2. Navigate to Settings → Integrations
+3. Click "Add custom integration"
+4. Name your integration (e.g., "Typesense Search")
+5. Copy the Content API Key
+6. Generate a secure random string for your webhook secret:
+   ```bash
+   openssl rand -hex 32
+   ```
+7. Under Webhooks, add the following webhooks:
+
+| Name | Event | Target URL |
+|------|--------|------------|
+| Post published | Post published | `https://your-netlify-site.netlify.app/.netlify/functions/handler?secret=your-secret-key` |
+| Post updated | Post updated | `https://your-netlify-site.netlify.app/.netlify/functions/handler?secret=your-secret-key` |
+| Post unpublished | Post unpublished | `https://your-netlify-site.netlify.app/.netlify/functions/handler?secret=your-secret-key` |
+| Post deleted | Post deleted | `https://your-netlify-site.netlify.app/.netlify/functions/handler?secret=your-secret-key` |
+
+Make sure to replace `your-secret-key` with the same secure random string you set in your Netlify environment variables.
+
+## Local Development
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Create a `.env` file with your configuration:
+```env
+GHOST_URL=https://your-blog.ghost.io
+GHOST_CONTENT_API_KEY=your_content_api_key
+TYPESENSE_HOST=your_typesense_host
+TYPESENSE_API_KEY=your_typesense_api_key
+COLLECTION_NAME=posts
+WEBHOOK_SECRET=your-development-secret
+```
+
+3. Start the development server:
+```bash
+npm run dev
+```
+
+4. Send webhook events to the local server from a local Ghost instance, including your secret:
+   `http://localhost:8888/.netlify/functions/handler?secret=your-development-secret`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.

package/netlify.toml

@@ -0,0 +1,16 @@
+[build]
+  command = "npm run build"
+  functions = "dist"
+  publish = "public"
+
+[functions]
+  node_bundler = "esbuild"
+  included_files = ["dist/**"]
+
+[template.environment]
+  GHOST_URL = "Your Ghost site URL"
+  GHOST_CONTENT_API_KEY = "Your Ghost Content API key"
+  TYPESENSE_HOST = "Your Typesense host"
+  TYPESENSE_API_KEY = "Your Typesense API key"
+  COLLECTION_NAME = "Name of your Typesense collection (default: posts)"
+  WEBHOOK_SECRET = "A secure random string to validate webhook requests" 

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@magicpages/ghost-typesense-webhook",
+  "version": "0.0.0",
+  "description": "Webhook handler for real-time Ghost content synchronization with Typesense",
+  "author": "MagicPages",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magicpages/ghost-typesense.git",
+    "directory": "apps/webhook-handler"
+  },
+  "scripts": {
+    "build": "tsup src/handler.ts --format cjs --dts",
+    "clean": "rimraf dist",
+    "dev": "tsup src/handler.ts --format cjs --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@magicpages/ghost-typesense-config": "*",
+    "@magicpages/ghost-typesense-core": "*",
+    "@netlify/functions": "^2.5.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.17",
+    "tsup": "^8.0.1",
+    "rimraf": "^5.0.5",
+    "vitest": "^1.2.2",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/handler.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import type { HandlerEvent, HandlerResponse } from '@netlify/functions';
+import { handler } from '../handler';
+import { GhostTypesenseManager } from '@magicpages/ghost-typesense-core';
+
+// Mock environment variables
+const mockEnv = {
+  GHOST_URL: 'https://test.com',
+  GHOST_CONTENT_API_KEY: 'test-key',
+  TYPESENSE_HOST: 'localhost',
+  TYPESENSE_API_KEY: 'test-key',
+  COLLECTION_NAME: 'test-collection',
+  WEBHOOK_SECRET: 'test-secret'
+};
+
+Object.entries(mockEnv).forEach(([key, value]) => {
+  vi.stubEnv(key, value);
+});
+
+// Mock the core package
+vi.mock('@magicpages/ghost-typesense-core', () => {
+  const indexPost = vi.fn().mockResolvedValue(undefined);
+  const deletePost = vi.fn().mockResolvedValue(undefined);
+  return {
+    GhostTypesenseManager: vi.fn().mockImplementation(() => ({
+      indexPost,
+      deletePost
+    }))
+  };
+});
+
+describe('Webhook Handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const createEvent = (overrides: Partial<HandlerEvent> = {}): HandlerEvent => ({
+    httpMethod: 'POST',
+    headers: {},
+    multiValueHeaders: {},
+    queryStringParameters: {},
+    multiValueQueryStringParameters: {},
+    path: '/',
+    body: null,
+    rawUrl: '',
+    rawQuery: '',
+    isBase64Encoded: false,
+    ...overrides
+  });
+
+  const parseResponse = (response: HandlerResponse | void): HandlerResponse => {
+    if (!response) {
+      throw new Error('Handler returned void');
+    }
+    return {
+      ...response,
+      body: response.body || ''
+    };
+  };
+
+  const parseResponseBody = <T>(response: HandlerResponse): T => {
+    if (!response.body) {
+      throw new Error('Response body is empty');
+    }
+    return JSON.parse(response.body) as T;
+  };
+
+  const mockContext = {
+    awsRequestId: '123',
+    callbackWaitsForEmptyEventLoop: true,
+    functionName: 'test',
+    functionVersion: '1',
+    invokedFunctionArn: 'test',
+    memoryLimitInMB: '128',
+    logGroupName: 'test',
+    logStreamName: 'test',
+    identity: undefined,
+    clientContext: undefined,
+    getRemainingTimeInMillis: () => 1000,
+    done: () => {},
+    fail: () => {},
+    succeed: () => {}
+  };
+
+  it('should return 401 if no secret provided', async () => {
+    const event = createEvent();
+    const response = parseResponse(await handler(event, mockContext));
+
+    expect(response.statusCode, 'Status code').toBe(401);
+    expect(parseResponseBody<{ error: string }>(response), 'Response body').toStrictEqual({ error: 'Missing webhook secret' });
+  });
+
+  it('should return 401 if invalid secret provided', async () => {
+    const event = createEvent({
+      queryStringParameters: { secret: 'wrong-secret' }
+    });
+
+    const response = parseResponse(await handler(event, mockContext));
+
+    expect(response.statusCode, 'Status code').toBe(401);
+    expect(parseResponseBody<{ error: string }>(response), 'Response body').toStrictEqual({ error: 'Invalid webhook secret' });
+  });
+
+  it('should return 405 for non-POST requests', async () => {
+    const event = createEvent({
+      httpMethod: 'GET',
+      queryStringParameters: { secret: 'test-secret' }
+    });
+
+    const response = parseResponse(await handler(event, mockContext));
+
+    expect(response.statusCode, 'Status code').toBe(405);
+    expect(parseResponseBody<{ error: string }>(response), 'Response body').toStrictEqual({ error: 'Method not allowed' });
+  });
+
+  it('should index post when published', async () => {
+    const event = createEvent({
+      queryStringParameters: { secret: 'test-secret' },
+      body: JSON.stringify({
+        post: {
+          current: {
+            id: 'test-post-1',
+            title: 'Test Post',
+            slug: 'test-post-1',
+            html: '<p>Test content</p>',
+            status: 'published',
+            visibility: 'public',
+            updated_at: '2024-02-09T12:00:00.000Z',
+            published_at: '2024-02-09T12:00:00.000Z',
+            custom_excerpt: 'Test excerpt',
+            feature_image: null
+          }
+        }
+      })
+    });
+
+    const response = parseResponse(await handler(event, mockContext));
+
+    expect(GhostTypesenseManager, 'Manager constructor').toHaveBeenCalledTimes(1);
+    const mockManager = (GhostTypesenseManager as unknown as Mock).mock.results[0]?.value;
+    expect(mockManager.indexPost, 'Index post').toHaveBeenCalledWith('test-post-1');
+    expect(response.statusCode, 'Status code').toBe(200);
+    expect(parseResponseBody<{ message: string }>(response), 'Response body').toStrictEqual({ message: 'Post indexed in Typesense' });
+  });
+
+  it('should delete post when unpublished', async () => {
+    const event = createEvent({
+      queryStringParameters: { secret: 'test-secret' },
+      body: JSON.stringify({
+        post: {
+          current: {
+            id: 'test-post-1',
+            title: 'Test Post',
+            slug: 'test-post-1',
+            html: '<p>Test content</p>',
+            status: 'draft',
+            visibility: 'public',
+            updated_at: '2024-02-09T12:00:00.000Z',
+            published_at: '2024-02-09T12:00:00.000Z',
+            custom_excerpt: 'Test excerpt',
+            feature_image: null
+          }
+        }
+      })
+    });
+
+    const response = parseResponse(await handler(event, mockContext));
+
+    expect(GhostTypesenseManager, 'Manager constructor').toHaveBeenCalledTimes(1);
+    const mockManager = (GhostTypesenseManager as unknown as Mock).mock.results[0]?.value;
+    expect(mockManager.deletePost, 'Delete post').toHaveBeenCalledWith('test-post-1');
+    expect(response.statusCode, 'Status code').toBe(200);
+    expect(parseResponseBody<{ message: string }>(response), 'Response body').toStrictEqual({ message: 'Post removed from Typesense' });
+  });
+}); 

package/src/handler.ts

@@ -0,0 +1,146 @@
+import { Handler } from '@netlify/functions';
+import { z } from 'zod';
+import { createDefaultConfig } from '@magicpages/ghost-typesense-config';
+import { GhostTypesenseManager } from '@magicpages/ghost-typesense-core';
+
+// Validate environment variables
+const EnvSchema = z.object({
+  GHOST_URL: z.string().url(),
+  GHOST_CONTENT_API_KEY: z.string().min(1),
+  TYPESENSE_HOST: z.string().min(1),
+  TYPESENSE_API_KEY: z.string().min(1),
+  COLLECTION_NAME: z.string().min(1).default('posts'),
+  WEBHOOK_SECRET: z.string().min(1)
+});
+
+// Ghost webhook payload schema
+const WebhookSchema = z.object({
+  post: z.object({
+    current: z.object({
+      id: z.string(),
+      title: z.string(),
+      slug: z.string(),
+      html: z.string(),
+      status: z.string(),
+      visibility: z.string(),
+      updated_at: z.string(),
+      published_at: z.string().nullable(),
+      custom_excerpt: z.string().nullable().optional(),
+      feature_image: z.string().nullable().optional(),
+      tags: z.array(z.object({
+        name: z.string()
+      })).optional(),
+      authors: z.array(z.object({
+        name: z.string()
+      })).optional()
+    }).optional(),
+    previous: z.object({
+      updated_at: z.string(),
+      html: z.string().optional(),
+      plaintext: z.string().optional()
+    }).optional()
+  })
+});
+
+const handler: Handler = async (event) => {
+  try {
+    // Log request info
+    console.log('\n🔔 Incoming webhook request');
+    console.log('📝 Method:', event.httpMethod);
+    
+    // Validate environment variables
+    const env = EnvSchema.parse(process.env);
+    console.log('✅ Environment loaded successfully');
+
+    // Validate webhook secret
+    const secret = event.queryStringParameters?.secret;
+    if (!secret) {
+      console.log('❌ No secret provided in request');
+      return {
+        statusCode: 401,
+        body: JSON.stringify({ error: 'Missing webhook secret' })
+      };
+    }
+    
+    if (secret !== env.WEBHOOK_SECRET) {
+      console.log('🚫 Invalid secret provided');
+      return {
+        statusCode: 401,
+        body: JSON.stringify({ error: 'Invalid webhook secret' })
+      };
+    }
+
+    console.log('🔐 Webhook secret validated');
+
+    // Create configuration
+    const config = createDefaultConfig(
+      env.GHOST_URL,
+      env.GHOST_CONTENT_API_KEY,
+      env.TYPESENSE_HOST,
+      env.TYPESENSE_API_KEY,
+      env.COLLECTION_NAME
+    );
+    console.log('⚙️  Configuration loaded');
+
+    // Initialize manager
+    const manager = new GhostTypesenseManager(config);
+    console.log('🔄 Typesense manager initialized');
+
+    // Only process POST requests
+    if (event.httpMethod !== 'POST') {
+      console.log('⚠️  Invalid HTTP method:', event.httpMethod);
+      return {
+        statusCode: 405,
+        body: JSON.stringify({ error: 'Method not allowed' })
+      };
+    }
+
+    // Parse and validate webhook payload
+    if (!event.body) {
+      console.log('❌ No request body provided');
+      throw new Error('No request body');
+    }
+
+    const webhook = WebhookSchema.parse(JSON.parse(event.body));
+    const { post } = webhook;
+    console.log('📦 Webhook payload validated');
+
+    // Handle different webhook events based on post status changes
+    if (post.current) {
+      const { id, status, visibility, title } = post.current;
+      console.log(`📄 Processing post: "${title}" (${id})`);
+      
+      if (status === 'published' && visibility === 'public') {
+        console.log('📝 Indexing published post');
+        await manager.indexPost(id);
+        console.log('✨ Post indexed successfully');
+        return {
+          statusCode: 200,
+          body: JSON.stringify({ message: 'Post indexed in Typesense' })
+        };
+      } else {
+        console.log('🗑️  Removing unpublished/private post');
+        await manager.deletePost(id);
+        console.log('✨ Post removed successfully');
+        return {
+          statusCode: 200,
+          body: JSON.stringify({ message: 'Post removed from Typesense' })
+        };
+      }
+    }
+
+    console.log('ℹ️  No action required');
+    return {
+      statusCode: 200,
+      body: JSON.stringify({ message: 'No action required' })
+    };
+  } catch (error) {
+    console.error('❌ Error processing webhook:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: (error as Error).message })
+    };
+  }
+};
+
+export { handler };