@slotchain/sdk 1.0.0

package/src/clients/tenant-client.ts

@@ -0,0 +1,148 @@
+import { AxiosInstance } from 'axios';
+import { ApiResponse, Tenant, TenantFullConfig } from '../types/api';
+
+export class TenantClient {
+  constructor(private client: AxiosInstance) {}
+
+  /**
+   * Get tenant configuration by slug
+   * GET /api/v1/tenant-config/:slug
+   */
+  async getBySlug(slug: string): Promise<ApiResponse<Tenant>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.get<ApiResponse<Tenant>>(
+      `/api/v1/tenant-config/${slug}`
+    );
+    return response.data;
+  }
+
+  /**
+   * Get tenant by ID
+   * GET /api/v1/tenants/:id
+   */
+  async getById(id: string): Promise<ApiResponse<Tenant>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.get<ApiResponse<Tenant>>(
+      `/api/v1/tenants/${id}`
+    );
+    return response.data;
+  }
+
+  /**
+   * List all tenants
+   * GET /api/v1/tenants
+   */
+  async list(params?: {
+    page?: number;
+    limit?: number;
+  }): Promise<ApiResponse<Tenant[]>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.get<ApiResponse<Tenant[]>>(
+      '/api/v1/tenants',
+      { params }
+    );
+    return response.data;
+  }
+
+  /**
+   * Create a new tenant
+   * POST /api/v1/tenants
+   */
+  async create(data: Partial<Tenant>): Promise<ApiResponse<Tenant>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.post<ApiResponse<Tenant>>(
+      '/api/v1/tenants',
+      data
+    );
+    return response.data;
+  }
+
+  /**
+   * Update tenant by ID
+   * PATCH /api/v1/tenants/:id
+   */
+  async update(id: string, data: Partial<Tenant>): Promise<ApiResponse<Tenant>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.patch<ApiResponse<Tenant>>(
+      `/api/v1/tenants/${id}`,
+      data
+    );
+    return response.data;
+  }
+
+  /**
+   * Delete tenant by ID
+   * DELETE /api/v1/tenants/:id
+   */
+  async delete(id: string): Promise<ApiResponse<void>> {
+    // TODO: Replace with actual endpoint when available
+    const response = await this.client.delete<ApiResponse<void>>(
+      `/api/v1/tenants/${id}`
+    );
+    return response.data;
+  }
+
+  /**
+   * 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
+   */
+  async getFullConfig(slug: string, includeServices: boolean = true): Promise<ApiResponse<TenantFullConfig>> {
+    const response = await this.client.get<ApiResponse<TenantFullConfig>>(
+      `/api/v1/tenants/${slug}`,
+      { params: { includeServices } }
+    );
+    return response.data;
+  }
+}
+

package/src/errors.ts

@@ -0,0 +1,41 @@
+/**
+ * Custom error classes for Slotly SDK
+ */
+
+export class SlotlyApiError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public statusCode?: number,
+    public details?: any
+  ) {
+    super(message);
+    this.name = 'SlotlyApiError';
+    Object.setPrototypeOf(this, SlotlyApiError.prototype);
+  }
+}
+
+export class SlotlyAuthError extends SlotlyApiError {
+  constructor(message: string, details?: any) {
+    super('AUTH_ERROR', message, 401, details);
+    this.name = 'SlotlyAuthError';
+    Object.setPrototypeOf(this, SlotlyAuthError.prototype);
+  }
+}
+
+export class SlotlyNetworkError extends Error {
+  constructor(message: string, public originalError?: any) {
+    super(message);
+    this.name = 'SlotlyNetworkError';
+    Object.setPrototypeOf(this, SlotlyNetworkError.prototype);
+  }
+}
+
+export class SlotlyConfigurationError extends Error {
+  constructor(message: string, public details?: any) {
+    super(message);
+    this.name = 'SlotlyConfigurationError';
+    Object.setPrototypeOf(this, SlotlyConfigurationError.prototype);
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,296 @@
+import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { TenantClient } from './clients/tenant-client';
+import { BookingClient } from './clients/booking-client';
+import { ServiceClient } from './clients/service-client';
+import { ServiceItemClient } from './clients/service-item-client';
+import { SlotClient } from './clients/slot-client';
+import { CustomerClient } from './clients/customer-client';
+import { FlowClient } from './clients/flow-client';
+import { StudioClient } from './clients/studio-client';
+import { NotificationClient } from './clients/notification-client';
+import { DataQualityClient } from './clients/data-quality-client';
+import { setupRequestInterceptor, setupResponseInterceptor, setupErrorInterceptor } from './interceptors';
+import { setupRetryInterceptor } from './retry';
+import { SlotlyConfigurationError } from './errors';
+
+// Re-export types
+export type {
+  ApiResponse,
+  Tenant,
+  TenantFullConfig,
+  TenantBranding,
+  Booking,
+  Service,
+  ServiceItem,
+  ServiceWithItems,
+  ServiceItemWithService,
+  Category,
+  Slot,
+  Customer,
+  Flow,
+  FlowStep,
+  Studio,
+  Notification,
+  DataQualityIssue,
+} from './types/api';
+
+// Re-export errors
+export {
+  SlotlyApiError,
+  SlotlyAuthError,
+  SlotlyNetworkError,
+  SlotlyConfigurationError,
+} from './errors';
+
+// Re-export middleware
+export {
+  validateSlotlyRequest,
+  getSlotlyContext,
+  type SlotlyAuthContext,
+  type SlotlyRequest,
+} from './middleware/validateSlotlyRequest';
+
+export 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.
+ */
+export interface SlotlyApi {
+  tenant: TenantClient;
+  booking: BookingClient;
+  service: ServiceClient;
+  serviceItem: ServiceItemClient;
+  slot: SlotClient;
+  customer: CustomerClient;
+  flow: FlowClient;
+  studio: StudioClient;
+  notification: NotificationClient;
+  dataQuality: DataQualityClient;
+}
+
+const defaultBaseURL = typeof process !== 'undefined' && process.env?.SLOTLY_API_URL 
+  ? process.env.SLOTLY_API_URL 
+  : 'https://api.slotly.dev';
+
+/**
+ * Creates a new isolated Axios instance with authentication interceptors.
+ * Client isolation per instantiation ensures:
+ * - No cross-contamination between different auth contexts
+ * - SSR safety (each request gets its own client instance)
+ * - Proper isolation for scoped keys/roles in the future
+ */
+function createAuthenticatedClient(options: SlotlyClientOptions): AxiosInstance {
+  const client = axios.create({
+    baseURL: options.baseURL || defaultBaseURL,
+    headers: {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+    timeout: 30000, // 30 seconds
+  });
+
+  // Request interceptor: Add authentication headers
+  // This interceptor runs once per request and fetches fresh tokens
+  client.interceptors.request.use(
+    async (config: InternalAxiosRequestConfig) => {
+      try {
+        // Fetch both credentials in parallel for performance
+        const [clientKeyPromise, userTokenPromise] = [
+          options.getClientKey(),
+          options.getUserToken?.() ?? Promise.resolve(null),
+        ];
+
+        const [clientKey, userToken] = await Promise.all([
+          clientKeyPromise,
+          userTokenPromise,
+        ]);
+
+        // Validate that clientKey is provided and non-empty
+        if (!clientKey || typeof clientKey !== 'string' || clientKey.trim().length === 0) {
+          throw new SlotlyConfigurationError(
+            'getClientKey() must return a non-empty string. API key is required for all requests.',
+            { received: clientKey }
+          );
+        }
+
+        // Always set the API key header
+        config.headers['x-slotly-api-key'] = clientKey;
+
+        // Conditionally set Authorization header if user token is provided
+        if (userToken && typeof userToken === 'string' && userToken.trim().length > 0) {
+          config.headers['Authorization'] = `Bearer ${userToken}`;
+        }
+
+        return config;
+      } catch (error) {
+        // If it's already a SlotlyConfigurationError, re-throw it
+        if (error instanceof SlotlyConfigurationError) {
+          throw error;
+        }
+
+        // Handle errors from getClientKey() or getUserToken()
+        // If getClientKey fails, this is critical
+        if (error && typeof error === 'object' && 'message' in error) {
+          // eslint-disable-next-line no-console
+          console.error('[Slotly SDK] Failed to retrieve authentication credentials:', error);
+          
+          throw new SlotlyConfigurationError(
+            `Failed to retrieve authentication credentials: ${error.message}`,
+            { originalError: error }
+          );
+        }
+
+        throw error;
+      }
+    },
+    (error: Error) => Promise.reject(error)
+  );
+
+  // Request interceptor: Logging
+  client.interceptors.request.use(setupRequestInterceptor());
+
+  // Response interceptor: Logging and error shaping
+  client.interceptors.response.use(
+    (response: any) => setupResponseInterceptor()(response),
+    (error: any) => setupErrorInterceptor()(error)
+  );
+
+  // Error interceptor: Retry logic
+  client.interceptors.response.use(
+    (response: any) => response,
+    setupRetryInterceptor({
+      maxRetries: options.retry?.maxRetries ?? 3,
+      retryDelay: options.retry?.retryDelay ?? 1000,
+    })
+  );
+
+  return client;
+}
+
+/**
+ * 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.
+ */
+export const useSlotly = (options: SlotlyClientOptions): SlotlyApi => {
+  // Validate required options
+  if (!options || typeof options !== 'object') {
+    throw new SlotlyConfigurationError(
+      'useSlotly() requires an options object with getClientKey function'
+    );
+  }
+
+  if (!options.getClientKey || typeof options.getClientKey !== 'function') {
+    throw new SlotlyConfigurationError(
+      'getClientKey must be a function that returns Promise<string>'
+    );
+  }
+
+  // Create a new isolated client instance for this configuration
+  // This ensures SSR safety and prevents cross-contamination
+  const client = createAuthenticatedClient(options);
+
+  // Return the unified API object with all domain clients
+  return {
+    tenant: new TenantClient(client),
+    booking: new BookingClient(client),
+    service: new ServiceClient(client),
+    serviceItem: new ServiceItemClient(client),
+    slot: new SlotClient(client),
+    customer: new CustomerClient(client),
+    flow: new FlowClient(client),
+    studio: new StudioClient(client),
+    notification: new NotificationClient(client),
+    dataQuality: new DataQualityClient(client),
+  };
+};
+
+// Default export for convenience
+export default useSlotly;

package/src/interceptors.ts

@@ -0,0 +1,81 @@
+import { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+import { SlotlyApiError, SlotlyAuthError, SlotlyNetworkError } from './errors';
+import { ApiResponse } from './types/api';
+
+/**
+ * Request interceptor for logging
+ */
+export function setupRequestInterceptor() {
+  return (config: InternalAxiosRequestConfig) => {
+    // TODO: Add request logging if needed
+    // console.log(`[Slotly SDK] ${config.method?.toUpperCase()} ${config.url}`);
+    return config;
+  };
+}
+
+/**
+ * Response interceptor for error shaping and logging
+ */
+export function setupResponseInterceptor() {
+  return (response: AxiosResponse) => {
+    // TODO: Add response logging if needed
+    // console.log(`[Slotly SDK] Response: ${response.status} ${response.config.url}`);
+    return response;
+  };
+}
+
+/**
+ * Error interceptor for shaping errors into SlotlyApiError
+ */
+export function setupErrorInterceptor() {
+  return (error: AxiosError<ApiResponse<any>>) => {
+    // Network errors (no response)
+    if (!error.response) {
+      const networkError = new SlotlyNetworkError(
+        error.message || 'Network error occurred',
+        error
+      );
+      // TODO: Add error logging
+      // console.error('[Slotly SDK] Network error:', networkError);
+      return Promise.reject(networkError);
+    }
+
+    const { status, data } = error.response;
+
+    // Handle authentication errors
+    if (status === 401 || status === 403) {
+      const authError = new SlotlyAuthError(
+        data?.error?.message || 'Authentication failed',
+        data?.error?.details
+      );
+      // TODO: Add error logging
+      // console.error('[Slotly SDK] Auth error:', authError);
+      return Promise.reject(authError);
+    }
+
+    // Handle API errors with structured error format
+    if (data?.error) {
+      const apiError = new SlotlyApiError(
+        data.error.code || 'API_ERROR',
+        data.error.message || 'An error occurred',
+        status,
+        data.error.details
+      );
+      // TODO: Add error logging
+      // console.error('[Slotly SDK] API error:', apiError);
+      return Promise.reject(apiError);
+    }
+
+    // Handle other HTTP errors
+    const apiError = new SlotlyApiError(
+      'HTTP_ERROR',
+      error.message || `Request failed with status ${status}`,
+      status,
+      data
+    );
+    // TODO: Add error logging
+    // console.error('[Slotly SDK] HTTP error:', apiError);
+    return Promise.reject(apiError);
+  };
+}
+