@praxium/sdk 0.2.4

package/dist/index.d.ts

@@ -0,0 +1,707 @@
+/**
+ * Tenant identifier slug
+ */
+type TenantSlug = string;
+/**
+ * Weekly opening hours schedule. Null if not configured.
+ */
+type OpeningHours = {
+    /**
+     * Weekly schedule (7 entries, Mon-Sun)
+     */
+    schedule: Array<PublicDaySchedule>;
+    /**
+     * General note about opening hours
+     */
+    globalNote: string | null;
+} | null;
+/**
+ * Daily opening schedule entry
+ */
+type PublicDaySchedule = {
+    /**
+     * Day of week (0=Monday, 6=Sunday)
+     */
+    dayIndex: number;
+    /**
+     * Localized day name
+     */
+    dayName: string;
+    /**
+     * Opening hours text
+     */
+    hours: string | null;
+    /**
+     * Whether the practice is closed on this day
+     */
+    isClosed: boolean;
+    /**
+     * Additional note for this day
+     */
+    note: string | null;
+};
+/**
+ * Standard error response
+ */
+type ApiError = {
+    /**
+     * Error type
+     */
+    error: string;
+    /**
+     * Machine-readable error code
+     */
+    errorCode: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Validation error details (only for 400 responses)
+     */
+    details?: Array<{
+        /**
+         * Field path that failed validation
+         */
+        field: string;
+        /**
+         * Validation error message
+         */
+        message: string;
+    }>;
+};
+/**
+ * Practice contact details. Null if not configured.
+ */
+type ContactDetails = {
+    /**
+     * Main phone number
+     */
+    phone: string;
+    /**
+     * WhatsApp contact number
+     */
+    whatsappPhone: string;
+    /**
+     * Contact email address
+     */
+    email: string;
+} | null;
+/**
+ * Contact form submission result
+ */
+type ContactFormResult = {
+    /**
+     * Whether the form was submitted successfully
+     */
+    success: boolean;
+    /**
+     * Email delivery status
+     */
+    emailStatus: string;
+};
+/**
+ * Practice location with coordinates and directions. Null if not configured.
+ */
+type Location = {
+    /**
+     * 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 the practice
+     */
+    googleMapsUrl: string | null;
+    /**
+     * Parking information (localized)
+     */
+    parkingInfo: string | null;
+    /**
+     * Accessibility information (localized)
+     */
+    accessibility: string | null;
+} | null;
+/**
+ * Practice business name
+ */
+type BusinessName = {
+    /**
+     * Practice name (localized)
+     */
+    name: string;
+};
+/**
+ * Social media profile URLs. Null if not configured.
+ */
+type SocialLinks = {
+    /**
+     * Facebook page URL
+     */
+    facebook?: string;
+    /**
+     * Instagram profile URL
+     */
+    instagram?: string;
+    /**
+     * LinkedIn page URL
+     */
+    linkedin?: string;
+    /**
+     * Twitter/X profile URL
+     */
+    twitter?: string;
+} | null;
+/**
+ * List of team members visible on the public team page
+ */
+type TeamMembers = Array<PublicTeamMember>;
+/**
+ * Public team member profile
+ */
+type PublicTeamMember = {
+    /**
+     * Staff member UUID
+     */
+    id: string;
+    /**
+     * Public display name
+     */
+    publicName: string;
+    /**
+     * Public profile image URL (Supabase CDN)
+     */
+    publicImage: string;
+    /**
+     * List of specializations
+     */
+    specializations: Array<LocalizedSpecialization>;
+    /**
+     * Staff biography in NL and EN
+     */
+    bio: BilingualText | null;
+    /**
+     * BIG registration number (Dutch healthcare registration)
+     */
+    bigNumber: string | null;
+};
+/**
+ * Specialization with bilingual names
+ */
+type LocalizedSpecialization = {
+    /**
+     * Dutch specialization name
+     */
+    nl: string;
+    /**
+     * English specialization name
+     */
+    en: string;
+};
+/**
+ * Bilingual text with Dutch (nl) and English (en) translations
+ */
+type BilingualText = {
+    /**
+     * Dutch text
+     */
+    nl: string;
+    /**
+     * English text
+     */
+    en: string;
+};
+/**
+ * FAQs grouped by category, ordered by category.order then faq.order
+ */
+type FaqContent = Array<FaqGroup>;
+/**
+ * FAQ category with its items
+ */
+type FaqGroup = {
+    /**
+     * The FAQ category
+     */
+    category: FaqCategory;
+    /**
+     * FAQ items in this category
+     */
+    faqs: Array<FaqItem>;
+};
+/**
+ * FAQ category with bilingual name
+ */
+type FaqCategory = {
+    /**
+     * Category UUID
+     */
+    id: string;
+    /**
+     * Category name per locale
+     */
+    name: {
+        [key: string]: string;
+    };
+    /**
+     * Display order (ascending)
+     */
+    order: number;
+};
+/**
+ * Individual FAQ question and answer
+ */
+type FaqItem = {
+    /**
+     * FAQ item UUID
+     */
+    id: string;
+    /**
+     * Question text per locale
+     */
+    question: {
+        [key: string]: string;
+    };
+    /**
+     * Answer text per locale (may contain HTML)
+     */
+    answer: {
+        [key: string]: string;
+    };
+    /**
+     * Parent category UUID
+     */
+    categoryId: string;
+    /**
+     * Display order within category (ascending)
+     */
+    order: number;
+    /**
+     * Whether this FAQ item is currently visible
+     */
+    visible: boolean;
+};
+/**
+ * All service variants ordered by category, service, then variant order
+ */
+type PricingVariants = Array<PricingVariant>;
+/**
+ * Service variant with pricing and category info
+ */
+type PricingVariant = {
+    /**
+     * Variant UUID
+     */
+    id: string;
+    /**
+     * Parent service name per locale
+     */
+    serviceName: {
+        [key: string]: string;
+    };
+    /**
+     * Variant name per locale (null if single variant)
+     */
+    name: {
+        [key: string]: string;
+    } | null;
+    /**
+     * Variant description per locale
+     */
+    description: {
+        [key: string]: string;
+    } | null;
+    /**
+     * Duration in minutes
+     */
+    duration: number;
+    /**
+     * Price in euros (cents)
+     */
+    price: number;
+    /**
+     * Display order within service
+     */
+    order: number;
+    /**
+     * Parent service category
+     */
+    category: ServiceCategoryInfo;
+    /**
+     * Category display order
+     */
+    categoryOrder: number;
+    /**
+     * Service display order within category
+     */
+    serviceOrder: number;
+};
+/**
+ * Service category metadata
+ */
+type ServiceCategoryInfo = {
+    /**
+     * Category UUID
+     */
+    id: string;
+    /**
+     * Category name per locale
+     */
+    name: {
+        [key: string]: string;
+    };
+    /**
+     * URL-safe category identifier
+     */
+    slug: string;
+    /**
+     * Category color hex code
+     */
+    color: string | null;
+};
+/**
+ * Insurance information items ordered by display order
+ */
+type InsuranceList = Array<InsuranceInfo>;
+/**
+ * Insurance coverage information
+ */
+type InsuranceInfo = {
+    /**
+     * Insurance info UUID
+     */
+    id: string;
+    /**
+     * Title per locale
+     */
+    title: {
+        [key: string]: string;
+    };
+    /**
+     * Description per locale (may contain HTML)
+     */
+    description: {
+        [key: string]: string;
+    };
+    /**
+     * Display order (ascending)
+     */
+    order: number;
+    /**
+     * ISO 8601 creation timestamp
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 last update timestamp
+     */
+    updatedAt: string;
+};
+/**
+ * Practice feature items ordered by display order
+ */
+type FeatureList = Array<FeatureItem>;
+/**
+ * Practice feature or highlight
+ */
+type FeatureItem = {
+    /**
+     * Feature item UUID
+     */
+    id: string;
+    /**
+     * Feature text per locale
+     */
+    text: {
+        [key: string]: string;
+    };
+    /**
+     * Display order (ascending)
+     */
+    order: number;
+    /**
+     * ISO 8601 creation timestamp
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 last update timestamp
+     */
+    updatedAt: string;
+};
+/**
+ * Accepted payment methods ordered by display order
+ */
+type PaymentMethodList = Array<PaymentMethod>;
+/**
+ * Accepted payment method
+ */
+type PaymentMethod = {
+    /**
+     * Payment method UUID
+     */
+    id: string;
+    /**
+     * Payment method name per locale
+     */
+    name: {
+        [key: string]: string;
+    };
+    /**
+     * Display order (ascending)
+     */
+    order: number;
+    /**
+     * ISO 8601 creation timestamp
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 last update timestamp
+     */
+    updatedAt: string;
+};
+/**
+ * Practice policy items ordered by display order
+ */
+type PolicyList = Array<PolicyInfo>;
+/**
+ * Cancellation/practice policy information
+ */
+type PolicyInfo = {
+    /**
+     * Policy info UUID
+     */
+    id: string;
+    /**
+     * Policy title per locale
+     */
+    title: {
+        [key: string]: string;
+    };
+    /**
+     * Policy description per locale (may contain HTML)
+     */
+    description: {
+        [key: string]: string;
+    };
+    /**
+     * Display order (ascending)
+     */
+    order: number;
+    /**
+     * ISO 8601 creation timestamp
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 last update timestamp
+     */
+    updatedAt: string;
+};
+/**
+ * All bookable services with their variants and categories
+ */
+type BookableServices = Array<BookableService>;
+/**
+ * Service available for online booking with its variants
+ */
+type BookableService = {
+    /**
+     * Service UUID
+     */
+    id: string;
+    /**
+     * URL-safe service identifier
+     */
+    slug: string;
+    /**
+     * Service name per locale
+     */
+    name: {
+        [key: string]: string;
+    };
+    /**
+     * Service description per locale
+     */
+    description: {
+        [key: string]: string;
+    };
+    /**
+     * Service category
+     */
+    category: ServiceCategoryInfo;
+    /**
+     * Service color hex code
+     */
+    color: string | null;
+    /**
+     * Available booking variants
+     */
+    variants: Array<BookableVariantInfo>;
+};
+/**
+ * Bookable service variant with pricing
+ */
+type BookableVariantInfo = {
+    /**
+     * Variant UUID
+     */
+    id: string;
+    /**
+     * Variant name per locale (null for single-variant services)
+     */
+    name: {
+        [key: string]: string;
+    } | null;
+    /**
+     * Duration in minutes
+     */
+    duration: number;
+    /**
+     * Price in euros (cents)
+     */
+    price: number;
+    /**
+     * Display order within service
+     */
+    order: number;
+    /**
+     * Whether this is the default variant for the service
+     */
+    isDefault: boolean;
+    /**
+     * Cal.com event type slug for online booking
+     */
+    externalEventTypeSlug: string | null;
+    /**
+     * Variant description per locale
+     */
+    description: {
+        [key: string]: string;
+    } | null;
+};
+type SubmitContactFormData = {
+    body: {
+        name: string;
+        email: string;
+        phone?: string;
+        subject: string;
+        message: string;
+    };
+    path: {
+        /**
+         * Tenant identifier slug
+         */
+        tenantSlug: TenantSlug;
+    };
+    query?: never;
+    url: '/api/public/{tenantSlug}/contact';
+};
+
+interface TenantClientConfig {
+    /** Platform base URL (e.g., 'https://platform.praxium.nl') */
+    baseUrl: string;
+    /** HMAC-signed API key (format: hmac_v1_{slug}_{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;
+}
+declare function createTenantClient(config: TenantClientConfig): {
+    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>;
+    getFeatures: () => Promise<FeatureList>;
+    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>;
+
+/**
+ * Typed error hierarchy for the Praxium SDK.
+ *
+ * Every method on `TenantClient` 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`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const hours = await client.getOpeningHours()
+ * } catch (err) {
+ *   if (err instanceof PraxiumNotFoundError) {
+ *     // tenant slug is invalid
+ *   }
+ * }
+ * ```
+ */
+
+/** Validation error detail from the API */
+type ValidationDetail = NonNullable<ApiError['details']>[number];
+/**
+ * Base error for all Praxium API failures.
+ *
+ * Properties mirror the `ApiError` response body from the platform:
+ * - `status`    — HTTP status code
+ * - `errorCode` — Machine-readable code (e.g. `'TENANT_NOT_FOUND'`)
+ * - `message`   — Human-readable explanation
+ * - `details`   — Optional validation error details (400 responses only)
+ */
+declare class PraxiumError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly details?: ApiError['details'];
+    name: string;
+    constructor(status: number, errorCode: string, message: string, details?: ApiError['details']);
+}
+/** Thrown when the server rejects the request body (HTTP 400). */
+declare class PraxiumValidationError extends PraxiumError {
+    constructor(errorCode: string, message: string, details?: ApiError['details']);
+}
+/** Thrown when the API key is missing or invalid (HTTP 401). */
+declare class PraxiumAuthError extends PraxiumError {
+    constructor(errorCode: string, message: string);
+}
+/** Thrown when the API key does not match the requested tenant (HTTP 403). */
+declare class PraxiumForbiddenError extends PraxiumError {
+    constructor(errorCode: string, message: string);
+}
+/** Thrown when the tenant is not found or inactive (HTTP 404). */
+declare class PraxiumNotFoundError extends PraxiumError {
+    constructor(errorCode: string, message: string);
+}
+/** Thrown when the rate limit is exceeded (HTTP 429). */
+declare class PraxiumRateLimitError extends PraxiumError {
+    constructor(errorCode: string, message: string);
+}
+
+export { type ApiError, type BilingualText, type BookableService, type BookableServices, type BookableVariantInfo, type BusinessName, type ContactDetails, type ContactFormResult, type FaqCategory, type FaqContent, type FaqGroup, type FaqItem, type FeatureItem, type FeatureList, type InsuranceInfo, type InsuranceList, type LocalizedSpecialization, 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 };