@praxium/sdk 0.4.85 → 0.5.89

package/dist/index.d.ts

@@ -674,7 +674,7 @@ type ClientLocale = SupportedLocale | '*';
 /**
  * Extract the tenant slug from a profile-scoped API key.
  *
- * Key format: praxium_v1_{tenantSlug}_{profileSlug}_{timestamp}_{signature}
+ * Key format: `${API_KEY_PREFIX}_{tenantSlug}_{profileSlug}_{timestamp}_{signature}`
  * Parts:      [0]praxium [1]v1 [2]tenantSlug [3]profileSlug [4]timestamp [5]signature
  *
  * @throws Error if key format is invalid (wrong prefix or insufficient parts)
@@ -719,6 +719,20 @@ declare function createPraxiumClient(config: PraxiumClientConfig & {
 /** Locale-specific mode: returns PublicTeamMember[] with resolved labels/values */
 declare function createPraxiumClient(config: PraxiumClientConfig): PraxiumClient;
 
+/** Version-prefixed identifier at the start of every Praxium API key. */
+declare const API_KEY_PREFIX: "praxium_v1";
+/** Separator used between all key segments. */
+declare const API_KEY_SEPARATOR: "_";
+/**
+ * Convenience composition: `praxium_v1_` (prefix + separator).
+ *
+ * Use this when validating that a string starts with the full Praxium API
+ * key prefix. Avoids re-composing `${API_KEY_PREFIX}${API_KEY_SEPARATOR}`
+ * at every call site. Compile-time `as const` so consumer Zod schemas can
+ * pass it to `.startsWith()` without widening to `string`.
+ */
+declare const API_KEY_PREFIX_WITH_SEPARATOR: "praxium_v1_";
+
 /**
  * Typed error hierarchy for the Praxium SDK.
  *
@@ -849,4 +863,4 @@ declare function getCustomField(member: MultilingualTeamMember, identifier: stri
  */
 declare function localizeText(text: MultilingualText | null | undefined, locale: SupportedLocale): string;
 
-export { type ApiError, type BilingualText, type BookableService, type BookableServices, type BookableVariantInfo, type BusinessName, type ClientLocale, type ContactDetails, type ContactFormResult, type CustomField, type FaqCategory, type FaqContent, type FaqGroup, type FaqItem, type FeatureItem, type FeatureList, type InsuranceInfo, type InsuranceList, type Location, type MultilingualCustomField, type MultilingualPraxiumClient, type MultilingualTeamMember, type MultilingualText, type OpeningHours, type PaymentMethod, type PaymentMethodList, type PolicyInfo, type PolicyList, PraxiumAuthError, type PraxiumClient, type PraxiumClientConfig, PraxiumError, PraxiumForbiddenError, PraxiumNotFoundError, PraxiumRateLimitError, PraxiumValidationError, type PricingVariant, type PricingVariants, type PublicDaySchedule, type PublicTeamMember, type ServiceCategoryInfo, type SocialLinks, type SupportedLocale, type TeamMembers, type ValidationDetail, createPraxiumClient, extractTenantSlugFromApiKey, getCustomField, getCustomFieldValue, localizeText };
+export { API_KEY_PREFIX, API_KEY_PREFIX_WITH_SEPARATOR, API_KEY_SEPARATOR, type ApiError, type BilingualText, type BookableService, type BookableServices, type BookableVariantInfo, type BusinessName, type ClientLocale, type ContactDetails, type ContactFormResult, type CustomField, type FaqCategory, type FaqContent, type FaqGroup, type FaqItem, type FeatureItem, type FeatureList, type InsuranceInfo, type InsuranceList, type Location, type MultilingualCustomField, type MultilingualPraxiumClient, type MultilingualTeamMember, type MultilingualText, type OpeningHours, type PaymentMethod, type PaymentMethodList, type PolicyInfo, type PolicyList, PraxiumAuthError, type PraxiumClient, type PraxiumClientConfig, PraxiumError, PraxiumForbiddenError, PraxiumNotFoundError, PraxiumRateLimitError, PraxiumValidationError, type PricingVariant, type PricingVariants, type PublicDaySchedule, type PublicTeamMember, type ServiceCategoryInfo, type SocialLinks, type SupportedLocale, type TeamMembers, type ValidationDetail, createPraxiumClient, extractTenantSlugFromApiKey, getCustomField, getCustomFieldValue, localizeText };

package/dist/index.js

@@ -928,16 +928,19 @@ var STATUS_ERROR_MAP = {
   429: PraxiumRateLimitError
 };
 
-// src/tenant-client.ts
+// src/api-key.constants.ts
 var API_KEY_PREFIX = "praxium_v1";
 var API_KEY_SEPARATOR = "_";
+var API_KEY_PREFIX_WITH_SEPARATOR = `${API_KEY_PREFIX}${API_KEY_SEPARATOR}`;
+
+// src/tenant-client.ts
 function extractTenantSlugFromApiKey(apiKey) {
   const parts = apiKey.split(API_KEY_SEPARATOR);
   if (parts.length < 6 || `${parts[0]}${API_KEY_SEPARATOR}${parts[1]}` !== API_KEY_PREFIX) {
     throw new PraxiumError(
       400,
       "INVALID_API_KEY_FORMAT",
-      `API key must start with '${API_KEY_PREFIX}' and contain at least 6 segments. Format: praxium_v1_{tenantSlug}_{profileSlug}_{timestamp}_{signature}`
+      `API key must start with '${API_KEY_PREFIX}' and contain at least 6 segments. Format: ${API_KEY_PREFIX}${API_KEY_SEPARATOR}{tenantSlug}${API_KEY_SEPARATOR}{profileSlug}${API_KEY_SEPARATOR}{timestamp}${API_KEY_SEPARATOR}{signature}`
     );
   }
   return parts[2];
@@ -1013,6 +1016,9 @@ function localizeText(text, locale) {
   return text[locale] || text["en"] || Object.values(text)[0] || "";
 }
 export {
+  API_KEY_PREFIX,
+  API_KEY_PREFIX_WITH_SEPARATOR,
+  API_KEY_SEPARATOR,
   PraxiumAuthError,
   PraxiumError,
   PraxiumForbiddenError,

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.85",
+  "version": "0.5.89",
   "description": "Official TypeScript SDK for the Praxium platform API",
   "type": "module",
   "exports": {
@@ -19,14 +19,18 @@
   "scripts": {
     "generate": "openapi-ts",
     "build": "tsup",
+    "lint": "eslint src/ tests/",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
     "@hey-api/openapi-ts": "^0.92.4",
+    "eslint": "^9.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {