@getdraft/plugin 1.17.5 → 1.19.0-alpha.1

package/src/plugin.ts

@@ -14,6 +14,7 @@ import {
   HandlerParams,
   MessageData,
   ExportAsFileParams,
+  RenderSectionPersonalizationGroupInput,
 } from './types';
 import {
   getImageParamsFromFileUrl,
@@ -22,6 +23,8 @@ import {
 } from './utils';
 import pkg from '../package.json';
 
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+
 const getDeployLink = () => {
   const regex = new RegExp(`(^| )seplugin-dev=([^;]+)`);
   const match = document.cookie.match(regex);
@@ -170,7 +173,7 @@ export class PluginInstance {
             reject(
               new DraftError(
                 code || 'unknown_error',
-                message || 'Unknown error',
+                message || UNKNOWN_ERROR_MESSAGE,
               ),
             );
           } else {
@@ -221,7 +224,7 @@ export class PluginInstance {
     }
   };
 
-  private onLoadPersonalization = async () => {
+  private onLoadPersonalization = async (requestId?: string) => {
     try {
       if (!this.config.on.loadPersonalization) {
         throw new Error('No personalization loader provided');
@@ -232,9 +235,62 @@ export class PluginInstance {
 
       this.postEvent('loadPersonalization', {
         items: personalizationDictionary,
+        requestId,
       });
     } catch (e) {
-      this.postEvent('loadPersonalization', {});
+      this.postEvent('loadPersonalization', { requestId });
+    }
+  };
+
+  private onLoadSectionPersonalizationCatalog = async (requestId?: string) => {
+    try {
+      const handler = this.config.on.loadSectionPersonalizationCatalog;
+
+      if (!handler) {
+        throw new Error('No section personalization catalog loader provided');
+      }
+
+      const catalog = await handler();
+
+      this.postEvent('loadSectionPersonalizationCatalog', {
+        ok: true,
+        requestId,
+        catalog,
+      });
+    } catch (error) {
+      this.postEvent('loadSectionPersonalizationCatalog', {
+        ok: false,
+        requestId,
+        message: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+      });
+    }
+  };
+
+  private onRenderSectionPersonalizationGroup = async (
+    data: RenderSectionPersonalizationGroupInput & { requestId?: string },
+  ) => {
+    const { requestId, ...input } = data;
+
+    try {
+      const handler = this.config.on.renderSectionPersonalizationGroup;
+
+      if (!handler) {
+        throw new Error('No section personalization renderer provided');
+      }
+
+      const renderedHtml = await handler(input);
+
+      this.postEvent('renderSectionPersonalizationGroup', {
+        ok: true,
+        requestId,
+        html: renderedHtml,
+      });
+    } catch (error) {
+      this.postEvent('renderSectionPersonalizationGroup', {
+        ok: false,
+        requestId,
+        message: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+      });
     }
   };
 
@@ -284,7 +340,17 @@ export class PluginInstance {
       } else if (event === 'uploadImage') {
         this.onImageUpload(data as UploadImageParams & { id: string });
       } else if (event === 'loadPersonalization') {
-        this.onLoadPersonalization();
+        this.onLoadPersonalization((data as { requestId?: string }).requestId);
+      } else if (event === 'loadSectionPersonalizationCatalog') {
+        this.onLoadSectionPersonalizationCatalog(
+          (data as { requestId?: string }).requestId,
+        );
+      } else if (event === 'renderSectionPersonalizationGroup') {
+        this.onRenderSectionPersonalizationGroup(
+          data as RenderSectionPersonalizationGroupInput & {
+            requestId?: string;
+          },
+        );
       } else {
         this.triggerEvent(
           this.config.on[event],
@@ -326,12 +392,21 @@ export class PluginInstance {
             apiUrl,
             pluginId,
             authData,
+            sectionPersonalization,
             __config,
           } = this.config;
 
           verifyConfig(this.config);
 
           if (this.iframe && this.iframe.contentWindow) {
+            const resolvedSectionPersonalization = {
+              ...sectionPersonalization,
+              enabled:
+                sectionPersonalization?.enabled === true &&
+                !!on.loadSectionPersonalizationCatalog &&
+                !!on.renderSectionPersonalizationGroup,
+            };
+
             this.postEvent('init', {
               container,
               locale,
@@ -340,6 +415,7 @@ export class PluginInstance {
               token,
               pluginId,
               authData,
+              sectionPersonalization: resolvedSectionPersonalization,
               apiUrl,
               __config,
               enabledListeners: Object.keys(on),

package/src/types.ts

@@ -23,6 +23,130 @@ type PersonalizationDictionaryEntry =
 
 export type PersonalizationDictionaryItems = PersonalizationDictionaryEntry[];
 
+export type SectionPersonalizationScalarValue = string | number | boolean;
+
+export interface SectionPersonalizationRangeValue {
+  from: string | number | null;
+  to: string | number | null;
+}
+
+export type SectionPersonalizationValue =
+  | SectionPersonalizationScalarValue
+  | SectionPersonalizationScalarValue[]
+  | SectionPersonalizationRangeValue
+  | null;
+
+export interface SectionPersonalizationField {
+  id: string;
+}
+
+export interface SectionPersonalizationCondition {
+  operatorId: string;
+  value: SectionPersonalizationValue;
+}
+
+export type SectionPersonalizationConditions = Record<
+  string,
+  SectionPersonalizationCondition
+>;
+
+export interface SectionPersonalizationCatalogOption {
+  label: string;
+  value: SectionPersonalizationScalarValue;
+}
+
+export type SectionPersonalizationRangeEndpointEditor =
+  | {
+      type: 'number';
+      integer?: boolean;
+      min?: number;
+      max?: number;
+    }
+  | { type: 'date' };
+
+export type SectionPersonalizationValueEditor =
+  | { type: 'none' }
+  | { type: 'text'; maxLength?: number }
+  | {
+      type: 'number';
+      integer?: boolean;
+      min?: number;
+      max?: number;
+    }
+  | { type: 'boolean' }
+  | { type: 'date' }
+  | { type: 'select'; options: SectionPersonalizationCatalogOption[] }
+  | { type: 'multi-select'; options: SectionPersonalizationCatalogOption[] }
+  | {
+      type: 'range';
+      valueEditor: SectionPersonalizationRangeEndpointEditor;
+    };
+
+export interface SectionPersonalizationCatalogOperator {
+  id: string;
+  label: string;
+  /**
+   * Optional abbreviation for compact summaries, e.g. a math symbol. The
+   * integration owns it, so Draft never derives one from `id` or `label`.
+   */
+  shortLabel?: string;
+  valueEditor: SectionPersonalizationValueEditor;
+}
+
+export interface SectionPersonalizationCatalogGroup {
+  type: 'group';
+  id: string;
+  label: string;
+  children: SectionPersonalizationCatalogNode[];
+}
+
+export interface SectionPersonalizationCatalogField {
+  type: 'field';
+  id: string;
+  label: string;
+  defaultOperatorId: string;
+  operators: SectionPersonalizationCatalogOperator[];
+}
+
+export type SectionPersonalizationCatalogNode =
+  | SectionPersonalizationCatalogGroup
+  | SectionPersonalizationCatalogField;
+
+export interface SectionPersonalizationConfig {
+  enabled: boolean;
+  aboutUrl?: string;
+}
+
+/**
+ * One audience the whole group is hidden from. Conditions inside are joined
+ * with AND, exclusions between themselves with OR.
+ */
+export interface SectionPersonalizationExclusion {
+  id: string;
+  conditions: SectionPersonalizationConditions;
+}
+
+export interface RenderSectionPersonalizationGroupInput {
+  groupId: string;
+  fields: SectionPersonalizationField[];
+  variants: Array<{
+    id: string;
+    conditions: SectionPersonalizationConditions;
+    html: string;
+  }>;
+  fallback?: {
+    id: string;
+    html: string;
+  };
+  /**
+   * Audiences the whole group must be hidden from, already stripped of unfilled
+   * conditions. Empty exclusions are dropped by Draft, so every entry carries at
+   * least one condition and the renderer never has to guard against a rule that
+   * would match everyone.
+   */
+  hiddenFor?: SectionPersonalizationExclusion[];
+}
+
 export interface SerializedTemplate {
   [key: string]: unknown;
   parentId: string | null;
@@ -55,6 +179,7 @@ export type MessageData = {
   code?: string;
   message?: string;
   action?: string;
+  requestId?: string;
 };
 
 export interface ExportAsFileParams {
@@ -266,6 +391,14 @@ export interface Handlers {
   openGallery: EventHandler<(url?: string) => Promise<void>>;
   uploadImage: AsyncEventHandler<UploadImageParams, string>;
   loadPersonalization: AsyncEventHandler<void, PersonalizationDictionary>;
+  loadSectionPersonalizationCatalog: AsyncEventHandler<
+    void,
+    SectionPersonalizationCatalogNode[]
+  >;
+  renderSectionPersonalizationGroup: AsyncEventHandler<
+    RenderSectionPersonalizationGroupInput,
+    string
+  >;
 }
 
 export type HandlerParams<H> = H extends
@@ -290,6 +423,7 @@ export interface PluginConfig {
   pluginId: string;
   apiUrl: string;
   disableHotkeysPassing?: boolean;
+  sectionPersonalization?: SectionPersonalizationConfig;
   __config?: object;
   on: Partial<Handlers>;
 }