@finueva/drive 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @finueva/drive
+
+## 0.1.0
+
+### Minor Changes
+
+- 80bb160: Add the first Local Experimental managed-folder and permission client for browsers, Cloudflare Workers, and Node.js.
+- 2a61a60: Add managed upload quota reservation and release operations for browser, Worker, and Node clients.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Finueva
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# `@finueva/drive`
+
+The public TypeScript client for Finueva Drive. The initial API is Local Experimental and is not yet published to npm.
+
+The package is ESM-only. Node.js 22 is the exact minimum; package CI qualifies Node.js 22 and 24. Modern browsers and Cloudflare Workers use Web Fetch, Streams, URL, and AbortSignal.
+
+## 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 folder, permission, and upload quota types     |
+
+## Browser
+
+```ts
+import { createDriveClient } from "@finueva/drive";
+
+const drive = createDriveClient({
+  baseUrl: "https://drive.example.com",
+  getCredential: ({ signal }) => auth.getDriveCredential({ signal }),
+  timeoutMilliseconds: 30_000,
+});
+
+const page = await drive.listFolderChildren({
+  workspaceId,
+  itemId,
+  limit: 50,
+});
+```
+
+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.
+
+## Worker And Node
+
+```ts
+import { createDriveServerClient } from "@finueva/drive/server";
+
+const drive = createDriveServerClient({
+  baseUrl: "https://drive.example.com",
+  credential: ({ signal }) => requestCredential(request, signal),
+});
+```
+
+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.
+
+## Operations
+
+Methods use the Native API operation IDs:
+
+- `listFolderChildren`
+- `createFolder`
+- `listItemPermissions`
+- `readEffectiveItemPermissions`
+- `createItemPermission`
+- `updateItemPermission`
+- `revokeItemPermission`
+- `createUpload`
+- `abortUpload`
+
+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.
+
+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.
+
+## Errors
+
+Failures throw `DriveError`. Known canonical API envelopes preserve their closed API code, HTTP status, and request ID. SDK-owned codes are:
+
+- `credential_unavailable`
+- `invalid_input`
+- `network_error`
+- `timeout`
+- `aborted`
+- `invalid_response`
+
+Messages are fixed and details are always empty. Every operation input is runtime-validated before credential lookup or Fetch. Response bodies, URLs, credentials, provider exceptions, submitted values, and raw thrown values are never included. JSON response reads have byte, chunk, and elapsed-time bounds and are cancelled when rejected.
+
+## Base URL
+
+Use an absolute HTTPS URL. Plain HTTP is accepted only for `localhost`, `127.0.0.1`, or `[::1]`. Credentials, query strings, fragments, and other protocols are rejected.
+
+## Release Status
+
+This release prepares `0.1.0` from the reviewed minor Changesets. Qualification builds the exact compiled Drive Worker, obtains `/api/v1/openapi.json` through Miniflare, checks generated types byte-for-byte, packs the package, and installs that tarball into clean external projects with lifecycle scripts disabled.
+
+`@finueva/drive` does not yet exist on npm. The source repository is private, so public provenance is unavailable. First publication must follow ADR 0016's exact retained-artifact maintainer-2FA bootstrap. The protected OIDC workflow stages only later releases after npm trusts the exact workflow; it has no npm token and cannot bootstrap the package itself.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,55 @@
+# Third-Party Notices
+
+`@finueva/drive` bundles runtime code from these packages.
+
+## openapi-fetch 0.17.0
+
+Source: https://github.com/openapi-ts/openapi-typescript
+
+MIT License
+
+Copyright (c) 2023 Drew Powers
+
+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.
+
+## ufo 1.6.4
+
+Source: https://github.com/unjs/ufo
+
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+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.

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+import { O as UploadQuotaReservation, T as ReservedUploadQuota, a as CreateUploadInput, l as DriveCredentialProvider, n as AbortedUploadQuota, o as DriveClient, s as DriveClientConfig, t as AbortUploadInput } from "./contract.js";
+//#region src/client.d.ts
+declare function createDriveClient(config: DriveClientConfig): DriveClient;
+//#endregion
+export { type AbortUploadInput, type AbortedUploadQuota, type CreateUploadInput, type DriveClient, type DriveClientConfig, type DriveCredentialProvider, type ReservedUploadQuota, type UploadQuotaReservation, createDriveClient };