@praxium/sdk 0.5.94 → 0.6.97

package/README.md

@@ -88,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:
@@ -116,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
  */
@@ -715,30 +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>;
-    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 {
-    getFaq: () => Promise<FaqContent>;
-    getTeamMembers: () => Promise<TeamMembers>;
+    getFaq: (options?: LocationFilterOptions) => Promise<FaqContent>;
+    getTeamMembers: (options?: LocationFilterOptions) => Promise<TeamMembers>;
 }
 /** Client for multilingual responses (locale='*') */
 interface MultilingualPraxiumClient extends PraxiumClientBase {
-    getFaq: () => Promise<MultilingualFaqContent>;
-    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 & {
@@ -891,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 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 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,34 +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 ───
-    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,
-      getFaq: () => getFaq({ client: clientInstance, path }).then(unwrapOrThrow),
-      getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow)
+      getFaq: (options) => getFaq(requestOptions(options)).then(unwrapOrThrow),
+      getTeamMembers: (options) => getTeamMembers(requestOptions(options)).then(unwrapOrThrow)
     };
   }
   return {
     ...baseMethods,
-    getFaq: () => getFaq({ client: clientInstance, path }).then(unwrapOrThrow),
-    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.94",
+  "version": "0.6.97",
   "description": "Official TypeScript SDK for the Praxium platform API",
   "type": "module",
   "exports": {