visual-ai-assertions 0.16.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 +12 -6
  2. package/dist/index.cjs +145 -51
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +100 -1
  5. package/dist/index.d.ts +100 -1
  6. package/dist/index.js +144 -51
  7. package/dist/index.js.map +1 -1
  8. package/package.json +4 -2
package/dist/index.d.cts CHANGED
@@ -9,6 +9,19 @@ 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";
@@ -20,6 +33,7 @@ declare const Provider: {
20
33
  declare const Model: {
21
34
  readonly Anthropic: {
22
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
23
37
  readonly OPUS_4_8: "claude-opus-4-8";
24
38
  readonly OPUS_4_7: "claude-opus-4-7";
25
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -40,6 +54,8 @@ declare const Model: {
40
54
  readonly GPT_5_MINI: "gpt-5-mini";
41
55
  };
42
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
43
59
  readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
44
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
45
61
  readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
@@ -53,9 +69,11 @@ declare const Model: {
53
69
  * recognizes them. All listed models accept image input.
54
70
  */
55
71
  readonly OpenRouter: {
72
+ readonly GROK_4_6: "x-ai/grok-4.6";
56
73
  readonly GROK_4_5: "x-ai/grok-4.5";
57
74
  readonly KIMI_K3: "moonshotai/kimi-k3";
58
75
  readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
76
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
59
77
  readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
60
78
  readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
61
79
  };
@@ -173,19 +191,33 @@ declare const UsageInfoSchema: z.ZodObject<{
173
191
  outputTokens: z.ZodNumber;
174
192
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
175
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). */
176
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>;
177
205
  durationSeconds: z.ZodOptional<z.ZodNumber>;
178
206
  }, "strip", z.ZodTypeAny, {
179
207
  inputTokens: number;
180
208
  outputTokens: number;
181
209
  reasoningTokens?: number | undefined;
210
+ cachedInputTokens?: number | undefined;
182
211
  estimatedCost?: number | undefined;
212
+ reportedCost?: number | undefined;
183
213
  durationSeconds?: number | undefined;
184
214
  }, {
185
215
  inputTokens: number;
186
216
  outputTokens: number;
187
217
  reasoningTokens?: number | undefined;
218
+ cachedInputTokens?: number | undefined;
188
219
  estimatedCost?: number | undefined;
220
+ reportedCost?: number | undefined;
189
221
  durationSeconds?: number | undefined;
190
222
  }>;
191
223
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -206,19 +238,33 @@ declare const CheckResultSchema: z.ZodObject<{
206
238
  outputTokens: z.ZodNumber;
207
239
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
208
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). */
209
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>;
210
252
  durationSeconds: z.ZodOptional<z.ZodNumber>;
211
253
  }, "strip", z.ZodTypeAny, {
212
254
  inputTokens: number;
213
255
  outputTokens: number;
214
256
  reasoningTokens?: number | undefined;
257
+ cachedInputTokens?: number | undefined;
215
258
  estimatedCost?: number | undefined;
259
+ reportedCost?: number | undefined;
216
260
  durationSeconds?: number | undefined;
217
261
  }, {
218
262
  inputTokens: number;
219
263
  outputTokens: number;
220
264
  reasoningTokens?: number | undefined;
265
+ cachedInputTokens?: number | undefined;
221
266
  estimatedCost?: number | undefined;
267
+ reportedCost?: number | undefined;
222
268
  durationSeconds?: number | undefined;
223
269
  }>>;
224
270
  } & {
@@ -282,7 +328,9 @@ declare const CheckResultSchema: z.ZodObject<{
282
328
  inputTokens: number;
283
329
  outputTokens: number;
284
330
  reasoningTokens?: number | undefined;
331
+ cachedInputTokens?: number | undefined;
285
332
  estimatedCost?: number | undefined;
333
+ reportedCost?: number | undefined;
286
334
  durationSeconds?: number | undefined;
287
335
  } | undefined;
288
336
  }, {
@@ -305,7 +353,9 @@ declare const CheckResultSchema: z.ZodObject<{
305
353
  inputTokens: number;
306
354
  outputTokens: number;
307
355
  reasoningTokens?: number | undefined;
356
+ cachedInputTokens?: number | undefined;
308
357
  estimatedCost?: number | undefined;
358
+ reportedCost?: number | undefined;
309
359
  durationSeconds?: number | undefined;
310
360
  } | undefined;
311
361
  }>;
@@ -348,19 +398,33 @@ declare const CompareResultSchema: z.ZodObject<{
348
398
  outputTokens: z.ZodNumber;
349
399
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
350
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). */
351
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>;
352
412
  durationSeconds: z.ZodOptional<z.ZodNumber>;
353
413
  }, "strip", z.ZodTypeAny, {
354
414
  inputTokens: number;
355
415
  outputTokens: number;
356
416
  reasoningTokens?: number | undefined;
417
+ cachedInputTokens?: number | undefined;
357
418
  estimatedCost?: number | undefined;
419
+ reportedCost?: number | undefined;
358
420
  durationSeconds?: number | undefined;
359
421
  }, {
360
422
  inputTokens: number;
361
423
  outputTokens: number;
362
424
  reasoningTokens?: number | undefined;
425
+ cachedInputTokens?: number | undefined;
363
426
  estimatedCost?: number | undefined;
427
+ reportedCost?: number | undefined;
364
428
  durationSeconds?: number | undefined;
365
429
  }>>;
366
430
  } & {
@@ -385,7 +449,9 @@ declare const CompareResultSchema: z.ZodObject<{
385
449
  inputTokens: number;
386
450
  outputTokens: number;
387
451
  reasoningTokens?: number | undefined;
452
+ cachedInputTokens?: number | undefined;
388
453
  estimatedCost?: number | undefined;
454
+ reportedCost?: number | undefined;
389
455
  durationSeconds?: number | undefined;
390
456
  } | undefined;
391
457
  }, {
@@ -399,7 +465,9 @@ declare const CompareResultSchema: z.ZodObject<{
399
465
  inputTokens: number;
400
466
  outputTokens: number;
401
467
  reasoningTokens?: number | undefined;
468
+ cachedInputTokens?: number | undefined;
402
469
  estimatedCost?: number | undefined;
470
+ reportedCost?: number | undefined;
403
471
  durationSeconds?: number | undefined;
404
472
  } | undefined;
405
473
  }>;
@@ -447,19 +515,33 @@ declare const AskResultSchema: z.ZodObject<{
447
515
  outputTokens: z.ZodNumber;
448
516
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
449
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). */
450
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>;
451
529
  durationSeconds: z.ZodOptional<z.ZodNumber>;
452
530
  }, "strip", z.ZodTypeAny, {
453
531
  inputTokens: number;
454
532
  outputTokens: number;
455
533
  reasoningTokens?: number | undefined;
534
+ cachedInputTokens?: number | undefined;
456
535
  estimatedCost?: number | undefined;
536
+ reportedCost?: number | undefined;
457
537
  durationSeconds?: number | undefined;
458
538
  }, {
459
539
  inputTokens: number;
460
540
  outputTokens: number;
461
541
  reasoningTokens?: number | undefined;
542
+ cachedInputTokens?: number | undefined;
462
543
  estimatedCost?: number | undefined;
544
+ reportedCost?: number | undefined;
463
545
  durationSeconds?: number | undefined;
464
546
  }>>;
465
547
  }, "strip", z.ZodTypeAny, {
@@ -474,7 +556,9 @@ declare const AskResultSchema: z.ZodObject<{
474
556
  inputTokens: number;
475
557
  outputTokens: number;
476
558
  reasoningTokens?: number | undefined;
559
+ cachedInputTokens?: number | undefined;
477
560
  estimatedCost?: number | undefined;
561
+ reportedCost?: number | undefined;
478
562
  durationSeconds?: number | undefined;
479
563
  } | undefined;
480
564
  frameReferences?: number[] | null | undefined;
@@ -490,7 +574,9 @@ declare const AskResultSchema: z.ZodObject<{
490
574
  inputTokens: number;
491
575
  outputTokens: number;
492
576
  reasoningTokens?: number | undefined;
577
+ cachedInputTokens?: number | undefined;
493
578
  estimatedCost?: number | undefined;
579
+ reportedCost?: number | undefined;
494
580
  durationSeconds?: number | undefined;
495
581
  } | undefined;
496
582
  frameReferences?: number[] | null | undefined;
@@ -567,6 +653,19 @@ interface VisualAIConfig {
567
653
  debugResponse?: boolean;
568
654
  maxTokens?: number;
569
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;
570
669
  trackUsage?: boolean;
571
670
  }
572
671
  /** Optional instructions for `check()`. */
@@ -1105,4 +1204,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1105
1204
  */
1106
1205
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1107
1206
 
1108
- 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,6 +9,19 @@ 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";
@@ -20,6 +33,7 @@ declare const Provider: {
20
33
  declare const Model: {
21
34
  readonly Anthropic: {
22
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
23
37
  readonly OPUS_4_8: "claude-opus-4-8";
24
38
  readonly OPUS_4_7: "claude-opus-4-7";
25
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -40,6 +54,8 @@ declare const Model: {
40
54
  readonly GPT_5_MINI: "gpt-5-mini";
41
55
  };
42
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
43
59
  readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
44
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
45
61
  readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
@@ -53,9 +69,11 @@ declare const Model: {
53
69
  * recognizes them. All listed models accept image input.
54
70
  */
55
71
  readonly OpenRouter: {
72
+ readonly GROK_4_6: "x-ai/grok-4.6";
56
73
  readonly GROK_4_5: "x-ai/grok-4.5";
57
74
  readonly KIMI_K3: "moonshotai/kimi-k3";
58
75
  readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
76
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
59
77
  readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
60
78
  readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
61
79
  };
@@ -173,19 +191,33 @@ declare const UsageInfoSchema: z.ZodObject<{
173
191
  outputTokens: z.ZodNumber;
174
192
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
175
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). */
176
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>;
177
205
  durationSeconds: z.ZodOptional<z.ZodNumber>;
178
206
  }, "strip", z.ZodTypeAny, {
179
207
  inputTokens: number;
180
208
  outputTokens: number;
181
209
  reasoningTokens?: number | undefined;
210
+ cachedInputTokens?: number | undefined;
182
211
  estimatedCost?: number | undefined;
212
+ reportedCost?: number | undefined;
183
213
  durationSeconds?: number | undefined;
184
214
  }, {
185
215
  inputTokens: number;
186
216
  outputTokens: number;
187
217
  reasoningTokens?: number | undefined;
218
+ cachedInputTokens?: number | undefined;
188
219
  estimatedCost?: number | undefined;
220
+ reportedCost?: number | undefined;
189
221
  durationSeconds?: number | undefined;
190
222
  }>;
191
223
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -206,19 +238,33 @@ declare const CheckResultSchema: z.ZodObject<{
206
238
  outputTokens: z.ZodNumber;
207
239
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
208
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). */
209
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>;
210
252
  durationSeconds: z.ZodOptional<z.ZodNumber>;
211
253
  }, "strip", z.ZodTypeAny, {
212
254
  inputTokens: number;
213
255
  outputTokens: number;
214
256
  reasoningTokens?: number | undefined;
257
+ cachedInputTokens?: number | undefined;
215
258
  estimatedCost?: number | undefined;
259
+ reportedCost?: number | undefined;
216
260
  durationSeconds?: number | undefined;
217
261
  }, {
218
262
  inputTokens: number;
219
263
  outputTokens: number;
220
264
  reasoningTokens?: number | undefined;
265
+ cachedInputTokens?: number | undefined;
221
266
  estimatedCost?: number | undefined;
267
+ reportedCost?: number | undefined;
222
268
  durationSeconds?: number | undefined;
223
269
  }>>;
224
270
  } & {
@@ -282,7 +328,9 @@ declare const CheckResultSchema: z.ZodObject<{
282
328
  inputTokens: number;
283
329
  outputTokens: number;
284
330
  reasoningTokens?: number | undefined;
331
+ cachedInputTokens?: number | undefined;
285
332
  estimatedCost?: number | undefined;
333
+ reportedCost?: number | undefined;
286
334
  durationSeconds?: number | undefined;
287
335
  } | undefined;
288
336
  }, {
@@ -305,7 +353,9 @@ declare const CheckResultSchema: z.ZodObject<{
305
353
  inputTokens: number;
306
354
  outputTokens: number;
307
355
  reasoningTokens?: number | undefined;
356
+ cachedInputTokens?: number | undefined;
308
357
  estimatedCost?: number | undefined;
358
+ reportedCost?: number | undefined;
309
359
  durationSeconds?: number | undefined;
310
360
  } | undefined;
311
361
  }>;
@@ -348,19 +398,33 @@ declare const CompareResultSchema: z.ZodObject<{
348
398
  outputTokens: z.ZodNumber;
349
399
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
350
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). */
351
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>;
352
412
  durationSeconds: z.ZodOptional<z.ZodNumber>;
353
413
  }, "strip", z.ZodTypeAny, {
354
414
  inputTokens: number;
355
415
  outputTokens: number;
356
416
  reasoningTokens?: number | undefined;
417
+ cachedInputTokens?: number | undefined;
357
418
  estimatedCost?: number | undefined;
419
+ reportedCost?: number | undefined;
358
420
  durationSeconds?: number | undefined;
359
421
  }, {
360
422
  inputTokens: number;
361
423
  outputTokens: number;
362
424
  reasoningTokens?: number | undefined;
425
+ cachedInputTokens?: number | undefined;
363
426
  estimatedCost?: number | undefined;
427
+ reportedCost?: number | undefined;
364
428
  durationSeconds?: number | undefined;
365
429
  }>>;
366
430
  } & {
@@ -385,7 +449,9 @@ declare const CompareResultSchema: z.ZodObject<{
385
449
  inputTokens: number;
386
450
  outputTokens: number;
387
451
  reasoningTokens?: number | undefined;
452
+ cachedInputTokens?: number | undefined;
388
453
  estimatedCost?: number | undefined;
454
+ reportedCost?: number | undefined;
389
455
  durationSeconds?: number | undefined;
390
456
  } | undefined;
391
457
  }, {
@@ -399,7 +465,9 @@ declare const CompareResultSchema: z.ZodObject<{
399
465
  inputTokens: number;
400
466
  outputTokens: number;
401
467
  reasoningTokens?: number | undefined;
468
+ cachedInputTokens?: number | undefined;
402
469
  estimatedCost?: number | undefined;
470
+ reportedCost?: number | undefined;
403
471
  durationSeconds?: number | undefined;
404
472
  } | undefined;
405
473
  }>;
@@ -447,19 +515,33 @@ declare const AskResultSchema: z.ZodObject<{
447
515
  outputTokens: z.ZodNumber;
448
516
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
449
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). */
450
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>;
451
529
  durationSeconds: z.ZodOptional<z.ZodNumber>;
452
530
  }, "strip", z.ZodTypeAny, {
453
531
  inputTokens: number;
454
532
  outputTokens: number;
455
533
  reasoningTokens?: number | undefined;
534
+ cachedInputTokens?: number | undefined;
456
535
  estimatedCost?: number | undefined;
536
+ reportedCost?: number | undefined;
457
537
  durationSeconds?: number | undefined;
458
538
  }, {
459
539
  inputTokens: number;
460
540
  outputTokens: number;
461
541
  reasoningTokens?: number | undefined;
542
+ cachedInputTokens?: number | undefined;
462
543
  estimatedCost?: number | undefined;
544
+ reportedCost?: number | undefined;
463
545
  durationSeconds?: number | undefined;
464
546
  }>>;
465
547
  }, "strip", z.ZodTypeAny, {
@@ -474,7 +556,9 @@ declare const AskResultSchema: z.ZodObject<{
474
556
  inputTokens: number;
475
557
  outputTokens: number;
476
558
  reasoningTokens?: number | undefined;
559
+ cachedInputTokens?: number | undefined;
477
560
  estimatedCost?: number | undefined;
561
+ reportedCost?: number | undefined;
478
562
  durationSeconds?: number | undefined;
479
563
  } | undefined;
480
564
  frameReferences?: number[] | null | undefined;
@@ -490,7 +574,9 @@ declare const AskResultSchema: z.ZodObject<{
490
574
  inputTokens: number;
491
575
  outputTokens: number;
492
576
  reasoningTokens?: number | undefined;
577
+ cachedInputTokens?: number | undefined;
493
578
  estimatedCost?: number | undefined;
579
+ reportedCost?: number | undefined;
494
580
  durationSeconds?: number | undefined;
495
581
  } | undefined;
496
582
  frameReferences?: number[] | null | undefined;
@@ -567,6 +653,19 @@ interface VisualAIConfig {
567
653
  debugResponse?: boolean;
568
654
  maxTokens?: number;
569
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;
570
669
  trackUsage?: boolean;
571
670
  }
572
671
  /** Optional instructions for `check()`. */
@@ -1105,4 +1204,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1105
1204
  */
1106
1205
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1107
1206
 
1108
- 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 };