@salesforce/b2c-tooling-sdk 2.4.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/dx/scapi-schemas/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "SCAPI Schemas",
-    "version": "1.0.2",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/scapi-schemas/scapi-schemas-oas-v1-public.yaml)\n\n# API Overview\n\nThe SCAPI Schema API provides programmatic retrieval of OpenAPI schema definitions for all B2C Commerce API (SCAPI) endpoints, which facilitates better integration, validation, and development workflows across the Commerce Cloud ecosystem.\n\nThis API serves as a central registry for all SCAPI schema definitions, allowing you to discover available APIs by family, name, and version, as well as retrieve detailed schema specifications for specific API endpoints.\n\n## Authentication & Authorization\n\nThe SCAPI Schema API uses an Account Manager OAuth 2.0 bearer token for authentication. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account manager to log in.\n\nThe necessary scope for accessing the SCAPI Schema API is:\n\n- `sfcc.scapi-schemas`: Provides access to retrieve SCAPI schema definitions and listings.\n\nYou must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).\n\nFor detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).\n\nAccess is typically intended for developers, integration tools, and administrative applications that need to programmatically work with SCAPI schema definitions.\n\n## Response Details\n\n### Timeouts\n\nAdmin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)\n\n### Error Handling\n\nError responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)\n\n## Use Cases\n\n### Schema Discovery and Cataloging\n\nDiscover all available SCAPI endpoints and their current schema versions. This is particularly useful for:\n- Development Tools: IDE plugins and code generators that need to understand available APIs\n- Integration Platforms: Systems that need to dynamically discover and adapt to available Commerce Cloud APIs\n- Documentation Systems: Tools that automatically generate API documentation or SDK references\n- Governance and Compliance: Tracking which APIs are available, their versions, and deprecation status\n\nThe API allows filtering by:\n- API family, for example: \"product\", \"checkout\", \"customer\n- API name, for example: \"shopper-products\", \"orders\"\n- API version, for example: \"v1\", \"v2\"\n- Cartridge name, for example: \"my_cartridge\". **Only for Custom APIs.**\n- Status, for example: \"current\", \"deprecated\"\n\n### Schema Validation and Code Generation\n\nRetrieve detailed OpenAPI schema specifications to enable:\n- Request/Response Validation: Validate API requests and responses against the official schema.\n- Mock Server Creation: Generate mock servers for testing and development.\n- API Contract Testing: Ensure your implementations comply with the SCAPI specifications.\n\n### Version Management and Migration Planning\n\nTrack schema versions and plan migrations by:\n- Version Comparison: Compare different versions of the same API to understand changes.\n- Deprecation Tracking: Identify deprecated schemas and plan migration strategies.  \n- Breaking Change Detection: Analyze schema differences to identify potential breaking changes.\n- Rollback Planning: Access historical schema versions for rollback scenarios.\n\n### Development Workflow Integration\n\nIntegrate schema access into your development workflows:\n- CI/CD Pipeline Integration: Validate API implementations against current schemas during build processes.\n- Local Development: Provide developers with up-to-date schema definitions for better IDE support.\n- Testing Automation: Generate comprehensive test suites based on schema definitions.\n- API Gateway Configuration: Configure API gateways with current schema definitions for validation and routing.",
+    "version": "1.0.3",
     "x-api-type": "Admin",
     "x-api-family": "DX"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/dx/scapi-schemas/v1",
       "variables": {
         "shortCode": {
+          "description": "An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)",
           "default": "shortCode"
         }
       }
@@ -19,21 +21,25 @@
   "paths": {
     "/organizations/{organizationId}/schemas": {
       "get": {
+        "summary": "Get a list of known SCAPI schema definitions.",
         "operationId": "getSchemaList",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "apiFamily",
             "in": "query",
+            "description": "The API family",
             "required": false,
             "style": "form",
             "explode": true,
@@ -44,6 +50,7 @@
           {
             "name": "apiName",
             "in": "query",
+            "description": "The API name",
             "required": false,
             "style": "form",
             "explode": true,
@@ -54,6 +61,7 @@
           {
             "name": "apiVersion",
             "in": "query",
+            "description": "The API version",
             "required": false,
             "style": "form",
             "explode": true,
@@ -61,9 +69,21 @@
               "$ref": "#/components/schemas/ApiVersion"
             }
           },
+          {
+            "name": "cartridgeName",
+            "in": "query",
+            "description": "The cartridge name",
+            "required": false,
+            "style": "form",
+            "explode": true,
+            "schema": {
+              "$ref": "#/components/schemas/CartridgeName"
+            }
+          },
           {
             "name": "status",
             "in": "query",
+            "description": "The schema status",
             "required": false,
             "style": "form",
             "explode": true,
@@ -72,7 +92,8 @@
               "enum": [
                 "current",
                 "deprecated"
-              ]
+              ],
+              "example": "current"
             }
           }
         ],
@@ -83,6 +104,14 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/SchemaListResult"
+                },
+                "examples": {
+                  "SchemaListSuccess": {
+                    "$ref": "#/components/examples/SchemaListSuccess"
+                  },
+                  "SchemaListSuccessNoFilter": {
+                    "$ref": "#/components/examples/SchemaListSuccessNoFilter"
+                  }
                 }
               }
             }
@@ -93,6 +122,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BadRequest": {
+                    "$ref": "#/components/examples/BadRequest"
+                  }
                 }
               }
             }
@@ -103,6 +137,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Unauthorized": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -113,6 +152,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Forbidden": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -129,21 +173,25 @@
     },
     "/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}": {
       "get": {
+        "summary": "Get a SCAPI schema specification.",
         "operationId": "getSchemaDetails",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "apiFamily",
             "in": "path",
+            "description": "The API family",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -154,6 +202,7 @@
           {
             "name": "apiName",
             "in": "path",
+            "description": "The API name",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -164,6 +213,7 @@
           {
             "name": "apiVersion",
             "in": "path",
+            "description": "The API version",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -174,16 +224,21 @@
           {
             "name": "expand",
             "in": "query",
+            "description": "Optional schema expansion e.g. 'custom_properties'.",
             "required": false,
             "style": "form",
             "explode": false,
             "schema": {
               "type": "array",
+              "example": [
+                "custom_properties"
+              ],
               "items": {
                 "type": "string",
                 "enum": [
                   "custom_properties"
-                ]
+                ],
+                "example": "custom_properties"
               }
             }
           }
@@ -193,7 +248,8 @@
             "description": "SCAPI schema specifications successfully retrieved.",
             "content": {
               "application/json": {
-                "schema": {}
+                "schema": {},
+                "example": {}
               }
             }
           },
@@ -203,6 +259,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BadRequest": {
+                    "$ref": "#/components/examples/BadRequest"
+                  }
                 }
               }
             }
@@ -213,6 +274,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Unauthorized": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -223,6 +289,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Forbidden": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -233,6 +304,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "ResourceNotFound": {
+                    "$ref": "#/components/examples/ResourceNotFound"
+                  }
                 }
               }
             }
@@ -252,35 +328,53 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
-        "maxLength": 32,
-        "minLength": 1
+        "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
+        "example": "f_ecom_zzxy_prd",
+        "pattern": "^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$"
       },
       "ApiFamily": {
         "type": "string",
+        "description": "The API family name",
+        "example": "product",
         "maxLength": 50,
         "pattern": "^[a-z0-9-]+$"
       },
       "ApiName": {
         "type": "string",
+        "description": "The API name",
+        "example": "shopper-products",
         "maxLength": 200,
         "pattern": "^[a-z0-9-]+$"
       },
       "ApiVersion": {
         "type": "string",
+        "description": "The API version",
+        "example": "v1",
         "pattern": "^v\\d+$"
       },
+      "CartridgeName": {
+        "type": "string",
+        "description": "The cartridge name",
+        "example": "my_cartridge",
+        "pattern": "^[a-z_][a-z0-9_]*$"
+      },
       "Total": {
         "type": "integer",
         "format": "int32",
         "default": 0,
+        "description": "The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.",
+        "example": 10,
         "minimum": 0
       },
       "ResultBase": {
         "type": "object",
+        "description": "Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. \nAdditionally it needs to be defined what data is returned.",
         "properties": {
           "limit": {
             "type": "integer",
-            "format": "int32"
+            "format": "int32",
+            "description": "Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.",
+            "example": 10
           },
           "total": {
             "$ref": "#/components/schemas/Total"
@@ -303,12 +397,16 @@
           "apiVersion": {
             "$ref": "#/components/schemas/ApiVersion"
           },
+          "cartridgeName": {
+            "$ref": "#/components/schemas/CartridgeName"
+          },
           "status": {
             "type": "string",
             "enum": [
               "current",
               "deprecated"
-            ]
+            ],
+            "example": "current"
           }
         }
       },
@@ -317,31 +415,48 @@
         "properties": {
           "schemaVersion": {
             "type": "string",
+            "description": "Semantic OAS schema version",
+            "example": "1.0.0",
             "pattern": "^\\d+\\.\\d+\\.\\d+$"
           },
           "apiFamily": {
             "type": "string",
+            "description": "The API family name",
+            "example": "product",
             "maxLength": 50,
             "pattern": "^[a-z0-9-]+$"
           },
           "apiName": {
             "type": "string",
+            "description": "The API name",
+            "example": "shopper-products",
             "maxLength": 200,
             "pattern": "^[a-z0-9-]+$"
           },
           "apiVersion": {
             "type": "string",
+            "description": "The API version",
+            "example": "v1",
             "pattern": "^v\\d+$"
           },
+          "cartridgeName": {
+            "type": "string",
+            "description": "The cartridge name (only for Custom APIs)",
+            "example": "my_cartridge",
+            "pattern": "^[a-z_][a-z0-9_]*$"
+          },
           "status": {
             "type": "string",
             "enum": [
               "current",
               "deprecated"
-            ]
+            ],
+            "example": "deprecated"
           },
           "link": {
             "type": "string",
+            "description": "The URL to the SCAPI schema detail endpoint",
+            "example": "https://api.example.com/scapi/schemas/customer/customers/v1",
             "maxLength": 2048
           }
         }
@@ -358,6 +473,7 @@
           },
           "data": {
             "type": "array",
+            "description": "List containing all filtered schema entries.",
             "items": {
               "$ref": "#/components/schemas/SchemaListItem"
             }
@@ -370,17 +486,25 @@
         "properties": {
           "title": {
             "type": "string",
+            "description": "A short, human-readable summary of the problem\ntype.  It will not change from occurrence to occurrence of the \nproblem, except for purposes of localization\n",
+            "example": "You do not have enough credit",
             "maxLength": 256
           },
           "type": {
             "type": "string",
+            "description": "A URI reference [RFC3986] that identifies the\nproblem type.  This specification encourages that, when\ndereferenced, it provide human-readable documentation for the\nproblem type (e.g., using HTML [W3C.REC-html5-20141028]).  When\nthis member is not present, its value is assumed to be\n\"about:blank\". It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "NotEnoughMoney",
             "maxLength": 2048
           },
           "detail": {
-            "type": "string"
+            "type": "string",
+            "description": "A human-readable explanation specific to this occurrence of the problem.",
+            "example": "Your current balance is 30, but that costs 50"
           },
           "instance": {
             "type": "string",
+            "description": "A URI reference that identifies the specific\noccurrence of the problem.  It may or may not yield further\ninformation if dereferenced.  It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "/account/12345/msgs/abc",
             "maxLength": 2048
           }
         },
@@ -395,16 +519,19 @@
       "organizationId": {
         "name": "organizationId",
         "in": "path",
+        "description": "An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).",
         "required": true,
         "style": "simple",
         "explode": false,
         "schema": {
           "$ref": "#/components/schemas/OrganizationId"
-        }
+        },
+        "example": "f_ecom_zzxy_prd"
       },
       "apiFamily": {
         "name": "apiFamily",
         "in": "query",
+        "description": "The API family",
         "required": false,
         "style": "form",
         "explode": true,
@@ -415,6 +542,7 @@
       "apiName": {
         "name": "apiName",
         "in": "query",
+        "description": "The API name",
         "required": false,
         "style": "form",
         "explode": true,
@@ -425,6 +553,7 @@
       "apiVersion": {
         "name": "apiVersion",
         "in": "query",
+        "description": "The API version",
         "required": false,
         "style": "form",
         "explode": true,
@@ -432,9 +561,21 @@
           "$ref": "#/components/schemas/ApiVersion"
         }
       },
+      "cartridgeName": {
+        "name": "cartridgeName",
+        "in": "query",
+        "description": "The cartridge name",
+        "required": false,
+        "style": "form",
+        "explode": true,
+        "schema": {
+          "$ref": "#/components/schemas/CartridgeName"
+        }
+      },
       "status": {
         "name": "status",
         "in": "query",
+        "description": "The schema status",
         "required": false,
         "style": "form",
         "explode": true,
@@ -443,12 +584,14 @@
           "enum": [
             "current",
             "deprecated"
-          ]
+          ],
+          "example": "current"
         }
       },
       "parameters-apiFamily": {
         "name": "apiFamily",
         "in": "path",
+        "description": "The API family",
         "required": true,
         "style": "simple",
         "explode": false,
@@ -459,6 +602,7 @@
       "parameters-apiName": {
         "name": "apiName",
         "in": "path",
+        "description": "The API name",
         "required": true,
         "style": "simple",
         "explode": false,
@@ -469,6 +613,7 @@
       "parameters-apiVersion": {
         "name": "apiVersion",
         "in": "path",
+        "description": "The API version",
         "required": true,
         "style": "simple",
         "explode": false,
@@ -479,23 +624,113 @@
       "expand": {
         "name": "expand",
         "in": "query",
+        "description": "Optional schema expansion e.g. 'custom_properties'.",
         "required": false,
         "style": "form",
         "explode": false,
         "schema": {
           "type": "array",
+          "example": [
+            "custom_properties"
+          ],
           "items": {
             "type": "string",
             "enum": [
               "custom_properties"
-            ]
+            ],
+            "example": "custom_properties"
           }
         }
       }
     },
+    "examples": {
+      "SchemaListSuccess": {
+        "value": {
+          "limit": 1,
+          "total": 3,
+          "filter": {
+            "apiFamily": "product",
+            "apiName": "shopper-products",
+            "apiVersion": "v1",
+            "status": "current"
+          },
+          "data": [
+            {
+              "schemaVersion": "1.0.25",
+              "apiFamily": "product",
+              "apiName": "shopper-products",
+              "apiVersion": "v1",
+              "status": "current",
+              "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
+            }
+          ]
+        }
+      },
+      "SchemaListSuccessNoFilter": {
+        "value": {
+          "limit": 3,
+          "total": 3,
+          "data": [
+            {
+              "schemaVersion": "1.0.25",
+              "apiFamily": "product",
+              "apiName": "shopper-products",
+              "apiVersion": "v1",
+              "status": "current",
+              "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
+            },
+            {
+              "schemaVersion": "2.1.0",
+              "apiFamily": "checkout",
+              "apiName": "shopper-baskets",
+              "apiVersion": "v2",
+              "status": "current",
+              "link": "https://api.example.com/scapi/schemas/checkout/shopper-baskets/v2"
+            },
+            {
+              "schemaVersion": "1.5.12",
+              "apiFamily": "customer",
+              "apiName": "customers",
+              "apiVersion": "v1",
+              "status": "deprecated",
+              "link": "https://api.example.com/scapi/schemas/customer/customers/v1"
+            }
+          ]
+        }
+      },
+      "BadRequest": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/value-constraint-violation",
+          "title": "Bad Request",
+          "detail": "Value for parameter 'apiFamily' violates API constraint '^[a-z0-9-]+$'"
+        }
+      },
+      "Unauthorized": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
+          "title": "Unauthorized",
+          "detail": "Unauthorized request"
+        }
+      },
+      "Forbidden": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
+          "title": "Forbidden",
+          "detail": "Access to requested resource forbidden"
+        }
+      },
+      "ResourceNotFound": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
+          "title": "Resource Not Found",
+          "detail": "Could not find requested resource"
+        }
+      }
+    },
     "securitySchemes": {
       "AmOAuth2": {
         "type": "oauth2",
+        "description": "AccountManager OAuth 2.0 bearer token Authentication.",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
@@ -506,9 +741,8 @@
           "authorizationCode": {
             "authorizationUrl": "https://account.demandware.com/dwsso/oauth2/authorize",
             "tokenUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
-            "scopes": {
-              "sfcc.scapi-schemas": "SCAPI schema READONLY scope"
-            }
+            "refreshUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
+            "scopes": {}
           }
         }
       }