@slotchain/sdk 1.0.0

package/src/middleware/validateSlotlyRequest.ts

@@ -0,0 +1,337 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { jwtDecode } from 'jwt-decode';
+import { SlotlyAuthError } from '../errors';
+
+/**
+ * Authentication context extracted from validated Slotly request
+ */
+export interface SlotlyAuthContext {
+  clientKey: string;
+  userId?: string;
+  tenantId?: string;
+  permissions?: string[];
+  tokenClaims?: Record<string, any>;
+}
+
+/**
+ * Extended Next.js request with Slotly context
+ */
+export interface SlotlyRequest extends NextApiRequest {
+  slotlyContext: SlotlyAuthContext;
+}
+
+/**
+ * Next.js API route handler type
+ */
+export type NextApiHandler = (
+  req: NextApiRequest,
+  res: NextApiResponse
+) => Promise<void> | void;
+
+/**
+ * Mock allowlist for client keys
+ * 
+ * ⚠️ DEVELOPMENT ONLY: This is a mock allowlist for development/testing purposes.
+ * 
+ * In production, this MUST be replaced with:
+ * - A secure database lookup (e.g., PostgreSQL, DynamoDB)
+ * - A secrets management system (e.g., AWS Secrets Manager, HashiCorp Vault)
+ * - A Redis cache with appropriate TTL for high-throughput scenarios
+ * - Rate limiting per client key to prevent abuse
+ * 
+ * Consider implementing:
+ * - Key rotation policies
+ * - Per-key rate limiting (especially important for public booking flows)
+ * - Audit logging of key usage
+ * - Revocation mechanisms
+ * 
+ * TODO: Replace with actual database or cache lookup
+ */
+const allowedKeys: Record<
+  string,
+  { tenantId: string; permissions: string[] }
+> = {
+  'test-key-123': {
+    tenantId: 'bright-accountants',
+    permissions: ['booking:create'],
+  },
+  'admin-ui': {
+    tenantId: 'slotly-core',
+    permissions: ['*'],
+  },
+};
+
+/**
+ * Validates an API key against the allowlist
+ * Returns the associated tenant and permissions if valid
+ */
+function validateApiKey(clientKey: string): {
+  tenantId: string;
+  permissions: string[];
+} | null {
+  if (!clientKey || typeof clientKey !== 'string') {
+    return null;
+  }
+
+  const keyInfo = allowedKeys[clientKey];
+  if (!keyInfo) {
+    return null;
+  }
+
+  return {
+    tenantId: keyInfo.tenantId,
+    permissions: keyInfo.permissions,
+  };
+}
+
+/**
+ * Extracts and decodes JWT token from Authorization header
+ * 
+ * If present, extracts user identity from the token. This is optional:
+ * - Anonymous/client-only flows: Authorization header not required
+ * - User-authenticated flows: Authorization header provides user traceability
+ * 
+ * Returns userId from 'sub' claim and full token claims for additional context.
+ * Note: Currently decodes without signature validation (development).
+ * TODO: Add signature validation in production using Clerk or JWT library.
+ */
+function extractUserToken(authHeader?: string): {
+  userId?: string;
+  tokenClaims?: Record<string, any>;
+} | null {
+  if (!authHeader || typeof authHeader !== 'string') {
+    return null;
+  }
+
+  // Extract Bearer token
+  const bearerMatch = authHeader.match(/^Bearer\s+(.+)$/i);
+  if (!bearerMatch || !bearerMatch[1]) {
+    return null;
+  }
+
+  const token = bearerMatch[1];
+
+  try {
+    // Decode JWT without signature validation
+    // WARNING: This is for development only. Production should validate signatures.
+    // TODO: Add signature validation in production (e.g., using Clerk's verifyToken or jsonwebtoken)
+    const claims = jwtDecode(token) as Record<string, any>;
+
+    if (!claims || typeof claims !== 'object') {
+      // eslint-disable-next-line no-console
+      console.error('[Slotly SDK] Invalid JWT token: claims is not an object');
+      return null;
+    }
+
+    // Extract userId from 'sub' claim
+    const userId = claims.sub || claims.user_id || claims.userId;
+
+    return {
+      userId: typeof userId === 'string' ? userId : undefined,
+      tokenClaims: claims,
+    };
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error('[Slotly SDK] Failed to decode JWT token:', error);
+    return null;
+  }
+}
+
+/**
+ * Validates Slotly request headers and extracts authentication context
+ * 
+ * Validates:
+ * - `x-slotly-api-key`: Required header identifying the client/application
+ * - `Authorization: Bearer ...`: Optional header providing user identity (if present, extracts user identity)
+ * 
+ * Throws SlotlyAuthError if validation fails. Error includes code, message, and details
+ * fields that align with the ApiResponse<T> error shape for consistent error handling.
+ * 
+ * @throws {SlotlyAuthError} If x-slotly-api-key is missing, invalid, or not in allowlist
+ */
+function validateAndExtractContext(req: NextApiRequest): SlotlyAuthContext {
+  // Extract x-slotly-api-key header (required)
+  // Support both lowercase and mixed case headers
+  const clientKey =
+    (req.headers['x-slotly-api-key'] as string) ||
+    (req.headers['X-Slotly-Api-Key'] as string) ||
+    (req.headers['x-slotly-api-key'] as string);
+
+  if (!clientKey || typeof clientKey !== 'string' || clientKey.trim().length === 0) {
+    const error = new SlotlyAuthError(
+      'Missing or invalid x-slotly-api-key header. API key is required.',
+      { header: 'x-slotly-api-key' }
+    );
+    // eslint-disable-next-line no-console
+    console.error('[Slotly SDK] Validation failed:', error.message);
+    throw error;
+  }
+
+  // Validate API key against allowlist
+  const keyInfo = validateApiKey(clientKey);
+  if (!keyInfo) {
+    const error = new SlotlyAuthError(
+      'Invalid API key. Client key not found in allowlist.',
+      { clientKey: clientKey.substring(0, 8) + '...' }
+    );
+    // eslint-disable-next-line no-console
+    console.error('[Slotly SDK] Validation failed:', error.message);
+    throw error;
+  }
+
+  // Extract Authorization header (optional)
+  // Support both lowercase and mixed case headers
+  const authHeader =
+    (req.headers.authorization as string) ||
+    (req.headers.Authorization as string);
+
+  const tokenInfo = authHeader ? extractUserToken(authHeader) : null;
+
+  // Build context
+  const context: SlotlyAuthContext = {
+    clientKey,
+    tenantId: keyInfo.tenantId,
+    permissions: keyInfo.permissions,
+    ...(tokenInfo?.userId && { userId: tokenInfo.userId }),
+    ...(tokenInfo?.tokenClaims && { tokenClaims: tokenInfo.tokenClaims }),
+  };
+
+  return context;
+}
+
+/**
+ * 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
+ */
+export function getSlotlyContext(
+  req: NextApiRequest
+): SlotlyAuthContext | null {
+  const slotlyReq = req as SlotlyRequest;
+  return slotlyReq.slotlyContext || 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
+ */
+export function validateSlotlyRequest(
+  handler: (req: SlotlyRequest, res: NextApiResponse) => Promise<void> | void
+) {
+  return async (req: NextApiRequest, res: NextApiResponse): Promise<void> => {
+    try {
+      // Validate and extract context
+      const context = validateAndExtractContext(req);
+
+      // Inject context into request
+      const slotlyReq = req as SlotlyRequest;
+      slotlyReq.slotlyContext = context;
+
+      // Call the actual handler with validated request
+      await handler(slotlyReq, res);
+    } catch (error) {
+      // Handle SlotlyAuthError
+      if (error instanceof SlotlyAuthError) {
+        // eslint-disable-next-line no-console
+        console.error(
+          '[Slotly SDK] Authentication failed:',
+          error.message,
+          error.details
+        );
+
+        // Error response follows ApiResponse<T> format for consistency
+        // SlotlyAuthError includes code, message, and details fields that align
+        // with the ApiResponse<T> error shape
+        res.status(error.statusCode || 401).json({
+          success: false,
+          error: {
+            code: error.code,
+            message: error.message,
+            details: error.details,
+          },
+        });
+        return;
+      }
+
+      // Handle other errors
+      // eslint-disable-next-line no-console
+      console.error('[Slotly SDK] Unexpected error:', error);
+
+      // Error response follows ApiResponse<T> format for consistency
+      res.status(500).json({
+        success: false,
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: 'An unexpected error occurred',
+        },
+      });
+    }
+  };
+}
+

package/src/mocks/mockAdapter.ts

@@ -0,0 +1,32 @@
+import axiosMockAdapter from 'axios-mock-adapter';
+import { AxiosInstance } from 'axios';
+
+/**
+ * Setup mock adapter for testing
+ * This allows you to mock API responses during development and testing
+ *
+ * Usage:
+ * ```ts
+ * import { createSlotlyClient } from '../client';
+ * import { setupMockAdapter } from './mocks/mockAdapter';
+ *
+ * const client = createSlotlyClient();
+ * const mockAdapter = setupMockAdapter(client);
+ *
+ * // Mock a response
+ * mockAdapter.onGet('/api/v1/tenant-config/my-slug').reply(200, {
+ *   success: true,
+ *   data: { id: '1', slug: 'my-slug', name: 'My Tenant' }
+ * });
+ * ```
+ */
+export function setupMockAdapter(client: AxiosInstance): axiosMockAdapter {
+  const mockAdapter = new axiosMockAdapter(client, {
+    delayResponse: 0, // Set to simulate network delay if needed
+  });
+
+  // TODO: Add default mock responses for common endpoints if needed
+
+  return mockAdapter;
+}
+

package/src/retry.ts

@@ -0,0 +1,82 @@
+import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
+
+/**
+ * Exponential backoff retry configuration
+ */
+export interface RetryConfig {
+  maxRetries: number;
+  retryDelay: number; // Base delay in milliseconds
+  retryCondition?: (error: AxiosError) => boolean;
+}
+
+const defaultRetryConfig: RetryConfig = {
+  maxRetries: 3,
+  retryDelay: 1000, // 1 second
+  retryCondition: (error: AxiosError) => {
+    // Retry on network errors and 5xx server errors
+    if (!error.response) {
+      return true; // Network error
+    }
+    const status = error.response.status;
+    return status >= 500 && status < 600;
+  },
+};
+
+/**
+ * Calculate exponential backoff delay with jitter
+ */
+function calculateRetryDelay(attempt: number, baseDelay: number): number {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = Math.random() * 0.3 * exponentialDelay; // Add up to 30% jitter
+  return exponentialDelay + jitter;
+}
+
+/**
+ * Axios interceptor for retry logic
+ */
+export function setupRetryInterceptor(
+  config: RetryConfig = defaultRetryConfig
+) {
+  return async (error: AxiosError) => {
+    const requestConfig = error.config as InternalAxiosRequestConfig & {
+      _retry?: boolean;
+      _retryCount?: number;
+    };
+
+    // If no config, reject
+    if (!requestConfig) {
+      return Promise.reject(error);
+    }
+
+    // Initialize retry count
+    if (requestConfig._retryCount === undefined) {
+      requestConfig._retryCount = 0;
+    }
+
+    // Check if we should retry
+    const shouldRetry =
+      requestConfig._retryCount < config.maxRetries &&
+      (!config.retryCondition || config.retryCondition(error));
+
+    if (!shouldRetry) {
+      return Promise.reject(error);
+    }
+
+    // Mark as retrying
+    requestConfig._retry = true;
+    requestConfig._retryCount += 1;
+
+    // Calculate delay
+    const delay = calculateRetryDelay(
+      requestConfig._retryCount - 1,
+      config.retryDelay
+    );
+
+    // Wait before retrying
+    await new Promise((resolve) => setTimeout(resolve, delay));
+
+    // Retry the request
+    return axios(requestConfig);
+  };
+}
+

package/src/types/api.ts

@@ -0,0 +1,192 @@
+/**
+ * Standard API response format for all Slotly API endpoints
+ */
+export 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
+ */
+
+export interface Tenant {
+  id: string;
+  slug: string;
+  name: string;
+  // TODO: Add actual tenant properties
+}
+
+/**
+ * Tenant branding configuration
+ */
+export interface TenantBranding {
+  logoUrl?: string;
+  primaryColor?: string;
+  secondaryColor?: string;
+  faviconUrl?: string;
+  customCss?: string;
+  // TODO: Add additional branding properties
+}
+
+/**
+ * Service item within a service
+ */
+export interface ServiceItem {
+  id: string;
+  serviceId: string;
+  name: string;
+  description?: string;
+  price?: number;
+  duration?: number;
+  available?: boolean;
+  // TODO: Add actual service item properties
+}
+
+/**
+ * Enhanced Service type with nested service items
+ */
+export 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
+ */
+export interface ServiceItemWithService extends ServiceItem {
+  /** Parent service reference (optional, for convenience when fetching items separately) */
+  parentService?: Service;
+}
+
+/**
+ * Category extracted from services
+ */
+export 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[];
+  // TODO: Add actual category properties
+}
+
+export interface Booking {
+  id: string;
+  tenantId: string;
+  slotId?: string;
+  customerId?: string;
+  status?: string;
+  // TODO: Add actual booking properties
+}
+
+export interface Service {
+  id: string;
+  tenantId: string;
+  name: string;
+  description?: string;
+  duration?: number;
+  price?: number;
+  // TODO: Add actual service properties
+}
+
+export interface Slot {
+  id: string;
+  tenantId: string;
+  serviceId?: string;
+  startTime: string;
+  endTime: string;
+  available: boolean;
+  // TODO: Add actual slot properties
+}
+
+export interface Customer {
+  id: string;
+  tenantId: string;
+  email?: string;
+  name?: string;
+  phone?: string;
+  // TODO: Add actual customer properties
+}
+
+export interface Flow {
+  id: string;
+  tenantId: string;
+  name: string;
+  steps?: FlowStep[];
+  // TODO: Add actual flow properties
+}
+
+export interface FlowStep {
+  id: string;
+  type: string;
+  config?: Record<string, any>;
+  // TODO: Add actual flow step properties
+}
+
+export interface Studio {
+  id: string;
+  name: string;
+  slug?: string;
+  // TODO: Add actual studio properties
+}
+
+export interface Notification {
+  id: string;
+  tenantId?: string;
+  type: string;
+  recipient: string;
+  content: string;
+  sentAt?: string;
+  // TODO: Add actual notification properties
+}
+
+export interface DataQualityIssue {
+  id: string;
+  tenantId?: string;
+  type: string;
+  severity: 'low' | 'medium' | 'high';
+  message: string;
+  resolved: boolean;
+  // TODO: Add actual data quality issue properties
+}
+
+/**
+ * Full tenant configuration including branding, services, and service items
+ * Service items are nested within each service object (not as a separate top-level array)
+ */
+export 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>;
+  // TODO: Add additional tenant config properties
+}
+