@finueva/drive 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @finueva/drive
 
+## 0.3.0
+
+### Minor Changes
+
+- 90e29ff: Add all six strict upload controls and resumable browser direct-`Blob` orchestration with zero-byte completion, bounded incremental SHA-256 hashing, isolated archive PUTs, lost-response reconciliation, progress, and cancellation cleanup.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -6,13 +6,13 @@ The package is ESM-only. Node.js 22 is the exact minimum; package CI qualifies N
 
 ## Exports
 
-| Import                  | Runtime                                                       |
-| ----------------------- | ------------------------------------------------------------- |
-| `@finueva/drive`        | Browser-safe client factory, errors, and curated types        |
-| `@finueva/drive/client` | Browser-safe client factory                                   |
-| `@finueva/drive/server` | Request-scoped Worker and Node client factory                 |
-| `@finueva/drive/core`   | Reviewed error values only                                    |
-| `@finueva/drive/types`  | Curated workspace, folder, permission, and upload quota types |
+| Import                  | Runtime                                                 |
+| ----------------------- | ------------------------------------------------------- |
+| `@finueva/drive`        | Browser-safe client factory, errors, and curated types  |
+| `@finueva/drive/client` | Browser-safe client factory                             |
+| `@finueva/drive/server` | Request-scoped Worker and Node low-level client factory |
+| `@finueva/drive/core`   | Reviewed error values only                              |
+| `@finueva/drive/types`  | Curated workspace, folder, permission, and upload types |
 
 ## Browser
 
@@ -31,6 +31,19 @@ const page = await drive.listFolderChildren({
   itemId: workspace.rootItemId,
   limit: 50,
 });
+
+const uploaded = await drive.uploadFile({
+  workspaceId: workspace.workspaceId,
+  parentItemId: workspace.rootItemId,
+  source: file, // Blob; File is supported without being required
+  displayFilename: file.name,
+  mediaType: file.type || "application/octet-stream",
+  idempotencyKey: crypto.randomUUID(),
+  completionIdempotencyKey: crypto.randomUUID(),
+  onProgress: ({ phase, confirmedByteLength, totalByteLength }) => {
+    renderProgress(phase, confirmedByteLength, totalByteLength);
+  },
+});
 ```
 
 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.
@@ -48,6 +61,8 @@ const drive = createDriveServerClient({
 
 Create a client per request when using user authority. A fixed `credential` string is accepted for an explicitly scoped credential, but the SDK does not create, refresh, persist, or infer sessions, cookies, provider tokens, or service authority.
 
+The server client exposes the Native Drive operations, including all six upload controls, but intentionally has no Blob-only `uploadFile` method. Browser upload orchestration is available from the package root and `@finueva/drive/client` only.
+
 ## Operations
 
 Methods use the Native API operation IDs:
@@ -61,7 +76,12 @@ Methods use the Native API operation IDs:
 - `updateItemPermission`
 - `revokeItemPermission`
 - `createUpload`
+- `getUploadStatus`
+- `createUploadPartDescriptor`
+- `recordUploadPart`
+- `completeUpload`
 - `abortUpload`
+- `uploadFile` (high-level orchestration)
 
 `getCurrentWorkspace` maps the credential's selected Auth context to the provisioned Drive workspace and canonical managed root. It accepts only an optional `{ signal }` input, never provisions as a side effect, and returns no entitlement, credential, or private persistence fields.
 
@@ -69,7 +89,19 @@ Every mutation requires the API's explicit idempotency key when the operation de
 
 Successful calls return `{ data, status, requestId, validators }`. A successful response must carry one valid `X-Request-ID`; canonical API errors must carry the same request ID in their header and body. Any missing, malformed, or mismatched value is an `invalid_response`. The only exposed validators are `etag`, `permissionCollectionEtag`, and `permissionGrantEtag`.
 
-`createUpload` and `abortUpload` only reserve and release managed upload quota. They return reservation metadata and no transfer URL, capability, provider data, or file bytes. Upload-byte transfer, completion, and file-byte helpers remain excluded until issue #81.
+The six low-level upload methods map directly to the Native API. `createUpload` accepts `callerDeclaredContentDigest`, an ordinary whole-file `sha256:{64 lowercase hex}` value calculated or supplied by the caller. It is untrusted metadata, not provider verification evidence. `getUploadStatus` returns one bounded confirmed-part page and the current lifecycle/revision. Descriptor issuance accepts one base64 SHA-256 part checksum, `recordUploadPart` records exact provider ETag/checksum evidence and revision, `completeUpload` returns only a server-verified `ready` result, and `abortUpload` returns bodyless `204` success.
+
+Provider part checksums and the provider's multipart composite checksum are verified server-side before publication. They are deliberately distinct from `callerDeclaredContentDigest`: multipart composite SHA-256 is not the ordinary SHA-256 of the complete file. Every low-level control obtains one credential, sends one request, validates exact IDs, checksums, ETags, and safe-integer bounds at runtime, and never retries automatically. `upload_recovery_required` is preserved as a canonical `DriveError` code.
+
+`uploadFile` is the browser-safe direct-byte path for a Web `Blob` or `File`. It accepts zero-byte input, hashes the empty input correctly, accepts the server-mediated zero-byte mode, skips part transfer, and completes normally. Nonempty input is incrementally hashed in slices no larger than 32 MiB and is never materialized as a complete `ArrayBuffer`, Blob copy, base64 string, or SDK request body. The fixed policy permits at most 10,000 parts and 312.5 GiB.
+
+Each nonempty slice is sent directly to the exact descriptor URL. The request includes only descriptor-required headers, uses `credentials: "omit"`, `cache: "no-store"`, `redirect: "error"`, and `referrerPolicy: "no-referrer"`, and shares the configured cancellation/deadline bound. The archive CORS policy must expose both `ETag` and `x-amz-checksum-sha256`; missing, malformed, or mismatched values fail closed. Drive authorization, cookies, default headers, and file metadata never enter the archive request.
+
+Repeating `uploadFile` with the same creation and completion idempotency keys explicitly resumes the retained session. After create/replay, the SDK reads status in pages of 100, bounded to 100 pages and 10,000 parts; validates session identity, mode, policy, lifecycle, revision, and pagination; re-hashes the supplied source; compares every confirmed part checksum; skips exact confirmed parts; and continues from the current revision. A matching `ready` status returns its exact ready projection. `completing` and `provider-completed` replay completion. Recovery-required and aborted states fail without pretending to resume.
+
+There is no automatic network or provider retry. If a part-record callback response may have been lost, the SDK performs one bounded status reconciliation before either accepting the confirmed part or recording the same provider evidence once more; it never blindly re-uploads the bytes. If a completion response may have been lost, one status reconciliation returns success only when `ready` is proven. Other transient failures preserve the session for an explicit repeat until server expiry.
+
+Progress values are frozen and limited to `preparing`, `uploading`, and `completing`, with truthful server-confirmed bytes and part counts, including resumed parts. Observer exceptions are isolated from transfer state. Reaching all confirmed bytes enters `completing`; only a resolved or status-proven `ready` result is success. Caller cancellation after session creation makes one bounded best-effort abort with fresh control-plane authority. Ordinary API or archive failures do not auto-abort.
 
 ## Errors
 

package/THIRD_PARTY_NOTICES.md

@@ -2,6 +2,32 @@
 
 `@finueva/drive` bundles runtime code from these packages.
 
+## @noble/hashes 2.3.0
+
+Source: https://github.com/paulmillr/noble-hashes
+
+MIT License
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+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.
+
 ## openapi-fetch 0.17.0
 
 Source: https://github.com/openapi-ts/openapi-typescript

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { A as UploadQuotaReservation, D as ReservedUploadQuota, _ as FolderPage, a as CreateUploadInput, c as DriveClientConfig, g as FolderItem, n as AbortedUploadQuota, o as CurrentWorkspace, s as DriveClient, t as AbortUploadInput, u as DriveCredentialProvider, v as GetCurrentWorkspaceInput, y as ListFolderChildrenInput } from "./contract.js";
+import { A as ProtectionClassification, B as UploadFileProgressCallback, C as ListFolderChildrenInput, H as UploadPartResult, I as UploadConfirmedPart, L as UploadFileInput, M as ReadyUpload, N as RecordUploadPartInput, R as UploadFilePhase, S as GetUploadStatusInput, U as UploadSession, V as UploadPartDescriptor, W as UploadStatus, a as CreateUploadInput, b as FolderPage, c as DriveClient, d as DriveCredentialProvider, l as DriveClientConfig, n as CompleteUploadInput, o as CreateUploadPartDescriptorInput, s as CurrentWorkspace, t as AbortUploadInput, x as GetCurrentWorkspaceInput, y as FolderItem, z as UploadFileProgress } from "./contract.js";
 //#region src/client.d.ts
 declare function createDriveClient(config: DriveClientConfig): DriveClient;
 //#endregion
-export { type AbortUploadInput, type AbortedUploadQuota, type CreateUploadInput, type CurrentWorkspace, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type FolderItem, type FolderPage, type GetCurrentWorkspaceInput, type ListFolderChildrenInput, type ReservedUploadQuota, type UploadQuotaReservation, createDriveClient };
+export { type AbortUploadInput, type CompleteUploadInput, type CreateUploadInput, type CreateUploadPartDescriptorInput, type CurrentWorkspace, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type FolderItem, type FolderPage, type GetCurrentWorkspaceInput, type GetUploadStatusInput, type ListFolderChildrenInput, type ProtectionClassification, type ReadyUpload, type RecordUploadPartInput, type UploadConfirmedPart, type UploadFileInput, type UploadFilePhase, type UploadFileProgress, type UploadFileProgressCallback, type UploadPartDescriptor, type UploadPartResult, type UploadSession, type UploadStatus, createDriveClient };