@adobe/spacecat-shared-tokowaka-client 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.2.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.1.0...@adobe/spacecat-shared-tokowaka-client-v1.2.0) (2025-11-27)
+
+
+### Features
+
+* url path-wise edge deployment  ([#1178](https://github.com/adobe/spacecat-shared/issues/1178)) ([37b0d1a](https://github.com/adobe/spacecat-shared/commit/37b0d1a388f842a62cb95eb5272feb49d1dfb3e8))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.1.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.0.6...@adobe/spacecat-shared-tokowaka-client-v1.1.0) (2025-11-25)
 
 

package/README.md

@@ -26,34 +26,44 @@ Creates a client instance from a context object.
 **Required context properties:**
 - `context.s3.s3Client` (S3Client): AWS S3 client instance
 - `context.log` (Object, optional): Logger instance
-- `context.env.TOKOWAKA_SITE_CONFIG_BUCKET` (string): S3 bucket name for configurations
+- `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_EDGE_URL` (string): Tokowaka edge URL for preview HTML fetching
 
 ## Environment Variables
 
 **Required:**
-- `TOKOWAKA_SITE_CONFIG_BUCKET` - S3 bucket name for storing configurations
+- `TOKOWAKA_SITE_CONFIG_BUCKET` - S3 bucket name for storing deployed configurations
+- `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" }})
 
+**Optional (for preview functionality):**
+- `TOKOWAKA_EDGE_URL` - Tokowaka edge URL for fetching HTML content during preview
+
 ### Main Methods
 
 #### `deploySuggestions(site, opportunity, suggestions)`
 
-Generates configuration and uploads to S3. **Automatically fetches existing configuration and merges** new suggestions with it. Invalidates CDN cache after upload.
+Generates configuration and uploads to S3 **per URL**. **Automatically fetches existing configuration for each URL and merges** new suggestions with it. Invalidates CDN cache after upload.
+
+**Architecture Change:** Creates one S3 file per URL instead of a single file with all URLs. This prevents files from growing too large over time.
 
 **Returns:** `Promise<DeploymentResult>` with:
-- `s3Path` - S3 key where config was uploaded
-- `cdnInvalidation` - CDN invalidation result (or error)
+- `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
+- `cdnInvalidations` - Array of CDN invalidation results (one per URL)
 - `succeededSuggestions` - Array of deployed suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
 
 #### `rollbackSuggestions(site, opportunity, suggestions)`
 
-Rolls back previously deployed suggestions by removing their patches from the configuration. **Automatically fetches existing configuration** and removes patches matching the provided suggestions. Invalidates CDN cache after upload.
+Rolls back previously deployed suggestions by removing their patches from the configuration. **Automatically fetches existing configuration for each URL** and removes patches matching the provided suggestions. Invalidates CDN cache after upload.
+
+**Architecture Change:** Updates one S3 file per URL instead of a single file with all URLs.
 
 **Mapper-Specific Rollback Behavior:**
 - Each opportunity mapper handles its own rollback logic via `rollbackPatches()` method
@@ -61,15 +71,31 @@ Rolls back previously deployed suggestions by removing their patches from the co
 - **Headings/Summarization:** Simple removal by suggestion ID (default behavior)
 
 **Returns:** `Promise<RollbackResult>` with:
-- `s3Path` - S3 key where config was uploaded
-- `cdnInvalidation` - CDN invalidation result (or error)
+- `s3Paths` - Array of S3 keys where configs were uploaded (one per URL)
+- `cdnInvalidations` - Array of CDN invalidation results (one per URL)
 - `succeededSuggestions` - Array of rolled back suggestions
 - `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
-- `removedPatchesCount` - Number of patches removed from the configuration
+- `removedPatchesCount` - Total number of patches removed across all URLs
+
+#### `previewSuggestions(site, opportunity, suggestions, options)`
+
+Previews suggestions by uploading to preview S3 path and fetching HTML comparison. **All suggestions must belong to the same URL.**
+
+**Returns:** `Promise<PreviewResult>` with:
+- `s3Path` - S3 key where preview config was uploaded
+- `config` - Preview configuration object
+- `cdnInvalidation` - CDN invalidation result
+- `succeededSuggestions` - Array of previewed suggestions
+- `failedSuggestions` - Array of `{suggestion, reason}` objects for ineligible suggestions
+- `html` - Object with `url`, `originalHtml`, and `optimizedHtml`
 
-#### `fetchConfig(apiKey)`
+#### `fetchConfig(url, isPreview)`
 
-Fetches existing Tokowaka configuration from S3.
+Fetches existing Tokowaka configuration from S3 for a specific URL.
+
+**Parameters:**
+- `url` - Full URL (e.g., 'https://www.example.com/products/item')
+- `isPreview` - Whether to fetch from preview path (default: false)
 
 **Returns:** `Promise<TokowakaConfig | null>` - Configuration object or null if not found
 
@@ -79,36 +105,135 @@ Merges existing configuration with new configuration. For each URL path, checks
 
 **Returns:** `TokowakaConfig` - Merged configuration
 
-#### `generateConfig(site, opportunity, suggestions)`
+#### `generateConfig(url, opportunity, suggestions)`
+
+Generates Tokowaka configuration from opportunity suggestions for a specific URL without uploading.
+
+**Parameters:**
+- `url` - Full URL for which to generate config
+- `opportunity` - Opportunity entity
+- `suggestions` - Array of suggestion entities
+
+#### `uploadConfig(url, config, isPreview)`
 
-Generates Tokowaka configuration from opportunity suggestions without uploading.
+Uploads configuration to S3 for a specific URL.
 
-#### `uploadConfig(apiKey, config)`
+**Parameters:**
+- `url` - Full URL (e.g., 'https://www.example.com/products/item')
+- `config` - Tokowaka configuration object
+- `isPreview` - Whether to upload to preview path (default: false)
 
-Uploads configuration to S3. Returns S3 key of uploaded configuration.
+**Returns:** `Promise<string>` - S3 key of uploaded configuration
 
 ## CDN Cache Invalidation
 
 The client invalidates CDN cache after uploading configurations. Failures are logged but don't block deployment.
 
+## Site Configuration
+
+Sites must have the following configuration in their `tokowakaConfig`:
+
+```javascript
+{
+  "tokowakaConfig": {
+    "apiKey": "legacy-key-kept-for-backward-compatibility", // Optional, kept for backward compatibility
+    "forwardedHost": "www.example.com"  // Required for preview functionality
+  }
+}
+```
+
+**Note:** 
+- `apiKey` is optional and **not used** for S3 paths or HTTP headers (kept in schema for potential future use)
+- `forwardedHost` is **required** for preview functionality to fetch HTML from Tokowaka edge
+
 ## Supported Opportunity Types
 
 ### Headings
 
 **Deployment Eligibility:** Only suggestions with `checkType: 'heading-empty'`, `checkType: 'heading-missing-h1'` and `checkType: 'heading-h1-length'` can be deployed currently.
 
+### FAQ
+
+**Deployment Eligibility:** Suggestions must have `shouldOptimize: true` flag and valid FAQ item structure.
+
+**Special Behavior:** Automatically manages heading patch - adds heading when first FAQ is deployed, removes heading when last FAQ is rolled back.
+
 ### Content Summarization
 
-**Deployment Eligibility:**  Currently all suggestions for `summarization` opportunity can be deployed.
+**Deployment Eligibility:** Currently all suggestions for `summarization` opportunity can be deployed.
 
 ## S3 Storage
 
-Configurations are stored at:
+Configurations are now stored **per URL** with domain-level metadata:
+
+### Structure
 ```
-s3://{TOKOWAKA_SITE_CONFIG_BUCKET}/opportunities/{tokowakaApiKey}
+s3://{TOKOWAKA_SITE_CONFIG_BUCKET}/opportunities/{normalized-domain}/
+├── config (domain-level metaconfig: siteId, prerender)
+├── {base64-encoded-path-1} (URL-specific patches)
+├── {base64-encoded-path-2} (URL-specific patches)
+└── ...
+```
+
+For preview configurations:
+```
+s3://{TOKOWAKA_PREVIEW_BUCKET}/preview/opportunities/{normalized-domain}/
+├── config
+├── {base64-encoded-path-1}
+└── ...
+```
+
+**Architecture Change:** Each URL has its own configuration file instead of one file per site. Domain-level metaconfig is stored separately to avoid duplication.
+
+**URL Normalization:**
+- Domain: Strips `www.` prefix (e.g., `www.example.com` → `example.com`)
+- Path: Removes trailing slash (except for root `/`), ensures starts with `/`, then base64 URL encodes
+
+**Example:**
+- URL: `https://www.example.com/products/item`
+- Metaconfig Path: `opportunities/example.com/config`
+- Patch Config Path: `opportunities/example.com/L3Byb2R1Y3RzL2l0ZW0`
+- Where `L3Byb2R1Y3RzL2l0ZW0` is base64 URL encoding of `/products/item`
+
+### Metaconfig File Structure
+Domain-level metaconfig (created once per domain, shared by all URLs):
+```json
+{
+  "siteId": "abc-123",
+  "prerender": true
+}
+```
+
+### Configuration File Structure
+Per-URL configuration (flat structure):
+```json
+{
+  "url": "https://example.com/products/item",
+  "version": "1.0",
+  "forceFail": false,
+  "prerender": true,
+  "patches": [
+    {
+      "opportunityId": "abc-123",
+      "suggestionId": "xyz-789",
+      "prerenderRequired": true,
+      "lastUpdated": 1234567890,
+      "op": "insertAfter",
+      "selector": "main",
+      "value": { ... },
+      "valueFormat": "hast",
+      "target": "ai-bots"
+    }
+  ]
+}
 ```
 
-**Note:** The configuration is stored as a JSON file containing the complete Tokowaka optimization config for the site.
+**Note:** 
+- `siteId` is stored only in domain-level `config` (metaconfig)
+- `prerender` is stored in both metaconfig (domain-level) and patch files (URL-level)
+- The `baseURL` field has been renamed to `url`
+- The `tokowakaOptimizations` nested structure has been removed
+- The `tokowakaForceFail` field has been renamed to `forceFail`
 
 ## Reference Material
 

package/package.json

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

package/src/index.d.ts

@@ -32,17 +32,17 @@ export const TARGET_USER_AGENTS_CATEGORIES: {
   ALL: 'all';
 };
 
-export interface TokowakaUrlOptimization {
+export interface TokowakaMetaconfig {
+  siteId: string;
   prerender: boolean;
-  patches: TokawakaPatch[];
 }
 
 export interface TokowakaConfig {
-  siteId: string;
-  baseURL: string;
+  url: string;
   version: string;
-  tokowakaForceFail: boolean;
-  tokowakaOptimizations: Record<string, TokowakaUrlOptimization>;
+  forceFail: boolean;
+  prerender: boolean;
+  patches: TokawakaPatch[];
 }
 
 export interface CdnInvalidationResult {
@@ -55,16 +55,37 @@ export interface CdnInvalidationResult {
 }
 
 export interface DeploymentResult {
+  s3Paths: string[];
+  cdnInvalidations: (CdnInvalidationResult | null)[];
+  succeededSuggestions: Array<any>;
+  failedSuggestions: Array<{ suggestion: any; reason: string }>;
+}
+
+export interface RollbackResult {
+  s3Paths: string[];
+  cdnInvalidations: (CdnInvalidationResult | null)[];
+  succeededSuggestions: Array<any>;
+  failedSuggestions: Array<{ suggestion: any; reason: string }>;
+  removedPatchesCount: number;
+}
+
+export interface PreviewResult {
   s3Path: string;
+  config: TokowakaConfig;
   cdnInvalidation: CdnInvalidationResult | null;
   succeededSuggestions: Array<any>;
   failedSuggestions: Array<{ suggestion: any; reason: string }>;
+  html: {
+    url: string;
+    originalHtml: string;
+    optimizedHtml: string;
+  };
 }
 
 export interface SiteConfig {
   getTokowakaConfig(): {
-    apiKey: string;
-    cdnProvider?: string;
+    apiKey?: string;
+    forwardedHost?: string;
   };
   getFetchConfig?(): {
     overrideBaseURL?: string;
@@ -261,6 +282,7 @@ export class CdnClientRegistry {
 export default class TokowakaClient {
   constructor(config: {
     bucketName: string;
+    previewBucketName?: string;
     s3Client: S3Client;
     env?: Record<string, any>;
   }, log: any);
@@ -268,26 +290,44 @@ export default class TokowakaClient {
   static createFrom(context: {
     env: {
       TOKOWAKA_SITE_CONFIG_BUCKET: string;
+      TOKOWAKA_PREVIEW_BUCKET?: string;
       TOKOWAKA_CDN_PROVIDER?: string;
       TOKOWAKA_CDN_CONFIG?: string;
+      TOKOWAKA_EDGE_URL?: string;
     };
     log?: any;
     s3: { s3Client: S3Client };
     tokowakaClient?: TokowakaClient;
   }): TokowakaClient;
 
+  /**
+   * Generates Tokowaka configuration from suggestions for a specific URL
+   */
   generateConfig(
-    site: Site,
+    url: string,
     opportunity: Opportunity,
     suggestions: Suggestion[]
-  ): TokowakaConfig;
+  ): TokowakaConfig | null;
 
-  uploadConfig(apiKey: string, config: TokowakaConfig): Promise<string>;
+  /**
+   * Uploads configuration to S3 for a specific URL
+   */
+  uploadConfig(url: string, config: TokowakaConfig, isPreview?: boolean): Promise<string>;
   
   /**
-   * Fetches existing Tokowaka configuration from S3
+   * Fetches existing Tokowaka configuration from S3 for a specific URL
    */
-  fetchConfig(apiKey: string): Promise<TokowakaConfig | null>;
+  fetchConfig(url: string, isPreview?: boolean): Promise<TokowakaConfig | null>;
+  
+  /**
+   * Fetches domain-level metaconfig from S3
+   */
+  fetchMetaconfig(url: string, isPreview?: boolean): Promise<TokowakaMetaconfig | null>;
+  
+  /**
+   * Uploads domain-level metaconfig to S3
+   */
+  uploadMetaconfig(url: string, metaconfig: TokowakaMetaconfig, isPreview?: boolean): Promise<string>;
   
   /**
    * Merges existing configuration with new configuration
@@ -295,16 +335,42 @@ export default class TokowakaClient {
   mergeConfigs(existingConfig: TokowakaConfig, newConfig: TokowakaConfig): TokowakaConfig;
   
   /**
-   * Invalidates CDN cache
+   * Invalidates CDN cache for a specific URL
    */
-  invalidateCdnCache(apiKey: string, cdnProvider?: string): Promise<CdnInvalidationResult | null>;
+  invalidateCdnCache(url: string, provider?: string, isPreview?: boolean): Promise<CdnInvalidationResult | null>;
 
+  /**
+   * Deploys suggestions to Tokowaka edge
+   */
   deploySuggestions(
     site: Site,
     opportunity: Opportunity,
     suggestions: Suggestion[]
   ): Promise<DeploymentResult>;
   
+  /**
+   * Rolls back deployed suggestions
+   */
+  rollbackSuggestions(
+    site: Site,
+    opportunity: Opportunity,
+    suggestions: Suggestion[]
+  ): Promise<RollbackResult>;
+  
+  /**
+   * Previews suggestions (all must belong to same URL)
+   */
+  previewSuggestions(
+    site: Site,
+    opportunity: Opportunity,
+    suggestions: Suggestion[],
+    options?: {
+      warmupDelayMs?: number;
+      maxRetries?: number;
+      retryDelayMs?: number;
+    }
+  ): Promise<PreviewResult>;
+  
   /**
    * Registers a custom mapper for an opportunity type
    */