@automate.ax/integration-contracts 0.55.0

package/dist/google-forms/google-forms.js

@@ -0,0 +1,581 @@
+import { auth, forms } from "@googleapis/forms";
+import { z } from "zod";
+import { FORM_ITEM_SCHEMA, FORM_RESPONSE_SCHEMA, FORM_SCHEMA, } from "./schemas.js";
+const GOOGLE_FORMS_URL_HOSTS = new Set(["docs.google.com", "forms.google.com"]);
+const GOOGLE_FORMS_SECRET_SCHEMA = z.object({
+    accessToken: z.string().min(1),
+});
+const EMAIL_COLLECTION_TYPES = {
+    none: "DO_NOT_COLLECT",
+    respondentInput: "RESPONDER_INPUT",
+    verified: "VERIFIED",
+};
+const CHOICE_TYPES = {
+    checkbox: "CHECKBOX",
+    dropdown: "DROP_DOWN",
+    multipleChoice: "RADIO",
+};
+const RATING_ICON_TYPES = {
+    heart: "HEART",
+    star: "STAR",
+    thumbUp: "THUMB_UP",
+};
+const MEDIA_ALIGNMENTS = {
+    center: "CENTER",
+    left: "LEFT",
+    right: "RIGHT",
+};
+/**
+ * Creates the official Forms client from a resolved Google integration secret.
+ *
+ * @param secret - Refreshed Google integration secret.
+ */
+export function getGoogleFormsApi(secret) {
+    const { accessToken } = GOOGLE_FORMS_SECRET_SCHEMA.parse(secret);
+    return forms({
+        auth: new auth.OAuth2({
+            credentials: { access_token: accessToken },
+        }),
+        version: "v1",
+    });
+}
+/**
+ * Accepts either a raw form ID or a standard Google Forms URL.
+ *
+ * @param form - Form ID or URL.
+ * @throws When a URL is not a recognizable Google Forms URL.
+ */
+export function normalizeFormId(form) {
+    const value = form.trim();
+    if (!URL.canParse(value))
+        return value;
+    const url = new URL(value);
+    if (!GOOGLE_FORMS_URL_HOSTS.has(url.hostname)) {
+        throw new Error(`Expected a Google Forms URL, received "${value}".`);
+    }
+    const pathParts = url.pathname.split("/");
+    const dIndex = pathParts.indexOf("d", pathParts.indexOf("forms") + 1);
+    const formId = dIndex === -1
+        ? undefined
+        : pathParts[dIndex + 1] === "e"
+            ? pathParts[dIndex + 2]
+            : pathParts[dIndex + 1];
+    if (!formId) {
+        throw new Error(`Could not find a form ID in "${value}".`);
+    }
+    return formId;
+}
+/**
+ * Converts a code-first item definition to the provider request shape.
+ *
+ * @param input - Code-first form item.
+ */
+export function toGoogleFormItem(input) {
+    const base = {
+        description: input.description,
+        itemId: input.itemId,
+        title: input.title,
+    };
+    switch (input.type) {
+        case "question":
+            return {
+                ...base,
+                questionItem: {
+                    question: {
+                        ...toGoogleQuestion(input.question),
+                        grading: input.grading
+                            ? {
+                                correctAnswers: {
+                                    answers: input.grading.correctAnswers.map((value) => ({
+                                        value,
+                                    })),
+                                },
+                                generalFeedback: input.grading.generalFeedback
+                                    ? { text: input.grading.generalFeedback }
+                                    : undefined,
+                                pointValue: input.grading.points,
+                                whenRight: input.grading.whenRight
+                                    ? { text: input.grading.whenRight }
+                                    : undefined,
+                                whenWrong: input.grading.whenWrong
+                                    ? { text: input.grading.whenWrong }
+                                    : undefined,
+                            }
+                            : undefined,
+                    },
+                },
+            };
+        case "grid":
+            return {
+                ...base,
+                questionGroupItem: {
+                    grid: {
+                        columns: {
+                            options: input.columns.map((value) => ({ value })),
+                            type: input.gridType === "checkbox" ? "CHECKBOX" : "RADIO",
+                        },
+                        shuffleQuestions: input.shuffleRows,
+                    },
+                    questions: input.rows.map((row) => ({
+                        questionId: row.questionId,
+                        required: row.required,
+                        rowQuestion: { title: row.title },
+                    })),
+                },
+            };
+        case "pageBreak":
+            return { ...base, pageBreakItem: {} };
+        case "text":
+            return { ...base, textItem: {} };
+        case "image":
+            return {
+                ...base,
+                imageItem: {
+                    image: {
+                        altText: input.altText,
+                        properties: {
+                            alignment: input.alignment
+                                ? MEDIA_ALIGNMENTS[input.alignment]
+                                : undefined,
+                            width: input.width,
+                        },
+                        sourceUri: input.sourceUrl,
+                    },
+                },
+            };
+        case "video":
+            return {
+                ...base,
+                videoItem: {
+                    caption: input.caption,
+                    video: {
+                        properties: {
+                            alignment: input.alignment
+                                ? MEDIA_ALIGNMENTS[input.alignment]
+                                : undefined,
+                            width: input.width,
+                        },
+                        youtubeUri: input.youtubeUrl,
+                    },
+                },
+            };
+    }
+}
+/**
+ * Normalizes a provider form and all nested items.
+ *
+ * @param form - Google Forms resource.
+ * @throws When required provider identifiers are absent.
+ */
+export function normalizeForm(form) {
+    if (!form.formId)
+        throw new Error("Google Forms returned no form ID.");
+    return FORM_SCHEMA.parse({
+        description: form.info?.description ?? undefined,
+        documentTitle: form.info?.documentTitle ?? undefined,
+        editUrl: `https://docs.google.com/forms/d/${form.formId}/edit`,
+        formId: form.formId,
+        items: (form.items ?? []).map(normalizeFormItem),
+        linkedSheetId: form.linkedSheetId ?? undefined,
+        publishSettings: form.publishSettings?.publishState
+            ? {
+                isAcceptingResponses: form.publishSettings.publishState.isAcceptingResponses ?? false,
+                isPublished: form.publishSettings.publishState.isPublished ?? false,
+            }
+            : undefined,
+        responderUrl: form.responderUri ?? undefined,
+        revisionId: form.revisionId ?? undefined,
+        settings: {
+            emailCollection: toPublicEmailCollectionType(form.settings?.emailCollectionType),
+            isQuiz: form.settings?.quizSettings?.isQuiz ?? false,
+        },
+        title: form.info?.title ?? "",
+    });
+}
+/**
+ * Normalizes a provider item at its display position.
+ *
+ * @param item - Google Forms item.
+ * @param index - Zero-based display position.
+ */
+export function normalizeFormItem(item, index) {
+    return FORM_ITEM_SCHEMA.parse({
+        description: item.description ?? undefined,
+        index,
+        itemId: item.itemId ?? "",
+        questions: item.questionItem?.question
+            ? [normalizeQuestion(item.questionItem.question)]
+            : (item.questionGroupItem?.questions ?? []).map((question) => normalizeQuestion({
+                ...question,
+                choiceQuestion: item.questionGroupItem?.grid?.columns,
+            })),
+        title: item.title ?? "",
+        type: item.questionItem
+            ? "question"
+            : item.questionGroupItem
+                ? "grid"
+                : item.pageBreakItem
+                    ? "pageBreak"
+                    : item.textItem
+                        ? "text"
+                        : item.imageItem
+                            ? "image"
+                            : item.videoItem
+                                ? "video"
+                                : "unknown",
+    });
+}
+/**
+ * Collects question titles in form display order.
+ *
+ * @param form - Google Forms resource.
+ */
+export function getQuestionMetadata(form) {
+    return (form.items ?? []).flatMap((item) => {
+        if (item.questionItem?.question?.questionId) {
+            return [
+                {
+                    questionId: item.questionItem.question.questionId,
+                    title: item.title ?? undefined,
+                },
+            ];
+        }
+        return (item.questionGroupItem?.questions ?? []).flatMap((question) => question.questionId
+            ? [
+                {
+                    questionId: question.questionId,
+                    title: question.rowQuestion?.title ?? item.title ?? undefined,
+                },
+            ]
+            : []);
+    });
+}
+/**
+ * Normalizes a submitted response and sorts answers in form display order.
+ *
+ * @param response - Google Forms response.
+ * @param formId - Form ID used when list responses omit it.
+ * @param questions - Optional form question metadata.
+ * @throws When the provider response omits its response ID.
+ */
+export function normalizeFormResponse(response, formId, questions = []) {
+    if (!response.responseId) {
+        throw new Error("Google Forms returned a response without an ID.");
+    }
+    const questionOrder = new Map(questions.map(({ questionId }, index) => [questionId, index]));
+    const titles = new Map(questions.map(({ questionId, title }) => [questionId, title]));
+    // Keep this pipeline named so the response assembly remains readable.
+    const answers = Object.values(response.answers ?? {})
+        .filter((answer) => Boolean(answer.questionId))
+        .toSorted((left, right) => (questionOrder.get(left.questionId) ?? Number.MAX_SAFE_INTEGER) -
+        (questionOrder.get(right.questionId) ?? Number.MAX_SAFE_INTEGER))
+        .map((answer) => ({
+        files: (answer.fileUploadAnswers?.answers ?? []).flatMap((file) => file.fileId && file.fileName && file.mimeType
+            ? [
+                {
+                    fileId: file.fileId,
+                    fileName: file.fileName,
+                    mimeType: file.mimeType,
+                },
+            ]
+            : []),
+        grade: answer.grade
+            ? {
+                correct: answer.grade.correct ?? undefined,
+                correctAnswers: [],
+                feedback: answer.grade.feedback?.text ?? undefined,
+                score: answer.grade.score ?? undefined,
+            }
+            : undefined,
+        questionId: answer.questionId,
+        questionTitle: titles.get(answer.questionId) ?? undefined,
+        values: (answer.textAnswers?.answers ?? []).flatMap(({ value }) => value == null ? [] : [value]),
+    }));
+    return FORM_RESPONSE_SCHEMA.parse({
+        answers,
+        createTime: response.createTime ?? undefined,
+        formId: response.formId ?? formId,
+        lastSubmittedTime: response.lastSubmittedTime ?? undefined,
+        respondentEmail: response.respondentEmail ?? undefined,
+        responseId: response.responseId,
+        totalScore: response.totalScore ?? undefined,
+    });
+}
+/**
+ * Resolves a one-based item position or immutable item ID to a zero-based
+ * index.
+ *
+ * @param formsApi - Authenticated Forms client.
+ * @param formId - Immutable form ID.
+ * @param reference - One-based position or item ID.
+ * @throws When the referenced item does not exist.
+ */
+export async function resolveItemIndex(formsApi, formId, reference) {
+    if (typeof reference === "number")
+        return reference - 1;
+    const { data } = await formsApi.forms.get({ formId });
+    const index = data.items?.findIndex(({ itemId }) => itemId === reference) ?? -1;
+    if (index === -1) {
+        throw new Error(`Google Forms item "${reference}" was not found.`);
+    }
+    return index;
+}
+/**
+ * Resolves a one-based item position or immutable item ID with its form.
+ *
+ * @param formsApi - Authenticated Forms client.
+ * @param formId - Immutable form ID.
+ * @param reference - One-based position or item ID.
+ * @throws When the referenced item does not exist.
+ */
+export async function resolveFormItem(formsApi, formId, reference) {
+    const { data: form } = await formsApi.forms.get({ formId });
+    const index = typeof reference === "number"
+        ? reference - 1
+        : (form.items?.findIndex(({ itemId }) => itemId === reference) ?? -1);
+    const item = form.items?.[index];
+    if (!item) {
+        throw new Error(`Google Forms item "${reference}" was not found.`);
+    }
+    return { form, index, item };
+}
+/**
+ * Preserves provider-generated item and question IDs during full replacement.
+ *
+ * @param next - Replacement item.
+ * @param current - Existing provider item.
+ */
+export function preserveItemIds(next, current) {
+    return {
+        ...next,
+        itemId: next.itemId ?? current.itemId,
+        questionGroupItem: next.questionGroupItem
+            ? {
+                ...next.questionGroupItem,
+                questions: next.questionGroupItem.questions?.map((question, index) => ({
+                    ...question,
+                    questionId: question.questionId ??
+                        current.questionGroupItem?.questions?.[index]?.questionId,
+                })),
+            }
+            : undefined,
+        questionItem: next.questionItem
+            ? {
+                ...next.questionItem,
+                question: next.questionItem.question
+                    ? {
+                        ...next.questionItem.question,
+                        questionId: next.questionItem.question.questionId ??
+                            current.questionItem?.question?.questionId,
+                    }
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+/**
+ * Resolves an optional one-based insertion position, defaulting to the end.
+ *
+ * @param formsApi - Authenticated Forms client.
+ * @param formId - Immutable form ID.
+ * @param position - Optional one-based insertion position.
+ */
+export async function resolveInsertionIndex(formsApi, formId, position) {
+    if (position !== undefined)
+        return position - 1;
+    const { data } = await formsApi.forms.get({ formId });
+    return data.items?.length ?? 0;
+}
+/**
+ * Converts public settings into Google Forms settings.
+ *
+ * @param settings - Code-first form settings.
+ * @param settings.emailCollection - Email collection behavior.
+ * @param settings.isQuiz - Whether the form is a quiz.
+ */
+export function toGoogleFormSettings(settings) {
+    return {
+        emailCollectionType: settings.emailCollection
+            ? EMAIL_COLLECTION_TYPES[settings.emailCollection]
+            : undefined,
+        quizSettings: settings.isQuiz === undefined ? undefined : { isQuiz: settings.isQuiz },
+    };
+}
+/**
+ * Builds a comma-separated settings update mask.
+ *
+ * @param settings - Code-first form settings.
+ * @param settings.emailCollection - Email collection behavior.
+ * @param settings.isQuiz - Whether the form is a quiz.
+ */
+export function getSettingsUpdateMask(settings) {
+    return [
+        settings.emailCollection === undefined ? undefined : "emailCollectionType",
+        settings.isQuiz === undefined ? undefined : "quizSettings.isQuiz",
+    ]
+        .filter((field) => Boolean(field))
+        .join(",");
+}
+/**
+ * Converts a code-first question to Google Forms' union representation.
+ *
+ * @param input - Code-first question definition.
+ */
+function toGoogleQuestion(input) {
+    const base = {
+        questionId: input.questionId,
+        required: input.required,
+    };
+    switch (input.type) {
+        case "shortText":
+            return { ...base, textQuestion: { paragraph: false } };
+        case "paragraph":
+            return { ...base, textQuestion: { paragraph: true } };
+        case "multipleChoice":
+        case "checkbox":
+        case "dropdown":
+            return {
+                ...base,
+                choiceQuestion: {
+                    options: input.options.map((option) => typeof option === "string"
+                        ? { value: option }
+                        : { isOther: true, value: option.value }),
+                    shuffle: input.shuffle,
+                    type: CHOICE_TYPES[input.type],
+                },
+            };
+        case "scale":
+            return {
+                ...base,
+                scaleQuestion: {
+                    high: input.high,
+                    highLabel: input.highLabel,
+                    low: input.low,
+                    lowLabel: input.lowLabel,
+                },
+            };
+        case "date":
+            return {
+                ...base,
+                dateQuestion: {
+                    includeTime: input.includeTime,
+                    includeYear: input.includeYear,
+                },
+            };
+        case "time":
+            return { ...base, timeQuestion: { duration: false } };
+        case "duration":
+            return { ...base, timeQuestion: { duration: true } };
+        case "rating":
+            return {
+                ...base,
+                ratingQuestion: {
+                    iconType: RATING_ICON_TYPES[input.icon],
+                    ratingScaleLevel: input.levels,
+                },
+            };
+    }
+}
+/**
+ * Normalizes one provider question.
+ *
+ * @param question - Google Forms question.
+ */
+function normalizeQuestion(question) {
+    return {
+        choices: (question.choiceQuestion?.options ?? []).flatMap(({ value }) => value == null ? [] : [value]),
+        date: question.dateQuestion
+            ? {
+                includeTime: question.dateQuestion.includeTime ?? false,
+                includeYear: question.dateQuestion.includeYear ?? false,
+            }
+            : undefined,
+        fileUpload: question.fileUploadQuestion
+            ? {
+                folderId: question.fileUploadQuestion.folderId ?? undefined,
+                maxFileSizeBytes: question.fileUploadQuestion.maxFileSize ?? undefined,
+                maxFiles: question.fileUploadQuestion.maxFiles ?? undefined,
+                types: question.fileUploadQuestion.types ?? [],
+            }
+            : undefined,
+        grading: question.grading
+            ? {
+                correctAnswers: (question.grading.correctAnswers?.answers ?? []).flatMap(({ value }) => (value == null ? [] : [value])),
+                feedback: question.grading.generalFeedback?.text ?? undefined,
+                points: question.grading.pointValue ?? undefined,
+                whenRight: question.grading.whenRight?.text ?? undefined,
+                whenWrong: question.grading.whenWrong?.text ?? undefined,
+            }
+            : undefined,
+        questionId: question.questionId ?? "",
+        rating: question.ratingQuestion
+            ? {
+                icon: question.ratingQuestion.iconType ?? "",
+                levels: question.ratingQuestion.ratingScaleLevel ?? 0,
+            }
+            : undefined,
+        required: question.required ?? false,
+        rowTitle: question.rowQuestion?.title ?? undefined,
+        scale: question.scaleQuestion
+            ? {
+                high: question.scaleQuestion.high ?? 0,
+                highLabel: question.scaleQuestion.highLabel ?? undefined,
+                low: question.scaleQuestion.low ?? 0,
+                lowLabel: question.scaleQuestion.lowLabel ?? undefined,
+            }
+            : undefined,
+        type: question.rowQuestion
+            ? "gridRow"
+            : question.textQuestion
+                ? question.textQuestion.paragraph
+                    ? "paragraph"
+                    : "shortText"
+                : question.choiceQuestion
+                    ? toPublicChoiceType(question.choiceQuestion.type)
+                    : question.scaleQuestion
+                        ? "scale"
+                        : question.dateQuestion
+                            ? "date"
+                            : question.timeQuestion
+                                ? question.timeQuestion.duration
+                                    ? "duration"
+                                    : "time"
+                                : question.ratingQuestion
+                                    ? "rating"
+                                    : question.fileUploadQuestion
+                                        ? "fileUpload"
+                                        : "unknown",
+    };
+}
+/**
+ * Maps the provider email collection enum to the public enum.
+ *
+ * @param type - Google Forms enum value.
+ */
+function toPublicEmailCollectionType(type) {
+    switch (type) {
+        case "VERIFIED":
+            return "verified";
+        case "RESPONDER_INPUT":
+            return "respondentInput";
+        default:
+            return "none";
+    }
+}
+/**
+ * Maps the provider choice enum to the public question kind.
+ *
+ * @param type - Google Forms enum value.
+ */
+function toPublicChoiceType(type) {
+    switch (type) {
+        case "RADIO":
+            return "multipleChoice";
+        case "CHECKBOX":
+            return "checkbox";
+        case "DROP_DOWN":
+            return "dropdown";
+        default:
+            return "unknown";
+    }
+}