@howells/stow-next 0.1.0

package/dist/image-loader.d.ts

@@ -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 };

package/dist/image-loader.js

@@ -0,0 +1,118 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/image-loader.ts
+var image_loader_exports = {};
+__export(image_loader_exports, {
+  createStowLoader: () => createStowLoader,
+  stowLoader: () => stowLoader
+});
+module.exports = __toCommonJS(image_loader_exports);
+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();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStowLoader,
+  stowLoader
+});

package/dist/image-loader.mjs

@@ -0,0 +1,8 @@
+import {
+  createStowLoader,
+  stowLoader
+} from "./chunk-WN3NWAEN.mjs";
+export {
+  createStowLoader,
+  stowLoader
+};

package/dist/index.d.mts

@@ -0,0 +1,156 @@
+import { NextRequest, NextResponse } from 'next/server';
+export { StowLoaderConfig, createStowLoader, stowLoader } from './image-loader.mjs';
+
+/**
+ * Stow Next.js Integration
+ *
+ * Provides Next.js-specific utilities for Stow file storage:
+ * - Route handlers for direct uploads (presign + confirm)
+ * - Image loader for next/image optimization
+ *
+ * @example
+ * ```typescript
+ * // app/api/stow/presign/route.ts
+ * import { createPresignHandler } from "@howells/stow-next";
+ * import { StowServer } from "@howells/stow-server";
+ *
+ * const stow = new StowServer(process.env.STOW_API_KEY!);
+ * export const POST = createPresignHandler({ stow });
+ *
+ * // app/api/stow/confirm/route.ts
+ * import { createConfirmHandler } from "@howells/stow-next";
+ * export const POST = createConfirmHandler({ stow });
+ * ```
+ */
+
+interface CorsConfig {
+    /** Allowed headers (default: ["Content-Type"]) */
+    allowedHeaders?: string[];
+    /** Max age for preflight cache in seconds (default: 86400 = 24 hours) */
+    maxAge?: number;
+    /** Allowed methods (default: ["POST", "OPTIONS"]) */
+    methods?: string[];
+    /** Allowed origins (default: "*") */
+    origin?: string | string[];
+}
+/**
+ * Create an OPTIONS handler for CORS preflight requests
+ */
+declare function createCorsPreflightHandler(config?: CorsConfig): () => NextResponse;
+interface StowServerLike {
+    confirmUpload: (request: {
+        fileKey: string;
+        size: number;
+        contentType: string;
+    }) => Promise<{
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }>;
+    getPresignedUrl: (request: {
+        filename: string;
+        contentType: string;
+        size: number;
+        route?: string;
+    }) => Promise<{
+        dedupe: true;
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    } | {
+        fileKey: string;
+        uploadUrl: string;
+        r2Key: string;
+        confirmUrl: string;
+        dedupe?: false;
+    }>;
+}
+interface PresignHandlerConfig {
+    /** Allowed content types (supports wildcards like "image/*") */
+    allowedTypes?: string[];
+    /** CORS configuration (enabled by default for browser uploads) */
+    cors?: CorsConfig | false;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Default route for organizing files */
+    route?: string;
+    /** Stow server instance */
+    stow: StowServerLike;
+    /** Custom validation function */
+    validate?: (request: {
+        filename: string;
+        contentType: string;
+        size: number;
+    }) => Promise<boolean | string> | boolean | string;
+}
+interface ConfirmHandlerConfig {
+    /** CORS configuration (enabled by default for browser uploads) */
+    cors?: CorsConfig | false;
+    /** Called after upload is confirmed */
+    onUploadComplete?: (result: {
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    /** Stow server instance */
+    stow: StowServerLike;
+}
+/**
+ * Create a Next.js route handler for presigning uploads.
+ * This is called by @howells/stow-client to get a presigned URL for direct R2 upload.
+ *
+ * Returns both POST handler and OPTIONS handler for CORS preflight.
+ */
+declare function createPresignHandler(config: PresignHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Create a Next.js route handler for confirming uploads.
+ * This is called by @howells/stow-client after uploading to R2.
+ *
+ * Returns both POST handler and OPTIONS handler for CORS preflight.
+ */
+declare function createConfirmHandler(config: ConfirmHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+interface StowLike {
+    uploadFile: (file: Blob, options?: {
+        filename?: string;
+        contentType?: string;
+        route?: string;
+    }) => Promise<{
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }>;
+}
+interface UploadHandlerConfig {
+    /** Allowed content types (supports wildcards like "image/*") */
+    allowedTypes?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Called before upload starts */
+    onUploadBegin?: (file: File) => Promise<void> | void;
+    /** Called after upload completes */
+    onUploadComplete?: (result: {
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    /** Optional route for organizing files */
+    route?: string;
+    /** Stow server instance */
+    stow: StowLike;
+    /** Custom validation function */
+    validate?: (file: File) => Promise<boolean | string> | boolean | string;
+}
+/**
+ * Create a Next.js route handler for proxied file uploads.
+ *
+ * @deprecated Use createPresignHandler + createConfirmHandler for direct uploads.
+ * Proxied uploads are limited by serverless payload limits (~4.5MB on Vercel).
+ */
+declare function createUploadHandler(config: UploadHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+
+export { type ConfirmHandlerConfig, type CorsConfig, type PresignHandlerConfig, type StowLike, type StowServerLike, type UploadHandlerConfig, createConfirmHandler, createCorsPreflightHandler, createPresignHandler, createUploadHandler };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { NextRequest, NextResponse } from 'next/server';
+export { StowLoaderConfig, createStowLoader, stowLoader } from './image-loader.js';
+
+/**
+ * Stow Next.js Integration
+ *
+ * Provides Next.js-specific utilities for Stow file storage:
+ * - Route handlers for direct uploads (presign + confirm)
+ * - Image loader for next/image optimization
+ *
+ * @example
+ * ```typescript
+ * // app/api/stow/presign/route.ts
+ * import { createPresignHandler } from "@howells/stow-next";
+ * import { StowServer } from "@howells/stow-server";
+ *
+ * const stow = new StowServer(process.env.STOW_API_KEY!);
+ * export const POST = createPresignHandler({ stow });
+ *
+ * // app/api/stow/confirm/route.ts
+ * import { createConfirmHandler } from "@howells/stow-next";
+ * export const POST = createConfirmHandler({ stow });
+ * ```
+ */
+
+interface CorsConfig {
+    /** Allowed headers (default: ["Content-Type"]) */
+    allowedHeaders?: string[];
+    /** Max age for preflight cache in seconds (default: 86400 = 24 hours) */
+    maxAge?: number;
+    /** Allowed methods (default: ["POST", "OPTIONS"]) */
+    methods?: string[];
+    /** Allowed origins (default: "*") */
+    origin?: string | string[];
+}
+/**
+ * Create an OPTIONS handler for CORS preflight requests
+ */
+declare function createCorsPreflightHandler(config?: CorsConfig): () => NextResponse;
+interface StowServerLike {
+    confirmUpload: (request: {
+        fileKey: string;
+        size: number;
+        contentType: string;
+    }) => Promise<{
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }>;
+    getPresignedUrl: (request: {
+        filename: string;
+        contentType: string;
+        size: number;
+        route?: string;
+    }) => Promise<{
+        dedupe: true;
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    } | {
+        fileKey: string;
+        uploadUrl: string;
+        r2Key: string;
+        confirmUrl: string;
+        dedupe?: false;
+    }>;
+}
+interface PresignHandlerConfig {
+    /** Allowed content types (supports wildcards like "image/*") */
+    allowedTypes?: string[];
+    /** CORS configuration (enabled by default for browser uploads) */
+    cors?: CorsConfig | false;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Default route for organizing files */
+    route?: string;
+    /** Stow server instance */
+    stow: StowServerLike;
+    /** Custom validation function */
+    validate?: (request: {
+        filename: string;
+        contentType: string;
+        size: number;
+    }) => Promise<boolean | string> | boolean | string;
+}
+interface ConfirmHandlerConfig {
+    /** CORS configuration (enabled by default for browser uploads) */
+    cors?: CorsConfig | false;
+    /** Called after upload is confirmed */
+    onUploadComplete?: (result: {
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    /** Stow server instance */
+    stow: StowServerLike;
+}
+/**
+ * Create a Next.js route handler for presigning uploads.
+ * This is called by @howells/stow-client to get a presigned URL for direct R2 upload.
+ *
+ * Returns both POST handler and OPTIONS handler for CORS preflight.
+ */
+declare function createPresignHandler(config: PresignHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Create a Next.js route handler for confirming uploads.
+ * This is called by @howells/stow-client after uploading to R2.
+ *
+ * Returns both POST handler and OPTIONS handler for CORS preflight.
+ */
+declare function createConfirmHandler(config: ConfirmHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+interface StowLike {
+    uploadFile: (file: Blob, options?: {
+        filename?: string;
+        contentType?: string;
+        route?: string;
+    }) => Promise<{
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }>;
+}
+interface UploadHandlerConfig {
+    /** Allowed content types (supports wildcards like "image/*") */
+    allowedTypes?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Called before upload starts */
+    onUploadBegin?: (file: File) => Promise<void> | void;
+    /** Called after upload completes */
+    onUploadComplete?: (result: {
+        key: string;
+        url: string | null;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    /** Optional route for organizing files */
+    route?: string;
+    /** Stow server instance */
+    stow: StowLike;
+    /** Custom validation function */
+    validate?: (file: File) => Promise<boolean | string> | boolean | string;
+}
+/**
+ * Create a Next.js route handler for proxied file uploads.
+ *
+ * @deprecated Use createPresignHandler + createConfirmHandler for direct uploads.
+ * Proxied uploads are limited by serverless payload limits (~4.5MB on Vercel).
+ */
+declare function createUploadHandler(config: UploadHandlerConfig): (request: NextRequest) => Promise<NextResponse>;
+
+export { type ConfirmHandlerConfig, type CorsConfig, type PresignHandlerConfig, type StowLike, type StowServerLike, type UploadHandlerConfig, createConfirmHandler, createCorsPreflightHandler, createPresignHandler, createUploadHandler };