@surfside/ads-core 2.0.22 → 2.1.0

package/lib/types/Api.d.ts

@@ -5,14 +5,16 @@ import Handlebars from 'handlebars/runtime';
 import { type BuildHybridCarouselFn, type BuildHybridCarouselFromInitialBidFn, type BuildRecommendedCarouselFn, type BuildSponsoredCarouselFn, type BuildSponsoredCarouselFromInitialBidFn } from './helpers/response/Carousel';
 import { type EvaluateClickthroughTemplateFn, type EvaluateProductCardTemplateFn } from './services/Template';
 import { type BuildDynamicZoneRequestFn, type GetDynamicZoneFn } from './services/Dynamic';
-import { type GenerateCategoriesFn } from './services/Category';
+import { type MapCategoriesFn } from './services/Category';
 import { type InitTrackerServiceFn, type IProductTrackerService } from './services/Tracker';
 export declare const PROD_BIDDER = "//bid.surfside.io/rtb/bids/surfside";
 export declare const PROD_CONFIGURATION_SERVICE = "//r.surfside.io";
+export declare const PROD_CATEGORY_CONFIGURATION_SERVICE = "//r.surfside.io";
 export declare const PROD_SPONSORED_PRODUCT_FEED = "//creative.surfside.io";
 export declare const PROD_RECOMMENDED_PRODUCT_FEED = "//creative.surfside.io";
 export declare const PROD_RECOMMENDER_SERVICE = "//t.surfside.io";
 export declare const PROD_DYNAMIC_ZONE_SERVICE = "//r.surfside.io/";
+export declare const PROD_TELEMETRY_SERVICE = "//telemetry.surfside.io/v1/ingest";
 /**
  * A collection of services for querying the surfside API and building responses
  */
@@ -46,9 +48,14 @@ export interface ISurfsideApi {
      */
     getConfiguration: GetConfigurationFn;
     /**
-     * Generates categories for the site
+     * @deprecated Use mapCategories instead
+     * Maps publisher categories to Surfside canonical categories
      */
-    generateCategories: GenerateCategoriesFn;
+    generateCategories: MapCategoriesFn;
+    /**
+     * Maps publisher categories to Surfside canonical categories
+     */
+    mapCategories: MapCategoriesFn;
     /**
      * Creates a set of trackers from a product input. Builds a URL with all relevant info from the trackers
      * and returns functions to call when the relevant events fire
@@ -128,17 +135,11 @@ export interface ISurfsideApi {
     getDynamicZone: GetDynamicZoneFn;
     buildDynamicZoneRequest: BuildDynamicZoneRequestFn;
 }
-/**
- * Initializes the API with the services explicitly passed to it. This function is used by the framework for overloading
- * mock services. It should not be used in an application
- * @param internalApiDto The list of services and helpers to inject
- * @returns An initialized Surfside API
- */
-export declare function InitSurfAdsCoreInternal(internalApiDto: {
+export type SurfAdsCoreInitDto = {
     logger: ILogger | undefined;
     requestBids: RequestBidsFn;
     getConfiguration: GetConfigurationFn;
-    generateCategories: GenerateCategoriesFn;
+    generateCategories: MapCategoriesFn;
     getGeo: GetGeoFn;
     getDevice: GetDeviceFn;
     getAllSponsoredProducts: GetAllSponsoredProductFromNativeIdFn;
@@ -164,13 +165,29 @@ export declare function InitSurfAdsCoreInternal(internalApiDto: {
     channelId: string;
     locationId: string;
     userId: string | undefined;
-}): AsyncResult<ISurfsideApi>;
-export declare const InitSurfAdsCoreServices: (logger: ILogger | undefined, bidderServiceUrl: string, configurationServiceUrl: string, productFeedUrl: string, recommendedProductFeedUrl: string, recommenderServiceUrl: string, dynamicZoneServiceUrl: string, windowInfo: INativeTemplateDelegateWindow, screenInfo: IScreen, navigator: INavigator, mobile: boolean, ip: string | undefined, geoProviderToken: string | undefined, accountId: string, siteId: string, channelId: string, locationId: string, userId: string | undefined, initTrackerService?: InitTrackerServiceFn) => AsyncResult<ISurfsideApi>;
+};
+/**
+ * Initializes the API with the services explicitly passed to it. This function is used by the framework for overloading
+ * mock services. It should not be used in an application
+ * @param internalApiDto The list of services and helpers to inject
+ * @returns An initialized Surfside API
+ */
+export declare function InitSurfAdsCoreInternal(internalApiDto: SurfAdsCoreInitDto): AsyncResult<ISurfsideApi>;
+export declare const InitSurfAdsCoreServices: (logger: ILogger | undefined, bidderServiceUrl: string, configurationServiceUrl: string, productFeedUrl: string, recommendedProductFeedUrl: string, recommenderServiceUrl: string, dynamicZoneServiceUrl: string, windowInfo: INativeTemplateDelegateWindow, screenInfo: IScreen, navigator: INavigator, mobile: boolean, ip: string | undefined, geoProviderToken: string | undefined, accountId: string, siteId: string, channelId: string, locationId: string, userId: string | undefined, initTrackerService?: InitTrackerServiceFn, overrides?: Partial<SurfAdsCoreInitDto>) => AsyncResult<ISurfsideApi>;
 export declare const InitSurfAdsCoreSSR: (windowInfo: INativeTemplateDelegateWindow, screen: IScreen, navigator: INavigator, mobile: boolean, ip: string, geoProviderToken: string, accountId: string, siteId: string, channelId: string, locationId: string, userId: string | undefined, logger?: ILogger) => AsyncResult<ISurfsideApi>;
 export declare const InitSurfAdsCore: (channelId: string, accountId: string, siteId: string, locationId: string, userId: string | undefined, logger?: ILogger) => AsyncResult<ISurfsideApi>;
-export declare class MissingConfigurationError extends Error {
-    constructor(accountId: string, siteId: string);
-}
 export declare class NotABrowserError extends Error {
     constructor();
 }
+export declare class SurfsideAdsDisabledError extends Error {
+    constructor();
+}
+export declare class LocationExcludedError extends Error {
+    constructor(locationId: string);
+}
+export declare class ZoneExcludedError extends Error {
+    constructor(zoneId: string);
+}
+export declare class MissingConfigurationError extends Error {
+    constructor(accountId: string, siteId: string);
+}

package/lib/types/BuildInfo.d.ts

@@ -1,4 +1,4 @@
-export declare const SurfsideAdsCoreVersionInfo: {
+export declare const VersionInfo: {
     buildBranch: string;
     buildHash: string;
     buildVer: string;

package/lib/types/Init.d.ts

@@ -0,0 +1,99 @@
+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 MapCategoriesFn } from './services/Category';
+export type OverrideFactory<T, U = ISurfAdsCoreConfiguration> = (config: U, original: T) => Result<T>;
+export interface ISurfAdsCoreConfigurationOverrides {
+    mapCategories: OverrideFactory<(categories: string[]) => string[]>;
+    generateCategories: OverrideFactory<MapCategoriesFn>;
+    requestBids: OverrideFactory<RequestBidsFn>;
+    getAllSponsoredProducts: OverrideFactory<GetAllSponsoredProductFromNativeIdFn>;
+    getAllSponsoredBrandProducts: OverrideFactory<GetAllSponsoredProductFromNativeIdFn>;
+    getRecommendedProduct: OverrideFactory<GetRecommendedProductFromProductIdFn>;
+    generateTopProducts: OverrideFactory<NonPersonalRecommenderFn>;
+    generateForYou: OverrideFactory<PersonalRecommenderFn>;
+    generatePreviousPurchases: OverrideFactory<PersonalRecommenderFn>;
+    getDynamicZone: OverrideFactory<GetDynamicZoneFn>;
+    buildAllSponsoredProductCardResponses: OverrideFactory<BuildAllSponsoredProductCardResponsesFn>;
+    generateSponsoredProductCardResponse: OverrideFactory<GenerateSponsoredProductCardResponseFn>;
+    evaluateProductCardTemplate: OverrideFactory<EvaluateProductCardTemplateFn>;
+    evaluateClickthroughTemplate: OverrideFactory<EvaluateClickthroughTemplateFn>;
+    startRequest: (config: ISurfAdsCoreConfiguration, startRequest: RequestBuilderFn) => Result<RequestBuilderFn>;
+    trackerService: OverrideFactory<IProductTrackerService>;
+    createTelemetryCollector: OverrideFactory<ITelemetryCollector | undefined, Omit<ISurfAdsCoreConfiguration, 'geo' | 'handlebars' | 'configuration' | 'logger'>>;
+}
+export interface ISurfAdsCoreConfiguration extends ISurfAdsCoreDependencies {
+    windowInfo: INativeTemplateDelegateWindow;
+    screen: IScreen;
+    navigator: INavigator;
+    mobile: boolean;
+    ip: string | undefined;
+    accountId: string;
+    siteId: string;
+    channelId: string;
+    locationId: string;
+    userId: string | undefined;
+    overrides?: {
+        services?: Partial<ISurfAdsCoreConfigurationOverrides>;
+    };
+}
+export declare function CreateSurfAdsCore(config: ISurfAdsCoreConfiguration): Result<ISurfsideApi>;
+export interface ILoadSurfAdsCoreConfiguration {
+    logger?: ILogger;
+    windowInfo: INativeTemplateDelegateWindow;
+    screen: IScreen;
+    navigator: INavigator;
+    mobile: boolean;
+    ip: string | undefined;
+    accountId: string;
+    siteId: string;
+    channelId: string;
+    locationId: string;
+    userId: string | undefined;
+    telemetry?: boolean;
+    overrides?: {
+        services?: Partial<ISurfAdsCoreConfigurationOverrides>;
+        dependencies?: Partial<ISurfAdsCoreDependencies>;
+    };
+}
+export interface ISurfAdsCoreDependencies {
+    handlebars: typeof Handlebars;
+    configuration: ICompiledPublisherConfiguration;
+    geo: IGeoContext | undefined;
+    device: IDevice | undefined;
+    logger: ILogger | undefined;
+}
+export declare const LoadSurfAdsCoreHandlebarsDependencies: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow) => [typeof Handlebars, HandlebarsHelpers];
+export interface ILoadSurfAdsCoreConfigurationDependenciesConfig {
+    logger: ILogger | undefined;
+    accountId: string;
+    siteId: string;
+    handlebars: typeof Handlebars;
+    handlebarsHelpers: HandlebarsHelpers;
+    overrides?: {
+        dependencies?: Partial<ISurfAdsCoreDependencies>;
+    };
+}
+export declare const LoadSurfAdsCoreConfigurationDependencies: (config: ILoadSurfAdsCoreConfigurationDependenciesConfig) => AsyncResult<ICompiledPublisherConfiguration>;
+export interface ILoadSurfAdsCoreGeoDependenciesConfig {
+    logger: ILogger | undefined;
+    overrides?: {
+        dependencies?: Partial<ISurfAdsCoreDependencies>;
+    };
+}
+export declare const LoadSurfAdsCoreGeoDependencies: (config: ILoadSurfAdsCoreGeoDependenciesConfig) => AsyncResult<IGeoContext>;
+export interface ILoadSurfAdsCoreDeviceDependenciesConfig {
+    logger: ILogger | undefined;
+    screen: IScreen;
+    navigator: INavigator;
+    mobile: boolean;
+    overrides?: {
+        dependencies?: Partial<ISurfAdsCoreDependencies>;
+    };
+}
+export declare const LoadSurfAdsCoreDeviceDependencies: (config: ILoadSurfAdsCoreDeviceDependenciesConfig) => IDevice | undefined;
+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>;

package/lib/types/helpers/Handlebars.d.ts

@@ -28,6 +28,7 @@ export declare function slug(name: string, options: {
         dropBefore: string | undefined;
         length: number | undefined;
         separator: string | undefined;
+        asciify: boolean | undefined;
     };
 }): string;
 /**

package/lib/types/helpers/RequestBuilder.d.ts

@@ -1,7 +1,7 @@
 import { type IApp, type IBanner, type IBidRequest, type IDevice, type IGeoContext, type IImp, type INative, type INativeRequest, type IRegs, type ISite, type IUser, type IVideo } from '../models';
 import { type ILogger } from '../services';
 import { type NativeRequestBuilder } from './NativeRequestBuilder';
-import { type GenerateCategoriesFn } from '../services/Category';
+import { type MapCategoriesFn } from '../services/Category';
 export type RequestBuilderFn = (zoneId: string, id?: string) => RequestBuilder;
 export type RequestWith<T> = (t: T) => RequestBuilder;
 export type RequestBuilder = {
@@ -17,6 +17,13 @@ export type RequestBuilder = {
     withNatives: (requests: (string | INativeRequest)[], options?: Partial<INative>, impOptions?: Partial<IImp>) => RequestBuilder;
     withNativeCopies: (request: string | INativeRequest, n: number, options?: Partial<INative>, impOptions?: Partial<IImp>) => RequestBuilder;
     withProductCards: (nativeBuilder: NativeRequestBuilder, options?: Partial<INative>, impOptions?: Partial<IImp>) => RequestBuilder;
+    withImp: (zoneId: string, imp?: Partial<IImp>) => ImpressionRequestBuilder;
     build: () => IBidRequest;
 };
-export declare function StartRequest(logger: ILogger | undefined, accountId: string, siteId: string, channelId: string, locationId: string, device: IDevice | undefined, geo: IGeoContext | undefined, userId: string | undefined, generateCategories: GenerateCategoriesFn, zoneId: string, id?: string): RequestBuilder;
+export type ImpressionRequestBuilder = RequestBuilder & {
+    andBanner: (w: number, h: number, options?: Partial<IBanner>) => ImpressionRequestBuilder;
+    andVideo: (w: number, h: number, minduration: number | undefined, maxduration: number, mimes?: string[], options?: Partial<IVideo>) => ImpressionRequestBuilder;
+    andNative: (request: string | INativeRequest, options?: Partial<INative>) => ImpressionRequestBuilder;
+    andProductCards: (nativeBuilder: NativeRequestBuilder, options?: Partial<INative>) => ImpressionRequestBuilder;
+};
+export declare function StartRequest(logger: ILogger | undefined, accountId: string, siteId: string, channelId: string, locationId: string, device: IDevice | undefined, geo: IGeoContext | undefined, userId: string | undefined, generateCategories: MapCategoriesFn, strictCategoryFiltering: boolean | undefined, zoneId: string, id?: string): RequestBuilder;

package/lib/types/helpers/TelemetryCollector.d.ts

@@ -0,0 +1,25 @@
+import { type IDevice } from '../models';
+import { ITelemetryCollector, type ITelemetryDevice, type ITelemetryEntry } from '../services/Logger';
+export interface ISSRTelemetryCollectorOptions {
+    accountId: string;
+    siteId: string;
+    channelId: string;
+    locationId: string;
+    endpoint: string;
+    tags?: Record<string, string>;
+    batchIntervalMs?: number;
+    url: string;
+    device?: ITelemetryDevice;
+}
+export declare const DeviceToTelemetryDevice: (device: IDevice | undefined) => ITelemetryDevice | undefined;
+export declare class SSRTelemetryCollector extends ITelemetryCollector {
+    private readonly _endpoint;
+    private readonly _tags;
+    private readonly _batchIntervalMs;
+    private readonly _pageUrl;
+    private queue;
+    private flushTimer;
+    constructor(options: ISSRTelemetryCollectorOptions);
+    record(entry: ITelemetryEntry): void;
+    flush(): void;
+}

package/lib/types/helpers/Types.d.ts

@@ -0,0 +1 @@
+export type Debouncer = ReturnType<typeof globalThis.setTimeout>;

package/lib/types/helpers/Window.d.ts

@@ -1,7 +1,17 @@
+import { NotABrowserError } from '../Api';
 import { type INativeTemplateDelegateWindow } from '../models';
-import { type Result } from '../services';
+import { type INavigator, type IScreen, type Result } from '../services';
 export declare const WindowFromUrl: (urlStr: string) => Result<INativeTemplateDelegateWindow>;
 export declare const GetWindowInfo: () => Result<INativeTemplateDelegateWindow>;
+export declare const GetNavigator: () => Result<INavigator>;
+export declare const GetScreenInfo: () => Result<IScreen>;
+export declare const GetBrowserInfo: () => Result<{
+    windowInfo: INativeTemplateDelegateWindow;
+    navigator: INavigator;
+    isMobile: boolean;
+    screen: IScreen;
+}>;
+export declare const IsMobile: () => import("../services").ErrResult<NotABrowserError> | import("../services").OkResult<boolean>;
 export declare class NotAUrlError extends Error {
     url: string;
     constructor(url: string);

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

@@ -2,7 +2,9 @@ export * from './NativeRequestBuilder';
 export * from './RequestBuilder';
 export * from './response';
 export * from './Handlebars';
+export * from './TelemetryCollector';
 export * from './TryGet';
 export * from './Window';
 export * from './Generator';
 export * from './Functions';
+export * from './Types';

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

@@ -5,7 +5,7 @@ import { type IProductTrackerService } from '../../services/Tracker';
 import type { GenerateSponsoredProductCardResponseFn, IBuiltProductCardResponse } from './ProductCard';
 export type BuildSponsoredCarouselFn = (request: IBidRequest) => Result<IBuiltCarousel>;
 export type BuildSponsoredCarouselFromInitialBidFn = (request: IBidRequest, initialBid: IBid) => Result<IBuiltCarousel>;
-export type BuildRecommendedCarouselFn = (RecommenderType: PublicRecommenderType) => Result<IBuiltCarousel>;
+export type BuildRecommendedCarouselFn = (RecommenderType: PublicRecommenderType, category?: string) => Result<IBuiltCarousel>;
 export type BuildHybridCarouselFn = (recommenderType: PublicRecommenderType, request: IBidRequest) => Result<IBuiltCarousel>;
 export type BuildHybridCarouselFromInitialBidFn = (RecommenderType: PublicRecommenderType, request: IBidRequest, initialBid: IBid) => Result<IBuiltCarousel>;
 export type CarouselNextProductFn = () => AsyncGenerator<IBuiltProductCardResponse>;
@@ -43,9 +43,9 @@ export interface IPastPurchasesProductRecommender {
 export type ProductRecommender = ITopProductRecommender | IForYouProductRecommender | IPastPurchasesProductRecommender;
 export declare const BuildSponsoredCarousel: (logger: ILogger | undefined, requestBids: RequestBidsFn, generateProductCardResponse: GenerateSponsoredProductCardResponseFn, request: IBidRequest) => Result<IBuiltCarousel>;
 export declare const BuildSponsoredCarouselFromInitialBid: (logger: ILogger | undefined, requestBids: RequestBidsFn, generateProductCardResponse: GenerateSponsoredProductCardResponseFn, request: IBidRequest, initialBid: IBid) => Result<IBuiltCarousel>;
-export declare const BuildRecommendedCarousel: (logger: ILogger | undefined, evaluateClickthroughTemplate: EvaluateClickthroughTemplateFn, topProductGenerator: NonPersonalRecommenderFn, forYouProductGenerator: PersonalRecommenderFn, pastPurchasesProductGenerator: PersonalRecommenderFn, userId: string | undefined, trackers: IProductTrackerService, recommenderType: PublicRecommenderType) => 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, 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, recommenderType: PublicRecommenderType, request: IBidRequest, initialBid: IBid) => Result<IBuiltCarousel>;
+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 declare class InvalidRecommenderTypeError extends Error {
     type: string;
     constructor(type: string);

package/lib/types/index.d.ts

@@ -2,4 +2,5 @@ export * from './helpers';
 export * from './models';
 export * from './services';
 export * from './Api';
-export * from './BuildInfo';
+export * as SurfsideAdsCoreVersionInfo from './BuildInfo';
+export * from './Init';

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

@@ -4,7 +4,7 @@ export interface ICompiledCategoryGlobalConfigDTO {
     globalPatterns: string[];
 }
 export interface ICompiledCategoryPublisherConfigurationDTO {
-    'strategy': CategoryStrategy;
+    strategy: CategoryStrategy;
     customCanonicalMap: Record<string, string>;
     customPatterns: string[];
 }

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

@@ -32,6 +32,7 @@ export interface IPublisherConfiguration {
     carouselStyleSheet?: string;
     reAuctionEnabled?: boolean;
     reAuctionInterval?: number;
+    brandTakeover?: Record<string, string[]>;
 }
 export interface ICompiledPublisherConfigurationTemplatesDTO {
     productCardTemplate: string;
@@ -65,6 +66,10 @@ export interface ICompiledPublisherConfigurationSettingsDTO {
     sponsoredByEnabled?: boolean;
     defaultImage?: string;
     strictCategoryMatching?: boolean;
+    disableSurfsideAds?: boolean;
+    excludedLocations?: string[];
+    excludedZones?: string[];
+    brandTakeover?: Record<string, string[]>;
 }
 export interface ICompiledPublisherConfigurationDTO {
     templates: ICompiledPublisherConfigurationTemplatesDTO;
@@ -72,6 +77,11 @@ export interface ICompiledPublisherConfigurationDTO {
     category: ICompiledCategoryPublisherConfigurationDTO;
     dynamicZones?: Record<string, IDynamicZone>;
 }
+export interface ILoadedTemplateModules {
+    productCardTemplateRaw?: TemplateSpecification;
+    clickthroughTemplateRaw?: TemplateSpecification;
+    callbacks?: Callbacks;
+}
 export interface ICompiledPublisherConfiguration {
     settings: ICompiledPublisherConfigurationSettingsDTO;
     templates: ICompiledPublisherConfigurationTemplates;

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

@@ -1,3 +1,4 @@
 export * from './Configuration';
 export * from './Product';
 export * from './Recommended';
+export * from './Category';

package/lib/types/models/rtb/BidRequest.d.ts

@@ -229,7 +229,7 @@ export interface ISite {
 }
 export interface IDeal {
     id: string;
-    bidfloor: number;
+    bidfloor?: number;
     bidfloorcur?: string;
     at?: number;
     wseat?: string[];
@@ -408,4 +408,7 @@ export interface ISurfExtension {
     accountLocationId: string;
     surfCategory: string[];
     keywords?: string[];
+    publisherConfig?: string;
+    bcreatives?: number[];
+    bplacements?: number[];
 }

package/lib/types/models/rtb/BidResponse.d.ts

@@ -1,6 +1,7 @@
 export interface IBidExtensions extends Record<string, any> {
     primaryCategory?: string;
     originalCategories?: string[];
+    filteringEnabled?: boolean;
 }
 export interface IBid {
     id: string;

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

@@ -1,8 +1,21 @@
-import type { IBidRequest, IBidResponse } from '../models';
+import type { IBidRequest, IBidResponse, ICompiledPublisherConfiguration, INativeTemplateDelegateWindow } from '../models';
 import { type ILogger } from './Logger';
-import { type AsyncResult } from './Result';
+import { type AsyncResult, type ErrResult, type Result } from './Result';
 export type RequestBidsFn = (request: IBidRequest) => AsyncResult<IBidResponse>;
-export declare const RequestBids: (logger: ILogger | undefined, url: string, accountId: string, siteId: string, locationId: string, channelId: string, bidRequest: IBidRequest) => AsyncResult<IBidResponse>;
+export declare const RequestBids: (logger: ILogger | undefined, url: string, accountId: string, siteId: string, locationId: string, channelId: string, excludedZones: string[] | undefined, bidRequest: IBidRequest) => AsyncResult<IBidResponse>;
+export declare class StatefulRequestBidsSubscriber {
+    private _log;
+    private _requestBids;
+    private _bounce?;
+    private _resolvers;
+    private _requestToImpIdMap;
+    private _request;
+    constructor(_log: ILogger | undefined, _requestBids: RequestBidsFn);
+    kill(err: ErrResult): void;
+    debounce(bidRequest: IBidRequest, res: (value: Result<IBidResponse>) => void): void;
+}
+export declare const DebounceBidRequests: (state: StatefulRequestBidsSubscriber) => (bidRequest: IBidRequest) => AsyncResult<IBidResponse>;
+export declare const WrapBidRequestDebouncerIfEnabled: (logger: ILogger | undefined, config: ICompiledPublisherConfiguration, window: INativeTemplateDelegateWindow, requestBids: RequestBidsFn) => RequestBidsFn;
 export declare class NoBidsError extends Error {
     readonly request: IBidRequest;
     readonly response?: Response | undefined;
@@ -29,3 +42,6 @@ export declare class MalformedBidResponseError extends Error {
     readonly bidResponse: unknown;
     constructor(request: IBidRequest, response: Response, bidResponse: unknown);
 }
+export declare class MissingBidRequestInDebouncerError extends Error {
+    constructor();
+}

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

@@ -1,4 +1,12 @@
 import { type ICompiledCategoryPublisherConfiguration } from '../models/retail/Category';
 import { type ILogger } from './Logger';
-export type GenerateCategoriesFn = (providedCategories: string[]) => string[];
+export type MapCategoriesFn = (providedCategories: string[]) => string[];
+/**
+ * @deprecated Use MapCategoriesFn
+ */
+export type GenerateCategoriesFn = MapCategoriesFn;
+export declare const MapCategories: (logger: ILogger | undefined, providedCategories: string[], page: string, categoryConfig: ICompiledCategoryPublisherConfiguration) => string[];
+/**
+ * @deprecated Use MapCategories
+ */
 export declare const GenerateCategories: (logger: ILogger | undefined, providedCategories: string[], page: string, categoryConfig: ICompiledCategoryPublisherConfiguration) => string[];

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

@@ -1,6 +1,27 @@
 import type Handlebars from 'handlebars/runtime';
-import type { ICompiledPublisherConfiguration } from '../models';
-import { type AsyncResult, type ILogger } from '.';
+import type { ICompiledPublisherConfiguration, ICompiledPublisherConfigurationDTO, ILoadedTemplateModules } from '../models';
+import { type AsyncResult, type ILogger, type Result } from '.';
 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 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 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 {
+    accountId: string;
+    siteId: string;
+    constructor(accountId: string, siteId: string);
+}
+export declare class MalformedConfigurationError extends Error {
+    accountId: string;
+    siteId: string;
+    constructor(accountId: string, siteId: string);
+}
+export declare class FailedToFetchGlobalCategoryConfigurationError extends Error {
+    constructor();
+}

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

@@ -1,4 +1,5 @@
-import type { NativeRequestBuilderFn, RequestBuilder, RequestBuilderFn } from '../helpers';
+import { ZoneExcludedError } from '../Api';
+import type { ImpressionRequestBuilder, NativeRequestBuilderFn, RequestBuilder, RequestBuilderFn } from '../helpers';
 import type { IBidRequest, ICompiledPublisherConfiguration } from '../models';
 import { type DynamicCreative, type IDynamicZone, type IScreenSize } from '../models/dynamic/DynamicZone';
 import type { IScreen } from './Device';
@@ -6,11 +7,12 @@ import { type ILogger } from './Logger';
 import { type AsyncResult, type Result } from './Result';
 export interface IDynamicZoneRequest {
     request: IBidRequest;
+    /** @deprecated */
     requestIds: Record<string, DynamicCreative>;
 }
 export type BuildDynamicZoneRequestFn = (zoneId: string, dynamicZone: IDynamicZone, category?: string[]) => Result<IDynamicZoneRequest>;
 export type GetDynamicZoneFn = (zoneId: string) => AsyncResult<IDynamicZone>;
-export declare const GetDynamicZone: (logger: ILogger | undefined, config: ICompiledPublisherConfiguration, zoneId: string) => Promise<import("./Result").ErrResult<MissingDynamicZoneError> | import("./Result").OkResult<IDynamicZone>>;
+export declare const GetDynamicZone: (logger: ILogger | undefined, config: ICompiledPublisherConfiguration, zoneId: string) => Promise<import("./Result").ErrResult<ZoneExcludedError> | import("./Result").OkResult<IDynamicZone>>;
 export declare const BuildDynamicZoneRequest: (logger: ILogger | undefined, startRequest: RequestBuilderFn, nativeRequest: NativeRequestBuilderFn, screenInfo: IScreen, zoneId: string, dynamicZone: IDynamicZone, category?: string[]) => Result<IDynamicZoneRequest>;
 export declare class NoDynamicScreenSizeMatchError extends Error {
     readonly dynamicZone: IDynamicZone;
@@ -19,7 +21,7 @@ export declare class NoDynamicScreenSizeMatchError extends Error {
     constructor(dynamicZone: IDynamicZone, screenInfo: IScreen, selectedStringSize: string);
 }
 export declare const buildDynamicBidRequestFromSelectedScreenSize: (logger: ILogger | undefined, startRequest: RequestBuilderFn, nativeRequest: NativeRequestBuilderFn, zoneId: string, screenSize: IScreenSize, category?: string[]) => Result<IDynamicZoneRequest>;
-export declare const buildDynamicBidRequestRecursive: (logger: ILogger | undefined, nativeRequest: NativeRequestBuilderFn, builder: RequestBuilder, requestIds: Record<string, DynamicCreative>, [head, ...tail]: DynamicCreative[]) => Result<[builder: RequestBuilder, requestIds: Record<string, DynamicCreative>]>;
+export declare const buildDynamicBidRequestRecursive: (logger: ILogger | undefined, nativeRequest: NativeRequestBuilderFn, builder: ImpressionRequestBuilder, requestIds: Record<string, DynamicCreative>, [head, ...tail]: DynamicCreative[]) => Result<[builder: RequestBuilder, /** @deprecated */ requestIds: Record<string, DynamicCreative>]>;
 export declare class MissingDynamicZoneError extends Error {
     readonly zoneId: string;
     constructor(zoneId: string);

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

@@ -1,5 +1,34 @@
 export type LoggerFn = (...args: any[]) => void;
-export type ContextFn = (...prefix: (string | undefined)[]) => IContextLogger;
+export type ContextFn = (name: string | undefined, tags?: Record<string, string>) => IContextLogger;
+export interface ITelemetryDevice {
+    ua?: string;
+    browser?: string;
+    os?: string;
+    osv?: string;
+    make?: string;
+    model?: string;
+    deviceType?: number;
+    screenW?: number;
+    screenH?: number;
+    language?: string;
+}
+export interface ITelemetryEntry {
+    name: string;
+    durationMs: number;
+    timestamp: number;
+    pageUrl?: string;
+    device?: ITelemetryDevice;
+    tags?: Record<string, string>;
+}
+export declare abstract class ITelemetryCollector {
+    protected readonly accountId: string;
+    protected readonly siteId: string;
+    protected readonly channelId: string;
+    protected readonly locationId: string;
+    protected readonly device: ITelemetryDevice | undefined;
+    constructor(accountId: string, siteId: string, channelId: string, locationId: string, device: ITelemetryDevice | undefined);
+    abstract record(entry: ITelemetryEntry): void;
+}
 export interface ILogger {
     info: LoggerFn;
     debug: LoggerFn;
@@ -9,6 +38,11 @@ export interface ILogger {
 }
 export interface IContextLogger extends ILogger {
     with: ContextFn;
+    prefix?: string;
+    time?: (name: string) => () => void;
+    collector?: ITelemetryCollector;
 }
 export declare const InitLogger: (rich?: boolean) => IContextLogger;
-export declare const Ctx: (logger: ILogger | undefined) => IContextLogger | undefined;
+export declare function CreateTelemetryLogger(logger: ILogger, telemetryCollector: ITelemetryCollector | undefined): IContextLogger;
+export declare function Ctx(logger: ILogger): IContextLogger;
+export declare function Ctx(logger: ILogger | undefined): IContextLogger | undefined;

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

@@ -1 +1,4 @@
+/**
+ * @deprecated @see Memoize
+ */
 export declare const Memo: <T extends any[], R>(fn: (...args: T) => R) => (...args: T) => R;

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

@@ -4,8 +4,8 @@ import type { GetRecommendedProductFromProductIdFn } from './Product';
 export type NonPersonalRecommenderFn = (category?: string) => AsyncGenerator<IProductInformation>;
 export type PersonalRecommenderFn = (userId: string, category?: string) => AsyncGenerator<IProductInformation>;
 export declare function GenerateTopProducts(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, category?: string): AsyncGenerator<IProductInformation>;
-export declare function GenerateForYou(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string, category?: string): AsyncGenerator<IProductInformation>;
-export declare function GeneratePreviousPurchases(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string, category?: string): AsyncGenerator<IProductInformation>;
+export declare function GenerateForYou(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string | undefined, category?: string): AsyncGenerator<IProductInformation>;
+export declare function GeneratePreviousPurchases(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string | undefined, category?: string): AsyncGenerator<IProductInformation>;
 export declare class NoRecommendationsError extends Error {
     constructor();
 }

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

@@ -18,6 +18,7 @@ export declare const GetValue: <T, E = Error>(result: Result<T, E> | undefined)
 export declare const ValueOr: <T, E = Error, U = T>(result: Result<T, E> | undefined, or: U) => T | U;
 export declare const GetValueOrThrow: <T>(result: Result<T, Error>, error?: Error) => T;
 export declare const WrapValue: <T>(value: T | undefined | null) => Result<T>;
+export declare const WrapValueAsync: <T>(value: T | undefined | null) => AsyncResult<T>;
 export declare const AssertValue: <T>(result: Result<T, Error>, error?: Error) => T;
 export declare const AllOrNone: <T>(results: Result<T, Error>[]) => Result<T[]>;
 export declare const Some: <T>(results: Result<T, Error>[]) => OkResult<T[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surfside/ads-core",
-  "version": "2.0.22",
+  "version": "2.1.0",
   "module": "./lib/esm/index.js",
   "main": "./lib/cjs/index.js",
   "types": "./lib/types/index.d.ts",
@@ -37,8 +37,8 @@
   },
   "scripts": {
     "clean": "rm -rf ./lib",
-    "prebuild": "echo \"export const SurfsideAdsCoreVersionInfo = { buildBranch: '$(git rev-parse --abbrev-ref HEAD)', buildHash: '$(git rev-parse --short HEAD)', buildVer: '$(bun -e 'console.log(require(\"./package.json\").version)')'};\" > src/BuildInfo.ts",
-    "build": "bunx npm-run-all --parallel \"types\" \"esm\" \"cjs\"",
+    "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",