@adobe/spacecat-shared-tokowaka-client 1.19.0 → 1.20.0

package/src/index.d.ts

@@ -155,6 +155,268 @@ export class FastlyKVClient {
  */
 export function calculateForwardedHost(url: string, logger?: { debug?: (msg: string) => void; error?: (msg: string) => void }): string;
 
+/**
+ * Temporary AWS credentials returned by {@link assumeConnectorRole}.
+ */
+export interface AWSCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+  expiration?: Date;
+}
+
+/**
+ * One row of the Edge Optimize deploy/plan step contract.
+ */
+export interface DeployStep {
+  key: string;
+  label: string;
+  status?: string;
+  action?: string;
+  detail?: string;
+  probe?: Record<string, any>;
+}
+
+// ── CloudFront "Optimize at Edge" control-plane (free functions) ──────────────
+
+/**
+ * Assume the customer's cross-account connector role and return short-lived credentials.
+ */
+export function assumeConnectorRole(params: {
+  accountId: string;
+  externalId: string;
+  roleName?: string;
+  region?: string;
+}): Promise<{ roleArn: string; accountId: string; credentials: AWSCredentials }>;
+
+/**
+ * List the CloudFront distributions in the customer account using assumed-role credentials.
+ */
+export function listDistributions(
+  credentials: AWSCredentials,
+  region?: string,
+): Promise<Array<{
+  id: string;
+  domainName: string;
+  aliases: string[];
+  status: string;
+  enabled: boolean;
+  comment: string;
+}>>;
+
+/**
+ * Fetch a single CloudFront distribution's configuration using assumed-role credentials.
+ */
+export function getDistributionConfig(
+  credentials: AWSCredentials,
+  distributionId: string,
+  region?: string,
+): Promise<{
+  origins: Array<{ id: string; domainName: string; originPath: string }>;
+  defaultCacheBehavior: { pathPattern: string; targetOriginId: string } | null;
+  cacheBehaviors: Array<{ pathPattern: string; targetOriginId: string }>;
+}>;
+
+/**
+ * Add the Edge Optimize origin to a CloudFront distribution (idempotent + self-healing).
+ */
+export function createOrigin(
+  credentials: AWSCredentials,
+  distributionId: string,
+  originDomain?: string,
+  headers?: { apiKey?: string; forwardedHost?: string; fetcherKey?: string },
+  region?: string,
+): Promise<{ created: boolean; alreadyExisted: boolean; updated: boolean; originId: string }>;
+
+/**
+ * Create or update the routing CloudFront Function and publish it to LIVE (idempotent).
+ */
+export function createCloudFrontFunction(
+  credentials: AWSCredentials,
+  defaultOriginId: string,
+  distributionId: string,
+  targetedPaths?: string[] | null,
+  region?: string,
+): Promise<{ name: string; created: boolean; stage: string }>;
+
+/**
+ * Add the Edge Optimize routing headers to the cache key for the target behavior.
+ */
+export function updateCacheSettings(
+  credentials: AWSCredentials,
+  distributionId: string,
+  pathPattern: string,
+  opts?: { setMinTTLZero?: boolean; region?: string },
+): Promise<{
+  scenario: string;
+  policyId: string | null;
+  updated: boolean;
+  alreadyForwarded: boolean;
+  reused?: boolean;
+}>;
+
+/**
+ * Create (or update) the Edge Optimize Lambda@Edge function and publish a version (idempotent).
+ */
+export function createLambdaAtEdge(
+  credentials: AWSCredentials,
+  accountId: string,
+  opts?: {
+    region?: string;
+    distributionId?: string;
+    originDomain?: string;
+    retryDelayMs?: number;
+  },
+): Promise<{
+  status: string;
+  functionArn?: string;
+  versionArn: string | null;
+  version?: string;
+  roleArn: string;
+  created: boolean;
+  alreadyExisted?: boolean;
+}>;
+
+/**
+ * Read-only status of the Edge Optimize Lambda@Edge function and its execution role.
+ */
+export function getLambdaAtEdgeStatus(
+  credentials: AWSCredentials,
+  distributionId: string,
+  region?: string,
+): Promise<{
+  exists: boolean;
+  roleExists: boolean;
+  roleOk: boolean;
+  state?: string;
+  lastUpdateStatus?: string;
+  functionArn?: string;
+  versionArn: string | null;
+  version?: string;
+  ready: boolean;
+}>;
+
+/**
+ * Wire the routing CloudFront Function and the Lambda@Edge function onto a cache behavior.
+ */
+export function applyAssociations(
+  credentials: AWSCredentials,
+  distributionId: string,
+  pathPattern: string,
+  lambdaVersionArn: string,
+  region?: string,
+): Promise<{ cloudFrontFunctionArn: string; lambdaArn: string }>;
+
+/**
+ * Verify Edge Optimize routing end-to-end by probing as a bot and as a human.
+ */
+export function verifyRouting(url: string): Promise<{
+  passed: boolean;
+  requestId: string | null;
+  details: { bot: Record<string, any>; human: Record<string, any> };
+}>;
+
+/**
+ * Run one poll of the idempotent Edge Optimize "Deploy routing" orchestrator.
+ */
+export function runDeployStep(
+  credentials: AWSCredentials,
+  params: {
+    distributionId: string;
+    originId: string;
+    behavior: string;
+    originDomain?: string;
+    originHeaders?: { apiKey?: string; forwardedHost?: string; fetcherKey?: string };
+    accountId: string;
+  },
+  region?: string,
+): Promise<{ routingDeployed: boolean; verified: boolean; steps: DeployStep[] }>;
+
+/**
+ * Read-only "preview" of what {@link runDeployStep} would do, without mutating.
+ */
+export function planDeploy(
+  credentials: AWSCredentials,
+  params: {
+    distributionId: string;
+    originId?: string;
+    behavior: string;
+    originDomain?: string;
+    originHeaders?: { apiKey?: string; forwardedHost?: string; fetcherKey?: string };
+    accountId?: string;
+  },
+  region?: string,
+): Promise<{ canProceed: boolean; blocker: string | null; steps: DeployStep[] }>;
+
+export interface CloudFrontEdgeClientOptions {
+  credentials: AWSCredentials;
+  region?: string;
+}
+
+/**
+ * CloudFront control-plane client initialized with short-lived AWS credentials.
+ */
+export class CloudFrontEdgeClient {
+  constructor(options: CloudFrontEdgeClientOptions);
+
+  listDistributions(): ReturnType<typeof listDistributions>;
+
+  getDistributionConfig(distributionId: string): ReturnType<typeof getDistributionConfig>;
+
+  createOrigin(
+    distributionId: string,
+    originDomain?: string,
+    headers?: { apiKey?: string; forwardedHost?: string; fetcherKey?: string },
+  ): ReturnType<typeof createOrigin>;
+
+  createCloudFrontFunction(
+    defaultOriginId: string,
+    distributionId: string,
+    targetedPaths?: string[] | null,
+  ): ReturnType<typeof createCloudFrontFunction>;
+
+  updateCacheSettings(
+    distributionId: string,
+    pathPattern: string,
+    opts?: { setMinTTLZero?: boolean; region?: string },
+  ): ReturnType<typeof updateCacheSettings>;
+
+  createLambdaAtEdge(
+    accountId: string,
+    opts?: {
+      region?: string;
+      distributionId?: string;
+      originDomain?: string;
+      retryDelayMs?: number;
+    },
+  ): ReturnType<typeof createLambdaAtEdge>;
+
+  getLambdaAtEdgeStatus(distributionId: string): ReturnType<typeof getLambdaAtEdgeStatus>;
+
+  applyAssociations(
+    distributionId: string,
+    pathPattern: string,
+    lambdaVersionArn: string,
+  ): ReturnType<typeof applyAssociations>;
+
+  runDeployStep(params: Parameters<typeof runDeployStep>[1]): ReturnType<typeof runDeployStep>;
+
+  planDeploy(params: Parameters<typeof planDeploy>[1]): ReturnType<typeof planDeploy>;
+}
+
+/**
+ * Build the CloudFront Function (viewer-request) routing code.
+ */
+export function buildCloudfrontFunctionCode(
+  defaultOriginId: string,
+  targetedPaths?: string[] | null,
+): string;
+
+/**
+ * Build an in-memory zip containing a single file (used to package the Lambda@Edge code).
+ */
+export function buildLambdaZip(filename: string, content: string | Buffer): Buffer;
+
 /**
  * Base class for opportunity mappers
  * Extend this class to create custom mappers for new opportunity types
@@ -481,4 +743,3 @@ export default class TokowakaClient {
    */
   getSupportedOpportunityTypes(): string[];
 }
-

package/src/index.js

@@ -51,6 +51,25 @@ import {
 export { FastlyKVClient } from './fastly-kv-client.js';
 export { calculateForwardedHost } from './utils/custom-html-utils.js';
 
+// CloudFront control-plane (free functions + constants).
+export {
+  assumeConnectorRole,
+  listDistributions,
+  getDistributionConfig,
+  createOrigin,
+  createCloudFrontFunction,
+  updateCacheSettings,
+  createLambdaAtEdge,
+  getLambdaAtEdgeStatus,
+  applyAssociations,
+  verifyRouting,
+  runDeployStep,
+  planDeploy,
+  CloudFrontEdgeClient,
+  buildCloudfrontFunctionCode,
+  buildLambdaZip,
+} from './cdn/cloudfront/index.js';
+
 const HTTP_BAD_REQUEST = 400;
 const HTTP_INTERNAL_SERVER_ERROR = 500;
 const HTTP_NOT_IMPLEMENTED = 501;
@@ -712,7 +731,8 @@ class TokowakaClient {
    * @param {Array} suggestions - Array of suggestion entities to deploy
    * @returns {Promise<Object>} - Deployment result with succeeded/failed suggestions
    */
-  async deploySuggestions(site, opportunity, suggestions) {
+  async deploySuggestions(site, opportunity, suggestions, metadata = {}) {
+    const { applyStale = false } = metadata;
     const opportunityType = opportunity.getType();
     const baseURL = getEffectiveBaseURL(site);
     const mapper = this.mapperRegistry.getMapper(opportunityType);
@@ -788,6 +808,10 @@ class TokowakaClient {
         continue;
       }
 
+      if (applyStale && newConfig.patches?.length > 0) {
+        newConfig.patches = newConfig.patches.map((patch) => ({ ...patch, applyStale: true }));
+      }
+
       // Merge with existing config for this URL
       const config = this.mergeConfigs(existingConfig, newConfig);
 
@@ -828,8 +852,15 @@ class TokowakaClient {
    * @returns {Promise<number>} Number of patches removed
    * @private
    */
-  // eslint-disable-next-line max-len
-  async #rollbackPerUrlConfig(fullUrl, urlSuggestions, opportunity, mapper, opportunityType, s3Paths, rolledBackUrls) {
+  async #rollbackPerUrlConfig(
+    fullUrl,
+    urlSuggestions,
+    opportunity,
+    mapper,
+    opportunityType,
+    s3Paths,
+    rolledBackUrls,
+  ) {
     const existingConfig = await this.fetchConfig(fullUrl);
     if (!existingConfig) {
       this.log.warn(`No existing configuration found for URL: ${fullUrl}`);
@@ -1427,9 +1458,11 @@ class TokowakaClient {
    * @returns {Promise<{ succeededSuggestions: Array, failedSuggestions: Array }>}
    * @private
    */
-  async #deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy) {
+  // eslint-disable-next-line max-len
+  async #deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy, metadata = {}) {
     try {
-      const result = await this.deploySuggestions(site, opportunity, validSuggestions);
+      // eslint-disable-next-line max-len
+      const result = await this.deploySuggestions(site, opportunity, validSuggestions, metadata);
       const deploymentTimestamp = Date.now();
 
       const succeeded = result.succeededSuggestions.map((s) => {
@@ -1590,6 +1623,7 @@ class TokowakaClient {
     targetSuggestions,
     allSuggestions,
     updatedBy = 'edge-deploy',
+    metadata = {},
   }) {
     // Step 1: classify suggestions into pattern vs per-URL buckets.
     // eslint-disable-next-line max-len
@@ -1609,7 +1643,7 @@ class TokowakaClient {
     // Step 3: deploy per-URL suggestions via S3.
     if (validSuggestions.length > 0) {
       // eslint-disable-next-line max-len
-      const result = await this.#deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy);
+      const result = await this.#deployPerUrlSuggestions(site, opportunity, validSuggestions, updatedBy, metadata);
       const { succeededSuggestions: perUrlSucceeded, failedSuggestions: perUrlFailed } = result;
       succeededSuggestions = perUrlSucceeded;
       failedSuggestions.push(...perUrlFailed);
@@ -1698,6 +1732,74 @@ class TokowakaClient {
 
     return { succeededSuggestions, failedSuggestions, coveredSuggestions };
   }
+
+  /**
+   * Strips the `applyStale` flag from patches in S3 for the given per-URL suggestions.
+   * Called when an experiment completes so edge reverts to normal (non-stale) behaviour.
+   * Pattern / domain-wide suggestions are skipped — they have no per-URL S3 config.
+   * CDN cache is invalidated for every URL whose config was actually modified.
+   *
+   * @param {Object} site - Site entity
+   * @param {Object} opportunity - Opportunity entity
+   * @param {Array}  suggestions - Suggestion entities to clear (may include pattern suggestions,
+   *   which are silently skipped)
+   * @returns {Promise<void>}
+   */
+  async clearApplyStaleFromPatches(site, opportunity, suggestions) {
+    const baseURL = getEffectiveBaseURL(site);
+
+    const perUrlSuggestions = suggestions.filter((s) => {
+      const data = s.getData();
+      return data?.url && !Array.isArray(data?.allowedRegexPatterns);
+    });
+
+    if (perUrlSuggestions.length === 0) {
+      return;
+    }
+
+    const suggestionsByUrl = groupSuggestionsByUrlPath(perUrlSuggestions, baseURL, this.log);
+    const clearedUrls = [];
+
+    for (const [urlPath, urlSuggestions] of Object.entries(suggestionsByUrl)) {
+      const fullUrl = new URL(urlPath, baseURL).toString();
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const existingConfig = await this.fetchConfig(fullUrl);
+        if (!existingConfig?.patches?.length) {
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        const suggestionIds = new Set(urlSuggestions.map((s) => s.getId()));
+        let modified = false;
+        const updatedPatches = existingConfig.patches.map((patch) => {
+          if (suggestionIds.has(patch.suggestionId) && patch.applyStale) {
+            modified = true;
+            const { applyStale: _, ...rest } = patch;
+            return rest;
+          }
+          return patch;
+        });
+
+        if (modified) {
+          // eslint-disable-next-line no-await-in-loop
+          await this.uploadConfig(fullUrl, { ...existingConfig, patches: updatedPatches });
+          clearedUrls.push(fullUrl);
+        }
+      } catch (err) {
+        this.log.error(`[clear-apply-stale-failed] Failed to process URL ${fullUrl}: ${err.message}`, err);
+      }
+    }
+
+    if (clearedUrls.length > 0) {
+      try {
+        await this.invalidateCdnCache({ urls: clearedUrls });
+        this.log.info(`[clear-apply-stale] Cleared applyStale from ${clearedUrls.length} URL(s) and invalidated CDN`);
+      } catch (err) {
+        this.log.warn(`[clear-apply-stale-failed] CDN invalidation failed for ${clearedUrls.length} URL(s), S3 configs already updated: ${err.message}`, err);
+      }
+    }
+  }
 }
 
 // Export the client as default and base classes for custom implementations