@praxium/sdk 0.3.56 → 0.3.66

package/README.md

@@ -2,14 +2,19 @@
 
 Official TypeScript SDK for the [Praxium](https://praxium.nl) platform API. Build tenant websites that display practice data (team, services, FAQ, opening hours) with full locale support.
 
-## Installation
+- [Quick Start](#quick-start) — Installation and usage examples
+- [Configuration](#configuration) — Environment variables and tenant routing
+- [Available Methods](#available-methods) — All API endpoints
+- [Error Handling](#error-handling) — Typed error classes
+- [Webhooks](#webhooks) — React to entity changes (ISR revalidation, cache busting, etc.)
+- [Contributing](#contributing) — Development commands
+
+## Quick Start
 
 ```bash
 npm install @praxium/sdk
 ```
 
-## Quick Start
-
 ### Locale-Specific Mode
 
 Pass a locale to get pre-resolved labels and values in that language:
@@ -72,6 +77,32 @@ const result = await client.submitContactForm({
 // → { success: true, emailStatus: 'sent' }
 ```
 
+## Configuration
+
+Your website needs two environment variables to connect to the Praxium platform, plus an optional third for webhook-based cache revalidation:
+
+**Required:**
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `PRAXIUM_API_URL` | Your tenant's admin portal URL. The SDK sends API requests to this host. | `https://ijfysio.admin.praxium.nl` |
+| `PRAXIUM_API_KEY` | HMAC API key for authentication. Generated in the admin portal under API Profiles. The tenant slug is embedded in the key — no need to configure it separately. | `hmac_v1_ijfysio_default_17..._abc...` |
+
+**Optional (only if using ISR revalidation webhooks):**
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `PRAXIUM_WEBHOOK_SECRET` | Shared secret for webhook signature verification. Only needed if you want the platform to notify your site when data changes (team, FAQ, opening hours). See [Webhooks](#webhooks). | (32+ character random string) |
+
+```bash
+# .env.local
+PRAXIUM_API_URL="https://mypractice.admin.praxium.nl"
+PRAXIUM_API_KEY="hmac_v1_mypractice_default_1234567890_abcdef..."
+PRAXIUM_WEBHOOK_SECRET="your-webhook-secret-from-admin-portal"  # optional
+```
+
+> **How tenant routing works:** Each tenant has its own admin subdomain (`{slug}.admin.praxium.nl`). The platform identifies your tenant from both the hostname AND the API key's embedded slug, cross-validating them for security. You don't need to configure the tenant slug separately — it's derived from your API key automatically.
+
 ## Available Methods
 
 | Method | Description |
@@ -118,21 +149,39 @@ try {
 | `PraxiumRateLimitError` | 429 | Too many requests |
 | `PraxiumError` | Other | Base class for all errors |
 
-## Next.js ISR Revalidation
+## Webhooks
+
+When an admin updates data (team, FAQ, opening hours), the platform sends an HMAC-signed webhook to your registered endpoint. You can use this to react to entity changes in any way your application needs.
+
+**Common use cases:**
 
-For websites using Next.js [ISR (Incremental Static Regeneration)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration), the SDK provides a webhook handler for on-demand cache revalidation. When an admin updates data (team, FAQ, opening hours), the platform sends an HMAC-signed webhook to your revalidation endpoint. The handler verifies the signature and calls `revalidatePath()` for the affected pages.
+| Use Case | What you do on entity change |
+|----------|------------------------------|
+| **ISR revalidation** | Call `revalidatePath()` to refresh cached pages |
+| **Search index** | Re-index changed entities in your search engine |
+| **CDN cache** | Purge cached API responses or assets |
+
+**Prerequisites:**
+
+1. Register your webhook endpoint URL in the admin portal (Settings → Webhooks)
+2. Set `PRAXIUM_WEBHOOK_SECRET` to the shared secret from the admin portal
+
+All webhook handlers include HMAC-SHA256 signature verification, timestamp-based replay protection (5-minute window), and timing-safe comparison.
+
+### Next.js ISR Revalidation
+
+The SDK provides a ready-made handler for Next.js [ISR](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) revalidation. It verifies the webhook signature and calls `revalidatePath()` for the affected pages.
 
 The `pathMap` is fully customizable — you define which pages to revalidate for each entity based on your website's routing structure:
 
 ```typescript
 // app/api/revalidate/route.ts
-import { createRevalidationHandler } from '@praxium/sdk/revalidation'
+import { createRevalidationHandler } from '@praxium/sdk/webhooks'
 
 export const POST = createRevalidationHandler({
-  secret: process.env.PRAXIUM_REVALIDATION_SECRET!,
+  secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
   // Map platform entities to YOUR website's page paths.
-  // These are specific to your project's routing structure —
-  // adjust the paths to match your pages.
+  // Adjust the paths to match your project's routing structure.
   pathMap: {
     'team': ['/nl/team', '/en/team'],
     'rates': ['/nl/tarieven', '/en/rates'],
@@ -143,9 +192,35 @@ export const POST = createRevalidationHandler({
 })
 ```
 
-**Prerequisites:** Register your revalidation endpoint URL in the admin portal (Settings → Webhooks) before the platform can send webhook events to your website.
+Requires `next` as a peer dependency.
+
+### Custom Webhook Handler
+
+For non-Next.js use cases or custom logic, use `processWebhook()` to verify the signature and extract the changed entity:
+
+```typescript
+// Example: invalidate a Redis cache on entity change
+import { processWebhook, WEBHOOK_SIGNATURE_HEADER } from '@praxium/sdk/webhooks'
+
+export async function POST(request: Request) {
+  const body = await request.text()
+
+  const result = await processWebhook({
+    body,
+    signature: request.headers.get(WEBHOOK_SIGNATURE_HEADER)!,
+    secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
+  })
+
+  if (!result.valid) {
+    return new Response(result.error, { status: 401 })
+  }
+
+  // result.entity = 'team' | 'faq' | 'rates' | ...
+  await redis.del(`cache:${result.entity}`)
 
-The handler includes HMAC-SHA256 signature verification, timestamp-based replay protection (5-minute window), and timing-safe comparison. Requires `next` as a peer dependency.
+  return new Response('OK')
+}
+```
 
 ## Contributing
 

package/dist/webhooks.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Praxium Webhook Utilities
+ *
+ * Process and verify webhooks sent by the Praxium platform when entity
+ * data changes (team, FAQ, opening hours, etc.).
+ *
+ * Two levels of abstraction:
+ *
+ * **`processWebhook()`** — Framework-agnostic. Verifies HMAC signature,
+ * checks timestamp freshness, parses the body, and returns the entity
+ * that changed. Use this with Express, Fastify, or any custom handler.
+ *
+ * **`createRevalidationHandler()`** — Next.js-specific. Wraps processWebhook
+ * with path resolution and `revalidatePath()` calls. Returns a ready-made
+ * route handler for `app/api/revalidate/route.ts`.
+ *
+ * Signature scheme (H6):
+ *   X-Praxium-Signature: t={unix_timestamp},sha256={HMAC-SHA256(secret, timestamp.body)}
+ *
+ * Security features:
+ *   - HMAC-SHA256 signature verification (secret never sent in body)
+ *   - Timestamp-based replay protection (default 5-minute window)
+ *   - Timing-safe signature comparison (prevents timing side-channel attacks)
+ *   - Web Crypto API (platform-agnostic: Edge, Node.js, browser)
+ *
+ * @example
+ * // Framework-agnostic (Express, Fastify, etc.):
+ * import { processWebhook } from '@praxium/sdk/webhooks'
+ *
+ * const result = await processWebhook({
+ *   body: rawBody,
+ *   signature: req.headers['x-praxium-signature'],
+ *   secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
+ * })
+ * if (result.valid) console.log('Entity changed:', result.entity)
+ *
+ * @example
+ * // Next.js ISR revalidation:
+ * import { createRevalidationHandler } from '@praxium/sdk/webhooks'
+ *
+ * export const POST = createRevalidationHandler({
+ *   secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
+ *   pathMap: { 'team': ['/nl/team', '/en/team'] },
+ * })
+ */
+/** Header name for the HMAC signature */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Praxium-Signature";
+/** Input for processWebhook() */
+interface ProcessWebhookInput {
+    /** Raw request body as string */
+    body: string;
+    /** Value of the X-Praxium-Signature header */
+    signature: string;
+    /** Shared secret for HMAC verification */
+    secret: string;
+    /** Maximum age of request timestamp in milliseconds (default: 5 minutes) */
+    maxTimestampAge?: number;
+}
+/** Successful webhook processing result */
+interface WebhookSuccess {
+    valid: true;
+    /** Entity type that changed (e.g., 'team', 'rates', 'faq') */
+    entity: string | undefined;
+}
+/** Failed webhook processing result */
+interface WebhookFailure {
+    valid: false;
+    /** Human-readable error description */
+    error: string;
+}
+/** Result of processWebhook() */
+type WebhookResult = WebhookSuccess | WebhookFailure;
+/** Configuration for createRevalidationHandler() */
+interface RevalidationConfig {
+    /** Shared secret for HMAC signature verification */
+    secret: string;
+    /** Maximum age of request timestamp in milliseconds (default: 5 minutes) */
+    maxTimestampAge?: number;
+    /**
+     * Entity → full paths to revalidate (including locale prefix).
+     *
+     * Paths are specific to YOUR website's routing structure.
+     * When a webhook arrives with `{ entity: 'team' }`, the handler looks up
+     * `pathMap['team']` and calls `revalidatePath()` for each path.
+     *
+     * Unknown entities fall back to revalidating ALL registered paths.
+     *
+     * @example
+     * pathMap: {
+     *   'team': ['/nl/team', '/en/team'],
+     *   'rates': ['/nl/tarieven', '/en/rates'],
+     *   'opening-hours': ['/nl', '/en'],
+     * }
+     */
+    pathMap: Record<string, string[]>;
+}
+/**
+ * Process and verify a Praxium platform webhook.
+ *
+ * Verifies the HMAC-SHA256 signature, checks timestamp freshness (replay
+ * protection), and parses the webhook body to extract the changed entity.
+ *
+ * Use this for custom webhook handling in any framework (Express, Fastify,
+ * Deno, etc.). For Next.js ISR revalidation, use createRevalidationHandler()
+ * which wraps this with path resolution and revalidatePath() calls.
+ *
+ * @example
+ * ```typescript
+ * import { processWebhook } from '@praxium/sdk/webhooks'
+ *
+ * const result = await processWebhook({
+ *   body: rawBody,
+ *   signature: req.headers['x-praxium-signature'],
+ *   secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
+ * })
+ *
+ * if (result.valid) {
+ *   await redis.del(`cache:${result.entity}`)
+ * }
+ * ```
+ */
+declare function processWebhook(input: ProcessWebhookInput): Promise<WebhookResult>;
+/**
+ * Resolve entity to revalidation paths using the pathMap.
+ *
+ * Resolution priority:
+ * 1. pathMap[entity] → pre-computed paths for this entity
+ * 2. Unknown/missing entity → deduplicated union of ALL pathMap values
+ */
+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 a Praxium platform webhook.
+ *
+ * Wraps processWebhook() with path resolution and revalidatePath() calls.
+ * Returns a Fetch API handler `(request: Request) => Promise<Response>`
+ * compatible with Next.js App Router route exports.
+ *
+ * @example
+ * ```typescript
+ * // app/api/revalidate/route.ts
+ * import { createRevalidationHandler } from '@praxium/sdk/webhooks'
+ *
+ * export const POST = createRevalidationHandler({
+ *   secret: process.env.PRAXIUM_WEBHOOK_SECRET!,
+ *   pathMap: {
+ *     'team': ['/nl/team', '/en/team'],
+ *     'rates': ['/nl/tarieven', '/en/rates'],
+ *     'faq': ['/nl/faq', '/en/faq'],
+ *     'opening-hours': ['/nl', '/en'],
+ *   },
+ * })
+ * ```
+ */
+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 };

package/dist/{revalidation.js → webhooks.js}

@@ -1,5 +1,5 @@
-// src/revalidation.ts
-var SIGNATURE_HEADER = "X-Praxium-Signature";
+// src/webhooks.ts
+var WEBHOOK_SIGNATURE_HEADER = "X-Praxium-Signature";
 var DEFAULT_MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1e3;
 var CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1e3;
 async function computeHmacSignature(secret, payload) {
@@ -46,6 +46,36 @@ function parseSignatureHeader(headerValue) {
     signature: signatureMatch[1]
   };
 }
+async function processWebhook(input) {
+  const {
+    body,
+    signature: signatureHeader,
+    secret,
+    maxTimestampAge = DEFAULT_MAX_TIMESTAMP_AGE_MS
+  } = input;
+  const parsed = parseSignatureHeader(signatureHeader);
+  if (!parsed) {
+    return { valid: false, error: "Invalid signature format" };
+  }
+  const requestAgeMs = Date.now() - parsed.timestamp * 1e3;
+  if (requestAgeMs < -CLOCK_SKEW_TOLERANCE_MS) {
+    return { valid: false, error: "Request timestamp is in the future" };
+  }
+  if (requestAgeMs > maxTimestampAge) {
+    return { valid: false, error: "Request timestamp expired" };
+  }
+  const payload = `${parsed.timestamp}.${body}`;
+  const expectedSignature = await computeHmacSignature(secret, payload);
+  if (!isSecretValid(parsed.signature, expectedSignature)) {
+    return { valid: false, error: "Invalid signature" };
+  }
+  try {
+    const parsedBody = body ? JSON.parse(body) : {};
+    return { valid: true, entity: parsedBody.entity };
+  } catch {
+    return { valid: false, error: "Invalid JSON body" };
+  }
+}
 function resolveRevalidationPaths(entity, pathMap) {
   if (entity && pathMap[entity]) {
     return { paths: pathMap[entity], fallback: false };
@@ -54,60 +84,32 @@ function resolveRevalidationPaths(entity, pathMap) {
   return { paths: allPaths, fallback: true };
 }
 function createRevalidationHandler(config) {
-  const maxTimestampAge = config.maxTimestampAge ?? DEFAULT_MAX_TIMESTAMP_AGE_MS;
   return async (request) => {
-    const signatureHeader = request.headers.get(SIGNATURE_HEADER);
+    const signatureHeader = request.headers.get(WEBHOOK_SIGNATURE_HEADER);
     if (!signatureHeader) {
       return Response.json(
-        { error: `Missing ${SIGNATURE_HEADER} header` },
-        { status: 401 }
-      );
-    }
-    const parsed = parseSignatureHeader(signatureHeader);
-    if (!parsed) {
-      return Response.json(
-        { error: "Invalid signature format" },
-        { status: 401 }
-      );
-    }
-    const requestAgeMs = Date.now() - parsed.timestamp * 1e3;
-    if (requestAgeMs < -CLOCK_SKEW_TOLERANCE_MS) {
-      return Response.json(
-        { error: "Request timestamp is in the future" },
-        { status: 401 }
-      );
-    }
-    if (requestAgeMs > maxTimestampAge) {
-      return Response.json(
-        { error: "Request timestamp expired" },
+        { error: `Missing ${WEBHOOK_SIGNATURE_HEADER} header` },
         { status: 401 }
       );
     }
     const rawBody = await request.text();
-    const payload = `${parsed.timestamp}.${rawBody}`;
-    const expectedSignature = await computeHmacSignature(
-      config.secret,
-      payload
-    );
-    if (!isSecretValid(parsed.signature, expectedSignature)) {
-      return Response.json(
-        { error: "Invalid signature" },
-        { status: 401 }
-      );
-    }
-    let body;
-    try {
-      body = rawBody ? JSON.parse(rawBody) : {};
-    } catch {
-      return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+    const result = await processWebhook({
+      body: rawBody,
+      signature: signatureHeader,
+      secret: config.secret,
+      maxTimestampAge: config.maxTimestampAge
+    });
+    if (!result.valid) {
+      const status = result.error === "Invalid JSON body" ? 400 : 401;
+      return Response.json({ error: result.error }, { status });
     }
     const { paths, fallback } = resolveRevalidationPaths(
-      body.entity,
+      result.entity,
       config.pathMap
     );
     if (fallback) {
       console.warn(
-        `[Revalidation] Unknown entity "${body.entity ?? "(none)"}" \u2014 falling back to full revalidation (${paths.length} paths)`
+        `[Webhook] Unknown entity "${result.entity ?? "(none)"}" \u2014 falling back to full revalidation (${paths.length} paths)`
       );
     }
     try {
@@ -125,6 +127,8 @@ function createRevalidationHandler(config) {
   };
 }
 export {
+  WEBHOOK_SIGNATURE_HEADER,
   createRevalidationHandler,
+  processWebhook,
   resolveRevalidationPaths
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxium/sdk",
-  "version": "0.3.56",
+  "version": "0.3.66",
   "description": "Official TypeScript SDK for the Praxium platform API",
   "type": "module",
   "exports": {
@@ -8,9 +8,9 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./revalidation": {
-      "import": "./dist/revalidation.js",
-      "types": "./dist/revalidation.d.ts"
+    "./webhooks": {
+      "import": "./dist/webhooks.js",
+      "types": "./dist/webhooks.d.ts"
     }
   },
   "files": [
@@ -18,8 +18,8 @@
   ],
   "scripts": {
     "generate": "openapi-ts",
-    "build": "tsup src/index.ts src/revalidation.ts --format esm --dts --clean --external next",
-    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/dist/revalidation.d.ts

@@ -1,95 +0,0 @@
-/**
- * ISR Revalidation Handler for Tenant Websites
- *
- * When admin updates data in the platform, a webhook triggers
- * 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)}
- *
- * Security features:
- *   - HMAC-SHA256 signature verification (secret never sent in body)
- *   - Timestamp-based replay protection (default 5-minute window)
- *   - Timing-safe signature comparison (prevents timing side-channel attacks)
- *   - Web Crypto API (platform-agnostic: Edge, Node.js, browser)
- *
- * Usage in tenant website's `app/api/revalidate/route.ts`:
- *
- * ```ts
- * import { createRevalidationHandler } from '@praxium/sdk/revalidation'
- *
- * 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'],
- *   },
- * })
- * ```
- */
-interface RevalidationConfig {
-    /** Shared secret for HMAC signature verification */
-    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, resolveRevalidationPaths };