@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/google/declared.js

@@ -0,0 +1,146 @@
+import { ITEM_BODY_MAX_BYTES } from "../contract.js";
+import { KitRefusal } from "../refusal.js";
+import { googleJson } from "./gateway.js";
+
+function valueAt(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (current === null || current === undefined || typeof current !== "object") return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function requiredText(value, declaration) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new KitRefusal("google_provider_response_invalid", declaration);
+  }
+  return value;
+}
+
+function optionalText(value, declaration) {
+  if (value === undefined || value === null) return null;
+  return requiredText(value, declaration);
+}
+
+function cursorOf(value) {
+  if (value === null) return { pageToken: null, checkpoint: null };
+  let cursor;
+  try {
+    cursor = JSON.parse(value);
+  } catch {
+    throw new KitRefusal("google_checkpoint_invalid", "declared service");
+  }
+  if (
+    typeof cursor !== "object" ||
+    cursor === null ||
+    (cursor.pageToken !== null && typeof cursor.pageToken !== "string") ||
+    (cursor.checkpoint !== null && typeof cursor.checkpoint !== "string")
+  ) {
+    throw new KitRefusal("google_checkpoint_invalid", "declared service");
+  }
+  return cursor;
+}
+
+function composedBody(item, paths) {
+  const parts = paths.map((path) => valueAt(item, path));
+  if (parts.some((part) => !["string", "number", "boolean"].includes(typeof part))) {
+    throw new KitRefusal("google_provider_response_invalid", "declared body");
+  }
+  const body = parts.map((part) => `${part}`).join("\n\n");
+  if (Buffer.byteLength(body, "utf8") > ITEM_BODY_MAX_BYTES) {
+    throw new KitRefusal("google_provider_response_invalid", "declared body");
+  }
+  return body;
+}
+
+function normalizedItem(service, item) {
+  const fields = service.declaration.fields;
+  const observedAt = requiredText(valueAt(item, fields.observedAt), "declared observed time");
+  if (Number.isNaN(Date.parse(observedAt))) {
+    throw new KitRefusal("google_provider_response_invalid", "declared observed time");
+  }
+  const container = requiredText(valueAt(item, fields.container), "declared container");
+  const nativeVersion =
+    fields.nativeVersion === null
+      ? null
+      : optionalText(valueAt(item, fields.nativeVersion), "declared native version");
+  const providerModifiedAt =
+    fields.providerModifiedAt === null
+      ? null
+      : optionalText(
+          valueAt(item, fields.providerModifiedAt),
+          "declared provider modification time",
+        );
+  if (providerModifiedAt !== null && Number.isNaN(Date.parse(providerModifiedAt))) {
+    throw new KitRefusal("google_provider_response_invalid", "declared provider modification time");
+  }
+  return {
+    namespace: `google/${service.service}`,
+    nativeObjectId: requiredText(valueAt(item, fields.nativeId), "declared native id"),
+    nativeVersion,
+    providerModifiedAt:
+      providerModifiedAt === null ? null : new Date(providerModifiedAt).toISOString(),
+    observedAt: new Date(observedAt).toISOString(),
+    body: composedBody(item, fields.body),
+    author:
+      fields.author === null
+        ? null
+        : optionalText(valueAt(item, fields.author), "declared author"),
+    url:
+      fields.url === null ? null : optionalText(valueAt(item, fields.url), "declared url"),
+    attachments: [],
+    container: `google/${service.service}/${container}`,
+  };
+}
+
+export async function declaredPage(options, dependencies = {}) {
+  const declared = options.service.declaration;
+  const cursor = cursorOf(options.cursor);
+  const url = new URL(declared.path, `https://${declared.host}`);
+  for (const [name, value] of Object.entries(declared.query)) url.searchParams.set(name, value);
+  url.searchParams.set(declared.pageSize, `${options.limit}`);
+  if (cursor.pageToken !== null) {
+    url.searchParams.set(declared.pageToken.request, cursor.pageToken);
+  }
+  if (cursor.checkpoint !== null) {
+    url.searchParams.set(declared.pageToken.checkpointRequest, cursor.checkpoint);
+  }
+  const answer = await googleJson(
+    {
+      directory: options.directory,
+      instance: options.instance,
+      client: options.client,
+      requiredScopes: declared.scopes,
+      url: url.toString(),
+      signal: options.signal,
+    },
+    dependencies,
+  );
+  const entries = valueAt(answer, declared.items);
+  if (!Array.isArray(entries) || entries.length > options.limit) {
+    throw new KitRefusal("google_provider_response_invalid", "declared items");
+  }
+  const pageToken = valueAt(answer, declared.pageToken.response);
+  let next;
+  if (pageToken !== undefined && pageToken !== null) {
+    next = {
+      pageToken: requiredText(pageToken, "declared page token"),
+      checkpoint: cursor.checkpoint,
+    };
+  } else {
+    next = {
+      pageToken: null,
+      checkpoint: requiredText(
+        valueAt(answer, declared.pageToken.checkpointResponse),
+        "declared checkpoint",
+      ),
+    };
+  }
+  return {
+    items: entries.map((entry) => normalizedItem(options.service, entry)),
+    dropped: [],
+    cursor: JSON.stringify(next),
+    more: pageToken !== undefined && pageToken !== null,
+  };
+}

package/src/google/drive.js

@@ -0,0 +1,435 @@
+import { ITEM_BODY_MAX_BYTES } from "../contract.js";
+import { KitRefusal } from "../refusal.js";
+import { googleBoundedText, googleJson } from "./gateway.js";
+import { GOOGLE_DRIVE_ID } from "./id.js";
+import { GOOGLE_SCOPES } from "./oauth.js";
+
+const DRIVE_ORIGIN = "https://www.googleapis.com";
+const FOLDER_MIME = "application/vnd.google-apps.folder";
+const GOOGLE_MIME_PREFIX = "application/vnd.google-apps.";
+const GOOGLE_EXPORT_MIMES = new Map([
+  [`${GOOGLE_MIME_PREFIX}document`, "text/plain"],
+  [`${GOOGLE_MIME_PREFIX}spreadsheet`, "text/csv"],
+  [`${GOOGLE_MIME_PREFIX}presentation`, "text/plain"],
+  [`${GOOGLE_MIME_PREFIX}drawing`, "image/svg+xml"],
+  [`${GOOGLE_MIME_PREFIX}script`, `${GOOGLE_MIME_PREFIX}script+json`],
+]);
+const TEXT_MIMES = new Set([
+  "application/json",
+  "application/xml",
+  "application/xhtml+xml",
+  "image/svg+xml",
+]);
+const FILE_FIELDS = "id,name,mimeType,modifiedTime,version,parents,webViewLink,owners,trashed";
+const FOLDER_FRONTIER_MAX = 4096;
+
+function selectionsOf(selection) {
+  return [
+    ...selection.files.map((id) => ({ kind: "file", id })),
+    ...selection.folders.map((id) => ({ kind: "folder", id })),
+  ];
+}
+
+function cursorOf(value, selections) {
+  if (value === null) return null;
+  let cursor;
+  try {
+    cursor = JSON.parse(value);
+  } catch {
+    throw new KitRefusal("google_checkpoint_invalid", "drive");
+  }
+  const validSnapshot =
+    cursor?.phase === "snapshot" &&
+    Number.isInteger(cursor.selection) &&
+    cursor.selection >= 0 &&
+    cursor.selection < selections.length &&
+    (cursor.pageToken === null || typeof cursor.pageToken === "string") &&
+    typeof cursor.changeToken === "string" &&
+    Array.isArray(cursor.folders) &&
+    cursor.folders.every(
+      (folder) => typeof folder === "string" && GOOGLE_DRIVE_ID.test(folder),
+    ) &&
+    Array.isArray(cursor.visited) &&
+    cursor.visited.every(
+      (folder) => typeof folder === "string" && GOOGLE_DRIVE_ID.test(folder),
+    ) &&
+    new Set([...cursor.folders, ...cursor.visited]).size ===
+      cursor.folders.length + cursor.visited.length &&
+    cursor.folders.length + cursor.visited.length <= FOLDER_FRONTIER_MAX &&
+    (selections[cursor.selection].kind === "folder"
+      ? cursor.folders.length > 0
+      : cursor.folders.length === 0 && cursor.visited.length === 0);
+  const validChanges =
+    cursor?.phase === "changes" &&
+    cursor.selection === 0 &&
+    typeof cursor.pageToken === "string";
+  if (!validSnapshot && !validChanges) throw new KitRefusal("google_checkpoint_invalid", "drive");
+  return cursor;
+}
+
+function common(options) {
+  return {
+    directory: options.directory,
+    instance: options.instance,
+    client: options.client,
+    requiredScopes: [GOOGLE_SCOPES.drive],
+    signal: options.signal,
+  };
+}
+
+function fileUrl(id, query = {}) {
+  const url = new URL(`/drive/v3/files/${encodeURIComponent(id)}`, DRIVE_ORIGIN);
+  for (const [name, value] of Object.entries(query)) url.searchParams.set(name, value);
+  return url.toString();
+}
+
+function fileMetadata(value) {
+  if (
+    typeof value?.id !== "string" ||
+    !GOOGLE_DRIVE_ID.test(value.id) ||
+    typeof value.name !== "string" ||
+    typeof value.mimeType !== "string" ||
+    (value.parents !== undefined &&
+      (!Array.isArray(value.parents) ||
+        value.parents.some(
+          (parent) => typeof parent !== "string" || !GOOGLE_DRIVE_ID.test(parent),
+        )))
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "drive file");
+  }
+  return value;
+}
+
+async function parentPath(options, file, dependencies, cache) {
+  const names = [];
+  const identifiers = [];
+  const seen = new Set();
+  let parent = file.parents?.[0] ?? null;
+  while (parent !== null && parent !== "root") {
+    if (seen.has(parent)) throw new KitRefusal("google_provider_response_invalid", "drive parents");
+    seen.add(parent);
+    let metadata = cache.get(parent);
+    if (metadata === undefined) {
+      metadata = fileMetadata(
+        await googleJson(
+          {
+            ...common(options),
+            url: fileUrl(parent, { fields: FILE_FIELDS }),
+            notFoundCode: "google_drive_item_missing",
+          },
+          dependencies,
+        ),
+      );
+      cache.set(parent, metadata);
+    }
+    if (metadata.mimeType !== FOLDER_MIME) {
+      throw new KitRefusal("google_provider_response_invalid", "drive parent");
+    }
+    names.unshift(metadata.name);
+    identifiers.unshift(metadata.id);
+    parent = metadata.parents?.[0] ?? null;
+  }
+  return { names, identifiers };
+}
+
+async function contentOf(options, file, dependencies) {
+  const exported = GOOGLE_EXPORT_MIMES.get(file.mimeType);
+  if (
+    exported === undefined &&
+    !file.mimeType.startsWith("text/") &&
+    !TEXT_MIMES.has(file.mimeType)
+  ) {
+    throw new KitRefusal("google_drive_content_unsupported");
+  }
+  const url =
+    exported === undefined
+      ? fileUrl(file.id, { alt: "media" })
+      : `${DRIVE_ORIGIN}/drive/v3/files/${encodeURIComponent(file.id)}/export?mimeType=${encodeURIComponent(exported)}`;
+  try {
+    return await googleBoundedText(
+      { ...common(options), url, notFoundCode: "google_drive_item_missing" },
+      ITEM_BODY_MAX_BYTES,
+      dependencies,
+    );
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "google_content_exceeded") {
+      throw new KitRefusal("google_drive_content_exceeded");
+    }
+    throw error;
+  }
+}
+
+function authorOf(file) {
+  const owner = Array.isArray(file.owners) ? file.owners[0] : null;
+  if (typeof owner?.emailAddress !== "string") return null;
+  return typeof owner.displayName === "string"
+    ? `${owner.displayName} <${owner.emailAddress}>`
+    : owner.emailAddress;
+}
+
+async function normalizedFile(options, file, dependencies, cache) {
+  const metadata = fileMetadata(file);
+  if (
+    metadata.mimeType === FOLDER_MIME ||
+    typeof metadata.modifiedTime !== "string" ||
+    Number.isNaN(Date.parse(metadata.modifiedTime)) ||
+    (metadata.version !== undefined && typeof metadata.version !== "string") ||
+    (metadata.webViewLink !== undefined && typeof metadata.webViewLink !== "string")
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "drive content");
+  }
+  const body = await contentOf(options, metadata, dependencies);
+  const folders = await parentPath(options, metadata, dependencies, cache);
+  return {
+    namespace: "google/drive",
+    nativeObjectId: metadata.id,
+    nativeVersion: metadata.version ?? metadata.modifiedTime,
+    providerModifiedAt: new Date(metadata.modifiedTime).toISOString(),
+    observedAt: new Date(metadata.modifiedTime).toISOString(),
+    body,
+    author: authorOf(metadata),
+    url: metadata.webViewLink ?? null,
+    attachments: [],
+    container: `google/drive${folders.names.length === 0 ? "" : `/${folders.names.join("/")}`}`,
+  };
+}
+
+function droppedFile(file, code) {
+  return {
+    namespace: "google/drive",
+    nativeObjectId: file.id,
+    nativeVersion: file.version ?? file.modifiedTime ?? null,
+    code,
+  };
+}
+
+async function normalizeFiles(options, files, dependencies, cache) {
+  const items = [];
+  const dropped = [];
+  for (const file of files) {
+    if (file.mimeType === FOLDER_MIME) continue;
+    try {
+      items.push(await normalizedFile(options, file, dependencies, cache));
+    } catch (error) {
+      if (
+        error instanceof KitRefusal &&
+        [
+          "google_drive_content_unsupported",
+          "google_drive_content_exceeded",
+          "google_drive_item_missing",
+        ].includes(error.code)
+      ) {
+        dropped.push(droppedFile(file, error.code));
+      } else {
+        throw error;
+      }
+    }
+  }
+  return { items, dropped };
+}
+
+async function startPageToken(options, dependencies) {
+  const answer = await googleJson(
+    { ...common(options), url: `${DRIVE_ORIGIN}/drive/v3/changes/startPageToken` },
+    dependencies,
+  );
+  if (typeof answer.startPageToken !== "string") {
+    throw new KitRefusal("google_provider_response_invalid", "drive start page token");
+  }
+  return answer.startPageToken;
+}
+
+async function snapshotPage(options, cursor, selections, dependencies) {
+  const selected = selections[cursor.selection];
+  let files;
+  const dropped = [];
+  let nextPageToken = null;
+  if (selected.kind === "file") {
+    try {
+      files = [
+        fileMetadata(
+          await googleJson(
+            {
+              ...common(options),
+              url: fileUrl(selected.id, { fields: FILE_FIELDS }),
+              notFoundCode: "google_drive_item_missing",
+            },
+            dependencies,
+          ),
+        ),
+      ];
+    } catch (error) {
+      if (!(error instanceof KitRefusal) || error.code !== "google_drive_item_missing") throw error;
+      files = [];
+      dropped.push({
+        namespace: "google/drive",
+        nativeObjectId: selected.id,
+        nativeVersion: null,
+        code: error.code,
+      });
+    }
+  } else {
+    const folder = cursor.folders[0];
+    const url = new URL("/drive/v3/files", DRIVE_ORIGIN);
+    url.searchParams.set("q", `'${folder}' in parents and trashed = false`);
+    url.searchParams.set("pageSize", `${options.limit}`);
+    url.searchParams.set("fields", `nextPageToken,files(${FILE_FIELDS})`);
+    if (cursor.pageToken !== null) url.searchParams.set("pageToken", cursor.pageToken);
+    const answer = await googleJson({ ...common(options), url: url.toString() }, dependencies);
+    if (
+      !Array.isArray(answer.files) ||
+      (answer.nextPageToken !== undefined && typeof answer.nextPageToken !== "string")
+    ) {
+      throw new KitRefusal("google_provider_response_invalid", "drive files");
+    }
+    files = answer.files.map(fileMetadata);
+    nextPageToken = answer.nextPageToken ?? null;
+  }
+  const cache = new Map();
+  const normalized = await normalizeFiles(options, files, dependencies, cache);
+  const knownFolders = new Set([...cursor.folders, ...cursor.visited]);
+  const discoveredFolders = [
+    ...new Set(
+      files
+        .filter((file) => file.mimeType === FOLDER_MIME && !knownFolders.has(file.id))
+        .map((file) => file.id),
+    ),
+  ];
+  if (knownFolders.size + discoveredFolders.length > FOLDER_FRONTIER_MAX) {
+    throw new KitRefusal("google_drive_selection_exceeded");
+  }
+  let next;
+  if (nextPageToken !== null) {
+    next = {
+      phase: "snapshot",
+      selection: cursor.selection,
+      pageToken: nextPageToken,
+      changeToken: cursor.changeToken,
+      folders: [...cursor.folders, ...discoveredFolders],
+      visited: cursor.visited,
+    };
+  } else if (
+    selected.kind === "folder" &&
+    cursor.folders.length - 1 + discoveredFolders.length > 0
+  ) {
+    next = {
+      phase: "snapshot",
+      selection: cursor.selection,
+      pageToken: null,
+      changeToken: cursor.changeToken,
+      folders: [...cursor.folders.slice(1), ...discoveredFolders],
+      visited: [...cursor.visited, cursor.folders[0]],
+    };
+  } else if (cursor.selection + 1 < selections.length) {
+    const following = selections[cursor.selection + 1];
+    next = {
+      phase: "snapshot",
+      selection: cursor.selection + 1,
+      pageToken: null,
+      changeToken: cursor.changeToken,
+      folders: following.kind === "folder" ? [following.id] : [],
+      visited: [],
+    };
+  } else {
+    next = { phase: "changes", selection: 0, pageToken: cursor.changeToken };
+  }
+  return {
+    items: normalized.items,
+    dropped: [...dropped, ...normalized.dropped],
+    cursor: JSON.stringify(next),
+    more: true,
+  };
+}
+
+async function selectedChange(options, file, dependencies, cache) {
+  if (options.selection.files.includes(file.id)) return true;
+  const folders = await parentPath(options, file, dependencies, cache);
+  return folders.identifiers.some((folder) => options.selection.folders.includes(folder));
+}
+
+async function changesPage(options, cursor, dependencies) {
+  const url = new URL("/drive/v3/changes", DRIVE_ORIGIN);
+  url.searchParams.set("pageToken", cursor.pageToken);
+  url.searchParams.set("pageSize", `${options.limit}`);
+  url.searchParams.set("includeRemoved", "false");
+  url.searchParams.set("fields", `nextPageToken,newStartPageToken,changes(fileId,removed,file(${FILE_FIELDS}))`);
+  const answer = await googleJson(
+    {
+      ...common(options),
+      url: url.toString(),
+      goneCode: "google_drive_cursor_expired",
+    },
+    dependencies,
+  );
+  if (
+    !Array.isArray(answer.changes) ||
+    (answer.nextPageToken !== undefined && typeof answer.nextPageToken !== "string") ||
+    (answer.newStartPageToken !== undefined && typeof answer.newStartPageToken !== "string")
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "drive changes");
+  }
+  const files = answer.changes
+    .filter((change) => change?.removed !== true && change?.file !== undefined)
+    .map((change) => fileMetadata(change.file));
+  const cache = new Map();
+  const selected = [];
+  const dropped = [];
+  for (const file of files) {
+    if (file.mimeType === FOLDER_MIME) continue;
+    try {
+      if (await selectedChange(options, file, dependencies, cache)) selected.push(file);
+    } catch (error) {
+      if (!(error instanceof KitRefusal) || error.code !== "google_drive_item_missing") throw error;
+      dropped.push(droppedFile(file, error.code));
+    }
+  }
+  const normalized = await normalizeFiles(options, selected, dependencies, cache);
+  const pageToken = answer.nextPageToken ?? answer.newStartPageToken;
+  if (typeof pageToken !== "string") {
+    throw new KitRefusal("google_provider_response_invalid", "drive change token");
+  }
+  return {
+    items: normalized.items,
+    dropped: [...dropped, ...normalized.dropped],
+    cursor: JSON.stringify({ phase: "changes", selection: 0, pageToken }),
+    more: answer.nextPageToken !== undefined,
+  };
+}
+
+export async function drivePage(options, dependencies = {}) {
+  const selections = selectionsOf(options.selection);
+  const stored = cursorOf(options.cursor, selections);
+  const cursor =
+    stored ?? {
+      phase: "snapshot",
+      selection: 0,
+      pageToken: null,
+      changeToken: await startPageToken(options, dependencies),
+      folders: selections[0].kind === "folder" ? [selections[0].id] : [],
+      visited: [],
+    };
+  if (cursor.phase === "snapshot") {
+    return snapshotPage(options, cursor, selections, dependencies);
+  }
+  try {
+    return await changesPage(options, cursor, dependencies);
+  } catch (error) {
+    if (!(error instanceof KitRefusal) || error.code !== "google_drive_cursor_expired") {
+      throw error;
+    }
+    const first = selections[0];
+    return snapshotPage(
+      options,
+      {
+        phase: "snapshot",
+        selection: 0,
+        pageToken: null,
+        changeToken: await startPageToken(options, dependencies),
+        folders: first.kind === "folder" ? [first.id] : [],
+        visited: [],
+      },
+      selections,
+      dependencies,
+    );
+  }
+}