@ez-gform/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webadeva
+
+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,70 @@
+# @ez-gform/core
+
+Read a Google Form's questions and submit answers to it, from any JavaScript.
+No dependencies. Works in Node 20+ and browsers.
+
+Using React? You want [`@ez-gform/react`](../react) instead.
+
+## Install
+
+```sh
+pnpm add @ez-gform/core
+```
+
+## Usage
+
+```ts
+import { parseFormHtml, submitForm } from "@ez-gform/core";
+
+// 1. Turn a public form's /viewform HTML into a typed schema.
+const schema = parseFormHtml(html);
+
+// 2. Submit answers, keyed by entry id.
+const result = await submitForm(
+  schema.formId,
+  { "entry.123": "hello" },
+  { schema },
+);
+```
+
+`result.status` is:
+
+- `"sent"` by default. The request is `no-cors` (browsers require it), so you
+  can't know whether Google accepted it.
+- `"ok"` or `"error"` if you pass `mode: "cors"`. Only works outside the
+  browser (Node), where the response is readable.
+
+## Value shapes
+
+What to pass for each kind of question:
+
+| Question                  | Value                                            |
+| ------------------------- | ------------------------------------------------ |
+| Short answer, paragraph   | `"text"`                                         |
+| Multiple choice, dropdown | `"Option text"` (must match exactly)             |
+| Checkboxes                | `["Option A", "Option B"]`                       |
+| "Other" option            | `{ other: "my text" }`                           |
+| Linear scale              | `4`                                              |
+| Date                      | `{ year, month, day }` (`year` is optional)      |
+| Date with time            | `{ year, month, day, hour, minute }`             |
+| Time                      | `{ hour, minute }`                               |
+| Grid                      | `{ "entry.<rowId>": "Column" }`, one key per row |
+| Checkbox grid             | `{ "entry.<rowId>": ["Col A", "Col B"] }`        |
+
+Empty strings, `null` and `undefined` are skipped.
+
+Each grid row has its own entry id. Pass rows nested under the grid question's
+id (`{ "entry.1": { "entry.10": "Agree" } }`) or flat
+(`{ "entry.10": "Agree" }`); both work.
+
+## Other exports
+
+| Export                                   | What it does                                          |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `validateValues(values, schema)`         | Finds unknown entry ids and missing required answers. |
+| `encodeValues(values, schema)`           | Answers → `URLSearchParams`, without submitting.      |
+| `buildSubmitBody`                        | The exact POST body `submitForm` sends.               |
+| `buildPrefillUrl`                        | A link to the form prefilled with your values.        |
+| `normalizeFormId`, `formUrls`            | Accept any form URL or id; get its endpoints.         |
+| `parseFormData`, `extractPublicLoadData` | Lower-level parsing steps behind `parseFormHtml`.     |
+| `ParseError`, `ValidationError`          | Error classes.                                        |

package/dist/index.cjs

@@ -0,0 +1,577 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ParseError: () => ParseError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  buildPrefillUrl: () => buildPrefillUrl,
+  buildSubmitBody: () => buildSubmitBody,
+  encodeValues: () => encodeValues,
+  extractPublicLoadData: () => extractPublicLoadData,
+  formUrls: () => formUrls,
+  normalizeFormId: () => normalizeFormId,
+  parseFormData: () => parseFormData,
+  parseFormHtml: () => parseFormHtml,
+  submitForm: () => submitForm,
+  validateValues: () => validateValues
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/encode.ts
+var OTHER_SENTINEL = "__other_option__";
+var isOtherValue = (v) => {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && "other" in v;
+};
+var isDateValue = (v) => {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && "day" in v && "month" in v;
+};
+var isTimeValue = (v) => {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && "hour" in v && "minute" in v && !("day" in v);
+};
+var pad2 = (n) => {
+  return String(n).padStart(2, "0");
+};
+var appendScalar = (params, key, value) => {
+  if (value === void 0 || value === null) return;
+  const str = String(value);
+  if (str.length === 0) return;
+  params.append(key, str);
+};
+var appendChoiceItem = (params, entryId, item) => {
+  if (isOtherValue(item)) {
+    params.append(entryId, OTHER_SENTINEL);
+    appendScalar(params, `${entryId}.other_option_response`, item.other);
+  } else {
+    appendScalar(params, entryId, item);
+  }
+};
+var appendGridMap = (params, gridMap) => {
+  for (const [rowEntryId, colValue] of Object.entries(gridMap)) {
+    if (Array.isArray(colValue)) {
+      for (const v of colValue) appendScalar(params, rowEntryId, v);
+    } else {
+      appendScalar(params, rowEntryId, colValue);
+    }
+  }
+};
+var encodeValues = (values, _) => {
+  const params = new URLSearchParams();
+  for (const [entryId, rawValue] of Object.entries(values)) {
+    encodeOne(params, entryId, rawValue);
+  }
+  return params;
+};
+var encodeOne = (params, entryId, value) => {
+  if (value === null || value === void 0) return;
+  if (Array.isArray(value)) {
+    for (const item of value) appendChoiceItem(params, entryId, item);
+    return;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    appendScalar(params, entryId, value);
+    return;
+  }
+  if (isOtherValue(value)) {
+    appendChoiceItem(params, entryId, value);
+    return;
+  }
+  if (isDateValue(value)) {
+    if (value.year !== void 0)
+      appendScalar(params, `${entryId}_year`, value.year);
+    appendScalar(params, `${entryId}_month`, value.month);
+    appendScalar(params, `${entryId}_day`, value.day);
+    if (value.hour !== void 0)
+      appendScalar(params, `${entryId}_hour`, pad2(value.hour));
+    if (value.minute !== void 0)
+      appendScalar(params, `${entryId}_minute`, pad2(value.minute));
+    return;
+  }
+  if (isTimeValue(value)) {
+    appendScalar(params, `${entryId}_hour`, pad2(value.hour));
+    appendScalar(params, `${entryId}_minute`, pad2(value.minute));
+    return;
+  }
+  appendGridMap(params, value);
+};
+var validateValues = (values, schema) => {
+  const errors = [];
+  const knownEntryIds = /* @__PURE__ */ new Set();
+  for (const q of schema.questions) {
+    knownEntryIds.add(q.entryId);
+    for (const row of q.rows ?? []) knownEntryIds.add(row.entryId);
+  }
+  for (const key of Object.keys(values)) {
+    if (!knownEntryIds.has(key)) {
+      errors.push({
+        entryId: key,
+        message: `Unknown entry id "${key}" is not present in the form schema`
+      });
+    }
+  }
+  for (const q of schema.questions) {
+    if (!q.required) continue;
+    const idsToCheck = q.rows && q.rows.length > 0 ? q.rows.map((r) => {
+      return r.entryId;
+    }) : [q.entryId];
+    for (const id of idsToCheck) {
+      const v = values[id];
+      const isEmpty = v === void 0 || v === null || v === "" || Array.isArray(v) && v.length === 0 || typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0;
+      if (isEmpty) {
+        errors.push({
+          entryId: id,
+          message: `Missing required answer for question "${q.title}" (${id})`
+        });
+      }
+    }
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+};
+
+// src/errors.ts
+var ParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ParseError";
+  }
+};
+var ValidationError = class extends Error {
+  errors;
+  constructor(message, errors) {
+    super(message);
+    this.name = "ValidationError";
+    this.errors = errors;
+  }
+};
+
+// src/extract.ts
+var ASSIGNMENT_MARKER = "FB_PUBLIC_LOAD_DATA_";
+var extractPublicLoadData = (html) => {
+  const markerIndex = html.indexOf(ASSIGNMENT_MARKER);
+  if (markerIndex === -1) {
+    throw new ParseError(
+      "extractPublicLoadData: FB_PUBLIC_LOAD_DATA_ not found in HTML"
+    );
+  }
+  const equalsIndex = html.indexOf("=", markerIndex);
+  if (equalsIndex === -1) {
+    throw new ParseError(
+      "extractPublicLoadData: malformed FB_PUBLIC_LOAD_DATA_ assignment"
+    );
+  }
+  let start = equalsIndex + 1;
+  while (start < html.length && /\s/.test(html[start])) {
+    start++;
+  }
+  if (html[start] !== "[") {
+    throw new ParseError(
+      "extractPublicLoadData: expected array literal after FB_PUBLIC_LOAD_DATA_ ="
+    );
+  }
+  const end = findMatchingBracketEnd(html, start);
+  const literal = html.slice(start, end + 1);
+  try {
+    return JSON.parse(literal);
+  } catch (cause) {
+    throw new ParseError(
+      `extractPublicLoadData: failed to JSON.parse the extracted FB_PUBLIC_LOAD_DATA_ literal: ${cause instanceof Error ? cause.message : String(cause)}`
+    );
+  }
+};
+var findMatchingBracketEnd = (text, startIndex) => {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = startIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === "[") {
+      depth++;
+    } else if (ch === "]") {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  throw new ParseError(
+    "extractPublicLoadData: unterminated array literal (no matching closing bracket)"
+  );
+};
+var extractFbzx = (html) => {
+  const match = /name="fbzx"\s+value="([^"]*)"/.exec(html);
+  return match?.[1];
+};
+
+// src/parse.ts
+var asArray = (value, context) => {
+  if (!Array.isArray(value)) {
+    throw new ParseError(
+      `parseFormData: expected an array at ${context}, got ${typeof value}`
+    );
+  }
+  return value;
+};
+var optionalString = (value) => {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+var toEntryId = (rawId) => {
+  return `entry.${String(rawId)}`;
+};
+var mapOptions = (rawOptions) => {
+  if (!Array.isArray(rawOptions)) return void 0;
+  return rawOptions.map((tuple) => {
+    const t = Array.isArray(tuple) ? tuple : [];
+    const value = typeof t[0] === "string" ? t[0] : "";
+    const isOther = t[4] === 1;
+    return { value, isOther };
+  });
+};
+var parseSubQuestions = (rawSubs) => {
+  const subs = asArray(rawSubs, "question[4]");
+  return subs.map((rawSub) => {
+    const s = asArray(rawSub, "question[4][i]");
+    return {
+      entryId: s[0],
+      options: s[1],
+      required: s[2],
+      extra: s[3],
+      rest: s
+    };
+  });
+};
+var TYPE_CODE_NAME = {
+  0: "short_answer",
+  1: "paragraph",
+  2: "multiple_choice",
+  3: "dropdown",
+  4: "checkboxes",
+  5: "linear_scale",
+  6: "section_header",
+  7: "grid",
+  // resolved to "grid" | "checkbox_grid" below
+  8: "page_break",
+  9: "date",
+  10: "time",
+  11: "image",
+  12: "video",
+  13: "file_upload",
+  // ponytail: rating (stars/hearts) has the same wire shape as a linear scale
+  // (options "1".."N", submits entry.N=<number>), so it reuses that type. Add a
+  // "rating" QuestionType if consumers need to render the icon.
+  18: "linear_scale"
+};
+var parseFormData = (data, opts = {}) => {
+  if (!Array.isArray(data)) {
+    throw new ParseError(
+      "parseFormData: expected the top-level FB_PUBLIC_LOAD_DATA_ value to be an array"
+    );
+  }
+  const container = data[1];
+  if (!Array.isArray(container)) {
+    throw new ParseError(
+      "parseFormData: expected data[1] (main container) to be an array"
+    );
+  }
+  const description = optionalString(container[0]);
+  const rawQuestions = container[1];
+  if (!Array.isArray(rawQuestions)) {
+    throw new ParseError(
+      "parseFormData: expected data[1][1] (question list) to be an array"
+    );
+  }
+  const container8 = container[8];
+  const wrappedTitle = typeof container8 === "string" ? container8 : Array.isArray(container8) ? container8[1] : void 0;
+  const title = typeof wrappedTitle === "string" ? wrappedTitle : typeof data[3] === "string" ? data[3] : "";
+  let { formId } = opts;
+  if (!formId) {
+    const rawFormId = data[14];
+    if (typeof rawFormId === "string") {
+      formId = rawFormId.startsWith("e/") ? rawFormId.slice(2) : rawFormId;
+    } else {
+      formId = "";
+    }
+  }
+  const questions = [];
+  const sections = [{ title, description, questionIds: [] }];
+  let sawPageBreak = false;
+  for (const rawEntry of rawQuestions) {
+    const entry = asArray(rawEntry, "question entry");
+    const id = entry[0];
+    const entryTitle = typeof entry[1] === "string" ? entry[1] : "";
+    const entryDescription = optionalString(entry[2]);
+    const typeCode = entry[3];
+    if (typeof typeCode !== "number") {
+      throw new ParseError(
+        `parseFormData: question ${String(id)} has a non-numeric type code`
+      );
+    }
+    const kind = TYPE_CODE_NAME[typeCode];
+    if (kind === void 0) {
+      throw new ParseError(
+        `parseFormData: unknown question type code ${typeCode} for question ${String(id)}`
+      );
+    }
+    if (kind === "image" || kind === "video") {
+      continue;
+    }
+    if (kind === "section_header") {
+      const current = sections[sections.length - 1];
+      current.title = entryTitle;
+      current.description = entryDescription;
+      continue;
+    }
+    if (kind === "page_break") {
+      sawPageBreak = true;
+      sections.push({
+        title: entryTitle,
+        description: entryDescription,
+        questionIds: []
+      });
+      continue;
+    }
+    const subs = parseSubQuestions(entry[4]);
+    if (subs.length === 0) {
+      throw new ParseError(
+        `parseFormData: question ${String(id)} (type ${typeCode}) has no sub-question entries`
+      );
+    }
+    const firstSub = subs[0];
+    const question = {
+      id: String(id),
+      entryId: toEntryId(firstSub.entryId),
+      title: entryTitle,
+      description: entryDescription,
+      type: kind,
+      required: firstSub.required === 1
+    };
+    switch (kind) {
+      case "multiple_choice":
+      case "dropdown":
+      case "checkboxes": {
+        question.options = mapOptions(firstSub.options);
+        break;
+      }
+      case "linear_scale": {
+        const options = mapOptions(firstSub.options) ?? [];
+        const first = options[0]?.value;
+        const last = options[options.length - 1]?.value;
+        const min = first !== void 0 ? Number(first) : Number.NaN;
+        const max = last !== void 0 ? Number(last) : Number.NaN;
+        const labels = Array.isArray(firstSub.extra) ? firstSub.extra : [];
+        question.scale = {
+          min,
+          max,
+          lowLabel: optionalString(labels[0]),
+          highLabel: optionalString(labels[1])
+        };
+        break;
+      }
+      case "grid": {
+        const rows = subs.map((sub) => {
+          const label = Array.isArray(sub.extra) ? optionalString(sub.extra[0]) : void 0;
+          return { entryId: toEntryId(sub.entryId), label: label ?? "" };
+        });
+        const isCheckboxGrid = subs.some((sub) => {
+          const flag = sub.rest[sub.rest.length - 1];
+          return Array.isArray(flag) && flag[0] === 1;
+        });
+        question.type = isCheckboxGrid ? "checkbox_grid" : "grid";
+        question.rows = rows;
+        question.options = mapOptions(firstSub.options);
+        break;
+      }
+      case "date": {
+        const flags = Array.isArray(firstSub.rest[7]) ? firstSub.rest[7] : void 0;
+        question.date = {
+          includeTime: flags?.[0] === 1,
+          includeYear: flags ? flags[1] === 1 : true
+        };
+        break;
+      }
+      case "time": {
+        const flags = Array.isArray(firstSub.rest[6]) ? firstSub.rest[6] : void 0;
+        question.time = { isDuration: flags?.[0] === 1 };
+        break;
+      }
+      case "file_upload":
+        break;
+      default:
+        break;
+    }
+    questions.push(question);
+    const currentSection = sections[sections.length - 1];
+    currentSection.questionIds.push(question.id);
+  }
+  return {
+    formId: formId ?? "",
+    title,
+    description,
+    questions,
+    sections,
+    multiPage: sawPageBreak
+  };
+};
+var parseFormHtml = (html) => {
+  const data = extractPublicLoadData(html);
+  const schema = parseFormData(data);
+  const fbzx = extractFbzx(html);
+  return fbzx ? { ...schema, fbzx } : schema;
+};
+
+// src/url.ts
+var BARE_ID_RE = /^[A-Za-z0-9_-]{10,}$/;
+var normalizeFormId = (input) => {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new Error("normalizeFormId: input is empty");
+  }
+  if (trimmed.startsWith("e/")) {
+    const id = trimmed.slice(2);
+    return normalizeFormId(id);
+  }
+  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith("docs.google.com")) {
+    const url = new URL(
+      /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`
+    );
+    const parts = url.pathname.split("/").filter(Boolean);
+    const dIndex = parts.indexOf("d");
+    if (dIndex === -1 || dIndex + 1 >= parts.length) {
+      throw new Error(
+        `normalizeFormId: could not find form id in URL "${input}"`
+      );
+    }
+    const afterD = parts[dIndex + 1];
+    const id = afterD === "e" ? parts[dIndex + 2] : afterD;
+    if (!id) {
+      throw new Error(
+        `normalizeFormId: could not find form id in URL "${input}"`
+      );
+    }
+    return normalizeFormId(id);
+  }
+  if (!BARE_ID_RE.test(trimmed)) {
+    throw new Error(
+      `normalizeFormId: "${input}" is not a recognizable Google Form id or URL`
+    );
+  }
+  return trimmed;
+};
+var formUrls = (formId) => {
+  const id = normalizeFormId(formId);
+  return {
+    viewform: `https://docs.google.com/forms/d/e/${id}/viewform`,
+    formResponse: `https://docs.google.com/forms/d/e/${id}/formResponse`
+  };
+};
+
+// src/submit.ts
+var buildPrefillUrl = (formId, values, schema) => {
+  const { viewform } = formUrls(formId);
+  const params = encodeValues(values, schema);
+  const url = new URL(viewform);
+  url.searchParams.set("usp", "pp_url");
+  for (const [key, value] of params) {
+    url.searchParams.append(key, value);
+  }
+  return url.toString();
+};
+var randomFbzx = () => {
+  const digits = Array.from({ length: 19 }, () => {
+    return Math.floor(Math.random() * 10);
+  }).join("");
+  return `-${digits}`;
+};
+var buildSubmitBody = (formId, values, schema) => {
+  normalizeFormId(formId);
+  const params = encodeValues(values, schema);
+  if (schema?.multiPage) {
+    const fbzx = schema.fbzx ?? randomFbzx();
+    const pageCount = Math.max(schema.sections.length, 1);
+    const pageHistory = Array.from({ length: pageCount }, (_, i) => {
+      return i;
+    }).join(",");
+    params.set("fbzx", fbzx);
+    params.set("pageHistory", pageHistory);
+    params.set("partialResponse", JSON.stringify([null, null, fbzx]));
+  }
+  params.set("submit", "Submit");
+  return params;
+};
+var submitForm = async (formId, values, opts = {}) => {
+  const { formResponse } = formUrls(formId);
+  const body = buildSubmitBody(formId, values, opts.schema);
+  const doFetch = opts.fetch ?? fetch;
+  const mode = opts.mode ?? "no-cors";
+  try {
+    const response = await doFetch(formResponse, {
+      method: "POST",
+      mode,
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+      signal: opts.signal
+    });
+    if (mode === "no-cors") {
+      return { status: "sent" };
+    }
+    if (response.ok) {
+      return { status: "ok", httpStatus: response.status };
+    }
+    return {
+      status: "error",
+      error: new Error(`formResponse returned HTTP ${response.status}`),
+      httpStatus: response.status
+    };
+  } catch (error) {
+    return { status: "error", error };
+  }
+};
+
+// src/index.ts
+var VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ParseError,
+  VERSION,
+  ValidationError,
+  buildPrefillUrl,
+  buildSubmitBody,
+  encodeValues,
+  extractPublicLoadData,
+  formUrls,
+  normalizeFormId,
+  parseFormData,
+  parseFormHtml,
+  submitForm,
+  validateValues
+});
+//# sourceMappingURL=index.cjs.map