@braze/sanity-plugin-ai-translation 0.2.2 → 0.2.4

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,269 @@ 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;
+
 /**
  *
  * Configuration for the Sanity AI Translation plugin.
  * @public
  *
  */
-declare interface PluginConfig {
+export declare interface PluginConfig {
   supportedLanguages: Array<{
     id: string;
     title: string;
@@ -30,12 +287,163 @@ 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-5-mini"
+      | "gpt-5-nano"
+      | "gpt-5-pro"
+      | "gpt-4o"
+      | "gpt-4-turbo"
+      | "gpt-4";
+    reasoningEffort?: "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[];
+}
+
+/**
+ * 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",
+  ];
+};
+
+/**
+ * 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
+>;
+
+/**
+ * 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 +464,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 {};