@howells/stow-client 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -25,11 +25,13 @@
  * console.log(result.url);
  * ```
  */
+/** Error thrown when an SDK request fails. */
 declare class StowError extends Error {
     readonly status: number;
     readonly code?: string;
     constructor(message: string, status: number, code?: string);
 }
+/** Configuration for creating a {@link StowClient} instance. */
 interface StowClientConfig {
     /**
      * Your server endpoint that handles presign/confirm requests.
@@ -37,38 +39,57 @@ interface StowClientConfig {
      */
     endpoint: string;
 }
+/** Result returned after a successful upload or dedupe short-circuit. */
 interface UploadResult {
+    contentType: string;
+    /** True when upload short-circuited to an existing file via dedupe. */
+    deduped?: boolean;
     key: string;
-    url: string | null;
     size: number;
-    contentType: string;
+    url: string | null;
 }
+/** Progress payload emitted during `uploadFile`. */
 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";
+    /** Total bytes to upload */
+    total: number;
 }
+/** Optional behavior for a single upload operation. */
 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;
+    /** Optional upload route (server-side configured route/path policy). */
+    route?: string;
 }
+/** Browser SDK for direct-to-R2 uploads via your server's presign/confirm endpoints. */
 declare class StowClient {
     private readonly endpoint;
+    /**
+     * @param config Server upload endpoint base path.
+     *
+     * The endpoint should expose:
+     * - `POST {endpoint}/presign`
+     * - `POST {endpoint}/confirm` (or a `confirmUrl` returned from presign)
+     */
     constructor(config: StowClientConfig | string);
+    private endpointUrl;
+    private resolveConfirmUrl;
     /**
      * 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.
+     *
+     * Dedup behavior:
+     * If presign responds with `{ dedupe: true, ... }`, upload skips R2 PUT and
+     * confirm entirely, returning the existing file metadata with `deduped: true`.
      */
     uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>;
     /**
@@ -77,6 +98,10 @@ declare class StowClient {
     private uploadToR2;
     /**
      * Upload multiple files with optional concurrency
+     *
+     * - `concurrency=1` preserves strict sequential ordering.
+     * - `concurrency>1` uses a bounded worker pool and stops scheduling new files
+     *   after the first error.
      */
     uploadFiles(files: FileList | File[], options?: UploadOptions & {
         /** Number of concurrent uploads (default: 3) */

package/dist/index.d.ts

@@ -25,11 +25,13 @@
  * console.log(result.url);
  * ```
  */
+/** Error thrown when an SDK request fails. */
 declare class StowError extends Error {
     readonly status: number;
     readonly code?: string;
     constructor(message: string, status: number, code?: string);
 }
+/** Configuration for creating a {@link StowClient} instance. */
 interface StowClientConfig {
     /**
      * Your server endpoint that handles presign/confirm requests.
@@ -37,38 +39,57 @@ interface StowClientConfig {
      */
     endpoint: string;
 }
+/** Result returned after a successful upload or dedupe short-circuit. */
 interface UploadResult {
+    contentType: string;
+    /** True when upload short-circuited to an existing file via dedupe. */
+    deduped?: boolean;
     key: string;
-    url: string | null;
     size: number;
-    contentType: string;
+    url: string | null;
 }
+/** Progress payload emitted during `uploadFile`. */
 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";
+    /** Total bytes to upload */
+    total: number;
 }
+/** Optional behavior for a single upload operation. */
 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;
+    /** Optional upload route (server-side configured route/path policy). */
+    route?: string;
 }
+/** Browser SDK for direct-to-R2 uploads via your server's presign/confirm endpoints. */
 declare class StowClient {
     private readonly endpoint;
+    /**
+     * @param config Server upload endpoint base path.
+     *
+     * The endpoint should expose:
+     * - `POST {endpoint}/presign`
+     * - `POST {endpoint}/confirm` (or a `confirmUrl` returned from presign)
+     */
     constructor(config: StowClientConfig | string);
+    private endpointUrl;
+    private resolveConfirmUrl;
     /**
      * 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.
+     *
+     * Dedup behavior:
+     * If presign responds with `{ dedupe: true, ... }`, upload skips R2 PUT and
+     * confirm entirely, returning the existing file metadata with `deduped: true`.
      */
     uploadFile(file: File, options?: UploadOptions): Promise<UploadResult>;
     /**
@@ -77,6 +98,10 @@ declare class StowClient {
     private uploadToR2;
     /**
      * Upload multiple files with optional concurrency
+     *
+     * - `concurrency=1` preserves strict sequential ordering.
+     * - `concurrency>1` uses a bounded worker pool and stops scheduling new files
+     *   after the first error.
      */
     uploadFiles(files: FileList | File[], options?: UploadOptions & {
         /** Number of concurrent uploads (default: 3) */

package/dist/index.js

@@ -36,18 +36,44 @@ var StowError = class extends Error {
 };
 var StowClient = class {
   endpoint;
+  /**
+   * @param config Server upload endpoint base path.
+   *
+   * The endpoint should expose:
+   * - `POST {endpoint}/presign`
+   * - `POST {endpoint}/confirm` (or a `confirmUrl` returned from presign)
+   */
   constructor(config) {
     if (typeof config === "string") {
-      this.endpoint = config;
+      this.endpoint = config.replace(/\/+$/, "");
     } else {
-      this.endpoint = config.endpoint;
+      this.endpoint = config.endpoint.replace(/\/+$/, "");
+    }
+  }
+  endpointUrl(path) {
+    if (!this.endpoint) {
+      return path;
+    }
+    return `${this.endpoint}${path}`;
+  }
+  resolveConfirmUrl(confirmUrl) {
+    if (!confirmUrl) {
+      return this.endpointUrl("/confirm");
+    }
+    if (confirmUrl.startsWith("/") || /^[a-z][a-z0-9+\-.]*:\/\//i.test(confirmUrl)) {
+      return confirmUrl;
     }
+    return this.endpointUrl(`/${confirmUrl.replace(/^\/+/, "")}`);
   }
   /**
    * 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.
+   *
+   * Dedup behavior:
+   * If presign responds with `{ dedupe: true, ... }`, upload skips R2 PUT and
+   * confirm entirely, returning the existing file metadata with `deduped: true`.
    */
   async uploadFile(file, options) {
     const { route, metadata, onProgress } = options || {};
@@ -57,7 +83,7 @@ var StowClient = class {
       percent: 0,
       phase: "presigning"
     });
-    const presignResponse = await fetch(`${this.endpoint}/presign`, {
+    const presignResponse = await fetch(this.endpointUrl("/presign"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -77,6 +103,21 @@ var StowClient = class {
       );
     }
     const presign = await presignResponse.json();
+    if ("dedupe" in presign && presign.dedupe) {
+      onProgress?.({
+        loaded: file.size,
+        total: file.size,
+        percent: 100,
+        phase: "confirming"
+      });
+      return {
+        key: presign.key,
+        url: presign.url,
+        size: presign.size,
+        contentType: presign.contentType,
+        deduped: true
+      };
+    }
     onProgress?.({
       loaded: 0,
       total: file.size,
@@ -97,16 +138,19 @@ var StowClient = class {
       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 } : {}
-      })
-    });
+    const confirmResponse = await fetch(
+      this.resolveConfirmUrl(presign.confirmUrl),
+      {
+        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(
@@ -162,6 +206,10 @@ var StowClient = class {
   }
   /**
    * Upload multiple files with optional concurrency
+   *
+   * - `concurrency=1` preserves strict sequential ordering.
+   * - `concurrency>1` uses a bounded worker pool and stops scheduling new files
+   *   after the first error.
    */
   async uploadFiles(files, options) {
     const fileArray = Array.from(files);

package/dist/index.mjs

@@ -11,18 +11,44 @@ var StowError = class extends Error {
 };
 var StowClient = class {
   endpoint;
+  /**
+   * @param config Server upload endpoint base path.
+   *
+   * The endpoint should expose:
+   * - `POST {endpoint}/presign`
+   * - `POST {endpoint}/confirm` (or a `confirmUrl` returned from presign)
+   */
   constructor(config) {
     if (typeof config === "string") {
-      this.endpoint = config;
+      this.endpoint = config.replace(/\/+$/, "");
     } else {
-      this.endpoint = config.endpoint;
+      this.endpoint = config.endpoint.replace(/\/+$/, "");
+    }
+  }
+  endpointUrl(path) {
+    if (!this.endpoint) {
+      return path;
+    }
+    return `${this.endpoint}${path}`;
+  }
+  resolveConfirmUrl(confirmUrl) {
+    if (!confirmUrl) {
+      return this.endpointUrl("/confirm");
+    }
+    if (confirmUrl.startsWith("/") || /^[a-z][a-z0-9+\-.]*:\/\//i.test(confirmUrl)) {
+      return confirmUrl;
     }
+    return this.endpointUrl(`/${confirmUrl.replace(/^\/+/, "")}`);
   }
   /**
    * 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.
+   *
+   * Dedup behavior:
+   * If presign responds with `{ dedupe: true, ... }`, upload skips R2 PUT and
+   * confirm entirely, returning the existing file metadata with `deduped: true`.
    */
   async uploadFile(file, options) {
     const { route, metadata, onProgress } = options || {};
@@ -32,7 +58,7 @@ var StowClient = class {
       percent: 0,
       phase: "presigning"
     });
-    const presignResponse = await fetch(`${this.endpoint}/presign`, {
+    const presignResponse = await fetch(this.endpointUrl("/presign"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -52,6 +78,21 @@ var StowClient = class {
       );
     }
     const presign = await presignResponse.json();
+    if ("dedupe" in presign && presign.dedupe) {
+      onProgress?.({
+        loaded: file.size,
+        total: file.size,
+        percent: 100,
+        phase: "confirming"
+      });
+      return {
+        key: presign.key,
+        url: presign.url,
+        size: presign.size,
+        contentType: presign.contentType,
+        deduped: true
+      };
+    }
     onProgress?.({
       loaded: 0,
       total: file.size,
@@ -72,16 +113,19 @@ var StowClient = class {
       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 } : {}
-      })
-    });
+    const confirmResponse = await fetch(
+      this.resolveConfirmUrl(presign.confirmUrl),
+      {
+        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(
@@ -137,6 +181,10 @@ var StowClient = class {
   }
   /**
    * Upload multiple files with optional concurrency
+   *
+   * - `concurrency=1` preserves strict sequential ordering.
+   * - `concurrency>1` uses a bounded worker pool and stops scheduling new files
+   *   after the first error.
    */
   async uploadFiles(files, options) {
     const fileArray = Array.from(files);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/stow-client",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Client-side SDK for Stow file storage",
   "license": "MIT",
   "repository": {
@@ -29,17 +29,17 @@
   "files": [
     "dist"
   ],
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@stow/typescript-config": "0.0.0"
+  },
   "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"
   }
-}
+}