@salesforce/b2c-tooling-sdk 0.0.7 → 0.1.0

package/dist/esm/clients/scapi-schemas.generated.d.ts

@@ -0,0 +1,328 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/organizations/{organizationId}/schemas": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a list of available SCAPI schemas.
+         * @description List available SCAPI schema definitions with optional filtering by API family, name, version, or status.
+         */
+        get: operations["getSchemas"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a specific SCAPI schema.
+         * @description Retrieve the detailed OpenAPI schema specification for a specific SCAPI API.
+         */
+        get: operations["getSchema"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * @description An identifier for the organization the request is being made by
+         * @example f_ecom_zzxy_prd
+         */
+        OrganizationId: string;
+        /**
+         * @example current
+         * @enum {string}
+         */
+        SchemaStatus: "current" | "deprecated";
+        /**
+         * 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).
+         * @default 10
+         * @example 10
+         */
+        Limit: number;
+        /**
+         * 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.
+         * @default 0
+         * @example 10
+         */
+        Total: number;
+        /** @description Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. */
+        ResultBase: {
+            limit: components["schemas"]["Limit"];
+            total: components["schemas"]["Total"];
+        };
+        SchemaListFilter: {
+            /** @example shopper */
+            apiFamily?: string;
+            /** @example products */
+            apiName?: string;
+            /** @example v1 */
+            apiVersion?: string;
+            status?: components["schemas"]["SchemaStatus"];
+        };
+        SchemaListItem: {
+            /**
+             * @description Semantic version of the schema (e.g., "1.0.0")
+             * @example 1.0.0
+             */
+            schemaVersion?: string;
+            /**
+             * @description The API family (e.g., shopper, admin)
+             * @example shopper
+             */
+            apiFamily?: string;
+            /**
+             * @description The API name (e.g., products, orders)
+             * @example products
+             */
+            apiName?: string;
+            /**
+             * @description The API version (e.g., v1)
+             * @example v1
+             */
+            apiVersion?: string;
+            status?: components["schemas"]["SchemaStatus"];
+            /**
+             * @description URL to the schema detail endpoint
+             * @example /organizations/f_ecom_zzxy_prd/schemas/shopper/products/v1
+             */
+            link?: string;
+        };
+        SchemaListResult: {
+            filter?: components["schemas"]["SchemaListFilter"];
+            data?: components["schemas"]["SchemaListItem"][];
+        } & components["schemas"]["ResultBase"];
+        /** @description An OpenAPI 3.0 schema specification */
+        OpenApiSchema: {
+            /**
+             * @description OpenAPI version
+             * @example 3.0.3
+             */
+            openapi?: string;
+            info?: {
+                title?: string;
+                version?: string;
+                description?: string;
+            } & {
+                [key: string]: unknown;
+            };
+            paths?: {
+                [key: string]: unknown;
+            };
+            components?: {
+                [key: string]: unknown;
+            };
+        } & {
+            [key: string]: unknown;
+        };
+        ErrorResponse: {
+            /**
+             * @description A short, human-readable summary of the problem type.
+             * @example Bad Request
+             */
+            title: string;
+            /**
+             * @description A URI reference that identifies the problem type.
+             * @example https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request
+             */
+            type: string;
+            /**
+             * @description A human-readable explanation specific to this occurrence of the problem.
+             * @example Invalid value for filter parameter.
+             */
+            detail: string;
+            /** @description A URI reference that identifies the specific occurrence of the problem. */
+            instance?: string;
+        } & {
+            [key: string]: unknown;
+        };
+    };
+    responses: never;
+    parameters: {
+        /**
+         * @description An identifier for the organization the request is being made by
+         * @example f_ecom_zzxy_prd
+         */
+        organizationId: components["schemas"]["OrganizationId"];
+        /** @description Filter by API family (e.g., shopper, admin) */
+        apiFamily: string;
+        /** @description Filter by API name (e.g., products, orders) */
+        apiName: string;
+        /** @description Filter by API version (e.g., v1) */
+        apiVersion: string;
+        /** @description Filter by schema status */
+        status: components["schemas"]["SchemaStatus"];
+        /** @description The API family (e.g., shopper, admin) */
+        apiFamilyPath: string;
+        /** @description The API name (e.g., products, orders) */
+        apiNamePath: string;
+        /** @description The API version (e.g., v1) */
+        apiVersionPath: string;
+        /** @description Comma-separated list of sections to expand (e.g., "custom_properties") */
+        expand: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    getSchemas: {
+        parameters: {
+            query?: {
+                /** @description Filter by API family (e.g., shopper, admin) */
+                apiFamily?: components["parameters"]["apiFamily"];
+                /** @description Filter by API name (e.g., products, orders) */
+                apiName?: components["parameters"]["apiName"];
+                /** @description Filter by API version (e.g., v1) */
+                apiVersion?: components["parameters"]["apiVersion"];
+                /** @description Filter by schema status */
+                status?: components["parameters"]["status"];
+            };
+            header?: never;
+            path: {
+                /**
+                 * @description An identifier for the organization the request is being made by
+                 * @example f_ecom_zzxy_prd
+                 */
+                organizationId: components["parameters"]["organizationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful operation */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SchemaListResult"];
+                };
+            };
+            /** @description Invalid or malformed filter parameter */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Unauthorized - invalid or missing authentication */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Forbidden - insufficient permissions */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getSchema: {
+        parameters: {
+            query?: {
+                /** @description Comma-separated list of sections to expand (e.g., "custom_properties") */
+                expand?: components["parameters"]["expand"];
+            };
+            header?: never;
+            path: {
+                /**
+                 * @description An identifier for the organization the request is being made by
+                 * @example f_ecom_zzxy_prd
+                 */
+                organizationId: components["parameters"]["organizationId"];
+                /** @description The API family (e.g., shopper, admin) */
+                apiFamily: components["parameters"]["apiFamilyPath"];
+                /** @description The API name (e.g., products, orders) */
+                apiName: components["parameters"]["apiNamePath"];
+                /** @description The API version (e.g., v1) */
+                apiVersion: components["parameters"]["apiVersionPath"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful operation - returns OpenAPI schema */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OpenApiSchema"];
+                };
+            };
+            /** @description Invalid parameter value */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Unauthorized - invalid or missing authentication */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Forbidden - insufficient permissions */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Schema not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+}

package/dist/esm/clients/scapi-schemas.generated.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=scapi-schemas.generated.js.map

package/dist/esm/clients/scapi-schemas.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-schemas.generated.js","sourceRoot":"","sources":["../../../src/clients/scapi-schemas.generated.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/clients/scapi-schemas.js

@@ -0,0 +1,95 @@
+/*
+ * 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 API client for B2C Commerce.
+ *
+ * Provides a fully typed client for SCAPI Schemas API operations using
+ * openapi-fetch with OAuth authentication middleware. Used for discovering
+ * and retrieving OpenAPI schema specifications for SCAPI APIs.
+ *
+ * @module clients/scapi-schemas
+ */
+import createClient, {} from 'openapi-fetch';
+import { OAuthStrategy } from '../auth/oauth.js';
+import { createAuthMiddleware, createLoggingMiddleware } from './middleware.js';
+import { globalMiddlewareRegistry } from './middleware-registry.js';
+import { toOrganizationId, toTenantId, buildTenantScope } from './custom-apis.js';
+/**
+ * Re-export organization/tenant utilities for convenience.
+ */
+export { toOrganizationId, toTenantId, buildTenantScope };
+/** Default OAuth scopes required for SCAPI Schemas (read-only) */
+export const SCAPI_SCHEMAS_DEFAULT_SCOPES = ['sfcc.scapi-schemas'];
+/**
+ * Creates a typed SCAPI Schemas API client.
+ *
+ * Returns the openapi-fetch client directly, with authentication
+ * handled via middleware. This gives full access to all openapi-fetch
+ * features with type-safe paths, parameters, and responses.
+ *
+ * The client automatically handles OAuth scope requirements:
+ * - Domain scope: `sfcc.scapi-schemas` (or custom via config.scopes)
+ * - Tenant scope: `SALESFORCE_COMMERCE_API:{tenantId}`
+ *
+ * @param config - SCAPI Schemas client configuration including shortCode and tenantId
+ * @param auth - Authentication strategy (typically OAuth)
+ * @returns Typed openapi-fetch client
+ *
+ * @example
+ * // Create SCAPI Schemas client - scopes are handled automatically
+ * const oauthStrategy = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ *
+ * const client = createScapiSchemasClient(
+ *   { shortCode: 'kv7kzm78', tenantId: 'zzxy_prd' },
+ *   oauthStrategy
+ * );
+ *
+ * // List available SCAPI schemas
+ * const { data, error } = await client.GET('/organizations/{organizationId}/schemas', {
+ *   params: {
+ *     path: { organizationId: toOrganizationId('zzxy_prd') }
+ *   }
+ * });
+ *
+ * // Get a specific schema
+ * const { data: schema } = await client.GET(
+ *   '/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}',
+ *   {
+ *     params: {
+ *       path: {
+ *         organizationId: toOrganizationId('zzxy_prd'),
+ *         apiFamily: 'shopper',
+ *         apiName: 'products',
+ *         apiVersion: 'v1'
+ *       },
+ *       query: { expand: 'custom_properties' }
+ *     }
+ *   }
+ * );
+ */
+export function createScapiSchemasClient(config, auth) {
+    const registry = config.middlewareRegistry ?? globalMiddlewareRegistry;
+    const client = createClient({
+        baseUrl: `https://${config.shortCode}.api.commercecloud.salesforce.com/dx/scapi-schemas/v1`,
+    });
+    // Build required scopes: domain scope + tenant-specific scope
+    const requiredScopes = config.scopes ?? [...SCAPI_SCHEMAS_DEFAULT_SCOPES, buildTenantScope(config.tenantId)];
+    // If OAuth strategy, add required scopes; otherwise use as-is
+    const scopedAuth = auth instanceof OAuthStrategy ? auth.withAdditionalScopes(requiredScopes) : auth;
+    // Core middleware: auth first
+    client.use(createAuthMiddleware(scopedAuth));
+    // Plugin middleware from registry
+    for (const middleware of registry.getMiddleware('scapi-schemas')) {
+        client.use(middleware);
+    }
+    // Logging middleware last (sees complete request with all modifications)
+    client.use(createLoggingMiddleware('SCAPI-SCHEMAS'));
+    return client;
+}
+//# sourceMappingURL=scapi-schemas.js.map

package/dist/esm/clients/scapi-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-schemas.js","sourceRoot":"","sources":["../../../src/clients/scapi-schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;GAQG;AACH,OAAO,YAAY,EAAE,EAAa,MAAM,eAAe,CAAC;AAExD,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAC,wBAAwB,EAA0B,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAC,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAOhF;;GAEG;AACH,OAAO,EAAC,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAC,CAAC;AAkCxD,kEAAkE;AAClE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAgC,EAAE,IAAkB;IAC3F,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,uDAAuD;KAC5F,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,4BAA4B,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE7G,8DAA8D;IAC9D,MAAM,UAAU,GAAG,IAAI,YAAY,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEpG,8BAA8B;IAC9B,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7C,kCAAkC;IAClC,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,eAAe,CAAC,CAAC,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,150 @@
+/**
+ * OpenAPI schema collapsing utilities for agentic clients.
+ *
+ * These utilities implement a three-tier disclosure model for OpenAPI schemas:
+ * - **Collapsed** (default): Show structure only - paths as method names, schemas as keys
+ * - **Selective expansion**: Full details for specific items only
+ * - **Full expansion**: Complete schema without any collapsing
+ *
+ * This approach addresses context length concerns when working with large OpenAPI
+ * schemas in agentic/LLM contexts.
+ *
+ * @module operations/scapi-schemas/collapse
+ */
+/**
+ * Options for collapsing an OpenAPI schema.
+ */
+export interface SchemaCollapseOptions {
+    /**
+     * Paths to fully expand (e.g., ["/products", "/orders"]).
+     * When provided, only these paths will have full operation details.
+     * Other paths will show only their HTTP method names.
+     */
+    expandPaths?: string[];
+    /**
+     * Schema names to fully expand (e.g., ["Product", "Order"]).
+     * When provided, only these schemas will have full definitions.
+     * Other schemas will be shown as empty objects.
+     */
+    expandSchemas?: string[];
+    /**
+     * Example names to fully expand (e.g., ["ProductExample"]).
+     * When provided, only these examples will have full content.
+     * Other examples will be shown as empty objects.
+     */
+    expandExamples?: string[];
+}
+/**
+ * Represents an OpenAPI 3.x schema structure.
+ * This is a simplified type that captures the structure we need for collapsing.
+ */
+export interface OpenApiSchemaInput {
+    openapi?: string;
+    info?: Record<string, unknown>;
+    servers?: unknown[];
+    paths?: Record<string, Record<string, unknown>>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        examples?: Record<string, unknown>;
+        parameters?: Record<string, unknown>;
+        responses?: Record<string, unknown>;
+        requestBodies?: Record<string, unknown>;
+        headers?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+        links?: Record<string, unknown>;
+        callbacks?: Record<string, unknown>;
+    };
+    security?: unknown[];
+    tags?: unknown[];
+    externalDocs?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Represents a collapsed path entry.
+ * When collapsed, a path only shows the HTTP methods it supports.
+ */
+export type CollapsedPath = string[] | Record<string, unknown>;
+/**
+ * The output schema structure after collapsing.
+ */
+export interface CollapsedOpenApiSchema {
+    openapi?: string;
+    info?: Record<string, unknown>;
+    servers?: unknown[];
+    paths?: Record<string, CollapsedPath>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        examples?: Record<string, unknown>;
+        parameters?: Record<string, unknown>;
+        responses?: Record<string, unknown>;
+        requestBodies?: Record<string, unknown>;
+        headers?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+        links?: Record<string, unknown>;
+        callbacks?: Record<string, unknown>;
+    };
+    security?: unknown[];
+    tags?: unknown[];
+    externalDocs?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function collapseOpenApiSchema(schema: OpenApiSchemaInput, options?: SchemaCollapseOptions): CollapsedOpenApiSchema;
+/**
+ * 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 declare function isCollapsedSchema(schema: CollapsedOpenApiSchema): boolean;
+/**
+ * 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 declare function getPathKeys(schema: OpenApiSchemaInput | CollapsedOpenApiSchema): string[];
+/**
+ * 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 declare function getSchemaNames(schema: OpenApiSchemaInput | CollapsedOpenApiSchema): string[];
+/**
+ * Gets the list of available example names from a schema.
+ *
+ * @param schema - The OpenAPI schema
+ * @returns Array of example names
+ */
+export declare function getExampleNames(schema: OpenApiSchemaInput | CollapsedOpenApiSchema): string[];