@finueva/drive 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @finueva/drive
 
+## 0.5.0
+
+### Minor Changes
+
+- 2ff64ff: Add authorized managed download descriptors, ranged streaming, HEAD metadata, and visible cold restore operations.
+- 785cea5: Add authorized exact managed item-version lookup across browser, Worker, and Node clients.
+- e5cc9cb: Add authorized exact managed-item metadata reads across browser, Worker, and Node clients.
+- fa7c00b: Add qualified workspace item search across browser, Worker, and Node clients.
+
+## 0.4.0
+
+### Minor Changes
+
+- c1755b1: Add strict managed-item rename, move, trash, restore, permanent deletion, version listing, and prior-version restore operations across browser, Worker, and Node clients.
+
+## 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, search, item, version, permission, and upload types |
 
 ## Browser
 
@@ -31,6 +31,24 @@ const page = await drive.listFolderChildren({
   itemId: workspace.rootItemId,
   limit: 50,
 });
+const matches = await drive.searchWorkspaceItems({
+  workspaceId: workspace.workspaceId,
+  query: "Project",
+  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,28 +66,68 @@ 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 all 24 Native Drive operations plus streaming `downloadItem`, but intentionally has no Blob-only `uploadFile` method. The package root and browser client add `uploadFile`, for 26 methods total.
+
 ## Operations
 
 Methods use the Native API operation IDs:
 
 - `getCurrentWorkspace`
+- `getItem`
+- `searchWorkspaceItems`
 - `listFolderChildren`
 - `createFolder`
+- `updateItem`
+- `trashItem`
+- `restoreItem`
+- `deleteItem`
+- `listItemVersions`
+- `getItemVersion`
+- `restoreItemVersion`
+- `createDownload`
+- `downloadItem` (high-level direct streaming)
 - `listItemPermissions`
 - `readEffectiveItemPermissions`
 - `createItemPermission`
 - `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.
 
-Every mutation requires the API's explicit idempotency key when the operation defines one and, for grants, a precondition validator. Mutations are never retried automatically. Sparse updates omit `undefined` properties and preserve explicit `null` expiry.
+`getItem` reads one active managed item under exact `items:metadata:read` authority. It conceals absent, cross-workspace, unauthorized, tombstoned, ancestor-tombstoned, and unpublished file items as not found. Results expose exact `workspaceId`, `itemId`, nullable `parentId`, `type`, `name`, `lifecycleState`, `revision`, and `currentVersion`. Folder metadata returns `currentVersion: null`; published files return only the current immutable version ID, state, byte length, untrusted media type, and untrusted protection classification. The strong item ETag matches the returned item revision. Digests, archive/cache state, provider keys, upload state, and content authority are not exposed.
+
+`searchWorkspaceItems` searches active managed metadata in one workspace by a required NFC, case-sensitive name prefix. The prefix is 1 through 64 Unicode code points, at most 255 UTF-8 bytes, and excludes C0/C1 controls plus U+2028/U+2029. Results are exact frozen `{ items, nextCursor }` pages of at most the requested limit or 50 by default, in binary name then item-ID order. Each item adds exact `volumeId` and `provider: "managed"` fields to the `getItem` metadata shape; folders require `currentVersion: null` and files require current-version metadata. Cursors use the existing opaque syntax and an empty page cannot carry a continuation.
+
+Every mutation requires the API's explicit idempotency key when the operation defines one. Item lifecycle mutations also require the current strong item ETag as `ifMatch`; grant mutations use their documented collection or grant precondition. Mutations are never retried automatically. Sparse updates omit `undefined` properties and preserve explicit `null` expiry.
 
 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.
+`updateItem` renames and moves one stable item ID. A move immediately changes inherited-grant ancestry; Drive does not copy grants to the item. `trashItem` retains a 30-day tombstone, `restoreItem` requires the original parent to remain active, and `deleteItem` starts permanent archive cleanup only after retention expires and no hold applies. Permanent deletion is currently bounded to at most 25 subtree items and 25 total versions; larger trees fail unavailable until a durable workflow exists. Exact retries resume retained deletion checkpoints and never trigger blind provider duplication.
+
+`listItemVersions` returns only immutable `current` and `superseded` managed version projections in pages of at most 50 using an opaque encrypted cursor. `getItemVersion` returns a strict frozen `ManagedItemVersionResource` containing the requested `workspaceId`, `itemId`, and `versionId` plus those version fields; all three response IDs must match the request. It conceals clean absence, valid wrong-item identity, unpublished history, and deleting or deleted history, while malformed retained state is unavailable. `restoreItemVersion` atomically makes one selected superseded version current, demotes the previous current version, advances the item revision, and never copies or overwrites archive bytes.
+
+`createDownload` returns a short-lived archive descriptor for the current or an explicit immutable version, one visible `restore-pending` result for cold content, or a no-body `304` operation result whose validators retain the source ETag. Full, closed, open, and suffix ranges use the selected archive object's strong ETag; malformed or multiple ranges are served as full representations, while valid non-overlapping ranges fail with `range_not_satisfiable`. `downloadItem` follows a descriptor with no Drive credential, ambient browser credentials, or referrer and returns the provider body as a backpressured `Response`; it preserves the same `304` and cold-restore results without a provider request. It validates exact status, ETag, identity encoding, length, and `Content-Range`, cancels malformed upstream bodies, and keeps caller cancellation/deadline authority active until the stream closes or is cancelled. It never returns Blob, ArrayBuffer, text, or base64 whole-file convenience values.
+
+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 { $ as UpdateItemInput, A as ListItemVersionsInput, C as FolderPage, D as GetUploadStatusInput, E as GetItemVersionInput, F as ManagedItemVersionPage, I as ManagedItemVersionResource, J as RestoreItemInput, K as ReadyUpload, L as ManagedItemVersionRestoreResult, M as ManagedDownloadRestorePending, N as ManagedItemMetadata, O as ListFolderChildrenInput, P as ManagedItemVersion, Q as TrashItemInput, R as ManagedLifecycleItem, S as FolderItem, T as GetItemInput, W as ProtectionClassification, Y as RestoreItemVersionInput, Z as SearchWorkspaceItemsInput, at as UploadFileProgressCallback, c as CurrentWorkspace, ct as UploadSession, d as DriveClient, dt as WorkspaceItemSearchPage, f as DriveClientConfig, it as UploadFileProgress, j as ManagedDownloadDescriptor, l as DeleteItemInput, lt as UploadStatus, m as DriveCredentialProvider, n as CompleteUploadInput, nt as UploadFileInput, o as CreateUploadInput, ot as UploadPartDescriptor, q as RecordUploadPartInput, r as CreateDownloadInput, rt as UploadFilePhase, s as CreateUploadPartDescriptorInput, st as UploadPartResult, t as AbortUploadInput, tt as UploadConfirmedPart, u as DownloadItemResult, ut as WorkspaceItemSearchItem, w as GetCurrentWorkspaceInput } 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 CreateDownloadInput, type CreateUploadInput, type CreateUploadPartDescriptorInput, type CurrentWorkspace, type DeleteItemInput, type DownloadItemResult, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type FolderItem, type FolderPage, type GetCurrentWorkspaceInput, type GetItemInput, type GetItemVersionInput, type GetUploadStatusInput, type ListFolderChildrenInput, type ListItemVersionsInput, type ManagedDownloadDescriptor, type ManagedDownloadRestorePending, type ManagedItemMetadata, type ManagedItemVersion, type ManagedItemVersionPage, type ManagedItemVersionResource, type ManagedItemVersionRestoreResult, type ManagedLifecycleItem, type ProtectionClassification, type ReadyUpload, type RecordUploadPartInput, type RestoreItemInput, type RestoreItemVersionInput, type SearchWorkspaceItemsInput, type TrashItemInput, type UpdateItemInput, type UploadConfirmedPart, type UploadFileInput, type UploadFilePhase, type UploadFileProgress, type UploadFileProgressCallback, type UploadPartDescriptor, type UploadPartResult, type UploadSession, type UploadStatus, type WorkspaceItemSearchItem, type WorkspaceItemSearchPage, createDriveClient };