@automate.ax/integration-contracts 0.55.0

package/src/teams/graph.ts

@@ -0,0 +1,130 @@
+import { z } from "zod"
+
+const GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0/"
+const MICROSOFT_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const GRAPH_ERROR_SCHEMA = z.looseObject({
+  error: z
+    .looseObject({
+      code: z.string().optional(),
+      message: z.string().optional(),
+    })
+    .optional(),
+})
+
+/** Options accepted by the authenticated Teams Graph request helper. */
+export interface TeamsGraphRequestOptions {
+  /** JSON-serializable request body. */
+  body?: unknown
+
+  /** Additional HTTP headers. */
+  headers?: RequestInit["headers"]
+
+  /** HTTP method. */
+  method?: string
+}
+
+/**
+ * Creates a small authenticated Microsoft Graph client for Teams APIs.
+ *
+ * The raw `fetch` method is an escape hatch for Graph operations not yet
+ * represented by a built-in action.
+ *
+ * @param secret - Refreshed Microsoft OAuth integration secret.
+ */
+export function getTeamsGraphApi(secret: Record<string, unknown>) {
+  const { accessToken } = MICROSOFT_SECRET_SCHEMA.parse(secret)
+
+  /**
+   * Performs one authenticated Graph request.
+   *
+   * @param path - Relative or absolute Microsoft Graph URL.
+   * @param init - Standard fetch request options.
+   */
+  async function graphFetch(path: string, init?: RequestInit) {
+    const headers = new Headers(init?.headers)
+    headers.set("Accept", "application/json")
+    headers.set("Authorization", `Bearer ${accessToken}`)
+    return fetch(new URL(path.replace(/^\//, ""), GRAPH_BASE_URL), {
+      ...init,
+      headers,
+    })
+  }
+
+  /**
+   * Performs one authenticated Graph JSON request.
+   *
+   * @param path - Relative or absolute Microsoft Graph URL.
+   * @param options - HTTP method, body, and headers.
+   */
+  async function request(
+    path: string,
+    options: TeamsGraphRequestOptions = {},
+  ): Promise<unknown> {
+    const headers = new Headers(options.headers)
+    if (options.body !== undefined) {
+      headers.set("Content-Type", "application/json")
+    }
+    const response = await graphFetch(path, {
+      body:
+        options.body === undefined ? undefined : JSON.stringify(options.body),
+      headers,
+      method: options.method,
+    })
+
+    if (!response.ok) {
+      const payload = GRAPH_ERROR_SCHEMA.safeParse(
+        await response.json().catch(() => undefined),
+      )
+      const graphError = payload.success ? payload.data.error : undefined
+      const detail = [graphError?.code, graphError?.message]
+        .filter(Boolean)
+        .join(": ")
+      throw new Error(
+        `Microsoft Graph request failed with ${response.status} ${response.statusText}${detail ? `: ${detail}` : ""}.`,
+      )
+    }
+
+    if (response.status === 202 || response.status === 204) return undefined
+    return response.json()
+  }
+
+  return {
+    /** Performs an authenticated request and returns the raw Response. */
+    fetch: graphFetch,
+
+    /** Performs an authenticated request and returns its untrusted JSON value. */
+    request,
+  }
+}
+
+/**
+ * Reads Graph collection pages until the requested limit is reached.
+ *
+ * @param request - Authenticated Graph JSON request function.
+ * @param path - Initial relative Graph path.
+ * @param itemSchema - Schema for one collection item.
+ * @param limit - Maximum total items.
+ */
+export async function listTeamsGraphCollection<T>(
+  request: (path: string) => Promise<unknown>,
+  path: string,
+  itemSchema: z.ZodType<T>,
+  limit: number,
+) {
+  const pageSchema = z.object({
+    "@odata.nextLink": z.string().optional(),
+    value: itemSchema.array(),
+  })
+  const items: T[] = []
+  let nextPath: string | undefined = path
+
+  while (nextPath && items.length < limit) {
+    const page = pageSchema.parse(await request(nextPath))
+    items.push(...page.value)
+    nextPath = page["@odata.nextLink"]
+  }
+
+  return items.slice(0, limit)
+}

package/src/teams/index.ts

@@ -0,0 +1,27 @@
+import { z } from "zod"
+import {
+  TEAMS_CHANNEL_MESSAGE_POSTED_EVENT_SCHEMA,
+  TEAMS_CHAT_MESSAGE_POSTED_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./graph"
+export * from "./schemas"
+
+export const TEAMS_CHANNEL_TRIGGER_CONFIG_SCHEMA = z.object({
+  channel: z.string().trim().min(1),
+  team: z.string().trim().min(1),
+})
+export const TEAMS_CHAT_TRIGGER_CONFIG_SCHEMA = z.object({
+  chatId: z.string().min(1),
+})
+
+export const teamsTriggerContracts = {
+  "teams.channel.message.posted": {
+    configSchema: TEAMS_CHANNEL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TEAMS_CHANNEL_MESSAGE_POSTED_EVENT_SCHEMA,
+  },
+  "teams.chat.message.posted": {
+    configSchema: TEAMS_CHAT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TEAMS_CHAT_MESSAGE_POSTED_EVENT_SCHEMA,
+  },
+} as const

package/src/teams/schemas.ts

@@ -0,0 +1,463 @@
+import { z } from "zod"
+
+const OPTIONAL_DATE_SCHEMA = z
+  .union([
+    z.date(),
+    z.iso.datetime({ offset: true }).transform((value) => new Date(value)),
+  ])
+  .nullish()
+  .transform((value) => value ?? undefined)
+const OPTIONAL_STRING_SCHEMA = z
+  .string()
+  .nullish()
+  .transform((value) => value ?? undefined)
+
+export const TEAMS_TEAM_SCHEMA = z.object({
+  /** Whether the team is archived. */
+  isArchived: z.boolean().prefault(false),
+
+  /** Team classification assigned by the organization. */
+  classification: OPTIONAL_STRING_SCHEMA,
+
+  /** Team description. */
+  description: OPTIONAL_STRING_SCHEMA,
+
+  /** Human-readable team name. */
+  displayName: z.string(),
+
+  /** Opaque Microsoft team identifier. */
+  teamId: z.string(),
+
+  /** Team specialization, when configured. */
+  specialization: OPTIONAL_STRING_SCHEMA,
+
+  /** Team visibility. */
+  visibility: z
+    .enum(["private", "public", "hiddenMembership", "unknownFutureValue"])
+    .nullish()
+    .transform((value) => value ?? undefined),
+
+  /** Microsoft Teams web URL. */
+  webUrl: OPTIONAL_STRING_SCHEMA,
+})
+
+export const GRAPH_TEAM_SCHEMA = z
+  .looseObject({
+    classification: z.string().nullish(),
+    description: z.string().nullish(),
+    displayName: z.string(),
+    id: z.string(),
+    isArchived: z.boolean().optional(),
+    specialization: z.string().nullish(),
+    visibility: z
+      .enum(["private", "public", "hiddenMembership", "unknownFutureValue"])
+      .nullish(),
+    webUrl: z.string().nullish(),
+  })
+  .transform((team) => TEAMS_TEAM_SCHEMA.parse({ ...team, teamId: team.id }))
+
+export const TEAMS_CHANNEL_SCHEMA = z.object({
+  /** Time the channel was created. */
+  createdAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Channel description. */
+  description: OPTIONAL_STRING_SCHEMA,
+
+  /** Human-readable channel name. */
+  displayName: z.string(),
+
+  /** Email address assigned to the channel. */
+  email: OPTIONAL_STRING_SCHEMA,
+
+  /** Opaque Microsoft channel identifier. */
+  channelId: z.string(),
+
+  /** Whether the channel is archived. */
+  isArchived: z.boolean().prefault(false),
+
+  /** Standard, private, or shared membership model. */
+  membershipType: z
+    .enum(["standard", "private", "shared", "unknownFutureValue"])
+    .nullish()
+    .transform((value) => value ?? undefined),
+
+  /** Microsoft Teams web URL. */
+  webUrl: OPTIONAL_STRING_SCHEMA,
+})
+
+export const GRAPH_CHANNEL_SCHEMA = z
+  .looseObject({
+    createdDateTime: z.string().nullish(),
+    description: z.string().nullish(),
+    displayName: z.string(),
+    email: z.string().nullish(),
+    id: z.string(),
+    isArchived: z.boolean().optional(),
+    membershipType: z
+      .enum(["standard", "private", "shared", "unknownFutureValue"])
+      .nullish(),
+    webUrl: z.string().nullish(),
+  })
+  .transform((channel) =>
+    TEAMS_CHANNEL_SCHEMA.parse({
+      ...channel,
+      channelId: channel.id,
+      createdAt: channel.createdDateTime,
+    }),
+  )
+
+export const TEAMS_MEMBER_SCHEMA = z.object({
+  /** Member display name. */
+  displayName: OPTIONAL_STRING_SCHEMA,
+
+  /** Member email address, when Graph exposes it. */
+  email: OPTIONAL_STRING_SCHEMA,
+
+  /** Opaque conversation membership identifier. */
+  memberId: z.string(),
+
+  /** Membership roles such as `owner`. */
+  roles: z.string().array().prefault([]),
+
+  /** Microsoft Entra tenant identifier. */
+  tenantId: OPTIONAL_STRING_SCHEMA,
+
+  /** Microsoft Entra user identifier, when the member is a user. */
+  userId: OPTIONAL_STRING_SCHEMA,
+
+  /** Earliest history visible to this member. */
+  visibleHistoryStartAt: OPTIONAL_DATE_SCHEMA,
+})
+
+export const GRAPH_MEMBER_SCHEMA = z
+  .looseObject({
+    displayName: z.string().nullish(),
+    email: z.string().nullish(),
+    id: z.string(),
+    roles: z.string().array().optional(),
+    tenantId: z.string().nullish(),
+    userId: z.string().nullish(),
+    visibleHistoryStartDateTime: z.string().nullish(),
+  })
+  .transform((member) =>
+    TEAMS_MEMBER_SCHEMA.parse({
+      ...member,
+      memberId: member.id,
+      visibleHistoryStartAt: member.visibleHistoryStartDateTime,
+    }),
+  )
+
+export const TEAMS_CHAT_SCHEMA = z.object({
+  /** Chat kind. */
+  chatType: z.enum(["oneOnOne", "group", "meeting", "unknownFutureValue"]),
+
+  /** Time the chat was created. */
+  createdAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Opaque Microsoft chat identifier. */
+  chatId: z.string(),
+
+  /** Time the chat was last updated. */
+  updatedAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Microsoft Entra tenant identifier. */
+  tenantId: OPTIONAL_STRING_SCHEMA,
+
+  /** Optional group-chat or meeting topic. */
+  topic: OPTIONAL_STRING_SCHEMA,
+
+  /** Microsoft Teams web URL. */
+  webUrl: OPTIONAL_STRING_SCHEMA,
+})
+
+export const GRAPH_CHAT_SCHEMA = z
+  .looseObject({
+    chatType: z.enum(["oneOnOne", "group", "meeting", "unknownFutureValue"]),
+    createdDateTime: z.string().nullish(),
+    id: z.string(),
+    lastUpdatedDateTime: z.string().nullish(),
+    tenantId: z.string().nullish(),
+    topic: z.string().nullish(),
+    webUrl: z.string().nullish(),
+  })
+  .transform((chat) =>
+    TEAMS_CHAT_SCHEMA.parse({
+      ...chat,
+      chatId: chat.id,
+      createdAt: chat.createdDateTime,
+      updatedAt: chat.lastUpdatedDateTime,
+    }),
+  )
+
+export const TEAMS_MESSAGE_BODY_SCHEMA = z.object({
+  /** Message content. */
+  content: z.string(),
+
+  /** Plain text or HTML content type. */
+  contentType: z.enum(["text", "html"]),
+})
+
+const TEAMS_MESSAGE_FROM_SCHEMA = z.object({
+  /** Application identifier, when sent by an app. */
+  applicationId: OPTIONAL_STRING_SCHEMA,
+
+  /** Device identifier, when sent by a device. */
+  deviceId: OPTIONAL_STRING_SCHEMA,
+
+  /** Display name supplied by Teams. */
+  displayName: OPTIONAL_STRING_SCHEMA,
+
+  /** Microsoft Entra user identifier, when sent by a user. */
+  userId: OPTIONAL_STRING_SCHEMA,
+})
+
+const TEAMS_MESSAGE_ATTACHMENT_SCHEMA = z.object({
+  /** Provider attachment identifier. */
+  attachmentId: z.string(),
+
+  /** Attachment content or card JSON. */
+  content: OPTIONAL_STRING_SCHEMA,
+
+  /** MIME media type or Teams card type. */
+  contentType: z.string(),
+
+  /** Display name. */
+  name: OPTIONAL_STRING_SCHEMA,
+
+  /** External content URL. */
+  contentUrl: OPTIONAL_STRING_SCHEMA,
+})
+
+const TEAMS_MESSAGE_MENTION_SCHEMA = z.object({
+  /** Mention identifier corresponding to the HTML `<at>` token. */
+  mentionId: z.number().int(),
+
+  /** Text displayed for the mention. */
+  mentionText: z.string(),
+
+  /** Mentioned conversation identity. */
+  mentioned: TEAMS_MESSAGE_FROM_SCHEMA,
+})
+
+const TEAMS_MESSAGE_REACTION_SCHEMA = z.object({
+  /** Reaction name such as `like` or `heart`. */
+  reactionType: z.string(),
+
+  /** Time the reaction was created. */
+  createdAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Identity that created the reaction. */
+  user: TEAMS_MESSAGE_FROM_SCHEMA,
+})
+
+export const TEAMS_CHAT_MESSAGE_SCHEMA = z.object({
+  /** Attachments and cards associated with the message. */
+  attachments: TEAMS_MESSAGE_ATTACHMENT_SCHEMA.array().prefault([]),
+
+  /** Message body. */
+  body: TEAMS_MESSAGE_BODY_SCHEMA,
+
+  /** Time the message was created. */
+  createdAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Time the message was soft-deleted. */
+  deletedAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Graph concurrency token. */
+  etag: OPTIONAL_STRING_SCHEMA,
+
+  /** Sender identity. */
+  from: TEAMS_MESSAGE_FROM_SCHEMA.nullish().transform(
+    (value) => value ?? undefined,
+  ),
+
+  /** Message importance. */
+  importance: z
+    .enum(["normal", "high", "urgent", "unknownFutureValue"])
+    .prefault("normal"),
+
+  /** Message locale. */
+  locale: OPTIONAL_STRING_SCHEMA,
+
+  /** Opaque Teams message identifier. */
+  messageId: z.string(),
+
+  /** Message kind. */
+  messageType: z.string(),
+
+  /** Structured mentions embedded in the body. */
+  mentions: TEAMS_MESSAGE_MENTION_SCHEMA.array().prefault([]),
+
+  /** Reactions currently applied to the message. */
+  reactions: TEAMS_MESSAGE_REACTION_SCHEMA.array().prefault([]),
+
+  /** Parent channel message identifier for a reply. */
+  replyToId: OPTIONAL_STRING_SCHEMA,
+
+  /** Subject, commonly present on channel announcements. */
+  subject: OPTIONAL_STRING_SCHEMA,
+
+  /** Provider-generated summary. */
+  summary: OPTIONAL_STRING_SCHEMA,
+
+  /** Time the message was last modified. */
+  updatedAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Microsoft Teams web URL. */
+  webUrl: OPTIONAL_STRING_SCHEMA,
+})
+
+const GRAPH_IDENTITY_SCHEMA = z
+  .looseObject({
+    id: z.string().nullish(),
+    displayName: z.string().nullish(),
+  })
+  .optional()
+
+export const GRAPH_CHAT_MESSAGE_SCHEMA = z
+  .looseObject({
+    attachments: z
+      .looseObject({
+        content: z.string().nullish(),
+        contentType: z.string(),
+        contentUrl: z.string().nullish(),
+        id: z.string(),
+        name: z.string().nullish(),
+      })
+      .array()
+      .optional(),
+    body: z.object({
+      content: z.string(),
+      contentType: z.enum(["text", "html"]),
+    }),
+    createdDateTime: z.string().nullish(),
+    deletedDateTime: z.string().nullish(),
+    etag: z.string().nullish(),
+    from: z
+      .looseObject({
+        application: GRAPH_IDENTITY_SCHEMA,
+        device: GRAPH_IDENTITY_SCHEMA,
+        user: GRAPH_IDENTITY_SCHEMA,
+      })
+      .nullish(),
+    id: z.string(),
+    importance: z
+      .enum(["normal", "high", "urgent", "unknownFutureValue"])
+      .optional(),
+    lastModifiedDateTime: z.string().nullish(),
+    locale: z.string().nullish(),
+    mentions: z
+      .looseObject({
+        id: z.number().int(),
+        mentionText: z.string(),
+        mentioned: z.looseObject({
+          application: GRAPH_IDENTITY_SCHEMA,
+          device: GRAPH_IDENTITY_SCHEMA,
+          user: GRAPH_IDENTITY_SCHEMA,
+        }),
+      })
+      .array()
+      .optional(),
+    messageType: z.string(),
+    reactions: z
+      .looseObject({
+        createdDateTime: z.string().nullish(),
+        reactionType: z.string(),
+        user: z.looseObject({
+          application: GRAPH_IDENTITY_SCHEMA,
+          device: GRAPH_IDENTITY_SCHEMA,
+          user: GRAPH_IDENTITY_SCHEMA,
+        }),
+      })
+      .array()
+      .optional(),
+    replyToId: z.string().nullish(),
+    subject: z.string().nullish(),
+    summary: z.string().nullish(),
+    webUrl: z.string().nullish(),
+  })
+  .transform((message) =>
+    TEAMS_CHAT_MESSAGE_SCHEMA.parse({
+      attachments: message.attachments?.map((attachment) => ({
+        attachmentId: attachment.id,
+        content: attachment.content,
+        contentType: attachment.contentType,
+        contentUrl: attachment.contentUrl,
+        name: attachment.name,
+      })),
+      body: message.body,
+      createdAt: message.createdDateTime,
+      deletedAt: message.deletedDateTime,
+      etag: message.etag,
+      from: graphIdentitySet(message.from),
+      importance: message.importance,
+      locale: message.locale,
+      mentions: message.mentions?.map((mention) => ({
+        mentionId: mention.id,
+        mentioned: graphIdentitySet(mention.mentioned),
+        mentionText: mention.mentionText,
+      })),
+      messageId: message.id,
+      messageType: message.messageType,
+      reactions: message.reactions?.map((reaction) => ({
+        createdAt: reaction.createdDateTime,
+        reactionType: reaction.reactionType,
+        user: graphIdentitySet(reaction.user),
+      })),
+      replyToId: message.replyToId,
+      subject: message.subject,
+      summary: message.summary,
+      updatedAt: message.lastModifiedDateTime,
+      webUrl: message.webUrl,
+    }),
+  )
+
+/**
+ * Normalizes an untrusted Microsoft Graph chat-message payload.
+ *
+ * @param payload - Provider chat-message payload.
+ */
+export function normalizeTeamsChatMessage(payload: unknown) {
+  return GRAPH_CHAT_MESSAGE_SCHEMA.parse(payload)
+}
+
+export const TEAMS_CHANNEL_MESSAGE_POSTED_EVENT_SCHEMA =
+  TEAMS_CHAT_MESSAGE_SCHEMA.extend({
+    /** Channel containing the posted message. */
+    channelId: z.string(),
+
+    /** Team containing the posted message. */
+    teamId: z.string(),
+  })
+
+export const TEAMS_CHAT_MESSAGE_POSTED_EVENT_SCHEMA =
+  TEAMS_CHAT_MESSAGE_SCHEMA.extend({
+    /** Chat containing the posted message. */
+    chatId: z.string(),
+  })
+
+/**
+ * Flattens Graph's user/application/device identity-set union.
+ *
+ * @param identitySet - Provider identity set.
+ */
+function graphIdentitySet(
+  identitySet:
+    | {
+        application?: { displayName?: string | null; id?: string | null }
+        device?: { displayName?: string | null; id?: string | null }
+        user?: { displayName?: string | null; id?: string | null }
+      }
+    | null
+    | undefined,
+) {
+  return {
+    applicationId: identitySet?.application?.id,
+    deviceId: identitySet?.device?.id,
+    displayName:
+      identitySet?.user?.displayName ??
+      identitySet?.application?.displayName ??
+      identitySet?.device?.displayName,
+    userId: identitySet?.user?.id,
+  }
+}