Types

type AccountSectionId =
  | "spark-slot-my-account"
  | "recent-activity"
  | "shopping-lists"
  | "favourites"
  | "financials"
  | "my-details"
  | "reports"
  | "address-book"
  | "company-users";

type AnalyticsEventName =
  | "addToCart"
  | "cartUpdate"
  | "shoppingListSave"
  | "shoppingListLoad"
  | "shoppingListDelete"
  | "csvUpload"
  | "quickAdd"
  | "finalStageCheckout"
  | "shippingUpdate"
  | "beginCheckout"
  | "purchase"
  | "viewCart";

type AnalyticsOptions = {
  providers: {
    // "ga" for Google Analytics (GA4), "gtm" for Google Tag Manager, or your own function
    handler: "ga" | "gtm" | ((eventName: AnalyticsEventName, eventParams: unknown) => void);
    // The events to send to this provider
    events: Partial<Record<AnalyticsEventName, boolean>>;
  }[];
};

type Cart = {
  cartUuid: string;
  intent: string; // For example "ORDER"
  canCreateOrder: boolean;
  canCreateQuote: boolean;
  hasLaunched: boolean;
  lockedByUserId: string | null;
  lockedByUserLastAccessedAt: string | null;
  loadedFromPurchaseAt: string | null;
  loadedFromPurchaseType: string | null;
  items: CartItem[];
  validationErrors: CartValidationError[];
  taxInclusiveDisplay: boolean;
  totals: CartTotals;
  currencyCode: string;
  totalWeight: number | null;
  customerAddresses: { id: string; description: string }[];
  deliveryAddressId: string | null;
  customerReference: string | null;
  poNumber: string | null;
  shippingRequestedDate: string | null;
  customFields: { name: string; value: string }[];
  approvingFor: { name: string } | null;
  discounts: {
    id: string;
    slug: string;
    name: string;
    appliedCouponCodes: string[];
    amount: { net: number; gross: number; currencyCode: string };
  }[];
  discountsAreAvailable: boolean;
  couponCodes: string[];
  removedCouponCodes: string[];
  quote: {
    statusSlug: string;
    statusUpdated: string;
    expiry: string | null;
    assignedAgent: { id: string } | null;
    message: string | null;
    note: string | null;
  } | null;
};

type CartItem = ProductVariant & {
  type: string;
  itemKey: string; // Identifies the line in updateCart
  quantity: number;
  customAttributes: { key: string; value: string; type?: string | null }[];
  lineTotal: CartLineAmount;
  lineTotalPreDiscounts: CartLineAmount;
  lineTotalDiscountAmount: CartLineAmount;
  unitTotal: CartLineAmount;
  unitTotalPreDiscounts: CartLineAmount;
  unitTotalDiscountAmount: CartLineAmount;
  quotedPrice: string | null;
  preorderQuantityDisplay: number | null;
};

type CartItemInput = {
  sku?: string;
  itemKey?: string; // From a CartItem
  adjustQuantity?: number;
  quantity?: number;
  customAttributes?: { key: string; value: string; type?: string }[];
};

type CartLineAmount = {
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean;
};

type CartMoney = { number: string };

type CartResults = {
  messages: { type: string }[];
  requestedQuantity: number;
  resultantQuantity: number;
  itemKey: string;
  sku: string;
  name: string;
};

type CartTotals = {
  subTotal: {
    preDiscount: { net: CartMoney; gross: CartMoney };
    discount: { net: CartMoney; gross: CartMoney };
    charge: { net: CartMoney; gross: CartMoney };
  };
  shipping: {
    preDiscount: { net: CartMoney };
    discount: { net: CartMoney };
    charge: { net: CartMoney };
  };
  total: {
    charge: { gross: CartMoney; tax: CartMoney };
    discount: { net: CartMoney };
    preDiscount: { gross: CartMoney };
  };
};

type CartUIState = "cart" | "shipping" | "quote-details" | "payment" | "thanks";

type CartValidationError = {
  type: string;
  amount?: number;
  amountGross?: number;
  minimum?: number;
  maximum?: number;
  productName?: string;
  parentSKU?: string;
  variantSKU?: string;
  packSize?: number;
  availableQuantity?: number;
  overridden?: boolean;
};

type CheckoutElementConfig = {
  // A standard field
  id?: "customer-reference" | "po-number" | "shipping-requested-date";
  // A custom field (required unless id is set)
  name?: string;
  // Customer-facing text, keyed by language code
  translations?: Record<string, { title: string; detail?: string; [messageKey: string]: string | undefined }>;
  // HTML attributes such as type, required, min, max, maxlength and pattern
  attributes?: Record<string, string | number | boolean>;
  // For select fields: the drop-down options, optionally in groups
  options?: {
    translations?: Record<string, { groupName: string }>;
    items: { value: string; translations: Record<string, { label: string }> }[];
  }[];
  // Returns a message key from translations if the value is invalid
  onChange?(value: string, element: HTMLElement): string | null | undefined;
};

type CustomAccountDetailLinkType = "email" | "phone" | "sms" | "website";

type CustomLineItemInput = {
  // The name shown on the custom line item
  name: string;
  // The price of a single unit, as a decimal string
  quotedPrice: string;
  quantity: number;
};

type DisplayOptions = {
  orderListShowShippingAddress: boolean;
  customerReferenceHidden: boolean; // deprecated
  customerReferenceRequired: boolean; // deprecated
  customerReferenceMaxLength?: number; // deprecated
  darkTheme: boolean;
  savingsUseRrp: boolean;
  roundPriceBreakPercentages: boolean;
  showPriceBreakSavings: boolean;
  sectionConfiguration: {
    "my-account"?: {
      order?: AccountSectionId[];
      hide?: AccountSectionId[];
    };
  };
  showSlots: string[];
  showRrpToggle: boolean;
  showFavouritesLists: boolean;
  showShoppingLists: boolean;
  showSkus: boolean;
  hideFinancials?: boolean;
};

type DrawerUIState = "dashboard" | "browse-catalog" | "cart" | "sales-agent" | "account";

type ErrorOf<Q> = Q extends { readonly __graphqlTypes?: { error: infer TError } }
  ? TError
  : GraphqlError;

interface FetchResponse<TData = unknown, TError = GraphqlError> extends Response {
  json(): Promise<{ data: TData; errors: TError[] }>;
}

type GraphqlError = {
  message: string;
  path?: (string | number)[];
  extensions?: { code?: string; [key: string]: unknown };
};

type GraphqlExtensionError = GraphqlError & {
  extensions: { code: string; [key: string]: unknown };
};

type GraphqlQueryOrMutation<
  TResponse = unknown,
  TVariables = Record<string, unknown>,
  TError = GraphqlError,
> = string & {
  // Type-only: never set at runtime
  readonly __graphqlTypes?: { response: TResponse; variables: TVariables; error: TError };
};

type PaymentMethodName = "paymentOnAccount" | "paymentByInvoice" | "upfrontPayment" | "quote";

type Product = {
  id: string;
  externalId: string; // Your platform's product ID
  slug: string;
  variants: ProductVariant[];
};

type ProductVariant = {
  id: string;
  externalId: string; // Your platform's variant ID
  parentExternalId: string; // Your platform's product ID
  stockDisplay: {
    status: string; // For example "out_of_stock" or "backorder"
    units: number | null;
    available: unknown;
  } | null;
  restockDate: string | null;
  cartImageUrl: string | null;
  position: number;
  sku: string;
  barcode: string | null;
  slug: string;
  name: string;
  price: VariantPrice | null;
  rrp: unknown; // Legacy: use rrpV2
  rrpV2: { number: string; currency: string } | null;
  priceBreaks: VariantPriceBreak[];
  // Product settings, such as packSize, minOrderQuantity and maxOrderQuantity
  settings: { key: string; value: unknown }[];
  // The variant's options, such as { group: "Size", value: "M" }
  options: { group: string; value: string }[];
};

type ProductVariantDataPricing = {
  priceBreaks: VariantPriceBreak[] | null;
  rrpV2?: { number: string; currency: string } | null;
  unitTotal?: { currencyCode: string } | null; // Cart items only
};

type ProductVariantPricing = {
  totalPrice: number | null; // unitPrice × quantity
  totalRrpPrice: number | null;
  hasPriceBreaks: boolean;
  unitPrice: number | null; // The unit price at this quantity
  basePrice: number | null; // The unit price before price breaks
  priceBreaks: VariantPriceBreak[];
  priceBreakSavingsPercentage: number | null;
  rrpV2: { number: string; currency: string } | null;
  currencyCode: string;
  unitPriceBreakdown: {
    items: {
      unitOfMeasure: string | null;
      price: number;
      quantity: number;
      uomQuantity: number;
    }[];
  };
};

type ResponseOf<Q> = Q extends { readonly __graphqlTypes?: { response: infer TResponse } }
  ? TResponse
  : unknown;

type SimplifiedProductPrice = {
  numberOfPrices: number;
  numberOfPricesExcludingBreaks: number;
  numberOfRrpPrices: number;
  fromPrice: number | null;
  fromPriceExcludingBreaks: number | null;
  currencyCode: string;
  hasPriceBreaks: boolean;
  rrpPrice: number | null;
  rrpCurrencyCode: string | null;
  taxInclusiveDisplay: boolean;
};

type Spark = {
  options: SparkLayerOptions;
  isLoggedIn(): Promise<boolean>;
  switchImpersonatingCustomer(customerId: string | null): Promise<UserData | null>;
  refreshGlobalData(): Promise<UserData | null>;
  getActiveCustomerVerificationToken(): Promise<string | null>;
  setActiveCompanySection(sectionId: string): Promise<boolean>;
  getProduct(parentProductId: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
  getVariant(parentProductId: string, variantSku: string): Promise<ProductVariant>;
  getPriceForProduct(parentProductId: string): Promise<SimplifiedProductPrice>;
  getPricingForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{
    price: number | null;
    rrp: number | null;
    rrpCurrencyCode: string | null;
    priceBreaks: VariantPriceBreak[];
    currencyCode: string;
  }>;
  getRrpPriceForVariant(
    parentProductId: string,
    variantSku: string,
  ): Promise<{ rrp: number | null; currencyCode: string | null }>;
  getPackSizeForVariant(parentProductId: string, variantSku: string): Promise<number>;
  calculatePricingForVariant(
    parentProductId: string,
    variantSku: string,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): Promise<ProductVariantPricing>;
  calculatePricingForVariantData(
    variant: ProductVariantDataPricing,
    qty: number,
    qtyAcrossVariants?: number | null,
  ): ProductVariantPricing;
  getCart(): Promise<Cart | null>;
  getCartCache(): Cart | null;
  updateCart(
    input: Partial<UpdateCart>,
    cartSuccessHandledLocally?: boolean,
    cartErrorsHandledLocally?: boolean,
  ): Promise<CartResults[] | null>;
  addCustomLineItem(customItem: CustomLineItemInput): Promise<Cart | null>;
  externalClearBasket(): Promise<void>;
  openDrawer(initialTab?: DrawerUIState): void;
  closeDrawer(): void;
  uploadFile(fileName: string, fileData: Blob): Promise<string>;
  fetch<Q extends GraphqlQueryOrMutation<unknown, Record<string, unknown>, GraphqlError | GraphqlExtensionError>>(
    query: Q,
    variables?: VariablesOf<Q>,
    useImpersonatingCustomer?: boolean,
    bypassAppProxy?: boolean,
    signal?: AbortSignal,
  ): Promise<FetchResponse<ResponseOf<Q>, ErrorOf<Q>>>;
};

type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};

type Translations = Record<string, Record<string, string>>;

type UpdateCart = {
  clearCart?: boolean;
  products?: CartItemInput[];
  deliveryAddressId?: string;
  customerReference?: string;
  poNumber?: string;
  shippingRequestedDate?: string;
  customFields?: { name: string; value: string }[];
  cartIntent?: string;
};

type UserData = {
  id: string;
  email: string;
  name: string;
  companyName: string | null;
  customerVerificationToken: string | null;
  salesAgent: boolean;
  parentAccount: { id: string; name: string; email: string } | null;
  companySections: { id: string; name: string }[];
};

type VariablesOf<Q> = Q extends { readonly __graphqlTypes?: { variables: infer TVariables } }
  ? TVariables
  : Record<string, unknown>;

type VariantPrice = {
  taxRate: number;
  net: number;
  gross: number;
  currencyCode: string;
  taxInclusiveDisplay: boolean; // If true, show gross; otherwise net
};

type VariantPriceBreak = {
  quantity: number;
  price: VariantPrice;
  unitOfMeasure: string | null;
};