diff --git a/generator/catalog-ingestion-openapi-spec.yaml b/generator/catalog-ingestion-openapi-spec.yaml index 3ac9653..ebcf441 100644 --- a/generator/catalog-ingestion-openapi-spec.yaml +++ b/generator/catalog-ingestion-openapi-spec.yaml @@ -10,10 +10,11 @@ info: This API provides the following resource collections to create and update catalog data: - [Metadata](#tag/Metadata)—define and manage product attribute metadata including display settings, search characteristics, filtering options, and sorting rules. - - [Categories](#tag/Categories)—define and manage categories with hierarchical structure to build navigation menu. - - [Products](#tag/Products)—define and manage catalog items with their attributes (name, description, SKU, images, and variants). - - [Price books](#tag/Price-Books)—define and manage pricing scopes for different customer tiers and markets. - - [Prices](#tag/Prices)—define and manage product SKU prices and their associated price books. + - [Categories](#tag/Categories)—Define and manage categories with hierarchical structure to build navigation menu. + - [Products](#tag/Products)—Define and manage catalog items with their attributes (name, description, SKU, images, and variants). + - [Price books](#tag/Price-Books)—Define and manage pricing scopes for different customer tiers and markets. + - [Prices](#tag/Prices)—Define and manage product SKU prices and their associated price books. + - [Product Layers](#tag/Product-Layers)—Define and manage product layers to customize and override base product data for specific contexts, locales, or business requirements. version: 1.0.0 servers: - url: https://na1-sandbox.api.commerce.adobe.com/{tenantId} @@ -42,6 +43,10 @@ tags: Categories use a slug-based hierarchy format to represent parent-child relationships, for example, "men/clothing/pants'. + After you create categories and assign them to products, you can retrieve category data to render storefront menus and manage hierarchical category + trees using the GraphQL `navigation` and `categorytree` queries. See + [Implement categories on the storefront](https://developer-stage.adobe.com/commerce/services/optimizer/merchandising-services/categories-v2/). + - name: Products description: Create and manage product data including simple products, configurable products, and their variants. Control product visibility, attributes, images, and pricing - name: Price Books @@ -1282,31 +1287,48 @@ paths: - Product Layers summary: Create or replace product layers description: | - You can create a product layer to merge and override a base product. - - When creating product layers: - - Each product layer requires a SKU identifier which matches to a base product. - - A product layer may have a defined catalog `source.locale`, and if absent is treated as a global layer for any locale. - - A product layer must have a defined catalog `source.layer`. - - All other fields are optional. If provided, they are used to override the base product. - - When merging array lists, the first array is merged with the base list. All other inner lists of the same object are treated as replace values. - For example `attributes` is merged with base list, but `attributes.values` is a replacement. - 
-           {
-             "sku": "pants-red-32",
-             "source": {
-               "locale": "en",
-               "layer": "custom-layer"
-             },
-             "attributes": [
-               {
-                 "code": "color",
-                 "values": ["Green", "Light Green"],
-                 "variantReferenceId": "pants-color-green"
-               }
-             ]
-           }
-
+ Create product layers to customize and override base product data for specific contexts, locales, or business requirements. + + Product layers enable you to: + - Override product attributes for specific markets or channels + - Provide locale-specific content while maintaining a global base product + - Create seasonal or promotional variations without duplicating entire product records + - Implement A/B testing scenarios with different product presentations + + ## Layer behavior and requirements + + **Required fields:** + - `sku`: Must match an existing base product SKU + - `source.layer`: Identifies the layer name for organization and retrieval + + **Optional Fields:** + - `source.locale`: When specified, layer applies only to that locale. When omitted, layer applies globally across all locales + - All product fields (name, description, images, and so on): Override corresponding base product values + + ## Merging logic + + Product layers use intelligent merging: + - **Simple fields** (name, description, and so on): Complete replacement of base values + - **Array fields** (attributes, images, etc.): First-level arrays are merged with base arrays + - **Nested arrays** (attribute.values, etc.): Complete replacement of nested arrays + + **Example:** Adding a color variant while preserving existing attributes: + ```json + { + "sku": "red-pants", + "source": { + "locale": "en-US", + "layer": "seasonal-colors" + }, + "attributes": [ + { + "code": "color", + "values": ["Crimson Red", "Deep Red"], + "variantReferenceId": "pants-color-crimson" + } + ] + } + ``` operationId: createProductLayers parameters: @@ -1333,29 +1355,29 @@ paths: $ref: "#/components/schemas/FeedProductLayer" examples: ProductLayerWithImages: - summary: Create a product layer + summary: Create a seasonal product layer description: > - Create a product layer with changes. + Create a product layer that overrides the base product with seasonal branding, + localized content, and updated imagery for the US market. value: [ { "sku": "red-pants", "source": { "locale": "en-US", - "layer": "custom-layer" + "layer": "seasonal-winter-2024" }, - "name": "red pants for my custom layer", - "description": "long description about red pants for my custom layer", - "shortDescription": "just pants for custom layer", - "images": - [ - { - "url": "https://example.com/images/pants.jpg", - "label": "photo of my pants for my custom layer", - "roles": ["BASE", "SMALL"], - "customRoles": ["widget"] - } - ] + "name": "Premium Red Winter Pants - Limited Edition", + "description": "Stay warm and stylish with our premium red winter pants. Features thermal lining and water-resistant fabric perfect for cold weather adventures.", + "shortDescription": "Premium thermal-lined winter pants in classic red", + "images": [ + { + "url": "https://cdn.example.com/products/red-pants-winter-2024.jpg", + "label": "Premium Red Winter Pants - Front View", + "roles": ["BASE", "THUMBNAIL"], + "customRoles": ["hero", "seasonal-banner"] + } + ] } ] /v1/catalog/products/layers/delete: @@ -1363,8 +1385,20 @@ paths: tags: - Product Layers summary: Delete product layers - description: > - Delete product layers with specified `sku` and `source` values + description: | + Remove specific product layers by SKU and source identifiers. This operation permanently deletes + the layer data while preserving the base product. + + **Use Cases:** + - Remove expired seasonal or promotional layers + - Clean up test layers after A/B testing completion + - Delete locale-specific layers when discontinuing market support + - Remove outdated customizations + + **Important Notes:** + - Only the specified layer is deleted; base product and other layers remain intact + - Both `sku` and `source` (locale + layer) must match exactly for successful deletion + operationId: deleteProductLayers parameters: - $ref: "#/components/parameters/Authorization" @@ -1389,17 +1423,18 @@ paths: items: $ref: "#/components/schemas/FeedProductLayerDelete" examples: - DeleteSimpleProduct: - summary: Delete product layer + DeleteSeasonalLayer: + summary: Delete seasonal product layer description: > - Delete a product layer with specified `sku` and `source` values + Delete a seasonal product layer after the promotion period ends, + reverting the product to its base configuration. value: [ { "sku": "red-pants", "source": { "locale": "en-US", - "layer": "custom-layer" + "layer": "seasonal-winter-2024" } } ] @@ -2614,63 +2649,63 @@ components: properties: sku: type: string - description: SKU (Stock Keeping Unit) is a unique identifier for a product. - example: MH01 + description: SKU (Stock Keeping Unit) that uniquely identifies the base product this layer will modify. Must match an existing product SKU in the catalog. + example: red-pants source: $ref: "#/components/schemas/SourceLayer" name: type: string - description: Product name - example: Kangaroo Hoodie + description: Product display name that will override the base product name. Use for localized names, seasonal branding, or promotional titles. + example: Premium Red Winter Pants - Limited Edition slug: type: string - description: The URL key for the product. - example: kangaroo-hoodie.html + description: URL-friendly identifier for the product page. Override to create layer-specific URLs for SEO or campaign tracking. + example: premium-red-winter-pants-limited-edition description: type: string nullable: true - description: The main description for the product - example: A kangaroo hoodie for all seasons + description: Detailed product description that replaces the base product description. Use for localized content, seasonal messaging, or enhanced marketing copy. + example: Stay warm and stylish with our premium red winter pants. Features thermal lining and water-resistant fabric perfect for cold weather adventures. shortDescription: type: string nullable: true - description: A short description of the product - example: A hoodie for all seasons with a kangaroo pocket + description: Brief product summary that appears in product listings and search results. Override for concise, layer-specific messaging. + example: Premium thermal-lined winter pants in classic red metaTags: $ref: "#/components/schemas/ProductMetaAttribute" attributes: type: array - description: A list of product attributes. + description: Product attributes that will be merged with base product attributes. Use to add layer-specific variants, localized values, or seasonal properties. items: $ref: "#/components/schemas/ProductAttribute" images: type: array - description: A list of product images. + description: Product images that will be merged with base product images. Use to add seasonal imagery, locale-specific photos, or promotional visuals. items: $ref: "#/components/schemas/ProductImage" links: type: array - description: A list of linked SKUs. + description: Related product SKUs that will be merged with base product links. Use to add seasonal recommendations, locale-specific cross-sells, or promotional bundles. items: $ref: "#/components/schemas/ProductLink" routes: type: array - description: A list of product routes. + description: URL routing configurations that will be merged with base product routes. Use to add layer-specific navigation paths or campaign-specific URLs. items: $ref: "#/components/schemas/ProductRoutes" configurations: type: array - description: Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.). + description: Product configuration options for composite products (for example, configurable products) that will be merged with base configurations. Use to add layer-specific variants or seasonal options. items: $ref: "#/components/schemas/ProductConfiguration" bundles: type: array - description: Composite products, such as bundle products, must include a list of individual products that are part of the bundle, organized into groups (for example, "shirts", "pants", "accessories"). + description: Bundle product definitions that will be merged with base product bundles. Use to create seasonal bundles, promotional packages, or locale-specific product groupings. items: $ref: "#/components/schemas/ProductBundle" externalIds: type: array - description: A list of external IDs for the product. + description: External system identifiers that will be merged with base product external IDs. Use to add layer-specific tracking codes, campaign IDs, or integration references. items: $ref: "#/components/schemas/ProductExternalId" FeedProductLayerDelete: @@ -2682,8 +2717,8 @@ components: properties: sku: type: string - description: Product unique identifier - example: MH01 + description: SKU (Stock Keeping Unit) that identifies the base product containing the layer to delete. Must match an existing product SKU in the catalog. + example: red-pants source: $ref: "#/components/schemas/SourceLayer" FeedPricebook: @@ -2972,19 +3007,25 @@ components: example: English SourceLayer: title: Catalog layer source - description: Source of the entity, for example, "en-US" for US English for layer "MyLayer" + description: | + Identifies the source context for a product layer, combining locale and layer name to create + a unique layer identifier. This allows for precise targeting of content overrides. type: object required: - layer properties: locale: type: string - description: A single value that represents content locale. When absent layer is treated as global for any locale. - example: English + description: | + ISO locale code (for example, "en-US", "fr-FR", "de-DE") that specifies the target market or language. + When omitted, the layer applies globally across all locales. Use for market-specific customizations. + example: en-US layer: type: string - description: A single value that represents content layer. - example: MyLayer + description: | + Unique identifier for the layer within the product's layer hierarchy. Use descriptive names + that indicate the layer's purpose (for example, "seasonal-winter-2024", "promotional-black-friday", "a-b-test-variant"). + example: seasonal-winter-2024 ProductMetaAttribute: title: Meta Attributes description: Meta attributes that are specified in tags. diff --git a/package.json b/package.json index ea2785e..dbd0677 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@adobe-commerce/aco-ts-sdk", - "version": "1.2.0", + "version": "1.2.1", "description": "TypeScript Client SDK for the Adobe Commerce Optimizer API", "type": "module", "license": "Apache-2.0", diff --git a/src/client.ts b/src/client.ts index 5f76422..fb1744b 100644 --- a/src/client.ts +++ b/src/client.ts @@ -224,15 +224,20 @@ export interface Client { */ updatePrices(data: FeedPricesUpdate[]): Promise; /** - * Create or replace product layers You can create a product layer to merge and override a base product. When creating - * product layers: - Each product layer requires a SKU identifier which matches to a base product. - A product layer - * may have a defined catalog `source.locale`, and if absent is treated as a global layer for any locale. - A product - * layer must have a defined catalog `source.layer`. - All other fields are optional. If provided, they are used to - * override the base product. - When merging array lists, the first array is merged with the base list. All other - * inner lists of the same object are treated as replace values. For example `attributes` is merged with base list, - * but `attributes.values` is a replacement. 
 { "sku": "pants-red-32", "source": { "locale": "en", "layer":
-   * "custom-layer" }, "attributes": [ { "code": "color", "values": ["Green", "Light Green"], "variantReferenceId":
-   * "pants-color-green" } ] }
+ * Create or replace product layers Create product layers to customize and override base product data for specific + * contexts, locales, or business requirements. Product layers enable you to: - Override product attributes for + * specific markets or channels - Provide locale-specific content while maintaining a global base product - Create + * seasonal or promotional variations without duplicating entire product records - Implement A/B testing scenarios + * with different product presentations ## Layer behavior and requirements **Required fields:** - `sku`: Must match an + * existing base product SKU - `source.layer`: Identifies the layer name for organization and retrieval **Optional + * Fields:** - `source.locale`: When specified, layer applies only to that locale. When omitted, layer applies + * globally across all locales - All product fields (name, description, images, and so on): Override corresponding + * base product values ## Merging logic Product layers use intelligent merging: - **Simple fields** (name, + * description, and so on): Complete replacement of base values - **Array fields** (attributes, images, etc.): + * First-level arrays are merged with base arrays - **Nested arrays** (attribute.values, etc.): Complete replacement + * of nested arrays **Example:** Adding a color variant while preserving existing attributes: `json { \"sku\": + * \"red-pants\", \"source\": { \"locale\": \"en-US\", \"layer\": \"seasonal-colors\" }, \"attributes\": [ { \"code\": + * \"color\", \"values\": [\"Crimson Red\", \"Deep Red\"], \"variantReferenceId\": \"pants-color-crimson\" } ] } ` * * @param data - FeedProductLayer[] payload * @returns {Promise} Feed response indicating the number of accepted items @@ -240,7 +245,12 @@ export interface Client { */ createProductLayers(data: FeedProductLayer[]): Promise; /** - * Delete product layers Delete product layers with specified `sku` and `source` values + * Delete product layers Remove specific product layers by SKU and source identifiers. This operation permanently + * deletes the layer data while preserving the base product. **Use Cases:** - Remove expired seasonal or promotional + * layers - Clean up test layers after A/B testing completion - Delete locale-specific layers when discontinuing + * market support - Remove outdated customizations **Important Notes:** - Only the specified layer is deleted; base + * product and other layers remain intact - Both `sku` and `source` (locale + layer) must match exactly for successful + * deletion * * @param data - FeedProductLayerDelete[] payload * @returns {Promise} Feed response indicating the number of accepted items diff --git a/src/types.ts b/src/types.ts index 81c58a0..376e1ad 100644 --- a/src/types.ts +++ b/src/types.ts @@ -663,7 +663,8 @@ export interface FeedProductDelete { */ export interface FeedProductLayer { /** - * SKU (Stock Keeping Unit) is a unique identifier for a product. + * SKU (Stock Keeping Unit) that uniquely identifies the base product this layer will modify. Must match an existing + * product SKU in the catalog. * * @memberof FeedProductLayer * @type {string} @@ -675,28 +676,31 @@ export interface FeedProductLayer { */ source: SourceLayer; /** - * Product name + * Product display name that will override the base product name. Use for localized names, seasonal branding, or + * promotional titles. * * @memberof FeedProductLayer * @type {string} */ name?: string; /** - * The URL key for the product. + * URL-friendly identifier for the product page. Override to create layer-specific URLs for SEO or campaign tracking. * * @memberof FeedProductLayer * @type {string} */ slug?: string; /** - * The main description for the product + * Detailed product description that replaces the base product description. Use for localized content, seasonal + * messaging, or enhanced marketing copy. * * @memberof FeedProductLayer * @type {string} */ description?: string; /** - * A short description of the product + * Brief product summary that appears in product listings and search results. Override for concise, layer-specific + * messaging. * * @memberof FeedProductLayer * @type {string} @@ -708,51 +712,56 @@ export interface FeedProductLayer { */ metaTags?: ProductMetaAttribute; /** - * A list of product attributes. + * Product attributes that will be merged with base product attributes. Use to add layer-specific variants, localized + * values, or seasonal properties. * * @memberof FeedProductLayer * @type {ProductAttribute[]} */ attributes?: ProductAttribute[]; /** - * A list of product images. + * Product images that will be merged with base product images. Use to add seasonal imagery, locale-specific photos, + * or promotional visuals. * * @memberof FeedProductLayer * @type {ProductImage[]} */ images?: ProductImage[]; /** - * A list of linked SKUs. + * Related product SKUs that will be merged with base product links. Use to add seasonal recommendations, + * locale-specific cross-sells, or promotional bundles. * * @memberof FeedProductLayer * @type {ProductLink[]} */ links?: ProductLink[]; /** - * A list of product routes. + * URL routing configurations that will be merged with base product routes. Use to add layer-specific navigation paths + * or campaign-specific URLs. * * @memberof FeedProductLayer * @type {ProductRoutes[]} */ routes?: ProductRoutes[]; /** - * Composite products, such as configurable products, must provide a list of product options that a shopper can select - * (for example, "color", "size", etc.). + * Product configuration options for composite products (for example, configurable products) that will be merged with + * base configurations. Use to add layer-specific variants or seasonal options. * * @memberof FeedProductLayer * @type {ProductConfiguration[]} */ configurations?: ProductConfiguration[]; /** - * Composite products, such as bundle products, must include a list of individual products that are part of the - * bundle, organized into groups (for example, "shirts", "pants", "accessories"). + * Bundle product definitions that will be merged with base product bundles. Use to create seasonal bundles, + * promotional packages, or locale-specific product groupings. * * @memberof FeedProductLayer * @type {ProductBundle[]} */ bundles?: ProductBundle[]; /** - * A list of external IDs for the product. + * External system identifiers that will be merged with base product external IDs. Use to add layer-specific tracking + * codes, campaign IDs, or integration references. * * @memberof FeedProductLayer * @type {ProductExternalId[]} @@ -765,7 +774,8 @@ export interface FeedProductLayer { */ export interface FeedProductLayerDelete { /** - * Product unique identifier + * SKU (Stock Keeping Unit) that identifies the base product containing the layer to delete. Must match an existing + * product SKU in the catalog. * * @memberof FeedProductLayerDelete * @type {string} @@ -1403,21 +1413,24 @@ export interface Source { locale: string; } /** - * Source of the entity, for example, "en-US" for US English for layer "MyLayer" + * Identifies the source context for a product layer, combining locale and layer name to create a unique layer + * identifier. This allows for precise targeting of content overrides. * * @export * @interface SourceLayer */ export interface SourceLayer { /** - * A single value that represents content locale. When absent layer is treated as global for any locale. + * ISO locale code (for example, "en-US", "fr-FR", "de-DE") that specifies the target market or language. When + * omitted, the layer applies globally across all locales. Use for market-specific customizations. * * @memberof SourceLayer * @type {string} */ locale?: string; /** - * A single value that represents content layer. + * Unique identifier for the layer within the product's layer hierarchy. Use descriptive names that indicate the + * layer's purpose (for example, "seasonal-winter-2024", "promotional-black-friday", "a-b-test-variant"). * * @memberof SourceLayer * @type {string}