@microsoft/power-apps-native-common 0.1.8

package/lib/commonjs/types/ClusterCategory.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Regions = void 0;
+exports.regionToClusterCategory = regionToClusterCategory;
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+/**
+ * Identifies the Power Platform cluster environment category.
+ * Used to resolve telemetry endpoints, instrumentation keys, and collector URLs.
+ *
+ * This is the **normalised** internal form used by telemetry providers.
+ * The raw `region` string from power.config.json may differ — use
+ * `regionToClusterCategory()` to convert before passing here.
+ *
+ * Canonical power.config.json `region` values → ClusterCategory mapping:
+ *   preview     → prod
+ *   gccmoderate → gov
+ *   gcchigh     → high
+ *   (all others are identity mappings)
+ */
+
+/**
+ * All valid `region` strings accepted in power.config.json.
+ * Mirrors the `Region` type from `@microsoft/power-apps-common/services`.
+ */
+const Regions = exports.Regions = ['local', 'dev', 'test', 'preprod', 'preview', 'prod', 'firstrelease', 'gccmoderate', 'gcchigh', 'dod', 'mooncake', 'ex', 'rx'];
+/**
+ * Normalise a power.config.json `region` string to the internal
+ * `ClusterCategory` used by telemetry providers.
+ *
+ * Mirrors the CLI's `regionToClusterCategory` in OneDSWriter.ts:
+ *   preview     → prod       (preview ring uses production telemetry)
+ *   gccmoderate → gov        (GCC Moderate sovereign cloud)
+ *   gcchigh     → high       (GCC High sovereign cloud)
+ *   firstrelease → firstrelease (first-release prod ring)
+ *   all others  → identity
+ */
+function regionToClusterCategory(region) {
+  switch (region) {
+    case 'preview':
+      return 'prod';
+    case 'gccmoderate':
+      return 'gov';
+    case 'gcchigh':
+      return 'high';
+    default:
+      return region;
+  }
+}

package/lib/commonjs/utils/DeviceIdUtils.js

@@ -0,0 +1,66 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveDeviceId = resolveDeviceId;
+var Application = _interopRequireWildcard(require("expo-application"));
+var SecureStore = _interopRequireWildcard(require("expo-secure-store"));
+var _reactNative = require("react-native");
+var _GuidUtils = require("./GuidUtils.js");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+// Fallback key used when the platform native ID is unavailable.
+// Only alphanumeric, dots, hyphens, and underscores are valid for SecureStore.
+const DEVICE_ID_FALLBACK_KEY = 'microsoft.power-apps-native-common.device_id';
+
+/**
+ * Returns a stable device identifier, preferring platform-native IDs that
+ * survive app reinstalls:
+ *
+ * - **iOS**: `getIosIdForVendorAsync()` (IDFV) — stable while ≥1 app from the
+ *   same vendor bundle prefix is installed. Resets only when ALL vendor apps
+ *   are removed.
+ * - **Android**: `getAndroidId()` (SSAID) — scoped to the app signing key on
+ *   Android 8+; survives reinstalls as long as the signing key is unchanged.
+ *
+ * If the platform API returns null (rare edge cases: first boot, some emulators)
+ * the function falls back to a UUID persisted in `expo-secure-store`, which on
+ * iOS survives reinstalls via the Keychain and on Android is per-install only.
+ *
+ * Pass the resolved value to `OneDsTelemetryProviderConfig.deviceId` at startup.
+ *
+ * @example
+ * ```ts
+ * import { resolveDeviceId, OneDsTelemetryProvider } from '@microsoft/power-apps-native-common';
+ *
+ * const deviceId = await resolveDeviceId();
+ * const telemetry = new OneDsTelemetryProvider({ deviceId, ... });
+ * ```
+ */
+async function resolveDeviceId() {
+  if (_reactNative.Platform.OS === 'ios') {
+    const idfv = await Application.getIosIdForVendorAsync();
+    if (idfv) {
+      return idfv;
+    }
+  } else if (_reactNative.Platform.OS === 'android') {
+    const androidId = Application.getAndroidId();
+    if (androidId) {
+      return androidId;
+    }
+  }
+
+  // Fallback: stable UUID in SecureStore (iOS: survives reinstall via Keychain;
+  // Android: per-install only, but only reached when SSAID is unavailable).
+  const existing = await SecureStore.getItemAsync(DEVICE_ID_FALLBACK_KEY);
+  if (existing) {
+    return existing;
+  }
+  const id = (0, _GuidUtils.generateGuid)();
+  await SecureStore.setItemAsync(DEVICE_ID_FALLBACK_KEY, id);
+  return id;
+}

package/lib/commonjs/utils/GuidUtils.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.generateGuid = generateGuid;
+require("react-native-get-random-values");
+var _uuid = require("uuid");
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+// Must be imported before 'uuid' so that the crypto.getRandomValues polyfill is
+// in place when uuid initialises on Hermes/JSC (React Native).
+
+/**
+ * Generates a RFC-4122 v4 GUID/UUID string.
+ * Uses the `uuid` package (backed by `react-native-get-random-values` on RN)
+ * instead of `crypto.randomUUID()` which is unavailable in Hermes/JSC.
+ */
+function generateGuid() {
+  return (0, _uuid.v4)();
+}

package/lib/commonjs/utils/PlatformInfoUtils.js

@@ -0,0 +1,60 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolvePlatformInfo = resolvePlatformInfo;
+var Device = _interopRequireWildcard(require("expo-device"));
+var _reactNative = require("react-native");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+// Maps expo-device DeviceType numeric enum to a readable string.
+const DEVICE_TYPE_LABEL = {
+  0: 'Unknown',
+  1: 'Phone',
+  2: 'Tablet',
+  3: 'Desktop',
+  4: 'TV'
+};
+
+/**
+ * Resolves 1DS Part A Common Schema device/OS/locale values using `expo-device`
+ * and the Intl API. Provides more accurate data than raw Platform.constants:
+ *
+ * - Correctly returns `'iPadOS'` for iPad (not `'iOS'`).
+ * - Returns human-friendly `modelName` (e.g. `'iPhone 16 Pro'`, `'Pixel 9'`).
+ * - Returns proper `manufacturer` (e.g. `'Apple'`, `'Google'`, `'Samsung'`).
+ * - Includes form-factor `deviceType` (Phone / Tablet / Desktop / TV).
+ *
+ * Safe to call once at provider construction time — all values are stable for
+ * the lifetime of the process.
+ */
+function resolvePlatformInfo() {
+  // expo-device returns 'iOS' or 'iPadOS' on Apple platforms.
+  // On Android, osName maps to Build.VERSION.BASE_OS which can be a build
+  // fingerprint on some OEMs, so we always use the literal 'Android' there.
+  const osName = _reactNative.Platform.OS === 'ios' ? Device.osName ?? 'iOS' : 'Android';
+  const osVersion = Device.osVersion ?? String(_reactNative.Platform.Version);
+  const deviceMake = Device.manufacturer ?? (_reactNative.Platform.OS === 'ios' ? 'Apple' : '');
+  const deviceModel = Device.modelName ?? '';
+  const deviceType = DEVICE_TYPE_LABEL[Device.deviceType ?? 0] ?? 'Unknown';
+  let userLocale = '';
+  let userTimeZone = '';
+  try {
+    const dtf = Intl.DateTimeFormat().resolvedOptions();
+    userLocale = dtf.locale;
+    userTimeZone = dtf.timeZone;
+  } catch {/* Intl unavailable — leave empty */}
+  return {
+    osName,
+    osVersion,
+    deviceMake,
+    deviceModel,
+    deviceType,
+    userLocale,
+    userTimeZone
+  };
+}

package/lib/module/TelemetryTypes.js

@@ -0,0 +1,25 @@
+"use strict";
+
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+/** Canonical 1DS event names matching webplayer conventions. */
+export const TelemetryEventNames = {
+  Activity: 'PowerAppsClient.Activity',
+  Error: 'PowerAppsClient.Error',
+  StartScenario: 'PowerAppsClient.StartScenario',
+  EndScenario: 'PowerAppsClient.EndScenario'
+};
+export const ScenarioResults = {
+  Success: 'Success',
+  Failed: 'Failed',
+  SuccessWithErrors: 'SuccessWithErrors'
+};
+
+/** Telemetry data residency location. EU routes to eu-mobile collector. */
+
+/**
+ * Structural type for the 1DS telemetry envelope passed to telemetry initializers.
+ * Decouples consumers from the internal `ITelemetryItem` type.
+ */

package/lib/module/index.js

@@ -0,0 +1,18 @@
+"use strict";
+
+/*!
+ * power-apps-native-common
+ * Shared utilities and types for Power Apps native packages
+ */
+
+export { ConsoleAdapter } from "./telemetry/ConsoleAdapter.js";
+export { Logger } from "./telemetry/Logger.js";
+export { OneDsTelemetryProvider } from "./telemetry/OneDsTelemetryProvider.js";
+export { resolveTelemetryLocation } from "./telemetry/resolveTelemetryLocation.js";
+export { stringifyError } from "./telemetry/stringifyError.js";
+export { sanitizeErrorString, sanitizeUrl, sanitizeProperties } from "./telemetry/TelemetrySanitizer.js";
+export { suppressKnownWarnings } from "./telemetry/suppressKnownWarnings.js";
+export { resolveDeviceId } from "./utils/DeviceIdUtils.js";
+export { configureAppLogger, getAppLogger } from "./telemetry/AppLogger.js";
+export { ScenarioResults, TelemetryEventNames } from "./telemetry/TelemetryTypes.js";
+export { Regions, regionToClusterCategory } from "./types/ClusterCategory.js";

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/module/telemetry/AppLogger.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *
+ * power-apps-native-common — app-level logger singleton
+ *
+ * Provides a single shared `ILogger` instance for the entire app process.
+ * The logger starts as a no-op (no providers) and is configured once at
+ * startup by the hosting infrastructure (e.g. `PowerAppsProvider`).
+ *
+ * App code and library packages call `getAppLogger()` to emit telemetry
+ * without coupling to a specific provider or needing to pass a logger around.
+ *
+ * Usage in a library:
+ *
+ *   import { getAppLogger } from '@microsoft/power-apps-native-common';
+ *   getAppLogger().trackActivityEvent('MyLib.SomeOperation', { … });
+ *
+ * Usage in the host / root layout (once, at startup):
+ *
+ *   import { configureAppLogger } from '@microsoft/power-apps-native-common';
+ *   configureAppLogger(new Logger({ providers: [myProvider] }));
+ */
+
+import { Logger } from "./Logger.js";
+let _logger = new Logger(); // no-op until configured
+
+/**
+ * Replace the shared app logger with a configured instance.
+ * All subsequent `getAppLogger()` calls return the new instance.
+ * Idempotent — calling again replaces the previous logger.
+ */
+export function configureAppLogger(logger) {
+  _logger = logger;
+}
+
+/**
+ * Returns the shared app-level logger.
+ * No-op (no providers) until `configureAppLogger` is called.
+ */
+export function getAppLogger() {
+  return _logger;
+}

package/lib/module/telemetry/ConsoleAdapter.js

@@ -0,0 +1,59 @@
+"use strict";
+
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+import { generateGuid } from "../utils/GuidUtils.js";
+/**
+ * A telemetry adapter that writes events to the JavaScript console.
+ * Useful during development and for unit-testing telemetry flows.
+ * Can be replaced in production by the native telemetry adapter.
+ */
+export class ConsoleAdapter {
+  defaultProperties = {};
+  constructor(minSeverity = 'verbose') {
+    this.minSeverity = minSeverity;
+    this._sessionId = generateGuid();
+  }
+  track(event) {
+    const payload = {
+      ...event.properties,
+      sessionId: this._sessionId,
+      ...this.defaultProperties,
+      ...(this.userIdentity ?? {})
+    };
+    const label = `[${event.severity.toUpperCase()}] ${event.eventName} | ${event.properties['operationName'] ?? ''} (#${event.sequenceNumber})`;
+    switch (event.severity) {
+      case 'error':
+        console.error(label, payload);
+        break;
+      case 'warning':
+        console.warn(label, payload);
+        break;
+      case 'verbose':
+        console.debug(label, payload);
+        break;
+      default:
+        console.log(label, payload);
+    }
+  }
+  flush() {
+    return Promise.resolve();
+  }
+  teardown() {
+    return Promise.resolve();
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  set sessionId(value) {
+    this._sessionId = value;
+  }
+  identifyUser(identity) {
+    this.userIdentity = identity;
+  }
+  setDefaultProperty(name, value) {
+    this.defaultProperties[name] = value;
+  }
+}

package/lib/module/telemetry/ILogger.js

@@ -0,0 +1,3 @@
+"use strict";
+
+export {};

package/lib/module/telemetry/Logger.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+
+import { generateGuid } from "../utils/GuidUtils.js";
+import { stringifyError } from "./stringifyError.js";
+import { sanitizeProperties } from "./TelemetrySanitizer.js";
+import { ScenarioResults, TelemetryEventNames } from "./TelemetryTypes.js";
+const severityOrder = {
+  verbose: 0,
+  info: 1,
+  warning: 2,
+  error: 3
+};
+
+/**
+ * Structured logger with canonical event names, severity filtering,
+ * sequence numbering, and scenario tracking.
+ * Supports multiple telemetry adapters; no-op safe when none are given.
+ */
+export class Logger {
+  sequence = 0;
+  constructor(config) {
+    this.providers = config?.providers ?? [];
+    // Use the least-restrictive minSeverity among all providers, falling back to 'verbose'.
+    if (this.providers.length === 0) {
+      this.minSeverity = 'verbose';
+    } else {
+      const order = severityOrder;
+      this.minSeverity = this.providers.reduce((min, p) => {
+        const pSev = p.minSeverity ?? 'verbose';
+        return order[pSev] < order[min] ? pSev : min;
+      }, 'error');
+    }
+  }
+  trackActivityEvent(name, properties, eventName) {
+    this.emit('info', eventName ?? TelemetryEventNames.Activity, name, properties);
+  }
+  trackVerboseEvent(name, properties, eventName) {
+    this.emit('verbose', eventName ?? TelemetryEventNames.Activity, name, properties);
+  }
+  trackErrorEvent(name, properties, eventName) {
+    this.emit('error', eventName ?? TelemetryEventNames.Error, name, properties);
+  }
+  trackScenario(name, properties) {
+    const startTime = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    const scenarioGuid = generateGuid();
+    const scenarioProps = {
+      ...properties,
+      scenarioName: name,
+      scenarioGuid
+    };
+    this.emit('info', TelemetryEventNames.StartScenario, name, scenarioProps);
+    return {
+      complete: extraProps => {
+        const duration = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startTime;
+        this.emit('info', TelemetryEventNames.EndScenario, name, {
+          ...scenarioProps,
+          ...extraProps,
+          scenarioResult: ScenarioResults.Success,
+          duration
+        });
+      },
+      completeWithError: extraProps => {
+        const duration = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startTime;
+        this.emit('warning', TelemetryEventNames.EndScenario, name, {
+          ...scenarioProps,
+          ...extraProps,
+          scenarioResult: ScenarioResults.SuccessWithErrors,
+          duration
+        });
+      },
+      fail: (error, extraProps) => {
+        const duration = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startTime;
+        this.emit('error', TelemetryEventNames.EndScenario, name, {
+          ...scenarioProps,
+          ...extraProps,
+          scenarioResult: ScenarioResults.Failed,
+          error: error !== undefined ? stringifyError(error) : undefined,
+          duration
+        });
+      }
+    };
+  }
+  setDefaultProperty(name, value) {
+    for (const p of this.providers) p.setDefaultProperty(name, value);
+  }
+  identifyUser(identity) {
+    for (const p of this.providers) p.identifyUser(identity);
+  }
+  get sessionId() {
+    return this.providers[0]?.sessionId;
+  }
+  set sessionId(value) {
+    for (const p of this.providers) p.sessionId = value;
+  }
+  async flush() {
+    await Promise.all(this.providers.map(p => p.flush()));
+  }
+  shouldLog(severity) {
+    return severityOrder[severity] >= severityOrder[this.minSeverity];
+  }
+  emit(severity, eventName, operationName, properties) {
+    if (this.providers.length === 0) {
+      return;
+    }
+    if (!this.shouldLog(severity)) {
+      return;
+    }
+    const flatProps = flattenProperties(properties);
+    flatProps.operationName = operationName;
+    const event = {
+      eventName,
+      timestamp: new Date().toISOString(),
+      severity,
+      sequenceNumber: ++this.sequence,
+      duration: typeof flatProps.duration === 'number' ? flatProps.duration : undefined,
+      properties: flatProps
+    };
+    for (const p of this.providers) {
+      // Per-adapter severity filtering
+      const adapterMin = p.minSeverity ?? 'verbose';
+      if (severityOrder[severity] >= severityOrder[adapterMin]) {
+        p.track(event);
+      }
+    }
+  }
+}
+
+/** Convert Record<string, unknown> to Record<string, string | number | boolean> by JSON-stringifying non-primitives. Applies PII sanitization before flattening. */
+function flattenProperties(properties) {
+  const sanitized = properties ? sanitizeProperties(properties) : undefined;
+  const result = {};
+  if (!sanitized) return result;
+  for (const [key, value] of Object.entries(sanitized)) {
+    if (value === undefined) continue;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      result[key] = value;
+    } else {
+      result[key] = JSON.stringify(value);
+    }
+  }
+  return result;
+}