@el-j/google-sheet-translations 1.0.2 → 1.2.0

package/dist/utils/publicSheetReader.d.ts

@@ -0,0 +1,17 @@
+import type { SheetRow } from "../types";
+/**
+ * Reads rows from a *publicly accessible* Google Spreadsheet sheet without
+ * requiring any service-account credentials or API key.
+ *
+ * The spreadsheet must be shared with **"Anyone with link can view"** (or
+ * broader). Works via Google's Visualization (gviz) query endpoint which
+ * is available at no cost for public sheets.
+ *
+ * @param spreadsheetId - The Google Spreadsheet ID (from the URL)
+ * @param sheetName     - The sheet tab name to fetch
+ * @returns An array of row objects keyed by column header
+ * @throws  If the sheet is not accessible or the response cannot be parsed
+ */
+export declare function readPublicSheet(spreadsheetId: string, sheetName: string): Promise<SheetRow[]>;
+export default readPublicSheet;
+//# sourceMappingURL=publicSheetReader.d.ts.map

package/dist/utils/publicSheetReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicSheetReader.d.ts","sourceRoot":"","sources":["../../src/utils/publicSheetReader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAiFzC;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACpC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiDrB;AAED,eAAe,eAAe,CAAC"}

package/dist/utils/publicSheetReader.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPublicSheet = readPublicSheet;
+const node_https_1 = __importDefault(require("node:https"));
+const node_http_1 = __importDefault(require("node:http"));
+/**
+ * Fetches the raw response body from a URL using the built-in http/https module.
+ * Follows a single redirect if the server issues one (3xx).
+ */
+function fetchUrl(url) {
+    return new Promise((resolve, reject) => {
+        const client = url.startsWith("https") ? node_https_1.default : node_http_1.default;
+        const req = client.get(url, (res) => {
+            // Follow one redirect (e.g. Google auth redirect)
+            if (res.statusCode !== undefined &&
+                res.statusCode >= 300 &&
+                res.statusCode < 400 &&
+                res.headers.location) {
+                fetchUrl(res.headers.location).then(resolve).catch(reject);
+                return;
+            }
+            if (res.statusCode !== undefined && res.statusCode >= 400) {
+                reject(new Error(`HTTP ${res.statusCode} while fetching ${url}`));
+                return;
+            }
+            let data = "";
+            res.on("data", (chunk) => {
+                data += chunk.toString();
+            });
+            res.on("end", () => resolve(data));
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+        req.end();
+    });
+}
+/**
+ * Strips the JSONP wrapper that the Google Visualization API adds and parses
+ * the inner JSON object.
+ *
+ * Expected wrapper format:
+ *   `/*O_o*\/\ngoogle.visualization.Query.setResponse({...});`
+ */
+function parseGvizResponse(raw) {
+    const match = raw.match(/google\.visualization\.Query\.setResponse\((\{[\s\S]*?\})\)/);
+    if (!match) {
+        throw new Error('Unexpected response format from Google Visualization API. ' +
+            'Make sure the spreadsheet is shared as "Anyone with link can view".');
+    }
+    return JSON.parse(match[1]);
+}
+/**
+ * Reads rows from a *publicly accessible* Google Spreadsheet sheet without
+ * requiring any service-account credentials or API key.
+ *
+ * The spreadsheet must be shared with **"Anyone with link can view"** (or
+ * broader). Works via Google's Visualization (gviz) query endpoint which
+ * is available at no cost for public sheets.
+ *
+ * @param spreadsheetId - The Google Spreadsheet ID (from the URL)
+ * @param sheetName     - The sheet tab name to fetch
+ * @returns An array of row objects keyed by column header
+ * @throws  If the sheet is not accessible or the response cannot be parsed
+ */
+async function readPublicSheet(spreadsheetId, sheetName) {
+    const url = `https://docs.google.com/spreadsheets/d/${encodeURIComponent(spreadsheetId)}` +
+        `/gviz/tq?tqx=out:json&sheet=${encodeURIComponent(sheetName)}`;
+    let raw;
+    try {
+        raw = await fetchUrl(url);
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch public sheet "${sheetName}" from spreadsheet "${spreadsheetId}"`, { cause: err });
+    }
+    let data;
+    try {
+        data = parseGvizResponse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse response for sheet "${sheetName}" in spreadsheet "${spreadsheetId}"`, { cause: err });
+    }
+    if (data.status !== "ok") {
+        const message = data.errors?.[0]?.message ?? "Unknown error";
+        throw new Error(`Google Visualization API returned an error for sheet "${sheetName}": ${message}`);
+    }
+    if (!data.table) {
+        return [];
+    }
+    const { cols, rows } = data.table;
+    const headers = cols.map((col) => col.label || col.id);
+    return rows
+        .filter((row) => row && row.c)
+        .map((row) => {
+        const obj = {};
+        for (let i = 0; i < headers.length; i++) {
+            const cell = row.c?.[i];
+            obj[headers[i]] = cell?.v != null ? String(cell.v) : "";
+        }
+        return obj;
+    });
+}
+exports.default = readPublicSheet;
+//# sourceMappingURL=publicSheetReader.js.map

package/dist/utils/publicSheetReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicSheetReader.js","sourceRoot":"","sources":["../../src/utils/publicSheetReader.ts"],"names":[],"mappings":"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"}

package/dist/utils/rateLimiter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Calls `fn` and, on a rate-limit error (HTTP 429 / 503), retries with
+ * exponential back-off.  Any other error is re-thrown immediately.
+ *
+ * @param fn           - The async operation to execute (and potentially retry)
+ * @param label        - Human-readable label used in warning logs
+ * @param baseDelayMs  - Base back-off delay in milliseconds (default: 1 000)
+ * @param retries      - Maximum number of retry attempts (default: 3)
+ * @param maxDelayMs   - Back-off ceiling in milliseconds (default: 30 000)
+ * @returns The resolved value of `fn`
+ * @throws  The last error if all retries are exhausted, or any non-rate-limit error immediately
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, label: string, baseDelayMs?: number, retries?: number, maxDelayMs?: number): Promise<T>;
+export default withRetry;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/utils/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../src/utils/rateLimiter.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,SAAQ,EACnB,OAAO,SAAkB,EACzB,UAAU,SAAuB,GAC/B,OAAO,CAAC,CAAC,CAAC,CAkBZ;AAED,eAAe,SAAS,CAAC"}

package/dist/utils/rateLimiter.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const promises_1 = require("node:timers/promises");
+const DEFAULT_RETRIES = 3;
+const DEFAULT_MAX_DELAY_MS = 30000;
+/**
+ * Returns true when the error looks like a Google Sheets API rate-limit or
+ * transient server error (HTTP 429 or 503).
+ */
+function isRateLimitError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    const response = e['response'];
+    const status = typeof e['status'] === 'number'
+        ? e['status']
+        : typeof response?.['status'] === 'number'
+            ? response['status']
+            : undefined;
+    return status === 429 || status === 503;
+}
+/**
+ * Calls `fn` and, on a rate-limit error (HTTP 429 / 503), retries with
+ * exponential back-off.  Any other error is re-thrown immediately.
+ *
+ * @param fn           - The async operation to execute (and potentially retry)
+ * @param label        - Human-readable label used in warning logs
+ * @param baseDelayMs  - Base back-off delay in milliseconds (default: 1 000)
+ * @param retries      - Maximum number of retry attempts (default: 3)
+ * @param maxDelayMs   - Back-off ceiling in milliseconds (default: 30 000)
+ * @returns The resolved value of `fn`
+ * @throws  The last error if all retries are exhausted, or any non-rate-limit error immediately
+ */
+async function withRetry(fn, label, baseDelayMs = 1000, retries = DEFAULT_RETRIES, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!isRateLimitError(err) || attempt === retries)
+                throw err;
+            const backoff = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+            console.warn(`[rate-limit] ${label}: retry ${attempt + 1}/${retries} in ${backoff} ms`);
+            await (0, promises_1.setTimeout)(backoff);
+        }
+    }
+    // The loop above always returns (on success) or throws (on exhausted retries or
+    // non-rate-limit errors).  This line is here solely to satisfy TypeScript's
+    // control-flow analysis — it cannot actually be reached at runtime.
+    /* c8 ignore next */
+    throw new Error('withRetry: unreachable');
+}
+exports.default = withRetry;
+//# sourceMappingURL=rateLimiter.js.map

package/dist/utils/rateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.js","sourceRoot":"","sources":["../../src/utils/rateLimiter.ts"],"names":[],"mappings":";;AAkCA,8BAwBC;AA1DD,mDAA2D;AAE3D,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,oBAAoB,GAAG,KAAM,CAAC;AAEpC;;;GAGG;AACH,SAAS,gBAAgB,CAAC,GAAY;IACrC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAwC,CAAC;IACtE,MAAM,MAAM,GACX,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC9B,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACb,CAAC,CAAC,OAAO,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,QAAQ;YACzC,CAAC,CAAE,QAAQ,CAAC,QAAQ,CAAY;YAChC,CAAC,CAAC,SAAS,CAAC;IACf,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,SAAS,CAC9B,EAAoB,EACpB,KAAa,EACb,WAAW,GAAG,IAAK,EACnB,OAAO,GAAG,eAAe,EACzB,UAAU,GAAG,oBAAoB;IAEjC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,EAAE,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,OAAO;gBAAE,MAAM,GAAG,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,EAAE,UAAU,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CACX,gBAAgB,KAAK,WAAW,OAAO,GAAG,CAAC,IAAI,OAAO,OAAO,OAAO,KAAK,CACzE,CAAC;YACF,MAAM,IAAA,qBAAK,EAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACF,CAAC;IACD,gFAAgF;IAChF,4EAA4E;IAC5E,oEAAoE;IACpE,oBAAoB;IACpB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAC3C,CAAC;AAED,kBAAe,SAAS,CAAC"}

package/dist/utils/sheetProcessor.d.ts

@@ -1,5 +1,5 @@
 import type { GoogleSpreadsheetWorksheet } from "google-spreadsheet";
-import type { TranslationData } from "../types";
+import type { SheetRow, TranslationData } from "../types";
 /**
  * Result of processing a single sheet
  */
@@ -11,12 +11,26 @@ export interface SheetProcessingResult {
     success: boolean;
 }
 /**
- * Processes a single Google Sheet and extracts translation data
- * @param sheet The Google Spreadsheet worksheet to process
+ * Core row-processing logic shared by both the authenticated and public sheet paths.
+ * Accepts pre-fetched rows (as plain objects) and returns the same
+ * {@link SheetProcessingResult} shape that `processSheet` produces.
+ * Contains only pure computation — no API calls are made here.
+ *
+ * @param rows       - Array of row objects keyed by column header
+ * @param sheetTitle - The sheet tab name (used as namespace key in translations)
+ * @returns Processing result containing translations and locales
+ */
+export declare function processRawRows(rows: SheetRow[], sheetTitle: string): Promise<SheetProcessingResult>;
+/**
+ * Fetches rows from a Google Sheet and extracts translation data.
+ * The underlying `getRows` API call is automatically retried on rate-limit
+ * responses (HTTP 429 / 503) using exponential back-off.
+ *
+ * @param sheet      The Google Spreadsheet worksheet to process
  * @param sheetTitle The title of the sheet being processed
- * @param rowLimit Maximum number of rows to fetch
- * @param waitSeconds Time to wait after processing
+ * @param rowLimit   Maximum number of rows to fetch
+ * @param baseDelayMs Base back-off delay in ms for retrying rate-limited requests
  * @returns Processing result containing translations and locales
  */
-export declare function processSheet(sheet: GoogleSpreadsheetWorksheet, sheetTitle: string, rowLimit: number, waitSeconds: number): Promise<SheetProcessingResult>;
+export declare function processSheet(sheet: GoogleSpreadsheetWorksheet, sheetTitle: string, rowLimit: number, baseDelayMs?: number): Promise<SheetProcessingResult>;
 //# sourceMappingURL=sheetProcessor.d.ts.map

package/dist/utils/sheetProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sheetProcessor.d.ts","sourceRoot":"","sources":["../../src/utils/sheetProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAY,eAAe,EAAE,MAAM,UAAU,CAAC;AAK1D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,YAAY,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,0BAA0B,EACjC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,CAAC,CA6FhC"}
+{"version":3,"file":"sheetProcessor.d.ts","sourceRoot":"","sources":["../../src/utils/sheetProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAK1D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACtC,YAAY,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CACpC,IAAI,EAAE,QAAQ,EAAE,EAChB,UAAU,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAwFhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAClC,KAAK,EAAE,0BAA0B,EACjC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,WAAW,SAAQ,GAChB,OAAO,CAAC,qBAAqB,CAAC,CA4BhC"}

package/dist/utils/sheetProcessor.js

@@ -1,34 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.processRawRows = processRawRows;
 exports.processSheet = processSheet;
-const wait_1 = require("./wait");
+const rateLimiter_1 = require("./rateLimiter");
 const localeFilter_1 = require("./localeFilter");
 const localeNormalizer_1 = require("./localeNormalizer");
 /**
- * Processes a single Google Sheet and extracts translation data
- * @param sheet The Google Spreadsheet worksheet to process
- * @param sheetTitle The title of the sheet being processed
- * @param rowLimit Maximum number of rows to fetch
- * @param waitSeconds Time to wait after processing
+ * Core row-processing logic shared by both the authenticated and public sheet paths.
+ * Accepts pre-fetched rows (as plain objects) and returns the same
+ * {@link SheetProcessingResult} shape that `processSheet` produces.
+ * Contains only pure computation — no API calls are made here.
+ *
+ * @param rows       - Array of row objects keyed by column header
+ * @param sheetTitle - The sheet tab name (used as namespace key in translations)
  * @returns Processing result containing translations and locales
  */
-async function processSheet(sheet, sheetTitle, rowLimit, waitSeconds) {
+async function processRawRows(rows, sheetTitle) {
     const result = {
         translations: {},
         locales: [],
         localeMapping: {},
         originalMapping: {},
-        success: false
+        success: false,
     };
     try {
-        const rows = await sheet.getRows({ limit: rowLimit });
         if (!rows || rows.length === 0) {
             console.warn(`No rows found in sheet "${sheetTitle}"`);
             return result;
         }
         // Extract header information
-        const rowObject = rows[0].toObject();
-        const headerRow = Object.keys(rowObject).map(key => key.toLowerCase());
+        const headerRow = Object.keys(rows[0]).map((key) => key.toLowerCase());
         console.log(`Header row for sheet "${sheetTitle}":`, headerRow);
         const keyColumn = headerRow[0];
         const validLocales = (0, localeFilter_1.filterValidLocales)(headerRow, keyColumn);
@@ -37,22 +38,20 @@ async function processSheet(sheet, sheetTitle, rowLimit, waitSeconds) {
             return result;
         }
         // Create locale mapping for normalization
-        const originalHeaders = Object.keys(rowObject); // Keep original case
+        const originalHeaders = Object.keys(rows[0]); // Keep original case
         const { normalizedLocales, localeMapping, originalMapping } = (0, localeNormalizer_1.createLocaleMapping)(originalHeaders, keyColumn);
         // Store the mappings in the result
         result.localeMapping = localeMapping;
         result.originalMapping = originalMapping;
-        // Convert rows to data objects
-        const cells = rows.map(row => row.toObject());
         // Process each normalized locale
         for (const normalizedLocale of normalizedLocales) {
             // Find the original header for this normalized locale
             const originalHeader = localeMapping[normalizedLocale];
             if (!originalHeader)
                 continue;
-            const languageCells = cells.map((row) => {
+            const languageCells = rows.map((row) => {
                 // Look for the key column (case-insensitive)
-                const keyField = Object.keys(row).find(k => k.toLowerCase() === keyColumn);
+                const keyField = Object.keys(row).find((k) => k.toLowerCase() === keyColumn);
                 if (!keyField || !row[keyField] || !row[originalHeader]) {
                     return {}; // Skip rows without key or translation
                 }
@@ -62,13 +61,16 @@ async function processSheet(sheet, sheetTitle, rowLimit, waitSeconds) {
                 return rowLocal;
             });
             // Filter out empty objects before combining
-            const nonEmptyLanguageCells = languageCells.filter(cell => Object.keys(cell).length > 0);
+            const nonEmptyLanguageCells = languageCells.filter((cell) => Object.keys(cell).length > 0);
             // Combine all keys into one object
             const prepareObj = {};
             prepareObj[sheetTitle] = nonEmptyLanguageCells.reduce((acc, cell) => Object.assign(acc, cell), {});
             // Use normalized locale as the key in translations
             if (result.translations[normalizedLocale]) {
-                result.translations[normalizedLocale] = { ...result.translations[normalizedLocale], ...prepareObj };
+                result.translations[normalizedLocale] = {
+                    ...result.translations[normalizedLocale],
+                    ...prepareObj,
+                };
             }
             else {
                 result.translations[normalizedLocale] = { ...prepareObj };
@@ -76,11 +78,44 @@ async function processSheet(sheet, sheetTitle, rowLimit, waitSeconds) {
         }
         result.locales = normalizedLocales;
         result.success = true;
-        await (0, wait_1.wait)(waitSeconds, `after processing sheet: ${sheetTitle}`);
     }
     catch (error) {
         console.error(`Error processing sheet "${sheetTitle}":`, error);
     }
     return result;
 }
+/**
+ * Fetches rows from a Google Sheet and extracts translation data.
+ * The underlying `getRows` API call is automatically retried on rate-limit
+ * responses (HTTP 429 / 503) using exponential back-off.
+ *
+ * @param sheet      The Google Spreadsheet worksheet to process
+ * @param sheetTitle The title of the sheet being processed
+ * @param rowLimit   Maximum number of rows to fetch
+ * @param baseDelayMs Base back-off delay in ms for retrying rate-limited requests
+ * @returns Processing result containing translations and locales
+ */
+async function processSheet(sheet, sheetTitle, rowLimit, baseDelayMs = 1000) {
+    const emptyResult = {
+        translations: {},
+        locales: [],
+        localeMapping: {},
+        originalMapping: {},
+        success: false,
+    };
+    try {
+        const googleRows = await (0, rateLimiter_1.withRetry)(() => sheet.getRows({ limit: rowLimit }), `getRows: ${sheetTitle}`, baseDelayMs);
+        if (!googleRows || googleRows.length === 0) {
+            console.warn(`No rows found in sheet "${sheetTitle}"`);
+            return emptyResult;
+        }
+        // Convert GoogleSpreadsheetRow objects to plain SheetRow objects, then reuse shared logic
+        const rows = googleRows.map((row) => row.toObject());
+        return processRawRows(rows, sheetTitle);
+    }
+    catch (error) {
+        console.error(`Error processing sheet "${sheetTitle}":`, error);
+        return emptyResult;
+    }
+}
 //# sourceMappingURL=sheetProcessor.js.map

package/dist/utils/sheetProcessor.js.map

@@ -1 +1 @@
-{"version":3,"file":"sheetProcessor.js","sourceRoot":"","sources":["../../src/utils/sheetProcessor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sheetProcessor.js","sourceRoot":"","sources":["../../src/utils/sheetProcessor.ts"],"names":[],"mappings":"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"}

package/dist/utils/spreadsheetCreator.d.ts

@@ -0,0 +1,23 @@
+import type { JWT } from "google-auth-library";
+export interface CreateSpreadsheetOptions {
+    /** Spreadsheet title (default: "google-sheet-translations") */
+    title?: string;
+    /** Source locale column header – translations in this locale are real text (default: "en") */
+    sourceLocale?: string;
+    /** Additional locale columns – filled with GOOGLETRANSLATE formulas (default: common languages) */
+    targetLocales?: string[];
+    /** Seed keys: key → source-locale value. If omitted a starter template is used. */
+    seedKeys?: Record<string, string>;
+}
+export interface CreatedSpreadsheetInfo {
+    spreadsheetId: string;
+    url: string;
+}
+/**
+ * Creates a new Google Spreadsheet seeded with translation starter content and
+ * GOOGLETRANSLATE formulas for every non-source locale.
+ *
+ * Returns the spreadsheet ID and URL.
+ */
+export declare function createSpreadsheet(authClient: JWT, options?: CreateSpreadsheetOptions): Promise<CreatedSpreadsheetInfo>;
+//# sourceMappingURL=spreadsheetCreator.d.ts.map

package/dist/utils/spreadsheetCreator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spreadsheetCreator.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetCreator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAiB/C,MAAM,WAAW,wBAAwB;IACxC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACZ;AAiBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,GAAG,EACf,OAAO,GAAE,wBAA6B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA8GjC"}

package/dist/utils/spreadsheetCreator.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpreadsheet = createSpreadsheet;
+const google_spreadsheet_1 = require("google-spreadsheet");
+const rateLimiter_1 = require("./rateLimiter");
+/** Column index (0-based) → spreadsheet letter (A, B…Z, AA, AB…). */
+function colLetter(index) {
+    let result = '';
+    let i = index;
+    do {
+        // Each digit in base-26 maps to a letter A–Z
+        result = String.fromCharCode(65 + (i % 26)) + result;
+        // Move to the next more-significant "digit", adjusting for 1-based indexing
+        i = Math.floor(i / 26) - 1;
+    } while (i >= 0);
+    return result;
+}
+const DEFAULT_TARGET_LOCALES = ['de', 'fr', 'es', 'it', 'pt', 'ja', 'zh'];
+const STARTER_KEYS = {
+    'app.name': 'My App',
+    'app.description': 'A great application',
+    'nav.home': 'Home',
+    'nav.about': 'About',
+    'nav.contact': 'Contact',
+    'common.save': 'Save',
+    'common.cancel': 'Cancel',
+    'common.loading': 'Loading…',
+    'common.error': 'An error occurred',
+    'common.success': 'Success!',
+};
+/**
+ * Creates a new Google Spreadsheet seeded with translation starter content and
+ * GOOGLETRANSLATE formulas for every non-source locale.
+ *
+ * Returns the spreadsheet ID and URL.
+ */
+async function createSpreadsheet(authClient, options = {}) {
+    const { title = 'google-sheet-translations', sourceLocale = 'en', targetLocales = DEFAULT_TARGET_LOCALES, seedKeys = STARTER_KEYS, } = options;
+    // ── Step 1: Create the spreadsheet via the Sheets REST API ─────────────
+    // google-spreadsheet v4 does not expose a static create method, so we use
+    // the underlying JWT client to make a direct API call.
+    await authClient.authorize();
+    const createRes = await (0, rateLimiter_1.withRetry)(() => authClient.request({
+        url: 'https://sheets.googleapis.com/v4/spreadsheets',
+        method: 'POST',
+        data: {
+            properties: { title },
+            sheets: [
+                { properties: { title: '__welcome__', index: 0 } },
+                { properties: { title: 'i18n', index: 1 } },
+            ],
+        },
+    }), 'createSpreadsheet');
+    const spreadsheetId = createRes.data.spreadsheetId;
+    const url = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/edit`;
+    // ── Step 2: Open the spreadsheet with google-spreadsheet ───────────────
+    const doc = new google_spreadsheet_1.GoogleSpreadsheet(spreadsheetId, authClient);
+    await (0, rateLimiter_1.withRetry)(() => doc.loadInfo(), 'loadInfo after create');
+    // ── Step 3: Populate __welcome__ sheet ─────────────────────────────────
+    const welcomeSheet = doc.sheetsByTitle['__welcome__'];
+    if (welcomeSheet) {
+        await (0, rateLimiter_1.withRetry)(() => welcomeSheet.loadCells('A1:B20'), 'loadCells welcome');
+        const lines = [
+            ['📊 Google Sheet Translations', ''],
+            ['', ''],
+            ['Package:', '@el-j/google-sheet-translations'],
+            ['Docs:', 'https://el-j.github.io/google-sheet-translations/'],
+            ['', ''],
+            ['Your Spreadsheet ID:', spreadsheetId],
+            ['URL:', url],
+            ['', ''],
+            ['Add to your .env file:', ''],
+            ['GOOGLE_SPREADSHEET_ID=' + spreadsheetId, ''],
+            ['', ''],
+            ['How this works:', ''],
+            ['1. The "i18n" sheet (and any other sheet you add) holds your translation keys.', ''],
+            ['2. Column A = key, Column B = source language, other columns = auto-translated.', ''],
+            ['3. Run getSpreadSheetData([\'i18n\']) in your project to sync to local files.', ''],
+            ['4. Add more sheets for different pages/features of your app.', ''],
+            ['5. Use syncLocalChanges: true (default) to push new keys back to this spreadsheet.', ''],
+        ];
+        for (let r = 0; r < lines.length; r++) {
+            for (let c = 0; c < lines[r].length; c++) {
+                const cell = welcomeSheet.getCell(r, c);
+                cell.value = lines[r][c];
+            }
+        }
+        await (0, rateLimiter_1.withRetry)(() => welcomeSheet.saveUpdatedCells(), 'saveWelcome');
+    }
+    // ── Step 4: Populate i18n sheet with headers + GOOGLETRANSLATE rows ────
+    const i18nSheet = doc.sheetsByTitle['i18n'];
+    if (i18nSheet) {
+        const allLocales = [sourceLocale, ...targetLocales];
+        // Row 1 = headers
+        await (0, rateLimiter_1.withRetry)(() => i18nSheet.setHeaderRow(['key', ...allLocales]), 'setHeaderRow');
+        // Build rows: source column has real text; other columns get GOOGLETRANSLATE formula.
+        // Source is always column B (index 1 after 'key')
+        const sourceColLetter = colLetter(1); // B
+        const rows = Object.entries(seedKeys).map(([key, sourceValue]) => {
+            const row = { key, [sourceLocale]: sourceValue };
+            targetLocales.forEach((locale, idx) => {
+                const targetColLetter = colLetter(2 + idx); // C, D, E, …
+                row[locale] =
+                    `=GOOGLETRANSLATE(INDIRECT("${sourceColLetter}"&ROW());$${sourceColLetter}$1;${targetColLetter}$1)`;
+            });
+            return row;
+        });
+        await (0, rateLimiter_1.withRetry)(() => i18nSheet.addRows(rows), 'addRows i18n');
+    }
+    console.log('');
+    console.log('✅ New spreadsheet created!');
+    console.log(`   Title  : ${title}`);
+    console.log(`   URL    : ${url}`);
+    console.log(`   ID     : ${spreadsheetId}`);
+    console.log('');
+    console.log('   Add this to your .env file (or environment):');
+    console.log(`   GOOGLE_SPREADSHEET_ID=${spreadsheetId}`);
+    console.log('');
+    return { spreadsheetId, url };
+}
+//# sourceMappingURL=spreadsheetCreator.js.map

package/dist/utils/spreadsheetCreator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spreadsheetCreator.js","sourceRoot":"","sources":["../../src/utils/spreadsheetCreator.ts"],"names":[],"mappings":"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"}

package/dist/utils/spreadsheetUpdater.d.ts

@@ -16,7 +16,7 @@ import type { TranslationData } from "../types";
  *
  * @param doc - The Google Spreadsheet instance
  * @param changes - Object containing new keys to add to the spreadsheet
- * @param waitSeconds - Number of seconds to wait between API calls
+ * @param waitSeconds - Base back-off delay in seconds for retrying rate-limited API calls
  * @param autoTranslate - Whether to add Google Translate formulas for missing translations (default: false)
  * @param localeMapping - Mapping from normalized locale codes to original spreadsheet headers
  * @returns Promise that resolves when the update is complete

package/dist/utils/spreadsheetUpdater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spreadsheetUpdater.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAehD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iCAAiC,CACnD,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,EACnB,aAAa,UAAQ,EACrB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC3C,OAAO,CAAC,IAAI,CAAC,CA2Mf"}
+{"version":3,"file":"spreadsheetUpdater.d.ts","sourceRoot":"","sources":["../../src/utils/spreadsheetUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAehD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iCAAiC,CACnD,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,EACnB,aAAa,UAAQ,EACrB,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC3C,OAAO,CAAC,IAAI,CAAC,CA8Mf"}