agentic-drive 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   VERSION
-} from "./chunk-4QE7E5UQ.js";
+} from "./chunk-GMA5I5L6.js";
 import {
   DriveError,
   buildExport,
   openLocal,
   publicNode,
   upload
-} from "./chunk-QRGKXPLX.js";
+} from "./chunk-VSVIJBMJ.js";
 
 // src/cli.ts
 import { createReadStream, realpathSync, writeFileSync } from "fs";
@@ -33,7 +33,10 @@ Commands:
   purge <id>                   Delete a trashed item for good.
   search                       Find items. Flags: --name --mime --kind --min-size --max-size --created-by-kind --limit
   export <out.zip>             Write everything you own to a zip with a JSON manifest.
-  delete-all --yes             Delete everything you own for good.
+  home [--app <name>]          List files and app documents, newest change first.
+  register <ref> <name>        Put an app document in the drive. Flag: --parent <folder>
+  forget <ref>                 Move the references to an app document to the trash.
+  delete-all --yes             Erase you for good: your drive, and what you shared or held.
   mcp                          Start the MCP server on stdio.
 
 Flags:
@@ -62,6 +65,7 @@ var options = {
   "max-size": { type: "string" },
   "created-by-kind": { type: "string" },
   limit: { type: "string" },
+  app: { type: "string" },
   yes: { type: "boolean" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "V" }
@@ -164,9 +168,22 @@ async function runCli(argv, io) {
         print({ saved: resolve(args[0]), size: zip.byteLength });
         break;
       }
+      case "home": {
+        const home = await drive.home(ctx, { app: values.app, limit: num(values.limit, "limit") });
+        print({ apps: home.apps, files: home.files, items: home.items.map((i) => ({ ...publicNode(i.node, i.path), app: i.app })) });
+        break;
+      }
+      case "register":
+        need(2, "register <ref> <name>");
+        print(publicNode(await drive.registerDocument(ctx, { ref: args[0], name: args[1], folder: values.parent })));
+        break;
+      case "forget":
+        need(1, "forget <ref>");
+        print(await drive.forgetDocument(ctx, args[0]));
+        break;
       case "delete-all":
-        if (!values.yes) throw new UsageError("delete-all removes everything you own for good. Add --yes to confirm.");
-        print(await drive.deleteAll(ctx));
+        if (!values.yes) throw new UsageError("delete-all erases you for good. Add --yes to confirm.");
+        print(await drive.erasePerson(ctx));
         break;
       case "mcp": {
         const { startMcp } = await import("./mcp.js");

package/dist/client.d.ts

@@ -0,0 +1,173 @@
+import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Dlzwukjq.js';
+import 'agentic-identity';
+
+type Role = "viewer" | "commenter" | "editor" | "owner";
+type OnConflict = "fail" | "rename" | "replace";
+type SubjectKind = "human" | "agent";
+type Subject = {
+    kind: SubjectKind;
+    id: string;
+};
+/** An item as the API prints it: no storage keys. */
+type Item = Omit<Node, "nameKey" | "blobKey" | "purging">;
+/** A search hit, or a home item: an item with its path. */
+type PathItem = Item & {
+    path: string;
+};
+/** The codes of the drive, and the ones that only the Worker raises. */
+type ApiErrorCode = ErrorCode | "UNAUTHORIZED" | "NOT_CONFIGURED" | "INVALID_LINK" | "INTERNAL";
+/** `NETWORK_ERROR` means no answer came (status 0). `BAD_RESPONSE` means an answer that is not the API's. */
+type ClientErrorCode = ApiErrorCode | "NETWORK_ERROR" | "BAD_RESPONSE";
+/** The error of every failed call. `code` is the code of the API, and `status` is the HTTP status. */
+declare class DriveApiError extends Error {
+    readonly code: ClientErrorCode;
+    readonly status: number;
+    constructor(code: ClientErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** The origin of the Worker, such as `https://drive.example.com`. */
+    baseUrl: string;
+    /** A bearer token. It is optional only for the link routes, `openShared`, `listShared`, and `readShared`. */
+    token?: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** How often a read (GET) call tries again after a network error or a 502, 503, or 504. The default is 0. A write is never tried again. */
+    retries?: number;
+}
+interface CallOptions {
+    signal?: AbortSignal;
+}
+type UploadBody = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+interface Downloaded {
+    data: Uint8Array;
+    contentType: string;
+    sha256: string;
+}
+declare function createClient(options: ClientOptions): {
+    /** The live items of a folder. */
+    list: (path?: string, o?: CallOptions) => Promise<Item[]>;
+    stat: (path: string, o?: CallOptions) => Promise<Item>;
+    mkdir: (path: string, opts?: {
+        parents?: boolean;
+    }, o?: CallOptions) => Promise<Item>;
+    /** Writes a file. A `ReadableStream` body streams in runtimes that allow it. */
+    upload: (path: string, body: UploadBody, opts?: {
+        mime?: string;
+        parents?: boolean;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    /** The bytes. They are checked against the hash that the server sends. */
+    download: (path: string, o?: CallOptions) => Promise<Downloaded>;
+    /** A signed link that works without a token, for `expires` seconds. You fetch the link yourself. */
+    url: (path: string, expires?: number, o?: CallOptions) => Promise<{
+        url: string;
+        expiresInSeconds: number;
+    }>;
+    move: (src: string, folder: string, opts?: {
+        name?: string;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    trash: (path: string, o?: CallOptions) => Promise<Item>;
+    listTrash: (o?: CallOptions) => Promise<Item[]>;
+    restore: (itemId: string, opts?: {
+        parentId?: string;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
+    /** Deletes a trashed item for good. */
+    purge: (itemId: string, o?: CallOptions) => Promise<{
+        removed: number;
+    }>;
+    search: (q?: Pick<SearchQuery, "name" | "mime" | "kind" | "minSize" | "maxSize" | "createdByKind" | "app" | "limit">, o?: CallOptions) => Promise<PathItem[]>;
+    /** Everything the caller has, as a zip. */
+    export: (o?: CallOptions) => Promise<Uint8Array<ArrayBufferLike>>;
+    /** Erases the caller for good. The client sends `confirm=yes`. */
+    deleteAccount: (o?: CallOptions) => Promise<{
+        removed: number;
+        grants: number;
+        invites: number;
+        anonymized: number;
+    }>;
+    home: (q?: {
+        app?: string;
+        limit?: number;
+    }, o?: CallOptions) => Promise<{
+        apps: Record<string, number>;
+        files: number;
+        items: (PathItem & {
+            app: string | null;
+        })[];
+    }>;
+    registerDocument: (input: {
+        ref: string;
+        name: string;
+        folder?: string;
+    }, o?: CallOptions) => Promise<Item>;
+    forgetDocument: (ref: string, o?: CallOptions) => Promise<{
+        trashed: number;
+    }>;
+    shares: (path: string, o?: CallOptions) => Promise<{
+        grants: {
+            subjectKind: SubjectKind;
+            subjectId: string;
+            role: Role;
+        }[];
+        links: {
+            id: string;
+            role: Role;
+            signedInOnly: boolean;
+            expiresAt: number | null;
+            revoked: boolean;
+        }[];
+        invites: {
+            id: string;
+            role: Role;
+            email: string | null;
+            handle: string | null;
+            expiresAt: number | null;
+            accepted: boolean;
+        }[];
+    }>;
+    share: (path: string, subject: Subject, role: Role, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    unshare: (path: string, subject: Subject, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** Invite by `email` (a person) or `handle` (an agent). It sends no message. */
+    invite: (path: string, input: {
+        role: Role;
+        email?: string;
+        handle?: string;
+        expiresInMs?: number;
+    }, o?: CallOptions) => Promise<{
+        id: string;
+    }>;
+    acceptInvite: (inviteId: string, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** The token of a link comes back once. */
+    createLink: (path: string, input: {
+        role: Role;
+        expiresInMs?: number;
+        signedInOnly?: boolean;
+    }, o?: CallOptions) => Promise<{
+        id: string;
+        token: string;
+    }>;
+    revokeLink: (linkId: string, o?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** The next three read a shared item by id. Pass a link token, a bearer token, or both. */
+    openShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Item>;
+    listShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Item[]>;
+    readShared: (itemId: string, opts?: {
+        linkToken?: string;
+    } & CallOptions) => Promise<Omit<Downloaded, "sha256">>;
+};
+type DriveClient = ReturnType<typeof createClient>;
+
+export { type ApiErrorCode, type CallOptions, type ClientErrorCode, type ClientOptions, type Downloaded, DriveApiError, type DriveClient, type Item, type OnConflict, type PathItem, type Role, type Subject, type SubjectKind, type UploadBody, createClient };

package/dist/client.js

@@ -0,0 +1,240 @@
+// 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", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+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(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);
+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
+};