@automate.ax/integration-contracts 0.139.2 → 0.142.0

package/src/clickup/index.ts

@@ -0,0 +1,108 @@
+export * from "./api"
+export * from "./schemas"
+
+import * as z from "zod"
+import {
+  CLICKUP_TRIGGER_CONFIG_SCHEMA,
+  CLICKUP_WEBHOOK_EVENT_SCHEMA,
+} from "./schemas"
+
+export const CLICKUP_EVENT_TYPE_BY_PROVIDER_EVENT = {
+  folderCreated: "clickup.folder.created",
+  folderDeleted: "clickup.folder.deleted",
+  folderUpdated: "clickup.folder.updated",
+  goalCreated: "clickup.goal.created",
+  goalDeleted: "clickup.goal.deleted",
+  goalUpdated: "clickup.goal.updated",
+  keyResultCreated: "clickup.target.created",
+  keyResultDeleted: "clickup.target.deleted",
+  keyResultUpdated: "clickup.target.updated",
+  listCreated: "clickup.list.created",
+  listDeleted: "clickup.list.deleted",
+  listUpdated: "clickup.list.updated",
+  spaceCreated: "clickup.space.created",
+  spaceDeleted: "clickup.space.deleted",
+  spaceUpdated: "clickup.space.updated",
+  taskAssigneeUpdated: "clickup.task.assignee.updated",
+  taskCommentPosted: "clickup.task.comment.posted",
+  taskCommentUpdated: "clickup.task.comment.updated",
+  taskCreated: "clickup.task.created",
+  taskDeleted: "clickup.task.deleted",
+  taskDueDateUpdated: "clickup.task.due-date.updated",
+  taskMoved: "clickup.task.moved",
+  taskPriorityUpdated: "clickup.task.priority.updated",
+  taskStatusUpdated: "clickup.task.status.updated",
+  taskTagUpdated: "clickup.task.tag.updated",
+  taskTimeEstimateUpdated: "clickup.task.time-estimate.updated",
+  taskTimeTrackedUpdated: "clickup.task.time-tracked.updated",
+  taskUpdated: "clickup.task.updated",
+} as const
+
+/**
+ * Narrows the shared webhook payload to one provider event name.
+ *
+ * @param event - ClickUp provider event name.
+ */
+function semanticEventSchema<
+  const TEvent extends keyof typeof CLICKUP_EVENT_TYPE_BY_PROVIDER_EVENT,
+>(event: TEvent) {
+  return CLICKUP_WEBHOOK_EVENT_SCHEMA.extend({ event: z.literal(event) })
+}
+
+/**
+ * Creates one semantic ClickUp trigger contract.
+ *
+ * @param event - ClickUp provider event name.
+ */
+function semanticContract<
+  const TEvent extends keyof typeof CLICKUP_EVENT_TYPE_BY_PROVIDER_EVENT,
+>(event: TEvent) {
+  return {
+    configSchema: CLICKUP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: semanticEventSchema(event),
+  }
+}
+
+export const clickUpTriggerContracts = {
+  "clickup.workspace.event": {
+    configSchema: CLICKUP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CLICKUP_WEBHOOK_EVENT_SCHEMA,
+  },
+  "clickup.folder.created": semanticContract("folderCreated"),
+  "clickup.folder.deleted": semanticContract("folderDeleted"),
+  "clickup.folder.updated": semanticContract("folderUpdated"),
+  "clickup.goal.created": semanticContract("goalCreated"),
+  "clickup.goal.deleted": semanticContract("goalDeleted"),
+  "clickup.goal.updated": semanticContract("goalUpdated"),
+  "clickup.list.created": semanticContract("listCreated"),
+  "clickup.list.deleted": semanticContract("listDeleted"),
+  "clickup.list.updated": semanticContract("listUpdated"),
+  "clickup.space.created": semanticContract("spaceCreated"),
+  "clickup.space.deleted": semanticContract("spaceDeleted"),
+  "clickup.space.updated": semanticContract("spaceUpdated"),
+  "clickup.target.created": semanticContract("keyResultCreated"),
+  "clickup.target.deleted": semanticContract("keyResultDeleted"),
+  "clickup.target.updated": semanticContract("keyResultUpdated"),
+  "clickup.task.assignee.updated": semanticContract("taskAssigneeUpdated"),
+  "clickup.task.comment.posted": semanticContract("taskCommentPosted"),
+  "clickup.task.comment.updated": semanticContract("taskCommentUpdated"),
+  "clickup.task.created": semanticContract("taskCreated"),
+  "clickup.task.deleted": semanticContract("taskDeleted"),
+  "clickup.task.due-date.updated": semanticContract("taskDueDateUpdated"),
+  "clickup.task.moved": semanticContract("taskMoved"),
+  "clickup.task.priority.updated": semanticContract("taskPriorityUpdated"),
+  "clickup.task.status.updated": semanticContract("taskStatusUpdated"),
+  "clickup.task.tag.updated": semanticContract("taskTagUpdated"),
+  "clickup.task.time-estimate.updated": semanticContract(
+    "taskTimeEstimateUpdated",
+  ),
+  "clickup.task.time-tracked.updated": semanticContract(
+    "taskTimeTrackedUpdated",
+  ),
+  "clickup.task.updated": semanticContract("taskUpdated"),
+} as const
+
+export const CLICKUP_EVENT_TYPES = [
+  "clickup.workspace.event",
+  ...Object.values(CLICKUP_EVENT_TYPE_BY_PROVIDER_EVENT),
+] as const

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/api.ts

@@ -0,0 +1,157 @@
+import { isEncodable, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+const CLOSEBOT_API_ORIGIN = "https://api.closebot.com/"
+
+const CLOSEBOT_SECRET_SCHEMA = z.object({
+  apiKey: z.string().trim().min(1),
+})
+
+export const CLOSEBOT_VALUE_SCHEMA = z.custom<Encodable>(isEncodable, {
+  message: "Expected a codec-safe CloseBot value.",
+})
+
+export const CLOSEBOT_RESPONSE_SCHEMA = z.union([
+  CLOSEBOT_VALUE_SCHEMA,
+  z.undefined().transform(() => null),
+])
+
+interface CloseBotRequestOptions<TSchema extends z.ZodType> {
+  body?: Encodable | FormData
+  method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+  query?: Record<
+    string,
+    | boolean
+    | Date
+    | number
+    | string
+    | (boolean | Date | number | string)[]
+    | null
+    | undefined
+  >
+  responseSchema: TSchema
+}
+
+/** Error returned by a rejected CloseBot API request. */
+export class CloseBotApiError extends Error {
+  readonly details: Encodable
+  readonly retryAfter?: string
+  readonly status: number
+
+  /**
+   * Creates an error from a rejected CloseBot response.
+   *
+   * @param status - HTTP response status.
+   * @param details - Codec-safe response details.
+   * @param retryAfter - Raw provider retry timing, when present.
+   */
+  constructor(status: number, details: Encodable, retryAfter?: string) {
+    super(`CloseBot API request failed (${status}).`)
+    this.name = "CloseBotApiError"
+    this.details = details
+    this.retryAfter = retryAfter
+    this.status = status
+  }
+}
+
+/**
+ * Creates an authenticated CloseBot REST API client.
+ *
+ * @param secret - Stored CloseBot API key.
+ */
+export function getCloseBotApi(secret: unknown) {
+  const { apiKey } = CLOSEBOT_SECRET_SCHEMA.parse(secret)
+  const root = new URL(CLOSEBOT_API_ORIGIN)
+
+  return {
+    /**
+     * Sends one JSON request to a CloseBot API path.
+     *
+     * @param path - Relative path below the CloseBot API origin.
+     * @param options - Request method, query, body, and response schema.
+     */
+    async request<TSchema extends z.ZodType>(
+      path: string,
+      options: CloseBotRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      const normalizedPath = path.replace(/^\/+/, "")
+      if (
+        !normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\")
+      ) {
+        throw new TypeError("CloseBot API paths must be relative.")
+      }
+
+      const url = new URL(normalizedPath, root)
+      if (url.origin !== root.origin) {
+        throw new TypeError(
+          "CloseBot API paths must remain on api.closebot.com.",
+        )
+      }
+      for (const [key, value] of Object.entries(options.query ?? {})) {
+        if (value == null) continue
+        if (Array.isArray(value)) {
+          for (const item of value)
+            url.searchParams.append(key, queryValue(item))
+        } else {
+          url.searchParams.set(key, queryValue(value))
+        }
+      }
+
+      const headers = new Headers({
+        Accept: "application/json",
+        "X-CB-KEY": apiKey,
+      })
+      if (options.body !== undefined && !(options.body instanceof FormData)) {
+        headers.set("Content-Type", "application/json")
+      }
+
+      const response = await fetch(url, {
+        body:
+          options.body === undefined
+            ? undefined
+            : options.body instanceof FormData
+              ? options.body
+              : JSON.stringify(options.body),
+        headers,
+        method: options.method ?? "GET",
+        redirect: "error",
+      })
+      const text = await response.text()
+      const parsed = CLOSEBOT_RESPONSE_SCHEMA.safeParse(
+        text ? parseJson(text) : null,
+      )
+      if (!response.ok || !parsed.success) {
+        throw new CloseBotApiError(
+          response.status,
+          parsed.success ? parsed.data : { response: text },
+          response.headers.get("Retry-After") ?? undefined,
+        )
+      }
+      return options.responseSchema.parse(parsed.data)
+    },
+  }
+}
+
+/**
+ * Parses a response while retaining non-JSON provider diagnostics.
+ *
+ * @param value - Raw response body.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+/**
+ * Serializes one supported query value.
+ *
+ * @param value - Public query value.
+ */
+function queryValue(value: boolean | Date | number | string) {
+  return value instanceof Date ? value.toISOString() : String(value)
+}

package/src/closebot/index.ts

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