@swell/apps-sdk 1.0.189 → 2.0.0-alpha.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.
Files changed (229) hide show
  1. package/README.md +146 -247
  2. package/dist/backend.d.cts +81 -0
  3. package/dist/backend.d.ts +81 -0
  4. package/dist/backend.js +152 -0
  5. package/dist/browser-refusal.d.cts +1 -0
  6. package/dist/browser-refusal.d.ts +1 -0
  7. package/dist/browser-refusal.js +2 -0
  8. package/dist/context.d.cts +21 -0
  9. package/dist/context.d.ts +21 -0
  10. package/dist/context.js +42 -0
  11. package/dist/error.d.cts +23 -0
  12. package/dist/error.d.ts +23 -0
  13. package/dist/error.js +30 -0
  14. package/dist/guard.d.cts +1 -0
  15. package/dist/guard.d.ts +1 -0
  16. package/dist/guard.js +4 -0
  17. package/dist/index.d.cts +9 -0
  18. package/dist/index.d.ts +9 -0
  19. package/dist/index.js +5 -20298
  20. package/dist/staff.d.cts +16 -0
  21. package/dist/staff.d.ts +16 -0
  22. package/dist/staff.js +33 -0
  23. package/dist/storefront.d.cts +28 -0
  24. package/dist/storefront.d.ts +28 -0
  25. package/dist/storefront.js +44 -0
  26. package/dist/version.d.cts +1 -0
  27. package/dist/version.d.ts +1 -0
  28. package/dist/version.js +2 -0
  29. package/dist/workflow.d.cts +1 -0
  30. package/dist/workflow.d.ts +1 -0
  31. package/dist/workflow.js +35 -0
  32. package/package.json +48 -63
  33. package/dist/index.cjs +0 -20546
  34. package/dist/index.cjs.map +0 -7
  35. package/dist/index.js.map +0 -7
  36. package/dist/index.mjs +0 -20403
  37. package/dist/index.mjs.map +0 -7
  38. package/dist/src/api.d.ts +0 -96
  39. package/dist/src/cache/cache.d.ts +0 -41
  40. package/dist/src/cache/cf-worker-kv-keyv-adapter.d.ts +0 -18
  41. package/dist/src/cache/constants.d.ts +0 -7
  42. package/dist/src/cache/content-cache.d.ts +0 -21
  43. package/dist/src/cache/html-cache/html-cache-backend.d.ts +0 -64
  44. package/dist/src/cache/html-cache/html-cache-factory.d.ts +0 -9
  45. package/dist/src/cache/html-cache/html-cache-kv.d.ts +0 -38
  46. package/dist/src/cache/html-cache/html-cache-worker.d.ts +0 -8
  47. package/dist/src/cache/html-cache/html-cache.d.ts +0 -120
  48. package/dist/src/cache/html-cache/index.d.ts +0 -4
  49. package/dist/src/cache/index.d.ts +0 -9
  50. package/dist/src/cache/kv-variety.d.ts +0 -10
  51. package/dist/src/cache/request-cache.d.ts +0 -4
  52. package/dist/src/cache/resource-cache.d.ts +0 -4
  53. package/dist/src/cache/theme-cache.d.ts +0 -4
  54. package/dist/src/cache/theme-file-cache.d.ts +0 -87
  55. package/dist/src/compatibility/drops/all_products.d.ts +0 -10
  56. package/dist/src/compatibility/drops/articles.d.ts +0 -10
  57. package/dist/src/compatibility/drops/blogs.d.ts +0 -10
  58. package/dist/src/compatibility/drops/collections.d.ts +0 -19
  59. package/dist/src/compatibility/drops/image-src.d.ts +0 -15
  60. package/dist/src/compatibility/drops/image.d.ts +0 -29
  61. package/dist/src/compatibility/drops/images.d.ts +0 -9
  62. package/dist/src/compatibility/drops/money.d.ts +0 -10
  63. package/dist/src/compatibility/drops/object-handles.d.ts +0 -6
  64. package/dist/src/compatibility/drops/pages.d.ts +0 -17
  65. package/dist/src/compatibility/drops/robots-rule.d.ts +0 -9
  66. package/dist/src/compatibility/drops/template.d.ts +0 -9
  67. package/dist/src/compatibility/shopify-configs.d.ts +0 -8
  68. package/dist/src/compatibility/shopify-fonts.d.ts +0 -1
  69. package/dist/src/compatibility/shopify-objects/address.d.ts +0 -7
  70. package/dist/src/compatibility/shopify-objects/article.d.ts +0 -7
  71. package/dist/src/compatibility/shopify-objects/blog.d.ts +0 -6
  72. package/dist/src/compatibility/shopify-objects/cart.d.ts +0 -6
  73. package/dist/src/compatibility/shopify-objects/collection.d.ts +0 -7
  74. package/dist/src/compatibility/shopify-objects/collections.d.ts +0 -6
  75. package/dist/src/compatibility/shopify-objects/content.d.ts +0 -12
  76. package/dist/src/compatibility/shopify-objects/currency.d.ts +0 -5
  77. package/dist/src/compatibility/shopify-objects/customer.d.ts +0 -6
  78. package/dist/src/compatibility/shopify-objects/filter.d.ts +0 -6
  79. package/dist/src/compatibility/shopify-objects/font.d.ts +0 -5
  80. package/dist/src/compatibility/shopify-objects/form.d.ts +0 -29
  81. package/dist/src/compatibility/shopify-objects/image.d.ts +0 -10
  82. package/dist/src/compatibility/shopify-objects/index.d.ts +0 -27
  83. package/dist/src/compatibility/shopify-objects/line_item.d.ts +0 -7
  84. package/dist/src/compatibility/shopify-objects/link.d.ts +0 -5
  85. package/dist/src/compatibility/shopify-objects/localization.d.ts +0 -5
  86. package/dist/src/compatibility/shopify-objects/media.d.ts +0 -9
  87. package/dist/src/compatibility/shopify-objects/money.d.ts +0 -3
  88. package/dist/src/compatibility/shopify-objects/order.d.ts +0 -11
  89. package/dist/src/compatibility/shopify-objects/page.d.ts +0 -5
  90. package/dist/src/compatibility/shopify-objects/paginate.d.ts +0 -5
  91. package/dist/src/compatibility/shopify-objects/predictive_search.d.ts +0 -5
  92. package/dist/src/compatibility/shopify-objects/product.d.ts +0 -9
  93. package/dist/src/compatibility/shopify-objects/recommendations.d.ts +0 -5
  94. package/dist/src/compatibility/shopify-objects/resource.d.ts +0 -27
  95. package/dist/src/compatibility/shopify-objects/search.d.ts +0 -5
  96. package/dist/src/compatibility/shopify-objects/shop.d.ts +0 -5
  97. package/dist/src/compatibility/shopify-objects/template.d.ts +0 -4
  98. package/dist/src/compatibility/shopify-objects/variant.d.ts +0 -6
  99. package/dist/src/compatibility/shopify.d.ts +0 -134
  100. package/dist/src/constants.d.ts +0 -598
  101. package/dist/src/content.d.ts +0 -8
  102. package/dist/src/easyblocks/config.d.ts +0 -152
  103. package/dist/src/easyblocks/index.d.ts +0 -2
  104. package/dist/src/easyblocks/utils.d.ts +0 -23
  105. package/dist/src/editor/resources.d.ts +0 -9
  106. package/dist/src/fonts.d.ts +0 -6
  107. package/dist/src/globals.d.ts +0 -7
  108. package/dist/src/index.d.ts +0 -16
  109. package/dist/src/liquid/color.d.ts +0 -33
  110. package/dist/src/liquid/drops/render.d.ts +0 -10
  111. package/dist/src/liquid/filters/asset_url.d.ts +0 -3
  112. package/dist/src/liquid/filters/brightness_difference.d.ts +0 -2
  113. package/dist/src/liquid/filters/color_brightness.d.ts +0 -2
  114. package/dist/src/liquid/filters/color_contrast.d.ts +0 -2
  115. package/dist/src/liquid/filters/color_darken.d.ts +0 -2
  116. package/dist/src/liquid/filters/color_desaturate.d.ts +0 -2
  117. package/dist/src/liquid/filters/color_difference.d.ts +0 -2
  118. package/dist/src/liquid/filters/color_extract.d.ts +0 -4
  119. package/dist/src/liquid/filters/color_lighten.d.ts +0 -2
  120. package/dist/src/liquid/filters/color_mix.d.ts +0 -2
  121. package/dist/src/liquid/filters/color_modify.d.ts +0 -3
  122. package/dist/src/liquid/filters/color_saturate.d.ts +0 -2
  123. package/dist/src/liquid/filters/color_to_hex.d.ts +0 -2
  124. package/dist/src/liquid/filters/color_to_hsl.d.ts +0 -2
  125. package/dist/src/liquid/filters/color_to_rgb.d.ts +0 -2
  126. package/dist/src/liquid/filters/date.d.ts +0 -7
  127. package/dist/src/liquid/filters/date_next_interval.d.ts +0 -3
  128. package/dist/src/liquid/filters/default_errors.d.ts +0 -3
  129. package/dist/src/liquid/filters/divided_by.d.ts +0 -2
  130. package/dist/src/liquid/filters/embedded_content.d.ts +0 -2
  131. package/dist/src/liquid/filters/escape.d.ts +0 -3
  132. package/dist/src/liquid/filters/font_face.d.ts +0 -2
  133. package/dist/src/liquid/filters/font_modify.d.ts +0 -3
  134. package/dist/src/liquid/filters/font_url.d.ts +0 -2
  135. package/dist/src/liquid/filters/format_address.d.ts +0 -6
  136. package/dist/src/liquid/filters/handleize.d.ts +0 -3
  137. package/dist/src/liquid/filters/image_tag.d.ts +0 -3
  138. package/dist/src/liquid/filters/image_url.d.ts +0 -8
  139. package/dist/src/liquid/filters/index.d.ts +0 -120
  140. package/dist/src/liquid/filters/inline_asset_content.d.ts +0 -2
  141. package/dist/src/liquid/filters/inline_editable.d.ts +0 -4
  142. package/dist/src/liquid/filters/json.d.ts +0 -3
  143. package/dist/src/liquid/filters/json_pretty.d.ts +0 -3
  144. package/dist/src/liquid/filters/locale_flag.d.ts +0 -2
  145. package/dist/src/liquid/filters/minus.d.ts +0 -2
  146. package/dist/src/liquid/filters/money.d.ts +0 -4
  147. package/dist/src/liquid/filters/money_with_currency.d.ts +0 -3
  148. package/dist/src/liquid/filters/money_without_currency.d.ts +0 -3
  149. package/dist/src/liquid/filters/money_without_trailing_zeros.d.ts +0 -3
  150. package/dist/src/liquid/filters/preload_tag.d.ts +0 -3
  151. package/dist/src/liquid/filters/script_tag.d.ts +0 -3
  152. package/dist/src/liquid/filters/shopify/asset_img_url.d.ts +0 -3
  153. package/dist/src/liquid/filters/shopify/default_pagination.d.ts +0 -3
  154. package/dist/src/liquid/filters/shopify/hex_to_rgba.d.ts +0 -2
  155. package/dist/src/liquid/filters/shopify/img_url.d.ts +0 -3
  156. package/dist/src/liquid/filters/shopify/item_count_for_variant.d.ts +0 -6
  157. package/dist/src/liquid/filters/shopify/payment_button.d.ts +0 -2
  158. package/dist/src/liquid/filters/shopify/payment_terms.d.ts +0 -2
  159. package/dist/src/liquid/filters/shopify/placeholder-svgs/index.d.ts +0 -5
  160. package/dist/src/liquid/filters/shopify/placeholder_svg_tag.d.ts +0 -3
  161. package/dist/src/liquid/filters/shopify/shopify_asset_url.d.ts +0 -3
  162. package/dist/src/liquid/filters/shopify/structured_data.d.ts +0 -3
  163. package/dist/src/liquid/filters/stylesheet_tag.d.ts +0 -3
  164. package/dist/src/liquid/filters/time_tag.d.ts +0 -2
  165. package/dist/src/liquid/filters/translate.d.ts +0 -3
  166. package/dist/src/liquid/filters/where.d.ts +0 -3
  167. package/dist/src/liquid/font.d.ts +0 -51
  168. package/dist/src/liquid/form.d.ts +0 -17
  169. package/dist/src/liquid/hash.d.ts +0 -5
  170. package/dist/src/liquid/index.d.ts +0 -52
  171. package/dist/src/liquid/operators.d.ts +0 -10
  172. package/dist/src/liquid/tags/assign.d.ts +0 -3
  173. package/dist/src/liquid/tags/case.d.ts +0 -3
  174. package/dist/src/liquid/tags/comment.d.ts +0 -3
  175. package/dist/src/liquid/tags/content_for.d.ts +0 -3
  176. package/dist/src/liquid/tags/doc.d.ts +0 -2
  177. package/dist/src/liquid/tags/for.d.ts +0 -3
  178. package/dist/src/liquid/tags/form.d.ts +0 -3
  179. package/dist/src/liquid/tags/if.d.ts +0 -4
  180. package/dist/src/liquid/tags/index.d.ts +0 -42
  181. package/dist/src/liquid/tags/inline_editable.d.ts +0 -3
  182. package/dist/src/liquid/tags/javascript.d.ts +0 -3
  183. package/dist/src/liquid/tags/layout.d.ts +0 -3
  184. package/dist/src/liquid/tags/paginate.d.ts +0 -3
  185. package/dist/src/liquid/tags/render.d.ts +0 -6
  186. package/dist/src/liquid/tags/section.d.ts +0 -3
  187. package/dist/src/liquid/tags/sections.d.ts +0 -3
  188. package/dist/src/liquid/tags/shopify/include.d.ts +0 -3
  189. package/dist/src/liquid/tags/shopify/schema.d.ts +0 -3
  190. package/dist/src/liquid/tags/style.d.ts +0 -3
  191. package/dist/src/liquid/tags/stylesheet.d.ts +0 -3
  192. package/dist/src/liquid/test-helpers.d.ts +0 -8
  193. package/dist/src/liquid/tokens/identifier-token.d.ts +0 -9
  194. package/dist/src/liquid/tokens/index.d.ts +0 -2
  195. package/dist/src/liquid/tokienizer.d.ts +0 -5
  196. package/dist/src/liquid/utils.d.ts +0 -45
  197. package/dist/src/menus.d.ts +0 -25
  198. package/dist/src/resources/account.d.ts +0 -6
  199. package/dist/src/resources/addresses.d.ts +0 -7
  200. package/dist/src/resources/blog.d.ts +0 -7
  201. package/dist/src/resources/blog_category.d.ts +0 -7
  202. package/dist/src/resources/cart.d.ts +0 -6
  203. package/dist/src/resources/categories.d.ts +0 -7
  204. package/dist/src/resources/category.d.ts +0 -7
  205. package/dist/src/resources/index.d.ts +0 -48
  206. package/dist/src/resources/order.d.ts +0 -7
  207. package/dist/src/resources/orders.d.ts +0 -7
  208. package/dist/src/resources/page.d.ts +0 -7
  209. package/dist/src/resources/predictive_search.d.ts +0 -6
  210. package/dist/src/resources/product.d.ts +0 -7
  211. package/dist/src/resources/product_helpers.d.ts +0 -21
  212. package/dist/src/resources/search.d.ts +0 -6
  213. package/dist/src/resources/subscription.d.ts +0 -7
  214. package/dist/src/resources/subscriptions.d.ts +0 -7
  215. package/dist/src/resources/swell_types.d.ts +0 -163
  216. package/dist/src/resources/variant.d.ts +0 -9
  217. package/dist/src/resources.d.ts +0 -113
  218. package/dist/src/theme/theme-loader.d.ts +0 -110
  219. package/dist/src/theme.d.ts +0 -204
  220. package/dist/src/utils/escape.d.ts +0 -1
  221. package/dist/src/utils/index.d.ts +0 -34
  222. package/dist/src/utils/kv-flavor.d.ts +0 -7
  223. package/dist/src/utils/logger.d.ts +0 -21
  224. package/dist/src/utils/md5.d.ts +0 -1
  225. package/dist/types/cloudflare.d.ts +0 -61
  226. package/dist/types/shopify.d.ts +0 -1035
  227. package/dist/types/swell.d.ts +0 -576
  228. package/types/index.d.ts +0 -4
  229. package/types/svg.d.ts +0 -4
package/dist/src/api.d.ts DELETED
@@ -1,96 +0,0 @@
1
- import qs from 'qs';
2
- import type { SwellClient } from 'swell-js';
3
- import type { SwellApiParams, SwellAppConfig, SwellErrorOptions, SwellMenu, SwellData, SwellAppShopifyCompatibilityConfig } from '../types/swell';
4
- import type { CFThemeEnv, CFWorkerContext } from '../types/cloudflare';
5
- export * from './resources';
6
- export * from './resources/index';
7
- export declare class Swell {
8
- url: URL;
9
- headers: Record<string, string | undefined>;
10
- swellHeaders: Record<string, string | undefined>;
11
- queryParams: qs.ParsedQs;
12
- workerCtx?: CFWorkerContext;
13
- workerEnv?: CFThemeEnv;
14
- config?: SwellAppConfig;
15
- shopifyCompatibilityConfig?: SwellAppShopifyCompatibilityConfig;
16
- backend?: SwellBackendAPI;
17
- storefront: SwellClient<'snake'>;
18
- storefrontContext: SwellData;
19
- instanceId: string;
20
- isPreview: boolean;
21
- isEditor: boolean;
22
- sentResponse: boolean;
23
- storefront_url?: string;
24
- private resourceLoadingIndicator?;
25
- constructor(params: SwellApiParams);
26
- static formatHeaders(serverHeaders?: Headers | Record<string, string | undefined>): {
27
- headers: Record<string, string | undefined>;
28
- swellHeaders: Record<string, string | undefined>;
29
- };
30
- static formatQueryParams(queryParams?: URLSearchParams | Record<string, string | undefined>): qs.ParsedQs;
31
- /**
32
- * Checks if cache bypass is requested via X-Cache-Bypass header
33
- */
34
- private shouldBypassCache;
35
- /**
36
- * Returns fields from the current account that may affect requests.
37
- * Currently, only the 'group' field is returned.
38
- * It is preferable to use the account_id from storefrontContext rather than the swell-session cookie, as the cookie contains a lot of other data
39
- * This increases the overall cache size
40
- */
41
- private getAccountCacheKey;
42
- /**
43
- * Fetches a resource.
44
- * First attempts to fetch from cache.
45
- */
46
- getCachedResource<T>(key: string, args: unknown[], handler: () => T | Promise<T>, isCacheble?: boolean): Promise<T | undefined>;
47
- getAppSettings(): Promise<SwellData>;
48
- getStorefrontSettings(force?: boolean): Promise<SwellData>;
49
- getStorefrontMenus(): SwellMenu[];
50
- getStorefrontLocalization(): {
51
- locale: string;
52
- currency: string;
53
- };
54
- get<T = SwellData>(...args: Parameters<SwellBackendAPI['get']>): Promise<T | undefined>;
55
- put<T = SwellData>(...args: Parameters<SwellBackendAPI['put']>): Promise<T | undefined>;
56
- post<T = SwellData>(...args: Parameters<SwellBackendAPI['post']>): Promise<T | undefined>;
57
- delete<T = SwellData>(...args: Parameters<SwellBackendAPI['delete']>): Promise<T | undefined>;
58
- /**
59
- * Sets a loading handler to be called when a storefront resource is loading.
60
- */
61
- isLoading(loading?: boolean): void;
62
- private getStorefrontInstance;
63
- /**
64
- * Initializes resources passed in from the server via request headers.
65
- */
66
- private initStorefrontContext;
67
- private isStorefrontRequestCacheable;
68
- private getCacheableStorefrontRequestHandler;
69
- /**
70
- * Caches client resources in memory.
71
- */
72
- private getResourceCache;
73
- /**
74
- * Caches client storefront API requests in memory.
75
- */
76
- private getRequestCache;
77
- }
78
- export declare class SwellBackendAPI {
79
- apiHost: string;
80
- apiAuth: string;
81
- constructor({ storeId, accessToken, apiHost, }: {
82
- storeId: string;
83
- accessToken: string;
84
- apiHost?: string;
85
- });
86
- makeRequest<T>(method: string, url: string, data?: object): Promise<T>;
87
- stringifyQuery(queryObject: object, prefix?: string): string;
88
- get<T = SwellData>(url: string, query?: SwellData): Promise<T>;
89
- put<T = SwellData>(url: string, data: SwellData): Promise<T>;
90
- post<T = SwellData>(url: string, data: SwellData): Promise<T>;
91
- delete<T = SwellData>(url: string, data?: SwellData): Promise<T>;
92
- }
93
- export declare class SwellError extends Error {
94
- status: number;
95
- constructor(message: string, options?: SwellErrorOptions);
96
- }
@@ -1,41 +0,0 @@
1
- import { type CreateCacheOptions as OriginalCreateCacheOptions } from 'cache-manager';
2
- import type { CFWorkerKV, CFWorkerContext } from 'types/cloudflare';
3
- export type CreateCacheOptions = OriginalCreateCacheOptions & {
4
- kvStore?: CFWorkerKV;
5
- workerCtx?: CFWorkerContext;
6
- };
7
- /**
8
- * Cache supports memory or KV
9
- * The KV layer supports namespacing and compression
10
- */
11
- export declare class Cache {
12
- private client;
13
- private workerCtx?;
14
- constructor(options?: CreateCacheOptions);
15
- /**
16
- * Always fetches fresh data and updates cache
17
- * Deduplicates concurrent requests with the same key
18
- *
19
- * @param key Cache key
20
- * @param fetchFn Function to fetch fresh data
21
- * @param ttl Time to live in milliseconds (default: DEFAULT_SWR_TTL)
22
- * @param isCacheable Whether to store result in cache (default: true)
23
- */
24
- fetch<T>(key: string, fetchFn: () => T | Promise<T>, ttl?: number, isCacheable?: boolean): Promise<T>;
25
- /**
26
- * Fetch cache using SWR (stale-while-revalidate)
27
- *
28
- * This will always return the cached value immediately if exists
29
- */
30
- fetchSWR<T>(key: string, fetchFn: () => T | Promise<T>, ttl?: number, isCacheble?: boolean): Promise<T>;
31
- get<T>(key: string): Promise<T | undefined>;
32
- set<T>(key: string, value: T, ttl?: number): Promise<T>;
33
- flush(key: string): Promise<void>;
34
- /**
35
- * Flushes the entire cache.
36
- *
37
- * __WARNING__: If the cache store is shared among many cache clients,
38
- * this will flush entries for other clients.
39
- */
40
- flushAll(): Promise<void>;
41
- }
@@ -1,18 +0,0 @@
1
- import type { KeyvStoreAdapter } from 'keyv';
2
- import type { CFWorkerKV } from 'types/cloudflare';
3
- /**
4
- * CloudFlare Workers KV adapter for Keyv.
5
- * Includes namespacing to prevent conflicts within shared storage.
6
- */
7
- export declare class CFWorkerKVKeyvAdapter implements KeyvStoreAdapter {
8
- private store;
9
- namespace: string;
10
- opts: unknown;
11
- constructor(store: CFWorkerKV);
12
- has(key: string): Promise<boolean>;
13
- get<T>(key: string): Promise<T | undefined>;
14
- set(key: string, value: string, ttl?: number): Promise<void>;
15
- delete(key: string): Promise<boolean>;
16
- clear(): Promise<void>;
17
- on(_event: string, _listener: (...args: unknown[]) => void): CFWorkerKVKeyvAdapter;
18
- }
@@ -1,7 +0,0 @@
1
- export declare const SECOND = 1000;
2
- export declare const MINUTE: number;
3
- export declare const HOUR: number;
4
- export declare const DAY: number;
5
- export declare const YEAR: number;
6
- export declare const MAX_TTL: number;
7
- export declare const SHORT_TTL: number;
@@ -1,21 +0,0 @@
1
- import { type CreateCacheOptions } from './cache';
2
- export interface ContentCacheOptions extends CreateCacheOptions {
3
- defaultTtl?: number;
4
- }
5
- /**
6
- * Simple content cache exposing only get/set operations.
7
- * Designed for caching versioned, immutable content like rendered assets.
8
- */
9
- export declare class ContentCache {
10
- private cache;
11
- private defaultTtl;
12
- constructor(options?: ContentCacheOptions);
13
- /**
14
- * Get content from cache
15
- */
16
- get<T = any>(key: string): Promise<T | undefined>;
17
- /**
18
- * Set content in cache
19
- */
20
- set<T = any>(key: string, value: T, ttl?: number): Promise<void>;
21
- }
@@ -1,64 +0,0 @@
1
- /**
2
- * Represents a standardized, serializable cache entry.
3
- * This object is used to pass data between the core caching logic and the
4
- * storage backend, ensuring that any backend can store and retrieve the
5
- * necessary information consistently.
6
- */
7
- export interface CachedEntry {
8
- /** The HTTP status code of the original response (e.g., 200). */
9
- status: number;
10
- /** The HTTP status text of the original response (e.g., "OK"). */
11
- statusText: string;
12
- /**
13
- * A record of the original response headers.
14
- * Stored as a plain object for easy JSON serialization.
15
- */
16
- headers: Record<string, string>;
17
- /** The response body, stored as a UTF-8 string. */
18
- body: string;
19
- /** The ISO 8601 timestamp string indicating when the entry was created. */
20
- cacheTimeISO: string;
21
- /** The Time-to-Live (TTL) for this entry in seconds. */
22
- ttl: number;
23
- /** The Stale-While-Revalidate (SWR) period for this entry in seconds. */
24
- swr: number;
25
- /**
26
- * The ETag from the original response, if present.
27
- * Used for handling 'If-None-Match' conditional requests.
28
- */
29
- etag?: string;
30
- /**
31
- * The Last-Modified date from the original response, if present.
32
- * Used for handling 'If-Modified-Since' conditional requests.
33
- * Should be stored as a UTC string.
34
- */
35
- lastModifiedUTC?: string;
36
- }
37
- /**
38
- * Defines the contract for a storage backend.
39
- * Any class implementing this interface can be used as a storage layer
40
- * for the HtmlCache, allowing for a pluggable architecture.
41
- */
42
- export interface CacheBackend {
43
- /**
44
- * Reads a cached entry from the storage.
45
- * @param key The unique identifier for the cache entry.
46
- * @returns A promise that resolves to the `CachedEntry` if found, or `null` otherwise.
47
- */
48
- read(key: string): Promise<CachedEntry | null>;
49
- /**
50
- * Writes a cache entry to the storage.
51
- * @param key The unique identifier for the cache entry.
52
- * @param entry The `CachedEntry` object to store.
53
- * @param hardExpireSeconds The total lifetime of the entry in the storage system
54
- * @returns A promise that resolves when the write operation is complete.
55
- */
56
- write(key: string, entry: CachedEntry, hardExpireSeconds: number): Promise<void>;
57
- /**
58
- * Deletes a cache entry from the storage.
59
- * This is optional but recommended for cache invalidation.
60
- * @param key The unique identifier for the cache entry to delete.
61
- * @returns A promise that resolves when the delete operation is complete.
62
- */
63
- delete?(key: string): Promise<void>;
64
- }
@@ -1,9 +0,0 @@
1
- import type { KVNamespace } from '@cloudflare/workers-types';
2
- import { HtmlCache, type CacheRules } from './html-cache';
3
- export type HtmlCacheEnv = {
4
- NAMESPACE?: KVNamespace;
5
- HTML_CACHE_EPOCH?: string;
6
- HTML_CACHE_BACKEND?: 'kv' | 'worker';
7
- HTML_CACHE_RULES?: CacheRules;
8
- };
9
- export declare function getHtmlCache(env?: HtmlCacheEnv, cacheRules?: CacheRules): HtmlCache | null;
@@ -1,38 +0,0 @@
1
- import type { CacheBackend, CachedEntry } from './html-cache-backend';
2
- type KVNamespace = import('@cloudflare/workers-types').KVNamespace;
3
- export type KVCacheBackendOptions = {
4
- /**
5
- * Optional key prefix to help with namespacing and easier debugging.
6
- * Example: "html" -> "html:<hash>"
7
- */
8
- prefix?: string;
9
- /**
10
- * If true (default), the logical key will be hashed with md5 to ensure
11
- * it stays under the 512-byte KV key length limit and is URL-safe.
12
- */
13
- hashKeys?: boolean;
14
- /**
15
- * Safety headroom against the 25 MiB KV value limit.
16
- * Default ~24.5 MiB to leave some slack for encoding overhead.
17
- */
18
- maxValueBytes?: number;
19
- };
20
- /**
21
- * Cloudflare KV implementation of CacheBackend.
22
- * Stores the entire CachedEntry as a compact JSON blob (value),
23
- * and a tiny summary in metadata for potential future use.
24
- */
25
- export declare class KVCacheBackend implements CacheBackend {
26
- private readonly kv;
27
- private readonly prefix;
28
- private readonly hashKeys;
29
- private readonly maxValueBytes;
30
- constructor(kv: KVNamespace, opts?: KVCacheBackendOptions);
31
- read(key: string): Promise<CachedEntry | null>;
32
- write(key: string, entry: CachedEntry, hardExpireSeconds: number): Promise<void>;
33
- delete(key: string): Promise<void>;
34
- private makeKey;
35
- private assertSize;
36
- private approxUtf8Bytes;
37
- }
38
- export {};
@@ -1,8 +0,0 @@
1
- import type { CacheBackend, CachedEntry } from './html-cache-backend';
2
- export declare class WorkerCacheBackend implements CacheBackend {
3
- private readonly cacheName;
4
- constructor(epoch: string);
5
- read(key: string): Promise<CachedEntry | null>;
6
- write(key: string, entry: CachedEntry, _hardExpireSeconds: number): Promise<void>;
7
- delete(key: string): Promise<void>;
8
- }
@@ -1,120 +0,0 @@
1
- import type { CacheBackend, CachedEntry } from './html-cache-backend';
2
- /**
3
- * Configuration for path-specific cache behavior.
4
- *
5
- * Paths support wildcards:
6
- * - `*` matches any characters except `/`
7
- * - `**` matches any characters including `/`
8
- *
9
- * Examples: `/account/*`, `/api/**`, `*.json`
10
- *
11
- * First matching rule wins.
12
- */
13
- export interface PathRule {
14
- path: string;
15
- /** Time-to-live in seconds */
16
- ttl?: number;
17
- /** Stale-while-revalidate in seconds */
18
- swr?: number;
19
- /** If true, skip caching for this path */
20
- skip?: boolean;
21
- /**
22
- * Optional list of allowed Content-Types for caching.
23
- *
24
- * If provided, responses whose Content-Type starts with one of these values are cacheable.
25
- *
26
- * If omitted, defaults to only allowing `text/html`.
27
- */
28
- contentTypes?: string[];
29
- }
30
- export interface CacheRules {
31
- defaults: {
32
- live: {
33
- ttl: number;
34
- swr: number;
35
- };
36
- preview: {
37
- ttl: number;
38
- swr: number;
39
- };
40
- };
41
- pathRules?: PathRule[];
42
- }
43
- export declare const DEFAULT_CACHE_RULES: CacheRules;
44
- interface PathRuleInner extends PathRule {
45
- regex: RegExp;
46
- }
47
- interface CacheRulesInner {
48
- defaults: {
49
- live: {
50
- ttl: number;
51
- swr: number;
52
- };
53
- preview: {
54
- ttl: number;
55
- swr: number;
56
- };
57
- };
58
- pathRules?: PathRuleInner[];
59
- }
60
- type DeploymentMode = 'live' | 'preview';
61
- export interface CacheResult {
62
- found: boolean;
63
- stale?: boolean;
64
- response?: Response;
65
- cacheable?: boolean;
66
- age?: number;
67
- notModified?: boolean;
68
- conditional304?: Response;
69
- }
70
- /**
71
- * Contains all the storage-agnostic HTML caching logic.
72
- * It determines what to cache, for how long, how to build cache keys,
73
- * and how to construct client responses, while delegating the actual
74
- * read/write operations to a pluggable backend.
75
- */
76
- export declare class HtmlCache {
77
- protected epoch: string;
78
- protected backend: CacheBackend;
79
- protected cacheRules: CacheRulesInner;
80
- constructor(epoch: string, backend: CacheBackend, cacheRules?: CacheRules);
81
- /**
82
- * Converts wildcard pattern to regex and tests against path.
83
- *
84
- * - `*` matches any characters except `/`
85
- * - `**` matches any characters including `/`
86
- */
87
- protected convertPathToRegex(pattern: string): RegExp;
88
- get(request: Request): Promise<CacheResult | null>;
89
- getWithConditionals(request: Request): Promise<CacheResult | null>;
90
- put(request: Request, response: Response): Promise<void>;
91
- delete(requestOrKey: Request | string): Promise<void>;
92
- canReadFromCache(request: Request): boolean;
93
- canWriteToCache(request: Request, response: Response): boolean;
94
- createRevalidationRequest(request: Request): Request;
95
- protected buildClientResponse(entry: CachedEntry, isStale: boolean, age: number): Response;
96
- protected buildCacheKey(request: Request): string;
97
- protected checkNotModified(ifModifiedSince: string | null, ifNoneMatch: string | null, lastModified: string | null, etag: string | null): boolean;
98
- protected ifNoneMatchMatches(ifNoneMatch: string | null, etag: string | null): boolean;
99
- protected quoteETag(value: string): string;
100
- protected sanitizeClientHeaders(headers: Headers): void;
101
- getCacheKeyHeaders(headers: Headers): Headers;
102
- protected generateVersionHash(headers: Headers): string;
103
- protected extractSwellData(cookie: string | null): Record<string, unknown>;
104
- protected isRequestCacheable(request: Request): boolean;
105
- protected isResponseCacheable(response: Response, matchedRule?: PathRule): boolean;
106
- protected getDeploymentMode(headers: Headers): DeploymentMode;
107
- protected getTTLForRequest(request: Request): number;
108
- protected getSWRForRequest(request: Request): number;
109
- protected getEntryAge(entry: CachedEntry): number;
110
- protected normalizeHeaders(headers: Headers): Record<string, string>;
111
- protected resolvePathRule(request: Request): {
112
- rule?: PathRule;
113
- mode: 'live' | 'preview';
114
- effectiveTTL: number;
115
- effectiveSWR: number;
116
- skip: boolean;
117
- };
118
- protected normalizeSearchParams(searchParams: URLSearchParams): string;
119
- }
120
- export {};
@@ -1,4 +0,0 @@
1
- export type { CacheResult, CacheRules, PathRule } from './html-cache';
2
- export { HtmlCache, DEFAULT_CACHE_RULES } from './html-cache';
3
- export { getHtmlCache } from './html-cache-factory';
4
- export type { HtmlCacheEnv } from './html-cache-factory';
@@ -1,9 +0,0 @@
1
- export { Cache } from './cache';
2
- export { RequestCache } from './request-cache';
3
- export { ResourceCache } from './resource-cache';
4
- export { ThemeCache } from './theme-cache';
5
- export { ThemeFileCache } from './theme-file-cache';
6
- export { ContentCache } from './content-cache';
7
- export type { ContentCacheOptions } from './content-cache';
8
- export type { ThemeFileCacheInterface, PutFilesResult, FileWarning, } from './theme-file-cache';
9
- export type { KVFlavor } from './kv-variety';
@@ -1,10 +0,0 @@
1
- import type { CFThemeEnv } from '../../types/cloudflare';
2
- export interface ClientKV {
3
- get(keys: string[]): Promise<Map<string, string | null>>;
4
- put(key: string, value: string, metadata?: Record<string, any>): Promise<void>;
5
- }
6
- export type KVFlavor = 'cf' | 'miniflare' | 'memory';
7
- /**
8
- * Factory function to create appropriate KV implementation
9
- */
10
- export declare function createClientKV(env?: CFThemeEnv, flavor?: KVFlavor): ClientKV;
@@ -1,4 +0,0 @@
1
- import { Cache, type CreateCacheOptions } from './cache';
2
- export declare class RequestCache extends Cache {
3
- constructor(options?: CreateCacheOptions);
4
- }
@@ -1,4 +0,0 @@
1
- import { Cache, type CreateCacheOptions } from './cache';
2
- export declare class ResourceCache extends Cache {
3
- constructor(options?: CreateCacheOptions);
4
- }
@@ -1,4 +0,0 @@
1
- import { Cache, type CreateCacheOptions } from './cache';
2
- export declare class ThemeCache extends Cache {
3
- constructor(options?: CreateCacheOptions);
4
- }
@@ -1,87 +0,0 @@
1
- import type { SwellThemeConfig } from '../../types/swell';
2
- import type { CFThemeEnv } from '../../types/cloudflare';
3
- import type { KVFlavor } from './kv-variety';
4
- /**
5
- * Main interface for theme file storage operations
6
- */
7
- export interface ThemeFileCacheInterface {
8
- /**
9
- * Load files for given configs, intelligently batching to avoid 413 errors
10
- * Returns new configs with file_data populated
11
- */
12
- getFiles(configs: SwellThemeConfig[]): Promise<SwellThemeConfig[]>;
13
- /**
14
- * Store files, checking existence first to avoid redundant writes
15
- * Validates file sizes and returns detailed results
16
- */
17
- putFiles(configs: SwellThemeConfig[]): Promise<PutFilesResult>;
18
- }
19
- /**
20
- * Result of a putFiles operation
21
- */
22
- export interface PutFilesResult {
23
- /** Number of files successfully written to storage */
24
- written: number;
25
- /** Number of files skipped due to size violations */
26
- skipped: number;
27
- /** Number of files skipped because they already exist */
28
- skippedExisting: number;
29
- /** Detailed warnings about file size issues */
30
- warnings: FileWarning[];
31
- }
32
- /**
33
- * Warning about a file that triggered size thresholds
34
- */
35
- export interface FileWarning {
36
- /** Hash identifier of the file */
37
- hash: string;
38
- /** Path of the file for logging */
39
- filePath: string;
40
- /** Size of the file in bytes */
41
- size: number;
42
- /** Reason for the warning */
43
- reason: 'warning_1mb' | 'rejected_5mb' | 'exceeded_25mb';
44
- /** Action taken for this file */
45
- action: 'stored' | 'rejected';
46
- }
47
- /**
48
- * Theme file storage implementation
49
- * Manages efficient batch operations for theme files in KV storage
50
- */
51
- export declare class ThemeFileCache implements ThemeFileCacheInterface {
52
- private kv;
53
- private maxBatchSize;
54
- constructor(env?: CFThemeEnv, flavor?: KVFlavor);
55
- /**
56
- * Build a KV storage key from a file hash
57
- */
58
- private buildKey;
59
- /**
60
- * Extract hash from a KV storage key
61
- */
62
- private extractHashFromKey;
63
- /**
64
- * Plan GET batches based on file sizes to avoid 413 errors
65
- * Uses round-robin distribution for even batch sizes
66
- */
67
- private planGetBatches;
68
- /**
69
- * Load a single batch from KV storage
70
- */
71
- private loadBatch;
72
- /**
73
- * Merge batch results with original configs
74
- */
75
- private mergeResults;
76
- getFiles(configs: SwellThemeConfig[]): Promise<SwellThemeConfig[]>;
77
- /**
78
- * Validate file sizes and categorize by threshold
79
- */
80
- private validateFiles;
81
- /**
82
- * Check which files already exist in KV storage
83
- * Uses batch planning to avoid 413 errors when checking existence
84
- */
85
- private checkExistence;
86
- putFiles(configs: SwellThemeConfig[]): Promise<PutFilesResult>;
87
- }
@@ -1,10 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import { type ShopifyResource } from '../shopify-objects';
3
- import type { ShopifyCompatibility } from '../shopify';
4
- import type { ShopifyProduct as ShopifyProductType } from 'types/shopify';
5
- export default class AllProductsDrop extends Drop {
6
- #private;
7
- constructor(instance: ShopifyCompatibility);
8
- liquidMethodMissing(key: unknown): unknown;
9
- getProduct(slug: string): ShopifyResource<ShopifyProductType> | null;
10
- }
@@ -1,10 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import { type ShopifyResource } from '../shopify-objects';
3
- import type { ShopifyCompatibility } from '../shopify';
4
- import type { ShopifyArticle as ShopifyArticleType } from 'types/shopify';
5
- export default class ArticlesDrop extends Drop {
6
- #private;
7
- constructor(instance: ShopifyCompatibility);
8
- liquidMethodMissing(key: unknown): unknown;
9
- getArticle(slug: string): ShopifyResource<ShopifyArticleType>;
10
- }
@@ -1,10 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import { type ShopifyResource } from '../shopify-objects';
3
- import type { ShopifyCompatibility } from '../shopify';
4
- import type { ShopifyBlog as ShopifyBlogType } from 'types/shopify';
5
- export default class BlogsDrop extends Drop {
6
- #private;
7
- constructor(instance: ShopifyCompatibility);
8
- liquidMethodMissing(key: unknown): unknown;
9
- getBlog(slug: string): ShopifyResource<ShopifyBlogType>;
10
- }
@@ -1,19 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import { SwellStorefrontCollection } from '@/resources';
3
- import { type ShopifyResource } from '../shopify-objects';
4
- import type { ShopifyCompatibility } from '../shopify';
5
- import type { ShopifyCollection as ShopifyCollectionType } from 'types/shopify';
6
- declare class CollectionsDrop extends Drop {
7
- #private;
8
- constructor(instance: ShopifyCompatibility);
9
- liquidMethodMissing(key: unknown): unknown;
10
- getCollection(slug: string): ShopifyResource<ShopifyCollectionType>;
11
- getAllCollection(): ShopifyResource<ShopifyCollectionType>;
12
- getAllCollectionsSize(): Promise<number> | number;
13
- }
14
- export default class Collections extends SwellStorefrontCollection<ShopifyCollectionType> {
15
- #private;
16
- constructor(instance: ShopifyCompatibility);
17
- toLiquid(): CollectionsDrop;
18
- }
19
- export {};
@@ -1,15 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import type { ShopifyImageSrc } from 'types/shopify';
3
- export declare class ImageSrcDrop extends Drop implements ShopifyImageSrc {
4
- url: string;
5
- width: number;
6
- height: number;
7
- constructor(url: string, width: number, height: number);
8
- toString(): string;
9
- toJSON(): string;
10
- toLiquid(): {
11
- url: string;
12
- width: number;
13
- height: number;
14
- };
15
- }
@@ -1,29 +0,0 @@
1
- import { Drop } from 'liquidjs';
2
- import type { StorefrontResource } from '@/resources';
3
- import type { SwellData, SwellRecord } from 'types/swell';
4
- import type { ShopifyImage, ShopifyImagePresentation, ShopifyImageSrc, ShopifyVariant } from 'types/shopify';
5
- interface ShopifyImageOptions {
6
- media_type?: 'image';
7
- position?: number;
8
- product_id?: number;
9
- }
10
- export declare class ImageDrop extends Drop implements ShopifyImage {
11
- id: number;
12
- alt: string;
13
- src: ShopifyImageSrc;
14
- media_type?: 'image' | undefined;
15
- preview_image?: ShopifyImage | undefined;
16
- presentation?: ShopifyImagePresentation | undefined;
17
- aspect_ratio: number;
18
- 'attached_to_variant?': boolean | undefined;
19
- width: number;
20
- height: number;
21
- position?: number | undefined;
22
- product_id?: number | undefined;
23
- variants?: ShopifyVariant[] | undefined;
24
- constructor(image: SwellData, options?: ShopifyImageOptions, product?: StorefrontResource | SwellRecord, variant?: StorefrontResource | SwellRecord);
25
- toString(): string;
26
- [Symbol.toPrimitive](): string;
27
- toJSON(): string;
28
- }
29
- export {};