@surfside/ads-core 2.0.1

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

@@ -0,0 +1,60 @@
+export declare enum CreativeType {
+    BANNER = 0,
+    INLINE = 1,
+    PRODUCT_CARD = 2,
+    PRODUCT_CAROUSEL = 3,
+    VIDEO = 4
+}
+export declare enum NativePosition {
+    UNKNOWN = 0,
+    ABOVE_THE_FOLD = 1,
+    BELOW_THE_FOLD = 3,
+    HEADER = 4,
+    FOOTER = 5,
+    SIDEBAR = 6,
+    FULL_SCREN = 7
+}
+export declare enum NativeImageTypes {
+    ICON = 1,
+    MAIN = 3
+}
+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
+}
+export declare enum NativeAssetId {
+    TITLE = 0,
+    IMAGE = 1,
+    SPONSORED = 2,
+    DESC = 3,
+    RATING = 4,
+    PRICE = 5,
+    SALEPRICE = 6,
+    DISPLAYURL = 7,
+    CTATEXT = 8,
+    SURF_CATEGORY = 9,
+    SURF_THC = 10,
+    SURF_CBD = 11,
+    SURF_STRAIN = 12
+}
+export interface INativeDataAsset {
+    id: number;
+    required: 0 | 1;
+    data: {
+        type: number;
+    };
+}

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/Geo.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/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 @@
+export * from './Geo';

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

@@ -0,0 +1,47 @@
+import type { IProductInformation } from '../../models';
+export interface IVast {
+    version: string;
+    ads: IAd[];
+}
+export interface IAd {
+    id?: string;
+    inline: IInline;
+}
+export interface IInline {
+    impression: IImpression;
+    adSystem: string;
+    adTitle: string;
+    creatives: ILinear[];
+    product?: IProductInformation;
+}
+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;
+    delivery: string;
+    type: string;
+    width: number;
+    height: number;
+    bitrate?: string;
+    url: string;
+}
+export interface IVideoClick {
+    id?: string;
+    url: string;
+}

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

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

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

@@ -0,0 +1,31 @@
+import { IBidRequest, IBidResponse } from '../models';
+import { ILogger } from './Logger';
+import { AsyncResult } 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 class NoBidsError extends Error {
+    readonly request: IBidRequest;
+    readonly response?: Response | undefined;
+    constructor(request: IBidRequest, response?: Response | undefined);
+}
+export declare class InternalServerError extends Error {
+    readonly request: IBidRequest;
+    readonly response: Response;
+    constructor(request: IBidRequest, response: Response);
+}
+export declare class BidderStartingUpError extends Error {
+    readonly request: IBidRequest;
+    readonly response: Response;
+    constructor(request: IBidRequest, response: Response);
+}
+export declare class UnknownBidderError extends Error {
+    readonly request: IBidRequest;
+    readonly response: Response;
+    constructor(request: IBidRequest, response: Response);
+}
+export declare class MalformedBidResponseError extends Error {
+    readonly request: IBidRequest;
+    readonly response: Response;
+    readonly bidResponse: unknown;
+    constructor(request: IBidRequest, response: Response, bidResponse: unknown);
+}

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

@@ -0,0 +1,6 @@
+import type Handlebars from 'handlebars/runtime';
+import type { ICompiledPublisherConfiguration } from '../models';
+import { type AsyncResult, type ILogger } from '.';
+import { HandlebarsHelpers } from '../helpers';
+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>;

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

@@ -0,0 +1,12 @@
+import { type IDevice } from '../models';
+import { type ILogger, type Result } from '.';
+export type GetDeviceFn = (screen: IScreen, navigator: INavigator, mobile: boolean) => Result<IDevice>;
+export interface IScreen {
+    width: number;
+    height: number;
+}
+export interface INavigator {
+    userAgent: string;
+    language: string;
+}
+export declare const GetDevice: (logger: ILogger | undefined, screen: IScreen, navigator: INavigator, mobile: boolean) => Result<IDevice>;