Integ Docs

Appearance

@happ-integ/google-sheets ​

Клиент для записи строк в Google Sheets через сервисный аккаунт.

Реализован на fetch + Web Crypto (RS256 JWT bearer flow), без пакета googleapis — тот тянет google-auth-library, которая использует Node-модули (http/https/net/stream) и не собирается esbuild'ом под Cloudflare Workers (platform: "browser"). Эта реализация полностью совместима с Workers.

Установка ​

bash
pnpm add @happ-integ/google-sheets

Использование ​

Инициализация ​

typescript
import { GoogleSheetsClient } from "@happ-integ/google-sheets";

const sheets = new GoogleSheetsClient({
	credentials: {
		client_email: secrets.GOOGLE_SHEETS_CLIENT_EMAIL,
		private_key: secrets.GOOGLE_SHEETS_PRIVATE_KEY,
	},
	scopes: ["https://www.googleapis.com/auth/spreadsheets"], // опционально
});

Запись строки ​

typescript
await sheets.appendRow({
	spreadsheetId: "1AbC...xyz",
	sheetName: "Дзвінки",
	values: ["2026-07-23 12:00", "+380991234567", "вхідна лінія", "", "Тема", "Суть", "Додатково", "Статус"],
});

Health Check ​

typescript
const isHealthy = await sheets.healthCheck("1AbC...xyz");

API ​

GoogleSheetsClient ​

typescript
new GoogleSheetsClient(config: IGoogleSheetsConfig)

Config:

typescript
{
  credentials: {
    client_email: string;
    private_key: string;   // "\n" внутри строки допустимы, нормализуются автоматически
    project_id?: string;
  };
  scopes?: string[];
}

Методы ​

appendRow({ spreadsheetId, sheetName, values }): Promise<IAppendRowResult> ​

Добавляет строку в конец листа (sheetName). Значения пишутся в том порядке, в котором переданы в values.

healthCheck(spreadsheetId): Promise<boolean> ​

Проверка доступа к таблице.

Google Service Account ​

  1. https://console.cloud.google.com/iam-admin/serviceaccounts
  2. Create Service Account
  3. Create Key (JSON)
  4. Enable Google Sheets API
  5. Открыть доступ сервисному аккаунту к таблице (Share → email сервисного аккаунта, роль Editor)
  6. Добавить client_email / private_key в credentials интеграции (см. docs/SECRETS.md — хранится как per-integration secret в D1, не в KV, т.к. это чувствительные данные)

Когда использовать ​

  • ✅ Запись строк в Google Sheets (логи, отчёты, экспорт)
  • ❌ Чтение/парсинг сложных таблиц — используйте @happ-integ/google-drive (downloadSpreadsheet)