@goldenhippo/builder-cart-schemas 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,22 @@
 # @goldenhippo/builder-cart-schemas
 
-Shared TypeScript types and Builder.io model definitions for Golden Hippo's cart/commerce Builder.io integration. This package provides factory functions for creating Builder.io content models and corresponding TypeScript content types for consuming model data.
+Builder.io model definitions and TypeScript content types for Golden Hippo's cart/commerce integration. Provides factory functions for creating Builder.io content models and strongly-typed interfaces for consuming model data.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Using Content Types](#using-content-types)
+  - [Fetching typed content in Angular](#fetching-typed-content-in-angular)
+  - [Working with page types](#working-with-page-types)
+  - [Using core types](#using-core-types)
+- [Exports](#exports)
+- [Models](#models)
+  - [Data Models](#data-models)
+  - [Page Models](#page-models)
+  - [Section Models](#section-models)
+- [Creating Model Definitions](#creating-model-definitions)
+- [Model Dependencies](#model-dependencies)
+- [Development](#development)
 
 ## Installation
 
@@ -8,6 +24,94 @@ Shared TypeScript types and Builder.io model definitions for Golden Hippo's cart
 npm install @goldenhippo/builder-cart-schemas
 ```
 
+## Using Content Types
+
+Content types represent the shape of data returned from Builder.io's Content API. Use them to get type-safe access to model fields when fetching content.
+
+### Fetching typed content in Angular
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { fetchOneEntry, fetchEntries } from '@builder.io/sdk-angular';
+import type { BuilderProductContent, BuilderBlogCategoryContent } from '@goldenhippo/builder-cart-schemas';
+import type { BuilderPageContent } from '@goldenhippo/builder-cart-schemas/page';
+
+@Component({ selector: 'app-product', templateUrl: './product.component.html' })
+export class ProductComponent implements OnInit {
+  product: BuilderProductContent | null = null;
+
+  async ngOnInit() {
+    const result = await fetchOneEntry({
+      model: 'product',
+      apiKey: environment.builderApiKey,
+      query: { 'data.gh.slug': 'example-product' },
+    });
+
+    this.product = result as BuilderProductContent;
+  }
+
+  get displayName(): string {
+    return this.product?.data?.displayName ?? '';
+  }
+
+  get featuredImage(): string {
+    return this.product?.data?.featuredImage ?? '';
+  }
+
+  get averageRating(): number {
+    return this.product?.data?.reviews?.averageRating ?? 0;
+  }
+}
+```
+
+```typescript
+// Fetching multiple entries
+const categories = (await fetchEntries({
+  model: 'blog-category',
+  apiKey: environment.builderApiKey,
+})) as BuilderBlogCategoryContent[];
+
+categories.forEach((cat) => {
+  console.log(cat?.data?.name, cat?.data?.displayName);
+});
+```
+
+### Working with page types
+
+Page content uses a discriminated union based on `pageType`. TypeScript narrows the type automatically:
+
+```typescript
+import type {
+  BuilderPageContent,
+  BuilderPdpPageContent,
+  BuilderBlogPageContent,
+} from '@goldenhippo/builder-cart-schemas/page';
+
+function renderPage(page: BuilderPageContent) {
+  const pageType = page?.data?.pageType;
+
+  if (pageType === 'Product') {
+    const pdp = page as BuilderPdpPageContent;
+    console.log(pdp?.data?.pdp?.product?.name);
+    console.log(pdp?.data?.pdp?.offerSelector?.osType);
+  }
+
+  if (pageType === 'Blog') {
+    const blog = page as BuilderBlogPageContent;
+    console.log(blog?.data?.blog?.author);
+    console.log(blog?.data?.blog?.publicationDate);
+  }
+}
+```
+
+### Using core types
+
+Core types like `ModelShape` and `BuilderIOFieldTypes` are available from the `@goldenhippo/builder-types` package:
+
+```typescript
+import type { ModelShape, BuilderIOFieldTypes } from '@goldenhippo/builder-types';
+```
+
 ## Exports
 
 The package provides multiple entry points for granular imports:
@@ -19,8 +123,6 @@ The package provides multiple entry points for granular imports:
 | `@goldenhippo/builder-cart-schemas/page`    | Page model creator and content types               |
 | `@goldenhippo/builder-cart-schemas/section` | Section/component model creators and content types |
 
-Core types (`ModelShape`, `BuilderIOFieldTypes`, etc.) are available from `@goldenhippo/builder-types`.
-
 ## Models
 
 ### Data Models
@@ -28,6 +130,7 @@ Core types (`ModelShape`, `BuilderIOFieldTypes`, etc.) are available from `@gold
 | Model                     | Creator                                                    | Content Type                           |
 | ------------------------- | ---------------------------------------------------------- | -------------------------------------- |
 | Product                   | `createProductModel(props)`                                | `BuilderProductContent`                |
+| Product Group             | `createProductGroupModel(props)`                           | `BuilderProductGroupContent`           |
 | Product Category          | `createCategoryModel()`                                    | `BuilderProductCategoryContent`        |
 | Product Tag               | `createProductTagModel()`                                  | `BuilderProductTagContent`             |
 | Product Ingredient        | `createIngredientsModel()`                                 | `BuilderIngredientContent`             |
@@ -50,9 +153,7 @@ Core types (`ModelShape`, `BuilderIOFieldTypes`, etc.) are available from `@gold
 | Site Banner             | `createSiteBannerModel(editUrl)`            | `BuilderSiteBannerModelContent`       |
 | Default Website Section | `createDefaultWebsiteSectionModel(editUrl)` | `BuilderDefaultWebsiteSectionContent` |
 
-## Usage
-
-### Creating model definitions
+## Creating Model Definitions
 
 Model creators return a `ModelShape` object suitable for registration with Builder.io's API. Some models require IDs of other models they reference.
 
@@ -81,32 +182,6 @@ const pageModel = createPageModel({
 });
 ```
 
-### Using content types
-
-Content types extend `BuilderContent` from `@builder.io/sdk` and represent the shape of data returned from Builder.io's Content API.
-
-```typescript
-import type { BuilderProductContent, BuilderPageContent } from '@goldenhippo/builder-cart-schemas';
-
-// Type-safe access to product content
-function getProductName(product: BuilderProductContent): string {
-  return product?.data?.displayName ?? product?.data?.name ?? '';
-}
-
-// Page content is a union type based on page type
-function handlePage(page: BuilderPageContent) {
-  if (page?.data?.pageType === 'Product') {
-    // TypeScript narrows to BuilderPdpPageContent
-  }
-}
-```
-
-### Using core types
-
-```typescript
-import type { ModelShape, BuilderIOFieldTypes } from '@goldenhippo/builder-types';
-```
-
 ## Model Dependencies
 
 Models that reference other models require their Builder.io model IDs at creation time:
@@ -130,12 +205,3 @@ npm run typecheck    # Type-check with tsc
 npm run test         # Run tests with vitest
 npm run lint         # Lint with eslint
 ```
-
-## Build Output
-
-Built with [tsup](https://tsup.egoist.dev/) producing:
-
-- **CJS** (`.cjs`) — CommonJS for Node.js / legacy bundlers
-- **ESM** (`.js`) — ES modules for modern bundlers
-- **Declarations** (`.d.ts`, `.d.cts`) — TypeScript type definitions
-- **Source maps** (`.map`) — for debugging

package/dist/data/index.d.mts

@@ -1,5 +1,6 @@
-import { BuilderResponseBaseData, ModelShape } from '@goldenhippo/builder-types';
+import { BuilderResponseBaseData, ModelShape, BuilderContentReference } from '@goldenhippo/builder-types';
 import { BuilderContent } from '@builder.io/sdk';
+import { BuilderBlogPageContent } from '../page/index.mjs';
 
 declare enum HeaderType {
     BASIC = "BASIC",
@@ -76,6 +77,94 @@ declare enum SubscriptionCancelButtonType {
     Cancel = "cancel"
 }
 
+declare const createCategoryModel: () => ModelShape;
+type BuilderProductCategoryContent = BuilderContent & Partial<{
+    data: BuilderResponseBaseData & {
+        name: string;
+        description?: string;
+        desktopImage?: string;
+        mobileImage?: string;
+        hidden?: boolean;
+        slug?: string;
+        searchKeys?: string[];
+    };
+}>;
+
+declare const createIngredientsModel: () => ModelShape;
+type BuilderIngredientContent = BuilderContent & Partial<{
+    data: BuilderResponseBaseData & {
+        name: string;
+        description?: string;
+        image?: string;
+        shortDescription?: string;
+        searchKeys?: string[];
+    };
+}>;
+
+declare const createProductUseCaseModel: () => ModelShape;
+type BuilderProductUseCaseContent = BuilderContent & Partial<{
+    data: BuilderResponseBaseData & {
+        name: string;
+        description?: string;
+        searchKeys?: string[];
+        image?: string;
+        hidden?: boolean;
+    };
+}>;
+
+declare const createProductTagModel: () => ModelShape;
+type BuilderProductTagContent = BuilderContent & Partial<{
+    data: BuilderResponseBaseData & {
+        name: string;
+        tagColor: string;
+        hidden?: boolean;
+        image?: string;
+        pluralDisplayName?: string;
+    };
+}>;
+
+interface ProductFilterModels {
+    categoryId: string;
+    useCaseId: string;
+    ingredientId: string;
+    tagId: string;
+}
+declare enum FilterApplicationType {
+    Inclusive = "Inclusive",
+    Exclusive = "Exclusive"
+}
+declare const createProductGridConfigModel: (models: ProductFilterModels) => ModelShape;
+type BuilderProductGridFilterGroupContent = BuilderContent & Partial<{
+    data: BuilderResponseBaseData & {
+        displayName: string;
+        categories: {
+            category: {
+                id: string;
+                value: BuilderContentReference<BuilderProductCategoryContent>;
+            };
+        }[];
+        ingredients: {
+            ingredient: {
+                id: string;
+                value: BuilderContentReference<BuilderIngredientContent>;
+            };
+        }[];
+        useCases: {
+            useCase: {
+                id: string;
+                value: BuilderContentReference<BuilderProductUseCaseContent>;
+            };
+        }[];
+        tags: {
+            tag: {
+                id: string;
+                value: BuilderContentReference<BuilderProductTagContent>;
+            };
+        }[];
+        filterApplicationType: FilterApplicationType;
+    };
+}>;
+
 declare const createBrandConfigModel: (gridFilterModelId: string, bannerModelId: string) => ModelShape;
 type BuilderBrandConfigContent = BuilderContent & Partial<{
     data: BuilderResponseBaseData & {
@@ -106,7 +195,7 @@ type BuilderBrandConfigContent = BuilderContent & Partial<{
         banners: {
             banner: {
                 id: string;
-                name: string;
+                value: BuilderContentReference<BuilderContent>;
             };
             alwaysShow: boolean;
         }[];
@@ -251,6 +340,7 @@ type BuilderBrandConfigContent = BuilderContent & Partial<{
             productGridFilterGroups: {
                 filterConfig: {
                     id: string;
+                    value: BuilderContentReference<BuilderProductGridFilterGroupContent>;
                 };
             }[];
             productGridHideRestricted: boolean;
@@ -422,6 +512,7 @@ type BuilderBlogCommentContent = BuilderContent & Partial<{
         blog: {
             id: string;
             name: string;
+            value: BuilderContentReference<BuilderBlogPageContent>;
         };
     };
 }>;
@@ -459,26 +550,26 @@ type BuilderProductContent = BuilderContent & Partial<{
         };
         tags?: {
             tag: {
-                name: string;
-                displayName: string;
+                id: string;
+                value: BuilderContentReference<BuilderProductTagContent>;
             };
         }[];
         categories?: {
             category: {
-                name: string;
-                displayName: string;
+                id: string;
+                value: BuilderContentReference<BuilderProductCategoryContent>;
             };
         }[];
         ingredients?: {
             ingredient: {
-                name: string;
-                displayName: string;
+                id: string;
+                value: BuilderContentReference<BuilderIngredientContent>;
             };
         }[];
         useCases?: {
             useCase: {
-                name: string;
-                displayName: string;
+                id: string;
+                value: BuilderContentReference<BuilderProductUseCaseContent>;
             };
         }[];
         gh: {
@@ -502,7 +593,10 @@ type BuilderProductGroupContent = BuilderContent & Partial<{
         gridTagline?: string;
         shortDescription?: string;
         products: {
-            product: string;
+            product: {
+                id: string;
+                value: BuilderContentReference<BuilderProductContent>;
+            };
             displayName?: string;
             isTrialSize?: boolean;
         }[];
@@ -517,88 +611,4 @@ type BuilderProductGroupContent = BuilderContent & Partial<{
     };
 }>;
 
-declare const createCategoryModel: () => ModelShape;
-type BuilderProductCategoryContent = BuilderContent & Partial<{
-    data: BuilderResponseBaseData & {
-        name: string;
-        description?: string;
-        desktopImage?: string;
-        mobileImage?: string;
-        hidden?: boolean;
-        slug?: string;
-        searchKeys?: string[];
-    };
-}>;
-
-interface ProductFilterModels {
-    categoryId: string;
-    useCaseId: string;
-    ingredientId: string;
-    tagId: string;
-}
-declare enum FilterApplicationType {
-    Inclusive = "Inclusive",
-    Exclusive = "Exclusive"
-}
-declare const createProductGridConfigModel: (models: ProductFilterModels) => ModelShape;
-type BuilderProductGridFilterGroupContent = BuilderContent & Partial<{
-    data: BuilderResponseBaseData & {
-        displayName: string;
-        categories: {
-            category: {
-                id: string;
-            } & Record<string, any>;
-        }[];
-        ingredients: {
-            ingredient: {
-                id: string;
-            } & Record<string, any>;
-        }[];
-        useCases: {
-            useCase: {
-                id: string;
-            } & Record<string, any>;
-        }[];
-        tags: {
-            tag: {
-                id: string;
-            } & Record<string, any>;
-        }[];
-        filterApplicationType: FilterApplicationType;
-    };
-}>;
-
-declare const createIngredientsModel: () => ModelShape;
-type BuilderIngredientContent = BuilderContent & Partial<{
-    data: BuilderResponseBaseData & {
-        name: string;
-        description?: string;
-        image?: string;
-        shortDescription?: string;
-        searchKeys?: string[];
-    };
-}>;
-
-declare const createProductTagModel: () => ModelShape;
-type BuilderProductTagContent = BuilderContent & Partial<{
-    data: BuilderResponseBaseData & {
-        name: string;
-        tagColor: string;
-        hidden?: boolean;
-        image?: string;
-        pluralDisplayName?: string;
-    };
-}>;
-
-declare const createProductUseCaseModel: () => ModelShape;
-type BuilderProductUseCaseContent = BuilderContent & Partial<{
-    data: BuilderResponseBaseData & {
-        name: string;
-        description?: string;
-        searchKeys?: string[];
-        image?: string;
-        hidden?: boolean;
-    };
-}>;
-
 export { type BuilderBlogCategoryContent, type BuilderBlogCommentContent, type BuilderBrandConfigContent, type BuilderIngredientContent, type BuilderProductCategoryContent, type BuilderProductContent, type BuilderProductGridFilterGroupContent, type BuilderProductGroupContent, type BuilderProductTagContent, type BuilderProductUseCaseContent, createBlogCategoryModel, createBlogCommentModel, createBrandConfigModel, createCategoryModel, createIngredientsModel, createProductGridConfigModel, createProductGroupModel, createProductModel, createProductTagModel, createProductUseCaseModel };