visual-ai-assertions 0.14.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +40 -14
  2. package/dist/index.cjs +325 -62
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +118 -3
  5. package/dist/index.d.ts +118 -3
  6. package/dist/index.js +324 -62
  7. package/dist/index.js.map +1 -1
  8. package/package.json +8 -2
package/dist/index.d.cts CHANGED
@@ -9,16 +9,31 @@ declare const ReasoningEffort: {
9
9
  };
10
10
  /** Union of valid reasoning effort values, derived from the ReasoningEffort constant. */
11
11
  type ReasoningEffortLevel = (typeof ReasoningEffort)[keyof typeof ReasoningEffort];
12
+ /**
13
+ * Abstract image-detail hint. Each provider driver maps it to its native
14
+ * mechanism (OpenAI/OpenRouter `detail`, Google `mediaResolution`); Anthropic
15
+ * has no equivalent (Claude auto-downscales to ~1568px / 1.15MP regardless).
16
+ * `"auto"` sends no detail field, preserving each provider's default.
17
+ */
18
+ declare const ImageDetail: {
19
+ readonly AUTO: "auto";
20
+ readonly LOW: "low";
21
+ readonly HIGH: "high";
22
+ };
23
+ /** Union of valid image-detail values, derived from the ImageDetail constant. */
24
+ type ImageDetailLevel = (typeof ImageDetail)[keyof typeof ImageDetail];
12
25
  /** Supported provider identifiers used internally for pricing and provider selection. */
13
26
  declare const Provider: {
14
27
  readonly ANTHROPIC: "anthropic";
15
28
  readonly OPENAI: "openai";
16
29
  readonly GOOGLE: "google";
30
+ readonly OPENROUTER: "openrouter";
17
31
  };
18
32
  /** Known model names grouped by provider. */
19
33
  declare const Model: {
20
34
  readonly Anthropic: {
21
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
22
37
  readonly OPUS_4_8: "claude-opus-4-8";
23
38
  readonly OPUS_4_7: "claude-opus-4-7";
24
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -39,19 +54,38 @@ declare const Model: {
39
54
  readonly GPT_5_MINI: "gpt-5-mini";
40
55
  };
41
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
59
+ readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
42
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
61
+ readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
43
62
  readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
44
63
  readonly GEMINI_3_1_FLASH_LITE: "gemini-3.1-flash-lite";
45
64
  readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
46
65
  };
66
+ /**
67
+ * Models routed through OpenRouter (https://openrouter.ai). Slugs always
68
+ * carry a vendor prefix (`vendor/model`), which is how provider inference
69
+ * recognizes them. All listed models accept image input.
70
+ */
71
+ readonly OpenRouter: {
72
+ readonly GROK_4_6: "x-ai/grok-4.6";
73
+ readonly GROK_4_5: "x-ai/grok-4.5";
74
+ readonly KIMI_K3: "moonshotai/kimi-k3";
75
+ readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
76
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
77
+ readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
78
+ readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
79
+ };
47
80
  };
48
81
  /** Union of all built-in model name literals exposed by `Model`. */
49
- type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google];
82
+ type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google] | (typeof Model.OpenRouter)[keyof typeof Model.OpenRouter];
50
83
  /** Default model selection used when a caller omits `config.model`. */
51
84
  declare const DEFAULT_MODELS: {
52
85
  readonly anthropic: "claude-sonnet-4-6";
53
86
  readonly openai: "gpt-5.4-mini";
54
87
  readonly google: "gemini-3-flash-preview";
88
+ readonly openrouter: "qwen/qwen3.6-flash";
55
89
  };
56
90
  /** Built-in content checks available through `client.content()`. */
57
91
  declare const Content: {
@@ -157,19 +191,33 @@ declare const UsageInfoSchema: z.ZodObject<{
157
191
  outputTokens: z.ZodNumber;
158
192
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
159
193
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
194
+ /**
195
+ * Prompt tokens served from the provider's cache, when reported. Informational
196
+ * only — `estimatedCost` does not apply a cache discount, because providers
197
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
198
+ * Google) or billed as a separate bucket alongside it (Anthropic).
199
+ */
200
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
201
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
160
202
  estimatedCost: z.ZodOptional<z.ZodNumber>;
203
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
204
+ reportedCost: z.ZodOptional<z.ZodNumber>;
161
205
  durationSeconds: z.ZodOptional<z.ZodNumber>;
162
206
  }, "strip", z.ZodTypeAny, {
163
207
  inputTokens: number;
164
208
  outputTokens: number;
165
209
  reasoningTokens?: number | undefined;
210
+ cachedInputTokens?: number | undefined;
166
211
  estimatedCost?: number | undefined;
212
+ reportedCost?: number | undefined;
167
213
  durationSeconds?: number | undefined;
168
214
  }, {
169
215
  inputTokens: number;
170
216
  outputTokens: number;
171
217
  reasoningTokens?: number | undefined;
218
+ cachedInputTokens?: number | undefined;
172
219
  estimatedCost?: number | undefined;
220
+ reportedCost?: number | undefined;
173
221
  durationSeconds?: number | undefined;
174
222
  }>;
175
223
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -190,19 +238,33 @@ declare const CheckResultSchema: z.ZodObject<{
190
238
  outputTokens: z.ZodNumber;
191
239
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
192
240
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
241
+ /**
242
+ * Prompt tokens served from the provider's cache, when reported. Informational
243
+ * only — `estimatedCost` does not apply a cache discount, because providers
244
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
245
+ * Google) or billed as a separate bucket alongside it (Anthropic).
246
+ */
247
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
248
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
193
249
  estimatedCost: z.ZodOptional<z.ZodNumber>;
250
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
251
+ reportedCost: z.ZodOptional<z.ZodNumber>;
194
252
  durationSeconds: z.ZodOptional<z.ZodNumber>;
195
253
  }, "strip", z.ZodTypeAny, {
196
254
  inputTokens: number;
197
255
  outputTokens: number;
198
256
  reasoningTokens?: number | undefined;
257
+ cachedInputTokens?: number | undefined;
199
258
  estimatedCost?: number | undefined;
259
+ reportedCost?: number | undefined;
200
260
  durationSeconds?: number | undefined;
201
261
  }, {
202
262
  inputTokens: number;
203
263
  outputTokens: number;
204
264
  reasoningTokens?: number | undefined;
265
+ cachedInputTokens?: number | undefined;
205
266
  estimatedCost?: number | undefined;
267
+ reportedCost?: number | undefined;
206
268
  durationSeconds?: number | undefined;
207
269
  }>>;
208
270
  } & {
@@ -266,7 +328,9 @@ declare const CheckResultSchema: z.ZodObject<{
266
328
  inputTokens: number;
267
329
  outputTokens: number;
268
330
  reasoningTokens?: number | undefined;
331
+ cachedInputTokens?: number | undefined;
269
332
  estimatedCost?: number | undefined;
333
+ reportedCost?: number | undefined;
270
334
  durationSeconds?: number | undefined;
271
335
  } | undefined;
272
336
  }, {
@@ -289,7 +353,9 @@ declare const CheckResultSchema: z.ZodObject<{
289
353
  inputTokens: number;
290
354
  outputTokens: number;
291
355
  reasoningTokens?: number | undefined;
356
+ cachedInputTokens?: number | undefined;
292
357
  estimatedCost?: number | undefined;
358
+ reportedCost?: number | undefined;
293
359
  durationSeconds?: number | undefined;
294
360
  } | undefined;
295
361
  }>;
@@ -332,19 +398,33 @@ declare const CompareResultSchema: z.ZodObject<{
332
398
  outputTokens: z.ZodNumber;
333
399
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
334
400
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
401
+ /**
402
+ * Prompt tokens served from the provider's cache, when reported. Informational
403
+ * only — `estimatedCost` does not apply a cache discount, because providers
404
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
405
+ * Google) or billed as a separate bucket alongside it (Anthropic).
406
+ */
407
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
408
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
335
409
  estimatedCost: z.ZodOptional<z.ZodNumber>;
410
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
411
+ reportedCost: z.ZodOptional<z.ZodNumber>;
336
412
  durationSeconds: z.ZodOptional<z.ZodNumber>;
337
413
  }, "strip", z.ZodTypeAny, {
338
414
  inputTokens: number;
339
415
  outputTokens: number;
340
416
  reasoningTokens?: number | undefined;
417
+ cachedInputTokens?: number | undefined;
341
418
  estimatedCost?: number | undefined;
419
+ reportedCost?: number | undefined;
342
420
  durationSeconds?: number | undefined;
343
421
  }, {
344
422
  inputTokens: number;
345
423
  outputTokens: number;
346
424
  reasoningTokens?: number | undefined;
425
+ cachedInputTokens?: number | undefined;
347
426
  estimatedCost?: number | undefined;
427
+ reportedCost?: number | undefined;
348
428
  durationSeconds?: number | undefined;
349
429
  }>>;
350
430
  } & {
@@ -369,7 +449,9 @@ declare const CompareResultSchema: z.ZodObject<{
369
449
  inputTokens: number;
370
450
  outputTokens: number;
371
451
  reasoningTokens?: number | undefined;
452
+ cachedInputTokens?: number | undefined;
372
453
  estimatedCost?: number | undefined;
454
+ reportedCost?: number | undefined;
373
455
  durationSeconds?: number | undefined;
374
456
  } | undefined;
375
457
  }, {
@@ -383,7 +465,9 @@ declare const CompareResultSchema: z.ZodObject<{
383
465
  inputTokens: number;
384
466
  outputTokens: number;
385
467
  reasoningTokens?: number | undefined;
468
+ cachedInputTokens?: number | undefined;
386
469
  estimatedCost?: number | undefined;
470
+ reportedCost?: number | undefined;
387
471
  durationSeconds?: number | undefined;
388
472
  } | undefined;
389
473
  }>;
@@ -431,19 +515,33 @@ declare const AskResultSchema: z.ZodObject<{
431
515
  outputTokens: z.ZodNumber;
432
516
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
433
517
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
518
+ /**
519
+ * Prompt tokens served from the provider's cache, when reported. Informational
520
+ * only — `estimatedCost` does not apply a cache discount, because providers
521
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
522
+ * Google) or billed as a separate bucket alongside it (Anthropic).
523
+ */
524
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
525
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
434
526
  estimatedCost: z.ZodOptional<z.ZodNumber>;
527
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
528
+ reportedCost: z.ZodOptional<z.ZodNumber>;
435
529
  durationSeconds: z.ZodOptional<z.ZodNumber>;
436
530
  }, "strip", z.ZodTypeAny, {
437
531
  inputTokens: number;
438
532
  outputTokens: number;
439
533
  reasoningTokens?: number | undefined;
534
+ cachedInputTokens?: number | undefined;
440
535
  estimatedCost?: number | undefined;
536
+ reportedCost?: number | undefined;
441
537
  durationSeconds?: number | undefined;
442
538
  }, {
443
539
  inputTokens: number;
444
540
  outputTokens: number;
445
541
  reasoningTokens?: number | undefined;
542
+ cachedInputTokens?: number | undefined;
446
543
  estimatedCost?: number | undefined;
544
+ reportedCost?: number | undefined;
447
545
  durationSeconds?: number | undefined;
448
546
  }>>;
449
547
  }, "strip", z.ZodTypeAny, {
@@ -458,7 +556,9 @@ declare const AskResultSchema: z.ZodObject<{
458
556
  inputTokens: number;
459
557
  outputTokens: number;
460
558
  reasoningTokens?: number | undefined;
559
+ cachedInputTokens?: number | undefined;
461
560
  estimatedCost?: number | undefined;
561
+ reportedCost?: number | undefined;
462
562
  durationSeconds?: number | undefined;
463
563
  } | undefined;
464
564
  frameReferences?: number[] | null | undefined;
@@ -474,7 +574,9 @@ declare const AskResultSchema: z.ZodObject<{
474
574
  inputTokens: number;
475
575
  outputTokens: number;
476
576
  reasoningTokens?: number | undefined;
577
+ cachedInputTokens?: number | undefined;
477
578
  estimatedCost?: number | undefined;
579
+ reportedCost?: number | undefined;
478
580
  durationSeconds?: number | undefined;
479
581
  } | undefined;
480
582
  frameReferences?: number[] | null | undefined;
@@ -528,7 +630,7 @@ type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif"
528
630
  /** Supported video MIME types the client can accept and sample frames from. */
529
631
  type SupportedVideoMimeType = "video/mp4" | "video/webm" | "video/quicktime" | "video/x-matroska";
530
632
  /** Supported provider identifiers. */
531
- type ProviderName = "anthropic" | "openai" | "google";
633
+ type ProviderName = "anthropic" | "openai" | "google" | "openrouter";
532
634
  /**
533
635
  * Configuration for creating a visual AI client.
534
636
  *
@@ -551,6 +653,19 @@ interface VisualAIConfig {
551
653
  debugResponse?: boolean;
552
654
  maxTokens?: number;
553
655
  reasoningEffort?: ReasoningEffortLevel;
656
+ /**
657
+ * Longest-edge pixel cap for image inputs before they are sent to the
658
+ * provider. Defaults to 1568. Raising it only helps providers that accept
659
+ * higher-resolution requests (OpenAI with `imageDetail: "high"` scales into a
660
+ * 2048px box); Anthropic re-downscales to ~1568px regardless.
661
+ */
662
+ maxImageDimension?: number;
663
+ /**
664
+ * Image-detail hint mapped per provider: OpenAI/OpenRouter `detail`, Google
665
+ * `mediaResolution`. `"auto"` (default) sends no detail field. No effect on
666
+ * Anthropic (Claude auto-downscales images).
667
+ */
668
+ imageDetail?: ImageDetailLevel;
554
669
  trackUsage?: boolean;
555
670
  }
556
671
  /** Optional instructions for `check()`. */
@@ -1089,4 +1204,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1089
1204
  */
1090
1205
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1091
1206
 
1092
- export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FramesInput, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
1207
+ export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FramesInput, ImageDetail, type ImageDetailLevel, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
package/dist/index.d.ts CHANGED
@@ -9,16 +9,31 @@ declare const ReasoningEffort: {
9
9
  };
10
10
  /** Union of valid reasoning effort values, derived from the ReasoningEffort constant. */
11
11
  type ReasoningEffortLevel = (typeof ReasoningEffort)[keyof typeof ReasoningEffort];
12
+ /**
13
+ * Abstract image-detail hint. Each provider driver maps it to its native
14
+ * mechanism (OpenAI/OpenRouter `detail`, Google `mediaResolution`); Anthropic
15
+ * has no equivalent (Claude auto-downscales to ~1568px / 1.15MP regardless).
16
+ * `"auto"` sends no detail field, preserving each provider's default.
17
+ */
18
+ declare const ImageDetail: {
19
+ readonly AUTO: "auto";
20
+ readonly LOW: "low";
21
+ readonly HIGH: "high";
22
+ };
23
+ /** Union of valid image-detail values, derived from the ImageDetail constant. */
24
+ type ImageDetailLevel = (typeof ImageDetail)[keyof typeof ImageDetail];
12
25
  /** Supported provider identifiers used internally for pricing and provider selection. */
13
26
  declare const Provider: {
14
27
  readonly ANTHROPIC: "anthropic";
15
28
  readonly OPENAI: "openai";
16
29
  readonly GOOGLE: "google";
30
+ readonly OPENROUTER: "openrouter";
17
31
  };
18
32
  /** Known model names grouped by provider. */
19
33
  declare const Model: {
20
34
  readonly Anthropic: {
21
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
22
37
  readonly OPUS_4_8: "claude-opus-4-8";
23
38
  readonly OPUS_4_7: "claude-opus-4-7";
24
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -39,19 +54,38 @@ declare const Model: {
39
54
  readonly GPT_5_MINI: "gpt-5-mini";
40
55
  };
41
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
59
+ readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
42
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
61
+ readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
43
62
  readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
44
63
  readonly GEMINI_3_1_FLASH_LITE: "gemini-3.1-flash-lite";
45
64
  readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
46
65
  };
66
+ /**
67
+ * Models routed through OpenRouter (https://openrouter.ai). Slugs always
68
+ * carry a vendor prefix (`vendor/model`), which is how provider inference
69
+ * recognizes them. All listed models accept image input.
70
+ */
71
+ readonly OpenRouter: {
72
+ readonly GROK_4_6: "x-ai/grok-4.6";
73
+ readonly GROK_4_5: "x-ai/grok-4.5";
74
+ readonly KIMI_K3: "moonshotai/kimi-k3";
75
+ readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
76
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
77
+ readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
78
+ readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
79
+ };
47
80
  };
48
81
  /** Union of all built-in model name literals exposed by `Model`. */
49
- type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google];
82
+ type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google] | (typeof Model.OpenRouter)[keyof typeof Model.OpenRouter];
50
83
  /** Default model selection used when a caller omits `config.model`. */
51
84
  declare const DEFAULT_MODELS: {
52
85
  readonly anthropic: "claude-sonnet-4-6";
53
86
  readonly openai: "gpt-5.4-mini";
54
87
  readonly google: "gemini-3-flash-preview";
88
+ readonly openrouter: "qwen/qwen3.6-flash";
55
89
  };
56
90
  /** Built-in content checks available through `client.content()`. */
57
91
  declare const Content: {
@@ -157,19 +191,33 @@ declare const UsageInfoSchema: z.ZodObject<{
157
191
  outputTokens: z.ZodNumber;
158
192
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
159
193
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
194
+ /**
195
+ * Prompt tokens served from the provider's cache, when reported. Informational
196
+ * only — `estimatedCost` does not apply a cache discount, because providers
197
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
198
+ * Google) or billed as a separate bucket alongside it (Anthropic).
199
+ */
200
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
201
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
160
202
  estimatedCost: z.ZodOptional<z.ZodNumber>;
203
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
204
+ reportedCost: z.ZodOptional<z.ZodNumber>;
161
205
  durationSeconds: z.ZodOptional<z.ZodNumber>;
162
206
  }, "strip", z.ZodTypeAny, {
163
207
  inputTokens: number;
164
208
  outputTokens: number;
165
209
  reasoningTokens?: number | undefined;
210
+ cachedInputTokens?: number | undefined;
166
211
  estimatedCost?: number | undefined;
212
+ reportedCost?: number | undefined;
167
213
  durationSeconds?: number | undefined;
168
214
  }, {
169
215
  inputTokens: number;
170
216
  outputTokens: number;
171
217
  reasoningTokens?: number | undefined;
218
+ cachedInputTokens?: number | undefined;
172
219
  estimatedCost?: number | undefined;
220
+ reportedCost?: number | undefined;
173
221
  durationSeconds?: number | undefined;
174
222
  }>;
175
223
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -190,19 +238,33 @@ declare const CheckResultSchema: z.ZodObject<{
190
238
  outputTokens: z.ZodNumber;
191
239
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
192
240
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
241
+ /**
242
+ * Prompt tokens served from the provider's cache, when reported. Informational
243
+ * only — `estimatedCost` does not apply a cache discount, because providers
244
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
245
+ * Google) or billed as a separate bucket alongside it (Anthropic).
246
+ */
247
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
248
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
193
249
  estimatedCost: z.ZodOptional<z.ZodNumber>;
250
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
251
+ reportedCost: z.ZodOptional<z.ZodNumber>;
194
252
  durationSeconds: z.ZodOptional<z.ZodNumber>;
195
253
  }, "strip", z.ZodTypeAny, {
196
254
  inputTokens: number;
197
255
  outputTokens: number;
198
256
  reasoningTokens?: number | undefined;
257
+ cachedInputTokens?: number | undefined;
199
258
  estimatedCost?: number | undefined;
259
+ reportedCost?: number | undefined;
200
260
  durationSeconds?: number | undefined;
201
261
  }, {
202
262
  inputTokens: number;
203
263
  outputTokens: number;
204
264
  reasoningTokens?: number | undefined;
265
+ cachedInputTokens?: number | undefined;
205
266
  estimatedCost?: number | undefined;
267
+ reportedCost?: number | undefined;
206
268
  durationSeconds?: number | undefined;
207
269
  }>>;
208
270
  } & {
@@ -266,7 +328,9 @@ declare const CheckResultSchema: z.ZodObject<{
266
328
  inputTokens: number;
267
329
  outputTokens: number;
268
330
  reasoningTokens?: number | undefined;
331
+ cachedInputTokens?: number | undefined;
269
332
  estimatedCost?: number | undefined;
333
+ reportedCost?: number | undefined;
270
334
  durationSeconds?: number | undefined;
271
335
  } | undefined;
272
336
  }, {
@@ -289,7 +353,9 @@ declare const CheckResultSchema: z.ZodObject<{
289
353
  inputTokens: number;
290
354
  outputTokens: number;
291
355
  reasoningTokens?: number | undefined;
356
+ cachedInputTokens?: number | undefined;
292
357
  estimatedCost?: number | undefined;
358
+ reportedCost?: number | undefined;
293
359
  durationSeconds?: number | undefined;
294
360
  } | undefined;
295
361
  }>;
@@ -332,19 +398,33 @@ declare const CompareResultSchema: z.ZodObject<{
332
398
  outputTokens: z.ZodNumber;
333
399
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
334
400
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
401
+ /**
402
+ * Prompt tokens served from the provider's cache, when reported. Informational
403
+ * only — `estimatedCost` does not apply a cache discount, because providers
404
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
405
+ * Google) or billed as a separate bucket alongside it (Anthropic).
406
+ */
407
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
408
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
335
409
  estimatedCost: z.ZodOptional<z.ZodNumber>;
410
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
411
+ reportedCost: z.ZodOptional<z.ZodNumber>;
336
412
  durationSeconds: z.ZodOptional<z.ZodNumber>;
337
413
  }, "strip", z.ZodTypeAny, {
338
414
  inputTokens: number;
339
415
  outputTokens: number;
340
416
  reasoningTokens?: number | undefined;
417
+ cachedInputTokens?: number | undefined;
341
418
  estimatedCost?: number | undefined;
419
+ reportedCost?: number | undefined;
342
420
  durationSeconds?: number | undefined;
343
421
  }, {
344
422
  inputTokens: number;
345
423
  outputTokens: number;
346
424
  reasoningTokens?: number | undefined;
425
+ cachedInputTokens?: number | undefined;
347
426
  estimatedCost?: number | undefined;
427
+ reportedCost?: number | undefined;
348
428
  durationSeconds?: number | undefined;
349
429
  }>>;
350
430
  } & {
@@ -369,7 +449,9 @@ declare const CompareResultSchema: z.ZodObject<{
369
449
  inputTokens: number;
370
450
  outputTokens: number;
371
451
  reasoningTokens?: number | undefined;
452
+ cachedInputTokens?: number | undefined;
372
453
  estimatedCost?: number | undefined;
454
+ reportedCost?: number | undefined;
373
455
  durationSeconds?: number | undefined;
374
456
  } | undefined;
375
457
  }, {
@@ -383,7 +465,9 @@ declare const CompareResultSchema: z.ZodObject<{
383
465
  inputTokens: number;
384
466
  outputTokens: number;
385
467
  reasoningTokens?: number | undefined;
468
+ cachedInputTokens?: number | undefined;
386
469
  estimatedCost?: number | undefined;
470
+ reportedCost?: number | undefined;
387
471
  durationSeconds?: number | undefined;
388
472
  } | undefined;
389
473
  }>;
@@ -431,19 +515,33 @@ declare const AskResultSchema: z.ZodObject<{
431
515
  outputTokens: z.ZodNumber;
432
516
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
433
517
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
518
+ /**
519
+ * Prompt tokens served from the provider's cache, when reported. Informational
520
+ * only — `estimatedCost` does not apply a cache discount, because providers
521
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
522
+ * Google) or billed as a separate bucket alongside it (Anthropic).
523
+ */
524
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
525
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
434
526
  estimatedCost: z.ZodOptional<z.ZodNumber>;
527
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
528
+ reportedCost: z.ZodOptional<z.ZodNumber>;
435
529
  durationSeconds: z.ZodOptional<z.ZodNumber>;
436
530
  }, "strip", z.ZodTypeAny, {
437
531
  inputTokens: number;
438
532
  outputTokens: number;
439
533
  reasoningTokens?: number | undefined;
534
+ cachedInputTokens?: number | undefined;
440
535
  estimatedCost?: number | undefined;
536
+ reportedCost?: number | undefined;
441
537
  durationSeconds?: number | undefined;
442
538
  }, {
443
539
  inputTokens: number;
444
540
  outputTokens: number;
445
541
  reasoningTokens?: number | undefined;
542
+ cachedInputTokens?: number | undefined;
446
543
  estimatedCost?: number | undefined;
544
+ reportedCost?: number | undefined;
447
545
  durationSeconds?: number | undefined;
448
546
  }>>;
449
547
  }, "strip", z.ZodTypeAny, {
@@ -458,7 +556,9 @@ declare const AskResultSchema: z.ZodObject<{
458
556
  inputTokens: number;
459
557
  outputTokens: number;
460
558
  reasoningTokens?: number | undefined;
559
+ cachedInputTokens?: number | undefined;
461
560
  estimatedCost?: number | undefined;
561
+ reportedCost?: number | undefined;
462
562
  durationSeconds?: number | undefined;
463
563
  } | undefined;
464
564
  frameReferences?: number[] | null | undefined;
@@ -474,7 +574,9 @@ declare const AskResultSchema: z.ZodObject<{
474
574
  inputTokens: number;
475
575
  outputTokens: number;
476
576
  reasoningTokens?: number | undefined;
577
+ cachedInputTokens?: number | undefined;
477
578
  estimatedCost?: number | undefined;
579
+ reportedCost?: number | undefined;
478
580
  durationSeconds?: number | undefined;
479
581
  } | undefined;
480
582
  frameReferences?: number[] | null | undefined;
@@ -528,7 +630,7 @@ type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif"
528
630
  /** Supported video MIME types the client can accept and sample frames from. */
529
631
  type SupportedVideoMimeType = "video/mp4" | "video/webm" | "video/quicktime" | "video/x-matroska";
530
632
  /** Supported provider identifiers. */
531
- type ProviderName = "anthropic" | "openai" | "google";
633
+ type ProviderName = "anthropic" | "openai" | "google" | "openrouter";
532
634
  /**
533
635
  * Configuration for creating a visual AI client.
534
636
  *
@@ -551,6 +653,19 @@ interface VisualAIConfig {
551
653
  debugResponse?: boolean;
552
654
  maxTokens?: number;
553
655
  reasoningEffort?: ReasoningEffortLevel;
656
+ /**
657
+ * Longest-edge pixel cap for image inputs before they are sent to the
658
+ * provider. Defaults to 1568. Raising it only helps providers that accept
659
+ * higher-resolution requests (OpenAI with `imageDetail: "high"` scales into a
660
+ * 2048px box); Anthropic re-downscales to ~1568px regardless.
661
+ */
662
+ maxImageDimension?: number;
663
+ /**
664
+ * Image-detail hint mapped per provider: OpenAI/OpenRouter `detail`, Google
665
+ * `mediaResolution`. `"auto"` (default) sends no detail field. No effect on
666
+ * Anthropic (Claude auto-downscales images).
667
+ */
668
+ imageDetail?: ImageDetailLevel;
554
669
  trackUsage?: boolean;
555
670
  }
556
671
  /** Optional instructions for `check()`. */
@@ -1089,4 +1204,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1089
1204
  */
1090
1205
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1091
1206
 
1092
- export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FramesInput, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
1207
+ export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type Frame, type FramesInput, ImageDetail, type ImageDetailLevel, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };