@moonbase.sh/react 0.0.0 → 1.2.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.
- package/README.md +127 -16
- package/dist/index.cjs +2002 -0
- package/dist/index.d.cts +910 -0
- package/dist/index.d.ts +910 -0
- package/dist/index.js +2005 -0
- package/package.json +42 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,910 @@
|
|
|
1
|
+
import { User, Address, SignUpOptions, SignUpResult, CommunicationPreferences, UserAccountConfirmed, ConnectableAccountProvider, CheckoutRedirectMode, StorefrontProduct, StorefrontBundle, PricingVariation, StorefrontOffer, LineItem, MoonbaseConfiguration, Storefront, MoonbaseClient, Order, UrchinTrackingModule, OpenOrder, Money, CheckoutPaymentFailure, CompletedOrder, AdConsentReport, AdSignals, OfferConditionContext, StorefrontPromotion, OfferProgress, OwnedProduct, Activation, License, Subscription, ActivationRequest, CartTotal, SubscribeInput, CommunicationPreferencesInput, ActivationMethod, Download, SubscriptionCancellationFeedback, Page, PriceFormat, ProductReviewSort, SubmitReviewRequest, ReviewVoteDirection, Vendor, Voucher } from '@moonbase.sh/storefront-api';
|
|
2
|
+
export * from '@moonbase.sh/storefront-api';
|
|
3
|
+
import { ReactNode } from 'react';
|
|
4
|
+
|
|
5
|
+
interface StorefrontAuth {
|
|
6
|
+
signIn: (email: string, password: string) => Promise<User>;
|
|
7
|
+
/**
|
|
8
|
+
* Creates the customer's account. Sends the UTM tags, campaign IDs, ad click IDs (only with consent)
|
|
9
|
+
* and referrer the visitor arrived with, and the ad signals, as the cart and checkout do, unless
|
|
10
|
+
* `options` names its own `utm` or `signals`. Signs them in straight away unless the store asks new
|
|
11
|
+
* customers to confirm their email first.
|
|
12
|
+
*/
|
|
13
|
+
signUp: (name: string, email: string, password: string, address: Address | null | undefined, acceptedPrivacyPolicy: boolean, acceptedTermsAndConditions: boolean, communicationOptIn?: boolean, options?: SignUpOptions) => Promise<SignUpResult>;
|
|
14
|
+
/**
|
|
15
|
+
* Signs the customer out. The cart stays, under a new ID, so it is no longer tied to them and can't
|
|
16
|
+
* be claimed by the next person who signs in on this browser.
|
|
17
|
+
*/
|
|
18
|
+
signOut: () => Promise<void>;
|
|
19
|
+
/**
|
|
20
|
+
* The signed-in customer's access token, renewed first if it is about to run out, or null when
|
|
21
|
+
* nobody is signed in. For calling your own API on their behalf.
|
|
22
|
+
*/
|
|
23
|
+
getAccessToken: () => Promise<string | null>;
|
|
24
|
+
/** Changes the customer's name, email or communication preferences. A null name leaves it as it is. */
|
|
25
|
+
update: (name: string | null, email: string, emailConfirmationToken?: string, communicationPreferences?: CommunicationPreferences) => Promise<{
|
|
26
|
+
user: User;
|
|
27
|
+
needsEmailConfirmationToken: boolean;
|
|
28
|
+
}>;
|
|
29
|
+
/** Saves the signed-in customer's address, which their next checkout starts from. */
|
|
30
|
+
updateAddress: (address: Address) => Promise<User>;
|
|
31
|
+
setPassword: (currentPassword: string, newPassword: string) => Promise<void>;
|
|
32
|
+
forgotPassword: (email: string) => Promise<void>;
|
|
33
|
+
resetPassword: (email: string, newPassword: string, code: string) => Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Confirms a new account from the code in its welcome email, which signs the customer in. A code works
|
|
36
|
+
* once, so calling this again with the same email and code, while the first call is in flight or for
|
|
37
|
+
* a few seconds after, hands back the first call's result rather than asking Moonbase twice: a page
|
|
38
|
+
* confirming as it loads can be run twice by React. The same goes for `confirmEmail` and
|
|
39
|
+
* `confirmEmailChange`.
|
|
40
|
+
*/
|
|
41
|
+
confirmAccount: (email: string, code: string) => Promise<UserAccountConfirmed>;
|
|
42
|
+
confirmEmail: (email: string, code: string) => Promise<void>;
|
|
43
|
+
confirmEmailChange: (email: string, code: string) => Promise<User | null>;
|
|
44
|
+
getConnectionUrl: (provider: ConnectableAccountProvider, redirectUri: string, loginId?: string) => Promise<string>;
|
|
45
|
+
disconnectAccount: (provider: ConnectableAccountProvider) => Promise<User | null>;
|
|
46
|
+
/** Asks Moonbase who is signed in again. */
|
|
47
|
+
refreshUser: () => Promise<User | null>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
interface CheckoutItem {
|
|
51
|
+
item: StorefrontProduct | StorefrontBundle;
|
|
52
|
+
/** The pricing option to buy it at. The default one when left out. */
|
|
53
|
+
variation?: PricingVariation;
|
|
54
|
+
quantity?: number;
|
|
55
|
+
/**
|
|
56
|
+
* The customer's license this purchase upgrades or renews, for a product whose licenses cover only
|
|
57
|
+
* some releases. Buying it extends that license instead of issuing another, at the price the
|
|
58
|
+
* storefront quotes for that license. Always a quantity of 1. Products only. Left out, the purchase
|
|
59
|
+
* issues new licenses.
|
|
60
|
+
*/
|
|
61
|
+
targetLicenseId?: string;
|
|
62
|
+
}
|
|
63
|
+
interface CheckoutResult {
|
|
64
|
+
/** Where the checkout suggested going next, if anywhere. */
|
|
65
|
+
next: string | undefined;
|
|
66
|
+
completed: boolean;
|
|
67
|
+
/**
|
|
68
|
+
* The buyer was sent to the hosted checkout by a full-page navigation, so this call can't report an
|
|
69
|
+
* outcome: the result arrives on the return page, as a `checkoutCompleted` event. Don't treat
|
|
70
|
+
* `completed: false` as a failure when this is set.
|
|
71
|
+
*/
|
|
72
|
+
redirected: boolean;
|
|
73
|
+
}
|
|
74
|
+
interface CheckoutRedirectOptions {
|
|
75
|
+
/**
|
|
76
|
+
* Where the checkout happens. `'auto'`, the default, opens it over the page on a computer and sends
|
|
77
|
+
* a phone to Moonbase's own checkout page, where Apple Pay and Google Pay work: those wallets need the
|
|
78
|
+
* checkout to be the top-level page. `'always'` (or `true`) always sends the buyer there, `'never'`
|
|
79
|
+
* (or `false`) always opens it over the page.
|
|
80
|
+
*/
|
|
81
|
+
redirect?: boolean | CheckoutRedirectMode;
|
|
82
|
+
/** Where a buyer sent to the hosted checkout comes back to. This page, by default, query and all. */
|
|
83
|
+
returnUrl?: string;
|
|
84
|
+
}
|
|
85
|
+
interface CheckoutOptions extends CheckoutRedirectOptions {
|
|
86
|
+
/** A coupon to apply. One the API refuses is reported to `onCouponRejected`, and the checkout opens without it. */
|
|
87
|
+
couponCode?: string;
|
|
88
|
+
/** Customer lists the buyer joins once the order is paid for. They have to be open to sign-ups. */
|
|
89
|
+
groupIds?: string[];
|
|
90
|
+
onCouponRejected?: (code: string, error: unknown) => void;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
type CartItem = LineItem;
|
|
94
|
+
interface AddToCartOptions {
|
|
95
|
+
/**
|
|
96
|
+
* What a bundle does to the lines for products it includes: `'append'` leaves them, `'replace'`
|
|
97
|
+
* takes out those sold on the same terms as the bundle, and puts them back if the bundle is removed.
|
|
98
|
+
*/
|
|
99
|
+
bundleBehaviour?: 'append' | 'replace';
|
|
100
|
+
/**
|
|
101
|
+
* The customer's license this purchase upgrades or renews, for a product whose licenses cover only
|
|
102
|
+
* some releases ("12 months of updates", "versions up to 2.x"). Buying it extends that license
|
|
103
|
+
* instead of issuing another, at the price the storefront quotes for that license
|
|
104
|
+
* (`licenseUpgrades`). Each license is a line of its own with a quantity of 1, so adding it again
|
|
105
|
+
* changes nothing, and adding it with another variation replaces the line. Products only. Left out,
|
|
106
|
+
* the purchase issues a new license.
|
|
107
|
+
*/
|
|
108
|
+
targetLicenseId?: string;
|
|
109
|
+
}
|
|
110
|
+
interface CartCheckoutOptions extends CheckoutRedirectOptions {
|
|
111
|
+
/** Customer lists the buyer joins once the order is paid for. They have to be open to sign-ups. */
|
|
112
|
+
groupIds?: string[];
|
|
113
|
+
}
|
|
114
|
+
interface StorefrontCart {
|
|
115
|
+
/**
|
|
116
|
+
* Puts a product or bundle in the cart, or one more of it if it is there already, at `variation` or
|
|
117
|
+
* the default one, with `offer` attached if one is given. Returns the cart's line for it.
|
|
118
|
+
*/
|
|
119
|
+
addToCart: (item: StorefrontProduct | StorefrontBundle, variation?: PricingVariation, offer?: StorefrontOffer, options?: AddToCartOptions) => CartItem;
|
|
120
|
+
/** Sets how many of a line the cart holds, and returns the line. Zero or less removes it. */
|
|
121
|
+
setQuantity: (cartItem: CartItem, quantity: number) => CartItem;
|
|
122
|
+
removeFromCart: (cartItem: CartItem) => void;
|
|
123
|
+
/**
|
|
124
|
+
* Opens the checkout for the cart. Over the page on a computer and on Moonbase's own checkout page
|
|
125
|
+
* on a phone, by default (see `redirect`). Settles once the overlay closes, or the page is on its way
|
|
126
|
+
* to the hosted checkout. The cart empties once the order is paid for.
|
|
127
|
+
*/
|
|
128
|
+
checkout: (options?: CartCheckoutOptions) => Promise<CheckoutResult>;
|
|
129
|
+
/**
|
|
130
|
+
* Takes the cart offer off the order without sending the cart again. Cart offers apply themselves,
|
|
131
|
+
* but a page driving the cart itself may want to.
|
|
132
|
+
*/
|
|
133
|
+
removeCartOffer: () => Promise<void>;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
type AttributionConsentStatus = 'granted' | 'refused' | 'unknown';
|
|
137
|
+
/** Where the visitor's consent stands for each ad platform a store can connect in Moonbase. */
|
|
138
|
+
interface AttributionConsentStatusByPlatform {
|
|
139
|
+
meta: AttributionConsentStatus;
|
|
140
|
+
googleAnalytics: AttributionConsentStatus;
|
|
141
|
+
}
|
|
142
|
+
/** Everything a storefront knows that a page draws from. Replaced, never changed in place, on every update. */
|
|
143
|
+
interface StorefrontState {
|
|
144
|
+
/**
|
|
145
|
+
* The visitor's answer to the site's cookie banner, given with `answerAttributionConsent` and
|
|
146
|
+
* remembered in this browser across visits, or `null` until they answer. The storefront starts from it
|
|
147
|
+
* when `attributionConsent` isn't passed to `createStorefront`.
|
|
148
|
+
*/
|
|
149
|
+
attributionConsentAnswer: boolean | null;
|
|
150
|
+
/**
|
|
151
|
+
* Whether the store asks this visitor to agree to marketing cookies before it keeps the ad click IDs
|
|
152
|
+
* they arrived with, as its "Ad and campaign tracking" setting in Moonbase decides for where they are.
|
|
153
|
+
* `undefined` until a catalog loaded in this browser says: one a server fetched, such as
|
|
154
|
+
* `initialCatalog`, describes where the server is. A cookie banner asks when this is `true` and
|
|
155
|
+
* `attributionConsentStatus` is still `'unknown'`.
|
|
156
|
+
*/
|
|
157
|
+
attributionConsentRequired: boolean | undefined;
|
|
158
|
+
/**
|
|
159
|
+
* Where the visitor's consent to marketing cookies stands: `'refused'` once the site reports a refusal,
|
|
160
|
+
* `'granted'` once the site reports consent or the store's own setting lets them go unasked, and
|
|
161
|
+
* `'unknown'` until either says. A browser that sends Global Privacy Control counts as refusing, unless the
|
|
162
|
+
* store set every ad platform it connected in Moonbase to ignore it.
|
|
163
|
+
*/
|
|
164
|
+
attributionConsentStatus: AttributionConsentStatus;
|
|
165
|
+
/**
|
|
166
|
+
* Where the visitor's consent stands for each ad platform a store can connect in Moonbase: as
|
|
167
|
+
* `attributionConsentStatus`, except that Global Privacy Control refuses only a platform the store has
|
|
168
|
+
* it honored for (`gpc` on `catalog.tracking.meta` and `.googleAnalytics`).
|
|
169
|
+
*/
|
|
170
|
+
attributionConsentStatusByPlatform: AttributionConsentStatusByPlatform;
|
|
171
|
+
/**
|
|
172
|
+
* The store's catalog for this visitor: products, bundles, offers and promotions, priced in their
|
|
173
|
+
* currency, with `owned` worked out for whoever is signed in. Starts from the copy this browser
|
|
174
|
+
* cached on an earlier visit, or empty, until Moonbase answers.
|
|
175
|
+
*/
|
|
176
|
+
catalog: Storefront;
|
|
177
|
+
/** Whether `catalog` holds a real catalog yet, from Moonbase or from this browser's cache. */
|
|
178
|
+
catalogLoaded: boolean;
|
|
179
|
+
/**
|
|
180
|
+
* Whether the store has closed its Moonbase account. Its API then answers nothing but a
|
|
181
|
+
* `StoreClosedError`, so the storefront drops the cached catalog, the cart and the signed-in buyer,
|
|
182
|
+
* and this turns `true` for the page to say the store has closed.
|
|
183
|
+
*/
|
|
184
|
+
closed: boolean;
|
|
185
|
+
/** The cart, as the order it becomes at checkout. Its lines are as stored: `useCart` has them priced. */
|
|
186
|
+
order: Order;
|
|
187
|
+
user: User | null;
|
|
188
|
+
/** Whether the storefront has asked Moonbase who is signed in, so `user: null` means nobody is. */
|
|
189
|
+
userLoaded: boolean;
|
|
190
|
+
/**
|
|
191
|
+
* The attribution the visitor arrived with, as the storefront keeps and sends it: the UTM tags, the
|
|
192
|
+
* referring site and the ad platforms a click came from, plus the ad click IDs themselves once the
|
|
193
|
+
* visitor has agreed to marketing cookies (`setAttributionConsent`), or where the store's own setting
|
|
194
|
+
* lets them go unasked.
|
|
195
|
+
*/
|
|
196
|
+
utm: UrchinTrackingModule | undefined;
|
|
197
|
+
}
|
|
198
|
+
/** What a storefront reports, to `storefront.on` and `useStorefrontEvent`. */
|
|
199
|
+
interface StorefrontEvents {
|
|
200
|
+
checkoutInitiated: (order: OpenOrder, total: Money) => void;
|
|
201
|
+
/** The buyer saved their billing details in the embedded checkout. Called again each time they change them. */
|
|
202
|
+
checkoutBillingDetailsAdded: (order: OpenOrder) => void;
|
|
203
|
+
/**
|
|
204
|
+
* The buyer submitted payment in the embedded checkout. Each attempt is followed by either
|
|
205
|
+
* `checkoutPaymentFailed` or `checkoutCompleted`.
|
|
206
|
+
*/
|
|
207
|
+
checkoutPaymentStarted: (order: OpenOrder) => void;
|
|
208
|
+
/**
|
|
209
|
+
* An attempt to pay in the embedded checkout failed: a declined card, or a 3-D Secure check the buyer
|
|
210
|
+
* did not pass. The checkout stays open for them to try again. `error.reason` says what kind of
|
|
211
|
+
* failure it was, never the card issuer's own decline code.
|
|
212
|
+
*/
|
|
213
|
+
checkoutPaymentFailed: (order: OpenOrder, error: CheckoutPaymentFailure) => void;
|
|
214
|
+
/** The buyer applied a coupon code in the embedded checkout. */
|
|
215
|
+
checkoutCouponApplied: (order: OpenOrder, code: string) => void;
|
|
216
|
+
/** The buyer took a coupon off the order in the embedded checkout. */
|
|
217
|
+
checkoutCouponRemoved: (order: OpenOrder, code: string) => void;
|
|
218
|
+
/** The embedded checkout refused a coupon code the buyer typed, with the reason they were shown. */
|
|
219
|
+
checkoutCouponRejected: (code: string, message: string | undefined) => void;
|
|
220
|
+
/** An order was paid for, including one the buyer paid for on the hosted checkout and came back from. */
|
|
221
|
+
checkoutCompleted: (order: CompletedOrder) => void;
|
|
222
|
+
/**
|
|
223
|
+
* The checkout closed. `completed` says whether it completed the order (when `checkoutCompleted` is
|
|
224
|
+
* called), and `order` is the order it was open for, when the checkout sent it.
|
|
225
|
+
*/
|
|
226
|
+
checkoutClosed: (intent: string | undefined, completed: boolean, order: Order | undefined) => void;
|
|
227
|
+
/**
|
|
228
|
+
* A fresh catalog arrived from Moonbase. The first one can arrive before a component's effects run, so
|
|
229
|
+
* a component that needs what it says reads it from the state instead: `catalog`, or
|
|
230
|
+
* `attributionConsentRequired` for whether to ask for consent.
|
|
231
|
+
*/
|
|
232
|
+
catalogUpdated: (catalog: Storefront) => void;
|
|
233
|
+
/**
|
|
234
|
+
* Moonbase refused to renew the buyer's session: they signed out of it elsewhere, changed their
|
|
235
|
+
* password, or stayed away too long. The storefront has gone anonymous, as it does on signing out.
|
|
236
|
+
*/
|
|
237
|
+
sessionEnded: (user: User) => void;
|
|
238
|
+
}
|
|
239
|
+
interface StorefrontOptions extends Omit<MoonbaseConfiguration, 'endpoint'> {
|
|
240
|
+
/**
|
|
241
|
+
* A catalog to start from, such as one a server fetched for the page it rendered. Used on the
|
|
242
|
+
* server, and in the browser until a fresher one loads unless this browser cached a newer one.
|
|
243
|
+
*/
|
|
244
|
+
initialCatalog?: Storefront;
|
|
245
|
+
/**
|
|
246
|
+
* Whether the cart attaches eligible item-scope offers to the lines they target by itself, rather
|
|
247
|
+
* than only when something hands one to `addToCart`. Off by default. It never adds anything to the
|
|
248
|
+
* cart, and never replaces an offer a line already holds: it only fills an empty slot on a line
|
|
249
|
+
* that is in the cart already. Change it later with `storefront.autoApplyItemOffers`.
|
|
250
|
+
*/
|
|
251
|
+
autoApplyItemOffers?: boolean;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* A connection to a Moonbase store from a browser: the catalog, the signed-in customer and the cart,
|
|
255
|
+
* kept in step with Moonbase, with other tabs and with the checkout. Made once per page with
|
|
256
|
+
* `createStorefront` and handed to `<StorefrontProvider>`. Nothing in it depends on React, so the same
|
|
257
|
+
* object serves a router loader, a store of your own, or plain scripts.
|
|
258
|
+
*/
|
|
259
|
+
declare class MoonbaseStorefront {
|
|
260
|
+
readonly configuration: MoonbaseConfiguration;
|
|
261
|
+
readonly client: MoonbaseClient;
|
|
262
|
+
static readonly sessionKey = "moonbase_session";
|
|
263
|
+
static readonly storefrontKey = "moonbase_storefront";
|
|
264
|
+
static readonly utmKey = "moonbase_utm";
|
|
265
|
+
static readonly arrivalKey = "moonbase_arrival";
|
|
266
|
+
static readonly adConsentReportedKey = "moonbase_ad_consent_reported";
|
|
267
|
+
static readonly attributionConsentKey = "moonbase_attribution_consent";
|
|
268
|
+
/**
|
|
269
|
+
* Whether the cart attaches eligible item-scope offers by itself. See
|
|
270
|
+
* `StorefrontOptions.autoApplyItemOffers`. Read on every cart change.
|
|
271
|
+
*/
|
|
272
|
+
autoApplyItemOffers: boolean;
|
|
273
|
+
/** Settles once `catalogLoaded` turns true. The same promise every time, so React's `use()` can suspend on it. */
|
|
274
|
+
readonly catalogLoadedPromise: Promise<void>;
|
|
275
|
+
/**
|
|
276
|
+
* Settles once the storefront knows who is signed in, if anyone. The same promise every time. On a
|
|
277
|
+
* server, at once: nobody is signed in there.
|
|
278
|
+
*/
|
|
279
|
+
readonly userLoadedPromise: Promise<void>;
|
|
280
|
+
/** Signing in and out, and the customer's own account. */
|
|
281
|
+
readonly auth: StorefrontAuth;
|
|
282
|
+
/** The cart's lines and its checkout. */
|
|
283
|
+
readonly cart: StorefrontCart;
|
|
284
|
+
private state;
|
|
285
|
+
private readonly serverState;
|
|
286
|
+
private readonly listeners;
|
|
287
|
+
private resolveCatalogLoaded;
|
|
288
|
+
private resolveUserLoaded;
|
|
289
|
+
/**
|
|
290
|
+
* The attribution this tab knows of, ad click IDs and all: this page's arrival, or the one stored
|
|
291
|
+
* earlier in the tab. Kept in memory, where it never leaves the device, so that consent given after
|
|
292
|
+
* the page loaded can still add the click IDs to `utm`.
|
|
293
|
+
*/
|
|
294
|
+
private arrival;
|
|
295
|
+
/** When and on which page `arrival` landed, for an arrival with tags. */
|
|
296
|
+
private landing;
|
|
297
|
+
/** What the site said of the visitor's consent, from its cookie banner; undefined until it says. */
|
|
298
|
+
private attributionConsentSetting;
|
|
299
|
+
/** Whether the store's own setting lets this visitor's attribution go ahead unasked, once the catalog has said. */
|
|
300
|
+
private storeAllowsAttribution;
|
|
301
|
+
private refreshOrderAbortController;
|
|
302
|
+
private pushTimeout;
|
|
303
|
+
/** Sends the cart change `pushTimeout` is waiting to send. */
|
|
304
|
+
private pendingPush;
|
|
305
|
+
/** Aborted by `dispose`, which takes the storefront's window listeners with it. */
|
|
306
|
+
private readonly lifetime;
|
|
307
|
+
/** Whether the storefront took the hosted checkout's parameters off the address as it was made. */
|
|
308
|
+
private tookCheckoutReturn;
|
|
309
|
+
private catalogRefreshesStarted;
|
|
310
|
+
private catalogRefreshLanded;
|
|
311
|
+
constructor(configuration: MoonbaseConfiguration, client: MoonbaseClient, options?: Pick<StorefrontOptions, 'initialCatalog' | 'autoApplyItemOffers'>);
|
|
312
|
+
/** The current state. A new object whenever anything in it changes, and the same one otherwise. */
|
|
313
|
+
readonly getState: () => StorefrontState;
|
|
314
|
+
/**
|
|
315
|
+
* The state a server renders with, and so what React hydrates against: the initial catalog, if any,
|
|
316
|
+
* an empty cart and nobody signed in. On the server itself, where there is nothing to hydrate, the
|
|
317
|
+
* current state, so a page that awaits `refreshCatalog()` before rendering renders with it.
|
|
318
|
+
*/
|
|
319
|
+
readonly getServerState: () => StorefrontState;
|
|
320
|
+
/** Calls `listener` after every change to the state, and returns the function that stops it. */
|
|
321
|
+
readonly subscribe: (listener: () => void) => (() => void);
|
|
322
|
+
/**
|
|
323
|
+
* Calls `callback` each time the storefront reports `event`, and returns the function that stops it.
|
|
324
|
+
* `dispose` stops it too. In a component, `useStorefrontEvent` does the subscribing and the cleaning up.
|
|
325
|
+
*/
|
|
326
|
+
on<K extends keyof StorefrontEvents>(event: K, callback: StorefrontEvents[K]): () => void;
|
|
327
|
+
/** Whether `dispose` has stopped the storefront. */
|
|
328
|
+
get disposed(): boolean;
|
|
329
|
+
/**
|
|
330
|
+
* Stops the storefront, for a test or for a page that swaps it for another: it stops following other
|
|
331
|
+
* tabs, the checkout and the customer's session, stops calling what `on` subscribed, stops renewing
|
|
332
|
+
* their sign-in, and ignores what requests still in flight bring back. A cart change still waiting to
|
|
333
|
+
* be sent goes at once. What it stored in the browser stays, for the next storefront to pick up.
|
|
334
|
+
* `getStorefront` makes a new one after this.
|
|
335
|
+
*/
|
|
336
|
+
dispose(): void;
|
|
337
|
+
/**
|
|
338
|
+
* Takes the hosted checkout's parameters off the address again, when the storefront took them off as
|
|
339
|
+
* it was made and a router has since put them back, and has the router read the address again.
|
|
340
|
+
* `<StorefrontProvider>` calls it once the page has hydrated, which is all a page needs.
|
|
341
|
+
*
|
|
342
|
+
* Next.js's router is why: it reads the address before any of the page's own code runs, and writes it
|
|
343
|
+
* back as the page hydrates. It is told with a `popstate`, as for Back, since it ignores an address
|
|
344
|
+
* changed under the history entry it wrote, and `useSearchParams()` would go on listing the parameters.
|
|
345
|
+
*/
|
|
346
|
+
clearCheckoutReturn(): void;
|
|
347
|
+
get hasUtm(): boolean;
|
|
348
|
+
get hasUtmOrReferrer(): boolean;
|
|
349
|
+
/** Whether the storefront may keep and send ad click IDs and record an arrival before any action. */
|
|
350
|
+
private get attributionConsent();
|
|
351
|
+
/**
|
|
352
|
+
* Buys these items straight away, without touching the cart: the "Buy now" path. Opens the checkout
|
|
353
|
+
* over the page, or on a phone sends the buyer to Moonbase's own checkout page (see `redirect`), and
|
|
354
|
+
* settles once the overlay closes or the page is on its way.
|
|
355
|
+
*/
|
|
356
|
+
checkout(items: CheckoutItem[], options?: CheckoutOptions): Promise<CheckoutResult>;
|
|
357
|
+
/** Closes the checkout overlay, if one is open. */
|
|
358
|
+
closeCheckout(): void;
|
|
359
|
+
/**
|
|
360
|
+
* Say whether the visitor has agreed to marketing cookies, typically from a cookie banner's callback.
|
|
361
|
+
* `StorefrontOptions.attributionConsent` sets where it starts. Until either says, the storefront
|
|
362
|
+
* follows the store's own setting in Moonbase, which the catalog reports for this visitor once it
|
|
363
|
+
* loads. A banner that asks for Google's two parts separately can pass `{ adUserData, adPersonalization }`,
|
|
364
|
+
* which counts as granted here when `adUserData` is.
|
|
365
|
+
*
|
|
366
|
+
* Granting it adds the ad click IDs the visitor arrived with in this tab (`gclid`, `fbclid` and the
|
|
367
|
+
* rest) to `utm`, and records the arrival on a new cart if there is none yet, so a visitor who leaves
|
|
368
|
+
* and comes back to buy is still put down to it. Withdrawing it drops the click IDs from `utm` and the
|
|
369
|
+
* browser's storage again. What has already been sent stays with the order.
|
|
370
|
+
*/
|
|
371
|
+
setAttributionConsent(granted: boolean | AdConsentReport): void;
|
|
372
|
+
/**
|
|
373
|
+
* Records the visitor's answer to the site's own cookie banner: remembered in this browser, so the
|
|
374
|
+
* storefront starts from it on their next visit, and passed on with `setAttributionConsent`. Other tabs
|
|
375
|
+
* follow it. `useAttributionConsent` hands it out. A banner that asks for Google's two consent mode
|
|
376
|
+
* signals separately passes them to `setAttributionConsent` instead.
|
|
377
|
+
*/
|
|
378
|
+
readonly answerAttributionConsent: (granted: boolean) => void;
|
|
379
|
+
/**
|
|
380
|
+
* What the storefront's requests say of the visit for ad measurement, beside `utm`: what the site last
|
|
381
|
+
* reported of the visitor's consent, left out until it says, and when and on which page the visit's
|
|
382
|
+
* tagged arrival landed, left out for a visit without tags. Where the store connected Meta or Google
|
|
383
|
+
* Analytics in Moonbase, and while the visitor's consent lets click IDs go, also their browser IDs and
|
|
384
|
+
* the page the request is made on.
|
|
385
|
+
*/
|
|
386
|
+
adSignals(): AdSignals;
|
|
387
|
+
/** Asks Moonbase who is signed in. `state.user` is null when nobody is, or the session has run out. */
|
|
388
|
+
refreshUser(): Promise<User | null>;
|
|
389
|
+
/** Asks Moonbase for the catalog again, for this visitor and whoever is signed in. */
|
|
390
|
+
refreshCatalog(): Promise<Storefront>;
|
|
391
|
+
/**
|
|
392
|
+
* Saves the cart in this browser and sends it to Moonbase, half a second after the last change, so a
|
|
393
|
+
* buyer pressing "+" five times sends one request.
|
|
394
|
+
*/
|
|
395
|
+
pushOrderContent(): void;
|
|
396
|
+
/**
|
|
397
|
+
* Starts a new, empty cart, or with `keepItems` a new cart holding the same lines, under a new ID.
|
|
398
|
+
* Coupons are not carried over: they are checked again for each order and customer.
|
|
399
|
+
*/
|
|
400
|
+
resetOrder(opts?: {
|
|
401
|
+
keepItems?: boolean;
|
|
402
|
+
}): void;
|
|
403
|
+
/** Takes the billing details off the cart's order in Moonbase, as a buyer leaving it would want. */
|
|
404
|
+
surrenderOrder(): Promise<void>;
|
|
405
|
+
/** The lines with their products, bundles and prices from the current catalog. */
|
|
406
|
+
enrichLineItems(lineItems: LineItem[], order?: Order): LineItem[];
|
|
407
|
+
/** The context an offer's condition is judged against: the cart, unless another order is given. */
|
|
408
|
+
offerConditionContext(order?: Order): OfferConditionContext;
|
|
409
|
+
/** Puts the best cart offer the cart qualifies for on it, returning whether that changed anything. */
|
|
410
|
+
reconcileCartOffer(): boolean;
|
|
411
|
+
/**
|
|
412
|
+
* Takes the cart offer off the order without sending the cart again. Cart offers apply themselves,
|
|
413
|
+
* but a page driving the cart itself may want to.
|
|
414
|
+
*/
|
|
415
|
+
removeCartOffer(): Promise<void>;
|
|
416
|
+
private setState;
|
|
417
|
+
/**
|
|
418
|
+
* The server refused to renew the buyer's session: they signed out of it elsewhere, changed their
|
|
419
|
+
* password, or stayed away too long. Goes anonymous the way signing out does, and says so, since
|
|
420
|
+
* nobody on this page signed out and the page would otherwise never hear of it.
|
|
421
|
+
*/
|
|
422
|
+
private endSession;
|
|
423
|
+
private refreshInBackground;
|
|
424
|
+
/**
|
|
425
|
+
* The store has closed for good, so nothing kept for it is any use: not the catalog a returning
|
|
426
|
+
* visitor would otherwise be shown, not the cart, and not the buyer's session.
|
|
427
|
+
*/
|
|
428
|
+
private closeStore;
|
|
429
|
+
/** Brings `utm`, its storage and the cart in line with the visitor's consent, when that changed. */
|
|
430
|
+
private attributionConsentChanged;
|
|
431
|
+
/** Keeps `landing` beside the arrival in `kind` storage, or clears what is there for an arrival without one. */
|
|
432
|
+
private storeLanding;
|
|
433
|
+
/** `utm` as the storefront may keep and send it: with its ad click IDs only once the visitor agreed. */
|
|
434
|
+
private consentedUtm;
|
|
435
|
+
/**
|
|
436
|
+
* The visitor's Meta and Google Analytics browser IDs, and this page, for a store that connected either
|
|
437
|
+
* in Moonbase, while the visitor's consent lets click IDs go. A browser that sends Global Privacy Control
|
|
438
|
+
* gives only those of a platform the store set to ignore it. Read as each request is made, since the
|
|
439
|
+
* vendors' tags write their cookies after the storefront starts.
|
|
440
|
+
*/
|
|
441
|
+
private browserIdentifiers;
|
|
442
|
+
private consentStatus;
|
|
443
|
+
/**
|
|
444
|
+
* Tells Moonbase when the site reports that a signed-in customer refuses ad tracking, which renewals
|
|
445
|
+
* and other events sent without a visit then follow. Once per tab for each customer and report, as a
|
|
446
|
+
* site's banner often reports the same choice on every page.
|
|
447
|
+
*/
|
|
448
|
+
private reportAdConsentRefusal;
|
|
449
|
+
private handleStorageUpdate;
|
|
450
|
+
private refreshOrder;
|
|
451
|
+
private static parseAnswer;
|
|
452
|
+
private static parseCachedUtm;
|
|
453
|
+
private static parseCachedOrder;
|
|
454
|
+
/**
|
|
455
|
+
* Reads a catalog out of local storage, normalising it through the schema, which fills in the
|
|
456
|
+
* defaults a catalog cached by an older version lacks. One the schema rejects is still used as it
|
|
457
|
+
* is: a catalog only partly understood beats an empty one while the refresh is in flight. Only
|
|
458
|
+
* unreadable JSON gives up.
|
|
459
|
+
*/
|
|
460
|
+
private static parseCachedCatalog;
|
|
461
|
+
private static normalizeCatalog;
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/** The store's catalog for this visitor, with `useStorefrontState(state => state.catalogLoaded)` saying whether it has loaded. */
|
|
465
|
+
declare function useCatalog(): Storefront;
|
|
466
|
+
declare function useProducts(): StorefrontProduct[];
|
|
467
|
+
/**
|
|
468
|
+
* The product with this ID in the catalog, or null, as before the catalog has loaded. Null for no ID, so a
|
|
469
|
+
* component that may have none, such as a cart line holding a bundle, can still call it.
|
|
470
|
+
*/
|
|
471
|
+
declare function useProduct(productId: string | null | undefined): StorefrontProduct | null;
|
|
472
|
+
declare function useBundles(): StorefrontBundle[];
|
|
473
|
+
/** The bundle with this ID in the catalog, or null, also for no ID. */
|
|
474
|
+
declare function useBundle(bundleId: string | null | undefined): StorefrontBundle | null;
|
|
475
|
+
declare function useOffers(): StorefrontOffer[];
|
|
476
|
+
/** The offer with this ID in the catalog, or null, also for no ID. */
|
|
477
|
+
declare function useOffer(offerId: string | null | undefined): StorefrontOffer | null;
|
|
478
|
+
/**
|
|
479
|
+
* The sales currently running across the store's catalog.
|
|
480
|
+
*
|
|
481
|
+
* Moonbase already applies their dates and who they are for before it sends them, so everything here
|
|
482
|
+
* is live and applies to this visitor: show them as they are, never filter them again. The list
|
|
483
|
+
* changes when the visitor signs in or out, since that changes who qualifies.
|
|
484
|
+
*/
|
|
485
|
+
declare function usePromotions(): StorefrontPromotion[];
|
|
486
|
+
|
|
487
|
+
interface LockedOffer {
|
|
488
|
+
offer: StorefrontOffer;
|
|
489
|
+
progress: OfferProgress;
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* What the cart's offer meter shows: the cart offer the buyer has earned, the one they are working
|
|
493
|
+
* toward, or both.
|
|
494
|
+
*
|
|
495
|
+
* A cart offer discounts the order as a whole, so there is nothing for the buyer to add and nothing to
|
|
496
|
+
* upsell: only a threshold to reach. Both fields can be set at once, which is the tiered case: only one
|
|
497
|
+
* cart offer ever applies to an order, so "10% over €50, 20% over €100" is two offers where reaching
|
|
498
|
+
* the second *replaces* the first. Without `next` a buyer on the lower rung would never learn the
|
|
499
|
+
* higher one exists.
|
|
500
|
+
*/
|
|
501
|
+
interface CartOfferState {
|
|
502
|
+
/** The cart offer currently discounting the cart, and what it takes off. */
|
|
503
|
+
applied: {
|
|
504
|
+
offer: StorefrontOffer;
|
|
505
|
+
saving: number;
|
|
506
|
+
} | null;
|
|
507
|
+
/**
|
|
508
|
+
* The next rung worth reaching. When something is already applied this is always a strictly more
|
|
509
|
+
* valuable cart offer, since reaching a lesser one would leave the buyer worse off.
|
|
510
|
+
*/
|
|
511
|
+
next: LockedOffer | null;
|
|
512
|
+
/** The cart before any cart offer. */
|
|
513
|
+
subtotal: number;
|
|
514
|
+
currency: string;
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/** Offers the cart qualifies for and hasn't used, on something it doesn't hold yet: the upsells to show. */
|
|
518
|
+
declare function useEligibleOffers(): StorefrontOffer[];
|
|
519
|
+
/**
|
|
520
|
+
* Item offers the cart is short of, with how far off each is, nearest first: "spend €20 more and get
|
|
521
|
+
* Glass FX for half price". Only offers gated on what the cart is worth, which a buyer could otherwise
|
|
522
|
+
* never learn about.
|
|
523
|
+
*/
|
|
524
|
+
declare function useLockedOffers(): LockedOffer[];
|
|
525
|
+
/** What the cart's offer meter shows: the cart offer the buyer has earned, the next one to reach, or both. */
|
|
526
|
+
declare function useCartOffer(): CartOfferState | null;
|
|
527
|
+
|
|
528
|
+
/** Part of the signed-in customer's account, as a hook loads it. */
|
|
529
|
+
interface AccountData<T> {
|
|
530
|
+
/**
|
|
531
|
+
* The data, or null: while it loads, with nobody signed in, and for no ID. A component that mounts
|
|
532
|
+
* again gets what was loaded before at once, and the hook asks for it again in the background.
|
|
533
|
+
*/
|
|
534
|
+
data: T | null;
|
|
535
|
+
/**
|
|
536
|
+
* Whether it is loading: while a request is in flight, a background refresh of `data` included, and
|
|
537
|
+
* until the storefront knows who is signed in. Show a placeholder while this is true and `data` is null.
|
|
538
|
+
*/
|
|
539
|
+
loading: boolean;
|
|
540
|
+
/** Why the last request failed, until one succeeds. */
|
|
541
|
+
error: Error | null;
|
|
542
|
+
/** Asks for it again, as after changing it. Settles once the answer is in, and never rejects. */
|
|
543
|
+
reload: () => Promise<void>;
|
|
544
|
+
}
|
|
545
|
+
/** A list in the signed-in customer's account, which Moonbase hands out a page at a time. */
|
|
546
|
+
interface PagedAccountData<T> extends AccountData<T[]> {
|
|
547
|
+
/**
|
|
548
|
+
* Every item loaded so far, or null. `reload` goes back to the first page. A page can hold more items
|
|
549
|
+
* than Moonbase's page size, so count what is here rather than pages.
|
|
550
|
+
*/
|
|
551
|
+
data: T[] | null;
|
|
552
|
+
/** Whether Moonbase has more after what is loaded. */
|
|
553
|
+
hasMore: boolean;
|
|
554
|
+
/** Adds the next page to `data`. Settles once it is in, and never rejects. */
|
|
555
|
+
loadMore: () => Promise<void>;
|
|
556
|
+
}
|
|
557
|
+
/** The products the signed-in customer owns, or has a trial of, a page at a time. */
|
|
558
|
+
declare function useOwnedProducts(): PagedAccountData<OwnedProduct>;
|
|
559
|
+
/** One product the signed-in customer owns, with its downloads. Null for no ID. */
|
|
560
|
+
declare function useOwnedProduct(productId: string | null | undefined): AccountData<OwnedProduct>;
|
|
561
|
+
/** The computers the signed-in customer's licenses for a product are activated on, a page at a time. */
|
|
562
|
+
declare function useProductActivations(productId: string | null | undefined): PagedAccountData<Activation>;
|
|
563
|
+
/** The signed-in customer's licenses for a product, a page at a time. */
|
|
564
|
+
declare function useProductLicenses(productId: string | null | undefined): PagedAccountData<License>;
|
|
565
|
+
/** The signed-in customer's completed orders, newest first, a page at a time. */
|
|
566
|
+
declare function useOrderHistory(): PagedAccountData<CompletedOrder>;
|
|
567
|
+
/** The signed-in customer's subscriptions, a page at a time. */
|
|
568
|
+
declare function useSubscriptions(): PagedAccountData<Subscription>;
|
|
569
|
+
/** One of the signed-in customer's subscriptions. Null for no ID. */
|
|
570
|
+
declare function useSubscription(subscriptionId: string | null | undefined): AccountData<Subscription>;
|
|
571
|
+
|
|
572
|
+
interface ActivationRequestState {
|
|
573
|
+
/** The request the app on the customer's computer made, or null until it has loaded. */
|
|
574
|
+
activationRequest: ActivationRequest | null;
|
|
575
|
+
loading: boolean;
|
|
576
|
+
/** Granting it a license or a trial, until Moonbase has. */
|
|
577
|
+
fulfilling: boolean;
|
|
578
|
+
/** Waiting for the app to pick up what was granted. */
|
|
579
|
+
completing: boolean;
|
|
580
|
+
error: string | null;
|
|
581
|
+
/** Whether the app has picked up its license or trial: the product is ready on that computer. */
|
|
582
|
+
isInstalled: boolean;
|
|
583
|
+
/** Activates the product on that computer with a license the signed-in customer owns. */
|
|
584
|
+
fulfillLicense: () => Promise<void>;
|
|
585
|
+
/** Starts a free trial on that computer, optionally signing the customer up for the newsletter. */
|
|
586
|
+
fulfillTrial: (newsletterOptIn?: boolean) => Promise<void>;
|
|
587
|
+
/** Turns the request down, as a customer who didn't make it would. */
|
|
588
|
+
cancel: () => Promise<void>;
|
|
589
|
+
}
|
|
590
|
+
interface ActivationRequestOptions {
|
|
591
|
+
/**
|
|
592
|
+
* Activates with a license the signed-in customer owns as soon as the request says they can: once
|
|
593
|
+
* `activationRequest.licenseEligibility.eligible` is true while it is still `Requested`. Tried once per
|
|
594
|
+
* request. A failure is left in `error`, and `fulfillLicense` tries again.
|
|
595
|
+
*/
|
|
596
|
+
autoFulfill?: boolean;
|
|
597
|
+
}
|
|
598
|
+
/**
|
|
599
|
+
* Activating a product in the browser: the page an app opens with a `token` when its customer chooses
|
|
600
|
+
* to activate online. Loads the request, again when someone signs in, and once it has been granted
|
|
601
|
+
* waits for the app to pick it up. Without a token, as on a link that lost it, it loads nothing. With
|
|
602
|
+
* `autoFulfill`, it activates with the customer's license as soon as the request says they can.
|
|
603
|
+
*/
|
|
604
|
+
declare function useActivationRequest(token: string | null | undefined, options?: ActivationRequestOptions): ActivationRequestState;
|
|
605
|
+
|
|
606
|
+
interface AttributionConsent {
|
|
607
|
+
/**
|
|
608
|
+
* Whether the store asks this visitor to agree to marketing cookies, as its "Ad and campaign tracking"
|
|
609
|
+
* setting decides for where they are, or `undefined` until the browser has loaded the catalog for them.
|
|
610
|
+
*/
|
|
611
|
+
required: boolean | undefined;
|
|
612
|
+
/** The visitor's answer, remembered in this browser across visits, or `null` until they answer. */
|
|
613
|
+
answer: boolean | null;
|
|
614
|
+
/** Records the visitor's answer, remembers it, and has the storefront follow it. */
|
|
615
|
+
setAnswer: (granted: boolean) => void;
|
|
616
|
+
}
|
|
617
|
+
/**
|
|
618
|
+
* What a cookie banner of the site's own needs: ask when `required` is `true` and `answer` is `null`, and
|
|
619
|
+
* hand the visitor's choice to `setAnswer`. The storefront remembers it in this browser and starts from it
|
|
620
|
+
* on their next visit, unless `attributionConsent` is passed to `createStorefront`. The banner itself is
|
|
621
|
+
* the site's.
|
|
622
|
+
*
|
|
623
|
+
* ```tsx
|
|
624
|
+
* const { required, answer, setAnswer } = useAttributionConsent()
|
|
625
|
+
* if (required && answer === null)
|
|
626
|
+
* return <Banner onAccept={() => setAnswer(true)} onDecline={() => setAnswer(false)} />
|
|
627
|
+
* ```
|
|
628
|
+
*/
|
|
629
|
+
declare function useAttributionConsent(): AttributionConsent;
|
|
630
|
+
|
|
631
|
+
interface Auth extends StorefrontAuth {
|
|
632
|
+
/** The signed-in customer, or null. */
|
|
633
|
+
user: User | null;
|
|
634
|
+
/**
|
|
635
|
+
* Whether the storefront has asked Moonbase who is signed in. Until it has, `user` can be null for a
|
|
636
|
+
* customer who is, so hold back anything that would show them "Sign in".
|
|
637
|
+
*/
|
|
638
|
+
loaded: boolean;
|
|
639
|
+
}
|
|
640
|
+
/** The signed-in customer, and signing in, out and up. Every function keeps its identity across renders. */
|
|
641
|
+
declare function useAuth(): Auth;
|
|
642
|
+
|
|
643
|
+
interface Cart extends StorefrontCart {
|
|
644
|
+
/** The cart's lines, with their products or bundles and the prices the cart shows. */
|
|
645
|
+
items: CartItem[];
|
|
646
|
+
/**
|
|
647
|
+
* Lines whose product, or a product their bundle includes, has sold out. The checkout takes no
|
|
648
|
+
* payment for a cart holding one, so they have to come out first.
|
|
649
|
+
*/
|
|
650
|
+
soldOutItems: CartItem[];
|
|
651
|
+
/** The currency the cart shows and checks out in: the one the store suggests for this visitor. */
|
|
652
|
+
currency: string;
|
|
653
|
+
total: {
|
|
654
|
+
amount: number;
|
|
655
|
+
currency: string;
|
|
656
|
+
};
|
|
657
|
+
/**
|
|
658
|
+
* The cart priced the way Moonbase prices it: product discounts and pricing tiers, then each line's
|
|
659
|
+
* own offer, then the cart offer. Before taxes, which the checkout works out from the billing address.
|
|
660
|
+
*/
|
|
661
|
+
breakdown: CartTotal;
|
|
662
|
+
cartOffer: CartTotal['cartOffer'];
|
|
663
|
+
}
|
|
664
|
+
/** The cart, and changing it. Every function keeps its identity across renders. */
|
|
665
|
+
declare function useCart(): Cart;
|
|
666
|
+
/**
|
|
667
|
+
* The currency the cart shows and checks out in: the one the store suggests for this visitor. Renders again
|
|
668
|
+
* only when that changes, not on every change to the cart, so a product card can price itself without
|
|
669
|
+
* `useCart`.
|
|
670
|
+
*/
|
|
671
|
+
declare function useCurrency(): string;
|
|
672
|
+
/**
|
|
673
|
+
* Changing the cart, `addToCart` and the rest, without reading it: a component using only this never
|
|
674
|
+
* renders again because the cart changed. The same object every time.
|
|
675
|
+
*/
|
|
676
|
+
declare function useCartActions(): StorefrontCart;
|
|
677
|
+
|
|
678
|
+
/**
|
|
679
|
+
* Buying straight away, without the cart: the function a "Buy now" button calls.
|
|
680
|
+
*
|
|
681
|
+
* ```tsx
|
|
682
|
+
* const checkout = useCheckout()
|
|
683
|
+
* <button onClick={() => checkout([{ item: product }])}>Buy now</button>
|
|
684
|
+
* ```
|
|
685
|
+
*
|
|
686
|
+
* It opens the checkout over the page, or on a phone sends the buyer to Moonbase's own checkout page
|
|
687
|
+
* (see `redirect`), and settles once the overlay closes or the page is on its way.
|
|
688
|
+
*/
|
|
689
|
+
declare function useCheckout(): (items: CheckoutItem[], options?: CheckoutOptions) => Promise<CheckoutResult>;
|
|
690
|
+
|
|
691
|
+
type CommunicationsEndpoints = MoonbaseClient['communications'];
|
|
692
|
+
interface Communications {
|
|
693
|
+
/** Signs someone up for the store's newsletter, with the attribution and ad signals the visit came with. */
|
|
694
|
+
subscribe: (input: SubscribeInput) => ReturnType<CommunicationsEndpoints['subscribe']>;
|
|
695
|
+
/** Confirms a newsletter sign-up from the link in its confirmation email. */
|
|
696
|
+
confirm: (email: string, token: string) => ReturnType<CommunicationsEndpoints['confirm']>;
|
|
697
|
+
get: (email: string, token: string) => ReturnType<CommunicationsEndpoints['getPreferences']>;
|
|
698
|
+
update: (email: string, token: string, preferences: CommunicationPreferencesInput) => ReturnType<CommunicationsEndpoints['updatePreferences']>;
|
|
699
|
+
unsubscribe: (email: string, token: string) => ReturnType<CommunicationsEndpoints['unsubscribe']>;
|
|
700
|
+
}
|
|
701
|
+
/** Newsletter sign-ups, and the preferences page an email's footer links to. */
|
|
702
|
+
declare function useCommunicationPreferences(): Communications;
|
|
703
|
+
|
|
704
|
+
interface Groups {
|
|
705
|
+
/**
|
|
706
|
+
* Joins the signed-in customer to a customer list of the store's that has been opened to sign-ups.
|
|
707
|
+
*
|
|
708
|
+
* Throws `NotAuthenticatedError` when nobody is signed in, and `NotFoundError` for every reason the
|
|
709
|
+
* join can be refused, which Moonbase deliberately does not tell apart. Joining twice is fine.
|
|
710
|
+
*/
|
|
711
|
+
join: (groupId: string) => Promise<void>;
|
|
712
|
+
}
|
|
713
|
+
declare function useGroups(): Groups;
|
|
714
|
+
|
|
715
|
+
type Inventory = MoonbaseClient['inventory'];
|
|
716
|
+
/** What the signed-in customer owns: products, licenses, the computers they're on, and subscriptions. */
|
|
717
|
+
interface StorefrontInventory {
|
|
718
|
+
getLicenses: (nextUrl?: string) => ReturnType<Inventory['licenses']['get']>;
|
|
719
|
+
getLicenseActivations: (licenseId: string, nextUrl?: string) => ReturnType<Inventory['licenses']['getActivations']>;
|
|
720
|
+
getProduct: (productId: string, version?: string) => ReturnType<Inventory['products']['get']>;
|
|
721
|
+
getProductReleases: (productId: string, nextUrl?: string) => ReturnType<Inventory['products']['getReleases']>;
|
|
722
|
+
getProducts: (nextUrl?: string) => ReturnType<Inventory['products']['getOwned']>;
|
|
723
|
+
getProductLicenses: (productId: string, nextUrl?: string) => ReturnType<Inventory['products']['getLicenses']>;
|
|
724
|
+
getProductActivations: (productId: string, nextUrl?: string) => ReturnType<Inventory['products']['getActivations']>;
|
|
725
|
+
/** Frees the seat an activation takes, so the license can go on another computer. */
|
|
726
|
+
revokeActivation: (activation: Activation) => ReturnType<Inventory['licenses']['revokeActivation']>;
|
|
727
|
+
/** Activates a product on the computer a device token is from, as the activation page and offline activation do. */
|
|
728
|
+
activateProduct: (deviceToken: string, activationMethod: ActivationMethod) => ReturnType<Inventory['activation']['activate']>;
|
|
729
|
+
/** Starts downloading a file, as the browser downloads anything. */
|
|
730
|
+
downloadProduct: (download: Download) => Promise<void>;
|
|
731
|
+
getSubscriptions: (nextUrl?: string) => ReturnType<Inventory['subscriptions']['get']>;
|
|
732
|
+
getSubscription: (subscriptionId: string) => ReturnType<Inventory['subscriptions']['getById']>;
|
|
733
|
+
cancelSubscription: (subscriptionId: string, feedback?: SubscriptionCancellationFeedback) => ReturnType<Inventory['subscriptions']['cancel']>;
|
|
734
|
+
/** The plans a subscription can switch to when its paid period ends. */
|
|
735
|
+
getSubscriptionPlanOptions: (subscriptionId: string) => ReturnType<Inventory['subscriptions']['getPlanOptions']>;
|
|
736
|
+
/** Switches a subscription to another plan of its product when its paid period ends. Nothing is charged until then. */
|
|
737
|
+
changeSubscriptionPlan: (subscriptionId: string, variationId: string) => ReturnType<Inventory['subscriptions']['changePlan']>;
|
|
738
|
+
cancelSubscriptionPlanChange: (subscriptionId: string) => ReturnType<Inventory['subscriptions']['cancelPlanChange']>;
|
|
739
|
+
/** Opens the checkout to renew a subscription that has lapsed, the way the cart's checkout opens. */
|
|
740
|
+
renewSubscription: (subscriptionId: string, options?: CheckoutRedirectOptions) => Promise<CheckoutResult>;
|
|
741
|
+
/** Opens Moonbase's form to change the card a subscription is paid with, over the page. */
|
|
742
|
+
updateSubscriptionPaymentMethod: (subscription: Subscription, options?: {
|
|
743
|
+
returnUrl?: string;
|
|
744
|
+
}) => Promise<{
|
|
745
|
+
completed: boolean;
|
|
746
|
+
}>;
|
|
747
|
+
}
|
|
748
|
+
|
|
749
|
+
/**
|
|
750
|
+
* What the signed-in customer owns, and managing it: products and their downloads, licenses and the
|
|
751
|
+
* computers they're activated on, and subscriptions.
|
|
752
|
+
*/
|
|
753
|
+
declare function useInventory(): StorefrontInventory;
|
|
754
|
+
|
|
755
|
+
interface Orders {
|
|
756
|
+
/**
|
|
757
|
+
* The signed-in customer's completed orders, newest first, a page at a time. Pass a page's `next` to
|
|
758
|
+
* get the one after it. Throws `NotAuthenticatedError` when nobody is signed in.
|
|
759
|
+
*/
|
|
760
|
+
getOrders: (nextUrl?: string) => Promise<Page<CompletedOrder>>;
|
|
761
|
+
/** The receipt for one of their orders, as a PDF, for your own download link or viewer. */
|
|
762
|
+
getReceipt: (order: Pick<CompletedOrder, 'id'>) => Promise<Blob>;
|
|
763
|
+
/** Saves the receipt for one of their orders, as the browser saves any download. */
|
|
764
|
+
downloadReceipt: (order: Pick<CompletedOrder, 'id'>) => Promise<void>;
|
|
765
|
+
}
|
|
766
|
+
/** The signed-in customer's purchases, for an account area of your own. */
|
|
767
|
+
declare function useOrders(): Orders;
|
|
768
|
+
|
|
769
|
+
/** A pricing option's price in the visitor's currency, written the way the checkout writes it. */
|
|
770
|
+
interface VariationPrice {
|
|
771
|
+
/** The visitor's currency, which the cart and the checkout use too. */
|
|
772
|
+
currency: string;
|
|
773
|
+
/** What it costs, or undefined until the catalog has a price for it in this currency. */
|
|
774
|
+
price: string | undefined;
|
|
775
|
+
/** What it cost before its discount, when it has one. */
|
|
776
|
+
originalPrice: string | undefined;
|
|
777
|
+
/** What its discount takes off, when it has one. */
|
|
778
|
+
saving: string | undefined;
|
|
779
|
+
/** What it costs as a number, for adding prices up. */
|
|
780
|
+
amount: number | undefined;
|
|
781
|
+
}
|
|
782
|
+
/**
|
|
783
|
+
* A pricing option's price, before and after its discount, in the visitor's currency. Renders again when
|
|
784
|
+
* the currency or the option changes, not when the cart does.
|
|
785
|
+
*
|
|
786
|
+
* ```tsx
|
|
787
|
+
* const { price, originalPrice } = usePrice(product.defaultVariation)
|
|
788
|
+
* ```
|
|
789
|
+
*/
|
|
790
|
+
declare function usePrice(variation: PricingVariation | null | undefined, format?: PriceFormat): VariationPrice;
|
|
791
|
+
|
|
792
|
+
type Reviews = MoonbaseClient['reviews'];
|
|
793
|
+
interface ProductReviews {
|
|
794
|
+
/** Whether the store takes reviews. Off until the catalog has loaded, and on older backends. */
|
|
795
|
+
enabled: boolean;
|
|
796
|
+
/** A product's published reviews, the first page. */
|
|
797
|
+
getReviews: (productId: string, filter?: {
|
|
798
|
+
sort?: ProductReviewSort;
|
|
799
|
+
stars?: number | null;
|
|
800
|
+
}) => ReturnType<Reviews['get']>;
|
|
801
|
+
/** The page after one `getReviews` or `getMoreReviews` returned, from its `next`. */
|
|
802
|
+
getMoreReviews: (next: string) => ReturnType<Reviews['getMore']>;
|
|
803
|
+
/** The signed-in customer's own review of a product. */
|
|
804
|
+
getMyReview: (productId: string) => ReturnType<Reviews['getMine']>;
|
|
805
|
+
/** Writes the customer's review, or rewrites the one they already have. */
|
|
806
|
+
saveReview: (productId: string, review: SubmitReviewRequest, existing: boolean) => ReturnType<Reviews['submit']>;
|
|
807
|
+
withdrawReview: (productId: string) => ReturnType<Reviews['withdraw']>;
|
|
808
|
+
/** Marks someone else's review helpful or not. */
|
|
809
|
+
voteOnReview: (productId: string, reviewId: string, direction: ReviewVoteDirection) => ReturnType<Reviews['vote']>;
|
|
810
|
+
}
|
|
811
|
+
/**
|
|
812
|
+
* The reviews of the store's products: reading them, writing your own, and voting on others'. Each
|
|
813
|
+
* product's `rating` comes with the catalog, and `hasRating(rating)` says whether there is a score
|
|
814
|
+
* worth showing yet.
|
|
815
|
+
*/
|
|
816
|
+
declare function useReviews(): ProductReviews;
|
|
817
|
+
|
|
818
|
+
interface VendorState {
|
|
819
|
+
/** The store's name, logo and contact details, or null until they load or if they can't. */
|
|
820
|
+
vendor: Vendor | null;
|
|
821
|
+
loading: boolean;
|
|
822
|
+
}
|
|
823
|
+
/** Who runs the store: its name, logo and contact details. */
|
|
824
|
+
declare function useVendor(): VendorState;
|
|
825
|
+
|
|
826
|
+
interface Vouchers {
|
|
827
|
+
/** What a voucher code gives, without redeeming it. */
|
|
828
|
+
peek: (code: string) => Promise<Voucher>;
|
|
829
|
+
/** Redeems a voucher code for the signed-in customer. */
|
|
830
|
+
redeem: (code: string) => Promise<Voucher>;
|
|
831
|
+
}
|
|
832
|
+
/** Voucher codes: what one gives, and redeeming it. An unknown code throws `Voucher code invalid`. */
|
|
833
|
+
declare function useVoucher(): Vouchers;
|
|
834
|
+
|
|
835
|
+
interface StorefrontProviderProps {
|
|
836
|
+
/**
|
|
837
|
+
* The storefront: one `createStorefront` made outside of any component, or one `getStorefront` hands
|
|
838
|
+
* back in a component.
|
|
839
|
+
*/
|
|
840
|
+
storefront: MoonbaseStorefront;
|
|
841
|
+
children?: ReactNode;
|
|
842
|
+
}
|
|
843
|
+
/** Makes a storefront available to every hook below it. */
|
|
844
|
+
declare function StorefrontProvider({ storefront, children }: StorefrontProviderProps): ReactNode;
|
|
845
|
+
/** The storefront from the nearest `<StorefrontProvider>`. */
|
|
846
|
+
declare function useStorefront(): MoonbaseStorefront;
|
|
847
|
+
/**
|
|
848
|
+
* Part of the storefront's state, and a render whenever that part changes. `selector` has to hand back
|
|
849
|
+
* something already in the state, such as `state => state.user`, rather than build a new object or
|
|
850
|
+
* array: anything worked out from the state belongs in a `useMemo` after this.
|
|
851
|
+
*/
|
|
852
|
+
declare function useStorefrontState<T>(selector: (state: StorefrontState) => T): T;
|
|
853
|
+
/**
|
|
854
|
+
* Calls `handler` each time the storefront reports `event`, for as long as the component is mounted.
|
|
855
|
+
* The latest `handler` is always the one called, so it can use the component's current props and state
|
|
856
|
+
* without subscribing again on every render.
|
|
857
|
+
*
|
|
858
|
+
* ```tsx
|
|
859
|
+
* useStorefrontEvent('checkoutCompleted', order => setThanks(order))
|
|
860
|
+
* ```
|
|
861
|
+
*
|
|
862
|
+
* It starts listening once the component has mounted, after hydration, so it misses what the storefront
|
|
863
|
+
* reported before then, such as the first `catalogUpdated` on a slow phone. Read what has to be known
|
|
864
|
+
* from the start from the state instead, with `useStorefrontState`, or subscribe with `storefront.on`
|
|
865
|
+
* where the storefront is made.
|
|
866
|
+
*/
|
|
867
|
+
declare function useStorefrontEvent<K extends keyof StorefrontEvents>(event: K, handler: StorefrontEvents[K]): void;
|
|
868
|
+
|
|
869
|
+
/**
|
|
870
|
+
* Connects to a Moonbase store, such as `https://demo.moonbase.sh`. Make it once, as the page loads
|
|
871
|
+
* and outside of any component, and hand it to `<StorefrontProvider>`:
|
|
872
|
+
*
|
|
873
|
+
* ```tsx
|
|
874
|
+
* const storefront = createStorefront('https://demo.moonbase.sh')
|
|
875
|
+
*
|
|
876
|
+
* createRoot(document.getElementById('root')!).render(
|
|
877
|
+
* <StorefrontProvider storefront={storefront}>
|
|
878
|
+
* <App />
|
|
879
|
+
* </StorefrontProvider>,
|
|
880
|
+
* )
|
|
881
|
+
* ```
|
|
882
|
+
*
|
|
883
|
+
* Coming back from the hosted checkout, it takes Moonbase's parameters off the address as it is made,
|
|
884
|
+
* so make it before a router that reads the address. To make it in a component instead, such as from
|
|
885
|
+
* a catalog the server fetched, use `getStorefront`.
|
|
886
|
+
*/
|
|
887
|
+
declare function createStorefront(endpoint: string, options?: StorefrontOptions): MoonbaseStorefront;
|
|
888
|
+
/**
|
|
889
|
+
* The storefront for `endpoint`: in a browser, made the first time it is asked for and the same one every
|
|
890
|
+
* time after, and on a server, a new one each time, as each render there is for another visitor. For
|
|
891
|
+
* making the storefront in a component, such as a Next.js layout's providers starting it from a catalog
|
|
892
|
+
* the server fetched:
|
|
893
|
+
*
|
|
894
|
+
* ```tsx
|
|
895
|
+
* 'use client'
|
|
896
|
+
*
|
|
897
|
+
* export function Providers({ catalog, children }: { catalog: Storefront, children: ReactNode }) {
|
|
898
|
+
* const storefront = getStorefront('https://demo.moonbase.sh', { initialCatalog: catalog })
|
|
899
|
+
* return <StorefrontProvider storefront={storefront}>{children}</StorefrontProvider>
|
|
900
|
+
* }
|
|
901
|
+
* ```
|
|
902
|
+
*
|
|
903
|
+
* React can render a component, and run a `useState` initializer, more than once for one page, and each
|
|
904
|
+
* `createStorefront` there would be another storefront following the tab. `options` only count when the
|
|
905
|
+
* storefront is made, so a later `initialCatalog` is ignored: the storefront already has a fresher
|
|
906
|
+
* catalog by then. Once the storefront is disposed, the next call makes a new one.
|
|
907
|
+
*/
|
|
908
|
+
declare function getStorefront(endpoint: string, options?: StorefrontOptions): MoonbaseStorefront;
|
|
909
|
+
|
|
910
|
+
export { type AccountData, type ActivationRequestOptions, type ActivationRequestState, type AddToCartOptions, type AttributionConsent, type AttributionConsentStatus, type AttributionConsentStatusByPlatform, type Auth, type Cart, type CartCheckoutOptions, type CartItem, type CartOfferState, type CheckoutItem, type CheckoutOptions, type CheckoutRedirectOptions, type CheckoutResult, type Communications, type Groups, type LockedOffer, MoonbaseStorefront, type Orders, type PagedAccountData, type ProductReviews, type StorefrontAuth, type StorefrontCart, type StorefrontEvents, type StorefrontInventory, type StorefrontOptions, StorefrontProvider, type StorefrontProviderProps, type StorefrontState, type VariationPrice, type VendorState, type Vouchers, createStorefront, getStorefront, useActivationRequest, useAttributionConsent, useAuth, useBundle, useBundles, useCart, useCartActions, useCartOffer, useCatalog, useCheckout, useCommunicationPreferences, useCurrency, useEligibleOffers, useGroups, useInventory, useLockedOffers, useOffer, useOffers, useOrderHistory, useOrders, useOwnedProduct, useOwnedProducts, usePrice, useProduct, useProductActivations, useProductLicenses, useProducts, usePromotions, useReviews, useStorefront, useStorefrontEvent, useStorefrontState, useSubscription, useSubscriptions, useVendor, useVoucher };
|