@procore/ai-translations 0.5.0 → 0.6.1

package/dist/modern/index.d.mts

@@ -2,6 +2,35 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+/** Shape of an analytic event passed to the MFE's `onTrackAnalyticsEvent` callback. */
+interface AnalyticEvent {
+    key: string;
+    properties: Record<string, unknown>;
+}
+/** Function provided by the MFE that sends the event to the analytics destination. */
+type AIAnalyticsTracker = (event: AnalyticEvent) => void;
+/** Feature scope: `'project'` for project-level tools, `'company'` for company-level tools. */
+type Scope = 'project' | 'company';
+/**
+ * Parts needed to build an event key following the pattern:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+interface EventKeyParts {
+    scope: Scope;
+    tool: string;
+    object: string;
+    action: string;
+}
+/** Standard properties included in every AI analytics event. */
+interface AIAnalyticsEventProperties {
+    user_locale: string;
+    project_locale?: string;
+    company_locale?: string;
+    tool: string;
+    page: string;
+    [key: string]: unknown;
+}
+
 interface TranslationProgress {
     /**
      * Progress percentage (0-100)
@@ -39,12 +68,22 @@ interface ModelDownloadProgress {
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
     locale: string;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). */
+    projectLocale?: string;
     renderVersion?: number;
     /** Batch-translation progress; `null` while the queue is idle. */
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
     tool: string;
+    /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context used to build the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 
 interface ConfigurationResponse {
@@ -117,6 +156,59 @@ declare function useConfig(toolName: string, options?: UseConfigOptions): _tanst
  */
 declare function useAITranslation(): AITranslationContextValue;
 
+/** Button type identifiers for the event key `object` segment. */
+declare const BUTTON_TYPE: {
+    readonly TRANSLATE: "translate";
+    readonly HIGHLIGHT: "highlight";
+};
+type ButtonType = (typeof BUTTON_TYPE)[keyof typeof BUTTON_TYPE];
+/** Action identifiers for the event key `action` segment. */
+declare const ACTION: {
+    readonly CLICKED: "clicked";
+};
+type Action = (typeof ACTION)[keyof typeof ACTION];
+/**
+ * Builds the `object` segment: `{pageContext}_{buttonType}_button`
+ * e.g. `buildObject('view', 'translate')` → `'view_translate_button'`
+ */
+declare function buildObject(pageContext: string, buttonType: ButtonType): string;
+/**
+ * Builds a fully-qualified event key:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+declare function buildEventKey(parts: EventKeyParts): string;
+interface BuildAnalyticEventParams {
+    scope: Scope;
+    tool: string;
+    /** Prefix for the object segment, matches the Provider `page` prop (e.g. `'view'`). */
+    pageContext: string;
+    buttonType: ButtonType;
+    baseProperties: AIAnalyticsEventProperties;
+    /** Defaults to `'clicked'` if omitted. */
+    action?: Action;
+    additionalProperties?: Record<string, unknown>;
+}
+/** Assembles a complete `AnalyticEvent` (key + merged properties) ready for `onTrackAnalyticsEvent`. */
+declare function buildAnalyticEvent(params: BuildAnalyticEventParams): AnalyticEvent;
+
+interface UseAIAnalyticsReturn {
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_translate_button.clicked`. */
+    trackTranslateButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_highlight_button.clicked`. */
+    trackHighlightButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Generic tracking for custom button types or actions. */
+    trackCustomEvent: (buttonType: ButtonType | string, action?: Action | string, additionalProperties?: Record<string, unknown>) => void;
+    /** `true` when `onTrackAnalyticsEvent` was provided to `AITranslationProvider`. */
+    isTrackingEnabled: boolean;
+}
+/**
+ * Returns analytics tracking helpers pre-wired to the Provider context.
+ * All functions no-op if `onTrackAnalyticsEvent` was not supplied.
+ *
+ * @throws if called outside of an `AITranslationProvider`.
+ */
+declare function useAIAnalytics(): UseAIAnalyticsReturn;
+
 interface AITranslationProviderProps {
     children: ReactNode;
     locale: string;
@@ -125,6 +217,16 @@ interface AITranslationProviderProps {
     userId: number;
     projectId: number;
     enableAIT?: boolean;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). Passed through to context for downstream consumers such as Amplitude. */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). Passed through to context for downstream consumers such as Amplitude. */
+    projectLocale?: string;
+    /** Called by `useAIAnalytics` with a pre-assembled event. The MFE sends it to the analytics API. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context for the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 declare function AITranslationProvider(props: AITranslationProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -177,4 +279,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type TranslatedIconProps, type UseConfigOptions, getAITranslationLDId, useAITranslation, useConfig };
+export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, type EventKeyParts, type Scope, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, useAIAnalytics, useAITranslation, useConfig };

package/dist/modern/index.d.ts

@@ -2,6 +2,35 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+/** Shape of an analytic event passed to the MFE's `onTrackAnalyticsEvent` callback. */
+interface AnalyticEvent {
+    key: string;
+    properties: Record<string, unknown>;
+}
+/** Function provided by the MFE that sends the event to the analytics destination. */
+type AIAnalyticsTracker = (event: AnalyticEvent) => void;
+/** Feature scope: `'project'` for project-level tools, `'company'` for company-level tools. */
+type Scope = 'project' | 'company';
+/**
+ * Parts needed to build an event key following the pattern:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+interface EventKeyParts {
+    scope: Scope;
+    tool: string;
+    object: string;
+    action: string;
+}
+/** Standard properties included in every AI analytics event. */
+interface AIAnalyticsEventProperties {
+    user_locale: string;
+    project_locale?: string;
+    company_locale?: string;
+    tool: string;
+    page: string;
+    [key: string]: unknown;
+}
+
 interface TranslationProgress {
     /**
      * Progress percentage (0-100)
@@ -39,12 +68,22 @@ interface ModelDownloadProgress {
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
     locale: string;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). */
+    projectLocale?: string;
     renderVersion?: number;
     /** Batch-translation progress; `null` while the queue is idle. */
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
     tool: string;
+    /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context used to build the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 
 interface ConfigurationResponse {
@@ -117,6 +156,59 @@ declare function useConfig(toolName: string, options?: UseConfigOptions): _tanst
  */
 declare function useAITranslation(): AITranslationContextValue;
 
+/** Button type identifiers for the event key `object` segment. */
+declare const BUTTON_TYPE: {
+    readonly TRANSLATE: "translate";
+    readonly HIGHLIGHT: "highlight";
+};
+type ButtonType = (typeof BUTTON_TYPE)[keyof typeof BUTTON_TYPE];
+/** Action identifiers for the event key `action` segment. */
+declare const ACTION: {
+    readonly CLICKED: "clicked";
+};
+type Action = (typeof ACTION)[keyof typeof ACTION];
+/**
+ * Builds the `object` segment: `{pageContext}_{buttonType}_button`
+ * e.g. `buildObject('view', 'translate')` → `'view_translate_button'`
+ */
+declare function buildObject(pageContext: string, buttonType: ButtonType): string;
+/**
+ * Builds a fully-qualified event key:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+declare function buildEventKey(parts: EventKeyParts): string;
+interface BuildAnalyticEventParams {
+    scope: Scope;
+    tool: string;
+    /** Prefix for the object segment, matches the Provider `page` prop (e.g. `'view'`). */
+    pageContext: string;
+    buttonType: ButtonType;
+    baseProperties: AIAnalyticsEventProperties;
+    /** Defaults to `'clicked'` if omitted. */
+    action?: Action;
+    additionalProperties?: Record<string, unknown>;
+}
+/** Assembles a complete `AnalyticEvent` (key + merged properties) ready for `onTrackAnalyticsEvent`. */
+declare function buildAnalyticEvent(params: BuildAnalyticEventParams): AnalyticEvent;
+
+interface UseAIAnalyticsReturn {
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_translate_button.clicked`. */
+    trackTranslateButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_highlight_button.clicked`. */
+    trackHighlightButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Generic tracking for custom button types or actions. */
+    trackCustomEvent: (buttonType: ButtonType | string, action?: Action | string, additionalProperties?: Record<string, unknown>) => void;
+    /** `true` when `onTrackAnalyticsEvent` was provided to `AITranslationProvider`. */
+    isTrackingEnabled: boolean;
+}
+/**
+ * Returns analytics tracking helpers pre-wired to the Provider context.
+ * All functions no-op if `onTrackAnalyticsEvent` was not supplied.
+ *
+ * @throws if called outside of an `AITranslationProvider`.
+ */
+declare function useAIAnalytics(): UseAIAnalyticsReturn;
+
 interface AITranslationProviderProps {
     children: ReactNode;
     locale: string;
@@ -125,6 +217,16 @@ interface AITranslationProviderProps {
     userId: number;
     projectId: number;
     enableAIT?: boolean;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). Passed through to context for downstream consumers such as Amplitude. */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). Passed through to context for downstream consumers such as Amplitude. */
+    projectLocale?: string;
+    /** Called by `useAIAnalytics` with a pre-assembled event. The MFE sends it to the analytics API. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context for the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 declare function AITranslationProvider(props: AITranslationProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -177,4 +279,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type TranslatedIconProps, type UseConfigOptions, getAITranslationLDId, useAITranslation, useConfig };
+export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, type EventKeyParts, type Scope, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, useAIAnalytics, useAITranslation, useConfig };