@adobe/spacecat-shared-tokowaka-client 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.4.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.4.0...@adobe/spacecat-shared-tokowaka-client-v1.4.1) (2025-12-12)
+
+
+### Bug Fixes
+
+* fastly CDN cache invalidation ([#1240](https://github.com/adobe/spacecat-shared/issues/1240)) ([fbb43e4](https://github.com/adobe/spacecat-shared/commit/fbb43e411053c6dc71255fc3883255785c301659))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.4.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.3.2...@adobe/spacecat-shared-tokowaka-client-v1.4.0) (2025-12-11)
 
 

package/README.md

@@ -28,8 +28,8 @@ Creates a client instance from a context object.
 - `context.log` (Object, optional): Logger instance
 - `context.env.TOKOWAKA_SITE_CONFIG_BUCKET` (string): S3 bucket name for deployed configurations
 - `context.env.TOKOWAKA_PREVIEW_BUCKET` (string): S3 bucket name for preview configurations
-- `context.env.TOKOWAKA_CDN_PROVIDER` (string): CDN provider for cache invalidation
-- `context.env.TOKOWAKA_CDN_CONFIG` (string): JSON configuration for CDN client
+- `context.env.TOKOWAKA_CDN_PROVIDER` (string | string[]): CDN provider(s) for cache invalidation
+- `context.env.TOKOWAKA_CDN_CONFIG` (string): JSON configuration for CDN clients
 - `context.env.TOKOWAKA_EDGE_URL` (string): Tokowaka edge URL for preview HTML fetching
 
 ## Environment Variables
@@ -39,8 +39,23 @@ Creates a client instance from a context object.
 - `TOKOWAKA_PREVIEW_BUCKET` - S3 bucket name for storing preview configurations
 
 **Optional (for CDN invalidation):**
-- `TOKOWAKA_CDN_PROVIDER` - CDN provider name (e.g., "cloudfront")
-- `TOKOWAKA_CDN_CONFIG` - JSON string with CDN-specific configuration. (e.g., { "cloudfront": { "distributionId": <distribution-id>, "region": "us-east-1" }})
+- `TOKOWAKA_CDN_PROVIDER` - CDN provider name(s). Can be a single provider (e.g., "cloudfront") or multiple providers as comma-separated string (e.g., "cloudfront,fastly") or array
+- `TOKOWAKA_CDN_CONFIG` - JSON string with CDN-specific configuration for all providers:
+  ```json
+  {
+    "cloudfront": {
+      "distributionId": "<distribution-id>",
+      "region": "us-east-1"
+    },
+    "fastly": {
+      "serviceId": "<service-id>",
+      "apiToken": "<api-token>",
+      "distributionUrl": "https://<cloudfront-distribution>.cloudfront.net"
+    }
+  }
+  ```
+  
+  **Note for Fastly**: The `distributionUrl` is required and should be the full CloudFront distribution URL (e.g., `https://deftbrsarcsf4.cloudfront.net`). Fastly uses this to construct full URLs as surrogate keys for cache purging.
 
 **Optional (for preview functionality):**
 - `TOKOWAKA_EDGE_URL` - Tokowaka edge URL for fetching HTML content during preview
@@ -55,7 +70,7 @@ Generates configuration and uploads to S3 **per URL**. **Automatically fetches e
 
 **Returns:** `Promise<DeploymentResult>` with:
 - `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
-- `cdnInvalidations` - Array of CDN invalidation results (one per URL)
+- `cdnInvalidations` - Array of CDN invalidation results (one per URL per provider)
 - `succeededSuggestions` - Array of deployed suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
 
@@ -72,7 +87,7 @@ Rolls back previously deployed suggestions by removing their patches from the co
 
 **Returns:** `Promise<RollbackResult>` with:
 - `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
-- `cdnInvalidations` - Array of CDN invalidation results (one per URL)
+- `cdnInvalidations` - Array of CDN invalidation results (one per URL per provider)
 - `succeededSuggestions` - Array of rolled back suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
 - `removedPatchesCount` - Total number of patches removed across all URLs
@@ -84,7 +99,7 @@ Previews suggestions by uploading to preview S3 path and fetching HTML compariso
 **Returns:** `Promise<PreviewResult>` with:
 - `s3Path` - S3 key where preview config was uploaded
 - `config` - Preview configuration object
-- `cdnInvalidation` - CDN invalidation result
+- `cdnInvalidations` - Array of CDN invalidation results (one per provider)
 - `succeededSuggestions` - Array of previewed suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
 - `html` - Object with `url`, `originalHtml`, and `optimizedHtml`
@@ -235,6 +250,91 @@ Per-URL configuration (flat structure):
 - The `tokowakaOptimizations` nested structure has been removed
 - The `tokowakaForceFail` field has been renamed to `forceFail`
 
+## CDN Cache Invalidation
+
+The client supports multiple CDN providers for cache invalidation with **intelligent batching** for optimal performance.
+
+### Batch Optimization
+
+When deploying or rolling back multiple URLs:
+- **Before**: Each URL triggered separate CDN invalidation calls (N URLs = N×2 API calls for 2 providers)
+- **After**: All URLs are collected and invalidated in a single batch call per provider (N URLs = 2 API calls for 2 providers)
+
+**Example Performance Improvement:**
+- 10 URLs with CloudFront + Fastly
+- Old: 20 API calls (10 per provider)
+- New: **2 API calls** (1 per provider)
+- **90% reduction in API calls!**
+
+### Supported CDN Providers
+
+#### CloudFront
+AWS CloudFront CDN invalidation using the AWS SDK.
+
+**Configuration:**
+```json
+{
+  "cloudfront": {
+    "distributionId": "E1234567890ABC",
+    "region": "us-east-1"
+  }
+}
+```
+
+#### Fastly
+Fastly CDN purging using surrogate key purging.
+
+**Configuration:**
+```json
+{
+  "fastly": {
+    "serviceId": "abc123xyz",
+    "apiToken": "your-fastly-api-token"
+  }
+}
+```
+
+### Multiple CDN Providers
+
+To invalidate cache on multiple CDNs simultaneously:
+
+**Environment Variable:**
+```bash
+TOKOWAKA_CDN_PROVIDER="cloudfront,fastly"
+# or as array in code: ["cloudfront", "fastly"]
+
+TOKOWAKA_CDN_CONFIG='{"cloudfront":{"distributionId":"...","region":"us-east-1"},"fastly":{"serviceId":"...","apiToken":"...","distributionUrl":"https://xxx.cloudfront.net"}}'
+```
+
+**Behavior:**
+- All URLs are batched into a single invalidation request per provider
+- All CDN providers are invalidated in parallel using `Promise.all()`
+- Failures in one CDN don't block others
+- Each CDN returns its own result in the `cdnInvalidations` array
+- Results include status, provider name, and provider-specific details
+
+### Fastly Batch Purging
+
+The Fastly client uses surrogate key purging with full CloudFront URLs:
+- **Surrogate Keys**: Constructed as full CloudFront URLs (e.g., `https://xxx.cloudfront.net/opportunities/adobe.com/config`)
+- **Batch Purging**: All paths are sent in a single API call using the `Surrogate-Key` header (space-separated URLs)
+- **Configuration**: Requires `distributionUrl` in the Fastly config to construct full URLs
+- Significantly reduces API calls and improves performance for bulk operations
+
+**Example Fastly Configuration:**
+```json
+{
+  "serviceId": "abc123xyz",
+  "apiToken": "your-fastly-api-token",
+  "distributionUrl": "https://deftbrsarcsf4.cloudfront.net"
+}
+```
+
+This configuration allows Fastly to purge cache entries using URLs like:
+```
+fastly purge --key https://deftbrsarcsf4.cloudfront.net/opportunities/adobe.com/config
+```
+
 ## Reference Material
 
 https://wiki.corp.adobe.com/display/AEMSites/Tokowaka+-+Spacecat+Integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {

package/src/cdn/cdn-client-registry.js

@@ -11,6 +11,7 @@
  */
 
 import CloudFrontCdnClient from './cloudfront-cdn-client.js';
+import FastlyCdnClient from './fastly-cdn-client.js';
 
 /**
  * Registry for CDN clients
@@ -30,6 +31,7 @@ export default class CdnClientRegistry {
    */
   #registerDefaultClients() {
     this.registerClient('cloudfront', CloudFrontCdnClient);
+    this.registerClient('fastly', FastlyCdnClient);
   }
 
   /**

package/src/cdn/fastly-cdn-client.js

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCdnClient from './base-cdn-client.js';
+
+/**
+ * Fastly CDN client implementation
+ * Handles cache invalidation for Fastly CDN using surrogate key purging
+ */
+export default class FastlyCdnClient extends BaseCdnClient {
+  constructor(env, log) {
+    super(env, log);
+    let parsedConfig = {};
+    try {
+      parsedConfig = JSON.parse(env.TOKOWAKA_CDN_CONFIG);
+    } catch (e) {
+      throw new Error('Invalid TOKOWAKA_CDN_CONFIG: must be valid JSON');
+    }
+
+    if (!parsedConfig.fastly) {
+      throw new Error("Missing 'fastly' config in TOKOWAKA_CDN_CONFIG");
+    }
+
+    this.cdnConfig = parsedConfig.fastly;
+    this.providerName = 'fastly';
+  }
+
+  getProviderName() {
+    return this.providerName;
+  }
+
+  validateConfig() {
+    // serviceId, apiToken, and distributionUrl are required for Fastly API
+    if (!this.cdnConfig.serviceId || !this.cdnConfig.apiToken) {
+      this.log.error('Fastly CDN config missing required fields: serviceId and apiToken');
+      return false;
+    }
+
+    if (!this.cdnConfig.distributionUrl) {
+      this.log.error('Fastly CDN config missing distributionUrl (CloudFront distribution URL)');
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Invalidates Fastly CDN cache for given paths using surrogate key purging
+   * Constructs full CloudFront URLs as surrogate keys for Fastly purge
+   * Works efficiently for both single and multiple paths
+   * @param {Array<string>} paths - Array of URL paths to invalidate
+   *   (e.g., '/opportunities/adobe.com/config')
+   * @returns {Promise<Object>} Result of the invalidation request
+   */
+  async invalidateCache(paths) {
+    if (!this.validateConfig()) {
+      throw new Error('Invalid Fastly CDN configuration');
+    }
+
+    if (!Array.isArray(paths) || paths.length === 0) {
+      this.log.warn('No paths provided for cache invalidation');
+      return { status: 'skipped', message: 'No paths to invalidate' };
+    }
+
+    this.log.info(`Starting Fastly cache invalidation for ${paths.length} path(s)`);
+
+    // Construct full CloudFront URLs as surrogate keys
+    // Example: "https://deftbrsarcsf4.cloudfront.net/opportunities/adobe.com/config"
+    const surrogateKeys = paths.map((path) => {
+      // Ensure path starts with /
+      const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+      // Combine CloudFront distribution URL with path
+      const fullUrl = `${this.cdnConfig.distributionUrl}${normalizedPath}`;
+      return fullUrl;
+    });
+
+    this.log.debug(`Generated ${surrogateKeys.length} surrogate key(s) for purge`);
+    this.log.debug(`Surrogate keys: ${surrogateKeys.join(', ')}`);
+
+    const startTime = Date.now();
+    const apiEndpoint = `https://api.fastly.com/service/${this.cdnConfig.serviceId}/purge`;
+    this.log.debug(`Calling Fastly API: POST ${apiEndpoint}`);
+    try {
+      // Fastly batch purge using Surrogate-Key header (space-separated)
+      // Works for both single and multiple keys
+      const response = await fetch(
+        `https://api.fastly.com/service/${this.cdnConfig.serviceId}/purge`,
+        {
+          method: 'POST',
+          headers: {
+            'Fastly-Key': this.cdnConfig.apiToken,
+            'Surrogate-Key': surrogateKeys.join(' '),
+            Accept: 'application/json',
+          },
+        },
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        this.log.error(`Failed to purge Fastly cache: ${response.status} - ${errorText}`);
+        return {
+          status: 'failed',
+          provider: 'fastly',
+          serviceId: this.cdnConfig.serviceId,
+          totalPaths: paths.length,
+          totalKeys: surrogateKeys.length,
+          successCount: 0,
+          failedCount: surrogateKeys.length,
+          error: errorText,
+          duration: Date.now() - startTime,
+        };
+      }
+
+      const result = await response.json();
+      const duration = Date.now() - startTime;
+      this.log.info(
+        `Successfully purged ${surrogateKeys.length} Fastly cache key(s) `
+        + `for service ${this.cdnConfig.serviceId} (took ${duration}ms)`,
+      );
+
+      return {
+        status: 'success',
+        provider: 'fastly',
+        serviceId: this.cdnConfig.serviceId,
+        totalPaths: paths.length,
+        totalKeys: surrogateKeys.length,
+        successCount: surrogateKeys.length,
+        failedCount: 0,
+        purgeId: result.id,
+        duration,
+      };
+    } catch (error) {
+      this.log.error(`Error purging Fastly cache: ${error.message}`, error);
+      return {
+        status: 'error',
+        provider: 'fastly',
+        serviceId: this.cdnConfig.serviceId,
+        totalPaths: paths.length,
+        totalKeys: surrogateKeys.length,
+        successCount: 0,
+        failedCount: surrogateKeys.length,
+        error: error.message,
+        duration: Date.now() - startTime,
+      };
+    }
+  }
+}

package/src/index.d.ts

@@ -49,23 +49,39 @@ export interface TokowakaConfig {
 
 export interface CdnInvalidationResult {
   status: string;
-  provider?: string;
+  provider: string;
   purgeId?: string;
+  invalidationId?: string;
+  invalidationStatus?: string;
+  createTime?: string;
   estimatedSeconds?: number;
   paths?: number;
+  totalPaths?: number;
+  totalKeys?: number;
+  successCount?: number;
+  failedCount?: number;
+  serviceId?: string;
+  duration?: number;
+  results?: Array<{
+    key: string;
+    status: string;
+    statusCode?: number;
+    error?: string;
+  }>;
   message?: string;
+  error?: string;
 }
 
 export interface DeploymentResult {
   s3Paths: string[];
-  cdnInvalidations: (CdnInvalidationResult | null)[];
+  cdnInvalidations: CdnInvalidationResult[];
   succeededSuggestions: Array<any>;
   failedSuggestions: Array<{ suggestion: any; reason: string }>;
 }
 
 export interface RollbackResult {
   s3Paths: string[];
-  cdnInvalidations: (CdnInvalidationResult | null)[];
+  cdnInvalidations: CdnInvalidationResult[];
   succeededSuggestions: Array<any>;
   failedSuggestions: Array<{ suggestion: any; reason: string }>;
   removedPatchesCount: number;
@@ -74,7 +90,7 @@ export interface RollbackResult {
 export interface PreviewResult {
   s3Path: string;
   config: TokowakaConfig;
-  cdnInvalidation: CdnInvalidationResult | null;
+  cdnInvalidations: CdnInvalidationResult[];
   succeededSuggestions: Array<any>;
   failedSuggestions: Array<{ suggestion: any; reason: string }>;
   html: {
@@ -300,14 +316,27 @@ export class CloudFrontCdnClient extends BaseCdnClient {
   invalidateCache(paths: string[]): Promise<CdnInvalidationResult>;
 }
 
+/**
+ * Fastly CDN client implementation
+ */
+export class FastlyCdnClient extends BaseCdnClient {
+  constructor(env: {
+    TOKOWAKA_CDN_CONFIG: string; // JSON string with fastly config
+  }, log: any);
+  
+  getProviderName(): string;
+  validateConfig(): boolean;
+  invalidateCache(paths: string[]): Promise<CdnInvalidationResult>;
+}
+
 /**
  * Registry for CDN clients
  */
 export class CdnClientRegistry {
-  constructor(log: any);
+  constructor(env: Record<string, any>, log: any);
   
   registerClient(provider: string, ClientClass: typeof BaseCdnClient): void;
-  getClient(provider: string, config: Record<string, any>): BaseCdnClient | null;
+  getClient(provider: string): BaseCdnClient | null;
   getSupportedProviders(): string[];
   isProviderSupported(provider: string): boolean;
 }
@@ -327,8 +356,8 @@ export default class TokowakaClient {
     env: {
       TOKOWAKA_SITE_CONFIG_BUCKET: string;
       TOKOWAKA_PREVIEW_BUCKET?: string;
-      TOKOWAKA_CDN_PROVIDER?: string;
-      TOKOWAKA_CDN_CONFIG?: string;
+      TOKOWAKA_CDN_PROVIDER?: string | string[]; // Single provider or comma-separated list
+      TOKOWAKA_CDN_CONFIG?: string; // JSON with cloudfront and/or fastly config
       TOKOWAKA_EDGE_URL?: string;
     };
     log?: any;
@@ -358,12 +387,12 @@ export default class TokowakaClient {
   /**
    * Fetches domain-level metaconfig from S3
    */
-  fetchMetaconfig(url: string, isPreview?: boolean): Promise<TokowakaMetaconfig | null>;
+  fetchMetaconfig(url: string): Promise<TokowakaMetaconfig | null>;
   
   /**
    * Uploads domain-level metaconfig to S3
    */
-  uploadMetaconfig(url: string, metaconfig: TokowakaMetaconfig, isPreview?: boolean): Promise<string>;
+  uploadMetaconfig(url: string, metaconfig: TokowakaMetaconfig): Promise<string>;
   
   /**
    * Merges existing configuration with new configuration
@@ -372,8 +401,15 @@ export default class TokowakaClient {
   
   /**
    * Invalidates CDN cache for a specific URL
+   * Supports multiple CDN providers in parallel
+   */
+  invalidateCdnCache(url: string, providers?: string | string[], isPreview?: boolean): Promise<CdnInvalidationResult[]>;
+
+  /**
+   * Batch invalidates CDN cache for multiple URLs at once
+   * More efficient than individual invalidations when processing multiple URLs
    */
-  invalidateCdnCache(url: string, provider?: string, isPreview?: boolean): Promise<CdnInvalidationResult | null>;
+  batchInvalidateCdnCache(urls: string[], providers?: string | string[], isPreview?: boolean): Promise<CdnInvalidationResult[]>;
 
   /**
    * Deploys suggestions to Tokowaka edge