@wervt/core 0.0.3 → 0.0.4
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/dist/image.d.ts +82 -0
- package/dist/image.js +97 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/user.d.ts +2 -0
- package/package.json +1 -1
package/dist/image.d.ts
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
export declare const IMAGE_FORMATS: readonly ['jpg', 'png', 'webp', 'avif', 'gif', 'bmp'];
|
|
2
|
+
export type ImageFormat = (typeof IMAGE_FORMATS)[number];
|
|
3
|
+
/** A named anchor, or a focus point: `x` and `y` from 0 to 1, from the top left. */
|
|
4
|
+
export type ImageGravity = 'center' | 'north' | 'south' | 'east' | 'west' | 'north-east' | 'north-west' | 'south-east' | 'south-west' | 'smart' | {
|
|
5
|
+
x: number;
|
|
6
|
+
y: number;
|
|
7
|
+
};
|
|
8
|
+
export interface ImageOptions {
|
|
9
|
+
/** Pixels; leave one of the two out to keep the aspect ratio. */
|
|
10
|
+
width?: number;
|
|
11
|
+
height?: number;
|
|
12
|
+
/**
|
|
13
|
+
* `fit` keeps the whole image inside width × height (the default), `fill` covers it and cuts
|
|
14
|
+
* off the rest, `force` ignores the aspect ratio.
|
|
15
|
+
*/
|
|
16
|
+
fit?: 'fit' | 'fill' | 'force';
|
|
17
|
+
/** Which part `fill` and `crop` keep. */
|
|
18
|
+
gravity?: ImageGravity;
|
|
19
|
+
/** Lets a small image grow to width × height; off by default. */
|
|
20
|
+
enlarge?: boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Cuts a window out before resizing. Sizes of 1 and above are pixels of the source, below 1 a
|
|
23
|
+
* share of it (`0.5` is half the width).
|
|
24
|
+
*/
|
|
25
|
+
crop?: {
|
|
26
|
+
width: number;
|
|
27
|
+
height: number;
|
|
28
|
+
gravity?: ImageGravity;
|
|
29
|
+
};
|
|
30
|
+
/** Degrees, clockwise, on top of the rotation the image's EXIF data asks for. */
|
|
31
|
+
rotate?: 0 | 90 | 180 | 270;
|
|
32
|
+
/** 1 to 100. */
|
|
33
|
+
quality?: number;
|
|
34
|
+
/** `webp` by default. */
|
|
35
|
+
format?: ImageFormat;
|
|
36
|
+
/** Multiplies width and height, for `srcset`. */
|
|
37
|
+
dpr?: number;
|
|
38
|
+
/** Gaussian blur, as sigma. */
|
|
39
|
+
blur?: number;
|
|
40
|
+
/** Keeps EXIF and other metadata, which is removed by default. */
|
|
41
|
+
keepMetadata?: boolean;
|
|
42
|
+
/** Answers as a download; a string names the file (without extension). */
|
|
43
|
+
download?: boolean | string;
|
|
44
|
+
/** Seconds the URL works. Without it, it works (and is cached) forever. */
|
|
45
|
+
expiresIn?: number;
|
|
46
|
+
/**
|
|
47
|
+
* Other imgproxy processing options, as they appear in its URLs (`['sh:0.7', 'bg:fff']`):
|
|
48
|
+
* https://docs.imgproxy.net/usage/processing
|
|
49
|
+
*/
|
|
50
|
+
options?: string[];
|
|
51
|
+
}
|
|
52
|
+
/** A file in the app's bucket: its key, or an ablage file (`{ group, id }`). */
|
|
53
|
+
export type ImageSource = string | {
|
|
54
|
+
group: string;
|
|
55
|
+
id: string;
|
|
56
|
+
};
|
|
57
|
+
/** imgproxy's processing options for `options`, as URL path segments. */
|
|
58
|
+
export declare function imageProcessingOptions(options: ImageOptions, now?: number): string[];
|
|
59
|
+
/** The key of an ablage file's bytes in the bucket (ablage's S3 layout). */
|
|
60
|
+
export declare function imageSourceKey(source: ImageSource): string;
|
|
61
|
+
/** The path the runtime's image gateway serves, signed with `key`. */
|
|
62
|
+
export declare function signImagePath(key: string, source: ImageSource, options?: ImageOptions): string;
|
|
63
|
+
/**
|
|
64
|
+
* The URL of a resized or converted version of an image in the app's bucket, as a path on the
|
|
65
|
+
* app's own host. Use it wherever the browser loads the image (`<img :src>`, `srcset`, CSS):
|
|
66
|
+
*
|
|
67
|
+
* ```ts
|
|
68
|
+
* imageUrl({ group: 'photos', id }, { width: 800, quality: 80 })
|
|
69
|
+
* imageUrl(file, { width: 400, height: 400, fit: 'fill', gravity: 'smart', format: 'jpg' })
|
|
70
|
+
* ```
|
|
71
|
+
*
|
|
72
|
+
* The URL carries no login of its own: whoever has it can load that version of the image (in a
|
|
73
|
+
* private app, after signing in). Hand out URLs only to users who may see the file, and set
|
|
74
|
+
* `expiresIn` when that can change.
|
|
75
|
+
*/
|
|
76
|
+
export declare function imageUrl(source: ImageSource, options?: ImageOptions): string;
|
|
77
|
+
/**
|
|
78
|
+
* Loads a resized or converted image on the server, e.g. to read its pixels, store the result as
|
|
79
|
+
* a new file or send it to another service. Same options as `imageUrl`. The answer is imgproxy's
|
|
80
|
+
* image, or a JSON `{ error }` with the status when the file is missing or can't be processed.
|
|
81
|
+
*/
|
|
82
|
+
export declare function fetchImage(source: ImageSource, options?: ImageOptions): Promise<Response>;
|
package/dist/image.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { WervtError } from "./errors.js";
|
|
2
|
+
import { appHeaders, runtimeUrl } from "./runtime.js";
|
|
3
|
+
import { createHmac } from "node:crypto";
|
|
4
|
+
// src/image.ts
|
|
5
|
+
const IMAGE_FORMATS = [
|
|
6
|
+
"jpg",
|
|
7
|
+
"png",
|
|
8
|
+
"webp",
|
|
9
|
+
"avif",
|
|
10
|
+
"gif",
|
|
11
|
+
"bmp"
|
|
12
|
+
];
|
|
13
|
+
const GRAVITIES = {
|
|
14
|
+
center: "ce",
|
|
15
|
+
north: "no",
|
|
16
|
+
south: "so",
|
|
17
|
+
east: "ea",
|
|
18
|
+
west: "we",
|
|
19
|
+
"north-east": "noea",
|
|
20
|
+
"north-west": "nowe",
|
|
21
|
+
"south-east": "soea",
|
|
22
|
+
"south-west": "sowe",
|
|
23
|
+
smart: "sm"
|
|
24
|
+
};
|
|
25
|
+
const number = (value) => String(Number(value.toFixed(6)));
|
|
26
|
+
const gravity = (value) => typeof value === "string" ? GRAVITIES[value] : `fp:${number(value.x)}:${number(value.y)}`;
|
|
27
|
+
/** imgproxy's processing options for `options`, as URL path segments. */
|
|
28
|
+
function imageProcessingOptions(options, now = Date.now()) {
|
|
29
|
+
const parts = [];
|
|
30
|
+
if (options.crop) parts.push([
|
|
31
|
+
"c",
|
|
32
|
+
number(options.crop.width),
|
|
33
|
+
number(options.crop.height),
|
|
34
|
+
...options.crop.gravity ? [gravity(options.crop.gravity)] : []
|
|
35
|
+
].join(":"));
|
|
36
|
+
if (options.width || options.height || options.fit) parts.push([
|
|
37
|
+
"rs",
|
|
38
|
+
options.fit ?? "fit",
|
|
39
|
+
Math.round(options.width ?? 0),
|
|
40
|
+
Math.round(options.height ?? 0),
|
|
41
|
+
options.enlarge ? 1 : 0
|
|
42
|
+
].join(":"));
|
|
43
|
+
if (options.gravity) parts.push(`g:${gravity(options.gravity)}`);
|
|
44
|
+
if (options.rotate) parts.push(`rot:${options.rotate}`);
|
|
45
|
+
if (options.dpr) parts.push(`dpr:${number(options.dpr)}`);
|
|
46
|
+
if (options.blur) parts.push(`bl:${number(options.blur)}`);
|
|
47
|
+
if (options.quality) parts.push(`q:${Math.round(options.quality)}`);
|
|
48
|
+
if (options.keepMetadata) parts.push("sm:0");
|
|
49
|
+
if (typeof options.download === "string") {
|
|
50
|
+
const name = options.download.replace(/[^A-Za-z0-9._-]+/g, "_").slice(0, 100);
|
|
51
|
+
if (name) parts.push(`fn:${name}`);
|
|
52
|
+
}
|
|
53
|
+
if (options.download) parts.push("att:1");
|
|
54
|
+
if (options.expiresIn) parts.push(`exp:${Math.floor(now / 1e3) + Math.round(options.expiresIn)}`);
|
|
55
|
+
parts.push(...options.options ?? []);
|
|
56
|
+
return parts;
|
|
57
|
+
}
|
|
58
|
+
/** The key of an ablage file's bytes in the bucket (ablage's S3 layout). */
|
|
59
|
+
function imageSourceKey(source) {
|
|
60
|
+
return typeof source === "string" ? source : `${source.group}/data/${source.id}`;
|
|
61
|
+
}
|
|
62
|
+
/** The path the runtime's image gateway serves, signed with `key`. */
|
|
63
|
+
function signImagePath(key, source, options = {}) {
|
|
64
|
+
const encoded = Buffer.from(imageSourceKey(source), "utf8").toString("base64url");
|
|
65
|
+
const signed = [...imageProcessingOptions(options), `${encoded}.${options.format ?? "webp"}`].join("/");
|
|
66
|
+
return `/_wervt/image/${createHmac("sha256", key).update(signed).digest("base64url")}/${signed}`;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The URL of a resized or converted version of an image in the app's bucket, as a path on the
|
|
70
|
+
* app's own host. Use it wherever the browser loads the image (`<img :src>`, `srcset`, CSS):
|
|
71
|
+
*
|
|
72
|
+
* ```ts
|
|
73
|
+
* imageUrl({ group: 'photos', id }, { width: 800, quality: 80 })
|
|
74
|
+
* imageUrl(file, { width: 400, height: 400, fit: 'fill', gravity: 'smart', format: 'jpg' })
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* The URL carries no login of its own: whoever has it can load that version of the image (in a
|
|
78
|
+
* private app, after signing in). Hand out URLs only to users who may see the file, and set
|
|
79
|
+
* `expiresIn` when that can change.
|
|
80
|
+
*/
|
|
81
|
+
function imageUrl(source, options = {}) {
|
|
82
|
+
const key = process.env.WERVT_IMAGE_KEY;
|
|
83
|
+
if (!key) throw new WervtError(503, "Images need wervt with its image service (locally: docker compose up -d garage imgproxy)");
|
|
84
|
+
return signImagePath(key, source, options);
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Loads a resized or converted image on the server, e.g. to read its pixels, store the result as
|
|
88
|
+
* a new file or send it to another service. Same options as `imageUrl`. The answer is imgproxy's
|
|
89
|
+
* image, or a JSON `{ error }` with the status when the file is missing or can't be processed.
|
|
90
|
+
*/
|
|
91
|
+
async function fetchImage(source, options = {}) {
|
|
92
|
+
const path = imageUrl(source, options);
|
|
93
|
+
const runtime = runtimeUrl();
|
|
94
|
+
if (!runtime) throw new WervtError(503, "fetchImage only works on wervt, not in local dev");
|
|
95
|
+
return fetch(new URL(path, runtime), { headers: appHeaders() });
|
|
96
|
+
}
|
|
97
|
+
export { IMAGE_FORMATS, fetchImage, imageProcessingOptions, imageSourceKey, imageUrl, signImagePath };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { WervtAccess, WervtInvite, appAccess } from "./access.js";
|
|
2
2
|
import { WervtError, errorResponse } from "./errors.js";
|
|
3
3
|
import { WorkloadIdentity, workloadIdentity } from "./identity.js";
|
|
4
|
+
import { IMAGE_FORMATS, ImageFormat, ImageGravity, ImageOptions, ImageSource, fetchImage, imageProcessingOptions, imageSourceKey, imageUrl, signImagePath } from "./image.js";
|
|
4
5
|
import { MailMessage, sendMail } from "./mail.js";
|
|
5
6
|
import { BUNDLE_MANIFEST, BrandManifest, BundleManifest, PreviewManifest, TaskSchedule, TasksManifest } from "./manifest.js";
|
|
6
7
|
import { appHeaders, callRuntime, runtimeUrl } from "./runtime.js";
|
|
7
8
|
import { ShapeRequest, ShapeResponse, ShapeRowOf, parseTimestamp, proxyShape, shapeParser } from "./shape.js";
|
|
8
9
|
import { ACCOUNT_MERGED_TASK, AccountMergedPayload, TASK_HEADER, Task, TaskEvent, TaskResult, createTaskHandler, defineTask, isTaskRequest, taskRunResponse } from "./tasks.js";
|
|
9
10
|
import { AGENT_TOKEN_HEADER, AgentToken, USER_HEADER, USER_PROOF_HEADER, WervtRole, WervtUser, checkRole, getAgentToken, getUser, parseAgentToken, parseWervtUser, requireRole, userFromClaims } from "./user.js";
|
|
10
|
-
export { ACCOUNT_MERGED_TASK, AGENT_TOKEN_HEADER, type AccountMergedPayload, type AgentToken, BUNDLE_MANIFEST, type BrandManifest, type BundleManifest, type MailMessage, type PreviewManifest, type ShapeRequest, type ShapeResponse, type ShapeRowOf, TASK_HEADER, type Task, type TaskEvent, type TaskResult, type TaskSchedule, type TasksManifest, USER_HEADER, USER_PROOF_HEADER, type WervtAccess, WervtError, type WervtInvite, type WervtRole, type WervtUser, type WorkloadIdentity, appAccess, appHeaders, callRuntime, checkRole, createTaskHandler, defineTask, errorResponse, getAgentToken, getUser, isTaskRequest, parseAgentToken, parseTimestamp, parseWervtUser, proxyShape, requireRole, runtimeUrl, sendMail, shapeParser, taskRunResponse, userFromClaims, workloadIdentity };
|
|
11
|
+
export { ACCOUNT_MERGED_TASK, AGENT_TOKEN_HEADER, type AccountMergedPayload, type AgentToken, BUNDLE_MANIFEST, type BrandManifest, type BundleManifest, IMAGE_FORMATS, type ImageFormat, type ImageGravity, type ImageOptions, type ImageSource, type MailMessage, type PreviewManifest, type ShapeRequest, type ShapeResponse, type ShapeRowOf, TASK_HEADER, type Task, type TaskEvent, type TaskResult, type TaskSchedule, type TasksManifest, USER_HEADER, USER_PROOF_HEADER, type WervtAccess, WervtError, type WervtInvite, type WervtRole, type WervtUser, type WorkloadIdentity, appAccess, appHeaders, callRuntime, checkRole, createTaskHandler, defineTask, errorResponse, fetchImage, getAgentToken, getUser, imageProcessingOptions, imageSourceKey, imageUrl, isTaskRequest, parseAgentToken, parseTimestamp, parseWervtUser, proxyShape, requireRole, runtimeUrl, sendMail, shapeParser, signImagePath, taskRunResponse, userFromClaims, workloadIdentity };
|
package/dist/index.js
CHANGED
|
@@ -3,8 +3,9 @@ import { appHeaders, callRuntime, runtimeUrl } from "./runtime.js";
|
|
|
3
3
|
import { AGENT_TOKEN_HEADER, USER_HEADER, USER_PROOF_HEADER, checkRole, getAgentToken, getUser, parseAgentToken, parseWervtUser, requireRole, userFromClaims } from "./user.js";
|
|
4
4
|
import { appAccess } from "./access.js";
|
|
5
5
|
import { workloadIdentity } from "./identity.js";
|
|
6
|
+
import { IMAGE_FORMATS, fetchImage, imageProcessingOptions, imageSourceKey, imageUrl, signImagePath } from "./image.js";
|
|
6
7
|
import { sendMail } from "./mail.js";
|
|
7
8
|
import { BUNDLE_MANIFEST } from "./manifest.js";
|
|
8
9
|
import { parseTimestamp, proxyShape, shapeParser } from "./shape.js";
|
|
9
10
|
import { ACCOUNT_MERGED_TASK, TASK_HEADER, createTaskHandler, defineTask, isTaskRequest, taskRunResponse } from "./tasks.js";
|
|
10
|
-
export { ACCOUNT_MERGED_TASK, AGENT_TOKEN_HEADER, BUNDLE_MANIFEST, TASK_HEADER, USER_HEADER, USER_PROOF_HEADER, WervtError, appAccess, appHeaders, callRuntime, checkRole, createTaskHandler, defineTask, errorResponse, getAgentToken, getUser, isTaskRequest, parseAgentToken, parseTimestamp, parseWervtUser, proxyShape, requireRole, runtimeUrl, sendMail, shapeParser, taskRunResponse, userFromClaims, workloadIdentity };
|
|
11
|
+
export { ACCOUNT_MERGED_TASK, AGENT_TOKEN_HEADER, BUNDLE_MANIFEST, IMAGE_FORMATS, TASK_HEADER, USER_HEADER, USER_PROOF_HEADER, WervtError, appAccess, appHeaders, callRuntime, checkRole, createTaskHandler, defineTask, errorResponse, fetchImage, getAgentToken, getUser, imageProcessingOptions, imageSourceKey, imageUrl, isTaskRequest, parseAgentToken, parseTimestamp, parseWervtUser, proxyShape, requireRole, runtimeUrl, sendMail, shapeParser, signImagePath, taskRunResponse, userFromClaims, workloadIdentity };
|
package/dist/user.d.ts
CHANGED
|
@@ -16,6 +16,8 @@ export interface WervtUser {
|
|
|
16
16
|
accounts?: Record<string, string>;
|
|
17
17
|
/** Missing only for users an app's own `/mcp` tokens stand for. */
|
|
18
18
|
role?: WervtRole;
|
|
19
|
+
/** An admin of the wervt server, whatever their `role` in this app. */
|
|
20
|
+
admin?: boolean;
|
|
19
21
|
}
|
|
20
22
|
/** Parses the `x-wervt-user` header the runtime sets. */
|
|
21
23
|
export declare function parseWervtUser(header: string | null | undefined): WervtUser | undefined;
|
package/package.json
CHANGED