@squadbase/vite-server 0.1.3-dev.8 → 0.1.3

package/dist/connectors/google-sheets.js

@@ -1,239 +1,104 @@
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-
-// ../connectors/src/connectors/google-sheets/utils.ts
-function extractSpreadsheetId(urlOrId) {
-  const trimmed = urlOrId.trim();
-  const match = trimmed.match(SPREADSHEET_URL_PATTERN);
-  if (match) {
-    return match[1];
-  }
-  return trimmed;
-}
-var SPREADSHEET_URL_PATTERN;
-var init_utils = __esm({
-  "../connectors/src/connectors/google-sheets/utils.ts"() {
-    "use strict";
-    SPREADSHEET_URL_PATTERN = /docs\.google\.com\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/;
-  }
-});
-
-// ../connectors/src/parameter-definition.ts
-var ParameterDefinition = class {
-  slug;
-  name;
-  description;
-  envVarBaseKey;
-  type;
-  secret;
-  required;
-  constructor(config) {
-    this.slug = config.slug;
-    this.name = config.name;
-    this.description = config.description;
-    this.envVarBaseKey = config.envVarBaseKey;
-    this.type = config.type;
-    this.secret = config.secret;
-    this.required = config.required;
+// ../connectors/src/connectors/google-sheets/sdk/index.ts
+var SHEETS_BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets";
+function createClient(_params, fetchFn = fetch) {
+  function request(path2, init) {
+    const url = `${SHEETS_BASE_URL}${path2 === "" || path2.startsWith("/") ? "" : "/"}${path2}`;
+    return fetchFn(url, init);
   }
-  /**
-   * Get the parameter value from a ConnectorConnectionObject.
-   */
-  getValue(connection2) {
-    const param = connection2.parameters.find(
-      (p) => p.parameterSlug === this.slug
-    );
-    if (!param || param.value == null) {
+  async function getSpreadsheet(spreadsheetId) {
+    const url = `${SHEETS_BASE_URL}/${spreadsheetId}?fields=spreadsheetId,properties,sheets.properties`;
+    const response = await fetchFn(url);
+    if (!response.ok) {
+      const body = await response.text();
       throw new Error(
-        `Parameter "${this.slug}" not found or has no value in connection "${connection2.id}"`
+        `google-sheets: getSpreadsheet failed (${response.status}): ${body}`
       );
     }
-    return param.value;
-  }
-  /**
-   * Try to get the parameter value. Returns undefined if not found (for optional params).
-   */
-  tryGetValue(connection2) {
-    const param = connection2.parameters.find(
-      (p) => p.parameterSlug === this.slug
-    );
-    if (!param || param.value == null) return void 0;
-    return param.value;
-  }
-};
-
-// ../connectors/src/connectors/google-sheets/sdk/index.ts
-import * as crypto from "crypto";
-
-// ../connectors/src/connectors/google-sheets/parameters.ts
-var parameters = {
-  serviceAccountKeyJsonBase64: new ParameterDefinition({
-    slug: "service-account-key-json-base64",
-    name: "Google Cloud Service Account JSON",
-    description: "The service account JSON key used to authenticate with Google Cloud Platform. Ensure that the service account has the necessary permissions to access Google Sheets.",
-    envVarBaseKey: "GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_BASE64",
-    type: "base64EncodedJson",
-    secret: true,
-    required: true
-  }),
-  spreadsheetUrl: new ParameterDefinition({
-    slug: "spreadsheet-url",
-    name: "Google Spreadsheet URL",
-    description: "The URL of the Google Spreadsheet (e.g., https://docs.google.com/spreadsheets/d/xxxxx/edit). The spreadsheet ID is automatically extracted from the URL.",
-    envVarBaseKey: "GOOGLE_SHEETS_SPREADSHEET_URL",
-    type: "text",
-    secret: false,
-    required: true
-  })
-};
-
-// ../connectors/src/connectors/google-sheets/sdk/index.ts
-init_utils();
-var TOKEN_URL = "https://oauth2.googleapis.com/token";
-var BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets";
-var SCOPE = "https://www.googleapis.com/auth/spreadsheets.readonly";
-function base64url(input) {
-  const buf = typeof input === "string" ? Buffer.from(input) : input;
-  return buf.toString("base64url");
-}
-function buildJwt(clientEmail, privateKey, nowSec) {
-  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
-  const payload = base64url(
-    JSON.stringify({
-      iss: clientEmail,
-      scope: SCOPE,
-      aud: TOKEN_URL,
-      iat: nowSec,
-      exp: nowSec + 3600
-    })
-  );
-  const signingInput = `${header}.${payload}`;
-  const sign = crypto.createSign("RSA-SHA256");
-  sign.update(signingInput);
-  sign.end();
-  const signature = base64url(sign.sign(privateKey));
-  return `${signingInput}.${signature}`;
-}
-function createClient(params) {
-  const serviceAccountKeyJsonBase64 = params[parameters.serviceAccountKeyJsonBase64.slug];
-  const spreadsheetUrl = params[parameters.spreadsheetUrl.slug];
-  const defaultSpreadsheetId = spreadsheetUrl ? extractSpreadsheetId(spreadsheetUrl) : void 0;
-  if (!serviceAccountKeyJsonBase64) {
-    throw new Error(
-      `google-sheets: missing required parameter: ${parameters.serviceAccountKeyJsonBase64.slug}`
-    );
+    return await response.json();
   }
-  let serviceAccountKey;
-  try {
-    const decoded = Buffer.from(
-      serviceAccountKeyJsonBase64,
-      "base64"
-    ).toString("utf-8");
-    serviceAccountKey = JSON.parse(decoded);
-  } catch {
-    throw new Error(
-      "google-sheets: failed to decode service account key JSON from base64"
-    );
+  async function getValues(spreadsheetId, range) {
+    const url = `${SHEETS_BASE_URL}/${spreadsheetId}/values/${encodeURIComponent(range)}`;
+    const response = await fetchFn(url);
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `google-sheets: getValues failed (${response.status}): ${body}`
+      );
+    }
+    return await response.json();
   }
-  if (!serviceAccountKey.client_email || !serviceAccountKey.private_key) {
-    throw new Error(
-      "google-sheets: service account key JSON must contain client_email and private_key"
-    );
+  async function batchGetValues(spreadsheetId, ranges) {
+    const searchParams = new URLSearchParams();
+    for (const range of ranges) {
+      searchParams.append("ranges", range);
+    }
+    const url = `${SHEETS_BASE_URL}/${spreadsheetId}/values:batchGet?${searchParams.toString()}`;
+    const response = await fetchFn(url);
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `google-sheets: batchGetValues failed (${response.status}): ${body}`
+      );
+    }
+    return await response.json();
   }
-  let cachedToken = null;
-  let tokenExpiresAt = 0;
-  async function getAccessToken() {
-    const nowSec = Math.floor(Date.now() / 1e3);
-    if (cachedToken && nowSec < tokenExpiresAt - 60) {
-      return cachedToken;
+  async function updateValues(spreadsheetId, range, values) {
+    const url = `${SHEETS_BASE_URL}/${spreadsheetId}/values/${encodeURIComponent(range)}?valueInputOption=USER_ENTERED`;
+    const response = await fetchFn(url, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ range, majorDimension: "ROWS", values })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `google-sheets: updateValues failed (${response.status}): ${body}`
+      );
     }
-    const jwt = buildJwt(
-      serviceAccountKey.client_email,
-      serviceAccountKey.private_key,
-      nowSec
-    );
-    const response = await fetch(TOKEN_URL, {
+    return await response.json();
+  }
+  async function appendValues(spreadsheetId, range, values) {
+    const url = `${SHEETS_BASE_URL}/${spreadsheetId}/values/${encodeURIComponent(range)}:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS`;
+    const response = await fetchFn(url, {
       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
-      })
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ range, majorDimension: "ROWS", values })
     });
     if (!response.ok) {
-      const text = await response.text();
+      const body = await response.text();
       throw new Error(
-        `google-sheets: token exchange failed (${response.status}): ${text}`
+        `google-sheets: appendValues failed (${response.status}): ${body}`
       );
     }
-    const data = await response.json();
-    cachedToken = data.access_token;
-    tokenExpiresAt = nowSec + data.expires_in;
-    return cachedToken;
+    return await response.json();
   }
-  function resolveSpreadsheetId(override) {
-    const id = override ?? defaultSpreadsheetId;
-    if (!id) {
+  async function createSpreadsheet(title, sheetTitles) {
+    const sheets = sheetTitles && sheetTitles.length > 0 ? sheetTitles.map((t) => ({ properties: { title: t } })) : void 0;
+    const url = `${SHEETS_BASE_URL}`;
+    const response = await fetchFn(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        properties: { title },
+        ...sheets ? { sheets } : {}
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
       throw new Error(
-        "google-sheets: spreadsheetId is required. Either configure a default or pass it explicitly."
+        `google-sheets: createSpreadsheet failed (${response.status}): ${body}`
       );
     }
-    return id;
-  }
-  async function authenticatedFetch(url, init) {
-    const accessToken = await getAccessToken();
-    const headers = new Headers(init?.headers);
-    headers.set("Authorization", `Bearer ${accessToken}`);
-    return fetch(url, { ...init, headers });
+    return await response.json();
   }
   return {
-    async request(path2, init) {
-      const resolvedPath = defaultSpreadsheetId ? path2.replace(/\{spreadsheetId\}/g, defaultSpreadsheetId) : path2;
-      const url = `${BASE_URL}${resolvedPath.startsWith("/") ? "" : "/"}${resolvedPath}`;
-      return authenticatedFetch(url, init);
-    },
-    async getSpreadsheet(spreadsheetId) {
-      const id = resolveSpreadsheetId(spreadsheetId);
-      const url = `${BASE_URL}/${id}?fields=spreadsheetId,properties,sheets.properties`;
-      const response = await authenticatedFetch(url);
-      if (!response.ok) {
-        const body = await response.text();
-        throw new Error(
-          `google-sheets: getSpreadsheet failed (${response.status}): ${body}`
-        );
-      }
-      return await response.json();
-    },
-    async getValues(range, spreadsheetId) {
-      const id = resolveSpreadsheetId(spreadsheetId);
-      const url = `${BASE_URL}/${id}/values/${encodeURIComponent(range)}`;
-      const response = await authenticatedFetch(url);
-      if (!response.ok) {
-        const body = await response.text();
-        throw new Error(
-          `google-sheets: getValues failed (${response.status}): ${body}`
-        );
-      }
-      return await response.json();
-    },
-    async batchGetValues(ranges, spreadsheetId) {
-      const id = resolveSpreadsheetId(spreadsheetId);
-      const searchParams = new URLSearchParams();
-      for (const range of ranges) {
-        searchParams.append("ranges", range);
-      }
-      const url = `${BASE_URL}/${id}/values:batchGet?${searchParams.toString()}`;
-      const response = await authenticatedFetch(url);
-      if (!response.ok) {
-        const body = await response.text();
-        throw new Error(
-          `google-sheets: batchGetValues failed (${response.status}): ${body}`
-        );
-      }
-      return await response.json();
-    }
+    request,
+    getSpreadsheet,
+    getValues,
+    batchGetValues,
+    updateValues,
+    appendValues,
+    createSpreadsheet
   };
 }
 
@@ -319,21 +184,58 @@ var ConnectorPlugin = class _ConnectorPlugin {
    * Filters connections by connectorKey internally.
    * Returns tools keyed as `${connectorKey}_${toolName}`.
    */
-  createTools(connections, config) {
+  createTools(connections, config, opts) {
     const myConnections = connections.filter(
       (c) => _ConnectorPlugin.deriveKey(c.connector.slug, c.connector.authType) === this.connectorKey
     );
     const result = {};
     for (const t of Object.values(this.tools)) {
-      result[`${this.connectorKey}_${t.name}`] = t.createTool(
-        myConnections,
-        config
-      );
+      const tool = t.createTool(myConnections, config);
+      const originalToModelOutput = tool.toModelOutput;
+      result[`${this.connectorKey}_${t.name}`] = {
+        ...tool,
+        toModelOutput: async (options) => {
+          if (!originalToModelOutput) {
+            return opts.truncateOutput(options.output);
+          }
+          const modelOutput = await originalToModelOutput(options);
+          if (modelOutput.type === "text" || modelOutput.type === "json") {
+            return opts.truncateOutput(modelOutput.value);
+          }
+          return modelOutput;
+        }
+      };
     }
     return result;
   }
   static deriveKey(slug, authType) {
-    return authType ? `${slug}-${authType}` : slug;
+    if (authType) return `${slug}-${authType}`;
+    const LEGACY_NULL_AUTH_TYPE_MAP = {
+      // user-password
+      "postgresql": "user-password",
+      "mysql": "user-password",
+      "clickhouse": "user-password",
+      "kintone": "user-password",
+      "squadbase-db": "user-password",
+      // service-account
+      "snowflake": "service-account",
+      "bigquery": "service-account",
+      "google-analytics": "service-account",
+      "google-calendar": "service-account",
+      "aws-athena": "service-account",
+      "redshift": "service-account",
+      // api-key
+      "databricks": "api-key",
+      "dbt": "api-key",
+      "airtable": "api-key",
+      "openai": "api-key",
+      "gemini": "api-key",
+      "anthropic": "api-key",
+      "wix-store": "api-key"
+    };
+    const fallbackAuthType = LEGACY_NULL_AUTH_TYPE_MAP[slug];
+    if (fallbackAuthType) return `${slug}-${fallbackAuthType}`;
+    return slug;
   }
 };
 
@@ -350,27 +252,61 @@ var AUTH_TYPES = {
 // ../connectors/src/connectors/google-sheets/setup.ts
 var googleSheetsOnboarding = new ConnectorOnboarding({
   dataOverviewInstructions: {
-    en: `1. Call google-sheets_request with GET /{spreadsheetId} to get spreadsheet metadata (sheet names and properties)
-2. Call google-sheets_request with GET /{spreadsheetId}/values/{sheetName}!A1:Z5 to sample data from key sheets`,
-    ja: `1. google-sheets_request \u3067 GET /{spreadsheetId} \u3092\u547C\u3073\u51FA\u3057\u3001\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\uFF08\u30B7\u30FC\u30C8\u540D\u3068\u30D7\u30ED\u30D1\u30C6\u30A3\uFF09\u3092\u53D6\u5F97
-2. google-sheets_request \u3067 GET /{spreadsheetId}/values/{sheetName}!A1:Z5 \u3092\u547C\u3073\u51FA\u3057\u3001\u4E3B\u8981\u30B7\u30FC\u30C8\u306E\u30C7\u30FC\u30BF\u3092\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0`
+    en: `1. Create a new spreadsheet with google-sheets-oauth_request (POST with body { properties: { title: "..." } }) or use an existing spreadsheet ID.
+2. Call google-sheets-oauth_request with GET /{spreadsheetId} to fetch spreadsheet metadata (sheet names and properties).`,
+    ja: `1. google-sheets-oauth_request \u3092 POST\uFF08Body: { properties: { title: "..." } }\uFF09\u3067\u547C\u3073\u51FA\u3057\u3066\u65B0\u3057\u3044\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3092\u4F5C\u6210\u3059\u308B\u304B\u3001\u65E2\u5B58\u306E\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8ID\u3092\u5229\u7528\u3057\u307E\u3059\u3002
+2. google-sheets-oauth_request \u3067 GET /{spreadsheetId} \u3092\u547C\u3073\u51FA\u3057\u3001\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\uFF08\u30B7\u30FC\u30C8\u540D\u3068\u30D7\u30ED\u30D1\u30C6\u30A3\uFF09\u3092\u53D6\u5F97\u3057\u307E\u3059\u3002`
   }
 });
 
+// ../connectors/src/connectors/google-sheets/parameters.ts
+var parameters = {};
+
 // ../connectors/src/connectors/google-sheets/tools/request.ts
 import { z } from "zod";
-init_utils();
-var BASE_URL2 = "https://sheets.googleapis.com/v4/spreadsheets";
+var SHEETS_BASE_URL2 = "https://sheets.googleapis.com/v4/spreadsheets";
 var REQUEST_TIMEOUT_MS = 6e4;
+var cachedToken = null;
+async function getProxyToken(config) {
+  if (cachedToken && cachedToken.expiresAt > Date.now() + 6e4) {
+    return cachedToken.token;
+  }
+  const url = `${config.appApiBaseUrl}/v0/database/${config.projectId}/environment/${config.environmentId}/oauth-request-proxy-token`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": config.appApiKey,
+      "project-id": config.projectId
+    },
+    body: JSON.stringify({
+      sandboxId: config.sandboxId,
+      issuedBy: "coding-agent"
+    })
+  });
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => res.statusText);
+    throw new Error(
+      `Failed to get proxy token: HTTP ${res.status} ${errorText}`
+    );
+  }
+  const data = await res.json();
+  cachedToken = {
+    token: data.token,
+    expiresAt: new Date(data.expiresAt).getTime()
+  };
+  return data.token;
+}
 var inputSchema = z.object({
   toolUseIntent: z.string().optional().describe(
     "Brief description of what you intend to accomplish with this tool call"
   ),
   connectionId: z.string().describe("ID of the Google Sheets connection to use"),
-  method: z.enum(["GET"]).describe("HTTP method (read-only, GET only)"),
+  method: z.enum(["GET", "POST", "PUT"]).describe("HTTP method"),
   path: z.string().describe(
-    "API path appended to https://sheets.googleapis.com/v4/spreadsheets (e.g., '/{spreadsheetId}', '/{spreadsheetId}/values/Sheet1!A1:D10'). {spreadsheetId} is automatically replaced if a default is configured."
+    "API path appended to https://sheets.googleapis.com/v4/spreadsheets (e.g., '', '/{spreadsheetId}', '/{spreadsheetId}/values/Sheet1!A1:D10')."
   ),
+  body: z.record(z.string(), z.unknown()).optional().describe("JSON request body for POST/PUT requests"),
   queryParams: z.record(z.string(), z.string()).optional().describe("Query parameters to append to the URL")
 });
 var outputSchema = z.discriminatedUnion("success", [
@@ -386,12 +322,12 @@ var outputSchema = z.discriminatedUnion("success", [
 ]);
 var requestTool = new ConnectorTool({
   name: "request",
-  description: `Send authenticated GET requests to the Google Sheets API v4.
-Authentication is handled automatically using a service account.
-{spreadsheetId} in the path is automatically replaced with the connection's default spreadsheet ID if configured.`,
+  description: `Send authenticated requests to the Google Sheets API v4.
+Supports GET (read), POST (create/append), and PUT (update) methods.
+Authentication is handled automatically via OAuth proxy.`,
   inputSchema,
   outputSchema,
-  async execute({ connectionId, method, path: path2, queryParams }, connections) {
+  async execute({ connectionId, method, path: path2, body, queryParams }, connections, config) {
     const connection2 = connections.find((c) => c.id === connectionId);
     if (!connection2) {
       return {
@@ -403,47 +339,33 @@ Authentication is handled automatically using a service account.
       `[connector-request] google-sheets/${connection2.name}: ${method} ${path2}`
     );
     try {
-      const { GoogleAuth } = await import("google-auth-library");
-      const keyJsonBase64 = parameters.serviceAccountKeyJsonBase64.getValue(connection2);
-      const spreadsheetUrl = parameters.spreadsheetUrl.tryGetValue(connection2);
-      const spreadsheetId = spreadsheetUrl ? extractSpreadsheetId(spreadsheetUrl) : void 0;
-      const credentials = JSON.parse(
-        Buffer.from(keyJsonBase64, "base64").toString("utf-8")
-      );
-      const auth = new GoogleAuth({
-        credentials,
-        scopes: ["https://www.googleapis.com/auth/spreadsheets.readonly"]
-      });
-      const token = await auth.getAccessToken();
-      if (!token) {
-        return {
-          success: false,
-          error: "Failed to obtain access token"
-        };
-      }
-      const resolvedPath = spreadsheetId ? path2.replace(/\{spreadsheetId\}/g, spreadsheetId) : path2;
-      let url = `${BASE_URL2}${resolvedPath.startsWith("/") ? "" : "/"}${resolvedPath}`;
+      let url = `${SHEETS_BASE_URL2}${path2 === "" || path2.startsWith("/") ? "" : "/"}${path2}`;
       if (queryParams) {
         const searchParams = new URLSearchParams(queryParams);
         url += `?${searchParams.toString()}`;
       }
+      const token = await getProxyToken(config.oauthProxy);
+      const proxyUrl = `https://${config.oauthProxy.sandboxId}.${config.oauthProxy.previewBaseDomain}/_sqcore/connections/${connectionId}/request`;
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
       try {
-        const response = await fetch(url, {
-          method,
+        const response = await fetch(proxyUrl, {
+          method: "POST",
           headers: {
+            "Content-Type": "application/json",
             Authorization: `Bearer ${token}`
           },
+          body: JSON.stringify({
+            url,
+            method,
+            ...body != null ? { body: JSON.stringify(body) } : {}
+          }),
           signal: controller.signal
         });
         const data = await response.json();
         if (!response.ok) {
-          const errorObj = data?.error;
-          return {
-            success: false,
-            error: errorObj?.message ?? `HTTP ${response.status} ${response.statusText}`
-          };
+          const errorMessage = typeof data?.error === "string" ? data.error : typeof data?.message === "string" ? data.message : `HTTP ${response.status} ${response.statusText}`;
+          return { success: false, error: errorMessage };
         }
         return { success: true, status: response.status, data };
       } finally {
@@ -460,25 +382,41 @@ Authentication is handled automatically using a service account.
 var tools = { request: requestTool };
 var googleSheetsConnector = new ConnectorPlugin({
   slug: "google-sheets",
-  authType: AUTH_TYPES.SERVICE_ACCOUNT,
+  authType: AUTH_TYPES.OAUTH,
   name: "Google Sheets",
-  description: "Connect to Google Sheets for spreadsheet data access using a service account.",
+  description: "Connect to Google Sheets for spreadsheet data access and creation using OAuth.",
   iconUrl: "https://images.ctfassets.net/9ncizv60xc5y/1UPQuggyiZmbb26CuaSr2h/032770e8739b183fa00b7625f024e536/google-sheets.svg",
   parameters,
   releaseFlag: { dev1: true, dev2: false, prod: false },
   onboarding: googleSheetsOnboarding,
+  proxyPolicy: {
+    allowlist: [
+      {
+        host: "sheets.googleapis.com",
+        methods: ["GET", "POST", "PUT"]
+      }
+    ]
+  },
   systemPrompt: {
-    en: `### Tools
+    en: `### Tools (setup-time only)
+
+- \`google-sheets-oauth_request\`: Call the Google Sheets API during setup / data overview. Supports read and write operations. Use it to get/update spreadsheet metadata, cell values, create new spreadsheets, and more. Authentication is configured automatically via OAuth.
 
-- \`google-sheets_request\`: The only way to call the Google Sheets API (read-only). Use it to get spreadsheet metadata, cell values, and batch values. Authentication is configured automatically via service account. The {spreadsheetId} placeholder in paths is automatically replaced with the configured default spreadsheet ID.
+> **Important**: The \`google-sheets-oauth_request\` tool is only available at setup time. Inside server-logic handlers, use the SDK (\`connection(id).getValues\`, etc.) \u2014 the SDK's fetch is already wired through the OAuth proxy. **Do NOT** hand-roll HTTP calls to \`_sqcore/connections/*/request\` from a handler.
 
 ### Google Sheets API Reference
 
-#### Available Endpoints
+#### Read Endpoints
 - GET \`/{spreadsheetId}\` \u2014 Get spreadsheet metadata (title, sheets, properties)
 - GET \`/{spreadsheetId}/values/{range}\` \u2014 Get cell values for a range
 - GET \`/{spreadsheetId}/values:batchGet?ranges={range1}&ranges={range2}\` \u2014 Get values for multiple ranges
 
+#### Write Endpoints
+- POST \`\` (empty path, with body) \u2014 Create a new spreadsheet. Body: \`{ "properties": { "title": "My Sheet" }, "sheets": [{ "properties": { "title": "Sheet1" } }] }\`
+- PUT \`/{spreadsheetId}/values/{range}?valueInputOption=USER_ENTERED\` \u2014 Update cell values for a range. Body: \`{ "range": "Sheet1!A1:B2", "majorDimension": "ROWS", "values": [["a","b"],["c","d"]] }\`
+- POST \`/{spreadsheetId}/values/{range}:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS\` \u2014 Append rows after the last row. Body: \`{ "range": "Sheet1!A1", "majorDimension": "ROWS", "values": [["a","b"]] }\`
+- POST \`/{spreadsheetId}:batchUpdate\` \u2014 Apply multiple updates (formatting, add sheets, merge cells, etc.). Body: \`{ "requests": [...] }\`
+
 ### Range Notation (A1 notation)
 - \`Sheet1!A1:D10\` \u2014 Specific range on Sheet1
 - \`Sheet1!A:A\` \u2014 Entire column A on Sheet1
@@ -487,15 +425,27 @@ var googleSheetsConnector = new ConnectorPlugin({
 - \`A1:D10\` \u2014 Range on the first sheet (when only one sheet exists)
 
 ### Tips
-- Use \`{spreadsheetId}\` placeholder in paths \u2014 it is automatically replaced with the configured default spreadsheet ID
 - To explore a spreadsheet, first get metadata to see available sheet names
 - Use \`valueRenderOption=FORMATTED_VALUE\` query param to get display values
 - Use \`valueRenderOption=UNFORMATTED_VALUE\` for raw numeric values
 - Use \`majorDimension=COLUMNS\` to get data organized by columns instead of rows
+- For write operations, always use \`valueInputOption=USER_ENTERED\` so values are parsed as if typed by a user (dates, numbers, formulas are auto-detected)
+- Sharing (permissions) cannot be done via this connector; only the OAuth user has access to the created spreadsheets
 
 ### Business Logic
 
-The business logic type for this connector is "typescript". Write handler code using the connector SDK shown below. Do NOT access credentials directly from environment variables.
+The business logic type for this connector is "typescript". Write handler code using the connector SDK shown below. Do NOT access credentials directly from environment variables and do NOT read \`INTERNAL_SQUADBASE_*\` env vars \u2014 the SDK takes care of OAuth.
+
+SDK surface (client created via \`connection(connectionId)\`):
+- \`client.request(path, init?)\` \u2014 low-level authenticated fetch (\`path\` is appended to \`https://sheets.googleapis.com/v4/spreadsheets\`).
+- \`client.getSpreadsheet(spreadsheetId)\` \u2014 fetch spreadsheet metadata.
+- \`client.getValues(spreadsheetId, range)\` \u2014 read a range (A1 notation).
+- \`client.batchGetValues(spreadsheetId, ranges)\` \u2014 read multiple ranges.
+- \`client.updateValues(spreadsheetId, range, values)\` \u2014 write values to a range.
+- \`client.appendValues(spreadsheetId, range, values)\` \u2014 append rows after the last row.
+- \`client.createSpreadsheet(title, sheetNames?)\` \u2014 create a new spreadsheet.
+
+If a handler test fails with \`Connection proxy is not configured\`, retry \u2014 the sandbox is still initializing. Do NOT abandon the SDK and construct OAuth proxy URLs manually.
 
 #### Example
 
@@ -504,29 +454,43 @@ import { connection } from "@squadbase/vite-server/connectors/google-sheets";
 
 const sheets = connection("<connectionId>");
 
+// Create a new spreadsheet
+const newSheet = await sheets.createSpreadsheet("Sales Report", ["Q1", "Q2", "Q3", "Q4"]);
+const spreadsheetId = newSheet.spreadsheetId;
+
 // Get spreadsheet metadata
-const metadata = await sheets.getSpreadsheet();
+const metadata = await sheets.getSpreadsheet(spreadsheetId);
 console.log(metadata.properties.title, metadata.sheets.map(s => s.properties.title));
 
 // Get cell values
-const values = await sheets.getValues("Sheet1!A1:D10");
+const values = await sheets.getValues(spreadsheetId, "Sheet1!A1:D10");
 console.log(values.values); // 2D array
 
-// Get multiple ranges at once
-const batch = await sheets.batchGetValues(["Sheet1!A1:B5", "Sheet2!A1:C3"]);
-batch.valueRanges.forEach(vr => console.log(vr.range, vr.values));
+// Update cell values
+await sheets.updateValues(spreadsheetId, "Sheet1!A1:B2", [["Name", "Score"], ["Alice", "100"]]);
+
+// Append rows
+await sheets.appendValues(spreadsheetId, "Sheet1!A1", [["Bob", "95"], ["Charlie", "88"]]);
 \`\`\``,
-    ja: `### \u30C4\u30FC\u30EB
+    ja: `### \u30C4\u30FC\u30EB\uFF08\u30BB\u30C3\u30C8\u30A2\u30C3\u30D7\u6642\u306E\u307F\uFF09
+
+- \`google-sheets-oauth_request\`: \u30BB\u30C3\u30C8\u30A2\u30C3\u30D7\u3084\u30C7\u30FC\u30BF\u6982\u8981\u628A\u63E1\u6642\u306B Google Sheets API \u3092\u547C\u3073\u51FA\u3059\u30C4\u30FC\u30EB\u3067\u3059\u3002\u8AAD\u307F\u53D6\u308A\u3068\u66F8\u304D\u8FBC\u307F\u306E\u4E21\u65B9\u3092\u30B5\u30DD\u30FC\u30C8\u3057\u307E\u3059\u3002\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\u30FB\u30BB\u30EB\u5024\u306E\u53D6\u5F97/\u66F4\u65B0\u3001\u65B0\u3057\u3044\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u4F5C\u6210\u306A\u3069\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002OAuth \u7D4C\u7531\u3067\u8A8D\u8A3C\u306F\u81EA\u52D5\u8A2D\u5B9A\u3055\u308C\u307E\u3059\u3002
 
-- \`google-sheets_request\`: Google Sheets API\u3092\u547C\u3073\u51FA\u3059\u552F\u4E00\u306E\u624B\u6BB5\u3067\u3059\uFF08\u8AAD\u307F\u53D6\u308A\u5C02\u7528\uFF09\u3002\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\u3001\u30BB\u30EB\u5024\u3001\u30D0\u30C3\u30C1\u5024\u306E\u53D6\u5F97\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002\u30B5\u30FC\u30D3\u30B9\u30A2\u30AB\u30A6\u30F3\u30C8\u7D4C\u7531\u3067\u8A8D\u8A3C\u306F\u81EA\u52D5\u8A2D\u5B9A\u3055\u308C\u307E\u3059\u3002\u30D1\u30B9\u5185\u306E{spreadsheetId}\u30D7\u30EC\u30FC\u30B9\u30DB\u30EB\u30C0\u30FC\u306F\u8A2D\u5B9A\u6E08\u307F\u306E\u30C7\u30D5\u30A9\u30EB\u30C8\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8ID\u3067\u81EA\u52D5\u7684\u306B\u7F6E\u63DB\u3055\u308C\u307E\u3059\u3002
+> **\u91CD\u8981**: \`google-sheets-oauth_request\` \u306F\u30BB\u30C3\u30C8\u30A2\u30C3\u30D7\u6642\u306E\u307F\u5229\u7528\u53EF\u80FD\u3067\u3059\u3002\u30B5\u30FC\u30D0\u30FC\u30ED\u30B8\u30C3\u30AF\u306E\u30CF\u30F3\u30C9\u30E9\u5185\u3067\u306F\u5FC5\u305A SDK\uFF08\`connection(id).getValues\` \u306A\u3069\uFF09\u3092\u4F7F\u3063\u3066\u304F\u3060\u3055\u3044\u3002SDK \u306E fetch \u306F OAuth \u30D7\u30ED\u30AD\u30B7\u7D4C\u7531\u3067\u65E2\u306B\u914D\u7DDA\u3055\u308C\u3066\u3044\u307E\u3059\u3002\u30CF\u30F3\u30C9\u30E9\u304B\u3089 \`_sqcore/connections/*/request\` \u3092\u624B\u66F8\u304D\u3067\u547C\u3073\u51FA\u3055\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002
 
 ### Google Sheets API \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9
 
-#### \u5229\u7528\u53EF\u80FD\u306A\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8
+#### \u8AAD\u307F\u53D6\u308A\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8
 - GET \`/{spreadsheetId}\` \u2014 \u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\u3092\u53D6\u5F97\uFF08\u30BF\u30A4\u30C8\u30EB\u3001\u30B7\u30FC\u30C8\u3001\u30D7\u30ED\u30D1\u30C6\u30A3\uFF09
 - GET \`/{spreadsheetId}/values/{range}\` \u2014 \u7BC4\u56F2\u306E\u30BB\u30EB\u5024\u3092\u53D6\u5F97
 - GET \`/{spreadsheetId}/values:batchGet?ranges={range1}&ranges={range2}\` \u2014 \u8907\u6570\u7BC4\u56F2\u306E\u5024\u3092\u53D6\u5F97
 
+#### \u66F8\u304D\u8FBC\u307F\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8
+- POST \`\`\uFF08\u7A7A\u30D1\u30B9\u3001\u30DC\u30C7\u30A3\u4ED8\u304D\uFF09\u2014 \u65B0\u3057\u3044\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3092\u4F5C\u6210\u3002Body: \`{ "properties": { "title": "\u30DE\u30A4\u30B7\u30FC\u30C8" }, "sheets": [{ "properties": { "title": "Sheet1" } }] }\`
+- PUT \`/{spreadsheetId}/values/{range}?valueInputOption=USER_ENTERED\` \u2014 \u7BC4\u56F2\u306E\u30BB\u30EB\u5024\u3092\u66F4\u65B0\u3002Body: \`{ "range": "Sheet1!A1:B2", "majorDimension": "ROWS", "values": [["a","b"],["c","d"]] }\`
+- POST \`/{spreadsheetId}/values/{range}:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS\` \u2014 \u6700\u7D42\u884C\u306E\u5F8C\u306B\u884C\u3092\u8FFD\u52A0\u3002Body: \`{ "range": "Sheet1!A1", "majorDimension": "ROWS", "values": [["a","b"]] }\`
+- POST \`/{spreadsheetId}:batchUpdate\` \u2014 \u8907\u6570\u306E\u66F4\u65B0\u3092\u9069\u7528\uFF08\u66F8\u5F0F\u8A2D\u5B9A\u3001\u30B7\u30FC\u30C8\u8FFD\u52A0\u3001\u30BB\u30EB\u7D50\u5408\u306A\u3069\uFF09\u3002Body: \`{ "requests": [...] }\`
+
 ### \u7BC4\u56F2\u306E\u8868\u8A18\u6CD5\uFF08A1\u8868\u8A18\u6CD5\uFF09
 - \`Sheet1!A1:D10\` \u2014 Sheet1\u4E0A\u306E\u7279\u5B9A\u7BC4\u56F2
 - \`Sheet1!A:A\` \u2014 Sheet1\u306EA\u5217\u5168\u4F53
@@ -535,15 +499,27 @@ batch.valueRanges.forEach(vr => console.log(vr.range, vr.values));
 - \`A1:D10\` \u2014 \u6700\u521D\u306E\u30B7\u30FC\u30C8\u306E\u7BC4\u56F2\uFF08\u30B7\u30FC\u30C8\u304C1\u3064\u306E\u307F\u306E\u5834\u5408\uFF09
 
 ### \u30D2\u30F3\u30C8
-- \u30D1\u30B9\u306B \`{spreadsheetId}\` \u30D7\u30EC\u30FC\u30B9\u30DB\u30EB\u30C0\u30FC\u3092\u4F7F\u7528 \u2014 \u8A2D\u5B9A\u6E08\u307F\u306E\u30C7\u30D5\u30A9\u30EB\u30C8\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8ID\u3067\u81EA\u52D5\u7684\u306B\u7F6E\u63DB\u3055\u308C\u307E\u3059
 - \u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3092\u63A2\u7D22\u3059\u308B\u306B\u306F\u3001\u307E\u305A\u30E1\u30BF\u30C7\u30FC\u30BF\u3092\u53D6\u5F97\u3057\u3066\u5229\u7528\u53EF\u80FD\u306A\u30B7\u30FC\u30C8\u540D\u3092\u78BA\u8A8D\u3057\u307E\u3059
 - \u8868\u793A\u5024\u3092\u53D6\u5F97\u3059\u308B\u306B\u306F \`valueRenderOption=FORMATTED_VALUE\` \u30AF\u30A8\u30EA\u30D1\u30E9\u30E1\u30FC\u30BF\u3092\u4F7F\u7528\u3057\u307E\u3059
 - \u751F\u306E\u6570\u5024\u3092\u53D6\u5F97\u3059\u308B\u306B\u306F \`valueRenderOption=UNFORMATTED_VALUE\` \u3092\u4F7F\u7528\u3057\u307E\u3059
 - \u5217\u3054\u3068\u306B\u30C7\u30FC\u30BF\u3092\u53D6\u5F97\u3059\u308B\u306B\u306F \`majorDimension=COLUMNS\` \u3092\u4F7F\u7528\u3057\u307E\u3059
+- \u66F8\u304D\u8FBC\u307F\u64CD\u4F5C\u3067\u306F\u5E38\u306B \`valueInputOption=USER_ENTERED\` \u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u5024\u304C\u30E6\u30FC\u30B6\u30FC\u5165\u529B\u306E\u3088\u3046\u306B\u89E3\u6790\u3055\u308C\u307E\u3059\uFF08\u65E5\u4ED8\u3001\u6570\u5024\u3001\u6570\u5F0F\u304C\u81EA\u52D5\u691C\u51FA\uFF09
+- \u5171\u6709\uFF08permissions\uFF09\u306F\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u7D4C\u7531\u3067\u306F\u884C\u3048\u307E\u305B\u3093\u3002\u4F5C\u6210\u3057\u305F\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3078\u306F\u63A5\u7D9A\u3057\u305FOAuth\u30E6\u30FC\u30B6\u30FC\u306E\u307F\u304C\u30A2\u30AF\u30BB\u30B9\u53EF\u80FD\u3067\u3059
 
 ### Business Logic
 
-\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u4EE5\u4E0B\u306B\u793A\u3059\u30B3\u30CD\u30AF\u30BFSDK\u3092\u4F7F\u7528\u3057\u3066\u30CF\u30F3\u30C9\u30E9\u30B3\u30FC\u30C9\u3092\u8A18\u8FF0\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u74B0\u5883\u5909\u6570\u304B\u3089\u76F4\u63A5\u8A8D\u8A3C\u60C5\u5831\u306B\u30A2\u30AF\u30BB\u30B9\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002
+\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u4EE5\u4E0B\u306B\u793A\u3059\u30B3\u30CD\u30AF\u30BF SDK \u3092\u4F7F\u7528\u3057\u3066\u30CF\u30F3\u30C9\u30E9\u30B3\u30FC\u30C9\u3092\u8A18\u8FF0\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u74B0\u5883\u5909\u6570\u304B\u3089\u76F4\u63A5\u8A8D\u8A3C\u60C5\u5831\u306B\u30A2\u30AF\u30BB\u30B9\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002\`INTERNAL_SQUADBASE_*\` \u306E\u74B0\u5883\u5909\u6570\u3092\u4F7F\u3063\u3066\u624B\u52D5\u3067 OAuth \u30D7\u30ED\u30AD\u30B7\u3092\u53E9\u304F\u3053\u3068\u3082\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044 \u2014 SDK \u304C OAuth \u3092\u51E6\u7406\u3057\u307E\u3059\u3002
+
+SDK\uFF08\`connection(connectionId)\` \u3067\u4F5C\u6210\u3057\u305F\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\uFF09:
+- \`client.request(path, init?)\` \u2014 \u4F4E\u30EC\u30D9\u30EB\u306E\u8A8D\u8A3C\u4ED8\u304D fetch\uFF08\`path\` \u306F \`https://sheets.googleapis.com/v4/spreadsheets\` \u306B\u8FFD\u52A0\u3055\u308C\u307E\u3059\uFF09\u3002
+- \`client.getSpreadsheet(spreadsheetId)\` \u2014 \u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\u3092\u53D6\u5F97\u3002
+- \`client.getValues(spreadsheetId, range)\` \u2014 \u7BC4\u56F2\u306E\u5024\u3092\u53D6\u5F97\uFF08A1 \u8868\u8A18\uFF09\u3002
+- \`client.batchGetValues(spreadsheetId, ranges)\` \u2014 \u8907\u6570\u7BC4\u56F2\u306E\u5024\u3092\u53D6\u5F97\u3002
+- \`client.updateValues(spreadsheetId, range, values)\` \u2014 \u7BC4\u56F2\u306B\u5024\u3092\u66F8\u304D\u8FBC\u307F\u3002
+- \`client.appendValues(spreadsheetId, range, values)\` \u2014 \u6700\u7D42\u884C\u306E\u5F8C\u306B\u884C\u3092\u8FFD\u52A0\u3002
+- \`client.createSpreadsheet(title, sheetNames?)\` \u2014 \u65B0\u3057\u3044\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3092\u4F5C\u6210\u3002
+
+\u30CF\u30F3\u30C9\u30E9\u306E\u30C6\u30B9\u30C8\u304C \`Connection proxy is not configured\` \u3067\u5931\u6557\u3059\u308B\u5834\u5408\u306F\u518D\u8A66\u884C\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u901A\u5E38\u306F\u30B5\u30F3\u30C9\u30DC\u30C3\u30AF\u30B9\u306E\u521D\u671F\u5316\u4E2D\u306B\u8D77\u304D\u307E\u3059\u3002SDK \u3092\u8AE6\u3081\u3066 OAuth \u30D7\u30ED\u30AD\u30B7\u306E URL \u3092\u81EA\u5206\u3067\u7D44\u307F\u7ACB\u3066\u308B\u3053\u3068\u306F **\u3057\u306A\u3044\u3067\u304F\u3060\u3055\u3044**\u3002
 
 #### Example
 
@@ -552,17 +528,23 @@ import { connection } from "@squadbase/vite-server/connectors/google-sheets";
 
 const sheets = connection("<connectionId>");
 
-// Get spreadsheet metadata
-const metadata = await sheets.getSpreadsheet();
+// \u65B0\u3057\u3044\u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u3092\u4F5C\u6210
+const newSheet = await sheets.createSpreadsheet("\u58F2\u4E0A\u30EC\u30DD\u30FC\u30C8", ["Q1", "Q2", "Q3", "Q4"]);
+const spreadsheetId = newSheet.spreadsheetId;
+
+// \u30B9\u30D7\u30EC\u30C3\u30C9\u30B7\u30FC\u30C8\u306E\u30E1\u30BF\u30C7\u30FC\u30BF\u3092\u53D6\u5F97
+const metadata = await sheets.getSpreadsheet(spreadsheetId);
 console.log(metadata.properties.title, metadata.sheets.map(s => s.properties.title));
 
-// Get cell values
-const values = await sheets.getValues("Sheet1!A1:D10");
+// \u30BB\u30EB\u5024\u3092\u53D6\u5F97
+const values = await sheets.getValues(spreadsheetId, "Sheet1!A1:D10");
 console.log(values.values); // 2D array
 
-// Get multiple ranges at once
-const batch = await sheets.batchGetValues(["Sheet1!A1:B5", "Sheet2!A1:C3"]);
-batch.valueRanges.forEach(vr => console.log(vr.range, vr.values));
+// \u30BB\u30EB\u5024\u3092\u66F4\u65B0
+await sheets.updateValues(spreadsheetId, "Sheet1!A1:B2", [["\u540D\u524D", "\u30B9\u30B3\u30A2"], ["Alice", "100"]]);
+
+// \u884C\u3092\u8FFD\u52A0
+await sheets.appendValues(spreadsheetId, "Sheet1!A1", [["Bob", "95"], ["Charlie", "88"]]);
 \`\`\``
   },
   tools