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

package/src/index.d.ts

@@ -21,7 +21,7 @@ export interface TokawakaPatch {
   currValue?: string;
   target: 'ai-bots' | 'bots' | 'all';
   opportunityId: string;
-  suggestionId: string;
+  suggestionId?: string;
   prerenderRequired: boolean;
   lastUpdated: number;
 }
@@ -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;
@@ -108,12 +129,14 @@ export abstract class BaseOpportunityMapper {
   abstract requiresPrerender(): boolean;
   
   /**
-   * Converts a suggestion to a Tokowaka patch
+   * Converts suggestions to Tokowaka patches
    */
-  abstract suggestionToPatch(
-    suggestion: Suggestion,
-    opportunityId: string
-  ): TokawakaPatch | null;
+  abstract suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string,
+    existingConfig: TokowakaConfig | null
+  ): TokawakaPatch[];
   
   /**
    * Checks if a suggestion can be deployed for this opportunity type
@@ -142,7 +165,11 @@ export class HeadingsMapper extends BaseOpportunityMapper {
   
   getOpportunityType(): string;
   requiresPrerender(): boolean;
-  suggestionToPatch(suggestion: Suggestion, opportunityId: string): TokawakaPatch | null;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
   canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
 }
 
@@ -155,13 +182,36 @@ export class ContentSummarizationMapper extends BaseOpportunityMapper {
   
   getOpportunityType(): string;
   requiresPrerender(): boolean;
-  suggestionToPatch(suggestion: Suggestion, opportunityId: string): TokawakaPatch | null;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string
+  ): TokawakaPatch[];
+  canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
+}
+
+/**
+ * FAQ opportunity mapper
+ * Handles conversion of FAQ suggestions to Tokowaka patches
+ */
+export class FaqMapper extends BaseOpportunityMapper {
+  constructor(log: any);
+  
+  getOpportunityType(): string;
+  requiresPrerender(): boolean;
   canDeploy(suggestion: Suggestion): { eligible: boolean; reason?: string };
   
   /**
-   * Converts markdown text to HAST (Hypertext Abstract Syntax Tree) format
+   * Creates patches for FAQ suggestions
+   * First patch is heading (h2) if it doesn't exist, then individual FAQ divs
+   * @throws {Error} if suggestionToPatch is called directly
    */
-  markdownToHast(markdown: string): object;
+  suggestionsToPatches(
+    urlPath: string,
+    suggestions: Suggestion[],
+    opportunityId: string,
+    existingConfig: TokowakaConfig | null
+  ): TokawakaPatch[];
 }
 
 /**
@@ -232,6 +282,7 @@ export class CdnClientRegistry {
 export default class TokowakaClient {
   constructor(config: {
     bucketName: string;
+    previewBucketName?: string;
     s3Client: S3Client;
     env?: Record<string, any>;
   }, log: any);
@@ -239,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
@@ -266,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
    */