@praxium/sdk 0.5.91 → 0.6.97

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Learn more on the [Praxium developer platform](https://platform.praxium.nl).
+
 - [Quick Start](#quick-start) — Installation and usage examples
 - [Configuration](#configuration) — Environment variables and tenant routing
 - [Available Methods](#available-methods) — All API endpoints
@@ -31,6 +33,7 @@ const client = createPraxiumClient({
 const hours = await client.getOpeningHours()
 const team = await client.getTeamMembers()
 const faq = await client.getFaq()
+// FAQ category names, questions, and answers are strings in the requested locale.
 ```
 
 All methods return data directly or throw a typed `PraxiumError` on failure (see [Error Handling](#error-handling)).
@@ -39,6 +42,10 @@ All methods return data directly or throw a typed `PraxiumError` on failure (see
 
 Pass `locale: '*'` to receive all translations as objects. Resolve them at render time with `localizeText()`:
 
+When a method has a different response shape in multilingual mode, the SDK exposes that shape with a `Multilingual*` type. For example, `getTeamMembers()` returns `MultilingualTeamMember[]`, and `getFaq()` returns `MultilingualFaqContent`.
+
+`localizeText(text, locale)` resolves values in this order: requested locale, then English, then the first available value, then an empty string.
+
 ```typescript
 import { createPraxiumClient, localizeText } from '@praxium/sdk'
 
@@ -60,6 +67,9 @@ const team = await client.getTeamMembers()
 
 const label = localizeText(team[0].customFields[0].label, 'nl')  // → "Specialisatie"
 const value = localizeText(team[0].customFields[0].value, 'nl')  // → "Sport"
+
+const faq = await client.getFaq()
+const question = localizeText(faq[0].faqs[0].question, 'nl')
 ```
 
 ### Contact Form
@@ -78,6 +88,24 @@ const result = await client.submitContactForm({
 // → { success: true, emailStatus: 'sent' }
 ```
 
+### Multiple Locations
+
+Practices with more than one location expose each location under a stable slug. List them with `getLocations()`, then pass `{ location: slug }` to any location-aware method to narrow the response:
+
+```typescript
+const locations = await client.getLocations()
+// → [{ slug: 'centrum', name: 'Centrum', kind: 'PHYSICAL',
+//      phone: '...', email: '...', fullAddress: '...',
+//      openingHours: { schedule: [...], globalNote: null } }, ...]
+
+// Per-location data:
+const hours = await client.getOpeningHours({ location: 'zuid' })
+const team = await client.getTeamMembers({ location: 'zuid' })
+const services = await client.getBookableServices({ location: 'zuid' })
+```
+
+Without the filter, single-value methods (`getContactDetails`, `getLocation`, `getOpeningHours`, `getSocialLinks`) return the practice's main location, and collection methods (`getTeamMembers`, `getFaq`, `getServiceVariants`, `getBookableServices`) return the practice-wide data set. An unknown slug — or one outside your API key's location scope — throws `PraxiumNotFoundError` (HTTP 404).
+
 ## Configuration
 
 Your website needs two environment variables to connect to the Praxium platform, plus an optional third for webhook-based cache revalidation:
@@ -106,21 +134,24 @@ PRAXIUM_WEBHOOK_SECRET="your-webhook-secret-from-admin-portal"  # optional
 
 ## Available Methods
 
+Methods marked with `options?` accept an optional `{ location: slug }` filter — see [Multiple Locations](#multiple-locations).
+
 | Method | Description |
 |--------|-------------|
-| `getOpeningHours()` | Weekly opening schedule |
-| `getTeamMembers()` | Staff members with photos and custom fields |
-| `getContactDetails()` | Practice contact information |
-| `getLocation()` | Address and map coordinates |
+| `getLocations(options?)` | Practice locations with address, contact, and weekly hours |
+| `getOpeningHours(options?)` | Weekly opening schedule |
+| `getTeamMembers(options?)` | Staff members with photos and custom fields |
+| `getContactDetails(options?)` | Practice contact information |
+| `getLocation(options?)` | Address and map coordinates |
 | `getBusinessName()` | Practice display name |
-| `getSocialLinks()` | Social media URLs |
-| `getFaq()` | FAQ grouped by category |
-| `getServiceVariants()` | Service pricing and variants |
+| `getSocialLinks(options?)` | Social media URLs |
+| `getFaq(options?)` | FAQ grouped by category |
+| `getServiceVariants(options?)` | 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 |
+| `getBookableServices(options?)` | Services available for online booking |
 | `submitContactForm(body)` | Submit a contact form |
 
 ## Error Handling

package/dist/index.d.ts

@@ -145,6 +145,92 @@ type Location = {
      */
     accessibility: string | null;
 } | null;
+/**
+ * Practice locations ordered by display order, clamped to the API key location scope. Filter with ?location={slug} (unknown or out-of-scope slugs return 404).
+ */
+type Locations = Array<PublicLocationDetail>;
+/**
+ * One practice location: identity, address, contact, and weekly hours
+ */
+type PublicLocationDetail = {
+    /**
+     * URL-safe location identifier — the value the `location` query parameter accepts on every public endpoint
+     */
+    slug: string;
+    /**
+     * Location display name (localized)
+     */
+    name: string;
+    /**
+     * Location kind (e.g. PHYSICAL, MOBILE, VIRTUAL)
+     */
+    kind: string;
+    /**
+     * Location phone number
+     */
+    phone: string;
+    /**
+     * WhatsApp contact number
+     */
+    whatsappPhone: string;
+    /**
+     * Location email address
+     */
+    email: string;
+    /**
+     * Street address
+     */
+    address: string;
+    /**
+     * City name
+     */
+    city: string;
+    /**
+     * Postal/ZIP code
+     */
+    postalCode: string;
+    /**
+     * Country name (localized)
+     */
+    country: string;
+    /**
+     * Complete formatted address
+     */
+    fullAddress: string;
+    /**
+     * GPS latitude coordinate
+     */
+    latitude: number | null;
+    /**
+     * GPS longitude coordinate
+     */
+    longitude: number | null;
+    /**
+     * Google Maps URL for this location
+     */
+    googleMapsUrl: string | null;
+    /**
+     * Parking information (localized)
+     */
+    parkingInfo: string | null;
+    /**
+     * Accessibility information (localized)
+     */
+    accessibility: string | null;
+    /**
+     * Weekly opening hours for this location
+     */
+    openingHours: {
+        /**
+         * Weekly schedule (7 entries)
+         */
+        schedule: Array<PublicDaySchedule>;
+        /**
+         * General note about opening hours
+         */
+        globalNote: string | null;
+    };
+};
 /**
  * Practice business name
  */
@@ -239,7 +325,7 @@ type FaqGroup = {
     faqs: Array<FaqItem>;
 };
 /**
- * FAQ category with bilingual name
+ * FAQ category
  */
 type FaqCategory = {
     /**
@@ -247,11 +333,9 @@ type FaqCategory = {
      */
     id: string;
     /**
-     * Category name per locale
+     * Category name resolved to requested locale
      */
-    name: {
-        [key: string]: string;
-    };
+    name: string;
     /**
      * Display order (ascending)
      */
@@ -266,17 +350,13 @@ type FaqItem = {
      */
     id: string;
     /**
-     * Question text per locale
+     * Question text resolved to requested locale
      */
-    question: {
-        [key: string]: string;
-    };
+    question: string;
     /**
-     * Answer text per locale (may contain HTML)
+     * Answer text resolved to requested locale (may contain HTML)
      */
-    answer: {
-        [key: string]: string;
-    };
+    answer: string;
     /**
      * Parent category UUID
      */
@@ -659,6 +739,39 @@ type MultilingualTeamMember = {
     /** Custom fields with multilingual labels and values */
     customFields: Array<MultilingualCustomField>;
 };
+/** FAQ category in locale='*' mode. */
+type MultilingualFaqCategory = {
+    /** Category UUID */
+    id: string;
+    /** Category name in all available locales */
+    name: MultilingualText;
+    /** Display order (ascending) */
+    order: number;
+};
+/** FAQ item in locale='*' mode. */
+type MultilingualFaqItem = {
+    /** FAQ item UUID */
+    id: string;
+    /** Question text in all available locales */
+    question: MultilingualText;
+    /** Answer text in all available locales (may contain HTML) */
+    answer: MultilingualText;
+    /** Parent category UUID */
+    categoryId: string;
+    /** Display order within category (ascending) */
+    order: number;
+    /** Whether this FAQ item is currently visible */
+    visible: boolean;
+};
+/** FAQ category group in locale='*' mode. */
+type MultilingualFaqGroup = {
+    /** The FAQ category */
+    category: MultilingualFaqCategory;
+    /** FAQ items in this category */
+    faqs: Array<MultilingualFaqItem>;
+};
+/** FAQ content in locale='*' mode. */
+type MultilingualFaqContent = Array<MultilingualFaqGroup>;
 
 /**
  * Supported locale codes for server-side content resolution.
@@ -688,29 +801,49 @@ interface PraxiumClientConfig {
     /** Locale for server-side content resolution */
     locale: ClientLocale;
 }
+/**
+ * Options accepted by every location-aware read method.
+ *
+ * Multi-location practices expose each location under a stable slug
+ * (see `getLocations()` — the `slug` field of each entry). Passing
+ * `{ location: slug }` narrows the response to that location, within
+ * the location scope of your API key. An unknown or out-of-scope slug
+ * rejects with `PraxiumNotFoundError` (HTTP 404).
+ *
+ * Omitting the filter keeps the default behavior: the practice's main
+ * location for single-value endpoints (contact details, address,
+ * opening hours, social links), and the practice-wide data set for
+ * collections (team, FAQ, services, prices).
+ */
+interface LocationFilterOptions {
+    /** Location slug (e.g., 'zuid') from `getLocations()`. */
+    location?: string;
+}
 /** Shared methods available on both client types */
 interface PraxiumClientBase {
-    getOpeningHours: () => Promise<OpeningHours>;
-    getContactDetails: () => Promise<ContactDetails>;
-    getLocation: () => Promise<Location>;
+    getOpeningHours: (options?: LocationFilterOptions) => Promise<OpeningHours>;
+    getContactDetails: (options?: LocationFilterOptions) => Promise<ContactDetails>;
+    getLocation: (options?: LocationFilterOptions) => Promise<Location>;
+    getLocations: (options?: LocationFilterOptions) => Promise<Locations>;
     getBusinessName: () => Promise<BusinessName>;
-    getSocialLinks: () => Promise<SocialLinks>;
-    getFaq: () => Promise<FaqContent>;
-    getServiceVariants: () => Promise<PricingVariants>;
+    getSocialLinks: (options?: LocationFilterOptions) => Promise<SocialLinks>;
+    getServiceVariants: (options?: LocationFilterOptions) => Promise<PricingVariants>;
     getInsuranceInfo: () => Promise<InsuranceList>;
     getFeatures: () => Promise<FeatureList>;
     getPaymentMethods: () => Promise<PaymentMethodList>;
     getPolicyInfo: () => Promise<PolicyList>;
-    getBookableServices: () => Promise<BookableServices>;
+    getBookableServices: (options?: LocationFilterOptions) => Promise<BookableServices>;
     submitContactForm: (body: SubmitContactFormData['body']) => Promise<ContactFormResult>;
 }
 /** Client for locale-specific responses (locale='nl', 'en', etc.) */
 interface PraxiumClient extends PraxiumClientBase {
-    getTeamMembers: () => Promise<TeamMembers>;
+    getFaq: (options?: LocationFilterOptions) => Promise<FaqContent>;
+    getTeamMembers: (options?: LocationFilterOptions) => Promise<TeamMembers>;
 }
 /** Client for multilingual responses (locale='*') */
 interface MultilingualPraxiumClient extends PraxiumClientBase {
-    getTeamMembers: () => Promise<MultilingualTeamMember[]>;
+    getFaq: (options?: LocationFilterOptions) => Promise<MultilingualFaqContent>;
+    getTeamMembers: (options?: LocationFilterOptions) => Promise<MultilingualTeamMember[]>;
 }
 /** Multilingual mode: returns MultilingualTeamMember[] (use localizeText() helper for resolution) */
 declare function createPraxiumClient(config: PraxiumClientConfig & {
@@ -863,4 +996,4 @@ declare function getCustomField(member: MultilingualTeamMember, identifier: stri
  */
 declare function localizeText(text: MultilingualText | null | undefined, locale: SupportedLocale): string;
 
-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 };
+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 LocationFilterOptions, type Locations, type MultilingualCustomField, type MultilingualFaqCategory, type MultilingualFaqContent, type MultilingualFaqGroup, type MultilingualFaqItem, 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 PublicLocationDetail, type PublicTeamMember, type ServiceCategoryInfo, type SocialLinks, type SupportedLocale, type TeamMembers, type ValidationDetail, createPraxiumClient, extractTenantSlugFromApiKey, getCustomField, getCustomFieldValue, localizeText };

package/dist/index.js

@@ -827,6 +827,11 @@ var getLocation = (options) => (options.client ?? client).get({
   url: "/api/{tenantSlug}/location",
   ...options
 });
+var getLocations = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/api/{tenantSlug}/locations",
+  ...options
+});
 var getBusinessName = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/api/{tenantSlug}/business",
@@ -973,33 +978,42 @@ function createPraxiumClient(config) {
     return request;
   });
   const path = { tenantSlug };
+  const baseRequest = { client: clientInstance, path };
+  const requestOptions = (options) => ({
+    ...baseRequest,
+    ...options?.location !== void 0 && {
+      query: { location: options.location }
+    }
+  });
   const baseMethods = {
     // ─── Layout Endpoints ───
-    getOpeningHours: () => getOpeningHours({ client: clientInstance, path }).then(unwrapOrThrow),
-    getContactDetails: () => getContactDetails({ client: clientInstance, path }).then(unwrapOrThrow),
-    getLocation: () => getLocation({ client: clientInstance, path }).then(unwrapOrThrow),
-    getBusinessName: () => getBusinessName({ client: clientInstance, path }).then(unwrapOrThrow),
-    getSocialLinks: () => getSocialLinks({ client: clientInstance, path }).then(unwrapOrThrow),
+    getOpeningHours: (options) => getOpeningHours(requestOptions(options)).then(unwrapOrThrow),
+    getContactDetails: (options) => getContactDetails(requestOptions(options)).then(unwrapOrThrow),
+    getLocation: (options) => getLocation(requestOptions(options)).then(unwrapOrThrow),
+    getLocations: (options) => getLocations(requestOptions(options)).then(unwrapOrThrow),
+    getBusinessName: () => getBusinessName(baseRequest).then(unwrapOrThrow),
+    getSocialLinks: (options) => getSocialLinks(requestOptions(options)).then(unwrapOrThrow),
     // ─── Content Endpoints ───
-    getFaq: () => getFaq({ client: clientInstance, path }).then(unwrapOrThrow),
-    getServiceVariants: () => getServiceVariants({ client: clientInstance, path }).then(unwrapOrThrow),
-    getInsuranceInfo: () => getInsuranceInfo({ client: clientInstance, path }).then(unwrapOrThrow),
-    getFeatures: () => getFeatures({ client: clientInstance, path }).then(unwrapOrThrow),
-    getPaymentMethods: () => getPaymentMethods({ client: clientInstance, path }).then(unwrapOrThrow),
-    getPolicyInfo: () => getPolicyInfo({ client: clientInstance, path }).then(unwrapOrThrow),
-    getBookableServices: () => getBookableServices({ client: clientInstance, path }).then(unwrapOrThrow),
+    getServiceVariants: (options) => getServiceVariants(requestOptions(options)).then(unwrapOrThrow),
+    getInsuranceInfo: () => getInsuranceInfo(baseRequest).then(unwrapOrThrow),
+    getFeatures: () => getFeatures(baseRequest).then(unwrapOrThrow),
+    getPaymentMethods: () => getPaymentMethods(baseRequest).then(unwrapOrThrow),
+    getPolicyInfo: () => getPolicyInfo(baseRequest).then(unwrapOrThrow),
+    getBookableServices: (options) => getBookableServices(requestOptions(options)).then(unwrapOrThrow),
     // ─── Contact Form ───
-    submitContactForm: (body) => submitContactForm({ client: clientInstance, path, body }).then(unwrapOrThrow)
+    submitContactForm: (body) => submitContactForm({ ...baseRequest, body }).then(unwrapOrThrow)
   };
   if (config.locale === "*") {
     return {
       ...baseMethods,
-      getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow)
+      getFaq: (options) => getFaq(requestOptions(options)).then(unwrapOrThrow),
+      getTeamMembers: (options) => getTeamMembers(requestOptions(options)).then(unwrapOrThrow)
     };
   }
   return {
     ...baseMethods,
-    getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow)
+    getFaq: (options) => getFaq(requestOptions(options)).then(unwrapOrThrow),
+    getTeamMembers: (options) => getTeamMembers(requestOptions(options)).then(unwrapOrThrow)
   };
 }
 

package/package.json

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