Merge branch 'main' of https://github.com/commercetools/commercetools…

…-api-reference

.github/workflows/sdks.yml

@@ -23,24 +23,20 @@ jobs:
         include:
           - language: java
             repository: 'commercetools/commercetools-sdk-java-v2'
-            sshKey: JAVA_SDK_DEPLOY_KEY
             apiMixin: true
             API_RAML: "../commercetools-api-reference/api-specs/api/api-mixin.raml"
             diffFormat: JAVA_MARKDOWN
           - language: csharp
             repository: 'commercetools/commercetools-dotnet-core-sdk-v2'
-            sshKey: CSHARP_SDK_DEPLOY_KEY
             apiMixin: true
             API_RAML: "../commercetools-api-reference/api-specs/api/api-mixin.raml"
             diffFormat: DOTNET_MARKDOWN
           - language: typescript
             repository: 'commercetools/commercetools-sdk-typescript'
-            sshKey: TS_SDK_DEPLOY_KEY
             API_RAML: "../commercetools-api-reference/api-specs/api/api.raml"
             diffFormat: TS_MARKDOWN
           - language: php
             repository: 'commercetools/commercetools-sdk-php-v2'
-            sshKey: SDK_DEPLOY_KEY
             apiMixin: true
             makeParams: "-j2"
             API_RAML: "../commercetools-api-reference/api-specs/api/api-mixin.raml"
@@ -49,17 +45,38 @@ jobs:
 #            repository: 'commercetools/commercetools-postman-collection'
 #            sshKey: ${{ secrets.POSTMAN_DEPLOY_KEY }}
     steps:
+        # Get GitHub token via the CT SDKs App
+      - name: Generate GitHub token (via CT SDKs App)
+        id: generate_github_token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.SDK_APP_ID }}
+          private-key: ${{ secrets.SDK_APP_PEM }}
+          owner: ${{ github.repository_owner }}
+
+      - name: Get App user
+        id: get_app_user
+        env:
+           GITHUB_TOKEN: ${{ steps.generate_github_token.outputs.token }}
+        run: |
+          export GH_APP_USER=`gh api /users/ct-sdks%5Bbot%5D | jq .id`
+          echo "email=${GH_APP_USER}+ct-sdks[bot]@users.noreply.github.com" >> "$GITHUB_OUTPUT"
+
       - name: "Checkout api reference"
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           path: commercetools-api-reference
-
+          # Pass a personal access token (using our CT SDKs App) to be able to trigger other workflows
+          # https://help.github.com/en/actions/reference/events-that-trigger-workflows#triggering-new-workflows-using-a-personal-access-token
+          # https://github.community/t/action-does-not-trigger-another-on-push-tag-action/17148/8
+          token: ${{ steps.generate_github_token.outputs.token }}
+
       - name: "Checkout SDK"
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: ${{ matrix.repository }}
           path: commercetools-sdk
-          ssh-key: ${{ secrets[matrix.sshKey] }}
+          token: ${{ steps.generate_github_token.outputs.token }}
 
       - name: 'Setup Java'
         uses: actions/setup-java@v3
@@ -137,10 +154,11 @@ jobs:
           HISTORY_RAML: "../commercetools-api-reference/api-specs/history/api.raml"
 
       - name: "Checkout previous api reference"
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
           path: commercetools-api-reference-previous
+          token: ${{ steps.generate_github_token.outputs.token }}
 
       - name: "Store api reference version"
         run: |
@@ -164,9 +182,6 @@ jobs:
       - name: "Calculate diff (History)"
         run: rmf-codegen diff -f ${{ matrix.diffFormat }} -o ./changes_history.md commercetools-api-reference-previous/api-specs/history/api.raml commercetools-api-reference/api-specs/history/api.raml
 
-      - name: "Calculate diff (ML)"
-        run: rmf-codegen diff -f ${{ matrix.diffFormat }} -o ./changes_ml.md commercetools-api-reference-previous/api-specs/ml/api.raml commercetools-api-reference/api-specs/ml/api.raml
-
       - name: 'Create change file'
         run: |
           if [ -f ./changes_api.md ]; then
@@ -187,12 +202,6 @@ jobs:
             cat ./changes_history.md >> ./changes.md
             echo "" >> ./changes.md
           fi
-          if [ -f ./changes_ml.md ]; then
-            echo "**ML changes**" >> ./changes.md
-            echo "" >> ./changes.md
-            cat ./changes_ml.md >> ./changes.md
-            echo "" >> ./changes.md
-          fi
           if [ -f ./changes.md ]; then
             cat ./changes.md
             cp ./changes.md ./commercetools-sdk/changes.md
@@ -208,16 +217,16 @@ jobs:
           repository: commercetools-sdk
           branch: gen-sdk-updates
           commit_message: "build(codegen): updating SDK"
-          commit_user_name: Auto Mation
-          commit_user_email: [email protected]
-          commit_author: Auto Mation <[email protected]>
+          commit_author: ct-sdks[bot] <${{ steps.get_app_user.outputs.email }}>
+          commit_user_name: ct-sdks[bot]
+          commit_user_email: ${{ steps.get_app_user.outputs.email }}
 
       - uses: stefanzweifel/git-auto-commit-action@v4
         if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
         with:
           repository: commercetools-sdk
           branch: ${{ github.ref_name }}
           commit_message: "build(codegen): updating SDK"
-          commit_user_name: Auto Mation
-          commit_user_email: [email protected]
-          commit_author: Auto Mation <[email protected]>
+          commit_author: ct-sdks[bot] <${{ steps.get_app_user.outputs.email }}>
+          commit_user_name: ct-sdks[bot]
+          commit_user_email: ${{ steps.get_app_user.outputs.email }}

Makefile

@@ -13,15 +13,14 @@ validate_oas:
 	npx autorest --v3 --azure-validator --input-file=oas/api/openapi.yaml
 	npx autorest --v3 --azure-validator --input-file=oas/history/openapi.yaml
 	npx autorest --v3 --azure-validator --input-file=oas/import/openapi.yaml
-	npx autorest --v3 --azure-validator --input-file=oas/ml/openapi.yaml
 
 codegen_install:
 	curl -o- -s https://raw.githubusercontent.com/vrapio/rmf-codegen/master/scripts/install.sh | bash
 
 validate_raml: codegen_install
 	rmf-codegen verify api-specs/api/api.raml
 
-generate_oas: generate_oas_api generate_oas_import generate_oas_history generate_oas_ml
+generate_oas: generate_oas_api generate_oas_import generate_oas_history
 
 generate_oas_api: codegen_install
 	rmf-codegen generate -o oas/api -t OAS api-specs/api/api.raml

api-specs/api/examples/approval-flow-update-response.example.json

@@ -23,7 +23,6 @@
     {
       "id": "ff806a85-1457-4cef-929a-79aefe85f02d",
       "version": 1,
-      "lastMessageSequenceNumber": 1,
       "createdAt": "2023-06-12T14:43:45.732Z",
       "lastModifiedAt": "2023-06-12T14:43:45.732Z",
       "lastModifiedBy": {
@@ -96,4 +95,4 @@
   "eligibleApprovers": [],
   "pendingApprovers": [],
   "currentTierPendingApprovers": []
-}
+}

api-specs/api/examples/approval-flow.example.json

@@ -23,7 +23,6 @@
     {
       "id": "ff806a85-1457-4cef-929a-79aefe85f02d",
       "version": 1,
-      "lastMessageSequenceNumber": 1,
       "createdAt": "2023-06-12T14:43:45.732Z",
       "lastModifiedAt": "2023-06-12T14:43:45.732Z",
       "lastModifiedBy": {
@@ -158,4 +157,4 @@
       }
     }
   ]
-}
+}

api-specs/api/examples/approval-flows.example.json

@@ -29,7 +29,6 @@
         {
           "id": "ff806a85-1457-4cef-929a-79aefe85f02d",
           "version": 1,
-          "lastMessageSequenceNumber": 1,
           "createdAt": "2023-06-12T14:43:45.732Z",
           "lastModifiedAt": "2023-06-12T14:43:45.732Z",
           "lastModifiedBy": {
@@ -166,4 +165,4 @@
       ]
     }
   ]
-}
+}

api-specs/api/resources/in-store.raml

@@ -2131,10 +2131,12 @@ uriParameters:
         ]
       description: |
         Gets the current or staged representation of a [Product](ctp:api:type:Product) by its key from the specified [Store](ctp:api:type:Store).
-        If the Store has defined some languages, countries, distribution or supply Channels,
+        If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection,
         they are used for projections based on [locale](ctp:api:type:ProductProjectionLocales), [price](ctp:api:type:ProductProjectionPrices)
         and [inventory](ctp:api:type:ProductProjectionInventoryEntries).
 
+        If [ProductSelection](ctp:api:type:ProductSelection) is used, it affects the [availability of the Product](/projects/stores#products-available-in-store) in the specified Store.
+
         When used with an API Client that has the `view_published_products:{projectKey}` scope, this endpoint only returns published (current) Product Projections.
       is:
         - projectionSelecting
@@ -2174,10 +2176,12 @@ uriParameters:
         ]
       description: |
         Gets the current or staged representation of a [Product](ctp:api:type:Product) by its ID from the specified [Store](ctp:api:type:Store).
-        If the Store has defined some languages, countries, distribution or supply Channels,
+        If the Store has defined some languages, countries, distribution, supply Channels, and/or Product Selection,
         they are used for projections based on [locale](ctp:api:type:ProductProjectionLocales), [price](ctp:api:type:ProductProjectionPrices)
         and [inventory](ctp:api:type:ProductProjectionInventoryEntries).
 
+        If [ProductSelection](ctp:api:type:ProductSelection) is used, it affects the [availability of the Product](/projects/stores#products-available-in-store) in the specified Store.
+
         When used with an API Client that has the `view_published_products:{projectKey}` scope, this endpoint only returns published (current) Product Projections.
       is:
         - projectionSelecting

api-specs/api/resources/products.raml

@@ -43,7 +43,7 @@ head:
 post:
   securedBy: [oauth_2_0: { scopes: ['manage_products:{projectKey}'] }]
   description: |
-    To create a new Product, send a representation that is going to become the initial _staged_ representation of the new Product in the master catalog.
+    To create a new Product, send a representation that is going to become the initial _staged_ and _current_ representation of the new Product in the catalog.
     If [Price Selection](ctp:api:type:ProductPriceSelection) query parameters are provided, selected Prices will be added to the response.
     Produces the [ProductCreated](/projects/messages#product-created) Message.
   is:

api-specs/api/traits/data-erasure.raml

@@ -6,4 +6,4 @@ queryParameters:
     required: false
     description: |
       Defaults to `false`.
-      Set to `true` if you want to [erase all related personal data](/../api/general-concepts#data-erasure-of-personal-data) in compliance with GDPR.
+      Set to `true` if you want to [erase all related personal data](/../api/gdpr#data-erasure-of-personal-data) in compliance with GDPR.

api-specs/api/types/approval-flow/ApprovalFlow.raml

@@ -23,7 +23,7 @@ properties:
     type: CreatedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/general-concepts#events-tracked).
   lastModifiedAt:
     type: datetime
     description: |
@@ -32,7 +32,7 @@ properties:
     type: LastModifiedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/general-concepts#events-tracked).
   order:
     type: OrderReference
     description: |

api-specs/api/types/approval-flow/ApprovalFlowUpdate.raml

@@ -8,7 +8,7 @@ properties:
     format: int64
     description: |
       Expected version of the [Approval Flow](ctp:api:type:ApprovalFlow) to which the changes should be applied.
-      If the expected version does not match the actual version, a [409 Conflict](/../api/errors#409-conflict) error will be returned.
+      If the expected version does not match the actual version, a [ConcurrentModification](ctp:api:type:ConcurrentModificationError) error will be returned.
   actions:
     type: array
     items: ApprovalFlowUpdateAction

api-specs/api/types/approval-rule/ApprovalRule.raml

@@ -23,7 +23,7 @@ properties:
     type: CreatedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/general-concepts#events-tracked).
   lastModifiedAt:
     type: datetime
     description: |
@@ -32,7 +32,7 @@ properties:
     type: LastModifiedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/general-concepts#events-tracked).
   key?:
     type: string
     description: |

api-specs/api/types/approval-rule/ApprovalRuleUpdate.raml

@@ -8,7 +8,7 @@ properties:
     format: int64
     description: |
       Expected version of the [ApprovalRule](ctp:api:type:ApprovalRule) to which the changes should be applied.
-      If the expected version does not match the actual version, a [409 Conflict](/../api/errors#409-conflict) error will be returned.
+      If the expected version does not match the actual version, a [ConcurrentModification](ctp:api:type:ConcurrentModificationError) error will be returned.
   actions:
     type: array
     items: ApprovalRuleUpdateAction

api-specs/api/types/associate-role/AssociateRole.raml

@@ -27,12 +27,12 @@ properties:
     type: LastModifiedBy
     (beta): true
     description: |
-      Present on resources updated after 1 February 2019 except for [events not tracked](/../api/client-logging#events-tracked).
+      Present on resources updated after 1 February 2019 except for [events not tracked](/../api/general-concepts#events-tracked).
   createdBy?:
     type: CreatedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/../api/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/../api/general-concepts#events-tracked).
   key:
     type: string
     description: |

api-specs/api/types/associate-role/AssociateRoleResourceIdentifier.raml

@@ -5,13 +5,13 @@ type: ResourceIdentifier
 displayName: AssociateRoleResourceIdentifier
 discriminatorValue: associate-role
 description: |
-  [ResourceIdentifier](ctp:api:type:TypeResourceIdentifier) of an [AssociateRole](ctp:api:type:AssociateRole).
+  [ResourceIdentifier](ctp:api:type:TypeResourceIdentifier) of an [AssociateRole](ctp:api:type:AssociateRole). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/../api/errors#invalidjsoninput) error is returned.
 properties:
   id?:
     type: string
     description: |
-      Unique identifier of the referenced [AssociateRole](ctp:api:type:AssociateRole). Either `id` or `key` is required.
+      Unique identifier of the referenced [AssociateRole](ctp:api:type:AssociateRole). Required if `key` is absent.
   key?:
     type: string
     description: |
-      Unique key of the referenced [AssociateRole](ctp:api:type:AssociateRole). Either `id` or `key` is required.
+      Unique key of the referenced [AssociateRole](ctp:api:type:AssociateRole). Required if `id` is absent.

api-specs/api/types/associate-role/AssociateRoleUpdate.raml

@@ -8,7 +8,7 @@ properties:
     format: int64
     description: |
       Expected version of the AssociateRole on which the changes should be applied.
-      If the expected version does not match the actual version, a [409 Conflict](/../api/errors#409-conflict) error will be returned.
+      If the expected version does not match the actual version, a [ConcurrentModification](ctp:api:type:ConcurrentModificationError) error will be returned.
   actions:
     type: array
     items: AssociateRoleUpdateAction

api-specs/api/types/attribute-group/AttributeGroup.raml

@@ -27,12 +27,12 @@ properties:
     type: LastModifiedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/../api/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/../api/general-concepts#events-tracked).
   createdBy?:
     type: CreatedBy
     (beta): true
     description: |
-      Present on resources created after 1 February 2019 except for [events not tracked](/../api/client-logging#events-tracked).
+      Present on resources created after 1 February 2019 except for [events not tracked](/../api/general-concepts#events-tracked).
   name:
     type: LocalizedString
     description: |

api-specs/api/types/attribute-group/AttributeGroupResourceIdentifier.raml

@@ -5,13 +5,13 @@ type: ResourceIdentifier
 displayName: AttributeGroupResourceIdentifier
 discriminatorValue: attribute-group
 description: |
-  [ResourceIdentifier](/../api/types#resourceidentifier) to an [AttributeGroup](ctp:api:type:AttributeGroup).
+  [ResourceIdentifier](/../api/types#resourceidentifier) to an [AttributeGroup](ctp:api:type:AttributeGroup). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/../api/errors#invalidjsoninput) error is returned.
 properties:
   id?:
     type: string
     description: |
-      Platform-generated unique identifier of the referenced [AttributeGroup](ctp:api:type:AttributeGroup). Either `id` or `key` is required.
+      Platform-generated unique identifier of the referenced [AttributeGroup](ctp:api:type:AttributeGroup). Required if `key` is absent.
   key?:
     type: string
     description: |
-      User-generated unique identifier of the referenced [AttributeGroup](ctp:api:type:AttributeGroup). Either `id` or `key` is required.
+      User-generated unique identifier of the referenced [AttributeGroup](ctp:api:type:AttributeGroup). Required if `id` is absent.

api-specs/api/types/attribute-group/AttributeGroupUpdate.raml

@@ -7,7 +7,8 @@ properties:
     type: number
     format: int64
     description: |
-      Expected version of the AttributeGroup on which the changes should be applied. If the expected version does not match the actual version, a [409 Conflict](/../api/errors#409-conflict) will be returned.
+      Expected version of the AttributeGroup on which the changes should be applied.
+      If the expected version does not match the actual version, a [ConcurrentModification](ctp:api:type:ConcurrentModificationError) error will be returned.
   actions:
     type: array
     items: AttributeGroupUpdateAction

api-specs/api/types/business-unit/Associate.raml

@@ -11,7 +11,7 @@ properties:
     (deprecated): true
     type: AssociateRoleDeprecated[]
     description: |
-      Deprecated type. Use `associateRoleAssignment` instead.
+      Deprecated type. Use `associateRoleAssignments` instead.
   customer:
     type: CustomerReference
     description: |

api-specs/api/types/business-unit/AssociateDraft.raml

@@ -12,7 +12,7 @@ properties:
     (deprecated): true
     type: AssociateRoleDeprecated[]
     description: |
-      Deprecated type. Use `associateRoleAssignment` instead.
+      Deprecated type. Use `associateRoleAssignments` instead.
   customer:
     type: CustomerResourceIdentifier
     description: |