@flink-app/google-sheets-plugin 2.0.0-alpha.60

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @flink-app/google-sheets-plugin
+
+## 2.0.0-alpha.60
+
+### Minor Changes
+
+-   831892b: feat: add @flink-app/google-sheets-plugin
+
+    New plugin for reading and writing Google Sheets from a Flink app using service account authentication.
+
+    -   `googleSheetsPlugin()` factory adds `ctx.plugins.googleSheets` to the app context
+    -   Scoped sheet API via `.sheet(title)` and `.sheetByIndex(n)` with `getRows`, `appendRow`, `updateRow`, `deleteRow`
+    -   `getInfo()` for spreadsheet metadata
+    -   Static credentials via `credentials` option or dynamic loading via `loadCredentials` callback
+    -   Bundled `GoogleSheetsTool` for use with Flink AI agents
+    -   Supports raw PEM private keys and base64-encoded service account JSON
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.60

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Frost Experience AB https://www.frost.se
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @flink-app/google-sheets-plugin
+
+Read and write Google Sheets from a Flink app using service account authentication.
+
+## Prerequisites
+
+1. Create a service account in [Google Cloud Console](https://console.cloud.google.com/) → IAM & Admin → Service Accounts
+2. Enable the **Google Sheets API** for your project
+3. Share your spreadsheet with the service account email (Editor access)
+
+## Register the plugin
+
+```typescript
+import { googleSheetsPlugin, GoogleSheetsPluginCtx } from "@flink-app/google-sheets-plugin";
+
+interface AppCtx extends FlinkContext<GoogleSheetsPluginCtx> {
+    repos: {};
+}
+
+new FlinkApp<AppCtx>({
+    plugins: [
+        googleSheetsPlugin({
+            spreadsheetId: process.env.GOOGLE_SPREADSHEET_ID!,
+            credentials: {
+                clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
+                privateKey: process.env.GOOGLE_PRIVATE_KEY!,
+            },
+        }),
+    ],
+});
+```
+
+The private key accepts a raw PEM string (with `\n`) or a base64-encoded service account JSON blob.
+
+## Usage
+
+Access the API via `ctx.plugins.googleSheets`. Use `.sheet("Title")` or `.sheetByIndex(n)` to scope operations to a specific sheet.
+
+```typescript
+// Read all rows
+const rows = await ctx.plugins.googleSheets.sheet("Tasks").getRows();
+// [{ rowIndex: 0, data: { title: "Fix bug", status: "pending" } }, ...]
+
+// Append a row
+const row = await ctx.plugins.googleSheets.sheet("Tasks").appendRow({
+    title: "New task",
+    status: "pending",
+});
+
+// Update a row
+await ctx.plugins.googleSheets.sheet("Tasks").updateRow(row.rowIndex, {
+    status: "completed",
+});
+
+// Delete a row
+await ctx.plugins.googleSheets.sheet("Tasks").deleteRow(row.rowIndex);
+
+// Spreadsheet metadata
+const info = await ctx.plugins.googleSheets.getInfo();
+// { title, spreadsheetId, sheetCount }
+```
+
+Rows are plain objects: `{ rowIndex: number, data: Record<string, string> }` where keys are column headers.
+
+## Dynamic credentials
+
+Load credentials from the database at startup instead of env vars:
+
+```typescript
+googleSheetsPlugin({
+    loadCredentials: async (ctx) => {
+        const config = await ctx.repos.configRepo.getOne({ key: "google" });
+        return {
+            credentials: {
+                clientEmail: config.serviceAccountEmail,
+                privateKey: config.privateKey,
+            },
+            spreadsheetId: config.spreadsheetId,
+        };
+    },
+});
+```
+
+## AI tool
+
+A generic `GoogleSheetsTool` is included for use with Flink agents. It supports `getRows`, `appendRow`, `updateRow`, `deleteRow`, and `getInfo` operations.
+
+```typescript
+import GoogleSheetsTool, { Tool } from "@flink-app/google-sheets-plugin/tools/GoogleSheetsTool";
+
+class MyAgent extends FlinkAgent<AppCtx> {
+    tools = [{ ...Tool, handler: GoogleSheetsTool }];
+}
+```

package/dist/GoogleSheetsClient.d.ts

@@ -0,0 +1,2 @@
+import { GoogleSheetsCredentials, GoogleSheetsApi } from "./types";
+export declare function createGoogleSheetsApi(credentials: GoogleSheetsCredentials, spreadsheetId: string): GoogleSheetsApi;

package/dist/GoogleSheetsClient.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGoogleSheetsApi = createGoogleSheetsApi;
+const google_spreadsheet_1 = require("google-spreadsheet");
+const google_auth_library_1 = require("google-auth-library");
+function parsePrivateKey(raw) {
+    // Handle escaped newlines
+    let key = raw.replace(/\\n/g, "\n");
+    // Handle base64-encoded service account JSON
+    if (!key.includes("BEGIN PRIVATE KEY")) {
+        try {
+            const decoded = Buffer.from(key, "base64").toString("utf-8");
+            const parsed = JSON.parse(decoded);
+            if (parsed.private_key) {
+                key = parsed.private_key;
+            }
+        }
+        catch (_a) {
+            // Not base64-encoded JSON, use as-is
+        }
+    }
+    return key;
+}
+function createScopedSheetApi(doc, resolve) {
+    return {
+        async getRows() {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+            return rows.map((row, index) => ({
+                rowIndex: index,
+                data: Object.fromEntries(sheet.headerValues.map((h) => { var _a; return [h, (_a = row.get(h)) !== null && _a !== void 0 ? _a : ""]; })),
+            }));
+        },
+        async appendRow(data) {
+            const sheet = await resolve();
+            const row = await sheet.addRow(data);
+            return {
+                rowIndex: row.rowNumber - 2, // 1-indexed; header is row 1
+                data: Object.fromEntries(sheet.headerValues.map((h) => { var _a; return [h, (_a = row.get(h)) !== null && _a !== void 0 ? _a : ""]; })),
+            };
+        },
+        async updateRow(rowIndex, data) {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+            if (rowIndex < 0 || rowIndex >= rows.length) {
+                throw new Error(`Invalid rowIndex ${rowIndex}. Valid range: 0–${rows.length - 1}`);
+            }
+            const row = rows[rowIndex];
+            for (const [key, value] of Object.entries(data)) {
+                row.set(key, value);
+            }
+            await row.save();
+            return {
+                rowIndex,
+                data: Object.fromEntries(sheet.headerValues.map((h) => { var _a; return [h, (_a = row.get(h)) !== null && _a !== void 0 ? _a : ""]; })),
+            };
+        },
+        async deleteRow(rowIndex) {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+            if (rowIndex < 0 || rowIndex >= rows.length) {
+                throw new Error(`Invalid rowIndex ${rowIndex}. Valid range: 0–${rows.length - 1}`);
+            }
+            await rows[rowIndex].delete();
+        },
+    };
+}
+function createGoogleSheetsApi(credentials, spreadsheetId) {
+    const auth = new google_auth_library_1.JWT({
+        email: credentials.clientEmail,
+        key: parsePrivateKey(credentials.privateKey),
+        scopes: [
+            "https://www.googleapis.com/auth/spreadsheets",
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    });
+    const doc = new google_spreadsheet_1.GoogleSpreadsheet(spreadsheetId, auth);
+    let initialized = false;
+    const ensureInitialized = async () => {
+        if (!initialized) {
+            await doc.loadInfo();
+            initialized = true;
+        }
+    };
+    return {
+        async getInfo() {
+            await ensureInitialized();
+            return {
+                title: doc.title,
+                spreadsheetId,
+                sheetCount: doc.sheetCount,
+            };
+        },
+        sheet(title) {
+            return createScopedSheetApi(doc, async () => {
+                await ensureInitialized();
+                const sheet = doc.sheetsByTitle[title];
+                if (!sheet) {
+                    throw new Error(`Sheet "${title}" not found. Available sheets: ${Object.keys(doc.sheetsByTitle).join(", ")}`);
+                }
+                return sheet;
+            });
+        },
+        sheetByIndex(index) {
+            return createScopedSheetApi(doc, async () => {
+                await ensureInitialized();
+                const sheet = doc.sheetsByIndex[index];
+                if (!sheet) {
+                    throw new Error(`Sheet at index ${index} not found. Spreadsheet has ${doc.sheetCount} sheet(s).`);
+                }
+                return sheet;
+            });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { GoogleSheetsApi, GoogleSheetsPluginOptions } from "./types";
+export * from "./types";
+export declare function googleSheetsPlugin<TCtx>(options: GoogleSheetsPluginOptions<TCtx>): {
+    id: string;
+    readonly ctx: GoogleSheetsApi;
+    init: (app: {
+        ctx: TCtx;
+    }) => Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.googleSheetsPlugin = googleSheetsPlugin;
+const GoogleSheetsClient_1 = require("./GoogleSheetsClient");
+__exportStar(require("./types"), exports);
+function googleSheetsPlugin(options) {
+    let api;
+    return {
+        id: "googleSheets",
+        get ctx() {
+            if (!api) {
+                throw new Error("googleSheetsPlugin: plugin not yet initialized. " +
+                    "Ensure it is passed to FlinkApp before use.");
+            }
+            return api;
+        },
+        init: async (app) => {
+            let credentials = options.credentials;
+            let spreadsheetId = options.spreadsheetId;
+            if (options.loadCredentials) {
+                const loaded = await options.loadCredentials(app.ctx);
+                credentials = loaded.credentials;
+                if (loaded.spreadsheetId) {
+                    spreadsheetId = loaded.spreadsheetId;
+                }
+            }
+            if (!credentials) {
+                throw new Error("googleSheetsPlugin: no credentials provided. " +
+                    "Supply `credentials` or `loadCredentials` in the plugin options.");
+            }
+            if (!spreadsheetId) {
+                throw new Error("googleSheetsPlugin: no spreadsheetId provided. " +
+                    "Supply `spreadsheetId` in the plugin options or return it from `loadCredentials`.");
+            }
+            api = (0, GoogleSheetsClient_1.createGoogleSheetsApi)(credentials, spreadsheetId);
+        },
+    };
+}

package/dist/tools/GoogleSheetsTool.d.ts

@@ -0,0 +1,8 @@
+import { FlinkContext, FlinkTool, FlinkToolProps } from "@flink-app/flink";
+import { z } from "zod";
+import { GoogleSheetsPluginCtx } from "../types";
+export declare const Tool: FlinkToolProps;
+type Input = z.infer<typeof Tool.inputSchema>;
+type Output = z.infer<typeof Tool.outputSchema>;
+declare const GoogleSheetsTool: FlinkTool<FlinkContext<GoogleSheetsPluginCtx>, Input, Output>;
+export default GoogleSheetsTool;

package/dist/tools/GoogleSheetsTool.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+const zod_1 = require("zod");
+const RowDataSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.string());
+const RowWithIndexSchema = zod_1.z.object({
+    rowIndex: zod_1.z.number(),
+    data: RowDataSchema,
+});
+exports.Tool = {
+    id: "google-sheets",
+    description: "Read and write rows in a Google Sheets spreadsheet. " +
+        "Supports getRows, appendRow, updateRow, deleteRow, and getInfo operations. " +
+        "Rows are referenced by 0-based rowIndex. " +
+        "Data is a key-value map of column header to cell value.",
+    inputSchema: zod_1.z.strictObject({
+        operation: zod_1.z
+            .enum(["getRows", "appendRow", "updateRow", "deleteRow", "getInfo"])
+            .describe("Operation to perform"),
+        sheet: zod_1.z
+            .string()
+            .optional()
+            .describe("Sheet title. Defaults to the first sheet when omitted."),
+        rowIndex: zod_1.z
+            .number()
+            .optional()
+            .describe("0-based row index. Required for updateRow and deleteRow."),
+        data: RowDataSchema.optional().describe("Row data as column-header → value pairs. Required for appendRow and updateRow."),
+    }),
+    outputSchema: zod_1.z.object({
+        rows: zod_1.z.array(RowWithIndexSchema).optional(),
+        row: RowWithIndexSchema.optional(),
+        info: zod_1.z
+            .object({
+            title: zod_1.z.string(),
+            spreadsheetId: zod_1.z.string(),
+            sheetCount: zod_1.z.number(),
+        })
+            .optional(),
+    }),
+};
+const GoogleSheetsTool = async ({ input, ctx, }) => {
+    const api = ctx.plugins.googleSheets;
+    const sheetApi = input.sheet ? api.sheet(input.sheet) : api.sheetByIndex(0);
+    switch (input.operation) {
+        case "getInfo": {
+            const info = await api.getInfo();
+            return { success: true, data: { info } };
+        }
+        case "getRows": {
+            const rows = await sheetApi.getRows();
+            return { success: true, data: { rows } };
+        }
+        case "appendRow": {
+            if (!input.data) {
+                return { success: false, error: "`data` is required for appendRow" };
+            }
+            const row = await sheetApi.appendRow(input.data);
+            return { success: true, data: { row } };
+        }
+        case "updateRow": {
+            if (input.rowIndex === undefined) {
+                return { success: false, error: "`rowIndex` is required for updateRow" };
+            }
+            if (!input.data) {
+                return { success: false, error: "`data` is required for updateRow" };
+            }
+            const row = await sheetApi.updateRow(input.rowIndex, input.data);
+            return { success: true, data: { row } };
+        }
+        case "deleteRow": {
+            if (input.rowIndex === undefined) {
+                return { success: false, error: "`rowIndex` is required for deleteRow" };
+            }
+            await sheetApi.deleteRow(input.rowIndex);
+            return { success: true, data: {} };
+        }
+        default:
+            return { success: false, error: `Unknown operation: ${input.operation}` };
+    }
+};
+exports.default = GoogleSheetsTool;

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export interface GoogleSheetsCredentials {
+    /** Service account email (e.g. my-service@project.iam.gserviceaccount.com) */
+    clientEmail: string;
+    /**
+     * Private key in PEM format or base64-encoded service account JSON.
+     * Escaped newlines (\\n) are handled automatically.
+     */
+    privateKey: string;
+}
+/** A plain record of column header → cell value */
+export type SheetRow = Record<string, string>;
+/** A row with its 0-based position in the sheet */
+export interface SheetRowWithIndex {
+    rowIndex: number;
+    data: SheetRow;
+}
+export interface ScopedSheetApi {
+    /** Read all data rows from this sheet */
+    getRows(): Promise<SheetRowWithIndex[]>;
+    /** Append a new row. Returns the created row with its index. */
+    appendRow(data: SheetRow): Promise<SheetRowWithIndex>;
+    /** Update a row by 0-based rowIndex. Returns the updated row. */
+    updateRow(rowIndex: number, data: Partial<SheetRow>): Promise<SheetRowWithIndex>;
+    /** Delete a row by 0-based rowIndex. */
+    deleteRow(rowIndex: number): Promise<void>;
+}
+export interface GoogleSheetsApi {
+    /** Get spreadsheet metadata */
+    getInfo(): Promise<{
+        title: string;
+        spreadsheetId: string;
+        sheetCount: number;
+    }>;
+    /** Return a scoped API bound to a specific sheet by title */
+    sheet(title: string): ScopedSheetApi;
+    /** Return a scoped API bound to a sheet by 0-based index */
+    sheetByIndex(index: number): ScopedSheetApi;
+}
+export interface GoogleSheetsPluginOptions<TCtx = unknown> {
+    /**
+     * Target spreadsheet ID (the long ID from the Google Sheets URL).
+     * Can be omitted if `loadCredentials` resolves it dynamically.
+     */
+    spreadsheetId?: string;
+    /**
+     * Static service account credentials.
+     * Use `loadCredentials` instead when credentials come from the database or
+     * secrets manager.
+     */
+    credentials?: GoogleSheetsCredentials;
+    /**
+     * Dynamically load credentials (and optionally spreadsheetId) from the app
+     * context at startup. Takes priority over static `credentials`.
+     */
+    loadCredentials?: (ctx: TCtx) => Promise<{
+        credentials: GoogleSheetsCredentials;
+        spreadsheetId?: string;
+    }>;
+}
+export interface GoogleSheetsPluginCtx {
+    googleSheets: GoogleSheetsApi;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@flink-app/google-sheets-plugin",
+  "version": "2.0.0-alpha.60",
+  "description": "Flink plugin for reading and writing Google Sheets using service account authentication",
+  "author": "joel@frost.se",
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "google-auth-library": "^10.5.0",
+    "google-spreadsheet": "^5.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.10",
+    "tsc-watch": "^4.2.9",
+    "rimraf": "^5.0.5",
+    "@flink-app/flink": "2.0.0-alpha.60"
+  },
+  "peerDependencies": {
+    "@flink-app/flink": ">=2.0.0-alpha.60"
+  },
+  "scripts": {
+    "watch": "tsc-watch --project tsconfig.dist.json",
+    "build": "tsc --project tsconfig.dist.json",
+    "clean": "rimraf dist"
+  }
+}

package/src/GoogleSheetsClient.ts

@@ -0,0 +1,150 @@
+import { GoogleSpreadsheet } from "google-spreadsheet";
+import { JWT } from "google-auth-library";
+import { GoogleSheetsCredentials, GoogleSheetsApi, ScopedSheetApi, SheetRow, SheetRowWithIndex } from "./types";
+
+function parsePrivateKey(raw: string): string {
+    // Handle escaped newlines
+    let key = raw.replace(/\\n/g, "\n");
+
+    // Handle base64-encoded service account JSON
+    if (!key.includes("BEGIN PRIVATE KEY")) {
+        try {
+            const decoded = Buffer.from(key, "base64").toString("utf-8");
+            const parsed = JSON.parse(decoded);
+            if (parsed.private_key) {
+                key = parsed.private_key;
+            }
+        } catch {
+            // Not base64-encoded JSON, use as-is
+        }
+    }
+
+    return key;
+}
+
+function createScopedSheetApi(
+    doc: GoogleSpreadsheet,
+    resolve: () => Promise<import("google-spreadsheet").GoogleSpreadsheetWorksheet>
+): ScopedSheetApi {
+    return {
+        async getRows(): Promise<SheetRowWithIndex[]> {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+            return rows.map((row, index) => ({
+                rowIndex: index,
+                data: Object.fromEntries(
+                    sheet.headerValues.map((h) => [h, row.get(h) ?? ""])
+                ),
+            }));
+        },
+
+        async appendRow(data: SheetRow): Promise<SheetRowWithIndex> {
+            const sheet = await resolve();
+            const row = await sheet.addRow(data);
+            return {
+                rowIndex: row.rowNumber - 2, // 1-indexed; header is row 1
+                data: Object.fromEntries(
+                    sheet.headerValues.map((h) => [h, row.get(h) ?? ""])
+                ),
+            };
+        },
+
+        async updateRow(rowIndex: number, data: Partial<SheetRow>): Promise<SheetRowWithIndex> {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+
+            if (rowIndex < 0 || rowIndex >= rows.length) {
+                throw new Error(
+                    `Invalid rowIndex ${rowIndex}. Valid range: 0–${rows.length - 1}`
+                );
+            }
+
+            const row = rows[rowIndex];
+            for (const [key, value] of Object.entries(data)) {
+                row.set(key, value);
+            }
+            await row.save();
+
+            return {
+                rowIndex,
+                data: Object.fromEntries(
+                    sheet.headerValues.map((h) => [h, row.get(h) ?? ""])
+                ),
+            };
+        },
+
+        async deleteRow(rowIndex: number): Promise<void> {
+            const sheet = await resolve();
+            const rows = await sheet.getRows();
+
+            if (rowIndex < 0 || rowIndex >= rows.length) {
+                throw new Error(
+                    `Invalid rowIndex ${rowIndex}. Valid range: 0–${rows.length - 1}`
+                );
+            }
+
+            await rows[rowIndex].delete();
+        },
+    };
+}
+
+export function createGoogleSheetsApi(
+    credentials: GoogleSheetsCredentials,
+    spreadsheetId: string
+): GoogleSheetsApi {
+    const auth = new JWT({
+        email: credentials.clientEmail,
+        key: parsePrivateKey(credentials.privateKey),
+        scopes: [
+            "https://www.googleapis.com/auth/spreadsheets",
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    });
+
+    const doc = new GoogleSpreadsheet(spreadsheetId, auth);
+    let initialized = false;
+
+    const ensureInitialized = async () => {
+        if (!initialized) {
+            await doc.loadInfo();
+            initialized = true;
+        }
+    };
+
+    return {
+        async getInfo() {
+            await ensureInitialized();
+            return {
+                title: doc.title,
+                spreadsheetId,
+                sheetCount: doc.sheetCount,
+            };
+        },
+
+        sheet(title: string): ScopedSheetApi {
+            return createScopedSheetApi(doc, async () => {
+                await ensureInitialized();
+                const sheet = doc.sheetsByTitle[title];
+                if (!sheet) {
+                    throw new Error(
+                        `Sheet "${title}" not found. Available sheets: ${Object.keys(doc.sheetsByTitle).join(", ")}`
+                    );
+                }
+                return sheet;
+            });
+        },
+
+        sheetByIndex(index: number): ScopedSheetApi {
+            return createScopedSheetApi(doc, async () => {
+                await ensureInitialized();
+                const sheet = doc.sheetsByIndex[index];
+                if (!sheet) {
+                    throw new Error(
+                        `Sheet at index ${index} not found. Spreadsheet has ${doc.sheetCount} sheet(s).`
+                    );
+                }
+                return sheet;
+            });
+        },
+    };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+import { createGoogleSheetsApi } from "./GoogleSheetsClient";
+import { GoogleSheetsApi, GoogleSheetsPluginOptions } from "./types";
+
+export * from "./types";
+
+export function googleSheetsPlugin<TCtx>(options: GoogleSheetsPluginOptions<TCtx>) {
+    let api: GoogleSheetsApi | undefined;
+
+    return {
+        id: "googleSheets",
+        get ctx(): GoogleSheetsApi {
+            if (!api) {
+                throw new Error(
+                    "googleSheetsPlugin: plugin not yet initialized. " +
+                    "Ensure it is passed to FlinkApp before use."
+                );
+            }
+            return api;
+        },
+        init: async (app: { ctx: TCtx }) => {
+            let credentials = options.credentials;
+            let spreadsheetId = options.spreadsheetId;
+
+            if (options.loadCredentials) {
+                const loaded = await options.loadCredentials(app.ctx);
+                credentials = loaded.credentials;
+                if (loaded.spreadsheetId) {
+                    spreadsheetId = loaded.spreadsheetId;
+                }
+            }
+
+            if (!credentials) {
+                throw new Error(
+                    "googleSheetsPlugin: no credentials provided. " +
+                    "Supply `credentials` or `loadCredentials` in the plugin options."
+                );
+            }
+
+            if (!spreadsheetId) {
+                throw new Error(
+                    "googleSheetsPlugin: no spreadsheetId provided. " +
+                    "Supply `spreadsheetId` in the plugin options or return it from `loadCredentials`."
+                );
+            }
+
+            api = createGoogleSheetsApi(credentials, spreadsheetId);
+        },
+    };
+}

package/src/tools/GoogleSheetsTool.ts

@@ -0,0 +1,101 @@
+import { FlinkContext, FlinkTool, FlinkToolProps } from "@flink-app/flink";
+import { z } from "zod";
+import { GoogleSheetsPluginCtx } from "../types";
+
+const RowDataSchema = z.record(z.string(), z.string());
+
+const RowWithIndexSchema = z.object({
+    rowIndex: z.number(),
+    data: RowDataSchema,
+});
+
+export const Tool: FlinkToolProps = {
+    id: "google-sheets",
+    description:
+        "Read and write rows in a Google Sheets spreadsheet. " +
+        "Supports getRows, appendRow, updateRow, deleteRow, and getInfo operations. " +
+        "Rows are referenced by 0-based rowIndex. " +
+        "Data is a key-value map of column header to cell value.",
+    inputSchema: z.strictObject({
+        operation: z
+            .enum(["getRows", "appendRow", "updateRow", "deleteRow", "getInfo"])
+            .describe("Operation to perform"),
+        sheet: z
+            .string()
+            .optional()
+            .describe("Sheet title. Defaults to the first sheet when omitted."),
+        rowIndex: z
+            .number()
+            .optional()
+            .describe("0-based row index. Required for updateRow and deleteRow."),
+        data: RowDataSchema.optional().describe(
+            "Row data as column-header → value pairs. Required for appendRow and updateRow."
+        ),
+    }),
+    outputSchema: z.object({
+        rows: z.array(RowWithIndexSchema).optional(),
+        row: RowWithIndexSchema.optional(),
+        info: z
+            .object({
+                title: z.string(),
+                spreadsheetId: z.string(),
+                sheetCount: z.number(),
+            })
+            .optional(),
+    }),
+};
+
+type Input = z.infer<typeof Tool.inputSchema>;
+type Output = z.infer<typeof Tool.outputSchema>;
+
+const GoogleSheetsTool: FlinkTool<FlinkContext<GoogleSheetsPluginCtx>, Input, Output> = async ({
+    input,
+    ctx,
+}) => {
+    const api = ctx.plugins.googleSheets;
+    const sheetApi = input.sheet ? api.sheet(input.sheet) : api.sheetByIndex(0);
+
+    switch (input.operation) {
+        case "getInfo": {
+            const info = await api.getInfo();
+            return { success: true, data: { info } };
+        }
+
+        case "getRows": {
+            const rows = await sheetApi.getRows();
+            return { success: true, data: { rows } };
+        }
+
+        case "appendRow": {
+            if (!input.data) {
+                return { success: false, error: "`data` is required for appendRow" };
+            }
+            const row = await sheetApi.appendRow(input.data);
+            return { success: true, data: { row } };
+        }
+
+        case "updateRow": {
+            if (input.rowIndex === undefined) {
+                return { success: false, error: "`rowIndex` is required for updateRow" };
+            }
+            if (!input.data) {
+                return { success: false, error: "`data` is required for updateRow" };
+            }
+            const row = await sheetApi.updateRow(input.rowIndex, input.data);
+            return { success: true, data: { row } };
+        }
+
+        case "deleteRow": {
+            if (input.rowIndex === undefined) {
+                return { success: false, error: "`rowIndex` is required for deleteRow" };
+            }
+            await sheetApi.deleteRow(input.rowIndex);
+            return { success: true, data: {} };
+        }
+
+        default:
+            return { success: false, error: `Unknown operation: ${(input as Input).operation}` };
+    }
+};
+
+export default GoogleSheetsTool;

package/src/types.ts

@@ -0,0 +1,80 @@
+import { GoogleSpreadsheetRow } from "google-spreadsheet";
+
+// ─── Credentials ─────────────────────────────────────────────────────────────
+
+export interface GoogleSheetsCredentials {
+    /** Service account email (e.g. my-service@project.iam.gserviceaccount.com) */
+    clientEmail: string;
+    /**
+     * Private key in PEM format or base64-encoded service account JSON.
+     * Escaped newlines (\\n) are handled automatically.
+     */
+    privateKey: string;
+}
+
+// ─── Row types ────────────────────────────────────────────────────────────────
+
+/** A plain record of column header → cell value */
+export type SheetRow = Record<string, string>;
+
+/** A row with its 0-based position in the sheet */
+export interface SheetRowWithIndex {
+    rowIndex: number;
+    data: SheetRow;
+}
+
+// ─── Scoped sheet API ─────────────────────────────────────────────────────────
+
+export interface ScopedSheetApi {
+    /** Read all data rows from this sheet */
+    getRows(): Promise<SheetRowWithIndex[]>;
+    /** Append a new row. Returns the created row with its index. */
+    appendRow(data: SheetRow): Promise<SheetRowWithIndex>;
+    /** Update a row by 0-based rowIndex. Returns the updated row. */
+    updateRow(rowIndex: number, data: Partial<SheetRow>): Promise<SheetRowWithIndex>;
+    /** Delete a row by 0-based rowIndex. */
+    deleteRow(rowIndex: number): Promise<void>;
+}
+
+// ─── Top-level API ────────────────────────────────────────────────────────────
+
+export interface GoogleSheetsApi {
+    /** Get spreadsheet metadata */
+    getInfo(): Promise<{ title: string; spreadsheetId: string; sheetCount: number }>;
+    /** Return a scoped API bound to a specific sheet by title */
+    sheet(title: string): ScopedSheetApi;
+    /** Return a scoped API bound to a sheet by 0-based index */
+    sheetByIndex(index: number): ScopedSheetApi;
+}
+
+// ─── Plugin options ───────────────────────────────────────────────────────────
+
+export interface GoogleSheetsPluginOptions<TCtx = unknown> {
+    /**
+     * Target spreadsheet ID (the long ID from the Google Sheets URL).
+     * Can be omitted if `loadCredentials` resolves it dynamically.
+     */
+    spreadsheetId?: string;
+
+    /**
+     * Static service account credentials.
+     * Use `loadCredentials` instead when credentials come from the database or
+     * secrets manager.
+     */
+    credentials?: GoogleSheetsCredentials;
+
+    /**
+     * Dynamically load credentials (and optionally spreadsheetId) from the app
+     * context at startup. Takes priority over static `credentials`.
+     */
+    loadCredentials?: (ctx: TCtx) => Promise<{
+        credentials: GoogleSheetsCredentials;
+        spreadsheetId?: string;
+    }>;
+}
+
+// ─── Context extension ────────────────────────────────────────────────────────
+
+export interface GoogleSheetsPluginCtx {
+    googleSheets: GoogleSheetsApi;
+}

package/tsconfig.dist.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig",
+  "exclude": []
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "lib": ["esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "checkJs": false,
+    "outDir": "dist",
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["./node_modules/*"]
+}