altalandi 0.6.1 → 0.6.3

package/client.d.ts

@@ -1,122 +1,200 @@
-export type SourceLang = "auto" | "en" | "is";
-export type Domain = "general" | "marketing" | "data-analysis" | "childrens-fiction";
-export type Register = "formal" | "neutral" | "warm";
-export type WriterTier = "standard" | "max";
-export type ScoringTier = "none" | "fast" | "rigorous";
-
-export interface GlossaryTerm {
-  en: string;
-  is: string;
-  note?: string;
-}
-
-export interface FetchResponseLike {
-  ok: boolean;
-  status: number;
-  statusText?: string;
-  /** Read for Retry-After on a 429. */
-  headers?: { get(name: string): string | null };
-  text(): Promise<string>;
-}
-
-export type FetchLike = (
-  url: string,
-  init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-    signal: any;
-  },
-) => Promise<FetchResponseLike>;
-
-export interface RefineOptions {
-  sourceLang?: SourceLang;
-  domain?: Domain;
-  register?: Register;
-  preserveMeaning?: boolean;
-  scoreNativeness?: boolean;
-  /** IS-refine: keep the original unless improvement is verified. */
-  onlyImprove?: boolean;
-  /** Optional EN→IS monolingual polish pass; false by default. */
-  polishPass?: boolean;
-  writer?: WriterTier;
-  scoring?: ScoringTier;
-  glossary?: GlossaryTerm[];
-  returnDiffs?: boolean;
-  /** Let Altalandi keep this text and its output to improve the service. Only with the person's consent; default false. */
-  contribute?: boolean;
-  /** Defaults to ALTALANDI_API_KEY. Never put a key in source control. */
-  apiKey?: string;
-  /** Defaults to https://altalandi.is/api. */
-  baseUrl?: string;
-  /** Per-request timeout in milliseconds; defaults to 300000. */
-  timeoutMs?: number;
-  /** Optional fetch-compatible implementation, useful for controlled runtimes and tests. */
-  fetch?: FetchLike;
-}
-
-export interface RefineDiff {
-  before: string;
-  after: string;
-  layer: "L1" | "L2" | "L3";
-  reason: string;
-}
-
-export interface RefineQuality {
-  nativenessScore: number | null;
-  translationeseTells: string[];
-  iceBertScore: number | null;
-  morphologyOk: boolean | null;
-  calqueFlags: string[];
-  englishRemnants: string[];
-  encodingArtifacts: string[];
-}
-
-export interface RefineResult {
-  id: string;
-  output: string;
-  sourceLang: "en" | "is";
-  diffs: RefineDiff[];
-  quality: RefineQuality;
-  /** Only strict true is a completed verification; null means skipped/unavailable. */
-  meaningPreserved: boolean | null;
-  meaningNotes: string;
-  modelUsed: string;
-  tier?: { writer: WriterTier; scoring: ScoringTier };
-  billedTier?: { writer: WriterTier; scoring: ScoringTier };
-  warnings: string[];
-  /** true when a test key made the call: no model ran, nothing was charged, output = input. */
-  test?: boolean | null;
-}
-
-export type VerifiedRefineResult = RefineResult & { meaningPreserved: true };
-
-export interface AltalandiErrorOptions {
-  code?: string;
-  status?: number;
-  retryAfterMs?: number;
-}
-
-export class AltalandiError extends Error {
-  readonly code: string;
-  readonly status?: number;
-  /** From the Retry-After header of an error response (429), when present. */
-  readonly retryAfterMs?: number;
-  constructor(message: string, options?: AltalandiErrorOptions);
-}
-
-export class MeaningVerificationError extends AltalandiError {
-  readonly verdict: false | null;
-  constructor(verdict: boolean | null | undefined);
-}
-
-/** Refine text and return the full hosted API response. */
-export function refine(text: string, options?: RefineOptions): Promise<RefineResult>;
-
-/** Refine text and throw unless meaningPreserved is strict true. */
-export function refineVerified(text: string, options?: RefineOptions): Promise<VerifiedRefineResult>;
-
-/** Narrow an existing result to one with a verified meaning verdict. */
-export function assertMeaningVerified(
-  result: RefineResult,
-): asserts result is VerifiedRefineResult;
+export type SourceLang = "auto" | "en" | "is";
+export type Domain = "general" | "marketing" | "data-analysis" | "childrens-fiction";
+export type Register = "formal" | "neutral" | "warm";
+export type WriterTier = "standard" | "max";
+export type ScoringTier = "none" | "fast" | "rigorous";
+
+export interface GlossaryTerm {
+  en: string;
+  is: string;
+  note?: string;
+}
+
+/** Groups calls into one job ("verk") on the account: a document sent in
+ *  parts, a folder or a site. The first call that names an id creates the job. */
+export interface JobRef {
+  /** `j_` and 8–64 of [A-Za-z0-9_-], chosen by the client. */
+  id: string;
+  /** The job's name (at most 120 characters); the first one sent is kept. */
+  title?: string;
+  /** This call's piece: a file path, a page URL, "Hluti 2 af 5" (at most 300 characters). */
+  part?: string;
+}
+
+export interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  statusText?: string;
+  /** Read for Retry-After on a 429. */
+  headers?: { get(name: string): string | null };
+  text(): Promise<string>;
+}
+
+export type FetchLike = (
+  url: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: any;
+  },
+) => Promise<FetchResponseLike>;
+
+export interface RefineOptions {
+  sourceLang?: SourceLang;
+  domain?: Domain;
+  register?: Register;
+  preserveMeaning?: boolean;
+  scoreNativeness?: boolean;
+  /** IS-refine: keep the original unless improvement is verified. */
+  onlyImprove?: boolean;
+  /** Optional EN→IS monolingual polish pass; false by default. */
+  polishPass?: boolean;
+  writer?: WriterTier;
+  scoring?: ScoringTier;
+  glossary?: GlossaryTerm[];
+  returnDiffs?: boolean;
+  /** Let Altalandi keep this text and its output to improve the service. Only with the person's consent; default false. */
+  contribute?: boolean;
+  /** Make this call a part of a job. Ignored for anonymous calls. */
+  job?: JobRef;
+  /** Defaults to ALTALANDI_API_KEY. Never put a key in source control. */
+  apiKey?: string;
+  /** Defaults to https://altalandi.is/api. */
+  baseUrl?: string;
+  /** Per-request timeout in milliseconds; defaults to 300000. */
+  timeoutMs?: number;
+  /** Optional fetch-compatible implementation, useful for controlled runtimes and tests. */
+  fetch?: FetchLike;
+}
+
+export interface RefineDiff {
+  before: string;
+  after: string;
+  layer: "L1" | "L2" | "L3";
+  reason: string;
+}
+
+export interface RefineQuality {
+  nativenessScore: number | null;
+  translationeseTells: string[];
+  iceBertScore: number | null;
+  morphologyOk: boolean | null;
+  calqueFlags: string[];
+  englishRemnants: string[];
+  encodingArtifacts: string[];
+}
+
+export interface RefineResult {
+  id: string;
+  output: string;
+  sourceLang: "en" | "is";
+  diffs: RefineDiff[];
+  quality: RefineQuality;
+  /** Only strict true is a completed verification; null means skipped/unavailable. */
+  meaningPreserved: boolean | null;
+  meaningNotes: string;
+  modelUsed: string;
+  tier?: { writer: WriterTier; scoring: ScoringTier };
+  billedTier?: { writer: WriterTier; scoring: ScoringTier };
+  warnings: string[];
+  /** true when a test key made the call: no model ran, nothing was charged, output = input. */
+  test?: boolean | null;
+  /** Characters billed (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** /v1 only: what the call cost and what is left (characters, chargedIsk, balanceIsk, freeCharsLeftToday, …). */
+  billing?: Record<string, unknown> | null;
+  /** This call's own page. */
+  runUrl?: string | null;
+  /** When `job` was sent (and the engine knows jobs): the job's id and page. */
+  jobId?: string;
+  jobUrl?: string;
+}
+
+export type VerifiedRefineResult = RefineResult & { meaningPreserved: true };
+
+export interface AltalandiErrorOptions {
+  code?: string;
+  status?: number;
+  retryAfterMs?: number;
+}
+
+export class AltalandiError extends Error {
+  readonly code: string;
+  readonly status?: number;
+  /** From the Retry-After header of an error response (429), when present. */
+  readonly retryAfterMs?: number;
+  constructor(message: string, options?: AltalandiErrorOptions);
+}
+
+export class MeaningVerificationError extends AltalandiError {
+  readonly verdict: false | null;
+  constructor(verdict: boolean | null | undefined);
+}
+
+/** Refine text and return the full hosted API response. */
+export function refine(text: string, options?: RefineOptions): Promise<RefineResult>;
+
+export interface BatchItem {
+  /** Your key for the string; defaults to its index, as a string. */
+  id?: string;
+  /** At most 2,000 characters. */
+  text: string;
+}
+
+export interface BatchOptions {
+  sourceLang?: SourceLang;
+  domain?: Domain;
+  register?: Register;
+  preserveMeaning?: boolean;
+  scoreNativeness?: boolean;
+  onlyImprove?: boolean;
+  glossary?: GlossaryTerm[];
+  autoTerminology?: boolean;
+  contribute?: boolean;
+  job?: JobRef;
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+}
+
+export interface BatchItemResult {
+  id: string;
+  output: string;
+  sourceLang: "en" | "is";
+  diffs: RefineDiff[];
+  meaningCheck: "passed" | "changed" | "reverted" | "skipped" | "unavailable";
+  meaningPreserved: boolean | null;
+  warnings: string[];
+  /** true: refined in one model call with other strings, then checked on its own. */
+  packed: boolean;
+  /** Set when this string could not be refined: it came back unchanged and was not billed. */
+  error?: string | null;
+}
+
+export interface BatchResult {
+  id: string;
+  runUrl: string | null;
+  items: BatchItemResult[];
+  /** Characters billed for the whole batch (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** @deprecated The word equivalent of `characters` (= billing.units). */
+  units: number;
+  billing: Record<string, unknown> | null;
+  quality: RefineQuality;
+  warnings: string[];
+  jobId?: string;
+  jobUrl?: string;
+}
+
+/** Refine many short strings in one call (POST /v1/refine/batch). */
+export function refineBatch(items: BatchItem[], options?: BatchOptions): Promise<BatchResult>;
+
+/** Refine text and throw unless meaningPreserved is strict true. */
+export function refineVerified(text: string, options?: RefineOptions): Promise<VerifiedRefineResult>;
+
+/** Narrow an existing result to one with a verified meaning verdict. */
+export function assertMeaningVerified(
+  result: RefineResult,
+): asserts result is VerifiedRefineResult;