@usethrottle/catalog 1.1.0 → 1.3.0

package/dist/react.d.cts

@@ -1,15 +1,32 @@
-import { CatalogClient } from './index.cjs';
-export { S as SDK_VERSION } from './client-BAoq6jmM.cjs';
+export { ReviewEligibility } from './index.cjs';
 import { ReactNode } from 'react';
+import { CatalogClient } from './index.cjs';
+import { C as CustomerCartSource } from './types-D0PywKnN.cjs';
+import { CategoryTreeDepth, ProductsQuery, ThrottleCart, CartWarning } from './index.cjs';
+export { O as OpenCartRef } from './types-D0PywKnN.cjs';
+import { Q as QueryOptions, a as QueryResult } from './use-query-UWf6Pi5g.cjs';
+export { c as catalogQueryKey } from './use-query-UWf6Pi5g.cjs';
 import { CatalogError } from './admin.cjs';
-import { CategoryTreeDepth, ProductsQuery, ThrottleCart } from './index.cjs';
 import { ReviewSubmitAnswer, ReviewSubmitInput } from './index.cjs';
+export { S as SDK_VERSION } from './version-ev3p03v2.cjs';
+import '@usethrottle/money';
 
-/** Where `useCart` keeps the cart session id (P6-R15). The default is memory only. */
+/**
+ * Where `useCart` keeps the cart session id (P6-R15). The default is memory
+ * only. The optional per-currency slots let a guest's `switchCurrency` find
+ * the cart it already has in that currency (MC2-R41); without them a guest
+ * switch makes a new cart. They hold a guest's carts only: `useCart` never
+ * writes them while signed in, and forgets them on a sign-in, a sign-out or
+ * a customer change (`removeFor`, else `setFor(currency, '')`).
+ */
 type CartStorage = {
     get(): string | null | Promise<string | null>;
     set(id: string): void | Promise<void>;
     remove(): void | Promise<void>;
+    /** The session id last saved for `currency` (upper case), or `null`. */
+    getFor?(currency: string): string | null | Promise<string | null>;
+    setFor?(currency: string, id: string): void | Promise<void>;
+    removeFor?(currency: string): void | Promise<void>;
 };
 /** In memory only: the cart is forgotten on reload. The default `cartStorage`. */
 declare function createMemoryCartStorage(): CartStorage;
@@ -22,6 +39,7 @@ type CartUrls = {
     cancelUrl?: string;
     storefrontUrl?: string;
 };
+
 type CatalogProviderProps = {
     client: CatalogClient;
     /**
@@ -31,6 +49,8 @@ type CatalogProviderProps = {
      */
     customerKey?: string | null;
     cartStorage?: CartStorage;
+    /** Resumes the signed-in customer's cart on any device (P8-R14). */
+    customerCart?: CustomerCartSource;
     cartUrls?: CartUrls;
     throttleBaseUrl?: string;
     throttleCheckoutUrl?: string;
@@ -42,37 +62,11 @@ type CatalogProviderProps = {
  * limit is the visitor's, not the customer's.
  */
 declare function CatalogProvider(props: CatalogProviderProps): ReactNode;
+/** The provider's `customerKey` (`null` when signed out). */
+declare function useCustomerKey(): string | null;
 /** The provider's client. */
 declare function useCatalog(): CatalogClient;
 
-type QueryResult<T> = {
-    data: T | undefined;
-    error: CatalogError | undefined;
-    /** No data and no error yet, and the hook is enabled. */
-    isLoading: boolean;
-    /** A request for this key is in flight (first load or revalidation). */
-    isValidating: boolean;
-    /** Fetches again now (unless a rate-limit pause holds every read). Never rejects. */
-    refetch(): Promise<void>;
-};
-type QueryOptions<T> = {
-    /** `false` makes no request; `data` stays `undefined`. */
-    enabled?: boolean;
-    /**
-     * Shown at once (SSR hand-off). Treated as fetched at mount when the
-     * provider has no `customerKey`; under a signed-in customer it is
-     * revalidated at once, since a server render is usually anonymous (P6-R51).
-     */
-    initialData?: T;
-    /** Cached data younger than this is not fetched again; default `STALE_MS`. */
-    staleTimeMs?: number;
-};
-/**
- * The cache key of a read: the route name and its canonical parameters.
- * Hooks prefix it with the provider's `customerKey` (P6-R14).
- */
-declare function catalogQueryKey(route: string, params: unknown): string;
-
 type Answer<F extends (...args: never[]) => unknown> = Awaited<ReturnType<F>>;
 type Products = CatalogClient['products'];
 declare function useProducts(query?: ProductsQuery, options?: QueryOptions<Answer<Products['list']>>): QueryResult<Answer<Products['list']>>;
@@ -116,6 +110,12 @@ type CartState = {
     error: CatalogError | undefined;
     /** A change is queued or running. */
     pending: boolean;
+    /**
+     * What the last `switchCurrency` could not carry over: `lines_removed`
+     * (lines with no price in the new currency, left behind) and
+     * `discount_dropped` (a code the new currency refuses). Empty otherwise.
+     */
+    warnings: CartWarning[];
 };
 type CartOptions = {
     currency?: string;
@@ -138,14 +138,20 @@ type UseCartResult = CartState & {
         checkoutUrl: string;
     }>;
     /**
-     * A new cart with the current lines in `currency` (BC4); the old one is
-     * left to Throttle. It lands whole or not at all: if the new cart cannot be
-     * made, read back or saved, it rejects and the old cart, its stored id and
-     * the old currency stay (the unused new cart is left to Throttle).
+     * Moves the cart into `currency`, keeping one cart per currency (MC2-R41):
+     * the shopper's open cart in `currency` (the signed-in customer's from
+     * `customerCart`, a guest's from `cartStorage.getFor`), else a new empty
+     * one, absorbs the current cart, which Throttle then closes as merged. Lines
+     * with no price in `currency` stay behind and a discount it refuses is
+     * dropped; both show in `warnings`. If anything fails before the absorb
+     * lands, it rejects and the old cart, its stored id and the old currency
+     * stay (an unused new cart is left to Throttle).
      */
     switchCurrency(currency: string): Promise<void>;
     /** Forgets the cart (no request). */
     clear(): Promise<void>;
+    /** `formatMoney(minor, currency)` in the cart's currency (before a cart, the hook's or the client's). */
+    format(minor: number): string;
 };
 /**
  * The provider's cart (P6-R15). The session id is kept in the provider's
@@ -178,5 +184,5 @@ type SubmitReviewResult = SubmitReviewState & {
  */
 declare function useSubmitReview(handle: string): SubmitReviewResult;
 
-export { CatalogProvider, catalogQueryKey, createMemoryCartStorage, useCart, useCatalog, useCategories, useCollection, useConfig, useFilterValues, useProduct, useProducts, useRelated, useReviews, useSubmitReview, useSuggest };
-export type { CartOptions, CartState, CartStorage, CartUrls, CatalogProviderProps, QueryOptions, QueryResult, SubmitReviewResult, SubmitReviewState, UseCartResult };
+export { CatalogProvider, CustomerCartSource, QueryOptions, QueryResult, createMemoryCartStorage, useCart, useCatalog, useCategories, useCollection, useConfig, useCustomerKey, useFilterValues, useProduct, useProducts, useRelated, useReviews, useSubmitReview, useSuggest };
+export type { CartOptions, CartState, CartStorage, CartUrls, CatalogProviderProps, SubmitReviewResult, SubmitReviewState, UseCartResult };

package/dist/react.d.ts

@@ -1,15 +1,32 @@
-import { CatalogClient } from './index.js';
-export { S as SDK_VERSION } from './client-c2F-eCaL.js';
+export { ReviewEligibility } from './index.js';
 import { ReactNode } from 'react';
+import { CatalogClient } from './index.js';
+import { C as CustomerCartSource } from './types-BfveENg1.js';
+import { CategoryTreeDepth, ProductsQuery, ThrottleCart, CartWarning } from './index.js';
+export { O as OpenCartRef } from './types-BfveENg1.js';
+import { Q as QueryOptions, a as QueryResult } from './use-query-CR7r5tam.js';
+export { c as catalogQueryKey } from './use-query-CR7r5tam.js';
 import { CatalogError } from './admin.js';
-import { CategoryTreeDepth, ProductsQuery, ThrottleCart } from './index.js';
 import { ReviewSubmitAnswer, ReviewSubmitInput } from './index.js';
+export { S as SDK_VERSION } from './version-ev3p03v2.js';
+import '@usethrottle/money';
 
-/** Where `useCart` keeps the cart session id (P6-R15). The default is memory only. */
+/**
+ * Where `useCart` keeps the cart session id (P6-R15). The default is memory
+ * only. The optional per-currency slots let a guest's `switchCurrency` find
+ * the cart it already has in that currency (MC2-R41); without them a guest
+ * switch makes a new cart. They hold a guest's carts only: `useCart` never
+ * writes them while signed in, and forgets them on a sign-in, a sign-out or
+ * a customer change (`removeFor`, else `setFor(currency, '')`).
+ */
 type CartStorage = {
     get(): string | null | Promise<string | null>;
     set(id: string): void | Promise<void>;
     remove(): void | Promise<void>;
+    /** The session id last saved for `currency` (upper case), or `null`. */
+    getFor?(currency: string): string | null | Promise<string | null>;
+    setFor?(currency: string, id: string): void | Promise<void>;
+    removeFor?(currency: string): void | Promise<void>;
 };
 /** In memory only: the cart is forgotten on reload. The default `cartStorage`. */
 declare function createMemoryCartStorage(): CartStorage;
@@ -22,6 +39,7 @@ type CartUrls = {
     cancelUrl?: string;
     storefrontUrl?: string;
 };
+
 type CatalogProviderProps = {
     client: CatalogClient;
     /**
@@ -31,6 +49,8 @@ type CatalogProviderProps = {
      */
     customerKey?: string | null;
     cartStorage?: CartStorage;
+    /** Resumes the signed-in customer's cart on any device (P8-R14). */
+    customerCart?: CustomerCartSource;
     cartUrls?: CartUrls;
     throttleBaseUrl?: string;
     throttleCheckoutUrl?: string;
@@ -42,37 +62,11 @@ type CatalogProviderProps = {
  * limit is the visitor's, not the customer's.
  */
 declare function CatalogProvider(props: CatalogProviderProps): ReactNode;
+/** The provider's `customerKey` (`null` when signed out). */
+declare function useCustomerKey(): string | null;
 /** The provider's client. */
 declare function useCatalog(): CatalogClient;
 
-type QueryResult<T> = {
-    data: T | undefined;
-    error: CatalogError | undefined;
-    /** No data and no error yet, and the hook is enabled. */
-    isLoading: boolean;
-    /** A request for this key is in flight (first load or revalidation). */
-    isValidating: boolean;
-    /** Fetches again now (unless a rate-limit pause holds every read). Never rejects. */
-    refetch(): Promise<void>;
-};
-type QueryOptions<T> = {
-    /** `false` makes no request; `data` stays `undefined`. */
-    enabled?: boolean;
-    /**
-     * Shown at once (SSR hand-off). Treated as fetched at mount when the
-     * provider has no `customerKey`; under a signed-in customer it is
-     * revalidated at once, since a server render is usually anonymous (P6-R51).
-     */
-    initialData?: T;
-    /** Cached data younger than this is not fetched again; default `STALE_MS`. */
-    staleTimeMs?: number;
-};
-/**
- * The cache key of a read: the route name and its canonical parameters.
- * Hooks prefix it with the provider's `customerKey` (P6-R14).
- */
-declare function catalogQueryKey(route: string, params: unknown): string;
-
 type Answer<F extends (...args: never[]) => unknown> = Awaited<ReturnType<F>>;
 type Products = CatalogClient['products'];
 declare function useProducts(query?: ProductsQuery, options?: QueryOptions<Answer<Products['list']>>): QueryResult<Answer<Products['list']>>;
@@ -116,6 +110,12 @@ type CartState = {
     error: CatalogError | undefined;
     /** A change is queued or running. */
     pending: boolean;
+    /**
+     * What the last `switchCurrency` could not carry over: `lines_removed`
+     * (lines with no price in the new currency, left behind) and
+     * `discount_dropped` (a code the new currency refuses). Empty otherwise.
+     */
+    warnings: CartWarning[];
 };
 type CartOptions = {
     currency?: string;
@@ -138,14 +138,20 @@ type UseCartResult = CartState & {
         checkoutUrl: string;
     }>;
     /**
-     * A new cart with the current lines in `currency` (BC4); the old one is
-     * left to Throttle. It lands whole or not at all: if the new cart cannot be
-     * made, read back or saved, it rejects and the old cart, its stored id and
-     * the old currency stay (the unused new cart is left to Throttle).
+     * Moves the cart into `currency`, keeping one cart per currency (MC2-R41):
+     * the shopper's open cart in `currency` (the signed-in customer's from
+     * `customerCart`, a guest's from `cartStorage.getFor`), else a new empty
+     * one, absorbs the current cart, which Throttle then closes as merged. Lines
+     * with no price in `currency` stay behind and a discount it refuses is
+     * dropped; both show in `warnings`. If anything fails before the absorb
+     * lands, it rejects and the old cart, its stored id and the old currency
+     * stay (an unused new cart is left to Throttle).
      */
     switchCurrency(currency: string): Promise<void>;
     /** Forgets the cart (no request). */
     clear(): Promise<void>;
+    /** `formatMoney(minor, currency)` in the cart's currency (before a cart, the hook's or the client's). */
+    format(minor: number): string;
 };
 /**
  * The provider's cart (P6-R15). The session id is kept in the provider's
@@ -178,5 +184,5 @@ type SubmitReviewResult = SubmitReviewState & {
  */
 declare function useSubmitReview(handle: string): SubmitReviewResult;
 
-export { CatalogProvider, catalogQueryKey, createMemoryCartStorage, useCart, useCatalog, useCategories, useCollection, useConfig, useFilterValues, useProduct, useProducts, useRelated, useReviews, useSubmitReview, useSuggest };
-export type { CartOptions, CartState, CartStorage, CartUrls, CatalogProviderProps, QueryOptions, QueryResult, SubmitReviewResult, SubmitReviewState, UseCartResult };
+export { CatalogProvider, CustomerCartSource, QueryOptions, QueryResult, createMemoryCartStorage, useCart, useCatalog, useCategories, useCollection, useConfig, useCustomerKey, useFilterValues, useProduct, useProducts, useRelated, useReviews, useSubmitReview, useSuggest };
+export type { CartOptions, CartState, CartStorage, CartUrls, CatalogProviderProps, SubmitReviewResult, SubmitReviewState, UseCartResult };