@temple-wallet/extension-ads 1.0.0

package/src/execute-ads-actions/observing.ts

@@ -0,0 +1,115 @@
+import browser from 'webextension-polyfill';
+
+import { AdsConfiguration } from 'src/ads-configuration';
+import { AD_SEEN_THRESHOLD } from 'src/constants';
+import { AdsProviderName, AdsProviderTitle } from 'src/types/ads-provider';
+
+const loadingAdsIds = new Set();
+const loadedAdsIds = new Set();
+const alreadySentAnalyticsAdsIds = new Set();
+
+const IFRAME_READY_TIMEOUT = 10_000;
+
+export const subscribeToIframeLoadIfNecessary = (
+  adId: string,
+  providerName: AdsProviderName,
+  element: HTMLIFrameElement
+) => {
+  if (loadingAdsIds.has(adId)) {
+    return;
+  }
+
+  loadingAdsIds.add(adId);
+
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      window.removeEventListener('message', messageListener);
+      reject(new Error(`Timeout exceeded for ${adId}`));
+    }, IFRAME_READY_TIMEOUT);
+
+    const messageListener = (event: MessageEvent<any>) => {
+      if (event.source !== element.contentWindow) return;
+
+      try {
+        const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+
+        if (data.id !== adId) return;
+
+        if (data.type === 'ready') {
+          window.removeEventListener('message', messageListener);
+          resolve();
+        } else if (data.type === 'error') {
+          window.removeEventListener('message', messageListener);
+          reject(new Error(data.reason ?? 'Unknown error'));
+        }
+      } catch (error) {
+        console.error('Observing error:', error);
+      }
+    };
+
+    window.addEventListener('message', messageListener);
+  })
+    .then(() => {
+      if (loadedAdsIds.has(adId)) return;
+
+      loadedAdsIds.add(adId);
+      const adIsSeen = adRectIsSeen(element);
+
+      if (adIsSeen) {
+        sendExternalAdsActivity(adId, providerName);
+      } else {
+        observeIntersection(element, providerName);
+      }
+    })
+    .finally(() => void loadingAdsIds.delete(adId));
+};
+
+export const observeIntersection = (element: HTMLElement, providerName: AdsProviderName) => {
+  const observer = new IntersectionObserver(
+    entries => {
+      if (entries.some(entry => entry.isIntersecting)) {
+        sendExternalAdsActivity(element.id, providerName);
+        observer.disconnect();
+      }
+    },
+    { threshold: AD_SEEN_THRESHOLD }
+  );
+
+  observer.observe(element);
+};
+
+const sendExternalAdsActivity = (adId: string, providerName: AdsProviderName) => {
+  if (alreadySentAnalyticsAdsIds.has(adId)) {
+    return;
+  }
+
+  alreadySentAnalyticsAdsIds.add(adId);
+
+  const url = window.parent.location.href;
+
+  browser.runtime
+    .sendMessage({
+      type: AdsConfiguration.EXTERNAL_ADS_ACTIVITY_MESSAGE_TYPE,
+      url,
+      provider: AdsProviderTitle[providerName]
+    })
+    .catch(err => void console.error(err));
+};
+
+const adRectIsSeen = (element: Element) => {
+  const elementRect = element.getBoundingClientRect();
+  const viewport = window.visualViewport;
+
+  if (!viewport) {
+    return false;
+  }
+
+  const intersectionX0 = Math.min(Math.max(0, elementRect.x), viewport.width);
+  const intersectionX1 = Math.min(Math.max(0, elementRect.x + elementRect.width), viewport.width);
+  const intersectionY0 = Math.min(Math.max(0, elementRect.y), viewport.height);
+  const intersectionY1 = Math.min(Math.max(0, elementRect.y + elementRect.height), viewport.height);
+  const elementArea = elementRect.width * elementRect.height;
+  const intersectionArea = (intersectionX1 - intersectionX0) * (intersectionY1 - intersectionY0);
+
+  return intersectionArea / elementArea >= AD_SEEN_THRESHOLD;
+};

package/src/execute-ads-actions/override-element-styles.ts

@@ -0,0 +1,7 @@
+import { StringRecord } from 'src/utils';
+
+export const overrideElementStyles = (element: HTMLElement, overrides: StringRecord) => {
+  for (const stylePropName in overrides) {
+    element.style.setProperty(stylePropName, overrides[stylePropName]);
+  }
+};

package/src/execute-ads-actions/process-insert-ad-action.ts

@@ -0,0 +1,104 @@
+import { TEMPLE_WALLET_AD_ATTRIBUTE_NAME } from 'src/constants';
+import { AdActionType, InsertAdAction, ReplaceElementWithAdAction } from 'src/types/ads-actions';
+import { AdMetadata } from 'src/types/ads-meta';
+
+import { makeHypelabAdView, makePersonaAdView, makeTKeyAdView } from './ads-views';
+import { observeIntersection, subscribeToIframeLoadIfNecessary } from './observing';
+import { overrideElementStyles } from './override-element-styles';
+
+const processInsertAdActionOnce = async (action: InsertAdAction, ad: AdMetadata, wrapperElement: HTMLDivElement) => {
+  const { source, dimensions } = ad;
+
+  const { elementStyle = {}, stylesOverrides = [] } = action;
+
+  stylesOverrides.sort((a, b) => a.parentDepth - b.parentDepth);
+
+  let stylesOverridesCurrentElement: HTMLElement | null;
+
+  const { providerName } = source;
+
+  const { element: adElement, postAppend } =
+    providerName === 'Temple'
+      ? makeTKeyAdView(dimensions.width, dimensions.height, elementStyle)
+      : providerName === 'HypeLab'
+        ? makeHypelabAdView(source, dimensions, elementStyle)
+        : makePersonaAdView(source.shape, dimensions, elementStyle);
+
+  adElement.setAttribute(TEMPLE_WALLET_AD_ATTRIBUTE_NAME, 'true');
+  wrapperElement.appendChild(adElement);
+
+  switch (action.type) {
+    case AdActionType.ReplaceAllChildren:
+      stylesOverridesCurrentElement = action.parent;
+      action.parent.innerHTML = '';
+      action.parent.appendChild(wrapperElement);
+      break;
+    case AdActionType.ReplaceElement:
+      stylesOverridesCurrentElement = action.element.parentElement;
+      action.element.replaceWith(wrapperElement);
+      break;
+    default:
+      stylesOverridesCurrentElement = action.parent;
+      action.parent.insertBefore(wrapperElement, action.parent.children[action.insertionIndex]);
+      break;
+  }
+
+  if (postAppend) await postAppend();
+
+  if (adElement instanceof HTMLIFrameElement) {
+    await subscribeToIframeLoadIfNecessary(adElement.id, source.providerName, adElement);
+  } else {
+    observeIntersection(adElement, source.providerName);
+  }
+
+  let currentParentDepth = 0;
+  stylesOverrides.forEach(({ parentDepth, style }) => {
+    while (parentDepth > currentParentDepth && stylesOverridesCurrentElement) {
+      stylesOverridesCurrentElement = stylesOverridesCurrentElement.parentElement;
+      currentParentDepth++;
+    }
+    if (stylesOverridesCurrentElement) {
+      overrideElementStyles(stylesOverridesCurrentElement, style);
+    }
+  });
+};
+
+export const processInsertAdAction = async (action: InsertAdAction, ad: AdMetadata) => {
+  const { shouldUseDivWrapper, divWrapperStyle = {} } = action;
+
+  const wrapperElement = document.createElement('div');
+  wrapperElement.setAttribute(TEMPLE_WALLET_AD_ATTRIBUTE_NAME, 'true');
+
+  if (shouldUseDivWrapper) {
+    overrideElementStyles(wrapperElement, divWrapperStyle);
+  } else {
+    wrapperElement.style.display = 'contents';
+  }
+
+  await processInsertAdActionOnce(action, ad, wrapperElement).catch(error => {
+    console.error('Inserting an ad attempt error:', error);
+
+    const nextAd = action.fallbacks.shift();
+    if (nextAd) {
+      const { ad, fallbacks, divWrapperStyle, elementStyle, stylesOverrides } = action;
+      const newAction: ReplaceElementWithAdAction = {
+        type: AdActionType.ReplaceElement,
+        element: wrapperElement,
+        ad,
+        fallbacks,
+        divWrapperStyle,
+        elementStyle,
+        stylesOverrides
+      };
+
+      return processInsertAdAction(newAction, nextAd);
+    }
+
+    const emptyAdElement = document.createElement('div');
+    emptyAdElement.setAttribute(TEMPLE_WALLET_AD_ATTRIBUTE_NAME, 'true');
+    emptyAdElement.style.display = 'none';
+    wrapperElement.replaceWith(emptyAdElement);
+
+    throw error;
+  });
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+export type { AdAction, AdActionType } from './types/ads-actions';
+
+export type { PersonaAdShape } from './types/ads-meta';
+
+export type { AdsProviderName, AdsProviderTitle } from './types/ads-provider';
+
+export type { AdsRules } from './types/ads-rules';
+
+export type { RawAllAdsRules } from './types/temple-wallet-api';
+
+export { getAdsActions } from './ads-actions';
+
+export { configureAds } from './ads-configuration';
+
+export { executeAdsActions } from './execute-ads-actions';
+
+export { transformRawRules } from './transform-raw-rules';
+
+export { TempleWalletApi } from './temple-wallet-api';

package/src/temple-wallet-api.ts

@@ -0,0 +1,80 @@
+import axiosFetchAdapter from '@vespaiach/axios-fetch-adapter';
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+
+import {
+  RawAllAdsRules,
+  RawAdPlacesRule,
+  RawAdProvidersRule,
+  RawPermanentAdPlacesRule
+} from 'src/types/temple-wallet-api';
+
+const withFetchDataExtraction =
+  <A extends unknown[], T>(fetchFn: (...args: A) => Promise<AxiosResponse<T>>) =>
+  async (...args: A) => {
+    const { data } = await fetchFn(...args);
+
+    return data;
+  };
+
+export class TempleWalletApi {
+  private api: AxiosInstance;
+
+  constructor(baseUrl: string) {
+    this.api = axios.create({
+      baseURL: new URL('/api', baseUrl).href,
+      adapter: axiosFetchAdapter
+    });
+  }
+
+  getAdPlacesRulesForAllDomains = withFetchDataExtraction(() =>
+    this.api.get<Record<string, RawAdPlacesRule[]>>('/slise-ad-rules/ad-places')
+  );
+
+  getProvidersToReplaceAtAllSites = withFetchDataExtraction(() =>
+    this.api.get<string[]>('/slise-ad-rules/providers/all-sites')
+  );
+
+  getProvidersRulesForAllDomains = withFetchDataExtraction(() =>
+    this.api.get<Record<string, RawAdProvidersRule[]>>(`/slise-ad-rules/providers/by-sites`)
+  );
+
+  getSelectorsForAllProviders = withFetchDataExtraction(() =>
+    this.api.get<Record<string, string[]>>('/slise-ad-rules/providers')
+  );
+
+  getPermanentAdPlacesRulesForAllDomains = withFetchDataExtraction(() =>
+    this.api.get<Record<string, RawPermanentAdPlacesRule[]>>('/slise-ad-rules/ad-places/permanent')
+  );
+
+  getPermanentNativeAdPlacesRulesForAllDomains = withFetchDataExtraction(() =>
+    this.api.get<Record<string, RawPermanentAdPlacesRule[]>>('/slise-ad-rules/ad-places/permanent-native')
+  );
+
+  getAllRules = async (): Promise<RawAllAdsRules> => {
+    const [
+      adPlacesRulesForAllDomains,
+      providersRulesForAllDomains,
+      providersSelectors,
+      providersToReplaceAtAllSites,
+      permanentAdPlacesRulesForAllDomains,
+      permanentNativeAdPlacesRulesForAllDomains
+    ] = await Promise.all([
+      this.getAdPlacesRulesForAllDomains(),
+      this.getProvidersRulesForAllDomains(),
+      this.getSelectorsForAllProviders(),
+      this.getProvidersToReplaceAtAllSites(),
+      this.getPermanentAdPlacesRulesForAllDomains(),
+      this.getPermanentNativeAdPlacesRulesForAllDomains()
+    ]);
+
+    return {
+      adPlacesRulesForAllDomains,
+      providersRulesForAllDomains,
+      providersSelectors,
+      providersToReplaceAtAllSites,
+      permanentAdPlacesRulesForAllDomains,
+      permanentNativeAdPlacesRulesForAllDomains,
+      timestamp: Date.now()
+    };
+  };
+}

package/src/transform-raw-rules.ts

@@ -0,0 +1,139 @@
+import { isEqual } from 'lodash';
+
+import { AdPlacesRule, AdsRules } from 'src/types/ads-rules';
+import { RawAllAdsRules } from 'src/types/temple-wallet-api';
+
+export const transformRawRules = (location: Location, rules: RawAllAdsRules): AdsRules => {
+  const {
+    adPlacesRulesForAllDomains,
+    providersRulesForAllDomains,
+    providersSelectors,
+    providersToReplaceAtAllSites,
+    permanentAdPlacesRulesForAllDomains,
+    permanentNativeAdPlacesRulesForAllDomains = {},
+    timestamp
+  } = rules;
+  const { hostname, href } = location;
+  const hrefWithoutHash = href.replace(/#.*$/, '');
+
+  const hrefMatchPredicate = (regex: RegExp) => {
+    const hrefToTest = regex.source.includes('#') ? href : hrefWithoutHash;
+
+    return regex.test(hrefToTest);
+  };
+
+  return {
+    adPlacesRules: buildAdPlacesRules(hostname, hrefMatchPredicate, adPlacesRulesForAllDomains),
+    permanentAdPlacesRules: buildPermanentAdPlacesRules(
+      hostname,
+      hrefMatchPredicate,
+      permanentAdPlacesRulesForAllDomains,
+      permanentNativeAdPlacesRulesForAllDomains
+    ),
+    providersSelector: buildProvidersSelector(
+      hostname,
+      hrefMatchPredicate,
+      providersRulesForAllDomains,
+      providersSelectors,
+      providersToReplaceAtAllSites
+    ),
+    timestamp
+  };
+};
+
+const buildAdPlacesRules = (
+  hostname: string,
+  hrefMatchPredicate: (regex: RegExp) => boolean,
+  adPlacesRulesForAllDomains: RawAllAdsRules['adPlacesRulesForAllDomains']
+): AdsRules['adPlacesRules'] => {
+  const adPlacesRules = (adPlacesRulesForAllDomains[hostname] ?? []).map(({ urlRegexes, ...restRuleProps }) => ({
+    ...restRuleProps,
+    urlRegexes: urlRegexes.map(regex => new RegExp(regex))
+  }));
+
+  const aggregatedRelatedAdPlacesRules = adPlacesRules.reduce<Omit<AdPlacesRule, 'urlRegexes'>[]>(
+    (acc, { urlRegexes, selector, ...restProps }) => {
+      if (!urlRegexes.some(hrefMatchPredicate)) return acc;
+
+      const { cssString, ...restSelectorProps } = selector;
+      const ruleToComplementIndex = acc.findIndex(({ selector: candidateSelector, ...candidateRestProps }) => {
+        const { cssString: _candidateCssString, ...restCandidateSelectorProps } = candidateSelector;
+
+        return isEqual(restSelectorProps, restCandidateSelectorProps) && isEqual(restProps, candidateRestProps);
+      });
+      if (ruleToComplementIndex === -1) {
+        acc.push({ selector, ...restProps });
+      } else {
+        acc[ruleToComplementIndex].selector.cssString += ', '.concat(cssString);
+      }
+
+      return acc;
+    },
+    []
+  );
+
+  return aggregatedRelatedAdPlacesRules;
+};
+
+const buildPermanentAdPlacesRules = (
+  hostname: string,
+  hrefMatchPredicate: (regex: RegExp) => boolean,
+  permanentAdPlacesRulesForAllDomains: RawAllAdsRules['permanentAdPlacesRulesForAllDomains'],
+  permanentNativeAdPlacesRulesForAllDomains: RawAllAdsRules['permanentNativeAdPlacesRulesForAllDomains'] = {}
+): AdsRules['permanentAdPlacesRules'] => {
+  const rawPermanentAdPlacesRules = permanentAdPlacesRulesForAllDomains[hostname] ?? [];
+  const rawPermanentNativeAdPlacesRules = permanentNativeAdPlacesRulesForAllDomains[hostname] ?? [];
+
+  const permanentAdPlacesRules = rawPermanentAdPlacesRules
+    .map(({ urlRegexes, ...restRuleProps }) => ({
+      ...restRuleProps,
+      urlRegexes: urlRegexes.map(regex => new RegExp(regex)),
+      isNative: false
+    }))
+    .concat(
+      rawPermanentNativeAdPlacesRules.map(({ urlRegexes, ...restRuleProps }) => ({
+        ...restRuleProps,
+        urlRegexes: urlRegexes.map(regex => new RegExp(regex)),
+        isNative: true
+      }))
+    );
+
+  return permanentAdPlacesRules.filter(({ urlRegexes }) => urlRegexes.some(hrefMatchPredicate));
+};
+
+const buildProvidersSelector = (
+  hostname: string,
+  hrefMatchPredicate: (regex: RegExp) => boolean,
+  providersRulesForAllDomains: RawAllAdsRules['providersRulesForAllDomains'],
+  providersSelectors: RawAllAdsRules['providersSelectors'],
+  providersToReplaceAtAllSites: RawAllAdsRules['providersToReplaceAtAllSites']
+): string => {
+  const providersRules = (providersRulesForAllDomains[hostname] ?? []).map(({ urlRegexes, ...restRuleProps }) => ({
+    ...restRuleProps,
+    urlRegexes: urlRegexes.map(regex => new RegExp(regex))
+  }));
+
+  const relatedProvidersRules = providersRules.filter(({ urlRegexes }) => urlRegexes.some(hrefMatchPredicate));
+  const alreadyProcessedProviders = new Set<string>();
+  const selectorsForProvidersToReplace = new Set<string>();
+  const handleProvider = (provider: string) => {
+    if (alreadyProcessedProviders.has(provider)) return;
+
+    const newSelectors = providersSelectors[provider] ?? [];
+    newSelectors.forEach(selector => selectorsForProvidersToReplace.add(selector));
+    alreadyProcessedProviders.add(provider);
+  };
+
+  providersToReplaceAtAllSites.forEach(handleProvider);
+  relatedProvidersRules.forEach(({ providers }) => providers.forEach(handleProvider));
+
+  let providersSelector = '';
+  selectorsForProvidersToReplace.forEach(selector => {
+    providersSelector += selector + ', ';
+  });
+  if (providersSelector) {
+    providersSelector = providersSelector.slice(0, -2);
+  }
+
+  return providersSelector;
+};

package/src/types/ad-view.ts

@@ -0,0 +1,4 @@
+export interface AdView {
+  element: HTMLDivElement | HTMLIFrameElement;
+  postAppend?: () => void | Promise<unknown>;
+}

package/src/types/ads-actions.ts

@@ -0,0 +1,73 @@
+import { StringRecord } from 'src/utils';
+
+import type { AdMetadata } from './ads-meta';
+import type { AdStylesOverrides } from './temple-wallet-api';
+
+export enum AdActionType {
+  ReplaceAllChildren = 'replace-all-children',
+  ReplaceElement = 'replace-element',
+  SimpleInsertAd = 'simple-insert-ad',
+  RemoveElement = 'remove-element',
+  HideElement = 'hide-element'
+}
+
+interface AdActionBase {
+  type: AdActionType;
+}
+
+interface InsertAdActionProps {
+  ad: AdMetadata;
+  fallbacks: AdMetadata[];
+  /** @deprecated // Always wrapping now
+   * TODO: Clean-up usage
+   */
+  shouldUseDivWrapper?: boolean;
+  divWrapperStyle?: StringRecord<string>;
+  elementStyle?: StringRecord<string>;
+  stylesOverrides?: AdStylesOverrides[];
+}
+
+export interface ReplaceAllChildrenWithAdAction extends AdActionBase, InsertAdActionProps {
+  type: AdActionType.ReplaceAllChildren;
+  parent: HTMLElement;
+}
+
+export interface ReplaceElementWithAdAction extends AdActionBase, InsertAdActionProps {
+  type: AdActionType.ReplaceElement;
+  element: HTMLElement;
+}
+
+export interface SimpleInsertAdAction extends AdActionBase, InsertAdActionProps {
+  type: AdActionType.SimpleInsertAd;
+  parent: HTMLElement;
+  insertionIndex: number;
+}
+
+export interface RemoveElementAction extends AdActionBase {
+  type: AdActionType.RemoveElement;
+  element: HTMLElement;
+}
+
+export interface HideElementAction extends AdActionBase {
+  type: AdActionType.HideElement;
+  element: HTMLElement;
+}
+
+export type InsertAdAction = ReplaceAllChildrenWithAdAction | ReplaceElementWithAdAction | SimpleInsertAdAction;
+
+export type OmitAdInAction<T extends InsertAdActionProps> = Omit<T, 'ad' | 'fallbacks'>;
+
+export type InsertAdActionWithoutMeta =
+  | OmitAdInAction<ReplaceAllChildrenWithAdAction>
+  | OmitAdInAction<ReplaceElementWithAdAction>
+  | OmitAdInAction<SimpleInsertAdAction>;
+
+export type AdAction = InsertAdAction | RemoveElementAction | HideElementAction;
+
+export type AddActionsIfAdResolutionAvailable = (
+  elementToMeasure: Element,
+  shouldUseStrictContainerLimits: boolean,
+  minContainerWidthIsBannerWidth: boolean,
+  adIsNative: boolean,
+  ...actionsBases: (InsertAdActionWithoutMeta | HideElementAction | RemoveElementAction)[]
+) => boolean;

package/src/types/ads-meta.ts

@@ -0,0 +1,51 @@
+interface AdSourceBase {
+  shouldNotUseStrictContainerLimits?: boolean;
+}
+
+interface HypeLabBannerAdSource extends AdSourceBase {
+  providerName: 'HypeLab';
+  native: false;
+  size: 'small' | 'high' | 'wide';
+}
+
+interface HypeLabNativeAdSource extends AdSourceBase {
+  providerName: 'HypeLab';
+  native: true;
+  slug: string;
+}
+
+/** Only covers TKEY ads for now */
+interface TempleAdSource extends AdSourceBase {
+  providerName: 'Temple';
+}
+
+/** See: https://pub.persona3.io/docs
+ * `regular` - 321x101
+ * `medium` - 600x160
+ * `wide` - 970x90
+ * `squarish` - 300x250
+ */
+export type PersonaAdShape = 'regular' | 'medium' | 'wide' | 'squarish';
+
+interface PersonaAdSource extends AdSourceBase {
+  providerName: 'Persona';
+  shape: PersonaAdShape;
+}
+
+export type HypeLabAdSources = HypeLabBannerAdSource | HypeLabNativeAdSource;
+
+type AdSource = HypeLabAdSources | TempleAdSource | PersonaAdSource;
+
+export interface AdDimensions {
+  width: number;
+  height: number;
+  minContainerWidth: number;
+  minContainerHeight: number;
+  maxContainerWidth: number;
+  maxContainerHeight: number;
+}
+
+export interface AdMetadata {
+  source: AdSource;
+  dimensions: AdDimensions;
+}

package/src/types/ads-provider.ts

@@ -0,0 +1,8 @@
+export enum AdsProviderTitle {
+  Optimal = 'Optimal',
+  HypeLab = 'HypeLab',
+  Persona = 'Persona',
+  Temple = 'Temple Wallet'
+}
+
+export type AdsProviderName = keyof typeof AdsProviderTitle;

package/src/types/ads-rules.ts

@@ -0,0 +1,17 @@
+import { RawAdPlacesRule, RawPermanentAdPlacesRule } from './temple-wallet-api';
+
+export interface AdPlacesRule extends Omit<RawAdPlacesRule, 'urlRegexes'> {
+  urlRegexes: RegExp[];
+}
+
+export interface PermanentAdPlacesRule extends Omit<RawPermanentAdPlacesRule, 'urlRegexes'> {
+  urlRegexes: RegExp[];
+  isNative: boolean;
+}
+
+export interface AdsRules {
+  adPlacesRules: Array<Omit<AdPlacesRule, 'urlRegexes'>>;
+  permanentAdPlacesRules: PermanentAdPlacesRule[];
+  providersSelector: string;
+  timestamp: number;
+}

package/src/types/temple-wallet-api.ts

@@ -0,0 +1,56 @@
+export interface AdStylesOverrides {
+  parentDepth: number;
+  style: Record<string, string>;
+}
+
+export interface RawAdPlacesRule {
+  urlRegexes: string[];
+  selector: {
+    isMultiple: boolean;
+    cssString: string;
+    parentDepth: number;
+    shouldUseDivWrapper: boolean;
+    divWrapperStyle?: Record<string, string>;
+  };
+  stylesOverrides?: AdStylesOverrides[];
+  shouldHideOriginal?: boolean;
+}
+
+export interface RawPermanentAdPlacesRule {
+  urlRegexes: string[];
+  adSelector: {
+    isMultiple: boolean;
+    cssString: string;
+    parentDepth: number;
+  };
+  parentSelector: {
+    isMultiple: boolean;
+    cssString: string;
+    parentDepth: number;
+  };
+  insertionIndex?: number;
+  insertBeforeSelector?: string;
+  insertAfterSelector?: string;
+  insertionsCount?: number;
+  shouldUseDivWrapper: boolean;
+  divWrapperStyle?: Record<string, string>;
+  elementStyle?: Record<string, string>;
+  elementToMeasureSelector?: string;
+  stylesOverrides?: AdStylesOverrides[];
+  shouldHideOriginal?: boolean;
+}
+
+export interface RawAdProvidersRule {
+  urlRegexes: string[];
+  providers: string[];
+}
+
+export interface RawAllAdsRules {
+  adPlacesRulesForAllDomains: Record<string, RawAdPlacesRule[]>;
+  providersRulesForAllDomains: Record<string, RawAdProvidersRule[]>;
+  providersSelectors: Record<string, string[]>;
+  providersToReplaceAtAllSites: string[];
+  permanentAdPlacesRulesForAllDomains: Record<string, RawPermanentAdPlacesRule[]>;
+  permanentNativeAdPlacesRulesForAllDomains: Record<string, RawPermanentAdPlacesRule[]>;
+  timestamp: number;
+}

package/src/utils.ts

@@ -0,0 +1,10 @@
+/** From lodash */
+type Truthy<T> = T extends null | undefined | void | false | '' | 0 | 0n ? never : T;
+
+export const isTruthy = <T>(value: T): value is Truthy<T> => Boolean(value);
+
+const DEFAULT_DELAY = 300;
+
+export const delay = (ms = DEFAULT_DELAY) => new Promise(res => setTimeout(res, ms));
+
+export type StringRecord<T = string> = Record<string, T>;