@lokalise/ragnarok-api-contracts 4.0.0 → 4.0.2

package/dist/objects-v2.d.ts

@@ -0,0 +1,598 @@
+import { z } from 'zod';
+/**
+ * V2 evaluation result objects.
+ *
+ * Unlike V1 (`objects.ts`), every metric carries coverage and reliability metadata so consumers
+ * can distinguish a perfect score from one computed on a degraded segment set, and can tell an
+ * unsupported locale pair apart from an integration outage.
+ *
+ * V1 schemas remain the source of truth for `/v1/...`; these are additive and used only by `/v2/...`.
+ */
+/**
+ * Reliability classification of a single computed metric:
+ * - `perfect`  — computed over the full comparable segment set (`computedSegments === comparableSegments`).
+ * - `degraded` — some segments were excluded, but the surviving set still meets the reliability threshold.
+ * - `failed`   — too few comparable segments to be trustworthy (below the reliability threshold).
+ */
+export declare const METRIC_STATUS_SCHEMA: z.ZodEnum<{
+    failed: "failed";
+    perfect: "perfect";
+    degraded: "degraded";
+}>;
+export type MetricStatus = z.infer<typeof METRIC_STATUS_SCHEMA>;
+/**
+ * A single metric value paired with the coverage it was computed over and a reliability status.
+ */
+export declare const METRIC_RESULT_SCHEMA: z.ZodObject<{
+    value: z.ZodNumber;
+    computedSegments: z.ZodNumber;
+    comparableSegments: z.ZodNumber;
+    status: z.ZodEnum<{
+        failed: "failed";
+        perfect: "perfect";
+        degraded: "degraded";
+    }>;
+}, z.core.$strip>;
+export type MetricResult = z.infer<typeof METRIC_RESULT_SCHEMA>;
+/**
+ * V2 per-locale-pair metrics. Each metric is optional (a metric is omitted when it does not apply,
+ * e.g. BLEU for a pair with no corpus-level computation). The whole object is `null` on the
+ * locale-pair result when no metrics could be produced (see `LOCALE_PAIR_RESULT_V2_SCHEMA`).
+ */
+export declare const METRICS_V2_SCHEMA: z.ZodObject<{
+    exactMatch: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+    }, z.core.$strip>>;
+    ter: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+    }, z.core.$strip>>;
+    bleu: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+    }, z.core.$strip>>;
+    meteor: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+    }, z.core.$strip>>;
+    chrf: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MetricsV2 = z.infer<typeof METRICS_V2_SCHEMA>;
+/**
+ * Outcome of translating a locale pair within a run configuration:
+ * - `success`                 — all in-scope segments translated.
+ * - `partial_success`         — some segments translated, some failed (metrics computed on the survivors).
+ * - `unsupported_locale_pair` — the integration does not support this pair; metrics are `null`. Does
+ *                               NOT cause cross-configuration exclusion (other configs are unaffected).
+ * - `integration_failure`     — the integration failed to translate the pair (e.g. provider outage);
+ *                               metrics are `null` and the pair is excluded from all configs' comparable sets.
+ */
+export declare const TRANSLATION_STATUS_SCHEMA: z.ZodEnum<{
+    success: "success";
+    partial_success: "partial_success";
+    unsupported_locale_pair: "unsupported_locale_pair";
+    integration_failure: "integration_failure";
+}>;
+export type TranslationStatus = z.infer<typeof TRANSLATION_STATUS_SCHEMA>;
+export declare const LOCALE_PAIR_RESULT_V2_SCHEMA: z.ZodObject<{
+    sourceLocale: z.ZodString;
+    targetLocale: z.ZodString;
+    totalSegments: z.ZodNumber;
+    translatedSegments: z.ZodNumber;
+    translationStatus: z.ZodEnum<{
+        success: "success";
+        partial_success: "partial_success";
+        unsupported_locale_pair: "unsupported_locale_pair";
+        integration_failure: "integration_failure";
+    }>;
+    metrics: z.ZodNullable<z.ZodObject<{
+        exactMatch: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+        }, z.core.$strip>>;
+        ter: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+        }, z.core.$strip>>;
+        bleu: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+        }, z.core.$strip>>;
+        meteor: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+        }, z.core.$strip>>;
+        chrf: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalePairResultV2 = z.infer<typeof LOCALE_PAIR_RESULT_V2_SCHEMA>;
+/**
+ * A reference to a locale pair, used to list pairs excluded from a global metric aggregate.
+ * Intentionally flat (no `reason`): the per-pair `translationStatus` already carries the cause.
+ */
+export declare const LOCALE_PAIR_REF_SCHEMA: z.ZodObject<{
+    sourceLocale: z.ZodString;
+    targetLocale: z.ZodString;
+}, z.core.$strip>;
+export type LocalePairRef = z.infer<typeof LOCALE_PAIR_REF_SCHEMA>;
+/**
+ * A global (cross-locale-pair) aggregate for a single metric. Weighted by comparable segments and
+ * annotated with the locale pairs that were excluded from this metric's aggregation.
+ */
+export declare const GLOBAL_METRIC_RESULT_SCHEMA: z.ZodObject<{
+    value: z.ZodNumber;
+    computedSegments: z.ZodNumber;
+    comparableSegments: z.ZodNumber;
+    status: z.ZodEnum<{
+        failed: "failed";
+        perfect: "perfect";
+        degraded: "degraded";
+    }>;
+    excludedLocalePairs: z.ZodArray<z.ZodObject<{
+        sourceLocale: z.ZodString;
+        targetLocale: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GlobalMetricResult = z.infer<typeof GLOBAL_METRIC_RESULT_SCHEMA>;
+export declare const GLOBAL_METRICS_V2_SCHEMA: z.ZodObject<{
+    exactMatch: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+        excludedLocalePairs: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    ter: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+        excludedLocalePairs: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    bleu: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+        excludedLocalePairs: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    meteor: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+        excludedLocalePairs: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    chrf: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+        computedSegments: z.ZodNumber;
+        comparableSegments: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            perfect: "perfect";
+            degraded: "degraded";
+        }>;
+        excludedLocalePairs: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GlobalMetricsV2 = z.infer<typeof GLOBAL_METRICS_V2_SCHEMA>;
+export declare const CONFIGURATION_RESULT_V2_SCHEMA: z.ZodObject<{
+    configurationName: z.ZodString;
+    global: z.ZodObject<{
+        exactMatch: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+            excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                sourceLocale: z.ZodString;
+                targetLocale: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        ter: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+            excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                sourceLocale: z.ZodString;
+                targetLocale: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        bleu: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+            excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                sourceLocale: z.ZodString;
+                targetLocale: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        meteor: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+            excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                sourceLocale: z.ZodString;
+                targetLocale: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        chrf: z.ZodOptional<z.ZodObject<{
+            value: z.ZodNumber;
+            computedSegments: z.ZodNumber;
+            comparableSegments: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                perfect: "perfect";
+                degraded: "degraded";
+            }>;
+            excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                sourceLocale: z.ZodString;
+                targetLocale: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    resultsByLocalePair: z.ZodArray<z.ZodObject<{
+        sourceLocale: z.ZodString;
+        targetLocale: z.ZodString;
+        totalSegments: z.ZodNumber;
+        translatedSegments: z.ZodNumber;
+        translationStatus: z.ZodEnum<{
+            success: "success";
+            partial_success: "partial_success";
+            unsupported_locale_pair: "unsupported_locale_pair";
+            integration_failure: "integration_failure";
+        }>;
+        metrics: z.ZodNullable<z.ZodObject<{
+            exactMatch: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+            }, z.core.$strip>>;
+            ter: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+            }, z.core.$strip>>;
+            bleu: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+            }, z.core.$strip>>;
+            meteor: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+            }, z.core.$strip>>;
+            chrf: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConfigurationResultV2 = z.infer<typeof CONFIGURATION_RESULT_V2_SCHEMA>;
+export declare const EVALUATION_V2_SCHEMA: z.ZodObject<{
+    id: z.ZodUUID;
+    ownerId: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        pending: "pending";
+    }>;
+    metricsMetadata: z.ZodObject<{
+        exactMatch: z.ZodObject<{
+            betterWhen: z.ZodEnum<{
+                higher: "higher";
+                lower: "lower";
+            }>;
+        }, z.core.$strip>;
+        ter: z.ZodObject<{
+            betterWhen: z.ZodEnum<{
+                higher: "higher";
+                lower: "lower";
+            }>;
+        }, z.core.$strip>;
+        bleu: z.ZodObject<{
+            betterWhen: z.ZodEnum<{
+                higher: "higher";
+                lower: "lower";
+            }>;
+        }, z.core.$strip>;
+        meteor: z.ZodObject<{
+            betterWhen: z.ZodEnum<{
+                higher: "higher";
+                lower: "lower";
+            }>;
+        }, z.core.$strip>;
+        chrf: z.ZodObject<{
+            betterWhen: z.ZodEnum<{
+                higher: "higher";
+                lower: "lower";
+            }>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    results: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        configurationName: z.ZodString;
+        global: z.ZodObject<{
+            exactMatch: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+                excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                    sourceLocale: z.ZodString;
+                    targetLocale: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            ter: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+                excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                    sourceLocale: z.ZodString;
+                    targetLocale: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            bleu: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+                excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                    sourceLocale: z.ZodString;
+                    targetLocale: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            meteor: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+                excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                    sourceLocale: z.ZodString;
+                    targetLocale: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            chrf: z.ZodOptional<z.ZodObject<{
+                value: z.ZodNumber;
+                computedSegments: z.ZodNumber;
+                comparableSegments: z.ZodNumber;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    perfect: "perfect";
+                    degraded: "degraded";
+                }>;
+                excludedLocalePairs: z.ZodArray<z.ZodObject<{
+                    sourceLocale: z.ZodString;
+                    targetLocale: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        resultsByLocalePair: z.ZodArray<z.ZodObject<{
+            sourceLocale: z.ZodString;
+            targetLocale: z.ZodString;
+            totalSegments: z.ZodNumber;
+            translatedSegments: z.ZodNumber;
+            translationStatus: z.ZodEnum<{
+                success: "success";
+                partial_success: "partial_success";
+                unsupported_locale_pair: "unsupported_locale_pair";
+                integration_failure: "integration_failure";
+            }>;
+            metrics: z.ZodNullable<z.ZodObject<{
+                exactMatch: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodNumber;
+                    computedSegments: z.ZodNumber;
+                    comparableSegments: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        failed: "failed";
+                        perfect: "perfect";
+                        degraded: "degraded";
+                    }>;
+                }, z.core.$strip>>;
+                ter: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodNumber;
+                    computedSegments: z.ZodNumber;
+                    comparableSegments: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        failed: "failed";
+                        perfect: "perfect";
+                        degraded: "degraded";
+                    }>;
+                }, z.core.$strip>>;
+                bleu: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodNumber;
+                    computedSegments: z.ZodNumber;
+                    comparableSegments: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        failed: "failed";
+                        perfect: "perfect";
+                        degraded: "degraded";
+                    }>;
+                }, z.core.$strip>>;
+                meteor: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodNumber;
+                    computedSegments: z.ZodNumber;
+                    comparableSegments: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        failed: "failed";
+                        perfect: "perfect";
+                        degraded: "degraded";
+                    }>;
+                }, z.core.$strip>>;
+                chrf: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodNumber;
+                    computedSegments: z.ZodNumber;
+                    comparableSegments: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        failed: "failed";
+                        perfect: "perfect";
+                        degraded: "degraded";
+                    }>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type EvaluationV2 = z.infer<typeof EVALUATION_V2_SCHEMA>;