@automate.ax/integration-contracts 0.55.0

package/src/trello/api.ts

@@ -0,0 +1,190 @@
+import { z } from "zod"
+
+const TRELLO_API_BASE_URL = "https://api.trello.com/1/"
+const TRELLO_API_ORIGIN = new URL(TRELLO_API_BASE_URL).origin
+const TRELLO_SECRET_SCHEMA = z.object({
+  apiKey: z.string().min(1),
+  token: z.string().min(1),
+})
+const TRELLO_ERROR_SCHEMA = z.looseObject({
+  message: z.string().optional(),
+})
+
+/** Scalar value serialized into one Trello query parameter. */
+type TrelloQueryValue = boolean | number | string | undefined
+
+/** Options for one authenticated Trello REST request. */
+export interface TrelloRequestOptions<TSchema extends z.ZodType> {
+  /** JSON request body for endpoints that accept one. */
+  body?: unknown
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "DELETE" | "GET" | "POST" | "PUT"
+
+  /** Query parameters appended to the request URL. */
+  query?: Record<string, TrelloQueryValue>
+
+  /** Schema that validates and types the successful response. */
+  responseSchema: TSchema
+}
+
+/** Authenticated raw Trello REST helper. */
+export interface TrelloApi {
+  /**
+   * Calls any Trello REST endpoint and validates its successful response.
+   *
+   * @param path - Relative path below Trello's `/1` API root.
+   * @param options - Request data and successful response schema.
+   */
+  request<TSchema extends z.ZodType>(
+    path: string,
+    options: TrelloRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>>
+}
+
+/** Structured Trello REST request error. */
+export class TrelloApiError extends Error {
+  /** Provider error body, when Trello returned text. */
+  readonly providerMessage?: string
+
+  /** Retry delay from Trello's `Retry-After` header, in seconds. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Trello. */
+  readonly status: number
+
+  /**
+   * Creates a structured Trello API error.
+   *
+   * @param options - Provider and transport error details.
+   * @param options.providerMessage - Provider error body.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    providerMessage?: string
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      options.providerMessage
+        ? `Trello API error (${options.status}): ${options.providerMessage}`
+        : `Trello API request failed with status ${options.status}.`,
+    )
+    this.name = "TrelloApiError"
+    this.providerMessage = options.providerMessage
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates a raw authenticated Trello REST helper.
+ *
+ * Use this escape hatch for provider endpoints that do not yet have a packaged
+ * action. Trello authenticates requests with the integration API key and user
+ * token, and the caller supplies a response schema for boundary validation.
+ *
+ * @param secret - Resolved Trello integration secret.
+ */
+export function getTrelloApi(secret: Record<string, unknown>): TrelloApi {
+  const { apiKey, token } = TRELLO_SECRET_SCHEMA.parse(secret)
+
+  return {
+    request: async (path, options) => {
+      const url = new URL(path.replace(/^\//, ""), TRELLO_API_BASE_URL)
+      if (url.origin !== TRELLO_API_ORIGIN) {
+        throw new Error("Trello API paths must use the Trello API origin.")
+      }
+      for (const [name, value] of Object.entries(options.query ?? {})) {
+        if (value !== undefined) url.searchParams.set(name, String(value))
+      }
+      url.searchParams.set("key", apiKey)
+      url.searchParams.set("token", token)
+
+      const headers = new Headers({ Accept: "application/json" })
+      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 ?? "GET",
+      })
+      if (!response.ok) {
+        const responseText = await response.text()
+        const error = TRELLO_ERROR_SCHEMA.safeParse(parseJson(responseText))
+        throw new TrelloApiError({
+          providerMessage:
+            error.success && error.data.message
+              ? error.data.message
+              : responseText || undefined,
+          retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+          status: response.status,
+        })
+      }
+      return options.responseSchema.parse(await response.json())
+    },
+  }
+}
+
+/**
+ * Accepts a raw card ID, short link, or standard Trello card URL.
+ *
+ * @param card - Card reference to normalize.
+ */
+export function normalizeTrelloCardId(card: string) {
+  return normalizeTrelloUrlReference(card, "c")
+}
+
+/**
+ * Accepts a raw board ID, short link, or standard Trello board URL.
+ *
+ * @param board - Board reference to normalize.
+ */
+export function normalizeTrelloBoardId(board: string) {
+  return normalizeTrelloUrlReference(board, "b")
+}
+
+/**
+ * Extracts a Trello short link from one recognized provider URL.
+ *
+ * @param value - Raw resource reference.
+ * @param resource - Expected Trello URL resource segment.
+ */
+function normalizeTrelloUrlReference(value: string, resource: "b" | "c") {
+  const trimmed = value.trim()
+  if (!URL.canParse(trimmed)) return trimmed
+
+  const url = new URL(trimmed)
+  if (url.hostname !== "trello.com" && url.hostname !== "www.trello.com") {
+    return trimmed
+  }
+  const parts = url.pathname.split("/").filter(Boolean)
+  const resourceIndex = parts.indexOf(resource)
+  return resourceIndex === -1 ? trimmed : (parts[resourceIndex + 1] ?? trimmed)
+}
+
+/**
+ * Parses an optional provider JSON error body without masking the HTTP error.
+ *
+ * @param value - Raw provider response text.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses Trello'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/trello/event-schemas.ts

@@ -0,0 +1,290 @@
+import { z } from "zod"
+
+const TRELLO_JSON_OBJECT_SCHEMA = z.record(z.string(), z.json())
+const TRELLO_RESOURCE_SCHEMA = z
+  .looseObject({
+    id: z.string(),
+    name: z.string().optional(),
+  })
+  .catchall(z.json())
+const TRELLO_BOARD_SCHEMA = TRELLO_RESOURCE_SCHEMA.extend({
+  closed: z.boolean().optional(),
+  url: z.string().optional(),
+})
+const TRELLO_CARD_SCHEMA = TRELLO_RESOURCE_SCHEMA.extend({
+  closed: z.boolean().optional(),
+  idShort: z.number().int().optional(),
+  shortLink: z.string().optional(),
+})
+const TRELLO_LIST_SCHEMA = TRELLO_RESOURCE_SCHEMA
+const TRELLO_MEMBER_SCHEMA = TRELLO_RESOURCE_SCHEMA.extend({
+  fullName: z.string().optional(),
+  username: z.string().optional(),
+})
+const TRELLO_ACTION_DATA_SCHEMA = z
+  .looseObject({
+    /** Attachment affected by the action, when applicable. */
+    attachment: TRELLO_RESOURCE_SCHEMA.extend({
+      url: z.string().optional(),
+    }).optional(),
+
+    /** Board affected by the action. */
+    board: TRELLO_BOARD_SCHEMA.optional(),
+
+    /** Card affected by the action, when applicable. */
+    card: TRELLO_CARD_SCHEMA.optional(),
+
+    /** Checklist affected by the action, when applicable. */
+    checklist: TRELLO_RESOURCE_SCHEMA.optional(),
+
+    /** Checklist item affected by the action, when applicable. */
+    checkItem: TRELLO_RESOURCE_SCHEMA.optional(),
+
+    /** List associated with the action. */
+    list: TRELLO_LIST_SCHEMA.optional(),
+
+    /** Destination list for a move action. */
+    listAfter: TRELLO_LIST_SCHEMA.optional(),
+
+    /** Source list for a move action. */
+    listBefore: TRELLO_LIST_SCHEMA.optional(),
+
+    /** Member affected by the action, when applicable. */
+    member: TRELLO_MEMBER_SCHEMA.optional(),
+
+    /** Previous field values supplied for an update action. */
+    old: TRELLO_JSON_OBJECT_SCHEMA.optional(),
+
+    /** Organization affected by the action, when applicable. */
+    organization: TRELLO_RESOURCE_SCHEMA.optional(),
+
+    /** Comment or other action text. */
+    text: z.string().optional(),
+  })
+  .catchall(z.json())
+const TRELLO_CARD_ACTION_DATA_SCHEMA = TRELLO_ACTION_DATA_SCHEMA.extend({
+  old: z
+    .looseObject({ closed: z.boolean().optional() })
+    .catchall(z.json())
+    .optional(),
+})
+
+const TRELLO_WEBHOOK_EVENT_SCHEMA = z.object({
+  action: z
+    .looseObject({
+      data: TRELLO_ACTION_DATA_SCHEMA,
+      date: z.iso.datetime({ offset: true }),
+      id: z.string(),
+      memberCreator: TRELLO_MEMBER_SCHEMA.optional(),
+      type: z.string(),
+    })
+    .catchall(z.json()),
+  model: TRELLO_BOARD_SCHEMA,
+  webhook: z.looseObject({ id: z.string() }).catchall(z.json()),
+})
+const TRELLO_CARD_CREATED_ACTION_SCHEMA = z.enum([
+  "copyCard",
+  "convertToCardFromCheckItem",
+  "createCard",
+  "emailCard",
+])
+const TRELLO_CARD_UPDATED_ACTION_SCHEMA = z.literal("updateCard")
+const TRELLO_CARD_COMMENTED_ACTION_SCHEMA = z.literal("commentCard")
+
+export const TRELLO_CARD_EVENT_KINDS = [
+  "created",
+  "moved",
+  "updated",
+  "archived",
+  "commented",
+] as const
+
+export type TrelloCardEventKind = (typeof TRELLO_CARD_EVENT_KINDS)[number]
+
+export const TRELLO_BOARD_EVENT_SCHEMA = TRELLO_ACTION_DATA_SCHEMA.extend({
+  /** Stable ID of the Trello action that caused this event. */
+  actionId: z.string(),
+
+  /** Trello action category, such as `createCard` or `updateCard`. */
+  actionType: z.string(),
+
+  /** Board affected by the action, falling back to the watched board. */
+  board: TRELLO_BOARD_SCHEMA,
+
+  /** Complete provider webhook envelope. */
+  event: TRELLO_WEBHOOK_EVENT_SCHEMA,
+
+  /** Member responsible for the action, when Trello includes one. */
+  memberCreator: TRELLO_MEMBER_SCHEMA.optional(),
+
+  /** When the underlying Trello action occurred. */
+  occurredAt: z.iso.datetime({ offset: true }),
+
+  /** Provider webhook that delivered the event. */
+  webhookId: z.string(),
+})
+
+export const TRELLO_CARD_EVENT_SCHEMA = z.object({
+  /** Stable ID of the Trello action that caused this event. */
+  actionId: z.string(),
+
+  /** Provider-native Trello action category. */
+  actionType: z.string(),
+
+  /** Board containing the affected card. */
+  board: TRELLO_BOARD_EVENT_SCHEMA.shape.board,
+
+  /** Card affected by the action. */
+  card: TRELLO_CARD_SCHEMA,
+
+  /** Comment text for card-comment events. */
+  commentText: z.string().optional(),
+
+  /** Complete provider webhook envelope. */
+  event: TRELLO_WEBHOOK_EVENT_SCHEMA,
+
+  /** List containing the card after the action. */
+  list: TRELLO_LIST_SCHEMA.optional(),
+
+  /** Member responsible for the action, when supplied by Trello. */
+  memberCreator: TRELLO_BOARD_EVENT_SCHEMA.shape.memberCreator,
+
+  /** When the underlying Trello action occurred. */
+  occurredAt: z.iso.datetime({ offset: true }),
+
+  /** List containing the card before a move. */
+  previousList: TRELLO_LIST_SCHEMA.optional(),
+})
+
+export const TRELLO_CARD_CREATED_EVENT_SCHEMA = TRELLO_CARD_EVENT_SCHEMA.extend(
+  {
+    actionType: TRELLO_CARD_CREATED_ACTION_SCHEMA,
+    event: trelloWebhookEventSchema(TRELLO_CARD_CREATED_ACTION_SCHEMA),
+  },
+)
+
+export const TRELLO_CARD_MOVED_EVENT_SCHEMA = TRELLO_CARD_EVENT_SCHEMA.extend({
+  actionType: TRELLO_CARD_UPDATED_ACTION_SCHEMA,
+  event: trelloWebhookEventSchema(TRELLO_CARD_UPDATED_ACTION_SCHEMA),
+  list: TRELLO_LIST_SCHEMA,
+  previousList: TRELLO_LIST_SCHEMA,
+})
+
+export const TRELLO_CARD_UPDATED_EVENT_SCHEMA = TRELLO_CARD_EVENT_SCHEMA.extend(
+  {
+    actionType: TRELLO_CARD_UPDATED_ACTION_SCHEMA,
+    event: trelloWebhookEventSchema(TRELLO_CARD_UPDATED_ACTION_SCHEMA),
+  },
+)
+
+export const TRELLO_CARD_ARCHIVED_EVENT_SCHEMA =
+  TRELLO_CARD_UPDATED_EVENT_SCHEMA.extend({
+    card: TRELLO_CARD_SCHEMA.extend({ closed: z.literal(true) }),
+  })
+
+export const TRELLO_CARD_COMMENTED_EVENT_SCHEMA =
+  TRELLO_CARD_EVENT_SCHEMA.extend({
+    actionType: TRELLO_CARD_COMMENTED_ACTION_SCHEMA,
+    commentText: z.string(),
+    event: trelloWebhookEventSchema(TRELLO_CARD_COMMENTED_ACTION_SCHEMA),
+  })
+
+/**
+ * Normalizes one provider-native Trello board webhook payload.
+ *
+ * @param value - Untrusted Trello webhook body.
+ */
+export function normalizeTrelloBoardEvent(value: unknown) {
+  const event = TRELLO_WEBHOOK_EVENT_SCHEMA.parse(value)
+
+  return TRELLO_BOARD_EVENT_SCHEMA.parse({
+    ...event.action.data,
+    actionId: event.action.id,
+    actionType: event.action.type,
+    board: { ...event.model, ...event.action.data.board },
+    event,
+    memberCreator: event.action.memberCreator,
+    occurredAt: event.action.date,
+    webhookId: event.webhook.id,
+  })
+}
+
+/**
+ * Classifies one normalized board action into semantic card event categories.
+ *
+ * A single Trello action can intentionally belong to more than one category;
+ * for example, moving a card is also a card update.
+ *
+ * @param event - Normalized board event received from Trello.
+ */
+export function getTrelloCardEventKinds(
+  event: z.output<typeof TRELLO_BOARD_EVENT_SCHEMA>,
+): TrelloCardEventKind[] {
+  const data = TRELLO_CARD_ACTION_DATA_SCHEMA.parse(event.event.action.data)
+
+  return [
+    ...([
+      "createCard",
+      "copyCard",
+      "convertToCardFromCheckItem",
+      "emailCard",
+    ].includes(event.actionType)
+      ? (["created"] as const)
+      : []),
+    ...(event.actionType === "updateCard" &&
+    data.listBefore !== undefined &&
+    data.listAfter !== undefined
+      ? (["moved"] as const)
+      : []),
+    ...(event.actionType === "updateCard" ? (["updated"] as const) : []),
+    ...(event.actionType === "updateCard" &&
+    data.old?.closed === false &&
+    data.card?.closed === true
+      ? (["archived"] as const)
+      : []),
+    ...(event.actionType === "commentCard" ? (["commented"] as const) : []),
+  ]
+}
+
+/**
+ * Promotes provider-native card action data into the stable semantic payload.
+ *
+ * @param event - Normalized board event classified as a card event.
+ * @throws When the classified Trello action does not identify a card.
+ */
+export function normalizeTrelloCardEvent(
+  event: z.output<typeof TRELLO_BOARD_EVENT_SCHEMA>,
+) {
+  const data = TRELLO_CARD_ACTION_DATA_SCHEMA.parse(event.event.action.data)
+  if (!data.card) {
+    throw new Error(`Trello ${event.actionType} action did not include a card.`)
+  }
+
+  return TRELLO_CARD_EVENT_SCHEMA.parse({
+    actionId: event.actionId,
+    actionType: event.actionType,
+    board: event.board,
+    card: data.card,
+    commentText: data.text,
+    event: event.event,
+    list: data.listAfter ?? data.list,
+    memberCreator: event.memberCreator,
+    occurredAt: event.occurredAt,
+    previousList: data.listBefore,
+  })
+}
+
+/**
+ * Narrows the provider action type retained under a semantic event.
+ *
+ * @param actionType - Provider action-type schema for the semantic event.
+ */
+function trelloWebhookEventSchema<TAction extends z.ZodType<string>>(
+  actionType: TAction,
+) {
+  return TRELLO_WEBHOOK_EVENT_SCHEMA.extend({
+    action: TRELLO_WEBHOOK_EVENT_SCHEMA.shape.action.extend({
+      type: actionType,
+    }),
+  })
+}

package/src/trello/index.ts

@@ -0,0 +1,45 @@
+import { z } from "zod"
+import {
+  TRELLO_BOARD_EVENT_SCHEMA,
+  TRELLO_CARD_ARCHIVED_EVENT_SCHEMA,
+  TRELLO_CARD_COMMENTED_EVENT_SCHEMA,
+  TRELLO_CARD_CREATED_EVENT_SCHEMA,
+  TRELLO_CARD_MOVED_EVENT_SCHEMA,
+  TRELLO_CARD_UPDATED_EVENT_SCHEMA,
+} from "./event-schemas"
+
+export * from "./api"
+export * from "./event-schemas"
+export * from "./schemas"
+
+/** Canonical Trello board selected by one webhook subscription. */
+export const TRELLO_TRIGGER_CONFIG_SCHEMA = z.object({
+  boardId: z.string(),
+})
+
+export const trelloTriggerContracts = {
+  "trello.board.event": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_BOARD_EVENT_SCHEMA,
+  },
+  "trello.card.archived": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_CARD_ARCHIVED_EVENT_SCHEMA,
+  },
+  "trello.card.commented": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_CARD_COMMENTED_EVENT_SCHEMA,
+  },
+  "trello.card.created": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_CARD_CREATED_EVENT_SCHEMA,
+  },
+  "trello.card.moved": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_CARD_MOVED_EVENT_SCHEMA,
+  },
+  "trello.card.updated": {
+    configSchema: TRELLO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TRELLO_CARD_UPDATED_EVENT_SCHEMA,
+  },
+} as const