@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.
- package/README.md +79 -51
- package/agent.json +180 -0
- package/package.json +8 -2
- package/src/cache.js +145 -0
- package/src/engine/decode.js +60 -0
- package/src/engine/encode.js +106 -0
- package/src/engine/pipeline.js +116 -0
- package/src/engine/transform.js +37 -0
- package/src/errors/index.js +34 -0
- package/src/formats/avif.js +1 -1
- package/src/formats/gif.js +8 -2
- package/src/formats/index.js +5 -0
- package/src/formats/jpeg.js +14 -3
- package/src/formats/png.js +1 -1
- package/src/formats/svg.js +76 -14
- package/src/formats/tiff.js +8 -2
- package/src/formats/webp.js +1 -1
- package/src/index.d.ts +286 -9
- package/src/index.js +951 -80
- package/src/journal/index.js +73 -0
- package/src/metadata/c2pa.js +3 -10
- package/src/metadata/chunk-stripper.js +235 -0
- package/src/metadata/exif.js +3 -11
- package/src/metadata/icc.js +3 -10
- package/src/metadata/png-text.js +3 -10
- package/src/metadata/registry.js +25 -2
- package/src/metadata/xmp.js +3 -16
- package/src/parallel.js +134 -0
- package/src/policy.js +95 -6
- package/src/registry/compression.js +84 -0
- package/src/registry/formats.js +30 -0
- package/src/registry/metadata.js +28 -0
- package/src/registry/transforms.js +76 -0
- package/src/report.js +404 -0
- package/src/safety/path.js +52 -0
- package/src/safety/runtime.js +66 -0
- package/src/safety/ssrf.js +9 -0
- package/src/safety/svg.js +66 -0
- package/src/signals.js +683 -0
- package/src/smart.js +351 -0
- package/src/team-policy.js +319 -0
- package/src/testing.d.ts +18 -0
- package/src/testing.js +114 -0
- package/src/tools.js +240 -0
- 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
|
|
74
|
-
|
|
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(
|
|
116
|
-
|
|
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[];
|