@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 → 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

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.

// 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:

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.

import GoogleSheetsTool, { Tool } from "@flink-app/google-sheets-plugin/tools/GoogleSheetsTool";

class MyAgent extends FlinkAgent<AppCtx> {
    tools = [{ ...Tool, handler: GoogleSheetsTool }];
}