@braze/sanity-plugin-ai-translation 0.2.6 → 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,269 +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;
-
 /**
  *
  * Configuration for the Sanity AI Translation plugin.
  * @public
  *
  */
-export declare interface PluginConfig {
+declare interface PluginConfig {
   supportedLanguages: Array<{
     id: string;
     title: string;
@@ -287,178 +30,12 @@ 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[];
-}
-
-/**
- * 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[];
-}
-
-/**
- * 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;
-  }>;
 }
 
 /**
@@ -474,78 +51,9 @@ export declare const translationHistorySchema: {
   WidenValidation &
   WidenInitialValue;
 
-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 {};