@salesforce/telemetry 6.5.2 → 6.6.1

package/README.md

@@ -107,8 +107,8 @@ const reporter = await TelemetryReporter.create({
 reporter.start();
 // Default events use the default schema
 reporter.sendTelemetryEvent('event-name', { foo: 'bar' });
-// PFT or other schema-specific events: pass schema per call
-reporter.sendTelemetryEventWithSchema('pftEventName', { userId: 'user-1', action: 'view' }, pdpEventSchema);
+// Schema-specific events: pass only attributes (must include all fields required by the schema; no properties added by reporter)
+reporter.sendTelemetryEventWithSchema({ userId: 'user-1', action: 'view', eventName: 'pftEventName' }, pdpEventSchema);
 ```
 
 **Note:** `sendTelemetryEventWithSchema` sends only to O11y (not AppInsights). Use it for events that must conform to a given schema; use `sendTelemetryEvent` for all other events.

package/lib/exported.d.ts

@@ -2,4 +2,4 @@ import { TelemetryReporter } from './telemetryReporter';
 export * from './telemetryReporter';
 export { isEnabled } from './enabledCheck';
 export default TelemetryReporter;
-export type { Attributes, O11ySchema, O11yBatchingConfig } from './types';
+export type { Attributes, O11ySchema, O11yBatchingConfig, PdpEvent } from './types';

package/lib/o11yReporter.d.ts

@@ -1,5 +1,5 @@
 import { type BatchingOptions } from '@salesforce/o11y-reporter';
-import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
+import { Attributes, O11ySchema, PdpEvent, Properties, TelemetryOptions } from './types';
 import { BaseReporter } from './baseReporter';
 export declare class O11yReporter extends BaseReporter {
     private service;
@@ -40,12 +40,23 @@ export declare class O11yReporter extends BaseReporter {
      * Use this method when you need to send events that conform to a particular schema
      * (e.g. PFT/pdpEventSchema). Only the events you send via this method use the given schema;
      * all other events use the default schema via sendTelemetryEvent.
+     * Only the caller-provided attributes are sent; no properties (e.g. eventName, common.*)
+     * are added by the reporter.
      *
-     * @param eventName - Name of the event
-     * @param attributes - Properties and measurements to publish alongside the event
-     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     * The schema is the O11y encoding schema (e.g. from the o11y_schema package), not JSON Schema,
+     * so this library does not derive or run validation here. Callers should validate attributes
+     * (e.g. with zod) before calling, using the same schema context they use when importing the schema.
+     *
+     * @param attributes - Properties and measurements to publish (only these are sent; no properties added)
+     * @param schema - O11y encoding schema (e.g. from o11y_schema package)
+     */
+    sendTelemetryEventWithSchema(attributes: Attributes, schema: O11ySchema): Promise<void>;
+    /**
+     * Sends a PDP event via O11y service.
+     *
+     * @param event - PDP event to send.
      */
-    sendTelemetryEventWithSchema(eventName: string, attributes: Attributes, schema: O11ySchema): Promise<void>;
+    sendPdpEvent(event: PdpEvent): Promise<void>;
     flush(): Promise<void>;
     /**
      * Publishes exception to O11y service

package/lib/o11yReporter.js

@@ -17,6 +17,9 @@ exports.O11yReporter = void 0;
  * limitations under the License.
  */
 const o11y_reporter_1 = require("@salesforce/o11y-reporter");
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore o11y_schema/sf_pdp.d.ts is not a valid module
+const sf_pdp_1 = require("o11y_schema/sf_pdp");
 const baseReporter_1 = require("./baseReporter");
 const utils_1 = require("./utils");
 class O11yReporter extends baseReporter_1.BaseReporter {
@@ -88,23 +91,36 @@ class O11yReporter extends baseReporter_1.BaseReporter {
      * Use this method when you need to send events that conform to a particular schema
      * (e.g. PFT/pdpEventSchema). Only the events you send via this method use the given schema;
      * all other events use the default schema via sendTelemetryEvent.
+     * Only the caller-provided attributes are sent; no properties (e.g. eventName, common.*)
+     * are added by the reporter.
      *
-     * @param eventName - Name of the event
-     * @param attributes - Properties and measurements to publish alongside the event
-     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     * The schema is the O11y encoding schema (e.g. from the o11y_schema package), not JSON Schema,
+     * so this library does not derive or run validation here. Callers should validate attributes
+     * (e.g. with zod) before calling, using the same schema context they use when importing the schema.
+     *
+     * @param attributes - Properties and measurements to publish (only these are sent; no properties added)
+     * @param schema - O11y encoding schema (e.g. from o11y_schema package)
      */
-    async sendTelemetryEventWithSchema(eventName, attributes, schema) {
+    async sendTelemetryEventWithSchema(attributes, schema) {
         await this.initialized;
-        const merged = { ...this.commonProperties, ...attributes };
-        const eventData = {
-            eventName: `${this.extensionName}/${eventName}`,
-            ...merged,
-        };
+        const eventData = { ...attributes };
         this.service.logEventWithSchema(eventData, schema);
         if (!this._batchingEnabled) {
             await this.service.forceFlush();
         }
     }
+    /**
+     * Sends a PDP event via O11y service.
+     *
+     * @param event - PDP event to send.
+     */
+    async sendPdpEvent(event) {
+        await this.initialized;
+        this.service.logEventWithSchema(event, sf_pdp_1.pdpEventSchema);
+        if (!this._batchingEnabled) {
+            await this.service.forceFlush();
+        }
+    }
     async flush() {
         // Wait for initialization to complete before using the service
         await this.initialized;

package/lib/telemetryReporter.d.ts

@@ -1,7 +1,7 @@
 import { AsyncCreatable } from '@salesforce/kit';
 import type { BatchingOptions } from '@salesforce/o11y-reporter';
 import { TelemetryClient } from './appInsights';
-import { Attributes, O11ySchema, Properties, TelemetryOptions } from './types';
+import { Attributes, O11ySchema, PdpEvent, Properties, TelemetryOptions } from './types';
 /**
  * This is the main telemetry reporter that should be used by consumers.
  * It will check if telemetry is disabled and do GDPR checks.
@@ -38,12 +38,22 @@ export declare class TelemetryReporter extends AsyncCreatable<TelemetryOptions>
      * Sends a telemetry event to O11y only with a specific schema.
      * Use this for events that must conform to a given schema (e.g. PFT/pdpEventSchema).
      * Does not send to AppInsights. Only sends when O11y is enabled and reporter is initialized.
+     * Only the caller-provided attributes are sent; no properties are added by the reporter.
      *
-     * @param eventName - Name of the event
-     * @param attributes - Properties and measurements to publish alongside the event
-     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     * The schema is the O11y encoding schema (e.g. from the o11y_schema package), not JSON Schema,
+     * so this library does not derive or run validation here. Callers should validate attributes
+     * (e.g. with zod) before calling, using the same schema context they use when importing the schema.
+     *
+     * @param attributes - Properties and measurements to publish (only these are sent)
+     * @param schema - O11y encoding schema (e.g. from o11y_schema package)
+     */
+    sendTelemetryEventWithSchema(attributes: Attributes, schema: O11ySchema): void;
+    /**
+     * Sends a PDP event via O11y.
+     *
+     * @param event - PDP event data to send.
      */
-    sendTelemetryEventWithSchema(eventName: string, attributes: Attributes, schema: O11ySchema): void;
+    sendPdpEvent(event: PdpEvent): void;
     /**
      * Sends message to both AppInsights and O11y (if enabled).
      *

package/lib/telemetryReporter.js

@@ -191,18 +191,34 @@ class TelemetryReporter extends kit_1.AsyncCreatable {
      * Sends a telemetry event to O11y only with a specific schema.
      * Use this for events that must conform to a given schema (e.g. PFT/pdpEventSchema).
      * Does not send to AppInsights. Only sends when O11y is enabled and reporter is initialized.
+     * Only the caller-provided attributes are sent; no properties are added by the reporter.
      *
-     * @param eventName - Name of the event
-     * @param attributes - Properties and measurements to publish alongside the event
-     * @param schema - O11y schema object (e.g. from o11y_schema package)
+     * The schema is the O11y encoding schema (e.g. from the o11y_schema package), not JSON Schema,
+     * so this library does not derive or run validation here. Callers should validate attributes
+     * (e.g. with zod) before calling, using the same schema context they use when importing the schema.
+     *
+     * @param attributes - Properties and measurements to publish (only these are sent)
+     * @param schema - O11y encoding schema (e.g. from o11y_schema package)
      */
-    sendTelemetryEventWithSchema(eventName, attributes, schema) {
+    sendTelemetryEventWithSchema(attributes, schema) {
         if (this.isSfdxTelemetryEnabled() && this.enableO11y && this.o11yReporter) {
-            void this.o11yReporter.sendTelemetryEventWithSchema(eventName, attributes, schema).catch((error) => {
+            void this.o11yReporter.sendTelemetryEventWithSchema(attributes, schema).catch((error) => {
                 this.logger.debug('Failed to send event with schema to O11y:', error);
             });
         }
     }
+    /**
+     * Sends a PDP event via O11y.
+     *
+     * @param event - PDP event data to send.
+     */
+    sendPdpEvent(event) {
+        if (this.isSfdxTelemetryEnabled() && this.enableO11y && this.o11yReporter) {
+            void this.o11yReporter.sendPdpEvent(event).catch((error) => {
+                this.logger.debug('Failed to send PDP event to O11y:', error);
+            });
+        }
+    }
     /**
      * Sends message to both AppInsights and O11y (if enabled).
      *

package/lib/types.d.ts

@@ -15,6 +15,49 @@ export type Attributes = {
  * (not a primitive, null, or undefined).
  */
 export type O11ySchema = Record<string, unknown>;
+/**
+ * PDP Product Feature Taxonomy (PFT) event sent via O11y.
+ */
+export type PdpEvent = {
+    /**
+     * Unique identifier for the event. Follows this naming convention:
+     *     <object>.<action>
+     *
+     * object = Specific object within the Product Feature that give us context around the action in lowerCamelCase format.
+     *          Note: The object name can include context around the Product Feature (eg. slackforceMessage).
+     *          Examples: calculatedInsightsRecord,checkoutPaymentmethod, slackforceMessage, promptBuilderTemplate
+     *
+     * action = Action the user takes in past tense. This should only be ONE word, in lower case
+     *          Examples: processed, selected, sent, saved
+     */
+    eventName: `${string}.${string}`;
+    /**
+     * Product Feature ID from GUS.
+     *
+     * Examples:
+     *   Salesforce CLI = aJCEE0000000mHP4AY
+     *   Salesforce Extensions for VS Code = aJCEE0000000mLm4AI
+     */
+    productFeatureId: `aJC${string}`;
+    /**
+     * Populate this if there is a unique component with your Event for which a distinct count would be a relevant metric
+     * E.g., CLI plugin command name (<pluginName.commandName>) or ext command name.
+     */
+    componentId?: string;
+    /**
+     * Populate this if there is a unique quantity with your Event for which a sum would be a relevant metric for your
+     * Product Feature. E.g., rowsProcessed → total Rows processed for Data Streams.
+     */
+    eventVolume?: number;
+    /**
+     * Use this field to specify the name of your flexible attribute (eg. experimentId, buttonColor).
+     */
+    contextName?: string;
+    /**
+     * Use this field to specify the value of your flexible attribute (eg. exp_123, green).
+     */
+    contextValue?: string;
+};
 /**
  * Batching configuration for O11y telemetry
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/telemetry",
-  "version": "6.5.2",
+  "version": "6.6.1",
   "description": "Library for telemetry reporting to Application Insights and O11y",
   "main": "lib/exported",
   "exports": {
@@ -46,6 +46,7 @@
     "@salesforce/o11y-reporter": "1.7.3",
     "applicationinsights": "^2.9.8",
     "got": "^11",
+    "o11y_schema": "^260.41.0",
     "proxy-agent": "^6.5.0"
   },
   "devDependencies": {