@automate.ax/integration-contracts 0.55.0

package/src/google-forms/google-forms.ts

@@ -0,0 +1,683 @@
+import { auth, forms, type forms_v1 } from "@googleapis/forms"
+import { z } from "zod"
+import {
+  EMAIL_COLLECTION_TYPE_SCHEMA,
+  FORM_ITEM_INPUT_SCHEMA,
+  FORM_ITEM_SCHEMA,
+  FORM_QUESTION_INPUT_SCHEMA,
+  FORM_RESPONSE_SCHEMA,
+  FORM_SCHEMA,
+} from "./schemas"
+
+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",
+} satisfies Record<z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA>, string>
+const CHOICE_TYPES = {
+  checkbox: "CHECKBOX",
+  dropdown: "DROP_DOWN",
+  multipleChoice: "RADIO",
+} as const
+const RATING_ICON_TYPES = {
+  heart: "HEART",
+  star: "STAR",
+  thumbUp: "THUMB_UP",
+} as const
+const MEDIA_ALIGNMENTS = {
+  center: "CENTER",
+  left: "LEFT",
+  right: "RIGHT",
+} as const
+
+export interface QuestionMetadata {
+  questionId: string
+  title?: string
+}
+
+/**
+ * Creates the official Forms client from a resolved Google integration secret.
+ *
+ * @param secret - Refreshed Google integration secret.
+ */
+export function getGoogleFormsApi(secret: Record<string, unknown>) {
+  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: string) {
+  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: z.infer<typeof FORM_ITEM_INPUT_SCHEMA>,
+): forms_v1.Schema$Item {
+  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: forms_v1.Schema$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: forms_v1.Schema$Item, index: number) {
+  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: forms_v1.Schema$Form,
+): QuestionMetadata[] {
+  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: forms_v1.Schema$FormResponse,
+  formId: string,
+  questions: QuestionMetadata[] = [],
+) {
+  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): answer is forms_v1.Schema$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: forms_v1.Forms,
+  formId: string,
+  reference: string | number,
+) {
+  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: forms_v1.Forms,
+  formId: string,
+  reference: string | number,
+) {
+  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: forms_v1.Schema$Item,
+  current: forms_v1.Schema$Item,
+): forms_v1.Schema$Item {
+  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: forms_v1.Forms,
+  formId: string,
+  position?: number,
+) {
+  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: {
+  emailCollection?: z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA>
+  isQuiz?: boolean
+}): forms_v1.Schema$FormSettings {
+  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: {
+  emailCollection?: z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA>
+  isQuiz?: boolean
+}) {
+  return [
+    settings.emailCollection === undefined ? undefined : "emailCollectionType",
+    settings.isQuiz === undefined ? undefined : "quizSettings.isQuiz",
+  ]
+    .filter((field): field is string => Boolean(field))
+    .join(",")
+}
+
+/**
+ * Converts a code-first question to Google Forms' union representation.
+ *
+ * @param input - Code-first question definition.
+ */
+function toGoogleQuestion(
+  input: z.infer<typeof FORM_QUESTION_INPUT_SCHEMA>,
+): forms_v1.Schema$Question {
+  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: forms_v1.Schema$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: string | null | undefined,
+): z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA> {
+  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: string | null | undefined,
+): "multipleChoice" | "checkbox" | "dropdown" | "unknown" {
+  switch (type) {
+    case "RADIO":
+      return "multipleChoice"
+    case "CHECKBOX":
+      return "checkbox"
+    case "DROP_DOWN":
+      return "dropdown"
+    default:
+      return "unknown"
+  }
+}

package/src/google-forms/index.ts

@@ -0,0 +1,23 @@
+import { z } from "zod"
+import { GOOGLE_FORMS_FORM_CHANGED_EVENT_SCHEMA } from "./event-schemas"
+import { FORM_RESPONSE_SCHEMA } from "./schemas"
+
+export * from "./event-schemas"
+export * from "./google-forms"
+export * from "./schemas"
+
+/** Canonical Google Form selected by one subscription. */
+export const GOOGLE_FORMS_TRIGGER_CONFIG_SCHEMA = z.object({
+  formId: z.string(),
+})
+
+export const googleFormsTriggerContracts = {
+  "googleForms.form.changed": {
+    configSchema: GOOGLE_FORMS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: GOOGLE_FORMS_FORM_CHANGED_EVENT_SCHEMA,
+  },
+  "googleForms.response.submitted": {
+    configSchema: GOOGLE_FORMS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: FORM_RESPONSE_SCHEMA,
+  },
+} as const