@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/configuration/shopper-configurations/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Configurations",
-    "version": "1.4.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-configurations/shopper-configurations-oas-v1-public.yaml)\n\n# API Overview\n\nThe Shopper Configurations API provides cacheable configuration data to shopper-facing applications, enabling them to make decisions based on merchant settings without requiring server-side logic.\n\nThis highly cacheable data encompasses toggles, preferences, and configuration information that allows the application to be reactive to changes performed by the merchant, admin, or support engineer.\n\nConfiguration types include:\n\n- siteConfiguration: Site-specific settings such as name, status, currencies, and locales\n- globalConfiguration: Instance-wide settings such as feature flags\n\n## Authentication & Authorization\n\nThe Shopper Configuration API requires a shopper access token from the Shopper Login and API Access Service (SLAS).\n\nYou must include `sfcc.shopper-configurations` in the client ID used to generate the SLAS 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 details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.\n\n## Customization\n\n### Hooks\n\nYou can extend the Shopper Configurations response with custom data using the `dw.shop.shopper_configuration.modifyGETResponse` hook. This is useful for adding custom site preferences to the response.\n\n```javascript\nexports.modifyGETResponse = function (configResp) {\n  var customPreference = dw.system.Site.getCurrent().getCustomPreferenceValue(\n    \"customerServiceEmail\"\n  );\n  configResp.c_customPrefs = {\n    customerServiceEmail: customPreference || \"noreply@example.com\"\n  };\n};\n```\n\nFor details on hook registration, see [Hook Method Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook-method-details.html). For general information on hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)\n\n## Response Details\n\n### Personalization\n\nResponses from this API are not personalized via the Shopper Context API.\n\n### Caching\n\nCaching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)\n\n### Timeouts\n\nShopper API requests must respond within 10 seconds, including any hook execution. 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### Get Site Configuration\n\nRetrieve site and global configuration settings (name, status, currencies, locales, feature flags).\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/v1/organizations/{organizationId}/configurations?siteId=RefArch\" \\\n  -H \"Authorization: Bearer {access_token}\"\n```\n\n\n### Site Identification and Availability\n\nRetrieve the site's display name and current operational status to determine if the storefront is online, offline, or in a maintenance state for shoppers.\n\n### Currency Configuration\n\nIdentify the default currency for the site and the list of all supported currencies to ensure correct price rendering and multi-currency support.\n\n### Locale and Language Settings\n\nAccess the default locale and the full set of supported locales to localize content, formatting, and language for the shopper's specific region.\n\n### Feature Enablement\n\nView the status of various storefront features and toggles to dynamically enable or disable application logic based on the merchant's active configuration.",
+    "version": "1.4.2",
     "x-api-type": "Shopper",
     "x-api-family": "Configuration"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/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,56 +21,55 @@
   "paths": {
     "/organizations/{organizationId}/configurations": {
       "get": {
+        "summary": "Retrieves configurations",
+        "description": "Retrieves configurations for the specified organization and site.",
         "operationId": "getConfigurations",
         "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": "siteId",
             "in": "query",
+            "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -76,12 +77,14 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -97,6 +100,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/SiteConfiguration"
+                },
+                "examples": {
+                  "ConfigurationsExample": {
+                    "$ref": "#/components/examples/ConfigurationsExample"
+                  }
                 }
               }
             }
@@ -107,6 +115,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperConfigurations400": {
+                    "$ref": "#/components/examples/BadRequest"
+                  }
                 }
               }
             }
@@ -117,6 +130,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperConfigurations401": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -127,6 +145,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperConfigurations404": {
+                    "$ref": "#/components/examples/NotFound"
+                  }
                 }
               }
             }
@@ -153,25 +176,36 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
+        "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})$"
       },
       "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
       },
       "Configuration": {
         "type": "object",
+        "description": "Configuration object",
         "properties": {
           "id": {
             "type": "string",
+            "description": "identifier",
+            "example": "SalesforcePaymentsAllowed",
             "maxLength": 255
           },
           "value": {
+            "description": "value for identifier",
+            "example": true,
             "maxLength": 255
           },
           "configurationType": {
             "type": "string",
+            "description": "type of configuration value",
+            "example": "globalConfiguration",
             "maxLength": 255
           }
         },
@@ -182,9 +216,11 @@
       },
       "SiteConfiguration": {
         "type": "object",
+        "description": "Site Configuration object",
         "properties": {
           "configurations": {
             "type": "array",
+            "description": "List configurations for the instance and site",
             "items": {
               "$ref": "#/components/schemas/Configuration"
             },
@@ -201,17 +237,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
           }
         },
@@ -226,51 +270,48 @@
       "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"
       },
       "siteId": {
         "name": "siteId",
         "in": "query",
+        "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.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/SiteId"
+        },
+        "examples": {
+          "SiteId": {
+            "value": "RefArch"
+          }
         }
       },
       "sfdcUsid": {
         "name": "sfdc_usid",
         "in": "header",
+        "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
         "required": false,
         "style": "simple",
         "explode": false,
         "schema": {
           "type": "string",
-          "format": "uuid"
-        }
-      },
-      "sfdcDwDnt": {
-        "name": "sfdc_dw_dnt",
-        "in": "header",
-        "required": false,
-        "style": "simple",
-        "explode": false,
-        "schema": {
-          "type": "string",
-          "enum": [
-            "0",
-            "1"
-          ]
+          "format": "uuid",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
         }
       },
       "personalized": {
         "name": "personalized",
         "in": "query",
+        "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -278,12 +319,14 @@
           "type": "string",
           "enum": [
             "none"
-          ]
+          ],
+          "example": "none"
         }
       },
       "sfdcShopperContext": {
         "name": "sfdc_shopper_context",
         "in": "header",
+        "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
         "required": false,
         "style": "simple",
         "explode": false,
@@ -292,9 +335,131 @@
         }
       }
     },
+    "examples": {
+      "ConfigurationsExample": {
+        "value": {
+          "configurations": [
+            {
+              "id": "id",
+              "value": "RefArch",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "name",
+              "value": "Ref Arch",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "status",
+              "value": "online",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "timezone",
+              "value": "Etc/UTC",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "timezoneOffset",
+              "value": 0,
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "defaultCurrency",
+              "value": "USD",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "allowedCurrencies",
+              "value": [
+                "USD",
+                "EUR"
+              ],
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "defaultLocale",
+              "value": "en-US",
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "allowedLocales",
+              "value": [
+                {
+                  "id": "en-US",
+                  "country": "US",
+                  "default": true,
+                  "displayCountry": "United States",
+                  "displayLanguage": "English",
+                  "displayName": "English (United States)",
+                  "iso3Country": "USA",
+                  "iso3Language": "eng",
+                  "language": "en",
+                  "name": "English (United States)"
+                },
+                {
+                  "id": "en-CA",
+                  "country": "CA",
+                  "default": false,
+                  "displayCountry": "Canada",
+                  "displayLanguage": "English",
+                  "displayName": "English (Canada)",
+                  "iso3Country": "CAN",
+                  "iso3Language": "eng",
+                  "language": "en",
+                  "name": "English (Canada)"
+                }
+              ],
+              "configurationType": "siteConfiguration"
+            },
+            {
+              "id": "SalesforcePaymentsAllowed",
+              "value": true,
+              "configurationType": "globalConfiguration"
+            },
+            {
+              "id": "gcp",
+              "value": "abc123",
+              "configurationType": "globalConfiguration"
+            }
+          ]
+        }
+      },
+      "BadRequest": {
+        "summary": "Bad Request Error",
+        "description": "Example of a 400 Bad Request error response",
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
+          "title": "Bad Request",
+          "detail": "The request could not be processed due to invalid parameters.",
+          "correlationId": "12345678-1234-1234-1234-123456789012"
+        }
+      },
+      "Unauthorized": {
+        "summary": "Unauthorized Error",
+        "description": "Example of a 401 Unauthorized error response",
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
+          "title": "Unauthorized",
+          "detail": "Your shopper JWT is invalid and cannot be used to identify the API client.",
+          "correlationId": "12345678-1234-1234-1234-123456789012"
+        }
+      },
+      "NotFound": {
+        "summary": "Not Found Error",
+        "description": "Example of a 404 Not Found error response",
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
+          "title": "Not Found",
+          "detail": "Configuration not found for the specified organization and site.",
+          "correlationId": "12345678-1234-1234-1234-123456789012"
+        }
+      }
+    },
     "securitySchemes": {
       "ShopperToken": {
         "type": "oauth2",
+        "description": "Shopper token flow.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
@@ -313,6 +478,7 @@
       },
       "ShopperClientContextToken": {
         "type": "oauth2",
+        "description": "ShopperClientContextToken is a separate security scheme used to track and validate client context information.\nIt is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows.\nFor authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nThis token allows access to Shopper API endpoints for guest shoppers only.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client_context",