@salesforce/b2c-tooling-sdk 2.0.0 → 2.1.0

package/specs/storefront-environments-v1.yaml

@@ -0,0 +1,272 @@
+openapi: "3.0.3"
+# ---------------------------------------------------------------------------
+# SCAPI MRT Storefront Environments API (v1) — self-contained bundle.
+#
+# Source of truth: git.soma.salesforce.com/cc-mercury-api/storefront-oas
+#   environments-oas/v1/api_spec/src/environments.yaml
+#
+# The upstream source is a multi-file spec whose $refs resolve component files
+# under src/components/ plus a build-time `dependencies/commerce-cloud-standards-oas`
+# folder (populated by the redocly/maven build, not committed to git). That tree
+# is not directly consumable by openapi-typescript, and every other spec in this
+# repo is a single self-contained file, so this file inlines the referenced
+# components: the standard SCAPI `organizationId`/`storefrontId`/`environmentId`
+# parameters and the RFC 7807 `ErrorResponse` envelope.
+#
+# Scope note: this bundle covers ONLY the environment-variables sub-resource
+# (GET + merge-PATCH), which is what the `mrt env var` commands need. The broader
+# Environments lifecycle surface (list/create/clone/get/update/delete/...) is
+# intentionally omitted; it belongs to a later story. When adding that surface or
+# bumping to a newer upstream version, re-bundle from the same source path.
+# ---------------------------------------------------------------------------
+info:
+  x-api-type: Admin
+  x-api-family: Storefront
+  title: Environments
+  version: 1.0.0
+  description: >-
+    SCAPI Managed Runtime Storefront Environments API. Read and update the
+    environment variables for a storefront environment. Variables are returned
+    with their values masked; updates use merge-PATCH semantics.
+servers:
+  - url: "https://{shortCode}.api.commercecloud.salesforce.com/storefront/environments/v1"
+    variables:
+      shortCode:
+        default: "123456gf"
+paths:
+  /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/environment-variables:
+    get:
+      summary: Get environment variables for an environment.
+      description: >-
+        Retrieves the environment variables configured for the specified
+        environment. Values are returned masked (only the last few characters are
+        visible) and cannot be read back in plaintext.
+      operationId: getEnvironmentVariables
+      parameters:
+        - $ref: "#/components/parameters/organizationId"
+        - $ref: "#/components/parameters/storefrontId"
+        - $ref: "#/components/parameters/environmentId"
+      responses:
+        "200":
+          description: Environment variables successfully retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnvironmentVariables"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "403":
+          $ref: "#/components/responses/403Forbidden"
+        "404":
+          $ref: "#/components/responses/404NotFound"
+      security:
+        - AmOAuth2:
+            - "sfcc.storefront.environments"
+            - "sfcc.storefront.environments.rw"
+    patch:
+      summary: Update environment variables for an environment.
+      description: >-
+        Updates the environment variables using merge-PATCH semantics: a key
+        present in the request is created or replaced; a key with a `null` value is
+        deleted; a key omitted from the request is left unchanged. Returns 204 No
+        Content on success.
+      operationId: updateEnvironmentVariables
+      parameters:
+        - $ref: "#/components/parameters/organizationId"
+        - $ref: "#/components/parameters/storefrontId"
+        - $ref: "#/components/parameters/environmentId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EnvironmentVariablesUpdateRequest"
+      responses:
+        "204":
+          description: Environment variables successfully updated.
+        "400":
+          $ref: "#/components/responses/400BadRequest"
+        "401":
+          $ref: "#/components/responses/401Unauthorized"
+        "403":
+          $ref: "#/components/responses/403Forbidden"
+        "404":
+          $ref: "#/components/responses/404NotFound"
+      security:
+        - AmOAuth2:
+            - "sfcc.storefront.environments.rw"
+components:
+  securitySchemes:
+    AmOAuth2:
+      type: oauth2
+      description: AccountManager OAuth 2.0 bearer token Authentication.
+      flows:
+        clientCredentials:
+          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
+          scopes:
+            sfcc.storefront.environments: Read-only access to the Environments API.
+            sfcc.storefront.environments.rw: Read and write access to the Environments API.
+        authorizationCode:
+          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
+          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
+          scopes:
+            sfcc.storefront.environments: Read-only access to the Environments API.
+            sfcc.storefront.environments.rw: Read and write access to the Environments API.
+  parameters:
+    # Standard SCAPI organization identifier (inlined from
+    # commerce-cloud-standards-oas). For B2C Commerce this is `f_ecom_<tenant>`.
+    organizationId:
+      name: organizationId
+      in: path
+      required: true
+      style: simple
+      explode: false
+      description: The B2C Commerce organization identifier, e.g. `f_ecom_zzxy_prd`.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 32
+    storefrontId:
+      name: storefrontId
+      in: path
+      required: true
+      description: >-
+        The storefront identifier. Must consist only of lowercase letters,
+        numbers, and hyphens, with no leading or trailing hyphens.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 20
+        pattern: "^[a-z0-9]+(?:-+[a-z0-9]+)*$"
+    environmentId:
+      name: environmentId
+      in: path
+      required: true
+      description: >-
+        The environment identifier. Must consist only of lowercase letters,
+        numbers, and hyphens, with no leading or trailing hyphens.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 19
+        pattern: "^[a-z0-9]+(?:-+[a-z0-9]+)*$"
+  responses:
+    401Unauthorized:
+      description: Your access token is invalid or expired and can't be used to identify a user.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    403Forbidden:
+      description: You aren't authorized to perform this action.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    400BadRequest:
+      description: The request was malformed or failed validation.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    404NotFound:
+      description: The requested resource was not found.
+      content:
+        application/problem+json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+  schemas:
+    # Standard SCAPI RFC 7807 error envelope (inlined from commerce-cloud-standards-oas).
+    ErrorResponse:
+      type: object
+      additionalProperties: true
+      properties:
+        title:
+          type: string
+          maxLength: 256
+        type:
+          type: string
+          maxLength: 2048
+        detail:
+          type: string
+        instance:
+          type: string
+          maxLength: 2048
+      required:
+        - detail
+        - title
+        - type
+    PublishingStatus:
+      type: string
+      description: The publishing status of an environment variable.
+      enum:
+        - pending
+        - completed
+        - failed
+      example: "completed"
+    EnvironmentVariableEntry:
+      description: A single environment variable's masked value and metadata.
+      type: object
+      properties:
+        value:
+          type: string
+          nullable: true
+          description: >-
+            The masked value of the environment variable (only the last few
+            characters are visible). Null if no value is set.
+          maxLength: 32768
+          example: "****cret"
+        createdBy:
+          type: string
+          nullable: true
+          description: The email address of the user who created the variable. Null if no user is associated.
+          maxLength: 254
+          example: "dev@example.com"
+        creationDate:
+          type: string
+          format: date-time
+          description: The timestamp when the variable was created.
+          example: "2026-04-08T21:47:28.188965Z"
+        lastModified:
+          type: string
+          format: date-time
+          description: The timestamp when the variable was last modified.
+          example: "2026-04-08T21:47:31.307595Z"
+        lastModifiedBy:
+          type: string
+          nullable: true
+          description: The email address of the user who last modified the variable. Null if no user is associated.
+          maxLength: 254
+          example: "dev@example.com"
+        publishingStatus:
+          $ref: "#/components/schemas/PublishingStatus"
+    EnvironmentVariables:
+      description: >-
+        The environment variables for an environment, keyed by variable name. Each
+        value is an {@link EnvironmentVariableEntry} with a masked value and metadata.
+      type: object
+      additionalProperties:
+        $ref: "#/components/schemas/EnvironmentVariableEntry"
+    EnvironmentVariableUpdateEntry:
+      description: >-
+        A single environment variable update. A `null` value deletes the variable;
+        a string or number value creates or replaces it.
+      type: object
+      required:
+        - value
+      properties:
+        value:
+          nullable: true
+          description: The new value for the variable, or `null` to delete it.
+          oneOf:
+            - type: string
+              maxLength: 32768
+            - type: number
+    EnvironmentVariablesUpdateRequest:
+      description: >-
+        Merge-PATCH request body, keyed by variable name. Present keys are
+        created/replaced, keys with a `null` value are deleted, and omitted keys are
+        left unchanged.
+      type: object
+      additionalProperties:
+        $ref: "#/components/schemas/EnvironmentVariableUpdateEntry"