@salesforce/platform-sdk 9.10.2 → 9.10.3

package/README.md

@@ -47,6 +47,100 @@ const result = await sdk.graphql?.query<GetAccountsQuery>({
 
 The chat, view, lightning, telemetry, and analytics surfaces follow the same pattern — see [Migrating from individual SDK packages](#migrating-from-individual-sdk-packages) for the full set of factories.
 
+## Instrumenting a widget
+
+`createAnalytics` is the recommended entry point for Mosaic widget tiles and other MCP-embedded UI components. It wires an `o11y` instrumented app, a Proxy-wrapped `ChatSDK` for auto-instrumentation, global error listeners, and an optional upload transport — all from one call.
+
+```ts
+import { createAnalytics, createTelemetryTransport, getChatSDK } from "@salesforce/platform-sdk";
+
+const sdk = await getChatSDK();
+const transport = createTelemetryTransport({ sdk });
+const analytics = await createAnalytics({
+  appId: "my-mosaic-tile",
+  sdk,
+  transport,
+});
+
+// Pass `analytics.instrumentedSDK` to widget hosts that expect a `ChatSDK` —
+// SDK calls made through it are auto-instrumented.
+
+analytics.trackPageView("AccountTile");
+analytics.trackInteraction("account-tile-row", { accountId });
+analytics.trackEvent("record_opened", { recordId });
+
+// On widget/app teardown:
+analytics.dispose();
+```
+
+| Method                                     | When to call                                                                                                   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `trackPageView(componentRef)`              | Widget mounted or navigated to a new component. Consecutive identical calls are deduplicated.                  |
+| `trackInteraction(elementId, properties?)` | User interacted with a UI element (click, change, submit).                                                     |
+| `trackEvent(eventName, properties?)`       | Custom business event that isn't an interaction or page view.                                                  |
+| `trackError(error, properties?)`           | Explicitly report a caught error. Uncaught errors and unhandled promise rejections are captured automatically. |
+| `dispose()`                                | Removes global error listeners, logs session duration, and flushes the upload buffer. Call once on teardown.   |
+
+`createAnalytics` is async because it constructs a `ChatSDK` if you don't supply one. To skip the transport (e.g., during local development), omit the `transport` option — events still flow through `o11y` but aren't uploaded.
+
+## Telemetry transport
+
+`createTelemetryTransport` buffers `o11y` envelopes and uploads them via the `telemetry/upload` tool exposed by the host `ChatSDK`. Use it directly when you want batching independent of `createAnalytics`.
+
+```ts
+import { createTelemetryTransport, getChatSDK } from "@salesforce/platform-sdk";
+
+const transport = createTelemetryTransport({
+  sdk: await getChatSDK(),
+  flushInterval: 30_000, // ms; default 30s
+  maxBufferSize: 65_536, // bytes; default 64 KB
+  onError: ({ reason, error, droppedCount }) => {
+    console.warn("[telemetry]", reason, { error, droppedCount });
+  },
+});
+
+transport.enqueue(envelopeBytes);
+transport.dispose(); // flush + cleanup
+```
+
+Behavior:
+
+- **Buffering.** Up to `maxBufferSize` bytes. On overflow the oldest entries are evicted and `onError` fires with `reason: "buffer_overflow"` and a `droppedCount`.
+- **Automatic flush.** On `flushInterval`, on `visibilitychange` → hidden, on `pagehide`, and on `dispose()`.
+- **Upload path.** Each flush calls `sdk.callTool({ toolName: "telemetry/upload", params: { inputs: [{ envelopes }] } })`. If the call rejects, `onError` fires with `reason: "tool_call_failed"`.
+
+## Advanced: `registerTelemetryUploader`
+
+Use `registerTelemetryUploader` when you already manage your own `o11y` `InstrumentedApp` and don't want `createAnalytics` to create one for you.
+
+```ts
+import {
+  registerTelemetryUploader,
+  createTelemetryTransport,
+  getChatSDK,
+} from "@salesforce/platform-sdk";
+import { registerInstrumentedApp } from "o11y/client";
+
+const app = registerInstrumentedApp("my-app", {
+  /* o11y options */
+});
+const transport = createTelemetryTransport({ sdk: await getChatSDK() });
+
+const uploader = registerTelemetryUploader(app, {
+  onEnvelope: (envelope) => transport.enqueue(envelope),
+  uploadInterval: 10_000,
+  messagesLimit: 10,
+  metricsLimit: 10,
+  enableClickTrigger: true,
+  enableVisibilityTrigger: true,
+});
+
+// On teardown:
+await uploader.dispose({ flush: true });
+```
+
+`uploader.flush(reason)` accepts a `FlushReason` of `"manual" | "interval" | "threshold" | "click" | "visibilitychange" | "pagehide" | "dispose"` and is exposed via the `TelemetryUploadContext` passed to `onEnvelope`.
+
 ## Migrating from individual SDK packages
 
 This package replaced the seven previously-published per-domain SDK packages. The deprecation shims published as their final 5.x.x versions forwarded every export to `@salesforce/platform-sdk` and have now been removed:

package/dist/index.js

@@ -999,7 +999,7 @@ class Ze {
     })).structuredContent;
   }
 }
-const et = "X-SFDC-Client-Name", tt = "X-SFDC-Client-Version", st = "@salesforce/platform-sdk", rt = "9.10.2", nt = (s) => {
+const et = "X-SFDC-Client-Name", tt = "X-SFDC-Client-Version", st = "@salesforce/platform-sdk", rt = "9.10.3", nt = (s) => {
   let e = _(et, st, s);
   return e = _(tt, rt, e), w(e);
 }, it = "X-CSRF-Token";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/platform-sdk",
-  "version": "9.10.2",
+  "version": "9.10.3",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",