@braze/sanity-plugin-ai-translation 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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";
 
@@ -12,13 +13,215 @@ 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>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
 /**
  *
  * Configuration for the Sanity AI Translation plugin.
  * @public
  *
  */
-declare interface PluginConfig {
+export declare interface PluginConfig {
   supportedLanguages: Array<{
     id: string;
     title: string;
@@ -30,12 +233,72 @@ declare interface PluginConfig {
   maxReferenceDepth?: number;
   openai?: {
     apiKey: string;
-    model?: "gpt-5" | "gpt-4o" | "gpt-4-turbo" | "gpt-4";
-    reasoningEffort?: "minimal" | "low" | "medium" | "high";
-    verbosity?: "low" | "medium" | "high";
+    model?: "gpt-5.1" | "gpt-5" | "gpt-4o" | "gpt-4-turbo" | "gpt-4";
+    reasoningEffort?: "low" | "medium" | "high";
     enabled?: boolean;
     defaultMode?: TranslationMode;
   };
+  fieldTransforms?: AnyFieldTransform[];
+}
+
+/**
+ * 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
+>;
+
+/**
+ * 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[];
 }
 
 /**
@@ -56,4 +319,40 @@ declare type TranslationMode =
   | "openai-only"
   | "sanity-with-review";
 
+/**
+ * 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
+>;
+
 export {};