@fragno-dev/upload 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,148 @@
-# Fragno Fragment
+# Upload Fragment
 
-You've created a new [Fragno](https://fragno.dev/) fragment!
+Full-stack upload fragment for Fragno. It supports direct-to-storage uploads (signed URLs), proxy
+uploads, and one-shot multipart form uploads. Strategy selection is driven by the storage adapter in
+`storage.initUpload` and the configured thresholds.
+
+## Upload Inventory
+
+Routes below are relative to the fragment mount (for example, `/api/uploads`). Upload session
+responses include the resolved `provider` plus canonical provider-sticky follow-up URLs:
+`statusEndpoint`, `progressEndpoint`, `completeEndpoint`, `abortEndpoint`, and the strategy-specific
+`partsEndpoint`, `partsCompleteEndpoint`, or `contentEndpoint` when applicable.
+
+**Direct single (signed URL to storage)** Steps:
+
+1. `POST /uploads` returns `uploadUrl`, `uploadHeaders`, and canonical follow-up URLs. Writes:
+   `upload`.
+2. Client `PUT` to the signed URL. Writes: none.
+3. `POST /uploads/:uploadId/complete`. Writes: `upload`, `file`.
+4. Optional `POST /uploads/:uploadId/progress`. Writes: `upload`.
+
+Storage ops: `initUpload` (before DB availability checks), optional `finalizeUpload` (before
+completion writes). DB ops: after `initUpload`, read `file` + `upload` (availability), write
+`upload`, then mark complete + insert `file`.
+
+**Direct multipart (signed part URLs)** Steps:
+
+1. `POST /uploads` creates the upload and returns canonical follow-up URLs. Writes: `upload`.
+2. `POST /uploads/:uploadId/parts` returns signed part URLs. Writes: none.
+3. Client `PUT` to part URLs. Writes: none.
+4. `POST /uploads/:uploadId/parts/complete`. Writes: `upload_part`, `upload`.
+5. `POST /uploads/:uploadId/complete`. Writes: `upload`, `file`.
+
+Storage ops: `initUpload` (before DB availability checks), `getPartUploadUrls`,
+`completeMultipartUpload`. DB ops: after `initUpload`, read `file` + `upload` (availability) and
+write `upload`; later read `upload`, write `upload_part` rows + progress, then mark complete +
+insert `file`.
+
+**Proxy stream (upload session)** Steps:
+
+1. `POST /uploads` creates the upload and returns canonical follow-up URLs. Writes: `upload`.
+2. `PUT /uploads/:uploadId/content` streams content through the fragment. Writes: `upload`, `file`.
+
+Storage ops: `initUpload` (before DB availability checks), `writeStream`. DB ops: after
+`initUpload`, read `file` + `upload` (availability) and write `upload`; then mark complete + insert
+`file` (or mark failed on storage error).
+
+**One-shot multipart form (server mediated)** Steps:
+
+1. `POST /files` with `multipart/form-data`. Writes: `upload`, `file`.
+2. Server chooses proxy stream or server-side `PUT` to `uploadUrl`. Writes: none.
+3. Upload finalizes on success. Writes: none.
+
+Storage ops: `initUpload`, `writeStream` OR server `PUT` to `uploadUrl`, optional `finalizeUpload`
+(before DB writes). DB ops: after storage succeeds, read availability, then create completed
+`upload` + `file` (or failed `upload` on error).
+
+Note: If `initUpload` returns `direct-multipart`, this route responds with
+`409 UPLOAD_INVALID_STATE` and you should use the multipart session flow instead.
+
+**Helpers (status, progress, abort)** Steps:
+
+1. `GET /uploads/:uploadId` fetches status. Writes: none.
+2. `POST /uploads/:uploadId/progress` records progress. Writes: `upload`.
+3. `POST /uploads/:uploadId/abort` cancels the upload. Writes: `upload`.
+
+Helper behavior note:
+
+- Official helpers use the returned canonical follow-up URLs instead of reconstructing
+  `/uploads/:uploadId/...` paths locally.
+- For proxy uploads (`PUT /uploads/:uploadId/content`), helpers try streamed upload first and then a
+  buffered fallback.
+- If both attempts fail at the transport layer, helpers throw an actionable error suggesting
+  `POST /files` (one-shot multipart) or switching to a direct strategy.
+
+## Upload Flow Diagram
+
+```mermaid
+flowchart TD
+  C[Client]
+  F[Upload Fragment]
+  S[(Storage Adapter)]
+  D[(DB)]
+
+  C -->|"POST /uploads"| F
+  F -->|"storage.initUpload"| S
+  F -->|"DB read: availability"| D
+  F -->|"DB write: create upload"| D
+
+  C -->|"PUT uploadUrl (direct single)"| S
+  C -->|"POST /uploads/:uploadId/complete"| F
+  F -->|"DB read: upload"| D
+  F -->|"storage.finalizeUpload (optional)"| S
+  F -->|"DB write: complete upload + file"| D
+
+  C -->|"POST /uploads/:uploadId/parts"| F
+  F -->|"DB read: upload"| D
+  F -->|"storage.getPartUploadUrls"| S
+  C -->|"PUT part URLs"| S
+  C -->|"POST /uploads/:uploadId/parts/complete"| F
+  F -->|"DB write: upload_part + progress"| D
+  C -->|"POST /uploads/:uploadId/complete"| F
+  F -->|"storage.completeMultipartUpload"| S
+  F -->|"DB write: complete upload + file"| D
+
+  C -->|"PUT /uploads/:uploadId/content (proxy)"| F
+  F -->|"storage.writeStream"| S
+  F -->|"DB write: complete upload + file"| D
+
+  C -->|"POST /files (multipart form)"| F
+  F -->|"storage.initUpload"| S
+  F -->|"storage.writeStream OR server PUT uploadUrl"| S
+  F -->|"storage.finalizeUpload (optional)"| S
+  F -->|"DB read: availability"| D
+  F -->|"DB write: completed upload + file"| D
+```
+
+## Durable Hooks and DB Entities
+
+Durable hooks are persisted to the internal `fragno_hooks` table when `uow.triggerHook(...)` is
+called inside a DB transaction. Hook execution is out-of-band and may re-read or update upload
+entities.
+
+**onUploadTimeout (scheduled when `POST /uploads` creates a new upload)** Steps:
+
+1. Writes: `fragno_hooks` (process time = `upload.expiresAt`, payload includes `uploadId`).
+2. When executed, reads: `upload`. If still active and expired, writes: `upload` (status `expired`,
+   error fields, timestamps).
+3. Invokes `config.onUploadFailed` (no DB writes from the hook itself).
+
+**onFileReady (after `upload` completes + `file` is created)** Steps:
+
+1. Writes: `fragno_hooks`.
+2. Hook execution is notification-only; no DB writes.
+
+**onUploadFailed (after upload failure or abort)** Steps:
+
+1. Writes: `fragno_hooks`.
+2. Hook execution is notification-only; no DB writes.
+
+**onFileDeleted (after `file` is marked deleted)** Steps:
+
+1. Writes: `fragno_hooks`.
+2. Hook execution deletes the storage object via `storage.deleteObject`.
+3. Invokes `config.onFileDeleted` (the storage delete is retried durably first).
 
 ## Build
 
@@ -22,10 +164,10 @@ node packages/fragment-upload/bin/run.js --help
 ```bash
 # Use the CLI (base URL points to the mounted upload fragment)
 fragno-upload --help
-fragno-upload uploads create -b https://host.example.com/api/uploads --file-key s~Zm9v --filename demo.txt --size-bytes 10 --content-type text/plain
-fragno-upload uploads transfer -b https://host.example.com/api/uploads -f ./demo.txt --file-key s~Zm9v
-fragno-upload files list -b https://host.example.com/api/uploads --prefix s~Zm9v.
-fragno-upload files download -b https://host.example.com/api/uploads --file-key s~Zm9v -o ./download.txt
+fragno-upload uploads create -b https://host.example.com/api/uploads --provider r2-binding --file-key users/42/avatar --filename demo.txt --size-bytes 10 --content-type text/plain
+fragno-upload uploads transfer -b https://host.example.com/api/uploads -f ./demo.txt --provider r2-binding --file-key users/42/avatar
+fragno-upload files list -b https://host.example.com/api/uploads --provider r2-binding --prefix users/42/
+fragno-upload files download -b https://host.example.com/api/uploads --provider r2-binding --file-key users/42/avatar -o ./download.txt
 ```
 
 Environment defaults:
@@ -35,9 +177,3 @@ Environment defaults:
 - `FRAGNO_UPLOAD_TIMEOUT_MS`
 - `FRAGNO_UPLOAD_RETRIES`
 - `FRAGNO_UPLOAD_RETRY_DELAY_MS`
-
-## Next Steps
-
-- Define your routes in `src/index.ts`
-- Add framework-specific clients in `src/client/`
-- See `AGENTS.md` for detailed development patterns

package/dist/browser/client/clients.js

@@ -14,7 +14,7 @@ function createUploadFragmentClients(config = {}) {
 	});
 	return {
 		useFiles: builder.createHook("/files"),
-		useFile: builder.createHook("/files/:fileKey"),
+		useFile: builder.createHook("/files/by-key"),
 		useCreateUpload: builder.createMutator("POST", "/uploads"),
 		useUploadStatus: builder.createHook("/uploads/:uploadId"),
 		useCompleteUpload: builder.createMutator("POST", "/uploads/:uploadId/complete", (invalidate, params) => {
@@ -28,16 +28,24 @@ function createUploadFragmentClients(config = {}) {
 			if (!uploadId) return;
 			invalidate("GET", "/uploads/:uploadId", { pathParams: { uploadId } });
 		}),
-		useUpdateFile: builder.createMutator("PATCH", "/files/:fileKey", (invalidate, params) => {
-			const fileKey = params.pathParams.fileKey;
-			if (!fileKey) return;
-			invalidate("GET", "/files/:fileKey", { pathParams: { fileKey } });
+		useUpdateFile: builder.createMutator("PATCH", "/files/by-key", (invalidate, params) => {
+			const provider = params.queryParams?.["provider"];
+			const key = params.queryParams?.["key"];
+			if (!provider || !key) return;
+			invalidate("GET", "/files/by-key", { queryParams: {
+				provider,
+				key
+			} });
 			invalidate("GET", "/files", {});
 		}),
-		useDeleteFile: builder.createMutator("DELETE", "/files/:fileKey", (invalidate, params) => {
-			const fileKey = params.pathParams.fileKey;
-			if (!fileKey) return;
-			invalidate("GET", "/files/:fileKey", { pathParams: { fileKey } });
+		useDeleteFile: builder.createMutator("DELETE", "/files/by-key", (invalidate, params) => {
+			const provider = params.queryParams?.["provider"];
+			const key = params.queryParams?.["key"];
+			if (!provider || !key) return;
+			invalidate("GET", "/files/by-key", { queryParams: {
+				provider,
+				key
+			} });
 			invalidate("GET", "/files", {});
 		}),
 		useUploadHelpers: builder.createStore(helpers)

package/dist/browser/client/clients.js.map

@@ -1 +1 @@
-{"version":3,"file":"clients.js","names":["createClientBuilder","FragnoPublicClientConfig","uploadFragmentDefinition","uploadRoutes","createUploadHelpers","createUploadFragmentClients","config","builder","fetcher","defaultOptions","getFetcher","helpers","buildUrl","path","useFiles","createHook","useFile","useCreateUpload","createMutator","useUploadStatus","useCompleteUpload","invalidate","params","uploadId","pathParams","useAbortUpload","useUpdateFile","fileKey","useDeleteFile","useUploadHelpers","createStore"],"sources":["../../../src/client/clients.ts"],"sourcesContent":["import { createClientBuilder } from \"@fragno-dev/core/client\";\nimport type { FragnoPublicClientConfig } from \"@fragno-dev/core/client\";\nimport { uploadFragmentDefinition } from \"../definition\";\nimport { uploadRoutes } from \"../routes\";\nimport { createUploadHelpers } from \"./helpers\";\n\nexport function createUploadFragmentClients(config: FragnoPublicClientConfig = {}) {\n  const builder = createClientBuilder(uploadFragmentDefinition, config, uploadRoutes);\n  const { fetcher, defaultOptions } = builder.getFetcher();\n  const helpers = createUploadHelpers({\n    buildUrl: (path) => builder.buildUrl(path),\n    fetcher,\n    defaultOptions,\n  });\n\n  return {\n    useFiles: builder.createHook(\"/files\"),\n    useFile: builder.createHook(\"/files/:fileKey\"),\n    useCreateUpload: builder.createMutator(\"POST\", \"/uploads\"),\n    useUploadStatus: builder.createHook(\"/uploads/:uploadId\"),\n    useCompleteUpload: builder.createMutator(\n      \"POST\",\n      \"/uploads/:uploadId/complete\",\n      (invalidate, params) => {\n        const uploadId = params.pathParams.uploadId;\n        if (!uploadId) {\n          return;\n        }\n        invalidate(\"GET\", \"/uploads/:uploadId\", { pathParams: { uploadId } });\n        invalidate(\"GET\", \"/files\", {});\n      },\n    ),\n    useAbortUpload: builder.createMutator(\n      \"POST\",\n      \"/uploads/:uploadId/abort\",\n      (invalidate, params) => {\n        const uploadId = params.pathParams.uploadId;\n        if (!uploadId) {\n          return;\n        }\n        invalidate(\"GET\", \"/uploads/:uploadId\", { pathParams: { uploadId } });\n      },\n    ),\n    useUpdateFile: builder.createMutator(\"PATCH\", \"/files/:fileKey\", (invalidate, params) => {\n      const fileKey = params.pathParams.fileKey;\n      if (!fileKey) {\n        return;\n      }\n      invalidate(\"GET\", \"/files/:fileKey\", { pathParams: { fileKey } });\n      invalidate(\"GET\", \"/files\", {});\n    }),\n    useDeleteFile: builder.createMutator(\"DELETE\", \"/files/:fileKey\", (invalidate, params) => {\n      const fileKey = params.pathParams.fileKey;\n      if (!fileKey) {\n        return;\n      }\n      invalidate(\"GET\", \"/files/:fileKey\", { pathParams: { fileKey } });\n      invalidate(\"GET\", \"/files\", {});\n    }),\n    useUploadHelpers: builder.createStore(helpers),\n  };\n}\n"],"mappings":";;;;;;AAMA,SAAgBK,4BAA4BC,SAAmC,EAAE,EAAE;CACjF,MAAMC,UAAUP,oBAAoBE,0BAA0BI,QAAQH,aAAa;CACnF,MAAM,EAAEK,SAASC,mBAAmBF,QAAQG,YAAY;CACxD,MAAMC,UAAUP,oBAAoB;EAClCQ,WAAWC,SAASN,QAAQK,SAASC,KAAK;EAC1CL;EACAC;EACD,CAAC;AAEF,QAAO;EACLK,UAAUP,QAAQQ,WAAW,SAAS;EACtCC,SAAST,QAAQQ,WAAW,kBAAkB;EAC9CE,iBAAiBV,QAAQW,cAAc,QAAQ,WAAW;EAC1DC,iBAAiBZ,QAAQQ,WAAW,qBAAqB;EACzDK,mBAAmBb,QAAQW,cACzB,QACA,gCACCG,YAAYC,WAAW;GACtB,MAAMC,WAAWD,OAAOE,WAAWD;AACnC,OAAI,CAACA,SACH;AAEFF,cAAW,OAAO,sBAAsB,EAAEG,YAAY,EAAED,UAAS,EAAG,CAAC;AACrEF,cAAW,OAAO,UAAU,EAAE,CAAC;IAElC;EACDI,gBAAgBlB,QAAQW,cACtB,QACA,6BACCG,YAAYC,WAAW;GACtB,MAAMC,WAAWD,OAAOE,WAAWD;AACnC,OAAI,CAACA,SACH;AAEFF,cAAW,OAAO,sBAAsB,EAAEG,YAAY,EAAED,UAAS,EAAG,CAAC;IAExE;EACDG,eAAenB,QAAQW,cAAc,SAAS,oBAAoBG,YAAYC,WAAW;GACvF,MAAMK,UAAUL,OAAOE,WAAWG;AAClC,OAAI,CAACA,QACH;AAEFN,cAAW,OAAO,mBAAmB,EAAEG,YAAY,EAAEG,SAAQ,EAAG,CAAC;AACjEN,cAAW,OAAO,UAAU,EAAE,CAAC;IAC/B;EACFO,eAAerB,QAAQW,cAAc,UAAU,oBAAoBG,YAAYC,WAAW;GACxF,MAAMK,UAAUL,OAAOE,WAAWG;AAClC,OAAI,CAACA,QACH;AAEFN,cAAW,OAAO,mBAAmB,EAAEG,YAAY,EAAEG,SAAQ,EAAG,CAAC;AACjEN,cAAW,OAAO,UAAU,EAAE,CAAC;IAC/B;EACFQ,kBAAkBtB,QAAQuB,YAAYnB,QAAO;EAC9C"}
+{"version":3,"file":"clients.js","names":["createClientBuilder","FragnoPublicClientConfig","uploadFragmentDefinition","uploadRoutes","createUploadHelpers","createUploadFragmentClients","config","builder","fetcher","defaultOptions","getFetcher","helpers","buildUrl","path","useFiles","createHook","useFile","useCreateUpload","createMutator","useUploadStatus","useCompleteUpload","invalidate","params","uploadId","pathParams","useAbortUpload","useUpdateFile","provider","queryParams","key","useDeleteFile","useUploadHelpers","createStore"],"sources":["../../../src/client/clients.ts"],"sourcesContent":["import { createClientBuilder } from \"@fragno-dev/core/client\";\nimport type { FragnoPublicClientConfig } from \"@fragno-dev/core/client\";\n\nimport { uploadFragmentDefinition } from \"../definition\";\nimport { uploadRoutes } from \"../routes\";\nimport { createUploadHelpers } from \"./helpers\";\n\nexport function createUploadFragmentClients(config: FragnoPublicClientConfig = {}) {\n  const builder = createClientBuilder(uploadFragmentDefinition, config, uploadRoutes);\n  const { fetcher, defaultOptions } = builder.getFetcher();\n  const helpers = createUploadHelpers({\n    buildUrl: (path) => builder.buildUrl(path),\n    fetcher,\n    defaultOptions,\n  });\n\n  return {\n    useFiles: builder.createHook(\"/files\"),\n    useFile: builder.createHook(\"/files/by-key\"),\n    useCreateUpload: builder.createMutator(\"POST\", \"/uploads\"),\n    useUploadStatus: builder.createHook(\"/uploads/:uploadId\"),\n    useCompleteUpload: builder.createMutator(\n      \"POST\",\n      \"/uploads/:uploadId/complete\",\n      (invalidate, params) => {\n        const uploadId = params.pathParams.uploadId;\n        if (!uploadId) {\n          return;\n        }\n        invalidate(\"GET\", \"/uploads/:uploadId\", { pathParams: { uploadId } });\n        invalidate(\"GET\", \"/files\", {});\n      },\n    ),\n    useAbortUpload: builder.createMutator(\n      \"POST\",\n      \"/uploads/:uploadId/abort\",\n      (invalidate, params) => {\n        const uploadId = params.pathParams.uploadId;\n        if (!uploadId) {\n          return;\n        }\n        invalidate(\"GET\", \"/uploads/:uploadId\", { pathParams: { uploadId } });\n      },\n    ),\n    useUpdateFile: builder.createMutator(\"PATCH\", \"/files/by-key\", (invalidate, params) => {\n      const provider = params.queryParams?.[\"provider\"];\n      const key = params.queryParams?.[\"key\"];\n      if (!provider || !key) {\n        return;\n      }\n      invalidate(\"GET\", \"/files/by-key\", { queryParams: { provider, key } });\n      invalidate(\"GET\", \"/files\", {});\n    }),\n    useDeleteFile: builder.createMutator(\"DELETE\", \"/files/by-key\", (invalidate, params) => {\n      const provider = params.queryParams?.[\"provider\"];\n      const key = params.queryParams?.[\"key\"];\n      if (!provider || !key) {\n        return;\n      }\n      invalidate(\"GET\", \"/files/by-key\", { queryParams: { provider, key } });\n      invalidate(\"GET\", \"/files\", {});\n    }),\n    useUploadHelpers: builder.createStore(helpers),\n  };\n}\n"],"mappings":";;;;;;AAOA,SAAgBK,4BAA4BC,SAAmC,EAAE,EAAE;CACjF,MAAMC,UAAUP,oBAAoBE,0BAA0BI,QAAQH,aAAa;CACnF,MAAM,EAAEK,SAASC,mBAAmBF,QAAQG,YAAY;CACxD,MAAMC,UAAUP,oBAAoB;EAClCQ,WAAWC,SAASN,QAAQK,SAASC,KAAK;EAC1CL;EACAC;EACD,CAAC;AAEF,QAAO;EACLK,UAAUP,QAAQQ,WAAW,SAAS;EACtCC,SAAST,QAAQQ,WAAW,gBAAgB;EAC5CE,iBAAiBV,QAAQW,cAAc,QAAQ,WAAW;EAC1DC,iBAAiBZ,QAAQQ,WAAW,qBAAqB;EACzDK,mBAAmBb,QAAQW,cACzB,QACA,gCACCG,YAAYC,WAAW;GACtB,MAAMC,WAAWD,OAAOE,WAAWD;AACnC,OAAI,CAACA,SACH;AAEFF,cAAW,OAAO,sBAAsB,EAAEG,YAAY,EAAED,UAAS,EAAG,CAAC;AACrEF,cAAW,OAAO,UAAU,EAAE,CAAC;IAElC;EACDI,gBAAgBlB,QAAQW,cACtB,QACA,6BACCG,YAAYC,WAAW;GACtB,MAAMC,WAAWD,OAAOE,WAAWD;AACnC,OAAI,CAACA,SACH;AAEFF,cAAW,OAAO,sBAAsB,EAAEG,YAAY,EAAED,UAAS,EAAG,CAAC;IAExE;EACDG,eAAenB,QAAQW,cAAc,SAAS,kBAAkBG,YAAYC,WAAW;GACrF,MAAMK,WAAWL,OAAOM,cAAc;GACtC,MAAMC,MAAMP,OAAOM,cAAc;AACjC,OAAI,CAACD,YAAY,CAACE,IAChB;AAEFR,cAAW,OAAO,iBAAiB,EAAEO,aAAa;IAAED;IAAUE;IAAI,EAAG,CAAC;AACtER,cAAW,OAAO,UAAU,EAAE,CAAC;IAC/B;EACFS,eAAevB,QAAQW,cAAc,UAAU,kBAAkBG,YAAYC,WAAW;GACtF,MAAMK,WAAWL,OAAOM,cAAc;GACtC,MAAMC,MAAMP,OAAOM,cAAc;AACjC,OAAI,CAACD,YAAY,CAACE,IAChB;AAEFR,cAAW,OAAO,iBAAiB,EAAEO,aAAa;IAAED;IAAUE;IAAI,EAAG,CAAC;AACtER,cAAW,OAAO,UAAU,EAAE,CAAC;IAC/B;EACFU,kBAAkBxB,QAAQyB,YAAYrB,QAAO;EAC9C"}

package/dist/browser/client/helpers.d.ts

@@ -1,4 +1,3 @@
-import { FileKeyEncoded, FileKeyParts } from "./packages/fragment-upload/src/keys.js";
 import { UploadChecksum } from "./packages/fragment-upload/src/storage/types.js";
 import { FileMetadata, FileVisibility, UploadStrategy } from "./packages/fragment-upload/src/types.js";
 
@@ -10,8 +9,8 @@ type UploadProgress = {
   totalParts?: number;
 };
 type CreateUploadAndTransferOptions = {
-  keyParts?: FileKeyParts;
-  fileKey?: FileKeyEncoded;
+  provider: string;
+  fileKey: string;
   filename?: string;
   contentType?: string;
   checksum?: UploadChecksum | null;
@@ -21,10 +20,16 @@ type CreateUploadAndTransferOptions = {
   metadata?: Record<string, unknown>;
   onProgress?: (progress: UploadProgress) => void;
 };
+type DownloadMethod = "signed-url" | "content";
+type DownloadFileOptions = {
+  provider: string;
+  method: DownloadMethod;
+};
 type UploadCreateResponse = {
   uploadId: string;
   fileKey: string;
-  status: "created";
+  provider: string;
+  status: "created" | "in_progress";
   strategy: UploadStrategy;
   expiresAt: string;
   upload: {
@@ -34,8 +39,12 @@ type UploadCreateResponse = {
     uploadHeaders?: Record<string, string>;
     partSizeBytes?: number;
     maxParts?: number;
+    statusEndpoint: string;
+    progressEndpoint: string;
     partsEndpoint?: string;
+    partsCompleteEndpoint?: string;
     completeEndpoint: string;
+    abortEndpoint: string;
     contentEndpoint?: string;
   };
 };
@@ -44,8 +53,8 @@ type UploadHelpers = {
     upload: UploadCreateResponse;
     file: FileMetadata;
   }>;
-  downloadFile: (fileKeyOrParts: FileKeyEncoded | FileKeyParts) => Promise<Response>;
+  downloadFile: (fileKey: string, options: DownloadFileOptions) => Promise<Response>;
 };
 //#endregion
-export { CreateUploadAndTransferOptions, UploadCreateResponse, UploadHelpers };
+export { CreateUploadAndTransferOptions, DownloadFileOptions, UploadCreateResponse, UploadHelpers };
 //# sourceMappingURL=helpers.d.ts.map

package/dist/browser/client/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","names":[],"sources":["../../../src/client/helpers.ts"],"sourcesContent":[],"mappings":";;;;;KAIY,cAAA;;EAAA,UAAA,EAAA,MAAc;EAOd,aAAA,EAAA,MAAA;EAA8B,UAAA,CAAA,EAAA,MAAA;;AAE9B,KAFA,8BAAA,GAEA;UAGC,CAAA,EAJA,YAIA;SAEE,CAAA,EALH,cAKG;UAEF,CAAA,EAAA,MAAA;aACa,CAAA,EAAA,MAAA;EAAc,QAAA,CAAA,EAL3B,cAK2B,GAAA,IAAA;EAG5B,IAAA,CAAA,EAAA,MAAA,EAAA;EAAoB,UAAA,CAAA,EANjB,cAMiB;YAIpB,CAAA,EAAA,MAAA;UAMQ,CAAA,EAdP,MAcO,CAAA,MAAA,EAAA,OAAA,CAAA;EAAM,UAAA,CAAA,EAAA,CAAA,QAAA,EAbA,cAaA,EAAA,GAAA,IAAA;AAS1B,CAAA;AAAyB,KAnBb,oBAAA,GAmBa;UAEf,EAAA,MAAA;SACG,EAAA,MAAA;QACY,EAAA,SAAA;UAA4B,EAnBzC,cAmByC;WAA9C,EAAA,MAAA;QAC0B,EAAA;IAAiB,IAAA,EAAA,QAAA,GAAA,WAAA;IAAyB,SAAA,EAAA,QAAA,GAAA,OAAA;IAAR,SAAA,CAAA,EAAA,MAAA;IAAO,aAAA,CAAA,EAdtD,MAcsD,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;;;KAL9D,aAAA;kCAEF,eACG,mCACN;YAAkB;UAA4B;;iCACpB,iBAAiB,iBAAiB,QAAQ"}
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../../../src/client/helpers.ts"],"sourcesContent":[],"mappings":";;;;KAGY,cAAA;;EAAA,UAAA,EAAA,MAAc;EAOd,aAAA,EAAA,MAAA;EAA8B,UAAA,CAAA,EAAA,MAAA;;AAO3B,KAPH,8BAAA,GAOG;UAEF,EAAA,MAAA;SACa,EAAA,MAAA;EAAc,QAAA,CAAA,EAAA,MAAA;EAG5B,WAAA,CAAA,EAAA,MAAc;EAEd,QAAA,CAAA,EAVC,cAUkB,GAAA,IAErB;EAGE,IAAA,CAAA,EAAA,MAAA,EAAA;EAAoB,UAAA,CAAA,EAbjB,cAaiB;YAKpB,CAAA,EAAA,MAAA;UAMQ,CAAA,EAtBP,MAsBO,CAAA,MAAA,EAAA,OAAA,CAAA;EAAM,UAAA,CAAA,EAAA,CAAA,QAAA,EArBA,cAqBA,EAAA,GAAA,IAAA;AAa1B,CAAA;AAAyB,KA/Bb,cAAA,GA+Ba,YAAA,GAAA,SAAA;AAEf,KA/BE,mBAAA,GA+BF;UACG,EAAA,MAAA;QACY,EA/Bf,cA+Be;;AAAlB,KA5BK,oBAAA,GA4BL;UACoC,EAAA,MAAA;SAAgC,EAAA,MAAA;UAAR,EAAA,MAAA;EAAO,MAAA,EAAA,SAAA,GAAA,aAAA;YAxB9D;;;;;;oBAMQ;;;;;;;;;;;;KAaR,aAAA;kCAEF,eACG,mCACN;YAAkB;UAA4B;;2CACV,wBAAwB,QAAQ"}

package/dist/browser/client/helpers.js

@@ -1,7 +1,8 @@
-import { encodeFileKey } from "./packages/fragment-upload/src/keys.js";
-
 //#region src/client/helpers.ts
 const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+const PROXY_UPLOAD_STRATEGY_HINT = "Server selected proxy upload strategy for this file (no direct upload URL was returned). If you expected direct-to-storage upload, your active provider/config does not support direct upload for this request.";
+const PROXY_UPLOAD_RECOVERY_HINT = "Verify the /uploads/:uploadId/content endpoint is reachable from the client, or switch provider/config so /uploads returns a direct strategy.";
+const DOWNLOAD_METHOD_HINT = "Pick the download method explicitly: use 'signed-url' for GET /files/by-key/download-url, otherwise use 'content' for GET /files/by-key/content.";
 const mergeHeaders = (base, next) => {
 	const merged = new Headers(base ?? void 0);
 	if (!next) return merged;
@@ -25,6 +26,74 @@ const readJsonSafely = async (response) => {
 		return null;
 	}
 };
+const toErrorMessage = (error) => {
+	if (error instanceof Error && error.message) return error.message;
+	if (typeof error === "string" && error.length > 0) return error;
+	return "Unknown network error";
+};
+const readMessageFromPayload = (payload) => {
+	if (payload && typeof payload === "object" && "message" in payload && typeof payload.message === "string" && payload.message.length > 0) return payload.message;
+	return null;
+};
+const toAbsoluteUrl = (url) => {
+	try {
+		if (typeof window !== "undefined" && window.location?.origin) return new URL(url, window.location.origin);
+		return new URL(url, "http://fragno.local");
+	} catch {
+		return null;
+	}
+};
+const validateProxyContentUrl = (url) => {
+	const parsed = toAbsoluteUrl(url);
+	if (!parsed) return `Proxy upload endpoint '${url}' is not a valid URL.`;
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return `Proxy upload endpoint '${url}' must use http:// or https://.`;
+	if (typeof window !== "undefined" && window.location?.protocol === "https:" && parsed.protocol === "http:") return `Proxy upload endpoint '${url}' uses http:// on a https:// page.`;
+	return null;
+};
+const buildProxyUploadErrorMessage = (input) => {
+	const detailLines = [];
+	if (typeof input.status === "number") detailLines.push(`response status ${input.status}`);
+	if (input.streamError !== void 0) detailLines.push(`streamed upload error: ${toErrorMessage(input.streamError)}`);
+	if (input.fallbackError !== void 0) detailLines.push(`buffered upload error: ${toErrorMessage(input.fallbackError)}`);
+	const details = detailLines.length > 0 ? ` Details: ${detailLines.join(" | ")}.` : "";
+	return `${PROXY_UPLOAD_STRATEGY_HINT} Proxy upload to '${input.endpointUrl}' failed.${details} ${PROXY_UPLOAD_RECOVERY_HINT}`;
+};
+const buildDownloadRequestErrorMessage = (input) => {
+	const detailLines = [];
+	if (typeof input.status === "number") detailLines.push(`response status ${input.status}`);
+	const payloadMessage = readMessageFromPayload(input.payload);
+	if (payloadMessage) detailLines.push(`message: ${payloadMessage}`);
+	if (input.requestError !== void 0) detailLines.push(`request error: ${toErrorMessage(input.requestError)}`);
+	const details = detailLines.length > 0 ? ` Details: ${detailLines.join(" | ")}.` : "";
+	const hint = input.hint ? ` ${input.hint}` : "";
+	return `Download request to '${input.endpointUrl}' failed.${details}${hint}`;
+};
+const sanitizeSignedDownloadUrl = (url) => {
+	try {
+		const parsed = new URL(url);
+		parsed.search = "";
+		parsed.hash = "";
+		return parsed.toString();
+	} catch {
+		return "<redacted-signed-url>";
+	}
+};
+const readErrorCodeFromPayload = (payload) => {
+	if (payload && typeof payload === "object" && "code" in payload) {
+		const code = payload.code;
+		if (typeof code === "string" && code.length > 0) return code;
+	}
+	return null;
+};
+const hasText = (value) => typeof value === "string" && value.trim().length > 0;
+const requireUploadEndpoint = (endpoint, label) => {
+	if (!hasText(endpoint)) throw new Error(`Missing ${label} endpoint for upload`);
+	return endpoint;
+};
+const buildByKeyQuery = (provider, fileKey) => new URLSearchParams({
+	provider,
+	key: fileKey
+}).toString();
 const createUploadHelpers = (input) => {
 	const { buildUrl, fetcher, defaultOptions } = input;
 	const fetchJson = async (path, init, expectedErrorCode) => {
@@ -38,9 +107,9 @@ const createUploadHelpers = (input) => {
 		}
 		return await response.json();
 	};
-	const reportProgress = async (uploadId, progress, onProgress) => {
+	const reportProgress = async (progressEndpoint, progress, onProgress) => {
 		onProgress?.(progress);
-		await fetchJson(`/uploads/${uploadId}/progress`, {
+		await fetchJson(progressEndpoint, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({
@@ -53,12 +122,13 @@ const createUploadHelpers = (input) => {
 		const filename = options.filename ?? (typeof File !== "undefined" && file instanceof File && file.name ? file.name : "upload");
 		const contentType = options.contentType ?? (file.type && file.type.length > 0 ? file.type : void 0) ?? DEFAULT_CONTENT_TYPE;
 		const sizeBytes = file.size;
-		if (!options.keyParts && !options.fileKey) throw new Error("File key parts or file key is required");
+		if (!hasText(options.provider)) throw new Error("Provider is required");
+		if (!hasText(options.fileKey)) throw new Error("File key is required");
 		const upload = await fetchJson("/uploads", {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({
-				keyParts: options.keyParts,
+				provider: options.provider,
 				fileKey: options.fileKey,
 				filename,
 				sizeBytes,
@@ -73,6 +143,7 @@ const createUploadHelpers = (input) => {
 		const totalBytes = sizeBytes;
 		let bytesUploaded = 0;
 		let partsUploaded = 0;
+		const progressEndpoint = requireUploadEndpoint(upload.upload.progressEndpoint, "progress");
 		if (upload.strategy === "direct-single") {
 			if (!upload.upload.uploadUrl) throw new Error("Missing upload URL for direct upload");
 			const uploadResponse = await fetcher(upload.upload.uploadUrl, {
@@ -83,7 +154,7 @@ const createUploadHelpers = (input) => {
 			if (!uploadResponse.ok) throw new Error(`Direct upload failed (${uploadResponse.status})`);
 			bytesUploaded = totalBytes;
 			partsUploaded = 1;
-			await reportProgress(upload.uploadId, {
+			await reportProgress(progressEndpoint, {
 				bytesUploaded,
 				totalBytes,
 				partsUploaded,
@@ -101,6 +172,7 @@ const createUploadHelpers = (input) => {
 		if (upload.strategy === "direct-multipart") {
 			const partSizeBytes = upload.upload.partSizeBytes;
 			if (!partSizeBytes || !upload.upload.partsEndpoint) throw new Error("Missing multipart configuration for upload");
+			const partsCompleteEndpoint = requireUploadEndpoint(upload.upload.partsCompleteEndpoint, "multipart completion");
 			const totalParts = Math.ceil(totalBytes / partSizeBytes);
 			if (upload.upload.maxParts && totalParts > upload.upload.maxParts) throw new Error("Multipart upload exceeds maximum parts");
 			const partNumbers = Array.from({ length: totalParts }, (_, i) => i + 1);
@@ -135,14 +207,14 @@ const createUploadHelpers = (input) => {
 				});
 				bytesUploaded += partSize;
 				partsUploaded += 1;
-				await reportProgress(upload.uploadId, {
+				await reportProgress(progressEndpoint, {
 					bytesUploaded,
 					totalBytes,
 					partsUploaded,
 					totalParts
 				}, options.onProgress);
 			}
-			await fetchJson(`/uploads/${upload.uploadId}/parts/complete`, {
+			await fetchJson(partsCompleteEndpoint, {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
 				body: JSON.stringify({ parts: completedParts })
@@ -157,6 +229,9 @@ const createUploadHelpers = (input) => {
 			};
 		}
 		if (!upload.upload.contentEndpoint) throw new Error("Missing proxy content endpoint for upload");
+		const proxyContentUrl = buildUrl(upload.upload.contentEndpoint);
+		const proxyUrlValidationError = validateProxyContentUrl(proxyContentUrl);
+		if (proxyUrlValidationError) throw new Error(`${proxyUrlValidationError} ${PROXY_UPLOAD_RECOVERY_HINT}`);
 		const source = file.stream();
 		const stream = new ReadableStream({ start(controller) {
 			const reader = source.getReader();
@@ -190,14 +265,27 @@ const createUploadHelpers = (input) => {
 		requestInit.duplex = "half";
 		let proxyResponse;
 		try {
-			proxyResponse = await fetcher(buildUrl(upload.upload.contentEndpoint), requestInit);
-		} catch (_error) {
-			const fallbackResponse = await fetcher(buildUrl(upload.upload.contentEndpoint), buildRequestInit(defaultOptions, {
-				method: "PUT",
-				headers: { "Content-Type": DEFAULT_CONTENT_TYPE },
-				body: file
+			proxyResponse = await fetcher(proxyContentUrl, requestInit);
+		} catch (streamError) {
+			let fallbackResponse;
+			try {
+				fallbackResponse = await fetcher(proxyContentUrl, buildRequestInit(defaultOptions, {
+					method: "PUT",
+					headers: { "Content-Type": DEFAULT_CONTENT_TYPE },
+					body: file
+				}));
+			} catch (fallbackError) {
+				throw new Error(buildProxyUploadErrorMessage({
+					endpointUrl: proxyContentUrl,
+					streamError,
+					fallbackError
+				}));
+			}
+			if (!fallbackResponse.ok) throw new Error(buildProxyUploadErrorMessage({
+				endpointUrl: proxyContentUrl,
+				status: fallbackResponse.status,
+				streamError
 			}));
-			if (!fallbackResponse.ok) throw new Error(`Proxy upload failed (${fallbackResponse.status})`);
 			options.onProgress?.({
 				bytesUploaded: totalBytes,
 				totalBytes,
@@ -208,28 +296,86 @@ const createUploadHelpers = (input) => {
 				file: await fallbackResponse.json()
 			};
 		}
-		if (!proxyResponse.ok) throw new Error(`Proxy upload failed (${proxyResponse.status})`);
+		if (!proxyResponse.ok) throw new Error(buildProxyUploadErrorMessage({
+			endpointUrl: proxyContentUrl,
+			status: proxyResponse.status
+		}));
 		return {
 			upload,
 			file: await proxyResponse.json()
 		};
 	};
-	const downloadFile = async (fileKeyOrParts) => {
-		const fileKey = Array.isArray(fileKeyOrParts) ? encodeFileKey(fileKeyOrParts) : fileKeyOrParts;
-		const downloadUrlResponse = await fetcher(buildUrl(`/files/${fileKey}/download-url`), buildRequestInit(defaultOptions, { method: "GET" }));
-		if (downloadUrlResponse.ok) {
+	const downloadFile = async (fileKey, options) => {
+		if (!hasText(fileKey)) throw new Error("File key is required");
+		if (!options || !hasText(options.provider)) throw new Error("Download provider is required");
+		if (!options || options.method !== "signed-url" && options.method !== "content") throw new Error(`Download method is required. ${DOWNLOAD_METHOD_HINT}`);
+		const byKeyQuery = buildByKeyQuery(options.provider, fileKey);
+		if (options.method === "signed-url") {
+			const downloadUrlEndpoint = buildUrl(`/files/by-key/download-url?${byKeyQuery}`);
+			let downloadUrlResponse;
+			try {
+				downloadUrlResponse = await fetcher(downloadUrlEndpoint, buildRequestInit(defaultOptions, { method: "GET" }));
+			} catch (error) {
+				throw new Error(buildDownloadRequestErrorMessage({
+					endpointUrl: downloadUrlEndpoint,
+					requestError: error
+				}));
+			}
+			if (!downloadUrlResponse.ok) {
+				const errorPayload = await readJsonSafely(downloadUrlResponse);
+				const hint = readErrorCodeFromPayload(errorPayload) === "SIGNED_URL_UNSUPPORTED" ? "Requested method 'signed-url' is unsupported by this storage adapter. This is a programming error. Use method 'content' when streaming downloads are available." : void 0;
+				throw new Error(buildDownloadRequestErrorMessage({
+					endpointUrl: downloadUrlEndpoint,
+					status: downloadUrlResponse.status,
+					payload: errorPayload,
+					hint
+				}));
+			}
 			const payload = await downloadUrlResponse.json();
-			return fetcher(payload.url, {
-				method: "GET",
-				headers: payload.headers
-			});
+			const sanitizedUrl = sanitizeSignedDownloadUrl(payload.url);
+			let response;
+			try {
+				response = await fetcher(payload.url, {
+					method: "GET",
+					headers: payload.headers
+				});
+			} catch (error) {
+				throw new Error(buildDownloadRequestErrorMessage({
+					endpointUrl: sanitizedUrl,
+					requestError: error
+				}));
+			}
+			if (!response.ok) {
+				const payloadError = await readJsonSafely(response);
+				throw new Error(buildDownloadRequestErrorMessage({
+					endpointUrl: sanitizedUrl,
+					status: response.status,
+					payload: payloadError
+				}));
+			}
+			return response;
 		}
-		const errorPayload = await readJsonSafely(downloadUrlResponse);
-		if ((typeof errorPayload === "object" && errorPayload ? errorPayload.code : void 0) !== "SIGNED_URL_UNSUPPORTED") {
-			const message = typeof errorPayload === "object" && errorPayload && "message" in errorPayload ? String(errorPayload.message) : `Download failed (${downloadUrlResponse.status})`;
-			throw new Error(message);
+		const contentEndpoint = buildUrl(`/files/by-key/content?${byKeyQuery}`);
+		let contentResponse;
+		try {
+			contentResponse = await fetcher(contentEndpoint, buildRequestInit(defaultOptions, { method: "GET" }));
+		} catch (error) {
+			throw new Error(buildDownloadRequestErrorMessage({
+				endpointUrl: contentEndpoint,
+				requestError: error
+			}));
+		}
+		if (!contentResponse.ok) {
+			const contentError = await readJsonSafely(contentResponse);
+			const hint = readErrorCodeFromPayload(contentError) === "SIGNED_URL_UNSUPPORTED" ? "The 'content' download endpoint is unsupported by this storage adapter. This request used method 'content'. Use method 'signed-url' when signed downloads are available." : void 0;
+			throw new Error(buildDownloadRequestErrorMessage({
+				endpointUrl: contentEndpoint,
+				status: contentResponse.status,
+				payload: contentError,
+				hint
+			}));
 		}
-		return fetcher(buildUrl(`/files/${fileKey}/content`), buildRequestInit(defaultOptions, { method: "GET" }));
+		return contentResponse;
 	};
 	return {
 		createUploadAndTransfer,