@automate.ax/integration-contracts 0.141.0 → 0.142.0

package/src/clickup/schemas.ts

@@ -0,0 +1,324 @@
+import * as z from "zod"
+
+export const CLICKUP_USER_SCHEMA = z.object({
+  color: z.string().nullable().optional(),
+  email: z.email().optional(),
+  id: z.number().int(),
+  initials: z.string().optional(),
+  profilePicture: z.url().nullable().optional(),
+  role: z.number().int().optional(),
+  username: z.string(),
+})
+
+export const CLICKUP_WORKSPACE_SCHEMA = z.object({
+  avatar: z.url().nullable().optional(),
+  color: z.string().nullable().optional(),
+  id: z.string(),
+  members: z.object({ user: CLICKUP_USER_SCHEMA }).array().prefault([]),
+  name: z.string(),
+})
+
+export const CLICKUP_STATUS_SCHEMA = z.object({
+  color: z.string().optional(),
+  orderindex: z.number().optional(),
+  status: z.string(),
+  type: z.string().optional(),
+})
+
+export const CLICKUP_SPACE_SCHEMA = z.object({
+  archived: z.boolean().prefault(false),
+  color: z.string().nullable().optional(),
+  id: z.string(),
+  multipleAssignees: z.boolean().optional(),
+  name: z.string(),
+  private: z.boolean().optional(),
+  statuses: CLICKUP_STATUS_SCHEMA.array().prefault([]),
+})
+
+export const CLICKUP_FOLDER_SCHEMA: z.ZodType<{
+  folders: z.output<typeof CLICKUP_FOLDER_SCHEMA>[]
+  hidden?: boolean
+  id: string
+  lists: z.output<typeof CLICKUP_LIST_SCHEMA>[]
+  name: string
+  orderindex?: number
+  overrideStatuses?: boolean
+  parentFolder?: string
+  space?: { id: string; name?: string }
+  taskCount?: string
+}> = z.object({
+  folders: z.lazy(() => CLICKUP_FOLDER_SCHEMA.array()).prefault([]),
+  hidden: z.boolean().optional(),
+  id: z.string(),
+  lists: z.lazy(() => CLICKUP_LIST_SCHEMA.array()).prefault([]),
+  name: z.string(),
+  orderindex: z.number().optional(),
+  overrideStatuses: z.boolean().optional(),
+  parentFolder: z.string().optional(),
+  space: z.object({ id: z.string(), name: z.string().optional() }).optional(),
+  taskCount: z
+    .string()
+    .nullable()
+    .optional()
+    .transform((value) => value ?? undefined),
+})
+
+export const CLICKUP_LIST_SCHEMA = z.object({
+  archived: z.boolean().optional(),
+  content: z.string().optional(),
+  dueDate: z.string().nullable().optional(),
+  dueDateTime: z.boolean().optional(),
+  folder: z
+    .object({
+      hidden: z.boolean().optional(),
+      id: z.string(),
+      name: z.string().optional(),
+    })
+    .optional(),
+  id: z.string(),
+  name: z.string(),
+  orderindex: z.number().optional(),
+  space: z.object({ id: z.string(), name: z.string().optional() }).optional(),
+  statuses: CLICKUP_STATUS_SCHEMA.array().prefault([]),
+  taskCount: z.string().nullable().optional(),
+})
+
+export const CLICKUP_CUSTOM_FIELD_SCHEMA = z.object({
+  id: z.string(),
+  name: z.string(),
+  required: z.boolean().optional(),
+  type: z.string(),
+  typeConfig: z.json().optional(),
+  value: z.json().optional(),
+})
+
+const CLICKUP_TASK_BASE_SCHEMA = z.object({
+  archived: z.boolean().prefault(false),
+  assignees: CLICKUP_USER_SCHEMA.array().prefault([]),
+  creator: CLICKUP_USER_SCHEMA.optional(),
+  customFields: CLICKUP_CUSTOM_FIELD_SCHEMA.array().prefault([]),
+  dateClosed: z.string().nullable().optional(),
+  dateCreated: z.string().optional(),
+  dateDone: z.string().nullable().optional(),
+  dateUpdated: z.string().optional(),
+  description: z.string().optional(),
+  dueDate: z.string().nullable().optional(),
+  id: z.string(),
+  list: z.object({ id: z.string(), name: z.string().optional() }).optional(),
+  name: z.string(),
+  parent: z.string().nullable().optional(),
+  priority: z
+    .object({
+      color: z.string().optional(),
+      id: z.string().optional(),
+      orderindex: z.string().optional(),
+      priority: z.string(),
+    })
+    .nullable()
+    .optional(),
+  space: z.object({ id: z.string() }).optional(),
+  startDate: z.string().nullable().optional(),
+  status: CLICKUP_STATUS_SCHEMA.optional(),
+  tags: z
+    .object({
+      name: z.string(),
+      tagBg: z.string().optional(),
+      tagFg: z.string().optional(),
+    })
+    .array()
+    .prefault([]),
+  textContent: z.string().optional(),
+  timeEstimate: z.coerce.number().nullable().optional(),
+  timeSpent: z.number().optional(),
+  url: z.url().optional(),
+  watchers: CLICKUP_USER_SCHEMA.array().prefault([]),
+})
+
+export type ClickUpTask = z.output<typeof CLICKUP_TASK_BASE_SCHEMA> & {
+  subtasks: ClickUpTask[]
+}
+
+export const CLICKUP_TASK_SCHEMA: z.ZodType<ClickUpTask> =
+  CLICKUP_TASK_BASE_SCHEMA.extend({
+    subtasks: z.lazy(() => CLICKUP_TASK_SCHEMA.array()).prefault([]),
+  })
+
+export const CLICKUP_COMMENT_SCHEMA = z.object({
+  assignee: CLICKUP_USER_SCHEMA.optional(),
+  comment: z.json().array().prefault([]),
+  commentText: z.string().optional(),
+  date: z.string(),
+  id: z.string(),
+  resolved: z.boolean().optional(),
+  user: CLICKUP_USER_SCHEMA,
+})
+
+export const CLICKUP_TIME_ENTRY_SCHEMA = z.object({
+  at: z.coerce.string().optional(),
+  billable: z.boolean().optional(),
+  description: z.string().optional(),
+  duration: z.coerce.string(),
+  end: z.coerce.string().optional(),
+  id: z.string(),
+  start: z.coerce.string(),
+  task: z
+    .object({ id: z.string(), name: z.string().optional() })
+    .nullable()
+    .optional(),
+  source: z.string().optional(),
+  tags: z.json().array().prefault([]),
+  taskLocation: z
+    .object({
+      folderId: z.union([z.number(), z.string()]).transform(String),
+      folderName: z.string(),
+      listId: z.union([z.number(), z.string()]).transform(String),
+      listName: z.string(),
+      spaceId: z.union([z.number(), z.string()]).transform(String),
+      spaceName: z.string(),
+    })
+    .optional(),
+  taskTags: z
+    .object({
+      creator: z.number().int().optional(),
+      name: z.string(),
+      tagBg: z.string().optional(),
+      tagFg: z.string().optional(),
+    })
+    .array()
+    .prefault([]),
+  taskUrl: z.url().optional(),
+  user: CLICKUP_USER_SCHEMA.optional(),
+  wid: z.string().optional(),
+})
+
+export const CLICKUP_KEY_RESULT_SCHEMA = z.object({
+  completed: z.boolean().optional(),
+  creator: z.number().int().optional(),
+  current: z.number().optional(),
+  dateCreated: z.string().optional(),
+  goalId: z.string().optional(),
+  goalPrettyId: z.string().optional(),
+  id: z.string(),
+  lastAction: z.json().optional(),
+  name: z.string(),
+  owners: CLICKUP_USER_SCHEMA.array().prefault([]),
+  percentCompleted: z.coerce.number().nullable().optional(),
+  subcategoryIds: z.string().array().prefault([]),
+  stepsCurrent: z.number().nullable().optional(),
+  stepsEnd: z.number().optional(),
+  stepsStart: z.number().optional(),
+  taskIds: z.string().array().prefault([]),
+  target: z.number().optional(),
+  type: z.string().optional(),
+  unit: z.string().optional(),
+})
+
+const CLICKUP_GOAL_BASE_SCHEMA = z.object({
+  archived: z.boolean().optional(),
+  color: z.string().optional(),
+  dateCreated: z.string().optional(),
+  description: z.string().optional(),
+  dueDate: z.string().nullable().optional(),
+  id: z.string(),
+  multipleOwners: z.boolean().optional(),
+  name: z.string(),
+  percentCompleted: z.number().optional(),
+  private: z.boolean().optional(),
+  teamId: z.string().optional(),
+})
+
+/** Goal shape returned by the Workspace Goal listing endpoint. */
+export const CLICKUP_GOAL_LIST_ITEM_SCHEMA = CLICKUP_GOAL_BASE_SCHEMA.extend({
+  keyResults: z.string().array().prefault([]),
+  owners: z.string().array().prefault([]),
+})
+
+/** Goal shape returned by get, create, and update endpoints. */
+export const CLICKUP_GOAL_SCHEMA = CLICKUP_GOAL_BASE_SCHEMA.extend({
+  keyResults: z.string().array().prefault([]),
+  owners: CLICKUP_USER_SCHEMA.array().prefault([]),
+})
+
+export const CLICKUP_HISTORY_ITEM_SCHEMA = z.object({
+  after: z.json().optional(),
+  before: z.json().optional(),
+  comment: z
+    .object({
+      comment: z.json().array().prefault([]),
+      date: z.string(),
+      id: z.string(),
+      parent: z.string().optional(),
+      textContent: z.string().optional(),
+      type: z.number().int().optional(),
+      user: CLICKUP_USER_SCHEMA,
+    })
+    .catchall(z.json())
+    .optional(),
+  customField: CLICKUP_CUSTOM_FIELD_SCHEMA.optional(),
+  data: z.json().optional(),
+  date: z.string(),
+  field: z.string().optional(),
+  id: z.string(),
+  parentId: z.string().optional(),
+  source: z.json().optional(),
+  type: z.number().int(),
+  user: CLICKUP_USER_SCHEMA.optional(),
+})
+
+export const CLICKUP_WEBHOOK_EVENT_NAMES = [
+  "taskCreated",
+  "taskUpdated",
+  "taskDeleted",
+  "taskPriorityUpdated",
+  "taskStatusUpdated",
+  "taskAssigneeUpdated",
+  "taskDueDateUpdated",
+  "taskTagUpdated",
+  "taskMoved",
+  "taskCommentPosted",
+  "taskCommentUpdated",
+  "taskTimeEstimateUpdated",
+  "taskTimeTrackedUpdated",
+  "listCreated",
+  "listUpdated",
+  "listDeleted",
+  "folderCreated",
+  "folderUpdated",
+  "folderDeleted",
+  "spaceCreated",
+  "spaceUpdated",
+  "spaceDeleted",
+  "goalCreated",
+  "goalUpdated",
+  "goalDeleted",
+  "keyResultCreated",
+  "keyResultUpdated",
+  "keyResultDeleted",
+] as const
+
+export const CLICKUP_WEBHOOK_EVENT_NAME_SCHEMA = z.enum(
+  CLICKUP_WEBHOOK_EVENT_NAMES,
+)
+
+export const CLICKUP_WEBHOOK_EVENT_SCHEMA = z.object({
+  data: z
+    .object({
+      description: z.string().optional(),
+      intervalId: z.string().optional(),
+    })
+    .catchall(z.json())
+    .optional(),
+  event: CLICKUP_WEBHOOK_EVENT_NAME_SCHEMA,
+  folderId: z.string().optional(),
+  goalId: z.string().optional(),
+  historyItems: CLICKUP_HISTORY_ITEM_SCHEMA.array().prefault([]),
+  keyResultId: z.string().optional(),
+  listId: z.string().optional(),
+  spaceId: z.string().optional(),
+  taskId: z.string().optional(),
+  webhookId: z.string(),
+})
+
+export const CLICKUP_TRIGGER_CONFIG_SCHEMA = z.object({
+  workspaceId: z.string().min(1),
+})

package/src/closebot/schemas.ts

@@ -3,8 +3,12 @@ import * as z from "zod"
 export const CLOSEBOT_ID_SCHEMA = z.string().trim().min(1)
 
 export const CLOSEBOT_DATE_SCHEMA = z
-  .union([z.date(), z.iso.datetime({ offset: true })])
-  .transform((value) => (value instanceof Date ? value : new Date(value)))
+  .union([z.date(), z.iso.datetime({ local: true, offset: true })])
+  .transform((value) =>
+    value instanceof Date
+      ? value
+      : new Date(/(?:Z|[+-]\d{2}:\d{2})$/.test(value) ? value : `${value}Z`),
+  )
 
 const OPTIONAL_STRING = z.string().nullable().optional()
 const OPTIONAL_BOOLEAN = z.boolean().optional()
@@ -187,7 +191,7 @@ export const CLOSEBOT_BOT_SCHEMA = z.object({
   modifiedBy: OPTIONAL_STRING,
   name: OPTIONAL_STRING,
   personaIds: z.string().array().nullable().optional(),
-  personaSplitTest: CLOSEBOT_PERSONA_SPLIT_TEST_SCHEMA.optional(),
+  personaSplitTest: CLOSEBOT_PERSONA_SPLIT_TEST_SCHEMA.nullable().optional(),
   personaWeights: z.record(z.string(), z.number().int()).nullable().optional(),
   reschedulingEnabled: OPTIONAL_BOOLEAN,
   smartFollowUp: OPTIONAL_BOOLEAN,

package/src/google-ads/api.ts

@@ -0,0 +1,151 @@
+import * as z from "zod"
+
+const GOOGLE_ADS_API_ORIGIN = "https://googleads.googleapis.com"
+const GOOGLE_ADS_API_VERSION = "v25"
+
+export const GOOGLE_ADS_CUSTOMER_ID_SCHEMA = z
+  .string()
+  .trim()
+  .regex(/^(?:\d{3}-?\d{3}-?\d{4})$/, "Enter a 10-digit customer ID.")
+  .transform((value) => value.replaceAll("-", ""))
+
+export const GOOGLE_ADS_RESOURCE_NAME_SCHEMA = z
+  .string()
+  .regex(/^customers\/\d{10}\/[A-Za-z][A-Za-z0-9]*(?:\/[^/]+)+$/)
+
+export const GOOGLE_ADS_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  developerToken: z.string().min(1),
+  tokenType: z.string().min(1),
+})
+
+const GOOGLE_ADS_FAILURE_SCHEMA = z.looseObject({
+  error: z
+    .looseObject({
+      code: z.number().int().optional(),
+      message: z.string().optional(),
+      status: z.string().optional(),
+    })
+    .optional(),
+})
+
+export interface GoogleAdsRequestOptions<TSchema extends z.ZodType> {
+  body?: z.input<ReturnType<typeof z.json>>
+  loginCustomerId?: string
+  method?: "GET" | "POST"
+  responseSchema: TSchema
+}
+
+interface GoogleAdsApiErrorOptions {
+  message?: string
+  providerStatus?: string
+  requestId?: string
+  retryAfter?: string
+  status: number
+}
+
+/** Structured Google Ads REST failure with correlation metadata. */
+export class GoogleAdsApiError extends Error {
+  readonly providerStatus?: string
+  readonly requestId?: string
+  readonly retryAfter?: string
+  readonly status: number
+
+  /** Creates a structured failure from one provider response. */
+  /** @param options - HTTP and Google Ads error metadata. */
+  constructor(options: GoogleAdsApiErrorOptions) {
+    super(
+      options.message ??
+        `Google Ads API request failed with status ${options.status}.`,
+    )
+    this.name = "GoogleAdsApiError"
+    this.providerStatus = options.providerStatus
+    this.requestId = options.requestId
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/** Creates an authenticated Google Ads v25 REST client. */
+/** @param secret - Resolved Google OAuth and platform developer credentials. */
+export function getGoogleAdsApi(secret: unknown) {
+  const credentials = GOOGLE_ADS_SECRET_SCHEMA.parse(secret)
+
+  return {
+    async request<TSchema extends z.ZodType>(
+      path: string,
+      options: GoogleAdsRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      const normalizedPath = path.replace(/^\/+/, "")
+      if (
+        !normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\")
+      ) {
+        throw new TypeError("Google Ads API paths must be relative.")
+      }
+      const url = new URL(
+        `${GOOGLE_ADS_API_VERSION}/${normalizedPath}`,
+        `${GOOGLE_ADS_API_ORIGIN}/`,
+      )
+      if (url.origin !== GOOGLE_ADS_API_ORIGIN) {
+        throw new TypeError(
+          "Google Ads API paths must remain on googleads.googleapis.com.",
+        )
+      }
+
+      const headers = new Headers({
+        Accept: "application/json",
+        Authorization: `${credentials.tokenType} ${credentials.accessToken}`,
+        "developer-token": credentials.developerToken,
+      })
+      if (options.loginCustomerId) {
+        headers.set(
+          "login-customer-id",
+          GOOGLE_ADS_CUSTOMER_ID_SCHEMA.parse(options.loginCustomerId),
+        )
+      }
+      if (options.body !== undefined) {
+        headers.set("Content-Type", "application/json")
+      }
+
+      const response = await fetch(url, {
+        body:
+          options.body === undefined ? undefined : JSON.stringify(options.body),
+        headers,
+        method: options.method ?? (options.body === undefined ? "GET" : "POST"),
+      })
+      const payload = parseGoogleAdsJson(await response.text())
+      if (!response.ok) {
+        const failure = GOOGLE_ADS_FAILURE_SCHEMA.safeParse(payload)
+        throw new GoogleAdsApiError({
+          message: failure.success ? failure.data.error?.message : undefined,
+          providerStatus: failure.success
+            ? failure.data.error?.status
+            : undefined,
+          requestId: response.headers.get("request-id") ?? undefined,
+          retryAfter: response.headers.get("retry-after") ?? undefined,
+          status: response.status,
+        })
+      }
+      return options.responseSchema.parse(payload)
+    },
+  }
+}
+
+/** Normalizes a Google Ads customer ID for paths and headers. */
+/** @param value - Dashed or compact 10-digit customer ID. */
+export function normalizeGoogleAdsCustomerId(value: string) {
+  return GOOGLE_ADS_CUSTOMER_ID_SCHEMA.parse(value)
+}
+
+/** Parses an optional Google Ads JSON response body. */
+/** @param value - Raw response body. */
+function parseGoogleAdsJson(value: string): unknown {
+  if (!value) return undefined
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}

package/src/google-ads/events.ts

@@ -0,0 +1,131 @@
+import type * as z from "zod"
+import {
+  GOOGLE_ADS_CHANGE_EVENT_PAYLOAD_SCHEMA,
+  GOOGLE_ADS_CHANGE_TRIGGER_CONFIG_SCHEMA,
+} from "./schemas"
+
+const changeContract = {
+  configSchema: GOOGLE_ADS_CHANGE_TRIGGER_CONFIG_SCHEMA,
+  eventSchema: GOOGLE_ADS_CHANGE_EVENT_PAYLOAD_SCHEMA,
+}
+
+export const googleAdsTriggerContracts = {
+  "googleAds.adGroup.created": changeContract,
+  "googleAds.adGroup.removed": changeContract,
+  "googleAds.adGroup.updated": changeContract,
+  "googleAds.adGroupAd.created": changeContract,
+  "googleAds.adGroupAd.removed": changeContract,
+  "googleAds.adGroupAd.updated": changeContract,
+  "googleAds.adGroupAsset.created": changeContract,
+  "googleAds.adGroupAsset.removed": changeContract,
+  "googleAds.adGroupAsset.updated": changeContract,
+  "googleAds.asset.created": changeContract,
+  "googleAds.asset.removed": changeContract,
+  "googleAds.asset.updated": changeContract,
+  "googleAds.campaign.created": changeContract,
+  "googleAds.campaign.removed": changeContract,
+  "googleAds.campaign.updated": changeContract,
+  "googleAds.campaignAsset.created": changeContract,
+  "googleAds.campaignAsset.removed": changeContract,
+  "googleAds.campaignAsset.updated": changeContract,
+  "googleAds.campaignBudget.created": changeContract,
+  "googleAds.campaignBudget.removed": changeContract,
+  "googleAds.campaignBudget.updated": changeContract,
+  "googleAds.change": changeContract,
+} as const
+
+export type GoogleAdsEventType = keyof typeof googleAdsTriggerContracts
+
+/**
+ * Returns the broad and optional semantic event types for one change.
+ *
+ * @param event - Normalized Google Ads change event.
+ */
+export function getGoogleAdsChangeEventTypes(
+  event: z.output<typeof GOOGLE_ADS_CHANGE_EVENT_PAYLOAD_SCHEMA>,
+): GoogleAdsEventType[] {
+  const semanticType = getSemanticEventType(
+    event.event.changeResourceType,
+    event.event.resourceChangeOperation,
+  )
+  return semanticType
+    ? ["googleAds.change", semanticType]
+    : ["googleAds.change"]
+}
+
+/**
+ * Maps provider resource and operation enums to public event types.
+ *
+ * @param resource - Provider change resource enum.
+ * @param operation - Provider mutation operation.
+ */
+function getSemanticEventType(
+  resource: z.output<
+    typeof GOOGLE_ADS_CHANGE_EVENT_PAYLOAD_SCHEMA
+  >["event"]["changeResourceType"],
+  operation: z.output<
+    typeof GOOGLE_ADS_CHANGE_EVENT_PAYLOAD_SCHEMA
+  >["event"]["resourceChangeOperation"],
+): GoogleAdsEventType | undefined {
+  if (operation === "UNSPECIFIED" || operation === "UNKNOWN") return undefined
+  switch (resource) {
+    case "AD_GROUP":
+      return (
+        {
+          CREATE: "googleAds.adGroup.created",
+          REMOVE: "googleAds.adGroup.removed",
+          UPDATE: "googleAds.adGroup.updated",
+        } as const
+      )[operation]
+    case "AD_GROUP_AD":
+      return (
+        {
+          CREATE: "googleAds.adGroupAd.created",
+          REMOVE: "googleAds.adGroupAd.removed",
+          UPDATE: "googleAds.adGroupAd.updated",
+        } as const
+      )[operation]
+    case "AD_GROUP_ASSET":
+      return (
+        {
+          CREATE: "googleAds.adGroupAsset.created",
+          REMOVE: "googleAds.adGroupAsset.removed",
+          UPDATE: "googleAds.adGroupAsset.updated",
+        } as const
+      )[operation]
+    case "ASSET":
+      return (
+        {
+          CREATE: "googleAds.asset.created",
+          REMOVE: "googleAds.asset.removed",
+          UPDATE: "googleAds.asset.updated",
+        } as const
+      )[operation]
+    case "CAMPAIGN":
+      return (
+        {
+          CREATE: "googleAds.campaign.created",
+          REMOVE: "googleAds.campaign.removed",
+          UPDATE: "googleAds.campaign.updated",
+        } as const
+      )[operation]
+    case "CAMPAIGN_ASSET":
+      return (
+        {
+          CREATE: "googleAds.campaignAsset.created",
+          REMOVE: "googleAds.campaignAsset.removed",
+          UPDATE: "googleAds.campaignAsset.updated",
+        } as const
+      )[operation]
+    case "CAMPAIGN_BUDGET":
+      return (
+        {
+          CREATE: "googleAds.campaignBudget.created",
+          REMOVE: "googleAds.campaignBudget.removed",
+          UPDATE: "googleAds.campaignBudget.updated",
+        } as const
+      )[operation]
+    default:
+      return undefined
+  }
+}

package/src/google-ads/index.ts

@@ -0,0 +1,3 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"