@usethrottle/storefront-react 0.0.0-stage → 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.
- package/CLAUDE.md +67 -0
- package/README.md +119 -2
- package/dist/StorefrontProvider-Br4wUHui.d.cts +559 -0
- package/dist/StorefrontProvider-DLEPEjg6.d.ts +559 -0
- package/dist/account/index.cjs +69 -0
- package/dist/account/index.cjs.map +1 -0
- package/dist/account/index.d.cts +23 -0
- package/dist/account/index.d.ts +23 -0
- package/dist/account/index.js +68 -0
- package/dist/account/index.js.map +1 -0
- package/dist/chunk-2LCPIY2P.cjs +16 -0
- package/dist/chunk-2LCPIY2P.cjs.map +1 -0
- package/dist/chunk-3A72UY6T.js +2126 -0
- package/dist/chunk-3A72UY6T.js.map +1 -0
- package/dist/chunk-3JMIVAHN.js +185 -0
- package/dist/chunk-3JMIVAHN.js.map +1 -0
- package/dist/chunk-4J6AGWNC.cjs +24 -0
- package/dist/chunk-4J6AGWNC.cjs.map +1 -0
- package/dist/chunk-4U6MYDZV.js +17 -0
- package/dist/chunk-4U6MYDZV.js.map +1 -0
- package/dist/chunk-66HDJVPS.js +22 -0
- package/dist/chunk-66HDJVPS.js.map +1 -0
- package/dist/chunk-6X2OZSNV.cjs +83 -0
- package/dist/chunk-6X2OZSNV.cjs.map +1 -0
- package/dist/chunk-6ZMMZ245.cjs +2127 -0
- package/dist/chunk-6ZMMZ245.cjs.map +1 -0
- package/dist/chunk-7R37CVAB.cjs +23 -0
- package/dist/chunk-7R37CVAB.cjs.map +1 -0
- package/dist/chunk-A3IFWQUV.js +368 -0
- package/dist/chunk-A3IFWQUV.js.map +1 -0
- package/dist/chunk-AYC2YK4E.cjs +95 -0
- package/dist/chunk-AYC2YK4E.cjs.map +1 -0
- package/dist/chunk-AZV5U7YB.cjs +18 -0
- package/dist/chunk-AZV5U7YB.cjs.map +1 -0
- package/dist/chunk-CE2SKNQP.cjs +71 -0
- package/dist/chunk-CE2SKNQP.cjs.map +1 -0
- package/dist/chunk-D76CRI4X.js +2175 -0
- package/dist/chunk-D76CRI4X.js.map +1 -0
- package/dist/chunk-DOAII637.cjs +186 -0
- package/dist/chunk-DOAII637.cjs.map +1 -0
- package/dist/chunk-DYHHAOMG.cjs +17 -0
- package/dist/chunk-DYHHAOMG.cjs.map +1 -0
- package/dist/chunk-EYSVU5SJ.js +196 -0
- package/dist/chunk-EYSVU5SJ.js.map +1 -0
- package/dist/chunk-HSUUDZWS.js +37 -0
- package/dist/chunk-HSUUDZWS.js.map +1 -0
- package/dist/chunk-HZ6VEN6Q.cjs +101 -0
- package/dist/chunk-HZ6VEN6Q.cjs.map +1 -0
- package/dist/chunk-IJOTLGPT.js +16 -0
- package/dist/chunk-IJOTLGPT.js.map +1 -0
- package/dist/chunk-ISDATHVC.js +219 -0
- package/dist/chunk-ISDATHVC.js.map +1 -0
- package/dist/chunk-LW2A6USV.js +100 -0
- package/dist/chunk-LW2A6USV.js.map +1 -0
- package/dist/chunk-M4YXSLRG.cjs +369 -0
- package/dist/chunk-M4YXSLRG.cjs.map +1 -0
- package/dist/chunk-NDUEJJLP.cjs +2176 -0
- package/dist/chunk-NDUEJJLP.cjs.map +1 -0
- package/dist/chunk-NNE4FYRT.js +820 -0
- package/dist/chunk-NNE4FYRT.js.map +1 -0
- package/dist/chunk-NW3EFHY2.js +15 -0
- package/dist/chunk-NW3EFHY2.js.map +1 -0
- package/dist/chunk-NZRUQUN5.js +167 -0
- package/dist/chunk-NZRUQUN5.js.map +1 -0
- package/dist/chunk-P6HHE57S.cjs +38 -0
- package/dist/chunk-P6HHE57S.cjs.map +1 -0
- package/dist/chunk-PHY7AY27.cjs +197 -0
- package/dist/chunk-PHY7AY27.cjs.map +1 -0
- package/dist/chunk-PNJOFFTL.cjs +128 -0
- package/dist/chunk-PNJOFFTL.cjs.map +1 -0
- package/dist/chunk-PXZQ4ONA.js +127 -0
- package/dist/chunk-PXZQ4ONA.js.map +1 -0
- package/dist/chunk-Q3VTUBPP.js +82 -0
- package/dist/chunk-Q3VTUBPP.js.map +1 -0
- package/dist/chunk-Q3XFD5UI.js +45 -0
- package/dist/chunk-Q3XFD5UI.js.map +1 -0
- package/dist/chunk-QM7KTT7F.js +94 -0
- package/dist/chunk-QM7KTT7F.js.map +1 -0
- package/dist/chunk-RLWZOLXL.js +70 -0
- package/dist/chunk-RLWZOLXL.js.map +1 -0
- package/dist/chunk-SV53BRP2.js +23 -0
- package/dist/chunk-SV53BRP2.js.map +1 -0
- package/dist/chunk-VWXJO427.cjs +821 -0
- package/dist/chunk-VWXJO427.cjs.map +1 -0
- package/dist/chunk-WIIOJDHR.cjs +220 -0
- package/dist/chunk-WIIOJDHR.cjs.map +1 -0
- package/dist/chunk-XQHGFWLG.cjs +46 -0
- package/dist/chunk-XQHGFWLG.cjs.map +1 -0
- package/dist/chunk-ZHCXI2ZZ.cjs +168 -0
- package/dist/chunk-ZHCXI2ZZ.cjs.map +1 -0
- package/dist/index-RSj2Rg62.d.cts +8 -0
- package/dist/index-RSj2Rg62.d.ts +8 -0
- package/dist/index.cjs +2829 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1718 -0
- package/dist/index.d.ts +1718 -0
- package/dist/index.js +2828 -0
- package/dist/index.js.map +1 -0
- package/dist/metadata-QhKw-tvz.d.cts +188 -0
- package/dist/metadata-QhKw-tvz.d.ts +188 -0
- package/dist/next/client.cjs +84 -0
- package/dist/next/client.cjs.map +1 -0
- package/dist/next/client.d.cts +40 -0
- package/dist/next/client.d.ts +40 -0
- package/dist/next/client.js +83 -0
- package/dist/next/client.js.map +1 -0
- package/dist/next/index.cjs +1090 -0
- package/dist/next/index.cjs.map +1 -0
- package/dist/next/index.d.cts +218 -0
- package/dist/next/index.d.ts +218 -0
- package/dist/next/index.js +1049 -0
- package/dist/next/index.js.map +1 -0
- package/dist/server/index.cjs +994 -0
- package/dist/server/index.cjs.map +1 -0
- package/dist/server/index.d.cts +229 -0
- package/dist/server/index.d.ts +229 -0
- package/dist/server/index.js +951 -0
- package/dist/server/index.js.map +1 -0
- package/dist/styles.css +2111 -0
- package/dist/use-part-DCfFk7kf.d.ts +24 -0
- package/dist/use-part-DgjPBL_O.d.cts +24 -0
- package/package.json +121 -3
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
import { SiteDesign } from '@usethrottle/ui';
|
|
2
|
+
import { ReactElement } from 'react';
|
|
3
|
+
import { S as SearchParamsInput, h as StorefrontMetadata } from '../metadata-QhKw-tvz.js';
|
|
4
|
+
import { CatalogClient } from '@usethrottle/catalog';
|
|
5
|
+
export { getPreviewToken, previewMiddleware } from '@usethrottle/catalog/next';
|
|
6
|
+
|
|
7
|
+
/** Options shared by every `create*Page` helper. */
|
|
8
|
+
type StorefrontRouteOptions = {
|
|
9
|
+
/** The catalog's publishable key. */
|
|
10
|
+
catalogKey: string;
|
|
11
|
+
/** The store's origin (`https://shop.example`), for canonical URLs. */
|
|
12
|
+
baseUrl: string;
|
|
13
|
+
/**
|
|
14
|
+
* The preview token of the request (`getPreviewToken`): draft settings and pages, read uncached. It reads
|
|
15
|
+
* the request's cookies, which makes every route built with this option render dynamically. Pass it
|
|
16
|
+
* only where that is wanted (a preview deployment or a preview-only route group), never on the
|
|
17
|
+
* statically cached production routes.
|
|
18
|
+
*/
|
|
19
|
+
previewToken?: () => Promise<string | undefined>;
|
|
20
|
+
/** The site design, for the title template and the share image (a Builder store passes its `loadSite`). */
|
|
21
|
+
site?: () => Promise<SiteDesign | null>;
|
|
22
|
+
/**
|
|
23
|
+
* How the product, collection or category the page is about is read (`LoaderInput.primaryCache`).
|
|
24
|
+
* `'no-store'` reads it live on every request, so a deleted product is a 404 at once, never a cached 200;
|
|
25
|
+
* the route then renders on demand (no ISR write). Default `'default'`: the long cache, cleared by the
|
|
26
|
+
* revalidate webhook, which a store that has set it up can keep.
|
|
27
|
+
*/
|
|
28
|
+
primaryCache?: 'default' | 'no-store';
|
|
29
|
+
};
|
|
30
|
+
type RouteProps = {
|
|
31
|
+
params: Promise<Record<string, string>>;
|
|
32
|
+
searchParams: Promise<SearchParamsInput>;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* What a `create*Page` helper returns: a route's `Page` and `generateMetadata` (and `generateStaticParams` for products), ready to re-export from `page.tsx`.
|
|
36
|
+
*/
|
|
37
|
+
type StorefrontRoute = {
|
|
38
|
+
Page: (p: RouteProps) => Promise<ReactElement>;
|
|
39
|
+
generateMetadata: (p: RouteProps) => Promise<StorefrontMetadata>;
|
|
40
|
+
generateStaticParams?: () => Promise<Array<Record<string, string>>>;
|
|
41
|
+
};
|
|
42
|
+
/** The shop, a collection, a category or a tag listing. The handle is the `handle` param (`tag` for a tag). */
|
|
43
|
+
declare function createShopAllPage(o: StorefrontRouteOptions & {
|
|
44
|
+
source?: 'all' | 'collection' | 'category' | 'tag';
|
|
45
|
+
}): StorefrontRoute;
|
|
46
|
+
/**
|
|
47
|
+
* A product page, `handle` param. By default no product is prerendered at build: each is rendered on its first
|
|
48
|
+
* visit and then cached until the catalog changes, because every deploy writes all of its prerendered pages
|
|
49
|
+
* (ISR writes on Vercel). `staticParams: n` prerenders the `n` most recently updated products at build, capped at 50:
|
|
50
|
+
* each prerendered product is an ISR write (its HTML and its data) on every deploy, so 50 is about 100 writes per deploy
|
|
51
|
+
* and a larger number is never accepted. The rest render on their first visit and are cached until the catalog changes.
|
|
52
|
+
*/
|
|
53
|
+
declare function createProductPage(o: StorefrontRouteOptions & {
|
|
54
|
+
staticParams?: number;
|
|
55
|
+
}): StorefrontRoute;
|
|
56
|
+
/**
|
|
57
|
+
* The search results page, query in `?q=`. It reads `searchParams`, so Next renders it per request, and its
|
|
58
|
+
* list is read with `cache: 'no-store'`: nothing about a search is cached or written as a static page.
|
|
59
|
+
*/
|
|
60
|
+
declare function createSearchPage(o: StorefrontRouteOptions): StorefrontRoute;
|
|
61
|
+
/** The account page: the dashboard, or the sign-in or sign-up form. Never indexed. */
|
|
62
|
+
declare function createAccountPage(o: StorefrontRouteOptions & {
|
|
63
|
+
view?: 'dashboard' | 'sign-in' | 'sign-up';
|
|
64
|
+
}): StorefrontRoute;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The server-side half of the generation backstop. `useGenerationWatch` sees the catalog's generation
|
|
68
|
+
* change in an open tab, but `router.refresh()` re-renders from Next's data cache, which only the
|
|
69
|
+
* `storefront.changed` webhook clears. With the webhook off or lost, nothing would. This is the check
|
|
70
|
+
* the tab asks for first: read the generation uncached, and when it differs from the last one this
|
|
71
|
+
* instance knew, clear the catalog's cache tags so the refresh that follows renders fresh.
|
|
72
|
+
*
|
|
73
|
+
* Pure: the clock, the reads and the tag clearing are injected (`createGenerationSyncHandler` wires
|
|
74
|
+
* the SDK's `syncCatalogGeneration` and Next's `revalidateTag`). One upstream read per `minIntervalMs`
|
|
75
|
+
* per instance; a request inside the window, or while a read is running, shares or skips it, so the
|
|
76
|
+
* route cannot be used to hammer the catalog. Nothing is cleared unless the generation really changed,
|
|
77
|
+
* so it cannot be used to empty the cache either.
|
|
78
|
+
*/
|
|
79
|
+
type GenerationSyncDeps = {
|
|
80
|
+
now(): number;
|
|
81
|
+
/** The generation of the config Next's cache holds (cached read); undefined if it cannot be read. */
|
|
82
|
+
cachedGeneration(): Promise<number | undefined>;
|
|
83
|
+
/** The SDK's `syncCatalogGeneration` shape: reads uncached, calls `onChange` when `previous` differs. */
|
|
84
|
+
sync(previous: number | undefined, onChange: (generation: number) => Promise<void>): Promise<{
|
|
85
|
+
generation: number;
|
|
86
|
+
changed: boolean;
|
|
87
|
+
}>;
|
|
88
|
+
/**
|
|
89
|
+
* Clears the catalog's cache tag. It runs inside the request that asked for it (Next applies a
|
|
90
|
+
* `revalidateTag` when that request ends). Answer `{ deferredMs }` when the clearing was not made (a
|
|
91
|
+
* minute has not passed since the last one): the change is then not recorded as applied, so the next
|
|
92
|
+
* call finds it again, and the answer tells the tab when to ask.
|
|
93
|
+
*/
|
|
94
|
+
revalidate(): void | {
|
|
95
|
+
deferredMs: number;
|
|
96
|
+
} | Promise<void | {
|
|
97
|
+
deferredMs: number;
|
|
98
|
+
}>;
|
|
99
|
+
/** Default 5000. */
|
|
100
|
+
minIntervalMs?: number;
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* What the generation sync answers: whether the catalog changed, whether the read was throttled, and when to ask again.
|
|
104
|
+
*/
|
|
105
|
+
type GenerationSyncResult = {
|
|
106
|
+
changed: boolean;
|
|
107
|
+
throttled?: true;
|
|
108
|
+
/** A change was found but its clearing is deferred: ask again after this many ms. */
|
|
109
|
+
retryAfterMs?: number;
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* Builds the generation check behind `createGenerationSyncHandler`, for a store that writes its own route. The returned function reads the live generation at most once per `minIntervalMs` and clears the cache only when the generation really moved.
|
|
113
|
+
*/
|
|
114
|
+
declare function createGenerationSync(deps: GenerationSyncDeps): () => Promise<GenerationSyncResult>;
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The one cache tag the storefront clears. Every catalog read of `createStorefrontServerClient` carries it,
|
|
118
|
+
* so clearing it is enough; clearing per scope, per product or per route would regenerate pages (ISR
|
|
119
|
+
* writes on Vercel) once for each.
|
|
120
|
+
*/
|
|
121
|
+
declare const CATALOG_TAG = "throttle-catalog";
|
|
122
|
+
/** Clearing happens at most once in this window per server instance. */
|
|
123
|
+
declare const REVALIDATE_WINDOW_MS = 60000;
|
|
124
|
+
/** Clears one tag. Next 16's `revalidateTag(tag, { expire: 0 })`; Next 15 ignores the second argument. */
|
|
125
|
+
type TagRevalidator = (tag: string) => void | Promise<void>;
|
|
126
|
+
/** The cache-clearing gate: it turns any number of change notices into at most one clearing per window. */
|
|
127
|
+
type CoalescedRevalidate = {
|
|
128
|
+
/**
|
|
129
|
+
* A change was seen (a verified webhook). Clears now when the window is over, else leaves it pending
|
|
130
|
+
* for the next call. Resolves `'cleared'` or `{ deferredMs }`, the time until a call can clear it.
|
|
131
|
+
*/
|
|
132
|
+
request(): Promise<'cleared' | {
|
|
133
|
+
deferredMs: number;
|
|
134
|
+
}>;
|
|
135
|
+
/** Clears now when a change is pending and the window is over, else does nothing. */
|
|
136
|
+
flushIfDue(): Promise<void>;
|
|
137
|
+
/**
|
|
138
|
+
* Like `request` for a caller that keeps the change itself (the generation sync keeps the generation it
|
|
139
|
+
* has not applied): nothing is left pending here when the window is not over.
|
|
140
|
+
*/
|
|
141
|
+
tryClear(): Promise<'cleared' | {
|
|
142
|
+
deferredMs: number;
|
|
143
|
+
}>;
|
|
144
|
+
};
|
|
145
|
+
/**
|
|
146
|
+
* Options of `createCoalescedRevalidate`. The defaults are the cost-safe ones; there is rarely a reason to change them.
|
|
147
|
+
*/
|
|
148
|
+
type CoalescedRevalidateOptions = {
|
|
149
|
+
/** Default `[CATALOG_TAG]`. */
|
|
150
|
+
tags?: readonly string[];
|
|
151
|
+
/** Default Next's `revalidateTag`. */
|
|
152
|
+
revalidateTag?: TagRevalidator;
|
|
153
|
+
/** Never below `REVALIDATE_WINDOW_MS`. */
|
|
154
|
+
windowMs?: number;
|
|
155
|
+
};
|
|
156
|
+
/**
|
|
157
|
+
* At most one clearing per window, per server instance (another instance has its own window, so a
|
|
158
|
+
* multi-instance deployment can clear once a minute on each).
|
|
159
|
+
*
|
|
160
|
+
* There is no timer. Next applies `revalidateTag` when the request that called it ends, so a clearing
|
|
161
|
+
* made from a timer, after the response, would do nothing. A change inside the window is instead left
|
|
162
|
+
* pending (the webhook) or unrecorded (the generation sync), and the first later call that finds the
|
|
163
|
+
* window over clears it inside its own request.
|
|
164
|
+
*/
|
|
165
|
+
declare function createCoalescedRevalidate(options?: CoalescedRevalidateOptions): CoalescedRevalidate;
|
|
166
|
+
|
|
167
|
+
/** Options of `createGenerationSyncHandler`. */
|
|
168
|
+
type GenerationSyncHandlerOptions = {
|
|
169
|
+
/** A server catalog client (`createStorefrontServerClient`): its cached `config()` is the generation the data cache holds. */
|
|
170
|
+
client: CatalogClient;
|
|
171
|
+
/** The tags to clear when the generation moved. Default `['throttle-catalog']`, the one coarse tag. */
|
|
172
|
+
tags?: string[];
|
|
173
|
+
/** The least time between two upstream reads, default 5000. */
|
|
174
|
+
minIntervalMs?: number;
|
|
175
|
+
/** Replaces Next's `revalidateTag` (tests). The clearing is still limited to once a minute. */
|
|
176
|
+
revalidateTag?: TagRevalidator;
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* The generation backstop's server half, for `app/api/throttle/sync/route.ts`:
|
|
180
|
+
* `export const { POST } = createGenerationSyncHandler({ client })`.
|
|
181
|
+
*
|
|
182
|
+
* The open tab's watcher POSTs here when it sees the generation move, before it refreshes. It reads the live
|
|
183
|
+
* generation (at most once per `minIntervalMs`), and only when that differs from the one the data cache holds
|
|
184
|
+
* it clears the catalog tag, and at most once a minute. Answers `200 { changed, throttled? }`, or
|
|
185
|
+
* `502 { changed: false }` when the catalog cannot be read. No auth: it cannot empty the cache unless the
|
|
186
|
+
* catalog's generation really moved.
|
|
187
|
+
*
|
|
188
|
+
* The once-a-minute limit is per server instance. A change found inside the window is not recorded as
|
|
189
|
+
* applied: the answer carries `retryAfterMs`, the tab asks again then, and that call clears the tag inside
|
|
190
|
+
* its own request (Next applies `revalidateTag` when the request ends, so nothing is cleared by a timer).
|
|
191
|
+
*/
|
|
192
|
+
declare function createGenerationSyncHandler(o: GenerationSyncHandlerOptions): {
|
|
193
|
+
POST(): Promise<Response>;
|
|
194
|
+
};
|
|
195
|
+
|
|
196
|
+
/** Options of `createRevalidateHandler`. */
|
|
197
|
+
type RevalidateHandlerOptions = {
|
|
198
|
+
/** The webhook's signing secret; pass `process.env.THROTTLE_WEBHOOK_SECRET` straight in. A list accepts any of them. */
|
|
199
|
+
secret: string | undefined | readonly (string | undefined)[];
|
|
200
|
+
/** The store's generation floor key, as `createRevalidateHandler` of `@usethrottle/catalog/next` takes it. */
|
|
201
|
+
floorKey?: string;
|
|
202
|
+
/** Default: the instance's shared coalescer on `throttle-catalog`. */
|
|
203
|
+
revalidate?: CoalescedRevalidate;
|
|
204
|
+
};
|
|
205
|
+
/**
|
|
206
|
+
* The route handler for the catalog's signed `storefront.changed` webhook, the primary way a change reaches
|
|
207
|
+
* the storefront. The catalog SDK's handler checks the signature first and refuses (401) an unsigned or wrong
|
|
208
|
+
* one before anything is read or cleared. What this adds is the cost rule: whatever scopes the notice names, one
|
|
209
|
+
* coarse tag (`throttle-catalog`) is cleared, and at most once a minute however many notices arrive, so a
|
|
210
|
+
* burst of merchant edits is one regeneration, not one per product. A `test` event clears nothing.
|
|
211
|
+
*
|
|
212
|
+
* The limit is per server instance. A notice inside the window is left pending, and the next webhook or
|
|
213
|
+
* sync call after the window clears it inside its own request (Next applies `revalidateTag` when the
|
|
214
|
+
* request ends, so there is no timer); the answer then says `deferred`.
|
|
215
|
+
*/
|
|
216
|
+
declare function createRevalidateHandler(options: RevalidateHandlerOptions): (req: Request) => Promise<Response>;
|
|
217
|
+
|
|
218
|
+
export { CATALOG_TAG, type CoalescedRevalidate, type CoalescedRevalidateOptions, type GenerationSyncDeps, type GenerationSyncHandlerOptions, type GenerationSyncResult, REVALIDATE_WINDOW_MS, type RevalidateHandlerOptions, type StorefrontRoute, type StorefrontRouteOptions, createAccountPage, createCoalescedRevalidate, createGenerationSync, createGenerationSyncHandler, createProductPage, createRevalidateHandler, createSearchPage, createShopAllPage };
|