@everystack/storage 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# @everystack/storage
+
+File upload handler with pluggable storage backends (filesystem, S3), presigned URLs, validation, and upload metadata tracking via Drizzle ORM.
+
+## Install
+
+```bash
+pnpm add @everystack/storage drizzle-orm
+```
+
+For S3 storage:
+
+```bash
+pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@everystack/storage` | Handler, adapters, validation |
+| `@everystack/storage/schema` | Drizzle `uploads` table |
+| `@everystack/storage/client` | Client-side presigned URL helpers |
+
+## Quick Start
+
+```typescript
+import { createStorageHandler, createObjectStorage } from '@everystack/storage';
+import { db } from './db';
+
+const storage = createObjectStorage({
+  type: 's3',
+  bucket: 'my-uploads',
+  region: 'us-east-1',
+  cdnUrl: 'https://cdn.example.com',
+});
+
+const handler = createStorageHandler({
+  db,
+  storage,
+  basePath: '/api/storage',
+  auth: {
+    verifyToken: async (token) => verifyJWT(token),
+  },
+  validation: {
+    maxSize: 10 * 1024 * 1024, // 10MB
+    allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  },
+});
+```
+
+### Mounting as an Expo Router API Route
+
+```typescript
+// app/api/storage/[...path]+api.ts
+export function GET(request: Request) { return handler(request); }
+export function POST(request: Request) { return handler(request); }
+export function DELETE(request: Request) { return handler(request); }
+```
+
+## Handler Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/presign` | Get a presigned upload URL |
+| `POST` | `/upload` | Direct multipart file upload |
+| `GET` | `/files/:key` | Download a file (or redirect to presigned URL) |
+| `GET` | `/uploads` | List upload metadata (paginated) |
+| `GET` | `/uploads/:id` | Get upload metadata |
+| `DELETE` | `/uploads/:id` | Delete upload + file |
+
+### Presigned Upload Flow
+
+```typescript
+// 1. Client requests presigned URL
+const res = await fetch('/api/storage/presign', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'photo.jpg', type: 'image/jpeg', size: 1024000 }),
+});
+const { url, key } = await res.json();
+
+// 2. Client uploads directly to S3
+await fetch(url, { method: 'PUT', body: file, headers: { 'Content-Type': 'image/jpeg' } });
+
+// 3. Use the `key` to reference the file
+```
+
+### Direct Upload
+
+```typescript
+const formData = new FormData();
+formData.append('file', file);
+
+const res = await fetch('/api/storage/upload', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${token}` },
+  body: formData,
+});
+const { id, key } = await res.json();
+```
+
+## Handler Options
+
+```typescript
+interface StorageHandlerOptions {
+  db: DrizzleDb;
+  storage: ObjectStorageAdapter;
+  basePath?: string;
+  bucket?: string; // Logical bucket name for metadata (default: 'default')
+  auth?: {
+    verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  };
+  validation?: {
+    maxSize?: number;           // Max file size in bytes
+    allowedTypes?: string[];    // MIME types (e.g., ['image/jpeg', 'image/png'])
+    allowedExtensions?: string[]; // File extensions (e.g., ['.jpg', '.png'])
+  };
+  keyGenerator?: (file: { name: string; type: string; userId?: string }) => string;
+  publishJob?: (type: string, payload: unknown) => Promise<string>;
+}
+```
+
+### Custom Key Generator
+
+```typescript
+const handler = createStorageHandler({
+  db,
+  storage,
+  keyGenerator: ({ name, type, userId }) => {
+    const ext = name.split('.').pop();
+    return `users/${userId}/${crypto.randomUUID()}.${ext}`;
+  },
+});
+```
+
+### Image Processing Integration
+
+Wire storage uploads to `@everystack/jobs` for automatic image processing:
+
+```typescript
+import { createJobClient, PostgresJobAdapter } from '@everystack/jobs';
+
+const jobClient = createJobClient(new PostgresJobAdapter(db));
+
+const handler = createStorageHandler({
+  db,
+  storage,
+  publishJob: (type, payload) => jobClient.publish(type, payload),
+});
+// Image uploads automatically publish a 'process-image' job
+```
+
+## Storage Adapters
+
+### Filesystem
+
+```typescript
+import { createObjectStorage } from '@everystack/storage';
+
+const storage = createObjectStorage({
+  type: 'filesystem',
+  directory: './uploads',
+  baseUrl: 'http://localhost:3000/files',
+});
+```
+
+### S3
+
+```typescript
+const storage = createObjectStorage({
+  type: 's3',
+  bucket: 'my-app-uploads',
+  region: 'us-east-1',
+  endpoint: 'https://s3.us-east-1.amazonaws.com', // Optional custom endpoint
+  cdnUrl: 'https://cdn.example.com',              // Optional CDN prefix
+});
+```
+
+### Custom Adapter
+
+Implement the `ObjectStorageAdapter` interface:
+
+```typescript
+interface ObjectStorageAdapter {
+  put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void>;
+  get(key: string): Promise<{ data: Buffer; contentType: string } | null>;
+  exists(key: string): Promise<boolean>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
+  deleteMany?(keys: string[]): Promise<void>;
+  getPresignedUploadUrl?(key: string, contentType: string, expiresIn?: number): Promise<string>;
+  getPresignedDownloadUrl?(key: string, expiresIn?: number): Promise<string>;
+}
+```
+
+## Schema
+
+Add the uploads table to your Drizzle migrations:
+
+```typescript
+import { uploads } from '@everystack/storage/schema';
+// Use in your Drizzle schema alongside your app tables
+```
+
+The `uploads` table tracks: `id`, `key`, `bucket`, `contentType`, `size`, `originalName`, `metadata`, `userId`, `createdAt`.
+
+## Peer Dependencies
+
+| Package | Version | Required |
+|---------|---------|----------|
+| `drizzle-orm` | `>=0.30.0` | Yes |
+| `@aws-sdk/client-s3` | `>=3.0.0` | For S3 adapter |
+| `@aws-sdk/s3-request-presigner` | `>=3.0.0` | For S3 presigned URLs |
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@everystack/storage",
+  "version": "0.1.0",
+  "description": "File uploads via S3 + CloudFront CDN with presigned URLs",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.30.0",
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/adapters/filesystem.ts

@@ -0,0 +1,93 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { ObjectStorageAdapter } from '../types';
+
+const MIME_MAP: Record<string, string> = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.json': 'application/json',
+  '.txt': 'text/plain',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.mp4': 'video/mp4',
+  '.mp3': 'audio/mpeg',
+  '.zip': 'application/zip',
+};
+
+function guessContentType(key: string): string {
+  const ext = path.extname(key).toLowerCase();
+  return MIME_MAP[ext] || 'application/octet-stream';
+}
+
+export class FilesystemObjectStorage implements ObjectStorageAdapter {
+  constructor(
+    private directory: string,
+    private baseUrl?: string
+  ) {}
+
+  private resolve(key: string): string {
+    return path.join(this.directory, key);
+  }
+
+  async put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void> {
+    const filePath = this.resolve(key);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, data);
+  }
+
+  async get(key: string): Promise<{ data: Buffer; contentType: string } | null> {
+    try {
+      const filePath = this.resolve(key);
+      const data = await fs.readFile(filePath);
+      const contentType = guessContentType(key);
+      return { data, contentType };
+    } catch {
+      return null;
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await fs.access(this.resolve(key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    const dir = this.resolve(prefix);
+    try {
+      const entries = await fs.readdir(dir, { recursive: true });
+      return entries.map((e) => path.join(prefix, String(e)));
+    } catch {
+      return [];
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await fs.unlink(this.resolve(key));
+    } catch {
+      // Ignore if file doesn't exist
+    }
+  }
+
+  async getPresignedUploadUrl(key: string, contentType: string, expiresIn?: number): Promise<string> {
+    // Filesystem doesn't support real presigned URLs — return handler upload path
+    const base = this.baseUrl || '';
+    return `${base}/upload?key=${encodeURIComponent(key)}&contentType=${encodeURIComponent(contentType)}`;
+  }
+
+  async getPresignedDownloadUrl(key: string, expiresIn?: number): Promise<string> {
+    const base = this.baseUrl || '';
+    return `${base}/files/${encodeURIComponent(key)}`;
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,10 @@
+import type { ObjectStorageAdapter, ObjectStorageOptions } from '../types';
+
+export function createObjectStorage(options: ObjectStorageOptions): ObjectStorageAdapter {
+  if (options.type === 'filesystem') {
+    const { FilesystemObjectStorage } = require('./filesystem') as typeof import('./filesystem');
+    return new FilesystemObjectStorage(options.directory, options.baseUrl);
+  }
+  const { S3ObjectStorage } = require('./s3') as typeof import('./s3');
+  return new S3ObjectStorage(options.bucket, options.region, options.endpoint, options.cdnUrl);
+}

package/src/adapters/s3.ts

@@ -0,0 +1,190 @@
+import type { ObjectStorageAdapter } from '../types';
+
+let S3ClientClass: any;
+let PutObjectCommand: any;
+let GetObjectCommand: any;
+let DeleteObjectCommand: any;
+let DeleteObjectsCommand: any;
+let ListObjectsV2Command: any;
+let HeadObjectCommand: any;
+let getSignedUrl: any;
+
+async function loadS3(): Promise<void> {
+  if (S3ClientClass) return;
+  try {
+    const s3Mod = await import('@aws-sdk/client-s3');
+    S3ClientClass = s3Mod.S3Client;
+    PutObjectCommand = s3Mod.PutObjectCommand;
+    GetObjectCommand = s3Mod.GetObjectCommand;
+    DeleteObjectCommand = s3Mod.DeleteObjectCommand;
+    DeleteObjectsCommand = s3Mod.DeleteObjectsCommand;
+    ListObjectsV2Command = s3Mod.ListObjectsV2Command;
+    HeadObjectCommand = s3Mod.HeadObjectCommand;
+  } catch {
+    throw new Error(
+      '@aws-sdk/client-s3 is required for S3 storage. Install it: pnpm add @aws-sdk/client-s3'
+    );
+  }
+}
+
+async function loadPresigner(): Promise<void> {
+  if (getSignedUrl) return;
+  try {
+    const mod = await import('@aws-sdk/s3-request-presigner');
+    getSignedUrl = mod.getSignedUrl;
+  } catch {
+    throw new Error(
+      '@aws-sdk/s3-request-presigner is required for presigned URLs. Install it: pnpm add @aws-sdk/s3-request-presigner'
+    );
+  }
+}
+
+export class S3ObjectStorage implements ObjectStorageAdapter {
+  private client: any = null;
+  private bucket: string;
+  private region?: string;
+  private endpoint?: string;
+  private cdnUrl?: string;
+
+  constructor(bucket: string, region?: string, endpoint?: string, cdnUrl?: string) {
+    this.bucket = bucket;
+    this.region = region;
+    this.endpoint = endpoint;
+    this.cdnUrl = cdnUrl;
+  }
+
+  private async getClient(): Promise<any> {
+    if (!this.client) {
+      await loadS3();
+      this.client = new S3ClientClass({
+        region: this.region,
+        ...(this.endpoint && {
+          endpoint: this.endpoint,
+          forcePathStyle: true,
+        }),
+      });
+    }
+    return this.client;
+  }
+
+  async put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void> {
+    const client = await this.getClient();
+    await client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: data,
+        ContentType: contentType || 'application/octet-stream',
+      })
+    );
+  }
+
+  async get(key: string): Promise<{ data: Buffer; contentType: string } | null> {
+    const client = await this.getClient();
+    try {
+      const response = await client.send(
+        new GetObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+      const chunks: Uint8Array[] = [];
+      for await (const chunk of response.Body) {
+        chunks.push(chunk);
+      }
+      return {
+        data: Buffer.concat(chunks),
+        contentType: response.ContentType || 'application/octet-stream',
+      };
+    } catch (err: any) {
+      if (err.name === 'NoSuchKey' || err.$metadata?.httpStatusCode === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const client = await this.getClient();
+    try {
+      await client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    const client = await this.getClient();
+    const keys: string[] = [];
+    let continuationToken: string | undefined;
+
+    do {
+      const response = await client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: continuationToken,
+        })
+      );
+
+      if (response.Contents) {
+        for (const obj of response.Contents) {
+          if (obj.Key) keys.push(obj.Key);
+        }
+      }
+
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+    } while (continuationToken);
+
+    return keys;
+  }
+
+  async delete(key: string): Promise<void> {
+    const client = await this.getClient();
+    await client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+
+  async deleteMany(keys: string[]): Promise<void> {
+    if (keys.length === 0) return;
+    const client = await this.getClient();
+
+    // S3 DeleteObjects supports up to 1000 keys per request
+    for (let i = 0; i < keys.length; i += 1000) {
+      const batch = keys.slice(i, i + 1000);
+      await client.send(
+        new DeleteObjectsCommand({
+          Bucket: this.bucket,
+          Delete: {
+            Objects: batch.map((Key: string) => ({ Key })),
+            Quiet: true,
+          },
+        })
+      );
+    }
+  }
+
+  async getPresignedUploadUrl(key: string, contentType: string, expiresIn: number = 3600): Promise<string> {
+    const client = await this.getClient();
+    await loadPresigner();
+    return getSignedUrl(
+      client,
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        ContentType: contentType,
+      }),
+      { expiresIn }
+    );
+  }
+
+  async getPresignedDownloadUrl(key: string, expiresIn: number = 3600): Promise<string> {
+    if (this.cdnUrl) {
+      return `${this.cdnUrl}/${key}`;
+    }
+    const client = await this.getClient();
+    await loadPresigner();
+    return getSignedUrl(
+      client,
+      new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+      { expiresIn }
+    );
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,258 @@
+import type { UploadMetadata } from '../types';
+
+export interface StorageClientOptions {
+  baseUrl: string;
+  getToken?: () => string | null | Promise<string | null>;
+}
+
+export interface UploadProgress {
+  loaded: number;
+  total: number;
+  percentage: number;
+}
+
+export interface UploadResult {
+  id: string;
+  key: string;
+}
+
+export function useUpload(clientOptions: StorageClientOptions) {
+  let React: any;
+  try {
+    React = require('react');
+  } catch {
+    throw new Error('react is required for useUpload hook');
+  }
+
+  const { useState, useCallback, useRef } = React;
+  const [progress, setProgress] = useState(null as UploadProgress | null);
+  const [isUploading, setIsUploading] = useState(false);
+  const [error, setError] = useState(null as Error | null);
+  const [result, setResult] = useState(null as UploadResult | null);
+  const abortRef = useRef(null as (() => void) | null);
+
+  const cancel = useCallback(() => {
+    abortRef.current?.();
+    abortRef.current = null;
+  }, []);
+
+  const upload = useCallback(async (file: File) => {
+    setIsUploading(true);
+    setError(null);
+    setProgress(null);
+    abortRef.current = null;
+
+    try {
+      const headers: Record<string, string> = {};
+      if (clientOptions.getToken) {
+        const token = await clientOptions.getToken();
+        if (token) headers.Authorization = `Bearer ${token}`;
+      }
+
+      // Try presigned URL first
+      const presignRes = await fetch(`${clientOptions.baseUrl}/presign`, {
+        method: 'POST',
+        headers: { ...headers, 'content-type': 'application/json' },
+        body: JSON.stringify({ name: file.name, type: file.type, size: file.size }),
+      });
+
+      if (presignRes.ok) {
+        const { url, key } = await presignRes.json() as { url: string; key: string };
+
+        // Upload via XHR for real progress tracking
+        await new Promise<void>((resolve, reject) => {
+          const xhr = new XMLHttpRequest();
+          xhr.upload.onprogress = (e: ProgressEvent) => {
+            if (e.lengthComputable) {
+              setProgress({
+                loaded: e.loaded,
+                total: e.total,
+                percentage: Math.round((e.loaded / e.total) * 100),
+              });
+            }
+          };
+          xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+              resolve();
+            } else {
+              reject(new Error(`Upload failed: ${xhr.status}`));
+            }
+          };
+          xhr.onerror = () => reject(new Error('Upload failed'));
+          xhr.onabort = () => reject(new Error('Upload cancelled'));
+          xhr.open('PUT', url);
+          xhr.setRequestHeader('content-type', file.type);
+          abortRef.current = () => xhr.abort();
+          xhr.send(file);
+        });
+
+        setProgress({ loaded: file.size, total: file.size, percentage: 100 });
+        const uploadResult = { id: key, key };
+        setResult(uploadResult);
+        return uploadResult;
+      }
+
+      // Fallback to multipart upload
+      const formData = new FormData();
+      formData.append('file', file);
+
+      const uploadRes = await fetch(`${clientOptions.baseUrl}/upload`, {
+        method: 'POST',
+        headers,
+        body: formData,
+      });
+
+      if (!uploadRes.ok) {
+        const err = await uploadRes.json().catch(() => ({ error: 'Upload failed' }));
+        throw new Error((err as any).error || 'Upload failed');
+      }
+
+      const uploadResult = await uploadRes.json() as UploadResult;
+      setProgress({ loaded: file.size, total: file.size, percentage: 100 });
+      setResult(uploadResult);
+      return uploadResult;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setIsUploading(false);
+      abortRef.current = null;
+    }
+  }, [clientOptions.baseUrl, clientOptions.getToken]);
+
+  return { upload, cancel, progress, isUploading, error, result };
+}
+
+export function usePresignedUrl(clientOptions: StorageClientOptions, key: string | null) {
+  let React: any;
+  try {
+    React = require('react');
+  } catch {
+    throw new Error('react is required for usePresignedUrl hook');
+  }
+
+  const { useState, useEffect } = React;
+  const [url, setUrl] = useState(null as string | null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (!key) return;
+    let cancelled = false;
+
+    async function load() {
+      setLoading(true);
+      try {
+        const fileUrl = `${clientOptions.baseUrl}/files/${encodeURIComponent(key!)}`;
+        if (!cancelled) {
+          setUrl(fileUrl);
+          setLoading(false);
+        }
+      } catch {
+        if (!cancelled) setLoading(false);
+      }
+    }
+
+    load();
+    return () => { cancelled = true; };
+  }, [clientOptions.baseUrl, key]);
+
+  return { url, loading };
+}
+
+export function useUploads(clientOptions: StorageClientOptions, options?: { limit?: number; offset?: number }) {
+  let React: any;
+  try {
+    React = require('react');
+  } catch {
+    throw new Error('react is required for useUploads hook');
+  }
+
+  const { useState, useEffect } = React;
+  const [data, setData] = useState([] as UploadMetadata[]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null as Error | null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      try {
+        const params = new URLSearchParams();
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const query = params.toString();
+        const url = `${clientOptions.baseUrl}/uploads${query ? `?${query}` : ''}`;
+
+        const headers: Record<string, string> = {};
+        if (clientOptions.getToken) {
+          const token = await clientOptions.getToken();
+          if (token) headers.Authorization = `Bearer ${token}`;
+        }
+
+        const res = await fetch(url, { headers });
+        if (!res.ok) throw new Error('Failed to fetch uploads');
+
+        const result = await res.json();
+        if (!cancelled) {
+          setData(result as UploadMetadata[]);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setLoading(false);
+        }
+      }
+    }
+
+    load();
+    return () => { cancelled = true; };
+  }, [clientOptions.baseUrl, options?.limit, options?.offset]);
+
+  return { data, loading, error };
+}
+
+// Image URL builder — constructs CloudFront image Lambda URLs with transform params.
+// Mirrors the contract from the Image Lambda's parseParams function.
+export interface ImageUrlOptions {
+  width?: number;
+  height?: number;
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+  format?: 'webp' | 'avif' | 'jpeg' | 'png';
+  quality?: number;
+  dpr?: number;
+}
+
+export function useImageUrl(baseUrl: string, key: string | null, options?: ImageUrlOptions): string | null {
+  let React: any;
+  try {
+    React = require('react');
+  } catch {
+    throw new Error('react is required for useImageUrl hook');
+  }
+
+  const { useMemo } = React;
+
+  return useMemo(() => {
+    if (!key) return null;
+
+    const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    const encodedKey = key.split('/').map(encodeURIComponent).join('/');
+    const url = `${base}/media/${encodedKey}`;
+
+    if (!options) return url;
+
+    const params = new URLSearchParams();
+    if (options.width != null) params.set('w', String(Math.min(Math.max(1, Math.round(options.width)), 4096)));
+    if (options.height != null) params.set('h', String(Math.min(Math.max(1, Math.round(options.height)), 4096)));
+    if (options.fit) params.set('fit', options.fit);
+    if (options.format) params.set('fm', options.format);
+    if (options.quality != null) params.set('q', String(Math.min(Math.max(1, Math.round(options.quality)), 100)));
+    if (options.dpr != null) params.set('dpr', String(Math.min(Math.max(1, options.dpr), 3)));
+
+    const qs = params.toString();
+    return qs ? `${url}?${qs}` : url;
+  }, [baseUrl, key, options?.width, options?.height, options?.fit, options?.format, options?.quality, options?.dpr]);
+}

package/src/handler/index.ts

@@ -0,0 +1,213 @@
+import { sql } from 'drizzle-orm';
+import { blobs } from '../schema';
+import { validateUpload } from '../validation';
+import { defaultKeyGenerator } from '../key-generator';
+import type { StorageHandlerOptions } from '../types';
+
+/**
+ * Compute SHA-256 hash of a buffer. Returns hex string.
+ */
+async function computeSha256(data: ArrayBuffer | Buffer | Uint8Array): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest('SHA-256', new Uint8Array(data as ArrayBuffer));
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export function createStorageHandler(options: StorageHandlerOptions): (request: Request) => Promise<Response> {
+  const basePath = options.basePath || '';
+  const { db, storage, auth, validation, publishJob } = options;
+  const keyGenerator = options.keyGenerator || defaultKeyGenerator;
+  const bucket = options.bucket || 'default';
+
+  function json(data: unknown, status: number = 200): Response {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    });
+  }
+
+  async function verifyAuth(request: Request): Promise<Record<string, unknown> | null> {
+    if (!auth) return {};
+    const header = request.headers.get('authorization');
+    if (!header?.startsWith('Bearer ')) return null;
+    return auth.verifyToken(header.slice(7));
+  }
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+
+    if (basePath && pathname.startsWith(basePath)) {
+      pathname = pathname.slice(basePath.length) || '/';
+    }
+
+    // POST /presign — generate presigned upload URL
+    if (request.method === 'POST' && pathname === '/presign') {
+      const user = await verifyAuth(request);
+      if (!user) return json({ error: 'Unauthorized' }, 401);
+
+      const body = (await request.json()) as { name: string; type: string; size: number };
+      if (!body.name || !body.type) {
+        return json({ error: 'Missing name or type' }, 400);
+      }
+
+      if (validation) {
+        const result = validateUpload(body, validation);
+        if (!result.valid) return json({ error: result.error }, 400);
+      }
+
+      const key = keyGenerator({
+        name: body.name,
+        type: body.type,
+        userId: user.sub as string | undefined,
+      });
+
+      if (storage.getPresignedUploadUrl) {
+        const uploadUrl = await storage.getPresignedUploadUrl(key, body.type);
+        return json({ url: uploadUrl, key });
+      }
+
+      // Fallback: return direct upload URL
+      const uploadUrl = `${basePath}/upload?key=${encodeURIComponent(key)}`;
+      return json({ url: uploadUrl, key });
+    }
+
+    // POST /upload — direct multipart upload
+    if (request.method === 'POST' && pathname === '/upload') {
+      const user = await verifyAuth(request);
+      if (!user) return json({ error: 'Unauthorized' }, 401);
+
+      let formData: FormData;
+      try {
+        formData = await request.formData();
+      } catch {
+        return json({ error: 'Invalid multipart form data' }, 400);
+      }
+
+      const file = formData.get('file') as File | null;
+      if (!file) return json({ error: 'Missing file field' }, 400);
+
+      if (validation) {
+        const result = validateUpload(
+          { name: file.name, type: file.type, size: file.size },
+          validation
+        );
+        if (!result.valid) return json({ error: result.error }, 400);
+      }
+
+      const key = keyGenerator({
+        name: file.name,
+        type: file.type,
+        userId: user.sub as string | undefined,
+      });
+
+      const buffer = Buffer.from(await file.arrayBuffer());
+      await storage.put(key, buffer, file.type);
+
+      // Compute content hash for dedup
+      const sha256 = await computeSha256(buffer);
+
+      // Write metadata to DB
+      const result = await db
+        .insert(blobs)
+        .values({
+          type: 'original',
+          sha256,
+          s3Key: key,
+          bucket,
+          sizeBytes: file.size,
+          contentType: file.type,
+          metadata: {
+            originalName: file.name,
+            userId: (user.sub as string) || null,
+          },
+        })
+        .returning({ id: blobs.id });
+
+      const uploadId = result[0].id;
+
+      // Publish image processing job if it's an image
+      if (publishJob && file.type.startsWith('image/')) {
+        await publishJob('process-image', { key, uploadId });
+      }
+
+      return json({ id: uploadId, key }, 201);
+    }
+
+    // GET /files/:key — serve file
+    const filesMatch = pathname.match(/^\/files\/(.+)$/);
+    if (request.method === 'GET' && filesMatch) {
+      const key = decodeURIComponent(filesMatch[1]);
+
+      // If adapter supports presigned download URLs, redirect
+      if (storage.getPresignedDownloadUrl) {
+        const downloadUrl = await storage.getPresignedDownloadUrl(key);
+        return Response.redirect(downloadUrl, 302);
+      }
+
+      const file = await storage.get(key);
+      if (!file) return json({ error: 'File not found' }, 404);
+
+      return new Response(new Uint8Array(file.data), {
+        headers: {
+          'content-type': file.contentType,
+          'cache-control': 'public, max-age=86400',
+        },
+      });
+    }
+
+    // GET /uploads — list upload metadata
+    if (request.method === 'GET' && pathname === '/uploads') {
+      const user = await verifyAuth(request);
+      if (!user) return json({ error: 'Unauthorized' }, 401);
+
+      const limit = url.searchParams.has('limit') ? parseInt(url.searchParams.get('limit')!, 10) : 50;
+      const offset = url.searchParams.has('offset') ? parseInt(url.searchParams.get('offset')!, 10) : 0;
+
+      let query = db.select().from(blobs);
+
+      if (user.sub) {
+        query = query.where(sql`${blobs.metadata}->>'userId' = ${user.sub}`);
+      }
+
+      query = query.orderBy(sql`${blobs.createdAt} DESC`).limit(limit).offset(offset);
+
+      const result = await query;
+      return json(result);
+    }
+
+    // GET /uploads/:id — get upload metadata
+    const uploadMatch = pathname.match(/^\/uploads\/([^/]+)$/);
+    if (request.method === 'GET' && uploadMatch) {
+      const result = await db
+        .select()
+        .from(blobs)
+        .where(sql`${blobs.id} = ${uploadMatch[1]}`);
+
+      if (!result[0]) return json({ error: 'Upload not found' }, 404);
+      return json(result[0]);
+    }
+
+    // DELETE /uploads/:id — delete upload + file
+    const deleteMatch = pathname.match(/^\/uploads\/([^/]+)$/);
+    if (request.method === 'DELETE' && deleteMatch) {
+      const user = await verifyAuth(request);
+      if (!user) return json({ error: 'Unauthorized' }, 401);
+
+      const result = await db
+        .select()
+        .from(blobs)
+        .where(sql`${blobs.id} = ${deleteMatch[1]}`);
+
+      if (!result[0]) return json({ error: 'Upload not found' }, 404);
+
+      await storage.delete(result[0].s3Key!);
+      await db.delete(blobs).where(sql`${blobs.id} = ${deleteMatch[1]}`);
+
+      return json({ ok: true });
+    }
+
+    return json({ error: 'Not found' }, 404);
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { createStorageHandler } from './handler/index';
+export { createObjectStorage } from './adapters/index';
+export { FilesystemObjectStorage } from './adapters/filesystem';
+export { S3ObjectStorage } from './adapters/s3';
+export { validateUpload } from './validation';
+export { defaultKeyGenerator } from './key-generator';
+export type {
+  ObjectStorageAdapter,
+  ObjectStorageOptions,
+  StorageHandlerOptions,
+  UploadMetadata,
+  UploadValidation,
+  StorageType,
+} from './types';
+export type { ValidationResult } from './validation';

package/src/key-generator.ts

@@ -0,0 +1,10 @@
+export function defaultKeyGenerator(file: { name: string; type: string; userId?: string }): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const uuid = crypto.randomUUID();
+  const parts = file.name.split('.');
+  const ext = parts.length > 1 ? parts.pop()!.toLowerCase() : 'bin';
+
+  return `uploads/${year}/${month}/${uuid}.${ext}`;
+}

package/src/schema.ts

@@ -0,0 +1,87 @@
+/**
+ * Storage schema — everyschema dist.blobs
+ *
+ * Content-addressed storage — in-DB (bytea) or S3-backed.
+ * Replaces the old `uploads` table.
+ *
+ * Type values for everystack:
+ *   'original'  — user-uploaded content (S3-backed)
+ *   'thumbnail' — derived image variant (parentId → original)
+ *   'preview'   — derived preview image
+ *   'webp'      — derived WebP variant
+ *
+ * @see everyschema — canonical schema definitions
+ */
+
+import {
+  pgSchema,
+  text,
+  timestamp,
+  uuid,
+  bigint,
+  index,
+  uniqueIndex,
+  jsonb,
+  customType,
+} from 'drizzle-orm/pg-core';
+
+const distSchema = pgSchema('dist');
+
+const bytea = customType<{ data: Buffer; driverValue: Buffer }>({
+  dataType() {
+    return 'bytea';
+  },
+});
+
+// =============================================================================
+// BLOBS - Raw binary storage, deduped by sha256
+// =============================================================================
+
+/**
+ * Content-addressed storage — in-DB or S3-backed.
+ *
+ * Storage modes:
+ *   In-DB:  data (bytea) populated, s3Key/bucket NULL
+ *   S3:     s3Key + bucket populated, data NULL
+ *
+ * Derived content uses parentId:
+ *   original → thumbnail, preview, webp, etc.
+ *
+ * metadata stores intrinsic content properties:
+ *   Images: { width, height, format, originalName, userId }
+ *   Video/audio: { codec, duration, bitrate }
+ */
+export const blobs = distSchema.table(
+  'blobs',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    repositoryId: uuid('repository_id'),
+    type: text('type').notNull(), // 'original' | 'thumbnail' | 'preview' | 'webp' | etc.
+    sha256: text('sha256').notNull().unique(),
+
+    // Storage: in-DB (bytea) or S3-backed (s3Key + bucket)
+    data: bytea('data'),
+    s3Key: text('s3_key'),
+    bucket: text('bucket'),
+
+    sizeBytes: bigint('size_bytes', { mode: 'number' }).notNull(),
+    contentType: text('content_type'),
+
+    // Derived content (thumbnail → original, webp → original, etc.)
+    parentId: uuid('parent_id'),
+
+    // Intrinsic content metadata
+    metadata: jsonb('metadata'),
+
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    typeIdx: index('blobs_type_idx').on(table.type),
+    sha256Idx: uniqueIndex('blobs_sha256_idx').on(table.sha256),
+    contentTypeIdx: index('blobs_content_type_idx').on(table.contentType),
+    createdAtIdx: index('blobs_created_at_idx').on(table.createdAt),
+    repoIdx: index('blobs_repo_idx').on(table.repositoryId),
+    parentIdx: index('blobs_parent_idx').on(table.parentId),
+    s3KeyIdx: index('blobs_s3_key_idx').on(table.s3Key),
+  })
+);

package/src/types.ts

@@ -0,0 +1,48 @@
+export interface ObjectStorageAdapter {
+  put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void>;
+  get(key: string): Promise<{ data: Buffer; contentType: string } | null>;
+  exists(key: string): Promise<boolean>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
+  /** Batch delete up to 1000 keys per call. Falls back to sequential delete if not implemented. */
+  deleteMany?(keys: string[]): Promise<void>;
+  getPresignedUploadUrl?(key: string, contentType: string, expiresIn?: number): Promise<string>;
+  getPresignedDownloadUrl?(key: string, expiresIn?: number): Promise<string>;
+}
+
+export interface UploadMetadata {
+  id: string;
+  key: string;
+  bucket: string;
+  contentType: string;
+  size: number;
+  originalName: string | null;
+  metadata: Record<string, unknown> | null;
+  userId: string | null;
+  createdAt: Date;
+}
+
+export interface UploadValidation {
+  maxSize?: number;
+  allowedTypes?: string[];
+  allowedExtensions?: string[];
+}
+
+export type StorageType = 'filesystem' | 's3';
+
+export type ObjectStorageOptions =
+  | { type: 'filesystem'; directory: string; baseUrl?: string }
+  | { type: 's3'; bucket: string; region?: string; endpoint?: string; cdnUrl?: string };
+
+export interface StorageHandlerOptions {
+  db: any;
+  storage: ObjectStorageAdapter;
+  basePath?: string;
+  bucket?: string;
+  auth?: {
+    verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  };
+  validation?: UploadValidation;
+  keyGenerator?: (file: { name: string; type: string; userId?: string }) => string;
+  publishJob?: (type: string, payload: unknown) => Promise<string>;
+}

package/src/validation.ts

@@ -0,0 +1,39 @@
+import type { UploadValidation } from './types';
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+export function validateUpload(
+  file: { name: string; type: string; size: number },
+  rules: UploadValidation
+): ValidationResult {
+  if (rules.maxSize && file.size > rules.maxSize) {
+    return {
+      valid: false,
+      error: `File size ${file.size} exceeds maximum ${rules.maxSize} bytes`,
+    };
+  }
+
+  if (rules.allowedTypes && rules.allowedTypes.length > 0) {
+    if (!rules.allowedTypes.includes(file.type)) {
+      return {
+        valid: false,
+        error: `File type ${file.type} is not allowed. Allowed: ${rules.allowedTypes.join(', ')}`,
+      };
+    }
+  }
+
+  if (rules.allowedExtensions && rules.allowedExtensions.length > 0) {
+    const ext = file.name.split('.').pop()?.toLowerCase();
+    if (!ext || !rules.allowedExtensions.includes(ext)) {
+      return {
+        valid: false,
+        error: `File extension .${ext || ''} is not allowed. Allowed: ${rules.allowedExtensions.map((e) => `.${e}`).join(', ')}`,
+      };
+    }
+  }
+
+  return { valid: true };
+}