@liquidcommerce/cloud-sdk 1.17.0 → 1.19.0

package/dist/types/interfaces/catalog.interface.d.ts

@@ -94,6 +94,81 @@ export interface ICatalogParams extends ILocBase {
     orderDirection?: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE;
     filters?: Array<ICategoryFilter | IPriceFilter | IAvailabilityFilter | IFulfillmentFilter | IEngravingFilter | IPresaleFilter | IFilter>;
 }
+export interface ICatalogComposeSectionParams {
+    sectionId: string;
+    source?: 'query' | 'regionalPopularity';
+    search?: string;
+    perPage?: number;
+    orderBy?: ENUM_ORDER_BY;
+    orderDirection?: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE;
+    filters?: ICatalogParams['filters'];
+}
+export interface ICatalogComposeParams {
+    /** Opaque Cloud-issued context; mutually exclusive with loc. */
+    locationContext?: string;
+    /** State and delivery area are resolved by Cloud from these coordinates. */
+    loc?: {
+        coords: {
+            lat: number;
+            long: number;
+        };
+    };
+    /** Cloud accepts at most one retailer ID; omit or pass [] for no hard retailer scope. */
+    retailers?: string[];
+    fulfillmentType?: 'onDemand' | 'shipping';
+    sections: ICatalogComposeSectionParams[];
+}
+export interface ICatalogComposeSectionResult {
+    sectionId: string;
+    status: 'ok' | 'partial' | 'exhausted' | 'error' | 'unavailable';
+    products: ICatalogComposeCardProduct[];
+    total: number;
+    requestedCount: number;
+    examinedCandidates: number;
+    selection?: IRegionalPopularitySelection;
+    reason?: string;
+}
+export interface IRegionalPopularityCandidate {
+    gtin14: string;
+    catalogVariantId: string;
+    catalogProductId: string;
+    rank: number;
+}
+export interface IRegionalPopularitySelection {
+    source: 'regionalPopularity';
+    status: 'fresh' | 'stale';
+    snapshotId: string;
+    policyVersion: 'v1';
+    generatedAtMs: number;
+    sourceWatermarkMs: number;
+    windowStart: string;
+    windowEndExclusive: string;
+    regionType: 'state' | 'national';
+    regionKey: string;
+    fallback: boolean;
+    fallbackReason?: 'no_state' | 'state_not_qualified';
+}
+export interface ICatalogComposeCardProduct extends Pick<IProduct, 'id' | 'name' | 'brand' | 'images' | 'priceInfo'> {
+    popularity?: IRegionalPopularityCandidate;
+    fulfillmentKind: 'onDemand' | 'shipping';
+    sizes: Array<Pick<IProductSize, 'id' | 'upc' | 'size' | 'image' | 'price' | 'pack' | 'packDesc'> & {
+        variants: Array<Pick<IProductVariant, 'partNumber' | 'retailerId' | 'price' | 'salePrice' | 'stock' | 'fulfillmentTypes'>>;
+    }>;
+}
+export interface ICatalogComposeRetailerSummary {
+    id: string;
+    name: string;
+    fulfillments: Array<{
+        id: string;
+        type: string;
+        fees: unknown;
+        expectation: unknown;
+    }>;
+}
+export interface ICatalogComposeResult {
+    sections: ICatalogComposeSectionResult[];
+    retailers: ICatalogComposeRetailerSummary[];
+}
 /**
  * ICatalog interface represents a structured collection of retailers, products, and navigation schema.
  */
@@ -255,6 +330,19 @@ export interface IAttributesPersonalization {
     fee: number;
     availableFrom: Date;
     availableTo: Date;
+    isRequired?: boolean;
+    /** Ordered; pickers preselect the first font. Absent or empty means no font choice. */
+    fonts?: IPartnerEngravingFont[];
+}
+/**
+ * One font as a partner attached it to a size. `maxLines`/`maxCharsPerLine` may only tighten
+ * the size's own limits; `sampleImageUrl` is the partner's mock-up of this bottle in this font.
+ */
+export interface IPartnerEngravingFont {
+    key: string;
+    maxLines?: number;
+    maxCharsPerLine?: number;
+    sampleImageUrl?: string;
 }
 /**
  * IAttributes interface represents the attributes of a product, including its origin,
@@ -301,8 +389,35 @@ export interface IProductVariant {
     fulfillments: string[];
     fulfillmentTypes: IProductFulfillmentTypes;
 }
+/**
+ * An engraving font a shopper may pick for a size.
+ *
+ * `woff2Url` is the file to load in the browser (CSS Font Loading API), `previewImageUrl`
+ * the selector tile. `maxLines`/`maxCharsPerLine` are the effective limits for text in this
+ * font on this size (never more than `IProductSizeEngraving` allows), so apply them to the
+ * input once a font is chosen; `allowedCharsPattern` and `supportsAllCaps` describe what the
+ * font can draw.
+ */
+export interface IEngravingFontOption {
+    key: string;
+    name: string;
+    woff2Url: string;
+    ttfUrl?: string;
+    previewImageUrl: string;
+    sampleImageUrl?: string;
+    maxLines: number;
+    maxCharsPerLine: number;
+    allowedCharsPattern?: string;
+    supportsAllCaps?: boolean;
+}
 /**
  * Represents the engraving details for a product size.
+ *
+ * `fonts` is ordered: preselect the first one in a picker and send the shopper's choice as
+ * `personalization.fontKey`. Filter it by the chosen fulfillment's `engravingFontKeys` first.
+ * Limits to apply are the chosen font's, never looser than the size's. Cloud applies a font only when a key
+ * is sent; lines alone are engraved without a font. An empty list means no font choice;
+ * engraving then behaves as it always has.
  */
 export interface IProductSizeEngraving {
     status: boolean;
@@ -312,6 +427,7 @@ export interface IProductSizeEngraving {
     fee: number;
     location: string;
     isRequired: boolean;
+    fonts?: IEngravingFontOption[];
 }
 /**
  * Interface representing a product presale.
@@ -501,3 +617,16 @@ export interface ICatalogProductsPage {
     nextCursor?: string;
     counts: ICatalogProductPageCounts;
 }
+/** Issue an opaque context through the authenticated partner's Cloud location semantics. */
+export interface ICatalogLocationContextParams {
+    loc: {
+        coords: {
+            lat: number;
+            long: number;
+        };
+    };
+}
+export interface ICatalogLocationContext {
+    locationContext: string;
+    expiresAt: string;
+}

package/dist/types/interfaces/liquid-commerce-client.interface.d.ts

@@ -1,7 +1,7 @@
 import type { IApiResponseWithData, IApiResponseWithoutData, IAuth, ILiquidCommerceConfig } from '../types';
 import type { IAddressAutocompleteParams, IAddressAutocompleteResult, IAddressDetailsParams, IAddressDetailsResult } from './address.interface';
 import type { ICart, ICartUpdateParams } from './cart.interface';
-import type { IAvailabilityParams, IAvailabilityResponse, ICatalog, ICatalogAutocompleteParams, ICatalogParams, ICatalogProductItem, ICatalogProductsPage, ICatalogProductsParams, ICatalogSuggestion } from './catalog.interface';
+import type { IAvailabilityParams, IAvailabilityResponse, ICatalog, ICatalogAutocompleteParams, ICatalogComposeParams, ICatalogComposeResult, ICatalogLocationContext, ICatalogLocationContextParams, ICatalogParams, ICatalogProductItem, ICatalogProductsPage, ICatalogProductsParams, ICatalogSuggestion } from './catalog.interface';
 import type { ICheckoutCompleteParams, ICheckoutCompleteResponse, ICheckoutPrepareParams, ICheckoutPrepareResponse } from './checkout.interface';
 import type { ILiquidPaymentConfig, ILiquidPaymentToken, IPaymentElementEventMap } from './payment.interface';
 import type { BaseUser, IPurgeResponse, IUser, IUserAddress, IUserAddressParams, IUserPayment, IUserPaymentAddParams, IUserPaymentParams, IUserPaymentSession, IUserSession, IUserSessionParams } from './user.interface';
@@ -318,6 +318,10 @@ export interface ICatalogMethod {
      * @see {@link ICatalogProductItem} for the structure of one product.
      */
     iterateProducts: (params?: Omit<ICatalogProductsParams, 'cursor'>) => AsyncGenerator<ICatalogProductItem>;
+    /** Optional for existing custom clients; check this capability before calling. */
+    createLocationContext?: (params: ICatalogLocationContextParams) => Promise<IApiResponseWithoutData<ICatalogLocationContext>>;
+    /** Optional for existing custom clients; check this capability before calling. */
+    compose?: (params: ICatalogComposeParams) => Promise<IApiResponseWithoutData<ICatalogComposeResult>>;
 }
 /**
  * Interface for methods related to cart operations, including retrieving and updating cart data.

package/dist/types/interfaces/retailer.interface.d.ts

@@ -164,6 +164,11 @@ export interface IRetailerFulfillments {
     id: string;
     type: ENUM_MODALITIES;
     canEngrave: boolean;
+    /**
+     * Engraving font keys this retailer can engrave; shoppers get the overlap with the size's
+     * fonts. Absent, null or empty: the retailer engraves, but offers no font choice.
+     */
+    engravingFontKeys?: string[] | null;
     deliveryFee?: number;
     shippingFee?: number;
     engravingFee?: number;

package/dist/types/services/catalog.service.d.ts

@@ -1,5 +1,5 @@
 import type { AuthenticatedService, CatalogHelperService } from '../core';
-import type { IAvailabilityParams, IAvailabilityResponse, ICatalog, ICatalogAutocompleteParams, ICatalogParams, ICatalogProductItem, ICatalogProductsPage, ICatalogProductsParams, ICatalogSuggestion } from '../interfaces';
+import type { IAvailabilityParams, IAvailabilityResponse, ICatalog, ICatalogAutocompleteParams, ICatalogComposeParams, ICatalogComposeResult, ICatalogLocationContext, ICatalogLocationContextParams, ICatalogParams, ICatalogProductItem, ICatalogProductsPage, ICatalogProductsParams, ICatalogSuggestion } from '../interfaces';
 import type { IApiResponseWithData, IApiResponseWithoutData } from '../types';
 /**
  * The CatalogService class provides methods for interacting with the catalog API.
@@ -84,4 +84,17 @@ export declare class CatalogService {
      * }
      */
     iterateProducts(params?: Omit<ICatalogProductsParams, 'cursor'>): AsyncGenerator<ICatalogProductItem>;
+    /**
+     * Issues an opaque location context for the authenticated partner.
+     * Rejects invalid coordinates before transport and forwards only coordinates.
+     * Does not log location-bearing requests or upstream error objects.
+     */
+    createLocationContext(params: ICatalogLocationContextParams): Promise<IApiResponseWithoutData<ICatalogLocationContext>>;
+    /**
+     * Requests delivery-first sections composed by Cloud in one catalog call.
+     * Rejects invalid section budgets and conflicting location inputs before transport.
+     * Does not log location-bearing requests or upstream error objects.
+     */
+    compose(params: ICatalogComposeParams): Promise<IApiResponseWithoutData<ICatalogComposeResult>>;
+    private validateComposeSection;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@liquidcommerce/cloud-sdk",
- "version": "1.17.0",
+ "version": "1.19.0",
  "description": "LiquidCommerce Cloud SDK",
  "main": "./dist/index.cjs",
  "module": "./dist/index.esm.js",