@el-j/google-sheet-translations 2.2.0-beta.3 → 2.2.0-beta.5

package/dist/esm/index.js

@@ -1188,13 +1188,13 @@ GOOGLE_SPREADSHEET_ID=${id}
 async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
   const config = normalizeConfig(options);
   const baseDelayMs = config.waitSeconds * 1e3;
-  const docTitle = _docTitle ?? [];
-  if (docTitle.length === 0) {
+  const docTitle2 = _docTitle ?? [];
+  if (docTitle2.length === 0) {
     console.warn("No sheet titles provided, cannot process spreadsheet data");
     return {};
   }
-  if (!docTitle.includes("i18n")) {
-    docTitle.push("i18n");
+  if (!docTitle2.includes("i18n")) {
+    docTitle2.push("i18n");
   }
   const finalTranslations = {};
   const allLocales = /* @__PURE__ */ new Set();
@@ -1231,9 +1231,9 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
         "No spreadsheet ID provided. Set GOOGLE_SPREADSHEET_ID or pass spreadsheetId in options."
       );
     }
-    console.log(`Processing ${docTitle.length} sheets: ${docTitle.join(", ")}`);
+    console.log(`Processing ${docTitle2.length} sheets: ${docTitle2.join(", ")}`);
     await Promise.all(
-      docTitle.map(async (title) => {
+      docTitle2.map(async (title) => {
         let rows;
         try {
           rows = await withRetry(
@@ -1266,7 +1266,7 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
         );
       }
     }
-    console.log(`Processing ${docTitle.length} sheets: ${docTitle.join(", ")}`);
+    console.log(`Processing ${docTitle2.length} sheets: ${docTitle2.join(", ")}`);
     const doc = new GoogleSpreadsheet2(spreadsheetId, serviceAuthClient);
     try {
       await withRetry(() => doc.loadInfo(true), "loadInfo", baseDelayMs);
@@ -1274,7 +1274,7 @@ async function getSpreadSheetData(_docTitle, options = {}, _refreshDepth = 0) {
       throw new Error(`Failed to load spreadsheet "${spreadsheetId}"`, { cause: err });
     }
     await Promise.all(
-      docTitle.map(async (title) => {
+      docTitle2.map(async (title) => {
         const sheet = doc.sheetsByTitle[title];
         if (!sheet) {
           console.warn(`Sheet "${title}" not found in the document`);
@@ -1809,6 +1809,7 @@ function buildManifest(options) {
     locales,
     defaultLocale: options.defaultLocale,
     spreadsheets: options.spreadsheets,
+    docs: options.docs,
     outputDirectory: options.outputDirectory,
     flatten: options.flatten,
     projectMetadata: options.projectMetadata
@@ -1822,11 +1823,388 @@ function writeManifest(manifest, manifestPath) {
   fs6.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
   console.log(`[driveProjectIndex] Wrote project manifest \u2192 ${manifestPath}`);
 }
+function readManifest(manifestPath) {
+  try {
+    const content = fs6.readFileSync(manifestPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/utils/driveDocScanner.ts
+import { GoogleAuth as GoogleAuth2 } from "google-auth-library";
+var DOC_MIME = "application/vnd.google-apps.document";
+var FOLDER_MIME3 = "application/vnd.google-apps.folder";
+var DRIVE_FILES_URL3 = "https://www.googleapis.com/drive/v3/files";
+async function getAccessToken3(credentials) {
+  const clientEmail = credentials?.GOOGLE_CLIENT_EMAIL ?? process.env.GOOGLE_CLIENT_EMAIL;
+  const privateKey = credentials?.GOOGLE_PRIVATE_KEY ?? process.env.GOOGLE_PRIVATE_KEY;
+  if (!clientEmail || !privateKey) {
+    throw new Error(
+      "Google Drive credentials required: GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY"
+    );
+  }
+  const normalizedKey = privateKey.replace(/\\n/g, "\n");
+  const auth = new GoogleAuth2({
+    credentials: { client_email: clientEmail, private_key: normalizedKey },
+    scopes: ["https://www.googleapis.com/auth/drive.readonly"]
+  });
+  const client = await auth.getClient();
+  const tokenResponse = await client.getAccessToken();
+  return tokenResponse.token;
+}
+async function listFilesInFolder3(folderId, mimeType, token) {
+  const results = [];
+  let pageToken;
+  do {
+    const query = `'${folderId}' in parents and mimeType = '${mimeType}' and trashed = false`;
+    const params = new URLSearchParams({
+      q: query,
+      fields: "nextPageToken,files(id,name,mimeType,modifiedTime)",
+      pageSize: "1000"
+    });
+    if (pageToken) params.set("pageToken", pageToken);
+    const response = await fetch(`${DRIVE_FILES_URL3}?${params.toString()}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Drive API error ${response.status}: ${text}`);
+    }
+    const data = await response.json();
+    results.push(...data.files);
+    pageToken = data.nextPageToken;
+  } while (pageToken);
+  return results;
+}
+function inferLocaleFromDocName(name) {
+  const baseName = name.replace(/\.[^.]+$/, "");
+  const match = baseName.match(/_([a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?)$/);
+  if (!match) return void 0;
+  const candidate = match[1].replace("_", "-");
+  const parts = candidate.split("-");
+  if (parts.length === 2) {
+    return `${parts[0].toLowerCase()}-${parts[1].toUpperCase()}`;
+  }
+  return parts[0].toLowerCase();
+}
+async function scanFolder2(folderId, folderPath, token, recursive, nameFilter, seen = /* @__PURE__ */ new Set()) {
+  console.log(
+    `[driveDocScanner] Scanning folder: ${folderId} (path: "${folderPath}")`
+  );
+  const docs = await listFilesInFolder3(folderId, DOC_MIME, token);
+  const results = [];
+  for (const file of docs) {
+    if (seen.has(file.id)) continue;
+    seen.add(file.id);
+    if (nameFilter && !nameFilter.test(file.name)) continue;
+    results.push({
+      id: file.id,
+      name: file.name,
+      folderPath,
+      mimeType: file.mimeType,
+      modifiedTime: file.modifiedTime,
+      sourceLocale: inferLocaleFromDocName(file.name)
+    });
+  }
+  if (recursive) {
+    const subfolders = await listFilesInFolder3(folderId, FOLDER_MIME3, token);
+    for (const folder of subfolders) {
+      const subPath = folderPath ? `${folderPath}/${folder.name}` : folder.name;
+      const subResults = await scanFolder2(
+        folder.id,
+        subPath,
+        token,
+        recursive,
+        nameFilter,
+        seen
+      );
+      results.push(...subResults);
+    }
+  }
+  return results;
+}
+async function scanDriveFolderForDocs(options) {
+  const { folderId, recursive = true, nameFilter, credentials } = options;
+  const token = await getAccessToken3(credentials);
+  return scanFolder2(folderId, "", token, recursive, nameFilter);
+}
+
+// src/utils/docIngester.ts
+import { GoogleAuth as GoogleAuth3 } from "google-auth-library";
+import { GoogleSpreadsheet as GoogleSpreadsheet3 } from "google-spreadsheet";
+
+// src/utils/docParser.ts
+function slugifyKey(text) {
+  return text.toLowerCase().replace(/[^\w]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+}
+function parseDocContent(content, options = {}) {
+  const { strategy = "heading", defaultSheetName = "content" } = options;
+  if (strategy === "marker") return parseWithMarkers(content, defaultSheetName);
+  if (strategy === "numbered") return parseNumbered(content, defaultSheetName);
+  return parseWithHeadings(content, defaultSheetName);
+}
+function parseWithHeadings(content, defaultSheetName) {
+  const lines = content.split("\n");
+  const entries = [];
+  let currentSheet = defaultSheetName;
+  let currentKey = null;
+  const valueLines = [];
+  function flushEntry() {
+    if (currentKey !== null) {
+      const value = valueLines.join("\n").trim();
+      if (value) {
+        entries.push({ sheetName: currentSheet, key: currentKey, value });
+      }
+      currentKey = null;
+      valueLines.length = 0;
+    }
+  }
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (line.startsWith("# ")) {
+      flushEntry();
+      currentSheet = slugifyKey(line.slice(2).trim()) || defaultSheetName;
+      currentKey = null;
+      valueLines.length = 0;
+    } else if (line.startsWith("## ")) {
+      flushEntry();
+      currentKey = slugifyKey(line.slice(3).trim());
+      valueLines.length = 0;
+    } else if (currentKey !== null) {
+      valueLines.push(line);
+    }
+  }
+  flushEntry();
+  return entries;
+}
+function parseWithMarkers(content, defaultSheetName) {
+  const MARKER_RE = /\[\[key:([^\]]{1,200})\]\]/g;
+  const entries = [];
+  const segments = content.split(MARKER_RE);
+  for (let i = 1; i < segments.length; i += 2) {
+    const keyPath = segments[i].trim();
+    const value = (segments[i + 1] ?? "").trim();
+    if (!keyPath || !value) continue;
+    const dotIdx = keyPath.indexOf(".");
+    let sheetName;
+    let key;
+    if (dotIdx !== -1) {
+      sheetName = slugifyKey(keyPath.slice(0, dotIdx));
+      key = slugifyKey(keyPath.slice(dotIdx + 1));
+    } else {
+      sheetName = defaultSheetName;
+      key = slugifyKey(keyPath);
+    }
+    if (sheetName && key) {
+      entries.push({ sheetName, key, value });
+    }
+  }
+  return entries;
+}
+function parseNumbered(content, defaultSheetName) {
+  const entries = [];
+  let counter = 0;
+  const paragraphs = content.split(/\n{2,}/);
+  for (const para of paragraphs) {
+    const value = para.replace(/^[#\s]+/, "").trim();
+    if (value) {
+      counter++;
+      entries.push({
+        sheetName: defaultSheetName,
+        key: `item_${counter}`,
+        value
+      });
+    }
+  }
+  return entries;
+}
+
+// src/utils/docIngester.ts
+async function getDriveExportToken(credentials) {
+  const clientEmail = credentials?.GOOGLE_CLIENT_EMAIL ?? process.env.GOOGLE_CLIENT_EMAIL;
+  const privateKey = credentials?.GOOGLE_PRIVATE_KEY ?? process.env.GOOGLE_PRIVATE_KEY;
+  if (!clientEmail || !privateKey) {
+    throw new Error(
+      "Google Drive credentials required: GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY"
+    );
+  }
+  const normalizedKey = privateKey.replace(/\\n/g, "\n");
+  const auth = new GoogleAuth3({
+    credentials: { client_email: clientEmail, private_key: normalizedKey },
+    scopes: ["https://www.googleapis.com/auth/drive.readonly"]
+  });
+  const client = await auth.getClient();
+  const tokenResponse = await client.getAccessToken();
+  return tokenResponse.token;
+}
+async function exportDoc(docId, credentials) {
+  const token = await getDriveExportToken(credentials);
+  const base = `https://www.googleapis.com/drive/v3/files/${docId}/export`;
+  const mdRes = await fetch(
+    `${base}?mimeType=text%2Fmarkdown`,
+    { headers: { Authorization: `Bearer ${token}` } }
+  );
+  if (mdRes.ok) return mdRes.text();
+  const txtRes = await fetch(
+    `${base}?mimeType=text%2Fplain`,
+    { headers: { Authorization: `Bearer ${token}` } }
+  );
+  if (txtRes.ok) return txtRes.text();
+  const errText = await txtRes.text();
+  throw new Error(
+    `Failed to export doc ${docId}: HTTP ${txtRes.status} \u2013 ${errText}`
+  );
+}
+function entriesToSeedKeys(entries) {
+  const keys = {};
+  const counts = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const base = `${entry.sheetName}.${entry.key}`;
+    const count = (counts.get(base) ?? 0) + 1;
+    counts.set(base, count);
+    const finalKey = count > 1 ? `${base}_${count}` : base;
+    keys[finalKey] = entry.value;
+  }
+  return keys;
+}
+function entriesToTranslationData(entries, locale) {
+  if (locale === "__proto__" || locale === "constructor" || locale === "prototype") {
+    return {};
+  }
+  const data = {};
+  data[locale] = {};
+  const counts = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const sheetName = entry.sheetName;
+    const entryKey = entry.key;
+    if (sheetName === "__proto__" || sheetName === "constructor" || sheetName === "prototype" || entryKey === "__proto__" || entryKey === "constructor" || entryKey === "prototype") {
+      continue;
+    }
+    if (!data[locale][sheetName]) {
+      data[locale][sheetName] = {};
+    }
+    const base = `${sheetName}::${entryKey}`;
+    const count = (counts.get(base) ?? 0) + 1;
+    counts.set(base, count);
+    const finalKey = count > 1 ? `${entryKey}_${count}` : entryKey;
+    data[locale][sheetName][finalKey] = entry.value;
+  }
+  return data;
+}
+function docTitle(name) {
+  return name.replace(/_[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/, "").trim() || name;
+}
+async function ingestDoc(docFile, options = {}) {
+  const {
+    targetLocales,
+    keyStrategy = "heading",
+    updateMode = "create-only",
+    credentials,
+    existingEntry,
+    waitSeconds = 1
+  } = options;
+  const sourceLocale = docFile.sourceLocale ?? "en";
+  const entry = existingEntry ? { ...existingEntry, modifiedTime: docFile.modifiedTime } : {
+    id: docFile.id,
+    name: docFile.name,
+    folderPath: docFile.folderPath,
+    generatedFromDoc: true,
+    sourceLocale,
+    modifiedTime: docFile.modifiedTime
+  };
+  const hasLinkedSheet = !!entry.linkedSpreadsheetId;
+  const shouldRefresh = updateMode === "refresh-if-newer" && hasLinkedSheet && !!docFile.modifiedTime && !!existingEntry?.lastIngestedAt && new Date(docFile.modifiedTime) > new Date(existingEntry.lastIngestedAt);
+  if (hasLinkedSheet && !shouldRefresh) {
+    console.log(
+      `[docIngester] Skipping "${docFile.name}" \u2013 linked spreadsheet is already up-to-date.`
+    );
+    return { action: "skipped", entry };
+  }
+  console.log(
+    `[docIngester] Exporting doc "${docFile.name}" (id: ${docFile.id})\u2026`
+  );
+  const content = await exportDoc(docFile.id, credentials);
+  const sheetBaseName = slugifyKey(docTitle(docFile.name)) || "content";
+  const entries = parseDocContent(content, {
+    strategy: keyStrategy,
+    defaultSheetName: sheetBaseName
+  });
+  if (entries.length === 0) {
+    console.warn(
+      `[docIngester] Doc "${docFile.name}" produced no translation entries \u2013 skipping.`
+    );
+    return { action: "skipped", entry };
+  }
+  if (!hasLinkedSheet) {
+    const authClient2 = createAuthClient();
+    const seedKeys = entriesToSeedKeys(entries);
+    const title = docTitle(docFile.name);
+    const { spreadsheetId: spreadsheetId2 } = await createSpreadsheet(authClient2, {
+      title,
+      sourceLocale,
+      targetLocales,
+      seedKeys
+    });
+    entry.linkedSpreadsheetId = spreadsheetId2;
+    entry.lastIngestedAt = (/* @__PURE__ */ new Date()).toISOString();
+    console.log(
+      `[docIngester] Created spreadsheet ${spreadsheetId2} from doc "${docFile.name}".`
+    );
+    return { action: "created", entry };
+  }
+  const authClient = createAuthClient();
+  const spreadsheetId = entry.linkedSpreadsheetId;
+  const doc = new GoogleSpreadsheet3(spreadsheetId, authClient);
+  await doc.loadInfo();
+  const changes = entriesToTranslationData(entries, sourceLocale);
+  await updateSpreadsheetWithLocalChanges(
+    doc,
+    changes,
+    waitSeconds,
+    false,
+    // autoTranslate – formulas already exist in non-base columns
+    {},
+    false
+  );
+  entry.lastIngestedAt = (/* @__PURE__ */ new Date()).toISOString();
+  console.log(
+    `[docIngester] Refreshed spreadsheet ${spreadsheetId} from doc "${docFile.name}".`
+  );
+  return { action: "refreshed", entry };
+}
 
 // src/utils/getDriveTranslations.ts
 function sanitizeFolderName(name) {
   return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "sheet";
 }
+async function moveSpreadsheetToFolder(spreadsheetId, folderId) {
+  const clientEmail = process.env.GOOGLE_CLIENT_EMAIL;
+  const rawPrivateKey = process.env.GOOGLE_PRIVATE_KEY;
+  let credentials;
+  if (clientEmail && rawPrivateKey) {
+    credentials = { client_email: clientEmail, private_key: normalizePrivateKey(rawPrivateKey) };
+  }
+  const driveAuth = buildGoogleAuth(
+    ["https://www.googleapis.com/auth/drive.file"],
+    credentials
+  );
+  const fileRes = await driveAuth.request({
+    url: `https://www.googleapis.com/drive/v3/files/${spreadsheetId}`,
+    params: { fields: "parents" }
+  });
+  const parentIds = fileRes.data.parents ?? [];
+  await driveAuth.request({
+    url: `https://www.googleapis.com/drive/v3/files/${spreadsheetId}`,
+    method: "PATCH",
+    params: {
+      addParents: folderId,
+      ...parentIds.length > 0 ? { removeParents: parentIds.join(",") } : {},
+      fields: "id,parents"
+    }
+  });
+}
 async function manageDriveTranslations(options) {
   const {
     driveFolderId,
@@ -1844,7 +2222,14 @@ async function manageDriveTranslations(options) {
     projectName,
     domain,
     defaultLocale,
-    projectMetadata
+    projectMetadata,
+    // Doc ingestion options
+    scanForDocs = false,
+    docNameFilter,
+    docSourceLocale,
+    docKeyStrategy,
+    docUpdateMode,
+    docTargetLocales
   } = options;
   if (syncImages && !imageOutputPath) {
     throw new Error(
@@ -1875,6 +2260,36 @@ async function manageDriveTranslations(options) {
     if (!name) return true;
     return spreadsheetNameFilter.test(name);
   }) : allIds;
+  if (driveFolderId && filteredIds.length === 0 && translationOptions.autoCreate !== false) {
+    console.log(
+      `[manageDriveTranslations] Drive folder "${driveFolderId}" contains no spreadsheets. Bootstrapping a new spreadsheet\u2026`
+    );
+    const authClient = createAuthClient();
+    const bootstrapTitle = translationOptions.spreadsheetTitle ?? "google-sheet-translations";
+    const created = await createSpreadsheet(authClient, {
+      title: bootstrapTitle,
+      sourceLocale: translationOptions.sourceLocale,
+      targetLocales: translationOptions.targetLocales
+    });
+    console.log(`[manageDriveTranslations] \u2705 Spreadsheet created: ${created.url}`);
+    try {
+      await moveSpreadsheetToFolder(created.spreadsheetId, driveFolderId);
+      console.log(
+        `[manageDriveTranslations] \u2705 Spreadsheet moved into Drive folder "${driveFolderId}"`
+      );
+    } catch (moveErr) {
+      console.warn(
+        `[manageDriveTranslations] \u26A0\uFE0F  Could not move spreadsheet into Drive folder:`,
+        moveErr.message
+      );
+      console.warn(
+        `   Please move spreadsheet "${created.spreadsheetId}" into folder "${driveFolderId}" manually.`
+      );
+    }
+    filteredIds.push(created.spreadsheetId);
+    discoveredNames.set(created.spreadsheetId, bootstrapTitle);
+    discoveredFolderPaths.set(created.spreadsheetId, "");
+  }
   let translations;
   const spreadsheetEntries = [];
   const baseOutputDir = translationOptions.translationsOutputDir ?? "translations";
@@ -1928,8 +2343,48 @@ async function manageDriveTranslations(options) {
     });
   }
   let manifest;
+  let docIngestResults;
+  const docEntries = [];
+  const resolvedManifestPath = manifestPath ?? path6.join(baseOutputDir, "i18n-manifest.json");
+  if (driveFolderId && scanForDocs) {
+    const previousManifest = readManifest(resolvedManifestPath);
+    const docScanOptions = {
+      folderId: driveFolderId
+    };
+    const discoveredDocs = await scanDriveFolderForDocs(docScanOptions);
+    console.log(
+      `[manageDriveTranslations] Found ${discoveredDocs.length} doc(s) in Drive folder`
+    );
+    docIngestResults = [];
+    for (const docFile of discoveredDocs) {
+      if (docNameFilter && !docNameFilter.test(docFile.name)) continue;
+      if (!docFile.sourceLocale && docSourceLocale) {
+        docFile.sourceLocale = docSourceLocale;
+      }
+      const existingEntry = previousManifest?.docs?.find(
+        (d) => d.id === docFile.id
+      );
+      const ingesterOptions = {
+        targetLocales: docTargetLocales,
+        keyStrategy: docKeyStrategy,
+        updateMode: docUpdateMode,
+        existingEntry,
+        waitSeconds: translationOptions.waitSeconds
+      };
+      try {
+        const result = await ingestDoc(docFile, ingesterOptions);
+        docEntries.push(result.entry);
+        docIngestResults.push({ docName: docFile.name, action: result.action });
+      } catch (err) {
+        console.error(
+          `[manageDriveTranslations] Failed to ingest doc "${docFile.name}":`,
+          err
+        );
+        if (existingEntry) docEntries.push(existingEntry);
+      }
+    }
+  }
   if (shouldCreateManifest) {
-    const resolvedManifestPath = manifestPath ?? path6.join(baseOutputDir, "i18n-manifest.json");
     manifest = buildManifest({
       translations,
       spreadsheets: spreadsheetEntries,
@@ -1938,11 +2393,226 @@ async function manageDriveTranslations(options) {
       projectName,
       domain,
       defaultLocale,
-      projectMetadata
+      projectMetadata,
+      docs: docEntries.length > 0 ? docEntries : void 0
     });
     writeManifest(manifest, resolvedManifestPath);
   }
-  return { translations, spreadsheetIds: filteredIds, imageSync, manifest };
+  return { translations, spreadsheetIds: filteredIds, imageSync, manifest, docIngestResults };
+}
+
+// src/setup/wifSetup.ts
+import { GoogleAuth as GoogleAuth4 } from "google-auth-library";
+var GcpApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "GcpApiError";
+  }
+};
+async function getAccessToken4(keyFilePath) {
+  const auth = new GoogleAuth4({
+    ...keyFilePath ? { keyFilename: keyFilePath } : {},
+    scopes: ["https://www.googleapis.com/auth/cloud-platform"]
+  });
+  const client = await auth.getClient();
+  const tokenResponse = await client.getAccessToken();
+  if (!tokenResponse.token) {
+    throw new Error(
+      "Failed to obtain a Google Cloud access token. Ensure you are authenticated via Application Default Credentials (run: gcloud auth application-default login) or provide --key-file pointing to a service account JSON key."
+    );
+  }
+  return tokenResponse.token;
+}
+async function gcpFetch(url, token, method = "GET", body) {
+  const response = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    },
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const data = await response.json();
+  if (!response.ok) {
+    const errData = data;
+    const message = errData.error?.message ?? `HTTP ${response.status}`;
+    throw new GcpApiError(message, response.status);
+  }
+  return data;
+}
+async function pollOperation(operationName, token, maxWaitMs = 6e4) {
+  const opUrl = operationName.startsWith("http") ? operationName : `https://iam.googleapis.com/v1/${operationName}`;
+  const deadline = Date.now() + maxWaitMs;
+  const maxWaitSecs = Math.round(maxWaitMs / 1e3);
+  while (Date.now() < deadline) {
+    const op = await gcpFetch(opUrl, token);
+    if (op.done) {
+      if (op.error) {
+        throw new Error(`Operation failed: ${op.error.message}`);
+      }
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2e3));
+  }
+  if (Date.now() >= deadline) {
+    throw new Error(
+      `Operation timed out after ${maxWaitSecs} s. The resources may still be provisioning in the background \u2013 re-running the command is safe (existing resources are reused).`
+    );
+  }
+}
+async function getProjectNumber(projectId, token) {
+  const data = await gcpFetch(
+    `https://cloudresourcemanager.googleapis.com/v1/projects/${encodeURIComponent(projectId)}`,
+    token
+  );
+  return data.projectNumber;
+}
+async function createOrGetWifPool(projectId, poolId, token) {
+  try {
+    const op = await gcpFetch(
+      `https://iam.googleapis.com/v1/projects/${encodeURIComponent(projectId)}/locations/global/workloadIdentityPools?workloadIdentityPoolId=${encodeURIComponent(poolId)}`,
+      token,
+      "POST",
+      {
+        displayName: "GitHub Actions Pool",
+        description: "Pool for GitHub Actions OIDC authentication",
+        disabled: false
+      }
+    );
+    if (!op.done) {
+      await pollOperation(op.name, token);
+    } else if (op.error) {
+      throw new Error(`Operation failed: ${op.error.message}`);
+    }
+  } catch (err) {
+    if (err instanceof GcpApiError && err.status === 409) {
+      return;
+    }
+    throw err;
+  }
+}
+async function createOrGetWifProvider(projectId, poolId, providerId, githubRepo, token) {
+  try {
+    const op = await gcpFetch(
+      `https://iam.googleapis.com/v1/projects/${encodeURIComponent(projectId)}/locations/global/workloadIdentityPools/${encodeURIComponent(poolId)}/providers?workloadIdentityPoolProviderId=${encodeURIComponent(providerId)}`,
+      token,
+      "POST",
+      {
+        displayName: "GitHub OIDC Provider",
+        disabled: false,
+        attributeMapping: {
+          "google.subject": "assertion.sub",
+          "attribute.actor": "assertion.actor",
+          "attribute.repository": "assertion.repository"
+        },
+        // Scope the provider to this exact repository for security
+        attributeCondition: `assertion.repository=='${githubRepo}'`,
+        oidc: {
+          issuerUri: "https://token.actions.githubusercontent.com"
+        }
+      }
+    );
+    if (!op.done) {
+      await pollOperation(op.name, token);
+    } else if (op.error) {
+      throw new Error(`Operation failed: ${op.error.message}`);
+    }
+  } catch (err) {
+    if (err instanceof GcpApiError && err.status === 409) {
+      return;
+    }
+    throw err;
+  }
+}
+async function bindServiceAccount(projectId, serviceAccountEmail, projectNumber, poolId, githubRepo, token) {
+  const saResource = `projects/${encodeURIComponent(projectId)}/serviceAccounts/${encodeURIComponent(serviceAccountEmail)}`;
+  const principal = `principalSet://iam.googleapis.com/projects/${projectNumber}/locations/global/workloadIdentityPools/${poolId}/attribute.repository/${githubRepo}`;
+  const policy = await gcpFetch(
+    `https://iam.googleapis.com/v1/${saResource}:getIamPolicy`,
+    token,
+    "POST",
+    {}
+  );
+  const bindings = policy.bindings ?? [];
+  const role = "roles/iam.workloadIdentityUser";
+  const existing = bindings.find((b) => b.role === role);
+  if (existing) {
+    if (existing.members.includes(principal)) {
+      return;
+    }
+    existing.members.push(principal);
+  } else {
+    bindings.push({ role, members: [principal] });
+  }
+  await gcpFetch(
+    `https://iam.googleapis.com/v1/${saResource}:setIamPolicy`,
+    token,
+    "POST",
+    { policy: { ...policy, bindings } }
+  );
+}
+async function setupWIF(options) {
+  const poolId = options.poolId ?? "github-actions";
+  const providerId = options.providerId ?? "github-oidc";
+  const log = options.onProgress ?? (() => void 0);
+  if (!options.githubRepo.includes("/")) {
+    throw new Error(
+      `githubRepo must be in "owner/repo" format, got: "${options.githubRepo}"`
+    );
+  }
+  log("Authenticating with Google Cloud...");
+  const token = await getAccessToken4(options.keyFilePath);
+  log("Fetching project number...");
+  const projectNumber = await getProjectNumber(options.projectId, token);
+  log(`Creating Workload Identity Pool "${poolId}"...`);
+  await createOrGetWifPool(options.projectId, poolId, token);
+  log(`Creating OIDC Provider "${providerId}"...`);
+  await createOrGetWifProvider(
+    options.projectId,
+    poolId,
+    providerId,
+    options.githubRepo,
+    token
+  );
+  log("Binding service account permissions...");
+  await bindServiceAccount(
+    options.projectId,
+    options.serviceAccountEmail,
+    projectNumber,
+    poolId,
+    options.githubRepo,
+    token
+  );
+  const wifProvider = `projects/${projectNumber}/locations/global/workloadIdentityPools/${poolId}/providers/${providerId}`;
+  return { wifProvider, projectNumber, poolId, providerId };
+}
+async function grantDrivePermissions(options) {
+  const token = await getAccessToken4(options.keyFilePath);
+  const policy = await gcpFetch(
+    `https://cloudresourcemanager.googleapis.com/v1/projects/${encodeURIComponent(options.projectId)}:getIamPolicy`,
+    token,
+    "POST",
+    {}
+  );
+  const bindings = policy.bindings ?? [];
+  const role = "roles/drive.file";
+  const member = `serviceAccount:${options.serviceAccountEmail}`;
+  const existing = bindings.find((b) => b.role === role);
+  if (existing) {
+    if (existing.members.includes(member)) {
+      return;
+    }
+    existing.members.push(member);
+  } else {
+    bindings.push({ role, members: [member] });
+  }
+  await gcpFetch(
+    `https://cloudresourcemanager.googleapis.com/v1/projects/${encodeURIComponent(options.projectId)}:setIamPolicy`,
+    token,
+    "POST",
+    { policy: { ...policy, bindings } }
+  );
 }
 
 // src/index.ts
@@ -1950,6 +2620,7 @@ var index_default = getSpreadSheetData;
 export {
   DEFAULT_IMAGE_EXTENSIONS,
   DEFAULT_WAIT_SECONDS,
+  GcpApiError,
   buildGoogleAuth,
   buildManifest,
   convertFromDataJsonFormat,
@@ -1958,6 +2629,9 @@ export {
   createLocaleMapping,
   createSpreadsheet,
   index_default as default,
+  entriesToSeedKeys,
+  entriesToTranslationData,
+  exportDoc,
   filterValidLocales,
   findLocalChanges,
   getGoogleTranslateCode,
@@ -1968,7 +2642,10 @@ export {
   getOriginalHeaderForLocale,
   getSpreadSheetData,
   getTranslationSummary,
+  grantDrivePermissions,
   handleBidirectionalSync,
+  inferLocaleFromDocName,
+  ingestDoc,
   isValidLocale,
   manageDriveTranslations,
   mergeMultipleTranslationData,
@@ -1976,10 +2653,15 @@ export {
   normalizeExtension,
   normalizeLocaleCode,
   normalizePrivateKey,
+  parseDocContent,
   processRawRows,
+  readManifest,
   readPublicSheet,
   resolveLocaleWithFallback,
+  scanDriveFolderForDocs,
   scanDriveFolderForSpreadsheets,
+  setupWIF,
+  slugifyKey,
   syncDriveImages,
   updateSpreadsheetWithLocalChanges,
   validateCredentials,