@finueva/drive 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @finueva/drive
 
+## 0.29.0
+
+### Minor Changes
+
+- 07e8b11: Report native upload progress and replace the fixed 30-second object PUT deadline with stall detection. `uploadVerifiedFile` now reports bytes hashed and bytes sent through the existing `onProgress` callback, with a `stage` (`hashing`, `preparing`, `uploading`, `completing`) and non-decreasing `hashedByteLength` and `sentByteLength`; earlier fields keep their meaning. Browsers and webviews send a cross-origin object PUT through `XMLHttpRequest` when no custom `fetch` is configured, and `createUploadProgressFetch` gives a custom `fetch` the same capability; Workers, Node and other `fetch` transports keep coarse events. The PUT is now bounded by the capability expiry, by a configurable stall window (`upload.stallTimeoutMilliseconds`, default 30 seconds) and by an overall cap only when `upload.maxDurationMilliseconds` or an explicit `timeoutMilliseconds` is set, so a slow transfer that keeps moving is no longer aborted. A measured transfer that stops before its last byte now rejects with `timeout` or `network_error` instead of attempting publication. All additions are optional.
+
 ## 0.28.0
 
 ### Minor Changes

package/README.md

@@ -71,7 +71,7 @@ const uploaded = await drive.uploadVerifiedFile({
 });
 ```
 
-The provider runs once for every request. The SDK sends its result only as `Authorization: Bearer`, always sets `credentials: "omit"` and `cache: "no-store"`, and never reads cookies. Configuration does not accept default headers. Credential acquisition, Fetch, and response handling share one bounded request deadline: 30 seconds by default, configurable from 1 millisecond through 120 seconds.
+The provider runs once for every request. The SDK sends its result only as `Authorization: Bearer`, always sets `credentials: "omit"` and `cache: "no-store"`, and never reads cookies. Configuration does not accept default headers. Credential acquisition, Fetch, and response handling share one bounded request deadline: 30 seconds by default, configurable from 1 millisecond through 120 seconds. The object PUT behind `uploadVerifiedFile` is not bound by that default; see [Upload progress and stall detection](#upload-progress-and-stall-detection).
 
 `auth` is a configured `@finueva/auth` client. Select the exact personal or organization workspace. Native Fetch needs no wrapper.
 
@@ -204,12 +204,38 @@ A create target is `{ type: "create", parentItemId, name }`. A replacement is `{
 
 Generate the prepare key with `createVerifiedOperationKey()`, then retain that key, the completion key and the exact source/intent for retry. The key has a fixed 24-hour replay deadline; new keys permit bounded client clock skew. Retired, expired or incorrectly issued keys return actionable closed reasons. They never authorize silently creating a new operation. An interrupted prepare or publication permits at most one immediate retry for network errors/timeouts. A lost PUT response or immutable create-only `412` proceeds to publication without a caller ETag; Drive must independently prove the exact retained object. A published prepare replay performs no provider PUT. Recovery returns only the current capability for that original admitted operation.
 
-The generic helper supports zero through 1 GiB and incrementally hashes in 256 KiB windows. It does not materialize the whole source as an ArrayBuffer or base64 string. Signed provider headers require whole SHA-256, exact content type and length, `cache-control: no-store, no-transform`, immutable `if-none-match: *`, and the complete encryption tuple when present. Requests omit user authority, cookies and referrers; redirects are refused. The SDK validates the returned canonical receipt against the source and requested classification. An ETag is provider identity, not a substitute for the checksum.
+The generic helper supports zero through 1 GiB and incrementally hashes in 256 KiB windows. It does not materialize the whole source as an ArrayBuffer or base64 string. Signed provider headers require whole SHA-256, exact content type and length, `cache-control: no-store, no-transform`, immutable `if-none-match: *`, and the complete encryption tuple when present. Requests omit user authority, cookies and referrers; redirects are refused. The browser `XMLHttpRequest` progress path is the exception to the referrer and redirect guarantees: it applies the page's referrer policy and reports a followed redirect as refused (see [Upload progress and stall detection](#upload-progress-and-stall-detection)). The SDK validates the returned canonical receipt against the source and requested classification. An ETag is provider identity, not a substitute for the checksum.
 
-Progress callbacks are immutable and isolated from the operation. Uploading all bytes enters `completing`; success requires the canonical `published` result. Caller cancellation stops further orchestration and reports `aborted`. It does not call a retired abort route or release a capacity hold: the service's bounded retention worker reconciles the original immutable operation.
+Progress callbacks are immutable and isolated from the operation. Uploading all bytes enters `completing`; success requires the canonical `published` result. See [Upload progress and stall detection](#upload-progress-and-stall-detection) for byte-level progress. Caller cancellation stops further orchestration and reports `aborted`. It does not call a retired abort route or release a capacity hold: the service's bounded retention worker reconciles the original immutable operation.
 
 The old multipart/session write and control API is intentionally absent: `createUpload`, `getUploadStatus`, `createUploadPartDescriptor`, `recordUploadPart`, `completeUpload`, `abortUpload`, `createFileVersionUpload`, `commitFileVersion`, `uploadFile` and `uploadFileVersion`. This is a coordinated breaking cutover. Deploy only with the matching current service and upgraded consumers or an isolated v2 deployment. Historical reads, downloads, editing, grants, visitor access and immutable version metadata remain available; absence of a new accounting authority is never treated as permission to adopt legacy data.
 
+### Upload progress and stall detection
+
+`onProgress` reports bytes while hashing and while sending, in the order `hashing`, `preparing`, `uploading`, `completing`. `phase`, `confirmedByteLength`, `totalByteLength` and the part counts keep their meaning; `stage`, `hashedByteLength` and `sentByteLength` are optional additions. Every counter is non-decreasing, a stage never repeats or goes back, and a byte stage reports at most about 200 times.
+
+```ts
+await drive.uploadVerifiedFile({
+  ...intent,
+  onProgress: ({ stage, hashedByteLength, sentByteLength, totalByteLength }) => {
+    const done = stage === "hashing" ? hashedByteLength : sentByteLength;
+    render(stage, (done ?? 0) / totalByteLength);
+  },
+});
+```
+
+Sent bytes need a transport that can observe an upload. With no custom `fetch`, browsers and webviews send a cross-origin object PUT through `XMLHttpRequest`, which reports real bytes. Node, Workers, a same-origin PUT, `upload: { transport: "fetch" }` and a custom `fetch` report only 0 and then the whole file at `completing`. If you supply a `fetch`, for example to fence each dispatch, make `createUploadProgressFetch(fetch)` its innermost transport to get the same progress. `XMLHttpRequest` cannot refuse a redirect before following it or set `referrerPolicy: "no-referrer"`; keep `transport: "fetch"` where those matter more than progress.
+
+The object PUT has no fixed 30-second deadline any more. It ends when the capability expires (at most five minutes after admission, and publication is refused after that), when a measured transfer sends no new byte for `upload.stallTimeoutMilliseconds` (default 30 000), or at `upload.maxDurationMilliseconds` when set. An explicit `timeoutMilliseconds` still caps the PUT unless `upload.maxDurationMilliseconds` is set. A transfer that stops before its last byte rejects with `timeout` or `network_error` and is not published; retry with the original keys. The SDK builds no multipart or resumable upload, so a file must fit in the capability window at the available uplink speed. See the [verified transfer guide](../../apps/developer/docs/sdk/verified-transfers.md#upload-progress-and-stall-detection).
+
+```ts
+const drive = createDriveClient({
+  baseUrl,
+  getCredential,
+  upload: { stallTimeoutMilliseconds: 20_000, maxDurationMilliseconds: 240_000 },
+});
+```
+
 ## Errors
 
 Failures throw `DriveError`. Known canonical API envelopes preserve their closed API code, HTTP status, and request ID. SDK-owned codes are:

package/dist/client.d.ts

@@ -1,7 +1,4 @@
-import { $ as ListIncomingItemsInput, $t as VisitorGrantCreation, A as DriveVisitorClient, At as RegisterItemRecipientInput, B as FolderPage, C as DriveEditingClientConfig, Ct as PrepareVerifiedTransferInput, Dt as PublishedVerifiedTransfer, Et as PublishVerifiedTransferInput, Ft as RevokeVisitorGrantInput, G as GetWorkspaceUsageInput, Gt as UploadSmallVerifiedFileInput, H as GetItemInput, Ht as UploadFilePhase, I as FileAccessContext, It as SearchWorkspaceItemsInput, J as IncomingShareContext, Jt as VisitorChildren, K as IncomingItemMetadata, Kt as UploadVerifiedFileInput, L as FolderItem, Lt as TransferItemOwnershipInput, M as EditingSession, Mt as RestoreItemInput, N as EditingSessionCreation, Nt as RestoreItemVersionInput, Q as ListFolderChildrenInput, Qt as VisitorGrant, R as FolderListInclude, Rt as TrashItemInput, S as DriveEditingClient, Tt as ProtectionClassification, U as GetItemVersionInput, Ut as UploadFileProgress, V as GetCurrentWorkspaceInput, Vt as UpdateWorkspaceSharingPolicyInput, W as GetVisitorGrantInput, Wt as UploadFileProgressCallback, X as ItemOwnershipTransfer, Y as IncomingSharePage, Z as ItemSharingPeoplePage, _ as DownloadItemResult, _t as OwnedItemPage, a as CollectOwnedItemsInput, an as WorkspaceDiscoveryPage, at as ListWorkspaceItemsInput, c as CreateEditingSessionInput, cn as WorkspaceSharingPolicy, ct as ManagedItemMetadata, dt as ManagedItemVersionResource, en as VisitorGrantPage, et as ListIncomingSharesInput, f as CreateVisitorGrantInput, ft as ManagedItemVersionRestoreResult, g as DeleteItemInput, gt as OwnedItem, h as CurrentWorkspaceSources, i as ChangeEditingSessionInput, in as WorkspaceDiscoveryItem, it as ListOwnedItemsInput, j as DriveVisitorClientConfig, jt as RegisteredRecipientDisplay, kt as RecoverVerifiedTransferInput, ln as WorkspaceUsage, lt as ManagedItemVersion, m as CurrentWorkspace, n as ArchiveItemInput, nt as ListItemSharingPeopleInput, o as CollectedOwnedItems, on as WorkspaceItemSearchItem, ot as ManagedDownloadDescriptor, pt as ManagedLifecycleItem, q as IncomingItemPage, qt as VerifiedTransferOperations, r as ArchivedItem, rn as VisitorSession, rt as ListItemVersionsInput, s as CreateDownloadInput, sn as WorkspaceItemSearchPage, st as ManagedDownloadRestorePending, t as AdmittedVerifiedTransfer, tn as VisitorItem, ut as ManagedItemVersionPage, v as DriveClient, wt as PreparedVerifiedTransfer, x as DriveCredentialProvider, y as DriveClientConfig, z as FolderListedItem, zt as UpdateItemInput } from "./contract.js";
+import { $ as ListFolderChildrenInput, A as DriveUploadConfig, At as RecoverVerifiedTransferInput, B as FolderListedItem, Bt as UpdateItemInput, C as DriveEditingClientConfig, Dt as PublishVerifiedTransferInput, Et as ProtectionClassification, G as GetVisitorGrantInput, Gt as UploadFileProgressCallback, H as GetCurrentWorkspaceInput, Ht as UpdateWorkspaceSharingPolicyInput, It as RevokeVisitorGrantInput, J as IncomingItemPage, Jt as UploadVerifiedFileInput, K as GetWorkspaceUsageInput, Kt as UploadFileStage, L as FileAccessContext, Lt as SearchWorkspaceItemsInput, M as DriveVisitorClientConfig, Mt as RegisteredRecipientDisplay, N as EditingSession, Nt as RestoreItemInput, Ot as PublishedVerifiedTransfer, P as EditingSessionCreation, Pt as RestoreItemVersionInput, Q as ItemSharingPeoplePage, R as FolderItem, Rt as TransferItemOwnershipInput, S as DriveEditingClient, Tt as PreparedVerifiedTransfer, U as GetItemInput, Ut as UploadFilePhase, V as FolderPage, W as GetItemVersionInput, Wt as UploadFileProgress, X as IncomingSharePage, Xt as VisitorChildren, Y as IncomingShareContext, Yt as VerifiedTransferOperations, Z as ItemOwnershipTransfer, _ as DownloadItemResult, _t as OwnedItem, a as CollectOwnedItemsInput, an as VisitorSession, at as ListOwnedItemsInput, c as CreateEditingSessionInput, cn as WorkspaceItemSearchItem, ct as ManagedDownloadRestorePending, dn as WorkspaceUsage, dt as ManagedItemVersionPage, en as VisitorGrant, et as ListIncomingItemsInput, f as CreateVisitorGrantInput, ft as ManagedItemVersionResource, g as DeleteItemInput, h as CurrentWorkspaceSources, i as ChangeEditingSessionInput, it as ListItemVersionsInput, j as DriveVisitorClient, jt as RegisterItemRecipientInput, ln as WorkspaceItemSearchPage, lt as ManagedItemMetadata, m as CurrentWorkspace, mt as ManagedLifecycleItem, n as ArchiveItemInput, nn as VisitorGrantPage, o as CollectedOwnedItems, on as WorkspaceDiscoveryItem, ot as ListWorkspaceItemsInput, pt as ManagedItemVersionRestoreResult, q as IncomingItemMetadata, qt as UploadSmallVerifiedFileInput, r as ArchivedItem, rn as VisitorItem, rt as ListItemSharingPeopleInput, s as CreateDownloadInput, sn as WorkspaceDiscoveryPage, st as ManagedDownloadDescriptor, t as AdmittedVerifiedTransfer, tn as VisitorGrantCreation, tt as ListIncomingSharesInput, un as WorkspaceSharingPolicy, ut as ManagedItemVersion, v as DriveClient, vt as OwnedItemPage, wt as PrepareVerifiedTransferInput, x as DriveCredentialProvider, y as DriveClientConfig, z as FolderListInclude, zt as TrashItemInput } from "./contract.js";
 import { n as createDriveVisitorClient, r as createVisitorSessionToken, t as collectOwnedItems } from "./contract2.js";
-//#region src/client.d.ts
-declare function createDriveEditingClient(config: DriveEditingClientConfig): DriveEditingClient;
-declare function createDriveClient(config: DriveClientConfig): DriveClient;
-//#endregion
-export { type AdmittedVerifiedTransfer, type ArchiveItemInput, type ArchivedItem, type ChangeEditingSessionInput, type CollectOwnedItemsInput, type CollectedOwnedItems, type CreateDownloadInput, type CreateEditingSessionInput, type CreateVisitorGrantInput, type CurrentWorkspace, type CurrentWorkspaceSources, type DeleteItemInput, type DownloadItemResult, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type DriveEditingClient, type DriveEditingClientConfig, type DriveVisitorClient, type DriveVisitorClientConfig, type EditingSession, type EditingSessionCreation, type FileAccessContext, type FolderItem, type FolderListInclude, type FolderListedItem, type FolderPage, type GetCurrentWorkspaceInput, type GetItemInput, type GetItemVersionInput, type GetVisitorGrantInput, type GetWorkspaceUsageInput, type IncomingItemMetadata, type IncomingItemPage, type IncomingShareContext, type IncomingSharePage, type ItemOwnershipTransfer, type ItemSharingPeoplePage, type ListFolderChildrenInput, type ListIncomingItemsInput, type ListIncomingSharesInput, type ListItemSharingPeopleInput, type ListItemVersionsInput, type ListOwnedItemsInput, type ListWorkspaceItemsInput, type ManagedDownloadDescriptor, type ManagedDownloadRestorePending, type ManagedItemMetadata, type ManagedItemVersion, type ManagedItemVersionPage, type ManagedItemVersionResource, type ManagedItemVersionRestoreResult, type ManagedLifecycleItem, type OwnedItem, type OwnedItemPage, type PrepareVerifiedTransferInput, type PreparedVerifiedTransfer, type ProtectionClassification, type PublishVerifiedTransferInput, type PublishedVerifiedTransfer, type RecoverVerifiedTransferInput, type RegisterItemRecipientInput, type RegisteredRecipientDisplay, type RestoreItemInput, type RestoreItemVersionInput, type RevokeVisitorGrantInput, type SearchWorkspaceItemsInput, type TransferItemOwnershipInput, type TrashItemInput, type UpdateItemInput, type UpdateWorkspaceSharingPolicyInput, type UploadFilePhase, type UploadFileProgress, type UploadFileProgressCallback, type UploadSmallVerifiedFileInput, type UploadVerifiedFileInput, type VerifiedTransferOperations, type VisitorChildren, type VisitorGrant, type VisitorGrantCreation, type VisitorGrantPage, type VisitorItem, type VisitorSession, type WorkspaceDiscoveryItem, type WorkspaceDiscoveryPage, type WorkspaceItemSearchItem, type WorkspaceItemSearchPage, type WorkspaceSharingPolicy, type WorkspaceUsage, collectOwnedItems, createDriveClient, createDriveEditingClient, createDriveVisitorClient, createVisitorSessionToken };
+import { n as createDriveEditingClient, r as createUploadProgressFetch, t as createDriveClient } from "./contract3.js";
+export { type AdmittedVerifiedTransfer, type ArchiveItemInput, type ArchivedItem, type ChangeEditingSessionInput, type CollectOwnedItemsInput, type CollectedOwnedItems, type CreateDownloadInput, type CreateEditingSessionInput, type CreateVisitorGrantInput, type CurrentWorkspace, type CurrentWorkspaceSources, type DeleteItemInput, type DownloadItemResult, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type DriveEditingClient, type DriveEditingClientConfig, type DriveUploadConfig, type DriveVisitorClient, type DriveVisitorClientConfig, type EditingSession, type EditingSessionCreation, type FileAccessContext, type FolderItem, type FolderListInclude, type FolderListedItem, type FolderPage, type GetCurrentWorkspaceInput, type GetItemInput, type GetItemVersionInput, type GetVisitorGrantInput, type GetWorkspaceUsageInput, type IncomingItemMetadata, type IncomingItemPage, type IncomingShareContext, type IncomingSharePage, type ItemOwnershipTransfer, type ItemSharingPeoplePage, type ListFolderChildrenInput, type ListIncomingItemsInput, type ListIncomingSharesInput, type ListItemSharingPeopleInput, type ListItemVersionsInput, type ListOwnedItemsInput, type ListWorkspaceItemsInput, type ManagedDownloadDescriptor, type ManagedDownloadRestorePending, type ManagedItemMetadata, type ManagedItemVersion, type ManagedItemVersionPage, type ManagedItemVersionResource, type ManagedItemVersionRestoreResult, type ManagedLifecycleItem, type OwnedItem, type OwnedItemPage, type PrepareVerifiedTransferInput, type PreparedVerifiedTransfer, type ProtectionClassification, type PublishVerifiedTransferInput, type PublishedVerifiedTransfer, type RecoverVerifiedTransferInput, type RegisterItemRecipientInput, type RegisteredRecipientDisplay, type RestoreItemInput, type RestoreItemVersionInput, type RevokeVisitorGrantInput, type SearchWorkspaceItemsInput, type TransferItemOwnershipInput, type TrashItemInput, type UpdateItemInput, type UpdateWorkspaceSharingPolicyInput, type UploadFilePhase, type UploadFileProgress, type UploadFileProgressCallback, type UploadFileStage, type UploadSmallVerifiedFileInput, type UploadVerifiedFileInput, type VerifiedTransferOperations, type VisitorChildren, type VisitorGrant, type VisitorGrantCreation, type VisitorGrantPage, type VisitorItem, type VisitorSession, type WorkspaceDiscoveryItem, type WorkspaceDiscoveryPage, type WorkspaceItemSearchItem, type WorkspaceItemSearchPage, type WorkspaceSharingPolicy, type WorkspaceUsage, collectOwnedItems, createDriveClient, createDriveEditingClient, createDriveVisitorClient, createUploadProgressFetch, createVisitorSessionToken };