@surfside/ads-react 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,215 @@
1
+ import { type ErrResult, type IBuiltCarousel, type IBuiltProductCardResponse, type IProductInformation, type Result } from '@surfside/ads-core-client';
2
+ /**
3
+ * The base properties passed to useSurfsideProducts. Includes settings on the behavior of product fetching, recommender
4
+ * strategy, and page size
5
+ */
6
+ export interface IUseSurfsideProductsPropsBase {
7
+ /** The Zone ID of the ad placement */
8
+ zoneId: string;
9
+ /** The number of products to fetch per-page */
10
+ pageSize: number;
11
+ /** Whether or not to enable the creative yet, useful for lazy loading */
12
+ enabled?: boolean;
13
+ /** Maximum number of products to be returned before halting the product feed */
14
+ maxProducts?: number;
15
+ /** What kind of product feed results to use. Sponsored will only request advertisements, recommended will only
16
+ * request recommended products, and hybrid will try to fill the feed with advertisements and then fall back to
17
+ * recommended products when it runs out of sponsored products
18
+ */
19
+ strategy: 'sponsored' | 'hybrid' | 'recommended';
20
+ /**
21
+ * If strategy is 'hybrid' or 'recommended', this setting determines what kind of recommendations to request. If no
22
+ * option is passed, this will default to 'top-products'. 'for-you' and 'past-purchases' require the User ID to be
23
+ * set at the Surfside Context level - if no User ID is set on the Surfside Context, this will fall back to
24
+ * 'top-products'
25
+ */
26
+ recommenderType?: 'top-products' | 'for-you' | 'past-purchases';
27
+ /** If true, `useSurfsideProducts` will map product feed results to their full product data fields, including name,
28
+ * description, price, etc.
29
+ *
30
+ * If false, `useSurfsideProducts` will return only product IDs
31
+ * @defaultValue true
32
+ *
33
+ */
34
+ withProductInfo?: boolean;
35
+ }
36
+ /** The product props state for returning a set of full product data
37
+ * @expandType IUseSurfsideProductsPropsBase
38
+ */
39
+ export type UseSurfsideProductsPropsWithProductData = IUseSurfsideProductsPropsBase & {
40
+ /** If true, `useSurfsideProducts` will map product feed results to their full product data fields, including name,
41
+ * description, price, etc.
42
+ *
43
+ * If false, `useSurfsideProducts` will return only product IDs
44
+ *
45
+ * **This type represents the `true` state.** For the `false` state,
46
+ * see {@link UseSurfsideProductsPropsWithProductIDs}
47
+ *
48
+ * @example
49
+ *
50
+ * ```tsx
51
+ * // returns product data
52
+ * const { products } = useSurfsideProducts({
53
+ * zoneId: '123',
54
+ * pageSize: 6,
55
+ * strategy: 'sponsored',
56
+ * withProductInfo: true // or pass nothing - withProductInfo is true by default
57
+ * })
58
+ *
59
+ * console.log(products.map(product => product.data.name))
60
+ * ```
61
+ */
62
+ withProductInfo?: true | undefined;
63
+ };
64
+ /** The product props state for returning a set of product IDs only
65
+ * @expandType IUseSurfsideProductsPropsBase
66
+ */
67
+ export type UseSurfsideProductsPropsWithProductIDs = IUseSurfsideProductsPropsBase & {
68
+ /** If true, `useSurfsideProducts` will map product feed results to their full product data fields, including name,
69
+ * description, price, etc.
70
+ *
71
+ * If false, `useSurfsideProducts` will return only product IDs
72
+ *
73
+ * **This type represents the `false` state.** For the `true` state,
74
+ * see {@link UseSurfsideProductsPropsWithProductData}
75
+ *
76
+ * @example
77
+ *
78
+ * ```tsx
79
+ * // returns product IDs
80
+ * const { products } = useSurfsideProducts({
81
+ * zoneId: '123',
82
+ * pageSize: 6,
83
+ * strategy: 'sponsored',
84
+ * withProductInfo: false
85
+ * })
86
+ *
87
+ * console.log(products.map(product => product.id))
88
+ * ```
89
+ */
90
+ withProductInfo: false;
91
+ };
92
+ /** The discriminated union for type-narrowing the product props return type */
93
+ export type UseSurfsideProductsProps = UseSurfsideProductsPropsWithProductIDs | UseSurfsideProductsPropsWithProductData;
94
+ export interface IUseSurfsideProductsResponsePropsBase {
95
+ carousel: Result<IBuiltCarousel> | undefined;
96
+ }
97
+ export type UseSurfsideProductsResponsePropsWithProductIDs = IUseSurfsideProductsResponsePropsBase & UseSurfsideProductsPropsWithProductIDs;
98
+ export type UseSurfsideProductsResponsePropsWithProductData = IUseSurfsideProductsResponsePropsBase & UseSurfsideProductsPropsWithProductData;
99
+ export type UseSurfsideProductsResponseProps = UseSurfsideProductsResponsePropsWithProductIDs | UseSurfsideProductsResponsePropsWithProductData;
100
+ /** A wrapper for product data results to indicate whether the product is sponsored or recommended */
101
+ export interface IProductDataBase {
102
+ type: 'recommended' | 'sponsored';
103
+ productCardResponse: IBuiltProductCardResponse;
104
+ }
105
+ /** This type is returned if useSurfsideProducts is passed { withProductInfo: true } or if nothing is passed at all
106
+ * (defaults to true)
107
+ */
108
+ export interface IProductInfoData extends IProductDataBase {
109
+ data: IProductInformation;
110
+ }
111
+ /** This type is returned if useSurfsideProducts is passed { withProductInfo: false } */
112
+ export interface IProductIDData extends IProductDataBase {
113
+ id?: string;
114
+ }
115
+ export interface IProductAnalyticsCallbacks {
116
+ trackClick: (product: IProductDataBase) => void;
117
+ trackImpression: (product: IProductDataBase) => void;
118
+ }
119
+ /**
120
+ * The base return type for useSurfsideProducts. `products` may be either a set of IDs or a set of product info
121
+ * */
122
+ export interface IUseSurfsideProductsReturnGeneric<T> {
123
+ /** The product information. Either a set of IDs or a set of Product Information objects, depending on the value
124
+ * of `{ withProductData: boolean }` in {@link UseSurfsideProductsProps}.
125
+ *
126
+ * * If `withProductData` is set to `true` or `undefined` (i.e, it defaults to true),
127
+ * then `T` will be {@link IProductInfoData}.
128
+ *
129
+ * * If `withProductData` is set to `false`, then `T` will be {@link IProductIDData}.
130
+ */
131
+ products: T[];
132
+ /** Whether the product feed is still loading or not */
133
+ loading: boolean;
134
+ /** Whether or not the product feed is done */
135
+ hasMore: boolean;
136
+ /** If any errors occur during fetching, they will be set here */
137
+ error?: ErrResult;
138
+ /** Gets the next page of products and updates the state of `products`. */
139
+ fetchNextPage?: () => void;
140
+ /** Resets the product feed, setting `products` to an empty array */
141
+ refetch?: () => void;
142
+ /** Callbacks for tracking clicks and impressions on the product feed */
143
+ analytics?: IProductAnalyticsCallbacks;
144
+ }
145
+ /**
146
+ * @expandType IUseSurfsideProductsReturnGeneric
147
+ */
148
+ export interface IUseSurfsideProductsReturnGenericSuccess<T> extends IUseSurfsideProductsReturnGeneric<T> {
149
+ loading: false;
150
+ error: undefined;
151
+ fetchNextPage: () => void;
152
+ refetch: () => void;
153
+ analytics: IProductAnalyticsCallbacks;
154
+ }
155
+ export interface IUseSurfsideProductsReturnGenericError<T> extends IUseSurfsideProductsReturnGeneric<T> {
156
+ loading: false;
157
+ error: ErrResult;
158
+ fetchNextPage: undefined;
159
+ refetch: undefined;
160
+ analytics: undefined;
161
+ }
162
+ export interface IUseSurfsideProductsReturnGenericLoading<T> extends IUseSurfsideProductsReturnGeneric<T> {
163
+ loading: true;
164
+ error: undefined;
165
+ fetchNextPage: undefined;
166
+ refetch: undefined;
167
+ analytics: undefined;
168
+ }
169
+ /**
170
+ * @expandType IUseSurfsideProductsReturnGenericSuccess
171
+ */
172
+ export type UseSurfsideProductsReturnGeneric<T> = IUseSurfsideProductsReturnGenericSuccess<T> | IUseSurfsideProductsReturnGenericError<T> | IUseSurfsideProductsReturnGenericLoading<T>;
173
+ /** A discriminated union for the return type of useSurfsideProducts. Returns either product data or product IDs
174
+ *
175
+ * @expandType UseSurfsideProductsReturnGeneric
176
+ */
177
+ export type UseSurfsideProductsReturn = UseSurfsideProductsReturnGeneric<IProductInfoData> | UseSurfsideProductsReturnGeneric<IProductIDData>;
178
+ /**
179
+ * @overload
180
+ * @function useSurfsideProducts
181
+ * Fetches a page of product data and returns callbacks for requesting more and tracking clicks. If you pass
182
+ * `{ withProductData: true }`, or do not pass anything at all (i.e, `{ withProductData: undefined }`), this function
183
+ * overload will be called and the function will return all product data fields associated with the products in the feed
184
+ *
185
+ * @expandType UseSurfsideProductsPropsWithProductData
186
+ * @expandType IUseSurfsideProductsPropsBase
187
+ * @param {UseSurfsideProductsPropsWithProductData} props The page information and recommender strategy
188
+ */
189
+ export declare function useSurfsideProducts(props: UseSurfsideProductsPropsWithProductData): UseSurfsideProductsReturnGeneric<IProductInfoData>;
190
+ /**
191
+ * @overload
192
+ * @function useSurfsideProducts
193
+ * Fetches a page of product IDs and returns callbacks for requesting more and tracking clicks.
194
+ * If you pass `{ withProductData: false }`, this function overload will be called and the function will return only
195
+ * product IDs.
196
+ *
197
+ * @expandType UseSurfsideProductsPropsWithProductIDs
198
+ * @expandType IUseSurfsideProductsPropsBase
199
+ *
200
+ * @param {UseSurfsideProductsPropsWithProductIDs} props The page information and recommender strategy
201
+ */
202
+ export declare function useSurfsideProducts(props: UseSurfsideProductsPropsWithProductIDs): UseSurfsideProductsReturnGeneric<IProductIDData>;
203
+ export declare function useSurfsideProductsResponse(props: UseSurfsideProductsResponsePropsWithProductData): UseSurfsideProductsReturnGeneric<IProductInfoData>;
204
+ export declare function useSurfsideProductsResponse(props: UseSurfsideProductsResponsePropsWithProductIDs): UseSurfsideProductsReturnGeneric<IProductIDData>;
205
+ export declare function useSurfsideProductsResponse(props: UseSurfsideProductsResponseProps | undefined): UseSurfsideProductsReturn;
206
+ export declare class InvalidStrategyError extends Error {
207
+ readonly strategy: string;
208
+ constructor(strategy: string);
209
+ }
210
+ export declare class InvalidProductsStateError extends Error {
211
+ readonly products: IBuiltProductCardResponse[];
212
+ readonly error: ErrResult | undefined;
213
+ readonly loading: boolean;
214
+ constructor(products: IBuiltProductCardResponse[], error: ErrResult | undefined, loading: boolean);
215
+ }
@@ -0,0 +1,265 @@
1
+ import { type ErrResult, type IBuiltVideo, type Result } from '@surfside/ads-core-client';
2
+ /**
3
+ * The Video response object returned by `useSurfsideVideo`. Contains both a parsed Vast field (`vast`) and the raw vast
4
+ * XML response (`adm`), as well as some metadata about the video
5
+ */
6
+ export interface IVideo extends IBuiltVideo {
7
+ id: string;
8
+ title: string;
9
+ duration: string;
10
+ mime: string;
11
+ adm: string;
12
+ videoUrl: string;
13
+ }
14
+ /**
15
+ * Options for the {@link useSurfsideVideo} hook
16
+ */
17
+ export interface IUseSurfsideVideoOptions {
18
+ /**
19
+ * Zone ID for the video placement
20
+ */
21
+ zoneId: string;
22
+ /**
23
+ * The requested size of the video, in aspect ratio ([w, h] form, e.g `[4, 1]` for 4x1 or `[16, 9]` for 16x9).
24
+ */
25
+ size: [number, number];
26
+ /**
27
+ * The minimum requested duration of the video, in seconds. If no minimum is set, 0 will be used.
28
+ *
29
+ * @default 0
30
+ */
31
+ minDuration?: number;
32
+ /**
33
+ * The maxmimum requested duration of the video, in seconds.
34
+ */
35
+ maxDuration: number;
36
+ /**
37
+ * A list of [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types)
38
+ * requested for the video. If this field is not set, the default value will be `['video/mp4']`.
39
+ *
40
+ * @remarks
41
+ *
42
+ * Currently, Surfside only supports mp4 MIME types, but more formats may be added in the future.
43
+ * You should **always** add `video/mp4` to your MIME types if you specify this field, or your video ads
44
+ * may not work.
45
+ */
46
+ mimes?: string[];
47
+ /**
48
+ * Whether or not to request the video right away. Useful for lazy loading
49
+ * @default true
50
+ */
51
+ enabled?: boolean;
52
+ }
53
+ export type ISurfsideVideoEventHandler = () => void;
54
+ /**
55
+ * Event handlers for different video playback events. All events will be defined within this object, but if the Vast
56
+ * response does not have a URL for that tracker, calling the tracker function will simply do nothing.
57
+ */
58
+ export interface ISurfsideVideoAnalytics {
59
+ /**
60
+ * This event should be called when the video begins playback
61
+ */
62
+ start: ISurfsideVideoEventHandler;
63
+ /**
64
+ * This event should be called when the video completes 25% of the playback duration
65
+ */
66
+ firstQuartile: ISurfsideVideoEventHandler;
67
+ /**
68
+ * This event should be called when the video completes 50% of the playback duration
69
+ */
70
+ midpoint: ISurfsideVideoEventHandler;
71
+ /**
72
+ * this event should be called when the video completes 75% of the playback duration
73
+ */
74
+ thirdQuartile: ISurfsideVideoEventHandler;
75
+ /**
76
+ * This event should be called when the video completes 100% of the playback duration
77
+ */
78
+ complete: ISurfsideVideoEventHandler;
79
+ /**
80
+ * This event should be called when the video is added to the page
81
+ */
82
+ impression: ISurfsideVideoEventHandler;
83
+ /**
84
+ * This event should be called when the video is added to the page.
85
+ */
86
+ win: ISurfsideVideoEventHandler;
87
+ }
88
+ /**
89
+ * Return type for the {@link useSurfsideVideo} hook. The optional fields are narrowed by typescript when checking the
90
+ * `loading` and `error` fields within the {@link UseSurfsideVideoReturn} discriminated union
91
+ */
92
+ export interface IUseSurfsideVideoReturnBase {
93
+ /**
94
+ * Video data returned from the API.
95
+ *
96
+ * If `useSurfsideVideo` returns successfully, this will be given a value.
97
+ *
98
+ * If `useSurfsideVideo` fails or is currently loading, this will be set to undefined
99
+ */
100
+ video?: IVideo;
101
+ /**
102
+ * Whether the video is currently loading.
103
+ *
104
+ * If `useSurfsideVideo` returns successfully or fails, this will be false.
105
+ */
106
+ loading: boolean;
107
+ /**
108
+ * Error object if an error occurred during fetch.
109
+ *
110
+ * If `useSurfsideVideo` returns successfully, this will be set to `undefined`.
111
+ *
112
+ * If `useSurfsideVideo` fails or is currently loading, this will be given a value describing the error.
113
+ */
114
+ error?: ErrResult;
115
+ /**
116
+ * Fetch a new video using the original bid request. Useful for re-auctioning on a fixed interval.
117
+ *
118
+ * If `useSurfsideVideo` succeeds, this property will be given a value
119
+ *
120
+ * If `useSurfsideVideo` fails or is currently loading, this will be set to `undefined`.
121
+ *
122
+ * For an example workflow, see {@link IUseSurfsideBannerReturnSuccess}
123
+ */
124
+ refetch?: () => Promise<void>;
125
+ /**
126
+ * A set of callbacks for different video playback events.
127
+ *
128
+ * If `useSurfsideVideo` succeeds, this property will be given a value
129
+ *
130
+ * If `useSurfsideVideo` fails or is currently loading, this will be set to `undefined`.
131
+ */
132
+ analytics?: ISurfsideVideoAnalytics;
133
+ }
134
+ /**
135
+ * The return type for the success state of {@link useSurfsideVideo}.
136
+ */
137
+ export interface IUseSurfsideVideoReturnSuccess extends IUseSurfsideVideoReturnBase {
138
+ video: IVideo;
139
+ loading: false;
140
+ error: undefined;
141
+ refetch: () => Promise<void>;
142
+ analytics: ISurfsideVideoAnalytics;
143
+ }
144
+ /**
145
+ * The return type for the error state of {@link useSurfsideVideo}.
146
+ */
147
+ export interface IUseSurfsideVideoReturnError extends IUseSurfsideVideoReturnBase {
148
+ video: undefined;
149
+ loading: false;
150
+ error: ErrResult;
151
+ refetch: () => Promise<void>;
152
+ analytics: undefined;
153
+ }
154
+ /**
155
+ * The return type for the loading state of {@link useSurfsideVideo}.
156
+ */
157
+ export interface IUseSurfsideVideoReturnLoading extends IUseSurfsideVideoReturnBase {
158
+ video: undefined;
159
+ loading: true;
160
+ error: undefined;
161
+ refetch: () => Promise<void>;
162
+ analytics: undefined;
163
+ }
164
+ /**
165
+ * A discriminated union for the different states of {@link useSurfsideVideo}. To narrow these types, check if `loading`
166
+ * is `true` or if `error` is undefined. See {@link IUseSurfsideVideoReturnBase}
167
+ *
168
+ * @expandType IUseSurfsideVideoReturnSuccess
169
+ * @expandType IUseSurfsideVideoReturnError
170
+ * @expandType IUseSurfsideVideoReturnLoading
171
+ */
172
+ export type UseSurfsideVideoReturn = IUseSurfsideVideoReturnSuccess | IUseSurfsideVideoReturnError | IUseSurfsideVideoReturnLoading;
173
+ /**
174
+ * Requests and returns a video creative. Accepts size, duration, and MIME type arguments and returns an object wrapping
175
+ * the creative, exporting both a deserialized object representing the VAST 3.0 XML markup as well as the raw XML
176
+ * itself, which can be passed into video players supporting the VAST 3.0 XML specification. The return type also
177
+ * contains an `analytics` object which is a set of callback functions to be called for specific video playback events,
178
+ * such as completing each quartile of the video playback, recording impressions, and starting/finishing the video.
179
+ *
180
+ * @remarks
181
+ * Video players are more complicated to implement than static banner creatives because of their inherently interactive
182
+ * nature. Modern browsers will disallow videos from autoplaying unmuted, [except under specific circumstances](
183
+ * https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay#autoplay_availability). For this reason, it is
184
+ * recommended that you mark your `<video>` tag as `autoPlay muted`. e.g:
185
+ *
186
+ * ```html
187
+ * <video autoPlay muted>
188
+ * <!-- ... <source> tags go here -->
189
+ * </video>
190
+ * ```
191
+ *
192
+ * It is *possible* to autoplay a video unmuted under other circumstances, such as if the user has interacted with the
193
+ * page already. That implementation is left up to the developer.
194
+ *
195
+ * Surfside's bidder will always return with a single video creative per video bid request. This means that the
196
+ * `video.vast.ads` field will always have exactly one {@link IAd} object, and all VAST creative types will be a single
197
+ * `linear` video creative. This means that it will always be safe to do this:
198
+ *
199
+ * ```ts
200
+ * if (video !== undefined) {
201
+ * // URL of the video and its MIME type
202
+ * const { url, type } = video.ads[0].inline.creatives[0].mediaFiles[0];
203
+ * }
204
+ * ```
205
+ *
206
+ * Since this is somewhat verbose, these values are available to you through the `video.url` and `video.mime` fields
207
+ * within the {@link IVideo} object.
208
+ *
209
+ * @example
210
+ * A very simple video player for a video response might look like this
211
+ *
212
+ * ```tsx
213
+ * const { video, loading, error, analytics } = useSurfsideVideo({
214
+ * zoneId: 'my-zone',
215
+ * size: [4, 3], // 4x3 video ad
216
+ * maxDuration: 30 // 30 seconds max
217
+ * });
218
+ *
219
+ * // Call impression and win handlers if they exist
220
+ * useEffect(() => {
221
+ * analytics?.impression();
222
+ * analytics?.win();
223
+ * }, [analytics]);
224
+ *
225
+ * if (loading) {
226
+ * return <div>loading...</div>;
227
+ * }
228
+ *
229
+ * if (error) {
230
+ * throw error.error; // error.error is the Javascript Error type and can be safely thrown
231
+ * }
232
+ *
233
+ * return (
234
+ * <video autoplay muted>
235
+ * <source src={video.url} type={video.mime} />
236
+ * </video>
237
+ * );
238
+ * ```
239
+ *
240
+ * Note that this implementation ONLY implements the `win` and `impression` events. In order to implement playback-based
241
+ * events, you must write handlers for the [`play`, `ended`, and `timeupdate` events](
242
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video#events). For quartile playback events, you
243
+ * will need to check the current time of the video during the `timeupdate` events to determine if the proper quartile
244
+ * has been passed (e.g, `firstQuartile` must be fired **a single time, only after the video has surpassed 25% of its
245
+ * duration**).
246
+ *
247
+ * @param {IUseSurfsideVideoOptions} props
248
+ *
249
+ * @expandType IUseSurfsideVideoOptions
250
+ * @expandType UseSurfsideVideoReturn
251
+ */
252
+ export declare const useSurfsideVideo: ({ zoneId, size, minDuration, maxDuration, mimes, enabled }: IUseSurfsideVideoOptions) => UseSurfsideVideoReturn;
253
+ export type UseSurfsideVideoResponseProps = Omit<IUseSurfsideVideoOptions, 'minDuration' | 'mimes' | 'enabled'> & {
254
+ video: Result<IBuiltVideo> | undefined;
255
+ minDuration: number;
256
+ mimes: string[];
257
+ enabled: boolean;
258
+ };
259
+ export declare const useSurfsideVideoResponse: (props: UseSurfsideVideoResponseProps | undefined) => UseSurfsideVideoReturn;
260
+ export declare class InvalidVideoStateError extends Error {
261
+ readonly video: IVideo | undefined;
262
+ readonly error: ErrResult | undefined;
263
+ readonly loading: boolean;
264
+ constructor(video: IVideo | undefined, error: ErrResult | undefined, loading: boolean);
265
+ }
@@ -0,0 +1,3 @@
1
+ export * from './components';
2
+ export * from './provider';
3
+ export * from './hooks';
@@ -0,0 +1,140 @@
1
+ import React, { type ReactNode } from 'react';
2
+ import { type ILogger, type ErrResult } from '@surfside/ads-core';
3
+ import { type ISurfsideWebApi } from '@surfside/ads-core-web';
4
+ /**
5
+ * The arguments for initializing the Surfside ads context. user ID is optional because it is not always
6
+ * available at initialization time, but it can be set later via the context's `setIds` function.
7
+ * Location ID is also not always available at initialization time, so you can pass undefined. The API will
8
+ * not initialize until `setLocation` has been called
9
+ */
10
+ export interface ISurfsideProviderProps {
11
+ /** The Account ID of the publisher */
12
+ accountId: string;
13
+ /** The Channel ID of the publisher */
14
+ channelId: string;
15
+ /** The Site ID of the publisher */
16
+ siteId: string;
17
+ /** The Location ID of the current menu */
18
+ locationId: string | undefined;
19
+ /** The User ID of the current user logged into the site. This is the site's user ID, not Surfside's */
20
+ userId?: string;
21
+ /** An optional logger. If no logger is passed, but `config.debug` is set to true, a default logger will be used */
22
+ logger?: ILogger;
23
+ /** A set of optional configuration arguments */
24
+ config?: {
25
+ /** Whether or not to enable default logging */
26
+ debug?: boolean;
27
+ mock?: boolean;
28
+ };
29
+ /** A callback for when any surfside services return an error */
30
+ onError?: (error: ErrResult) => void;
31
+ children: ReactNode;
32
+ }
33
+ /**
34
+ * The returned context of the Surfside context provider. If the provider initializes successfully, API functions will
35
+ * be made available in the final return type of the context, and `isReady` will be set to `true`.
36
+ */
37
+ export interface ISurfsideContextValueBase extends Partial<ISurfsideWebApi> {
38
+ /**
39
+ * If there is an error during initialization, `hasError` will be set to true, and `error` will contain an object
40
+ * describing the error. Check `hasError` first to get a type guarantee about `error`
41
+ */
42
+ error?: ErrResult;
43
+ /**
44
+ * The current location ID set for the page
45
+ */
46
+ locationId?: string;
47
+ /**
48
+ * The current user ID set for the page
49
+ */
50
+ userId?: string;
51
+ setLocationId: (id: string) => void;
52
+ setUserId: (id: string) => void;
53
+ }
54
+ /**
55
+ * This state describes the successful initialization of the Surfside context object. if `isReady` is true, Surfside
56
+ * context will contain all the functions and identifiers from the Surfside API. If you check `if(isReady)`, typescript
57
+ * will narrow to this type, and you can safely call any functions from the Surfside API without checking if they are
58
+ * undefined first.
59
+ */
60
+ export type ISurfsideContextValueInitialized = ISurfsideContextValueBase & ISurfsideWebApi & {
61
+ /** A description of the status of the surfside context */
62
+ status: 'ready';
63
+ /** Indicates if the Surfside API is available or not */
64
+ isReady: true;
65
+ /** Indicates if any errors occurred */
66
+ hasError: false;
67
+ /** Indicates if the API is currently initializing */
68
+ isInitializing: false;
69
+ };
70
+ /**
71
+ * This describes any state in which the Surfside API is not available in the Surfside context. Either the API is
72
+ * still currently initializing (i.e, waiting on a network request to finish), there was an error (i.e, a network
73
+ * request failed) or initialization has not even begun (i.e, locationID was set to `undefined` and we are waiting for
74
+ * it to be set). Check `hasError`, `isInitializing`, or even `status` to get the exact state of initialization.
75
+ */
76
+ export type ISurfsideContextValueUninitialized = ISurfsideContextValueBase & {
77
+ /** A description of the status of the surfside context */
78
+ status: 'error' | 'initializing' | 'not-started';
79
+ /** Indicates if the Surfside API is available or not */
80
+ isReady: false;
81
+ /** Indicates if the API is currently initializing */
82
+ isInitializing: boolean;
83
+ };
84
+ /**
85
+ * This describes a state in which the API tried to initialize, but failed. If you check `if(hasError)` in your client
86
+ * code, Typescript will narrow to this type. Check the `error` object to get a description of the problem.
87
+ */
88
+ export interface ISurfsideContextValueHasError {
89
+ /**
90
+ * If there is an error during initialization, `hasError` will be set to true, and `error` will contain an object
91
+ * describing the error. Check `hasError` first to get a type guarantee about `error`
92
+ */
93
+ error: ErrResult;
94
+ /** A description of the status of the surfside context */
95
+ status: 'error';
96
+ /** Indicates if any errors occurred */
97
+ hasError: true;
98
+ /** Indicates if the API is currently initializing */
99
+ isInitializing: false;
100
+ }
101
+ /** This describes a state in which the Surfside API is unavailable, but no error has occurred. Either the API is
102
+ * currently initializing or has not begun to initialize (i.e, it is waiting on the location ID to be set). `error` will
103
+ * be set to `undefined` */
104
+ export interface ISurfsideContextValueNoError {
105
+ /**
106
+ * If there is an error during initialization, `hasError` will be set to true, and `error` will contain an object
107
+ * describing the error. Check `hasError` first to get a type guarantee about `error`
108
+ */
109
+ error: undefined;
110
+ /** A description of the status of the surfside context */
111
+ status: 'initializing';
112
+ /** Indicates if any errors occurred */
113
+ hasError: false;
114
+ /** Indicates if the API is currently initializing */
115
+ isInitializing: boolean;
116
+ }
117
+ /**
118
+ * This type describes the various states of the Surfside context and provides data or errors depending on the
119
+ * initialization status.
120
+ */
121
+ export type SurfsideContextValue = ISurfsideContextValueInitialized | (ISurfsideContextValueUninitialized & (ISurfsideContextValueHasError | ISurfsideContextValueNoError));
122
+ /**
123
+ * Returns the Surfside Context state, or throws an error if the context failed to return at all (i.e, you are calling
124
+ * useSurfsideContext outside of SurfsideProvider node)
125
+ *
126
+ * @throws {Error} If the context failed to initialize.
127
+ */
128
+ export declare const useSurfsideContext: () => SurfsideContextValue;
129
+ /**
130
+ * The provider for the Surfside ads context.
131
+ *
132
+ * @see {@link ISurfsideProviderProps}
133
+ */
134
+ export declare const SurfsideProvider: React.FC<ISurfsideProviderProps>;
135
+ export declare class InvalidStateError extends Error {
136
+ constructor();
137
+ }
138
+ export declare class NotInProviderError extends Error {
139
+ constructor();
140
+ }
@@ -0,0 +1 @@
1
+ export * from './SurfsideContextProvider';
@@ -0,0 +1,33 @@
1
+ export interface IResponsiveConfig {
2
+ mobile: number;
3
+ tablet?: number;
4
+ desktop?: number;
5
+ }
6
+ export interface IDynamicContent {
7
+ id: string;
8
+ html: string;
9
+ [key: string]: unknown;
10
+ }
11
+ export interface IClickAnalytics {
12
+ timestamp: number;
13
+ zoneId: string;
14
+ productId?: string;
15
+ bannerId?: string;
16
+ locationId?: string;
17
+ [key: string]: unknown;
18
+ }
19
+ export interface IImpressionAnalytics {
20
+ timestamp: number;
21
+ zoneId: string;
22
+ productIds?: string[];
23
+ bannerId?: string;
24
+ locationId?: string;
25
+ [key: string]: unknown;
26
+ }
27
+ export interface IBannerSize {
28
+ width: number;
29
+ height: number;
30
+ }
31
+ /**
32
+ * Interface for video object returned by the API
33
+ */