@surfside/ads-core 2.0.22 → 2.3.0-0ff9dfa7.0

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;
@@ -79,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/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,29 @@
 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 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 {
+    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/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/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,47 +1,48 @@
-{
-  "name": "@surfside/ads-core",
-  "version": "2.0.22",
-  "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",
-    "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\"",
-    "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-0ff9dfa7.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"
+  }
+}