@goldenhippo/builder-cart-schemas 0.1.0 → 0.2.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goldenhippo/builder-cart-schemas",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared Zod schemas, TypeScript types, and utilities for Golden Hippo Builder.io models",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",