@salesforce/b2c-tooling-sdk 0.0.8 → 0.1.0

package/dist/esm/operations/scapi-schemas/collapse.js

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/** HTTP methods that can appear in OpenAPI paths */
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+/**
+ * Collapses an OpenAPI schema for context-efficient representation.
+ *
+ * This function implements a three-tier disclosure model:
+ *
+ * 1. **No options provided (default):**
+ *    - Paths: `{"/products": ["get", "post"]}` (method names only)
+ *    - Schemas: `{"Product": {}}` (keys only)
+ *    - Examples: `{"ProductExample": {}}` (keys only)
+ *
+ * 2. **Selective expansion:**
+ *    - Only specified paths/schemas/examples are fully expanded
+ *    - Everything else remains collapsed
+ *
+ * Non-collapsible sections (info, servers, security, tags, etc.) are preserved as-is.
+ *
+ * @param schema - The OpenAPI schema to collapse
+ * @param options - Options controlling what to expand
+ * @returns The collapsed schema
+ *
+ * @example
+ * // Collapse everything (default behavior)
+ * const collapsed = collapseOpenApiSchema(fullSchema);
+ *
+ * @example
+ * // Expand only /products path and Product schema
+ * const collapsed = collapseOpenApiSchema(fullSchema, {
+ *   expandPaths: ['/products'],
+ *   expandSchemas: ['Product']
+ * });
+ */
+export function collapseOpenApiSchema(schema, options = {}) {
+    const { expandPaths = [], expandSchemas = [], expandExamples = [] } = options;
+    // Start with a shallow copy
+    const result = { ...schema };
+    // Collapse paths
+    if (schema.paths) {
+        result.paths = collapsePaths(schema.paths, expandPaths);
+    }
+    // Collapse components
+    if (schema.components) {
+        result.components = {
+            ...schema.components,
+        };
+        if (schema.components.schemas) {
+            result.components.schemas = collapseSchemas(schema.components.schemas, expandSchemas);
+        }
+        if (schema.components.examples) {
+            result.components.examples = collapseExamples(schema.components.examples, expandExamples);
+        }
+    }
+    return result;
+}
+/**
+ * Collapses path items to show only HTTP method names.
+ *
+ * @param paths - The paths object from an OpenAPI schema
+ * @param expandPaths - Paths to keep fully expanded
+ * @returns Collapsed paths object
+ */
+function collapsePaths(paths, expandPaths) {
+    const result = {};
+    const expandSet = new Set(expandPaths);
+    for (const [pathKey, pathItem] of Object.entries(paths)) {
+        if (expandSet.has(pathKey)) {
+            // Keep full path item for expanded paths
+            result[pathKey] = pathItem;
+        }
+        else {
+            // Collapse to method names only
+            const methods = Object.keys(pathItem).filter((key) => HTTP_METHODS.includes(key));
+            result[pathKey] = methods;
+        }
+    }
+    return result;
+}
+/**
+ * Collapses schemas to show only keys with empty objects.
+ *
+ * @param schemas - The schemas object from components
+ * @param expandSchemas - Schema names to keep fully expanded
+ * @returns Collapsed schemas object
+ */
+function collapseSchemas(schemas, expandSchemas) {
+    const result = {};
+    const expandSet = new Set(expandSchemas);
+    for (const [schemaName, schemaValue] of Object.entries(schemas)) {
+        if (expandSet.has(schemaName)) {
+            // Keep full schema for expanded schemas
+            result[schemaName] = schemaValue;
+        }
+        else {
+            // Collapse to empty object
+            result[schemaName] = {};
+        }
+    }
+    return result;
+}
+/**
+ * Collapses examples to show only keys with empty objects.
+ *
+ * @param examples - The examples object from components
+ * @param expandExamples - Example names to keep fully expanded
+ * @returns Collapsed examples object
+ */
+function collapseExamples(examples, expandExamples) {
+    const result = {};
+    const expandSet = new Set(expandExamples);
+    for (const [exampleName, exampleValue] of Object.entries(examples)) {
+        if (expandSet.has(exampleName)) {
+            // Keep full example for expanded examples
+            result[exampleName] = exampleValue;
+        }
+        else {
+            // Collapse to empty object
+            result[exampleName] = {};
+        }
+    }
+    return result;
+}
+/**
+ * Checks if a schema has been collapsed (i.e., is in outline form).
+ *
+ * @param schema - The schema to check
+ * @returns true if paths are collapsed (arrays) or schemas are empty objects
+ */
+export function isCollapsedSchema(schema) {
+    // Check if any path is collapsed (array of methods instead of full path item)
+    if (schema.paths) {
+        for (const pathItem of Object.values(schema.paths)) {
+            if (Array.isArray(pathItem)) {
+                return true;
+            }
+        }
+    }
+    // Check if any schema is collapsed (empty object)
+    if (schema.components?.schemas) {
+        for (const schemaValue of Object.values(schema.components.schemas)) {
+            if (typeof schemaValue === 'object' && schemaValue !== null && Object.keys(schemaValue).length === 0) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Gets the list of available path keys from a schema.
+ *
+ * @param schema - The OpenAPI schema
+ * @returns Array of path keys (e.g., ["/products", "/orders"])
+ */
+export function getPathKeys(schema) {
+    return schema.paths ? Object.keys(schema.paths) : [];
+}
+/**
+ * Gets the list of available schema names from a schema.
+ *
+ * @param schema - The OpenAPI schema
+ * @returns Array of schema names (e.g., ["Product", "Order"])
+ */
+export function getSchemaNames(schema) {
+    return schema.components?.schemas ? Object.keys(schema.components.schemas) : [];
+}
+/**
+ * Gets the list of available example names from a schema.
+ *
+ * @param schema - The OpenAPI schema
+ * @returns Array of example names
+ */
+export function getExampleNames(schema) {
+    return schema.components?.examples ? Object.keys(schema.components.examples) : [];
+}
+//# sourceMappingURL=collapse.js.map

package/dist/esm/operations/scapi-schemas/collapse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collapse.js","sourceRoot":"","sources":["../../../../src/operations/scapi-schemas/collapse.ts"],"names":[],"mappings":"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"}

package/dist/esm/operations/scapi-schemas/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SCAPI Schemas operations for B2C Commerce.
+ *
+ * Provides utilities for working with SCAPI OpenAPI schemas, including
+ * collapsing large schemas for context-efficient representation in
+ * agentic/LLM scenarios.
+ *
+ * ## Schema Collapsing
+ *
+ * Use {@link collapseOpenApiSchema} to reduce the size of large OpenAPI schemas
+ * while preserving structure for discovery:
+ *
+ * ```typescript
+ * import { collapseOpenApiSchema } from '@salesforce/b2c-tooling-sdk/operations/scapi-schemas';
+ *
+ * // Collapse to outline form (default)
+ * const collapsed = collapseOpenApiSchema(fullSchema);
+ * // Result: paths show only ["get", "post"], schemas show only {}
+ *
+ * // Selectively expand specific items
+ * const collapsed = collapseOpenApiSchema(fullSchema, {
+ *   expandPaths: ['/products/search'],
+ *   expandSchemas: ['Product', 'SearchResult']
+ * });
+ * ```
+ *
+ * ## Utility Functions
+ *
+ * Helper functions for inspecting schemas:
+ *
+ * ```typescript
+ * import {
+ *   getPathKeys,
+ *   getSchemaNames,
+ *   isCollapsedSchema
+ * } from '@salesforce/b2c-tooling-sdk/operations/scapi-schemas';
+ *
+ * // Get available paths
+ * const paths = getPathKeys(schema); // ["/products", "/orders", ...]
+ *
+ * // Get available schemas
+ * const schemas = getSchemaNames(schema); // ["Product", "Order", ...]
+ *
+ * // Check if schema is collapsed
+ * if (isCollapsedSchema(schema)) {
+ *   console.log('Schema is in collapsed form');
+ * }
+ * ```
+ *
+ * @module operations/scapi-schemas
+ */
+export { collapseOpenApiSchema, isCollapsedSchema, getPathKeys, getSchemaNames, getExampleNames } from './collapse.js';
+export type { SchemaCollapseOptions, OpenApiSchemaInput, CollapsedOpenApiSchema, CollapsedPath } from './collapse.js';

package/dist/esm/operations/scapi-schemas/index.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * SCAPI Schemas operations for B2C Commerce.
+ *
+ * Provides utilities for working with SCAPI OpenAPI schemas, including
+ * collapsing large schemas for context-efficient representation in
+ * agentic/LLM scenarios.
+ *
+ * ## Schema Collapsing
+ *
+ * Use {@link collapseOpenApiSchema} to reduce the size of large OpenAPI schemas
+ * while preserving structure for discovery:
+ *
+ * ```typescript
+ * import { collapseOpenApiSchema } from '@salesforce/b2c-tooling-sdk/operations/scapi-schemas';
+ *
+ * // Collapse to outline form (default)
+ * const collapsed = collapseOpenApiSchema(fullSchema);
+ * // Result: paths show only ["get", "post"], schemas show only {}
+ *
+ * // Selectively expand specific items
+ * const collapsed = collapseOpenApiSchema(fullSchema, {
+ *   expandPaths: ['/products/search'],
+ *   expandSchemas: ['Product', 'SearchResult']
+ * });
+ * ```
+ *
+ * ## Utility Functions
+ *
+ * Helper functions for inspecting schemas:
+ *
+ * ```typescript
+ * import {
+ *   getPathKeys,
+ *   getSchemaNames,
+ *   isCollapsedSchema
+ * } from '@salesforce/b2c-tooling-sdk/operations/scapi-schemas';
+ *
+ * // Get available paths
+ * const paths = getPathKeys(schema); // ["/products", "/orders", ...]
+ *
+ * // Get available schemas
+ * const schemas = getSchemaNames(schema); // ["Product", "Order", ...]
+ *
+ * // Check if schema is collapsed
+ * if (isCollapsedSchema(schema)) {
+ *   console.log('Schema is in collapsed form');
+ * }
+ * ```
+ *
+ * @module operations/scapi-schemas
+ */
+// Collapse utilities
+export { collapseOpenApiSchema, isCollapsedSchema, getPathKeys, getSchemaNames, getExampleNames } from './collapse.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/operations/scapi-schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/scapi-schemas/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,qBAAqB;AACrB,OAAO,EAAC,qBAAqB,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAC,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/b2c-tooling-sdk",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "Core tooling library for Salesforce Commerce Cloud B2C CLI",
   "author": "Charles Lavery",
   "license": "Apache-2.0",
@@ -123,6 +123,17 @@
         "default": "./dist/cjs/operations/docs/index.js"
       }
     },
+    "./operations/scapi-schemas": {
+      "development": "./src/operations/scapi-schemas/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/scapi-schemas/index.d.ts",
+        "default": "./dist/esm/operations/scapi-schemas/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/scapi-schemas/index.d.ts",
+        "default": "./dist/cjs/operations/scapi-schemas/index.js"
+      }
+    },
     "./cli": {
       "development": "./src/cli/index.ts",
       "import": {
@@ -253,7 +264,7 @@
     "xml2js": "^0.6.2"
   },
   "scripts": {
-    "generate:types": "openapi-typescript specs/data-api.json -o src/clients/ocapi.generated.ts && openapi-typescript specs/slas-admin-v1.yaml -o src/clients/slas-admin.generated.ts && openapi-typescript specs/ods-api-v1.json -o src/clients/ods.generated.ts && openapi-typescript specs/mrt-api-v1.json -o src/clients/mrt.generated.ts && openapi-typescript specs/custom-apis-v1.yaml -o src/clients/custom-apis.generated.ts",
+    "generate:types": "openapi-typescript specs/data-api.json -o src/clients/ocapi.generated.ts && openapi-typescript specs/slas-admin-v1.yaml -o src/clients/slas-admin.generated.ts && openapi-typescript specs/ods-api-v1.json -o src/clients/ods.generated.ts && openapi-typescript specs/mrt-api-v1.json -o src/clients/mrt.generated.ts && openapi-typescript specs/custom-apis-v1.yaml -o src/clients/custom-apis.generated.ts && openapi-typescript specs/scapi-schemas-v1.yaml -o src/clients/scapi-schemas.generated.ts",
     "build": "pnpm run generate:types && pnpm run build:esm && pnpm run build:cjs",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",

package/specs/scapi-schemas-v1.yaml

@@ -0,0 +1,341 @@
+openapi: 3.0.3
+info:
+  x-api-type: Admin
+  x-api-family: DX
+  title: SCAPI Schemas
+  version: 1.0.0
+  description: |-
+    [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/scapi-schemas/scapi-schemas-oas-v1-public.yaml)
+
+    # API Overview
+
+    The SCAPI Schemas API provides access to OpenAPI schema definitions for Salesforce Commerce APIs (SCAPI). This API enables discovery and cataloging of available SCAPI endpoints, schema validation and code generation, version management for migration planning, and integration of schema access into development workflows including CI/CD pipelines and testing automation.
+
+    ## Authentication & Authorization
+
+    The SCAPI Schemas API requires valid authentication and authorization. It uses an Account Manager OAuth 2.0 bearer token for authentication. The necessary scope for accessing the API is:
+
+    * `sfcc.scapi-schemas`: Provides read-only access to schema definitions.
+
+    Access is intended for admin users only.
+
+    ## Use Cases
+
+    ### Schema Discovery
+
+    Developers can use this API to discover available SCAPI schemas, filter by API family (e.g., shopper, admin), and retrieve detailed OpenAPI specifications for code generation or documentation purposes.
+
+    ### Custom Property Expansion
+
+    When retrieving a schema, developers can request expansion of custom properties to see tenant-specific customizations applied to standard SCAPI schemas.
+servers:
+  - url: https://{shortCode}.api.commercecloud.salesforce.com/dx/scapi-schemas/v1
+    variables:
+      shortCode:
+        default: shortCode
+paths:
+  /organizations/{organizationId}/schemas:
+    get:
+      summary: Get a list of available SCAPI schemas.
+      description: List available SCAPI schema definitions with optional filtering by API family, name, version, or status.
+      operationId: getSchemas
+      parameters:
+        - $ref: '#/components/parameters/organizationId'
+        - $ref: '#/components/parameters/apiFamily'
+        - $ref: '#/components/parameters/apiName'
+        - $ref: '#/components/parameters/apiVersion'
+        - $ref: '#/components/parameters/status'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SchemaListResult'
+        '400':
+          description: Invalid or malformed filter parameter
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized - invalid or missing authentication
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: Forbidden - insufficient permissions
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - AmOAuth2:
+            - sfcc.scapi-schemas
+  /organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}:
+    get:
+      summary: Get a specific SCAPI schema.
+      description: Retrieve the detailed OpenAPI schema specification for a specific SCAPI API.
+      operationId: getSchema
+      parameters:
+        - $ref: '#/components/parameters/organizationId'
+        - $ref: '#/components/parameters/apiFamilyPath'
+        - $ref: '#/components/parameters/apiNamePath'
+        - $ref: '#/components/parameters/apiVersionPath'
+        - $ref: '#/components/parameters/expand'
+      responses:
+        '200':
+          description: Successful operation - returns OpenAPI schema
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpenApiSchema'
+        '400':
+          description: Invalid parameter value
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized - invalid or missing authentication
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: Forbidden - insufficient permissions
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Schema not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - AmOAuth2:
+            - sfcc.scapi-schemas
+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.scapi-schemas: SCAPI Schemas READONLY scope
+        authorizationCode:
+          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
+          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
+          scopes:
+            sfcc.scapi-schemas: SCAPI Schemas READONLY scope
+  schemas:
+    OrganizationId:
+      description: An identifier for the organization the request is being made by
+      example: f_ecom_zzxy_prd
+      type: string
+      minLength: 1
+      maxLength: 32
+    SchemaStatus:
+      type: string
+      enum:
+        - current
+        - deprecated
+      example: current
+    Limit:
+      default: 10
+      minimum: 1
+      format: int32
+      description: Maximum records to retrieve per request, not to exceed the maximum defined. A limit must be at least 1 so at least one record is returned (if any match the criteria).
+      type: integer
+      example: 10
+    Total:
+      default: 0
+      minimum: 0
+      format: int32
+      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 paginated.
+      type: integer
+      example: 10
+    ResultBase:
+      description: Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema.
+      type: object
+      required:
+        - limit
+        - total
+      properties:
+        limit:
+          maximum: 200
+          allOf:
+            - $ref: '#/components/schemas/Limit'
+        total:
+          $ref: '#/components/schemas/Total'
+    SchemaListFilter:
+      type: object
+      properties:
+        apiFamily:
+          type: string
+          example: shopper
+        apiName:
+          type: string
+          example: products
+        apiVersion:
+          type: string
+          example: v1
+        status:
+          $ref: '#/components/schemas/SchemaStatus'
+    SchemaListItem:
+      type: object
+      properties:
+        schemaVersion:
+          type: string
+          description: Semantic version of the schema (e.g., "1.0.0")
+          example: '1.0.0'
+        apiFamily:
+          type: string
+          description: The API family (e.g., shopper, admin)
+          example: shopper
+        apiName:
+          type: string
+          description: The API name (e.g., products, orders)
+          example: products
+        apiVersion:
+          type: string
+          description: The API version (e.g., v1)
+          example: v1
+        status:
+          $ref: '#/components/schemas/SchemaStatus'
+        link:
+          type: string
+          description: URL to the schema detail endpoint
+          example: /organizations/f_ecom_zzxy_prd/schemas/shopper/products/v1
+    SchemaListResult:
+      type: object
+      allOf:
+        - $ref: '#/components/schemas/ResultBase'
+      properties:
+        filter:
+          $ref: '#/components/schemas/SchemaListFilter'
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/SchemaListItem'
+    OpenApiSchema:
+      type: object
+      description: An OpenAPI 3.0 schema specification
+      additionalProperties: true
+      properties:
+        openapi:
+          type: string
+          description: OpenAPI version
+          example: '3.0.3'
+        info:
+          type: object
+          additionalProperties: true
+          properties:
+            title:
+              type: string
+            version:
+              type: string
+            description:
+              type: string
+        paths:
+          type: object
+          additionalProperties: true
+        components:
+          type: object
+          additionalProperties: true
+    ErrorResponse:
+      type: object
+      additionalProperties: true
+      properties:
+        title:
+          description: A short, human-readable summary of the problem type.
+          type: string
+          maxLength: 256
+          example: Bad Request
+        type:
+          description: A URI reference that identifies the problem type.
+          type: string
+          maxLength: 2048
+          example: https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request
+        detail:
+          description: A human-readable explanation specific to this occurrence of the problem.
+          type: string
+          example: Invalid value for filter parameter.
+        instance:
+          description: A URI reference that identifies the specific occurrence of the problem.
+          type: string
+          maxLength: 2048
+      required:
+        - title
+        - type
+        - detail
+  parameters:
+    organizationId:
+      description: An identifier for the organization the request is being made by
+      name: organizationId
+      in: path
+      required: true
+      example: f_ecom_zzxy_prd
+      schema:
+        $ref: '#/components/schemas/OrganizationId'
+    apiFamily:
+      name: apiFamily
+      in: query
+      required: false
+      description: Filter by API family (e.g., shopper, admin)
+      schema:
+        type: string
+    apiName:
+      name: apiName
+      in: query
+      required: false
+      description: Filter by API name (e.g., products, orders)
+      schema:
+        type: string
+    apiVersion:
+      name: apiVersion
+      in: query
+      required: false
+      description: Filter by API version (e.g., v1)
+      schema:
+        type: string
+    status:
+      name: status
+      in: query
+      required: false
+      description: Filter by schema status
+      schema:
+        $ref: '#/components/schemas/SchemaStatus'
+    apiFamilyPath:
+      name: apiFamily
+      in: path
+      required: true
+      description: The API family (e.g., shopper, admin)
+      schema:
+        type: string
+    apiNamePath:
+      name: apiName
+      in: path
+      required: true
+      description: The API name (e.g., products, orders)
+      schema:
+        type: string
+    apiVersionPath:
+      name: apiVersion
+      in: path
+      required: true
+      description: The API version (e.g., v1)
+      schema:
+        type: string
+    expand:
+      name: expand
+      in: query
+      required: false
+      description: Comma-separated list of sections to expand (e.g., "custom_properties")
+      schema:
+        type: string