@valentinkolb/filegate 2.2.0 → 2.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Valentin Kolb
+Copyright (c) 2026-Present Valentin Kolb
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -190,6 +190,61 @@ await client.transfer({
 - `ensureUniqueName: true` (default) - Appends `-01`, `-02`, etc. if target exists
 - `ensureUniqueName: false` - Overwrites existing target file
 
+### Thumbnails
+
+Filegate can generate image thumbnails on-the-fly using Sharp. No caching - thumbnails are generated per request (typically 5-20ms).
+
+```typescript
+// Get a 200x200 cover thumbnail (default)
+const result = await client.thumbnail.image({
+  path: "/data/photos/vacation.jpg",
+});
+
+if (result.ok) {
+  const blob = await result.data.blob();
+  // Use as image source
+}
+
+// Customized thumbnail
+const result = await client.thumbnail.image({
+  path: "/data/photos/vacation.jpg",
+  width: 400,
+  height: 300,
+  fit: "contain",      // Fit within bounds, preserve aspect ratio
+  format: "webp",      // Output format
+  quality: 90,         // Higher quality
+});
+
+// Smart cropping with attention detection
+const result = await client.thumbnail.image({
+  path: "/data/photos/portrait.jpg",
+  width: 150,
+  height: 150,
+  fit: "cover",
+  position: "attention",  // Focus on interesting areas
+});
+```
+
+**Options:**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `width` | 200 | Width in pixels (max 2000) |
+| `height` | 200 | Height in pixels (max 2000) |
+| `fit` | `cover` | `cover`, `contain`, `fill`, `inside`, `outside` |
+| `position` | `center` | Crop position: `center`, `top`, `bottom`, `left`, `right`, `entropy`, `attention` |
+| `format` | `webp` | Output: `webp`, `jpeg`, `png`, `avif` |
+| `quality` | 80 | Quality 1-100 |
+
+**Fit modes:**
+- `cover` - Fill the box, crop excess (best for uniform grids)
+- `contain` - Fit within box, preserve aspect ratio (may have letterboxing)
+- `fill` - Stretch to exact size (distorts)
+- `inside` - Like contain, but never upscale
+- `outside` - Like cover, but never downscale
+
+**Supported input formats:** JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG
+
 ### Chunked Uploads
 
 For large files, use chunked uploads. They support:
@@ -383,6 +438,17 @@ await client.glob({
   pattern: "**/*",
   directories: true,
 });
+
+// Generate image thumbnail
+await client.thumbnail.image({
+  path: "/data/photo.jpg",
+  width: 200,
+  height: 200,
+  fit: "cover",
+  position: "center",
+  format: "webp",
+  quality: 80,
+});
 ```
 
 ### Response Format
@@ -462,6 +528,7 @@ All `/files/*` endpoints require `Authorization: Bearer <token>`.
 | GET | `/files/search` | Search with glob pattern. Use `?directories=true` to include folders |
 | POST | `/files/upload/start` | Start or resume chunked upload |
 | POST | `/files/upload/chunk` | Upload a chunk |
+| GET | `/files/thumbnail/image` | Generate image thumbnail on-the-fly |
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/filegate",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,7 @@
     "hono": "^4.11.7",
     "hono-openapi": "^1.2.0",
     "sanitize-filename": "^1.6.3",
+    "sharp": "^0.34.5",
     "zod": "^4.3.6"
   }
 }

package/src/client.ts

@@ -120,6 +120,60 @@ export interface GlobOptions {
   directories?: boolean;
 }
 
+// --- Thumbnail ---
+export type ThumbnailFit = "cover" | "contain" | "fill" | "inside" | "outside";
+export type ThumbnailPosition = "center" | "top" | "bottom" | "left" | "right" | "entropy" | "attention";
+export type ThumbnailFormat = "webp" | "jpeg" | "png" | "avif";
+
+export interface ImageThumbnailOptions {
+  path: string;
+  /** Width in pixels (default: 200, max: 2000) */
+  width?: number;
+  /** Height in pixels (default: 200, max: 2000) */
+  height?: number;
+  /** Scaling mode (default: cover) */
+  fit?: ThumbnailFit;
+  /** Crop position for cover fit (default: center) */
+  position?: ThumbnailPosition;
+  /** Output format (default: webp) */
+  format?: ThumbnailFormat;
+  /** Quality 1-100 (default: 80) */
+  quality?: number;
+}
+
+// ============================================================================
+// Thumbnail Namespace Class
+// ============================================================================
+
+class ThumbnailClient {
+  constructor(
+    private readonly url: string,
+    private readonly hdrs: () => Headers,
+    private readonly _fetch: typeof fetch,
+  ) {}
+
+  async image(opts: ImageThumbnailOptions): Promise<FileProxyResponse<Response>> {
+    const params = new URLSearchParams({ path: opts.path });
+    if (opts.width !== undefined) params.set("width", String(opts.width));
+    if (opts.height !== undefined) params.set("height", String(opts.height));
+    if (opts.fit) params.set("fit", opts.fit);
+    if (opts.position) params.set("position", opts.position);
+    if (opts.format) params.set("format", opts.format);
+    if (opts.quality !== undefined) params.set("quality", String(opts.quality));
+
+    const res = await this._fetch(`${this.url}/files/thumbnail/image?${params}`, {
+      headers: this.hdrs(),
+    });
+
+    if (!res.ok) {
+      const body = (await res.json().catch(() => ({ error: "unknown error" }))) as ApiError;
+      return { ok: false, error: body.error || "unknown error", status: res.status };
+    }
+
+    return { ok: true, data: res };
+  }
+}
+
 // ============================================================================
 // Upload Namespace Class
 // ============================================================================
@@ -204,6 +258,7 @@ export class Filegate {
   private readonly _fetch: typeof fetch;
 
   readonly upload: UploadClient;
+  readonly thumbnail: ThumbnailClient;
 
   constructor(opts: ClientOptions) {
     this.url = opts.url.replace(/\/$/, "");
@@ -217,6 +272,8 @@ export class Filegate {
       this._fetch,
       (res) => this.handleResponse(res),
     );
+
+    this.thumbnail = new ThumbnailClient(this.url, () => this.hdrs(), this._fetch);
   }
 
   private hdrs(): Headers {

package/src/handlers/thumbnail.ts

@@ -0,0 +1,117 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import sharp from "sharp";
+import { validatePath } from "../lib/path";
+import { jsonResponse, requiresAuth } from "../lib/openapi";
+import { v } from "../lib/validator";
+import { ImageThumbnailQuerySchema, ErrorSchema } from "../schemas";
+
+const app = new Hono();
+
+// Supported image MIME types
+const SUPPORTED_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/avif",
+  "image/tiff",
+  "image/gif",
+  "image/svg+xml",
+]);
+
+// Format to MIME type mapping
+const FORMAT_MIME: Record<string, string> = {
+  webp: "image/webp",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  avif: "image/avif",
+};
+
+// GET /thumbnail/image - Generate image thumbnail
+app.get(
+  "/image",
+  describeRoute({
+    tags: ["Thumbnail"],
+    summary: "Generate image thumbnail",
+    description:
+      "Generate a thumbnail from an image file on-the-fly using Sharp. " +
+      "Supports JPEG, PNG, WebP, AVIF, TIFF, GIF, and SVG input formats.",
+    ...requiresAuth,
+    responses: {
+      200: {
+        description: "Thumbnail image",
+        content: {
+          "image/webp": { schema: { type: "string", format: "binary" } },
+          "image/jpeg": { schema: { type: "string", format: "binary" } },
+          "image/png": { schema: { type: "string", format: "binary" } },
+          "image/avif": { schema: { type: "string", format: "binary" } },
+        },
+      },
+      400: jsonResponse(ErrorSchema, "Invalid parameters or not an image"),
+      403: jsonResponse(ErrorSchema, "Forbidden"),
+      404: jsonResponse(ErrorSchema, "Not found"),
+    },
+  }),
+  v("query", ImageThumbnailQuerySchema),
+  async (c) => {
+    const { path, width, height, fit, position, format, quality } = c.req.valid("query");
+
+    // Validate path
+    const result = await validatePath(path);
+    if (!result.ok) return c.json({ error: result.error }, result.status);
+
+    // Check if file exists and is a file
+    const file = Bun.file(result.realPath);
+    if (!(await file.exists())) {
+      return c.json({ error: "file not found" }, 404);
+    }
+
+    // Check MIME type
+    if (!SUPPORTED_IMAGE_TYPES.has(file.type)) {
+      return c.json(
+        { error: `unsupported image type: ${file.type}. Supported: ${[...SUPPORTED_IMAGE_TYPES].join(", ")}` },
+        400,
+      );
+    }
+
+    try {
+      // Read file and process with Sharp
+      const buffer = await file.arrayBuffer();
+
+      let pipeline = sharp(Buffer.from(buffer)).resize(width, height, {
+        fit,
+        position,
+      });
+
+      // Apply format and quality
+      switch (format) {
+        case "webp":
+          pipeline = pipeline.webp({ quality });
+          break;
+        case "jpeg":
+          pipeline = pipeline.jpeg({ quality });
+          break;
+        case "png":
+          pipeline = pipeline.png({ quality });
+          break;
+        case "avif":
+          pipeline = pipeline.avif({ quality });
+          break;
+      }
+
+      const thumbnail = await pipeline.toBuffer();
+
+      return new Response(thumbnail, {
+        headers: {
+          "Content-Type": FORMAT_MIME[format],
+          "Cache-Control": "public, max-age=31536000, immutable",
+        },
+      });
+    } catch (err) {
+      console.error("[Filegate] Thumbnail error:", err);
+      return c.json({ error: "failed to generate thumbnail" }, 500);
+    }
+  },
+);
+
+export default app;

package/src/handlers/upload.ts

@@ -83,6 +83,13 @@ const assembleFile = async (meta: UploadMeta): Promise<string | null> => {
   const chunks = await getUploadedChunks(meta.uploadId);
   if (chunks.length !== meta.totalChunks) return "missing chunks";
 
+  // Verify all expected chunk indices are present (0 to totalChunks-1)
+  const expectedChunks = Array.from({ length: meta.totalChunks }, (_, i) => i);
+  const missingChunks = expectedChunks.filter((i) => !chunks.includes(i));
+  if (missingChunks.length > 0) {
+    return `missing chunk indices: ${missingChunks.join(", ")}`;
+  }
+
   const fullPath = join(meta.path, meta.filename);
   const pathResult = await validatePath(fullPath);
   if (!pathResult.ok) return pathResult.error;

package/src/index.ts

@@ -11,6 +11,7 @@ import { openApiMeta } from "./lib/openapi";
 import filesRoutes from "./handlers/files";
 import searchRoutes from "./handlers/search";
 import uploadRoutes, { cleanupOrphanedChunks } from "./handlers/upload";
+import thumbnailRoutes from "./handlers/thumbnail";
 
 // Dev mode warning
 if (config.isDev) {
@@ -56,7 +57,8 @@ const api = new Hono()
   .use("/*", bearerAuth({ token: config.token }))
   .route("/", filesRoutes)
   .route("/", searchRoutes)
-  .route("/upload", uploadRoutes);
+  .route("/upload", uploadRoutes)
+  .route("/thumbnail", thumbnailRoutes);
 
 app.route("/files", api);
 

package/src/schemas.ts

@@ -260,6 +260,63 @@ export const UploadChunkHeadersSchema = z
   })
   .describe("Headers for uploading a chunk");
 
+// ============================================================================
+// Thumbnail Schemas
+// ============================================================================
+
+export const ThumbnailFitSchema = z
+  .enum(["cover", "contain", "fill", "inside", "outside"])
+  .describe(
+    "Scaling mode: cover (crop to fill), contain (fit within), fill (stretch), inside (fit, never upscale), outside (cover, never downscale)",
+  );
+
+export const ThumbnailPositionSchema = z
+  .enum(["center", "top", "bottom", "left", "right", "entropy", "attention"])
+  .describe("Crop position for 'cover' fit: cardinal directions, or 'entropy'/'attention' for smart cropping");
+
+export const ThumbnailFormatSchema = z.enum(["webp", "jpeg", "png", "avif"]).describe("Output image format");
+
+export const ImageThumbnailQuerySchema = z
+  .object({
+    path: z.string().min(1).describe("Absolute path to the image file"),
+    width: z
+      .string()
+      .optional()
+      .transform((v) => (v ? parseInt(v, 10) : 200))
+      .refine((v) => v >= 1 && v <= 2000, "width must be between 1 and 2000")
+      .describe("Thumbnail width in pixels (default: 200, max: 2000)"),
+    height: z
+      .string()
+      .optional()
+      .transform((v) => (v ? parseInt(v, 10) : 200))
+      .refine((v) => v >= 1 && v <= 2000, "height must be between 1 and 2000")
+      .describe("Thumbnail height in pixels (default: 200, max: 2000)"),
+    fit: z
+      .string()
+      .optional()
+      .transform((v) => (v as z.infer<typeof ThumbnailFitSchema>) || "cover")
+      .describe("Scaling mode (default: cover)"),
+    position: z
+      .string()
+      .optional()
+      .transform((v) => (v as z.infer<typeof ThumbnailPositionSchema>) || "center")
+      .describe("Crop position for cover fit (default: center)"),
+    format: z
+      .string()
+      .optional()
+      .transform((v) => (v as z.infer<typeof ThumbnailFormatSchema>) || "webp")
+      .describe("Output format (default: webp)"),
+    quality: z
+      .string()
+      .optional()
+      .transform((v) => (v ? parseInt(v, 10) : 80))
+      .refine((v) => v >= 1 && v <= 100, "quality must be between 1 and 100")
+      .describe("Output quality 1-100 (default: 80)"),
+  })
+  .describe("Query parameters for image thumbnail generation");
+
+export type ImageThumbnailQuery = z.infer<typeof ImageThumbnailQuerySchema>;
+
 // ============================================================================
 // Types
 // ============================================================================