@snowcone-app/sdk 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.3
+
+### Patch Changes
+
+- [#268](https://github.com/snowcone-app/snowcone-monorepo/pull/268) [`dd90eba`](https://github.com/snowcone-app/snowcone-monorepo/commit/dd90eba8bbfbbaef82379cb997af84e21f7cad8f) Thanks [@kevinsproles](https://github.com/kevinsproles)! - fix(realtime): fail fast when a color/variant product is missing `variantId`
+
+  `RenderSession` now rejects a product that has a real variant axis (its
+  `options.combinations` expose 2+ distinct `variantId`s) but no valid `variantId`,
+  surfacing an immediate, actionable error at config/`connect()` time instead of
+  hanging silently for ~30s until the watchdog. Pass the catalog product's
+  `options` on `RenderProduct` to opt in. Single-variant / no-option products are
+  unaffected and still render with no `variantId`. The watchdog remains as the
+  backstop. New exports: `assertVariantSelected`, `RenderProductOptions`,
+  `RenderProductCombination`.
+
 ## 0.3.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -65,6 +65,7 @@ __export(index_exports, {
   UniversalContextProvider: () => UniversalContextProvider,
   VueAdapter: () => VueAdapter,
   adapterRegistry: () => adapterRegistry,
+  assertVariantSelected: () => assertVariantSelected,
   autoRegister: () => autoRegister,
   buildMockupUrl: () => buildMockupUrl2,
   componentRegistry: () => componentRegistry,
@@ -5523,6 +5524,30 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+function variantIdsOf(product) {
+  const combos = product.options?.combinations;
+  if (!combos?.length) return [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const c of combos) {
+    if (typeof c.variantId === "string" && c.variantId !== "") ids.add(c.variantId);
+  }
+  return [...ids];
+}
+function assertVariantSelected(product) {
+  const variantIds = variantIdsOf(product);
+  if (variantIds.length < 2) return;
+  const fix = `pass product.variantId from options.combinations[].variantId (valid ids: ${variantIds.join(", ")})`;
+  if (!product.variantId) {
+    throw new Error(
+      `RenderSession: product ${product.productId} requires a variantId \u2014 ${fix}`
+    );
+  }
+  if (!variantIds.includes(product.variantId)) {
+    throw new Error(
+      `RenderSession: product ${product.productId} has an invalid variantId "${product.variantId}" \u2014 ${fix}`
+    );
+  }
+}
 var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
@@ -5538,6 +5563,7 @@ var RenderSession = class {
     if (!opts.getToken && !opts.grantUrl) {
       throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
     }
+    if (opts.product) assertVariantSelected(opts.product);
     this.opts = opts;
     this.product = opts.product ?? null;
     this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
@@ -5557,6 +5583,7 @@ var RenderSession = class {
   }
   /** Set or update the product. Sends config immediately if already connected. */
   setProduct(product) {
+    assertVariantSelected(product);
     this.product = product;
     this.svc.sendConfig(this.toConfig(product));
   }
@@ -5572,6 +5599,13 @@ var RenderSession = class {
       );
     }
     const product = this.product;
+    try {
+      assertVariantSelected(product);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.errorCb?.(message);
+      return Promise.reject(err instanceof Error ? err : new Error(message));
+    }
     this.ready = new Promise((resolve, reject) => {
       let settled = false;
       this.svc.setCallbacks({
@@ -5831,6 +5865,7 @@ function createClient(config) {
   UniversalContextProvider,
   VueAdapter,
   adapterRegistry,
+  assertVariantSelected,
   autoRegister,
   buildMockupUrl,
   componentRegistry,

package/dist/index.d.cts

@@ -2604,6 +2604,29 @@ interface RenderState {
     elements?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 }
+/**
+ * A single variant combination from the catalog product's `options.combinations`.
+ * Each combination pins one value per variant-affecting attribute plus the
+ * `variantId` (gvid) that selection resolves to. Pass `options` on
+ * {@link RenderProduct} so the session can FAIL FAST when a required `variantId`
+ * is missing instead of silently hanging until the watchdog.
+ */
+interface RenderProductCombination {
+    /** The variant (gvid) this combination resolves to. */
+    variantId?: string;
+    /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
+    [attribute: string]: string | number | undefined;
+}
+/**
+ * The catalog product's `options` block (structurally typed). Only
+ * `combinations` is consumed by the session — to detect whether the product has
+ * a real variant axis (multiple distinct `variantId`s) so a missing/invalid
+ * {@link RenderProduct.variantId} can be rejected up front.
+ */
+interface RenderProductOptions {
+    combinations?: RenderProductCombination[];
+    [key: string]: unknown;
+}
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
@@ -2618,13 +2641,34 @@ interface RenderProduct {
      * Optional variant (gvid). Omit if the product has no variant axis. Required
      * for products with a color option — it auto-fills the color placement; without
      * it the render waits for a color blob that never comes.
+     *
+     * If you also pass {@link RenderProduct.options}, the session validates this
+     * up front: a product whose `options.combinations` exposes more than one
+     * variant REQUIRES a `variantId` (and it must be one of the combinations'),
+     * else the session throws immediately rather than hanging until the watchdog.
      */
     variantId?: string;
+    /**
+     * The catalog product's `options` block (its `options.combinations[].variantId`
+     * are the valid variant ids). Optional, but passing it lets the session detect
+     * a missing/invalid required `variantId` and FAIL FAST — turning the classic
+     * 30s silent hang into an immediate, actionable error. You can pass the whole
+     * catalog product's `options` object verbatim.
+     */
+    options?: RenderProductOptions;
     /** Render width in px (default 1000). */
     width?: number;
     /** Per-placement settings (tiling, scale mode). */
     placementSettings?: Record<string, PlacementSettings>;
 }
+/**
+ * Throws immediately if the product has a variant axis (its
+ * `options.combinations` expose 2+ distinct `variantId`s) but no valid
+ * `variantId` was supplied. This is the fail-fast guard for the otherwise-silent
+ * 30s render hang on color/variant products. Products with no `options` (or a
+ * single variant) are left untouched — they render fine with no `variantId`.
+ */
+declare function assertVariantSelected(product: RenderProduct): void;
 interface RenderSessionOptions {
     /** Publishable shop id (= shop.id, like Stripe pk_). */
     shop: string;
@@ -2819,4 +2863,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductCombination, type RenderProductOptions, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.d.ts

@@ -2604,6 +2604,29 @@ interface RenderState {
     elements?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 }
+/**
+ * A single variant combination from the catalog product's `options.combinations`.
+ * Each combination pins one value per variant-affecting attribute plus the
+ * `variantId` (gvid) that selection resolves to. Pass `options` on
+ * {@link RenderProduct} so the session can FAIL FAST when a required `variantId`
+ * is missing instead of silently hanging until the watchdog.
+ */
+interface RenderProductCombination {
+    /** The variant (gvid) this combination resolves to. */
+    variantId?: string;
+    /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
+    [attribute: string]: string | number | undefined;
+}
+/**
+ * The catalog product's `options` block (structurally typed). Only
+ * `combinations` is consumed by the session — to detect whether the product has
+ * a real variant axis (multiple distinct `variantId`s) so a missing/invalid
+ * {@link RenderProduct.variantId} can be rejected up front.
+ */
+interface RenderProductOptions {
+    combinations?: RenderProductCombination[];
+    [key: string]: unknown;
+}
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
@@ -2618,13 +2641,34 @@ interface RenderProduct {
      * Optional variant (gvid). Omit if the product has no variant axis. Required
      * for products with a color option — it auto-fills the color placement; without
      * it the render waits for a color blob that never comes.
+     *
+     * If you also pass {@link RenderProduct.options}, the session validates this
+     * up front: a product whose `options.combinations` exposes more than one
+     * variant REQUIRES a `variantId` (and it must be one of the combinations'),
+     * else the session throws immediately rather than hanging until the watchdog.
      */
     variantId?: string;
+    /**
+     * The catalog product's `options` block (its `options.combinations[].variantId`
+     * are the valid variant ids). Optional, but passing it lets the session detect
+     * a missing/invalid required `variantId` and FAIL FAST — turning the classic
+     * 30s silent hang into an immediate, actionable error. You can pass the whole
+     * catalog product's `options` object verbatim.
+     */
+    options?: RenderProductOptions;
     /** Render width in px (default 1000). */
     width?: number;
     /** Per-placement settings (tiling, scale mode). */
     placementSettings?: Record<string, PlacementSettings>;
 }
+/**
+ * Throws immediately if the product has a variant axis (its
+ * `options.combinations` expose 2+ distinct `variantId`s) but no valid
+ * `variantId` was supplied. This is the fail-fast guard for the otherwise-silent
+ * 30s render hang on color/variant products. Products with no `options` (or a
+ * single variant) are left untouched — they render fine with no `variantId`.
+ */
+declare function assertVariantSelected(product: RenderProduct): void;
 interface RenderSessionOptions {
     /** Publishable shop id (= shop.id, like Stripe pk_). */
     shop: string;
@@ -2819,4 +2863,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductCombination, type RenderProductOptions, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.js

@@ -4690,6 +4690,30 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+function variantIdsOf(product) {
+  const combos = product.options?.combinations;
+  if (!combos?.length) return [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const c of combos) {
+    if (typeof c.variantId === "string" && c.variantId !== "") ids.add(c.variantId);
+  }
+  return [...ids];
+}
+function assertVariantSelected(product) {
+  const variantIds = variantIdsOf(product);
+  if (variantIds.length < 2) return;
+  const fix = `pass product.variantId from options.combinations[].variantId (valid ids: ${variantIds.join(", ")})`;
+  if (!product.variantId) {
+    throw new Error(
+      `RenderSession: product ${product.productId} requires a variantId \u2014 ${fix}`
+    );
+  }
+  if (!variantIds.includes(product.variantId)) {
+    throw new Error(
+      `RenderSession: product ${product.productId} has an invalid variantId "${product.variantId}" \u2014 ${fix}`
+    );
+  }
+}
 var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
@@ -4705,6 +4729,7 @@ var RenderSession = class {
     if (!opts.getToken && !opts.grantUrl) {
       throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
     }
+    if (opts.product) assertVariantSelected(opts.product);
     this.opts = opts;
     this.product = opts.product ?? null;
     this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
@@ -4724,6 +4749,7 @@ var RenderSession = class {
   }
   /** Set or update the product. Sends config immediately if already connected. */
   setProduct(product) {
+    assertVariantSelected(product);
     this.product = product;
     this.svc.sendConfig(this.toConfig(product));
   }
@@ -4739,6 +4765,13 @@ var RenderSession = class {
       );
     }
     const product = this.product;
+    try {
+      assertVariantSelected(product);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.errorCb?.(message);
+      return Promise.reject(err instanceof Error ? err : new Error(message));
+    }
     this.ready = new Promise((resolve, reject) => {
       let settled = false;
       this.svc.setCallbacks({
@@ -4997,6 +5030,7 @@ export {
   UniversalContextProvider,
   VueAdapter,
   adapterRegistry,
+  assertVariantSelected,
   autoRegister,
   buildMockupUrl2 as buildMockupUrl,
   componentRegistry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",