@verbatra/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -226,6 +226,15 @@ type BoundedFileRead = {
 } | {
     readonly kind: "too-large";
 };
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
 /**
  * The minimal file-system surface the SDK needs for the lock-file and for existence
  * checks. Injectable so tests stay deterministic; the format adapters do their own
@@ -241,8 +250,17 @@ interface SdkFs {
      * unreadable path is "missing" (first-run); a file over the cap is "too-large".
      */
     readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /**
+     * Read a file as raw bytes through a single handle, bounded to maxBytes, with the SAME
+     * TOCTOU-safe discipline as {@link readFileBounded}: the handle is fstat'd and the read never
+     * advances past the sized length. Used for the untrusted workbook on import; a file over the
+     * cap is "too-large", a missing path is "missing".
+     */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
     /** Write atomically: a temp file in the same directory, then rename over the target. */
     writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
 }
 
 /** Builds the provider from its config. Injectable so tests stay offline. */
@@ -314,6 +332,89 @@ interface TranslateDeps {
  */
 declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
 
+/** Default workbook output path, relative to the resolved working directory. */
+declare const DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
+/** Input for {@link exportWorkbook}: the validated config and where/how to run the export. */
+interface ExportWorkbookInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern, lock-file, and output path resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Output path for the workbook; defaults to {@link DEFAULT_WORKBOOK_PATH} under cwd. */
+    readonly out?: string;
+    /** Subset of target locales to export; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+    /** Include unchanged keys (off by default; export is missing-and-changed only). */
+    readonly includeUnchanged?: boolean;
+}
+/** Composition seam for {@link exportWorkbook}: inject a registry and a file system for tests. */
+interface ExportWorkbookDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/** The outcome of an export: where it was written and how many rows per locale. */
+interface ExportWorkbookResult {
+    /** The absolute path the workbook was written to. */
+    readonly path: string;
+    /** Per-locale row counts, in config order; the same set the workbook carries. */
+    readonly locales: readonly {
+        readonly locale: string;
+        readonly rows: number;
+    }[];
+}
+/**
+ * Export the strings needing human translation into a styled `.xlsx` workbook. Reuses the same
+ * source read, adapter selection, and lock baseline the translate flow uses, runs `diffResources`
+ * per target locale to pick the rows (missing and changed by default; add unchanged with
+ * `includeUnchanged`), hands the neutral row model to `@verbatra/exchange`'s `buildWorkbook`, and
+ * writes the bytes through the {@link SdkFs} seam. No provider is called and no lock-file is written.
+ *
+ * @param input - The validated config and export options.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns Where the workbook was written and the per-locale row counts.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
+
+/** Input for {@link importWorkbook}: the validated config, the workbook path, and run options. */
+interface ImportWorkbookInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Path to the filled workbook to import. */
+    readonly workbook: string;
+    /** Directory the file pattern, lock-file, and workbook path resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** When true, validate and report only: write no locale file and update no lock-file. */
+    readonly dryRun?: boolean;
+}
+/** Composition seam for {@link importWorkbook}: inject a registry and a file system for tests. */
+interface ImportWorkbookDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Import a filled workbook back into the locale files. Reads the untrusted workbook through the
+ * SDK's bounded read, parses it with `@verbatra/exchange`'s `readWorkbook` (which bounds and
+ * sanitizes it), then for each target-locale data sheet runs the EXISTING core checks (source-drift
+ * via `contentHash`, placeholder integrity via `checkPlaceholders`, ICU via the adapter's
+ * `validateMessage`), writes the accepted values through the format adapter, and updates the lock
+ * through the existing lock logic. Returns a {@link RunSummary} structurally identical to
+ * `translate`'s, so the CLI formatter and exit-code rule are shared with no special case.
+ *
+ * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
+ * structured {@link SdkError}. A per-sheet failure (a locale not in config, a broken-round-trip key,
+ * a write failure) is isolated as that locale's `status: "failed"`, not a throw; per-row rejections
+ * are withheld and reported on the locale, exactly as the provider path treats integrity mismatches.
+ * `--dry-run` validates and reports without writing any locale or lock file.
+ *
+ * @param input - The validated config, the workbook path, and run options.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns A {@link RunSummary} with one locale per data sheet, in workbook order.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`.
+ */
+declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
+
 /** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
 interface Watcher {
     /** Register a listener invoked once per coalesced source-change event. */
@@ -411,4 +512,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CreateProvider, type CreateWatcher, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, loadConfig, translate, verbatraConfigSchema, watch };
+export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };

package/dist/index.d.ts

@@ -226,6 +226,15 @@ type BoundedFileRead = {
 } | {
     readonly kind: "too-large";
 };
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
 /**
  * The minimal file-system surface the SDK needs for the lock-file and for existence
  * checks. Injectable so tests stay deterministic; the format adapters do their own
@@ -241,8 +250,17 @@ interface SdkFs {
      * unreadable path is "missing" (first-run); a file over the cap is "too-large".
      */
     readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /**
+     * Read a file as raw bytes through a single handle, bounded to maxBytes, with the SAME
+     * TOCTOU-safe discipline as {@link readFileBounded}: the handle is fstat'd and the read never
+     * advances past the sized length. Used for the untrusted workbook on import; a file over the
+     * cap is "too-large", a missing path is "missing".
+     */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
     /** Write atomically: a temp file in the same directory, then rename over the target. */
     writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
 }
 
 /** Builds the provider from its config. Injectable so tests stay offline. */
@@ -314,6 +332,89 @@ interface TranslateDeps {
  */
 declare function translate(input: TranslateInput, deps?: TranslateDeps): Promise<RunSummary>;
 
+/** Default workbook output path, relative to the resolved working directory. */
+declare const DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
+/** Input for {@link exportWorkbook}: the validated config and where/how to run the export. */
+interface ExportWorkbookInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern, lock-file, and output path resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Output path for the workbook; defaults to {@link DEFAULT_WORKBOOK_PATH} under cwd. */
+    readonly out?: string;
+    /** Subset of target locales to export; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+    /** Include unchanged keys (off by default; export is missing-and-changed only). */
+    readonly includeUnchanged?: boolean;
+}
+/** Composition seam for {@link exportWorkbook}: inject a registry and a file system for tests. */
+interface ExportWorkbookDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/** The outcome of an export: where it was written and how many rows per locale. */
+interface ExportWorkbookResult {
+    /** The absolute path the workbook was written to. */
+    readonly path: string;
+    /** Per-locale row counts, in config order; the same set the workbook carries. */
+    readonly locales: readonly {
+        readonly locale: string;
+        readonly rows: number;
+    }[];
+}
+/**
+ * Export the strings needing human translation into a styled `.xlsx` workbook. Reuses the same
+ * source read, adapter selection, and lock baseline the translate flow uses, runs `diffResources`
+ * per target locale to pick the rows (missing and changed by default; add unchanged with
+ * `includeUnchanged`), hands the neutral row model to `@verbatra/exchange`'s `buildWorkbook`, and
+ * writes the bytes through the {@link SdkFs} seam. No provider is called and no lock-file is written.
+ *
+ * @param input - The validated config and export options.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns Where the workbook was written and the per-locale row counts.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
+ *   with the same meanings as in `translate`.
+ */
+declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
+
+/** Input for {@link importWorkbook}: the validated config, the workbook path, and run options. */
+interface ImportWorkbookInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Path to the filled workbook to import. */
+    readonly workbook: string;
+    /** Directory the file pattern, lock-file, and workbook path resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** When true, validate and report only: write no locale file and update no lock-file. */
+    readonly dryRun?: boolean;
+}
+/** Composition seam for {@link importWorkbook}: inject a registry and a file system for tests. */
+interface ImportWorkbookDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Import a filled workbook back into the locale files. Reads the untrusted workbook through the
+ * SDK's bounded read, parses it with `@verbatra/exchange`'s `readWorkbook` (which bounds and
+ * sanitizes it), then for each target-locale data sheet runs the EXISTING core checks (source-drift
+ * via `contentHash`, placeholder integrity via `checkPlaceholders`, ICU via the adapter's
+ * `validateMessage`), writes the accepted values through the format adapter, and updates the lock
+ * through the existing lock logic. Returns a {@link RunSummary} structurally identical to
+ * `translate`'s, so the CLI formatter and exit-code rule are shared with no special case.
+ *
+ * Whole-run failures (unknown format, unreadable/invalid/oversized workbook, corrupt lock) throw a
+ * structured {@link SdkError}. A per-sheet failure (a locale not in config, a broken-round-trip key,
+ * a write failure) is isolated as that locale's `status: "failed"`, not a throw; per-row rejections
+ * are withheld and reported on the locale, exactly as the provider path treats integrity mismatches.
+ * `--dry-run` validates and reports without writing any locale or lock file.
+ *
+ * @param input - The validated config, the workbook path, and run options.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns A {@link RunSummary} with one locale per data sheet, in workbook order.
+ * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`.
+ */
+declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
+
 /** A minimal source-change event source. Production wraps chokidar; tests inject a stub. */
 interface Watcher {
     /** Register a listener invoked once per coalesced source-change event. */
@@ -411,4 +512,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CreateProvider, type CreateWatcher, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, loadConfig, translate, verbatraConfigSchema, watch };
+export { type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate, verbatraConfigSchema, watch };