@zapwebp/core 1.1.1 → 1.1.2

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 (45) hide show
  1. package/README.md +79 -51
  2. package/agent.json +180 -0
  3. package/package.json +8 -2
  4. package/src/cache.js +145 -0
  5. package/src/engine/decode.js +60 -0
  6. package/src/engine/encode.js +106 -0
  7. package/src/engine/pipeline.js +116 -0
  8. package/src/engine/transform.js +37 -0
  9. package/src/errors/index.js +34 -0
  10. package/src/formats/avif.js +1 -1
  11. package/src/formats/gif.js +8 -2
  12. package/src/formats/index.js +5 -0
  13. package/src/formats/jpeg.js +14 -3
  14. package/src/formats/png.js +1 -1
  15. package/src/formats/svg.js +76 -14
  16. package/src/formats/tiff.js +8 -2
  17. package/src/formats/webp.js +1 -1
  18. package/src/index.d.ts +286 -9
  19. package/src/index.js +951 -80
  20. package/src/journal/index.js +73 -0
  21. package/src/metadata/c2pa.js +3 -10
  22. package/src/metadata/chunk-stripper.js +235 -0
  23. package/src/metadata/exif.js +3 -11
  24. package/src/metadata/icc.js +3 -10
  25. package/src/metadata/png-text.js +3 -10
  26. package/src/metadata/registry.js +25 -2
  27. package/src/metadata/xmp.js +3 -16
  28. package/src/parallel.js +134 -0
  29. package/src/policy.js +95 -6
  30. package/src/registry/compression.js +84 -0
  31. package/src/registry/formats.js +30 -0
  32. package/src/registry/metadata.js +28 -0
  33. package/src/registry/transforms.js +76 -0
  34. package/src/report.js +404 -0
  35. package/src/safety/path.js +52 -0
  36. package/src/safety/runtime.js +66 -0
  37. package/src/safety/ssrf.js +9 -0
  38. package/src/safety/svg.js +66 -0
  39. package/src/signals.js +683 -0
  40. package/src/smart.js +351 -0
  41. package/src/team-policy.js +319 -0
  42. package/src/testing.d.ts +18 -0
  43. package/src/testing.js +114 -0
  44. package/src/tools.js +240 -0
  45. package/src/types.ts +68 -0
package/src/index.d.ts CHANGED
@@ -1,13 +1,60 @@
1
- import type { ConversionPolicy } from '@zapwebp/shared';
1
+ import type { ConversionPolicy, ZapwebpError } from '@zapwebp/shared';
2
+ export { ZapwebpError };
3
+
4
+ export interface McpToolDefinition {
5
+ name: string;
6
+ description: string;
7
+ inputSchema: Record<string, any>;
8
+ }
9
+
10
+ export function listTools(): McpToolDefinition[];
11
+ export function getAgentManifest(): Record<string, any>;
12
+ export function createMockSvg(options?: { width?: number; height?: number; transparent?: boolean; fill?: string; withMetadata?: boolean }): Buffer;
13
+ export function createMockImage(options?: { format?: 'svg' | 'png' | 'webp' | 'jpeg' | 'avif'; width?: number; height?: number; transparent?: boolean; withMetadata?: boolean }): Promise<Buffer>;
14
+
15
+ export interface CacheStats {
16
+ size: number;
17
+ totalBytes: number;
18
+ hits: number;
19
+ misses: number;
20
+ hitRate: number;
21
+ }
22
+
23
+ export class ConversionCache {
24
+ constructor(options?: { maxEntries?: number; maxBytes?: number });
25
+ get(key: string): any;
26
+ set(key: string, result: any): void;
27
+ clear(): void;
28
+ stats(): CacheStats;
29
+ }
30
+
31
+ export const defaultCache: ConversionCache;
32
+ export function computeCacheKey(input: Buffer | Uint8Array, options?: object, engineVersion?: string): string;
33
+
34
+ export class ConversionPool {
35
+ constructor(options?: { concurrency?: number });
36
+ processBatch(inputs: any[], options: any, convertFn: Function): Promise<any[]>;
37
+ }
38
+
39
+ export const defaultPool: ConversionPool;
40
+ export function parallelMap<T, R>(items: T[], concurrency: number, workerFn: (item: T, index: number) => Promise<R>): Promise<R[]>;
41
+
42
+ export const testing: {
43
+ createMockSvg: typeof createMockSvg;
44
+ createMockImage: typeof createMockImage;
45
+ };
2
46
 
3
47
  export type InputFormat = 'svg' | 'png' | 'jpeg' | 'webp' | 'avif' | 'gif' | 'tiff';
4
48
  export type OutputFormat = 'webp' | 'png' | 'jpeg' | 'avif';
5
49
  export type FitMode = 'contain' | 'cover' | 'fill' | 'inside' | 'outside';
6
50
 
7
51
  export interface RawImage {
8
- data: Uint8ClampedArray;
52
+ data: Uint8ClampedArray | Uint8Array;
9
53
  width: number;
10
54
  height: number;
55
+ channels?: 4;
56
+ hasAlpha?: boolean;
57
+ format?: string;
11
58
  }
12
59
 
13
60
  export interface TransformStep {
@@ -17,8 +64,27 @@ export interface TransformStep {
17
64
  getMetadata?: () => Record<string, any>;
18
65
  }
19
66
 
67
+ export interface FormatHandler {
68
+ name: string;
69
+ mimeTypes: readonly string[];
70
+ extensions: readonly string[];
71
+ supportsAlpha: boolean;
72
+ isInput?: boolean;
73
+ isOutput?: boolean;
74
+ detect(bytes: Uint8Array | Buffer): boolean;
75
+ decode(bytes: Uint8Array | Buffer, options?: any): Promise<RawImage>;
76
+ encode(image: RawImage, options?: any): Promise<Uint8Array | Buffer>;
77
+ }
78
+
79
+ export interface MetadataHandler {
80
+ name: string;
81
+ inspect(bytes: Uint8Array | Buffer): Promise<any[]>;
82
+ strip(bytes: Uint8Array | Buffer, options?: any): Promise<Uint8Array | Buffer>;
83
+ }
84
+
20
85
  export interface ConvertOptions {
21
- to?: OutputFormat;
86
+ to?: OutputFormat | string;
87
+ format?: OutputFormat | string;
22
88
  width?: number;
23
89
  height?: number;
24
90
  fit?: FitMode;
@@ -26,14 +92,43 @@ export interface ConvertOptions {
26
92
  lossless?: boolean;
27
93
  effort?: number;
28
94
  background?: string;
95
+ defaultBackground?: string;
29
96
  svgBackground?: string;
30
97
  stripMetadata?: boolean;
31
98
  clean?: boolean;
32
99
  verify?: boolean;
33
100
  assertAlpha?: boolean;
34
101
  report?: boolean;
102
+ allowUnsafe?: boolean;
103
+ maxBytes?: number;
104
+ maxInputBytes?: number;
105
+ maxOutputBytes?: number;
106
+ minInputBytes?: number;
107
+ minOutputBytes?: number;
108
+ sameFormat?: 'passthrough' | 'reencode' | 'reject';
109
+ sizeMode?: 'strict' | 'compress' | 'flexible';
110
+ targetBytes?: number | string;
111
+ minQuality?: number;
112
+ allowDownscale?: boolean;
113
+ downscaleStep?: number;
114
+ maxDownscaleAttempts?: number;
115
+ compressor?: any;
35
116
  transforms?: TransformStep[];
36
117
  policy?: Partial<ConversionPolicy>;
118
+ keepOriginal?: boolean;
119
+ cleanupDelay?: 'immediate' | 'session' | 'manual';
120
+ inputPath?: string;
121
+ backupPath?: string;
122
+ originalDeleted?: boolean;
123
+ customMetadata?: Record<string, string | number | boolean>;
124
+ }
125
+
126
+ export interface LifecycleMetadata {
127
+ keepOriginal: boolean;
128
+ originalPath?: string;
129
+ originalDeleted: boolean;
130
+ backupPath?: string;
131
+ cleanupDelay: 'immediate' | 'session' | 'manual';
37
132
  }
38
133
 
39
134
  export interface CleanCertificate {
@@ -45,6 +140,18 @@ export interface CleanCertificate {
45
140
  tool: string;
46
141
  }
47
142
 
143
+ export interface SourceQuality {
144
+ estimated: 'high' | 'medium' | 'low';
145
+ reason: string;
146
+ }
147
+
148
+ export interface SizeImpact {
149
+ lossyEstimate: number;
150
+ losslessActual: number;
151
+ ratio: number;
152
+ note: string;
153
+ }
154
+
48
155
  export interface ConvertResult {
49
156
  data: Buffer;
50
157
  format: OutputFormat;
@@ -54,10 +161,31 @@ export interface ConvertResult {
54
161
  alphaPreserved: boolean;
55
162
  alphaVerified: boolean;
56
163
  clean: boolean;
164
+ lossless?: boolean;
165
+ losslessVerified?: boolean;
166
+ sourceQuality?: SourceQuality;
167
+ sizeImpact?: SizeImpact;
57
168
  removedMetadata: string[];
58
169
  certificate?: CleanCertificate;
59
170
  transforms?: Array<Record<string, any>>;
60
171
  policy?: Record<string, any>;
172
+ lifecycle?: LifecycleMetadata;
173
+ targetLockEnforced?: boolean;
174
+ targetLockBypassed?: boolean;
175
+ passedThrough?: boolean;
176
+ quality?: number;
177
+ warnings?: string[];
178
+ ingestion?: {
179
+ stage: 'passthrough' | 'converted';
180
+ action: string;
181
+ detectedFormat: string;
182
+ targetFormat: string;
183
+ sizeMode: 'strict' | 'compress' | 'flexible';
184
+ inputBytes: number;
185
+ outputBytes: number;
186
+ iterations?: number;
187
+ reason?: string;
188
+ };
61
189
  }
62
190
 
63
191
  export interface MetadataReport {
@@ -70,15 +198,47 @@ export interface MetadataReport {
70
198
  summary: string[];
71
199
  }
72
200
 
73
- export interface ImageInspection {
74
- format: InputFormat;
201
+ export interface ContentSignals {
202
+ edgeDensity: number;
203
+ colorCount: number;
204
+ sharpness: number;
205
+ luminanceMean: number;
206
+ luminanceVariance: number;
207
+ transparencyCoverage: number;
208
+ estimatedType: 'photo' | 'icon' | 'screenshot' | 'logo' | 'diagram' | 'text';
209
+ estimatedTypeConfidence: number;
210
+ }
211
+
212
+ export interface PaletteInfo {
213
+ dominant: string;
214
+ colors: Array<{ hex: string; percentage: number }>;
215
+ }
216
+
217
+ export type UseCase = 'icon' | 'photo' | 'hero' | 'thumbnail' | 'logo' | 'banner' | 'general';
218
+
219
+ export interface Suggestion {
220
+ to: OutputFormat | string;
221
+ quality: number;
222
+ lossless: boolean;
223
+ reason: string;
224
+ expectedBytes: number;
225
+ expectedSavings: number;
226
+ }
227
+
228
+ export interface InspectResult {
229
+ format: InputFormat | string;
75
230
  width?: number;
76
231
  height?: number;
77
232
  hasAlpha: boolean;
78
233
  bytes: number;
79
- metadata?: MetadataReport;
234
+ metadata?: MetadataReport & { custom?: Record<string, any> };
235
+ content?: ContentSignals;
236
+ palette?: PaletteInfo;
237
+ suggestions?: Suggestion[];
80
238
  }
81
239
 
240
+ export type ImageInspection = InspectResult;
241
+
82
242
  export interface AuditReport {
83
243
  safe: boolean;
84
244
  issues: string[];
@@ -92,17 +252,37 @@ export interface BlackBackgroundExplanation {
92
252
  zapSolution: string;
93
253
  }
94
254
 
255
+ // ==========================================
256
+ // Seven Frozen Canonical Core Functions
257
+ // ==========================================
258
+ export function convert(input: Buffer | Uint8Array | string, options?: ConvertOptions): Promise<Buffer & ConvertResult>;
259
+ export function inspect(input: Buffer | Uint8Array | string): Promise<InspectResult>;
260
+ export function registerFormat(handler: FormatHandler): void;
261
+ export function registerMetadataHandler(handler: MetadataHandler): void;
262
+ export function registerTransform(transform: TransformStep): void;
263
+ export function registerCompressor(compressor: any): void;
264
+ export function getCompressor(name?: string): any;
265
+ export function getCompressors(): any[];
266
+ export function getVersion(): string;
267
+ export function getFormats(): string[];
268
+ export function suggest(info: InspectResult, useCase?: UseCase): Suggestion[];
269
+
270
+ // ==========================================
271
+ // Compatibility and Auxiliary Functions
272
+ // ==========================================
95
273
  export function detectFormat(input: Buffer | Uint8Array | string): InputFormat;
96
274
  export function detectMetadata(input: Buffer | Uint8Array | string): MetadataReport;
275
+ export function cleanBytes(input: Buffer | Uint8Array, options?: object): Promise<{ output: Buffer; removed: Array<{ type: string; key: string; value: string }>; kept: Array<{ type: string; key: string; value: string }> }>;
276
+ export function cleanMetadata(input: Buffer | Uint8Array, options?: object): Promise<Buffer>;
97
277
  export function generateCleanCertificate(output: Buffer | Uint8Array): CleanCertificate;
98
278
  export function verifyAlpha(input: Buffer | Uint8Array | string): Promise<{ hasAlpha: boolean; alphaPreserved: boolean; cornerAlpha: number[] }>;
99
279
  export function auditConversionCommand(command: string): AuditReport;
100
280
  export function explainBlackBackground(context?: object): BlackBackgroundExplanation;
101
281
  export function validateSvg(input: Buffer | Uint8Array | string): string;
282
+ export function validateImageBytes(input: Buffer | Uint8Array): void;
102
283
  export function checkSvgSafety(input: Buffer | Uint8Array | string, options?: object): { safe: boolean; reason?: string; detail?: string };
103
284
  export function inspectImage(input: Buffer | Uint8Array | string): Promise<ImageInspection>;
104
285
  export function convertImage(input: Buffer | Uint8Array | string, options?: ConvertOptions): Promise<ConvertResult>;
105
- export function convert(input: Buffer | Uint8Array | string, options?: ConvertOptions): Promise<Buffer & ConvertResult>;
106
286
  export function convertSvgToWebp(input: Buffer | Uint8Array | string, options?: ConvertOptions): Promise<ConvertResult>;
107
287
  export function decodeToRgba(input: Buffer | Uint8Array | string, format?: InputFormat): Promise<RawImage>;
108
288
  export function encodeFromRgba(image: RawImage, options?: ConvertOptions): Promise<Buffer>;
@@ -112,11 +292,108 @@ export function scaleSuffix(scale: number): string;
112
292
  export function outputName(inputPath: string, format?: OutputFormat, scale?: number): string;
113
293
  export function generateSrcset(baseFile: string, scales?: number[], format?: OutputFormat, alt?: string): string;
114
294
  export function resolvePolicy(customPolicy?: Partial<ConversionPolicy> | null): ConversionPolicy;
115
- export function checkPolicyInput(inputBytes: number, format: InputFormat, policy: ConversionPolicy): void;
116
- export function evaluateQuality(format: OutputFormat, inputFormat: InputFormat, policy: ConversionPolicy): { quality: number; lossless: boolean; mode: string };
295
+ export function checkPolicyInput(params: {
296
+ policy: ConversionPolicy;
297
+ data: Buffer;
298
+ detectedFormat: string;
299
+ }): void;
300
+ export function evaluateQuality(params: {
301
+ policy: ConversionPolicy;
302
+ inputFormat: string;
303
+ inputBytes?: number;
304
+ hasAlpha?: boolean;
305
+ targetFormat?: string;
306
+ }): {
307
+ quality: number;
308
+ lossless: boolean;
309
+ mode: string;
310
+ targetQuality: number;
311
+ };
312
+ export function getTransforms(): TransformStep[];
313
+ export function parallelMap<T, R>(
314
+ items: T[],
315
+ concurrency?: number | ((item: T, index: number) => Promise<R>),
316
+ workerFn?: (item: T, index: number) => Promise<R>,
317
+ options?: { signal?: AbortSignal }
318
+ ): Promise<R[]>;
117
319
 
118
320
  export * from './formats/index';
119
321
 
322
+ export interface PerformanceReport {
323
+ period: string;
324
+ periodStart: string | null;
325
+ periodEnd: string | null;
326
+ totalFiles: number;
327
+ originalBytes: number;
328
+ originalFormatted: string;
329
+ optimizedBytes: number;
330
+ optimizedFormatted: string;
331
+ savedBytes: number;
332
+ savedFormatted: string;
333
+ savedPercentage: number;
334
+ avgLatencyMs: number;
335
+ topSavings: Array<{
336
+ fileName: string;
337
+ path: string;
338
+ inputPath: string;
339
+ originalBytes: number;
340
+ optimizedBytes: number;
341
+ savedBytes: number;
342
+ savedPercent: number;
343
+ format: string;
344
+ durationMs: number;
345
+ timestamp: string;
346
+ }>;
347
+ byFormat: Array<{
348
+ format: string;
349
+ count: number;
350
+ savedBytes: number;
351
+ originalBytes: number;
352
+ optimizedBytes: number;
353
+ savedFormatted: string;
354
+ }>;
355
+ bySource: Array<{
356
+ source: string;
357
+ count: number;
358
+ savedBytes: number;
359
+ savedFormatted: string;
360
+ }>;
361
+ carbon: {
362
+ gbSaved: number;
363
+ kwh: number;
364
+ wh: number;
365
+ co2Kg: number;
366
+ };
367
+ items: Array<any>;
368
+ }
369
+
370
+ export function computePerformanceReport(transactions?: any[], options?: { since?: string | number | Date; path?: string; topN?: number }): PerformanceReport;
371
+ export function formatPerformanceReport(report: PerformanceReport, format?: 'table' | 'json' | 'csv' | 'markdown'): string;
372
+
373
+ export interface SmartRecommendation {
374
+ detectedType: string;
375
+ signals: Record<string, any>;
376
+ recommendation: {
377
+ format: string;
378
+ quality: number;
379
+ lossless: boolean;
380
+ fallbackFormat: string | null;
381
+ reason: string;
382
+ explanation: string;
383
+ };
384
+ }
385
+
386
+ export function analyzeSmart(buffer: Buffer | Uint8Array, meta: Record<string, any>, getSharp: () => any): Promise<SmartRecommendation>;
387
+ export function classifyContentType(signals: Record<string, any>): string;
388
+ export function extractSmartSignals(rawData: Buffer | Uint8Array, width: number, height: number, meta?: Record<string, any>): Record<string, any>;
389
+ export const RECOMMENDATION_PROFILES: Record<string, any>;
390
+
391
+ export const DEFAULT_TEAM_POLICY_TEMPLATE: Record<string, any>;
392
+ export function validateTeamPolicy(policy: any): { valid: boolean; errors: string[] };
393
+ export function evaluateFilePolicy(policyConfig: any, fileItem: { path: string; format?: string; size?: number }, conversionOptions?: Record<string, any>, context?: Record<string, any>): { allowed: boolean; violations: string[]; exceptionApplied?: any };
394
+ export function checkExceptionsStatus(policyConfig: any): { active: any[]; expired: any[] };
395
+ export function formatPolicyStatus(policyConfig: any): string;
396
+
120
397
  export const MAX_WIDTH: number;
121
398
  export const INPUT_FORMATS: readonly InputFormat[];
122
399
  export const OUTPUT_FORMATS: readonly OutputFormat[];