> ## Documentation Index
> Fetch the complete documentation index at: https://docs.napps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# @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

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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.