@napps/component-extension contracts

These are the callback contracts used by native app extensions. Export the function or handler required by the selected extension page; the type definitions below describe the values passed to it and the mutations it may return. Async callbacks share the host’s extension timeout. Keep work bounded and return within the documented three-second budget. A timed-out or rejected promise is treated as a failed callback and native behavior continues according to the extension contract.

Product listing formatter

type ProductListingBaseDataEditor = {
  readonly product: Product;
  setVisible(isVisible: boolean): void;
  isVisible(): boolean;
  setVendor(vendor?: string): void;
  setStampImage(url?: string): void;
  getTags(): ProductTag[];
  replaceTags(input: ProductTag[]): void;
  addTag(input: ProductTag): void;
  removeTag(input: ProductTag): void;
  removeTagByType(type: string): void;
  clearTags(): void;
};

export function formatProducts(
  products: ProductListingBaseDataEditor[]
): void | Promise<void>;

The editor is mutable for the duration of the callback. Make formatting idempotent because the same listing can be formatted more than once.

Collection filters

interface CollectionProductsFiltersContext {
  readonly collection: CollectionProductsCollectionInfo;
  readonly trigger: CollectionProductsFiltersTrigger;
  readonly filters: CollectionProductsFiltersEditor;
}

interface CollectionProductsFiltersEditor {
  readonly available: AvailableCollectionProductsFilters;
  hideFilterById(filterId: string): boolean;
  hideFilterByLabel(filterLabel: string): boolean;
  showFilterById(filterId: string): boolean;
  showFilterByLabel(filterLabel: string): boolean;
  isFilterHiddenById(filterId: string): boolean;
  isFilterHiddenByLabel(filterLabel: string): boolean;
  renameFilterById(filterId: string, title: string): boolean;
  renameFilterByLabel(filterLabel: string, title: string): boolean;
  clearFilterRenameById(filterId: string): boolean;
  clearFilterRenameByLabel(filterLabel: string): boolean;
  renameValueById(filterId: string, value: string, label: string): boolean;
  renameValueByLabel(filterLabel: string, value: string, label: string): boolean;
  addValueById(filterId: string, value: string): boolean;
  addValueByLabel(filterLabel: string, value: string): boolean;
  removeValueById(filterId: string, value: string): boolean;
  removeValueByLabel(filterLabel: string, value: string): boolean;
  clearById(filterId: string): boolean;
  clearByLabel(filterLabel: string): boolean;
  hasValueById(filterId: string, value: string): boolean;
  hasValueByLabel(filterLabel: string, value: string): boolean;
  setPriceRange(min: number, max: number): void;
  clearPriceRange(): void;
  setOrder(order: FilterOrder): boolean;
  clearOrder(): boolean;
}

export function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
): void | Promise<void>;

trigger is either "Initial" or "UserFiltersChanged". The callback can change the editor before the product query runs. Boolean mutators return false when the requested filter or value does not exist.

Product detail handler

interface ProductDetailHandler {
  onFormat?(draft: ProductDetailInfoState): void | Promise<void>;
  onDestroyed?(): void | Promise<void>;
  onVariantSelected?(): void;
  onVariantsAvailability?(
    event: ProductDetailEventArgs<VariantsAvailabilityEventArgs>
  ): void | Promise<void>;
  onBeforeProductAddToCart?(
    event: ProductDetailEventArgs<OnBeforeAddToCartEventArgs>
  ): boolean | Promise<boolean>;
  onProductSelected?(
    event: ProductDetailEventArgs<ProductVariantEventArgs>
  ): boolean | Promise<boolean>;
  onProductClicked?(
    event: ProductDetailEventArgs<ProductEventArgs>
  ): boolean | Promise<boolean>;
  onProductQuickAddClicked?(
    event: ProductDetailEventArgs<ProductEventArgs>
  ): boolean | Promise<boolean>;
  onAddedToCart?(
    event: ProductDetailEventArgs<ProductVariantEventArgs>
  ): boolean | Promise<boolean>;
  onExternalNavigationRequestClicked?(
    event: ProductDetailEventArgs<ExternalNavigationRequestEventArgs>
  ): boolean | Promise<boolean>;
  onCollectionClicked?(
    event: ProductDetailEventArgs<CollectionClickedEventArgs>
  ): boolean | Promise<boolean>;
  onVendorClicked?(
    event: ProductDetailEventArgs<VendorClickedEventArgs>
  ): boolean | Promise<boolean>;
}

interface ProductDetailEventArgs<T> {
  data: T;
}

Callbacks that support cancellation suppress the native action when they return false. There is no preventDefault() method on the event object. onAddedToCart and onProductSelected receive { product, productVariant }; onBeforeProductAddToCart is the callback whose payload uses { product, variant, quantity }.

PDP formatting and media tags

interface ProductDetailInfoState {
  readonly mediaItems: ProductMediaItem[];
  setTitle(title: string): void;
  setVendor(vendor?: string): void;
  setSku(sku?: string): void;
  setStampImage(url?: string): void;
  clearLowStockInfo(): void;
  getTags(): ProductTag[];
  addTag(input: ProductTag): void;
  removeTag(input: ProductTag): void;
  removeTagByType(type: string): void;
  replaceTags(input: ProductTag[]): void;
  clearTags(): void;
  getMediaTags(mediaID: string): MediaTag[];
  addMediaTag(mediaID: string, tag: MediaTag): void;
  setMediaTags(mediaID: string, tags: MediaTag[]): void;
  removeMediaTag(mediaID: string, tagID: string): void;
  clearMediaTags(mediaID: string): void;
  clearAllMediaTags(): void;
}

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

Media is native-owned: handlers can inspect the gallery and manage tags, but cannot reorder or add media. A tag with the same ID on one media item is replaced. A tag must provide text, an icon, or both.

Cart operations

interface CartOperations {
  addLineItem(
    merchandiseID: string,
    attributes: Record<string, string>,
    quantity: number,
    sellingPlanID?: string,
    parentLineItemID?: string,
    parentMerchandiseID?: string
  ): CartOperation;
  removeLineItem(lineItemID: string): CartOperation;
  updateLineItem(
    lineItemID: string,
    attributes?: Record<string, string>,
    merchandiseID?: string,
    quantity?: number,
    sellingPlanID?: string
  ): CartOperation;
  updateCartAttributes(attributes: Record<string, string>): CartOperation;
  setMetaField(key: string, type: string, value: string): CartOperation;
  deleteMetaField(key: string): CartOperation;
  updateNotes(notes: string): CartOperation;
}

interface CartOperation {}

Use the returned operations from the cart extension. Operations are applied by the native runner; do not mutate a CartOperation after returning it.

Cart line-item formatter

interface CartLineItemsFormatterContext {
  readonly checkout: Cart;
  readonly lineItems: CartLineItemDataEditor[];
  addInfoBanner(banner: CartInfoBanner): void;
  removeInfoBanner(id: string): void;
  clearInfoBanners(): void;
  setCheckoutEnabled(enabled: boolean): void;
}

interface CartLineItemDataEditor {
  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 properties: Record<string, string>;
  readonly totalAmount: number;
  readonly subtotalAmount: number;
  setName(name: string): void;
  setImageUrl(url?: string): void;
  setQuantityEditable(editable: boolean): void;
  addExtraInfo(info: CartLineItemExtraInfo): void;
  replaceExtraInfos(infos: CartLineItemExtraInfo[]): void;
  clearExtraInfos(): void;
}

The formatter may change presentation and checkout availability. The line item’s product and variant references can be null when the underlying catalog object no longer exists.

Product-card bridge

Product-card modules receive their products through ComponentContext.cards.

interface ProductCardsBridge {
  readonly surface: string;
  subscribe(callback: (payload: ProductCardsPayload) => void): void;
}

type ProductCardsPayload = {
  op?: "append" | "reset" | "slide";
  dropLeading?: number;
  products: ProductCardItem[];
  loadingCount: number;
};

interface ProductCardItem {
  id: string;
  title: string;
  vendor: string;
  imageUrl: string;
  formattedPrice: string;
  formattedCompareAtPrice: string;
  hasDiscount: boolean;
  discountPercentage: number;
  isAvailable: boolean;
  isWishListed: boolean;
  stampImageUrl: string;
}

The bridge invokes the subscriber immediately and keeps only the latest subscriber. Render one root child per slot, with real products first and loading placeholders last.

Reference overview

@napps/nodes