@praxium/sdk 0.3.36 → 0.3.48

package/README.md

@@ -11,13 +11,12 @@ npm install @praxium/sdk
 ## Usage
 
 ```typescript
-import { createTenantClient } from '@praxium/sdk'
+import { createPraxiumClient } from '@praxium/sdk'
 
-const client = createTenantClient({
+const client = createPraxiumClient({
   baseUrl: process.env.PRAXIUM_API_URL!,   // 'https://platform.praxium.nl'
-  apiKey: process.env.PRAXIUM_API_KEY!,     // HMAC key: 'hmac_v1_mypractice_1234567890_abc...'
-  tenantSlug: 'mypractice',                 // must match the slug in the API key
-  locale: 'en',                             // 'en' (English) or 'nl' (Dutch)
+  apiKey: process.env.PRAXIUM_API_KEY!,     // tenant slug extracted from key automatically
+  locale: 'nl',                             // 'nl' | 'en' | '*' (multilingual)
 })
 
 // Returns data directly — throws PraxiumError on failure
@@ -25,6 +24,32 @@ const hours = await client.getOpeningHours()
 const team = await client.getTeamMembers()
 ```
 
+### Multilingual Mode
+
+```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
+})
+
+const team = await client.getTeamMembers()
+// Returns MultilingualTeamMember[] — labels/values are { nl: "...", en: "..." } objects:
+// {
+//   name: "Dr. Jan de Vries",
+//   role: "Fysiotherapeut",
+//   customFields: [
+//     { label: { nl: "Specialisatie", en: "Specialization" }, value: { nl: "Sport", en: "Sports" } }
+//   ]
+// }
+
+// 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"
+```
+
 ## Next.js Revalidation
 
 Optional utilities for ISR cache revalidation (requires `next` as peer dependency):

package/dist/index.d.ts

@@ -180,20 +180,37 @@ type SocialLinks = {
  */
 type TeamMembers = Array<PublicTeamMember>;
 /**
- * Custom field exposed on the public team API
+ * Custom field with server-resolved label (specific locale requested).
+ * When locale is 'nl' or 'en', the server resolves labels and values
+ * to that locale — label is a plain string, values are resolved strings.
  */
 type CustomField = {
     /** Field identifier (snake_case) */
     identifier: string;
     /** Custom field type (e.g., STRING, LONG_TEXT, SEARCHABLE_LIST) */
     type: string;
-    /** Localized field label */
-    label: LocalizedText;
+    /** Server-resolved field label for the requested locale */
+    label: string;
     /** Resolved field value (type depends on field.type) */
     value: unknown;
 };
 /**
- * Public team member profile
+ * Custom field with multilingual label (locale='*' requested).
+ * When locale is '*', the server returns all translations — label
+ * is a MultilingualText object, values are multilingual objects.
+ */
+type MultilingualCustomField = {
+    /** Field identifier (snake_case) */
+    identifier: string;
+    /** Custom field type (e.g., STRING, LONG_TEXT, SEARCHABLE_LIST) */
+    type: string;
+    /** Multilingual field label (all available locales) */
+    label: MultilingualText;
+    /** Multilingual field value (type depends on field.type) */
+    value: unknown;
+};
+/**
+ * Public team member profile with server-resolved custom fields
  */
 type PublicTeamMember = {
     /**
@@ -209,10 +226,33 @@ type PublicTeamMember = {
      */
     publicImage: string;
     /**
-     * Custom fields assigned to the public-team API access profile
+     * Custom fields with server-resolved labels and values
      */
     customFields: Array<CustomField>;
 };
+/**
+ * Public team member profile with multilingual custom fields (locale='*')
+ */
+type MultilingualTeamMember = {
+    /**
+     * Staff member UUID
+     */
+    id: string;
+    /**
+     * Public display name
+     */
+    publicName: string;
+    /**
+     * Public profile image URL (Supabase CDN)
+     */
+    publicImage: string;
+    /**
+     * Custom fields with multilingual labels and values
+     */
+    customFields: Array<MultilingualCustomField>;
+};
+/** Text in multiple languages. Keys are locale codes (e.g., 'nl', 'en'). */
+type MultilingualText = Record<string, string>;
 /**
  * Bilingual text with Dutch (nl) and English (en) translations
  */
@@ -226,8 +266,6 @@ type BilingualText = {
      */
     en: string;
 };
-/** Text with locale-specific values. Keys are locale codes (e.g., 'nl', 'en'). */
-type LocalizedText = Record<string, string>;
 /**
  * FAQs grouped by category, ordered by category.order then faq.order
  */
@@ -611,25 +649,41 @@ type SubmitContactFormData = {
     url: '/api/public/{tenantSlug}/contact';
 };
 
-interface TenantClientConfig {
+/**
+ * Supported locale codes for server-side content resolution.
+ * Adding a new language requires an SDK release.
+ */
+type SupportedLocale = 'nl' | 'en';
+/**
+ * Locale parameter for client creation.
+ * - Specific locale (`'nl'`, `'en'`) — server resolves labels/values
+ * - `'*'` — server returns all translations (multilingual mode)
+ */
+type ClientLocale = SupportedLocale | '*';
+/**
+ * Extract the tenant slug from a profile-scoped API key.
+ *
+ * Key format: hmac_v1_{tenantSlug}_{profileSlug}_{timestamp}_{signature}
+ * Parts:      [0]hmac [1]v1 [2]tenantSlug [3]profileSlug [4]timestamp [5]signature
+ *
+ * @throws Error if key format is invalid (wrong prefix or insufficient parts)
+ */
+declare function extractTenantSlugFromApiKey(apiKey: string): string;
+interface PraxiumClientConfig {
     /** Platform base URL (e.g., 'https://platform.praxium.nl') */
     baseUrl: string;
-    /** HMAC-signed API key (format: hmac_v1_{slug}_{timestamp}_{signature}) */
+    /** HMAC-signed API key (format: hmac_v1_{tenantSlug}_{profileSlug}_{timestamp}_{signature}) */
     apiKey: string;
-    /** Tenant identifier slug (must match the slug in the API key) */
-    tenantSlug: string;
-    /** Accept-Language header for locale-aware responses (e.g., 'nl', 'en') */
-    locale: string;
+    /** Locale for server-side content resolution */
+    locale: ClientLocale;
 }
-declare function createTenantClient(config: TenantClientConfig): {
-    /** Resolve a LocalizedText to a string using the client's configured locale. */
-    localize: (text: LocalizedText | null | undefined) => string;
+/** Shared methods available on both client types */
+interface PraxiumClientBase {
     getOpeningHours: () => Promise<OpeningHours>;
     getContactDetails: () => Promise<ContactDetails>;
     getLocation: () => Promise<Location>;
     getBusinessName: () => Promise<BusinessName>;
     getSocialLinks: () => Promise<SocialLinks>;
-    getTeamMembers: () => Promise<TeamMembers>;
     getFaq: () => Promise<FaqContent>;
     getServiceVariants: () => Promise<PricingVariants>;
     getInsuranceInfo: () => Promise<InsuranceList>;
@@ -637,15 +691,27 @@ declare function createTenantClient(config: TenantClientConfig): {
     getPaymentMethods: () => Promise<PaymentMethodList>;
     getPolicyInfo: () => Promise<PolicyList>;
     getBookableServices: () => Promise<BookableServices>;
-    submitContactForm: (body: SubmitContactFormData["body"]) => Promise<ContactFormResult>;
-};
-/** Return type of createTenantClient for type inference */
-type TenantClient = ReturnType<typeof createTenantClient>;
+    submitContactForm: (body: SubmitContactFormData['body']) => Promise<ContactFormResult>;
+}
+/** Client for locale-specific responses (locale='nl', 'en', etc.) */
+interface PraxiumClient extends PraxiumClientBase {
+    getTeamMembers: () => Promise<TeamMembers>;
+}
+/** Client for multilingual responses (locale='*') */
+interface MultilingualPraxiumClient extends PraxiumClientBase {
+    getTeamMembers: () => Promise<MultilingualTeamMember[]>;
+}
+/** Multilingual mode: returns MultilingualTeamMember[] (use localizeText() helper for resolution) */
+declare function createPraxiumClient(config: PraxiumClientConfig & {
+    locale: '*';
+}): MultilingualPraxiumClient;
+/** Locale-specific mode: returns PublicTeamMember[] with resolved labels/values */
+declare function createPraxiumClient(config: PraxiumClientConfig): PraxiumClient;
 
 /**
  * Typed error hierarchy for the Praxium SDK.
  *
- * Every method on `TenantClient` throws one of these errors when the
+ * Every method on `PraxiumClient` throws one of these errors when the
  * API returns a non-2xx response. Consumers can catch a specific
  * subclass (e.g. `PraxiumNotFoundError`) or the base `PraxiumError`.
  *
@@ -707,39 +773,69 @@ declare class PraxiumRateLimitError extends PraxiumError {
 /**
  * Get a custom field value by identifier from a team member's custom fields.
  *
+ * Works with both resolved (locale-specific) and multilingual (locale='*') members.
+ *
  * **Type safety warning:** The generic `T` is a cast (`as T`) — the caller is
  * responsible for ensuring `T` matches the actual runtime value shape for the
  * given field type. No runtime validation is performed.
  *
- * Runtime value shapes by custom field type:
+ * Runtime value shapes by custom field type (locale-specific):
  * - `STRING`           → `string`
  * - `LONG_TEXT`        → `string`
  * - `NUMBER`           → `number`
  * - `BOOLEAN`          → `boolean`
- * - `SINGLE_SELECT`    → `BilingualText` (`{ nl: string; en: string }`)
- * - `MULTI_SELECT`     → `BilingualText[]`
- * - `SEARCHABLE_LIST`  → `BilingualText[]`
+ * - `SINGLE_SELECT`    → `string`
+ * - `MULTI_SELECT`     → `string[]`
+ * - `SEARCHABLE_LIST`  → `string[]`
  * - `DATE`             → `string` (ISO 8601 date)
  *
+ * Runtime value shapes by custom field type (locale='*'):
+ * - `SINGLE_SELECT`    → `MultilingualText`
+ * - `MULTI_SELECT`     → `MultilingualText[]`
+ * - `SEARCHABLE_LIST`  → `MultilingualText[]`
+ * - Others: same as locale-specific
+ *
  * @example
  * ```ts
- * // Caller must match T to the field's actual type:
- * const specs = getCustomFieldValue<BilingualText[]>(member, 'specializations')
+ * // Locale-specific client (values are resolved strings):
+ * const specs = getCustomFieldValue<string[]>(member, 'specializations')
  * const bigNr = getCustomFieldValue<string>(member, 'big_number')
+ *
+ * // Multilingual client (locale='*'):
+ * const specs = getCustomFieldValue<MultilingualText[]>(member, 'specializations')
  * ```
  *
- * @param member - Public team member
+ * @param member - Public team member (resolved or multilingual)
  * @param identifier - Field identifier to look up
  * @returns The field value cast to `T`, or `null` if no field with that identifier exists
  */
-declare function getCustomFieldValue<T = unknown>(member: PublicTeamMember, identifier: string): T | null;
+declare function getCustomFieldValue<T = unknown>(member: PublicTeamMember | MultilingualTeamMember, identifier: string): T | null;
 /**
  * Get a custom field by identifier.
  *
- * @param member - Public team member
+ * @param member - Public team member (resolved or multilingual)
  * @param identifier - Field identifier to look up
  * @returns The full custom field, or undefined if not found
  */
 declare function getCustomField(member: PublicTeamMember, identifier: string): CustomField | undefined;
+declare function getCustomField(member: MultilingualTeamMember, identifier: string): MultilingualCustomField | undefined;
+/**
+ * Resolve a MultilingualText object to a single string for the given locale.
+ *
+ * Fallback chain: requested locale → 'en' (fallback) → first available value → ''
+ *
+ * @param text - Multilingual text object with locale keys
+ * @param locale - Desired locale code (e.g., 'nl', 'en', 'de')
+ * @returns The resolved text string, or empty string if no value available
+ *
+ * @example
+ * ```typescript
+ * const label = { nl: 'Specialisaties', en: 'Specializations' }
+ * localizeText(label, 'nl') // 'Specialisaties'
+ * localizeText(label, 'de') // 'Specializations' (falls back to 'en')
+ * localizeText({}, 'nl')    // ''
+ * ```
+ */
+declare function localizeText(text: MultilingualText | null | undefined, locale: SupportedLocale): string;
 
-export { type ApiError, type BilingualText, type BookableService, type BookableServices, type BookableVariantInfo, type BusinessName, type ContactDetails, type ContactFormResult, type CustomField, type FaqCategory, type FaqContent, type FaqGroup, type FaqItem, type FeatureItem, type FeatureList, type InsuranceInfo, type InsuranceList, type LocalizedText, type Location, type OpeningHours, type PaymentMethod, type PaymentMethodList, type PolicyInfo, type PolicyList, PraxiumAuthError, PraxiumError, PraxiumForbiddenError, PraxiumNotFoundError, PraxiumRateLimitError, PraxiumValidationError, type PricingVariant, type PricingVariants, type PublicDaySchedule, type PublicTeamMember, type ServiceCategoryInfo, type SocialLinks, type TeamMembers, type TenantClient, type TenantClientConfig, type ValidationDetail, createTenantClient, getCustomField, getCustomFieldValue };
+export { 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 };

package/dist/index.js

@@ -928,20 +928,20 @@ var STATUS_ERROR_MAP = {
   429: PraxiumRateLimitError
 };
 
-// src/helpers.ts
-function getCustomFieldValue(member, identifier) {
-  const field = member.customFields.find((f) => f.identifier === identifier);
-  return field ? field.value : null;
-}
-function getCustomField(member, identifier) {
-  return member.customFields.find((f) => f.identifier === identifier);
-}
-function getLocalizedText(text, locale) {
-  if (!text) return "";
-  return text[locale] || text["en"] || Object.values(text)[0] || "";
-}
-
 // src/tenant-client.ts
+var API_KEY_PREFIX = "hmac_v1";
+var API_KEY_SEPARATOR = "_";
+function extractTenantSlugFromApiKey(apiKey) {
+  const parts = apiKey.split(API_KEY_SEPARATOR);
+  if (parts.length < 6 || `${parts[0]}${API_KEY_SEPARATOR}${parts[1]}` !== API_KEY_PREFIX) {
+    throw new PraxiumError(
+      400,
+      "INVALID_API_KEY_FORMAT",
+      `API key must start with '${API_KEY_PREFIX}' and contain at least 6 segments. Format: hmac_v1_{tenantSlug}_{profileSlug}_{timestamp}_{signature}`
+    );
+  }
+  return parts[2];
+}
 function unwrapOrThrow(result) {
   if (result.data !== void 0 && result.error === void 0) {
     return result.data.data;
@@ -957,7 +957,8 @@ function unwrapOrThrow(result) {
   }
   throw new PraxiumError(status, errorCode, message, details);
 }
-function createTenantClient(config) {
+function createPraxiumClient(config) {
+  const tenantSlug = extractTenantSlugFromApiKey(config.apiKey);
   const clientInstance = createClient(
     createConfig({
       baseUrl: config.baseUrl,
@@ -968,11 +969,8 @@ function createTenantClient(config) {
     request.headers.set("Accept-Language", config.locale);
     return request;
   });
-  const path = { tenantSlug: config.tenantSlug };
-  return {
-    // ─── Locale Helper ───
-    /** Resolve a LocalizedText to a string using the client's configured locale. */
-    localize: (text) => getLocalizedText(text, config.locale),
+  const path = { tenantSlug };
+  const baseMethods = {
     // ─── Layout Endpoints ───
     getOpeningHours: () => getOpeningHours({ client: clientInstance, path }).then(unwrapOrThrow),
     getContactDetails: () => getContactDetails({ client: clientInstance, path }).then(unwrapOrThrow),
@@ -980,7 +978,6 @@ function createTenantClient(config) {
     getBusinessName: () => getBusinessName({ client: clientInstance, path }).then(unwrapOrThrow),
     getSocialLinks: () => getSocialLinks({ client: clientInstance, path }).then(unwrapOrThrow),
     // ─── Content Endpoints ───
-    getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow),
     getFaq: () => getFaq({ client: clientInstance, path }).then(unwrapOrThrow),
     getServiceVariants: () => getServiceVariants({ client: clientInstance, path }).then(unwrapOrThrow),
     getInsuranceInfo: () => getInsuranceInfo({ client: clientInstance, path }).then(unwrapOrThrow),
@@ -991,6 +988,29 @@ function createTenantClient(config) {
     // ─── Contact Form ───
     submitContactForm: (body) => submitContactForm({ client: clientInstance, path, body }).then(unwrapOrThrow)
   };
+  if (config.locale === "*") {
+    return {
+      ...baseMethods,
+      getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow)
+    };
+  }
+  return {
+    ...baseMethods,
+    getTeamMembers: () => getTeamMembers({ client: clientInstance, path }).then(unwrapOrThrow)
+  };
+}
+
+// src/helpers.ts
+function getCustomFieldValue(member, identifier) {
+  const field = member.customFields.find((f) => f.identifier === identifier);
+  return field ? field.value : null;
+}
+function getCustomField(member, identifier) {
+  return member.customFields.find((f) => f.identifier === identifier);
+}
+function localizeText(text, locale) {
+  if (!text) return "";
+  return text[locale] || text["en"] || Object.values(text)[0] || "";
 }
 export {
   PraxiumAuthError,
@@ -999,7 +1019,9 @@ export {
   PraxiumNotFoundError,
   PraxiumRateLimitError,
   PraxiumValidationError,
-  createTenantClient,
+  createPraxiumClient,
+  extractTenantSlugFromApiKey,
   getCustomField,
-  getCustomFieldValue
+  getCustomFieldValue,
+  localizeText
 };

package/package.json

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