@adobe/spacecat-shared-tokowaka-client 1.5.4 → 1.5.5

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-tokowaka-client-v1.5.5](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.4...@adobe/spacecat-shared-tokowaka-client-v1.5.5) (2026-01-21)
+
+
+### Bug Fixes
+
+* remove details from tokowaka readme ([#1277](https://github.com/adobe/spacecat-shared/issues/1277)) ([14f3aa8](https://github.com/adobe/spacecat-shared/commit/14f3aa82cfbde56c6baebd1ad979980cbe24dd12))
+
 # [@adobe/spacecat-shared-tokowaka-client-v1.5.4](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.5.3...@adobe/spacecat-shared-tokowaka-client-v1.5.4) (2026-01-21)
 
 

package/README.md

@@ -17,148 +17,6 @@ const tokowakaClient = TokowakaClient.createFrom(context);
 const result = await tokowakaClient.deploySuggestions(site, opportunity, suggestions);
 ```
 
-## API Reference
-
-### TokowakaClient.createFrom(context)
-
-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 deployed configurations
-- `context.env.TOKOWAKA_PREVIEW_BUCKET` (string): S3 bucket name for preview configurations
-- `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
-
-**Required:**
-- `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(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
-
-### Main Methods
-
-#### `deploySuggestions(site, opportunity, suggestions)`
-
-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. **Updates the metaconfig's `patches` field** to track deployed endpoints.
-
-**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.
-
-**Metaconfig Tracking:** After successful deployment, the method updates the domain-level metaconfig's `patches` object with the normalized paths of all deployed endpoints (e.g., `{ "/products/item": true }`). This provides a centralized registry of all deployed endpoints for the domain.
-
-**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 per provider)
-- `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 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
-- **FAQ:** Automatically removes the "FAQs" heading patch if no FAQ suggestions remain for that URL
-- **Headings/Summarization:** Simple removal by suggestion ID (default behavior)
-
-**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 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
-
-#### `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
-- `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`
-
-#### `fetchConfig(url, isPreview)`
-
-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
-
-#### `mergeConfigs(existingConfig, newConfig)`
-
-Merges existing configuration with new configuration. For each URL path, checks if `opportunityId` + `suggestionId` combination exists and either updates or adds patches accordingly.
-
-**Returns:** `TokowakaConfig` - Merged configuration
-
-#### `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)`
-
-Uploads configuration to S3 for a specific URL.
-
-**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)
-
-**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 `tokowakaConfig` field in their site-config to confirm that tokowaka is enabled for that particular site.
-
-```javascript
-{
-  ...
-  "tokowakaConfig": {
-    "enabled": true
-  }
-}
-```
-
 ## Supported Opportunity Types
 
 ### Headings
@@ -174,177 +32,3 @@ Sites must have the `tokowakaConfig` field in their site-config to confirm that
 ### Content Summarization
 
 **Deployment Eligibility:** Currently all suggestions for `summarization` opportunity can be deployed.
-
-## S3 Storage
-
-Configurations are now stored **per URL** with domain-level metadata:
-
-### Structure
-```
-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",
-  "apiKeys": ["tokowaka-api-key-1"],
-  "tokowakaEnabled": true,
-  "enhancements": true,
-  "prerender": {
-    "allowList": [],
-    "denyList": ["/*"]
-  },
-  "patches": {
-    "/products/item": true,
-    "/about": true,
-    "/contact": 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:** 
-- `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`
-
-## 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 sequentially
-- 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
-https://wiki.corp.adobe.com/display/AEMSites/Tokowaka+Patch+Format

package/package.json

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