@praxium/sdk 0.4.87 → 0.5.89

package/dist/webhooks.d.ts

@@ -70,6 +70,33 @@ interface WebhookFailure {
 }
 /** Result of processWebhook() */
 type WebhookResult = WebhookSuccess | WebhookFailure;
+/**
+ * Pluggable structured logger for createRevalidationHandler.
+ *
+ * Each method receives a string message + an optional structured context
+ * object. The handler NEVER logs the secret, signature value, or request
+ * body — only structural facts (HTTP status, entity name, path counts,
+ * error class names, duration).
+ *
+ * Default: routes to `console.{log,warn,error}` — the correct sink for
+ * Vercel/Next.js where function logs surface in the Vercel dashboard.
+ * Override to wire Pino / OpenTelemetry, or a no-op logger for tests.
+ */
+interface RevalidationLogger {
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Per-path revalidation failure. Returned in the response body for both
+ * 200 partial-success and 500 total-failure cases. `errorName` is the
+ * thrown error's class name only — never the message (which could leak
+ * PII or implementation details).
+ */
+interface PathFailure {
+    path: string;
+    errorName: string;
+}
 /** Configuration for createRevalidationHandler() */
 interface RevalidationConfig {
     /** Shared secret for HMAC signature verification */
@@ -93,6 +120,13 @@ interface RevalidationConfig {
      * }
      */
     pathMap: Record<string, string[]>;
+    /**
+     * Pluggable structured logger. Defaults to `console.{log,warn,error}`,
+     * which is the right sink for Vercel/Next.js (function logs surface in
+     * the Vercel dashboard). Pass a no-op logger for tests, or wire in
+     * Pino/OpenTelemetry for custom observability stacks.
+     */
+    logger?: RevalidationLogger;
 }
 /**
  * Process and verify a Praxium platform webhook.
@@ -132,11 +166,34 @@ declare function resolveRevalidationPaths(entity: string | undefined, pathMap: R
     fallback: boolean;
 };
 /**
- * Creates a Next.js route handler that revalidates ISR pages
- * when triggered by a Praxium platform webhook.
- *
- * Wraps processWebhook() with path resolution and revalidatePath() calls.
- * Returns a Fetch API handler `(request: Request) => Promise<Response>`
+ * Production-grade Next.js route handler for Praxium revalidation webhooks.
+ *
+ * Wraps `processWebhook()` + `resolveRevalidationPaths()` with three
+ * tenant-grade concerns the lower-level primitives don't own:
+ *
+ * 1. **PII-safe structural logging at every branch** — missing header,
+ *    bad signature format, expired timestamp, signature mismatch,
+ *    unknown entity (fallback), per-path failures, total success. Logs
+ *    NEVER include the secret, signature value, or request body. They
+ *    DO include: HTTP status, entity name, path counts, error class
+ *    names, duration. Sink defaults to `console.*` (Vercel/Next.js);
+ *    override via `config.logger` for tests / Pino / OpenTelemetry.
+ *
+ * 2. **Per-path try/catch + partial-success semantics** — one failing
+ *    `revalidatePath()` call does NOT abort the rest of the batch:
+ *      - all paths succeed → 200, info log, no warnings
+ *      - partial (N/M failed) → 200 with `failures[]` in body, warn log;
+ *        the dispatcher sees OK and does NOT retry, because retrying
+ *        would re-revalidate the paths that already succeeded
+ *      - all paths fail → 500 with `failures[]`, error log; dispatcher
+ *        retries the whole webhook
+ *
+ * 3. **Unknown-entity fallback warning** — `resolveRevalidationPaths`
+ *    falls back to revalidating every registered path when it doesn't
+ *    recognise the entity; this emits a warn so drift between the
+ *    monolith's entity enum and the tenant's `pathMap` is visible.
+ *
+ * Returns a Fetch-API handler `(request: Request) => Promise<Response>`
  * compatible with Next.js App Router route exports.
  *
  * @example
@@ -157,4 +214,4 @@ declare function resolveRevalidationPaths(entity: string | undefined, pathMap: R
  */
 declare function createRevalidationHandler(config: RevalidationConfig): (request: Request) => Promise<Response>;
 
-export { type ProcessWebhookInput, type RevalidationConfig, WEBHOOK_SIGNATURE_HEADER, type WebhookFailure, type WebhookResult, type WebhookSuccess, createRevalidationHandler, processWebhook, resolveRevalidationPaths };
+export { type PathFailure, type ProcessWebhookInput, type RevalidationConfig, type RevalidationLogger, WEBHOOK_SIGNATURE_HEADER, type WebhookFailure, type WebhookResult, type WebhookSuccess, createRevalidationHandler, processWebhook, resolveRevalidationPaths };

package/dist/webhooks.js

@@ -83,10 +83,20 @@ function resolveRevalidationPaths(entity, pathMap) {
   const allPaths = [...new Set(Object.values(pathMap).flat())];
   return { paths: allPaths, fallback: true };
 }
+var DEFAULT_LOGGER = {
+  info: (message, context) => context !== void 0 ? console.log(message, context) : console.log(message),
+  warn: (message, context) => context !== void 0 ? console.warn(message, context) : console.warn(message),
+  error: (message, context) => context !== void 0 ? console.error(message, context) : console.error(message)
+};
 function createRevalidationHandler(config) {
+  const log = config.logger ?? DEFAULT_LOGGER;
   return async (request) => {
+    const start = Date.now();
     const signatureHeader = request.headers.get(WEBHOOK_SIGNATURE_HEADER);
     if (!signatureHeader) {
+      log.warn(
+        `[revalidate] 401 \u2014 missing ${WEBHOOK_SIGNATURE_HEADER} header (${Date.now() - start}ms)`
+      );
       return Response.json(
         { error: `Missing ${WEBHOOK_SIGNATURE_HEADER} header` },
         { status: 401 }
@@ -101,6 +111,9 @@ function createRevalidationHandler(config) {
     });
     if (!result.valid) {
       const status = result.error === "Invalid JSON body" ? 400 : 401;
+      log.warn(
+        `[revalidate] ${status} \u2014 ${result.error} (bodyBytes=${rawBody.length}, ${Date.now() - start}ms)`
+      );
       return Response.json({ error: result.error }, { status });
     }
     const { paths, fallback } = resolveRevalidationPaths(
@@ -108,22 +121,69 @@ function createRevalidationHandler(config) {
       config.pathMap
     );
     if (fallback) {
-      console.warn(
-        `[Webhook] Unknown entity "${result.entity ?? "(none)"}" \u2014 falling back to full revalidation (${paths.length} paths)`
+      log.warn(
+        `[revalidate] unknown entity "${result.entity ?? "(none)"}" \u2014 falling back to full revalidation (${paths.length} paths)`
       );
     }
+    let revalidatePath;
     try {
-      const { revalidatePath } = await import("next/cache");
-      for (const path of paths) {
-        revalidatePath(path);
-      }
+      const mod = await import("next/cache");
+      revalidatePath = mod.revalidatePath;
     } catch {
+      log.error(
+        `[revalidate] 500 \u2014 next/cache module not available (${Date.now() - start}ms)`
+      );
       return Response.json(
         { error: "Revalidation failed \u2014 next/cache not available" },
         { status: 500 }
       );
     }
-    return Response.json({ revalidated: true, paths });
+    const failures = [];
+    for (const path of paths) {
+      try {
+        revalidatePath(path);
+      } catch (error) {
+        failures.push({
+          path,
+          errorName: error instanceof Error ? error.name : "unknown"
+        });
+      }
+    }
+    const succeeded = paths.length - failures.length;
+    const durationMs = Date.now() - start;
+    if (failures.length === paths.length && paths.length > 0) {
+      log.error("[revalidate] 500 \u2014 all revalidatePath calls threw", {
+        entity: result.entity,
+        pathCount: paths.length,
+        firstErrorName: failures[0].errorName,
+        durationMs
+      });
+      return Response.json(
+        { error: "Revalidation failed", failures },
+        { status: 500 }
+      );
+    }
+    if (failures.length > 0) {
+      log.warn(
+        "[revalidate] partial success \u2014 some revalidatePath calls threw",
+        {
+          entity: result.entity,
+          succeeded,
+          failed: failures.length,
+          totalPaths: paths.length,
+          failures,
+          durationMs
+        }
+      );
+    }
+    log.info(
+      `[revalidate] 200 \u2014 entity="${result.entity ?? "(none)"}" fallback=${fallback} succeeded=${succeeded}/${paths.length} (${durationMs}ms)`
+    );
+    return Response.json({
+      revalidated: true,
+      paths,
+      ...failures.length > 0 && { failures }
+    });
   };
 }
 export {

package/package.json

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