agentic-drive 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- **`createApp` takes an injected store, blobs, and auth.** `createApp({ store, blobs, auth })` from `agentic-drive/worker` lets a host serve the drive routes with its own `Store`, `Blobs`, and sign-in callback. Each part may be a function of the Worker env. With no options, the Worker works as before. A Worker with no `DB` or `FILES` binding and no injected store or blobs now answers 503 `NOT_CONFIGURED`. The package also exports the `AppOptions` type.
+- **Mountable UI at `agentic-drive/ui`.** `mount(element, { baseUrl, getToken })` renders the drive UI in any page and returns `{ update, unmount }`. `getToken` runs before each request. The styles are in `agentic-drive/ui.css`. The embed keeps its folder in memory, so it does not change the page address. `react` and `react-dom` 19 are optional peer dependencies, and `agentic-design` is now a dependency.
+
 ## 0.5.0
 
 Read the breaking changes before you upgrade or deploy.

package/README.md

@@ -7,7 +7,7 @@
 
 Store, sort, and share files and folders.
 
-> Status: 0.5.0, early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK and the HTTP API.
+> Status: 0.6.0, early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK and the HTTP API.
 > A small web UI works. See [UI](#ui).
 
 ## Live demo
@@ -47,18 +47,7 @@ await drive.trash(me, "/reports/2026");
 
 ## CLI and MCP
 
-```sh
-npx agentic-drive mkdir -p /reports
-npx agentic-drive upload ./q1.pdf /reports/
-npx agentic-drive search --name q1
-npx agentic-drive export ./everything.zip
-npx agentic-drive mcp
-```
-
-Every command prints JSON. A failure prints `{"error":{"code","message"}}` on stderr and exits 1.
-Exit code 2 means bad usage. Exit code 3 means no principal, or a key that is not valid.
-
-Every command except `help`, `version`, `principal`, and `key` needs a principal. Pass an API key with
+Every command except `help`, `--version`, `principal`, and `key` needs a principal. Pass an API key with
 `--token <key>` or `AGENTIC_DRIVE_TOKEN`. Prefer the variable: a flag shows in `ps`.
 `agentic-identity` resolves the key. The drive belongs to the person at the top of the
 principal's chain. An agent key marks each item it makes as made by a machine. A revoked,
@@ -73,10 +62,21 @@ npx agentic-drive key revoke <key>
 npx agentic-drive principal revoke helper             # stops its keys, and its agents
 ```
 
-`principal` and `key` need no key: anyone who can read the `--dir` folder can run them.
+`principal` and `key` need no key: anyone who can write to the `--dir` folder can run them.
 Set `--dir` (or `AGENTIC_DRIVE_DIR`) to choose the data folder.
 The local drive checks the owner only. It does not apply the scopes of an agent key.
 
+```sh
+npx agentic-drive mkdir -p /reports
+npx agentic-drive upload ./q1.pdf /reports/
+npx agentic-drive search --name q1
+npx agentic-drive export ./everything.zip
+npx agentic-drive mcp
+```
+
+Every command prints JSON, except `help`, `--version`, `mcp`, and `download` to `-`. A failure prints `{"error":{"code","message"}}` on stderr and exits 1.
+Exit code 2 means bad usage. Exit code 3 means no principal, or a key that is not valid.
+
 ## HTTP API
 
 A Cloudflare Worker (Hono) serves `/api/v1/drive` and mirrors the CLI. It uses D1 and R2
@@ -133,6 +133,35 @@ try {
 - A browser page needs the Worker on its own origin for now: the Worker sends no CORS headers.
 - Share with a subject: `share("/pub", { kind: "human", id: "u2" }, "viewer")`.
 
+### Other exports
+
+The root export, `agentic-drive`, also exports these names. The package typings give the type of each one.
+
+- `VERSION` is the package version. `ROOT_ID` is the id of a drive's root folder, `"root"`. `ACTOR_KINDS` lists
+  the five principal kinds that `agentic-identity` names.
+- `DEFAULT_MAX_BYTES` is the upload cap: 25 MiB (26,214,400 bytes). `sniffMime(head)` returns the type that
+  the first bytes name: PNG, JPEG, GIF, PDF, ZIP, gzip, or WebP. It returns `null` for any other bytes.
+- `parseName(raw)` returns `{ name, key }`. It normalizes the name to NFC, and `key` is the lowercase name.
+  It throws a `DriveError` with the code `INVALID_NAME` for a blank name, `.`, `..`, a lone surrogate, a `/`,
+  a control character (U+0000 to U+001F, or U+007F), or a name over 255 bytes in UTF-8. `parseSubject(input)` returns `{ kind, id }` for a valid subject, and throws
+  `INVALID_SHARE` for any other input. `subjectKindOf(kind)` returns `human` or `agent`, and throws
+  `INVALID_SHARE` for any other kind.
+- A `DriveError` has a `code` from `ErrorCode`, such as `NOT_FOUND` or `NAME_TAKEN`.
+- `readZip(bytes)` reads a zip that `writeZip` made, with stored (uncompressed) entries only. It returns a `Map`
+  from each entry name to its bytes. It throws for a compressed entry. `writeZip(entries, at)` writes a zip with
+  one `{ name, data }` entry for each file, and `at` sets the time in milliseconds. It throws for an unsafe
+  name, such as one with `..` or a leading `/`.
+- The local drive has the functions behind the CLI. `openLocal(dir)` returns `{ drive, store }` for a folder.
+  `addPrincipal(store, id, { parent?, scopes? })` makes a principal. `issueKey(store, principalId, label?)`
+  returns the key. Keep it: the store keeps no plain copy. `resolveToken(store, token)` returns the caller, or throws `AuthError`
+  with the code `UNAUTHENTICATED`. `revokeKey(store, token)` stops one key. `revokePrincipal(store, id)` stops a
+  principal, its keys, and every agent below it.
+  `publicNode(node, path?)` returns an item without its storage keys and its `purging` flag, and adds `machineMade`. When `path` is
+  given, it also adds `path`.
+
+  The local functions trust their caller. Local data is the trust boundary: anyone who can write the folder
+  can act as any principal in it.
+
 ## UI
 
 The Worker serves a small web UI. It uses the [agentic-design](https://www.npmjs.com/package/agentic-design) package and the typed client of this package (`agentic-drive/client`). It has a folder tree, breadcrumbs, a file list and grid, upload by button or by drag and drop, new folder, rename, move, trash and restore, and a share dialog with roles and a link. An item that an agent made shows a "Created by agent" label while a person is its last editor. "Edited by" names the last editor, a person or an agent. It works with the keyboard. An automated axe check for WCAG 2.2 AA passes on each view in the light and dark themes.
@@ -155,6 +184,26 @@ Run `npm run build:ui` before `npm run test:e2e` or `wrangler deploy`, because t
 
 Set `DRIVE_PUBLIC_URL` to the origin that serves the UI. A download link on another origin is refused.
 
+### Mount the UI in your app
+
+`agentic-drive/ui` renders the same UI inside your own page. It needs no framework in your app. You give it an element, the address of a drive server, and a function that returns the bearer token. `mount` returns a handle.
+
+```ts
+import "agentic-design/styles.css";   // tokens, fonts, and base styles for body, headings, and links
+import "agentic-drive/ui.css";        // the drive styles
+import { mount } from "agentic-drive/ui";
+
+const drive = mount(document.getElementById("drive")!, {
+  baseUrl: "https://drive.example.com",
+  getToken: () => session.token,      // runs before every request, so it can refresh
+});
+
+drive.update({ baseUrl, getToken });  // use another server or callback
+drive.unmount();                      // remove the UI
+```
+
+`getToken` returns 1 to 512 letters, digits, `-` or `_`, or `undefined` to send no `authorization` header. A bad `baseUrl` or a `getToken` that is not a function makes `mount` throw a `TypeError`. The server still checks every request against the token. The embed shows files and trash with upload, rename, move, share, and the "Created by agent" label. It has no sign-in form, because your app owns sign-in. It does not change the page address, and it has no theme switch. `agentic-design/styles.css` sets base styles for the whole page, and it follows the dark mode of the system unless your page sets `data-theme`. Add `agentic-design` to your own dependencies, because your page imports its files. The Worker sends no CORS headers, so the server must be on the origin of your page. Set `baseUrl` to the same address as `DRIVE_PUBLIC_URL`, or the UI refuses its download links. `unmount` and `update` abort the requests that run and stop an upload that has more files to send. The UI keeps the list or grid choice in `localStorage` under `agentic-drive-view`, and it has its own heading for each view. Dialogs, menus, and messages render in `document.body`, outside your element. A click with Ctrl, Cmd, Shift, or the middle button on a folder link does not open the folder. The class names start with `drive-`. `DriveBrowser` is the same UI as a React component. It closes its requests when it unmounts. Wrap it in `TooltipProvider` and `ToastProvider` from `agentic-design/react`. `react` and `react-dom` (version 19 or later) are optional peer dependencies. Install them in your project when you use `agentic-drive/ui`. The web UI that the Worker serves uses the same views.
+
 ### Serve the UI from the package
 
 The npm package ships the built UI in `ui-dist`. The package does not ship a `wrangler.jsonc`, so a project that deploys its own Worker adds the assets block to its config. Its Worker re-exports the package Worker. In a workspace, the package can sit in the root `node_modules`. Then point `assets.directory` at that folder, such as `../../node_modules/agentic-drive/ui-dist`:
@@ -190,6 +239,30 @@ The [seed script](https://github.com/pooriaarab/agentic-drive/blob/main/e2e/serv
 
 The UI does not make snapshot links yet. The address of a share link shows once, when you create it.
 
+### Inject a store, blobs, and sign-in
+
+A host that has its own Worker can serve the drive routes from it. `createApp` from `agentic-drive/worker` takes the parts to use. Each part is optional. A part may be a function of the Worker env, which runs on each request.
+
+```ts
+import { createApp } from "agentic-drive/worker";
+
+const app = createApp({
+  store: (env) => myStore(env),   // a Store of agentic-identity
+  blobs: (env) => myBlobs(env),   // a Blobs of agentic-identity
+  // Return a Ctx for the caller, or null for a 401.
+  auth: async (request, store, env) => {
+    const principal = await mySignIn(request, env);
+    return principal && { owner: principal.chain[0].id, actor: { id: principal.principalId, kind: principal.kind }, principal };
+  },
+});
+export default { fetch: app.fetch };
+```
+
+- With `store`, the Worker reads no `DB` binding. It does not create the table either, so the host owns the schema.
+- With `blobs`, the Worker reads no `FILES` binding and needs no `DRIVE_PUBLIC_URL`. The blobs must sign download URLs that point to `/api/v1/drive/blob` on this Worker. That route checks the signature with `DRIVE_URL_SECRET` before it reads the store or the blobs, so set that secret.
+- With `auth`, the Worker does not read bearer tokens from the store. The callback decides who the caller is. Return a whole `Ctx`: a `principal`, and an `owner` and `actor` that match it. Any other value gets 401. Make sure `principal.chain` and `principal.scopes` are real, because the drive checks them. A callback that reads a session cookie must check the request origin itself. Every write route is open to a cross-site form until it does.
+- With no options, `createApp()` works as before: D1, R2, and bearer tokens from the store. `export { default } from "agentic-drive/worker"` is the same.
+
 ## Features
 
 - Folders, files, and typed references to documents in other apps (`docs:<id>`).
@@ -217,7 +290,7 @@ The UI does not make snapshot links yet. The address of a share link shows once,
 - `registerDocument` makes one item per document in a drive. Two calls at the same moment can make two.
 
 - Drive reads the `store_docs` table in D1 and `store.jsonl` in the CLI folder. It does not read older layouts. There is no import and no claim backfill.
-- Uploads buffer the stream in memory up to the cap. The default cap is 25 MiB.
+- Uploads buffer the stream in memory up to the cap. The default cap is 25 MiB (`DEFAULT_MAX_BYTES`).
 - Local file blobs return a `file:` URL that nothing serves or checks.
 - Drive writes each new blob only when its key is free (`ifNoneMatch`). A write that finds the key taken fails with `BLOB_EXISTS`.
 - Only `upload()` enforces the size cap. A caller of `putFile()` must check size first.

package/dist/{chunk-B7E2Q3RB.js → chunk-BXFK3QXK.js}

@@ -1,7 +1,7 @@
 import {
   ROOT_ID,
   rootResource
-} from "./chunk-T6C5Y2WA.js";
+} from "./chunk-WJZNXLTR.js";
 
 // src/migrate.ts
 var PAGE = 10;

package/dist/{chunk-WQHJNHAR.js → chunk-ES3NZ7SX.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.5.0" : readPackageVersion();
+var VERSION = true ? "0.6.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/chunk-S4AGCKXW.js

@@ -0,0 +1,241 @@
+// src/client.ts
+var DriveApiError = class extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "DriveApiError";
+  }
+  code;
+  status;
+};
+var BASE = "/api/v1/drive";
+var CODES = {
+  NOT_FOUND: true,
+  NAME_TAKEN: true,
+  BLOB_EXISTS: true,
+  INVALID_NAME: true,
+  INVALID_PATH: true,
+  INVALID_REF: true,
+  NOT_A_FOLDER: true,
+  NOT_A_FILE: true,
+  MOVE_INTO_SELF: true,
+  TOO_DEEP: true,
+  PARENT_GONE: true,
+  TRASHED: true,
+  NOT_TRASHED: true,
+  IS_ROOT: true,
+  FORBIDDEN: true,
+  BLOB_MISSING: true,
+  TOO_LARGE: true,
+  INVALID_EXPIRY: true,
+  BUSY: true,
+  CROSS_DRIVE: true,
+  INVALID_SHARE: true,
+  TOO_MANY_ITEMS: true,
+  UNAUTHORIZED: true,
+  NOT_CONFIGURED: true,
+  INVALID_LINK: true,
+  INTERNAL: true
+};
+var KNOWN_CODES = new Set(Object.keys(CODES));
+var record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var text = (v) => typeof v === "string";
+var orNull = (test) => (v) => v === null || test(v);
+var num = (v) => typeof v === "number";
+var ACTOR_KINDS = { human: true, agent_of_human: true, agent_of_agent: true, agent: true, user_token: true };
+var ROLES = ["viewer", "commenter", "editor", "owner"];
+var oneOf = (list) => (v) => typeof v === "string" && list.includes(v);
+var actor = (v) => record(v) && text(v.id) && oneOf(Object.keys(ACTOR_KINDS))(v.kind);
+var isItem = (v) => record(v) && text(v.id) && text(v.owner) && text(v.parentId) && text(v.name) && (v.kind === "folder" || v.kind === "file" || v.kind === "ref") && num(v.size) && orNull(text)(v.mime) && orNull(text)(v.hash) && orNull(text)(v.ref) && num(v.createdAt) && num(v.updatedAt) && actor(v.createdBy) && actor(v.updatedBy) && text(v.createdById) && text(v.updatedById) && typeof v.trashed === "boolean" && orNull(num)(v.trashedAt) && typeof v.machineMade === "boolean";
+var isPathItem = (v) => isItem(v) && typeof v.path === "string";
+var listOf = (check) => (v) => Array.isArray(v) && v.every(check);
+var shape = (test) => (v) => record(v) && test(v);
+var numbers = (...keys) => shape((v) => keys.every((k) => typeof v[k] === "number"));
+var isOk = shape((v) => v.ok === true);
+var RETRY_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+function createClient(options) {
+  let origin;
+  try {
+    const url = new URL(options.baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("not http");
+    origin = url.origin;
+  } catch {
+    throw new TypeError("baseUrl must be an http or https URL");
+  }
+  const { token } = options;
+  if (token !== void 0 && (typeof token !== "string" || !/^[A-Za-z0-9_-]{1,512}$/.test(token))) throw new TypeError("token must be 1 to 512 letters, digits, - or _");
+  const retries = options.retries ?? 0;
+  if (!Number.isInteger(retries) || retries < 0 || retries > 5) throw new RangeError("retries must be an integer from 0 to 5");
+  const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const query = (params) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) if (value !== void 0) search.set(key, String(value));
+    const text2 = search.toString();
+    return text2 === "" ? "" : `?${text2}`;
+  };
+  async function send(method, path, init) {
+    if (init.auth !== false && token === void 0) throw new TypeError("this call needs a token");
+    const headers = { ...token === void 0 ? {} : { authorization: `Bearer ${token}` }, ...init.headers };
+    let body = init.body;
+    if (init.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.json);
+    }
+    const attempts = method === "GET" ? retries + 1 : 1;
+    for (let attempt = 1; ; attempt++) {
+      let response;
+      try {
+        response = await doFetch(`${origin}${BASE}${path}`, { method, headers, body, signal: init.signal, redirect: "manual", ...body instanceof ReadableStream ? { duplex: "half" } : {} });
+      } catch (error) {
+        if (init.signal?.aborted || error instanceof Error && error.name === "AbortError") throw error;
+        if (attempt < attempts) {
+          await pause(attempt, init.signal);
+          continue;
+        }
+        const refused = body instanceof ReadableStream ? " (a stream body may be refused by this runtime: send bytes)" : "";
+        throw new DriveApiError("NETWORK_ERROR", 0, `${error instanceof Error ? `no answer: ${error.message}` : "no answer"}${refused}`);
+      }
+      if (attempt < attempts && RETRY_STATUS.has(response.status)) {
+        await response.body?.cancel();
+        await pause(attempt, init.signal);
+        continue;
+      }
+      if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new DriveApiError("BAD_RESPONSE", response.status, "the server redirected. Set baseUrl to the final URL.");
+      }
+      if (response.ok) return response;
+      throw await errorOf(response, init.signal);
+    }
+  }
+  async function pause(attempt, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", stop);
+        resolve();
+      }, Math.min(100 * 2 ** (attempt - 1), 1e3));
+      const stop = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+      };
+      signal?.addEventListener("abort", stop, { once: true });
+    });
+  }
+  async function errorOf(response, signal) {
+    let code = "BAD_RESPONSE";
+    let message = `the server answered ${response.status}`;
+    try {
+      const parsed = await response.json();
+      if (typeof parsed.error?.code === "string" && KNOWN_CODES.has(parsed.error.code)) code = parsed.error.code;
+      else if (typeof parsed.error?.code === "string") message = `the server answered ${response.status} with an unknown code, ${JSON.stringify(parsed.error.code.slice(0, 40))}`;
+      if (code !== "BAD_RESPONSE" && typeof parsed.error?.message === "string") message = parsed.error.message;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+    }
+    return new DriveApiError(code, response.status, message);
+  }
+  async function json(method, path, init, check) {
+    const response = await send(method, path, init);
+    let value;
+    try {
+      value = await response.json();
+    } catch (error) {
+      if (init.signal?.aborted) throw error;
+      if (!(error instanceof SyntaxError)) throw new DriveApiError("NETWORK_ERROR", 0, "the connection dropped while the body came in");
+      throw new DriveApiError("BAD_RESPONSE", response.status, "the answer is not JSON");
+    }
+    if (!check(value)) throw new DriveApiError("BAD_RESPONSE", response.status, "the answer is not the shape that the API sends");
+    return value;
+  }
+  async function bytes(path, init, verify = false) {
+    const response = await send("GET", path, init);
+    let data;
+    try {
+      data = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      if (init.signal?.aborted) throw error;
+      throw new DriveApiError("NETWORK_ERROR", 0, "the connection dropped while the body came in");
+    }
+    const sha256 = response.headers.get("x-content-sha256") ?? "";
+    if (verify) {
+      if (!/^[0-9a-f]{64}$/.test(sha256)) throw new DriveApiError("BAD_RESPONSE", response.status, "the answer has no valid x-content-sha256");
+      if (typeof crypto === "undefined" || !crypto.subtle) throw new DriveApiError("BAD_RESPONSE", response.status, "this runtime has no WebCrypto, so the bytes cannot be checked. Use https.");
+      const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", data));
+      if (Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("") !== sha256) throw new DriveApiError("BAD_RESPONSE", response.status, "the bytes do not match their hash");
+    }
+    return { data, contentType: response.headers.get("content-type") ?? "application/octet-stream", sha256 };
+  }
+  const link = (token2) => {
+    if (token2 === void 0) return void 0;
+    if (!/^[A-Za-z0-9_-]{1,512}$/.test(token2)) throw new TypeError("a link token has 1 to 512 letters, digits, - or _");
+    return { "x-link-token": token2 };
+  };
+  const id = (value) => {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/.test(value) || value === "." || value === "..") throw new TypeError("an item id has letters, digits, -, _ and . (not first), and is not . or ..");
+    return value;
+  };
+  const isUrl = shape((v) => typeof v.url === "string" && /^https?:\/\//.test(v.url) && URL.canParse(v.url) && typeof v.expiresInSeconds === "number");
+  const isShares = shape(
+    (v) => listOf(shape((g) => (g.subjectKind === "human" || g.subjectKind === "agent") && text(g.subjectId) && oneOf(ROLES)(g.role)))(v.grants) && listOf(shape((l) => text(l.id) && oneOf(ROLES)(l.role) && typeof l.signedInOnly === "boolean" && orNull(num)(l.expiresAt) && typeof l.revoked === "boolean"))(v.links) && listOf(shape((i) => text(i.id) && oneOf(ROLES)(i.role) && orNull(text)(i.email) && orNull(text)(i.handle) && orNull(num)(i.expiresAt) && typeof i.accepted === "boolean"))(v.invites)
+  );
+  const isHome = shape((v) => record(v.apps) && Object.values(v.apps).every(num) && num(v.files) && listOf(shape((i) => isPathItem(i) && orNull(text)(i.app)))(v.items));
+  const isId = shape((v) => typeof v.id === "string");
+  const isLink = shape((v) => typeof v.id === "string" && typeof v.token === "string");
+  return {
+    /** The live items of a folder. */
+    list: (path = "/", o = {}) => json("GET", `/items${query({ path })}`, o, listOf(isItem)),
+    stat: (path, o = {}) => json("GET", `/stat${query({ path })}`, o, isItem),
+    mkdir: (path, opts = {}, o = {}) => json("POST", "/folders", { json: { path, parents: opts.parents === true }, ...o }, isItem),
+    /** Writes a file. A `ReadableStream` body streams in runtimes that allow it. */
+    upload: (path, body, opts = {}, o = {}) => json("PUT", `/files${query({ path, mime: opts.mime, parents: opts.parents === true ? true : void 0, onConflict: opts.onConflict })}`, {
+      body: typeof body === "string" ? new TextEncoder().encode(body) : body,
+      headers: { "content-type": "application/octet-stream" },
+      ...o
+    }, isItem),
+    /** The bytes. They are checked against the hash that the server sends. */
+    download: (path, o = {}) => bytes(`/files${query({ path })}`, o, true),
+    /** A signed link that works without a token, for `expires` seconds. You fetch the link yourself. */
+    url: (path, expires, o = {}) => json("GET", `/url${query({ path, expires })}`, o, isUrl),
+    move: (src, folder, opts = {}, o = {}) => json("POST", "/move", { json: { src, folder, ...opts }, ...o }, isItem),
+    trash: (path, o = {}) => json("POST", "/trash", { json: { path }, ...o }, isItem),
+    listTrash: (o = {}) => json("GET", "/trash", o, listOf(isItem)),
+    restore: (itemId, opts = {}, o = {}) => json("POST", "/restore", { json: { id: itemId, ...opts }, ...o }, isItem),
+    /** Deletes a trashed item for good. */
+    purge: (itemId, o = {}) => json("POST", "/purge", { json: { id: itemId }, ...o }, numbers("removed")),
+    search: (q = {}, o = {}) => json("GET", `/search${query(q)}`, o, listOf(isPathItem)),
+    /** Everything the caller has, as a zip. */
+    export: async (o = {}) => {
+      const { data } = await bytes("/export", o);
+      if (data[0] !== 80 || data[1] !== 75) throw new DriveApiError("BAD_RESPONSE", 200, "the answer is not a zip");
+      return data;
+    },
+    /** Erases the caller for good. The client sends `confirm=yes`. */
+    deleteAccount: (o = {}) => json("DELETE", "/account?confirm=yes", o, numbers("removed", "grants", "invites", "anonymized")),
+    home: (q = {}, o = {}) => json("GET", `/home${query(q)}`, o, isHome),
+    registerDocument: (input, o = {}) => json("POST", "/documents", { json: input, ...o }, isItem),
+    forgetDocument: (ref, o = {}) => json("DELETE", `/documents${query({ ref })}`, o, numbers("trashed")),
+    shares: (path, o = {}) => json("GET", `/shares${query({ path })}`, o, isShares),
+    share: (path, subject, role, o = {}) => json("POST", "/shares", { json: { path, subjectId: subject.id, subjectKind: subject.kind, role }, ...o }, isOk),
+    unshare: (path, subject, o = {}) => json("DELETE", `/shares${query({ path, subjectId: subject.id, subjectKind: subject.kind })}`, o, isOk),
+    /** Invite by `email` (a person) or `handle` (an agent). It sends no message. */
+    invite: (path, input, o = {}) => json("POST", "/invites", { json: { path, ...input }, ...o }, isId),
+    acceptInvite: (inviteId, o = {}) => json("POST", "/invites/accept", { json: { id: inviteId }, ...o }, isOk),
+    /** The token of a link comes back once. */
+    createLink: (path, input, o = {}) => json("POST", "/links", { json: { path, ...input }, ...o }, isLink),
+    revokeLink: (linkId, o = {}) => json("DELETE", `/links${query({ id: linkId })}`, o, isOk),
+    /** The next three read a shared item by id. Pass a link token, a bearer token, or both. */
+    openShared: async (itemId, opts = {}) => json("GET", `/shared/${id(itemId)}`, { auth: false, headers: link(opts.linkToken), signal: opts.signal }, isItem),
+    listShared: async (itemId, opts = {}) => json("GET", `/shared/${id(itemId)}/items`, { auth: false, headers: link(opts.linkToken), signal: opts.signal }, listOf(isItem)),
+    readShared: async (itemId, opts = {}) => {
+      const { data, contentType } = await bytes(`/shared/${id(itemId)}/content`, { auth: false, headers: link(opts.linkToken), signal: opts.signal });
+      return { data, contentType };
+    }
+  };
+}
+
+export {
+  DriveApiError,
+  createClient
+};