@finueva/drive 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @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

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 low-level client factory |
-| `@finueva/drive/core`   | Reviewed error values only                              |
-| `@finueva/drive/types`  | Curated workspace, folder, permission, and upload 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,11 @@ 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,
@@ -61,15 +66,26 @@ 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.
+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`
@@ -85,10 +101,20 @@ Methods use the Native API operation IDs:
 
 `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`.
 
+`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.

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-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";
+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 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 };
+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 };