@wix/himalaya-cli 0.1543.0 → 0.1545.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/site-list/src/index.d.ts

@@ -2,6 +2,17 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
@@ -14,6 +25,14 @@ declare global {
  *  it can be passed straight through: `someMethod(req, site.forSite(msid))`. */
 export interface WixCallOptions {
     site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
 }
 export declare function wixCall<T>(method: string, path: string, body?: unknown, opts?: WixCallOptions): Promise<T>;
 export interface WixCursorPaging {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/site-media/src/index.d.ts

@@ -2,6 +2,17 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/social-feed/src/index.d.ts

@@ -2,9 +2,31 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
+export interface WixCallOptions {
+    site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
+}
 export interface WixFeedItem {
     feedItemId?: string;
     author?: {
@@ -73,7 +95,7 @@ export interface WixListFeedItemsResponse {
  * @scope member — verified live with a signed-in member session; visitor/anonymous
  * readability of a public group's feed is unconfirmed.
  */
-export declare function listFeedItems(groupId: string, limit?: number): Promise<WixListFeedItemsResponse>;
+export declare function listFeedItems(groupId: string, limit?: number, options?: WixCallOptions): Promise<WixListFeedItemsResponse>;
 /**
  * Create a feed post in a group as the signed-in member — POST
  * https://social.wix.com/api/v1/feed/items. `content` is the post text (modern

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-collections/src/display.d.ts

@@ -1,3 +1,4 @@
+import { type WixCallOptions } from "./index.js";
 import { type WixImageSize } from "@wix/himalaya/wix-media";
 export interface StoreCategoryImage {
     id?: string;
@@ -32,10 +33,10 @@ export interface StoreGetCategoryResponse {
 }
 /** V3 visitor read: list store categories (the V3 replacement for `queryCollections`).
  *  POST /categories/v1/categories/query — `treeReference.appNamespace` is REQUIRED. */
-export declare function queryStoreCategories(limit?: number, cursor?: string): Promise<StoreCategoriesResponse>;
+export declare function queryStoreCategories(limit?: number, cursor?: string, options?: WixCallOptions): Promise<StoreCategoriesResponse>;
 /** V3 visitor read: one store category by id (the V3 replacement for `getCollection`).
  *  GET /categories/v1/categories/{id} — `treeReference.appNamespace` passed as a query param. */
-export declare function getStoreCategory(categoryId: string): Promise<StoreGetCategoryResponse>;
+export declare function getStoreCategory(categoryId: string, options?: WixCallOptions): Promise<StoreGetCategoryResponse>;
 /** "3 products" / "1 product" / "" — the count subtitle collection rows already render
  *  (from the V3 `itemCounter`, mirroring the v1 `numberOfProducts` helper). */
 export declare function categoryCount(c: StoreCategory): string;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-collections/src/index.d.ts

@@ -2,10 +2,34 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
-export declare function wixCall<T>(method: string, path: string, body?: unknown): Promise<T>;
+export interface WixCallOptions {
+    site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
+}
+/** The per-call header map for `opts`, or undefined when there is nothing to add — so
+ *  the no-options path calls the bridge with exactly the 3 arguments it always did. */
+export declare function wixCall<T>(method: string, path: string, body?: unknown, readOptions?: WixCallOptions): Promise<T>;
 export interface WixCollectionsPaging {
     limit?: number;
     offset?: number;
@@ -61,10 +85,10 @@ export interface WixGetCollectionResponse {
 /** Fetch a single collection by id — the detail screen's data source.
  *  ⚠️ Catalog **V1 only**: `/stores/v1/collections/*` returns HTTP 428 on modern
  *  ("stores-v3") sites. For the V3 visitor read use `getStoreCategory` (./display). */
-export declare function getCollection(collectionId: string): Promise<WixGetCollectionResponse>;
+export declare function getCollection(collectionId: string, options?: WixCallOptions): Promise<WixGetCollectionResponse>;
 /** ⚠️ Catalog **V1 only**: `/stores/v1/collections/query` returns HTTP 428 on modern
  *  ("stores-v3") sites. For the V3 visitor read use `queryStoreCategories` (./display). */
-export declare function queryCollections(req?: WixQueryCollectionsRequest): Promise<WixQueryCollectionsResponse>;
+export declare function queryCollections(req?: WixQueryCollectionsRequest, options?: WixCallOptions): Promise<WixQueryCollectionsResponse>;
 /** Writable collection fields for create/update. */
 export interface WixCollectionWrite {
     /** Required on create. */

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-v1/src/catalog.d.ts

@@ -5,9 +5,9 @@ export type CatalogVersion = "v1" | "v3";
  *  belongs to the site that produced it, and the SDK has no way to notice the swap
  *  on its own. Without it, the next worker starts on the previous site's catalog
  *  and only the backstop 428 rescues it. */
-export declare function forgetCatalogVersion(): void;
-/** This worker's resolved version, or the app-scoped answer a sibling worker stored. */
-export declare function observedCatalogVersion(): CatalogVersion | undefined;
+export declare function forgetCatalogVersion(site?: string): void;
+/** The requested site's resolved version, or its app-scoped answer from a sibling worker. */
+export declare function observedCatalogVersion(site?: string): CatalogVersion | undefined;
 /** Either catalog's "you are on the wrong version" rejection (both directions). */
 export declare function isCatalogMismatch(e: unknown): boolean;
 /** The catalog the REJECTION names, which is the site's real one:
@@ -24,11 +24,11 @@ export declare function catalogVersionFromMismatch(e: unknown): CatalogVersion |
  *  `witness` is the raw stored value from before the rejected call went out. A 428
  *  that crossed a site switch describes the PREVIOUS site just as a late provision
  *  reply does, so the same compare-and-set applies. */
-export declare function noteCatalogMismatch(attempted: CatalogVersion, error?: unknown, witness?: string): void;
+export declare function noteCatalogMismatch(attempted: CatalogVersion, error?: unknown, witness?: string, site?: string): void;
 /** Run `attempt` against the site's catalog — RESOLVED, not guessed — keeping the
  *  mismatch 428 as a backstop for the cases resolution cannot cover (the provision
  *  endpoint unavailable, or the site switched under a persisted answer). */
-export declare function readWithCatalogFallback<T>(attempt: (version: CatalogVersion) => Promise<T>): Promise<T>;
+export declare function readWithCatalogFallback<T>(attempt: (version: CatalogVersion) => Promise<T>, cacheOnly?: boolean, site?: string): Promise<T>;
 /**
  * Resolve the site's catalog version, asking Wix when it isn't already known.
  * Every caller routes through this now — writes, which must never guess, and
@@ -37,11 +37,11 @@ export declare function readWithCatalogFallback<T>(attempt: (version: CatalogVer
  * The provision endpoint needs a catalog-read scope. If it is unavailable — an
  * older token, a site without Stores, an offline worker — we do NOT fail the
  * caller: we fall back to `"v3"`, the default every new site gets, and leave the
- * memo unset so a later mismatch can still correct it. That fallback is the one
+ * state.memo unset so a later mismatch can still correct it. That fallback is the one
  * remaining guess, and it is exactly why reads keep the 428 backstop. A write
  * routed that way still surfaces its own 428 rather than being silently retried.
  */
-export declare function resolveCatalogVersion(): Promise<CatalogVersion>;
+export declare function resolveCatalogVersion(site?: string): Promise<CatalogVersion>;
 /** Test seam — clears everything this module remembers, INCLUDING the persisted
  *  hint. Leaving the hint behind would leak one test's site into the next (and,
  *  on a runtime that exposes a global web-storage object, across whole suites).

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-v1/src/display.d.ts

@@ -1,3 +1,4 @@
+import { type WixCallOptions } from "./index.js";
 /**
  * One media slot as the wire actually sends it: `{ url }`, a nested `{ image: {...} }`,
  * or the reference STRING itself. The string form is real — `mediaSlot()` in the
@@ -127,7 +128,7 @@ export interface StoreGetProductResponse {
 }
 /** List products from whichever catalog this site runs. `fields` is additive — it
  *  WIDENS the default v3 display fieldset rather than replacing it. */
-export declare function queryStoreProducts(limit?: number, cursor?: string, fields?: readonly string[]): Promise<StoreProductsResponse>;
+export declare function queryStoreProducts(limit?: number, cursor?: string, fields?: readonly string[], options?: WixCallOptions): Promise<StoreProductsResponse>;
 /** User-facing product discovery. V3 name search/sorting belong to Search
  * Products; Query Products deliberately does not support the name field.
  * V1 uses its documented JSON-string filter/sort dialect. */
@@ -161,10 +162,10 @@ export interface StoreProductSearch {
  * contract on both catalogs: pass back `pagingMetadata.cursors.next` as `cursor`.
  * A non-catalog failure (401/403, offline) rejects; it is never retried on V1.
  */
-export declare function searchStoreProducts(options?: StoreProductSearch): Promise<StoreProductsResponse>;
+export declare function searchStoreProducts(options?: StoreProductSearch, readOptions?: WixCallOptions): Promise<StoreProductsResponse>;
 /** Read one product from whichever catalog this site runs. `fields` is additive —
  *  it WIDENS the default v3 display fieldset rather than replacing it. */
-export declare function getStoreProduct(productId: string, fields?: readonly string[]): Promise<StoreGetProductResponse>;
+export declare function getStoreProduct(productId: string, fields?: readonly string[], readOptions?: WixCallOptions): Promise<StoreGetProductResponse>;
 export { wixMediaUrl, isUnsizedWixMedia, WIX_LIST_IMAGE, WIX_DETAIL_IMAGE, type WixImageSize, } from "@wix/himalaya/wix-media";
 import { type WixImageSize } from "@wix/himalaya/wix-media";
 /**

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-v1/src/extensions.d.ts

@@ -1,3 +1,4 @@
+import { type WixCallOptions } from "./index.js";
 import type { WixProductWrite, WixCreateProductResponse, WixUpdateProductResponse, WixDeleteProductResponse } from "./index.js";
 import type { WixQueryProductsRequest, WixQueryProductsResponse, WixGetProductResponse } from "./index.js";
 import { type V3RichContent } from "./products-v3.js";
@@ -15,7 +16,7 @@ export declare function queryProducts(req?: WixQueryProductsRequest): Promise<Wi
  *  none). The key is ABSENT on a V1 catalog, which has no Ricos description, and without the option. */
 export declare function getProduct(productId: string, opts?: {
     richDescription?: boolean;
-}): Promise<WixGetProductResponse>;
+}, readOptions?: WixCallOptions): Promise<WixGetProductResponse>;
 /** Create a product. V1: `POST /stores/v1/products`. V3: `POST /stores/v3/products`
  *  with the write model mapped onto V3's variants shape (see products-v3.ts). */
 export declare function createProduct(product: WixProductWrite): Promise<WixCreateProductResponse>;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/stores-v1/src/index.d.ts

@@ -2,6 +2,17 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
@@ -14,6 +25,14 @@ declare global {
  *  it can be passed straight through: `someMethod(req, site.forSite(msid))`. */
 export interface WixCallOptions {
     site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
 }
 export declare function wixCall<T>(method: string, path: string, body?: unknown, opts?: WixCallOptions): Promise<T>;
 export interface WixProductsPaging {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/table-reservations/src/index.d.ts

@@ -2,9 +2,31 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
+export interface WixCallOptions {
+    site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
+}
 export interface WixReservation {
     id: string;
     /** HELD | RESERVED | REQUESTED | DECLINED | CANCELED | NO_SHOW | FINISHED | SEATED */
@@ -52,12 +74,12 @@ export interface WixQueryReservationsResponse {
     };
 }
 /** POST /table-reservations/reservations/v1/reservations/query — list reservations. */
-export declare function queryReservations(query: WixReservationQuery): Promise<WixQueryReservationsResponse>;
+export declare function queryReservations(query: WixReservationQuery, readOptions?: WixCallOptions): Promise<WixQueryReservationsResponse>;
 export interface WixGetReservationResponse {
     reservation?: WixReservation;
 }
 /** GET /table-reservations/reservations/v1/reservations/{id} — single reservation (proto GetReservation; perm RESERVATION_READ). */
-export declare function getReservation(reservationId: string): Promise<WixGetReservationResponse>;
+export declare function getReservation(reservationId: string, readOptions?: WixCallOptions): Promise<WixGetReservationResponse>;
 /**
  * PATCH /table-reservations/reservations/v1/reservations/{id} — change status via
  * the proto UpdateReservation (fieldmask field = `mask`). Used for approve
@@ -89,7 +111,7 @@ export interface WixListReservationLocationsResponse {
 }
 /** GET /table-reservations/reservation-locations/v1/reservation-locations — up to
  *  100 locations (proto ListReservationLocations; perm RESERVATION_LOCATION_READ). */
-export declare function listReservationLocations(): Promise<WixListReservationLocationsResponse>;
+export declare function listReservationLocations(readOptions?: WixCallOptions): Promise<WixListReservationLocationsResponse>;
 export interface WixHeldReservationDetails {
     reservationLocationId: string;
     /** ISO-8601 start of the requested slot, e.g. "2026-08-01T19:00:00Z". */

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/users/src/index.d.ts

@@ -2,9 +2,31 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
+export interface WixCallOptions {
+    site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
+}
 export interface WixUserProfile {
     firstName?: string;
     lastName?: string;
@@ -37,7 +59,7 @@ export interface WixMyData {
  *  it silently falls back to guest (#676). For a visitor-facing member directory,
  *  query the Members Area instead: `@himalaya/wix-members` `queryMembers`
  *  (`POST /members/v1/members/query`), which surfaces the real roster. */
-export declare function getMyData(): Promise<WixMyData>;
+export declare function getMyData(options?: WixCallOptions): Promise<WixMyData>;
 /** Display name from my-data: full name (firstName + lastName) if present, else
  *  the userName handle, else the email. */
 export declare function displayName(d: WixMyData): string;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/video/src/index.d.ts

@@ -3,6 +3,17 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
@@ -11,6 +22,14 @@ export declare const WIX_VIDEO_GRAPHQL_URL = "https://manage.wix.com/_api/vod/pu
 /** Per-call options. `site` reads a business other than the app's active one. */
 export interface WixCallOptions {
     site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
 }
 /** One price option of a channel (`SUBSCRIPTION` | `PRICING_PLAN`) or a video (`SALE` | `RENT`). */
 export interface WixVideoPricing {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/wix-data/src/index.d.ts

@@ -2,10 +2,34 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
-declare function wixCall<T>(method: string, path: string, body?: unknown): Promise<T>;
+export interface WixCallOptions {
+    site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
+}
+/** The per-call header map for `opts`, or undefined when there is nothing to add — so
+ *  the no-options path calls the bridge with exactly the 3 arguments it always did. */
+declare function wixCall<T>(method: string, path: string, body?: unknown, readOptions?: WixCallOptions): Promise<T>;
 export interface WixDataItem {
     id?: string;
     dataCollectionId?: string;
@@ -33,7 +57,7 @@ export interface WixIncludeReference {
 }
 /** The rarely-needed read parameters of `queryDataItems`. Every field is omitted from the wire
  *  body unless set, so a caller that passes none sends the exact body it always sent. */
-export interface WixQueryOptions {
+export interface WixQueryOptions extends WixCallOptions {
     /** Read from the primary database instance instead of the nearest mirror. Slower, but a read
      *  right after your own write sees it — the default is eventually consistent. */
     consistentRead?: boolean;
@@ -183,7 +207,7 @@ export declare function queryDataItems(dataCollectionId: string, limit?: number,
  *  gateway drops a GET body — and the string is built with `encodeURIComponent`
  *  rather than `URLSearchParams`, which the bare Tier-5 worker runtimes (JSCore /
  *  Hermes / QuickJS-ng) do not provide. */
-export declare function getDataItem(dataCollectionId: string, dataItemId: string): Promise<{
+export declare function getDataItem(dataCollectionId: string, dataItemId: string, options?: WixCallOptions): Promise<{
     dataItem?: WixDataItem;
 }>;
 /** Insert an item — POST /wix-data/v2/items.

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/workflows-v1/src/index.d.ts

@@ -2,6 +2,17 @@ declare global {
     var himalaya: {
         wixApi?: {
             call: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<unknown>;
+            read?: (method: string, path: string, body: unknown, headers: Record<string, string> | undefined, options: {
+                cache: string;
+            }) => Promise<{
+                data: unknown;
+                cache: {
+                    source: "cache" | "network";
+                    fetchedAt: number;
+                    expiresAt?: number;
+                    cacheable: boolean;
+                };
+            }>;
         };
     };
 }
@@ -14,6 +25,14 @@ declare global {
  *  it can be passed straight through: `someMethod(req, site.forSite(msid))`. */
 export interface WixCallOptions {
     site?: string;
+    /** Explicit cache reads never touch the network; reload waits for a server response. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
 }
 export declare function wixCall<T>(method: string, path: string, body?: unknown, opts?: WixCallOptions): Promise<T>;
 /** `path` with `req` appended as the query string Wix's RPC gateway reads a GET or

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk-auto/_shared/runtime.generated.d.ts

@@ -2,6 +2,14 @@
  *  one (`site.forSite(msid)` from `@himalaya/wix-platform` returns this shape). */
 export interface WixCallOptions {
     site?: string;
+    /** Cache-only reads and forced-network recovery reads. */
+    cache?: "default" | "only-if-cached" | "reload";
+    onCacheResult?: (metadata: {
+        source: "cache" | "network";
+        fetchedAt: number;
+        expiresAt?: number;
+        cacheable: boolean;
+    }) => void;
 }
 /** The endpoint answered: `value` is what the call returns without `{ offline: "queue" }`. */
 export interface WixSent<T> {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/checkout.mjs

@@ -84,22 +84,30 @@ async function open(url, mode) {
 }
 
 // ../../stdlib/wix-sdk/pricing-plans/src/index.ts
-function wixCall(method, path, body) {
+function wixCall(method, path, body, readOptions) {
   if (!globalThis.himalaya?.wixApi) {
     return Promise.reject(
       new Error("@himalaya/wix-pricing-plans: host did not install the wixApi bridge")
     );
   }
-  return globalThis.himalaya.wixApi.call(method, path, body);
+  const api = globalThis.himalaya.wixApi;
+  if (readOptions?.cache || readOptions?.onCacheResult) {
+    if (!api.read) return Promise.reject(new Error("READ_LIFECYCLE_UNSUPPORTED: update the Himalaya runtime"));
+    return api.read(method, path, body, readOptions.site ? { "wix-site-id": readOptions.site } : void 0, { cache: readOptions.cache ?? "default" }).then((result) => {
+      readOptions.onCacheResult?.(result.cache);
+      return result.data;
+    });
+  }
+  return readOptions?.site ? api.call(method, path, body, { "wix-site-id": readOptions.site }) : api.call(method, path, body);
 }
-function listMyPlanOrders(opts = {}) {
+function listMyPlanOrders(opts = {}, readOptions) {
   const qs = [
     ...(opts.statuses ?? []).map((s2) => `orderStatuses=${encodeURIComponent(s2)}`),
     ...opts.limit === void 0 ? [] : [`limit=${opts.limit}`],
     ...opts.offset === void 0 ? [] : [`offset=${opts.offset}`]
   ];
   const path = "/pricing-plans/v2/member/orders" + (qs.length ? `?${qs.join("&")}` : "");
-  return wixCall("GET", path);
+  return wixCall("GET", path, void 0, readOptions);
 }
 
 // ../../stdlib/flows/checkout/src/index.ts

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/screens.mjs

@@ -120,6 +120,9 @@ function defineService(name, def) {
       "@himalaya/state: defineService called outside a Himalaya runtime. This bundle must run inside a JSWorker (Tier 5)."
     );
   }
+  if (def.readLifecycle && (himalaya.readLifecycleVersion ?? 0) < 1) {
+    throw new Error("READ_LIFECYCLE_UNSUPPORTED: update the Himalaya runtime before installing this screen");
+  }
   return himalaya.defineService(name, def);
 }
 
@@ -468,25 +471,33 @@ async function open(url, mode) {
 }
 
 // ../../stdlib/wix-sdk/pricing-plans/src/index.ts
-function wixCall(method, path, body) {
+function wixCall(method, path, body, readOptions) {
   if (!globalThis.himalaya?.wixApi) {
     return Promise.reject(
       new Error("@himalaya/wix-pricing-plans: host did not install the wixApi bridge")
     );
   }
-  return globalThis.himalaya.wixApi.call(method, path, body);
+  const api = globalThis.himalaya.wixApi;
+  if (readOptions?.cache || readOptions?.onCacheResult) {
+    if (!api.read) return Promise.reject(new Error("READ_LIFECYCLE_UNSUPPORTED: update the Himalaya runtime"));
+    return api.read(method, path, body, readOptions.site ? { "wix-site-id": readOptions.site } : void 0, { cache: readOptions.cache ?? "default" }).then((result) => {
+      readOptions.onCacheResult?.(result.cache);
+      return result.data;
+    });
+  }
+  return readOptions?.site ? api.call(method, path, body, { "wix-site-id": readOptions.site }) : api.call(method, path, body);
 }
-function listPublicPlans() {
-  return wixCall("GET", "/pricing-plans/v2/plans/public");
+function listPublicPlans(readOptions) {
+  return wixCall("GET", "/pricing-plans/v2/plans/public", void 0, readOptions);
 }
-function listMyPlanOrders(opts = {}) {
+function listMyPlanOrders(opts = {}, readOptions) {
   const qs = [
     ...(opts.statuses ?? []).map((s2) => `orderStatuses=${encodeURIComponent(s2)}`),
     ...opts.limit === void 0 ? [] : [`limit=${opts.limit}`],
     ...opts.offset === void 0 ? [] : [`offset=${opts.offset}`]
   ];
   const path = "/pricing-plans/v2/member/orders" + (qs.length ? `?${qs.join("&")}` : "");
-  return wixCall("GET", path);
+  return wixCall("GET", path, void 0, readOptions);
 }
 function createOnlineOrder(planId, couponCode) {
   return wixCall("POST", "/pricing-plans/v2/checkout/orders/online", couponCode ? { planId, couponCode } : { planId });
@@ -3864,12 +3875,26 @@ function wixCall2(method, path, body, opts) {
       )
     );
   }
-  return globalThis.himalaya.wixApi.call(
-    method,
-    path,
-    body,
-    wixCallHeaders(opts)
+  const api = globalThis.himalaya.wixApi;
+  const verb = method.toUpperCase();
+  const readShaped = verb === "GET" || verb === "HEAD" || verb === "POST" && /\/(query|query-cursor|search|list|count)(\?|$)/.test(
+    path.split("#")[0]
   );
+  if (readShaped && (opts?.cache || opts?.onCacheResult)) {
+    if (!api.read)
+      return Promise.reject(
+        new Error("READ_LIFECYCLE_UNSUPPORTED: update the Himalaya runtime")
+      );
+    return api.read(method, path, body, wixCallHeaders(opts), {
+      cache: opts.cache ?? "default"
+    }).then((result) => {
+      opts.onCacheResult?.(result.cache);
+      return result.data;
+    });
+  }
+  if (opts?.cache === "only-if-cached")
+    return Promise.reject(new Error("OFFLINE_CACHE_MISS"));
+  return api.call(method, path, body, wixCallHeaders(opts));
 }
 function createRedirectSession(req = {}, opts) {
   return wixCall2(