sfcc-dev-mcp 1.0.16 → 1.0.20

package/src/clients/base/abstract-documentation-client.ts

@@ -1,405 +0,0 @@
-/**
- * Abstract Documentation Client
- *
- * Base class for documentation clients (SFRA, ISML) that share common patterns:
- * - Category-based organization
- * - Caching with TTL
- * - Search with relevance scoring
- * - File-based document loading
- */
-
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { CacheManager } from '../../utils/cache.js';
-import { Logger } from '../../utils/logger.js';
-import {
-  extractDescriptionFromContent,
-  extractSections,
-  calculateSearchRelevance,
-  generateSearchPreview,
-} from '../../utils/markdown-utils.js';
-import { buildCategoryList, CategoryInfo } from '../../utils/category-utils.js';
-
-/**
- * Base document interface - extend for specific document types
- */
-export interface BaseDocument {
-  name: string;
-  title: string;
-  description: string;
-  sections: string[];
-  content: string;
-  category: string;
-  filename: string;
-  lastModified?: Date;
-}
-
-/**
- * Summary format for document lists
- */
-export interface DocumentSummary {
-  name: string;
-  title: string;
-  description: string;
-  category: string;
-  filename: string;
-}
-
-/**
- * Search result with relevance scoring
- */
-export interface SearchResult<T extends DocumentSummary> {
-  document: T;
-  relevance: number;
-  matchedSections: string[];
-  preview: string;
-}
-
-/**
- * Category information with count
- */
-export interface CategoryWithCount {
-  name: string;
-  displayName: string;
-  description: string;
-  count: number;
-}
-
-/**
- * Configuration for the documentation client
- */
-export interface DocumentationClientConfig<TCategory extends string> {
-  /** Name for logging */
-  clientName: string;
-  /** Path to documentation files */
-  docsPath: string;
-  /** Category mappings (document name -> category) */
-  categoryMappings: Record<string, TCategory>;
-  /** Category descriptions */
-  categoryDescriptions: Record<TCategory, CategoryInfo>;
-  /** Default category for unmapped documents */
-  defaultCategory: TCategory;
-  /** Cache key prefix */
-  cachePrefix: string;
-}
-
-/**
- * Abstract base class for documentation clients
- * Provides common functionality for loading, caching, and searching documents
- */
-export abstract class AbstractDocumentationClient<
-  TDocument extends BaseDocument,
-  TSummary extends DocumentSummary,
-  TCategory extends string,
-> {
-  protected readonly logger: Logger;
-  protected readonly cache: CacheManager;
-  protected readonly docsPath: string;
-  protected readonly config: DocumentationClientConfig<TCategory>;
-  protected documentsCache: TDocument[] | null = null;
-  protected lastScanTime: number = 0;
-  protected static readonly SCAN_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-
-  constructor(config: DocumentationClientConfig<TCategory>) {
-    this.config = config;
-    this.logger = Logger.getChildLogger(config.clientName);
-    this.cache = new CacheManager();
-    this.docsPath = config.docsPath;
-  }
-
-  /**
-   * Get list of all available documents with summaries
-   */
-  async getAvailableDocuments(): Promise<TSummary[]> {
-    this.logger.debug('Getting available documents');
-
-    const cacheKey = `${this.config.cachePrefix}:documents:list`;
-    const now = Date.now();
-
-    // Check cache validity
-    if (this.documentsCache && (now - this.lastScanTime) < AbstractDocumentationClient.SCAN_CACHE_TTL) {
-      const cached = this.cache.getSearchResults(cacheKey);
-      if (cached) {
-        return cached;
-      }
-    }
-
-    const documents = await this.loadAllDocuments();
-    const summaries = documents.map(doc => this.toSummary(doc));
-
-    // Sort by category and name
-    summaries.sort((a, b) => {
-      if (a.category !== b.category) {
-        return a.category.localeCompare(b.category);
-      }
-      return a.name.localeCompare(b.name);
-    });
-
-    this.cache.setSearchResults(cacheKey, summaries);
-    this.lastScanTime = now;
-
-    return summaries;
-  }
-
-  /**
-   * Get a specific document by name
-   */
-  async getDocument(documentName: string): Promise<TDocument | null> {
-    const normalizedName = this.normalizeDocumentName(documentName);
-    this.logger.debug(`Getting document: ${normalizedName}`);
-
-    const cacheKey = `${this.config.cachePrefix}:document:${normalizedName}`;
-    const cached = this.cache.getSearchResults(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const documents = await this.loadAllDocuments();
-    const document = documents.find(doc =>
-      doc.name.toLowerCase() === normalizedName.toLowerCase(),
-    );
-
-    if (!document) {
-      this.logger.warn(`Document not found: ${normalizedName}`);
-      return null;
-    }
-
-    this.cache.setSearchResults(cacheKey, document);
-    return document;
-  }
-
-  /**
-   * Search documents with relevance scoring
-   */
-  async searchDocuments(
-    query: string,
-    options?: { category?: string; limit?: number },
-  ): Promise<SearchResult<TSummary>[]> {
-    this.logger.debug(`Searching documents for: ${query}`);
-
-    const documents = await this.loadAllDocuments();
-    const searchQuery = query.toLowerCase();
-    const results: SearchResult<TSummary>[] = [];
-
-    for (const document of documents) {
-      // Skip if category filter doesn't match
-      if (options?.category && document.category !== options.category) {
-        continue;
-      }
-
-      const relevance = this.calculateDocumentRelevance(document, searchQuery);
-      if (relevance > 0) {
-        const matchedSections = this.findMatchedSections(document, searchQuery);
-        const preview = this.generateDocumentPreview(document, searchQuery);
-
-        results.push({
-          document: this.toSummary(document),
-          relevance,
-          matchedSections,
-          preview,
-        });
-      }
-    }
-
-    // Sort by relevance (highest first)
-    results.sort((a, b) => b.relevance - a.relevance);
-
-    // Apply limit if specified
-    return options?.limit ? results.slice(0, options.limit) : results;
-  }
-
-  /**
-   * Get documents filtered by category
-   */
-  async getDocumentsByCategory(category: string): Promise<TSummary[]> {
-    this.logger.debug(`Getting documents by category: ${category}`);
-
-    const documents = await this.loadAllDocuments();
-    return documents
-      .filter(doc => doc.category === category)
-      .map(doc => this.toSummary(doc));
-  }
-
-  /**
-   * Get available categories with counts
-   */
-  async getAvailableCategories(): Promise<CategoryWithCount[]> {
-    this.logger.debug('Getting available categories');
-
-    const cacheKey = `${this.config.cachePrefix}:categories`;
-    const cached = this.cache.getSearchResults(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const documents = await this.loadAllDocuments();
-    // Cast documents to the expected type - we know category will be TCategory since
-    // documents are created with that constraint via createDocument and getCategoryForItem
-    const categoryList = buildCategoryList(
-      documents as unknown as Array<{ category: TCategory }>,
-      this.config.categoryDescriptions,
-    );
-
-    const categories: CategoryWithCount[] = categoryList.map(cat => ({
-      name: cat.name,
-      displayName: cat.displayName,
-      description: cat.description,
-      count: cat.count ?? 0,
-    }));
-
-    this.cache.setSearchResults(cacheKey, categories);
-    return categories;
-  }
-
-  /**
-   * Clear all caches
-   */
-  clearCache(): void {
-    this.cache.clearAll();
-    this.documentsCache = null;
-    this.lastScanTime = 0;
-  }
-
-  // ==================== Protected methods for subclass customization ====================
-
-  // Batch size for parallel file reads (avoid file descriptor exhaustion)
-  protected static readonly PARALLEL_BATCH_SIZE = 30;
-
-  /**
-   * Load all documents from the docs directory
-   * Uses parallel batch processing for improved performance
-   */
-  protected async loadAllDocuments(): Promise<TDocument[]> {
-    if (this.documentsCache) {
-      return this.documentsCache;
-    }
-
-    this.logger.debug(`Scanning documentation directory: ${this.docsPath}`);
-
-    try {
-      const files = await fs.readdir(this.docsPath);
-      const mdFiles = files.filter(f =>
-        f.endsWith('.md') &&
-        !f.startsWith('.') &&
-        f !== 'README.md',
-      );
-
-      this.logger.debug(`Found ${mdFiles.length} documentation files`);
-
-      // Process files in parallel batches for faster loading
-      const documents: TDocument[] = [];
-      for (let i = 0; i < mdFiles.length; i += AbstractDocumentationClient.PARALLEL_BATCH_SIZE) {
-        const batch = mdFiles.slice(i, i + AbstractDocumentationClient.PARALLEL_BATCH_SIZE);
-        const results = await Promise.all(
-          batch.map(async file => {
-            const filePath = path.join(this.docsPath, file);
-            return this.parseDocumentFile(filePath, file);
-          }),
-        );
-        // Filter out null results and add to documents
-        for (const result of results) {
-          if (result) {
-            documents.push(result);
-          }
-        }
-      }
-
-      this.documentsCache = documents;
-      return documents;
-    } catch (error) {
-      this.logger.error(`Error loading documents: ${error}`);
-      throw new Error(`Failed to load documentation: ${error}`);
-    }
-  }
-
-  /**
-   * Parse a single document file - override for custom parsing
-   */
-  protected async parseDocumentFile(filePath: string, filename: string): Promise<TDocument | null> {
-    try {
-      const content = await fs.readFile(filePath, 'utf-8');
-      const stats = await fs.stat(filePath);
-
-      const documentName = filename.replace('.md', '');
-      const normalizedName = this.normalizeDocumentName(documentName);
-
-      // Extract title from first heading
-      const titleMatch = content.match(/^#\s+(.+)$/m);
-      const title = titleMatch ? titleMatch[1].trim() : documentName;
-
-      // Get category
-      const category = this.config.categoryMappings[normalizedName] ?? this.config.defaultCategory;
-
-      // Use base document creation
-      return this.createDocument({
-        name: documentName,
-        title,
-        description: extractDescriptionFromContent(content),
-        sections: extractSections(content, 2),
-        content,
-        category,
-        filename,
-        lastModified: stats.mtime,
-      });
-    } catch (error) {
-      this.logger.error(`Error parsing document file ${filename}: ${error}`);
-      return null;
-    }
-  }
-
-  /**
-   * Create a document instance - override for custom document types
-   */
-  protected abstract createDocument(baseData: BaseDocument): TDocument;
-
-  /**
-   * Convert document to summary - override for custom summary types
-   */
-  protected abstract toSummary(document: TDocument): TSummary;
-
-  /**
-   * Normalize document name for consistent lookup
-   */
-  protected normalizeDocumentName(name: string): string {
-    return name.toLowerCase();
-  }
-
-  /**
-   * Calculate relevance score for a document
-   */
-  protected calculateDocumentRelevance(document: TDocument, query: string): number {
-    return calculateSearchRelevance(query, {
-      name: document.name,
-      title: document.title,
-      description: document.description,
-      sections: document.sections,
-      content: document.content,
-    });
-  }
-
-  /**
-   * Find sections that match the search query
-   */
-  protected findMatchedSections(document: TDocument, query: string): string[] {
-    const matched: string[] = [];
-    const lowerQuery = query.toLowerCase();
-
-    for (const section of document.sections) {
-      if (section.toLowerCase().includes(lowerQuery)) {
-        matched.push(section);
-      }
-    }
-
-    return matched;
-  }
-
-  /**
-   * Generate a preview snippet for search results
-   */
-  protected generateDocumentPreview(document: TDocument, query: string): string {
-    if (!document.content.toLowerCase().includes(query.toLowerCase())) {
-      return document.description.slice(0, 200);
-    }
-    return generateSearchPreview(document.content, query, 100);
-  }
-}

package/src/clients/base/http-client.ts

@@ -1,152 +0,0 @@
-/**
- * Base HTTP Client for SFCC API requests
- *
- * This module provides a foundation for making authenticated HTTP requests to SFCC APIs.
- * It handles common concerns like authentication, request/response formatting, and error handling.
- */
-
-import { Logger } from '../../utils/logger.js';
-
-/**
- * HTTP request options interface
- */
-export interface HttpRequestOptions extends RequestInit {
-  headers?: Record<string, string>;
-}
-
-/**
- * Base HTTP client for SFCC API communication
- */
-export abstract class BaseHttpClient {
-  protected baseUrl: string;
-  protected logger: Logger;
-
-  constructor(baseUrl: string, loggerContext: string) {
-    this.baseUrl = baseUrl;
-    this.logger = Logger.getChildLogger(loggerContext);
-  }
-
-  /**
-   * Get authentication headers - must be implemented by subclasses
-   */
-  protected abstract getAuthHeaders(): Promise<Record<string, string>>;
-
-  /**
-   * Handle authentication errors - can be overridden by subclasses
-   */
-  protected async handleAuthError(): Promise<void> {
-    // Default implementation does nothing
-    // Subclasses can override to clear tokens, retry, etc.
-  }
-
-  /**
-   * Make an authenticated HTTP request
-   */
-  protected async makeRequest<T>(
-    endpoint: string,
-    options: HttpRequestOptions = {},
-  ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-    const method = options.method ?? 'GET';
-
-    this.logger.debug(`Making ${method} request to: ${endpoint}`);
-
-    // Get authentication headers
-    const authHeaders = await this.getAuthHeaders();
-
-    const requestOptions: RequestInit = {
-      ...options,
-      headers: {
-        'Content-Type': 'application/json',
-        ...authHeaders,
-        ...options.headers,
-      },
-    };
-
-    try {
-      const response = await fetch(url, requestOptions);
-
-      if (!response.ok) {
-        // Handle authentication errors
-        if (response.status === 401) {
-          this.logger.debug('Received 401, attempting to handle auth error');
-          await this.handleAuthError();
-
-          // Retry with fresh authentication
-          const newAuthHeaders = await this.getAuthHeaders();
-          requestOptions.headers = {
-            ...requestOptions.headers,
-            ...newAuthHeaders,
-          };
-
-          const retryResponse = await fetch(url, requestOptions);
-          if (!retryResponse.ok) {
-            const errorText = await retryResponse.text();
-            throw new Error(
-              `Request failed after retry: ${retryResponse.status} ${retryResponse.statusText} - ${errorText}`,
-            );
-          }
-
-          this.logger.debug('Retry request successful');
-          return retryResponse.json();
-        }
-
-        const errorText = await response.text();
-        throw new Error(`Request failed: ${response.status} ${response.statusText} - ${errorText}`);
-      }
-
-      this.logger.debug(`Request to ${endpoint} completed successfully`);
-      return response.json();
-    } catch (error) {
-      this.logger.error(`Network error during request to ${endpoint}: ${error}`);
-      throw error;
-    }
-  }
-
-  /**
-   * GET request
-   */
-  protected async get<T>(endpoint: string): Promise<T> {
-    return this.makeRequest<T>(endpoint, { method: 'GET' });
-  }
-
-  /**
-   * POST request
-   */
-  protected async post<T>(endpoint: string, data?: any): Promise<T> {
-    const options: HttpRequestOptions = { method: 'POST' };
-    if (data) {
-      options.body = JSON.stringify(data);
-    }
-    return this.makeRequest<T>(endpoint, options);
-  }
-
-  /**
-   * PUT request
-   */
-  protected async put<T>(endpoint: string, data?: any): Promise<T> {
-    const options: HttpRequestOptions = { method: 'PUT' };
-    if (data) {
-      options.body = JSON.stringify(data);
-    }
-    return this.makeRequest<T>(endpoint, options);
-  }
-
-  /**
-   * PATCH request
-   */
-  protected async patch<T>(endpoint: string, data?: any): Promise<T> {
-    const options: HttpRequestOptions = { method: 'PATCH' };
-    if (data) {
-      options.body = JSON.stringify(data);
-    }
-    return this.makeRequest<T>(endpoint, options);
-  }
-
-  /**
-   * DELETE request
-   */
-  protected async delete<T>(endpoint: string): Promise<T> {
-    return this.makeRequest<T>(endpoint, { method: 'DELETE' });
-  }
-}

package/src/clients/base/oauth-token.ts

@@ -1,164 +0,0 @@
-/**
- * OAuth Token Manager for SFCC OCAPI
- *
- * This module provides a singleton Token class that manages OAuth 2.0 access tokens
- * for SFCC OCAPI requests. It handles automatic token refresh when tokens expire.
- *
- * Security considerations:
- * - Tokens are stored in memory only, never persisted to disk
- * - Token values are not exposed in logs or error messages
- * - Automatic cleanup of expired tokens
- * - Secure comparison of token keys
- */
-
-import { OAuthToken, OAuthTokenResponse } from '../../types/types.js';
-
-/**
- * Singleton class for managing OAuth tokens
- * Handles token storage, expiration checking, and automatic refresh
- */
-export class TokenManager {
-  private static instance: TokenManager;
-  private tokens: Map<string, OAuthToken> = new Map();
-
-  private constructor() {}
-
-  /**
-   * Get the singleton instance of TokenManager
-   */
-  static getInstance(): TokenManager {
-    if (!TokenManager.instance) {
-      TokenManager.instance = new TokenManager();
-    }
-    return TokenManager.instance;
-  }
-
-  /**
-   * Generate a unique key for the token based on hostname and client ID
-   * Uses a hash-like approach to avoid storing sensitive data in keys
-   */
-  private getTokenKey(hostname: string, clientId: string): string {
-    // Simple key generation - in production you might use a more sophisticated approach
-    return `${hostname}:${clientId}`;
-  }
-
-  /**
-   * Check if a token is valid (exists and not expired)
-   * Includes a 60-second buffer to avoid using tokens that are about to expire
-   */
-  isTokenValid(hostname: string, clientId: string): boolean {
-    const key = this.getTokenKey(hostname, clientId);
-    const token = this.tokens.get(key);
-
-    if (!token) {
-      return false;
-    }
-
-    // Add 60-second buffer to avoid using tokens that are about to expire
-    const now = Date.now();
-    const expirationBuffer = 60 * 1000; // 60 seconds in milliseconds
-
-    const isValid = token.expiresAt > (now + expirationBuffer);
-
-    // Proactively clean up expired tokens
-    if (!isValid) {
-      this.tokens.delete(key);
-    }
-
-    return isValid;
-  }
-
-  /**
-   * Get a valid token for the given hostname and client ID
-   * Returns null if no valid token exists
-   */
-  getValidToken(hostname: string, clientId: string): string | null {
-    if (!this.isTokenValid(hostname, clientId)) {
-      return null;
-    }
-
-    const key = this.getTokenKey(hostname, clientId);
-    const token = this.tokens.get(key);
-    return token?.accessToken ?? null;
-  }
-
-  /**
-   * Store a new token from the OAuth response
-   * Validates the token response before storing
-   */
-  storeToken(hostname: string, clientId: string, tokenResponse: OAuthTokenResponse): void {
-    // Validate token response
-    if (!tokenResponse.access_token || typeof tokenResponse.access_token !== 'string') {
-      throw new Error('Invalid token response: missing or invalid access_token');
-    }
-    if (!tokenResponse.expires_in || typeof tokenResponse.expires_in !== 'number' || tokenResponse.expires_in <= 0) {
-      throw new Error('Invalid token response: missing or invalid expires_in');
-    }
-
-    const key = this.getTokenKey(hostname, clientId);
-    const now = Date.now();
-
-    const token: OAuthToken = {
-      accessToken: tokenResponse.access_token,
-      tokenType: tokenResponse.token_type || 'Bearer',
-      expiresAt: now + (tokenResponse.expires_in * 1000), // Convert seconds to milliseconds
-    };
-
-    this.tokens.set(key, token);
-  }
-
-  /**
-   * Clear a token (useful for testing or when a token becomes invalid)
-   */
-  clearToken(hostname: string, clientId: string): void {
-    const key = this.getTokenKey(hostname, clientId);
-    this.tokens.delete(key);
-  }
-
-  /**
-   * Clear all tokens
-   */
-  clearAllTokens(): void {
-    this.tokens.clear();
-  }
-
-  /**
-   * Get token expiration time for debugging purposes
-   * Does not expose the actual token value
-   */
-  getTokenExpiration(hostname: string, clientId: string): Date | null {
-    const key = this.getTokenKey(hostname, clientId);
-    const token = this.tokens.get(key);
-
-    if (!token) {
-      return null;
-    }
-
-    return new Date(token.expiresAt);
-  }
-
-  /**
-   * Get the number of tokens currently stored (for monitoring)
-   */
-  getTokenCount(): number {
-    return this.tokens.size;
-  }
-
-  /**
-   * Clean up all expired tokens
-   * This is called automatically during token validation but can be triggered manually
-   */
-  cleanupExpiredTokens(): number {
-    const now = Date.now();
-    let cleanedCount = 0;
-
-    for (const [key, token] of this.tokens.entries()) {
-      if (token.expiresAt <= now) {
-        this.tokens.delete(key);
-        cleanedCount++;
-      }
-    }
-
-    return cleanedCount;
-  }
-}