@braze/sanity-plugin-ai-translation 0.2.69 → 0.2.72

package/dist/index.js

@@ -1039,6 +1039,57 @@ const fetchTranslationPrompts = async ({
         payload
       }), mainSourceDocumentId && updateActiveTranslationJob(mainSourceDocumentId, payload);
     }
+}, emitTelemetryEvent = (config, event) => {
+  if (config?.onEvent)
+    try {
+      config.onEvent(event), devLog.debug("Telemetry event emitted", { eventName: event.name });
+    } catch (error) {
+      devLog.warn("Failed to emit telemetry event", {
+        eventName: event.name,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+}, emitTelemetryError = (config, bundle) => {
+  if (config?.onError)
+    try {
+      config.onError(bundle), devLog.debug("Telemetry error emitted", {
+        documentId: bundle.documentId,
+        errorType: bundle.error.type
+      });
+    } catch (error) {
+      devLog.warn("Failed to emit telemetry error", {
+        documentId: bundle.documentId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+}, buildErrorBundle = (params) => {
+  const durationMs = Date.now() - params.startTime;
+  return {
+    documentId: params.documentId,
+    documentType: params.documentType,
+    targetLanguage: params.targetLanguage,
+    sourceLanguage: params.sourceLanguage,
+    translationMode: params.translationMode,
+    error: {
+      message: params.error.message,
+      stack: params.error.stack,
+      type: params.errorType
+    },
+    debug: {
+      originalDocument: params.originalDocument,
+      serializedDocument: params.serializedDocument,
+      openaiResponse: params.openaiResponse,
+      translationPrompts: params.translationPrompts,
+      validationErrors: params.validationErrors
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    durationMs
+  };
+}, createTimestamp = () => (/* @__PURE__ */ new Date()).toISOString(), classifyError = (error, context) => {
+  if (context)
+    return context;
+  const message = error.message.toLowerCase();
+  return message.includes("network") || message.includes("fetch") || message.includes("timeout") || message.includes("econnrefused") || message.includes("enotfound") ? "network" : message.includes("openai") || message.includes("gpt") || message.includes("api error") ? "openai_api" : message.includes("validation") || message.includes("structure") || message.includes("invalid") ? "validation" : message.includes("deserialize") || message.includes("parse") ? "deserialization" : message.includes("serialize") || message.includes("xml") ? "serialization" : message.includes("agent") || message.includes("sanity") ? "sanity_agent" : "unknown";
 }, updateTranslationMetadata = async ({
   client,
   targetLanguage,
@@ -2231,16 +2282,18 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
   translationPrompts,
   targetLanguage,
   openaiConfig,
-  previousError,
-  errorContext
+  previousError: _previousError,
+  errorContext,
+  telemetryConfig
 }) => {
-  const sourceLanguage = sourceDocument[languageFieldName], logContext = {
+  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], logContext = {
     sourceId: sourceDocument._id,
     sourceLanguage
   };
+  let serializedDocument, openaiResponseContent;
   try {
     const sourceText = serializeDocument(sourceDocument);
-    devLog.info("Serialized document for OpenAI", {
+    serializedDocument = sourceText, devLog.info("Serialized document for OpenAI", {
       ...logContext,
       characterCount: sourceText.length,
       estimatedTokens: Math.ceil(sourceText.length / 4),
@@ -2263,7 +2316,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
       model: openaiConfig.model,
       reasoningEffort: openaiConfig.reasoningEffort
     });
-    devLog.info("OpenAI translation response received", {
+    openaiResponseContent = response.content, devLog.info("OpenAI translation response received", {
       ...logContext,
       tokensUsed: response.tokensUsed,
       cost: response.cost,
@@ -2301,9 +2354,35 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     })), setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating_with_openai", {
       tokensUsed: response.tokensUsed.total,
       estimatedCost: response.cost
-    }), result;
+    }), {
+      document: result,
+      tokensUsed: response.tokensUsed.total,
+      cost: response.cost
+    };
   } catch (error) {
-    throw devLog.error("OpenAI translation failed", error instanceof Error ? error : new Error(String(error)), logContext), error;
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw devLog.error("OpenAI translation failed", err, logContext), emitTelemetryError(
+      telemetryConfig,
+      buildErrorBundle({
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        targetLanguage,
+        sourceLanguage,
+        translationMode: "openai-only",
+        error: err,
+        errorType: classifyError(err, "openai_api"),
+        startTime,
+        originalDocument: sourceDocument,
+        serializedDocument,
+        openaiResponse: openaiResponseContent,
+        translationPrompts: {
+          globalPrompt: translationPrompts.globalPrompt,
+          localePrompt: translationPrompts.localeInstructions[targetLanguage]?.prompt,
+          protectedPhrases: translationPrompts.protectedPhrases,
+          glossaryTerms: translationPrompts.localeInstructions[targetLanguage]?.glossaryTerms ? [translationPrompts.localeInstructions[targetLanguage].glossaryTerms] : void 0
+        }
+      })
+    ), error;
   }
 }, buildTranslationPrompt$1 = ({
   sourceText,
@@ -2539,9 +2618,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   releaseId,
   excludeFields = [],
   replaceExisting = !1,
-  mainSourceDocumentId
+  mainSourceDocumentId,
+  telemetryConfig
 }) => {
-  const safeExcludeFields = excludeFields.filter((field) => field !== languageFieldName);
+  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], safeExcludeFields = excludeFields.filter((field) => field !== languageFieldName);
   excludeFields.length !== safeExcludeFields.length && devLog.warn("Language field was in excludeFields - removing it to prevent translation errors", {
     documentId: sourceDocument._id,
     languageFieldName,
@@ -2580,29 +2660,55 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       documentId: sourceDocument._id,
       documentType: sourceDocument._type
     }), documentToTranslate = filteredDocument;
-  let translatedDoc, previousError = null;
+  let translatedDoc, translationMetrics = {}, previousError = null;
   const performTranslation = async (errorContext) => {
     switch (translationMode) {
-      case "sanity-only":
-        return setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating", void 0, mainSourceDocumentId), await getSanityAgentTranslation({
-          sourceDocument: documentToTranslate,
-          targetLanguage,
-          languageFieldName,
-          schemaId,
-          client,
-          translationPrompts
-        });
+      case "sanity-only": {
+        setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating", void 0, mainSourceDocumentId);
+        try {
+          return { document: await getSanityAgentTranslation({
+            sourceDocument: documentToTranslate,
+            targetLanguage,
+            languageFieldName,
+            schemaId,
+            client,
+            translationPrompts
+          }) };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          throw emitTelemetryError(
+            telemetryConfig,
+            buildErrorBundle({
+              documentId: sourceDocument._id,
+              documentType: sourceDocument._type,
+              targetLanguage,
+              sourceLanguage,
+              translationMode: "sanity-only",
+              error: err,
+              errorType: classifyError(err, "sanity_agent"),
+              startTime,
+              originalDocument: sourceDocument,
+              translationPrompts: {
+                globalPrompt: translationPrompts.globalPrompt,
+                localePrompt: translationPrompts.localeInstructions[targetLanguage]?.prompt,
+                protectedPhrases: translationPrompts.protectedPhrases
+              }
+            })
+          ), error;
+        }
+      }
       case "openai-only": {
         if (!openaiConfig?.enabled || !openaiConfig?.apiKey)
           throw new Error("OpenAI is not configured but openai-only mode was selected");
-        return setJobStatus(
+        setJobStatus(
           dispatch,
           sourceDocument._id,
           targetLanguage,
           "translating_with_openai",
           void 0,
           mainSourceDocumentId
-        ), await getOpenAITranslation({
+        );
+        const result = await getOpenAITranslation({
           dispatch,
           sourceDocument: documentToTranslate,
           targetLanguage,
@@ -2610,14 +2716,23 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           translationPrompts,
           openaiConfig,
           previousError: errorContext && previousError ? previousError : void 0,
-          errorContext
+          errorContext,
+          telemetryConfig
         });
+        return result ? {
+          document: result.document,
+          tokensUsed: result.tokensUsed,
+          cost: result.cost
+        } : { document: null };
       }
       default:
         throw new Error(`Invalid translation mode: ${translationMode}`);
     }
-  };
-  if (translatedDoc = await performTranslation(), !translatedDoc)
+  }, translationResult = await performTranslation();
+  if (translatedDoc = translationResult.document, translationMetrics = {
+    tokensUsed: translationResult.tokensUsed,
+    cost: translationResult.cost
+  }, !translatedDoc)
     return null;
   let transformedResult;
   Object.keys(originalStructure).length > 0 ? (devLog.debug("Restoring field transforms after translation", {
@@ -2680,9 +2795,13 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         targetLanguage,
         error: error instanceof Error ? error.message : String(error)
       }), previousError = error instanceof Error ? error : new Error(String(error));
-      const errorContext = `Previous translation attempt failed with Sanity validation error: ${previousError.message}. Please ensure the translated document structure exactly matches the source document structure.`;
-      if (translatedDoc = await performTranslation(errorContext), !translatedDoc)
+      const errorContext = `Previous translation attempt failed with Sanity validation error: ${previousError.message}. Please ensure the translated document structure exactly matches the source document structure.`, retryResult = await performTranslation(errorContext);
+      if (translatedDoc = retryResult.document, !translatedDoc)
         throw new Error("Translation retry failed: no document returned");
+      translationMetrics = {
+        tokensUsed: retryResult.tokensUsed,
+        cost: retryResult.cost
+      };
       let retryTransformedResult;
       Object.keys(originalStructure).length > 0 ? retryTransformedResult = restoreTransforms({
         translatedDocument: translatedDoc,
@@ -2713,11 +2832,19 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
             isRetry: !0
           }
         }
-      ), retryNewDoc;
+      ), {
+        document: retryNewDoc,
+        tokensUsed: translationMetrics.tokensUsed,
+        cost: translationMetrics.cost
+      };
     }
     throw error;
   }
-  return newDoc;
+  return {
+    document: newDoc,
+    tokensUsed: translationMetrics.tokensUsed,
+    cost: translationMetrics.cost
+  };
 }, translateDocument = async ({
   dispatch,
   client,
@@ -2732,9 +2859,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   releaseId,
   excludeFields,
   replaceExisting,
-  mainSourceDocumentId
+  mainSourceDocumentId,
+  telemetryConfig
 }) => {
-  const logContext = {
+  const jobStartTime = Date.now(), logContext = {
     documentId: sourceDocument._id,
     targetLanguage,
     schemaId,
@@ -2746,7 +2874,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       client,
       sourceDocument,
       sourceLanguage
-    }), existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), newDocument = await handleTranslation({
+    }), existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), translationResult = await handleTranslation({
       dispatch,
       client,
       schemaId,
@@ -2760,10 +2888,12 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       releaseId,
       excludeFields,
       replaceExisting,
-      mainSourceDocumentId
-    });
+      mainSourceDocumentId,
+      telemetryConfig
+    }), newDocument = translationResult?.document;
     if (!newDocument) {
-      devLog.error("Translation failed: no document returned", new Error("Translation returned null"), logContext), setJobStatus(
+      const failureError = new Error("Translation returned null");
+      devLog.error("Translation failed: no document returned", failureError, logContext), setJobStatus(
         dispatch,
         sourceDocument._id,
         targetLanguage,
@@ -2772,7 +2902,20 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           errorMessage: "Translation failed"
         },
         mainSourceDocumentId
-      ), devLog.timeEnd("translateDocument"), devLog.groupEnd();
+      ), emitTelemetryEvent(telemetryConfig, {
+        name: "translation.job_failed",
+        timestamp: createTimestamp(),
+        data: {
+          documentId: sourceDocument._id,
+          documentType: sourceDocument._type,
+          sourceLanguage,
+          targetLanguage,
+          translationMode,
+          durationMs: Date.now() - jobStartTime,
+          errorType: classifyError(failureError),
+          errorMessage: "Translation failed"
+        }
+      }), devLog.timeEnd("translateDocument"), devLog.groupEnd();
       return;
     }
     return setJobStatus(
@@ -2798,16 +2941,31 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       targetLanguage,
       "completed",
       {
-        targetId: newDocument._id
+        targetId: newDocument._id,
+        tokensUsed: translationResult?.tokensUsed,
+        estimatedCost: translationResult?.cost
       },
       mainSourceDocumentId
     ), devLog.info("Translation completed successfully", {
       ...logContext,
       newDocumentId: newDocument._id
+    }), emitTelemetryEvent(telemetryConfig, {
+      name: "translation.job_completed",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguage,
+        translationMode,
+        durationMs: Date.now() - jobStartTime,
+        tokensUsed: translationResult?.tokensUsed,
+        estimatedCost: translationResult?.cost
+      }
     }), devLog.timeEnd("translateDocument"), devLog.groupEnd(), newDocument._id;
   } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    devLog.error("Translation failed", error instanceof Error ? error : new Error(String(error)), logContext), setJobStatus(
+    const errorMessage = error instanceof Error ? error.message : String(error), errorObj = error instanceof Error ? error : new Error(String(error));
+    devLog.error("Translation failed", errorObj, logContext), setJobStatus(
       dispatch,
       sourceDocument._id,
       targetLanguage,
@@ -2816,7 +2974,20 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         errorMessage
       },
       mainSourceDocumentId
-    ), devLog.timeEnd("translateDocument"), devLog.groupEnd();
+    ), emitTelemetryEvent(telemetryConfig, {
+      name: "translation.job_failed",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguage,
+        translationMode,
+        durationMs: Date.now() - jobStartTime,
+        errorType: classifyError(errorObj),
+        errorMessage
+      }
+    }), devLog.timeEnd("translateDocument"), devLog.groupEnd();
     return;
   }
 }, translationSemaphore = new Semaphore(2), translateDocumentSet = async ({
@@ -2831,9 +3002,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationMode,
   openaiConfig,
   excludeFields,
-  releaseConfig
+  releaseConfig,
+  telemetryConfig
 }) => {
-  const logContext = {
+  const batchStartTime = Date.now(), logContext = {
     documentId: sourceDocument._id,
     documentRev: sourceDocument._rev,
     targetLanguages,
@@ -2847,7 +3019,19 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     const sourceLanguage = sourceDocument[languageFieldName];
     if (!sourceLanguage)
       throw devLog.error("Source language not found"), new Error("Source language not found");
-    if (maxConcurrentTranslationJobs && translationSemaphore.updatePermits(maxConcurrentTranslationJobs), dispatch({
+    if (emitTelemetryEvent(telemetryConfig, {
+      name: "translation.batch_started",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguages,
+        translationMode,
+        referenceCount: references.length,
+        releaseMode: releaseConfig.mode
+      }
+    }), maxConcurrentTranslationJobs && translationSemaphore.updatePermits(maxConcurrentTranslationJobs), dispatch({
       type: "SET_OVERALL_STATUS",
       payload: "translating"
     }), releaseConfig.mode === "existing" && releaseConfig.existingReleaseId)
@@ -2940,7 +3124,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                 excludeFields,
                 replaceExisting: releaseConfig.replaceExisting,
                 // Pass main source document ID for active translations tracking
-                mainSourceDocumentId: sourceDocument._id
+                mainSourceDocumentId: sourceDocument._id,
+                telemetryConfig
               });
               versionedTargetDocumentId && versionedTargetDocumentIds.push(versionedTargetDocumentId);
             }
@@ -2965,6 +3150,20 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       failed,
       skipped: skippedCount,
       targetDocuments: versionedTargetDocumentIds.length
+    }), emitTelemetryEvent(telemetryConfig, {
+      name: "translation.batch_completed",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguages,
+        translationMode,
+        succeeded,
+        failed,
+        skipped: skippedCount,
+        durationMs: Date.now() - batchStartTime
+      }
     }), dispatch({
       type: "SET_OVERALL_STATUS",
       payload: "linking_references"
@@ -3110,7 +3309,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           // Use the override release ID if provided (from conflict context),
           // otherwise use the current releaseConfig value
           existingReleaseId: overrideReleaseId ?? releaseConfig.existingReleaseId
-        }
+        },
+        telemetryConfig: config.telemetry
       });
     },
     [
@@ -3124,6 +3324,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       config.maxReferenceDepth,
       config.openai,
       config.excludeFields,
+      config.telemetry,
       filteredReferences,
       translationMode,
       releaseConfig
@@ -3343,7 +3544,9 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     }), error;
   }
 }, ReconcileReferencesButton = ({ sourceLanguage }) => {
-  const { dispatch, releaseConfig, overallStatus, reconcilingStatus, reconciliationProgress, config } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [documentCount, setDocumentCount] = useState(null), [isLoadingCount, setIsLoadingCount] = useState(!1), releaseId = releaseConfig.existingReleaseId, languageFieldName = config?.languageFieldName ?? "language";
+  const { releaseConfig, overallStatus, config } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [documentCount, setDocumentCount] = useState(null), [isLoadingCount, setIsLoadingCount] = useState(!1), [reconcilingStatus, setReconcilingStatus] = useState("idle"), [reconciliationProgress, setReconciliationProgress] = useState(
+    void 0
+  ), releaseId = releaseConfig.existingReleaseId, languageFieldName = config?.languageFieldName ?? "language";
   useEffect(() => {
     if (!releaseId || releaseConfig.mode !== "existing") {
       setDocumentCount(null);
@@ -3378,7 +3581,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         releaseId,
         sourceLanguage,
         component: "ReconcileReferencesButton"
-      }), dispatch({ type: "SET_RECONCILING_STATUS", payload: "reconciling" });
+      }), setReconcilingStatus("reconciling");
       try {
         const result = await reconcileReleaseReferences({
           client,
@@ -3386,27 +3589,24 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           sourceLanguage,
           languageFieldName,
           onProgress: (current, total) => {
-            dispatch({
-              type: "SET_RECONCILIATION_PROGRESS",
-              payload: { current, total }
-            });
+            setReconciliationProgress({ current, total });
           }
         });
         devLog.info("Reference reconciliation completed", {
           releaseId,
           ...result,
           component: "ReconcileReferencesButton"
-        }), dispatch({ type: "SET_RECONCILING_STATUS", payload: "completed" }), setTimeout(() => {
-          dispatch({ type: "SET_RECONCILING_STATUS", payload: "idle" });
+        }), setReconcilingStatus("completed"), setTimeout(() => {
+          setReconcilingStatus("idle"), setReconciliationProgress(void 0);
         }, 2e3);
       } catch (error) {
         devLog.error("Reference reconciliation failed", error instanceof Error ? error : new Error(String(error)), {
           releaseId,
           component: "ReconcileReferencesButton"
-        }), dispatch({ type: "SET_RECONCILING_STATUS", payload: "error" });
+        }), setReconcilingStatus("error"), setReconciliationProgress(void 0);
       }
     }
-  }, [releaseId, sourceLanguage, languageFieldName, client, dispatch]);
+  }, [releaseId, sourceLanguage, languageFieldName, client]);
   if (releaseConfig.mode !== "existing" || !releaseId)
     return null;
   const isTranslating = overallStatus === "translating" || overallStatus === "linking_references", isReconciling = reconcilingStatus === "reconciling";
@@ -3583,7 +3783,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                     }
                   )
                 ] }),
-                releaseConfig.existingReleaseId && sourceLanguage && showReconcileUI && /* @__PURE__ */ jsx(ReconcileReferencesButton, { sourceLanguage })
+                isSelected && sourceLanguage && showReconcileUI && /* @__PURE__ */ jsx(ReconcileReferencesButton, { sourceLanguage })
               ] })
             },
             release._id