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

package/dist/index.d.ts

@@ -269,6 +269,26 @@ export declare type InferOriginalType<T> =
 export declare type InferTranslatableType<T> =
   T extends FieldTransform<unknown, infer R> ? R : never;
 
+/**
+ * Event emitted when an OpenAI API call is made
+ * @public
+ */
+declare interface OpenAIApiCallEvent extends TelemetryEventBase {
+  name: "openai.api_call";
+  data: {
+    model: string;
+    tokensUsed: {
+      prompt: number;
+      completion: number;
+      reasoning: number;
+      total: number;
+      cached: number;
+    };
+    cost: number;
+    durationMs: number;
+  };
+}
+
 /**
  *
  * Configuration for the Sanity AI Translation plugin.
@@ -312,6 +332,19 @@ export declare interface PluginConfig {
    * ```
    */
   excludeFields?: string[];
+  /**
+   * Optional telemetry configuration for monitoring translation operations.
+   * Provides callbacks for lightweight events and detailed error bundles.
+   *
+   * @example
+   * ```typescript
+   * telemetry: {
+   *   onEvent: (event) => datadogRum.addAction(event.name, event.data),
+   *   onError: (bundle) => datadogLogs.logger.error('Translation failed', bundle)
+   * }
+   * ```
+   */
+  telemetry?: TelemetryConfig;
 }
 
 /**
@@ -374,6 +407,8 @@ export declare const PREDEFINED_EXCLUSIONS: {
   ];
 };
 
+declare type ReleaseSelectionMode = "new" | "existing";
+
 /**
  * Restores previously excluded fields to a translated document
  * @param translatedDocument - The translated document
@@ -402,6 +437,57 @@ export declare const richTextTransform: FieldTransform<
   TranslatableRichText
 >;
 
+/**
+ * Configuration for telemetry/monitoring integration.
+ * Both callbacks are optional - configure based on your monitoring needs.
+ * @public
+ *
+ * @example Basic Datadog RUM integration
+ * ```typescript
+ * telemetry: {
+ *   onEvent: (event) => datadogRum.addAction(event.name, event.data),
+ *   onError: (bundle) => datadogRum.addError(new Error(bundle.error.message), {
+ *     documentId: bundle.documentId,
+ *     errorType: bundle.error.type,
+ *   })
+ * }
+ * ```
+ */
+declare interface TelemetryConfig {
+  /**
+   * Lightweight event callback - called for all translation events.
+   * Keep payloads small (IDs, counts, durations, costs).
+   * @param event - The telemetry event with name and data
+   */
+  onEvent?: (event: TelemetryEvent) => void;
+  /**
+   * Error callback with full debug bundle - only called on failures.
+   * Consumer decides how to handle (send to Datadog, store locally, truncate, etc.)
+   * @param bundle - Full debug context for troubleshooting
+   */
+  onError?: (bundle: TranslationErrorBundle) => void;
+}
+
+/**
+ * Union of all telemetry event types
+ * @public
+ */
+declare type TelemetryEvent =
+  | TranslationBatchStartedEvent
+  | TranslationBatchCompletedEvent
+  | TranslationJobCompletedEvent
+  | TranslationJobFailedEvent
+  | OpenAIApiCallEvent;
+
+/**
+ * Base interface for all telemetry events
+ * @public
+ */
+declare interface TelemetryEventBase {
+  name: string;
+  timestamp: string;
+}
+
 /**
  * Context passed to transform functions.
  * @public
@@ -461,6 +547,107 @@ declare interface TranslatableWistiaCaptions {
   }>;
 }
 
+/**
+ * Event emitted when a translation batch completes
+ * @public
+ */
+declare interface TranslationBatchCompletedEvent extends TelemetryEventBase {
+  name: "translation.batch_completed";
+  data: {
+    documentId: string;
+    documentType: string;
+    sourceLanguage: string;
+    targetLanguages: string[];
+    translationMode: TranslationMode;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+  };
+}
+
+/**
+ * Event emitted when a translation batch starts
+ * @public
+ */
+declare interface TranslationBatchStartedEvent extends TelemetryEventBase {
+  name: "translation.batch_started";
+  data: {
+    documentId: string;
+    documentType: string;
+    sourceLanguage: string;
+    targetLanguages: string[];
+    translationMode: TranslationMode;
+    referenceCount: number;
+    releaseMode: ReleaseSelectionMode;
+  };
+}
+
+/**
+ * Debug bundle containing full context for troubleshooting translation failures.
+ * This is only emitted when a translation fails.
+ * @public
+ */
+declare interface TranslationErrorBundle {
+  /** Document ID being translated */
+  documentId: string;
+  /** Document schema type */
+  documentType: string;
+  /** Target language for translation */
+  targetLanguage: string;
+  /** Source language of the document */
+  sourceLanguage: string;
+  /** Translation mode used */
+  translationMode: TranslationMode;
+  /** Error details */
+  error: {
+    /** Error message */
+    message: string;
+    /** Error stack trace if available */
+    stack?: string;
+    /** Categorized error type for filtering/alerting */
+    type: TranslationErrorType;
+  };
+  /**
+   * Debug data for troubleshooting.
+   * Can be large - consumer decides how to handle (truncate, store locally, etc.)
+   */
+  debug: {
+    /** Full source document */
+    originalDocument: SanityDocument;
+    /** XML-serialized document sent to OpenAI (if OpenAI mode) */
+    serializedDocument?: string;
+    /** Raw API response from OpenAI (if OpenAI mode) */
+    openaiResponse?: string;
+    /** Translation prompts used */
+    translationPrompts?: {
+      globalPrompt?: string;
+      localePrompt?: string;
+      protectedPhrases?: string[];
+      glossaryTerms?: any[];
+    };
+    /** Validation errors if structure validation failed */
+    validationErrors?: any[];
+  };
+  /** ISO timestamp when error occurred */
+  timestamp: string;
+  /** Duration of the translation attempt in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Error types for categorizing translation failures
+ * @public
+ */
+declare type TranslationErrorType =
+  | "serialization"
+  | "deserialization"
+  | "openai_api"
+  | "validation"
+  | "sanity_agent"
+  | "network"
+  | "unknown";
+
 /**
  * Schema for translation history
  *
@@ -474,6 +661,46 @@ export declare const translationHistorySchema: {
   WidenValidation &
   WidenInitialValue;
 
+/**
+ * Event emitted when an individual translation job completes successfully
+ * @public
+ */
+declare interface TranslationJobCompletedEvent extends TelemetryEventBase {
+  name: "translation.job_completed";
+  data: {
+    documentId: string;
+    documentType: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+    translationMode: TranslationMode;
+    durationMs: number;
+    tokensUsed?: number;
+    estimatedCost?: number;
+  };
+}
+
+/**
+ * Event emitted when an individual translation job fails.
+ * This is emitted alongside the detailed error bundle (via onError) to enable
+ * easy error rate calculations by comparing job_completed vs job_failed counts.
+ * @public
+ */
+declare interface TranslationJobFailedEvent extends TelemetryEventBase {
+  name: "translation.job_failed";
+  data: {
+    documentId: string;
+    documentType: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+    translationMode: TranslationMode;
+    durationMs: number;
+    /** Categorized error type for filtering/grouping */
+    errorType: TranslationErrorType;
+    /** Error message (kept short for metrics; full details in error bundle) */
+    errorMessage: string;
+  };
+}
+
 declare type TranslationMode = "sanity-only" | "openai-only";
 
 /**