@tryghost/algolia-netlify 0.3.3 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013-2023 Ghost Foundation
+Copyright (c) 2013-2025 Ghost Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,94 +1,95 @@
 # Algolia Netlify
 
-[Netlify Functions](https://www.netlify.com/products/functions/) to listen to [Ghost Webhooks](https://ghost.org/docs/api/webhooks/) on post changes and update defined [Algolia](https://www.algolia.com/) search index.
+`@tryghost/algolia-netlify` provides Netlify Functions that listen to Ghost post webhooks and update an Algolia search index.
 
-## Usage
-
-### Set up Algolia
+The public package exports the native Request/Response handlers from its root and from explicit subpaths:
 
-First step is to grab the API keys and Application ID from Algolia. For the setup we need both, the "Search-Only API Key" as well as the "Admin API Key".
+```js
+import {postPublished, postUnpublished} from '@tryghost/algolia-netlify';
+import publishedHandler from '@tryghost/algolia-netlify/post-published';
+import unpublishedHandler from '@tryghost/algolia-netlify/post-unpublished';
+```
 
-The Admin API Key can either be the general one, or can be created just for this specific search index.
+The named and subpath exports reference the same handlers. Consumers can wrap either subpath in a basename-preserving Netlify Function entry; this repository deploys the canonical `post-published` and `post-unpublished` entries directly.
 
-If you decide to create a new API key, you want to make sure that the generated key has the following authorizations on your index:
+## Security
 
-- Search (`search`)
-- Add records (`addObject`)
-- Delete records (`deleteObject`)
-- List indexes (`listIndexes`)
-- Delete index (`deleteIndex`)
+> [!WARNING]
+> The current handlers do not enforce authentication when the `key` query parameter is omitted; they reject only a supplied key that does not match `NETLIFY_KEY`. Netlify Function URLs are public endpoints, not secrets, and the user-agent check can be spoofed. Pause or restrict exposure outside the handlers until mandatory authentication is implemented before public use.
 
-### Set up Netlify Functions
+Use a restricted Algolia API key to limit the impact of unauthorized requests.
 
-The Ghost Algolia tooling uses [Ghost Webhooks](https://ghost.org/docs/api/webhooks/) to index and update posts. The scripts that receive and process the webhooks are hosted by [Netlify Functions](https://www.netlify.com/products/functions/):
+## Usage
 
-1. Deploy to Netlify by clicking on this button:
-   [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/TryGhost/algolia)
-2. Click 'Connect to Github' and give Netlify permission
-3. Configure your site
-    - Choose a repository name
-    - Set 'TRUE' to trigger indexing
-    - Algolia Application ID
-    - The Algolia Admin API key or and API key with the permissions as described above
-    - The name of the index you want to use
-    - Set the `NETLIFY_KEY` to be used with the target URL
+### Set up Algolia
 
-### Set up Ghost Webhooks
+The functions need the Algolia Application ID and an API key that can update the target index. The general Admin API key works, but a key scoped to this index is preferable. A scoped key needs these permissions:
 
-Ghost webhooks will initiate posts to be indexed to Algolia. This can be a new entry, an update, or a removal. On Ghost's admin panel, create a new **Custom Integration** (Ghost Admin → Settings → Integrations → Custom Integrations) and the following **webhooks**:
+- Add records (`addObject`)
+- Delete records matching a filter (`deleteIndex`)
+- Get index settings (`settings`)
+- Set index settings (`editSettings`)
 
-1. `post.published`
-   - Name: Post published
-   - Event: Post published
-   - Target URL: the endpoint of the post-published function, found on Netlify's admin panel plus the `NETLIFY_KEY` as a query parameter as defined in the configuration data above (https://YOUR-SITE-ID.netlify.com/.netlify/functions/post-published?key=NETLIFY_KEY)
+### Deploy the Netlify Functions
 
-2. `post.published.edited`
-   - Name: Post updated
-   - Event: Published post updated
-   - Target URL: the endpoint of the post-published function, found on Netlify's admin panel plus the `NETLIFY_KEY` as a query parameter as defined in the configuration data above (https://YOUR-SITE-ID.netlify.com/.netlify/functions/post-published?key=NETLIFY_KEY)
+Deploy manually, and do not expose the deployed functions publicly until mandatory authentication is implemented or access is restricted outside the handlers:
 
-3. `post.unpublished`
-   - Name: Post unpublished
-   - Event: Post unpublished
-   - Target URL: the endpoint of the post-published function, found on Netlify's admin panel plus the `NETLIFY_KEY` as a query parameter as defined in the configuration data above (https://YOUR-SITE-ID.netlify.com/.netlify/functions/post-unpublished?key=NETLIFY_KEY)
+1. Create a Netlify site and connect this repository manually.
+2. Configure the site and set the environment variables described in [`.env.example`](.env.example):
+   - Set `ALGOLIA_ACTIVE` to `TRUE` to enable indexing.
+   - Set the Algolia Application ID, API key, and index name.
+   - Choose a `NETLIFY_KEY` for the webhook query parameter. Setting it does not protect current handlers when the parameter is omitted.
 
-4. `post.deleted`
-   - Name: Post deleted
-   - Event: Post deleted
-   - Target URL: the endpoint of the post-published function, found on Netlify's admin panel plus the `NETLIFY_KEY` as a query parameter as defined in the configuration data above (https://YOUR-SITE-ID.netlify.com/.netlify/functions/post-unpublished?key=NETLIFY_KEY)
+The repository's [`netlify.toml`](../../netlify.toml) builds and deploys these functions from `packages/algolia-netlify`. The explicit `public` publish directory contains only a static landing page so package files, function sources, and function build artifacts are not exposed as site files.
 
-These webhooks will trigger an index on every **future change of posts**.
+### Set up Ghost webhooks
 
-> To run an initial index of all the content, you can use the handy CLI from our Ghost Algolia tooling. Head over [here](https://github.com/TryGhost/algolia/tree/master/packages/algolia) and follow the instructions from there.
+In Ghost Admin, create a **Custom Integration** under **Settings → Integrations** and add these webhooks:
 
+| Ghost event | Function |
+| --- | --- |
+| `post.published` | `post-published` |
+| `post.published.edited` | `post-published` |
+| `post.unpublished` | `post-unpublished` |
+| `post.deleted` | `post-unpublished` |
 
-## Security
+Use the function URL shown by Netlify and pass the configured `NETLIFY_KEY` as the `key` query parameter. For example:
 
-To avoid unauthorized access to the Netlify functions endpoints, we highly recommend to setup the `NETLIFY_KEY` variable. This key is currently optional but will be enforced in the future.
+```text
+https://YOUR-SITE-ID.netlify.app/.netlify/functions/post-published?key=NETLIFY_KEY
+```
 
-## Develop
+These webhooks keep future post changes synchronized. Use the [`@tryghost/algolia` CLI](../algolia/README.md) to create the initial index.
 
-This is a mono repository, managed with [lerna](https://lernajs.io/).
+## Development
 
-Follow the instructions for the top-level repo.
-1. `git clone` this repo & `cd` into it as usual
-2. Run `yarn` to install top-level dependencies.
+Install the monorepo dependencies from the repository root with `pnpm install`. Then configure and run this package locally:
 
-To run this package locally, you will need to copy the existing `.env.example` file to `.env` and fill it with the correct keys.
+```sh
+cd packages/algolia-netlify
+cp .env.example .env
+# Replace the example values in .env with development credentials.
+pnpm dev
+```
 
-By running
+`pnpm dev` starts Netlify Dev, which builds the TypeScript functions as needed. Use the local URL it prints for endpoints such as `/.netlify/functions/post-published`.
 
-- `yarn serve`
+Run this package's tests and ESLint checks from the repository root:
 
-you will create a server on `localhost:9000` where your functions will be exposed to listen to (e. g. http://localhost:9000/.netlify/functions/post-unpublished), so you can use them in your local Ghost instance as Webhook target URL.
+```sh
+pnpm --filter @tryghost/algolia-netlify test
+pnpm --filter @tryghost/algolia-netlify typecheck
+pnpm --filter @tryghost/algolia-netlify build
+```
 
+Run the full monorepo suite with `pnpm test`.
 
-## Test
+The modern handlers use native `Request` and `Response` objects. Malformed, empty, or structurally invalid JSON now receives `400 Invalid request body`; a valid Ghost envelope with no selected post remains a `200 No valid request body detected` response. Existing valid webhook behavior, endpoint URLs, and optional `key` handling are unchanged.
 
-- `yarn lint` run just eslint
-- `yarn test` run lint and tests
+`pnpm pack` builds an ESM-only Node 24 package with generated TypeScript declarations. The package intentionally exposes only the two handlers; webhook utilities remain internal.
 
+---
 
-# Copyright & License
+## Copyright & License
 
-Copyright (c) 2013-2023 Ghost Foundation - Released under the [MIT license](LICENSE).
+Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE). Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.

package/dist/functions/post-published.d.mts

@@ -0,0 +1 @@
+export default function postPublished(request: Request): Promise<Response>;

package/dist/functions/post-published.mjs

@@ -0,0 +1,80 @@
+// functions/utils/webhook.ts
+var TEXT_HEADERS = { "content-type": "text/plain; charset=utf-8" };
+var GHOST_SOURCE = String.raw`https://github\.com/TryGhost/Ghost`;
+var SEMVER = String.raw`(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?`;
+var GHOST_USER_AGENT = new RegExp(
+  `^Ghost(?:\\(${GHOST_SOURCE}\\)|/${SEMVER} \\(${GHOST_SOURCE}\\))$`,
+  "u"
+);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isGhostUserAgent = (value) => value !== null && GHOST_USER_AGENT.test(value);
+var textResponse = (body, status = 200) => new Response(body, { status, headers: TEXT_HEADERS });
+var invalidBodyResponse = () => textResponse("Invalid request body", 400);
+var noValidBodyResponse = () => textResponse("No valid request body detected");
+var authorizeRequest = (request) => {
+  const keys = new URL(request.url).searchParams.getAll("key");
+  if (keys.length > 1 || keys[0] && keys[0] !== process.env.NETLIFY_KEY) {
+    return textResponse("Unauthorized", 401);
+  }
+  return void 0;
+};
+var algoliaSettings = () => ({
+  appId: process.env.ALGOLIA_APP_ID,
+  apiKey: process.env.ALGOLIA_API_KEY,
+  index: process.env.ALGOLIA_INDEX
+});
+var parseWebhookBody = async (request) => {
+  try {
+    const body = await request.json();
+    if (!isRecord(body) || !isRecord(body.post)) {
+      return void 0;
+    }
+    return { post: body.post };
+  } catch {
+    return void 0;
+  }
+};
+
+// functions/utils/algolia.mts
+import IndexFactory from "@tryghost/algolia-indexer";
+import transforms from "@tryghost/algolia-fragmenter";
+import "algolia-html-extractor";
+import "algoliasearch";
+
+// functions/post-published.mts
+async function postPublished(request) {
+  const authorizationResponse = authorizeRequest(request);
+  if (authorizationResponse) {
+    return authorizationResponse;
+  }
+  if (process.env.ALGOLIA_ACTIVE !== "TRUE") {
+    return textResponse("Algolia is not activated");
+  }
+  if (!isGhostUserAgent(request.headers.get("user-agent"))) {
+    return textResponse("Unauthorized", 401);
+  }
+  const payload = await parseWebhookBody(request);
+  if (!payload) {
+    return invalidBodyResponse();
+  }
+  const post = payload.post.current;
+  if (!isRecord(post) || Object.keys(post).length === 0) {
+    return noValidBodyResponse();
+  }
+  try {
+    const algoliaObjects = transforms.transformToAlgoliaObject([post]);
+    const fragments = algoliaObjects.reduce(transforms.fragmentTransformer, []);
+    const index = new IndexFactory(algoliaSettings());
+    await index.setSettingsForIndex();
+    await index.save(fragments);
+    console.log("Fragments successfully saved to Algolia index");
+    return textResponse(`Post "${String(post.title)}" has been added to the index.`);
+  } catch (error) {
+    console.log(error);
+    const message = error instanceof Error ? error.message : String(error);
+    return Response.json({ msg: message }, { status: 500 });
+  }
+}
+export {
+  postPublished as default
+};

package/dist/functions/post-unpublished.d.mts

@@ -0,0 +1 @@
+export default function postUnpublished(request: Request): Promise<Response>;

package/dist/functions/post-unpublished.mjs

@@ -0,0 +1,81 @@
+// functions/utils/webhook.ts
+var TEXT_HEADERS = { "content-type": "text/plain; charset=utf-8" };
+var GHOST_SOURCE = String.raw`https://github\.com/TryGhost/Ghost`;
+var SEMVER = String.raw`(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?`;
+var GHOST_USER_AGENT = new RegExp(
+  `^Ghost(?:\\(${GHOST_SOURCE}\\)|/${SEMVER} \\(${GHOST_SOURCE}\\))$`,
+  "u"
+);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isGhostUserAgent = (value) => value !== null && GHOST_USER_AGENT.test(value);
+var textResponse = (body, status = 200) => new Response(body, { status, headers: TEXT_HEADERS });
+var invalidBodyResponse = () => textResponse("Invalid request body", 400);
+var noValidBodyResponse = () => textResponse("No valid request body detected");
+var authorizeRequest = (request) => {
+  const keys = new URL(request.url).searchParams.getAll("key");
+  if (keys.length > 1 || keys[0] && keys[0] !== process.env.NETLIFY_KEY) {
+    return textResponse("Unauthorized", 401);
+  }
+  return void 0;
+};
+var algoliaSettings = () => ({
+  appId: process.env.ALGOLIA_APP_ID,
+  apiKey: process.env.ALGOLIA_API_KEY,
+  index: process.env.ALGOLIA_INDEX
+});
+var parseWebhookBody = async (request) => {
+  try {
+    const body = await request.json();
+    if (!isRecord(body) || !isRecord(body.post)) {
+      return void 0;
+    }
+    return { post: body.post };
+  } catch {
+    return void 0;
+  }
+};
+
+// functions/utils/algolia.mts
+import IndexFactory from "@tryghost/algolia-indexer";
+import transforms from "@tryghost/algolia-fragmenter";
+import "algolia-html-extractor";
+import "algoliasearch";
+
+// functions/post-unpublished.mts
+async function postUnpublished(request) {
+  const authorizationResponse = authorizeRequest(request);
+  if (authorizationResponse) {
+    return authorizationResponse;
+  }
+  if (process.env.ALGOLIA_ACTIVE !== "TRUE") {
+    return textResponse("Algolia is not activated");
+  }
+  if (!isGhostUserAgent(request.headers.get("user-agent"))) {
+    return textResponse("Unauthorized", 401);
+  }
+  const payload = await parseWebhookBody(request);
+  if (!payload) {
+    return invalidBodyResponse();
+  }
+  const { current } = payload.post;
+  const { previous } = payload.post;
+  const post = isRecord(current) && Object.keys(current).length > 0 ? current : previous;
+  const slug = isRecord(post) && typeof post.slug === "string" ? post.slug : "";
+  if (!slug) {
+    return noValidBodyResponse();
+  }
+  try {
+    const index = new IndexFactory(algoliaSettings());
+    await index.initIndex();
+    await index.delete(slug);
+    console.log(`Fragments for slug "${slug}" successfully removed from Algolia index`);
+    return textResponse(`Post "${slug}" has been removed from the index.`);
+  } catch (error) {
+    console.log(error);
+    const message = error instanceof Error ? error.message : String(error);
+    return Response.json({ msg: message }, { status: 500 });
+  }
+}
+export {
+  postUnpublished as default
+};

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+export { default as postPublished } from './functions/post-published.mjs';
+export { default as postUnpublished } from './functions/post-unpublished.mjs';

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import { default as default2 } from "./functions/post-published.mjs";
+import { default as default3 } from "./functions/post-unpublished.mjs";
+export {
+  default2 as postPublished,
+  default3 as postUnpublished
+};

package/package.json

@@ -1,25 +1,45 @@
 {
   "name": "@tryghost/algolia-netlify",
-  "version": "0.3.3",
-  "repository": "https://github.com/TryGhost/algolia/tree/master/packages/algolia-netlify",
+  "version": "0.4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TryGhost/algolia.git",
+    "directory": "packages/algolia-netlify"
+  },
   "author": "Ghost Foundation",
   "license": "MIT",
-  "main": "index.js",
-  "scripts": {
-    "dev": "yarn build && netlify dev",
-    "test": "NODE_ENV=testing mocha './test/**/*.test.js'",
-    "lint": "eslint . --ext .js --cache",
-    "posttest": "yarn lint",
-    "build": "NODE_ENV=production netlify functions:build --functions build/functions --src functions"
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./post-published": {
+      "types": "./dist/functions/post-published.d.mts",
+      "import": "./dist/functions/post-published.mjs"
+    },
+    "./post-unpublished": {
+      "types": "./dist/functions/post-unpublished.d.mts",
+      "import": "./dist/functions/post-unpublished.mjs"
+    }
   },
   "files": [
-    "index.js",
-    "lib"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
   "eslintConfig": {
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+      "ecmaVersion": 2023,
+      "sourceType": "module"
+    },
     "extends": [
       "airbnb-base",
       "plugin:ghost/browser"
@@ -30,21 +50,33 @@
   },
   "eslintIgnore": [
     "webpack.functions.js",
-    "build/*"
+    "build/*",
+    "dist/*"
   ],
   "devDependencies": {
-    "eslint": "8.48.0",
+    "@types/node": "24.13.3",
+    "@typescript-eslint/parser": "8.67.0",
+    "eslint": "8.57.1",
     "eslint-config-airbnb-base": "15.0.0",
-    "eslint-plugin-ghost": "3.3.0",
-    "eslint-plugin-import": "2.28.1",
-    "mocha": "10.2.0",
-    "netlify-cli": "16.3.1",
-    "should": "13.2.3",
-    "sinon": "15.2.0"
+    "eslint-plugin-ghost": "3.5.0",
+    "eslint-plugin-import": "2.32.0",
+    "esbuild": "0.28.2",
+    "netlify-cli": "27.1.1",
+    "typescript": "6.0.3"
   },
   "dependencies": {
-    "@tryghost/algolia-fragmenter": "^0.2.6",
-    "@tryghost/algolia-indexer": "^0.3.0"
+    "algolia-html-extractor": "0.0.1",
+    "algoliasearch": "4.20.0",
+    "@tryghost/algolia-indexer": "^0.3.2",
+    "@tryghost/algolia-fragmenter": "^0.2.8"
   },
-  "gitHead": "0f0d8a416adb0f78fda0ec72f872146406d76eae"
-}
+  "scripts": {
+    "dev": "pnpm --dir ../.. exec netlify dev --filter @tryghost/algolia-netlify",
+    "test": "NODE_ENV=testing vitest run --root .",
+    "typecheck": "tsc --project tsconfig.functions.json && tsc --project tsconfig.test.json",
+    "lint": "eslint . --ext .js,.cjs,.ts,.mts,.cts --cache",
+    "posttest": "pnpm typecheck && pnpm lint",
+    "build": "NODE_ENV=production pnpm --dir ../.. exec netlify build --offline --filter @tryghost/algolia-netlify",
+    "build:package": "node scripts/build-package.mjs && tsc --project tsconfig.package.json && node scripts/clean-package.mjs"
+  }
+}