@uniformdev/mesh-edgehancer-sdk 19.132.0 → 19.134.0

package/dist/webhooks/index.d.mts

@@ -0,0 +1,88 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+
+type InvalidationResponse = {
+    status: number;
+    text: string;
+};
+declare abstract class APIError extends Error {
+    abstract readonly status: number;
+    abstract readonly statusText: string;
+}
+declare class BadRequestError extends APIError {
+    status: number;
+    statusText: string;
+    constructor(message?: string);
+}
+declare class ForbiddenError extends APIError {
+    status: number;
+    statusText: string;
+    constructor(message?: string);
+}
+
+type Purger = {
+    /** Purge all caches for the Data Type */
+    purgeAllCachesForDataType(): Promise<InvalidationResponse>;
+    /** Purge caches by surrogate keys. Your Custom Edgehancer is responsible to set them up first */
+    purgeBySurrogateKeys(surrogateKeys: string[]): Promise<InvalidationResponse>;
+};
+/**
+ * Returns Purger with two methods to invalidate cache for your Data Type.
+ * You should validate parameters before calling this function.
+ */
+declare const createPurger: ({ projectId, purgeKey, dataTypeId, edgeApiHost, logger, }: {
+    projectId: string;
+    purgeKey: string;
+    dataTypeId: string;
+    edgeApiHost?: string | undefined;
+    logger?: Console | undefined;
+}) => Purger;
+
+type handleNextJSWebhookRequestArgs = {
+    /** NextJS request object */
+    request: NextApiRequest;
+    /** NextJS response object */
+    response: NextApiResponse;
+    /**
+     *  Your custom handler that will be called after request validation with purger instance
+     * that has methods to invalidate your Data Type cache
+     * */
+    handler: (args: {
+        request: NextApiRequest;
+        purger: Purger;
+    }) => Promise<InvalidationResponse>;
+    logger?: Console;
+};
+/**
+ * Handles the incoming webhook request via NextJS api route.
+ *
+ * It validates the request, handle exceptions,
+ * calls your custom handler and sends the response back to webhook caller.
+ */
+declare const handleNextJSWebhookRequest: ({ request, response, handler, logger, }: handleNextJSWebhookRequestArgs) => Promise<void>;
+
+/**
+ * Reads the parameter from the Next.js api route request
+ */
+declare function getParam(query: NextApiRequest['query'], paramName: string): string | undefined;
+/**
+ * Throws an BadRequestError exception if the parameter is not found in the request.
+ */
+declare function getRequiredParam(query: NextApiRequest['query'], paramName: string): string;
+/**
+ * Reads and validates the request parameters required to perform cache invalidation.
+ * In case of invalid parameters, it throws an BadRequestError exception.
+ *
+ * URL example: https://my-nextjs-app.com/api/cache-invalidation?projectId=PROJECT_ID&dataTypeId=DATA_TYPE_ID&purgeKey=PURGE_KEY
+ */
+declare function validateParams(req: NextApiRequest): {
+    projectId: string;
+    dataTypeId: string;
+    purgeKey: string;
+    edgeApiHost: string | undefined;
+};
+/**
+ * Only allows Stable, Canary and PR edge API hosts.
+ */
+declare function isAllowedEdgeApiHost(edgeApiHost: string): boolean;
+
+export { APIError, BadRequestError, ForbiddenError, type InvalidationResponse, type Purger, createPurger, getParam, getRequiredParam, handleNextJSWebhookRequest, type handleNextJSWebhookRequestArgs, isAllowedEdgeApiHost, validateParams };

package/dist/webhooks/index.d.ts

@@ -0,0 +1,88 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+
+type InvalidationResponse = {
+    status: number;
+    text: string;
+};
+declare abstract class APIError extends Error {
+    abstract readonly status: number;
+    abstract readonly statusText: string;
+}
+declare class BadRequestError extends APIError {
+    status: number;
+    statusText: string;
+    constructor(message?: string);
+}
+declare class ForbiddenError extends APIError {
+    status: number;
+    statusText: string;
+    constructor(message?: string);
+}
+
+type Purger = {
+    /** Purge all caches for the Data Type */
+    purgeAllCachesForDataType(): Promise<InvalidationResponse>;
+    /** Purge caches by surrogate keys. Your Custom Edgehancer is responsible to set them up first */
+    purgeBySurrogateKeys(surrogateKeys: string[]): Promise<InvalidationResponse>;
+};
+/**
+ * Returns Purger with two methods to invalidate cache for your Data Type.
+ * You should validate parameters before calling this function.
+ */
+declare const createPurger: ({ projectId, purgeKey, dataTypeId, edgeApiHost, logger, }: {
+    projectId: string;
+    purgeKey: string;
+    dataTypeId: string;
+    edgeApiHost?: string | undefined;
+    logger?: Console | undefined;
+}) => Purger;
+
+type handleNextJSWebhookRequestArgs = {
+    /** NextJS request object */
+    request: NextApiRequest;
+    /** NextJS response object */
+    response: NextApiResponse;
+    /**
+     *  Your custom handler that will be called after request validation with purger instance
+     * that has methods to invalidate your Data Type cache
+     * */
+    handler: (args: {
+        request: NextApiRequest;
+        purger: Purger;
+    }) => Promise<InvalidationResponse>;
+    logger?: Console;
+};
+/**
+ * Handles the incoming webhook request via NextJS api route.
+ *
+ * It validates the request, handle exceptions,
+ * calls your custom handler and sends the response back to webhook caller.
+ */
+declare const handleNextJSWebhookRequest: ({ request, response, handler, logger, }: handleNextJSWebhookRequestArgs) => Promise<void>;
+
+/**
+ * Reads the parameter from the Next.js api route request
+ */
+declare function getParam(query: NextApiRequest['query'], paramName: string): string | undefined;
+/**
+ * Throws an BadRequestError exception if the parameter is not found in the request.
+ */
+declare function getRequiredParam(query: NextApiRequest['query'], paramName: string): string;
+/**
+ * Reads and validates the request parameters required to perform cache invalidation.
+ * In case of invalid parameters, it throws an BadRequestError exception.
+ *
+ * URL example: https://my-nextjs-app.com/api/cache-invalidation?projectId=PROJECT_ID&dataTypeId=DATA_TYPE_ID&purgeKey=PURGE_KEY
+ */
+declare function validateParams(req: NextApiRequest): {
+    projectId: string;
+    dataTypeId: string;
+    purgeKey: string;
+    edgeApiHost: string | undefined;
+};
+/**
+ * Only allows Stable, Canary and PR edge API hosts.
+ */
+declare function isAllowedEdgeApiHost(edgeApiHost: string): boolean;
+
+export { APIError, BadRequestError, ForbiddenError, type InvalidationResponse, type Purger, createPurger, getParam, getRequiredParam, handleNextJSWebhookRequest, type handleNextJSWebhookRequestArgs, isAllowedEdgeApiHost, validateParams };

package/dist/webhooks/index.js

@@ -0,0 +1,205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/webhooks/index.ts
+var webhooks_exports = {};
+__export(webhooks_exports, {
+  APIError: () => APIError,
+  BadRequestError: () => BadRequestError,
+  ForbiddenError: () => ForbiddenError,
+  createPurger: () => createPurger,
+  getParam: () => getParam,
+  getRequiredParam: () => getRequiredParam,
+  handleNextJSWebhookRequest: () => handleNextJSWebhookRequest,
+  isAllowedEdgeApiHost: () => isAllowedEdgeApiHost,
+  validateParams: () => validateParams
+});
+module.exports = __toCommonJS(webhooks_exports);
+
+// src/webhooks/purge.ts
+var defaultLogger = console;
+var createPurger = ({
+  projectId,
+  purgeKey,
+  dataTypeId,
+  edgeApiHost = "uniform.global",
+  logger = defaultLogger
+}) => {
+  const invalidationEndpointUrl = new URL(`https://${edgeApiHost}/api/v1/invalidation`);
+  invalidationEndpointUrl.searchParams.set("projectId", projectId);
+  invalidationEndpointUrl.searchParams.set("dataTypeId", dataTypeId);
+  invalidationEndpointUrl.searchParams.set("purgeKey", purgeKey);
+  const purgeAllCachesForDataType = async () => {
+    logger.log(`[purgeAllCachesForDataType] call`, {
+      invalidationEndpointUrl: invalidationEndpointUrl.toString()
+    });
+    const res = await fetch(invalidationEndpointUrl, {
+      method: "GET"
+    });
+    return {
+      status: res.status,
+      text: await res.text()
+    };
+  };
+  const purgeBySurrogateKeys = async (surrogateKeys) => {
+    logger.log(`[purgeBySurrogateKeys] call`, {
+      invalidationEndpointUrl: invalidationEndpointUrl.toString(),
+      surrogateKeys
+    });
+    const body = {
+      surrogateKeys: surrogateKeys.filter((x) => x)
+    };
+    if (body.surrogateKeys.length > 0) {
+      const res = await fetch(invalidationEndpointUrl, {
+        method: "POST",
+        body: JSON.stringify(body)
+      });
+      return {
+        status: res.status,
+        text: await res.text()
+      };
+    } else {
+      logger.log(`[purgeBySurrogateKeys] No surrogate keys found.`, {
+        invalidationEndpointUrl: invalidationEndpointUrl.toString(),
+        surrogateKeys
+      });
+      return {
+        status: 200,
+        text: "No surrogate keys found."
+      };
+    }
+  };
+  return { purgeAllCachesForDataType, purgeBySurrogateKeys };
+};
+
+// src/webhooks/shared.ts
+var APIError = class extends Error {
+};
+var BadRequestError = class _BadRequestError extends APIError {
+  constructor(message = "Invalid request received") {
+    super(message);
+    this.status = 400;
+    this.statusText = "Bad Request";
+    Object.setPrototypeOf(this, _BadRequestError.prototype);
+  }
+};
+var ForbiddenError = class _ForbiddenError extends APIError {
+  constructor(message = "This action is forbidden") {
+    super(message);
+    this.status = 403;
+    this.statusText = "Forbidden";
+    Object.setPrototypeOf(this, _ForbiddenError.prototype);
+  }
+};
+
+// src/webhooks/utils.ts
+function getParam(query, paramName) {
+  const values = query[paramName];
+  if (!values) {
+    return void 0;
+  } else if (typeof values === "string") {
+    return values;
+  } else if (values.length === 1) {
+    return values[0];
+  } else {
+    throw new BadRequestError(`Multiple values for ${paramName} found in request parameters`);
+  }
+}
+function getRequiredParam(query, paramName) {
+  const value = getParam(query, paramName);
+  if (!value) {
+    throw new BadRequestError(`${paramName} not found in request parameters`);
+  }
+  return value;
+}
+function validateParams(req) {
+  const edgeApiHost = getParam(req.query, "edgeApiHost");
+  if (edgeApiHost) {
+    if (!isAllowedEdgeApiHost(edgeApiHost)) {
+      throw new ForbiddenError(`Edge API hostname is not allowed: ${edgeApiHost}`);
+    }
+  }
+  const projectId = getRequiredParam(req.query, "projectId");
+  const dataTypeId = getRequiredParam(req.query, "dataTypeId");
+  const purgeKey = getRequiredParam(req.query, "purgeKey");
+  return { projectId, dataTypeId, purgeKey, edgeApiHost };
+}
+function isAllowedEdgeApiHost(edgeApiHost) {
+  if (["uniform.global", "canary.uniform.global"].includes(edgeApiHost)) {
+    return true;
+  }
+  if (edgeApiHost.endsWith(".uniform.rocks")) {
+    return true;
+  }
+  return false;
+}
+
+// src/webhooks/handleNextJSWebhookRequest.ts
+var ALLOWED_METHODS = ["POST", "GET"];
+var defaultLogger2 = console;
+var handleNextJSWebhookRequest = async ({
+  request,
+  response,
+  handler,
+  logger = defaultLogger2
+}) => {
+  try {
+    logger.log(`request`, {
+      url: request.url,
+      method: request.method
+    });
+    if (!ALLOWED_METHODS.includes(request.method || "")) {
+      throw new BadRequestError(
+        `Expected ${ALLOWED_METHODS.join(" or ")} but was called with ${request.method}`
+      );
+    }
+    const { projectId, purgeKey, dataTypeId, edgeApiHost } = validateParams(request);
+    const purger = createPurger({ projectId, purgeKey, dataTypeId, edgeApiHost, logger });
+    const { status, text } = await handler({
+      request,
+      purger
+    });
+    response.status(status).send(text);
+  } catch (err) {
+    if (err instanceof APIError) {
+      logger.error(`APIError: [${err.status} ${err.statusText}] ${err.message}`);
+      response.status(err.status).json({
+        type: err.statusText,
+        errorMessage: err.message
+      });
+    } else {
+      logger.error(`Error`, err);
+      response.status(500).json({
+        errorMessage: err.message || "Unknown error"
+      });
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  BadRequestError,
+  ForbiddenError,
+  createPurger,
+  getParam,
+  getRequiredParam,
+  handleNextJSWebhookRequest,
+  isAllowedEdgeApiHost,
+  validateParams
+});

package/dist/webhooks/index.mjs

@@ -0,0 +1,170 @@
+// src/webhooks/purge.ts
+var defaultLogger = console;
+var createPurger = ({
+  projectId,
+  purgeKey,
+  dataTypeId,
+  edgeApiHost = "uniform.global",
+  logger = defaultLogger
+}) => {
+  const invalidationEndpointUrl = new URL(`https://${edgeApiHost}/api/v1/invalidation`);
+  invalidationEndpointUrl.searchParams.set("projectId", projectId);
+  invalidationEndpointUrl.searchParams.set("dataTypeId", dataTypeId);
+  invalidationEndpointUrl.searchParams.set("purgeKey", purgeKey);
+  const purgeAllCachesForDataType = async () => {
+    logger.log(`[purgeAllCachesForDataType] call`, {
+      invalidationEndpointUrl: invalidationEndpointUrl.toString()
+    });
+    const res = await fetch(invalidationEndpointUrl, {
+      method: "GET"
+    });
+    return {
+      status: res.status,
+      text: await res.text()
+    };
+  };
+  const purgeBySurrogateKeys = async (surrogateKeys) => {
+    logger.log(`[purgeBySurrogateKeys] call`, {
+      invalidationEndpointUrl: invalidationEndpointUrl.toString(),
+      surrogateKeys
+    });
+    const body = {
+      surrogateKeys: surrogateKeys.filter((x) => x)
+    };
+    if (body.surrogateKeys.length > 0) {
+      const res = await fetch(invalidationEndpointUrl, {
+        method: "POST",
+        body: JSON.stringify(body)
+      });
+      return {
+        status: res.status,
+        text: await res.text()
+      };
+    } else {
+      logger.log(`[purgeBySurrogateKeys] No surrogate keys found.`, {
+        invalidationEndpointUrl: invalidationEndpointUrl.toString(),
+        surrogateKeys
+      });
+      return {
+        status: 200,
+        text: "No surrogate keys found."
+      };
+    }
+  };
+  return { purgeAllCachesForDataType, purgeBySurrogateKeys };
+};
+
+// src/webhooks/shared.ts
+var APIError = class extends Error {
+};
+var BadRequestError = class _BadRequestError extends APIError {
+  constructor(message = "Invalid request received") {
+    super(message);
+    this.status = 400;
+    this.statusText = "Bad Request";
+    Object.setPrototypeOf(this, _BadRequestError.prototype);
+  }
+};
+var ForbiddenError = class _ForbiddenError extends APIError {
+  constructor(message = "This action is forbidden") {
+    super(message);
+    this.status = 403;
+    this.statusText = "Forbidden";
+    Object.setPrototypeOf(this, _ForbiddenError.prototype);
+  }
+};
+
+// src/webhooks/utils.ts
+function getParam(query, paramName) {
+  const values = query[paramName];
+  if (!values) {
+    return void 0;
+  } else if (typeof values === "string") {
+    return values;
+  } else if (values.length === 1) {
+    return values[0];
+  } else {
+    throw new BadRequestError(`Multiple values for ${paramName} found in request parameters`);
+  }
+}
+function getRequiredParam(query, paramName) {
+  const value = getParam(query, paramName);
+  if (!value) {
+    throw new BadRequestError(`${paramName} not found in request parameters`);
+  }
+  return value;
+}
+function validateParams(req) {
+  const edgeApiHost = getParam(req.query, "edgeApiHost");
+  if (edgeApiHost) {
+    if (!isAllowedEdgeApiHost(edgeApiHost)) {
+      throw new ForbiddenError(`Edge API hostname is not allowed: ${edgeApiHost}`);
+    }
+  }
+  const projectId = getRequiredParam(req.query, "projectId");
+  const dataTypeId = getRequiredParam(req.query, "dataTypeId");
+  const purgeKey = getRequiredParam(req.query, "purgeKey");
+  return { projectId, dataTypeId, purgeKey, edgeApiHost };
+}
+function isAllowedEdgeApiHost(edgeApiHost) {
+  if (["uniform.global", "canary.uniform.global"].includes(edgeApiHost)) {
+    return true;
+  }
+  if (edgeApiHost.endsWith(".uniform.rocks")) {
+    return true;
+  }
+  return false;
+}
+
+// src/webhooks/handleNextJSWebhookRequest.ts
+var ALLOWED_METHODS = ["POST", "GET"];
+var defaultLogger2 = console;
+var handleNextJSWebhookRequest = async ({
+  request,
+  response,
+  handler,
+  logger = defaultLogger2
+}) => {
+  try {
+    logger.log(`request`, {
+      url: request.url,
+      method: request.method
+    });
+    if (!ALLOWED_METHODS.includes(request.method || "")) {
+      throw new BadRequestError(
+        `Expected ${ALLOWED_METHODS.join(" or ")} but was called with ${request.method}`
+      );
+    }
+    const { projectId, purgeKey, dataTypeId, edgeApiHost } = validateParams(request);
+    const purger = createPurger({ projectId, purgeKey, dataTypeId, edgeApiHost, logger });
+    const { status, text } = await handler({
+      request,
+      purger
+    });
+    response.status(status).send(text);
+  } catch (err) {
+    if (err instanceof APIError) {
+      logger.error(`APIError: [${err.status} ${err.statusText}] ${err.message}`);
+      response.status(err.status).json({
+        type: err.statusText,
+        errorMessage: err.message
+      });
+    } else {
+      logger.error(`Error`, err);
+      response.status(500).json({
+        errorMessage: err.message || "Unknown error"
+      });
+    }
+  }
+};
+export {
+  APIError,
+  BadRequestError,
+  ForbiddenError,
+  createPurger,
+  getParam,
+  getRequiredParam,
+  handleNextJSWebhookRequest,
+  isAllowedEdgeApiHost,
+  validateParams
+};

package/package.json

@@ -1,19 +1,39 @@
 {
   "name": "@uniformdev/mesh-edgehancer-sdk",
-  "version": "19.132.0",
+  "version": "19.134.0",
   "description": "Uniform Mesh Edgehancer SDK",
   "license": "SEE LICENSE IN LICENSE.txt",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",
   "exports": {
-    "import": {
-      "types": "./dist/index.d.mts",
-      "node": "./dist/index.mjs",
-      "default": "./dist/index.esm.js"
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "node": "./dist/index.mjs",
+        "default": "./dist/index.esm.js"
+      },
+      "require": "./dist/index.js"
     },
-    "require": "./dist/index.js"
+    "./webhooks": {
+      "import": {
+        "types": "./dist/webhooks/index.d.mts",
+        "node": "./dist/webhooks/index.mjs",
+        "default": "./dist/webhooks/index.esm.js"
+      },
+      "require": "./dist/webhooks/index.js"
+    }
   },
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/index.d.ts"
+      ],
+      "webhooks": [
+        "./dist/webhooks/index.d.ts"
+      ]
+    }
+  },
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
@@ -28,12 +48,18 @@
     "/dist"
   ],
   "dependencies": {
-    "@uniformdev/canvas": "19.132.0",
+    "@uniformdev/canvas": "19.134.0",
     "tsafe": "1.6.5",
     "zod": "3.22.4"
   },
+  "devDependencies": {
+    "next": "13.4.12"
+  },
+  "peerDependencies": {
+    "next": ">13"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7e50a3037d22f060b5de46fbe32b9e4a6fb1c16c"
+  "gitHead": "4d3856ce53d66b4e69fd693dadc98292cfbc37d1"
 }