@braze/sanity-plugin-ai-translation 0.2.7 → 0.2.21

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { ArrayDefinition } from "sanity";
 import { FieldDefinitionBase } from "sanity";
 import { Plugin as Plugin_2 } from "sanity";
-import type { SanityDocument } from "sanity";
 import { WidenInitialValue } from "sanity";
 import { WidenValidation } from "sanity";
 
@@ -13,289 +12,13 @@ import { WidenValidation } from "sanity";
  */
 export declare const aiTranslationPlugin: Plugin_2<PluginConfig>;
 
-/**
- * Type-erased version of FieldTransform for use in collections.
- * Uses `any` to allow variance - this is necessary because function parameters
- * are contravariant, and using `unknown` would prevent assigning specific
- * transforms like `FieldTransform<VTTCaption[], TranslatableVTT>` to the array.
- *
- * This type is used internally by the plugin for storing transforms
- * in arrays and registries where the specific types aren't known.
- *
- * @public
- *
- * @example Usage in plugin config
- * ```typescript
- * const config: PluginConfig = {
- *   // ... other config
- *   fieldTransforms: [
- *     vttTransform,     // FieldTransform<VTTCaption[], TranslatableVTT>
- *     richTextTransform, // FieldTransform<PortableTextBlock[], TranslatableRichText>
- *     customTransform,   // FieldTransform<CustomType, TranslatableCustom>
- *   ] // All coerced to AnyFieldTransform[]
- * }
- * ```
- */
-export declare type AnyFieldTransform = FieldTransform<any, any>;
-
-/**
- * Common enum field names that are typically excluded from translation
- * @internal
- */
-export declare const COMMON_ENUM_FIELDS: readonly [
-  "status",
-  "state",
-  "type",
-  "category",
-  "priority",
-  "visibility",
-  "role",
-  "permission",
-  "level",
-  "mode",
-  "format",
-  "variant",
-  "size",
-  "theme",
-  "kind",
-  "phase",
-  "stage",
-];
-
-/**
- * Criteria for matching fields that should be transformed.
- * @public
- * @typeParam TOriginal - Type of the original field value
- */
-export declare interface FieldMatcher<TOriginal = unknown> {
-  /**
-   * Schema type name to match (e.g., 'video')
-   */
-  schemaType?: string;
-  /**
-   * Field name to match (e.g., 'captions')
-   */
-  fieldName?: string;
-  /**
-   * Full field path pattern to match (e.g., 'captions[].text' or RegExp)
-   */
-  fieldPath?: string | RegExp;
-  /**
-   * Optional function to match based on field value.
-   * This is called after other matcher criteria pass (or if no other criteria specified).
-   * Useful for detecting field types by examining their content (e.g., Portable Text detection).
-   * @param value - The field value to examine
-   * @param context - Transform context with field path, schema type, and document
-   * @returns true if this field should be transformed, false otherwise
-   */
-  valueMatcher?: (value: TOriginal, context: TransformContext) => boolean;
-}
-
-/**
- * Transform definition for custom field handling.
- *
- * Transforms allow you to convert complex field values to simpler formats
- * for translation, then restore the original structure after translation.
- *
- * @public
- * @typeParam TOriginal - Type of the original field value
- * @typeParam TTranslatable - Type of the translatable format (what gets sent to translation)
- *
- * @example Creating a type-safe transform for video captions
- * ```typescript
- * interface VTTCaption {
- *   startTime: number;
- *   endTime: number;
- *   text: string;
- * }
- *
- * interface TranslatableCaption {
- *   _type: 'translatable.vtt';
- *   vtt: string;
- * }
- *
- * const vttTransform: FieldTransform<VTTCaption[], TranslatableCaption> = {
- *   matcher: {
- *     schemaType: 'video',
- *     fieldName: 'captions',
- *   },
- *   toTranslatable: (captions) => ({
- *     _type: 'translatable.vtt',
- *     vtt: captions.map(c => `${c.startTime} --> ${c.endTime}\n${c.text}`).join('\n\n')
- *   }),
- *   fromTranslatable: (translated, original) => {
- *     // Parse VTT and restore original structure with translated text
- *     const lines = translated.vtt.split('\n\n');
- *     return original.map((caption, i) => ({
- *       ...caption,
- *       text: lines[i]?.split('\n')[1] || caption.text
- *     }));
- *   }
- * };
- * ```
- */
-export declare interface FieldTransform<
-  TOriginal = unknown,
-  TTranslatable = unknown,
-> {
-  /**
-   * Criteria for matching fields that should be transformed
-   */
-  matcher: FieldMatcher<TOriginal>;
-  /**
-   * Transform complex field value to translatable format.
-   * This method is called before translation to simplify the field structure.
-   *
-   * @param value - Original field value (typed as TOriginal)
-   * @param context - Transform context with field path, schema type, and document
-   * @returns Transformed value for translation (typed as TTranslatable)
-   *
-   * @example
-   * ```typescript
-   * toTranslatable: (value: CustomField[], context) => {
-   *   return {
-   *     _type: 'translatable.custom',
-   *     text: value.map(item => item.content).join('\n'),
-   *     _metadata: value.map(item => ({ id: item.id }))
-   *   };
-   * }
-   * ```
-   */
-  toTranslatable: (
-    value: TOriginal,
-    context: TransformContext,
-  ) => TTranslatable;
-  /**
-   * Transform translated value back to original format.
-   * This method is called after translation to restore the original structure
-   * while preserving the translated content.
-   *
-   * @param value - Translated value (typed as TTranslatable)
-   * @param originalValue - Original value before translation (typed as TOriginal)
-   * @param context - Transform context with field path, schema type, and document
-   * @returns Restored value with translated content (must match TOriginal type)
-   *
-   * @example
-   * ```typescript
-   * fromTranslatable: (translated: TranslatableCustom, original: CustomField[], context) => {
-   *   const translatedLines = translated.text.split('\n');
-   *   return original.map((item, index) => ({
-   *     ...item, // Preserve original structure and metadata
-   *     content: translatedLines[index] || item.content // Apply translated text
-   *   }));
-   * }
-   * ```
-   */
-  fromTranslatable: (
-    value: TTranslatable,
-    originalValue: TOriginal,
-    context: TransformContext,
-  ) => TOriginal;
-}
-
-/**
- * Result of filtering excluded fields from a document
- * @internal
- */
-export declare interface FilteredDocument<T = any> {
-  /** Document with excluded fields removed */
-  filteredDocument: T;
-  /** Excluded field values that were removed */
-  excludedValues: Record<string, any>;
-}
-
-/**
- * Recursively filters out excluded fields from a document
- * @param document - The document to filter
- * @param excludeFields - Array of field patterns to exclude. Supports:
- *   - Field names: 'status' (matches any field named 'status' anywhere)
- *   - Exact paths: 'meta.category' (matches only 'category' under 'meta')
- *   - Array paths: 'body[0].imageType' (matches 'imageType' in first array item)
- *   - Wildcard arrays: 'body[*].imageType' (matches 'imageType' in any array item)
- *   - Hierarchical: '**.status' (explicitly matches 'status' anywhere - same as just 'status')
- * @param currentPath - Current path in the document (used internally)
- * @returns Filtered document and excluded values
- * @internal
- */
-export declare function filterExcludedFields<T extends Record<string, any>>(
-  document: T,
-  excludeFields?: string[],
-  currentPath?: string,
-): FilteredDocument<T>;
-
-/**
- * Helper type to infer the original type from a FieldTransform.
- * Useful for type checking and creating wrapper functions.
- *
- * @public
- * @typeParam T - The FieldTransform type to extract from
- *
- * @example
- * ```typescript
- * const myTransform: FieldTransform<MyType, TranslatableType> = { ... };
- *
- * // Inferred type will be MyType
- * type OriginalType = InferOriginalType<typeof myTransform>;
- *
- * // Use in function signature
- * function processOriginal(value: InferOriginalType<typeof myTransform>) {
- *   // value is typed as MyType
- * }
- * ```
- */
-export declare type InferOriginalType<T> =
-  T extends FieldTransform<infer O, unknown> ? O : never;
-
-/**
- * Helper type to infer the translatable type from a FieldTransform.
- * Useful for type checking intermediate translation formats.
- *
- * @public
- * @typeParam T - The FieldTransform type to extract from
- *
- * @example
- * ```typescript
- * const myTransform: FieldTransform<MyType, TranslatableType> = { ... };
- *
- * // Inferred type will be TranslatableType
- * type TransType = InferTranslatableType<typeof myTransform>;
- *
- * // Use in function signature
- * function processTranslatable(value: InferTranslatableType<typeof myTransform>) {
- *   // value is typed as TranslatableType
- * }
- * ```
- */
-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.
  * @public
  *
  */
-export declare interface PluginConfig {
+declare interface PluginConfig {
   supportedLanguages: Array<{
     id: string;
     title: string;
@@ -307,346 +30,14 @@ export declare interface PluginConfig {
   maxReferenceDepth?: number;
   openai?: {
     apiKey: string;
-    model?:
-      | "gpt-5.1"
-      | "gpt-5"
-      | "gpt-5-mini"
-      | "gpt-5-nano"
-      | "gpt-5-pro"
-      | "gpt-4o"
-      | "gpt-4-turbo"
-      | "gpt-4";
-    reasoningEffort?: "low" | "medium" | "high";
+    model?: "gpt-5" | "gpt-4o" | "gpt-4-turbo" | "gpt-4";
+    reasoningEffort?: "minimal" | "low" | "medium" | "high";
+    verbosity?: "low" | "medium" | "high";
     enabled?: boolean;
     defaultMode?: TranslationMode;
   };
-  fieldTransforms?: AnyFieldTransform[];
-  /**
-   * Fields to exclude from translation. These fields will be preserved as-is in the translated document.
-   * Supports field names (e.g., 'status') and nested field paths (e.g., 'meta.category').
-   * Useful for enum fields, IDs, technical values, and other non-translatable content.
-   *
-   * @example
-   * ```typescript
-   * excludeFields: ['status', 'category', 'type', 'meta.priority', 'config.mode']
-   * ```
-   */
-  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;
 }
 
-/**
- * Predefined exclusion lists for common use cases
- * @internal
- */
-export declare const PREDEFINED_EXCLUSIONS: {
-  /** Common enum and status fields */
-  readonly enums: readonly [
-    "status",
-    "state",
-    "type",
-    "category",
-    "priority",
-    "visibility",
-    "role",
-    "permission",
-    "level",
-    "mode",
-    "format",
-    "variant",
-    "size",
-    "theme",
-    "kind",
-    "phase",
-    "stage",
-  ];
-  /** All metadata and system fields (starting with _) */
-  readonly metadata: readonly [
-    "_id",
-    "_type",
-    "_rev",
-    "_createdAt",
-    "_updatedAt",
-  ];
-  /** Common technical and configuration fields */
-  readonly technical: readonly [
-    "slug",
-    "handle",
-    "key",
-    "code",
-    "id",
-    "uuid",
-    "token",
-    "hash",
-    "checksum",
-    "version",
-    "config",
-    "settings",
-  ];
-  /** SEO and URL-related fields that often shouldn't be translated */
-  readonly seo: readonly [
-    "slug",
-    "handle",
-    "permalink",
-    "canonical",
-    "redirect",
-    "robots",
-    "sitemap",
-  ];
-};
-
-declare type ReleaseSelectionMode = "new" | "existing";
-
-/**
- * Restores previously excluded fields to a translated document
- * @param translatedDocument - The translated document
- * @param excludedValues - The excluded field values to restore
- * @returns Document with excluded fields restored
- * @internal
- */
-export declare function restoreExcludedFields<T extends Record<string, any>>(
-  translatedDocument: T,
-  excludedValues: Record<string, any>,
-): T;
-
-/**
- * Transform for handling Portable Text (rich text) content using XML-like serialization.
- * This leverages the existing serialization utilities to convert complex rich text
- * to a format that's easier for translation models to process.
- *
- * Uses value-based detection to identify Portable Text arrays (checking for _type === 'block').
- * The fieldPath pattern is used as a performance optimization to avoid checking every field,
- * but the valueMatcher is the definitive check.
- *
- * @public
- */
-export declare const richTextTransform: FieldTransform<
-  unknown[],
-  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
-  | OpenAIApiCallEvent;
-
-/**
- * Base interface for all telemetry events
- * @public
- */
-declare interface TelemetryEventBase {
-  name: string;
-  timestamp: string;
-}
-
-/**
- * Context passed to transform functions.
- * @public
- */
-export declare interface TransformContext {
-  /**
-   * Current field path
-   */
-  fieldPath: string;
-  /**
-   * Document schema type
-   */
-  schemaType: string;
-  /**
-   * Full document being processed
-   */
-  document: TranslatableDocument;
-}
-
-declare interface TranslatableDocument extends SanityDocument {
-  language: string;
-}
-
-/**
- * Special type to track transformed rich text content.
- * This separates the serialized XML content from regular strings
- * so the main serialization can handle it correctly.
- */
-declare interface TranslatableRichText {
-  _type: "translatable.richtext";
-  translationText: string;
-  _originalValue: unknown[];
-}
-
-/**
- * Special type to track transformed VTT captions.
- * This combines metadata separation for token efficiency with XML format for translation.
- */
-declare interface TranslatableVTTCaptions {
-  _type: "translatable.vtt.captions";
-  translationText: string;
-  _originalMetadata: VTTCaptionMetadata[];
-}
-
-/**
- * Special type to track transformed Wistia captions.
- * This combines metadata separation for token efficiency with compact text format for translation.
- */
-declare interface TranslatableWistiaCaptions {
-  _type: "translatable.wistia.captions";
-  translationText: string;
-  _originalMetadata: WistiaCaptionsMetadata;
-  _srtCues: Array<{
-    index: number;
-    startTime: string;
-    endTime: string;
-  }>;
-}
-
-/**
- * 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
  *
@@ -660,96 +51,9 @@ 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;
-  };
-}
-
-declare type TranslationMode = "sanity-only" | "openai-only";
-
-/**
- * Represents a VTT caption cue with timing and text content.
- */
-declare interface VTTCaption {
-  _key?: string;
-  _type?: string;
-  text?: string;
-  startTime?: number;
-  endTime?: number;
-  [key: string]: string | number | undefined;
-}
-
-/**
- * VTT caption metadata without text content, used for preservation during translation.
- */
-declare interface VTTCaptionMetadata {
-  _key?: string;
-  _type?: string;
-  startTime?: number;
-  endTime?: number;
-  _originalIndex: number;
-  [key: string]: string | number | undefined;
-}
-
-/**
- * Transform for handling VTT captions in video documents using a hybrid approach.
- * This stores metadata separately for token efficiency while formatting
- * text content as XML for better translation results.
- *
- * @public
- */
-export declare const vttCaptionTransform: FieldTransform<
-  VTTCaption[],
-  TranslatableVTTCaptions
->;
-
-/**
- * Represents a Wistia captions object with SRT content and metadata.
- */
-declare interface WistiaCaptions {
-  captionContent?: string;
-  captionFileName?: string;
-  isoLanguage?: string;
-  captionUploadStatus?: string;
-  captionUploadMessage?: string;
-  [key: string]: string | undefined;
-}
-
-/**
- * Wistia captions metadata without captionContent, used for preservation during translation.
- */
-declare interface WistiaCaptionsMetadata {
-  captionFileName?: string;
-  isoLanguage?: string;
-  captionUploadStatus?: string;
-  captionUploadMessage?: string;
-  _originalIndex: number;
-  [key: string]: string | number | undefined;
-}
-
-/**
- * Transform for handling Wistia captions in documents using SRT format.
- * This stores metadata separately for token efficiency while formatting
- * text content in a compact indexed format for better translation results.
- *
- * @public
- */
-export declare const wistiaCaptionTransform: FieldTransform<
-  WistiaCaptions,
-  TranslatableWistiaCaptions
->;
+declare type TranslationMode =
+  | "sanity-only"
+  | "openai-only"
+  | "sanity-with-review";
 
 export {};