@automate.ax/integration-contracts 0.55.0

package/dist/google-forms/google-forms.d.ts

@@ -0,0 +1,243 @@
+import { type forms_v1 } from "@googleapis/forms";
+import { z } from "zod";
+import { EMAIL_COLLECTION_TYPE_SCHEMA, FORM_ITEM_INPUT_SCHEMA } from "./schemas.js";
+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 declare function getGoogleFormsApi(secret: Record<string, unknown>): forms_v1.Forms;
+/**
+ * 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 declare function normalizeFormId(form: string): string;
+/**
+ * Converts a code-first item definition to the provider request shape.
+ *
+ * @param input - Code-first form item.
+ */
+export declare function toGoogleFormItem(input: z.infer<typeof FORM_ITEM_INPUT_SCHEMA>): forms_v1.Schema$Item;
+/**
+ * Normalizes a provider form and all nested items.
+ *
+ * @param form - Google Forms resource.
+ * @throws When required provider identifiers are absent.
+ */
+export declare function normalizeForm(form: forms_v1.Schema$Form): {
+    editUrl: string;
+    formId: string;
+    items: {
+        index: number;
+        itemId: string;
+        questions: {
+            choices: string[];
+            questionId: string;
+            required: boolean;
+            type: "unknown" | "date" | "shortText" | "paragraph" | "multipleChoice" | "checkbox" | "dropdown" | "scale" | "time" | "duration" | "rating" | "fileUpload" | "gridRow";
+            date?: {
+                includeTime: boolean;
+                includeYear: boolean;
+            } | undefined;
+            fileUpload?: {
+                types: string[];
+                folderId?: string | undefined;
+                maxFileSizeBytes?: string | undefined;
+                maxFiles?: number | undefined;
+            } | undefined;
+            grading?: {
+                correctAnswers: string[];
+                correct?: boolean | undefined;
+                feedback?: string | undefined;
+                points?: number | undefined;
+                score?: number | undefined;
+                whenWrong?: string | undefined;
+                whenRight?: string | undefined;
+            } | undefined;
+            rating?: {
+                icon: string;
+                levels: number;
+            } | undefined;
+            rowTitle?: string | undefined;
+            scale?: {
+                high: number;
+                low: number;
+                highLabel?: string | undefined;
+                lowLabel?: string | undefined;
+            } | undefined;
+        }[];
+        title: string;
+        type: "unknown" | "text" | "question" | "grid" | "pageBreak" | "image" | "video";
+        description?: string | undefined;
+    }[];
+    settings: {
+        emailCollection: "none" | "verified" | "respondentInput";
+        isQuiz: boolean;
+    };
+    title: string;
+    linkedSheetId?: string | undefined;
+    publishSettings?: {
+        isAcceptingResponses: boolean;
+        isPublished: boolean;
+    } | undefined;
+    responderUrl?: string | undefined;
+    revisionId?: string | undefined;
+    description?: string | undefined;
+    documentTitle?: string | undefined;
+};
+/**
+ * Normalizes a provider item at its display position.
+ *
+ * @param item - Google Forms item.
+ * @param index - Zero-based display position.
+ */
+export declare function normalizeFormItem(item: forms_v1.Schema$Item, index: number): {
+    index: number;
+    itemId: string;
+    questions: {
+        choices: string[];
+        questionId: string;
+        required: boolean;
+        type: "unknown" | "date" | "shortText" | "paragraph" | "multipleChoice" | "checkbox" | "dropdown" | "scale" | "time" | "duration" | "rating" | "fileUpload" | "gridRow";
+        date?: {
+            includeTime: boolean;
+            includeYear: boolean;
+        } | undefined;
+        fileUpload?: {
+            types: string[];
+            folderId?: string | undefined;
+            maxFileSizeBytes?: string | undefined;
+            maxFiles?: number | undefined;
+        } | undefined;
+        grading?: {
+            correctAnswers: string[];
+            correct?: boolean | undefined;
+            feedback?: string | undefined;
+            points?: number | undefined;
+            score?: number | undefined;
+            whenWrong?: string | undefined;
+            whenRight?: string | undefined;
+        } | undefined;
+        rating?: {
+            icon: string;
+            levels: number;
+        } | undefined;
+        rowTitle?: string | undefined;
+        scale?: {
+            high: number;
+            low: number;
+            highLabel?: string | undefined;
+            lowLabel?: string | undefined;
+        } | undefined;
+    }[];
+    title: string;
+    type: "unknown" | "text" | "question" | "grid" | "pageBreak" | "image" | "video";
+    description?: string | undefined;
+};
+/**
+ * Collects question titles in form display order.
+ *
+ * @param form - Google Forms resource.
+ */
+export declare function getQuestionMetadata(form: forms_v1.Schema$Form): QuestionMetadata[];
+/**
+ * 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 declare function normalizeFormResponse(response: forms_v1.Schema$FormResponse, formId: string, questions?: QuestionMetadata[]): {
+    answers: {
+        files: {
+            fileId: string;
+            fileName: string;
+            mimeType: string;
+        }[];
+        questionId: string;
+        values: string[];
+        grade?: {
+            correctAnswers: string[];
+            correct?: boolean | undefined;
+            feedback?: string | undefined;
+            points?: number | undefined;
+            score?: number | undefined;
+            whenWrong?: string | undefined;
+            whenRight?: string | undefined;
+        } | undefined;
+        questionTitle?: string | undefined;
+    }[];
+    formId: string;
+    responseId: string;
+    createTime?: string | undefined;
+    lastSubmittedTime?: string | undefined;
+    respondentEmail?: string | undefined;
+    totalScore?: number | 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 declare function resolveItemIndex(formsApi: forms_v1.Forms, formId: string, reference: string | number): Promise<number>;
+/**
+ * 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 declare function resolveFormItem(formsApi: forms_v1.Forms, formId: string, reference: string | number): Promise<{
+    form: forms_v1.Schema$Form;
+    index: number;
+    item: forms_v1.Schema$Item;
+}>;
+/**
+ * Preserves provider-generated item and question IDs during full replacement.
+ *
+ * @param next - Replacement item.
+ * @param current - Existing provider item.
+ */
+export declare function preserveItemIds(next: forms_v1.Schema$Item, current: forms_v1.Schema$Item): forms_v1.Schema$Item;
+/**
+ * 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 declare function resolveInsertionIndex(formsApi: forms_v1.Forms, formId: string, position?: number): Promise<number>;
+/**
+ * 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 declare function toGoogleFormSettings(settings: {
+    emailCollection?: z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA>;
+    isQuiz?: boolean;
+}): forms_v1.Schema$FormSettings;
+/**
+ * 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 declare function getSettingsUpdateMask(settings: {
+    emailCollection?: z.infer<typeof EMAIL_COLLECTION_TYPE_SCHEMA>;
+    isQuiz?: boolean;
+}): string;