@surfside/ads-core 1.0.6

package/lib/types/models/rtb/native/INativeRequest.d.ts

@@ -0,0 +1,54 @@
+import type { ContextSubTypes, ContextTypes, EventTrackingMethods, EventTypes, NativeDataTypes, PlacementTypes, VideoMimes } from './NativeConstants';
+export interface INativeRequest {
+    ver?: string;
+    context?: ContextTypes;
+    contextsubtype?: ContextSubTypes;
+    plcmttype?: PlacementTypes;
+    plcmtcnt?: number;
+    seq?: number;
+    assets: IAssetObject[];
+    aurlsupport?: number;
+    durlsupport?: number;
+    eventtrackers?: IEventTrackerRequestObject[];
+    privacy?: number;
+    ext?: any;
+}
+export interface IAssetObject {
+    id: number;
+    required?: number;
+    title?: ITitleRequestObject;
+    img?: IImageRequestObject;
+    video?: IVideoRequestObject;
+    data?: IDataRequestObject;
+    ext?: any;
+}
+export interface ITitleRequestObject {
+    len: number;
+    ext?: any;
+}
+export interface IImageRequestObject {
+    type?: number;
+    w?: number;
+    wmin?: number;
+    h?: number;
+    hmin?: number;
+    mimes?: string[];
+    ext?: any;
+}
+export interface IVideoRequestObject {
+    mimes: VideoMimes[] | string[];
+    minduration: number;
+    maxduration: number;
+    protocols: number[];
+    ext?: any;
+}
+export interface IDataRequestObject {
+    type: NativeDataTypes;
+    len?: number;
+    ext?: any;
+}
+export interface IEventTrackerRequestObject {
+    event: EventTypes;
+    methods: EventTrackingMethods[];
+    ext?: any;
+}

package/lib/types/models/rtb/native/INativeResponse.d.ts

@@ -0,0 +1,60 @@
+import { type EventTrackingMethods, type IProductInformation, type NativeDataTypes, NativeImageTypes, EventTypes } from '../../../models';
+export interface INativeResponse {
+    native: INativeResponseDetails;
+}
+export interface INativeResponseDetails {
+    ver?: string;
+    assets?: IAssetResponseObject[];
+    assetsurl?: string;
+    dcourl?: string;
+    link: ILinkResponseObject;
+    imptrackers?: string[];
+    jstracker?: string;
+    eventtrackers?: IEventTrackerResponseObject[];
+    privacy?: string;
+    ext?: any;
+}
+export interface IAssetResponseObject {
+    id?: number;
+    required?: number;
+    title?: ITitleResponseObject;
+    img?: IImageResponseObject;
+    data?: IDataResponseObject;
+    video?: IVideoResponseObject;
+    link?: ILinkResponseObject;
+    ext?: any;
+}
+export interface ITitleResponseObject {
+    text: string;
+    len?: number;
+    ext?: any;
+}
+export interface IImageResponseObject {
+    type: NativeImageTypes;
+    url: string;
+    w?: number;
+    h?: number;
+    ext?: any;
+}
+export interface IDataResponseObject {
+    type?: NativeDataTypes;
+    value: string;
+    ext?: any;
+}
+export interface IVideoResponseObject {
+    vasttag: string;
+}
+export interface ILinkResponseObject {
+    url: string;
+    clicktrackers?: string[];
+    fallback?: string;
+    ext?: any;
+}
+export interface IEventTrackerResponseObject {
+    event: EventTypes;
+    method: EventTrackingMethods;
+    url?: string;
+    customdata?: any;
+    ext?: any;
+}
+export declare function NativeResponseToProductInformation(native: INativeResponse): IProductInformation;

package/lib/types/models/rtb/native/NativeConstants.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The position of the native ad, on the screen
+ */
+export declare enum NativePosition {
+    UNKNOWN = 0,
+    ABOVE_THE_FOLD = 1,
+    BELOW_THE_FOLD = 3,
+    HEADER = 4,
+    FOOTER = 5,
+    SIDEBAR = 6,
+    FULL_SCREN = 7
+}
+/**
+ * The type of the image within native ad (icon vs main image)
+ */
+export declare enum NativeImageTypes {
+    ICON = 1,
+    MAIN = 3
+}
+/**
+ * The type ID for each native asset type. IDs above 500 are surfside-specific fields, all
+ * others are OpenRTB Native Ad Spec 1.2 fields.
+ */
+export declare enum NativeDataTypes {
+    SPONSORED = 1,
+    DESC = 2,
+    RATING = 3,
+    LIKES = 4,
+    DOWNLOADS = 5,
+    PRICE = 6,
+    SALEPRICE = 7,
+    PHONE = 8,
+    ADDRESS = 9,
+    DESC2 = 10,
+    DISPLAYURL = 11,
+    CTATEXT = 12,
+    SURF_STRAIN = 500,
+    SURF_THC = 501,
+    SURF_CBD = 502,
+    SURF_CATEGORY = 503,
+    SURF_META_PRODUCT = 599
+}
+/**
+ * The ID for each field within a surfside native ad request. The Asset ID matches the asset type, for simplicity.
+ */
+export declare enum NativeAssetId {
+    TITLE = 0,
+    IMAGE = 1,
+    SPONSORED = 2,
+    DESC = 3,
+    RATING = 4,
+    PRICE = 5,
+    SALEPRICE = 6,
+    DISPLAYURL = 7,
+    CTATEXT = 8,
+    SURF_STRAIN = 500,
+    SURF_THC = 501,
+    SURF_CBD = 502,
+    SURF_CATEGORY = 503,
+    SURF_META_PRODUCT = 599
+}
+/**
+ * Event types which can be tracked by the native ad unit
+ */
+export declare enum EventTypes {
+    IMP = 1,
+    VIEWABLE_MRC50 = 2,
+    VIEWABLE_MRC100 = 3,
+    VIEWABLE_VIDEO50 = 4,
+    SURF_WIN = 500,
+    SURF_CLICK = 501
+}
+/**
+ * The context of the page for the native ad unit, i.e what type of content is being displayed
+ */
+export declare enum ContextTypes {
+    CONTENT = 1,
+    SOCIAL = 2,
+    PRODUCT = 3
+}
+/**
+ * The sub-type of the context
+ */
+export declare enum ContextSubTypes {
+    GENERAL = 10,
+    ARTICLE = 11,
+    VIDEO = 12,
+    AUDIO = 13,
+    IMAGE = 14,
+    USER_GENERATED = 15,
+    GENERAL_SOCIAL = 20,
+    EMAIL = 21,
+    CHAT = 22,
+    PRODUCT = 30,
+    APPLICATION = 31,
+    PRODUCT_REVIEWS = 32
+}
+/**
+ * The format of the ad unit, i.e: what type of ad is being displayed and where
+ */
+export declare enum PlacementTypes {
+    IN_FEED = 1,
+    ATOMIC = 2,
+    OUTSIDE_CORE = 3,
+    RECOMMENDATION = 4
+}
+/**
+ * Presets for default video MIME types
+ */
+export declare enum VideoMimes {
+    MP4 = "video/mp4",
+    WEBM = "video/webm"
+}
+/**
+ * The method used to track events, 1x1 pixel of Javascript tag
+ */
+export declare enum EventTrackingMethods {
+    IMG = 1,
+    JS = 2
+}

package/lib/types/models/rtb/native/NativeRequestBuilder.d.ts

@@ -0,0 +1,158 @@
+import { EventTrackingMethods, EventTypes, NativeAssetId, NativeDataTypes, type VideoMimes } from '../../../models';
+import type { INativeRequest } from './INativeRequest';
+/**
+ * Builder for creating an OpenRTB Native 1.2 request object.
+ */
+export declare class NativeRequestBuilder {
+    private readonly _request;
+    /**
+     * Creates a new NativeRequestBuilder instance, using version 1.2 and product type context.
+     */
+    constructor();
+    /**
+     * Overrides the 1.2 version with the provided version.
+     * @param ver The version to use
+     * @returns The builder instance
+     */
+    withVer(ver: string): this;
+    /**
+     * Overrides the native request context type with the provided context.
+     * @param context The context to use
+     * @returns The builder instance
+     */
+    withContext(context: number): this;
+    /**
+     * Adds a title asset to the request.
+     * @param length The lenght of the title, default is 80
+     * @param required Whether the title is required, default is true
+     * @returns The builder instance
+     */
+    withTitle(length?: number, required?: boolean): this;
+    /**
+     * Adds an image asset to the request.
+     * @param width The full width of the image. If minWidth is not provided, this is the exact width.
+     *              Otherwise, it is the max width
+     * @param height The full height of the image. If minHeight is not provided, this is the exact height.
+     *              Otherwise, it is the max height
+     * @param minWidth The minimum width of the image. undefined by default
+     * @param minHeight The minimum height of the image. undefined by default
+     * @param required Whether the image is required, default is true
+     * @returns
+     */
+    withImage(width: number, height: number, minWidth?: number, minHeight?: number, required?: boolean): this;
+    /**
+     * Adds a video asset to the request.
+     * @param mimes The supported MIME types for the video
+     * @param minDuration The minimum duration of the video
+     * @param maxDuration The maximum duration of the video
+     * @param required Whether the video is required, default is true
+     * @returns The builder instance
+     */
+    withVideo(mimes: VideoMimes[] | string[], minDuration: number, maxDuration: number, required?: boolean): this;
+    /**
+     * Adds a data asset to the request.
+     * @param type The type ID of the data asset
+     * @param id The ID of the asset field; This number is used to address the asset
+    *            in the response so it must be unique
+     * @param length The max length of the data asset's value, in characters
+     * @param required Whether the data asset is required, default is true
+     * @returns The builder instance
+     */
+    withData(type: NativeDataTypes, id: NativeAssetId, length?: number, required?: boolean): this;
+    /**
+     * Adds a sponsored field to the request.
+     * @param length The max length of the sponsored field, in characters. Default is 80
+     * @param required Whether the sponsored field is required. Default is true
+     * @returns The builder instance
+     */
+    withSponsored(length?: number, required?: boolean): this;
+    /**
+     * Adds a description field to the request.
+     * @param length The max length of the description field, in characters. Default is 80
+     * @param required Whether the description field is required. Default is true
+     * @returns The builder instance
+     */
+    withDescription(length?: number, required?: boolean): this;
+    /**
+     * Adds a rating field to the request.
+     * @param length The max length of the rating field, in characters. Default is 80
+     * @param required Whether the rating field is required. Default is true
+     * @returns The builder instance
+     */
+    withRating(length?: number, required?: boolean): this;
+    /**
+     * Adds a price field to the request.
+     * @param length The max length of the price field, in characters. Default is 80
+     * @param required Whether the price field is required. Default is true
+     * @returns The builder instance
+     */
+    withPrice(length?: number, required?: boolean): this;
+    /**
+     * Adds a sale price field to the request.
+     * @param length The max length of the sale price field, in characters. Default is 80
+     * @param required Whether the sale price field is required. Default is true
+     * @returns The builder instance
+     */
+    withSalePrice(length?: number, required?: boolean): this;
+    /**
+     * Adds a display URL field to the request.
+     * @param length The max length of the display URL field, in characters. Default is 80
+     * @param required Whether the display URL field is required. Default is true
+     * @returns The builder instance
+     */
+    withDisplayUrl(length?: number, required?: boolean): this;
+    /**
+     * Adds a CTA (call to action) text field to the request.
+     * @param length The max length of the call to action text field, in characters. Default is 80
+     * @param required Whether the call to action text field is required. Default is true
+     * @returns The builder instance
+     */
+    withCtaText(length?: number, required?: boolean): this;
+    /**
+     * Adds a category field to the request.
+     * @param length The max length of the category field, in characters. Default is 80
+     * @param required Whether the category field is required. Default is true
+     * @returns The builder instance
+     */
+    withCategory(length?: number, required?: boolean): this;
+    /**
+     * Adds a THC field to the request.
+     * @param length The max length of the THC field, in characters. Default is 80
+     * @param required Whether the THC field is required. Default is true
+     * @returns The builder instance
+     */
+    withTHC(length?: number, required?: boolean): this;
+    /**
+     * Adds a CBD field to the request.
+     * @param length The max length of the CBD field, in characters. Default is 80
+     * @param required Whether the CBD field is required. Default is true
+     * @returns The builder instance
+     */
+    withCBD(length?: number, required?: boolean): this;
+    /**
+     * Adds a strain field to the request.
+     * @param length The max length of the strain field, in characters. Default is 80
+     * @param required Whether the strain field is required. Default is true
+     * @returns The builder instance
+     */
+    withStrain(length?: number, required?: boolean): this;
+    /**
+     * Adds a meta product field to the request.
+     * @param length The max length of the meta product field, in characters. Default is 80
+     * @param required Whether the meta product field is required. Default is true
+     * @returns The builder instance
+     */
+    withMetaProduct(length?: number, required?: boolean): this;
+    /**
+     * Adds an event tracker to the request.
+     * @param event The type of event to be tracked
+     * @param methods Which methods are acceptable: either 1x1 image pixels or javascript tags, or both
+     * @returns The builder instance
+     */
+    withEventTracker(event: EventTypes, methods: EventTrackingMethods[]): this;
+    /**
+     * Generate the native bid request object.
+     * @returns The native request object
+     */
+    build(): INativeRequest;
+}

package/lib/types/models/rtb/native/index.d.ts

@@ -0,0 +1,4 @@
+export * from './INativeRequest';
+export * from './INativeResponse';
+export * from './NativeRequestBuilder';
+export * from './NativeConstants';

package/lib/types/models/tracking/IEvents.d.ts

@@ -0,0 +1,82 @@
+import type { ISite } from '../rtb';
+export interface IBidRequestedEvent {
+    auctionId: string;
+    bidderRequestId: string;
+    bids: IEventBid[];
+    auctionStart: number;
+    timeout: number;
+    refererInfo: IEventRefererInfo;
+    start: number;
+}
+export interface IBidderDoneEvent {
+    auctionId: string;
+    bidderRequestId: string;
+    bids?: IEventBid[];
+    auctionStart: number;
+    timeout: number;
+    refererInfo: IEventRefererInfo;
+    start: number;
+}
+export interface IEventBid {
+    params: IEventBidParams;
+    user?: IEventUser;
+    ortb2Imp: IEventOrtb2Imp;
+    mediaTypes: IEventMediaTypes;
+    transactionId: string;
+    sizes: number[][];
+    bidId: string;
+    ortb2: IEventOrtb2;
+}
+export interface IEventBidParams {
+    accountId: string;
+    channelId: string;
+    siteId: string;
+    placementId: string;
+    zone: string;
+    type: number | string;
+    storeId?: string;
+}
+export interface IEventUser {
+    geo?: IEventGeo;
+}
+export interface IEventGeo {
+    coords?: IEventCoords;
+    country?: string | null;
+    region?: string | null;
+    city?: string | null;
+    zip?: string | null;
+    utcOffset?: number;
+    timezone?: string;
+    ip?: string;
+}
+export interface IEventCoords {
+    lat: number;
+    lon: number;
+    accurary?: number | null;
+}
+export interface IEventOrtb2Imp {
+    ext?: {
+        tid?: string;
+    };
+}
+export interface IEventMediaTypes {
+    banner?: {
+        sizes: number[][];
+    };
+}
+export interface IEventOrtb2 {
+    site?: ISite;
+    device?: {
+        w?: number;
+        h?: number;
+        dnt?: number;
+        ua?: string;
+        language?: string;
+    };
+}
+export interface IEventRefererInfo {
+    stack: string[];
+    location: string;
+    page: string;
+    domain: string;
+}

package/lib/types/models/tracking/IGeoContext.d.ts

@@ -0,0 +1,14 @@
+export interface ICoordinates {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+}
+export interface IGeoContext {
+    country: string;
+    region: string;
+    city: string;
+    zip: string;
+    coords: ICoordinates;
+    utcoffset: number;
+    ip: string;
+}

package/lib/types/models/tracking/IUserID.d.ts

@@ -0,0 +1 @@
+export type IUserID = string;

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

@@ -0,0 +1,3 @@
+export * from './IGeoContext';
+export * from './IEvents';
+export * from './IUserID';

package/lib/types/models/vast/Vast.d.ts

@@ -0,0 +1,50 @@
+import type { IProductInformation } from '../../models';
+export interface IVast {
+    version: string;
+    ads: IAd[];
+}
+export interface IAd {
+    id: string | null;
+    inline: IInline;
+}
+export interface IVastProductData extends IProductInformation {
+    productId?: string;
+}
+export interface IInline {
+    impression: IImpression;
+    adSystem: string;
+    adTitle: string;
+    creatives: ICreative[];
+    product?: IVastProductData;
+}
+export interface IImpression {
+    id: string;
+    value: string;
+}
+export interface ICreative extends Record<string, unknown> {
+}
+export interface ICompanionAds extends ICreative {
+}
+export interface ILinear extends ICreative {
+    duration: string;
+    trackingEvents: ITrackingEvent[];
+    mediaFiles: IMediaFile[];
+    videoClicks: IVideoClick[];
+}
+export interface ITrackingEvent {
+    event: string;
+    url: string;
+}
+export interface IMediaFile {
+    id: string | null;
+    delivery: string;
+    type: string;
+    width: number;
+    height: number;
+    bitrate: string | null;
+    url: string;
+}
+export interface IVideoClick {
+    id: string | null;
+    url: string;
+}

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

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

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/index.d.ts

@@ -0,0 +1,5 @@
+export * from './logger';
+export * from './rtb';
+export * from './recommender';
+export * from './product-feed';
+export * from './tracking';

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/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';