@praxium/sdk 0.3.52 → 0.3.61

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
+- [Next.js ISR Revalidation](#nextjs-isr-revalidation) — Webhook-based cache invalidation
+- [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_REVALIDATION_SECRET` | Shared secret for webhook signature verification. Only needed if your website uses ISR and you want the platform to notify your site when data changes (team, FAQ, opening hours). See [Next.js ISR Revalidation](#nextjs-isr-revalidation). | (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_REVALIDATION_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 |
@@ -122,28 +153,35 @@ try {
 
 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.
 
+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'
 
 export const POST = createRevalidationHandler({
   secret: process.env.PRAXIUM_REVALIDATION_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.
   pathMap: {
-    // entity → locale-prefixed paths to revalidate
     'team': ['/nl/team', '/en/team'],
     'rates': ['/nl/tarieven', '/en/rates'],
     'faq': ['/nl/faq', '/en/faq'],
-    'opening-hours': ['/nl', '/en'],
-    'all': ['/nl', '/en'],
+    'opening-hours': ['/nl', '/en'],    // homepage shows opening hours
+    'all': ['/nl', '/en'],              // full-site revalidation
   },
 })
 ```
 
-**Prerequisites:** Register your revalidation endpoint URL in the admin portal (Settings → Webhooks) before the platform can send webhook events to your website.
+**Prerequisites:**
+
+1. Register your revalidation endpoint URL in the admin portal (Settings → Webhooks)
+2. Set the `PRAXIUM_REVALIDATION_SECRET` env var to match the webhook secret from the admin portal
 
 The handler includes HMAC-SHA256 signature verification, timestamp-based replay protection (5-minute window), and timing-safe comparison. Requires `next` as a peer dependency.
 
-## Development
+## Contributing
 
 ```bash
 npm run generate   # Regenerate client from OpenAPI spec

package/package.json

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