@verbatra/sdk 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -1,7 +1,43 @@
+import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { AdapterRegistry } from '@verbatra/format-adapters';
 
+/**
+ * The provider section of the config: a discriminated union over the provider id,
+ * reusing each provider's own exported config schema. There is no key field anywhere
+ * in this union. The provider reads its API key from the environment at construction.
+ *
+ * This union and the factory table below are co-located on purpose: adding a provider
+ * is a single edit here (one union variant plus one table entry), and the mapped-type
+ * table makes the two sets provably identical at compile time.
+ */
+declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodLiteral<"anthropic">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"gemini">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"deepl">;
+    options: z.ZodObject<{
+        glossaryId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strip>], "id">;
+type ProviderConfig = z.infer<typeof providerConfigSchema>;
+type ProviderId = ProviderConfig["id"];
+
 /**
  * The verbatra project configuration. Non-secret only: it carries no API key (the
  * provider reads its key from the environment), and unknown top-level keys are rejected
@@ -53,12 +89,56 @@ declare const verbatraConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
 
+/**
+ * An open union over a provider's known model IDs: the suggested IDs plus any other
+ * non-empty string. The `string & {}` arm keeps the union from collapsing to plain
+ * `string` (so editors still surface the literals as completions) while accepting a
+ * brand-new model ID the tool has never heard of. This is a static authoring hint
+ * only; the runtime schema stays `z.string().min(1)` and validates nothing against
+ * these literals.
+ */
+type OpenModel<M extends string> = M | (string & {});
+/**
+ * The authoring view of one provider variant: its runtime config with `options.model`
+ * narrowed to that provider's open model union. LLM providers (anthropic, openai,
+ * gemini) get suggestions; DeepL has no model field and is carried through unchanged.
+ */
+type AuthoringProviderConfig = AuthoringVariant<"anthropic", AnthropicModel> | AuthoringVariant<"openai", OpenAiModel> | AuthoringVariant<"gemini", GeminiModel> | Extract<ProviderConfig, {
+    id: "deepl";
+}>;
+type AuthoringVariant<Id extends ProviderConfig["id"], M extends string> = Extract<ProviderConfig, {
+    id: Id;
+}> extends infer Variant ? Variant extends {
+    options: {
+        model: string;
+    };
+} ? Omit<Variant, "options"> & {
+    options: Omit<Variant["options"], "model"> & {
+        model: OpenModel<M>;
+    };
+} : never : never;
+/**
+ * The authoring view of the whole config: identical to {@link VerbatraConfig} except
+ * that `provider` offers per-provider model completions. Every value assignable to
+ * this type is assignable to {@link VerbatraConfig}, because the open model union is a
+ * subtype of `string`; `defineConfig` returns the runtime {@link VerbatraConfig}.
+ */
+type AuthoringConfig = Omit<VerbatraConfig, "provider"> & {
+    provider: AuthoringProviderConfig;
+};
+
 /**
  * Identity helper for authoring a code-defined verbatra.config.ts. It returns its
  * argument unchanged; its only purpose is to give the author full type inference and
  * editor autocomplete on the config object.
+ *
+ * The argument type is {@link AuthoringConfig}, which is structurally a
+ * {@link VerbatraConfig} whose `provider.options.model` offers the selected provider's
+ * known model IDs as completions while still accepting any other string. The return
+ * type is the runtime {@link VerbatraConfig}: the suggestions are a static authoring
+ * hint, not a runtime constraint, and `loadConfig` validates `model` exactly as before.
  */
-declare function defineConfig(config: VerbatraConfig): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfig): VerbatraConfig;
 
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
@@ -107,42 +187,6 @@ interface LoadConfigOptions {
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig>;
 
-/**
- * The provider section of the config: a discriminated union over the provider id,
- * reusing each provider's own exported config schema. There is no key field anywhere
- * in this union. The provider reads its API key from the environment at construction.
- *
- * This union and the factory table below are co-located on purpose: adding a provider
- * is a single edit here (one union variant plus one table entry), and the mapped-type
- * table makes the two sets provably identical at compile time.
- */
-declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodLiteral<"anthropic">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"openai">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"gemini">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"deepl">;
-    options: z.ZodObject<{
-        glossaryId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>;
-}, z.core.$strip>], "id">;
-type ProviderConfig = z.infer<typeof providerConfigSchema>;
-type ProviderId = ProviderConfig["id"];
-
 /**
  * Structured, secret-free error codes for the SDK boundaries. A key never appears in
  * any message: provider/adapter/core errors are already secret-free, and the SDK never
@@ -236,9 +280,11 @@ type BoundedBytesRead = {
     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
- * file IO and are not routed through this seam.
+ * The minimal file-system surface the SDK needs: existence checks, the lock-file read/write,
+ * and the untrusted workbook bytes read/write for the export/import flow. Reads are bounded
+ * (see {@link readFileBounded} / {@link readBytesBounded}) and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and are not routed through
+ * this seam.
  */
 interface SdkFs {
     /** Whether a readable file exists at the path. */

package/dist/index.d.ts

@@ -1,7 +1,43 @@
+import { AnthropicModel, OpenAiModel, GeminiModel, ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { z } from 'zod';
-import { ProviderNotice, TranslationProvider } from '@verbatra/ai-providers';
 import { AdapterRegistry } from '@verbatra/format-adapters';
 
+/**
+ * The provider section of the config: a discriminated union over the provider id,
+ * reusing each provider's own exported config schema. There is no key field anywhere
+ * in this union. The provider reads its API key from the environment at construction.
+ *
+ * This union and the factory table below are co-located on purpose: adding a provider
+ * is a single edit here (one union variant plus one table entry), and the mapped-type
+ * table makes the two sets provably identical at compile time.
+ */
+declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodLiteral<"anthropic">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"gemini">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        maxOutputTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodLiteral<"deepl">;
+    options: z.ZodObject<{
+        glossaryId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strip>], "id">;
+type ProviderConfig = z.infer<typeof providerConfigSchema>;
+type ProviderId = ProviderConfig["id"];
+
 /**
  * The verbatra project configuration. Non-secret only: it carries no API key (the
  * provider reads its key from the environment), and unknown top-level keys are rejected
@@ -53,12 +89,56 @@ declare const verbatraConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
 
+/**
+ * An open union over a provider's known model IDs: the suggested IDs plus any other
+ * non-empty string. The `string & {}` arm keeps the union from collapsing to plain
+ * `string` (so editors still surface the literals as completions) while accepting a
+ * brand-new model ID the tool has never heard of. This is a static authoring hint
+ * only; the runtime schema stays `z.string().min(1)` and validates nothing against
+ * these literals.
+ */
+type OpenModel<M extends string> = M | (string & {});
+/**
+ * The authoring view of one provider variant: its runtime config with `options.model`
+ * narrowed to that provider's open model union. LLM providers (anthropic, openai,
+ * gemini) get suggestions; DeepL has no model field and is carried through unchanged.
+ */
+type AuthoringProviderConfig = AuthoringVariant<"anthropic", AnthropicModel> | AuthoringVariant<"openai", OpenAiModel> | AuthoringVariant<"gemini", GeminiModel> | Extract<ProviderConfig, {
+    id: "deepl";
+}>;
+type AuthoringVariant<Id extends ProviderConfig["id"], M extends string> = Extract<ProviderConfig, {
+    id: Id;
+}> extends infer Variant ? Variant extends {
+    options: {
+        model: string;
+    };
+} ? Omit<Variant, "options"> & {
+    options: Omit<Variant["options"], "model"> & {
+        model: OpenModel<M>;
+    };
+} : never : never;
+/**
+ * The authoring view of the whole config: identical to {@link VerbatraConfig} except
+ * that `provider` offers per-provider model completions. Every value assignable to
+ * this type is assignable to {@link VerbatraConfig}, because the open model union is a
+ * subtype of `string`; `defineConfig` returns the runtime {@link VerbatraConfig}.
+ */
+type AuthoringConfig = Omit<VerbatraConfig, "provider"> & {
+    provider: AuthoringProviderConfig;
+};
+
 /**
  * Identity helper for authoring a code-defined verbatra.config.ts. It returns its
  * argument unchanged; its only purpose is to give the author full type inference and
  * editor autocomplete on the config object.
+ *
+ * The argument type is {@link AuthoringConfig}, which is structurally a
+ * {@link VerbatraConfig} whose `provider.options.model` offers the selected provider's
+ * known model IDs as completions while still accepting any other string. The return
+ * type is the runtime {@link VerbatraConfig}: the suggestions are a static authoring
+ * hint, not a runtime constraint, and `loadConfig` validates `model` exactly as before.
  */
-declare function defineConfig(config: VerbatraConfig): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfig): VerbatraConfig;
 
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
@@ -107,42 +187,6 @@ interface LoadConfigOptions {
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig>;
 
-/**
- * The provider section of the config: a discriminated union over the provider id,
- * reusing each provider's own exported config schema. There is no key field anywhere
- * in this union. The provider reads its API key from the environment at construction.
- *
- * This union and the factory table below are co-located on purpose: adding a provider
- * is a single edit here (one union variant plus one table entry), and the mapped-type
- * table makes the two sets provably identical at compile time.
- */
-declare const providerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodLiteral<"anthropic">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"openai">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"gemini">;
-    options: z.ZodObject<{
-        model: z.ZodString;
-        maxOutputTokens: z.ZodNumber;
-    }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
-    id: z.ZodLiteral<"deepl">;
-    options: z.ZodObject<{
-        glossaryId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>;
-}, z.core.$strip>], "id">;
-type ProviderConfig = z.infer<typeof providerConfigSchema>;
-type ProviderId = ProviderConfig["id"];
-
 /**
  * Structured, secret-free error codes for the SDK boundaries. A key never appears in
  * any message: provider/adapter/core errors are already secret-free, and the SDK never
@@ -236,9 +280,11 @@ type BoundedBytesRead = {
     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
- * file IO and are not routed through this seam.
+ * The minimal file-system surface the SDK needs: existence checks, the lock-file read/write,
+ * and the untrusted workbook bytes read/write for the export/import flow. Reads are bounded
+ * (see {@link readFileBounded} / {@link readBytesBounded}) and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and are not routed through
+ * this seam.
  */
 interface SdkFs {
     /** Whether a readable file exists at the path. */