@napps/component-extension models

These shared models are used by services and extension callbacks. Properties marked readonly are snapshots supplied by the host; use the methods on an editor or draft when a model is editable.

Products and variants

interface Product {
  readonly id: string;
  readonly name: string;
  readonly vendor: string;
  readonly handle: string;
  readonly collectionIDs: string[];
  readonly tags: string[];
  readonly discountPercentage: number;
  readonly thumbnail?: string | null;
  metaFields(keys: string[]): MetaFieldsByNamespace;
  getMetaFields(keys: string[]): Promise<MetaFieldsByNamespace>;
}

interface ProductVariant {
  readonly id: string;
  readonly stock: number;
  readonly price: number;
  readonly policy: ProductVariantPolicy;
  getMetaFields(keys: string[]): Promise<MetaFieldsByNamespace>;
}

type ProductVariantPolicy = "continue" | "deny";

Product meta-field keys use the namespace.key form. The result is grouped by namespace.

type MetaFieldsByNamespace = Record<string, Record<string, MetaFieldValue>>;

type MetaFieldValue =
  | boolean
  | number
  | bigint
  | string
  | Date
  | string[]
  | MetaFieldMedia[]
  | MetaObject
  | MetaObject[]
  | null;

interface MetaFieldMedia {
  url: string;
  previewUrl: string | null;
  width: number | null;
  height: number | null;
  mimeType: string | null;
  aspectRatio?: number;
}

interface MetaObject {
  id: string;
  type: string;
  handle: string;
  fields: Record<string, MetaFieldValue>;
}

Product tags

declare class ProductTag {
  constructor(
    type: string,
    labelText: string,
    labelTextColor: string,
    labelBackgroundColor: string
  );
  type: string;
  labelText: string;
  labelTextColor: string;
  labelBackgroundColor: string;
}

The host provides the constructor. Import ProductTag as a type where your TypeScript settings require it, and construct it through the runtime-provided value.

Cart

interface Cart {
  readonly lineItems: CartLineItem[];
  readonly attributes: Record<string, string>;
  readonly currency: string;
  readonly note: string;
  readonly subtotalAmount: number;
  readonly totalAmount: number;
  readonly totalDiscount: number;
  readonly checkoutChargeAmount: number;
  readonly itemsSubTotalAmount: number;
  readonly itemCount: number;
  getTotalWeight(unit?: WeightUnit): CartTotalWeight;
}

interface CartLineItem {
  readonly id: string;
  readonly quantity: number;
  readonly productID: string;
  readonly product?: Product | null;
  readonly variantID: string;
  readonly variant?: ProductVariant | null;
  readonly attributes: Record<string, string>;
  readonly totalAmount: number;
  readonly subtotalAmount: number;
  readonly properties: Record<string, string>;
  readonly requiresShipping: boolean;
  readonly weight: number;
  readonly weightUnit: WeightUnit;
}

interface CartOperation {}

type WeightUnit = "Kilograms" | "Grams" | "Pounds" | "Ounces";

interface CartTotalWeight {
  unit: WeightUnit;
  value: number;
}

Collections and filters

interface Collection {
  readonly id: string;
  readonly title: string;
  readonly description: string;
  readonly url: string;
  readonly metafields: MetaFieldsByNamespace;
}

interface CollectionProductsCollectionInfo {
  readonly id: string;
  readonly title: string;
}

type CollectionProductsFiltersTrigger = "Initial" | "UserFiltersChanged";
type FilterType = "LIST" | "SINGLE_SELECTION_LIST" | "ORDERING" | "PRICE_RANGE";

Metaobject pagination

interface MetaObjectsPage {
  items: MetaObject[];
  endCursor?: string | null;
  hasNextPage: boolean;
}

Use hasNextPage and endCursor with getMetaObjectsByType. The unbounded getAllMetaObjectsByType method is available when the shop’s dataset is known to be small.

PDP media

interface ProductMediaItem {
  id: string;
  alt: string;
  contentType: string;
  previewImageUrl?: string | null;
  type: string;
}

interface MediaTag {
  id: string;
  text?: string | null;
  textColor?: string | null;
  backgroundColor?: string | null;
  iconUrl?: string | null;
  iconColor?: string | null;
}

ProductMediaItem.type is normally "image", "video", "external_video", or "model3d". Media tags are keyed by id per media item and support text, an icon, or both.

GraphQL response envelope

interface GraphQLResponse<T> {
  data: T;
  extensions: object | undefined;
  errors: object[] | undefined;
}

Check errors even when the promise resolves. A resolved promise means the request completed; it does not guarantee that the GraphQL operation had no errors.

Reference overview

@napps/nodes