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>;
}

Usage:

const config: GloodConfig = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3, default 3
  debug: true,
};

PixelConfig

Configuration for pixel tracking per app.

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.

Usage:

const pixelConfig: PixelConfig = {
  enabled: true,
  endpoint: 'https://events.glood.ai',
  consent: ['analytics', 'marketing'],
};

App Configuration Types

RecommendationsAppConfig

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[];
}

Client & App Types

GloodClient

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;
}

GloodAppModule

Function type for app module factories.

interface GloodAppModule {
  /** Create app instance with optional custom configuration */
  (): GloodApp;
}

Usage:

// App module functions return GloodAppModule
const recommendationsModule: GloodAppModule = recommendations();

React Component Types

GloodProviderProps

Props for the GloodProvider React component.

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;
}

Usage:

function App() {
  return (
    <GloodProvider client={glood} loaderData={data}>
      <YourApp />
    </GloodProvider>
  );
}

Analytics Event Data Types

PageViewData

Data structure for page view events.

interface PageViewData {
  url: string;
  title?: string;
  referrer?: string;
  timestamp: number;
}

ProductViewData

Data structure for product view events.

interface ProductViewData {
  productId: string;
  productHandle: string;
  productTitle: string;
  productPrice: number;
  productVendor?: string;
  productType?: string;
  currency: string;
  timestamp: number;
}

SearchData

Data structure for search events.

interface SearchData {
  query: string;
  resultsCount: number;
  timestamp: number;
}

CollectionViewData

Data structure for collection view events.

interface CollectionViewData {
  collectionId: string;
  collectionHandle: string;
  collectionTitle: string;
  timestamp: number;
}

CartViewData

Data structure for cart view events.

interface CartViewData {
  cartId: string;
  totalPrice: number;
  itemCount: number;
  timestamp: number;
}

Recommendations API Types

GetSectionsParams

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;
}

Usage:

const params: GetSectionsParams = {
  pageType: 'product_page',
  productId: '8977367564515',
};

SectionsResponse

Full response from the sections API.

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 }>;
}

SectionProductVariant

interface SectionProductVariant {
  /** Numeric Shopify variant id */
  variant_id: number;

  title: string;
  display_name?: string;
  position?: number;
  sku?: string;

  /** Selected option values, e.g. [{ name: 'Size', value: 'S' }] */
  selected_options: Array<{ name: string; value: string }>;

  price: number | string | null;
  compare_at_price: number | string | null;
  image?: { url?: string } | null;
}

SectionProductOption

interface SectionProductOption {
  id: number;
  name: string;
  values: string[];
  position: number;
}

SectionTrack

Attribution payload linking a glood:section:* event to a specific section render.

interface SectionTrack {
  /** Glood section id (as a string) */
  section?: string;

  /** section_serve_id from the sections response */
  sectionServeId?: string;

  /** request_id from the sections response */
  requestId?: string;

  /** Page type where the interaction happened */
  page?: string;

  /** Context product (e.g. the PDP product the section rendered on) */
  parent?: { productId?: string; variantId?: string };

  /** Products involved in the interaction */
  products?: SectionTrackProduct[];
}

interface SectionTrackProduct {
  productId: string;
  variantId?: string;
  quantity?: number;
}

FetchSectionsOptions

Options for fetchRecommendationSections().

interface FetchSectionsOptions {
  /** Glood storefront token (same value as GloodConfig.apiKey) */
  apiKey: string;

  /** Shop domain, e.g. 'store-name.myshopify.com' */
  myShopifyDomain: string;

  /** Recommendations endpoint override (defaults to https://storefront.glood.ai) */
  endpoint?: string;

  /** Log request/response details */
  debug?: boolean;
}

GloodApiError

Error thrown when the sections API responds with a non-2xx status.

class GloodApiError extends Error {
  /** HTTP status code */
  readonly status: number;

  /** Parsed JSON error body */
  readonly body: unknown;
}

Usage:

import { GloodApiError } from '@glood/hydrogen';

if (error instanceof GloodApiError) {
  console.error(error.status, error.body);
}

Headless API Types

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;
}

InitParams

Parameters for the v3 session init call.

interface InitParams {
  userId?: string;
  clientId?: string;
  customerId?: string;
  pageType?: PageType;
  pageUrl?: string;
}

InitResponse

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;
}

HeadlessEventResponse

Response from the events API.

interface HeadlessEventResponse {
  ok: boolean;
  [key: string]: any;
}

RecommendationView

Shape of items returned by a recommendation query.

type RecommendationView = 'product_details' | 'product_ids';

RecommendedProduct

A product returned in the product_details view — same shape as SectionProduct.

type RecommendedProduct = SectionProduct;

RecommendedProductRef

A product returned in the product_ids view.

interface RecommendedProductRef {
  product_id: number;
}

RecommendedItem

A recommended item — either a full product or a product id reference, depending on the query’s view.

type RecommendedItem = RecommendedProduct | RecommendedProductRef;

RecommendationQuery

A single query in a multi-query v3 recommendations request.

interface RecommendationQuery {
  /** Caller-chosen id; results are keyed by it in the response */
  id: string;

  /**
   * One of the RecommendationType values: 'similar_products' | 'bought_together' |
   * 'recently_viewed' | 'cross_sell' | 'bestsellers' | 'trending' | 'personalized' |
   * 'recent_launch' | 'collections' | 'purchases' | 'promoted' | 'custom' |
   * 'email_recommendations'. See the Signatures page → Enums for support notes.
   */
  recommendationType: string;

  /** Anchor product ids (v3 accepts up to 10 per query) */
  productIds: Array<string | number>;

  maxRecommendations?: number;
  creationType?: string;
  view: RecommendationView;
}

RecommendationsParams

Parameters for the v3 recommendations endpoint (POST /api/storefront/v3/headless/recommendations).

interface RecommendationsParams {
  queries: RecommendationQuery[];
  clientId?: string;
  userId?: string;
  customerId?: string;
}

RecommendationsResponse

Response from the v3 recommendations endpoint. Results are keyed by each query’s id.

interface RecommendationsResponse {
  status: string;
  serve_id: string;
  data: Record<
    string,
    {
      recommendation_serve_id: string;
      recommendation_type: string;
      max_recommendations?: number;
      creation_type?: string;
      product_ids: number[];
      view: RecommendationView;
      recommendations: RecommendedItem[];
    }
  >;
}

V2RecommendationsParams

Parameters for the legacy v2 recommendations endpoint (POST /api/storefront/v2/headless/recommendations, similar_products only).

interface V2RecommendationsParams {
  queries: RecommendationQuery[];
}

V2RecommendationsResponse

Response from the v2 recommendations endpoint. Results are keyed by each query’s id.

interface V2RecommendationsResponse {
  status: string;
  data: Record<string, { serve_id: string; products: RecommendedItem[] }>;
}

AutomaticRecommendationsParams

Parameters for the v3 automatic recommendations endpoint (POST /api/storefront/v3/headless/recommendations/automatic) — single anchor, paginated.

interface AutomaticRecommendationsParams {
  productIds: number[];
  view: RecommendationView;

  /** Only 'similar_products' is supported by this endpoint */
  recommendationType?: 'similar_products';

  maxRecommendations?: number;
  filter?: Record<string, any>;
  pagination?: { cursor?: string | null; limit?: number };
}

AutomaticRecommendationsResponse

interface AutomaticRecommendationsResponse {
  status: string;
  serve_id: string;
  pagination: { cursor: string | null; hasMore?: boolean };
  products: RecommendedItem[];
}

TopStrategy

Strategy for the anchorless top recommendations endpoint. Values are uppercase (they map directly to the backend enum).

type TopStrategy = 'BESTSELLERS' | 'NEW_ARRIVALS';

TopFacet

Facet dimensions returned by the top recommendations endpoint.

type TopFacet = 'vendor' | 'product_type' | 'tag' | 'price';

TopRecommendationsParams

Parameters for the v3 top recommendations endpoint (POST /api/storefront/v3/headless/recommendations/top) — anchorless, faceted.

interface TopRecommendationsParams {
  strategy: TopStrategy;
  view: RecommendationView;
  strategyOptions?: {
    salesTimePeriod?: 7 | 15 | 30;
    bestsellerMetric?: string;
  };

  /** Full-text search over the catalog */
  query?: string;

  filter?: Record<string, any>;
  facets?: TopFacet[];
  pagination?: { cursor?: string | null; limit?: number };
}

TopRecommendationsResponse

interface TopRecommendationsResponse {
  status: string;
  serve_id: string;
  strategy: string;
  pagination: {
    cursor: string | null;
    hasMore: boolean;
    total: number;
    totalRelation: string;
    limit: number;
  };
  products: RecommendedItem[];
  facets?: Record<string, any>;
}

Pixel System Types

PixelEvent

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;
}

PixelPayload

Complete pixel payload sent to Glood endpoints.

interface PixelPayload {
  events: Record<string, any>[];
  apiKey: string;
  shopDomain: string;
  timestamp: number;
}

Constant Types

AppName

Union type for available app names.

type AppName = 'recommendations';

Usage:

const appName: AppName = 'recommendations'; // ✅ Valid
const invalidName: AppName = 'invalid'; // ❌ TypeScript error

EventType

Union type for all supported analytics events.

type EventType =
  | 'page_viewed'
  | 'product_viewed'
  | 'collection_viewed'
  | 'cart_viewed'
  | 'search_viewed'
  | 'search_submitted'
  | 'custom_promotion_viewed'
  | 'product_added_to_cart'
  | 'product_removed_from_cart';

Usage:

const event: EventType = 'product_viewed'; // ✅ Valid
const invalidEvent: EventType = 'invalid_event'; // ❌ TypeScript error

ConsentType

Union type for customer privacy consent types.

type ConsentType =
  | 'analytics'
  | 'marketing'
  | 'preferences'
  | 'sale_of_data';

Usage:

const consent: ConsentType[] = ['analytics', 'marketing']; // ✅ Valid
const invalidConsent: ConsentType[] = ['invalid']; // ❌ TypeScript error

PageType

Union type of page types accepted by the sections API.

type PageType =
  | 'product_page'
  | 'collection'
  | 'home'
  | 'cart'
  | 'order_confirm'
  | 'other'
  | 'blog'
  | 'ajax_cart'
  | '404'
  | 'checkout'
  | 'returns';

The PAGE_TYPES constant exports the same list as a runtime array.

GloodSectionEventName

Union type of the custom attribution event names.

type GloodSectionEventName =
  | 'glood:section:render'
  | 'glood:section:view'
  | 'glood:section:click'
  | 'glood:section:add_to_cart';

The SECTION_EVENT_NAMES constant exports the same list as a runtime array.

Type Imports

Import specific types as needed:

// Import all types
import type {
  GloodConfig,
  GloodClient,
  GloodApp,
  AppName,
  EventType,
  ConsentType,
  PixelConfig,
} from '@glood/hydrogen';

// Import specific app config types
import type {
  RecommendationsAppConfig,
} from '@glood/hydrogen';

// Import event data types
import type {
  PageViewData,
  ProductViewData,
  SearchData,
  CartViewData,
} from '@glood/hydrogen';

// Import React component types
import type {
  GloodProviderProps,
} from '@glood/hydrogen';

// Import recommendations API types
import 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 import
import type { GloodConfig } from '@glood/hydrogen';

// ❌ Avoid - Runtime import for types
import { GloodConfig } from '@glood/hydrogen';

2. Use Const Assertions

Use const assertions for consent literals:

// ✅ Good - Const assertion preserves literal types
const consent = ['analytics', 'marketing'] as const;

​TypeScript Types

​Core Configuration Types

​GloodConfig

​PixelConfig

​App Configuration Types

​RecommendationsAppConfig

​Client & App Types

​GloodClient

​GloodApp

​GloodAppModule

​React Component Types

​GloodProviderProps

​Analytics Event Data Types

​PageViewData

​ProductViewData

​SearchData

​CollectionViewData

​CartViewData

​Recommendations API Types

​GetSectionsParams

​SectionsResponse

​RecommendationSection

​SectionProduct

​SectionProductVariant

​SectionProductOption

​SectionTrack

​FetchSectionsOptions

​GloodApiError

​Headless API Types

​ApiVersion

​HeadlessRequestOptions

​InitParams

​InitResponse

​HeadlessEventChannel

​HeadlessEventParams

​HeadlessEventResponse

​RecommendationView

​RecommendedProduct

​RecommendedProductRef

​RecommendedItem

​RecommendationQuery

​RecommendationsParams

​RecommendationsResponse

​V2RecommendationsParams

​V2RecommendationsResponse

​AutomaticRecommendationsParams

​AutomaticRecommendationsResponse

​TopStrategy

​TopFacet

​TopRecommendationsParams

​TopRecommendationsResponse

​Pixel System Types

​PixelEvent

​PixelPayload

​Constant Types

​AppName

​EventType

​ConsentType

​PageType

​GloodSectionEventName

​Type Imports

​Best Practices

​1. Use Type-Only Imports

​2. Use Const Assertions

​See Also

TypeScript Types

Core Configuration Types

GloodConfig

PixelConfig

App Configuration Types

RecommendationsAppConfig

Client & App Types

GloodClient

GloodApp

GloodAppModule

React Component Types

GloodProviderProps

Analytics Event Data Types

PageViewData

ProductViewData

SearchData

CollectionViewData

CartViewData

Recommendations API Types

GetSectionsParams

SectionsResponse

RecommendationSection

SectionProduct

SectionProductVariant

SectionProductOption

SectionTrack

FetchSectionsOptions

GloodApiError

Headless API Types

ApiVersion

HeadlessRequestOptions

InitParams

InitResponse

HeadlessEventChannel

HeadlessEventParams

HeadlessEventResponse

RecommendationView

RecommendedProduct

RecommendedProductRef

RecommendedItem

RecommendationQuery

RecommendationsParams

RecommendationsResponse

V2RecommendationsParams

V2RecommendationsResponse

AutomaticRecommendationsParams

AutomaticRecommendationsResponse

TopStrategy

TopFacet

TopRecommendationsParams

TopRecommendationsResponse

Pixel System Types

PixelEvent

PixelPayload

Constant Types

AppName

EventType

ConsentType

PageType

GloodSectionEventName

Type Imports

Best Practices

1. Use Type-Only Imports

2. Use Const Assertions

See Also