@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

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

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Custom APIs",
-    "version": "1.0.2",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/custom-apis/custom-apis-oas-v1-public.yaml)\n\n# API Overview\n\nThe Custom APIs DX API provides enhanced transparency and manageability of Custom API endpoints within the platform. This API offers a user-friendly and secure approach by providing real-time feedback on endpoint registration status, including successful registrations and failed attempts with error reasons.\n\n## Authentication & Authorization\n\nFor 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.\n\nYou must include `sfcc.custom-apis` (read-only access) or `sfcc.custom-apis.rw` (read-write access) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)\n\nFor detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)\n\nAccess is intended for admin users only.\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### Endpoint Status Transparency\n\nDuring a new code version activation, developers and administrators often struggle to verify the status of all their Custom API endpoints. This can lead to confusion and time-consuming manual log checks to diagnose why an endpoint might not be active. By using the Custom APIs DX endpoint, a user can programmatically fetch a list of all endpoints and their current status (`active` or `not_registered`). This allows for quick identification of any registration issues, including specific error reasons for endpoints that failed to register, thereby streamlining the validation process after a deployment.\n\n### Debug Failed Registrations\n\nWhen a Custom API endpoint fails to register, it can be difficult to understand the root cause without accessible error details. This API directly addresses this by providing an `errorReason` property for any endpoint with a `not_registered` status. For example, if an endpoint registration is skipped because its schema file cannot be read, the API response will explicitly state this, allowing developers to quickly pinpoint and resolve the issue without needing to contact support or search through extensive log files.",
+    "version": "1.0.3",
     "x-api-type": "Admin",
     "x-api-family": "DX"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/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,26 @@
   "paths": {
     "/organizations/{organizationId}/endpoints": {
       "get": {
+        "summary": "Get a list of resolved Custom API endpoints.",
+        "description": "List resolved Custom API endpoints, including not registered endpoints.",
         "operationId": "getEndpoints",
         "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": "status",
             "in": "query",
+            "description": "Filter endpoints by registration status.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -49,6 +56,14 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CustomApiEndpointResult"
+                },
+                "examples": {
+                  "SuccessWithFilter": {
+                    "$ref": "#/components/examples/SuccessWithFilter"
+                  },
+                  "SuccessWithoutFilter": {
+                    "$ref": "#/components/examples/SuccessWithoutFilter"
+                  }
                 }
               }
             }
@@ -59,6 +74,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "InvalidFilterParameter": {
+                    "$ref": "#/components/examples/InvalidFilterParameter"
+                  }
                 }
               }
             }
@@ -78,28 +98,35 @@
     "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})$"
       },
       "EndpointStatus": {
         "type": "string",
         "enum": [
           "active",
           "not_registered"
-        ]
+        ],
+        "example": "active"
       },
       "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"
@@ -118,12 +145,15 @@
             "enum": [
               "active",
               "not_registered"
-            ]
+            ],
+            "example": "not_registered"
           }
         }
       },
       "SiteId": {
         "type": "string",
+        "description": "The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites",
+        "example": "RefArch",
         "maxLength": 32,
         "minLength": 1
       },
@@ -132,22 +162,27 @@
         "properties": {
           "apiName": {
             "type": "string",
+            "example": "loyalty-info",
             "pattern": "^[a-z0-9-]+$"
           },
           "apiVersion": {
             "type": "string",
+            "example": "v1",
             "maxLength": 100
           },
           "cartridgeName": {
             "type": "string",
+            "example": "test_bc_wapi",
             "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
           },
           "endpointPath": {
             "type": "string",
+            "example": "/customers",
             "maxLength": 4000
           },
           "errorReason": {
             "type": "string",
+            "example": "API schema not found.",
             "maxLength": 4000
           },
           "httpMethod": {
@@ -160,19 +195,23 @@
               "PATCH",
               "OPTIONS",
               "HEAD"
-            ]
+            ],
+            "example": "GET"
           },
           "id": {
             "type": "string",
+            "example": "10bd7f2dc40ab7aede7f0d60e5c3a783abcd",
             "maxLength": 36,
             "minLength": 36
           },
           "implementationScript": {
             "type": "string",
+            "example": "script.js",
             "maxLength": 100
           },
           "operationId": {
             "type": "string",
+            "example": "getLoyaltyInfo",
             "maxLength": 100
           },
           "securityScheme": {
@@ -180,10 +219,12 @@
             "enum": [
               "ShopperToken",
               "AmOAuth2"
-            ]
+            ],
+            "example": "ShopperToken"
           },
           "schemaFile": {
             "type": "string",
+            "example": "schema.yaml",
             "maxLength": 100
           },
           "siteId": {
@@ -212,6 +253,7 @@
           },
           "activeCodeVersion": {
             "type": "string",
+            "example": "version1",
             "maxLength": 100,
             "minLength": 1
           }
@@ -223,17 +265,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
           }
         },
@@ -248,16 +298,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"
       },
       "status": {
         "name": "status",
         "in": "query",
+        "description": "Filter endpoints by registration status.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -266,9 +319,62 @@
         }
       }
     },
+    "examples": {
+      "SuccessWithFilter": {
+        "value": {
+          "limit": 1,
+          "total": 2,
+          "filter": {
+            "status": "active"
+          },
+          "data": [
+            {
+              "apiName": "loyalty-info",
+              "apiVersion": "v1",
+              "cartridgeName": "my_cartridge",
+              "endpointPath": "/customers",
+              "status": "active"
+            }
+          ],
+          "activeCodeVersion": "version1"
+        }
+      },
+      "SuccessWithoutFilter": {
+        "value": {
+          "limit": 2,
+          "total": 2,
+          "data": [
+            {
+              "apiName": "loyalty-info",
+              "apiVersion": "v1",
+              "cartridgeName": "my_cartridge",
+              "endpointPath": "/customers",
+              "status": "active"
+            },
+            {
+              "apiName": "loyalty-info",
+              "apiVersion": "v1",
+              "cartridgeName": "null",
+              "endpointPath": "/customers",
+              "errorReason": "Cartridge 'my_cartridge_2' not found.",
+              "status": "not_registered"
+            }
+          ],
+          "activeCodeVersion": "version1"
+        }
+      },
+      "InvalidFilterParameter": {
+        "value": {
+          "title": "Bad Request",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
+          "detail": "Invalid value 'foo' for filter parameter 'status'."
+        }
+      }
+    },
     "securitySchemes": {
       "AmOAuth2": {
         "type": "oauth2",
+        "description": "AccountManager OAuth 2.0 bearer token Authentication.",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
@@ -280,10 +386,8 @@
           "authorizationCode": {
             "authorizationUrl": "https://account.demandware.com/dwsso/oauth2/authorize",
             "tokenUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
-            "scopes": {
-              "sfcc.custom-apis": "Custom APIs READONLY scope",
-              "sfcc.custom-apis.rw": "Custom APIs scope"
-            }
+            "refreshUrl": "https://account.demandware.com/dwsso/oauth2/access_token",
+            "scopes": {}
           }
         }
       }