Complete TypeScript interface definitions for the Glood Hydrogen SDK
TypeScript Types
The Glood Hydrogen SDK is built with TypeScript-first design, providing comprehensive type definitions for all interfaces, configurations, and data structures.
Core Configuration Types
GloodConfig
Main configuration interface for creating a Glood client.
interface GloodConfig { /** Glood API key for authentication */ apiKey: string; /** Your Shopify domain (e.g., 'store-name.myshopify.com') */ myShopifyDomain: string; /** * Headless API version to use (2 or 3). Defaults to 3. Version 3 is the full * suite (init, sections, events, recommendations variants); version 2 only * has recommendations and authenticates by shop header alone (no bearer token). */ version?: ApiVersion; /** App-specific configurations (optional - uses defaults if not provided) */ apps?: { recommendations?: RecommendationsAppConfig; }; /** Enable debug logging in development */ debug?: boolean; /** Additional settings object */ settings?: Record<string, any>;}
interface PixelConfig { /** Enable/disable pixel tracking for this app */ enabled: boolean; /** Retained for config compatibility; no longer used to route events (see note) */ endpoint: string; /** Required consent types for pixel tracking */ consent: readonly ConsentType[];}
pixel.endpoint is retained for backward compatibility but no longer
determines where events are sent. Events are routed by the client’s
version off the app’s main endpoint (v3 → /api/storefront/v3/headless/events,
v2 → /api/storefront/event). pixel.enabled and pixel.consent still apply.
Configuration specific to the recommendations app.
interface RecommendationsAppConfig { /** Main app endpoint for features and API calls */ endpoint: string; /** Pixel tracking configuration */ pixel: PixelConfig; /** Events this app should subscribe to (defaults to all events if not specified) */ subscribedEvents?: EventType[];}
SearchAppConfig
Configuration specific to the search app.
interface SearchAppConfig { /** * Main app endpoint — used for init, config, instant-search, filters, * filter-aggregations and search. Point this at a regional edge to serve * those from the edge. Defaults to https://search.glood.ai. */ endpoint: string; /** * Non-edge (control-plane) endpoint for calls the edge cannot serve: * image search (needs the vision/embedding pipeline) and event ingestion. * Defaults to the built-in non-edge host, so overriding only `endpoint` * with an edge URL keeps image search + events on the control plane. */ controlEndpoint?: string; /** Pixel tracking configuration */ pixel: PixelConfig; /** Events this app should subscribe to (defaults to all events if not specified) */ subscribedEvents?: EventType[];}
The main client interface returned by createGlood().
interface GloodClient { /** Configuration used to create this client */ config: GloodConfig; /** Debug mode enabled */ debug: boolean; /** Registered apps */ apps: Map<AppName, GloodApp>; /** Get all enabled apps */ getEnabledApps(): GloodApp[]; /** Get specific app by name */ getApp(name: AppName): GloodApp | undefined; /** Add an app module to the client */ use(appModuleOrFactory: GloodAppModule | ((config?: any) => GloodAppModule)): GloodClient; /** Read the /v3/headless/init response saved on page load (null until it runs / for v2) */ getInitData(): InitResponse | null; /** Save the init response — called by runHeadlessInit; not intended for app code */ setInitData(data: InitResponse | null): void;}
GloodApp
Interface representing an individual app instance.
interface GloodApp { /** App name */ name: AppName; /** Main app endpoint for features */ endpoint: string; /** Pixel configuration */ pixel: PixelConfig; /** Events this app subscribes to */ subscribedEvents: EventType[]; /** Analytics instance from Hydrogen useAnalytics hook */ analytics?: any; /** Loader data from the Hydrogen route loader */ loaderData?: any; /** Handle an analytics event */ handleEvent(eventType: EventType, eventData: any, client: GloodClient): void; /** Set analytics instance on the app */ setAnalytics(analytics: any): void; /** Set loader data on the app */ setLoaderData?: (loaderData: any) => void; /** Set the owning client (injected by client.use()) so the app can make API calls */ setClient?: (client: GloodClient) => void; /** Update subscribed events for this app */ setSubscribedEvents(events: EventType[]): void;}
interface GloodProviderProps { /** Glood client instance */ client: GloodClient; /** Child components to wrap */ children: React.ReactNode; /** Route loader data — used to seed the session/init on first render */ loaderData: any;}
Parameters for fetching recommendation sections — used by both useRecommendations() and fetchRecommendationSections().
interface GetSectionsParams { /** Page type the visitor is on */ pageType: PageType; /** Full URL of the current page (defaults to window.location.href in the browser) */ pageUrl?: string; /** Locale code, e.g. 'en-US' (defaults to navigator.language in the browser) */ locale?: string; /** Numeric Shopify product id (not GID) — required for product page recommendations */ productId?: string | number; /** Numeric product ids currently in the cart */ cartProductIds?: Array<string | number>; /** Specific Glood section ids to fetch (empty = all enabled sections for the page) */ sections?: number[]; /** Glood client id (defaults to the _glood_client_id cookie in the browser) */ clientId?: string; /** Logged-in user id */ userId?: string; /** Shopify customer id */ customerId?: string; /** Market id for multi-market shops */ market?: string; /** Currency code */ currency?: string; /** Cart total value */ cartValue?: string; /** Numeric collection id (for collection pages) */ collection?: number; /** Query string used for experience assignment */ qs?: string; /** Include disabled sections (preview mode) */ preview?: boolean;}
interface SectionsResponse { /** Unique id for this request — pass to attribution events */ request_id: string; /** Sections with full product data */ sections: RecommendationSection[]; /** Current product details (product pages), or null */ product: Record<string, any> | null; /** Shopify storefront access token from the shop config */ token: string | null; /** Shop configuration (currency, money format, integrations, ...) */ config: Record<string, any>; /** Assigned A/B experience id — persisted to localStorage automatically */ experience: string | null; /** Unique id for this visit */ visit_id: string | null;}
RecommendationSection
A recommendation section configured in the Glood dashboard, served with its products.
interface RecommendationSection { /** Glood section id */ id: number; /** Serve id used to attribute glood:section:* events to this render */ section_serve_id: string; /** Page type this section was served for */ page_type: string; /** A/B experience this section belongs to */ experience_id: string | null; /** Layout, e.g. 'horizontal_grid', 'carousel' */ layout: string; /** Placement location configured in the dashboard */ location: string; /** Recommendation type, e.g. 'bestsellers', 'similar_products', 'bought_together' */ type: string; /** Position among sections on the page */ position: number; /** Translated section title */ title: string; /** Extra section settings */ extra: Record<string, any>; /** Discount configuration for this section */ discount_config: Record<string, any> | null; /** Whether to show discount labels */ show_discount_label: boolean; /** Title translations */ translations: Record<string, any> | null; /** Recommended products with full data */ products: SectionProduct[]; /** Pagination cursor (null when not paginated) */ cursor: string | null; /** Whether more products are available */ hasMore: boolean;}
SectionProduct
A recommended product with complete display data.
interface SectionProduct { /** Numeric Shopify product id */ product_id: number; title: string; handle: string; vendor?: string; product_type?: string; /** Comma-separated tag list */ tags?: string; /** Minimum price across variants */ price: number | null; /** Compare-at price (null when not on sale) */ compare_at_price: number | null; /** Featured image */ image?: { url?: string } | null; /** Product options (Size, Color, ...) */ options: SectionProductOption[]; /** All variants */ variants: SectionProductVariant[]; metafields?: Array<{ namespace: string; key: string; value: string }>;}
The headless API is version-aware. A v3 client uses the full suite (/init, /sections, /events, and the recommendations variants); a v2 client is legacy and only supports recommendations, authenticating by shop header alone (no bearer token).
ApiVersion
Headless API version selector. Defaults to 3.
type ApiVersion = 2 | 3;
HeadlessRequestOptions
Options passed as the first argument to every standalone headless function (server loaders / advanced usage).
interface HeadlessRequestOptions { /** Glood API key for authentication */ apiKey: string; /** Shop domain, e.g. 'store-name.myshopify.com' */ myShopifyDomain: string; /** Endpoint override (defaults to https://storefront.glood.ai) */ endpoint?: string; /** Headless API version to use (2 or 3). Defaults to 3. */ version?: ApiVersion; /** Log request/response details */ debug?: boolean;}
Response from POST /api/storefront/v3/headless/init. Exposed via the useGloodInit() hook. Always null for v2 clients (init is a v3-only endpoint).
interface InitResponse { /** Per-visit id (persisted to the _glood_visit_id session cookie) */ visit_id: string; /** Visitor id (persisted to the _glood_user_id cookie, replayed on return) */ user_id: string; client_id: string | null; customer_id: string | null; /** Visitor history */ visitor: { browsed_products: any[]; cart_products: any[]; purchased_products: any[]; }; /** Shop configuration (currency, money_format, storefront_graphql_version, integrations, analytics_enabled, ...) */ config: Record<string, any>; /** Shopify storefront access token */ token: string | null;}
HeadlessEventChannel
Channel a headless event originates from. Defaults to 'hydrogen'.
type HeadlessEventChannel = 'mobile' | 'headless' | 'hydrogen';
HeadlessEventParams
Parameters for sending an analytics/attribution event to the versioned events API. On a v3 client this posts to POST /api/storefront/v3/headless/events.
interface HeadlessEventParams { event: { id: string; name: string; type: 'standard' | 'custom'; /** ISO 8601 timestamp; must be within ±2 days of now (server rule) */ timestamp: string; data?: Record<string, any>; customData?: { track: SectionTrack }; }; /** Defaults to 'hydrogen' */ channel?: HeadlessEventChannel; /** Defaults to the session cookie in the browser (server requires it) */ sessionId?: string; /** At least one of clientId / userId is required by the server */ clientId?: string; userId?: string; customerId?: string; experience?: string | null; pageType?: string; pageUrl?: string; [key: string]: any;}
Session bootstrap. GloodProvider runs init once on mount; useSearchInit() exposes the
response and useSearchInitReady() the settled flag that useSearch/useInstantSearch gate on.
interface SearchInitParams { pageType?: string; pageUrl?: string; locale?: string; market?: number; visitorId?: string; // defaults from cookie in the browser clientId?: string; // defaults from cookie in the browser customerId?: string;}interface SearchInitResponse { visit_id: string; // fresh session id; echo as session_id on events visitor_id: string | null; client_id: string | null; customer_id: string | null; visitor: { browsed_products: number[]; cart_products: number[]; purchased_products: number[]; }; config: Record<string, any>; // lean feature flags (no filters/tree; see REST reference) token: string | null; // Shopify storefront access token metadata: { region?: string; locale?: string; market?: number | null; [k: string]: any };}
Structure for pixel events in the transmission queue.
interface PixelEvent { endpoint: string; data: Record<string, any>; /** * Request headers. When omitted, the queue falls back to * { 'Content-Type': 'application/json', 'x-shop-myshopify-domain': shopDomain }. */ headers?: Record<string, string>; /** Legacy shortcut used to build the x-shop-myshopify-domain header when `headers` is not given */ shopDomain?: string;}
The SECTION_EVENT_NAMES constant exports the same list as a runtime array.
Type Imports
Import specific types as needed:
// Import all typesimport type { GloodConfig, GloodClient, GloodApp, AppName, EventType, ConsentType, PixelConfig,} from '@glood/hydrogen';// Import specific app config typesimport type { RecommendationsAppConfig,} from '@glood/hydrogen';// Import event data typesimport type { PageViewData, ProductViewData, SearchData, CartViewData,} from '@glood/hydrogen';// Import React component typesimport type { GloodProviderProps,} from '@glood/hydrogen';// Import recommendations API typesimport type { GetSectionsParams, SectionsResponse, RecommendationSection, SectionProduct, SectionProductVariant, SectionProductOption, SectionTrack, SectionTrackProduct, FetchSectionsOptions, UseRecommendationsOptions, UseRecommendationsResult, PageType, GloodSectionEventName,} from '@glood/hydrogen';
Best Practices
1. Use Type-Only Imports
Import types with import type so they’re erased at build time:
// ✅ Good - Type-only importimport type { GloodConfig } from '@glood/hydrogen';// ❌ Avoid - Runtime import for typesimport { GloodConfig } from '@glood/hydrogen';
2. Use Const Assertions
Use const assertions for consent literals:
// ✅ Good - Const assertion preserves literal typesconst consent = ['analytics', 'marketing'] as const;