@microsoft/power-apps-native-common 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/LICENSE +112 -0
  2. package/README.md +15 -0
  3. package/lib/NOTICE.txt +179 -0
  4. package/lib/commonjs/TelemetryTypes.js +29 -0
  5. package/lib/commonjs/index.js +112 -0
  6. package/lib/commonjs/package.json +1 -0
  7. package/lib/commonjs/telemetry/AppLogger.js +49 -0
  8. package/lib/commonjs/telemetry/ConsoleAdapter.js +64 -0
  9. package/lib/commonjs/telemetry/ILogger.js +5 -0
  10. package/lib/commonjs/telemetry/Logger.js +151 -0
  11. package/lib/commonjs/telemetry/OneDsTelemetryProvider.js +276 -0
  12. package/lib/commonjs/telemetry/TelemetrySanitizer.js +100 -0
  13. package/lib/commonjs/telemetry/TelemetryTypes.js +29 -0
  14. package/lib/commonjs/telemetry/resolveTelemetryLocation.js +42 -0
  15. package/lib/commonjs/telemetry/stringifyError.js +31 -0
  16. package/lib/commonjs/telemetry/suppressKnownWarnings.js +28 -0
  17. package/lib/commonjs/types/ClusterCategory.js +54 -0
  18. package/lib/commonjs/utils/DeviceIdUtils.js +66 -0
  19. package/lib/commonjs/utils/GuidUtils.js +23 -0
  20. package/lib/commonjs/utils/PlatformInfoUtils.js +60 -0
  21. package/lib/module/TelemetryTypes.js +25 -0
  22. package/lib/module/index.js +18 -0
  23. package/lib/module/package.json +1 -0
  24. package/lib/module/telemetry/AppLogger.js +44 -0
  25. package/lib/module/telemetry/ConsoleAdapter.js +59 -0
  26. package/lib/module/telemetry/ILogger.js +3 -0
  27. package/lib/module/telemetry/Logger.js +146 -0
  28. package/lib/module/telemetry/OneDsTelemetryProvider.js +271 -0
  29. package/lib/module/telemetry/TelemetrySanitizer.js +94 -0
  30. package/lib/module/telemetry/TelemetryTypes.js +25 -0
  31. package/lib/module/telemetry/resolveTelemetryLocation.js +38 -0
  32. package/lib/module/telemetry/stringifyError.js +28 -0
  33. package/lib/module/telemetry/suppressKnownWarnings.js +25 -0
  34. package/lib/module/types/ClusterCategory.js +49 -0
  35. package/lib/module/utils/DeviceIdUtils.js +62 -0
  36. package/lib/module/utils/GuidUtils.js +19 -0
  37. package/lib/module/utils/PlatformInfoUtils.js +55 -0
  38. package/lib/typescript/commonjs/TelemetryTypes.d.ts +88 -0
  39. package/lib/typescript/commonjs/index.d.ts +19 -0
  40. package/lib/typescript/commonjs/package.json +1 -0
  41. package/lib/typescript/commonjs/telemetry/AppLogger.d.ts +35 -0
  42. package/lib/typescript/commonjs/telemetry/ConsoleAdapter.d.ts +24 -0
  43. package/lib/typescript/commonjs/telemetry/ILogger.d.ts +45 -0
  44. package/lib/typescript/commonjs/telemetry/Logger.d.ts +28 -0
  45. package/lib/typescript/commonjs/telemetry/OneDsTelemetryProvider.d.ts +39 -0
  46. package/lib/typescript/commonjs/telemetry/TelemetrySanitizer.d.ts +21 -0
  47. package/lib/typescript/commonjs/telemetry/TelemetryTypes.d.ts +88 -0
  48. package/lib/typescript/commonjs/telemetry/resolveTelemetryLocation.d.ts +26 -0
  49. package/lib/typescript/commonjs/telemetry/stringifyError.d.ts +10 -0
  50. package/lib/typescript/commonjs/telemetry/suppressKnownWarnings.d.ts +19 -0
  51. package/lib/typescript/commonjs/types/ClusterCategory.d.ts +37 -0
  52. package/lib/typescript/commonjs/utils/DeviceIdUtils.d.ts +29 -0
  53. package/lib/typescript/commonjs/utils/GuidUtils.d.ts +11 -0
  54. package/lib/typescript/commonjs/utils/PlatformInfoUtils.d.ts +33 -0
  55. package/lib/typescript/module/TelemetryTypes.d.ts +88 -0
  56. package/lib/typescript/module/index.d.ts +19 -0
  57. package/lib/typescript/module/package.json +1 -0
  58. package/lib/typescript/module/telemetry/AppLogger.d.ts +35 -0
  59. package/lib/typescript/module/telemetry/ConsoleAdapter.d.ts +24 -0
  60. package/lib/typescript/module/telemetry/ILogger.d.ts +45 -0
  61. package/lib/typescript/module/telemetry/Logger.d.ts +28 -0
  62. package/lib/typescript/module/telemetry/OneDsTelemetryProvider.d.ts +39 -0
  63. package/lib/typescript/module/telemetry/TelemetrySanitizer.d.ts +21 -0
  64. package/lib/typescript/module/telemetry/TelemetryTypes.d.ts +88 -0
  65. package/lib/typescript/module/telemetry/resolveTelemetryLocation.d.ts +26 -0
  66. package/lib/typescript/module/telemetry/stringifyError.d.ts +10 -0
  67. package/lib/typescript/module/telemetry/suppressKnownWarnings.d.ts +19 -0
  68. package/lib/typescript/module/types/ClusterCategory.d.ts +37 -0
  69. package/lib/typescript/module/utils/DeviceIdUtils.d.ts +29 -0
  70. package/lib/typescript/module/utils/GuidUtils.d.ts +11 -0
  71. package/lib/typescript/module/utils/PlatformInfoUtils.d.ts +33 -0
  72. package/package.json +83 -0
@@ -0,0 +1,19 @@
1
+ /*!
2
+ * power-apps-native-common
3
+ * Shared utilities and types for Power Apps native packages
4
+ */
5
+ export { ConsoleAdapter } from './telemetry/ConsoleAdapter.js';
6
+ export type { ILogger, ScenarioTracker } from './telemetry/ILogger.js';
7
+ export { Logger } from './telemetry/Logger.js';
8
+ export { OneDsTelemetryProvider } from './telemetry/OneDsTelemetryProvider.js';
9
+ export { resolveTelemetryLocation } from './telemetry/resolveTelemetryLocation.js';
10
+ export { stringifyError } from './telemetry/stringifyError.js';
11
+ export { sanitizeErrorString, sanitizeUrl, sanitizeProperties } from './telemetry/TelemetrySanitizer.js';
12
+ export { suppressKnownWarnings } from './telemetry/suppressKnownWarnings.js';
13
+ export { resolveDeviceId } from './utils/DeviceIdUtils.js';
14
+ export { configureAppLogger, getAppLogger } from './telemetry/AppLogger.js';
15
+ export type { ITelemetryProvider, LoggerConfig, OneDsTelemetryProviderConfig, PropertyColumnMap, TelemetryEnvelope, TelemetryEvent, TelemetryLocation, TelemetrySeverity, UserIdentity, } from './telemetry/TelemetryTypes.js';
16
+ export { ScenarioResults, TelemetryEventNames } from './telemetry/TelemetryTypes.js';
17
+ export type { ClusterCategory, Region } from './types/ClusterCategory.js';
18
+ export { Regions, regionToClusterCategory } from './types/ClusterCategory.js';
19
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"type":"module"}
@@ -0,0 +1,35 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ *
4
+ * power-apps-native-common — app-level logger singleton
5
+ *
6
+ * Provides a single shared `ILogger` instance for the entire app process.
7
+ * The logger starts as a no-op (no providers) and is configured once at
8
+ * startup by the hosting infrastructure (e.g. `PowerAppsProvider`).
9
+ *
10
+ * App code and library packages call `getAppLogger()` to emit telemetry
11
+ * without coupling to a specific provider or needing to pass a logger around.
12
+ *
13
+ * Usage in a library:
14
+ *
15
+ * import { getAppLogger } from '@microsoft/power-apps-native-common';
16
+ * getAppLogger().trackActivityEvent('MyLib.SomeOperation', { … });
17
+ *
18
+ * Usage in the host / root layout (once, at startup):
19
+ *
20
+ * import { configureAppLogger } from '@microsoft/power-apps-native-common';
21
+ * configureAppLogger(new Logger({ providers: [myProvider] }));
22
+ */
23
+ import type { ILogger } from './ILogger.js';
24
+ /**
25
+ * Replace the shared app logger with a configured instance.
26
+ * All subsequent `getAppLogger()` calls return the new instance.
27
+ * Idempotent — calling again replaces the previous logger.
28
+ */
29
+ export declare function configureAppLogger(logger: ILogger): void;
30
+ /**
31
+ * Returns the shared app-level logger.
32
+ * No-op (no providers) until `configureAppLogger` is called.
33
+ */
34
+ export declare function getAppLogger(): ILogger;
35
+ //# sourceMappingURL=AppLogger.d.ts.map
@@ -0,0 +1,24 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { ITelemetryProvider, TelemetryEvent, TelemetrySeverity, UserIdentity } from './TelemetryTypes.js';
5
+ /**
6
+ * A telemetry adapter that writes events to the JavaScript console.
7
+ * Useful during development and for unit-testing telemetry flows.
8
+ * Can be replaced in production by the native telemetry adapter.
9
+ */
10
+ export declare class ConsoleAdapter implements ITelemetryProvider {
11
+ readonly minSeverity: TelemetrySeverity;
12
+ private _sessionId;
13
+ private readonly defaultProperties;
14
+ private userIdentity?;
15
+ constructor(minSeverity?: TelemetrySeverity);
16
+ track(event: TelemetryEvent): void;
17
+ flush(): Promise<void>;
18
+ teardown(): Promise<void>;
19
+ get sessionId(): string;
20
+ set sessionId(value: string);
21
+ identifyUser(identity: UserIdentity): void;
22
+ setDefaultProperty(name: string, value: string): void;
23
+ }
24
+ //# sourceMappingURL=ConsoleAdapter.d.ts.map
@@ -0,0 +1,45 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { UserIdentity } from './TelemetryTypes.js';
5
+ export interface ScenarioTracker {
6
+ complete(properties?: Record<string, unknown>): void;
7
+ completeWithError(properties?: Record<string, unknown>): void;
8
+ fail(error?: unknown, properties?: Record<string, unknown>): void;
9
+ }
10
+ export interface ILogger {
11
+ /**
12
+ * Log an activity (info-severity) event.
13
+ * @param name Operation name — promoted to the `operation_Name` column in 1DS.
14
+ * @param properties Optional bag of telemetry properties.
15
+ * @param eventName Override the canonical 1DS event name. Defaults to `PowerAppsClient.Activity`.
16
+ * **Avoid using this parameter** — it exists for infrastructure-level telemetry (e.g. HttpClient)
17
+ * that needs a distinct event name. Most callers should omit it.
18
+ */
19
+ trackActivityEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
20
+ /**
21
+ * Log a verbose (debug-severity) event.
22
+ * @param name Operation name — promoted to the `operation_Name` column in 1DS.
23
+ * @param properties Optional bag of telemetry properties.
24
+ * @param eventName Override the canonical 1DS event name. Defaults to `PowerAppsClient.Activity`.
25
+ * **Avoid using this parameter** — it exists for infrastructure-level telemetry (e.g. HttpClient)
26
+ * that needs a distinct event name. Most callers should omit it.
27
+ */
28
+ trackVerboseEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
29
+ /**
30
+ * Log an error-severity event.
31
+ * @param name Operation name — promoted to the `operation_Name` column in 1DS.
32
+ * @param properties Optional bag of telemetry properties.
33
+ * @param eventName Override the canonical 1DS event name. Defaults to `PowerAppsClient.Error`.
34
+ * **Avoid using this parameter** — it exists for infrastructure-level telemetry (e.g. HttpClient)
35
+ * that needs a distinct event name. Most callers should omit it.
36
+ */
37
+ trackErrorEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
38
+ trackScenario(name: string, properties?: Record<string, unknown>): ScenarioTracker;
39
+ setDefaultProperty(name: string, value: string): void;
40
+ identifyUser(identity: UserIdentity): void;
41
+ get sessionId(): string | undefined;
42
+ set sessionId(value: string);
43
+ flush(): Promise<void>;
44
+ }
45
+ //# sourceMappingURL=ILogger.d.ts.map
@@ -0,0 +1,28 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { ILogger, ScenarioTracker } from './ILogger.js';
5
+ import type { LoggerConfig, UserIdentity } from './TelemetryTypes.js';
6
+ /**
7
+ * Structured logger with canonical event names, severity filtering,
8
+ * sequence numbering, and scenario tracking.
9
+ * Supports multiple telemetry adapters; no-op safe when none are given.
10
+ */
11
+ export declare class Logger implements ILogger {
12
+ private readonly providers;
13
+ private readonly minSeverity;
14
+ private sequence;
15
+ constructor(config?: LoggerConfig);
16
+ trackActivityEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
17
+ trackVerboseEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
18
+ trackErrorEvent(name: string, properties?: Record<string, unknown>, eventName?: string): void;
19
+ trackScenario(name: string, properties?: Record<string, unknown>): ScenarioTracker;
20
+ setDefaultProperty(name: string, value: string): void;
21
+ identifyUser(identity: UserIdentity): void;
22
+ get sessionId(): string | undefined;
23
+ set sessionId(value: string);
24
+ flush(): Promise<void>;
25
+ private shouldLog;
26
+ private emit;
27
+ }
28
+ //# sourceMappingURL=Logger.d.ts.map
@@ -0,0 +1,39 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { ITelemetryProvider, OneDsTelemetryProviderConfig, TelemetryEnvelope, TelemetryEvent, TelemetrySeverity, UserIdentity } from './TelemetryTypes.js';
5
+ export declare class OneDsTelemetryProvider implements ITelemetryProvider {
6
+ private readonly appName;
7
+ private readonly appVersion;
8
+ private readonly clientType;
9
+ private readonly clusterCategory;
10
+ private readonly core;
11
+ private readonly defaultProperties;
12
+ private readonly deviceId;
13
+ private readonly deviceMake;
14
+ private readonly deviceModel;
15
+ private readonly deviceType;
16
+ private readonly osName;
17
+ private readonly osVersion;
18
+ private readonly userLocale;
19
+ private readonly userTimeZone;
20
+ private readonly propertyColumnMap;
21
+ readonly minSeverity: TelemetrySeverity;
22
+ private _sessionId;
23
+ private userIdentity?;
24
+ constructor(config: OneDsTelemetryProviderConfig);
25
+ /**
26
+ * Register a telemetry initializer that runs on every envelope before send.
27
+ * Use this to add Part A Common Schema extensions (ext.app, ext.web, ext.os, etc.)
28
+ * that require platform-specific APIs (e.g. browser info, OS info).
29
+ */
30
+ addTelemetryInitializer(initializer: (envelope: TelemetryEnvelope) => void): void;
31
+ track(event: TelemetryEvent): void;
32
+ flush(): Promise<void>;
33
+ teardown(): Promise<void>;
34
+ get sessionId(): string;
35
+ set sessionId(value: string);
36
+ identifyUser(identity: UserIdentity): void;
37
+ setDefaultProperty(name: string, value: string): void;
38
+ }
39
+ //# sourceMappingURL=OneDsTelemetryProvider.d.ts.map
@@ -0,0 +1,21 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ /**
5
+ * Redacts PII and credentials from a string.
6
+ * Safe to use on error messages, URL paths, and arbitrary text.
7
+ */
8
+ export declare function sanitizeErrorString(raw: string): string;
9
+ /**
10
+ * Strips the query string and URL fragment from a URL string, then redacts any
11
+ * PII/credentials in the remaining path.
12
+ */
13
+ export declare function sanitizeUrl(url: string): string;
14
+ /**
15
+ * Returns a copy of `props` with PII and credentials scrubbed:
16
+ * - Keys matching SENSITIVE_KEY_RE → value replaced with '<redacted>'
17
+ * - String values run through sanitizeErrorString
18
+ * - Non-string primitives passed through unchanged
19
+ */
20
+ export declare function sanitizeProperties(props: Record<string, unknown>): Record<string, unknown>;
21
+ //# sourceMappingURL=TelemetrySanitizer.d.ts.map
@@ -0,0 +1,88 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { ClusterCategory } from '../types/ClusterCategory.js';
5
+ export type TelemetrySeverity = 'verbose' | 'info' | 'warning' | 'error';
6
+ /** Canonical 1DS event names matching webplayer conventions. */
7
+ export declare const TelemetryEventNames: {
8
+ readonly Activity: "PowerAppsClient.Activity";
9
+ readonly Error: "PowerAppsClient.Error";
10
+ readonly StartScenario: "PowerAppsClient.StartScenario";
11
+ readonly EndScenario: "PowerAppsClient.EndScenario";
12
+ };
13
+ export declare const ScenarioResults: {
14
+ readonly Success: "Success";
15
+ readonly Failed: "Failed";
16
+ readonly SuccessWithErrors: "SuccessWithErrors";
17
+ };
18
+ export interface TelemetryEvent {
19
+ eventName: string;
20
+ timestamp: string;
21
+ severity: TelemetrySeverity;
22
+ sequenceNumber: number;
23
+ duration?: number;
24
+ properties: Record<string, string | number | boolean>;
25
+ }
26
+ export type PropertyColumnMap = Record<string, string>;
27
+ /** Telemetry data residency location. EU routes to eu-mobile collector. */
28
+ export type TelemetryLocation = 'global' | 'eu';
29
+ export interface UserIdentity {
30
+ tenantId: string;
31
+ objectId: string;
32
+ }
33
+ export interface LoggerConfig {
34
+ /** One or more telemetry adapters to fan events out to. */
35
+ providers?: ITelemetryProvider[];
36
+ }
37
+ export interface ITelemetryProvider {
38
+ track(event: TelemetryEvent): void;
39
+ flush(): Promise<void>;
40
+ teardown?(): Promise<void>;
41
+ get sessionId(): string;
42
+ set sessionId(value: string);
43
+ identifyUser(identity: UserIdentity): void;
44
+ setDefaultProperty(name: string, value: string): void;
45
+ /** Optional minimum severity the provider accepts. Used by Logger for filtering. */
46
+ readonly minSeverity?: TelemetrySeverity;
47
+ }
48
+ /**
49
+ * Structural type for the 1DS telemetry envelope passed to telemetry initializers.
50
+ * Decouples consumers from the internal `ITelemetryItem` type.
51
+ */
52
+ export interface TelemetryEnvelope {
53
+ name?: string;
54
+ time?: string;
55
+ data?: Record<string, unknown>;
56
+ ext?: Record<string, Record<string, unknown>>;
57
+ [key: string]: unknown;
58
+ }
59
+ export interface OneDsTelemetryProviderConfig {
60
+ /** Client type identifier promoted to the top-level `clientType` column (e.g. 'HostSdk', 'WebPlayer'). */
61
+ clientType: string;
62
+ clusterCategory: ClusterCategory;
63
+ /**
64
+ * Application version string (e.g. '1.2.3').
65
+ * Mapped to the `AppInfo_Version` Kusto column via `ext.app.ver`.
66
+ * Pass `Constants.expoConfig?.version` from expo-constants in the consuming app.
67
+ */
68
+ appVersion?: string;
69
+ /**
70
+ * Stable device identifier promoted to the top-level `device_Id` column.
71
+ * Obtain via `resolveDeviceId()` from `@microsoft/power-apps-native-common` at app startup
72
+ * and pass the result here. Falls back to `'react-native'` if omitted.
73
+ */
74
+ deviceId?: string;
75
+ /**
76
+ * 1DS instrumentation key (Aria project ID).
77
+ * When omitted, resolved automatically from `clusterCategory`.
78
+ */
79
+ instrumentationKey?: string;
80
+ /** Minimum severity to send to 1DS. Default: 'info' (skips verbose). */
81
+ minSeverity?: TelemetrySeverity;
82
+ /** Data residency location. Default: 'global'. Set to 'eu' for European environments. */
83
+ telemetryLocation?: TelemetryLocation;
84
+ commonProperties?: Record<string, string>;
85
+ propertyColumnMap?: PropertyColumnMap;
86
+ channelConfig?: Record<string, unknown>;
87
+ }
88
+ //# sourceMappingURL=TelemetryTypes.d.ts.map
@@ -0,0 +1,26 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import type { TelemetryLocation } from './TelemetryTypes.js';
5
+ /**
6
+ * Resolve the 1DS telemetry collector location from a Power Platform BAP
7
+ * environment `location` string (`environment.properties.location`).
8
+ * Returns `'eu'` when the location maps to the EU data boundary, routing
9
+ * telemetry to `eu-mobile.events.data.microsoft.com` instead of the global
10
+ * US collector.
11
+ *
12
+ * Mirrors the CLI's detection in `CliLogger.ts`:
13
+ * ```
14
+ * if (metadata?.properties?.location && EUGeoRegions.has(metadata.properties.location)) {
15
+ * telemetryLocation = 'eu';
16
+ * }
17
+ * ```
18
+ *
19
+ * @example
20
+ * resolveTelemetryLocation('europe') // → 'eu'
21
+ * resolveTelemetryLocation('unitedkingdom') // → 'eu'
22
+ * resolveTelemetryLocation('italy') // → 'eu'
23
+ * resolveTelemetryLocation('unitedstates') // → 'global'
24
+ */
25
+ export declare function resolveTelemetryLocation(input?: string): TelemetryLocation;
26
+ //# sourceMappingURL=resolveTelemetryLocation.d.ts.map
@@ -0,0 +1,10 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ /**
5
+ * Converts an unknown thrown value to a string suitable for telemetry.
6
+ * PII (email addresses, private IPv4 addresses) is redacted before the
7
+ * string is returned.
8
+ */
9
+ export declare function stringifyError(error: unknown): string;
10
+ //# sourceMappingURL=stringifyError.d.ts.map
@@ -0,0 +1,19 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ /**
5
+ * Suppresses known noisy LogBox warnings that originate from third-party
6
+ * packages and are not actionable in a React Native context.
7
+ *
8
+ * Call once at app startup (e.g. in the root `_layout.tsx` or `App.tsx`)
9
+ * before rendering any UI.
10
+ *
11
+ * **Why these warnings appear:**
12
+ * - `"Deprecated API for given entry type."` — emitted by React Native's
13
+ * Performance API when a caller requests an entry type (e.g. `"navigation"`,
14
+ * `"resource"`) that only exists in the browser W3C spec. The
15
+ * `@microsoft/power-apps` package calls `getEntriesByType('navigation')` for
16
+ * app-load telemetry; on React Native the call returns `[]` harmlessly.
17
+ */
18
+ export declare function suppressKnownWarnings(): void;
19
+ //# sourceMappingURL=suppressKnownWarnings.d.ts.map
@@ -0,0 +1,37 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ /**
5
+ * Identifies the Power Platform cluster environment category.
6
+ * Used to resolve telemetry endpoints, instrumentation keys, and collector URLs.
7
+ *
8
+ * This is the **normalised** internal form used by telemetry providers.
9
+ * The raw `region` string from power.config.json may differ — use
10
+ * `regionToClusterCategory()` to convert before passing here.
11
+ *
12
+ * Canonical power.config.json `region` values → ClusterCategory mapping:
13
+ * preview → prod
14
+ * gccmoderate → gov
15
+ * gcchigh → high
16
+ * (all others are identity mappings)
17
+ */
18
+ export type ClusterCategory = 'local' | 'dev' | 'test' | 'preprod' | 'prod' | 'firstrelease' | 'ex' | 'rx' | 'mooncake' | 'gov' | 'high' | 'dod';
19
+ /**
20
+ * All valid `region` strings accepted in power.config.json.
21
+ * Mirrors the `Region` type from `@microsoft/power-apps-common/services`.
22
+ */
23
+ export declare const Regions: readonly ["local", "dev", "test", "preprod", "preview", "prod", "firstrelease", "gccmoderate", "gcchigh", "dod", "mooncake", "ex", "rx"];
24
+ export type Region = (typeof Regions)[number];
25
+ /**
26
+ * Normalise a power.config.json `region` string to the internal
27
+ * `ClusterCategory` used by telemetry providers.
28
+ *
29
+ * Mirrors the CLI's `regionToClusterCategory` in OneDSWriter.ts:
30
+ * preview → prod (preview ring uses production telemetry)
31
+ * gccmoderate → gov (GCC Moderate sovereign cloud)
32
+ * gcchigh → high (GCC High sovereign cloud)
33
+ * firstrelease → firstrelease (first-release prod ring)
34
+ * all others → identity
35
+ */
36
+ export declare function regionToClusterCategory(region: Region | string): ClusterCategory;
37
+ //# sourceMappingURL=ClusterCategory.d.ts.map
@@ -0,0 +1,29 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ /**
5
+ * Returns a stable device identifier, preferring platform-native IDs that
6
+ * survive app reinstalls:
7
+ *
8
+ * - **iOS**: `getIosIdForVendorAsync()` (IDFV) — stable while ≥1 app from the
9
+ * same vendor bundle prefix is installed. Resets only when ALL vendor apps
10
+ * are removed.
11
+ * - **Android**: `getAndroidId()` (SSAID) — scoped to the app signing key on
12
+ * Android 8+; survives reinstalls as long as the signing key is unchanged.
13
+ *
14
+ * If the platform API returns null (rare edge cases: first boot, some emulators)
15
+ * the function falls back to a UUID persisted in `expo-secure-store`, which on
16
+ * iOS survives reinstalls via the Keychain and on Android is per-install only.
17
+ *
18
+ * Pass the resolved value to `OneDsTelemetryProviderConfig.deviceId` at startup.
19
+ *
20
+ * @example
21
+ * ```ts
22
+ * import { resolveDeviceId, OneDsTelemetryProvider } from '@microsoft/power-apps-native-common';
23
+ *
24
+ * const deviceId = await resolveDeviceId();
25
+ * const telemetry = new OneDsTelemetryProvider({ deviceId, ... });
26
+ * ```
27
+ */
28
+ export declare function resolveDeviceId(): Promise<string>;
29
+ //# sourceMappingURL=DeviceIdUtils.d.ts.map
@@ -0,0 +1,11 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ import 'react-native-get-random-values';
5
+ /**
6
+ * Generates a RFC-4122 v4 GUID/UUID string.
7
+ * Uses the `uuid` package (backed by `react-native-get-random-values` on RN)
8
+ * instead of `crypto.randomUUID()` which is unavailable in Hermes/JSC.
9
+ */
10
+ export declare function generateGuid(): string;
11
+ //# sourceMappingURL=GuidUtils.d.ts.map
@@ -0,0 +1,33 @@
1
+ /*!
2
+ * Copyright (C) Microsoft Corporation. All rights reserved.
3
+ */
4
+ export interface PlatformInfo {
5
+ /** OS name (e.g. 'iOS', 'iPadOS', 'Android'). Maps to Kusto DeviceInfo_OsName. */
6
+ osName: string;
7
+ /** OS version string (e.g. '18.5', '14'). Maps to Kusto DeviceInfo_OsVersion. */
8
+ osVersion: string;
9
+ /** Device manufacturer (e.g. 'Apple', 'Google', 'Samsung'). Maps to Kusto DeviceInfo_Make. */
10
+ deviceMake: string;
11
+ /** Human-friendly device model name (e.g. 'iPhone 16 Pro', 'Pixel 9'). Maps to Kusto DeviceInfo_Model. */
12
+ deviceModel: string;
13
+ /** Form factor: 'Phone', 'Tablet', 'Desktop', 'TV', or 'Unknown'. */
14
+ deviceType: string;
15
+ /** BCP-47 locale string (e.g. 'en-US'). Maps to Kusto UserInfo_Language. */
16
+ userLocale: string;
17
+ /** IANA time zone (e.g. 'America/Los_Angeles'). Maps to Kusto UserInfo_TimeZone. */
18
+ userTimeZone: string;
19
+ }
20
+ /**
21
+ * Resolves 1DS Part A Common Schema device/OS/locale values using `expo-device`
22
+ * and the Intl API. Provides more accurate data than raw Platform.constants:
23
+ *
24
+ * - Correctly returns `'iPadOS'` for iPad (not `'iOS'`).
25
+ * - Returns human-friendly `modelName` (e.g. `'iPhone 16 Pro'`, `'Pixel 9'`).
26
+ * - Returns proper `manufacturer` (e.g. `'Apple'`, `'Google'`, `'Samsung'`).
27
+ * - Includes form-factor `deviceType` (Phone / Tablet / Desktop / TV).
28
+ *
29
+ * Safe to call once at provider construction time — all values are stable for
30
+ * the lifetime of the process.
31
+ */
32
+ export declare function resolvePlatformInfo(): PlatformInfo;
33
+ //# sourceMappingURL=PlatformInfoUtils.d.ts.map
package/package.json ADDED
@@ -0,0 +1,83 @@
1
+ {
2
+ "name": "@microsoft/power-apps-native-common",
3
+ "version": "0.1.8",
4
+ "description": "Shared utilities and types for Power Apps native packages",
5
+ "author": "Microsoft Corporation",
6
+ "license": "SEE LICENSE IN LICENSE",
7
+ "bugs": {
8
+ "email": "pawrap-team@microsoft.com"
9
+ },
10
+ "main": "./lib/commonjs/index.js",
11
+ "module": "./lib/module/index.js",
12
+ "types": "./lib/typescript/commonjs/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "import": {
16
+ "types": "./lib/typescript/module/index.d.ts",
17
+ "default": "./lib/module/index.js"
18
+ },
19
+ "require": {
20
+ "types": "./lib/typescript/commonjs/index.d.ts",
21
+ "default": "./lib/commonjs/index.js"
22
+ }
23
+ },
24
+ "./package.json": "./package.json"
25
+ },
26
+ "files": [
27
+ "lib/",
28
+ "!lib/**/*.map"
29
+ ],
30
+ "scripts": {
31
+ "prepack": "bob build && node ../../scripts/notices.js",
32
+ "build": "bob build && node ../../scripts/notices.js",
33
+ "type-check": "tsc --noEmit"
34
+ },
35
+ "peerDependencies": {
36
+ "expo-application": ">=6.0.0",
37
+ "expo-device": ">=6.0.0",
38
+ "expo-secure-store": ">=14.0.0",
39
+ "react": ">=19.2.0",
40
+ "react-native": ">=0.83.4",
41
+ "react-native-get-random-values": ">=1.9.0"
42
+ },
43
+ "dependencies": {
44
+ "@microsoft/1ds-post-js": "4.4.1",
45
+ "@microsoft/applicationinsights-core-js": "3.4.1",
46
+ "uuid": "^11.1.1"
47
+ },
48
+ "devDependencies": {
49
+ "@types/react": "19.2.14",
50
+ "@types/uuid": "^10.0.0",
51
+ "typescript": "5.8.3"
52
+ },
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "sideEffects": false,
57
+ "react-native-builder-bob": {
58
+ "source": "src",
59
+ "output": "lib",
60
+ "targets": [
61
+ [
62
+ "module",
63
+ {
64
+ "esm": true,
65
+ "sourceMaps": false
66
+ }
67
+ ],
68
+ [
69
+ "commonjs",
70
+ {
71
+ "esm": true,
72
+ "sourceMaps": false
73
+ }
74
+ ],
75
+ [
76
+ "typescript",
77
+ {
78
+ "project": "tsconfig.json"
79
+ }
80
+ ]
81
+ ]
82
+ }
83
+ }