@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,67 @@
1
+ import React from 'react';
2
+ import { type ErrResult } from '@surfside/ads-core-client';
3
+ /**
4
+ * Props for the `SurfsideBanner` component. This component handles rendering of banner creatives
5
+ * from Surfside’s ad platform, managing their loading, display, and error states.
6
+ *
7
+ * You can customize styling, stateful UI, and lifecycle callbacks through these props.
8
+ *
9
+ * @example
10
+ * ```tsx
11
+ * <SurfsideBanner
12
+ * zoneId="my-zone"
13
+ * size={[4, 1]}
14
+ * renderLoading={() => <div>Loading Ad...</div>}
15
+ * renderError={() => <div>No Ad Available</div>}
16
+ * onRender={(id) => console.log(`Rendered banner: ${id}`)}
17
+ * onWin={(id) => console.log(`Win tracked: ${id}`)}
18
+ * />
19
+ * ```
20
+ */
21
+ export interface ISurfsideBannerProps {
22
+ /**
23
+ * The Zone ID of the advertisement
24
+ */
25
+ zoneId: string;
26
+ /**
27
+ * The requested size of the banner, in aspect ratio `[w, h]` (e.g., `[4, 1]`)
28
+ */
29
+ size: [number, number];
30
+ /**
31
+ * Whether or not the banner is enabled. If `false`, the component will render `null`.
32
+ * @default true
33
+ */
34
+ enabled?: boolean;
35
+ /**
36
+ * Optional render function for the loading state
37
+ */
38
+ renderLoading?: () => React.ReactNode;
39
+ /**
40
+ * Optional render function for the error or no-ad state
41
+ */
42
+ renderError?: () => React.ReactNode;
43
+ /**
44
+ * Callback invoked when a banner is successfully rendered
45
+ */
46
+ onRender?: (bannerId: string) => void;
47
+ /**
48
+ * Callback invoked when a win is tracked
49
+ */
50
+ onWin?: (bannerId: string) => void;
51
+ /**
52
+ * Callback invoked when an error occurs or no bid is returned
53
+ */
54
+ onError?: (error: ErrResult) => void;
55
+ }
56
+ /**
57
+ * SurfsideBanner renders a banner ad using the `useSurfsideBanner` hook. It automatically
58
+ * manages banner fetching, win tracking, and optional UI fallback states.
59
+ *
60
+ * Customize the banner lifecycle using callbacks and optionally inject custom styles
61
+ * or loading/error content.
62
+ *
63
+ * @param {ISurfsideBannerProps} props Props used to configure the banner rendering behavior
64
+ * @returns A responsive ad container that manages display and state transitions
65
+ */
66
+ export declare const SurfsideBanner: React.FC<ISurfsideBannerProps>;
67
+ export default SurfsideBanner;
@@ -0,0 +1,24 @@
1
+ import { type NativeRequestBuilder, type RequestBuilder } from '@surfside/ads-core';
2
+ import type { CarouselLimits } from '@surfside/ads-core-web';
3
+ export interface ISurfsideCarouselRenderProps {
4
+ cardMinWidth: number;
5
+ carouselLimits: CarouselLimits;
6
+ nextType: 'page' | 'product';
7
+ }
8
+ export interface ISurfsideCarouselPropsBase extends ISurfsideCarouselRenderProps {
9
+ zoneId: string;
10
+ requestBuilder?: RequestBuilder;
11
+ nativeRequestBuilder?: NativeRequestBuilder;
12
+ recommender?: 'top-products' | 'for-you' | 'past-purchases';
13
+ enabled?: boolean;
14
+ }
15
+ export interface ISurfsideCarouselPropsRecommended extends ISurfsideCarouselPropsBase {
16
+ strategy: 'hybrid' | 'recommended';
17
+ recommender: 'top-products' | 'for-you' | 'past-purchases';
18
+ }
19
+ export interface ISurfsideCarouselPropsSponsored extends ISurfsideCarouselPropsBase {
20
+ strategy: 'sponsored';
21
+ recommender: undefined;
22
+ }
23
+ export type SurfsideCarouselProps = ISurfsideCarouselPropsRecommended | ISurfsideCarouselPropsSponsored;
24
+ export declare const SurfsideCarousel: ({ zoneId, cardMinWidth, carouselLimits, nextType, recommender, requestBuilder, nativeRequestBuilder, enabled, strategy }: SurfsideCarouselProps) => import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,12 @@
1
+ import { type ErrResult } from '@surfside/ads-core';
2
+ import { type ISurfsideCarouselRenderProps } from './SurfsideCarousel';
3
+ export interface ISurfsideDynamicZoneComponentProps {
4
+ zoneId: string;
5
+ enabled?: boolean;
6
+ carousel: ISurfsideCarouselRenderProps;
7
+ onError?: (error: ErrResult) => void;
8
+ }
9
+ export declare const SurfsideDynamicZone: ({ zoneId, carousel, enabled, onError }: ISurfsideDynamicZoneComponentProps) => import("react/jsx-runtime").JSX.Element;
10
+ export declare class DynamicZoneUnmountedError extends Error {
11
+ constructor();
12
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,72 @@
1
+ import { type RequestBuilder, type ErrResult } from '@surfside/ads-core-client';
2
+ /**
3
+ * Props for the `SurfsideVideo` component. This component handles rendering of video creatives
4
+ * from Surfside’s ad platform, managing their loading, display, and error states.
5
+ *
6
+ * You can customize styling, stateful UI, and lifecycle callbacks through these props.
7
+ *
8
+ * @example
9
+ * ```tsx
10
+ * <SurfsideVideo
11
+ * zoneId="my-zone"
12
+ * size={[4, 1]}
13
+ * renderLoading={() => <div>Loading Ad...</div>}
14
+ * renderError={() => <div>No Ad Available</div>}
15
+ * onRender={(id) => console.log(`Rendered video: ${id}`)}
16
+ * onWin={(id) => console.log(`Win tracked: ${id}`)}
17
+ * />
18
+ * ```
19
+ */
20
+ export interface ISurfsideVideoProps {
21
+ /**
22
+ * The Zone ID of the advertisement
23
+ */
24
+ zoneId: string;
25
+ /**
26
+ * The requested size of the video, in aspect ratio `[w, h]` (e.g., `[4, 1]`)
27
+ */
28
+ size: [number, number];
29
+ /**
30
+ * The minimum requested duration of the video, in seconds. If no minimum is set, 0 will be used.
31
+ *
32
+ * @default 0
33
+ */
34
+ minDuration?: number;
35
+ /**
36
+ * The maxmimum requested duration of the video, in seconds.
37
+ */
38
+ maxDuration: number;
39
+ /**
40
+ * A list of [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types)
41
+ * requested for the video. If this field is not set, the default value will be `['video/mp4']`.
42
+ *
43
+ * @remarks
44
+ *
45
+ * Currently, Surfside only supports mp4 MIME types, but more formats may be added in the future.
46
+ * You should **always** add `video/mp4` to your MIME types if you specify this field, or your video ads
47
+ * may not work.
48
+ */
49
+ mimes?: string[];
50
+ /**
51
+ * Whether or not the video is enabled. If `false`, the component will render `null`.
52
+ * @default true
53
+ */
54
+ enabled?: boolean;
55
+ /**
56
+ * Callback invoked when an error occurs or no bid is returned
57
+ */
58
+ onError?: (error: ErrResult) => void;
59
+ requestBuilder?: RequestBuilder;
60
+ }
61
+ /**
62
+ * SurfsideVideo renders a video ad using the `useSurfsideVideo` hook. It automatically
63
+ * manages video fetching, win tracking, and optional UI fallback states.
64
+ *
65
+ * Customize the video lifecycle using callbacks and optionally inject custom styles
66
+ * or loading/error content.
67
+ *
68
+ * @param {ISurfsideVideoProps} props Props used to configure the video rendering behavior
69
+ * @returns A responsive ad container that manages display and state transitions
70
+ */
71
+ export declare const SurfsideVideo: ({ zoneId, size, minDuration, maxDuration, mimes, enabled, requestBuilder, onError }: ISurfsideVideoProps) => import("react/jsx-runtime").JSX.Element;
72
+ export default SurfsideVideo;
@@ -0,0 +1,5 @@
1
+ export * from './SurfsideBanner';
2
+ export * from './SurfsideCarousel';
3
+ export * from './SurfsideDynamicZone';
4
+ export * from './SurfsideProduct';
5
+ export * from './SurfsideVideo';
@@ -0,0 +1,4 @@
1
+ export * from './useSurfsideBanner';
2
+ export * from './useSurfsideDynamicZone';
3
+ export * from './useSurfsideProducts';
4
+ export * from './useSurfsideVideo';
@@ -0,0 +1,7 @@
1
+ import { IUseSurfDynamicZoneOptions, UseSurfDynamicZoneReturn } from '../types';
2
+ /**
3
+ * Hook for working with Surfside dynamic zones
4
+ * Provides data and rendering functions for dynamic content zones
5
+ */
6
+ export declare const useSurfDynamicZone: ({ zoneId, enabled }: IUseSurfDynamicZoneOptions) => UseSurfDynamicZoneReturn;
7
+ export default useSurfDynamicZone;
@@ -0,0 +1,252 @@
1
+ import { type ErrResult, type IBuiltBannerResponse, type Result } from '@surfside/ads-core-client';
2
+ /**
3
+ * A banner creative returned by `useSurfsideBanner`. `adm` is a string with the HTML content of the banner ready for
4
+ * injection into the DOM. It is recommended that you inject the `adm` field into an HTML element with
5
+ * [`dangerouslySetInnerHTML`](
6
+ * https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html
7
+ * )
8
+ *
9
+ * @expandType IBuiltBannerResponse
10
+ *
11
+ * @example
12
+ * ```tsx
13
+ * const [banner, error, analytics] = useSurfsideBanner({
14
+ * zoneId: 'my-zone',
15
+ * size: [16, 9]
16
+ * });
17
+ *
18
+ * if(banner !== undefined) {
19
+ * return (
20
+ * <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>
21
+ * );
22
+ * }
23
+ * ```
24
+ *
25
+ * @expandType IBuiltBannerResponse
26
+ */
27
+ export interface IBanner extends IBuiltBannerResponse {
28
+ /** The ID of the bid response */
29
+ id: string;
30
+ }
31
+ /**
32
+ * The parameters used to configure `useSurfsideBanner`
33
+ */
34
+ export interface IUseSurfsideBannerOptions {
35
+ /**
36
+ * The Zone ID of the advertisement
37
+ */
38
+ zoneId: string;
39
+ /**
40
+ * The requested size of the placement, in aspect ratio [w, h] (i.e, `[16, 9]` or `[4, 1]`)
41
+ */
42
+ size: [number, number];
43
+ /**
44
+ * Whether or not to request the banner right away. Useful for lazy loading
45
+ * @default true
46
+ */
47
+ enabled?: boolean;
48
+ }
49
+ /**
50
+ * Callbacks for handling the win event for a banner. Impressions are automatically triggered via tracking pixel
51
+ * when the banner is added to the page and clicks are automatically handled via an `<a>` tag added to the adm field
52
+ * of the banner
53
+ */
54
+ export interface IBannerAnalyticsCallbacks {
55
+ trackWin: () => void;
56
+ }
57
+ /**
58
+ * The base return type for {@link useSurfsideBanner}. There are two child interfaces which represent the distinct
59
+ * states of `useSurfsideBanner`: {@link IUseSurfsideBannerReturnSuccess} (for successful states) and
60
+ * {@link IUseSurfsideBannerReturnError} (for error states). For documentation on both, see
61
+ * {@link UseSurfsideBannerReturn}.
62
+ *
63
+ * @expandType IBannerAnalyticsCallbacks
64
+ *
65
+ * @see UseSurfsideBannerReturn
66
+ */
67
+ export interface IUseSurfsideBannerReturn {
68
+ /**
69
+ * The banner creative and associated data. On success, this will be set to a value. On error, this will be
70
+ * `undefined`.
71
+ *
72
+ * For an example workflow, see {@link IBanner}
73
+ */
74
+ banner?: IBanner;
75
+ /**
76
+ * Indicates if Surfside ads is still fetching the banner from the bidder. On success and error, this is set to
77
+ * `false`.
78
+ */
79
+ loading: boolean;
80
+ /**
81
+ * Indicates if there was an error during the bidding process. If the bidder returns no ads, this will be set to
82
+ * {@link NoBidsError}.
83
+ *
84
+ * For an example workflow, see {@link IUseSurfsideBannerReturnError}
85
+ */
86
+ error?: ErrResult;
87
+ /**
88
+ * Fetch a new banner using the original bid request. Useful for re-auctioning on a fixed interval.
89
+ *
90
+ * `refetch` is always defined; you can call it at any time.
91
+ *
92
+ * If `enabled` is `false` or the provider ins't ready, `refetch` simple returns without making a network request.
93
+ *
94
+ * For an example workflow, see {@link IUseSurfsideBannerReturnSuccess}
95
+ */
96
+ refetch?: () => Promise<void>;
97
+ /**
98
+ * A set of functions to call for manually handling auction events.
99
+ *
100
+ * If `useSurfsideBanner` succeeds, this property will be set to a value
101
+ *
102
+ * If `useSurfsideBanner` fails with an error state, this will be set to `undefined`.
103
+ */
104
+ analytics?: IBannerAnalyticsCallbacks;
105
+ }
106
+ /**
107
+ * The success state version of the return type for `useSurfsideBanner`
108
+ */
109
+ export interface IUseSurfsideBannerReturnSuccess extends IUseSurfsideBannerReturn {
110
+ banner: IBanner;
111
+ loading: false;
112
+ error: undefined;
113
+ analytics: IBannerAnalyticsCallbacks;
114
+ /**
115
+ * Fetch a new banner using the original bid request. Useful for re-auctioning on a fixed interval.
116
+ *
117
+ * `refetch` is always defined; you can call it at any time.
118
+ *
119
+ * If `enabled` is `false` or the provider ins't ready, `refetch` simple returns without making a network request.
120
+ *
121
+ * @example
122
+ * ```tsx
123
+ * const { banner, refetch } = useSurfsideBanner(
124
+ * zoneId: 'my-zone',
125
+ * size: [16, 9]
126
+ * );
127
+ *
128
+ * useEffect(() => {
129
+ * const timer = setTimeout(refetch, 30000); // re-auction in 30s.
130
+ * return () => clearTimeout(timer); // cleanup after next run
131
+ * }, [refetch])
132
+ *
133
+ * return (
134
+ * <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>
135
+ * );
136
+ * ```
137
+ */
138
+ refetch: () => Promise<void>;
139
+ }
140
+ /**
141
+ * The error state version of the return type for `useSurfsideBanner`.
142
+ */
143
+ export interface IUseSurfsideBannerReturnError extends IUseSurfsideBannerReturn {
144
+ banner: undefined;
145
+ /**
146
+ *
147
+ * Indicates if there was an error during the bidding process. If the bidder returns no ads, this will be set to
148
+ * {@link NoBidsError}.
149
+ * @example
150
+ * All errors in surfside ads are class types, so to handle errors, use this pattern
151
+ *
152
+ * ```tsx
153
+ * const { banner, error, loading } = useSurfsideBanner({
154
+ * zoneId: 'my-zone',
155
+ * size: [16, 9]
156
+ * });
157
+ *
158
+ * if(loading) {
159
+ * return <></>;
160
+ * }
161
+ *
162
+ * if (error !== undefined) {
163
+ * if (error instanceof NoBidsError) { // Not a big problem - just don't render anything
164
+ * console.log("Bidder returned nothing - not rendering banner");
165
+ * return <></>;
166
+ * } else { // Actual error - Bidder returned an error code
167
+ * throw error.error; // `error.error` is the actual javascript error type
168
+ * }
169
+ * }
170
+ *
171
+ * // ... render banner here
172
+ * ```
173
+ */
174
+ error: ErrResult;
175
+ loading: false;
176
+ analytics: undefined;
177
+ refetch: () => Promise<void>;
178
+ }
179
+ /**
180
+ * The loading state version of the return type for `useSurfsideBanner`.
181
+ */
182
+ export interface IUseSurfsideBannerReturnLoading extends IUseSurfsideBannerReturn {
183
+ banner: undefined;
184
+ error: undefined;
185
+ /**
186
+ * Indicates if Surfside ads is still fetching the banner from the bidder. On success and error, this is set to
187
+ * `false`.
188
+ */
189
+ loading: true;
190
+ analytics: undefined;
191
+ refetch: () => Promise<void>;
192
+ }
193
+ /**
194
+ * Discriminated union representing the three output states of {@link useSurfsideBanner}.
195
+ *
196
+ * When `useSurfsideBanner` returns successfully, {@link IUseSurfsideBannerReturnSuccess} returns, and the `banner` and
197
+ * `analytics` fields are given values.
198
+ *
199
+ * If `useSurfsideBanner` fails, {@link IUseSurfsideBannerReturnError} returns, the `banner` and `analytics` fields are
200
+ * set to `undefined`, and the `error` field is given a value.
201
+ * @expandType IUseSurfsideBannerReturnSuccess
202
+ * @expandType IUseSurfsideBannerReturnError
203
+ * @expandType IUseSurfsideBannerReturnLoading
204
+ */
205
+ export type UseSurfsideBannerReturn = IUseSurfsideBannerReturnSuccess | IUseSurfsideBannerReturnError | IUseSurfsideBannerReturnLoading;
206
+ /**
207
+ * Requests and returns a banner creative. Accepts a size argument and returns an object wrapping the creative markup
208
+ * (called the `adm`) and some analytics callbacks for tracking auction events, as well as metadata such as the original
209
+ * bid response which creatived the banner.
210
+ *
211
+ * For documentation on the return values and possible states of this hook, see {@link UseSurfsideBannerReturn}.
212
+ *
213
+ * @example
214
+ * To request a banner and display it, pass a desired creative aspect ratio and check the status of the hook, then
215
+ * render when the banner has returned successfully
216
+ *
217
+ * ```tsx
218
+ * const { banner, loading, error, analytics } = useSurfsideBanner({
219
+ * zoneId: 'my-zone',
220
+ * size: [4, 1] // 4x1 banner
221
+ * })
222
+ *
223
+ * // Track win event
224
+ * useEffect(() => analytics?.trackWin(banner), [analytics]);
225
+ *
226
+ * if (loading) {
227
+ * return <div>Loading...</div>
228
+ * }
229
+ *
230
+ * if (error !== undefined) {
231
+ * throw error.error; // error.error is the Javascript "Error" type which can be safely thrown
232
+ * }
233
+ *
234
+ * return <div dangerouslySetInnerHTML={{ __html: banner.adm }}></div>;
235
+ * ```
236
+ *
237
+ * @expandType IUseSurfsideBannerOptions
238
+ * @expandType UseSurfsideBannerReturn
239
+ *
240
+ * @param {IUseSurfsideBannerOptions} params
241
+ */
242
+ export declare const useSurfsideBanner: ({ zoneId, size, enabled }: IUseSurfsideBannerOptions) => UseSurfsideBannerReturn;
243
+ export interface IUseSurfsideBannerResponseProps extends IUseSurfsideBannerOptions {
244
+ banner: Result<IBuiltBannerResponse> | undefined;
245
+ }
246
+ export declare const useSurfsideBannerResponse: (props: IUseSurfsideBannerResponseProps | undefined) => UseSurfsideBannerReturn;
247
+ export declare class InvalidBannerStateError extends Error {
248
+ readonly banner: IBanner | undefined;
249
+ readonly error: ErrResult | undefined;
250
+ readonly loading: boolean;
251
+ constructor(banner: IBanner | undefined, error: ErrResult | undefined, loading: boolean);
252
+ }
@@ -0,0 +1,179 @@
1
+ import { type ErrResult } from '@surfside/ads-core-client';
2
+ import { type IProductIDData, type IProductInfoData, type IUseSurfsideProductsReturnGenericSuccess, type IUseSurfsideBannerReturnSuccess, type UseSurfsideProductsReturn, type UseSurfsideVideoReturn } from '../hooks';
3
+ /**
4
+ * Options for dynamic zones to pass through to the underlying `useSurfsideProducts` hook.
5
+ */
6
+ export interface IUseSurfsideDynamicZoneOptionsConfigProductOptions {
7
+ /**
8
+ * If true, `useDSurfsideDynamicZone` will map product feed results to their full product data fields, including
9
+ * name, description, price, etc.
10
+ *
11
+ * If false, `useDSurfsideDynamicZone` will return only product IDs
12
+ * @defaultValue true
13
+ *
14
+ */
15
+ withProductInfo?: boolean;
16
+ pageSize: number;
17
+ }
18
+ /**
19
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigProductOptions
20
+ */
21
+ export interface IUseSurfsideDynamicZoneOptionsConfigWithProductInfo extends IUseSurfsideDynamicZoneOptionsConfigProductOptions {
22
+ withProductInfo?: true;
23
+ }
24
+ /**
25
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigProductOptions
26
+ */
27
+ export interface IUseSurfsideDynamicZoneOptionsConfigWithProductIDs extends IUseSurfsideDynamicZoneOptionsConfigProductOptions {
28
+ withProductInfo: false;
29
+ }
30
+ /**
31
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductInfo
32
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductIDs
33
+ */
34
+ export type UseSurfsideDynamicZoneOptionsConfigProductInfo = IUseSurfsideDynamicZoneOptionsConfigWithProductInfo | IUseSurfsideDynamicZoneOptionsConfigWithProductIDs;
35
+ export type UseSurfDynamicZoneOptionsBase = {
36
+ /** The Zone ID for the advertisement */
37
+ zoneId: string;
38
+ /** Whether or not to request the dynamic zone right away. Useful for lazy loading */
39
+ enabled?: boolean;
40
+ };
41
+ /**
42
+ * @expandType UseSurfDynamicZoneOptionsBase
43
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductInfo
44
+ */
45
+ export type UseSurfDynamicZoneOptionsWithProductInfo = UseSurfDynamicZoneOptionsBase & IUseSurfsideDynamicZoneOptionsConfigWithProductInfo;
46
+ /**
47
+ * @expandType UseSurfDynamicZoneOptionsBase
48
+ * @expandType IUseSurfsideDynamicZoneOptionsConfigWithProductIDs
49
+ */
50
+ export type UseSurfDynamicZoneOptionsWithProductIDs = UseSurfDynamicZoneOptionsBase & IUseSurfsideDynamicZoneOptionsConfigWithProductIDs;
51
+ /**
52
+ * @expandType UseSurfDynamicZoneOptionsWithProductIDs
53
+ * @expandType UseSurfDynamicZoneOptionsWithProductInfo
54
+ */
55
+ export type UseSurfDynamicZoneOptions = UseSurfDynamicZoneOptionsWithProductIDs | UseSurfDynamicZoneOptionsWithProductInfo;
56
+ /**
57
+ * The return type for `useSurfsideDynamicZone`. Returns different creatives in the `data` field depending on the result
58
+ * of the dynamic zone selection process.
59
+ */
60
+ export interface IUseDynamicZoneReturnBase<T> {
61
+ /**
62
+ * The type of creative returned by the dynamic zone. When the dynamic zone is still loading, this will be
63
+ * `undefined`. If the dynamic zone fails, this will be `undefined`.
64
+ */
65
+ type?: 'banner' | 'video' | 'products';
66
+ /**
67
+ * Indicates if the dynamic zone is still loading or not. If the dynamic zone is done loading or fails, this will be
68
+ * `false`.
69
+ */
70
+ loading: boolean;
71
+ /**
72
+ * Indicates if there was an error while loading the dynamic zone. If there was an error, this will be set to a
73
+ * value indicating the type of error
74
+ */
75
+ error?: ErrResult;
76
+ /**
77
+ * Re-trigger the dynamic zone creative selection process. If the dynamic zone loads successfully, this will be set
78
+ * to a value. If the dynamic zone is still loading or fails, this will be set to `undefined`.
79
+ *
80
+ * @remarks
81
+ *
82
+ * This callback will re-trigger the *creative selection process*. This means that if your dynamic zone can return,
83
+ * for example, a carousel *or* a banner, then calling this function may result in switching creative types (i.e,
84
+ * from banner to carousel), which may be a poor user experience. It is recommended that if you want to enable
85
+ * re-auctioning for the returned creative type, you use the `refetch` callback in the underlying creative type.
86
+ */
87
+ refetchDynamicZone?: () => Promise<void>;
88
+ /**
89
+ * The returned creative data for the dynamic zone. Either a banner, video, or products response. If the dynamic
90
+ * zone returns successfully, this will be set to a value. If the dynamic zone is still loading or fails, this will
91
+ * be set to `undefined`.
92
+ */
93
+ data?: T;
94
+ }
95
+ /**
96
+ * @expandType IUseDynamicZoneReturnBase
97
+ */
98
+ export interface IUseDynamicZoneReturnSuccess<T> extends IUseDynamicZoneReturnBase<T> {
99
+ type: 'banner' | 'video' | 'products';
100
+ loading: false;
101
+ error: undefined;
102
+ refetchDynamicZone: () => Promise<void>;
103
+ data: T;
104
+ }
105
+ /**
106
+ * @expandType IUseDynamicZoneReturnBase
107
+ */
108
+ export interface IUseDynamicZoneReturnError extends IUseDynamicZoneReturnBase<undefined> {
109
+ type: undefined;
110
+ loading: false;
111
+ error: ErrResult;
112
+ data: undefined;
113
+ }
114
+ export interface IUseDynamicZoneReturnLoading extends IUseDynamicZoneReturnBase<undefined> {
115
+ type: undefined;
116
+ loading: true;
117
+ error: undefined;
118
+ data: undefined;
119
+ }
120
+ /**
121
+ * The banner response type for a dynamic zone hook
122
+ * @expandType IUseDynamicZoneReturnSuccess
123
+ */
124
+ export interface IUseDynamicZoneReturnBanner extends IUseDynamicZoneReturnSuccess<IUseSurfsideBannerReturnSuccess> {
125
+ type: 'banner';
126
+ /**
127
+ * A successful banner response type from the {@link useSurfsideBanner} hook.
128
+ */
129
+ data: IUseSurfsideBannerReturnSuccess;
130
+ }
131
+ /**
132
+ * @expandType IUseDynamicZoneReturnSuccess
133
+ */
134
+ export interface IUseDynamicZoneReturnVideo extends IUseDynamicZoneReturnSuccess<UseSurfsideVideoReturn> {
135
+ type: 'video';
136
+ /**
137
+ * A successful video response type from the {@link useSurfsideVideo} hook.
138
+ */
139
+ data: UseSurfsideVideoReturn;
140
+ }
141
+ /**
142
+ * @expandType IUseDynamicZoneReturnSuccess
143
+ */
144
+ export interface IUseDynamicZoneReturnProducts<T> extends IUseDynamicZoneReturnSuccess<IUseSurfsideProductsReturnGenericSuccess<T>> {
145
+ type: 'products';
146
+ /**
147
+ * A successful product response type from the {@link useSurfsideProducts} hook. The generic type for this response
148
+ * depends on the value of `withProductInfo` from {@link UseSurfDynamicZoneOptions}.
149
+ */
150
+ data: IUseSurfsideProductsReturnGenericSuccess<T>;
151
+ }
152
+ export interface IUseDynamicZoneReturnProductsIndeterminate extends IUseDynamicZoneReturnSuccess<UseSurfsideProductsReturn> {
153
+ type: 'products';
154
+ }
155
+ /**
156
+ * @expandType IUseDynamicZoneReturnBanner
157
+ * @expandType IUseDynamicZoneReturnVideo
158
+ * @expandType IUseDynamicZoneReturnProducts
159
+ */
160
+ export type UseSurfDynamicZoneReturnGeneric<T> = IUseDynamicZoneReturnBanner | IUseDynamicZoneReturnVideo | IUseDynamicZoneReturnProducts<T> | IUseDynamicZoneReturnError | IUseDynamicZoneReturnLoading;
161
+ /**
162
+ * @expandType UseSurfDynamicZoneReturnGeneric
163
+ */
164
+ export type UseSurfDynamicZoneReturn = IUseDynamicZoneReturnBanner | IUseDynamicZoneReturnVideo | IUseDynamicZoneReturnProductsIndeterminate | IUseDynamicZoneReturnError | IUseDynamicZoneReturnLoading;
165
+ export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptionsWithProductInfo): UseSurfDynamicZoneReturnGeneric<IProductInfoData>;
166
+ /**
167
+ * @overload
168
+ *
169
+ * Returns a typed version of the `UseSurfsideDynamicZoneReturn` populated with full product IDs, if products are
170
+ * available. If you pass `withProductInfo: false` to props, this overload will be used.
171
+ * @param {UseSurfDynamicZoneOptionsWithProductIDs} props
172
+ * @expandType UseSurfDynamicZoneOptionsWithProductIDs
173
+ */
174
+ export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptionsWithProductIDs): UseSurfDynamicZoneReturnGeneric<IProductIDData>;
175
+ export declare function useSurfsideDynamicZone(props: UseSurfDynamicZoneOptions): UseSurfDynamicZoneReturn;
176
+ export declare class InvalidDynamicZoneState extends Error {
177
+ readonly zoneId: string;
178
+ constructor(zoneId: string);
179
+ }