npm - googleformsubmitter - Versions diffs - 1.0.0 - Mend

googleformsubmitter 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/.data/form-cache-1FAIpQLSc1aiEAhxWCMSNjZ1asGDtXV_mT8vTiJRquiqfdjsoMkKT9tw.json +16 -0
package/.env.example +4 -0
package/CLAUDE.md +106 -0
package/GoogleFormSubmitter.ts +319 -0
package/README.md +115 -0
package/bun.lock +328 -0
package/create-form.ts +410 -0
package/index.ts +2 -0
package/package.json +26 -0
package/test.ts +139 -0
package/tsconfig.json +30 -0
package/types.ts +18 -0

package/.data/form-cache-1FAIpQLSc1aiEAhxWCMSNjZ1asGDtXV_mT8vTiJRquiqfdjsoMkKT9tw.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "requestId": "1876174487",
+  "fullName": "1192130047",
+  "birthDate": "1354328376",
+  "grade": "1867801269",
+  "location": "1504377681",
+  "rate": "282114114",
+  "nds": "1347448341",
+  "exitDate": "1161802420",
+  "vacation": "1977793041",
+  "inStaff": "447126466",
+  "cvFile": "1595274093",
+  "company": "553187985",
+  "checklist": "1954006978",
+  "comment": "998553124"
+}

package/.env.example ADDED Viewed

@@ -0,0 +1,4 @@
+# Google Form Submitter Configuration
+# CDP Web Socket endpoint for connecting to the Lightpanda browser engine
+LIGHTPANDA_CDP_URL=ws://127.0.0.1:9222/

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,106 @@
+Default to using Bun instead of Node.js.
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+## APIs
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+## Testing
+Use `bun test` to run tests.
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+## Frontend
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+Server:
+```ts#index.ts
+import index from "./index.html"
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+With the following `frontend.tsx`:
+```tsx#frontend.tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+// import .css files directly and it works
+import './index.css';
+const root = createRoot(document.body);
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+root.render(<Frontend />);
+```
+Then, run index.ts
+```sh
+bun --hot ./index.ts
+```
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/GoogleFormSubmitter.ts ADDED Viewed

@@ -0,0 +1,319 @@
+import { chromium } from 'playwright';
+import Ajv from 'ajv';
+import fs from 'fs/promises';
+import path from 'path';
+import type { FormSchemaMapping, SubmissionResult } from './types';
+const ajv = new Ajv({ allErrors: true });
+export class GoogleFormSubmitter {
+  private formUrl: string;
+  private jsonSchema: Record<string, any>;
+  private mappingSchema: FormSchemaMapping;
+  private cdpUrl: string;
+  private cacheFilePath: string;
+  private entryIdCache: Record<string, string> | null = null;
+  private validateFn: ReturnType<typeof ajv.compile>;
+  private cookies?: Array<any>;
+  constructor(options: {
+    formUrl: string;
+    jsonSchema: Record<string, any>;
+    mappingSchema: FormSchemaMapping;
+    cdpUrl?: string;
+    cacheDir?: string;
+    cookies?: Array<any>;
+  }) {
+    this.formUrl = options.formUrl;
+    this.jsonSchema = options.jsonSchema;
+    this.mappingSchema = options.mappingSchema;
+    this.cdpUrl = options.cdpUrl || 'ws://127.0.0.1:9222/';
+    this.cookies = options.cookies;
+    // Compile JSON Schema validation function
+    this.validateFn = ajv.compile(this.jsonSchema);
+    // Compute a hash or safe name for the cache file based on the form URL
+    const formIdMatch = this.formUrl.match(/\/d\/e\/([a-zA-Z0-9_-]+)/) || this.formUrl.match(/\/d\/([a-zA-Z0-9_-]+)/);
+    const formHash = formIdMatch ? formIdMatch[1] : Buffer.from(this.formUrl).toString('base64').substring(0, 16);
+    const cacheDir = options.cacheDir || path.join(process.cwd(), '.data');
+    this.cacheFilePath = path.join(cacheDir, `form-cache-${formHash}.json`);
+  }
+  /**
+   * Lazily loads and returns the resolved entryId mapping cache.
+   * If cache file exists, reads it. Otherwise, launches Lightpanda CDP,
+   * scans the DOM, caches it, and closes the browser.
+   */
+  private async getOrResolveEntryIds(): Promise<Record<string, string>> {
+    if (this.entryIdCache) {
+      return this.entryIdCache;
+    }
+    // 1. Try reading from cache file
+    try {
+      const content = await fs.readFile(this.cacheFilePath, 'utf-8');
+      this.entryIdCache = JSON.parse(content);
+      console.log(`[GoogleFormSubmitter] Loaded entry ID mapping cache from: ${this.cacheFilePath}`);
+      return this.entryIdCache!;
+    } catch {
+      // Cache file doesn't exist, proceed to resolve
+      console.log(`[GoogleFormSubmitter] Cache not found. Resolving entry IDs dynamically via Lightpanda...`);
+    }
+    // 2. Launch browser to inspect DOM
+    let browser;
+    let context;
+    try {
+      console.log(`[GoogleFormSubmitter] Connecting to CDP server at ${this.cdpUrl}...`);
+      browser = await chromium.connectOverCDP(this.cdpUrl, { timeout: 5000 });
+      context = await browser.newContext();
+    } catch (e: any) {
+      console.warn(`[GoogleFormSubmitter] CDP connection to Lightpanda failed: ${e.message}. Falling back to native headless Chromium...`);
+      browser = await chromium.launch({ headless: true });
+      context = await browser.newContext();
+    }
+    if (this.cookies && this.cookies.length > 0) {
+      await context.addCookies(this.cookies);
+      console.log(`[GoogleFormSubmitter] Injected ${this.cookies.length} cookies into browser context.`);
+    }
+    const page = await context.newPage();
+    try {
+      await page.goto(this.formUrl);
+      // Wait for fields to load
+      await page.locator('.Qr7Oae').first().waitFor({ state: 'attached', timeout: 15000 });
+      // Scan DOM for question containers
+      const domMappings = await page.evaluate(() => {
+        const result: Record<string, string> = {};
+        const containers = document.querySelectorAll('.Qr7Oae');
+        containers.forEach((container: any) => {
+          const headerEl = container.querySelector('[role="heading"], .M7eMe, .HoRgec');
+          if (!headerEl) return;
+          let labelText = (headerEl.textContent || '').trim();
+          // Remove trailing required asterisks and clean up whitespace
+          labelText = labelText.replace(/\s*\*$/, '').trim();
+          let entryId: string | null = null;
+          // Strategy A: Find hidden or text inputs with name entry.XXXX
+          const inputs = container.querySelectorAll('input[name^="entry."], textarea[name^="entry."]');
+          for (const input of inputs) {
+            const nameAttr = input.getAttribute('name');
+            if (nameAttr && nameAttr.startsWith('entry.')) {
+              entryId = nameAttr.replace('entry.', '').replace('_sentinel', '');
+              break;
+            }
+          }
+          // Strategy B: Parse from data-params if Strategy A fails
+          if (!entryId) {
+            let dataParams = container.getAttribute('data-params') || '';
+            if (!dataParams) {
+              const el = container.querySelector('[data-params]');
+              if (el) {
+                dataParams = el.getAttribute('data-params') || '';
+              }
+            }
+            if (dataParams) {
+              const match = dataParams.match(/\[\[(\d+)/);
+              if (match && match[1]) {
+                entryId = match[1];
+              }
+            }
+          }
+          if (labelText && entryId) {
+            result[labelText] = entryId;
+          }
+        });
+        return result;
+      });
+      // 3. Map mappingSchema properties to resolved entry IDs
+      const resolvedCache: Record<string, string> = {};
+      for (const [propName, fieldMapping] of Object.entries(this.mappingSchema)) {
+        // Try finding a match in the scraped titles
+        let matchedEntryId: string | undefined = undefined;
+        // Try exact match first
+        matchedEntryId = domMappings[fieldMapping.label];
+        // Try substring match as fallback
+        if (!matchedEntryId) {
+          const lowerLabel = fieldMapping.label.toLowerCase();
+          const scrapedTitle = Object.keys(domMappings).find(
+            (t) => t.toLowerCase().includes(lowerLabel) || lowerLabel.includes(t.toLowerCase())
+          );
+          if (scrapedTitle) {
+            matchedEntryId = domMappings[scrapedTitle];
+          }
+        }
+        if (matchedEntryId) {
+          resolvedCache[propName] = matchedEntryId;
+        } else {
+          console.warn(`[GoogleFormSubmitter] Warning: Could not resolve entryId for field "${propName}" (label: "${fieldMapping.label}")`);
+        }
+      }
+      // Save to cache file
+      await fs.mkdir(path.dirname(this.cacheFilePath), { recursive: true });
+      await fs.writeFile(this.cacheFilePath, JSON.stringify(resolvedCache, null, 2));
+      console.log(`[GoogleFormSubmitter] Saved resolved entry IDs cache to: ${this.cacheFilePath}`);
+      this.entryIdCache = resolvedCache;
+      return resolvedCache;
+    } finally {
+      await context.close();
+      await browser.close();
+    }
+  }
+  /**
+   * Validates input data and submits the form via direct HTTP POST.
+   */
+  public async submit(data: unknown): Promise<SubmissionResult> {
+    // 1. Validate data against JSON Schema
+    const isValid = this.validateFn(data);
+    if (!isValid) {
+      const errorMsg = this.validateFn.errors
+        ?.map((err) => `${err.instancePath} ${err.message}`)
+        .join(', ');
+      throw new Error(`Validation failed: ${errorMsg}`);
+    }
+    const typedData = data as Record<string, any>;
+    // 2. Get entryId mapping cache (resolves lazily if needed)
+    const entryIds = await this.getOrResolveEntryIds();
+    const fieldsMap: Record<string, string[]> = {};
+    const fieldsSubmitted: Record<string, string> = {};
+    for (const [propName, value] of Object.entries(typedData)) {
+      const entryId = entryIds[propName];
+      if (!entryId) {
+        continue;
+      }
+      const fieldMapping = this.mappingSchema[propName];
+      if (!fieldMapping) {
+        continue;
+      }
+      if (!fieldsMap[entryId]) {
+        fieldsMap[entryId] = [];
+      }
+      const currentList = fieldsMap[entryId];
+      if (fieldMapping.type === 'file') {
+        if (value && typeof value === 'object' && 'fileId' in value) {
+          const filePayload = [[[value.fileId, value.filename, value.mimeType]]];
+          const serialized = JSON.stringify(filePayload);
+          currentList?.push(serialized);
+          fieldsSubmitted[fieldMapping.label] = serialized;
+        }
+      } else if (fieldMapping.type === 'choice' && fieldMapping.allowOther && value) {
+        const isPredefined = fieldMapping.options?.choices?.includes(value);
+        if (isPredefined === false) {
+          currentList?.push('__other_option__');
+          const otherResponseKey = `${entryId}.other_option_response`;
+          let otherResponseList = fieldsMap[otherResponseKey];
+          if (!otherResponseList) {
+            otherResponseList = [];
+            fieldsMap[otherResponseKey] = otherResponseList;
+          }
+          otherResponseList.push(value);
+          fieldsSubmitted[fieldMapping.label] = `__other_option__ (${value})`;
+        } else {
+          currentList?.push(value);
+          fieldsSubmitted[fieldMapping.label] = value;
+        }
+      } else {
+        currentList?.push(String(value));
+        fieldsSubmitted[fieldMapping.label] = String(value);
+      }
+    }
+    // 4. Send direct HTTP POST inside the browser context to preserve cookies and hidden fields
+    let browser;
+    let context;
+    try {
+      browser = await chromium.connectOverCDP(this.cdpUrl, { timeout: 5000 });
+      context = await browser.newContext();
+    } catch {
+      browser = await chromium.launch({ headless: true });
+      context = await browser.newContext();
+    }
+    if (this.cookies && this.cookies.length > 0) {
+      await context.addCookies(this.cookies);
+    }
+    const page = await context.newPage();
+    try {
+      await page.goto(this.formUrl);
+      await page.locator('.Qr7Oae').first().waitFor({ state: 'attached', timeout: 15000 });
+      console.log(`[GoogleFormSubmitter] Sending HTTP POST request in page context...`);
+      const responseInfo = await page.evaluate(async ({ fieldsMap }) => {
+        const g = globalThis as any;
+        const form = g.document.querySelector('form');
+        if (!form) throw new Error('Could not find form element on page');
+        const searchParams = new URLSearchParams();
+        const formData = new g.FormData(form);
+        for (const [key, val] of formData.entries()) {
+          if (!key.startsWith('entry.')) {
+            searchParams.append(key, String(val));
+          }
+        }
+        for (const [entryId, values] of Object.entries(fieldsMap)) {
+          for (const val of values as string[]) {
+            searchParams.append(`entry.${entryId}`, val);
+          }
+        }
+        const actionUrl = form.action || g.location.href.replace('/viewform', '/formResponse');
+        const res = await g.fetch(actionUrl, {
+          method: 'POST',
+          body: searchParams,
+          headers: {
+            'Content-Type': 'application/x-www-form-urlencoded'
+          }
+        });
+        return {
+          status: res.status,
+          text: await res.text()
+        };
+      }, { fieldsMap });
+      const isSuccess = responseInfo.status === 200 || responseInfo.text.includes('v-confirmation-msg') || responseInfo.text.toLowerCase().includes('confirmation');
+      return {
+        success: isSuccess,
+        statusCode: responseInfo.status,
+        message: isSuccess ? 'Form submitted successfully!' : 'Google Form rejected submission.',
+        fieldsSubmitted,
+      };
+    } finally {
+      await context.close();
+      await browser.close();
+    }
+  }
+}

package/README.md ADDED Viewed

@@ -0,0 +1,115 @@
+# Google Form Submitter
+Пакет для строго типизированной, валидируемой и кэшируемой отправки данных во внешние (в том числе сторонние) Google Формы с использованием Lightpanda (CDP-соединение) или стандартного Chromium.
+## 🚀 Возможности
+1. **Строгая валидация (JSON Schema)**: Входные данные проверяются через стандартную JSON схему с использованием библиотеки `Ajv` перед любой сетевой отправкой.
+2. **Декларативное описание полей**: Позволяет сопоставлять программные свойства (например, `fullName`, `exitDate`) с русскими заголовками вопросов в Google Форме.
+3. **Ленивый парсинг DOM (Lazy Loading)**: При первой отправке модуль автоматически открывает форму в безголовом браузере, сканирует структуру вопросов, находит соответствующие им бэкенд `entryId` и сохраняет карту соответствий в локальный кэш-файл.
+4. **Сверхбыстрые повторные отправки**: После наполнения кэша последующие отправки выполняются мгновенно через прямой HTTP POST-запрос, эмулируя отправку формы без запуска графического браузера.
+5. **Авторизация (Куки)**: Поддерживает инжекцию файлов куки для прохождения авторизации в формах, требующих аккаунт Google (например, если в форме есть поле загрузки файла).
+6. **Поддержка опции «Другое»**: Автоматически распознает кастомные текстовые ответы для радио-кнопок/чекбоксов с выбором «Другое» и правильно их кодирует.
+---
+## 🛠️ Установка и Запуск
+Перейдите в каталог `googleformsubmitter` и установите зависимости:
+```bash
+cd googleformsubmitter
+bun install
+```
+### Доступные скрипты:
+* **Запуск тестов**:
+  ```bash
+  bun run test
+  ```
+* **Проверка типов (tsgo)**:
+  ```bash
+  bun run validate
+  ```
+* **Линтинг (oxlint)**:
+  ```bash
+  bun run lint
+  ```
+* **Создание тестовой Google Формы**:
+  ```bash
+  bun run create-form
+  ```
+---
+## 📋 Описание Схемы данных
+Отправка настраивается с помощью двух схем:
+1. **JSON Schema** — описывает типы данных, ограничения, обязательность и формат (например, регулярные выражения для дат).
+2. **Mapping Schema** — описывает связь между ключом в JSON схеме и человекочитаемым заголовком вопроса в Google Форме.
+### Пример декларативной конфигурации:
+```typescript
+import { GoogleFormSubmitter } from './GoogleFormSubmitter';
+// 1. Описание типов данных формы (JSON Schema)
+const jsonSchema = {
+  type: 'object',
+  properties: {
+    fullName: { type: 'string' },
+    birthDate: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' },
+    inStaff: { type: 'string' },
+    cvFile: {
+      type: 'object',
+      properties: {
+        fileId: { type: 'string' },
+        filename: { type: 'string' },
+        mimeType: { type: 'string' }
+      },
+      required: ['fileId', 'filename', 'mimeType']
+    }
+  },
+  required: ['fullName', 'birthDate', 'inStaff', 'cvFile']
+};
+// 2. Декларативный маппинг полей на заголовки вопросов в Google Форме
+const mappingSchema = {
+  fullName: { label: 'ФИО (полностью)', type: 'text' },
+  birthDate: { label: 'Дата рождения', type: 'date' },
+  inStaff: { label: 'Находится ли специалист в штате?', type: 'choice', options: { choices: ['Да'], allowOther: true } },
+  cvFile: { label: 'CV (файл)', type: 'file' }
+};
+// 3. Инициализация сабмиттера
+const submitter = new GoogleFormSubmitter({
+  formUrl: 'https://docs.google.com/forms/d/e/.../viewform',
+  jsonSchema,
+  mappingSchema,
+  cdpUrl: 'ws://127.0.0.1:9222/', // CDP-сервер Lightpanda
+  cookies: loadedCookies          // Сессионные куки (необязательно)
+});
+// 4. Отправка данных
+const result = await submitter.submit({
+  fullName: 'Иванов Иван',
+  birthDate: '1990-01-01',
+  inStaff: 'С рынка, на предоффере', // Будет передано в "Другое"
+  cvFile: {
+    fileId: '1BRVwwPlohb_4g7DUZ3HTz...',
+    filename: 'resume.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  }
+});
+```
+---
+## 📂 Структура каталогов проекта
+* `GoogleFormSubmitter.ts` — основной класс управления, парсинга DOM и сетевых запросов.
+* `create-form.ts` — скрипт автоматического создания тестовой Google-формы со всеми необходимыми типами полей (включая текстовые, списки, даты, переключатели) через официальный Google Forms API.
+* `test.ts` — интеграционный тест, эмулирующий первую отправку (с динамическим парсингом) и повторную отправку (из кэша).
+* `types.ts` — TypeScript-интерфейсы и типы данных.
+* `.data/` — каталог для хранения временных кэшей сопоставлений entryId (`form-cache-*.json`).
+* `.env.example` — шаблон конфигурационного файла.