@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.0

package/dist/cjs/scaffold/validators.js

@@ -0,0 +1,334 @@
+/*
+ * 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
+ */
+/** Valid parameter types */
+const VALID_PARAMETER_TYPES = ['string', 'boolean', 'choice', 'multi-choice'];
+/** Reserved variable names that cannot be used as parameter names */
+const RESERVED_NAMES = ['kebabCase', 'camelCase', 'pascalCase', 'snakeCase', 'year', 'date', 'uuid'];
+/** Valid dynamic parameter sources */
+const VALID_SOURCES = ['cartridges', 'hook-points', 'sites'];
+/**
+ * Validate a scaffold manifest
+ * @param manifest - The manifest to validate
+ * @returns Array of validation error messages (empty if valid)
+ */
+export function validateScaffoldManifest(manifest) {
+    const errors = [];
+    if (!manifest || typeof manifest !== 'object') {
+        return ['Manifest must be an object'];
+    }
+    const m = manifest;
+    // Required fields
+    if (!m.name || typeof m.name !== 'string') {
+        errors.push('Manifest must have a "name" field (string)');
+    }
+    else if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(m.name) && m.name.length > 1) {
+        errors.push('Manifest "name" must be kebab-case (lowercase letters, numbers, hyphens)');
+    }
+    if (!m.displayName || typeof m.displayName !== 'string') {
+        errors.push('Manifest must have a "displayName" field (string)');
+    }
+    if (!m.description || typeof m.description !== 'string') {
+        errors.push('Manifest must have a "description" field (string)');
+    }
+    if (!m.category || typeof m.category !== 'string') {
+        errors.push('Manifest must have a "category" field (string)');
+    }
+    // Parameters validation
+    if (!Array.isArray(m.parameters)) {
+        errors.push('Manifest must have a "parameters" array');
+    }
+    else {
+        const paramNames = new Set();
+        for (let i = 0; i < m.parameters.length; i++) {
+            const param = m.parameters[i];
+            const prefix = `parameters[${i}]`;
+            if (!param || typeof param !== 'object') {
+                errors.push(`${prefix}: must be an object`);
+                continue;
+            }
+            const p = param;
+            if (!p.name || typeof p.name !== 'string') {
+                errors.push(`${prefix}: must have a "name" field (string)`);
+            }
+            else {
+                if (!/^[a-z][a-zA-Z0-9]*$/.test(p.name)) {
+                    errors.push(`${prefix}: "name" must be camelCase (start with lowercase letter)`);
+                }
+                if (paramNames.has(p.name)) {
+                    errors.push(`${prefix}: duplicate parameter name "${p.name}"`);
+                }
+                if (RESERVED_NAMES.includes(p.name)) {
+                    errors.push(`${prefix}: "${p.name}" is a reserved name`);
+                }
+                paramNames.add(p.name);
+            }
+            if (!p.prompt || typeof p.prompt !== 'string') {
+                errors.push(`${prefix}: must have a "prompt" field (string)`);
+            }
+            if (!p.type || typeof p.type !== 'string') {
+                errors.push(`${prefix}: must have a "type" field (string)`);
+            }
+            else if (!VALID_PARAMETER_TYPES.includes(p.type)) {
+                errors.push(`${prefix}: "type" must be one of: ${VALID_PARAMETER_TYPES.join(', ')}`);
+            }
+            if (typeof p.required !== 'boolean') {
+                errors.push(`${prefix}: must have a "required" field (boolean)`);
+            }
+            // Source validation
+            if (p.source !== undefined) {
+                if (typeof p.source !== 'string') {
+                    errors.push(`${prefix}: "source" must be a string`);
+                }
+                else if (!VALID_SOURCES.includes(p.source)) {
+                    errors.push(`${prefix}: "source" must be one of: ${VALID_SOURCES.join(', ')}`);
+                }
+            }
+            // Choice validation (choices are optional if source is provided)
+            if ((p.type === 'choice' || p.type === 'multi-choice') && !Array.isArray(p.choices) && !p.source) {
+                errors.push(`${prefix}: choice/multi-choice types must have a "choices" array or a "source" field`);
+            }
+            else if (Array.isArray(p.choices)) {
+                for (let j = 0; j < p.choices.length; j++) {
+                    const choice = p.choices[j];
+                    if (!choice || typeof choice !== 'object') {
+                        errors.push(`${prefix}.choices[${j}]: must be an object`);
+                    }
+                    else {
+                        if (!choice.value || typeof choice.value !== 'string') {
+                            errors.push(`${prefix}.choices[${j}]: must have a "value" field (string)`);
+                        }
+                        if (!choice.label || typeof choice.label !== 'string') {
+                            errors.push(`${prefix}.choices[${j}]: must have a "label" field (string)`);
+                        }
+                    }
+                }
+            }
+            // Pattern validation
+            if (p.pattern !== undefined && typeof p.pattern !== 'string') {
+                errors.push(`${prefix}: "pattern" must be a string`);
+            }
+            else if (typeof p.pattern === 'string') {
+                try {
+                    new RegExp(p.pattern);
+                }
+                catch {
+                    errors.push(`${prefix}: "pattern" is not a valid regex`);
+                }
+            }
+        }
+    }
+    // Files validation (optional)
+    if (m.files !== undefined) {
+        if (!Array.isArray(m.files)) {
+            errors.push('Manifest "files" must be an array');
+        }
+        else {
+            for (let i = 0; i < m.files.length; i++) {
+                const file = m.files[i];
+                const prefix = `files[${i}]`;
+                if (!file || typeof file !== 'object') {
+                    errors.push(`${prefix}: must be an object`);
+                    continue;
+                }
+                if (!file.template || typeof file.template !== 'string') {
+                    errors.push(`${prefix}: must have a "template" field (string)`);
+                }
+                if (!file.destination || typeof file.destination !== 'string') {
+                    errors.push(`${prefix}: must have a "destination" field (string)`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Check if a condition expression is satisfied
+ * @param condition - The condition expression (e.g., "paramName=value" or "paramName")
+ * @param variables - The current variable values
+ * @returns Whether the condition is satisfied
+ */
+export function evaluateCondition(condition, variables) {
+    if (!condition) {
+        return true;
+    }
+    // Handle equality check: "paramName=value"
+    if (condition.includes('=')) {
+        const [paramName, expectedValue] = condition.split('=', 2);
+        const actualValue = variables[paramName];
+        if (Array.isArray(actualValue)) {
+            return actualValue.includes(expectedValue);
+        }
+        return String(actualValue) === expectedValue;
+    }
+    // Handle negation: "!paramName"
+    if (condition.startsWith('!')) {
+        const paramName = condition.slice(1);
+        const value = variables[paramName];
+        return !value || value === '' || (Array.isArray(value) && value.length === 0);
+    }
+    // Handle truthy check: "paramName"
+    const value = variables[condition];
+    return Boolean(value) && value !== '' && !(Array.isArray(value) && value.length === 0);
+}
+/**
+ * Validate parameter values against a manifest
+ * @param manifest - The scaffold manifest
+ * @param values - The parameter values to validate
+ * @returns Validation result
+ */
+export function validateParameters(manifest, values) {
+    const errors = [];
+    const resolvedValues = {};
+    for (const param of manifest.parameters) {
+        // Check if this parameter should be evaluated (based on `when` condition)
+        if (param.when && !evaluateCondition(param.when, resolvedValues)) {
+            // Parameter is conditional and condition not met - skip it
+            continue;
+        }
+        let value = values[param.name];
+        // Use default if not provided
+        if (value === undefined || value === '') {
+            if (param.default !== undefined) {
+                value = param.default;
+            }
+        }
+        // Required check
+        if (param.required) {
+            const isEmpty = value === undefined || value === '' || (Array.isArray(value) && value.length === 0);
+            if (isEmpty) {
+                errors.push({
+                    parameter: param.name,
+                    message: `"${param.name}" is required`,
+                    value,
+                });
+                continue;
+            }
+        }
+        // Type-specific validation
+        if (value !== undefined && value !== '') {
+            switch (param.type) {
+                case 'boolean':
+                    if (typeof value !== 'boolean' && value !== 'true' && value !== 'false') {
+                        errors.push({
+                            parameter: param.name,
+                            message: `"${param.name}" must be a boolean`,
+                            value,
+                        });
+                    }
+                    else {
+                        // Normalize to boolean
+                        resolvedValues[param.name] = value === true || value === 'true';
+                    }
+                    break;
+                case 'string':
+                    if (typeof value !== 'string') {
+                        errors.push({
+                            parameter: param.name,
+                            message: `"${param.name}" must be a string`,
+                            value,
+                        });
+                    }
+                    else {
+                        // Pattern validation
+                        if (param.pattern) {
+                            const regex = new RegExp(param.pattern);
+                            if (!regex.test(value)) {
+                                errors.push({
+                                    parameter: param.name,
+                                    message: param.validationMessage || `"${param.name}" does not match required pattern`,
+                                    value,
+                                });
+                            }
+                        }
+                        resolvedValues[param.name] = value;
+                    }
+                    break;
+                case 'choice':
+                    if (typeof value !== 'string') {
+                        errors.push({
+                            parameter: param.name,
+                            message: `"${param.name}" must be a string`,
+                            value,
+                        });
+                    }
+                    else if (param.choices) {
+                        const validValues = param.choices.map((c) => c.value);
+                        if (!validValues.includes(value)) {
+                            errors.push({
+                                parameter: param.name,
+                                message: `"${param.name}" must be one of: ${validValues.join(', ')}`,
+                                value,
+                            });
+                        }
+                        else {
+                            resolvedValues[param.name] = value;
+                        }
+                    }
+                    break;
+                case 'multi-choice':
+                    {
+                        const arr = Array.isArray(value) ? value : [String(value)];
+                        if (param.choices) {
+                            const validValues = param.choices.map((c) => c.value);
+                            for (const v of arr) {
+                                if (!validValues.includes(v)) {
+                                    errors.push({
+                                        parameter: param.name,
+                                        message: `"${param.name}" contains invalid value "${v}". Must be one of: ${validValues.join(', ')}`,
+                                        value,
+                                    });
+                                }
+                            }
+                        }
+                        resolvedValues[param.name] = arr;
+                    }
+                    break;
+            }
+        }
+        else if (value !== undefined) {
+            // Value is defined but empty - still store it if not required
+            if (param.type === 'multi-choice') {
+                resolvedValues[param.name] = [];
+            }
+            else if (param.type === 'boolean') {
+                resolvedValues[param.name] = false;
+            }
+            else {
+                resolvedValues[param.name] = '';
+            }
+        }
+    }
+    // Preserve any extra variables that aren't manifest parameters
+    // (e.g., cartridgeNamePath set by CLI for cartridge source parameters)
+    const manifestParamNames = new Set(manifest.parameters.map((p) => p.name));
+    for (const [key, value] of Object.entries(values)) {
+        if (!manifestParamNames.has(key) && value !== undefined) {
+            resolvedValues[key] = value;
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        values: resolvedValues,
+    };
+}
+/**
+ * Validate that a string is a valid scaffold name (kebab-case)
+ * @param name - The name to validate
+ * @returns Whether the name is valid
+ */
+export function isValidScaffoldName(name) {
+    return /^[a-z][a-z0-9-]*[a-z0-9]$/.test(name) || /^[a-z]$/.test(name);
+}
+/**
+ * Validate that a string is a valid parameter name (camelCase)
+ * @param name - The name to validate
+ * @returns Whether the name is valid
+ */
+export function isValidParameterName(name) {
+    return /^[a-z][a-zA-Z0-9]*$/.test(name) && !RESERVED_NAMES.includes(name);
+}
+//# sourceMappingURL=validators.js.map

package/dist/cjs/scaffold/validators.js.map

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

package/dist/cjs/telemetry/index.d.ts

@@ -0,0 +1,26 @@
+export type { TelemetryAttributes, TelemetryEventProperties, TelemetryOptions } from './types.js';
+export { Telemetry } from './telemetry.js';
+import { Telemetry } from './telemetry.js';
+import type { TelemetryOptions } from './types.js';
+/**
+ * Factory function to create a Telemetry instance.
+ *
+ * @param options - Telemetry configuration options
+ * @returns A new Telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { createTelemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
+ *
+ * const telemetry = createTelemetry({
+ *   project: 'my-mcp-server',
+ *   appInsightsKey: process.env.APP_INSIGHTS_KEY,
+ *   version: '1.0.0',
+ *   initialAttributes: { environment: 'production' },
+ * });
+ *
+ * await telemetry.start();
+ * telemetry.sendEvent('SERVER_STATUS', { status: 'started' });
+ * ```
+ */
+export declare function createTelemetry(options: TelemetryOptions): Telemetry;

package/dist/cjs/telemetry/index.js

@@ -0,0 +1,32 @@
+/*
+ * 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
+ */
+export { Telemetry } from './telemetry.js';
+import { Telemetry } from './telemetry.js';
+/**
+ * Factory function to create a Telemetry instance.
+ *
+ * @param options - Telemetry configuration options
+ * @returns A new Telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { createTelemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
+ *
+ * const telemetry = createTelemetry({
+ *   project: 'my-mcp-server',
+ *   appInsightsKey: process.env.APP_INSIGHTS_KEY,
+ *   version: '1.0.0',
+ *   initialAttributes: { environment: 'production' },
+ * });
+ *
+ * await telemetry.start();
+ * telemetry.sendEvent('SERVER_STATUS', { status: 'started' });
+ * ```
+ */
+export function createTelemetry(options) {
+    return new Telemetry(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAEzC,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/cjs/telemetry/telemetry.d.ts

@@ -0,0 +1,90 @@
+import type { TelemetryAttributes, TelemetryOptions } from './types.js';
+/**
+ * Telemetry client for sending events to Application Insights.
+ *
+ * @example
+ * ```typescript
+ * const telemetry = new Telemetry({
+ *   project: 'my-app',
+ *   appInsightsKey: 'InstrumentationKey=...',
+ *   version: '1.0.0',
+ *   dataDir: '/path/to/data',
+ * });
+ *
+ * await telemetry.start();
+ * telemetry.sendEvent('USER_ACTION', { action: 'click' });
+ * telemetry.stop();
+ * ```
+ */
+export declare class Telemetry {
+    private attributes;
+    private cliId;
+    private project;
+    private reporter;
+    private sessionId;
+    private started;
+    private version;
+    private appInsightsKey;
+    private traceLog;
+    /**
+     * Check if telemetry is disabled via environment variables.
+     * Supports both SF_DISABLE_TELEMETRY (sf CLI standard) and SFCC_DISABLE_TELEMETRY.
+     */
+    static isDisabled(): boolean;
+    /**
+     * Get the connection string for telemetry, respecting disable flags and env overrides.
+     * @param projectDefault - Default connection string from project config (e.g., package.json)
+     * @returns Connection string to use, or undefined if telemetry should be disabled
+     */
+    static getConnectionString(projectDefault?: string): string | undefined;
+    constructor(options: TelemetryOptions);
+    /**
+     * Add additional attributes to include with all future events.
+     */
+    addAttributes(attributes: TelemetryAttributes): void;
+    /**
+     * Send a telemetry event. Events are buffered until you call {@link flush} or
+     * {@link stop}. Use this for batching; use {@link sendEventAndFlush} when you
+     * need one event sent before continuing.
+     *
+     * @param eventName - Name of the event (e.g., 'SERVER_STATUS', 'TOOL_CALLED')
+     * @param attributes - Event-specific attributes (only string/number/boolean are sent)
+     */
+    sendEvent(eventName: string, attributes?: TelemetryAttributes): void;
+    /**
+     * Send a telemetry event and flush immediately. Use this when you need the event
+     * delivered before continuing (e.g. after a tool call or server lifecycle event),
+     * so you don't have to remember to call {@link flush}. For batching multiple
+     * events and flushing once, use {@link sendEvent} and then {@link flush}.
+     *
+     * @param eventName - Name of the event (e.g., 'SERVER_STATUS', 'TOOL_CALLED')
+     * @param attributes - Event-specific attributes (only string/number/boolean are sent)
+     */
+    sendEventAndFlush(eventName: string, attributes?: TelemetryAttributes): Promise<void>;
+    /**
+     * Send an exception to telemetry.
+     *
+     * @param error - The error to report
+     * @param attributes - Additional attributes to include with the exception
+     */
+    sendException(error: Error, attributes?: TelemetryAttributes): void;
+    /**
+     * Start the telemetry reporter.
+     * Must be called before sending events.
+     */
+    start(): Promise<void>;
+    /**
+     * Flush pending telemetry events without stopping the reporter.
+     * Use this for long-running processes that need to ensure events are sent periodically.
+     * Uses the native reporter.flush() as documented in https://github.com/forcedotcom/telemetry,
+     * and also flushes the App Insights client when present (SDK flush() only flushes O11y).
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the telemetry reporter and flush any pending events.
+     * Includes a delay to allow async HTTP requests to complete.
+     */
+    stop(): Promise<void>;
+    private buildEventProperties;
+    private createReporter;
+}