@finueva/drive 0.3.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @finueva/drive
 
+## 0.5.1
+
+### Patch Changes
+
+- b54eff9: Bind the default Fetch implementation to its global receiver so browser requests do not fail with an illegal invocation. Custom Fetch implementations and request policies are unchanged.
+
+## 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 client, errors, types     |
+| `@finueva/drive/client` | Browser client                    |
+| `@finueva/drive/server` | Request-scoped Worker/Node client |
+| `@finueva/drive/core`   | Error values                      |
+| `@finueva/drive/types`  | Public operation types            |
 
 ## Browser
 
@@ -21,7 +21,12 @@ import { createDriveClient } from "@finueva/drive";
 
 const drive = createDriveClient({
   baseUrl: "https://drive.example.com",
-  getCredential: ({ signal }) => auth.getDriveCredential({ signal }),
+  getCredential: async ({ signal }) => {
+    signal.throwIfAborted();
+    const credential = await auth.getDriveCredential({ workspace: { type: "personal" } });
+    signal.throwIfAborted();
+    return credential.token;
+  },
   timeoutMilliseconds: 30_000,
 });
 
@@ -31,6 +36,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,
@@ -48,6 +58,10 @@ const uploaded = await drive.uploadFile({
 
 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.
 
+`auth` is a configured `@finueva/auth` client. Select the exact personal or organization workspace. Native Fetch needs no wrapper.
+
+Approve the exact application origin in Drive's `DRIVE_BROWSER_ORIGINS` policy and configure archive CORS separately. API responses must expose `X-Request-ID` and `ETag`. See [browser setup](https://github.com/Ifkafin/drive/blob/main/apps/developer/docs/architecture/configuration.md#native-api-browser-origins).
+
 ## Worker And Node
 
 ```ts
@@ -61,15 +75,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 +110,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` requires `items:metadata:read`. Absent, unauthorized, tombstoned, or unpublished items are concealed. Folders have `currentVersion: null`; files expose their current version. The strong ETag matches the item revision. Media type and protection classification are untrusted metadata, not content authority. Internal storage/provider state is never exposed.
+
+`searchWorkspaceItems` matches NFC, case-sensitive name prefixes: 1-64 Unicode code points, at most 255 UTF-8 bytes, without C0/C1 controls or U+2028/U+2029. Frozen `{ items, nextCursor }` pages default to 50 rows ordered by binary name then item ID. Results add `volumeId` and `provider: "managed"` to item metadata. An empty page cannot have a cursor.
+
+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` pages immutable current/superseded versions, at most 50 per page. `getItemVersion` verifies all three workspace/item/version IDs and conceals unavailable history. Malformed retained state fails unavailable. `restoreItemVersion` atomically changes the current version and item revision without copying or overwriting 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 };