You're Invited:Meet the Socket Team at RSAC and BSidesSF 2026, March 23–26.RSVP →
@topsort/sdk
Advanced tools
@topsort/sdk - npm Package Compare versions
+938
| /** | ||
| * Type of device used for the interaction. | ||
| * @typedef {("desktop"|"mobile")} DeviceType | ||
| * @property {string} desktop - Desktop computer or laptop | ||
| * @property {string} mobile - Mobile device (smartphone or tablet) | ||
| * @example "mobile" | ||
| * @example "desktop" | ||
| */ | ||
| type DeviceType = "desktop" | "mobile"; | ||
| /** | ||
| * Configuration options for the Topsort client. | ||
| * @interface Config | ||
| */ | ||
| interface Config { | ||
| /** | ||
| * The API key to use for requests. | ||
| * A valid API key generated in Topsort's UI is required for authentication. | ||
| * @type {string} | ||
| * @required | ||
| */ | ||
| apiKey: string; | ||
| /** | ||
| * An optional alternative host to use for requests. | ||
| * Defaults to the standard Topsort API endpoint if not provided. | ||
| * @type {string} | ||
| * @optional | ||
| * @example "https://api.topsort.com" | ||
| */ | ||
| host?: string; | ||
| /** | ||
| * An optional timeout for requests in milliseconds. | ||
| * Specifies how long to wait for a request to complete before timing out. | ||
| * @type {number} | ||
| * @optional | ||
| * @example 5000 | ||
| */ | ||
| timeout?: number; | ||
| /** | ||
| * Optional custom user agent string to use for requests. | ||
| * Allows identification of the client making the requests. | ||
| * @type {string} | ||
| * @optional | ||
| * @example "MyApp/1.0.0" | ||
| */ | ||
| userAgent?: string; | ||
| /** | ||
| * Optional fetch options to pass to the fetch call. | ||
| * Defaults to { keepalive: true }. | ||
| * Allows customization of the underlying HTTP request behavior. | ||
| * @type {RequestInit} | ||
| * @optional | ||
| * @default { keepalive: true } | ||
| */ | ||
| fetchOptions?: RequestInit; | ||
| } | ||
| /** | ||
| * Type of auction to run. | ||
| * @typedef {("banners"|"listings")} AuctionType | ||
| * @property {string} banners - Banner ads auction for display advertising | ||
| * @property {string} listings - Sponsored listings auction for product promotions | ||
| */ | ||
| type AuctionType = "banners" | "listings"; | ||
| /** | ||
| * Geographical information associated with this auction. | ||
| * @interface GeoTargeting | ||
| */ | ||
| interface GeoTargeting { | ||
| /** | ||
| * The location this auction is being run for. | ||
| * @type {string} | ||
| * @example "New York" | ||
| */ | ||
| location: string; | ||
| } | ||
| /** | ||
| * A single category for the purpose of running an auction. | ||
| * @interface AuctionSingleCategory | ||
| */ | ||
| interface AuctionSingleCategory { | ||
| /** | ||
| * The category ID of the bids that will participate in an auction. | ||
| * @type {string} | ||
| * @example "c_yogurt" | ||
| */ | ||
| id: string; | ||
| } | ||
| /** | ||
| * A set of categories for the purpose of running an auction. | ||
| * In order to participate in an auction, a bid product must belong to all of the categories provided. | ||
| * @interface AuctionMultipleCategories | ||
| */ | ||
| interface AuctionMultipleCategories { | ||
| /** | ||
| * An array containing the category IDs of the bids that will participate in an auction. | ||
| * In order to participate in an auction, a bid product must belong to all of the categories provided. | ||
| * @type {string[]} | ||
| * @example ["c_men_clothing", "c_shoes"] | ||
| */ | ||
| ids: string[]; | ||
| } | ||
| /** | ||
| * Multiple disjunctions of categories for the purpose of running an auction. | ||
| * A bid product must belong to at least one category in each disjunction to participate. | ||
| * @interface AuctionDisjunctiveCategories | ||
| */ | ||
| interface AuctionDisjunctiveCategories { | ||
| /** | ||
| * An array of disjunctions. | ||
| * In order to participate in an auction, a bid product must belong to at least one of the categories | ||
| * of the disjunction provided in the auction request. | ||
| * @type {string[][]} | ||
| * @minItems 1 | ||
| * @maxItems 5 | ||
| * @example [["c_red", "c_blue"], ["c_large", "c_medium"]] | ||
| */ | ||
| disjunctions: string[][]; | ||
| } | ||
| /** | ||
| * List of products for the purpose of running an auction. | ||
| * @interface AuctionProduct | ||
| */ | ||
| interface AuctionProduct { | ||
| /** | ||
| * An array of product IDs that should participate in the auction. | ||
| * We recommend sending no more than 500 products per auction. | ||
| * These IDs must match those in the catalog integration with Topsort. | ||
| * @type {string[]} | ||
| * @minItems 1 | ||
| * @maxItems 10000 | ||
| * @example ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"] | ||
| */ | ||
| ids: string[]; | ||
| /** | ||
| * An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. | ||
| * If given, these values will be combined with internal quality scores to provide a score | ||
| * that better represents the relevance of the participating products. | ||
| * Note that the length of this array must be the same as the length of the `ids` array. | ||
| * Values must be between 0 and 1. | ||
| * @type {number[]} | ||
| * @optional | ||
| * @minItems 1 | ||
| * @maxItems 10000 | ||
| * @example [0.75, 0.82, 0.91, 0.68] | ||
| */ | ||
| qualityScores?: number[]; | ||
| } | ||
| /** | ||
| * Base interface for all auction types. | ||
| * Describes the intent of running an auction. | ||
| * @interface AuctionBase | ||
| */ | ||
| interface AuctionBase { | ||
| /** | ||
| * Category filter for the auction. | ||
| * Can be a single category, multiple categories, or disjunctive categories. | ||
| * Exactly one of: products, category, or searchQuery should be set depending on the auction context. | ||
| * @type {AuctionSingleCategory | AuctionMultipleCategories | AuctionDisjunctiveCategories} | ||
| * @optional | ||
| */ | ||
| category?: AuctionSingleCategory | AuctionMultipleCategories | AuctionDisjunctiveCategories; | ||
| /** | ||
| * Geographical information associated with this auction. | ||
| * @type {GeoTargeting} | ||
| * @optional | ||
| */ | ||
| geoTargeting?: GeoTargeting; | ||
| /** | ||
| * List of products that should participate in the auction. | ||
| * @type {AuctionProduct} | ||
| * @optional | ||
| */ | ||
| products?: AuctionProduct; | ||
| /** | ||
| * The search string provided by a user. | ||
| * Used for keyword-based auction targeting. | ||
| * @type {string} | ||
| * @optional | ||
| * @example "vanilla yogurt" | ||
| */ | ||
| searchQuery?: string; | ||
| /** | ||
| * Specifies the maximum number of auction winners that should be returned. | ||
| * @type {number} | ||
| * @required | ||
| * @minimum 1 | ||
| * @example 2 | ||
| */ | ||
| slots: number; | ||
| /** | ||
| * Discriminator for the type of auction. | ||
| * @type {AuctionType} | ||
| * @required | ||
| */ | ||
| type: AuctionType; | ||
| } | ||
| /** | ||
| * Describes the intent of running a sponsored listings auction. | ||
| * Ideal for product listing pages and search results. | ||
| * @interface SponsoredListingAuction | ||
| * @extends {AuctionBase} | ||
| */ | ||
| interface SponsoredListingAuction extends AuctionBase { | ||
| /** | ||
| * Discriminator for sponsored listings auction type. | ||
| * @type {"listings"} | ||
| * @required | ||
| */ | ||
| type: "listings"; | ||
| } | ||
| /** | ||
| * Describes the intent of running a banner ads auction. | ||
| * For Landing Page banners, `category` and `searchQuery` must be empty. | ||
| * For Category banners, the `category` field must be set. | ||
| * For Keywords banners, the `searchQuery` field must be set. | ||
| * @interface BannerAuction | ||
| * @extends {AuctionBase} | ||
| */ | ||
| interface BannerAuction extends AuctionBase { | ||
| /** | ||
| * The device for which the ads are meant for. | ||
| * @type {DeviceType} | ||
| * @optional | ||
| * @default "desktop" | ||
| */ | ||
| device?: DeviceType; | ||
| /** | ||
| * The ID of the banner placement for which this auction will be run for. | ||
| * This must be a valid slot ID configured in your marketplace. | ||
| * @type {string} | ||
| * @required | ||
| * @example "categories-ribbon-banner" | ||
| */ | ||
| slotId: string; | ||
| /** | ||
| * Discriminator for banner auction type. | ||
| * @type {"banners"} | ||
| * @required | ||
| */ | ||
| type: "banners"; | ||
| } | ||
| /** | ||
| * Main auction request interface. | ||
| * Each batch of auction requests can be a combination of sponsored listing auctions and banner auctions. | ||
| * @interface Auction | ||
| */ | ||
| interface Auction { | ||
| /** | ||
| * Array of auction requests to be processed. | ||
| * Topsort will run an auction for each batched auction request. | ||
| * @type {(SponsoredListingAuction | BannerAuction)[]} | ||
| * @required | ||
| * @minItems 1 | ||
| * @maxItems 5 | ||
| */ | ||
| auctions: (SponsoredListingAuction | BannerAuction)[]; | ||
| } | ||
| /** | ||
| * A source available for an asset (banner or video). | ||
| * @interface Asset | ||
| */ | ||
| interface Asset { | ||
| /** | ||
| * A vendor provided asset that the marketplace has to use as a banner. | ||
| * The asset will be served by Topsort's CDN. | ||
| * @type {string} | ||
| * @required | ||
| * @format uri | ||
| * @example "https://cdn.topsort.com/assets/example-banner.jpg" | ||
| */ | ||
| url: string; | ||
| /** | ||
| * Additional content metadata for the asset. | ||
| * This is an open object that can contain any additional properties. | ||
| * @type {Record<string, any>} | ||
| * @optional | ||
| * @example { "headingText": "Summer Sale", "bannerText": "50% off", "bannerTextColour": "#FFFFFF", "heroImage": "hero.jpg", "heroImageAltText": "Hero" } | ||
| */ | ||
| content?: Record<string, any>; | ||
| } | ||
| /** | ||
| * Base interface for auction winners. | ||
| * @interface BaseWinner | ||
| */ | ||
| interface BaseWinner { | ||
| /** | ||
| * The marketplace's ID of the winning entity, depending on the target of the campaign. | ||
| * @type {string} | ||
| * @required | ||
| * @example "p_Mfk15" | ||
| */ | ||
| id: string; | ||
| /** | ||
| * Where the product's bid ranked in the auction. | ||
| * One-based, so the product with rank 1 won the auction. | ||
| * In an auction response, the winners array is sorted so rank will match the entry's index. | ||
| * @type {number} | ||
| * @required | ||
| * @minimum 1 | ||
| * @example 1 | ||
| */ | ||
| rank: number; | ||
| /** | ||
| * An opaque Topsort ID to be used when this item is interacted with. | ||
| * This must be included in impression and click events for proper attribution. | ||
| * @type {string} | ||
| * @required | ||
| * @example "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" | ||
| */ | ||
| resolvedBidId: string; | ||
| /** | ||
| * The target type of the winning bid. | ||
| * @type {string} | ||
| * @required | ||
| * @enum ["product", "vendor", "brand", "url"] | ||
| * @example "product" | ||
| */ | ||
| type: string; | ||
| /** | ||
| * The ID of the campaign that won the auction. | ||
| * @type {string} | ||
| * @example "82588593-85c5-47c0-b125-07e315b7f2b3" | ||
| */ | ||
| campaignId: string; | ||
| } | ||
| /** | ||
| * Represents a sponsored listing auction winner. | ||
| * @interface SponsoredListingWinner | ||
| * @extends {BaseWinner} | ||
| */ | ||
| interface SponsoredListingWinner extends BaseWinner {} | ||
| /** | ||
| * Represents a banner auction winner with asset information. | ||
| * @interface BannerWinner | ||
| * @extends {BaseWinner} | ||
| */ | ||
| interface BannerWinner extends BaseWinner { | ||
| /** | ||
| * The list of available sources for a banner. | ||
| * Only present for banner auction winners. | ||
| * @type {Asset[]} | ||
| * @required | ||
| * @minItems 1 | ||
| */ | ||
| asset: Asset[]; | ||
| } | ||
| /** | ||
| * Union type for all winner types. | ||
| * @typedef {(SponsoredListingWinner|BannerWinner)} Winner | ||
| */ | ||
| type Winner = SponsoredListingWinner | BannerWinner; | ||
| /** | ||
| * Result for a single auction. | ||
| * @interface Result | ||
| */ | ||
| interface Result { | ||
| /** | ||
| * A boolean indicating whether this auction was resolved successfully. | ||
| * @type {boolean} | ||
| * @required | ||
| * @example false | ||
| */ | ||
| error: boolean; | ||
| /** | ||
| * The type of auction result. | ||
| * Discriminator for the result type. | ||
| * @type {AuctionType} | ||
| * @required | ||
| */ | ||
| resultType: AuctionType; | ||
| /** | ||
| * Array of winner objects in order from highest to lowest bid. | ||
| * It will be empty if there were no qualifying bids or if there was an error. | ||
| * The list of winners will contain at most `slots` entries per auction. | ||
| * It may contain fewer or no entries at all if there aren't enough products with usable bids. | ||
| * Winners for listings auctions will be SponsoredListingWinner objects. | ||
| * Winners for banner auctions will be BannerWinner objects with asset information. | ||
| * @type {Winner[]} | ||
| * @required | ||
| */ | ||
| winners: Winner[]; | ||
| } | ||
| /** | ||
| * The auction results response. | ||
| * Contains results for all auctions requested in the batch. | ||
| * @interface AuctionResult | ||
| */ | ||
| interface AuctionResult { | ||
| /** | ||
| * Array of auction results, one for each auction in the request. | ||
| * @type {Result[]} | ||
| * @required | ||
| * @minItems 1 | ||
| * @maxItems 5 | ||
| */ | ||
| results: Result[]; | ||
| } | ||
| /** | ||
| * Channel through which the user interaction occurred. | ||
| * Specifies where the event took place in relation to the marketplace. | ||
| * @typedef {("onsite"|"offsite"|"instore")} ChannelType | ||
| * @property {string} onsite - User is on the merchant's website or app | ||
| * @property {string} offsite - User is on a third-party platform | ||
| * @property {string} instore - User is in a physical store location | ||
| * @example "onsite" | ||
| * @example "offsite" | ||
| * @example "instore" | ||
| */ | ||
| type ChannelType = "onsite" | "offsite" | "instore"; | ||
| /** | ||
| * Base interface for all events. | ||
| * Contains the minimum required fields for any event. | ||
| * @interface BaseEvent | ||
| */ | ||
| interface BaseEvent { | ||
| /** | ||
| * A unique identifier for the request. | ||
| * This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. | ||
| * If there is no event model on the marketplace side, generate a unique string that does not change if the event is resent. | ||
| * @type {string} | ||
| * @required | ||
| * @example "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c" | ||
| */ | ||
| id: string; | ||
| /** | ||
| * A RFC3339 formatted timestamp including UTC offset. | ||
| * Indicates the exact time when the event occurred. | ||
| * @type {string} | ||
| * @required | ||
| * @format date-time | ||
| * @example "2009-01-01T12:59:59-05:00" | ||
| * @example "2019-01-01T12:59:59-05:00" | ||
| */ | ||
| occurredAt: string; | ||
| /** | ||
| * The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. | ||
| * This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. | ||
| * For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, | ||
| * storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. | ||
| * Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. | ||
| * Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests. | ||
| * @type {string} | ||
| * @required | ||
| * @example "71303ce0-de89-496d-8270-6434589615e8" | ||
| */ | ||
| opaqueUserId: string; | ||
| } | ||
| /** | ||
| * Extended base event interface with additional attribution fields. | ||
| * Used for impression and click events that may relate to sponsored content. | ||
| * @interface AdditionalEventBase | ||
| * @extends {BaseEvent} | ||
| */ | ||
| interface AdditionalEventBase extends BaseEvent { | ||
| /** | ||
| * Additional entity for attribution purposes. | ||
| * Allows for more complex attribution scenarios. | ||
| * @type {Entity} | ||
| * @optional | ||
| */ | ||
| additionalAttribution?: Entity; | ||
| /** | ||
| * If the event is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. | ||
| * In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field. | ||
| * For organic events, use the `entity` field instead. | ||
| * @type {string} | ||
| * @optional | ||
| * @example "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" | ||
| */ | ||
| resolvedBidId?: string; | ||
| /** | ||
| * Page information describing which page the event occurred on. | ||
| * @type {Page} | ||
| * @optional | ||
| */ | ||
| page?: Page; | ||
| } | ||
| /** | ||
| * Placement information describing where an interaction occurred. | ||
| * For analytics purposes, you can use the `placement` field to differentiate different listings or banners. | ||
| * @interface Placement | ||
| */ | ||
| interface Placement { | ||
| /** | ||
| * Index signature to allow additional properties. | ||
| * Placement supports additional custom properties beyond the standard fields. | ||
| */ | ||
| [key: string]: any; | ||
| /** | ||
| * An array of IDs of the categories associated to the page in which this event occurred, if applicable. | ||
| * These IDs must match the IDs provided through the catalog service. | ||
| * @type {string[]} | ||
| * @optional | ||
| * @minItems 1 | ||
| */ | ||
| categoryIds?: string[]; | ||
| /** | ||
| * For paginated pages, this should indicate which page number triggered the event. | ||
| * @type {number} | ||
| * @optional | ||
| * @minimum 1 | ||
| * @example 1 | ||
| */ | ||
| page?: number; | ||
| /** | ||
| * For paginated pages this should indicate how many items are in each result page. | ||
| * @type {number} | ||
| * @optional | ||
| * @minimum 1 | ||
| * @example 15 | ||
| */ | ||
| pageSize?: number; | ||
| /** | ||
| * URL path of the page triggering the event. | ||
| * For web apps, this can be obtained in JS using `window.location.pathname`. | ||
| * For mobile apps, use the deep link for the current view, if available. | ||
| * Otherwise, encode the view from which the event occurred in your app as a path-like string. | ||
| * @type {string} | ||
| * @required | ||
| * @example "/categories/dairy" | ||
| * @example "/root/categories/:categoryId" | ||
| */ | ||
| path: string; | ||
| /** | ||
| * For components with multiple items (i.e. search results, similar products, etc), | ||
| * this should indicate the index of a given item within that list. | ||
| * @type {number} | ||
| * @optional | ||
| * @minimum 1 | ||
| */ | ||
| position?: number; | ||
| /** | ||
| * The ID of the product associated to the page in which this event occurred, if applicable. | ||
| * This ID must match the ID provided through the catalog service. | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| productId?: string; | ||
| /** | ||
| * The search string provided by the user in the page where this event occurred, if applicable. | ||
| * This search string must match the searchQuery field that was provided in the auction request (if provided). | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| searchQuery?: string; | ||
| } | ||
| /** | ||
| * Entity is meant for reporting organic events, not sponsored or promoted products. | ||
| * It refers to the object involved in the organic interaction. | ||
| * Be aware that if `resolvedBidId` has any value, `entity` will be disregarded. | ||
| * @interface Entity | ||
| */ | ||
| interface Entity { | ||
| /** | ||
| * The marketplace's ID of the entity associated with the interaction. | ||
| * @type {string} | ||
| * @required | ||
| */ | ||
| id: string; | ||
| /** | ||
| * The type of entity associated with the interaction. | ||
| * @type {"product" | "vendor"} | ||
| * @required | ||
| * @example "product" | ||
| * @example "vendor" | ||
| */ | ||
| type: "product" | "vendor"; | ||
| } | ||
| /** | ||
| * Information regarding an organic or non-sponsored event. | ||
| * Describes the type of object that was interacted with. | ||
| * @interface InteractionObject | ||
| */ | ||
| interface InteractionObject { | ||
| /** | ||
| * The type of object that is being reported on the interaction. | ||
| * @type {"listing" | "banner"} | ||
| * @required | ||
| * @example "listing" | ||
| */ | ||
| type: "listing" | "banner"; | ||
| /** | ||
| * When type is `banner`, signals the ID of the asset of the banner. | ||
| * @type {string} | ||
| * @optional | ||
| * @example "asset-123" | ||
| */ | ||
| assetId?: string; | ||
| /** | ||
| * When type is `listing`, signals the specific interaction flavor with the listing. | ||
| * @type {"image" | "add_to_cart" | "purchase_now"} | ||
| * @optional | ||
| */ | ||
| clickType?: "image" | "add_to_cart" | "purchase_now"; | ||
| } | ||
| /** | ||
| * An impression means a promotable has become visible to the consumer. | ||
| * For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. | ||
| * For unpromoted entities, include the `entity` field to describe what was seen. | ||
| * In case you cannot send an impression when the product becomes visible, send us an impression event | ||
| * when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. | ||
| * @interface Impression | ||
| * @extends {AdditionalEventBase} | ||
| */ | ||
| interface Impression extends AdditionalEventBase { | ||
| /** | ||
| * Optional channel where the impression occurred. | ||
| * @type {ChannelType} | ||
| * @optional | ||
| */ | ||
| channel?: ChannelType; | ||
| /** | ||
| * Optional device type used for the impression. | ||
| * @type {DeviceType} | ||
| * @optional | ||
| */ | ||
| deviceType?: DeviceType; | ||
| /** | ||
| * Entity is meant for reporting organic events, not sponsored or promoted products. | ||
| * Use this field when the impression is not related to an auction result. | ||
| * @type {Entity} | ||
| * @optional | ||
| */ | ||
| entity?: Entity; | ||
| /** | ||
| * Placement information describing where the impression occurred. | ||
| * @type {Placement} | ||
| * @optional | ||
| */ | ||
| placement?: Placement; | ||
| /** | ||
| * Information regarding an organic or non-sponsored event. | ||
| * @type {InteractionObject} | ||
| * @optional | ||
| */ | ||
| object?: InteractionObject; | ||
| /** | ||
| * Marketplace provided ID for a campaign. | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| externalCampaignId?: string; | ||
| /** | ||
| * Marketplace provided ID for a vendor. | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| externalVendorId?: string; | ||
| } | ||
| /** | ||
| * A click is sent to Topsort when the consumer has clicked on a promotable. | ||
| * For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. | ||
| * For unpromoted entities, include the `entity` field to describe what was clicked. | ||
| * Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. | ||
| * @interface Click | ||
| * @extends {AdditionalEventBase} | ||
| */ | ||
| interface Click extends AdditionalEventBase { | ||
| /** | ||
| * Optional channel where the click occurred. | ||
| * @type {ChannelType} | ||
| * @optional | ||
| */ | ||
| channel?: ChannelType; | ||
| /** | ||
| * Optional device type used for the click. | ||
| * @type {DeviceType} | ||
| * @optional | ||
| */ | ||
| deviceType?: DeviceType; | ||
| /** | ||
| * Entity is meant for reporting organic events, not sponsored or promoted products. | ||
| * Use this field when the click is not related to an auction result. | ||
| * @type {Entity} | ||
| * @optional | ||
| */ | ||
| entity?: Entity; | ||
| /** | ||
| * Placement information describing where the click occurred. | ||
| * @type {Placement} | ||
| * @optional | ||
| */ | ||
| placement?: Placement; | ||
| /** | ||
| * Information regarding an organic or non-sponsored event. | ||
| * @type {InteractionObject} | ||
| * @optional | ||
| */ | ||
| object?: InteractionObject; | ||
| /** | ||
| * For sponsored events only, signals the specific interaction flavor with the listing. | ||
| * @type {"image" | "add_to_cart" | "purchase_now"} | ||
| * @optional | ||
| */ | ||
| clickType?: "image" | "add_to_cart" | "purchase_now"; | ||
| /** | ||
| * Marketplace provided ID for a campaign. | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| externalCampaignId?: string; | ||
| /** | ||
| * Marketplace provided ID for a vendor. | ||
| * @type {string} | ||
| * @optional | ||
| */ | ||
| externalVendorId?: string; | ||
| } | ||
| /** | ||
| * An item that was purchased in a transaction. | ||
| * @interface Item | ||
| */ | ||
| interface Item { | ||
| /** | ||
| * The marketplace ID of the product being purchased. | ||
| * @type {string} | ||
| * @required | ||
| * @example "p_SA0238" | ||
| */ | ||
| productId: string; | ||
| /** | ||
| * Amount of products purchased. | ||
| * @type {number} | ||
| * @required | ||
| * @minimum 1 | ||
| * @default 1 | ||
| * @example 2 | ||
| */ | ||
| quantity: number; | ||
| /** | ||
| * The price of a single item in the marketplace currency. | ||
| * @type {number} | ||
| * @required | ||
| * @example 12.95 | ||
| */ | ||
| unitPrice: number; | ||
| /** | ||
| * The vendor ID of the product being purchased. | ||
| * This field is optional and should be filled in if: | ||
| * 1. a product is sold by multiple vendors, or | ||
| * 2. you want to use it for halo attribution | ||
| * @type {string} | ||
| * @optional | ||
| * @example "v_8fj2D" | ||
| */ | ||
| vendorId?: string; | ||
| } | ||
| /** | ||
| * A purchase is sent to Topsort once a marketplace customer places an order. | ||
| * These events are used to measure the effectiveness of an ad campaign. | ||
| * @interface Purchase | ||
| * @extends {BaseEvent} | ||
| */ | ||
| interface Purchase extends BaseEvent { | ||
| /** | ||
| * Optional channel where the purchase occurred. | ||
| * @type {ChannelType} | ||
| * @optional | ||
| */ | ||
| channel?: ChannelType; | ||
| /** | ||
| * Optional device type used for the purchase. | ||
| * @type {DeviceType} | ||
| * @optional | ||
| */ | ||
| deviceType?: DeviceType; | ||
| /** | ||
| * Items purchased in this transaction. | ||
| * @type {Item[]} | ||
| * @required | ||
| * @minItems 1 | ||
| */ | ||
| items: Item[]; | ||
| } | ||
| /** | ||
| * Base page interface containing common page properties. | ||
| * @interface BasePage | ||
| */ | ||
| interface BasePage { | ||
| /** | ||
| * Identifies the page. | ||
| * @type {string} | ||
| * @required | ||
| * @example "/category/electronics" | ||
| */ | ||
| pageId: string; | ||
| } | ||
| /** | ||
| * Standard page with a single value. | ||
| * Used for most page types except cart pages. | ||
| * @interface StandardPage | ||
| * @extends {BasePage} | ||
| */ | ||
| interface StandardPage extends BasePage { | ||
| /** | ||
| * Type of page. | ||
| * @type {"home" | "category" | "PDP" | "search" | "other"} | ||
| * @required | ||
| * @example "category" | ||
| */ | ||
| type: "home" | "category" | "PDP" | "search" | "other"; | ||
| /** | ||
| * Detail of the page, depending on the type. | ||
| * For category pages, this would be the category identifier. | ||
| * For search pages, this would be the search query. | ||
| * For PDP pages, this would be the product identifier. | ||
| * @type {string} | ||
| * @required | ||
| * @example "electronics" | ||
| */ | ||
| value: string; | ||
| } | ||
| /** | ||
| * Cart page with multiple product IDs. | ||
| * Used specifically for cart pages where multiple items are present. | ||
| * @interface CartPage | ||
| * @extends {BasePage} | ||
| */ | ||
| interface CartPage extends BasePage { | ||
| /** | ||
| * Type of page, must be "cart" for this interface. | ||
| * @type {"cart"} | ||
| * @required | ||
| */ | ||
| type: "cart"; | ||
| /** | ||
| * Items on the cart. | ||
| * Array of product IDs currently in the shopping cart. | ||
| * @type {string[]} | ||
| * @required | ||
| * @minItems 1 | ||
| * @example ["coffee", "cookies", "apples"] | ||
| */ | ||
| value: string[]; | ||
| } | ||
| /** | ||
| * Page information for a pageview event. | ||
| * Use StandardPage for single-value pages or CartPage for cart pages with multiple product IDs. | ||
| * @typedef {(StandardPage|CartPage)} Page | ||
| */ | ||
| type Page = StandardPage | CartPage; | ||
| /** | ||
| * PageView event - tracks when a user views a page. | ||
| * A page view represents the navigation of the user throughout the page. | ||
| * They are considered organic events. | ||
| * In contrast to clicks or impressions, which are events within a page, a page view is the | ||
| * interaction with the full page, which can contain multiple objects. | ||
| * @interface PageView | ||
| * @extends {BaseEvent} | ||
| */ | ||
| interface PageView extends BaseEvent { | ||
| /** | ||
| * Channel through which the page was viewed. | ||
| * @type {ChannelType} | ||
| * @optional | ||
| */ | ||
| channel?: ChannelType; | ||
| /** | ||
| * Type of device used to view the page. | ||
| * @type {DeviceType} | ||
| * @optional | ||
| */ | ||
| deviceType?: DeviceType; | ||
| /** | ||
| * Page information describing which page was viewed. | ||
| * @type {Page} | ||
| * @required | ||
| */ | ||
| page: Page; | ||
| } | ||
| /** | ||
| * Main event request interface. | ||
| * Contains arrays of different event types to be reported to Topsort. | ||
| * Use the `/events` endpoint to report user interactions and activity on a marketplace. | ||
| * @interface Event | ||
| */ | ||
| interface Event { | ||
| /** | ||
| * Click events to report. | ||
| * A user clicked on an asset. | ||
| * @type {Click[]} | ||
| * @optional | ||
| * @minItems 0 | ||
| * @maxItems 50 | ||
| */ | ||
| clicks?: Click[]; | ||
| /** | ||
| * Impression events to report. | ||
| * A user viewed an asset. | ||
| * @type {Impression[]} | ||
| * @optional | ||
| * @minItems 0 | ||
| * @maxItems 50 | ||
| */ | ||
| impressions?: Impression[]; | ||
| /** | ||
| * PageView events to report. | ||
| * A user visited a page. | ||
| * @type {PageView[]} | ||
| * @optional | ||
| * @minItems 0 | ||
| * @maxItems 50 | ||
| */ | ||
| pageviews?: PageView[]; | ||
| /** | ||
| * Purchase events to report. | ||
| * A user created an order. | ||
| * @type {Purchase[]} | ||
| * @optional | ||
| * @minItems 0 | ||
| * @maxItems 50 | ||
| */ | ||
| purchases?: Purchase[]; | ||
| } | ||
| /** | ||
| * Result of an event reporting request. | ||
| * @interface EventResult | ||
| */ | ||
| interface EventResult { | ||
| /** | ||
| * Indicates whether the event reporting was successful. | ||
| * @type {boolean} | ||
| * @required | ||
| */ | ||
| ok: boolean; | ||
| /** | ||
| * Indicates whether the request should be retried in case of failure. | ||
| * @type {boolean} | ||
| * @required | ||
| */ | ||
| retry: boolean; | ||
| } | ||
| declare class TopsortClient { | ||
| private config; | ||
| constructor(config: Config); | ||
| reportEvent(event: Event): Promise<EventResult>; | ||
| createAuction(auction: Auction): Promise<AuctionResult>; | ||
| } | ||
| export { TopsortClient, Purchase, Placement, PageView, Page, Item, InteractionObject, Impression, EventResult, Event, Entity, DeviceType, Config, Click, ChannelType, AuctionResult, Auction }; |
+1
-1
@@ -1,1 +0,1 @@ | ||
| var E=require("node:module");var{defineProperty:a,getOwnPropertyNames:x,getOwnPropertyDescriptor:A}=Object,C=Object.prototype.hasOwnProperty;var m=new WeakMap,b=(t)=>{var r=m.get(t),o;if(r)return r;if(r=a({},"__esModule",{value:!0}),t&&typeof t==="object"||typeof t==="function")x(t).map((e)=>!C.call(r,e)&&a(r,e,{get:()=>t[e],enumerable:!(o=A(t,e))||o.enumerable}));return m.set(t,r),r};var k=(t,r)=>{for(var o in r)a(t,o,{get:r[o],enumerable:!0,configurable:!0,set:(e)=>r[o]=()=>e})};var T={};k(T,{TopsortClient:()=>v});module.exports=b(T);var u="https://api.topsort.com",n={auctions:"v2/auctions",events:"v2/events"};var c="0.3.9";class d{status;statusText;body;retry;constructor(t,r,o,e=!1){this.status=t,this.statusText=r,this.body=o,this.retry=e}}var i=d;class f{async handleResponse(t){let r;if(t.status!==204)r=await t.json();if(!t.ok){let o=t.status===429||t.status>=500;throw new i(t.status,t.statusText,r,o)}return r}async request(t,r){try{let o=this.sanitizeUrl(t),e=await fetch(o,r);return this.handleResponse(e)}catch(o){let e=o instanceof Error?o.message:"Unknown error";throw new i(500,"Internal Server Error",e)}}setupTimeoutSignal(t){if(t.timeout!=null){let r=new AbortController;return setTimeout(()=>r.abort(),t.timeout),r.signal}}async post(t,r,o){let e=this.setupTimeoutSignal(o),w=o.fetchOptions??{keepalive:!0};return this.request(t,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json","X-UA":o.userAgent?`@topsort/sdk ${c} ${o.userAgent}`:`@topsort/sdk ${c}`,Authorization:`Bearer ${o.apiKey}`},body:JSON.stringify(r),signal:e,...w})}sanitizeUrl(t){try{return new URL(t).href.replace(/\/+$/,"")}catch(r){throw new i(400,"Invalid URL",{error:`Invalid URL: ${r}`})}}}var s=new f;function l(t){if(!t?.apiKey?.length)throw new i(401,"API Key is required.",{})}function p(t){return async(...r)=>{let o=r[r.length-1];return l(o),t(...r)}}async function U(t,r){let o=`${r.host}/${n.auctions}`;return await s.post(o.toString(),t,r)}var g=p(U);async function j(t,r){try{let o=`${r.host}/${n.events}`;return await s.post(o,t,r),{ok:!0,retry:!1}}catch(o){if(o instanceof i&&o.retry)return{ok:!1,retry:!0};throw o}}var h=p(j);class y{config;constructor(t){this.config=t,this.config.host=this.config.host??u}async reportEvent(t){return h(t,this.config)}async createAuction(t){return g(t,this.config)}}var v=y; | ||
| var E=require("node:module");var{defineProperty:a,getOwnPropertyNames:x,getOwnPropertyDescriptor:A}=Object,C=Object.prototype.hasOwnProperty;var m=new WeakMap,b=(t)=>{var r=m.get(t),o;if(r)return r;if(r=a({},"__esModule",{value:!0}),t&&typeof t==="object"||typeof t==="function")x(t).map((e)=>!C.call(r,e)&&a(r,e,{get:()=>t[e],enumerable:!(o=A(t,e))||o.enumerable}));return m.set(t,r),r};var k=(t,r)=>{for(var o in r)a(t,o,{get:r[o],enumerable:!0,configurable:!0,set:(e)=>r[o]=()=>e})};var T={};k(T,{TopsortClient:()=>v});module.exports=b(T);var u="https://api.topsort.com",n={auctions:"v2/auctions",events:"v2/events"};var c="0.4.0";class d{status;statusText;body;retry;constructor(t,r,o,e=!1){this.status=t,this.statusText=r,this.body=o,this.retry=e}}var i=d;class f{async handleResponse(t){let r;if(t.status!==204)r=await t.json();if(!t.ok){let o=t.status===429||t.status>=500;throw new i(t.status,t.statusText,r,o)}return r}async request(t,r){try{let o=this.sanitizeUrl(t),e=await fetch(o,r);return this.handleResponse(e)}catch(o){let e=o instanceof Error?o.message:"Unknown error";throw new i(500,"Internal Server Error",e)}}setupTimeoutSignal(t){if(t.timeout!=null){let r=new AbortController;return setTimeout(()=>r.abort(),t.timeout),r.signal}}async post(t,r,o){let e=this.setupTimeoutSignal(o),w=o.fetchOptions??{keepalive:!0};return this.request(t,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json","X-UA":o.userAgent?`@topsort/sdk ${c} ${o.userAgent}`:`@topsort/sdk ${c}`,Authorization:`Bearer ${o.apiKey}`},body:JSON.stringify(r),signal:e,...w})}sanitizeUrl(t){try{return new URL(t).href.replace(/\/+$/,"")}catch(r){throw new i(400,"Invalid URL",{error:`Invalid URL: ${r}`})}}}var s=new f;function l(t){if(!t?.apiKey?.length)throw new i(401,"API Key is required.",{})}function p(t){return async(...r)=>{let o=r[r.length-1];return l(o),t(...r)}}async function U(t,r){let o=`${r.host}/${n.auctions}`;return await s.post(o.toString(),t,r)}var g=p(U);async function j(t,r){try{let o=`${r.host}/${n.events}`;return await s.post(o,t,r),{ok:!0,retry:!1}}catch(o){if(o instanceof i&&o.retry)return{ok:!1,retry:!0};throw o}}var h=p(j);class y{config;constructor(t){this.config=t,this.config.host=this.config.host??u}async reportEvent(t){return h(t,this.config)}async createAuction(t){return g(t,this.config)}}var v=y; |
+1
-1
@@ -1,1 +0,1 @@ | ||
| var c="https://api.topsort.com",n={auctions:"v2/auctions",events:"v2/events"};var a="0.3.9";class m{status;statusText;body;retry;constructor(t,r,o,e=!1){this.status=t,this.statusText=r,this.body=o,this.retry=e}}var i=m;class u{async handleResponse(t){let r;if(t.status!==204)r=await t.json();if(!t.ok){let o=t.status===429||t.status>=500;throw new i(t.status,t.statusText,r,o)}return r}async request(t,r){try{let o=this.sanitizeUrl(t),e=await fetch(o,r);return this.handleResponse(e)}catch(o){let e=o instanceof Error?o.message:"Unknown error";throw new i(500,"Internal Server Error",e)}}setupTimeoutSignal(t){if(t.timeout!=null){let r=new AbortController;return setTimeout(()=>r.abort(),t.timeout),r.signal}}async post(t,r,o){let e=this.setupTimeoutSignal(o),h=o.fetchOptions??{keepalive:!0};return this.request(t,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json","X-UA":o.userAgent?`@topsort/sdk ${a} ${o.userAgent}`:`@topsort/sdk ${a}`,Authorization:`Bearer ${o.apiKey}`},body:JSON.stringify(r),signal:e,...h})}sanitizeUrl(t){try{return new URL(t).href.replace(/\/+$/,"")}catch(r){throw new i(400,"Invalid URL",{error:`Invalid URL: ${r}`})}}}var s=new u;function d(t){if(!t?.apiKey?.length)throw new i(401,"API Key is required.",{})}function p(t){return async(...r)=>{let o=r[r.length-1];return d(o),t(...r)}}async function v(t,r){let o=`${r.host}/${n.auctions}`;return await s.post(o.toString(),t,r)}var f=p(v);async function w(t,r){try{let o=`${r.host}/${n.events}`;return await s.post(o,t,r),{ok:!0,retry:!1}}catch(o){if(o instanceof i&&o.retry)return{ok:!1,retry:!0};throw o}}var l=p(w);class g{config;constructor(t){this.config=t,this.config.host=this.config.host??c}async reportEvent(t){return l(t,this.config)}async createAuction(t){return f(t,this.config)}}var x=g;export{x as TopsortClient}; | ||
| var c="https://api.topsort.com",n={auctions:"v2/auctions",events:"v2/events"};var a="0.4.0";class m{status;statusText;body;retry;constructor(t,r,o,e=!1){this.status=t,this.statusText=r,this.body=o,this.retry=e}}var i=m;class u{async handleResponse(t){let r;if(t.status!==204)r=await t.json();if(!t.ok){let o=t.status===429||t.status>=500;throw new i(t.status,t.statusText,r,o)}return r}async request(t,r){try{let o=this.sanitizeUrl(t),e=await fetch(o,r);return this.handleResponse(e)}catch(o){let e=o instanceof Error?o.message:"Unknown error";throw new i(500,"Internal Server Error",e)}}setupTimeoutSignal(t){if(t.timeout!=null){let r=new AbortController;return setTimeout(()=>r.abort(),t.timeout),r.signal}}async post(t,r,o){let e=this.setupTimeoutSignal(o),h=o.fetchOptions??{keepalive:!0};return this.request(t,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json","X-UA":o.userAgent?`@topsort/sdk ${a} ${o.userAgent}`:`@topsort/sdk ${a}`,Authorization:`Bearer ${o.apiKey}`},body:JSON.stringify(r),signal:e,...h})}sanitizeUrl(t){try{return new URL(t).href.replace(/\/+$/,"")}catch(r){throw new i(400,"Invalid URL",{error:`Invalid URL: ${r}`})}}}var s=new u;function d(t){if(!t?.apiKey?.length)throw new i(401,"API Key is required.",{})}function p(t){return async(...r)=>{let o=r[r.length-1];return d(o),t(...r)}}async function v(t,r){let o=`${r.host}/${n.auctions}`;return await s.post(o.toString(),t,r)}var f=p(v);async function w(t,r){try{let o=`${r.host}/${n.events}`;return await s.post(o,t,r),{ok:!0,retry:!1}}catch(o){if(o instanceof i&&o.retry)return{ok:!1,retry:!0};throw o}}var l=p(w);class g{config;constructor(t){this.config=t,this.config.host=this.config.host??c}async reportEvent(t){return l(t,this.config)}async createAuction(t){return f(t,this.config)}}var x=g;export{x as TopsortClient}; |
+5
-5
| { | ||
| "name": "@topsort/sdk", | ||
| "version": "0.3.9", | ||
| "version": "0.4.0", | ||
| "description": "The official Topsort SDK for TypeScript and JavaScript", | ||
@@ -35,3 +35,3 @@ "packageManager": "bun@1.3.3", | ||
| "README.md", | ||
| "dist/index.d.cjs", | ||
| "dist/index.d.cts", | ||
| "dist/index.d.ts", | ||
@@ -51,7 +51,7 @@ "dist/index.js", | ||
| "devDependencies": { | ||
| "@biomejs/biome": "2.3.7", | ||
| "@playwright/test": "1.56.1", | ||
| "@biomejs/biome": "2.3.12", | ||
| "@playwright/test": "1.58.0", | ||
| "@types/bun": "1.3.3", | ||
| "bunup": "0.16.10", | ||
| "lefthook": "2.0.4", | ||
| "lefthook": "2.0.15", | ||
| "msw": "2.12.3", | ||
@@ -58,0 +58,0 @@ "typescript": "5.9.3" |
New alerts
Network access
Supply chain riskThis module accesses the network.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
Found 1 instance in 1 package
Fixed alerts
Network access
Supply chain riskThis module accesses the network.
Found 1 instance in 1 package
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
67152
63.51%- Number of package files
8
14.29%Worsened metrics
- Number of low supply chain risk alerts
9
80%- Number of medium supply chain risk alerts
7
75%No dependency changes