@surfside/ads-core 1.0.6

package/lib/types/services/recommender/IRecommenderService.d.ts

@@ -0,0 +1,47 @@
+import type { IProductInformation, IRecommendedProduct } from '../../models';
+/**
+ * Recommender service, provides methods to get recommendations for products.
+ */
+export interface IRecommenderService {
+    /**
+     * @deprecated Use `generateTopProduct` instead
+     */
+    getTopProducts: (accountId: string, siteId: string, locationId: string, count: number) => Promise<IRecommendedProduct[] | null>;
+    /**
+     * Generator function for the next existing top recommended product.
+     * Returns when out of existing products.
+     * @param accountId The account id of the client.
+     * @param siteId The site id of the client.
+     * @param locationId The location id on the site.
+     * @returns A recommended product.
+     */
+    generateTopProduct: (accountId: string, siteId: string, locationId: string) => AsyncGenerator<IProductInformation>;
+    /**
+     * @deprecated Use `generateForYou` instead
+     */
+    getForYou: (accountId: string, siteId: string, locationId: string, userId: string, count: number) => Promise<IRecommendedProduct[] | null>;
+    /**
+     * Generator function for the next existing product recommended for the given user.
+     * Returns when out of existing products.
+     * @param accountId The account id of the client.
+     * @param siteId The site id of the client.
+     * @param locationId The location id on the site.
+     * @param userId The user id.
+     * @returns A recommended product.
+     */
+    generateForYou: (accountId: string, siteId: string, locationId: string, userId: string) => AsyncGenerator<IProductInformation>;
+    /**
+     * @deprecated Use `generatePreviousPurchase` instead
+     */
+    getPreviousPurchases: (accountId: string, siteId: string, locationId: string, userId: string, count: number) => Promise<IRecommendedProduct[] | null>;
+    /**
+     * Generator function for the next existing product recommended based on the user's
+     * previous purchases. Returns when out of existing products.
+     * @param accountId The account id of the client.
+     * @param siteId The site id of the client.
+     * @param locationId The location id on the site.
+     * @param userId The user id.
+     * @returns A recommended product.
+     */
+    generatePreviousPurchase: (accountId: string, siteId: string, locationId: string, userId: string) => AsyncGenerator<IProductInformation>;
+}

package/lib/types/services/recommender/SurfsideRecommenderService.d.ts

@@ -0,0 +1,31 @@
+import type { IProductInformation, IRecommendedProduct } from '../../models';
+import type { ILoggerService, IProductFeedService, IRecommenderService } from '../../services';
+export declare class SurfsideRecommenderService implements IRecommenderService {
+    private readonly _productFeedService;
+    private readonly _logger?;
+    private readonly _cache;
+    private readonly _url;
+    constructor(url: string, _productFeedService: IProductFeedService, _logger?: ILoggerService | undefined);
+    /**
+     * @deprecated Use `generateTopProduct` instead
+     */
+    getTopProducts(accountId: string, siteId: string, locationId: string, count: number): Promise<IRecommendedProduct[] | null>;
+    generateTopProduct(accountId: string, siteId: string, locationId: string): AsyncGenerator<IProductInformation>;
+    /**
+     * @deprecated Use `generateForYou` instead.
+     */
+    getForYou(accountId: string, siteId: string, locationId: string, userId: string, count: number): Promise<IRecommendedProduct[] | null>;
+    generateForYou(accountId: string, siteId: string, locationId: string, userId: string): AsyncGenerator<IProductInformation>;
+    /**
+     * @deprecated Use `generatePreviousPurchase` instead.
+     */
+    getPreviousPurchases(accountId: string, siteId: string, locationId: string, userId: string, count: number): Promise<IRecommendedProduct[] | null>;
+    generatePreviousPurchase(accountId: string, siteId: string, locationId: string, userId: string): AsyncGenerator<IProductInformation>;
+    private _generateProductRecommendation;
+    private _fetchRecommendations;
+    /**
+     * Used for the generator methods; just returns a simple list of products instead of managing a cache
+     */
+    private _fetchRecommendationList;
+    private _generateProduct;
+}

package/lib/types/services/recommender/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IRecommenderService';
+export * from './SurfsideRecommenderService';

package/lib/types/services/rtb/bidder/IBidderService.d.ts

@@ -0,0 +1,12 @@
+import type { IBidRequest, IBidResponse } from '../../../models';
+/**
+ * The core service for sending bid requests and receiving bid responses.
+ */
+export interface IBidderService {
+    /**
+     * Sends a bid request to the bidder
+     * @param request an OpenRTB 2.6 bid request
+     * @returns a promise that resolves with the OpenRTB 2.6 bid response
+     */
+    requestBids: (request: IBidRequest) => Promise<IBidResponse>;
+}

package/lib/types/services/rtb/bidder/SurfsideBidderService.d.ts

@@ -0,0 +1,28 @@
+import type { IBidRequest, IBidResponse } from '../../../models';
+import type { IBidderService } from './IBidderService';
+import type { IConfigurationService, IDeviceService, IGeoService, ILoggerService, IUserIDService } from '../../../services';
+/**
+ * The surfside implementation of the IBidderService interface. Sends all request to
+ * the surfside bidder.
+ */
+export declare class SurfsideBidderService implements IBidderService {
+    private readonly _configService;
+    private readonly _geoService;
+    private readonly _deviceService;
+    private readonly _userService;
+    private readonly _logger?;
+    private readonly _url;
+    /**
+     * Creates a new instance of the SurfsideBidderService, sending requests to the specified URL
+     * @param _url The URL of the bidder API
+     * @param _logger An optional logger service, for debugging purposes
+     */
+    constructor(url: string, _configService: IConfigurationService, _geoService: IGeoService, _deviceService: IDeviceService, _userService: IUserIDService, _logger?: ILoggerService | undefined);
+    /**
+     * Sends a bid request to the bidder. If the bidder returns a status code other than 200,
+     * a NoBidResponseError is thrown with the status code and status text as the message.
+     * @param request The OpenRTB 2.6 bid request
+     * @returns A promise that resolves with the OpenRTB 2.6 bid response
+     */
+    requestBids(request: IBidRequest): Promise<IBidResponse>;
+}

package/lib/types/services/rtb/bidder/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IBidderService';
+export * from './SurfsideBidderService';

package/lib/types/services/rtb/configuration/IConfigurationService.d.ts

@@ -0,0 +1,14 @@
+import type { ICompiledPublisherConfiguration } from '../../../models';
+/**
+ * The configuration service interface. account and site IDs come from the creative component attributes.
+ * Publisher configurations have flags for features on the site, and templates for rendering commerce media creatives.
+ */
+export interface IConfigurationService {
+    /**
+     * Gets the configuration for the given account and site IDs
+     * @param accountId The account ID of the component making the request
+     * @param siteId The site ID of the component making the request
+     * @returns The configuration for the account and site IDs, or null if no configuration is found
+     */
+    getConfiguration: (accountId: string, siteId: string) => Promise<ICompiledPublisherConfiguration | null>;
+}

package/lib/types/services/rtb/configuration/SurfsideConfigurationService.d.ts

@@ -0,0 +1,29 @@
+import type { ICompiledPublisherConfiguration } from '../../../models';
+import type { ILoggerService } from '../../../services';
+import type { IConfigurationService } from './IConfigurationService';
+/**
+ * The Surfside Configuration Service fetches the configuration for a given account and site.
+ */
+export declare class SurfsideConfigurationService implements IConfigurationService {
+    private readonly _handlebars;
+    private readonly _logger?;
+    private readonly _url;
+    /**
+     * Creates a new instance of the Surfside Configuration Service with the specified URL and Handlebars instance.
+     * Handlebars is used to parse the clickthrough URL templates and product card templates for the configuration.
+     * It is a peer dependency, so you will need to add handlebars to your project.
+     * @param _url The URL of the configuration service
+     * @param _handlebars The Handlebars instance to use for parsing templates. Created with `Handlebars.create()`
+     * @param _logger An optional logger service, for debugging purposes
+     */
+    constructor(url: string, _handlebars: typeof Handlebars, _logger?: ILoggerService | undefined);
+    /**
+     * Fetches the configuration for the specified account and site.
+     * @param accountId The account ID of the client
+     * @param siteId The site ID of the client
+     * @returns A promise that resolves with the compiled configuration, or null if the fetch fails
+     */
+    getConfiguration(accountId: string, siteId: string): Promise<ICompiledPublisherConfiguration | null>;
+    private _mapConfig;
+    private _importModule;
+}

package/lib/types/services/rtb/configuration/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IConfigurationService';
+export * from './SurfsideConfigurationService';

package/lib/types/services/rtb/index.d.ts

@@ -0,0 +1,2 @@
+export * from './bidder';
+export * from './configuration';

package/lib/types/services/tracking/device/DeviceOverrideService.d.ts

@@ -0,0 +1,8 @@
+import { OverrideService } from '../../../services/OverrideService';
+import type { IDevice } from '../../../models';
+import { type IDeviceService, type ILoggerService } from '../../../services';
+export declare class DeviceOverrideService extends OverrideService<IDevice> implements IDeviceService {
+    constructor(logger?: ILoggerService);
+    getDeviceInfo(): Promise<IDevice | null>;
+    mapDataSetToData(dataset: DOMStringMap): IDevice | null;
+}

package/lib/types/services/tracking/device/IDeviceService.d.ts

@@ -0,0 +1,4 @@
+import type { IDevice } from '../../../models';
+export interface IDeviceService {
+    getDeviceInfo: () => Promise<IDevice | null>;
+}

package/lib/types/services/tracking/device/SurfsideDeviceService.d.ts

@@ -0,0 +1,16 @@
+import type { ILoggerService } from '../../logger';
+import { DeviceOverrideService } from './DeviceOverrideService';
+import { type IBrandVersion, type IDevice } from '../../../models';
+interface IDeviceContext {
+    make?: string;
+    model?: string;
+    os?: string;
+    osv?: string;
+    browser?: IBrandVersion;
+}
+export declare class SurfsideDeviceService extends DeviceOverrideService {
+    constructor(logger?: ILoggerService);
+    getDeviceInfo(): Promise<IDevice | null>;
+}
+export declare function TryGetDeviceInfo(): IDeviceContext | null;
+export {};

package/lib/types/services/tracking/device/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IDeviceService';
+export * from './DeviceOverrideService';
+export * from './SurfsideDeviceService';

package/lib/types/services/tracking/events/IEventService.d.ts

@@ -0,0 +1,5 @@
+import type { IBidRequest, IBidResponse } from '../../../models';
+export interface IEventService {
+    raiseBidRequested: (request: IBidRequest) => Promise<void>;
+    raiseBidResponded: (response: IBidResponse, request: IBidRequest) => Promise<void>;
+}

package/lib/types/services/tracking/events/SurfsideEventService.d.ts

@@ -0,0 +1,42 @@
+import type { IBidRequest, IBidResponse } from '../../../models';
+import type { IEventService, ILoggerService } from '../../../services';
+interface ISurfTrackerOptions {
+    appId: string;
+    cookieName: string;
+    collectorUrl: string;
+    discoverRootDomain: boolean;
+    cookieSameSite: string;
+}
+type SurfTrack = (action: string, ...args: any[]) => void;
+interface ISurfTracker extends SurfTrack {
+    q?: any[];
+}
+declare global {
+    interface Window {
+        surf: ISurfTracker;
+        surfContext: any[];
+    }
+}
+export interface ISurfsideEventServiceLazyLoadConfig extends Partial<ISurfTrackerOptions> {
+    lazyLoad: true;
+    src: string;
+}
+export interface ISurfsideEventServiceDefaultConfig extends Partial<ISurfTrackerOptions> {
+    lazyLoad: false;
+}
+/**
+ * The surfside event service. This service is responsible for tracking events. It converts
+ * bid requests and responses to legacy snowplow/prebidJS style events and sends them to the
+ * surfside tracker.
+ */
+export declare class SurfsideEventService implements IEventService {
+    private readonly _logger?;
+    private _surf;
+    private readonly _appId;
+    private readonly _collectorUrl;
+    private readonly _src?;
+    constructor(config?: ISurfsideEventServiceLazyLoadConfig | ISurfsideEventServiceDefaultConfig, _logger?: ILoggerService | undefined);
+    raiseBidRequested(request: IBidRequest): Promise<void>;
+    raiseBidResponded(response: IBidResponse, request: IBidRequest): Promise<void>;
+}
+export {};

package/lib/types/services/tracking/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IEventService';
+export * from './SurfsideEventService';

package/lib/types/services/tracking/geo/GeoOverrideService.d.ts

@@ -0,0 +1,8 @@
+import { OverrideService } from '../../../services/OverrideService';
+import type { IGeoContext } from '../../../models';
+import { type IGeoService, type ILoggerService } from '../../../services';
+export declare class GeoOverrideService extends OverrideService<IGeoContext> implements IGeoService {
+    constructor(logger?: ILoggerService);
+    mapDataSetToData(dataset: DOMStringMap): IGeoContext | null;
+    getGeo(): Promise<IGeoContext | null>;
+}

package/lib/types/services/tracking/geo/IGeoService.d.ts

@@ -0,0 +1,12 @@
+import type { IGeoContext } from '../../../models';
+/**
+ * The geo service interface. Returns the geo context for the user, as well as the IP address of the user.
+ * This is useful for targeting ads based on the user's location, and is added to the "device" object in the bid request
+ */
+export interface IGeoService {
+    /**
+     * Gets the geo context for the user, including the user's location and IP address
+     * @returns The geo context, or null if the geo context could not be retrieved
+     */
+    getGeo: () => Promise<IGeoContext | null>;
+}

package/lib/types/services/tracking/geo/SurfsideGeoService.d.ts

@@ -0,0 +1,7 @@
+import type { IGeoContext } from '../../../models';
+import type { ILoggerService } from '../../../services';
+import { GeoOverrideService } from './GeoOverrideService';
+export declare class SurfsideGeoService extends GeoOverrideService {
+    constructor(logger?: ILoggerService);
+    getGeo(): Promise<IGeoContext | null>;
+}

package/lib/types/services/tracking/geo/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IGeoService';
+export * from './SurfsideGeoService';
+export * from './GeoOverrideService';

package/lib/types/services/tracking/index.d.ts

@@ -0,0 +1,4 @@
+export * from './geo';
+export * from './user';
+export * from './events';
+export * from './device';

package/lib/types/services/tracking/user/IUserIDService.d.ts

@@ -0,0 +1,4 @@
+import type { IUserID } from '../../../models';
+export interface IUserIDService {
+    getUserId: () => Promise<IUserID | null>;
+}

package/lib/types/services/tracking/user/SurfsideUserIDService.d.ts

@@ -0,0 +1,7 @@
+import type { IUserID } from '../../../models';
+import type { ILoggerService } from '../../../services';
+import { UserOverrideService } from './UserOverrideService';
+export declare class SurfsideUserIDService extends UserOverrideService {
+    constructor(logger?: ILoggerService);
+    getUserId(): Promise<IUserID | null>;
+}

package/lib/types/services/tracking/user/UserOverrideService.d.ts

@@ -0,0 +1,8 @@
+import { OverrideService } from '../../../services/OverrideService';
+import type { IUserID } from '../../../models';
+import { type ILoggerService, type IUserIDService } from '../../../services';
+export declare class UserOverrideService extends OverrideService<IUserID> implements IUserIDService {
+    constructor(logger?: ILoggerService);
+    getUserId(): Promise<IUserID | null>;
+    mapDataSetToData(dataset: DOMStringMap): string | null;
+}

package/lib/types/services/tracking/user/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IUserIDService';
+export * from './SurfsideUserIDService';
+export * from './UserOverrideService';

package/lib/types/utils/Protocol.d.ts

@@ -0,0 +1 @@
+export declare function GetSafeUrl(relativeUrl: string): string;

package/lib/types/utils/Rendering.d.ts

@@ -0,0 +1,44 @@
+import type { ICompiledPublisherConfiguration, INativeTemplateDelegateWindow, IProductContext, IProductInformation, IPublisherConfiguration } from '../models';
+import type Handlebars from 'handlebars/runtime';
+import type { ILoggerService } from '../services';
+export interface INativeTemplateDelegateData {
+    product: Partial<IProductInformation>;
+    window: INativeTemplateDelegateWindow;
+    publisher: IPublisherConfiguration;
+    catalog: IProductInformation;
+    ext: any;
+}
+export type NativeTemplateDelegate = Handlebars.TemplateDelegate<INativeTemplateDelegateData>;
+export type EventHandler = (e: Event) => (void | Promise<void>);
+export interface IEventHandleCallbackList {
+    click: EventHandler;
+    mousedown: EventHandler;
+    loadeddata: EventHandler;
+    error: EventHandler;
+    touchend: EventHandler;
+    touchstart: EventHandler;
+    touchmove: EventHandler;
+}
+/**
+ * Initializes Handlebars with all custom helpers
+ *
+ * @param logger The logger service for debug messages
+ */
+export declare function initHandlebars(handlebars: typeof Handlebars, logger?: ILoggerService): void;
+/**
+ * Returns a NativeTemplateDelegateWindow object with the current window location properties
+ *
+ * @returns A NativeTemplateDelegateWindow object with the current window location properties
+ */
+export declare function getNativeTemplateDelegateWindow(): INativeTemplateDelegateWindow;
+/**
+ * Renders a URL template using the provided delegate, native slot, and publisher configuration.
+ * Gets the window location properties from the current window.
+ *
+ * @param delegate The Handlebars delegate function to render the template
+ * @param productInformation The native slot object to render
+ * @param publisherConfiguration The publisher configuration object to render
+ * @returns The rendered URL template
+ */
+export declare function RenderTemplate(delegate: HandlebarsTemplateDelegate<IProductContext>, productInformation: IProductInformation | undefined, publisherConfiguration: ICompiledPublisherConfiguration, clickthrough?: string, catalogProduct?: IProductInformation): Element;
+export declare function RenderAndBind<T>(template: HandlebarsTemplateDelegate<T>, t: T & Partial<IEventHandleCallbackList>): Element;

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

@@ -0,0 +1,2 @@
+export * from './Protocol';
+export * from './Rendering';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@surfside/ads-core",
+  "version": "1.0.6",
+  "description": "My webpack project",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "author": "Collin Oswalt, Ranveer Dhaliwal",
+  "license": "UNLICENSED",
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "peerdependencies": {
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin-ts": "^1.5.4",
+    "@types/handlebars": "^4.1.0",
+    "@typescript-eslint/eslint-plugin": "^6.20.0",
+    "@webpack-cli/generators": "^3.0.7",
+    "eslint": "^8.56.0",
+    "eslint-config-standard-with-typescript": "^43.0.1",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-promise": "^6.1.1",
+    "prettier": "^3.3.3",
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.6.2",
+    "webpack": "^5.95.0",
+    "webpack-bundle-analyzer": "^4.10.2",
+    "webpack-cli": "^6.0.1"
+  },
+  "scripts": {
+    "lint": "npx eslint -c ./.eslintrc.json src/**/*.ts",
+    "build:mock": "npx webpack --mode=development --node-env=development",
+    "build:local": "npx webpack --mode=development --node-env=development",
+    "build:staging": "npx webpack --mode=production --node-env=development",
+    "build:prod": "npx webpack --mode=production --node-env=production",
+    "watch": "npx webpack --watch",
+    "serve": ";",
+    "serve:mock": ";",
+    "serve:local": ";",
+    "serve:staging": ";",
+    "serve:prod": ";",
+    "test": "echo test"
+  }
+}