@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.0

package/dist/esm/telemetry/telemetry.js

@@ -0,0 +1,283 @@
+/*
+ * 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
+ */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { TelemetryReporter } from '@salesforce/telemetry';
+import { getLogger } from '../logging/index.js';
+const generateRandomId = () => randomBytes(20).toString('hex');
+/**
+ * Sanitize attributes to only include string, number, boolean (App Insights–safe).
+ * Aligns with sf CLI telemetry record() validation.
+ */
+function sanitizeAttributes(attributes) {
+    const out = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Get the path to the persistent CLI ID file.
+ * @param dataDir - oclif dataDir for persistent storage
+ */
+const getCliIdPath = (dataDir) => {
+    if (!dataDir)
+        return null;
+    return path.join(dataDir, 'cliid');
+};
+/**
+ * Read or create a persistent CLI ID.
+ * @param dataDir - oclif dataDir for persistent storage
+ */
+const readOrCreateCliId = (dataDir) => {
+    const filePath = getCliIdPath(dataDir);
+    if (!filePath)
+        return generateRandomId();
+    // Try to read existing ID
+    try {
+        if (fs.existsSync(filePath)) {
+            const value = fs.readFileSync(filePath, 'utf8');
+            const trimmed = value?.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    catch {
+        // Fall through to create new
+    }
+    // Create new ID
+    const newId = generateRandomId();
+    try {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        fs.writeFileSync(filePath, newId, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // If we can't persist, still return the generated id
+    }
+    return newId;
+};
+/**
+ * Custom TelemetryReporter that always enables telemetry.
+ * Gating is handled at the instantiation site.
+ */
+class ConfigurableTelemetryReporter extends TelemetryReporter {
+    isSfdxTelemetryEnabled() {
+        return true;
+    }
+}
+/**
+ * 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 class Telemetry {
+    attributes;
+    cliId;
+    project;
+    reporter;
+    sessionId;
+    started;
+    version;
+    appInsightsKey;
+    traceLog;
+    /**
+     * Check if telemetry is disabled via environment variables.
+     * Supports both SF_DISABLE_TELEMETRY (sf CLI standard) and SFCC_DISABLE_TELEMETRY.
+     */
+    static isDisabled() {
+        return process.env.SF_DISABLE_TELEMETRY === 'true' || process.env.SFCC_DISABLE_TELEMETRY === 'true';
+    }
+    /**
+     * 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) {
+        if (Telemetry.isDisabled())
+            return undefined;
+        return process.env.SFCC_APP_INSIGHTS_KEY ?? projectDefault;
+    }
+    constructor(options) {
+        this.project = options.project;
+        this.appInsightsKey = options.appInsightsKey;
+        this.attributes = { ...(options.initialAttributes ?? {}) };
+        this.cliId = readOrCreateCliId(options.dataDir);
+        this.reporter = undefined;
+        this.sessionId = generateRandomId();
+        this.started = false;
+        this.version = options.version ?? '0.0.0';
+        if (process.env.SFCC_TELEMETRY_LOG === 'true') {
+            this.traceLog = getLogger().child({ component: 'telemetry' });
+        }
+    }
+    /**
+     * Add additional attributes to include with all future events.
+     */
+    addAttributes(attributes) {
+        this.traceLog?.debug({ attributes }, 'telemetry addAttributes');
+        this.attributes = { ...this.attributes, ...attributes };
+    }
+    /**
+     * 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, attributes = {}) {
+        try {
+            const name = eventName?.trim() || 'UNKNOWN';
+            this.traceLog?.debug({ event: name, attributes }, 'telemetry sendEvent');
+            const eventProperties = this.buildEventProperties(attributes);
+            this.reporter?.sendTelemetryEvent(name, eventProperties);
+        }
+        catch {
+            // ignore send errors
+        }
+    }
+    /**
+     * 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)
+     */
+    async sendEventAndFlush(eventName, attributes = {}) {
+        this.sendEvent(eventName, attributes);
+        await this.flush();
+    }
+    /**
+     * Send an exception to telemetry.
+     *
+     * @param error - The error to report
+     * @param attributes - Additional attributes to include with the exception
+     */
+    sendException(error, attributes = {}) {
+        try {
+            this.traceLog?.debug({ error: error.name, message: error.message }, 'telemetry sendException');
+            const properties = this.buildEventProperties(sanitizeAttributes(attributes));
+            this.reporter?.sendTelemetryException(error, properties);
+        }
+        catch {
+            // ignore send errors
+        }
+    }
+    /**
+     * Start the telemetry reporter.
+     * Must be called before sending events.
+     */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        // If no key provided, telemetry is disabled
+        if (!this.appInsightsKey)
+            return;
+        this.traceLog?.debug({ project: this.project, sessionId: this.sessionId, cliId: this.cliId.slice(0, 8) + '...' }, 'telemetry start');
+        try {
+            await this.createReporter();
+        }
+        catch {
+            // Best-effort retry after ~1s: first runs can hit transient failures
+            // establishing the Application Insights connection (DNS/proxy/VPN warm-up,
+            // brief network blips, or backend cold start). One short delay usually fixes it.
+            // If the retry still fails, ignore it to avoid impacting the application.
+            try {
+                await this.createReporter();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /**
+     * 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).
+     */
+    async flush() {
+        if (!this.started || !this.reporter)
+            return;
+        await this.reporter.flush();
+        // SDK flush() only flushes O11y; we use App Insights. Flush the underlying client.
+        try {
+            const client = this.reporter.getTelemetryClient();
+            if (client?.flush) {
+                await new Promise((resolve) => {
+                    client.flush({ callback: () => resolve() });
+                });
+            }
+        }
+        catch {
+            // getTelemetryClient() throws if App Insights not initialized
+        }
+    }
+    /**
+     * Stop the telemetry reporter and flush any pending events.
+     * Includes a delay to allow async HTTP requests to complete.
+     */
+    async stop() {
+        if (!this.started)
+            return;
+        this.traceLog?.debug('telemetry stop');
+        this.started = false;
+        this.reporter?.stop();
+        // Allow pending HTTP requests to flush before process exits.
+        // Application Insights SDK sends events asynchronously, so we need
+        // a delay to ensure events reach the server on fast exits.
+        // 300ms gives enough time for the HTTP request to complete even on
+        // cold starts when establishing the initial connection.
+        await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+    buildEventProperties(attributes = {}) {
+        const sanitized = sanitizeAttributes({ ...this.attributes, ...attributes });
+        return {
+            ...sanitized,
+            sessionId: this.sessionId,
+            cliId: this.cliId,
+            version: this.version,
+            platform: process.platform,
+            arch: process.arch,
+            nodeVersion: process.version,
+            nodeEnv: process.env.NODE_ENV,
+            origin: this.project,
+            date: new Date().toUTCString(),
+            timestamp: String(Date.now()),
+            processUptime: process.uptime() * 1000,
+        };
+    }
+    async createReporter() {
+        this.reporter = await ConfigurableTelemetryReporter.create({
+            project: this.project,
+            key: this.appInsightsKey ?? '',
+            userId: this.cliId,
+        });
+        this.reporter.start();
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/esm/telemetry/telemetry.js.map

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

package/dist/esm/telemetry/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Telemetry event attributes - key-value pairs sent with each event.
+ */
+export interface TelemetryAttributes {
+    [key: string]: boolean | number | string | undefined;
+}
+/**
+ * Core properties automatically included with every telemetry event.
+ */
+export interface TelemetryEventProperties extends TelemetryAttributes {
+    /** Unique session identifier (generated per Telemetry instance) */
+    sessionId: string;
+    /** Persistent CLI identifier (stored in {dataDir}/cliid) */
+    cliId: string;
+    /** Package version */
+    version: string;
+    /** Operating system platform (e.g., 'darwin', 'linux', 'win32') */
+    platform: string;
+    /** CPU architecture (e.g., 'x64', 'arm64') */
+    arch: string;
+    /** Node.js version */
+    nodeVersion: string;
+    /** NODE_ENV environment variable value */
+    nodeEnv: string | undefined;
+    /** Project name / origin of the event */
+    origin: string;
+    /** Human-readable UTC date string */
+    date: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: string;
+    /** Process uptime in milliseconds */
+    processUptime: number;
+}
+/**
+ * Options for creating a Telemetry instance.
+ */
+export interface TelemetryOptions {
+    /**
+     * Project identifier used for telemetry reporting.
+     * This is used as the project name in Application Insights.
+     */
+    project: string;
+    /**
+     * Application Insights connection string or instrumentation key.
+     * If not provided, telemetry will be disabled.
+     */
+    appInsightsKey?: string;
+    /**
+     * Initial attributes to include with every telemetry event.
+     */
+    initialAttributes?: TelemetryAttributes;
+    /**
+     * Package version to include in telemetry events.
+     */
+    version?: string;
+    /**
+     * oclif dataDir for persistent CLI ID storage.
+     * If provided, CLI ID is stored in {dataDir}/cliid.
+     * If not provided or non-writable, falls back to random ID.
+     */
+    dataDir?: string;
+}

package/dist/esm/telemetry/types.js

@@ -0,0 +1,7 @@
+/*
+ * 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 {};
+//# sourceMappingURL=types.js.map

package/dist/esm/telemetry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/b2c-tooling-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Core tooling library for Salesforce Commerce Cloud B2C CLI",
   "author": "Charles Lavery",
   "license": "Apache-2.0",
@@ -123,6 +123,50 @@
         "default": "./dist/cjs/operations/logs/index.js"
       }
     },
+    "./operations/users": {
+      "development": "./src/operations/users/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/users/index.d.ts",
+        "default": "./dist/esm/operations/users/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/users/index.d.ts",
+        "default": "./dist/cjs/operations/users/index.js"
+      }
+    },
+    "./operations/roles": {
+      "development": "./src/operations/roles/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/roles/index.d.ts",
+        "default": "./dist/esm/operations/roles/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/roles/index.d.ts",
+        "default": "./dist/cjs/operations/roles/index.js"
+      }
+    },
+    "./operations/orgs": {
+      "development": "./src/operations/orgs/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/orgs/index.d.ts",
+        "default": "./dist/esm/operations/orgs/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/orgs/index.d.ts",
+        "default": "./dist/cjs/operations/orgs/index.js"
+      }
+    },
+    "./operations/content": {
+      "development": "./src/operations/content/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/content/index.d.ts",
+        "default": "./dist/esm/operations/content/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/content/index.d.ts",
+        "default": "./dist/cjs/operations/content/index.js"
+      }
+    },
     "./cli": {
       "development": "./src/cli/index.ts",
       "import": {
@@ -200,6 +244,17 @@
         "default": "./dist/cjs/skills/index.js"
       }
     },
+    "./scaffold": {
+      "development": "./src/scaffold/index.ts",
+      "import": {
+        "types": "./dist/esm/scaffold/index.d.ts",
+        "default": "./dist/esm/scaffold/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/scaffold/index.d.ts",
+        "default": "./dist/cjs/scaffold/index.js"
+      }
+    },
     "./test-utils": {
       "development": "./src/test-utils/index.ts",
       "import": {
@@ -210,6 +265,17 @@
         "types": "./dist/cjs/test-utils/index.d.ts",
         "default": "./dist/cjs/test-utils/index.js"
       }
+    },
+    "./telemetry": {
+      "development": "./src/telemetry/index.ts",
+      "import": {
+        "types": "./dist/esm/telemetry/index.d.ts",
+        "default": "./dist/esm/telemetry/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/telemetry/index.d.ts",
+        "default": "./dist/cjs/telemetry/index.js"
+      }
     }
   },
   "main": "./dist/cjs/index.js",
@@ -229,8 +295,9 @@
     "@tony.ganchev/eslint-plugin-header": "^3.1.11",
     "@types/archiver": "^7.0.0",
     "@types/chai": "^4.3.20",
+    "@types/ejs": "^3.1.5",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^18.19.130",
+    "@types/node": "^22",
     "@types/sinon": "^21.0.0",
     "@types/xml2js": "^0.4.14",
     "c8": "^10.1.3",
@@ -260,23 +327,25 @@
     "node": ">=22.16.0"
   },
   "dependencies": {
-    "archiver": "^7.0.1",
-    "chokidar": "^5.0.0",
-    "cliui": "^9.0.1",
-    "fuse.js": "^7.0.0",
-    "glob": "^13.0.0",
-    "i18next": "^25.6.3",
-    "jszip": "^3.10.1",
-    "minimatch": "^10.1.1",
-    "open": "^11.0.0",
-    "openapi-fetch": "^0.15.0",
-    "pino": "^10.1.0",
-    "pino-pretty": "^13.1.2",
-    "undici": "^7.0.0",
-    "xml2js": "^0.6.2"
+    "@salesforce/telemetry": "6.4.6",
+    "archiver": "7.0.1",
+    "chokidar": "5.0.0",
+    "cliui": "9.0.1",
+    "ejs": "3.1.10",
+    "fuse.js": "7.1.0",
+    "glob": "13.0.0",
+    "i18next": "25.7.4",
+    "jszip": "3.10.1",
+    "minimatch": "10.1.1",
+    "open": "11.0.0",
+    "openapi-fetch": "0.15.0",
+    "pino": "10.1.0",
+    "pino-pretty": "13.1.2",
+    "undici": "7.19.2",
+    "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/mrt-b2c.json -o src/clients/mrt-b2c.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 && openapi-typescript specs/cdn-zones-v1.yaml -o src/clients/cdn-zones.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/mrt-b2c.json -o src/clients/mrt-b2c.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 && openapi-typescript specs/cdn-zones-v1.yaml -o src/clients/cdn-zones.generated.ts && openapi-typescript specs/am-users-api-v1.yaml -o src/clients/am-users-api.generated.ts && openapi-typescript specs/am-roles-api-v1.yaml -o src/clients/am-roles-api.generated.ts && openapi-typescript specs/am-apiclients-api-v1.yaml -o src/clients/am-apiclients-api.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",