feat(examples): feed export

Author: matoous

README.md

@@ -14,15 +14,17 @@ This repo bootstraps Go support for the [Agentic Commerce Protocol](https://deve
 
 - **Checkout API** — plug your own business logic into `NewCheckoutHandler` by implementing `CheckoutSessionService`. The handler exposes the official ACP checkout contract over `net/http`, supports optional signature verification and timestamp skew enforcement, and emits typed responses generated from the OpenAPI spec.
 - **Delegated Payment API** — payment service providers implement `DelegatedPaymentProvider` and wire it up via `NewDelegatedPaymentHandler` (optionally adding `DelegatedPaymentWithAuthenticator` and signature enforcement) to tokenize credentials and emit delegated vault tokens.
+- **Product Feed** - helper for building and exporting a [product feed](https://developers.openai.com/commerce/specs/feed).
 
-## Example Servers
+## Examples
 
-Two runnable samples live under [`examples`](examples):
+Three runnable samples live under [`examples`](examples):
 
 - [`examples/checkout`](examples/checkout) implements `CheckoutSessionService` with an in-memory catalog and session store.
 - [`examples/delegated_payment`](examples/delegated_payment) implements `DelegatedPaymentProvider` with an in-memory vault token map.
+- [`examples/feed`](examples/feed) builds and exports a product feed in JSONL and CSV formats.
 
-### Checkout sample
+### Checkout Sample
 
 ```bash
 go run ./examples/checkout
@@ -67,7 +69,7 @@ export ACP_WEBHOOK_SECRET="super-secret"
 go run ./examples/checkout
 ```
 
-### Delegated payment sample
+### Delegated Payment Sample
 
 ```bash
 go run ./examples/delegated_payment
@@ -104,6 +106,14 @@ curl -sS -X POST http://localhost:8080/agentic_commerce/delegate_payment \
       }'
 ```
 
+### Product Feed Sample
+
+```bash
+go run ./examples/feed
+```
+
+This writes compressed feed exports to `examples/feed/output/product_feed.jsonl.gz` and `examples/feed/output/product_feed.csv.gz`.
+
 ## License
 
 [Apache 2.0](/LICENSE)

examples/feed/feed.go

@@ -0,0 +1,133 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/sumup/acp/feed"
+)
+
+func main() {
+	products := sampleProducts()
+	productFeed := feed.New(products)
+
+	outDir := filepath.Join("examples", "feed", "output")
+	if err := os.MkdirAll(outDir, 0o755); err != nil {
+		log.Fatalf("create output directory: %v", err)
+	}
+
+	jsonlPath := filepath.Join(outDir, "product_feed.jsonl.gz")
+	if err := writeJSONL(productFeed, jsonlPath); err != nil {
+		log.Fatalf("write jsonl feed: %v", err)
+	}
+
+	csvPath := filepath.Join(outDir, "product_feed.csv.gz")
+	if err := writeCSV(productFeed, csvPath); err != nil {
+		log.Fatalf("write csv feed: %v", err)
+	}
+
+	log.Printf("wrote %s", jsonlPath)
+	log.Printf("wrote %s", csvPath)
+}
+
+func writeJSONL(productFeed feed.Feed, path string) error {
+	file, err := os.Create(path)
+	if err != nil {
+		return fmt.Errorf("create file: %w", err)
+	}
+	defer func() {
+		_ = file.Close()
+	}()
+
+	return productFeed.WriteJSONLGz(file)
+}
+
+func writeCSV(productFeed feed.Feed, path string) error {
+	file, err := os.Create(path)
+	if err != nil {
+		return fmt.Errorf("create file: %w", err)
+	}
+	defer func() {
+		_ = file.Close()
+	}()
+
+	return productFeed.WriteCSVGz(file)
+}
+
+func sampleProducts() []feed.Product {
+	return []feed.Product{
+		{
+			EnableSearch:      true,
+			EnableCheckout:    true,
+			ID:                "sku_latte_12oz",
+			Title:             "Oat Milk Latte (12oz)",
+			Description:       "Smooth espresso with steamed oat milk.",
+			Link:              "https://store.example.com/products/sku_latte_12oz",
+			ProductCategory:   "Food, Beverages & Tobacco > Beverages > Coffee",
+			ImageLink:         "https://store.example.com/images/sku_latte_12oz.jpg",
+			Price:             "6.50 USD",
+			Availability:      "in_stock",
+			SellerName:        "Example Roasters",
+			SellerURL:         "https://store.example.com",
+			InventoryQuantity: intPtr(120),
+			Shipping: []string{
+				"US:CA:Ground:5.00 USD",
+				"US:NY:Ground:6.00 USD",
+			},
+			PickupMethod: "in_store",
+			PickupSLA:    "1 day",
+		},
+		{
+			EnableSearch:    true,
+			EnableCheckout:  true,
+			ID:              "sku_mug_slate",
+			Title:           "Stoneware Mug (Slate)",
+			Description:     "12oz stoneware mug with matte finish.",
+			Link:            "https://store.example.com/products/sku_mug_slate",
+			ProductCategory: "Home & Garden > Kitchen & Dining > Drinkware",
+			ImageLink:       "https://store.example.com/images/sku_mug_slate.jpg",
+			AdditionalImageLink: []string{
+				"https://store.example.com/images/sku_mug_slate_alt1.jpg",
+				"https://store.example.com/images/sku_mug_slate_alt2.jpg",
+			},
+			Price:        "15.00 USD",
+			SalePrice:    "12.00 USD",
+			Availability: "in_stock",
+			Condition:    feed.ProductConditionNew,
+			Brand:        "Example Roasters",
+			Material:     "Stoneware",
+			Dimensions:   "4x4x4 in",
+			Shipping: []string{
+				"US:::7.00 USD",
+			},
+			SellerName: "Example Roasters",
+			SellerURL:  "https://store.example.com",
+		},
+		{
+			EnableSearch:    true,
+			EnableCheckout:  true,
+			ID:              "sku_shirt_black_s",
+			Title:           "Logo T-Shirt (Black, S)",
+			Description:     "Soft cotton tee with embroidered logo.",
+			Link:            "https://store.example.com/products/sku_shirt_black_s",
+			ProductCategory: "Apparel & Accessories > Clothing",
+			ImageLink:       "https://store.example.com/images/sku_shirt_black.jpg",
+			Price:           "24.00 USD",
+			Availability:    "in_stock",
+			ItemGroupID:     "sku_shirt_black",
+			ItemGroupTitle:  "Logo T-Shirt (Black)",
+			Color:           "Black",
+			Size:            "S",
+			SizeSystem:      "US",
+			Gender:          "unisex",
+			SellerName:      "Example Roasters",
+			SellerURL:       "https://store.example.com",
+		},
+	}
+}
+
+func intPtr(v int) *int {
+	return &v
+}

feed/csv.go

@@ -102,7 +102,7 @@ func (p Product) csvRecord() []string {
 		p.Width,
 		p.Height,
 		p.Weight,
-		p.AgeGroup,
+		string(p.AgeGroup),
 		p.ImageLink,
 		joinStrings(p.AdditionalImageLink),
 		p.VideoLink,

feed/feed.go

@@ -22,6 +22,17 @@ const (
 	ProductConditionUsed        ProductCondition = "used"
 )
 
+// ProductAgeGroup is the target demographic of the product.
+type ProductAgeGroup string
+
+const (
+	ProductAgeGroupNewborn ProductAgeGroup = "newborn"
+	ProductAgeGroupInfant  ProductAgeGroup = "infant"
+	ProductAgeGroupToddler ProductAgeGroup = "toddler"
+	ProductAgeGroupKids    ProductAgeGroup = "kids"
+	ProductAgeGroupAdult   ProductAgeGroup = "adult"
+)
+
 // Product describes a single product entry in an ACP product feed.
 // Field names follow the feed specification for JSONL and CSV export.
 type Product struct {
@@ -86,7 +97,7 @@ type Product struct {
 	// Weight is the product weight with a unit.
 	Weight string `json:"weight,omitempty" csv:"weight"`
 	// AgeGroup is the target demographic such as newborn, infant, toddler, kids, or adult.
-	AgeGroup string `json:"age_group,omitempty" csv:"age_group"`
+	AgeGroup ProductAgeGroup `json:"age_group,omitempty" csv:"age_group"`
 
 	// Media
 	//

feed/feed_test.go

@@ -59,7 +59,7 @@ func gunzipBytes(data []byte) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer reader.Close()
+	defer func() { _ = reader.Close() }()
 
 	return io.ReadAll(reader)
 }