@praxium/sdk 0.2.17 → 0.2.22

package/dist/revalidation.d.ts

@@ -5,6 +5,11 @@
  * revalidation on the tenant's public website. This handler
  * validates the HMAC signature and calls Next.js revalidatePath().
  *
+ * Architecture (entity-driven, three-layer path agnosticism):
+ *   - Monolith sends { entity } — knows WHAT changed, not WHERE
+ *   - SDK looks up pathMap[entity] — pure lookup + security, path-agnostic
+ *   - Tenant website provides pathMap — owns WHERE pages live (locale-prefixed)
+ *
  * Signature scheme (H6):
  *   X-Praxium-Signature: t={unix_timestamp},sha256={HMAC-SHA256(secret, timestamp.body)}
  *
@@ -21,6 +26,13 @@
  *
  * export const POST = createRevalidationHandler({
  *   secret: process.env.PRAXIUM_REVALIDATION_SECRET!,
+ *   pathMap: {
+ *     'team': ['/nl/team', '/en/team'],
+ *     'rates': ['/nl/tarieven', '/en/rates'],
+ *     'faq': ['/nl/faq', '/en/faq'],
+ *     'opening-hours': ['/nl', '/en'],
+ *     'all': ['/nl', '/en'],
+ *   },
  * })
  * ```
  */
@@ -29,14 +41,55 @@ interface RevalidationConfig {
     secret: string;
     /** Maximum age of request timestamp in milliseconds (default: 5 minutes) */
     maxTimestampAge?: number;
+    /**
+     * Entity → full paths to revalidate (including locale prefix).
+     *
+     * Paths are pre-computed by the tenant website — SDK does no path manipulation.
+     * Each tenant configures its own paths based on its URL structure and locales.
+     *
+     * When a webhook arrives with `{ entity: 'team' }`, the SDK looks up
+     * `pathMap['team']` and calls `revalidatePath()` for each path.
+     *
+     * Unknown entities fall back to revalidating ALL registered paths (union of
+     * all pathMap values) with a console warning.
+     *
+     * @example
+     * pathMap: {
+     *   'team': ['/nl/team', '/en/team'],
+     *   'rates': ['/nl/tarieven', '/en/rates'],
+     *   'opening-hours': ['/nl', '/en'],
+     * }
+     */
+    pathMap: Record<string, string[]>;
 }
+/**
+ * Resolve entity to revalidation paths using the tenant's pathMap.
+ *
+ * The SDK is path-agnostic — it performs a pure lookup against the
+ * tenant-provided pathMap. Paths are pre-computed by the tenant website
+ * including locale prefixes (e.g., '/nl/tarieven', '/en/rates').
+ *
+ * Resolution priority:
+ * 1. pathMap[entity] → pre-computed paths for this entity
+ * 2. Unknown/missing entity → deduplicated union of ALL pathMap values
+ *    (full site revalidation as safe fallback)
+ *
+ * @returns paths to revalidate and whether fallback was used
+ */
+declare function resolveRevalidationPaths(entity: string | undefined, pathMap: Record<string, string[]>): {
+    paths: string[];
+    fallback: boolean;
+};
 /**
  * Creates a Next.js route handler that revalidates ISR pages
  * when triggered by the Praxium platform webhook.
  *
  * Authentication uses HMAC-SHA256 signature verification with
  * timestamp-based replay protection (H6 security scheme).
+ *
+ * Path resolution is entity-driven: the monolith sends `{ entity }`,
+ * the SDK looks up `pathMap[entity]` for pre-computed full paths.
  */
 declare function createRevalidationHandler(config: RevalidationConfig): (request: Request) => Promise<Response>;
 
-export { createRevalidationHandler };
+export { createRevalidationHandler, resolveRevalidationPaths };

package/dist/revalidation.js

@@ -46,6 +46,13 @@ function parseSignatureHeader(headerValue) {
     signature: signatureMatch[1]
   };
 }
+function resolveRevalidationPaths(entity, pathMap) {
+  if (entity && pathMap[entity]) {
+    return { paths: pathMap[entity], fallback: false };
+  }
+  const allPaths = [...new Set(Object.values(pathMap).flat())];
+  return { paths: allPaths, fallback: true };
+}
 function createRevalidationHandler(config) {
   const maxTimestampAge = config.maxTimestampAge ?? DEFAULT_MAX_TIMESTAMP_AGE_MS;
   return async (request) => {
@@ -94,7 +101,15 @@ function createRevalidationHandler(config) {
     } catch {
       return Response.json({ error: "Invalid JSON body" }, { status: 400 });
     }
-    const paths = body.paths ?? ["/"];
+    const { paths, fallback } = resolveRevalidationPaths(
+      body.entity,
+      config.pathMap
+    );
+    if (fallback) {
+      console.warn(
+        `[Revalidation] Unknown entity "${body.entity ?? "(none)"}" \u2014 falling back to full revalidation (${paths.length} paths)`
+      );
+    }
     try {
       const { revalidatePath } = await import("next/cache");
       for (const path of paths) {
@@ -110,5 +125,6 @@ function createRevalidationHandler(config) {
   };
 }
 export {
-  createRevalidationHandler
+  createRevalidationHandler,
+  resolveRevalidationPaths
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxium/sdk",
-  "version": "0.2.17",
+  "version": "0.2.22",
   "description": "Official TypeScript SDK for the Praxium platform API",
   "type": "module",
   "exports": {