@adobe/spacecat-shared-tokowaka-client 1.19.1 → 1.21.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

@@ -50,6 +50,26 @@ import {
 
 export { FastlyKVClient } from './fastly-kv-client.js';
 export { calculateForwardedHost } from './utils/custom-html-utils.js';
+export { SUGGESTION_BULK_UPDATE_TYPE } from './utils/suggestion-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;
@@ -69,6 +89,7 @@ class TokowakaClient {
     const {
       TOKOWAKA_SITE_CONFIG_BUCKET: bucketName,
       TOKOWAKA_PREVIEW_BUCKET: previewBucketName,
+      IMPORT_WORKER_QUEUE_URL: importWorkerQueueUrl,
     } = env;
 
     if (context.tokowakaClient) {
@@ -81,6 +102,8 @@ class TokowakaClient {
       s3Client: s3?.s3Client ?? context.s3Client,
       env,
       dataAccess: context.dataAccess,
+      sqs: context.sqs,
+      importWorkerQueueUrl,
     }, log);
     context.tokowakaClient = client;
     return client;
@@ -95,10 +118,13 @@ class TokowakaClient {
    * @param {Object} config.env - Environment variables (for CDN credentials)
    * @param {Object} [config.dataAccess] - Data access layer
    *   (provides Suggestion.saveMany for batch saves)
+   * @param {Object} [config.sqs] - SQS client (sendMessage(queueUrl, payload)). Used to offload
+   *   very large covered-suggestion saves to the import worker instead of saving them directly.
+   * @param {string} [config.importWorkerQueueUrl] - Import worker SQS queue URL.
    * @param {Object} log - Logger instance
    */
   constructor({
-    bucketName, previewBucketName, s3Client, env = {}, dataAccess,
+    bucketName, previewBucketName, s3Client, env = {}, dataAccess, sqs, importWorkerQueueUrl,
   }, log) {
     this.log = log;
 
@@ -115,6 +141,8 @@ class TokowakaClient {
     this.s3Client = s3Client;
     this.env = env;
     this.dataAccess = dataAccess;
+    this.sqs = sqs;
+    this.importWorkerQueueUrl = importWorkerQueueUrl;
 
     this.mapperRegistry = new MapperRegistry(log);
     this.cdnClientRegistry = new CdnClientRegistry(env, log);
@@ -1058,7 +1086,14 @@ class TokowakaClient {
             this.log.info(`[edge-rollback] Cleaning ${covered.length} covered suggestion(s) for pattern ${suggestion.getId()} (isDomainWide=${isDomainWide}, fallback=${coveredFallback})`);
           }
           // eslint-disable-next-line no-await-in-loop, max-len
-          await cleanupCoveredSuggestions(this.dataAccess, covered, coveredFallback, updatedBy, fieldsToStrip, this.log);
+          await cleanupCoveredSuggestions(this.dataAccess, covered, coveredFallback, updatedBy, fieldsToStrip, this.log, {
+            sqs: this.sqs,
+            queueUrl: this.importWorkerQueueUrl,
+            siteId: site.getId(),
+            unset: fieldsToStrip,
+            updatedBy: updatedBy ?? coveredFallback,
+            log: this.log,
+          });
         }
       }
     }
@@ -1485,6 +1520,7 @@ class TokowakaClient {
    * @param {Array} allSuggestions - Full opportunity suggestion list
    * @param {string} updatedBy
    * @param {Array} coveredSuggestions - Accumulator (mutated)
+   * @param {string} siteId
    * @returns {Promise<void>} Throws on metaconfig upload failure
    * @private
    */
@@ -1497,6 +1533,7 @@ class TokowakaClient {
     allSuggestions,
     updatedBy,
     coveredSuggestions,
+    siteId,
   ) {
     const data = suggestion.getData();
     const coverageField = data?.isDomainWide ? 'coveredByDomainWide' : 'coveredByPattern';
@@ -1567,7 +1604,14 @@ class TokowakaClient {
         cs.setUpdatedBy(updatedBy);
       });
       try {
-        await saveSuggestions(this.dataAccess, covered);
+        await saveSuggestions(this.dataAccess, covered, {
+          sqs: this.sqs,
+          queueUrl: this.importWorkerQueueUrl,
+          siteId,
+          set: { [coverageField]: suggestion.getId() },
+          updatedBy,
+          log: this.log,
+        });
         coveredSuggestions.push(...covered);
         // eslint-disable-next-line max-len
         this.log.info(`[edge-deploy] Marked ${covered.length} suggestions as ${coverageField}=${suggestion.getId()}`);
@@ -1660,6 +1704,7 @@ class TokowakaClient {
             allSuggestions,
             updatedBy,
             coveredSuggestions,
+            site.getId(),
           );
           deployedPatternSuggestions.push(suggestion);
         } catch (error) {

package/src/utils/suggestion-utils.js

@@ -92,26 +92,68 @@ export function filterEligibleSuggestions(suggestions, mapper) {
   return { eligible, ineligible };
 }
 
+// Import worker job type for a bulk suggestion field update (agnostic set/unset by id).
+export const SUGGESTION_BULK_UPDATE_TYPE = 'suggestion-bulk-update';
+
 /**
  * Batch-saves suggestions using the optimal strategy based on count.
  *
  * - <= 1700: sequential chunked upsert via saveMany (chunkSize 25).
  *   ~4s for 1700 suggestions from the DB layer, but ~11s observed end-to-end
  *   from the API due to serialization, network, and Lambda overhead.
- * - > 1700: parallel individual .save() via Promise.allSettled to avoid
- *   sequential chunk bottleneck at scale.
+ * - > 1700 with no queueContext: parallel individual .save() via Promise.allSettled to
+ *   avoid sequential chunk bottleneck at scale.
+ * - > 1700 with queueContext: enqueues a SUGGESTION_BULK_UPDATE_TYPE job to the import
+ *   worker instead of saving here (the worker fetches by id and applies
+ *   queueContext.set/unset itself). Falls back to the Promise.allSettled path above
+ *   if sqs/queueUrl aren't configured or sendMessage fails, so a queue outage
+ *   degrades rather than silently drops the save.
  *
  * @param {Object} dataAccess - Data access layer
  * @param {Array} suggestions - Suggestion entities to save
+ * @param {Object} [queueContext] - sqs, queueUrl, siteId, set/unset,
+ *   updatedBy (already resolved), log
  * @returns {Promise<void>}
  */
 const PARALLEL_SAVE_THRESHOLD = 1700;
 
-export async function saveSuggestions(dataAccess, suggestions) {
+export async function saveSuggestions(dataAccess, suggestions, queueContext) {
   if (suggestions.length === 0) {
     return;
   }
   if (suggestions.length > PARALLEL_SAVE_THRESHOLD) {
+    if (queueContext) {
+      const {
+        sqs, queueUrl, siteId, set, unset, updatedBy, log,
+      } = queueContext;
+
+      if (queueUrl && sqs) {
+        try {
+          await sqs.sendMessage(queueUrl, {
+            type: SUGGESTION_BULK_UPDATE_TYPE,
+            siteId,
+            suggestionIds: suggestions.map((s) => s.getId()),
+            ...(set && { set }),
+            ...(unset && { unset }),
+            updatedBy,
+          });
+          log.info(
+            `[suggestion-bulk-update] Queued bulk update for ${suggestions.length} suggestion(s)`,
+          );
+          return;
+        } catch (error) {
+          log.error(
+            `[suggestion-bulk-update] Failed to queue bulk update, falling back to direct save: ${error.message}`,
+          );
+        }
+      } else {
+        log.warn(
+          '[suggestion-bulk-update] SQS/IMPORT_WORKER_QUEUE_URL not configured; '
+          + `falling back to direct save for ${suggestions.length} suggestion(s)`,
+        );
+      }
+    }
+
     const results = await Promise.allSettled(suggestions.map((s) => s.save()));
     const failed = results.filter((r) => r.status === 'rejected');
     if (failed.length > 0) {
@@ -150,10 +192,11 @@ export function stripSuggestion(suggestion, actorFallback, updatedBy) {
  * @param {string|undefined} updatedBy - Explicit actor
  * @param {string[]} fieldsToStrip - Specific fields to remove
  * @param {Object} log - Logger instance
+ * @param {Object} [queueContext] - Passed through to saveSuggestions unchanged
  * @returns {Promise<void>}
  */
 // eslint-disable-next-line max-len
-export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallback, updatedBy, fieldsToStrip, log) {
+export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallback, updatedBy, fieldsToStrip, log, queueContext) {
   if (covered.length === 0) {
     return;
   }
@@ -162,7 +205,7 @@ export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallba
     cs.setUpdatedBy(updatedBy ?? actorFallback);
   });
   try {
-    await saveSuggestions(dataAccess, covered);
+    await saveSuggestions(dataAccess, covered, queueContext);
   } catch (error) {
     // eslint-disable-next-line max-len
     log.error(`[edge-rollback-failed] Failed to clean ${covered.length} covered suggestion(s): ${error.message}`);