@automate.ax/integration-contracts 0.55.0

package/src/google-forms/schemas.ts

@@ -0,0 +1,499 @@
+import type { forms_v1 } from "@googleapis/forms"
+import { z } from "zod"
+
+export const FORM_REFERENCE_SCHEMA = z.string().trim().min(1)
+export const ITEM_REFERENCE_SCHEMA = z.union([
+  z.string().trim().min(1),
+  z.number().int().positive(),
+])
+
+export const EMAIL_COLLECTION_TYPE_SCHEMA = z.enum([
+  "none",
+  "verified",
+  "respondentInput",
+])
+
+export const FORM_SETTINGS_INPUT_SCHEMA = z
+  .object({
+    /** How respondent email addresses are collected. */
+    emailCollection: EMAIL_COLLECTION_TYPE_SCHEMA.optional(),
+
+    /** Whether the form is configured as a graded quiz. */
+    isQuiz: z.boolean().optional(),
+  })
+  .refine(
+    ({ emailCollection, isQuiz }) =>
+      emailCollection !== undefined || isQuiz !== undefined,
+    "Provide at least one form setting to update.",
+  )
+
+export const FORM_SETTINGS_SCHEMA = z.object({
+  /** How respondent email addresses are collected. */
+  emailCollection: EMAIL_COLLECTION_TYPE_SCHEMA,
+
+  /** Whether the form is configured as a graded quiz. */
+  isQuiz: z.boolean(),
+})
+
+export const PUBLISH_SETTINGS_SCHEMA = z.object({
+  /** Whether respondents can currently submit responses. */
+  isAcceptingResponses: z.boolean(),
+
+  /** Whether the form is published and visible to respondents. */
+  isPublished: z.boolean(),
+})
+
+export const QUESTION_GRADING_INPUT_SCHEMA = z.object({
+  /** Accepted exact answer values used for automatic grading. */
+  correctAnswers: z.string().array().min(1),
+
+  /** Feedback shown for any answer. */
+  generalFeedback: z.string().optional(),
+
+  /** Maximum points awarded for a correct answer. */
+  points: z.number().nonnegative(),
+
+  /** Feedback shown for an incorrect answer. */
+  whenWrong: z.string().optional(),
+
+  /** Feedback shown for a correct answer. */
+  whenRight: z.string().optional(),
+})
+
+const QUESTION_BASE_INPUT_SCHEMA = z.object({
+  /** Optional stable question ID to preserve during replacement updates. */
+  questionId: z.string().trim().min(1).optional(),
+
+  /** Whether respondents must answer the question. */
+  required: z.boolean().optional(),
+})
+
+const CHOICE_OPTION_INPUT_SCHEMA = z.union([
+  z.string().min(1),
+  z.object({
+    /** Whether this is Forms' built-in free-text "Other" option. */
+    isOther: z.literal(true),
+
+    /** Optional display value. Google may ignore this for "Other". */
+    value: z.string().min(1).optional(),
+  }),
+])
+
+export const FORM_QUESTION_INPUT_SCHEMA = z.discriminatedUnion("type", [
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Question kind. */
+    type: z.literal("shortText"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Question kind. */
+    type: z.literal("paragraph"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Available choices in display order. */
+    options: CHOICE_OPTION_INPUT_SCHEMA.array().min(1),
+
+    /** Whether each respondent sees choices in randomized order. */
+    shuffle: z.boolean().optional(),
+
+    /** Question kind. */
+    type: z.literal("multipleChoice"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Available choices in display order. */
+    options: CHOICE_OPTION_INPUT_SCHEMA.array().min(1),
+
+    /** Whether each respondent sees choices in randomized order. */
+    shuffle: z.boolean().optional(),
+
+    /** Question kind. */
+    type: z.literal("checkbox"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Available choices in display order. */
+    options: z.string().min(1).array().min(1),
+
+    /** Whether each respondent sees choices in randomized order. */
+    shuffle: z.boolean().optional(),
+
+    /** Question kind. */
+    type: z.literal("dropdown"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Inclusive maximum scale value. */
+    high: z.number().int().min(2).max(10),
+
+    /** Label displayed beside the maximum value. */
+    highLabel: z.string().optional(),
+
+    /** Inclusive minimum scale value. */
+    low: z.union([z.literal(0), z.literal(1)]),
+
+    /** Label displayed beside the minimum value. */
+    lowLabel: z.string().optional(),
+
+    /** Question kind. */
+    type: z.literal("scale"),
+  }).refine(({ high, low }) => high > low, {
+    message: "Scale high must be greater than low.",
+    path: ["high"],
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Whether respondents also enter a time of day. */
+    includeTime: z.boolean().optional(),
+
+    /** Whether respondents enter a four-digit year. */
+    includeYear: z.boolean().optional(),
+
+    /** Question kind. */
+    type: z.literal("date"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Question kind. */
+    type: z.literal("time"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Question kind. */
+    type: z.literal("duration"),
+  }),
+  QUESTION_BASE_INPUT_SCHEMA.extend({
+    /** Icon displayed for each rating value. */
+    icon: z.enum(["star", "heart", "thumbUp"]),
+
+    /** Number of available rating levels. */
+    levels: z.number().int().min(3).max(10),
+
+    /** Question kind. */
+    type: z.literal("rating"),
+  }),
+])
+
+const FORM_ITEM_BASE_INPUT_SCHEMA = z.object({
+  /** Optional item description displayed below its title. */
+  description: z.string().optional(),
+
+  /** Optional stable item ID to preserve during replacement updates. */
+  itemId: z.string().trim().min(1).optional(),
+
+  /** Item title visible to respondents. */
+  title: z.string().optional(),
+})
+
+export const FORM_ITEM_INPUT_SCHEMA = z.discriminatedUnion("type", [
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Optional quiz grading configuration. */
+    grading: QUESTION_GRADING_INPUT_SCHEMA.optional(),
+
+    /** Question configuration. */
+    question: FORM_QUESTION_INPUT_SCHEMA,
+
+    /** Item kind. */
+    type: z.literal("question"),
+  }),
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Choice columns shared by every grid row. */
+    columns: z.string().min(1).array().min(1),
+
+    /** Grid selection behavior. */
+    gridType: z.enum(["multipleChoice", "checkbox"]),
+
+    /** Row labels, one per generated question. */
+    rows: z
+      .object({
+        /** Optional stable question ID. */
+        questionId: z.string().trim().min(1).optional(),
+
+        /** Whether this row must be answered. */
+        required: z.boolean().optional(),
+
+        /** Row prompt. */
+        title: z.string().min(1),
+      })
+      .array()
+      .min(1),
+
+    /** Whether each respondent sees rows in randomized order. */
+    shuffleRows: z.boolean().optional(),
+
+    /** Item kind. */
+    type: z.literal("grid"),
+  }),
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Item kind. */
+    type: z.literal("pageBreak"),
+  }),
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Item kind. */
+    type: z.literal("text"),
+  }),
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Accessible image description. */
+    altText: z.string().optional(),
+
+    /** Horizontal image alignment. */
+    alignment: z.enum(["left", "center", "right"]).optional(),
+
+    /** Public source URL for the image. */
+    sourceUrl: z.url(),
+
+    /** Item kind. */
+    type: z.literal("image"),
+
+    /** Display width in pixels. */
+    width: z.number().int().min(1).max(740).optional(),
+  }),
+  FORM_ITEM_BASE_INPUT_SCHEMA.extend({
+    /** Caption displayed beneath the video. */
+    caption: z.string().optional(),
+
+    /** Horizontal video alignment. */
+    alignment: z.enum(["left", "center", "right"]).optional(),
+
+    /** Item kind. */
+    type: z.literal("video"),
+
+    /** Display width in pixels. */
+    width: z.number().int().min(1).max(740).optional(),
+
+    /** YouTube watch or share URL. */
+    youtubeUrl: z.url(),
+  }),
+])
+
+export const NORMALIZED_GRADING_SCHEMA = z.object({
+  /** Whether the submitted answer was marked correct. */
+  correct: z.boolean().optional(),
+
+  /** Exact answer values accepted for automatic grading. */
+  correctAnswers: z.string().array(),
+
+  /** General or respondent-specific feedback text. */
+  feedback: z.string().optional(),
+
+  /** Maximum available points. */
+  points: z.number().nonnegative().optional(),
+
+  /** Points awarded to a submitted answer. */
+  score: z.number().optional(),
+
+  /** Feedback shown for incorrect answers. */
+  whenWrong: z.string().optional(),
+
+  /** Feedback shown for correct answers. */
+  whenRight: z.string().optional(),
+})
+
+export const NORMALIZED_QUESTION_SCHEMA = z.object({
+  /** Available choice values for choice questions. */
+  choices: z.string().array(),
+
+  /** Date-question configuration. */
+  date: z
+    .object({
+      includeTime: z.boolean(),
+      includeYear: z.boolean(),
+    })
+    .optional(),
+
+  /** File-upload configuration for existing upload questions. */
+  fileUpload: z
+    .object({
+      folderId: z.string().optional(),
+      maxFileSizeBytes: z.string().optional(),
+      maxFiles: z.number().int().nonnegative().optional(),
+      types: z.string().array(),
+    })
+    .optional(),
+
+  /** Quiz grading configuration. */
+  grading: NORMALIZED_GRADING_SCHEMA.optional(),
+
+  /** Immutable question ID. */
+  questionId: z.string(),
+
+  /** Rating-question configuration. */
+  rating: z
+    .object({
+      icon: z.string(),
+      levels: z.number().int().nonnegative(),
+    })
+    .optional(),
+
+  /** Whether the question must be answered. */
+  required: z.boolean(),
+
+  /** Grid row title for questions inside a grid. */
+  rowTitle: z.string().optional(),
+
+  /** Scale-question configuration. */
+  scale: z
+    .object({
+      high: z.number(),
+      highLabel: z.string().optional(),
+      low: z.number(),
+      lowLabel: z.string().optional(),
+    })
+    .optional(),
+
+  /** Normalized question kind. */
+  type: z.enum([
+    "shortText",
+    "paragraph",
+    "multipleChoice",
+    "checkbox",
+    "dropdown",
+    "scale",
+    "date",
+    "time",
+    "duration",
+    "rating",
+    "fileUpload",
+    "gridRow",
+    "unknown",
+  ]),
+})
+
+export const FORM_ITEM_SCHEMA = z.object({
+  /** Item description. */
+  description: z.string().optional(),
+
+  /** Zero-based item position. */
+  index: z.number().int().nonnegative(),
+
+  /** Immutable item ID. */
+  itemId: z.string(),
+
+  /** Questions contained by this item. */
+  questions: NORMALIZED_QUESTION_SCHEMA.array(),
+
+  /** Item title. */
+  title: z.string(),
+
+  /** Normalized item kind. */
+  type: z.enum([
+    "question",
+    "grid",
+    "pageBreak",
+    "text",
+    "image",
+    "video",
+    "unknown",
+  ]),
+})
+
+export const FORM_SCHEMA = z.object({
+  /** Browser URL for editing the form. */
+  editUrl: z.string(),
+
+  /** Immutable Google Form ID. */
+  formId: z.string(),
+
+  /** Form items in display order. */
+  items: FORM_ITEM_SCHEMA.array(),
+
+  /** Linked response spreadsheet ID, when configured. */
+  linkedSheetId: z.string().optional(),
+
+  /** Publishing state for modern forms. */
+  publishSettings: PUBLISH_SETTINGS_SCHEMA.optional(),
+
+  /** Browser URL respondents use to submit the form. */
+  responderUrl: z.string().optional(),
+
+  /** Opaque content revision ID valid for optimistic writes. */
+  revisionId: z.string().optional(),
+
+  /** Form-level behavior and quiz configuration. */
+  settings: FORM_SETTINGS_SCHEMA,
+
+  /** Description visible to respondents. */
+  description: z.string().optional(),
+
+  /** Drive document title. */
+  documentTitle: z.string().optional(),
+
+  /** Form title visible to respondents. */
+  title: z.string(),
+})
+
+export const FORM_FILE_ANSWER_SCHEMA = z.object({
+  /** Immutable Google Drive file ID. */
+  fileId: z.string(),
+
+  /** Uploaded file name. */
+  fileName: z.string(),
+
+  /** Uploaded file MIME type. */
+  mimeType: z.string(),
+})
+
+export const FORM_ANSWER_SCHEMA = z.object({
+  /** Files submitted to a file-upload question. */
+  files: FORM_FILE_ANSWER_SCHEMA.array(),
+
+  /** Quiz grade data for this answer. */
+  grade: NORMALIZED_GRADING_SCHEMA.optional(),
+
+  /** Immutable question ID. */
+  questionId: z.string(),
+
+  /** Question title or grid-row title, when form metadata was available. */
+  questionTitle: z.string().optional(),
+
+  /** Submitted values in provider display format. */
+  values: z.string().array(),
+})
+
+export const FORM_RESPONSE_SCHEMA = z.object({
+  /** Submitted answers in form display order. */
+  answers: FORM_ANSWER_SCHEMA.array(),
+
+  /** Timestamp when the response was first submitted. */
+  createTime: z.string().optional(),
+
+  /** Immutable Google Form ID. */
+  formId: z.string(),
+
+  /** Timestamp when the response was last submitted. */
+  lastSubmittedTime: z.string().optional(),
+
+  /** Respondent email when collection was enabled. */
+  respondentEmail: z.string().optional(),
+
+  /** Immutable response ID. */
+  responseId: z.string(),
+
+  /** Total quiz score when graded. */
+  totalScore: z.number().optional(),
+})
+
+export const FORM_RESPONSE_LIST_SCHEMA = z.object({
+  /** Token for retrieving the next result page. */
+  nextPageToken: z.string().optional(),
+
+  /** Normalized form responses. */
+  responses: FORM_RESPONSE_SCHEMA.array(),
+})
+
+export const FORM_BATCH_UPDATE_SCHEMA = z.object({
+  /** Updated form when requested. */
+  form: FORM_SCHEMA.optional(),
+
+  /** Normalized replies corresponding one-to-one with update requests. */
+  replies: z
+    .object({
+      /** Generated item ID for a create-item request. */
+      createdItemId: z.string().optional(),
+
+      /** Generated question IDs for a create-item request. */
+      createdQuestionIds: z.string().array(),
+    })
+    .array(),
+
+  /** Revision ID returned after the updates. */
+  revisionId: z.string().optional(),
+})
+
+export const RAW_FORM_UPDATE_REQUEST_SCHEMA = z.custom<forms_v1.Schema$Request>(
+  (value) => z.looseObject({}).safeParse(value).success,
+  "Expected a Google Forms batch update request object.",
+)

package/src/linear/api.ts

@@ -0,0 +1,141 @@
+import type { JsonObject } from "type-fest"
+import { z } from "zod"
+
+const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql"
+const LINEAR_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const LINEAR_ERROR_SCHEMA = z.looseObject({
+  extensions: z.record(z.string(), z.json()).optional(),
+  message: z.string(),
+  path: z.union([z.string(), z.number()]).array().optional(),
+})
+const LINEAR_RESPONSE_SCHEMA = z.looseObject({
+  data: z.unknown().optional(),
+  errors: LINEAR_ERROR_SCHEMA.array().optional(),
+})
+
+/** Options for one authenticated Linear GraphQL operation. */
+export interface LinearGraphqlOptions<TSchema extends z.ZodType> {
+  /** Schema that validates and types the operation's `data` payload. */
+  responseSchema: TSchema
+
+  /** GraphQL variables referenced by the operation. */
+  variables?: JsonObject
+}
+
+/** Authenticated Linear GraphQL helper for custom actions. */
+export interface LinearApi {
+  /**
+   * Executes any Linear GraphQL query or mutation.
+   *
+   * GraphQL errors throw `LinearApiError`, including partial failures returned
+   * with HTTP 200. Successful `data` is validated with the supplied schema.
+   *
+   * @param document - GraphQL query or mutation document.
+   * @param options - Variables and successful response schema.
+   */
+  graphql<TSchema extends z.ZodType>(
+    document: string,
+    options: LinearGraphqlOptions<TSchema>,
+  ): Promise<z.output<TSchema>>
+}
+
+/** One provider error returned in Linear's GraphQL error envelope. */
+export interface LinearGraphqlError {
+  /** Provider-specific error metadata, including an error code when supplied. */
+  extensions?: Record<string, unknown>
+
+  /** Human-readable provider error message. */
+  message: string
+
+  /** Response path whose resolution failed. */
+  path?: (number | string)[]
+}
+
+/** Structured error returned by an authenticated Linear GraphQL operation. */
+export class LinearApiError extends Error {
+  /** GraphQL errors returned by Linear. */
+  readonly errors: LinearGraphqlError[]
+
+  /** Retry delay from Linear's `Retry-After` header, in seconds. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Linear. */
+  readonly status: number
+
+  /**
+   * Creates a structured Linear API error.
+   *
+   * @param options - Provider and transport error details.
+   * @param options.errors - GraphQL errors returned by Linear.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    errors: LinearGraphqlError[]
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      `Linear GraphQL request failed: ${options.errors.map(({ message }) => message).join("; ")}`,
+    )
+    this.name = "LinearApiError"
+    this.errors = options.errors
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates a raw authenticated Linear GraphQL helper.
+ *
+ * Use this escape hatch for provider operations that do not yet have a packaged
+ * action. OAuth access tokens are resolved by the platform and never exposed to
+ * automation code.
+ *
+ * @param secret - Resolved Linear OAuth integration secret.
+ */
+export function getLinearApi(secret: Record<string, unknown>): LinearApi {
+  const { accessToken } = LINEAR_SECRET_SCHEMA.parse(secret)
+
+  return {
+    graphql: async (document, options) => {
+      const response = await fetch(LINEAR_GRAPHQL_URL, {
+        body: JSON.stringify({
+          query: document,
+          ...(options.variables && { variables: options.variables }),
+        }),
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        method: "POST",
+      })
+      const envelope = LINEAR_RESPONSE_SCHEMA.parse(await response.json())
+      if (!response.ok || envelope.errors?.length) {
+        throw new LinearApiError({
+          errors: envelope.errors ?? [
+            { message: `HTTP ${response.status} ${response.statusText}` },
+          ],
+          retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+          status: response.status,
+        })
+      }
+
+      return options.responseSchema.parse(envelope.data)
+    },
+  }
+}
+
+/**
+ * Parses Linear's integer retry delay header.
+ *
+ * @param value - Raw `Retry-After` header.
+ */
+function parseRetryAfter(value: string | null) {
+  if (value === null) return undefined
+  const seconds = Number(value)
+  return Number.isFinite(seconds) ? seconds : undefined
+}

package/src/linear/index.ts

@@ -0,0 +1,71 @@
+import { z } from "zod"
+import {
+  LINEAR_COMMENT_CREATED_EVENT_SCHEMA,
+  LINEAR_COMMENT_EVENT_SCHEMA,
+  LINEAR_COMMENT_REMOVED_EVENT_SCHEMA,
+  LINEAR_COMMENT_UPDATED_EVENT_SCHEMA,
+  LINEAR_ISSUE_CREATED_EVENT_SCHEMA,
+  LINEAR_ISSUE_EVENT_SCHEMA,
+  LINEAR_ISSUE_REMOVED_EVENT_SCHEMA,
+  LINEAR_ISSUE_UPDATED_EVENT_SCHEMA,
+  LINEAR_PROJECT_CREATED_EVENT_SCHEMA,
+  LINEAR_PROJECT_EVENT_SCHEMA,
+  LINEAR_PROJECT_REMOVED_EVENT_SCHEMA,
+  LINEAR_PROJECT_UPDATED_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+export const LINEAR_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const linearTriggerContracts = {
+  "linear.comment.created": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_COMMENT_CREATED_EVENT_SCHEMA,
+  },
+  "linear.comment.event": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_COMMENT_EVENT_SCHEMA,
+  },
+  "linear.comment.removed": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_COMMENT_REMOVED_EVENT_SCHEMA,
+  },
+  "linear.comment.updated": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_COMMENT_UPDATED_EVENT_SCHEMA,
+  },
+  "linear.issue.created": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_ISSUE_CREATED_EVENT_SCHEMA,
+  },
+  "linear.issue.event": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_ISSUE_EVENT_SCHEMA,
+  },
+  "linear.issue.removed": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_ISSUE_REMOVED_EVENT_SCHEMA,
+  },
+  "linear.issue.updated": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_ISSUE_UPDATED_EVENT_SCHEMA,
+  },
+  "linear.project.created": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_PROJECT_CREATED_EVENT_SCHEMA,
+  },
+  "linear.project.event": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_PROJECT_EVENT_SCHEMA,
+  },
+  "linear.project.removed": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_PROJECT_REMOVED_EVENT_SCHEMA,
+  },
+  "linear.project.updated": {
+    configSchema: LINEAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LINEAR_PROJECT_UPDATED_EVENT_SCHEMA,
+  },
+} as const