@slotchain/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1149 @@
+import { AxiosInstance } from 'axios';
+import { NextApiRequest, NextApiResponse } from 'next';
+
+/**
+ * Standard API response format for all Slotly API endpoints
+ */
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+    pagination?: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+/**
+ * Placeholder types for domain models
+ * TODO: Replace with actual types from the Slotly API
+ */
+interface Tenant {
+    id: string;
+    slug: string;
+    name: string;
+}
+/**
+ * Tenant branding configuration
+ */
+interface TenantBranding {
+    logoUrl?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    faviconUrl?: string;
+    customCss?: string;
+}
+/**
+ * Service item within a service
+ */
+interface ServiceItem {
+    id: string;
+    serviceId: string;
+    name: string;
+    description?: string;
+    price?: number;
+    duration?: number;
+    available?: boolean;
+}
+/**
+ * Enhanced Service type with nested service items
+ */
+interface ServiceWithItems extends Service {
+    /** Array of service items nested within this service (optional, may be empty array) */
+    serviceItems?: ServiceItem[];
+}
+/**
+ * Service item with parent service reference
+ */
+interface ServiceItemWithService extends ServiceItem {
+    /** Parent service reference (optional, for convenience when fetching items separately) */
+    parentService?: Service;
+}
+/**
+ * Category extracted from services
+ */
+interface Category {
+    id: string;
+    name: string;
+    slug?: string;
+    description?: string;
+    /** Array of service IDs in this category */
+    serviceIds?: string[];
+    /** Optional: services in this category (if expanded) */
+    services?: Service[];
+}
+interface Booking {
+    id: string;
+    tenantId: string;
+    slotId?: string;
+    customerId?: string;
+    status?: string;
+}
+interface Service {
+    id: string;
+    tenantId: string;
+    name: string;
+    description?: string;
+    duration?: number;
+    price?: number;
+}
+interface Slot {
+    id: string;
+    tenantId: string;
+    serviceId?: string;
+    startTime: string;
+    endTime: string;
+    available: boolean;
+}
+interface Customer {
+    id: string;
+    tenantId: string;
+    email?: string;
+    name?: string;
+    phone?: string;
+}
+interface Flow {
+    id: string;
+    tenantId: string;
+    name: string;
+    steps?: FlowStep[];
+}
+interface FlowStep {
+    id: string;
+    type: string;
+    config?: Record<string, any>;
+}
+interface Studio {
+    id: string;
+    name: string;
+    slug?: string;
+}
+interface Notification {
+    id: string;
+    tenantId?: string;
+    type: string;
+    recipient: string;
+    content: string;
+    sentAt?: string;
+}
+interface DataQualityIssue {
+    id: string;
+    tenantId?: string;
+    type: string;
+    severity: 'low' | 'medium' | 'high';
+    message: string;
+    resolved: boolean;
+}
+/**
+ * Full tenant configuration including branding, services, and service items
+ * Service items are nested within each service object (not as a separate top-level array)
+ */
+interface TenantFullConfig {
+    /** Tenant ID (required, non-nullable) */
+    id: string;
+    /** Tenant slug (required, non-nullable) */
+    slug: string;
+    /** Tenant name (required, non-nullable) */
+    name: string;
+    /** Branding configuration (optional) */
+    branding?: TenantBranding;
+    /** Array of services with nested service items (required, non-nullable, may be empty array) */
+    services: ServiceWithItems[];
+    /** Enabled features (optional) */
+    featuresEnabled?: string[];
+    /** Subscription level (optional) */
+    subscriptionLevel?: string;
+    /** Additional configuration (optional) */
+    config?: Record<string, any>;
+}
+
+declare class TenantClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get tenant configuration by slug
+     * GET /api/v1/tenant-config/:slug
+     */
+    getBySlug(slug: string): Promise<ApiResponse<Tenant>>;
+    /**
+     * Get tenant by ID
+     * GET /api/v1/tenants/:id
+     */
+    getById(id: string): Promise<ApiResponse<Tenant>>;
+    /**
+     * List all tenants
+     * GET /api/v1/tenants
+     */
+    list(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Tenant[]>>;
+    /**
+     * Create a new tenant
+     * POST /api/v1/tenants
+     */
+    create(data: Partial<Tenant>): Promise<ApiResponse<Tenant>>;
+    /**
+     * Update tenant by ID
+     * PATCH /api/v1/tenants/:id
+     */
+    update(id: string, data: Partial<Tenant>): Promise<ApiResponse<Tenant>>;
+    /**
+     * Delete tenant by ID
+     * DELETE /api/v1/tenants/:id
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Get full tenant configuration including branding, services, and service items
+     * GET /api/v1/tenants/:slug
+     *
+     * This method returns the complete tenant configuration including:
+     * - Tenant basic info (id, slug, name)
+     * - Branding configuration (logo, colors, etc.)
+     * - All services associated with the tenant (with nested service items)
+     * - Feature flags and subscription level
+     *
+     * Note: Service items are nested within each service object (not as a separate top-level array).
+     * The endpoint returns full config by default (includes services with nested items).
+     *
+     * @param slug - Tenant slug identifier (required, non-nullable)
+     * @param includeServices - Include services with nested items (default: true)
+     * @returns Promise resolving to ApiResponse<TenantFullConfig>
+     *
+     * @example
+     * ```typescript
+     * const result = await slotly.tenant.getFullConfig('bright-accountants');
+     * if (result.success && result.data) {
+     *   const config = result.data;
+     *   console.log('Tenant:', config.name);
+     *   console.log('Logo:', config.branding?.logoUrl);
+     *   console.log('Services:', config.services.length);
+     *
+     *   // Service items are nested within each service
+     *   config.services.forEach(service => {
+     *     console.log(`Service: ${service.name}`);
+     *     if (service.serviceItems) {
+     *       console.log(`  Items: ${service.serviceItems.length}`);
+     *     }
+     *   });
+     * }
+     * ```
+     *
+     * **Guaranteed fields (non-nullable):**
+     * - `id`: string
+     * - `slug`: string
+     * - `name`: string
+     * - `services`: ServiceWithItems[] (may be empty array, each service may have nested `serviceItems`)
+     *
+     * **Optional fields:**
+     * - `branding`: TenantBranding | undefined
+     * - `services[].serviceItems`: ServiceItem[] | undefined (nested within each service)
+     * - `featuresEnabled`: string[] | undefined
+     * - `subscriptionLevel`: string | undefined
+     * - `config`: Record<string, any> | undefined
+     *
+     * **Error Codes:**
+     * - `TENANT_NOT_FOUND` - Tenant with slug not found
+     * - `AUTH_ERROR` - Authentication failed
+     * - `PERMISSION_DENIED` - Insufficient permissions
+     * - `NETWORK_ERROR` - Network request failed
+     */
+    getFullConfig(slug: string, includeServices?: boolean): Promise<ApiResponse<TenantFullConfig>>;
+}
+
+declare class BookingClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get booking by ID
+     * GET /api/v1/bookings/:id
+     */
+    getById(id: string): Promise<ApiResponse<Booking>>;
+    /**
+     * List bookings
+     * GET /api/v1/bookings
+     */
+    list(params?: {
+        slot_id?: string;
+        customer_id?: string;
+        status?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Booking[]>>;
+    /**
+     * Create a new booking (publishes booking.created event)
+     * POST /api/v1/bookings
+     */
+    create(data: {
+        slot_id: string;
+        customer_info: {
+            name: string;
+            email: string;
+            phone?: string;
+            address?: string;
+            city?: string;
+            state?: string;
+            zipCode?: string;
+            isGuestCheckout?: boolean;
+        };
+        booking_data?: Record<string, unknown>;
+    }): Promise<ApiResponse<Booking>>;
+    /**
+     * Update booking by ID
+     * PUT /api/v1/bookings/:id
+     */
+    update(id: string, data: {
+        status?: string;
+        customer_info?: Record<string, unknown>;
+        booking_data?: Record<string, unknown>;
+    }): Promise<ApiResponse<Booking>>;
+    /**
+     * Cancel booking by ID
+     * Note: Cancel is typically done via update with status change
+     * If dedicated cancel endpoint exists, update this method
+     */
+    cancel(id: string): Promise<ApiResponse<Booking>>;
+    /**
+     * Delete booking by ID (soft delete)
+     * DELETE /api/v1/bookings/:id
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+}
+
+declare class ServiceClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get service by ID
+     * GET /api/v1/services/:id
+     *
+     * @param id - Service ID
+     * @param includeItems - Include nested service items (default: false)
+     * @returns Service details (with items if includeItems=true)
+     */
+    getById(id: string, includeItems?: boolean): Promise<ApiResponse<Service | ServiceWithItems>>;
+    /**
+     * List services by tenant slug
+     * GET /api/v1/services?tenantSlug=:slug
+     *
+     * @param slug - Tenant slug (or use tenant_id in list() method)
+     * @param params - Optional parameters (includeItems, page, limit, is_active)
+     * @returns List of services for the tenant
+     */
+    listServices(slug: string, params?: {
+        includeItems?: boolean;
+        page?: number;
+        limit?: number;
+        is_active?: boolean;
+    }): Promise<ApiResponse<Service[] | ServiceWithItems[]>>;
+    /**
+     * List services with optional filters
+     * GET /api/v1/services
+     *
+     * @param params - Query parameters (tenant_id, tenantSlug, slot_id, page, limit, is_active, includeItems)
+     * @returns Paginated list of services
+     */
+    list(params?: {
+        tenant_id?: string;
+        tenantSlug?: string;
+        slot_id?: string;
+        page?: number;
+        limit?: number;
+        is_active?: boolean;
+        includeItems?: boolean;
+    }): Promise<ApiResponse<Service[] | ServiceWithItems[]>>;
+    /**
+     * Create a new service
+     * POST /api/v1/services
+     *
+     * @param data - Service creation data (tenant_id, name required)
+     * @returns Created service
+     */
+    create(data: Partial<Service>): Promise<ApiResponse<Service>>;
+    /**
+     * Update service by ID
+     * PUT /api/v1/services/:id
+     *
+     * @param id - Service ID
+     * @param data - Service update data
+     * @returns Updated service
+     */
+    update(id: string, data: Partial<Service>): Promise<ApiResponse<Service>>;
+    /**
+     * Delete service by ID
+     * DELETE /api/v1/services/:id
+     *
+     * @param id - Service ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Bulk create services
+     * POST /api/v1/services/bulk (if available)
+     *
+     * @param services - Array of services to create
+     * @returns Created services
+     */
+    bulkCreate(services: Partial<Service>[]): Promise<ApiResponse<Service[]>>;
+    /**
+     * Get service with its service items nested
+     * GET /api/v1/services/:id?includeItems=true
+     *
+     * @param id - Service ID
+     * @returns Service with nested service items
+     */
+    getWithItems(id: string): Promise<ApiResponse<ServiceWithItems>>;
+    /**
+     * List services with their service items nested
+     * GET /api/v1/services?includeItems=true
+     *
+     * @param params - Query parameters (tenant_id, tenantSlug, slot_id, page, limit, is_active)
+     * @returns Paginated list of services with nested service items
+     */
+    listWithItems(params?: {
+        tenant_id?: string;
+        tenantSlug?: string;
+        slot_id?: string;
+        page?: number;
+        limit?: number;
+        is_active?: boolean;
+    }): Promise<ApiResponse<ServiceWithItems[]>>;
+    /**
+     * List all categories for a tenant (extracted from services)
+     * GET /api/v1/categories?tenantSlug=:slug
+     *
+     * @param tenantSlug - Tenant slug (or use tenant_id in params)
+     * @param params - Optional query parameters (tenant_id, includeServices)
+     * @returns List of categories for the tenant
+     */
+    listCategories(tenantSlug?: string, params?: {
+        tenant_id?: string;
+        includeServices?: boolean;
+    }): Promise<ApiResponse<Category[]>>;
+    /**
+     * Get category by ID (category name, lowercase)
+     * GET /api/v1/categories/:id?tenantSlug=:slug
+     *
+     * @param categoryId - Category ID (lowercase category name, e.g., "consulting")
+     * @param tenantSlug - Tenant slug (or use tenant_id in params)
+     * @param params - Optional query parameters (tenant_id, includeServices, includeItems)
+     * @returns Category details
+     */
+    getCategory(categoryId: string, tenantSlug?: string, params?: {
+        tenant_id?: string;
+        includeServices?: boolean;
+        includeItems?: boolean;
+    }): Promise<ApiResponse<Category>>;
+}
+
+/**
+ * ServiceItemClient provides methods for managing service items independently
+ * or in relation to their parent services.
+ */
+declare class ServiceItemClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get service item by ID
+     * GET /api/v1/service-items/:id
+     *
+     * @param id - Service item ID
+     * @returns Service item details
+     */
+    getById(id: string): Promise<ApiResponse<ServiceItem>>;
+    /**
+     * List all service items for a service
+     * GET /api/v1/services/:serviceId/items
+     *
+     * @param serviceId - Service ID
+     * @returns List of service items for the specified service
+     */
+    listByService(serviceId: string): Promise<ApiResponse<ServiceItem[]>>;
+    /**
+     * Create a new service item for a service
+     * POST /api/v1/services/:serviceId/items
+     *
+     * @param serviceId - Service ID
+     * @param data - Service item creation data
+     * @returns Created service item
+     */
+    createForService(serviceId: string, data: Partial<ServiceItem>): Promise<ApiResponse<ServiceItem>>;
+    /**
+     * Create a new service item
+     * POST /api/v1/service-items (alternative to createForService)
+     *
+     * @param data - Service item creation data (must include service_id)
+     * @returns Created service item
+     */
+    create(data: Partial<ServiceItem>): Promise<ApiResponse<ServiceItem>>;
+    /**
+     * Update service item by ID
+     * PUT /api/v1/service-items/:id
+     *
+     * @param id - Service item ID
+     * @param data - Service item update data
+     * @returns Updated service item
+     */
+    update(id: string, data: Partial<ServiceItem>): Promise<ApiResponse<ServiceItem>>;
+    /**
+     * Delete service item by ID
+     * DELETE /api/v1/service-items/:id
+     *
+     * @param id - Service item ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+}
+
+declare class SlotClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get slot by ID
+     * GET /api/v1/slots/:id
+     *
+     * @param id - Slot ID
+     * @returns Slot details
+     */
+    getById(id: string): Promise<ApiResponse<Slot>>;
+    /**
+     * List available slots
+     * GET /api/v1/slots
+     *
+     * @param params - Query parameters (tenant_id required, status, is_active, page, limit)
+     * @returns Paginated list of slots
+     */
+    list(params: {
+        tenant_id: string;
+        status?: string;
+        is_active?: boolean;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Slot[]>>;
+    /**
+     * Create a new slot
+     * POST /api/v1/slots
+     *
+     * @param data - Slot creation data (tenant_id, name required)
+     * @returns Created slot
+     */
+    create(data: Partial<Slot>): Promise<ApiResponse<Slot>>;
+    /**
+     * Update slot by ID
+     * PUT /api/v1/slots/:id
+     *
+     * @param id - Slot ID
+     * @param data - Slot update data
+     * @returns Updated slot
+     */
+    update(id: string, data: Partial<Slot>): Promise<ApiResponse<Slot>>;
+    /**
+     * Delete slot by ID
+     * DELETE /api/v1/slots/:id
+     *
+     * @param id - Slot ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Bulk create slots
+     * POST /api/v1/slots/bulk (verify if available)
+     *
+     * @param slots - Array of slots to create
+     * @returns Created slots
+     */
+    bulkCreate(slots: Partial<Slot>[]): Promise<ApiResponse<Slot[]>>;
+    /**
+     * Mark slot as available/unavailable
+     * Note: Use update() method with status or other fields
+     */
+    setAvailability(id: string, available: boolean): Promise<ApiResponse<Slot>>;
+    /**
+     * Get all active services for a slot with their items
+     * GET /api/v1/slots/:id/services
+     *
+     * @param id - Slot ID
+     * @returns Services with nested service items
+     */
+    getServices(id: string): Promise<ApiResponse<ServiceWithItems[]>>;
+    /**
+     * Get slot with tenant information
+     * GET /api/v1/slots/:id/tenant-info
+     *
+     * @param id - Slot ID
+     * @returns Slot with tenant data
+     */
+    getWithTenant(id: string): Promise<ApiResponse<Slot & {
+        tenant: Tenant;
+    }>>;
+}
+
+declare class CustomerClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get customer by ID
+     * GET /api/v1/customers/:id
+     *
+     * @param id - Customer ID
+     * @returns Customer details
+     */
+    getById(id: string): Promise<ApiResponse<Customer>>;
+    /**
+     * Get customer by email
+     * GET /api/v1/customers?email=:email&tenant_id=:id
+     *
+     * @param email - Customer email
+     * @param tenantId - Required tenant ID for scoping
+     * @returns Customer details
+     */
+    getByEmail(email: string, tenantId: string): Promise<ApiResponse<Customer>>;
+    /**
+     * List customers with optional filters
+     * GET /api/v1/customers
+     *
+     * @param params - Query parameters (tenant_id required, page, limit, search, is_guest)
+     * @returns Paginated list of customers
+     */
+    list(params: {
+        tenant_id: string;
+        page?: number;
+        limit?: number;
+        search?: string;
+        is_guest?: boolean;
+    }): Promise<ApiResponse<Customer[]>>;
+    /**
+     * Create a new customer
+     * POST /api/v1/customers
+     *
+     * @param data - Customer creation data (tenant_id, name, email required)
+     * @returns Created customer
+     */
+    create(data: Partial<Customer>): Promise<ApiResponse<Customer>>;
+    /**
+     * Update customer by ID
+     * PUT /api/v1/customers/:id
+     *
+     * @param id - Customer ID
+     * @param data - Customer update data
+     * @returns Updated customer
+     */
+    update(id: string, data: Partial<Customer>): Promise<ApiResponse<Customer>>;
+    /**
+     * Delete customer by ID
+     * DELETE /api/v1/customers/:id
+     *
+     * @param id - Customer ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Lookup customer by userId or tenantId
+     * GET /api/v1/customers/lookup
+     *
+     * @param params - Query parameters (userId optional, tenantId required)
+     * @returns Customer or null
+     */
+    lookup(params: {
+        userId?: string;
+        tenantId: string;
+    }): Promise<ApiResponse<Customer | null>>;
+    /**
+     * Get autocomplete data from existing customers and bookings
+     * GET /api/v1/customers/autocomplete
+     *
+     * @param tenantId - Tenant ID (required)
+     * @returns Autocomplete data
+     */
+    autocomplete(tenantId: string): Promise<ApiResponse<any>>;
+    /**
+     * Get all bookings for a customer
+     * GET /api/v1/customers/bookings
+     *
+     * @param params - Query parameters (email optional, userId optional, tenantId required)
+     * @returns Customer bookings data
+     */
+    getBookings(params: {
+        email?: string;
+        userId?: string;
+        tenantId: string;
+    }): Promise<ApiResponse<{
+        customer: Customer | null;
+        bookings: Booking[];
+        groupedBySlot: Record<string, Booking[]>;
+        total: number;
+    }>>;
+}
+
+declare class FlowClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get flow by ID
+     * GET /api/v1/flows/:id
+     *
+     * @param id - Flow ID
+     * @returns Flow details
+     */
+    getById(id: string): Promise<ApiResponse<Flow>>;
+    /**
+     * List flows with optional filters
+     * GET /api/v1/flows
+     *
+     * @param params - Query parameters (tenantId, page, limit)
+     * @returns Paginated list of flows
+     */
+    list(params?: {
+        tenantId?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Flow[]>>;
+    /**
+     * Create a new flow
+     * POST /api/v1/flows
+     *
+     * @param data - Flow creation data
+     * @returns Created flow
+     */
+    create(data: Partial<Flow>): Promise<ApiResponse<Flow>>;
+    /**
+     * Update flow by ID
+     * PATCH /api/v1/flows/:id
+     *
+     * @param id - Flow ID
+     * @param data - Flow update data
+     * @returns Updated flow
+     */
+    update(id: string, data: Partial<Flow>): Promise<ApiResponse<Flow>>;
+    /**
+     * Delete flow by ID
+     * DELETE /api/v1/flows/:id
+     *
+     * @param id - Flow ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Execute a flow
+     * POST /api/v1/flows/:id/execute
+     *
+     * @param id - Flow ID
+     * @param input - Optional input data for flow execution
+     * @returns Flow execution result
+     */
+    execute(id: string, input?: Record<string, any>): Promise<ApiResponse<any>>;
+}
+
+declare class StudioClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get studio by ID
+     * GET /api/v1/studios/:id
+     *
+     * @param id - Studio ID
+     * @returns Studio details
+     */
+    getById(id: string): Promise<ApiResponse<Studio>>;
+    /**
+     * Get studio by slug
+     * GET /api/v1/studios/slug/:slug
+     *
+     * @param slug - Studio slug
+     * @returns Studio details
+     */
+    getBySlug(slug: string): Promise<ApiResponse<Studio>>;
+    /**
+     * List studios with optional filters
+     * GET /api/v1/studios
+     *
+     * @param params - Query parameters (page, limit, search)
+     * @returns Paginated list of studios
+     */
+    list(params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }): Promise<ApiResponse<Studio[]>>;
+    /**
+     * Create a new studio
+     * POST /api/v1/studios
+     *
+     * @param data - Studio creation data
+     * @returns Created studio
+     */
+    create(data: Partial<Studio>): Promise<ApiResponse<Studio>>;
+    /**
+     * Update studio by ID
+     * PATCH /api/v1/studios/:id
+     *
+     * @param id - Studio ID
+     * @param data - Studio update data
+     * @returns Updated studio
+     */
+    update(id: string, data: Partial<Studio>): Promise<ApiResponse<Studio>>;
+    /**
+     * Delete studio by ID
+     * DELETE /api/v1/studios/:id
+     *
+     * @param id - Studio ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Get data quality issues for a studio
+     * GET /api/v1/studios/:id/data-quality
+     *
+     * @param id - Studio ID
+     * @param params - Query parameters (resolved, severity)
+     * @returns List of data quality issues
+     */
+    getDataQualityIssues(id: string, params?: {
+        resolved?: boolean;
+        severity?: 'low' | 'medium' | 'high';
+    }): Promise<ApiResponse<any[]>>;
+}
+
+declare class NotificationClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get notification by ID
+     * GET /api/v1/notifications/:id
+     *
+     * @param id - Notification ID
+     * @returns Notification details
+     */
+    getById(id: string): Promise<ApiResponse<Notification>>;
+    /**
+     * List notifications with optional filters
+     * GET /api/v1/notifications
+     *
+     * @param params - Query parameters (tenantId, type, recipient, page, limit)
+     * @returns Paginated list of notifications
+     */
+    list(params?: {
+        tenantId?: string;
+        type?: string;
+        recipient?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<Notification[]>>;
+    /**
+     * Create a new notification
+     * POST /api/v1/notifications
+     *
+     * @param data - Notification creation data
+     * @returns Created notification
+     */
+    create(data: Partial<Notification>): Promise<ApiResponse<Notification>>;
+    /**
+     * Send notification immediately
+     * POST /api/v1/notifications/send
+     *
+     * @param data - Notification data to send
+     * @returns Sent notification
+     */
+    send(data: Partial<Notification>): Promise<ApiResponse<Notification>>;
+    /**
+     * Update notification by ID
+     * PATCH /api/v1/notifications/:id
+     *
+     * @param id - Notification ID
+     * @param data - Notification update data
+     * @returns Updated notification
+     */
+    update(id: string, data: Partial<Notification>): Promise<ApiResponse<Notification>>;
+    /**
+     * Delete notification by ID
+     * DELETE /api/v1/notifications/:id
+     *
+     * @param id - Notification ID
+     * @returns Empty response on success
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+}
+
+declare class DataQualityClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get data quality issue by ID
+     * GET /api/v1/data-quality/:id
+     *
+     * @param id - Issue ID
+     * @returns Data quality issue details
+     */
+    getById(id: string): Promise<ApiResponse<DataQualityIssue>>;
+    /**
+     * List data quality issues with optional filters
+     * GET /api/v1/data-quality
+     *
+     * @param params - Query parameters (tenantId, type, severity, resolved, page, limit)
+     * @returns Paginated list of data quality issues
+     */
+    list(params?: {
+        tenantId?: string;
+        type?: string;
+        severity?: 'low' | 'medium' | 'high';
+        resolved?: boolean;
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<DataQualityIssue[]>>;
+    /**
+     * Run data quality check for a tenant
+     * POST /api/v1/data-quality/check
+     *
+     * @param tenantId - Tenant ID to check
+     * @returns List of detected issues
+     */
+    runCheck(tenantId: string): Promise<ApiResponse<DataQualityIssue[]>>;
+    /**
+     * Resolve a data quality issue
+     * PATCH /api/v1/data-quality/:id/resolve
+     *
+     * @param id - Issue ID
+     * @returns Resolved issue
+     */
+    resolve(id: string): Promise<ApiResponse<DataQualityIssue>>;
+    /**
+     * Get data quality summary for a tenant
+     * GET /api/v1/data-quality/summary?tenantId=:id
+     *
+     * @param tenantId - Tenant ID
+     * @returns Summary of data quality issues
+     */
+    getSummary(tenantId: string): Promise<ApiResponse<any>>;
+}
+
+/**
+ * Custom error classes for Slotly SDK
+ */
+declare class SlotlyApiError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(code: string, message: string, statusCode?: number | undefined, details?: any | undefined);
+}
+declare class SlotlyAuthError extends SlotlyApiError {
+    constructor(message: string, details?: any);
+}
+declare class SlotlyNetworkError extends Error {
+    originalError?: any | undefined;
+    constructor(message: string, originalError?: any | undefined);
+}
+declare class SlotlyConfigurationError extends Error {
+    details?: any | undefined;
+    constructor(message: string, details?: any | undefined);
+}
+
+/**
+ * Authentication context extracted from validated Slotly request
+ */
+interface SlotlyAuthContext {
+    clientKey: string;
+    userId?: string;
+    tenantId?: string;
+    permissions?: string[];
+    tokenClaims?: Record<string, any>;
+}
+/**
+ * Extended Next.js request with Slotly context
+ */
+interface SlotlyRequest extends NextApiRequest {
+    slotlyContext: SlotlyAuthContext;
+}
+/**
+ * Safely extracts Slotly context from Next.js request
+ *
+ * Use this helper when you need to access the context outside of the middleware wrapper,
+ * or to check if the context exists.
+ *
+ * **Important:** Other route handlers should guard user-required flows:
+ * ```ts
+ * const context = getSlotlyContext(req);
+ * if (!context?.userId) {
+ *   return res.status(403).json({
+ *     success: false,
+ *     error: { code: 'USER_REQUIRED', message: 'User authentication required' }
+ *   });
+ * }
+ * ```
+ *
+ * @param req Next.js API request
+ * @returns SlotlyAuthContext if present, null otherwise
+ */
+declare function getSlotlyContext(req: NextApiRequest): SlotlyAuthContext | null;
+/**
+ * Middleware wrapper for Next.js API routes and Edge Functions
+ * Validates Slotly authentication headers and injects context into request
+ *
+ * **Supported Environments:**
+ * - Next.js API Routes (serverless functions)
+ * - Next.js Edge Functions (Edge Runtime)
+ * - Vercel Edge Functions
+ *
+ * **Note on Edge Functions:**
+ * Header names are normalized, but edge runtime may have different header casing.
+ * This middleware handles both `x-slotly-api-key` and `X-Slotly-Api-Key` variants.
+ *
+ * **Error Response Format:**
+ * All error responses follow the `ApiResponse<T>` format for consistency:
+ * ```ts
+ * {
+ *   success: false,
+ *   error: {
+ *     code: string,      // Error code (e.g., 'AUTH_ERROR', 'INTERNAL_ERROR')
+ *     message: string,   // Human-readable error message
+ *     details?: any      // Additional error details
+ *   }
+ * }
+ * ```
+ *
+ * **Usage:**
+ * ```ts
+ * import { validateSlotlyRequest } from "@slotly/sdk/middleware/validateSlotlyRequest";
+ *
+ * export default validateSlotlyRequest(async (req, res) => {
+ *   const { userId, clientKey, tenantId, permissions } = req.slotlyContext;
+ *
+ *   // Check if user authentication is required for this endpoint
+ *   if (!userId) {
+ *     return res.status(403).json({
+ *       success: false,
+ *       error: { code: 'USER_REQUIRED', message: 'User authentication required' }
+ *     });
+ *   }
+ *
+ *   // Authenticated + scoped — safe to proceed
+ *   res.json({ success: true, data: { userId, tenantId } });
+ * });
+ * ```
+ *
+ * **Performance Considerations:**
+ * - For high-throughput scenarios (e.g., many public booking flows), consider:
+ *   - Caching API key lookups with TTL (Redis, in-memory cache)
+ *   - Rate limiting per client key
+ *   - Database connection pooling for key validation
+ *
+ * @param handler Next.js API route handler or Edge Function handler
+ * @returns Wrapped handler with Slotly validation
+ */
+declare function validateSlotlyRequest(handler: (req: SlotlyRequest, res: NextApiResponse) => Promise<void> | void): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+interface SlotlyClientOptions {
+    /**
+     * Required: Function that returns the API key or service token.
+     * This must return a non-empty string.
+     */
+    getClientKey: () => Promise<string>;
+    /**
+     * Optional: Function that returns a Clerk JWT for user traceability.
+     * If provided and returns a token, it will be included in the Authorization header.
+     */
+    getUserToken?: () => Promise<string | null>;
+    /**
+     * Optional: Custom base URL for the API.
+     * Defaults to process.env.SLOTLY_API_URL or 'https://api.slotly.dev'
+     */
+    baseURL?: string;
+    /**
+     * Optional: Additional headers to include with every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional: Retry configuration.
+     */
+    retry?: {
+        maxRetries?: number;
+        retryDelay?: number;
+    };
+}
+/**
+ * Unified Slotly API client
+ * Provides typed access to all Slotly API domains
+ *
+ * Note: RegisterClient has been moved to @slotly/studio-sdk
+ * for studio-specific booking register operations.
+ */
+interface SlotlyApi {
+    tenant: TenantClient;
+    booking: BookingClient;
+    service: ServiceClient;
+    serviceItem: ServiceItemClient;
+    slot: SlotClient;
+    customer: CustomerClient;
+    flow: FlowClient;
+    studio: StudioClient;
+    notification: NotificationClient;
+    dataQuality: DataQualityClient;
+}
+/**
+ * Initialize and configure a new Slotly API client with dual authentication.
+ *
+ * This function creates an isolated Axios instance per call, ensuring:
+ * - SSR safety: Each request/context gets its own client instance
+ * - No cross-contamination: Different auth contexts don't interfere
+ * - Scalable: Supports future expansion for scoped keys, roles, or per-request tokens
+ *
+ * Authentication model:
+ * - **getClientKey()**: Required. Always sets `x-slotly-api-key` header.
+ *   Identifies the SDK/application making the request.
+ * - **getUserToken()**: Optional. Sets `Authorization: Bearer <token>` header if provided.
+ *   Provides user traceability and authorization scoping.
+ *
+ * @example Basic usage with API key (public SDK client):
+ * ```ts
+ * import { useSlotly } from '@slotly/sdk';
+ *
+ * const slotly = useSlotly({
+ *   getClientKey: async () => process.env.SLOTLY_SDK_KEY!,
+ * });
+ * ```
+ *
+ * @example Server-side with Clerk (authenticated, user-scoped):
+ * ```ts
+ * import { getToken } from '@clerk/clerk-sdk-node';
+ * import { useSlotly } from '@slotly/sdk';
+ *
+ * // In an API route or server action
+ * const slotly = useSlotly({
+ *   getClientKey: async () => process.env.SLOTLY_SDK_KEY!,
+ *   getUserToken: async () => await getToken(req),
+ * });
+ * ```
+ *
+ * @example Client-side with Clerk (Next.js):
+ * ```ts
+ * import { useAuth } from '@clerk/nextjs';
+ * import { useSlotly } from '@slotly/sdk';
+ *
+ * function MyComponent() {
+ *   const { getToken } = useAuth();
+ *
+ *   const slotly = useSlotly({
+ *     getClientKey: async () => process.env.NEXT_PUBLIC_SLOTLY_SDK_KEY!,
+ *     getUserToken: getToken,
+ *   });
+ * }
+ * ```
+ *
+ * @example Future: Scoped keys or role-based access
+ * ```ts
+ * // Future enhancement: Per-request scoping
+ * const slotly = useSlotly({
+ *   getClientKey: async () => getScopedKey(role, tenantId),
+ *   getUserToken: async () => getToken(),
+ * });
+ * ```
+ *
+ * @throws {SlotlyConfigurationError} If getClientKey is missing, returns null, undefined, or empty string.
+ */
+declare const useSlotly: (options: SlotlyClientOptions) => SlotlyApi;
+
+export { type ApiResponse, type Booking, type Category, type Customer, type DataQualityIssue, type Flow, type FlowStep, type Notification, type Service, type ServiceItem, type ServiceItemWithService, type ServiceWithItems, type Slot, type SlotlyApi, SlotlyApiError, type SlotlyAuthContext, SlotlyAuthError, type SlotlyClientOptions, SlotlyConfigurationError, SlotlyNetworkError, type SlotlyRequest, type Studio, type Tenant, type TenantBranding, type TenantFullConfig, useSlotly as default, getSlotlyContext, useSlotly, validateSlotlyRequest };