@howells/stow-client 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @howells/stow-client
+
+Client-side SDK for [Stow](https://stow.sh) file storage. Upload files directly from the browser with progress tracking.
+
+## Installation
+
+```bash
+npm install @howells/stow-client
+# or
+pnpm add @howells/stow-client
+# or
+yarn add @howells/stow-client
+```
+
+## Quick Start
+
+```typescript
+import { StowClient } from "@howells/stow-client";
+
+const stow = new StowClient("/api/upload");
+
+// Upload a file from a file input
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+const result = await stow.uploadFile(file, {
+  onProgress: (progress) => {
+    console.log(`Upload: ${progress.percent}%`);
+  },
+});
+
+console.log(result.url);
+```
+
+## Important: Server Endpoint Required
+
+This SDK uploads files through your server endpoint, not directly to Stow. Your server should use `@howells/stow-server` to handle the actual upload. This keeps your API key secure.
+
+```
+Browser → Your Server (/api/upload) → Stow
+```
+
+See `@howells/stow-next` for easy Next.js integration.
+
+## API Reference
+
+### `new StowClient(config)`
+
+Create a new client instance.
+
+```typescript
+// Simple: just pass the endpoint
+const stow = new StowClient("/api/upload");
+
+// With config object
+const stow = new StowClient({
+  endpoint: "/api/upload",
+});
+```
+
+### `uploadFile(file, options?)`
+
+Upload a single file with progress tracking.
+
+```typescript
+const result = await stow.uploadFile(file, {
+  route: "avatars", // optional folder/route
+  onProgress: (progress) => {
+    console.log(`${progress.loaded}/${progress.total} bytes (${progress.percent}%)`);
+  },
+});
+
+// Result:
+// {
+//   key: "bucket-id/avatars/abc123.jpg",
+//   url: "https://stow.sh/files/bucket-id/avatars/abc123.jpg",
+//   size: 12345,
+//   contentType: "image/jpeg"
+// }
+```
+
+### `uploadFiles(files, options?)`
+
+Upload multiple files sequentially.
+
+```typescript
+const results = await stow.uploadFiles(fileInput.files, {
+  route: "gallery",
+  onProgress: (progress) => {
+    console.log(`Current file: ${progress.percent}%`);
+  },
+  onFileComplete: (result, index) => {
+    console.log(`File ${index + 1} complete:`, result.url);
+  },
+  onFileError: (error, file, index) => {
+    console.error(`File ${index + 1} failed:`, error.message);
+  },
+});
+```
+
+## Error Handling
+
+```typescript
+import { StowError } from "@howells/stow-client";
+
+try {
+  await stow.uploadFile(file);
+} catch (error) {
+  if (error instanceof StowError) {
+    if (error.code === "ABORTED") {
+      console.log("Upload was cancelled");
+    } else {
+      console.error(`Upload failed: ${error.message}`);
+    }
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support:
+
+```typescript
+import type {
+  StowClientConfig,
+  UploadResult,
+  UploadProgress,
+  UploadOptions,
+} from "@howells/stow-client";
+```
+
+## Why XHR?
+
+This SDK uses XMLHttpRequest instead of fetch because **fetch doesn't support upload progress events**. XHR's `upload.onprogress` is the only way to show real upload progress to users.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,91 @@
+/**
+ * Stow Client SDK
+ *
+ * Client-side SDK for browser environments.
+ * Uploads files directly to R2 storage, bypassing your server for file bytes.
+ *
+ * Flow:
+ * 1. Client requests presigned URL from your server
+ * 2. Client uploads directly to R2 (your server never sees the file bytes!)
+ * 3. Client confirms upload via your server
+ *
+ * IMPORTANT: This SDK requires a server endpoint that handles presign/confirm.
+ * Never expose your API key to the client - use @howells/stow-server on your backend.
+ *
+ * @example
+ * ```typescript
+ * import { StowClient } from "@howells/stow-client";
+ *
+ * const stow = new StowClient("/api/stow");
+ *
+ * // Upload a file - goes directly to R2, not through your server!
+ * const result = await stow.uploadFile(file, {
+ *   onProgress: (p) => console.log(`${p.percent}%`),
+ * });
+ * console.log(result.url);
+ * ```
+ */
+declare class StowError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+interface StowClientConfig {
+    /**
+     * Your server endpoint that handles presign/confirm requests.
+     * This endpoint should use @howells/stow-server internally.
+     */
+    endpoint: string;
+}
+interface UploadResult {
+    key: string;
+    url: string | null;
+    size: number;
+    contentType: string;
+}
+interface UploadProgress {
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+    /** Upload percentage (0-100) */
+    percent: number;
+    /** Current phase of the upload */
+    phase: "presigning" | "uploading" | "confirming";
+}
+interface UploadOptions {
+    /** Optional route/folder for organizing files */
+    route?: string;
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, string>;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+}
+declare class StowClient {
+    private readonly endpoint;
+    constructor(config: StowClientConfig | string);
+    /**
+     * Upload a file directly to R2 storage.
+     *
+     * The file bytes never touch your server - they go directly to R2.
+     * Only small JSON requests go through your server for presign/confirm.
+     */
+    uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Upload file directly to R2 using presigned URL with progress tracking
+     */
+    private uploadToR2;
+    /**
+     * Upload multiple files with optional concurrency
+     */
+    uploadFiles(files: FileList | File[], options?: UploadOptions & {
+        /** Number of concurrent uploads (default: 3) */
+        concurrency?: number;
+        /** Called when a file completes */
+        onFileComplete?: (result: UploadResult, index: number) => void;
+        /** Called when a file fails */
+        onFileError?: (error: Error, file: File, index: number) => void;
+    }): Promise<UploadResult[]>;
+}
+
+export { StowClient, type StowClientConfig, StowError, type UploadOptions, type UploadProgress, type UploadResult };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Stow Client SDK
+ *
+ * Client-side SDK for browser environments.
+ * Uploads files directly to R2 storage, bypassing your server for file bytes.
+ *
+ * Flow:
+ * 1. Client requests presigned URL from your server
+ * 2. Client uploads directly to R2 (your server never sees the file bytes!)
+ * 3. Client confirms upload via your server
+ *
+ * IMPORTANT: This SDK requires a server endpoint that handles presign/confirm.
+ * Never expose your API key to the client - use @howells/stow-server on your backend.
+ *
+ * @example
+ * ```typescript
+ * import { StowClient } from "@howells/stow-client";
+ *
+ * const stow = new StowClient("/api/stow");
+ *
+ * // Upload a file - goes directly to R2, not through your server!
+ * const result = await stow.uploadFile(file, {
+ *   onProgress: (p) => console.log(`${p.percent}%`),
+ * });
+ * console.log(result.url);
+ * ```
+ */
+declare class StowError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+interface StowClientConfig {
+    /**
+     * Your server endpoint that handles presign/confirm requests.
+     * This endpoint should use @howells/stow-server internally.
+     */
+    endpoint: string;
+}
+interface UploadResult {
+    key: string;
+    url: string | null;
+    size: number;
+    contentType: string;
+}
+interface UploadProgress {
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+    /** Upload percentage (0-100) */
+    percent: number;
+    /** Current phase of the upload */
+    phase: "presigning" | "uploading" | "confirming";
+}
+interface UploadOptions {
+    /** Optional route/folder for organizing files */
+    route?: string;
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, string>;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+}
+declare class StowClient {
+    private readonly endpoint;
+    constructor(config: StowClientConfig | string);
+    /**
+     * Upload a file directly to R2 storage.
+     *
+     * The file bytes never touch your server - they go directly to R2.
+     * Only small JSON requests go through your server for presign/confirm.
+     */
+    uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Upload file directly to R2 using presigned URL with progress tracking
+     */
+    private uploadToR2;
+    /**
+     * Upload multiple files with optional concurrency
+     */
+    uploadFiles(files: FileList | File[], options?: UploadOptions & {
+        /** Number of concurrent uploads (default: 3) */
+        concurrency?: number;
+        /** Called when a file completes */
+        onFileComplete?: (result: UploadResult, index: number) => void;
+        /** Called when a file fails */
+        onFileError?: (error: Error, file: File, index: number) => void;
+    }): Promise<UploadResult[]>;
+}
+
+export { StowClient, type StowClientConfig, StowError, type UploadOptions, type UploadProgress, type UploadResult };

package/dist/index.js

@@ -0,0 +1,221 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StowClient: () => StowClient,
+  StowError: () => StowError
+});
+module.exports = __toCommonJS(index_exports);
+var StowError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "StowError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var StowClient = class {
+  endpoint;
+  constructor(config) {
+    if (typeof config === "string") {
+      this.endpoint = config;
+    } else {
+      this.endpoint = config.endpoint;
+    }
+  }
+  /**
+   * Upload a file directly to R2 storage.
+   *
+   * The file bytes never touch your server - they go directly to R2.
+   * Only small JSON requests go through your server for presign/confirm.
+   */
+  async uploadFile(file, options) {
+    const { route, metadata, onProgress } = options || {};
+    onProgress?.({
+      loaded: 0,
+      total: file.size,
+      percent: 0,
+      phase: "presigning"
+    });
+    const presignResponse = await fetch(`${this.endpoint}/presign`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        filename: file.name,
+        contentType: file.type || "application/octet-stream",
+        size: file.size,
+        route,
+        ...metadata ? { metadata } : {}
+      })
+    });
+    if (!presignResponse.ok) {
+      const error = await presignResponse.json().catch(() => ({ error: "Presign failed" }));
+      throw new StowError(
+        error.error || "Presign failed",
+        presignResponse.status,
+        error.code
+      );
+    }
+    const presign = await presignResponse.json();
+    onProgress?.({
+      loaded: 0,
+      total: file.size,
+      percent: 0,
+      phase: "uploading"
+    });
+    await this.uploadToR2(presign.uploadUrl, file, (loaded) => {
+      onProgress?.({
+        loaded,
+        total: file.size,
+        percent: Math.round(loaded / file.size * 100),
+        phase: "uploading"
+      });
+    });
+    onProgress?.({
+      loaded: file.size,
+      total: file.size,
+      percent: 100,
+      phase: "confirming"
+    });
+    const confirmResponse = await fetch(`${this.endpoint}/confirm`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        fileKey: presign.fileKey,
+        size: file.size,
+        contentType: file.type || "application/octet-stream",
+        ...metadata ? { metadata } : {}
+      })
+    });
+    if (!confirmResponse.ok) {
+      const error = await confirmResponse.json().catch(() => ({ error: "Confirm failed" }));
+      throw new StowError(
+        error.error || "Confirm failed",
+        confirmResponse.status,
+        error.code
+      );
+    }
+    const result = await confirmResponse.json();
+    return {
+      key: result.key,
+      url: result.url,
+      size: result.size,
+      contentType: result.contentType
+    };
+  }
+  /**
+   * Upload file directly to R2 using presigned URL with progress tracking
+   */
+  uploadToR2(uploadUrl, file, onProgress) {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable && onProgress) {
+          onProgress(event.loaded);
+        }
+      });
+      xhr.addEventListener("load", () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          resolve();
+        } else {
+          reject(
+            new StowError(
+              `R2 upload failed with status ${xhr.status}`,
+              xhr.status
+            )
+          );
+        }
+      });
+      xhr.addEventListener("error", () => {
+        reject(new StowError("Network error during R2 upload", 0));
+      });
+      xhr.addEventListener("abort", () => {
+        reject(new StowError("R2 upload aborted", 0, "ABORTED"));
+      });
+      xhr.open("PUT", uploadUrl);
+      xhr.setRequestHeader(
+        "Content-Type",
+        file.type || "application/octet-stream"
+      );
+      xhr.send(file);
+    });
+  }
+  /**
+   * Upload multiple files with optional concurrency
+   */
+  async uploadFiles(files, options) {
+    const fileArray = Array.from(files);
+    const concurrency = Math.max(1, options?.concurrency ?? 3);
+    if (concurrency === 1) {
+      const results2 = [];
+      for (let i = 0; i < fileArray.length; i++) {
+        try {
+          const result = await this.uploadFile(fileArray[i], options);
+          results2.push(result);
+          options?.onFileComplete?.(result, i);
+        } catch (error) {
+          options?.onFileError?.(
+            error instanceof Error ? error : new Error("Upload failed"),
+            fileArray[i],
+            i
+          );
+          throw error;
+        }
+      }
+      return results2;
+    }
+    const results = new Array(fileArray.length);
+    let nextIndex = 0;
+    let firstError = null;
+    const worker = async () => {
+      while (nextIndex < fileArray.length && !firstError) {
+        const i = nextIndex++;
+        try {
+          const result = await this.uploadFile(fileArray[i], options);
+          results[i] = result;
+          options?.onFileComplete?.(result, i);
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error("Upload failed");
+          options?.onFileError?.(err, fileArray[i], i);
+          if (!firstError) {
+            firstError = { error: err, file: fileArray[i], index: i };
+          }
+        }
+      }
+    };
+    const workers = Array.from(
+      { length: Math.min(concurrency, fileArray.length) },
+      () => worker()
+    );
+    await Promise.all(workers);
+    if (firstError !== null) {
+      throw firstError.error;
+    }
+    return results;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StowClient,
+  StowError
+});

package/dist/index.mjs

@@ -0,0 +1,195 @@
+// src/index.ts
+var StowError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "StowError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var StowClient = class {
+  endpoint;
+  constructor(config) {
+    if (typeof config === "string") {
+      this.endpoint = config;
+    } else {
+      this.endpoint = config.endpoint;
+    }
+  }
+  /**
+   * Upload a file directly to R2 storage.
+   *
+   * The file bytes never touch your server - they go directly to R2.
+   * Only small JSON requests go through your server for presign/confirm.
+   */
+  async uploadFile(file, options) {
+    const { route, metadata, onProgress } = options || {};
+    onProgress?.({
+      loaded: 0,
+      total: file.size,
+      percent: 0,
+      phase: "presigning"
+    });
+    const presignResponse = await fetch(`${this.endpoint}/presign`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        filename: file.name,
+        contentType: file.type || "application/octet-stream",
+        size: file.size,
+        route,
+        ...metadata ? { metadata } : {}
+      })
+    });
+    if (!presignResponse.ok) {
+      const error = await presignResponse.json().catch(() => ({ error: "Presign failed" }));
+      throw new StowError(
+        error.error || "Presign failed",
+        presignResponse.status,
+        error.code
+      );
+    }
+    const presign = await presignResponse.json();
+    onProgress?.({
+      loaded: 0,
+      total: file.size,
+      percent: 0,
+      phase: "uploading"
+    });
+    await this.uploadToR2(presign.uploadUrl, file, (loaded) => {
+      onProgress?.({
+        loaded,
+        total: file.size,
+        percent: Math.round(loaded / file.size * 100),
+        phase: "uploading"
+      });
+    });
+    onProgress?.({
+      loaded: file.size,
+      total: file.size,
+      percent: 100,
+      phase: "confirming"
+    });
+    const confirmResponse = await fetch(`${this.endpoint}/confirm`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        fileKey: presign.fileKey,
+        size: file.size,
+        contentType: file.type || "application/octet-stream",
+        ...metadata ? { metadata } : {}
+      })
+    });
+    if (!confirmResponse.ok) {
+      const error = await confirmResponse.json().catch(() => ({ error: "Confirm failed" }));
+      throw new StowError(
+        error.error || "Confirm failed",
+        confirmResponse.status,
+        error.code
+      );
+    }
+    const result = await confirmResponse.json();
+    return {
+      key: result.key,
+      url: result.url,
+      size: result.size,
+      contentType: result.contentType
+    };
+  }
+  /**
+   * Upload file directly to R2 using presigned URL with progress tracking
+   */
+  uploadToR2(uploadUrl, file, onProgress) {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable && onProgress) {
+          onProgress(event.loaded);
+        }
+      });
+      xhr.addEventListener("load", () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          resolve();
+        } else {
+          reject(
+            new StowError(
+              `R2 upload failed with status ${xhr.status}`,
+              xhr.status
+            )
+          );
+        }
+      });
+      xhr.addEventListener("error", () => {
+        reject(new StowError("Network error during R2 upload", 0));
+      });
+      xhr.addEventListener("abort", () => {
+        reject(new StowError("R2 upload aborted", 0, "ABORTED"));
+      });
+      xhr.open("PUT", uploadUrl);
+      xhr.setRequestHeader(
+        "Content-Type",
+        file.type || "application/octet-stream"
+      );
+      xhr.send(file);
+    });
+  }
+  /**
+   * Upload multiple files with optional concurrency
+   */
+  async uploadFiles(files, options) {
+    const fileArray = Array.from(files);
+    const concurrency = Math.max(1, options?.concurrency ?? 3);
+    if (concurrency === 1) {
+      const results2 = [];
+      for (let i = 0; i < fileArray.length; i++) {
+        try {
+          const result = await this.uploadFile(fileArray[i], options);
+          results2.push(result);
+          options?.onFileComplete?.(result, i);
+        } catch (error) {
+          options?.onFileError?.(
+            error instanceof Error ? error : new Error("Upload failed"),
+            fileArray[i],
+            i
+          );
+          throw error;
+        }
+      }
+      return results2;
+    }
+    const results = new Array(fileArray.length);
+    let nextIndex = 0;
+    let firstError = null;
+    const worker = async () => {
+      while (nextIndex < fileArray.length && !firstError) {
+        const i = nextIndex++;
+        try {
+          const result = await this.uploadFile(fileArray[i], options);
+          results[i] = result;
+          options?.onFileComplete?.(result, i);
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error("Upload failed");
+          options?.onFileError?.(err, fileArray[i], i);
+          if (!firstError) {
+            firstError = { error: err, file: fileArray[i], index: i };
+          }
+        }
+      }
+    };
+    const workers = Array.from(
+      { length: Math.min(concurrency, fileArray.length) },
+      () => worker()
+    );
+    await Promise.all(workers);
+    if (firstError !== null) {
+      throw firstError.error;
+    }
+    return results;
+  }
+};
+export {
+  StowClient,
+  StowError
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@howells/stow-client",
+  "version": "0.1.0",
+  "description": "Client-side SDK for Stow file storage",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/howells/stow.git",
+    "directory": "packages/stow-client"
+  },
+  "homepage": "https://stow.sh",
+  "keywords": [
+    "stow",
+    "file-storage",
+    "upload",
+    "presigned-url",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@stow/typescript-config": "workspace:*",
+    "jsdom": "^26.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  }
+}