@praxium/sdk 0.3.51 → 0.3.56

package/README.md

@@ -1,6 +1,6 @@
 # @praxium/sdk
 
-Official TypeScript SDK for the Praxium platform API.
+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
 
@@ -8,37 +8,43 @@ Official TypeScript SDK for the Praxium platform API.
 npm install @praxium/sdk
 ```
 
-## Usage
+## Quick Start
 
 ### Locale-Specific Mode
 
+Pass a locale to get pre-resolved labels and values in that language:
+
 ```typescript
 import { createPraxiumClient } from '@praxium/sdk'
 
 const client = createPraxiumClient({
-  baseUrl: process.env.PRAXIUM_API_URL!,   // 'https://platform.praxium.nl'
-  apiKey: process.env.PRAXIUM_API_KEY!,     // tenant slug extracted from key automatically
-  locale: 'nl',                             // 'nl' | 'en' | '*' (multilingual)
+  baseUrl: process.env.PRAXIUM_API_URL!,
+  apiKey: process.env.PRAXIUM_API_KEY!,
+  locale: 'nl',  // 'nl' | 'en' | '*' (see Multilingual Mode)
 })
 
-// Returns data directly — throws PraxiumError on failure
 const hours = await client.getOpeningHours()
 const team = await client.getTeamMembers()
+const faq = await client.getFaq()
 ```
 
+All methods return data directly or throw a typed `PraxiumError` on failure (see [Error Handling](#error-handling)).
+
 ### Multilingual Mode
 
+Pass `locale: '*'` to receive all translations as objects. Resolve them at render time with `localizeText()`:
+
 ```typescript
 import { createPraxiumClient, localizeText } from '@praxium/sdk'
 
 const client = createPraxiumClient({
   baseUrl: process.env.PRAXIUM_API_URL!,
   apiKey: process.env.PRAXIUM_API_KEY!,
-  locale: '*',  // returns all translations
+  locale: '*',
 })
 
 const team = await client.getTeamMembers()
-// Returns MultilingualTeamMember[] — labels/values are { nl: "...", en: "..." } objects:
+// Returns MultilingualTeamMember[] — labels and values are multilingual objects:
 // {
 //   name: "Dr. Jan de Vries",
 //   role: "Fysiotherapeut",
@@ -47,27 +53,76 @@ const team = await client.getTeamMembers()
 //   ]
 // }
 
-// Resolve multilingual text to a specific locale at render time
 const label = localizeText(team[0].customFields[0].label, 'nl')  // → "Specialisatie"
 const value = localizeText(team[0].customFields[0].value, 'nl')  // → "Sport"
 ```
 
 ### Contact Form
 
+Submit a contact form on behalf of a website visitor:
+
 ```typescript
 const result = await client.submitContactForm({
   name: 'Jan de Vries',
   email: 'jan@example.nl',
   phone: '+31612345678',
-  subject: 'Afspraak maken',
-  message: 'Ik wil graag een afspraak maken.',
+  subject: 'Appointment request',
+  message: 'I would like to book an appointment.',
 })
 // → { success: true, emailStatus: 'sent' }
 ```
 
-## Next.js Revalidation
+## Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `getOpeningHours()` | Weekly opening schedule |
+| `getTeamMembers()` | Staff members with photos and custom fields |
+| `getContactDetails()` | Practice contact information |
+| `getLocation()` | Address and map coordinates |
+| `getBusinessName()` | Practice display name |
+| `getSocialLinks()` | Social media URLs |
+| `getFaq()` | FAQ grouped by category |
+| `getServiceVariants()` | Service pricing and variants |
+| `getInsuranceInfo()` | Accepted insurance providers |
+| `getFeatures()` | Practice features and amenities |
+| `getPaymentMethods()` | Accepted payment methods |
+| `getPolicyInfo()` | Practice policies |
+| `getBookableServices()` | Services available for online booking |
+| `submitContactForm(body)` | Submit a contact form |
+
+## Error Handling
+
+All methods throw typed errors that you can catch individually:
 
-Tenant websites use Next.js ISR (Incremental Static Regeneration) for performance. When an admin updates data (team, FAQ, opening hours), a webhook triggers on-demand ISR revalidation on the tenant website. The SDK handles HMAC signature verification and path resolution.
+```typescript
+import { PraxiumNotFoundError, PraxiumAuthError } from '@praxium/sdk'
+
+try {
+  const team = await client.getTeamMembers()
+} catch (error) {
+  if (error instanceof PraxiumNotFoundError) {
+    // 404 — resource not found
+  } else if (error instanceof PraxiumAuthError) {
+    // 401 — invalid or expired API key
+  }
+}
+```
+
+| Error Class | HTTP Status | When |
+|-------------|-------------|------|
+| `PraxiumAuthError` | 401 | Invalid API key |
+| `PraxiumForbiddenError` | 403 | Key doesn't match tenant |
+| `PraxiumNotFoundError` | 404 | Resource not found |
+| `PraxiumValidationError` | 400 | Invalid request data |
+| `PraxiumRateLimitError` | 429 | Too many requests |
+| `PraxiumError` | Other | Base class for all errors |
+
+## Next.js ISR Revalidation
+
+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
@@ -75,20 +130,24 @@ 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
   },
 })
 ```
 
-Security: HMAC-SHA256 signature verification, timestamp-based replay protection (5-min window), timing-safe comparison. Requires `next` as peer dependency.
+**Prerequisites:** Register your revalidation endpoint URL in the admin portal (Settings → Webhooks) before the platform can send webhook events to your website.
+
+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.51",
+  "version": "0.3.56",
   "description": "Official TypeScript SDK for the Praxium platform API",
   "type": "module",
   "exports": {