@surfside/ads-core 2.1.0 → 2.3.0-c2d1d13c.0

package/lib/types/Init.d.ts

@@ -2,9 +2,34 @@ import { type ISurfsideApi } from './Api';
 import Handlebars from 'handlebars/runtime';
 import { type BuildAllSponsoredProductCardResponsesFn, type GenerateSponsoredProductCardResponseFn, type HandlebarsHelpers, type RequestBuilderFn } from './helpers';
 import { type IDevice, type ICompiledPublisherConfiguration, type IGeoContext, type INativeTemplateDelegateWindow } from './models';
-import { type RequestBidsFn, type GetAllSponsoredProductFromNativeIdFn, type GetRecommendedProductFromProductIdFn, type NonPersonalRecommenderFn, type PersonalRecommenderFn, type GetDynamicZoneFn, type EvaluateProductCardTemplateFn, type EvaluateClickthroughTemplateFn, type IProductTrackerService, type ILogger, type ITelemetryCollector, type IScreen, type INavigator, type Result, type AsyncResult } from './services';
+import { type RequestBidsFn, type GetAllSponsoredProductFromNativeIdFn, type GetRecommendedProductFromProductIdFn, type NonPersonalRecommenderFn, type PersonalRecommenderFn, type GetDynamicZoneFn, type EvaluateProductCardTemplateFn, type EvaluateClickthroughTemplateFn, type IProductTrackerService, type ILogger, type ITelemetryCollector, type IScreen, type INavigator, type Result, type AsyncResult, type LoadConfigurationFileFn, type LoadGlobalCategoryConfigurationFn } from './services';
 import { type MapCategoriesFn } from './services/Category';
 export type OverrideFactory<T, U = ISurfAdsCoreConfiguration> = (config: U, original: T) => Result<T>;
+export type AsyncOverrideFactory<T, U = ISurfAdsCoreConfiguration> = (config: U, original: T) => AsyncResult<T>;
+export declare const MemoizeOverride: <TArgs extends unknown[], TReturn, U = ISurfAdsCoreConfiguration>(time?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+}>) => OverrideFactory<(...args: TArgs) => TReturn, U>;
+export declare const MemoizeOverrideAsync: <TArgs extends unknown[], TReturn, U = ISurfAdsCoreConfiguration>(time?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+}>) => AsyncOverrideFactory<(...args: TArgs) => Promise<TReturn>, U>;
+export declare const CacheOverride: <TArgs extends unknown[], TReturn, U = ISurfAdsCoreConfiguration>(timeout?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+}>) => OverrideFactory<(...args: TArgs) => TReturn, U>;
+export declare const AsyncCacheOverride: <TArgs extends unknown[], TReturn, U = ISurfAdsCoreConfiguration>(timeout?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+}>) => OverrideFactory<(...args: TArgs) => Promise<TReturn>, U>;
 export interface ISurfAdsCoreConfigurationOverrides {
     mapCategories: OverrideFactory<(categories: string[]) => string[]>;
     generateCategories: OverrideFactory<MapCategoriesFn>;
@@ -23,6 +48,8 @@ export interface ISurfAdsCoreConfigurationOverrides {
     startRequest: (config: ISurfAdsCoreConfiguration, startRequest: RequestBuilderFn) => Result<RequestBuilderFn>;
     trackerService: OverrideFactory<IProductTrackerService>;
     createTelemetryCollector: OverrideFactory<ITelemetryCollector | undefined, Omit<ISurfAdsCoreConfiguration, 'geo' | 'handlebars' | 'configuration' | 'logger'>>;
+    loadConfigurationFile: OverrideFactory<LoadConfigurationFileFn, ILoadSurfAdsCoreConfigurationDependenciesConfig>;
+    loadGlobalCategoryConfiguration: OverrideFactory<LoadGlobalCategoryConfigurationFn, ILoadSurfAdsCoreConfigurationDependenciesConfig>;
 }
 export interface ISurfAdsCoreConfiguration extends ISurfAdsCoreDependencies {
     windowInfo: INativeTemplateDelegateWindow;
@@ -73,6 +100,10 @@ export interface ILoadSurfAdsCoreConfigurationDependenciesConfig {
     handlebars: typeof Handlebars;
     handlebarsHelpers: HandlebarsHelpers;
     overrides?: {
+        services?: Partial<{
+            loadConfigurationFile: OverrideFactory<LoadConfigurationFileFn, ILoadSurfAdsCoreConfigurationDependenciesConfig>;
+            loadGlobalCategoryConfiguration: OverrideFactory<LoadGlobalCategoryConfigurationFn, ILoadSurfAdsCoreConfigurationDependenciesConfig>;
+        }>;
         dependencies?: Partial<ISurfAdsCoreDependencies>;
     };
 }
@@ -97,3 +128,20 @@ export declare const LoadSurfAdsCoreDeviceDependencies: (config: ILoadSurfAdsCor
 export declare const LoadSurfAdsCoreDependencies: (config: ILoadSurfAdsCoreConfiguration) => AsyncResult<ISurfAdsCoreDependencies>;
 export declare const LoadSurfAdsCore: (config: ILoadSurfAdsCoreConfiguration) => AsyncResult<ISurfsideApi>;
 export declare const LoadAdsCoreBrowser: (accountId: string, channelId: string, siteId: string, locationId: string, userId?: string, logger?: ILogger) => AsyncResult<ISurfsideApi>;
+export type LoadsSurfAdsCoreHeadlessConfig = {
+    accountId: string;
+    siteId: string;
+    channelId: string;
+    locationId: string;
+    userId?: string;
+    ip: string;
+    telemetry?: boolean;
+    logging?: boolean;
+    userAgent: string;
+    url: string;
+    overrides?: {
+        services?: Partial<ISurfAdsCoreConfigurationOverrides>;
+        dependencies?: Partial<ISurfAdsCoreDependencies>;
+    };
+};
+export declare const LoadSurfAdsCoreHeadless: (config: LoadsSurfAdsCoreHeadlessConfig) => AsyncResult<ISurfsideApi>;

package/lib/types/helpers/response/Banner.d.ts

@@ -1,3 +1,5 @@
+import { type IBidResponse, type IBid, type ICompiledPublisherConfiguration, type INativeTemplateDelegateWindow } from '../../models';
+import { type ILogger, type Result } from '../../services';
 import { type IBuiltResponse } from './BuiltResponse';
 /**
  * A built banner response - includes the `adm` field for the banner as well as the rendered commerce media
@@ -19,4 +21,12 @@ export interface IBuiltBannerResponse extends IBuiltResponse {
      * the clickthrough URL template). For regular static banners that click out to 3rd party sites, this is `undefined`
      */
     clickthrough?: string;
+    win: string;
+}
+export type BuildBannerResponseCoreFn = (bid: IBid) => Result<IBuiltBannerResponse>;
+export declare const BuildBannerResponseCore: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, config: ICompiledPublisherConfiguration, bid: IBid) => Result<IBuiltBannerResponse>;
+export type BuildAllBannersCoreFn = (bidResponse: IBidResponse) => Result<IBuiltBannerResponse[]>;
+export declare const BuildAllBannersCore: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, config: ICompiledPublisherConfiguration, bidResponse: IBidResponse) => Result<IBuiltBannerResponse[]>;
+export declare class MissingCoreProductInfoError extends Error {
+    constructor();
 }

package/lib/types/helpers/response/Carousel.d.ts

@@ -1,5 +1,5 @@
-import { type IBid, type IBidRequest } from '../../models';
-import { type ILogger, type NonPersonalRecommenderFn, type PersonalRecommenderFn, type RequestBidsFn, type Result } from '../../services';
+import { type IBid, type IBidRequest, type ICompiledPublisherConfiguration, type INativeTemplateDelegateWindow, type IBidResponse } from '../../models';
+import { type AsyncResult, type GetAllSponsoredProductFromNativeIdFn, type ILogger, type NonPersonalRecommenderFn, type PersonalRecommenderFn, type RequestBidsFn, type Result } from '../../services';
 import { type EvaluateClickthroughTemplateFn } from '../../services/Template';
 import { type IProductTrackerService } from '../../services/Tracker';
 import type { GenerateSponsoredProductCardResponseFn, IBuiltProductCardResponse } from './ProductCard';
@@ -13,6 +13,10 @@ export interface IBuiltCarousel {
     type: 'carousel';
     getProduct: CarouselNextProductFn;
 }
+export interface ISimpleBuiltCarousel {
+    type: 'simpleCarousel';
+    products: IBuiltProductCardResponse[];
+}
 export type RecommenderType = 'top-products' | 'for-you' | 'past-purchases';
 export interface IPublicTopProductsRecommenderType {
     type: 'top-products';
@@ -46,6 +50,10 @@ export declare const BuildSponsoredCarouselFromInitialBid: (logger: ILogger | un
 export declare const BuildRecommendedCarousel: (logger: ILogger | undefined, evaluateClickthroughTemplate: EvaluateClickthroughTemplateFn, topProductGenerator: NonPersonalRecommenderFn, forYouProductGenerator: PersonalRecommenderFn, pastPurchasesProductGenerator: PersonalRecommenderFn, userId: string | undefined, trackers: IProductTrackerService, recommenderType: PublicRecommenderType, category?: string) => Result<IBuiltCarousel>;
 export declare const BuildHybridCarousel: (logger: ILogger | undefined, evaluateClickthroughTemplate: EvaluateClickthroughTemplateFn, requestBids: RequestBidsFn, generateProductCardResponse: GenerateSponsoredProductCardResponseFn, topProductGenerator: NonPersonalRecommenderFn, forYouProductGenerator: PersonalRecommenderFn, pastPurchasesProductGenerator: PersonalRecommenderFn, userId: string | undefined, trackers: IProductTrackerService, excludedZones: string[] | undefined, recommenderType: PublicRecommenderType, request: IBidRequest) => Result<IBuiltCarousel>;
 export declare const BuildHybridCarouselFromInitialBid: (logger: ILogger | undefined, evaluateClickthroughTemplate: EvaluateClickthroughTemplateFn, requestBids: RequestBidsFn, generateProductCardResponse: GenerateSponsoredProductCardResponseFn, topProductGenerator: NonPersonalRecommenderFn, forYouProductGenerator: PersonalRecommenderFn, pastPurchasesProductGenerator: PersonalRecommenderFn, userId: string | undefined, trackers: IProductTrackerService, excludedZones: string[] | undefined, recommenderType: PublicRecommenderType, request: IBidRequest, initialBid: IBid) => Result<IBuiltCarousel>;
+export type BuildSimpleCarouselFn = (bid: IBid) => AsyncResult<ISimpleBuiltCarousel>;
+export declare const BuildSimpleCarousel: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, getAllSponsoredBrandProducts: GetAllSponsoredProductFromNativeIdFn, config: ICompiledPublisherConfiguration, bid: IBid) => AsyncResult<ISimpleBuiltCarousel>;
+export type BuildAllSimpleCarouselsFn = (bidResponse: IBidResponse) => AsyncResult<ISimpleBuiltCarousel[]>;
+export declare const BuildAllSimpleCarousels: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, getAllSponsoredBrandProducts: GetAllSponsoredProductFromNativeIdFn, config: ICompiledPublisherConfiguration, bidResponse: IBidResponse) => AsyncResult<ISimpleBuiltCarousel[]>;
 export declare class InvalidRecommenderTypeError extends Error {
     type: string;
     constructor(type: string);

package/lib/types/helpers/response/Html.d.ts

@@ -0,0 +1,2 @@
+import { type IProductInformation } from '../../models';
+export declare const getDataFromHtmlString: (html: string) => Partial<IProductInformation>;

package/lib/types/helpers/response/Products.d.ts

@@ -0,0 +1,8 @@
+import { type IBid, type ICompiledPublisherConfiguration, type INativeResponse, type IProductInformation } from '../../models';
+import { type AsyncResult, type GetAllSponsoredProductFromNativeIdFn, type ILogger, type Result } from '../../services';
+import { type ITrackerObject } from './ProductCard';
+export declare const fetchProductsFromBid: (logger: ILogger | undefined, getAllSponsoredProducts: GetAllSponsoredProductFromNativeIdFn, getAllSponsoredBrandProducts: GetAllSponsoredProductFromNativeIdFn, config: ICompiledPublisherConfiguration, bid: IBid) => AsyncResult<{
+    products: IProductInformation[];
+    native: INativeResponse;
+}>;
+export declare const getTrackers: (logger: ILogger | undefined, bid: IBid, native: INativeResponse, productIds?: string[]) => Result<ITrackerObject>;

package/lib/types/helpers/response/Video.d.ts

@@ -1,5 +1,6 @@
-import type { IVast } from '../../models';
-import type { IBuiltResponse } from './BuiltResponse';
+import type { IBid, IBidResponse, ICompiledPublisherConfiguration, INativeTemplateDelegateWindow, IVast } from '../../models';
+import { type ILogger, type Result } from '../../services';
+import { type IBuiltResponse } from './BuiltResponse';
 /**
  * A built video response. The raw Vast XML response from the bidder has been parsed out into a structure object here.
  * @expandType IBuiltResponse
@@ -15,3 +16,13 @@ export interface IBuiltVideo extends IBuiltResponse {
      */
     clickthrough: string;
 }
+export interface IBuiltVideoCore extends IBuiltResponse {
+    type: 'video';
+    video: string;
+    clickthrough: string;
+    win: string;
+}
+export type BuildVideoResponseCoreFn = (bid: IBid) => Result<IBuiltVideoCore>;
+export declare const BuildVideoResponseCore: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, configuration: ICompiledPublisherConfiguration, bid: IBid) => Result<IBuiltVideoCore>;
+export type BuildAllVideosCoreFn = (bidResponse: IBidResponse) => Result<IBuiltVideoCore[]>;
+export declare const BuildAllVideosCore: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, configuration: ICompiledPublisherConfiguration, bidResponse: IBidResponse) => Result<IBuiltVideoCore[]>;

package/lib/types/helpers/response/index.d.ts

@@ -1,6 +1,18 @@
+import type { IBid, IBidResponse, ICompiledPublisherConfiguration, INativeTemplateDelegateWindow } from '../../models';
+import { type AsyncResult, type GetAllSponsoredProductFromNativeIdFn, type ILogger } from '../../services';
+import { type IBuiltBannerResponse } from './Banner';
+import { type ISimpleBuiltCarousel } from './Carousel';
+import { type IBuiltVideoCore } from './Video';
 export * from './BuiltResponse';
 export * from './Banner';
 export * from './Clickthrough';
 export * from './ProductCard';
 export * from './Video';
 export * from './Carousel';
+type CreativeResponsesCore = IBuiltBannerResponse | IBuiltVideoCore | ISimpleBuiltCarousel;
+export type BuildAllResponsesCoreFn = (bidResponse: IBidResponse) => AsyncResult<CreativeResponsesCore[]>;
+export declare const BuildAllResponsesCore: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, config: ICompiledPublisherConfiguration, getAllSponsoredBrandProducts: GetAllSponsoredProductFromNativeIdFn, bidResponse: IBidResponse) => AsyncResult<CreativeResponsesCore[]>;
+export declare class InvalidCreativeTypeError extends Error {
+    readonly bid: IBid;
+    constructor(bid: IBid);
+}

package/lib/types/models/retail/Configuration.d.ts

@@ -89,3 +89,10 @@ export interface ICompiledPublisherConfiguration {
     dynamicZones?: Record<string, IDynamicZone>;
 }
 export declare const DefaultProductCallbackExtras: () => ProductCallbackExtras;
+export declare class Configuration implements ICompiledPublisherConfiguration {
+    settings: ICompiledPublisherConfigurationSettingsDTO;
+    templates: ICompiledPublisherConfigurationTemplates;
+    category: ICompiledCategoryPublisherConfiguration;
+    dynamicZones?: Record<string, IDynamicZone> | undefined;
+    constructor(overrides?: Partial<ICompiledPublisherConfiguration>);
+}

package/lib/types/services/Configuration.d.ts

@@ -5,11 +5,13 @@ import { type HandlebarsHelpers } from '../helpers';
 import { type ICompiledCategoryGlobalConfigDTO, type ICompiledCategoryPublisherConfiguration, type ICompiledCategoryPublisherConfigurationDTO } from '../models/retail/Category';
 export type GetConfigurationFn = () => AsyncResult<ICompiledPublisherConfiguration>;
 export declare const GetConfiguration: (logger: ILogger | undefined, url: string, handlebars: typeof Handlebars, helpers: HandlebarsHelpers, accountId: string, siteId: string) => AsyncResult<ICompiledPublisherConfiguration>;
+export type LoadConfigurationFileFn = (accountId: string, siteId: string) => AsyncResult<ICompiledPublisherConfigurationDTO>;
 export declare const LoadConfigurationFile: (logger: ILogger | undefined, accountId: string, siteId: string) => AsyncResult<ICompiledPublisherConfigurationDTO>;
 export declare const LoadConfigurationTemplateModules: (logger: ILogger | undefined, configurationDto: ICompiledPublisherConfigurationDTO) => AsyncResult<ILoadedTemplateModules>;
 export declare const CreateCompiledConfiguration: (logger: ILogger | undefined, loadedTemplateModules: ILoadedTemplateModules, configurationDto: ICompiledPublisherConfigurationDTO, handlebars: typeof Handlebars, handlebarsHelpers: HandlebarsHelpers, globalCategories: ICompiledCategoryGlobalConfigDTO) => Result<ICompiledPublisherConfiguration>;
 export declare const LoadCompiledConfiguration: (logger: ILogger | undefined, configurationDto: ICompiledPublisherConfigurationDTO, handlebars: typeof Handlebars, handlebarsHelpers: HandlebarsHelpers) => AsyncResult<Omit<ICompiledPublisherConfiguration, "category">>;
 export declare const CreateCategoryConfiguration: (logger: ILogger | undefined, globalCategories: ICompiledCategoryGlobalConfigDTO, publisherCategories: ICompiledCategoryPublisherConfigurationDTO | undefined) => Result<ICompiledCategoryPublisherConfiguration>;
+export type LoadGlobalCategoryConfigurationFn = () => AsyncResult<ICompiledCategoryGlobalConfigDTO>;
 export declare const LoadGlobalCategoryConfiguration: (logger: ILogger | undefined) => AsyncResult<ICompiledCategoryGlobalConfigDTO>;
 export declare const LoadConfiguration: (logger: ILogger | undefined, accountId: string, siteId: string, handlebars: typeof Handlebars, handlebarsHelpers: HandlebarsHelpers) => AsyncResult<ICompiledPublisherConfiguration>;
 export declare class FailedToFetchConfigurationError extends Error {

package/lib/types/services/Memo.d.ts

@@ -1,2 +1,28 @@
-export declare const Memoize: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
-export declare const MemoizeAsync: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+export declare const Memoize: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn, { minutes, hours, seconds, milliseconds, cache }?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+    cache: Map<string, [last: number, value: TReturn]>;
+}>) => (...args: TArgs) => TReturn;
+export declare const MemoizeAsync: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, { minutes, hours, seconds, milliseconds, cache }?: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+    cache: Map<string, [last: number, value: Promise<TReturn>]>;
+}>) => (...args: TArgs) => Promise<TReturn>;
+export declare const Cache: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn, { minutes, hours, seconds, milliseconds, cache }: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+    cache: [last: number, value: TReturn];
+}>) => (...args: TArgs) => TReturn;
+export declare const CacheAsync: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, { minutes, hours, seconds, milliseconds, cache }: Partial<{
+    minutes: number;
+    hours: number;
+    seconds: number;
+    milliseconds: number;
+    cache: [last: number, value: Promise<TReturn>];
+}>) => (...args: TArgs) => Promise<TReturn>;

package/package.json

@@ -1,47 +1,48 @@
-{
-  "name": "@surfside/ads-core",
-  "version": "2.1.0",
-  "module": "./lib/esm/index.js",
-  "main": "./lib/cjs/index.js",
-  "types": "./lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./lib/esm/index.js",
-      "require": "./lib/cjs/index.js",
-      "types": "./lib/types/index.d.ts"
-    }
-  },
-  "license": "UNLICENSED",
-  "type": "module",
-  "files": [
-    "lib/",
-    "README.md"
-  ],
-  "devDependencies": {
-    "@eslint/js": "^9.25.1",
-    "@types/bun": "latest",
-    "@types/handlebars": "^4.1.0",
-    "@types/jest": "^29.5.14",
-    "eslint": "^9.25.1",
-    "jest": "^29.7.0",
-    "npm-run-all": "^4.1.5",
-    "ts-jest": "^29.3.2",
-    "typedoc": "^0.28.5",
-    "typescript-eslint": "^8.41.0"
-  },
-  "peerDependencies": {
-    "typescript": "^5.8.3"
-  },
-  "dependencies": {
-    "handlebars": "^4.7.8"
-  },
-  "scripts": {
-    "clean": "rm -rf ./lib",
-    "build": "bun x npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
-    "build:debug": "bun ./debug.build.ts",
-    "types": "tsc -p ./tsconfig.types.json",
-    "esm": "tsc -p ./tsconfig.esm.json",
-    "cjs": "tsc -p tsconfig.cjs.json",
-    "lint": "npx eslint"
-  }
-}
+{
+  "name": "@surfside/ads-core",
+  "version": "2.3.0-c2d1d13c.0",
+  "module": "./lib/esm/index.js",
+  "main": "./lib/cjs/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js",
+      "types": "./lib/types/index.d.ts"
+    }
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "lib/",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.25.1",
+    "@types/bun": "latest",
+    "@types/handlebars": "^4.1.0",
+    "@types/jest": "^29.5.14",
+    "eslint": "^9.25.1",
+    "jest": "^29.7.0",
+    "npm-run-all": "^4.1.5",
+    "ts-jest": "^29.3.2",
+    "typedoc": "^0.28.5",
+    "typescript-eslint": "^8.41.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8"
+  },
+  "scripts": {
+    "clean": "rm -rf ./lib",
+    "build": "bun x npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
+    "build:debug": "bun ./debug.build.ts",
+    "types": "tsc -p ./tsconfig.types.json",
+    "esm": "tsc -p ./tsconfig.esm.json",
+    "cjs": "tsc -p tsconfig.cjs.json",
+    "lint": "npx eslint",
+    "test": "jest --config jest.config.cjs"
+  }
+}