@surfside/ads-core 2.0.1

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

@@ -0,0 +1,26 @@
+import { NativeRequestBuilderFn, RequestBuilder, RequestBuilderFn } from '../helpers';
+import { IBidRequest, ICompiledPublisherConfiguration } from '../models';
+import { DynamicCreative, IDynamicZone, IScreenSize } from '../models/dynamic/DynamicZone';
+import { IScreen } from './Device';
+import { ILogger } from './Logger';
+import { AsyncResult, Result } from './Result';
+export interface IDynamicZoneRequest {
+    request: IBidRequest;
+    requestIds: Record<string, DynamicCreative>;
+}
+export type BuildDynamicZoneRequestFn = (zoneId: string, dynamicZone: IDynamicZone) => 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 BuildDynamicZoneRequest: (logger: ILogger | undefined, startRequest: RequestBuilderFn, nativeRequest: NativeRequestBuilderFn, screenInfo: IScreen, zoneId: string, dynamicZone: IDynamicZone) => Result<IDynamicZoneRequest>;
+export declare class NoDynamicScreenSizeMatchError extends Error {
+    readonly dynamicZone: IDynamicZone;
+    readonly screenInfo: IScreen;
+    readonly selectedStringSize: string;
+    constructor(dynamicZone: IDynamicZone, screenInfo: IScreen, selectedStringSize: string);
+}
+export declare const buildDynamicBidRequestFromSelectedScreenSize: (logger: ILogger | undefined, startRequest: RequestBuilderFn, nativeRequest: NativeRequestBuilderFn, zoneId: string, screenSize: IScreenSize) => 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 class MissingDynamicZoneError extends Error {
+    readonly zoneId: string;
+    constructor(zoneId: string);
+}

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

@@ -0,0 +1,6 @@
+import type { IGeo, IGeoContext } from '../models';
+import { type ILogger } from './Logger';
+import { type AsyncResult } from './Result';
+export type GetGeoFn = (ip?: string, geoProviderToken?: string) => AsyncResult<IGeoContext>;
+export declare const GetGeo: (logger?: ILogger, apiToken?: string, ip?: string) => AsyncResult<IGeoContext>;
+export declare const GeoContextToORTB: (logger: ILogger | undefined, geoContext: IGeoContext) => IGeo;

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

@@ -0,0 +1,14 @@
+export type LoggerFn = (...args: any[]) => void;
+export type ContextFn = (...prefix: (string | undefined)[]) => IContextLogger;
+export interface ILogger {
+    info: LoggerFn;
+    debug: LoggerFn;
+    warn: LoggerFn;
+    error: LoggerFn;
+    table: (data: any, properties?: string[]) => void;
+}
+export interface IContextLogger extends ILogger {
+    with: ContextFn;
+}
+export declare const InitLogger: () => IContextLogger;
+export declare const Ctx: (logger: ILogger | undefined) => IContextLogger | undefined;

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

@@ -0,0 +1 @@
+export declare const Memo: <T extends any[], R>(fn: (...args: T) => R) => (...args: T) => R;

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

@@ -0,0 +1,10 @@
+import type { ILoggerService } from './logger';
+export declare abstract class OverrideService<T> {
+    private readonly _selector;
+    protected readonly logger?: ILoggerService | undefined;
+    protected overrideData: T | null;
+    protected overrideNode: HTMLElement | null;
+    constructor(_selector: string, logger?: ILoggerService | undefined);
+    protected getOverrideNode(): HTMLElement | null;
+    abstract mapDataSetToData(dataset: DOMStringMap): T | null;
+}

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

@@ -0,0 +1,13 @@
+import type { IProductInformation } from '../models';
+import { type ILogger } from './Logger';
+import { Result, type AsyncResult } from './Result';
+export type GetSponsoredProductFromNativeIdFn = (nativeId: string) => AsyncGenerator<IProductInformation>;
+export type GetAllSponsoredProductFromNativeIdFn = (nativeId: string) => Promise<Result<IProductInformation[]>>;
+export type GetRecommendedProductFromProductIdFn = (productId: string) => AsyncResult<IProductInformation>;
+export declare function GetSponsoredProduct(logger: ILogger | undefined, url: string, accountId: string, locationId: string, nativeId: string): AsyncGenerator<IProductInformation>;
+export declare const GetAllSponsoredProducts: (logger: ILogger | undefined, url: string, accountId: string, locationId: string, nativeId: string) => Promise<Result<IProductInformation[]>>;
+export declare const GetRecommendedProduct: (logger: ILogger | undefined, url: string, accountId: string, locationId: string, productId: string) => AsyncResult<IProductInformation>;
+export declare class NoNativeError extends Error {
+    nativeId: string;
+    constructor(nativeId: string);
+}

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

@@ -0,0 +1,8 @@
+import type { IProductInformation } from '../models';
+import { type ILogger } from './Logger';
+import type { GetRecommendedProductFromProductIdFn } from './Product';
+export type NonPersonalRecommenderFn = () => AsyncGenerator<IProductInformation>;
+export type PersonalRecommenderFn = (userId: string) => AsyncGenerator<IProductInformation>;
+export declare function GenerateTopProducts(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string): AsyncGenerator<IProductInformation>;
+export declare function GenerateForYou(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string): AsyncGenerator<IProductInformation>;
+export declare function GeneratePreviousPurchases(logger: ILogger | undefined, productFeed: GetRecommendedProductFromProductIdFn, url: string, accountId: string, siteId: string, locationId: string, userId: string): AsyncGenerator<IProductInformation>;

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

@@ -0,0 +1,57 @@
+export type OkResult<T> = {
+    ok: true;
+    value: T;
+};
+export type ErrResult<E = Error> = {
+    ok: false;
+    error: E;
+};
+export type Result<T, E = Error> = OkResult<T> | ErrResult<E>;
+export type AsyncResult<T, E = Error> = Promise<Result<T, E>>;
+export declare const Ok: <T>(t: T) => OkResult<T>;
+export declare const Err: <E = Error>(e: E) => ErrResult<E>;
+export declare const TryDo: <T, E = Error>(fn: () => T) => Result<T, E>;
+export declare const TryDoFlat: <T, E = Error>(fn: () => Result<T, E>) => Result<T, E>;
+export declare const TryDoAsync: <T, E = Error>(fn: () => Promise<T>) => AsyncResult<T, E>;
+export declare const GetValue: <T, E = Error>(result: Result<T, E> | undefined) => T | 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>) => T;
+export declare const WrapValue: <T>(value: T | undefined | null) => Result<T>;
+export declare const AssertValue: <T>(result: Result<T, Error>) => T;
+export declare const AllOrNone: <T>(results: Result<T, Error>[]) => Result<T[]>;
+export declare const Some: <T>(results: Result<T, Error>[]) => OkResult<T[]>;
+export declare const Filter: <T>(...results: Result<T, Error>[]) => [OkResult<T>[], ErrResult[]];
+export declare const AnyFailed: (...results: Result<any, Error>[]) => [true, Error[]] | [false];
+export declare class MultipleErrorsError extends Error {
+    readonly errors: Error[];
+    constructor(errors: Error[]);
+}
+export interface IResultPipe<T, E = Error> {
+    then: <U>(fn: (t: T) => U) => IResultPipe<U, E>;
+    result: () => Result<T, E>;
+    value: () => T | undefined;
+    valueOr: <U>(or: U) => T | U;
+    valueOrThrow: () => T;
+}
+export declare const Pipe: <T, E = Error>(result: Result<T, E>) => IResultPipe<T, E>;
+export interface IAsyncResultPipe<T, E = Error> {
+    then: <U>(fn: (t: T) => AsyncResult<U> | Result<U>) => IAsyncResultPipe<U, E>;
+    result: () => AsyncResult<T, E>;
+    value: () => Promise<T | undefined>;
+    valueOr: <U>(or: U) => Promise<T | U>;
+    valueOrThrow: () => Promise<T>;
+}
+export declare const AsyncPipe: <T, E>(result: AsyncResult<T, E>) => IAsyncResultPipe<T, E>;
+export type IResultStream<T, E = Error> = {
+    map: <U>(fn: (t: T) => U) => IResultStream<U, E>;
+    filter: (fn: (t: T) => boolean) => IResultStream<T, E>;
+    results: () => Result<T[], E>;
+    value: () => T[] | undefined;
+    valueOr: <U>(u: U) => T[] | U;
+    valueOrThrow: () => T[];
+};
+export declare const ResultStream: <T, E = Error>(results: Result<T[], E>) => IResultStream<T, E>;
+export declare class NoValueError extends Error {
+    readonly value: undefined | null;
+    constructor(value: undefined | null);
+}

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

@@ -0,0 +1,7 @@
+import { ICompiledPublisherConfiguration, INativeTemplateDelegateWindow, IProductInformation } from '../models';
+import { ILogger } from './Logger';
+import { Result } from './Result';
+export type EvaluateProductCardTemplateFn = (product: IProductInformation, clickthrough?: string) => Result<string>;
+export type EvaluateClickthroughTemplateFn = (product: IProductInformation) => Result<string>;
+export declare const EvaluateHandlebarsProductCardTemplate: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, publisher: ICompiledPublisherConfiguration, product: IProductInformation, clickthrough?: string) => Result<string>;
+export declare const EvaluateHandlebarsClickthroughTemplate: (logger: ILogger | undefined, windowInfo: INativeTemplateDelegateWindow, publisher: ICompiledPublisherConfiguration, product: IProductInformation) => Result<string>;

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

@@ -0,0 +1,11 @@
+export * from './Geo';
+export * from './Logger';
+export * from './Result';
+export * from './Device';
+export * from './Configuration';
+export * from './Bidder';
+export * from './Product';
+export * from './Recommender';
+export * from './mock';
+export * from './Template';
+export * from './Dynamic';

package/lib/types/services/logger/ILoggerService.d.ts

@@ -0,0 +1,39 @@
+export declare enum LogLevel {
+    NONE = 0,
+    ERRORS = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+/**
+ * Interface for a logger service
+ */
+export interface ILoggerService {
+    /**
+     * Prints info. This is useful for tracking the lifecycle of a bid request
+     *
+     * @param args The arguments to print
+     */
+    info: (...args: any[]) => void;
+    /**
+     * Prints a warning. This is useful for tracking potential issues, but not critical errors. Warnings should not
+     * prevent the bidding process from continuing, but may disable certain features such as commerce media or certain
+     * types of targeting
+     *
+     * @param args
+     */
+    warn: (...args: any[]) => void;
+    /**
+     * Prints an error. This is useful for tracking critical errors. Printing an error should indicate that the bidding
+     * process can go no further.
+     *
+     * @param args The arguments to print
+     */
+    error: (...args: any[]) => void;
+    /**
+     * Spammy messages. This is useful for tracking the lifecycle of a bid request and debugging issues with special
+     * flags enabled. When there is an issue on the client side, enabling debug logs will help the developer understand
+     * where the issue is in the code and potentially what the issue is. These should be added to every function.
+     * @param args The arguments to print
+     */
+    debug: (...args: any[]) => void;
+}

package/lib/types/services/logger/LocalLoggerService.d.ts

@@ -0,0 +1,19 @@
+import { type ILoggerService, LogLevel } from '../../services';
+/**
+ * Logger service which adds some color to the console logs
+ */
+export declare class LocalLoggerService implements ILoggerService {
+    private readonly _logLevel;
+    constructor(_logLevel: LogLevel);
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    /**
+     * Shows a log message with [SURF] prepended and colored
+     * @param log The console log function to use (e.g: console.log, console.error, etc.)
+     * @param args The actual log message
+     * @param color The color to use for the log message
+     */
+    private _log;
+}

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

@@ -0,0 +1,2 @@
+export * from './ILoggerService';
+export * from './LocalLoggerService';

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export * from './Bidder';

package/lib/types/services/product-feed/IProductFeedService.d.ts

@@ -0,0 +1,5 @@
+import type { IProductInformation } from '../../models';
+export interface IProductFeedService {
+    getProduct: (accountId: string, siteId: string, locationId: string, productId: string) => Promise<IProductInformation | null>;
+    getNativeProduct: (accountId: string, siteId: string, locationId: string, productId: string) => Promise<IProductInformation | null>;
+}

package/lib/types/services/product-feed/SurfsideProductFeedService.d.ts

@@ -0,0 +1,11 @@
+import type { IProductInformation } from '../../models';
+import type { ILoggerService, IProductFeedService } from '../../services';
+export declare class SurfsideProductFeedService implements IProductFeedService {
+    private readonly _logger?;
+    private readonly _url;
+    constructor(url: string, _logger?: ILoggerService | undefined);
+    getProduct(accountId: string, siteId: string, locationId: string, productId: string): Promise<IProductInformation | null>;
+    getNativeProduct(accountId: string, siteId: string | undefined, locationId: string, productId: string): Promise<IProductInformation | null>;
+    private _mapResponseToProductInformation;
+    private _getFieldOrNull;
+}

package/lib/types/services/product-feed/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IProductFeedService';
+export * from './SurfsideProductFeedService';

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;