@crabcrop/mcp 0.1.0 → 0.9.11

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.
@@ -16,9 +16,12 @@ export declare function sign(secret: string, remainder: string): string;
16
16
  */
17
17
  export declare function purgeSignature(secret: string, target: string): string;
18
18
  /**
19
- * The purge-group signature for a cache group: a purge
20
- * signature over the literal string `purge-group/<group>`,
21
- * which appears nowhere in the request URL. The helper
19
+ * The purge-group signature for a cache group: HMAC-SHA256
20
+ * of the group name under a subkey derived from the secret
21
+ * (the raw HMAC of the secret over the label
22
+ * `crabcrop/purge-group-key`), its own domain beside the
23
+ * purge subkey, so a per-target purge signature can never
24
+ * be transplanted to the purge-group endpoint. The helper
22
25
  * exists so nobody has to know the signed string. This is
23
26
  * the signature segment for
24
27
  * `POST /purge-group/<signature>/<group>`.
@@ -31,8 +34,17 @@ export declare function purgeGroupSignature(secret: string, group: string): stri
31
34
  * so neither an image signature nor a purge signature can
32
35
  * ever be replayed as an upload signature. This is the
33
36
  * signature segment for `PUT /upload/<signature>/<name>`.
37
+ *
38
+ * With `expires` (unix seconds), the signature covers
39
+ * `exp:<expires>/<name>` instead, and the request path is
40
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
41
+ * expiry sits inside the signed string, so it can neither
42
+ * be stripped nor extended, and the server refuses the
43
+ * upload once that second is reached. Delegated upload
44
+ * tokens should always use the expiring form; without it
45
+ * a token replays until the secret rotates.
34
46
  */
35
- export declare function uploadSignature(secret: string, name: string): string;
47
+ export declare function uploadSignature(secret: string, name: string, expires?: number): string;
36
48
  export interface BuildOptions {
37
49
  /** Unix-seconds expiry, emitted as a leading `exp:` segment. */
38
50
  expires?: number;
@@ -51,6 +63,71 @@ export declare function isValidKeyId(id: string): boolean;
51
63
  * followed by the hex tag `sign` computes.
52
64
  */
53
65
  export declare function signWithKeyId(secret: string, keyId: string, remainder: string): string;
66
+ /**
67
+ * The largest remainder {@link seal} will encrypt, in bytes
68
+ * (issue #255). A recipe longer than this belongs in a
69
+ * preset; the cap also bounds the token a server must
70
+ * decode.
71
+ */
72
+ export declare const MAX_SEALED_REMAINDER = 2048;
73
+ /**
74
+ * Seal a remainder into a token segment with a
75
+ * caller-supplied nonce: `s1.<base64url(nonce ||
76
+ * ciphertext || tag)>`, AES-256-GCM under the derived seal
77
+ * subkey with the fixed associated data `crabcrop/sealed/1`.
78
+ *
79
+ * DANGER: a nonce must never repeat under one secret.
80
+ * Reusing a nonce with AES-GCM destroys the construction's
81
+ * confidentiality and integrity guarantees. This function
82
+ * is the deterministic seam the spec's test vectors use;
83
+ * production minting calls {@link seal}, which draws a
84
+ * fresh random nonce every time.
85
+ */
86
+ export declare function sealWithNonce(secret: string, remainder: string, nonce: Uint8Array, keyId?: string): string;
87
+ /**
88
+ * Seal a remainder into a token segment (issue #255), with
89
+ * a fresh random 96-bit nonce. The token is the whole
90
+ * signature segment; pass `keyId` to stamp `<key-id>:`
91
+ * in front of it, so servers in a rotation window open it
92
+ * against the named key only.
93
+ */
94
+ export declare function seal(secret: string, remainder: string, keyId?: string): string;
95
+ /**
96
+ * Open a token segment, with or without a `<key-id>:`
97
+ * prefix, under one secret, returning the remainder it
98
+ * seals. The key ID is routing metadata and is not
99
+ * consulted: the question is whether this secret opens the
100
+ * token. Every failure (malformed body, wrong secret,
101
+ * tampered bytes, unknown version) throws the one error,
102
+ * `the token did not open under this secret`: openers must
103
+ * never learn which stage failed.
104
+ */
105
+ export declare function unseal(secret: string, segment: string): string;
106
+ /** Options for {@link buildSealedURL}. */
107
+ export interface SealOptions {
108
+ /** Unix-seconds expiry, sealed inside the token as a leading `exp:` segment. */
109
+ expires?: number;
110
+ /** Key ID to stamp on the token segment (`<key-id>:s1.…`), for rotation. */
111
+ keyId?: string;
112
+ /**
113
+ * The cosmetic friendly name after the token. The server
114
+ * never parses, validates, or authenticates it; one
115
+ * filename-like segment is the dependable shape. Omit it
116
+ * and the URL ends at the token.
117
+ */
118
+ name?: string;
119
+ }
120
+ /**
121
+ * Assemble a sealed crabcrop URL:
122
+ * `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
123
+ * #255). The remainder is assembled exactly as
124
+ * {@link buildURL} assembles it (expiry segment,
125
+ * operations, source) and then sealed whole, pre-expansion,
126
+ * so the sealed and plain forms of one render are one cache
127
+ * entry and one purge target on the server. A secret is
128
+ * required: there is no `unsafe` spelling of a token.
129
+ */
130
+ export declare function buildSealedURL(base: string, secret: string, operations: string, source: string, options?: SealOptions): string;
54
131
  /**
55
132
  * Assemble a signed (or `unsafe`) crabcrop URL. `operations`
56
133
  * is the operation string verbatim (several `/`-separated
@@ -69,7 +146,7 @@ export { explainUrl } from "./explain.ts";
69
146
  export { FILTER_DESCRIPTIONS } from "./explain.ts";
70
147
  export type { ExplainedSegment, Explanation, SegmentKind, SignatureKind } from "./explain.ts";
71
148
  export { filter, joinOps, ops } from "./operations.ts";
72
- export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, } from "./operations.ts";
149
+ export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, StudioMode, StudioOptions, StudioShadow, } from "./operations.ts";
73
150
  /**
74
151
  * Verify a URL's signature locally. Returns true or false, or
75
152
  * null when the URL is unsigned or malformed.
@@ -2,7 +2,7 @@
2
2
  * Build and sign crabcrop URLs, per `spec/url-signing.md` in
3
3
  * the crabcrop repository. Standard library only.
4
4
  */
5
- import { createHmac, timingSafeEqual } from "node:crypto";
5
+ import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
6
6
  /**
7
7
  * Compute the signature segment for a remainder: the lowercase
8
8
  * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
@@ -26,15 +26,19 @@ export function purgeSignature(secret, target) {
26
26
  return createHmac("sha256", subkey).update(target, "utf8").digest("hex");
27
27
  }
28
28
  /**
29
- * The purge-group signature for a cache group: a purge
30
- * signature over the literal string `purge-group/<group>`,
31
- * which appears nowhere in the request URL. The helper
29
+ * The purge-group signature for a cache group: HMAC-SHA256
30
+ * of the group name under a subkey derived from the secret
31
+ * (the raw HMAC of the secret over the label
32
+ * `crabcrop/purge-group-key`), its own domain beside the
33
+ * purge subkey, so a per-target purge signature can never
34
+ * be transplanted to the purge-group endpoint. The helper
32
35
  * exists so nobody has to know the signed string. This is
33
36
  * the signature segment for
34
37
  * `POST /purge-group/<signature>/<group>`.
35
38
  */
36
39
  export function purgeGroupSignature(secret, group) {
37
- return purgeSignature(secret, `purge-group/${group}`);
40
+ const subkey = Buffer.from(sign(secret, "crabcrop/purge-group-key"), "hex");
41
+ return createHmac("sha256", subkey).update(group, "utf8").digest("hex");
38
42
  }
39
43
  /**
40
44
  * The upload signature for an object name: HMAC-SHA256 of
@@ -43,10 +47,20 @@ export function purgeGroupSignature(secret, group) {
43
47
  * so neither an image signature nor a purge signature can
44
48
  * ever be replayed as an upload signature. This is the
45
49
  * signature segment for `PUT /upload/<signature>/<name>`.
50
+ *
51
+ * With `expires` (unix seconds), the signature covers
52
+ * `exp:<expires>/<name>` instead, and the request path is
53
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
54
+ * expiry sits inside the signed string, so it can neither
55
+ * be stripped nor extended, and the server refuses the
56
+ * upload once that second is reached. Delegated upload
57
+ * tokens should always use the expiring form; without it
58
+ * a token replays until the secret rotates.
46
59
  */
47
- export function uploadSignature(secret, name) {
60
+ export function uploadSignature(secret, name, expires) {
48
61
  const subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
49
- return createHmac("sha256", subkey).update(name, "utf8").digest("hex");
62
+ const signed = expires === undefined ? name : `exp:${expires}/${name}`;
63
+ return createHmac("sha256", subkey).update(signed, "utf8").digest("hex");
50
64
  }
51
65
  /** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
52
66
  export function isValidKeyId(id) {
@@ -62,6 +76,151 @@ export function signWithKeyId(secret, keyId, remainder) {
62
76
  }
63
77
  return `${keyId}:${sign(secret, remainder)}`;
64
78
  }
79
+ /**
80
+ * The largest remainder {@link seal} will encrypt, in bytes
81
+ * (issue #255). A recipe longer than this belongs in a
82
+ * preset; the cap also bounds the token a server must
83
+ * decode.
84
+ */
85
+ export const MAX_SEALED_REMAINDER = 2048;
86
+ /** The AAD every sealed token is bound to. */
87
+ const SEAL_AAD = Buffer.from("crabcrop/sealed/1", "utf8");
88
+ /**
89
+ * The seal subkey: the raw bytes of the HMAC-SHA256 of the
90
+ * label `crabcrop/seal-key` under the secret, its own domain
91
+ * beside purge, purge-group, and upload, so there is no
92
+ * second secret to configure or rotate: each keyring entry
93
+ * yields its own seal subkey, and the rotation window for
94
+ * signatures is the rotation window for tokens.
95
+ */
96
+ function sealKey(secret) {
97
+ return Buffer.from(sign(secret, "crabcrop/seal-key"), "hex");
98
+ }
99
+ /**
100
+ * Seal a remainder into a token segment with a
101
+ * caller-supplied nonce: `s1.<base64url(nonce ||
102
+ * ciphertext || tag)>`, AES-256-GCM under the derived seal
103
+ * subkey with the fixed associated data `crabcrop/sealed/1`.
104
+ *
105
+ * DANGER: a nonce must never repeat under one secret.
106
+ * Reusing a nonce with AES-GCM destroys the construction's
107
+ * confidentiality and integrity guarantees. This function
108
+ * is the deterministic seam the spec's test vectors use;
109
+ * production minting calls {@link seal}, which draws a
110
+ * fresh random nonce every time.
111
+ */
112
+ export function sealWithNonce(secret, remainder, nonce, keyId) {
113
+ if (nonce.length !== 12) {
114
+ throw new Error(`sealed token nonce must be 12 bytes, got ${nonce.length}`);
115
+ }
116
+ if (Buffer.byteLength(remainder, "utf8") > MAX_SEALED_REMAINDER) {
117
+ throw new Error(`remainder is over the ${MAX_SEALED_REMAINDER}-byte sealing cap: a recipe that long belongs in a preset`);
118
+ }
119
+ const cipher = createCipheriv("aes-256-gcm", sealKey(secret), Buffer.from(nonce));
120
+ cipher.setAAD(SEAL_AAD);
121
+ const ciphertext = Buffer.concat([cipher.update(remainder, "utf8"), cipher.final()]);
122
+ const body = Buffer.concat([Buffer.from(nonce), ciphertext, cipher.getAuthTag()]);
123
+ const token = `s1.${body.toString("base64url")}`;
124
+ if (keyId === undefined) {
125
+ return token;
126
+ }
127
+ if (!isValidKeyId(keyId)) {
128
+ throw new Error(`invalid key ID ${JSON.stringify(keyId)}: 1 to 32 characters of [A-Za-z0-9_-]`);
129
+ }
130
+ return `${keyId}:${token}`;
131
+ }
132
+ /**
133
+ * Seal a remainder into a token segment (issue #255), with
134
+ * a fresh random 96-bit nonce. The token is the whole
135
+ * signature segment; pass `keyId` to stamp `<key-id>:`
136
+ * in front of it, so servers in a rotation window open it
137
+ * against the named key only.
138
+ */
139
+ export function seal(secret, remainder, keyId) {
140
+ return sealWithNonce(secret, remainder, randomBytes(12), keyId);
141
+ }
142
+ /**
143
+ * Open a token segment, with or without a `<key-id>:`
144
+ * prefix, under one secret, returning the remainder it
145
+ * seals. The key ID is routing metadata and is not
146
+ * consulted: the question is whether this secret opens the
147
+ * token. Every failure (malformed body, wrong secret,
148
+ * tampered bytes, unknown version) throws the one error,
149
+ * `the token did not open under this secret`: openers must
150
+ * never learn which stage failed.
151
+ */
152
+ export function unseal(secret, segment) {
153
+ const openFailed = () => new Error("the token did not open under this secret");
154
+ let token = segment;
155
+ const colon = segment.indexOf(":");
156
+ if (colon >= 0) {
157
+ if (!isValidKeyId(segment.slice(0, colon))) {
158
+ throw openFailed();
159
+ }
160
+ token = segment.slice(colon + 1);
161
+ }
162
+ if (!token.startsWith("s1.")) {
163
+ throw openFailed();
164
+ }
165
+ const body = token.slice(3);
166
+ // Node's base64 decoder is lenient (it skips characters
167
+ // outside the alphabet), so canonicity is checked by
168
+ // re-encoding: anything but the exact minted spelling
169
+ // fails here.
170
+ const raw = Buffer.from(body, "base64url");
171
+ if (raw.length < 12 + 16 || raw.toString("base64url") !== body) {
172
+ throw openFailed();
173
+ }
174
+ const decipher = createDecipheriv("aes-256-gcm", sealKey(secret), raw.subarray(0, 12));
175
+ decipher.setAAD(SEAL_AAD);
176
+ decipher.setAuthTag(raw.subarray(raw.length - 16));
177
+ let plain;
178
+ try {
179
+ plain = Buffer.concat([
180
+ decipher.update(raw.subarray(12, raw.length - 16)),
181
+ decipher.final(),
182
+ ]);
183
+ }
184
+ catch {
185
+ throw openFailed();
186
+ }
187
+ const text = plain.toString("utf8");
188
+ if (!Buffer.from(text, "utf8").equals(plain)) {
189
+ throw openFailed();
190
+ }
191
+ return text;
192
+ }
193
+ /**
194
+ * Assemble a sealed crabcrop URL:
195
+ * `{base}/[<key-id>:]s1.<token>/{friendly-name}` (issue
196
+ * #255). The remainder is assembled exactly as
197
+ * {@link buildURL} assembles it (expiry segment,
198
+ * operations, source) and then sealed whole, pre-expansion,
199
+ * so the sealed and plain forms of one render are one cache
200
+ * entry and one purge target on the server. A secret is
201
+ * required: there is no `unsafe` spelling of a token.
202
+ */
203
+ export function buildSealedURL(base, secret, operations, source, options = {}) {
204
+ if (secret === null || secret === undefined) {
205
+ throw new Error("sealing requires a secret: there is no unsafe token");
206
+ }
207
+ if (options.expires !== undefined) {
208
+ assertExpires(options.expires);
209
+ }
210
+ assertUrlText(operations, "operations");
211
+ assertUrlText(source, "source");
212
+ const trimmedBase = base.replace(/\/+$/, "");
213
+ let remainder = "";
214
+ if (options.expires !== undefined) {
215
+ remainder += `exp:${options.expires}/`;
216
+ }
217
+ if (operations) {
218
+ remainder += `${operations}/`;
219
+ }
220
+ remainder += source;
221
+ const segment = seal(secret, remainder, options.keyId);
222
+ return options.name ? `${trimmedBase}/${segment}/${options.name}` : `${trimmedBase}/${segment}`;
223
+ }
65
224
  /**
66
225
  * Fail loudly on inputs that can never produce a verifiable URL
67
226
  * (audit P-4, P-5): the remainder travels as a raw URL path, so
@@ -175,8 +334,14 @@ export function verifyUrlSignature(secret, input) {
175
334
  return matches(secret);
176
335
  }
177
336
  if (signature.keyId !== undefined) {
178
- const candidate = secret[signature.keyId];
179
- return candidate === undefined ? false : matches(candidate);
337
+ // Own properties only: key IDs are attacker-shaped text
338
+ // (`constructor`, `toString`, `__proto__` are all legal
339
+ // IDs), and an inherited lookup would hand a non-string
340
+ // to the HMAC and throw instead of answering false.
341
+ const candidate = Object.hasOwn(secret, signature.keyId)
342
+ ? secret[signature.keyId]
343
+ : undefined;
344
+ return typeof candidate === "string" ? matches(candidate) : false;
180
345
  }
181
346
  return Object.values(secret).some(matches);
182
347
  }
@@ -13,6 +13,21 @@
13
13
  */
14
14
  /** Output formats the `format(...)` filter accepts. */
15
15
  export type ImageFormat = "jpeg" | "jpg" | "png" | "webp" | "jxl" | "avif" | "gif" | "mp4" | "webm";
16
+ /** Formats a per-format quality entry can name (the video formats take no quality). */
17
+ export type PerFormatQualityFormat = "jpeg" | "png" | "webp" | "jxl" | "avif" | "gif";
18
+ /** Per-format encoder options for the `format(...)` filter (issue #319). */
19
+ export interface FormatOptions {
20
+ /** JPEG: progressive (multi-scan) encoding. */
21
+ progressive?: boolean;
22
+ /** JPEG: chroma subsampling, 444, 422, or 420. */
23
+ subsampling?: 444 | 422 | 420;
24
+ /** PNG: Adam7 interlacing. */
25
+ interlace?: boolean;
26
+ /** WebP: libwebp compression method, 0..6. */
27
+ method?: number;
28
+ /** WebP: smart subsampling strength, 0..100. */
29
+ sns?: number;
30
+ }
16
31
  /** Crop alignments; `center` is the bare `crop:WxH` spelling. */
17
32
  export type CropAlign = "center" | "smart" | "face" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
18
33
  /** Text-overlay anchor points. */
@@ -23,6 +38,36 @@ export type BlendMode = "normal" | "multiply" | "screen" | "overlay";
23
38
  export type MaskShape = "circle" | "ellipse";
24
39
  /** Channels the `curve(...)` filter remaps. */
25
40
  export type CurveChannel = "rgb" | "r" | "g" | "b";
41
+ /** Modes the `studio(...)` filter runs. */
42
+ export type StudioMode = "product" | "scene";
43
+ /** Contact shadow strengths for `studio(product, ...)`. */
44
+ export type StudioShadow = "soft" | "strong" | "none";
45
+ /**
46
+ * Named arguments for the `studio(...)` filter. `bg` and
47
+ * `shadow` are product arguments only: the server rejects
48
+ * them under `scene`, so the builder throws for them there.
49
+ */
50
+ export interface StudioOptions {
51
+ /**
52
+ * The product backdrop: `"white"`, `"brand"` (the
53
+ * operator brand color, white when none is configured),
54
+ * `"none"` (the subject keeps its transparency and no
55
+ * shadow is synthesized), or a RRGGBB hex color. Unset
56
+ * means the unnamed default: the brand color when one
57
+ * is configured, else white. Naming `"white"` is not
58
+ * the default: the two can resolve differently, so they
59
+ * spell differently.
60
+ */
61
+ bg?: string;
62
+ /** Contact shadow strength; the default is `"soft"`. */
63
+ shadow?: StudioShadow;
64
+ /**
65
+ * Pad margin in percent, 0..40; the default is 10.
66
+ * Under `scene` it is the margin the reframed subject
67
+ * keeps.
68
+ */
69
+ pad?: number;
70
+ }
26
71
  /**
27
72
  * One side of a size: a pixel count (1..16383), 0 for
28
73
  * proportional, a negative count to flip that axis, or
@@ -41,10 +86,26 @@ export declare const ops: {
41
86
  fitIn(width: Dimension, height: Dimension, adaptive?: boolean): string;
42
87
  /** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
43
88
  crop(width: number, height: number, align?: CropAlign): string;
89
+ /**
90
+ * `crop:300x200:objects(person,car):1.5`; crops to the
91
+ * union of every detection of the named classes, the
92
+ * union box scaled about its center by `scale` (1 is the
93
+ * tight box; the crop stays centered on the union).
94
+ * Needs a detection model configured on the server; when
95
+ * none of the classes is detected the render falls back
96
+ * to the plain center crop of the same size. Duplicate
97
+ * classes (case-insensitive) are spelled once, as the
98
+ * server's canonical form spells them; at most 32
99
+ * distinct classes, and a 33rd throws, since the server
100
+ * rejects it with `invalid_crop`.
101
+ */
102
+ cropObjects(width: number, height: number, classes: string[], scale?: number): string;
44
103
  /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
45
104
  cropRect(left: number, top: number, right: number, bottom: number): string;
46
105
  /** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
47
106
  focal(left: number, top: number, right: number, bottom: number): string;
107
+ /** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
108
+ focalPoint(x: number, y: number, zoom?: number): string;
48
109
  /** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
49
110
  pad(width: number, height: number, fill?: "blur" | string): string;
50
111
  /** `preset:thumb`; expands server-side. */
@@ -77,12 +138,13 @@ export declare const filter: {
77
138
  invert(): string;
78
139
  noUpscale(): string;
79
140
  equalize(): string;
141
+ enhance(): string;
80
142
  removeBg(): string;
81
143
  keepProfile(): string;
82
144
  sepia(): string;
83
145
  blurFaces(): string;
84
146
  pixelateFaces(): string;
85
- /** Gaussian blur by sigma (positive). */
147
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
86
148
  blur(sigma: number): string;
87
149
  /** Unsharp-mask strength (positive). */
88
150
  sharpen(amount: number): string;
@@ -90,6 +152,14 @@ export declare const filter: {
90
152
  brighten(amount: number): string;
91
153
  /** Percent contrast: -100..100 (0 unchanged, -100 flat). */
92
154
  contrast(percent: number): string;
155
+ /** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
156
+ gamma(value: number): string;
157
+ /** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
158
+ exposure(stops: number): string;
159
+ /** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
160
+ highlightsShadows(highlights: number, shadows: number): string;
161
+ /** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
162
+ vibrance(percent: number): string;
93
163
  /** Rotate the hue by integer degrees. */
94
164
  hueRotate(degrees: number): string;
95
165
  /** Saturation factor: 0..255 (0 grayscale, 1 identity). */
@@ -131,13 +201,46 @@ export declare const filter: {
131
201
  rotate(angle: number): string;
132
202
  /** Trim uniform borders; tolerance 0..255, default 10. */
133
203
  trim(tolerance?: number): string;
204
+ /** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
205
+ trimSides(tolerance: number, left: number, top: number, right: number, bottom: number): string;
134
206
  /** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
135
207
  quality(value: number | "auto"): string;
136
- format(format: ImageFormat): string;
208
+ /**
209
+ * Per-format quality in one URL: a map of format to value
210
+ * (1..100 or "auto"), plus an optional fallback for
211
+ * formats with no entry. Resolved by the server after
212
+ * format negotiation; entries spell in canonical
213
+ * (format-name) order with the fallback first.
214
+ */
215
+ qualityPerFormat(entries: Partial<Record<PerFormatQualityFormat, number | "auto">>, fallback?: number | "auto"): string;
216
+ /** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
217
+ palette(colors: number): string;
218
+ /**
219
+ * Output format, with its encoder options (issue #319):
220
+ * `progressive` and `subsampling` (444, 422, or 420) for
221
+ * JPEG, `interlace` for PNG, `method` (0..6) and `sns`
222
+ * (smart subsampling, 0..100) for WebP. An option its
223
+ * format cannot honour throws here, like the server's 400.
224
+ */
225
+ format(format: ImageFormat, options?: FormatOptions): string;
137
226
  /** The background color other operations pad with (RRGGBB). */
138
227
  fill(color: string): string;
139
228
  /** How much a face crop expands around the face: 0..3. */
140
229
  facePad(amount: number): string;
230
+ /**
231
+ * Studio mode: `studio(product)` composites the subject
232
+ * the server's segmentation model finds onto a backdrop
233
+ * with a synthesized contact shadow, scaled and centered
234
+ * to the pad margin; `studio(scene)` keeps the
235
+ * photograph's scene, reframing it on the detected
236
+ * subject and correcting light and color. See
237
+ * {@link StudioOptions} for the named arguments.
238
+ * Arguments spelled at their defaults (shadow `soft`,
239
+ * pad 10) are omitted, matching the server's canonical
240
+ * spelling, so `studio("product", { pad: 10 })` and
241
+ * `studio("product")` are the same string.
242
+ */
243
+ studio(mode: StudioMode, options?: StudioOptions): string;
141
244
  /** AI upscale by the given factor. */
142
245
  upscale(factor: 2 | 4): string;
143
246
  /** Device pixel ratio the sizes are multiplied by. */
@@ -146,7 +249,7 @@ export declare const filter: {
146
249
  maxBytes(bytes: number): string;
147
250
  /** Round the corners: one radius for all, or [tl, tr, br, bl]. */
148
251
  radius(value: number | [number, number, number, number]): string;
149
- /** Paint an opaque border inside the frame (RRGGBB). */
252
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
150
253
  border(width: number, color: string): string;
151
254
  mask(shape: MaskShape): string;
152
255
  duotone(shadow: string, highlight: string): string;
@@ -171,8 +274,12 @@ export declare const filter: {
171
274
  blurClass(name: string): string;
172
275
  /** Pixelate every detected object of the named class. */
173
276
  pixelateClass(name: string): string;
277
+ /** Recolor every detected object of the named class to the given RRGGBB color. */
278
+ recolorClass(name: string, color: string): string;
174
279
  /** Blur the rectangle (x, y, w, h) in pixels. */
175
280
  blurRegion(x: number, y: number, w: number, h: number): string;
176
281
  /** Pixelate the rectangle (x, y, w, h) in pixels. */
177
282
  pixelateRegion(x: number, y: number, w: number, h: number): string;
283
+ /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
284
+ removeRegion(x: number, y: number, w: number, h: number): string;
178
285
  };