@ariadng/sheets 0.4.0 → 0.4.2

package/dist/index.js

@@ -1,12 +1,811 @@
-/**
- * @ariadng/google-sheets
- * Google Sheets API interface and CLI tool
- */
-// Client
-export { SheetsClient, createClient } from './api/index.js';
-// Auth
-export { createAuthProvider, OAuthAuth, ServiceAccountAuth, UserAuth, login, loadStoredTokens, deleteTokens } from './auth/index.js';
-// HTTP
-export { HttpClient } from './http/index.js';
-export { SheetsError } from './types/index.js';
+// src/types/index.ts
+var SheetsError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(error) {
+    super(error.message);
+    this.name = "SheetsError";
+    this.code = error.code;
+    this.status = error.status;
+    this.details = error.details;
+  }
+};
+
+// src/http/index.ts
+var BASE_URL = "https://sheets.googleapis.com/v4";
+var MAX_RETRIES = 3;
+var INITIAL_BACKOFF_MS = 1e3;
+var HttpClient = class {
+  getAccessToken;
+  constructor(options) {
+    this.getAccessToken = options.getAccessToken;
+  }
+  async request(path2, options = {}) {
+    const { method = "GET", body, params } = options;
+    let url = `${BASE_URL}${path2}`;
+    if (params) {
+      const searchParams = new URLSearchParams(params);
+      url += `?${searchParams.toString()}`;
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        const accessToken = await this.getAccessToken();
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Content-Type": "application/json"
+          },
+          body: body ? JSON.stringify(body) : void 0
+        });
+        if (response.status === 429) {
+          const backoffMs = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+          await this.sleep(backoffMs);
+          continue;
+        }
+        const data = await response.json();
+        if (!response.ok) {
+          if (data.error) {
+            throw new SheetsError({
+              code: data.error.code,
+              message: data.error.message,
+              status: data.error.status
+            });
+          }
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof SheetsError && error.code !== 429 && error.code !== 500 && error.code !== 503) {
+          throw error;
+        }
+        if (attempt < MAX_RETRIES - 1) {
+          const backoffMs = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+          await this.sleep(backoffMs);
+        }
+      }
+    }
+    throw lastError || new Error("Request failed after retries");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/auth/constants.ts
+var OAUTH_CLIENT_ID = "344941894490-jmdvo5ghomqi7vuisfrf80hfassk1ma5.apps.googleusercontent.com";
+var OAUTH_CLIENT_SECRET = "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";
+var OAUTH_REDIRECT_URI = "http://localhost:8085/callback";
+var OAUTH_CALLBACK_PORT = 8085;
+var OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+var OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var OAUTH_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo";
+var OAUTH_SCOPES = [
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/userinfo.email"
+];
+
+// src/auth/oauth.ts
+var OAuthAuth = class {
+  config;
+  cachedToken;
+  expiresAt;
+  constructor(config) {
+    this.config = config;
+    this.cachedToken = config.accessToken;
+    this.expiresAt = config.expiresAt || 0;
+  }
+  async getAccessToken() {
+    if (!this.canRefresh()) {
+      return this.cachedToken;
+    }
+    if (this.isExpired()) {
+      await this.refreshToken();
+    }
+    return this.cachedToken;
+  }
+  canRefresh() {
+    return !!(this.config.refreshToken && this.config.clientId && this.config.clientSecret && this.expiresAt > 0);
+  }
+  isExpired() {
+    return Date.now() >= this.expiresAt - 6e4;
+  }
+  async refreshToken() {
+    if (!this.config.refreshToken || !this.config.clientId || !this.config.clientSecret) {
+      throw new Error("Token expired and missing refresh credentials (refreshToken, clientId, clientSecret)");
+    }
+    const response = await fetch(OAUTH_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        refresh_token: this.config.refreshToken,
+        grant_type: "refresh_token"
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token refresh failed: ${error}`);
+    }
+    const tokenResponse = await response.json();
+    this.cachedToken = tokenResponse.access_token;
+    this.expiresAt = Date.now() + tokenResponse.expires_in * 1e3;
+    if (tokenResponse.refresh_token) {
+      this.config.refreshToken = tokenResponse.refresh_token;
+    }
+  }
+  /**
+   * Get current token state for persistence in automation tools
+   * Returns updated tokens after any refresh operations
+   */
+  getTokenState() {
+    return {
+      accessToken: this.cachedToken,
+      refreshToken: this.config.refreshToken,
+      expiresAt: this.expiresAt
+    };
+  }
+};
+
+// src/auth/service-account.ts
+import * as crypto from "crypto";
+import * as fs from "fs/promises";
+var TOKEN_URI = "https://oauth2.googleapis.com/token";
+var SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+var TOKEN_LIFETIME_SECONDS = 3600;
+var ServiceAccountAuth = class {
+  config;
+  credentials = null;
+  cachedToken = null;
+  tokenExpiresAt = 0;
+  constructor(config) {
+    this.config = config;
+  }
+  async getAccessToken() {
+    if (this.cachedToken && Date.now() < this.tokenExpiresAt - 6e4) {
+      return this.cachedToken;
+    }
+    await this.loadCredentials();
+    const jwt = this.createJwt();
+    const token = await this.exchangeJwtForToken(jwt);
+    this.cachedToken = token.access_token;
+    this.tokenExpiresAt = Date.now() + token.expires_in * 1e3;
+    return this.cachedToken;
+  }
+  async loadCredentials() {
+    if (this.credentials) return;
+    if (this.config.credentials) {
+      this.credentials = this.config.credentials;
+      return;
+    }
+    if (!this.config.credentialsPath) {
+      throw new Error("Service account requires credentialsPath or credentials");
+    }
+    const content = await fs.readFile(this.config.credentialsPath, "utf-8");
+    this.credentials = JSON.parse(content);
+  }
+  createJwt() {
+    if (!this.credentials) {
+      throw new Error("Credentials not loaded");
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const header = {
+      alg: "RS256",
+      typ: "JWT"
+    };
+    const payload = {
+      iss: this.credentials.client_email,
+      scope: SCOPE,
+      aud: TOKEN_URI,
+      iat: now,
+      exp: now + TOKEN_LIFETIME_SECONDS
+    };
+    const encodedHeader = this.base64UrlEncode(JSON.stringify(header));
+    const encodedPayload = this.base64UrlEncode(JSON.stringify(payload));
+    const signatureInput = `${encodedHeader}.${encodedPayload}`;
+    const sign = crypto.createSign("RSA-SHA256");
+    sign.update(signatureInput);
+    const signature = sign.sign(this.credentials.private_key);
+    const encodedSignature = this.base64UrlEncode(signature);
+    return `${signatureInput}.${encodedSignature}`;
+  }
+  base64UrlEncode(input) {
+    const buffer = typeof input === "string" ? Buffer.from(input) : input;
+    return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
+  async exchangeJwtForToken(jwt) {
+    const response = await fetch(TOKEN_URI, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: jwt
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/auth/user-auth.ts
+import * as crypto2 from "crypto";
+import * as fs2 from "fs/promises";
+import * as http from "http";
+import * as os from "os";
+import * as path from "path";
+import { exec } from "child_process";
+var CONFIG_DIR = path.join(os.homedir(), ".sheets");
+var TOKENS_FILE = path.join(CONFIG_DIR, "tokens.json");
+function generatePKCE() {
+  const codeVerifier = crypto2.randomBytes(32).toString("base64url");
+  const codeChallenge = crypto2.createHash("sha256").update(codeVerifier).digest("base64url");
+  return { codeVerifier, codeChallenge };
+}
+function openBrowser(url) {
+  return new Promise((resolve, reject) => {
+    const platform = process.platform;
+    let command;
+    if (platform === "darwin") {
+      command = `open "${url}"`;
+    } else if (platform === "win32") {
+      command = `start "" "${url}"`;
+    } else {
+      command = `xdg-open "${url}"`;
+    }
+    exec(command, (error) => {
+      if (error) {
+        reject(new Error(`Failed to open browser: ${error.message}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url || "", `http://localhost:${OAUTH_CALLBACK_PORT}`);
+      if (url.pathname === "/callback") {
+        const code = url.searchParams.get("code");
+        const error = url.searchParams.get("error");
+        if (error) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end("<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>");
+          clearTimeout(timeoutId);
+          server.close();
+          reject(new Error(`Authorization error: ${error}`));
+          return;
+        }
+        if (code) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<html><body><h1>Authorization Successful</h1><p>You can close this window.</p></body></html>");
+          clearTimeout(timeoutId);
+          server.close();
+          resolve(code);
+          return;
+        }
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end("<html><body><h1>Missing Code</h1></body></html>");
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+    server.on("error", (err) => {
+      clearTimeout(timeoutId);
+      reject(new Error(`Callback server error: ${err.message}`));
+    });
+    server.listen(OAUTH_CALLBACK_PORT, () => {
+    });
+    timeoutId = setTimeout(() => {
+      server.close();
+      reject(new Error("Authorization timeout"));
+    }, 5 * 60 * 1e3);
+  });
+}
+function getAuthorizationUrl(codeChallenge, clientId) {
+  const params = new URLSearchParams({
+    client_id: clientId || OAUTH_CLIENT_ID,
+    redirect_uri: OAUTH_REDIRECT_URI,
+    response_type: "code",
+    scope: OAUTH_SCOPES.join(" "),
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256",
+    access_type: "offline",
+    prompt: "consent"
+  });
+  return `${OAUTH_AUTH_URL}?${params.toString()}`;
+}
+async function exchangeCodeForTokens(code, codeVerifier, credentials) {
+  const response = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: credentials?.clientId || OAUTH_CLIENT_ID,
+      client_secret: credentials?.clientSecret || OAUTH_CLIENT_SECRET,
+      code,
+      code_verifier: codeVerifier,
+      grant_type: "authorization_code",
+      redirect_uri: OAUTH_REDIRECT_URI
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Token exchange failed: ${error}`);
+  }
+  return await response.json();
+}
+async function refreshAccessToken(refreshToken) {
+  const response = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: OAUTH_CLIENT_ID,
+      client_secret: OAUTH_CLIENT_SECRET,
+      refresh_token: refreshToken,
+      grant_type: "refresh_token"
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Token refresh failed: ${error}`);
+  }
+  return await response.json();
+}
+async function getUserInfo(accessToken) {
+  const response = await fetch(OAUTH_USERINFO_URL, {
+    headers: { Authorization: `Bearer ${accessToken}` }
+  });
+  if (!response.ok) {
+    throw new Error("Failed to get user info");
+  }
+  return await response.json();
+}
+async function ensureConfigDir() {
+  try {
+    await fs2.mkdir(CONFIG_DIR, { recursive: true });
+  } catch {
+  }
+}
+async function loadStoredTokens() {
+  try {
+    const content = await fs2.readFile(TOKENS_FILE, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function saveTokens(tokens) {
+  await ensureConfigDir();
+  await fs2.writeFile(TOKENS_FILE, JSON.stringify(tokens, null, 2));
+}
+async function deleteTokens() {
+  try {
+    await fs2.unlink(TOKENS_FILE);
+  } catch {
+  }
+}
+async function login(credentials) {
+  const { codeVerifier, codeChallenge } = generatePKCE();
+  const authUrl = getAuthorizationUrl(codeChallenge, credentials?.clientId);
+  console.log("Opening browser for Google login...");
+  const codePromise = startCallbackServer();
+  await openBrowser(authUrl);
+  console.log("Waiting for authorization...");
+  const code = await codePromise;
+  console.log("Exchanging code for tokens...");
+  const tokenResponse = await exchangeCodeForTokens(code, codeVerifier, credentials);
+  const userInfo = await getUserInfo(tokenResponse.access_token);
+  const tokens = {
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token || "",
+    expiresAt: Date.now() + tokenResponse.expires_in * 1e3,
+    email: userInfo.email
+  };
+  await saveTokens(tokens);
+  return tokens;
+}
+var UserAuth = class {
+  tokens = null;
+  async getAccessToken() {
+    if (!this.tokens) {
+      this.tokens = await loadStoredTokens();
+    }
+    if (!this.tokens) {
+      throw new Error('Not logged in. Run "sheets login" first.');
+    }
+    if (Date.now() >= this.tokens.expiresAt - 6e4) {
+      if (!this.tokens.refreshToken) {
+        throw new Error('Token expired and no refresh token. Run "sheets login" again.');
+      }
+      const tokenResponse = await refreshAccessToken(this.tokens.refreshToken);
+      this.tokens.accessToken = tokenResponse.access_token;
+      this.tokens.expiresAt = Date.now() + tokenResponse.expires_in * 1e3;
+      if (tokenResponse.refresh_token) {
+        this.tokens.refreshToken = tokenResponse.refresh_token;
+      }
+      await saveTokens(this.tokens);
+    }
+    return this.tokens.accessToken;
+  }
+};
+
+// src/auth/index.ts
+function createAuthProvider(config) {
+  switch (config.type) {
+    case "oauth":
+      return new OAuthAuth(config);
+    case "service-account":
+      return new ServiceAccountAuth(config);
+    case "user":
+      return new UserAuth();
+    default:
+      throw new Error(`Unknown auth type: ${config.type}`);
+  }
+}
+
+// src/api/index.ts
+function columnLetterToNumber(letters) {
+  let result = 0;
+  for (let i = 0; i < letters.length; i++) {
+    result = result * 26 + (letters.charCodeAt(i) - 64);
+  }
+  return result;
+}
+function columnNumberToLetter(num) {
+  let result = "";
+  while (num > 0) {
+    const remainder = (num - 1) % 26;
+    result = String.fromCharCode(65 + remainder) + result;
+    num = Math.floor((num - 1) / 26);
+  }
+  return result;
+}
+function parseA1Range(range) {
+  const cellRef = range.includes("!") ? range.split("!")[1] : range;
+  const firstCell = cellRef.split(":")[0];
+  const match = firstCell.match(/^([A-Z]+)(\d+)$/i);
+  if (!match) {
+    return { startRow: 1, startCol: 1 };
+  }
+  return {
+    startCol: columnLetterToNumber(match[1].toUpperCase()),
+    startRow: parseInt(match[2], 10)
+  };
+}
+var SheetsClient = class {
+  http;
+  constructor(options) {
+    const authProvider = createAuthProvider(options.auth);
+    this.http = new HttpClient({
+      getAccessToken: () => authProvider.getAccessToken()
+    });
+  }
+  /**
+   * Get a spreadsheet by ID
+   */
+  async getSpreadsheet(spreadsheetId) {
+    return this.http.request(`/spreadsheets/${spreadsheetId}`);
+  }
+  /**
+   * Get list of sheets in a spreadsheet
+   */
+  async getSheets(spreadsheetId) {
+    const spreadsheet = await this.getSpreadsheet(spreadsheetId);
+    return spreadsheet.sheets.map((sheet) => sheet.properties);
+  }
+  /**
+   * Read cell values from a range
+   */
+  async getValues(spreadsheetId, range, options) {
+    const params = {};
+    if (options?.valueRenderOption) {
+      params.valueRenderOption = options.valueRenderOption;
+    }
+    if (options?.dateTimeRenderOption) {
+      params.dateTimeRenderOption = options.dateTimeRenderOption;
+    }
+    if (options?.majorDimension) {
+      params.majorDimension = options.majorDimension;
+    }
+    const encodedRange = encodeURIComponent(range);
+    const response = await this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}`,
+      { params }
+    );
+    return this.normalizeValueRange(response);
+  }
+  /**
+   * Read cell formulas from a range
+   */
+  async getFormulas(spreadsheetId, range) {
+    return this.getValues(spreadsheetId, range, { valueRenderOption: "FORMULA" });
+  }
+  /**
+   * Read multiple ranges at once
+   */
+  async batchGetValues(spreadsheetId, ranges, options) {
+    const params = {
+      ranges: ranges.join(",")
+    };
+    if (options?.valueRenderOption) {
+      params.valueRenderOption = options.valueRenderOption;
+    }
+    if (options?.dateTimeRenderOption) {
+      params.dateTimeRenderOption = options.dateTimeRenderOption;
+    }
+    if (options?.majorDimension) {
+      params.majorDimension = options.majorDimension;
+    }
+    const response = await this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchGet`,
+      { params }
+    );
+    return {
+      spreadsheetId: response.spreadsheetId,
+      valueRanges: (response.valueRanges || []).map((vr) => this.normalizeValueRange(vr))
+    };
+  }
+  /**
+   * Clear values from a single range
+   */
+  async clearValues(spreadsheetId, range) {
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}:clear`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Clear values from multiple ranges
+   */
+  async batchClearValues(spreadsheetId, ranges) {
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchClear`,
+      { method: "POST", body: { ranges } }
+    );
+  }
+  /**
+   * Write values to a range (or starting cell)
+   * Range can be "A1" or "A1:D10" - data array determines actual extent
+   */
+  async updateValues(spreadsheetId, range, values, options) {
+    const params = {
+      valueInputOption: options?.valueInputOption || "USER_ENTERED"
+    };
+    if (options?.includeValuesInResponse) {
+      params.includeValuesInResponse = "true";
+    }
+    if (options?.responseValueRenderOption) {
+      params.responseValueRenderOption = options.responseValueRenderOption;
+    }
+    if (options?.responseDateTimeRenderOption) {
+      params.responseDateTimeRenderOption = options.responseDateTimeRenderOption;
+    }
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}`,
+      {
+        method: "PUT",
+        params,
+        body: {
+          majorDimension: options?.majorDimension || "ROWS",
+          values
+        }
+      }
+    );
+  }
+  /**
+   * Write to multiple ranges in one request
+   */
+  async batchUpdateValues(spreadsheetId, data, options) {
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchUpdate`,
+      {
+        method: "POST",
+        body: {
+          valueInputOption: options?.valueInputOption || "USER_ENTERED",
+          data: data.map((d) => ({
+            range: d.range,
+            majorDimension: options?.majorDimension || "ROWS",
+            values: d.values
+          })),
+          includeValuesInResponse: options?.includeValuesInResponse || false,
+          responseValueRenderOption: options?.responseValueRenderOption,
+          responseDateTimeRenderOption: options?.responseDateTimeRenderOption
+        }
+      }
+    );
+  }
+  /**
+   * Append rows after the last row of detected table
+   */
+  async appendValues(spreadsheetId, range, values, options) {
+    const params = {
+      valueInputOption: options?.valueInputOption || "USER_ENTERED"
+    };
+    if (options?.insertDataOption) {
+      params.insertDataOption = options.insertDataOption;
+    }
+    if (options?.includeValuesInResponse) {
+      params.includeValuesInResponse = "true";
+    }
+    if (options?.responseValueRenderOption) {
+      params.responseValueRenderOption = options.responseValueRenderOption;
+    }
+    if (options?.responseDateTimeRenderOption) {
+      params.responseDateTimeRenderOption = options.responseDateTimeRenderOption;
+    }
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}:append`,
+      {
+        method: "POST",
+        params,
+        body: {
+          majorDimension: options?.majorDimension || "ROWS",
+          values
+        }
+      }
+    );
+  }
+  /**
+   * Search for values matching a query across sheets
+   */
+  async searchValues(spreadsheetId, query, options) {
+    const caseSensitive = options?.caseSensitive ?? false;
+    const exactMatch = options?.exactMatch ?? false;
+    const useRegex = options?.regex ?? false;
+    const limit = options?.limit;
+    const matchType = useRegex ? "regex" : exactMatch ? "exact" : "contains";
+    let matcher;
+    if (useRegex) {
+      const flags = caseSensitive ? "" : "i";
+      const regex = new RegExp(query, flags);
+      matcher = (cellValue) => regex.test(cellValue);
+    } else if (exactMatch) {
+      if (caseSensitive) {
+        matcher = (cellValue) => cellValue === query;
+      } else {
+        const lowerQuery = query.toLowerCase();
+        matcher = (cellValue) => cellValue.toLowerCase() === lowerQuery;
+      }
+    } else {
+      if (caseSensitive) {
+        matcher = (cellValue) => cellValue.includes(query);
+      } else {
+        const lowerQuery = query.toLowerCase();
+        matcher = (cellValue) => cellValue.toLowerCase().includes(lowerQuery);
+      }
+    }
+    const matches = [];
+    const allSheets = await this.getSheets(spreadsheetId);
+    let sheetsToSearch;
+    if (options?.sheetIndex !== void 0) {
+      const sheet = allSheets.find((s) => s.index === options.sheetIndex);
+      if (!sheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found.`);
+      }
+      sheetsToSearch = [sheet];
+    } else if (options?.gid !== void 0) {
+      const sheet = allSheets.find((s) => s.sheetId === options.gid);
+      if (!sheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found.`);
+      }
+      sheetsToSearch = [sheet];
+    } else if (options?.range && options.range.includes("!")) {
+      sheetsToSearch = [];
+    } else {
+      sheetsToSearch = allSheets.filter((s) => !s.hidden);
+    }
+    if (options?.range && options.range.includes("!")) {
+      const valueRange = await this.getValues(spreadsheetId, options.range);
+      const sheetName = options.range.split("!")[0].replace(/^'|'$/g, "").replace(/''/g, "'");
+      const sheet = allSheets.find((s) => s.title === sheetName);
+      const { startRow, startCol } = parseA1Range(options.range);
+      this.collectMatches(
+        valueRange,
+        sheetName,
+        sheet?.sheetId ?? 0,
+        startRow,
+        startCol,
+        matcher,
+        matches,
+        limit
+      );
+    } else {
+      for (const sheet of sheetsToSearch) {
+        if (limit && matches.length >= limit) break;
+        const escapedTitle = sheet.title.replace(/'/g, "''");
+        const range = options?.range ? `'${escapedTitle}'!${options.range}` : `'${escapedTitle}'`;
+        try {
+          const valueRange = await this.getValues(spreadsheetId, range);
+          const { startRow, startCol } = parseA1Range(valueRange.range);
+          this.collectMatches(
+            valueRange,
+            sheet.title,
+            sheet.sheetId,
+            startRow,
+            startCol,
+            matcher,
+            matches,
+            limit
+          );
+        } catch {
+          continue;
+        }
+      }
+    }
+    return {
+      query,
+      matchType,
+      caseSensitive,
+      totalMatches: matches.length,
+      matches
+    };
+  }
+  collectMatches(valueRange, sheetName, sheetId, startRow, startCol, matcher, matches, limit) {
+    for (let rowIndex = 0; rowIndex < valueRange.values.length; rowIndex++) {
+      if (limit && matches.length >= limit) return;
+      const row = valueRange.values[rowIndex];
+      for (let colIndex = 0; colIndex < row.length; colIndex++) {
+        if (limit && matches.length >= limit) return;
+        const cell = row[colIndex];
+        const cellValue = cell.value;
+        if (cellValue == null) continue;
+        const stringValue = String(cellValue);
+        if (matcher(stringValue)) {
+          const actualRow = startRow + rowIndex;
+          const actualCol = startCol + colIndex;
+          matches.push({
+            sheet: sheetName,
+            sheetId,
+            address: columnNumberToLetter(actualCol) + actualRow,
+            row: actualRow,
+            column: actualCol,
+            value: cellValue
+          });
+        }
+      }
+    }
+  }
+  normalizeValueRange(raw) {
+    const values = (raw.values || []).map(
+      (row) => row.map((cell) => ({
+        value: cell
+      }))
+    );
+    return {
+      range: raw.range,
+      majorDimension: raw.majorDimension || "ROWS",
+      values
+    };
+  }
+};
+function createClient(options) {
+  return new SheetsClient(options);
+}
+export {
+  HttpClient,
+  OAuthAuth,
+  ServiceAccountAuth,
+  SheetsClient,
+  SheetsError,
+  UserAuth,
+  createAuthProvider,
+  createClient,
+  deleteTokens,
+  loadStoredTokens,
+  login
+};
 //# sourceMappingURL=index.js.map