@howells/stow-next 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# @howells/stow-next
+
+Next.js integration for [Stow](https://stow.sh) file storage. Includes route handler helpers and an image loader for `next/image`.
+
+## Installation
+
+```bash
+npm install @howells/stow-next @howells/stow-server
+# or
+pnpm add @howells/stow-next @howells/stow-server
+# or
+yarn add @howells/stow-next @howells/stow-server
+```
+
+## Quick Start
+
+### 1. Create an upload route
+
+```typescript
+// app/api/upload/route.ts
+import { createUploadHandler } from "@howells/stow-next";
+import { StowServer } from "@howells/stow-server";
+
+const stow = new StowServer(process.env.STOW_API_KEY!);
+
+export const POST = createUploadHandler({
+  stow,
+  maxSize: 10 * 1024 * 1024, // 10MB
+  allowedTypes: ["image/*", "application/pdf"],
+});
+```
+
+### 2. Use with @howells/stow-react
+
+```tsx
+// app/page.tsx
+import { UploadDropzone } from "@howells/stow-react";
+
+export default function Page() {
+  return (
+    <UploadDropzone
+      endpoint="/api/upload"
+      onUploadComplete={(files) => console.log(files)}
+    />
+  );
+}
+```
+
+## Route Handler
+
+### `createUploadHandler(config)`
+
+Creates a Next.js route handler for file uploads.
+
+```typescript
+import { createUploadHandler } from "@howells/stow-next";
+
+export const POST = createUploadHandler({
+  // Required: Stow server instance
+  stow: new StowServer(process.env.STOW_API_KEY!),
+
+  // Optional: File restrictions
+  maxSize: 10 * 1024 * 1024,           // Max file size in bytes
+  allowedTypes: ["image/*", ".pdf"],    // Allowed MIME types or extensions
+  route: "uploads",                     // Default route/folder
+
+  // Optional: Custom validation
+  validate: async (file) => {
+    if (file.name.includes("secret")) {
+      return "Filename not allowed";
+    }
+    return true;
+  },
+
+  // Optional: Lifecycle hooks
+  onUploadBegin: async (file) => {
+    console.log(`Starting upload: ${file.name}`);
+  },
+  onUploadComplete: async (result) => {
+    console.log(`Uploaded: ${result.url}`);
+    // Save to database, etc.
+  },
+});
+```
+
+## Image Loader
+
+Use Stow's image transformation with Next.js Image component.
+
+### Setup
+
+```javascript
+// next.config.js
+module.exports = {
+  images: {
+    loader: "custom",
+    loaderFile: "./lib/stow-loader.ts",
+  },
+};
+```
+
+```typescript
+// lib/stow-loader.ts
+import { stowLoader } from "@howells/stow-next/image-loader";
+export default stowLoader;
+```
+
+### Usage
+
+```tsx
+import Image from "next/image";
+
+function MyComponent() {
+  return (
+    <Image
+      src="https://stow.sh/files/bucket-id/image.jpg"
+      alt="My image"
+      width={800}
+      height={600}
+      quality={80}
+    />
+  );
+}
+```
+
+### Custom Loader Config
+
+```typescript
+// lib/stow-loader.ts
+import { createStowLoader } from "@howells/stow-next/image-loader";
+
+export default createStowLoader({
+  baseUrl: "https://stow.sh",
+  defaultQuality: 80,
+  defaultFormat: "webp",
+});
+```
+
+## TypeScript
+
+```typescript
+import type {
+  UploadHandlerConfig,
+  StowLoaderConfig,
+} from "@howells/stow-next";
+```
+
+## Complete Example
+
+```typescript
+// app/api/upload/route.ts
+import { createUploadHandler } from "@howells/stow-next";
+import { StowServer } from "@howells/stow-server";
+import { db } from "@/lib/db";
+import { auth } from "@/lib/auth";
+
+const stow = new StowServer(process.env.STOW_API_KEY!);
+
+export const POST = createUploadHandler({
+  stow,
+  maxSize: 5 * 1024 * 1024,
+  allowedTypes: ["image/jpeg", "image/png", "image/webp"],
+
+  validate: async (file) => {
+    const session = await auth();
+    if (!session) return "Unauthorized";
+    return true;
+  },
+
+  onUploadComplete: async (result) => {
+    const session = await auth();
+    await db.insert(files).values({
+      key: result.key,
+      url: result.url,
+      userId: session!.user.id,
+    });
+  },
+});
+```
+
+## License
+
+MIT

package/dist/chunk-DZDX7UVD.mjs

@@ -0,0 +1,39 @@
+// src/image-loader.ts
+function createStowLoader(config = {}) {
+  const {
+    baseUrl = "https://stow.sh",
+    defaultQuality = 75,
+    defaultFormat
+  } = config;
+  return function stowLoader2({
+    src,
+    width,
+    quality
+  }) {
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const url = new URL(src, baseUrl);
+      const pathname = url.pathname;
+      const params = new URLSearchParams();
+      params.set("w", width.toString());
+      params.set("q", (quality || defaultQuality).toString());
+      if (defaultFormat) {
+        params.set("f", defaultFormat);
+      }
+      if (pathname.startsWith("/files/")) {
+        const transformPath = pathname.replace("/files/", "/transform/");
+        return `${baseUrl}${transformPath}?${params.toString()}`;
+      }
+      if (pathname.startsWith("/transform/")) {
+        return `${baseUrl}${pathname}?${params.toString()}`;
+      }
+      return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    return src;
+  };
+}
+var stowLoader = createStowLoader();
+
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/chunk-HRAABMBJ.mjs

@@ -0,0 +1,87 @@
+// src/image-loader.ts
+var STOW_DOMAIN_PATTERN = /\.stow\.sh$/;
+function isStowUrl(src) {
+  try {
+    const url = new URL(src);
+    return STOW_DOMAIN_PATTERN.test(url.hostname);
+  } catch {
+    return false;
+  }
+}
+function buildTransformParams(width, quality, config) {
+  const params = new URLSearchParams();
+  params.set("w", width.toString());
+  if (config.aspectRatio) {
+    params.set("h", Math.round(width / config.aspectRatio).toString());
+  }
+  params.set("q", quality.toString());
+  if (config.fit) {
+    params.set("fit", config.fit);
+  }
+  if (config.gravity) {
+    params.set("gravity", config.gravity);
+  }
+  if (config.defaultFormat) {
+    params.set("f", config.defaultFormat);
+  }
+  return params;
+}
+function transformStowUrl(src, baseUrl, params) {
+  const url = new URL(src, baseUrl);
+  const pathname = url.pathname;
+  if (pathname.startsWith("/files/")) {
+    const transformPath = pathname.replace("/files/", "/transform/");
+    return `${baseUrl}${transformPath}?${params.toString()}`;
+  }
+  if (pathname.startsWith("/transform/")) {
+    return `${baseUrl}${pathname}?${params.toString()}`;
+  }
+  return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+}
+function createStowLoader(config = {}) {
+  const {
+    baseUrl = "https://stow.sh",
+    defaultQuality = 75,
+    defaultFormat,
+    proxySlug,
+    fit,
+    gravity,
+    aspectRatio
+  } = config;
+  return function stowLoader2({
+    src,
+    width,
+    quality
+  }) {
+    const resolvedQuality = quality || defaultQuality;
+    const paramConfig = { defaultFormat, fit, gravity, aspectRatio };
+    if (isStowUrl(src)) {
+      const params = buildTransformParams(width, resolvedQuality, paramConfig);
+      return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const params = buildTransformParams(width, resolvedQuality, paramConfig);
+      return transformStowUrl(src, baseUrl, params);
+    }
+    if (proxySlug && (src.startsWith("http://") || src.startsWith("https://"))) {
+      const params = new URLSearchParams();
+      params.set("url", src);
+      params.set("w", width.toString());
+      if (aspectRatio) {
+        params.set("h", Math.round(width / aspectRatio).toString());
+      }
+      params.set("q", resolvedQuality.toString());
+      if (fit) params.set("fit", fit);
+      if (gravity) params.set("gravity", gravity);
+      if (defaultFormat) params.set("f", defaultFormat);
+      return `https://proxy.stow.sh/${proxySlug}/?${params.toString()}`;
+    }
+    return src;
+  };
+}
+var stowLoader = createStowLoader();
+
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/chunk-HYKV6KDZ.mjs

@@ -0,0 +1,31 @@
+// src/image-loader.ts
+function createObliqLoader(config = {}) {
+  const { baseUrl = "https://obliq.co", defaultQuality = 75, defaultFormat } = config;
+  return function obliqLoader2({ src, width, quality }) {
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const url = new URL(src, baseUrl);
+      const pathname = url.pathname;
+      const params = new URLSearchParams();
+      params.set("w", width.toString());
+      params.set("q", (quality || defaultQuality).toString());
+      if (defaultFormat) {
+        params.set("f", defaultFormat);
+      }
+      if (pathname.startsWith("/files/")) {
+        const transformPath = pathname.replace("/files/", "/transform/");
+        return `${baseUrl}${transformPath}?${params.toString()}`;
+      }
+      if (pathname.startsWith("/transform/")) {
+        return `${baseUrl}${pathname}?${params.toString()}`;
+      }
+      return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    return src;
+  };
+}
+var obliqLoader = createObliqLoader();
+
+export {
+  createObliqLoader,
+  obliqLoader
+};

package/dist/chunk-WN3NWAEN.mjs

@@ -0,0 +1,93 @@
+// src/image-loader.ts
+var STOW_DOMAIN_PATTERN = /\.stow\.sh$/;
+function isStowUrl(src) {
+  try {
+    const url = new URL(src);
+    return STOW_DOMAIN_PATTERN.test(url.hostname);
+  } catch {
+    return false;
+  }
+}
+function buildTransformParams(width, quality, config) {
+  const params = new URLSearchParams();
+  params.set("w", width.toString());
+  if (config.aspectRatio) {
+    params.set("h", Math.round(width / config.aspectRatio).toString());
+  }
+  params.set("q", quality.toString());
+  if (config.fit) {
+    params.set("fit", config.fit);
+  }
+  if (config.gravity) {
+    params.set("gravity", config.gravity);
+  }
+  if (config.defaultFormat) {
+    params.set("f", config.defaultFormat);
+  }
+  return params;
+}
+function transformStowUrl(src, baseUrl, params) {
+  const url = new URL(src, baseUrl);
+  const pathname = url.pathname;
+  if (pathname.startsWith("/files/")) {
+    const transformPath = pathname.replace("/files/", "/transform/");
+    return `${baseUrl}${transformPath}?${params.toString()}`;
+  }
+  if (pathname.startsWith("/transform/")) {
+    return `${baseUrl}${pathname}?${params.toString()}`;
+  }
+  return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+}
+function createStowLoader(config = {}) {
+  const {
+    baseUrl = "https://stow.sh",
+    defaultQuality = 75,
+    defaultFormat,
+    proxySlug,
+    fit,
+    gravity,
+    aspectRatio
+  } = config;
+  return function stowLoader2({
+    src,
+    width,
+    quality
+  }) {
+    const resolvedQuality = quality || defaultQuality;
+    const paramConfig = { defaultFormat, fit, gravity, aspectRatio };
+    if (isStowUrl(src)) {
+      const params = buildTransformParams(width, resolvedQuality, paramConfig);
+      return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const params = buildTransformParams(width, resolvedQuality, paramConfig);
+      return transformStowUrl(src, baseUrl, params);
+    }
+    if (proxySlug && (src.startsWith("http://") || src.startsWith("https://"))) {
+      const params = new URLSearchParams();
+      params.set("url", src);
+      params.set("w", width.toString());
+      if (aspectRatio) {
+        params.set("h", Math.round(width / aspectRatio).toString());
+      }
+      params.set("q", resolvedQuality.toString());
+      if (fit) {
+        params.set("fit", fit);
+      }
+      if (gravity) {
+        params.set("gravity", gravity);
+      }
+      if (defaultFormat) {
+        params.set("f", defaultFormat);
+      }
+      return `https://proxy.stow.sh/${proxySlug}/?${params.toString()}`;
+    }
+    return src;
+  };
+}
+var stowLoader = createStowLoader();
+
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/chunk-WWNT32U5.mjs

@@ -0,0 +1,62 @@
+// src/image-loader.ts
+function buildTransformParams(width, quality, defaultFormat) {
+  const params = new URLSearchParams();
+  params.set("w", width.toString());
+  params.set("q", quality.toString());
+  if (defaultFormat) {
+    params.set("f", defaultFormat);
+  }
+  return params;
+}
+function transformStowUrl(src, baseUrl, params) {
+  const url = new URL(src, baseUrl);
+  const pathname = url.pathname;
+  if (pathname.startsWith("/files/")) {
+    const transformPath = pathname.replace("/files/", "/transform/");
+    return `${baseUrl}${transformPath}?${params.toString()}`;
+  }
+  if (pathname.startsWith("/transform/")) {
+    return `${baseUrl}${pathname}?${params.toString()}`;
+  }
+  return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+}
+function createStowLoader(config = {}) {
+  const {
+    baseUrl = "https://stow.sh",
+    defaultQuality = 75,
+    defaultFormat,
+    proxySlug
+  } = config;
+  return function stowLoader2({
+    src,
+    width,
+    quality
+  }) {
+    const resolvedQuality = quality || defaultQuality;
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const params = buildTransformParams(
+        width,
+        resolvedQuality,
+        defaultFormat
+      );
+      return transformStowUrl(src, baseUrl, params);
+    }
+    if (proxySlug && (src.startsWith("http://") || src.startsWith("https://"))) {
+      const params = new URLSearchParams();
+      params.set("url", src);
+      params.set("w", width.toString());
+      params.set("q", resolvedQuality.toString());
+      if (defaultFormat) {
+        params.set("f", defaultFormat);
+      }
+      return `https://proxy.stow.sh/${proxySlug}/?${params.toString()}`;
+    }
+    return src;
+  };
+}
+var stowLoader = createStowLoader();
+
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/chunk-X2Y24T4H.mjs

@@ -0,0 +1,31 @@
+// src/image-loader.ts
+function createStowLoader(config = {}) {
+  const { baseUrl = "https://stow.sh", defaultQuality = 75, defaultFormat } = config;
+  return function stowLoader2({ src, width, quality }) {
+    if (src.startsWith(baseUrl) || src.startsWith("/files/")) {
+      const url = new URL(src, baseUrl);
+      const pathname = url.pathname;
+      const params = new URLSearchParams();
+      params.set("w", width.toString());
+      params.set("q", (quality || defaultQuality).toString());
+      if (defaultFormat) {
+        params.set("f", defaultFormat);
+      }
+      if (pathname.startsWith("/files/")) {
+        const transformPath = pathname.replace("/files/", "/transform/");
+        return `${baseUrl}${transformPath}?${params.toString()}`;
+      }
+      if (pathname.startsWith("/transform/")) {
+        return `${baseUrl}${pathname}?${params.toString()}`;
+      }
+      return `${src}${src.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+    return src;
+  };
+}
+var stowLoader = createStowLoader();
+
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/image-loader.d.mts

@@ -0,0 +1,119 @@
+/**
+ * Stow Image Loader for Next.js
+ *
+ * Use Stow's image transformation service with Next.js Image component.
+ * Supports both vanity subdomain URLs ({slug}.stow.sh/{key}) and
+ * legacy path-based URLs (stow.sh/files/{bucketId}/{key}).
+ *
+ * @example
+ * ```typescript
+ * // next.config.js — global loader
+ * module.exports = {
+ *   images: {
+ *     loader: "custom",
+ *     loaderFile: "./lib/stow-loader.ts",
+ *   },
+ * };
+ *
+ * // lib/stow-loader.ts
+ * import { stowLoader } from "@howells/stow-next/image-loader";
+ * export default stowLoader;
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Per-component loader with crop options
+ * import { createStowLoader } from "@howells/stow-next/image-loader";
+ * import Image from "next/image";
+ *
+ * const avatarLoader = createStowLoader({
+ *   fit: "cover",
+ *   gravity: "face",
+ *   aspectRatio: 1,
+ *   defaultFormat: "webp",
+ * });
+ *
+ * function Avatar({ src }: { src: string }) {
+ *   return <Image loader={avatarLoader} src={src} alt="Avatar" width={128} height={128} />;
+ * }
+ * ```
+ */
+interface ImageLoaderProps {
+    quality?: number;
+    src: string;
+    width: number;
+}
+interface StowLoaderConfig {
+    /**
+     * Fixed aspect ratio (width / height).
+     * When set, height is calculated from the requested width.
+     * Example: 1 for square, 16/9 for widescreen, 4/5 for portrait.
+     */
+    aspectRatio?: number;
+    /**
+     * Base URL for the Stow service.
+     * @default "https://stow.sh"
+     */
+    baseUrl?: string;
+    /**
+     * Default output format.
+     */
+    defaultFormat?: "webp" | "avif" | "jpeg" | "png";
+    /**
+     * Default image quality (1-100).
+     * @default 75
+     */
+    defaultQuality?: number;
+    /**
+     * Resize fit mode (Cloudflare Images).
+     * - "scale-down" — shrink to fit, never enlarge
+     * - "contain" — fit within bounds preserving aspect ratio
+     * - "cover" — fill bounds, crop excess
+     * - "crop" — crop to exact dimensions
+     * - "pad" — fit within bounds, pad remaining space
+     */
+    fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
+    /**
+     * Crop gravity / anchor point.
+     * - "auto" — subject-aware ML cropping
+     * - "face" — face-detection cropping
+     * - directional: "left", "right", "top", "bottom", "center"
+     */
+    gravity?: "auto" | "face" | "left" | "right" | "top" | "bottom" | "center";
+    /**
+     * Bucket slug for proxying external images through Stow.
+     * When set, external URLs (http/https) are routed through proxy.stow.sh
+     * for R2 caching and on-the-fly image transforms.
+     */
+    proxySlug?: string;
+}
+/**
+ * Create a custom image loader with configuration.
+ *
+ * Returns a stable function reference safe for use as a Next.js `loader` prop.
+ */
+declare function createStowLoader(config?: StowLoaderConfig): ({ src, width, quality, }: ImageLoaderProps) => string;
+/**
+ * Default Stow image loader.
+ *
+ * Handles vanity subdomain URLs ({slug}.stow.sh) and legacy
+ * path-based URLs (stow.sh/files/...). Appends width and quality
+ * as transform query params.
+ *
+ * ```js
+ * // next.config.js
+ * module.exports = {
+ *   images: {
+ *     loader: "custom",
+ *     loaderFile: "./lib/stow-loader.ts",
+ *   },
+ * };
+ *
+ * // lib/stow-loader.ts
+ * import { stowLoader } from "@howells/stow-next/image-loader";
+ * export default stowLoader;
+ * ```
+ */
+declare const stowLoader: ({ src, width, quality, }: ImageLoaderProps) => string;
+
+export { type ImageLoaderProps, type StowLoaderConfig, createStowLoader, stowLoader };