feat: Introduce ContentstackPlugin interface for extensible plugin architecture

nadeem-cs · nadeem-cs · commit 1627f1a76dde · 2025-09-17T15:24:31.000+05:30
- Added ContentstackPlugin interface to support custom plugins in the Contentstack SDK.
- Updated stack function to utilize plugins for request and response interception.
- Implemented comprehensive unit tests for plugin functionality, including various implementation patterns and edge cases.
- Enhanced type safety for plugins in StackConfig.
- Created tests for plugin interactions with interceptors, error handling, and performance scenarios.
- Added support for configurable plugins and state management within plugins.
diff --git a/.talismanrc b/.talismanrc
@@ -3,4 +3,12 @@ fileignoreconfig:
   checksum: dffbcb14c5761976a9b6ab90b96c7e4fc5784eebe381cf48014618cc93355dbc
 - filename: test/unit/query-optimization-comprehensive.spec.ts
   checksum: f5aaf6c784d7c101a05ca513c584bbd6e95f963d1e42779f2596050d9bcbac96
+- filename: src/lib/types.ts
+  checksum: 57d2f7eede6ab19ff92db9799e752e7dfa44c1368314525a41ab1a241778a230
+- filename: examples/custom-plugin.ts
+  checksum: 51a4b01f7c5f76c97c588bb0575cefd1f9462b28d88b24bb9f7dc2780aa323c5
+- filename: test/unit/plugin-comprehensive.spec.ts
+  checksum: d508f95f4a7eb5bed873ca91a5e1914aa4d5261f27593edb568502cb5855042e
+- filename: test/unit/plugin-interceptor-comprehensive.spec.ts
+  checksum: b9fbe9da166fd209853307f9f60464d25f805f82e9dbe09d5f476fdd5eb05d47
 version: ""
diff --git a/examples/custom-plugin.ts b/examples/custom-plugin.ts
@@ -0,0 +1,273 @@
+/**
+ * Example implementations of ContentstackPlugin interface
+ * This file demonstrates various ways to create and use plugins
+ */
+import contentstack, { ContentstackPlugin } from '@contentstack/delivery-sdk';
+import { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+// Example 1: Simple logging plugin as a class
+class LoggingPlugin implements ContentstackPlugin {
+  private requestCount = 0;
+
+  onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+    this.requestCount++;
+    console.log(`[Plugin] Request #${this.requestCount}: ${config.method?.toUpperCase()} ${config.url}`);
+    
+    return {
+      ...config,
+      headers: {
+        ...config.headers,
+        'X-Request-ID': `req-${this.requestCount}-${Date.now()}`
+      }
+    };
+  }
+
+  onResponse(request: AxiosRequestConfig, response: AxiosResponse, data: any): AxiosResponse {
+    console.log(`[Plugin] Response: ${response.status} for ${request.url}`);
+    
+    return {
+      ...response,
+      data: {
+        ...data,
+        _meta: {
+          requestId: request.headers?.['X-Request-ID'],
+          processedAt: new Date().toISOString()
+        }
+      }
+    };
+  }
+
+  getRequestCount(): number {
+    return this.requestCount;
+  }
+}
+
+// Example 2: Authentication plugin as an object
+const authPlugin: ContentstackPlugin = {
+  onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+    return {
+      ...config,
+      headers: {
+        ...config.headers,
+        'X-Custom-Auth': 'Bearer my-custom-token',
+        'X-Client-Version': '1.0.0'
+      }
+    };
+  },
+
+  onResponse(request: AxiosRequestConfig, response: AxiosResponse, data: any): AxiosResponse {
+    // Remove any sensitive information from the response
+    if (data && typeof data === 'object') {
+      const sanitized = { ...data };
+      delete sanitized.internal_data;
+      delete sanitized.debug_info;
+      
+      return {
+        ...response,
+        data: sanitized
+      };
+    }
+    
+    return response;
+  }
+};
+
+// Example 3: Performance monitoring plugin
+class PerformancePlugin implements ContentstackPlugin {
+  private requestTimes = new Map<string, number>();
+  private metrics = {
+    totalRequests: 0,
+    totalTime: 0,
+    slowRequests: 0,
+    errors: 0
+  };
+
+  onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+    const requestId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.requestTimes.set(requestId, performance.now());
+    this.metrics.totalRequests++;
+
+    return {
+      ...config,
+      metadata: {
+        ...config.metadata,
+        requestId,
+        startTime: performance.now()
+      }
+    };
+  }
+
+  onResponse(request: AxiosRequestConfig, response: AxiosResponse, data: any): AxiosResponse {
+    const requestId = request.metadata?.requestId;
+    const startTime = this.requestTimes.get(requestId);
+
+    if (startTime) {
+      const duration = performance.now() - startTime;
+      this.metrics.totalTime += duration;
+      
+      if (duration > 1000) { // Slow request threshold: 1 second
+        this.metrics.slowRequests++;
+        console.warn(`[Performance] Slow request detected: ${duration.toFixed(2)}ms for ${request.url}`);
+      }
+      
+      this.requestTimes.delete(requestId);
+    }
+
+    if (response.status >= 400) {
+      this.metrics.errors++;
+    }
+
+    return {
+      ...response,
+      data: {
+        ...data,
+        _performance: {
+          duration: startTime ? performance.now() - startTime : 0,
+          timestamp: new Date().toISOString()
+        }
+      }
+    };
+  }
+
+  getMetrics() {
+    return {
+      ...this.metrics,
+      averageTime: this.metrics.totalRequests > 0 
+        ? this.metrics.totalTime / this.metrics.totalRequests 
+        : 0
+    };
+  }
+
+  printReport() {
+    const metrics = this.getMetrics();
+    console.log(`
+Performance Report:
+- Total Requests: ${metrics.totalRequests}
+- Average Response Time: ${metrics.averageTime.toFixed(2)}ms
+- Slow Requests: ${metrics.slowRequests}
+- Errors: ${metrics.errors}
+    `);
+  }
+}
+
+// Example 4: Caching plugin with TTL
+class CachePlugin implements ContentstackPlugin {
+  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+  private defaultTTL = 5 * 60 * 1000; // 5 minutes
+
+  onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+    const cacheKey = this.generateCacheKey(config);
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < cached.ttl) {
+      // In a real implementation, you might want to return cached data directly
+      // This is just for demonstration
+      console.log(`[Cache] Cache hit for ${cacheKey}`);
+      return { ...config, fromCache: true };
+    }
+
+    return { ...config, cacheKey };
+  }
+
+  onResponse(request: AxiosRequestConfig, response: AxiosResponse, data: any): AxiosResponse {
+    if (response.status === 200 && request.cacheKey && !request.fromCache) {
+      this.cache.set(request.cacheKey, {
+        data,
+        timestamp: Date.now(),
+        ttl: this.defaultTTL
+      });
+      console.log(`[Cache] Cached response for ${request.cacheKey}`);
+    }
+
+    return response;
+  }
+
+  private generateCacheKey(config: AxiosRequestConfig): string {
+    return `${config.method || 'GET'}_${config.url}_${JSON.stringify(config.params || {})}`;
+  }
+
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  getCacheStats() {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys())
+    };
+  }
+}
+
+// Example 5: Error handling and retry plugin
+const errorHandlingPlugin: ContentstackPlugin = {
+  onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+    return {
+      ...config,
+      retryAttempts: config.retryAttempts || 0,
+      maxRetries: 3
+    };
+  },
+
+  onResponse(request: AxiosRequestConfig, response: AxiosResponse, data: any): AxiosResponse {
+    if (response.status >= 400) {
+      console.error(`[Error] HTTP ${response.status}: ${response.statusText} for ${request.url}`);
+      
+      // Log additional error context
+      if (response.status >= 500) {
+        console.error('[Error] Server error detected. Consider implementing retry logic.');
+      } else if (response.status === 429) {
+        console.warn('[Error] Rate limit exceeded. Implementing backoff strategy recommended.');
+      }
+    }
+
+    return {
+      ...response,
+      data: {
+        ...data,
+        _error_handled: response.status >= 400,
+        _error_code: response.status >= 400 ? response.status : null
+      }
+    };
+  }
+};
+
+// Usage example
+function createStackWithPlugins() {
+  const loggingPlugin = new LoggingPlugin();
+  const performancePlugin = new PerformancePlugin();
+  const cachePlugin = new CachePlugin();
+
+  const stack = contentstack.stack({
+    apiKey: 'your-api-key',
+    deliveryToken: 'your-delivery-token',
+    environment: 'your-environment',
+    plugins: [
+      loggingPlugin,        // Logs all requests/responses
+      authPlugin,           // Adds authentication headers
+      performancePlugin,    // Monitors performance
+      cachePlugin,          // Caches responses
+      errorHandlingPlugin   // Handles errors gracefully
+    ]
+  });
+
+  // You can access plugin methods if needed
+  console.log(`Total requests made: ${loggingPlugin.getRequestCount()}`);
+  
+  // Print performance report
+  performancePlugin.printReport();
+  
+  // Check cache stats
+  console.log('Cache stats:', cachePlugin.getCacheStats());
+
+  return stack;
+}
+
+// Export for use in other files
+export {
+  LoggingPlugin,
+  PerformancePlugin,
+  CachePlugin,
+  authPlugin,
+  errorHandlingPlugin,
+  createStackWithPlugins
+};
diff --git a/src/lib/contentstack.ts b/src/lib/contentstack.ts
@@ -2,7 +2,7 @@ import { httpClient, retryRequestHandler, retryResponseErrorHandler, retryRespon
 import { AxiosRequestHeaders } from 'axios';
 import { handleRequest } from './cache';
 import { Stack as StackClass } from './stack';
-import { Policy, StackConfig } from './types';
+import { Policy, StackConfig, ContentstackPlugin } from './types';
 import * as Utility from './utils';
 export * as Utils from '@contentstack/utils';
 
@@ -114,7 +114,7 @@ export function stack(config: StackConfig): StackClass {
   if (config.plugins) {
     client.interceptors.request.use((reqConfig: any): any => {
       if (config && config.plugins)
-        config.plugins.forEach((pluginInstance) => {
+        config.plugins.forEach((pluginInstance: ContentstackPlugin) => {
           reqConfig = pluginInstance.onRequest(reqConfig);
         });
       
@@ -123,7 +123,7 @@ export function stack(config: StackConfig): StackClass {
 
     client.interceptors.response.use((response: any) => {
       if (config && config.plugins)
-        config.plugins.forEach((pluginInstance) => {
+        config.plugins.forEach((pluginInstance: ContentstackPlugin) => {
           response = pluginInstance.onResponse(response.request, response, response.data);
         });
 
diff --git a/src/lib/types.ts b/src/lib/types.ts
@@ -1,6 +1,7 @@
 /* eslint-disable @cspell/spellchecker */
 import { HttpClientParams } from "@contentstack/core";
 import { PersistanceStoreOptions, StorageType } from "../persistance";
+import { AxiosRequestConfig, AxiosResponse } from "axios";
 
 // Internal Types
 export type params = {
@@ -11,6 +12,53 @@ export type queryParams = {
   [key: string]: string | boolean | number | string[];
 };
 
+/**
+ * Interface for creating Contentstack plugins
+ * 
+ * @example
+ * ```typescript
+ * import { ContentstackPlugin } from '@contentstack/delivery-sdk';
+ * 
+ * class MyPlugin implements ContentstackPlugin {
+ *   onRequest(config: any): any {
+ *     // Modify request configuration
+ *     console.log('Processing request:', config.url);
+ *     return { ...config, headers: { ...config.headers, 'X-Custom-Header': 'value' } };
+ *   }
+ * 
+ *   onResponse(request: any, response: any, data: any): any {
+ *     // Process response data
+ *     console.log('Processing response:', response.status);
+ *     return { ...response, data: { ...data, processed: true } };
+ *   }
+ * }
+ * 
+ * const stack = contentstack.stack({
+ *   apiKey: 'your-api-key',
+ *   deliveryToken: 'your-delivery-token',
+ *   environment: 'your-environment',
+ *   plugins: [new MyPlugin()]
+ * });
+ * ```
+ */
+export interface ContentstackPlugin {
+  /**
+   * Called before each request is sent
+   * @param config - Axios request configuration object (with possible custom properties)
+   * @returns Modified request configuration (can be sync or async)
+   */
+  onRequest(config: any): any;
+
+  /**
+   * Called after each response is received
+   * @param request - The original request configuration
+   * @param response - Axios response object (with possible custom properties)
+   * @param data - Response data
+   * @returns Modified response object (can be sync or async)
+   */
+  onResponse(request: any, response: any, data: any): any;
+}
+
 // External Types
 export enum Region {
   US = "us",
@@ -30,7 +78,7 @@ export interface StackConfig extends HttpClientParams {
   early_access?: string[];
   region?: Region;
   locale?: string;
-  plugins?: any[];
+  plugins?: ContentstackPlugin[];
   logHandler?: (level: string, data: any) => void;
   cacheOptions?: CacheOptions;
   live_preview?: LivePreview;
diff --git a/test/unit/plugin-comprehensive.spec.ts b/test/unit/plugin-comprehensive.spec.ts
diff --git a/test/unit/plugin-interceptor-comprehensive.spec.ts b/test/unit/plugin-interceptor-comprehensive.spec.ts
