@automate.ax/integration-contracts 0.55.0

package/dist/teams/schemas.js

@@ -0,0 +1,365 @@
+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) {
+    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) {
+    return {
+        applicationId: identitySet?.application?.id,
+        deviceId: identitySet?.device?.id,
+        displayName: identitySet?.user?.displayName ??
+            identitySet?.application?.displayName ??
+            identitySet?.device?.displayName,
+        userId: identitySet?.user?.id,
+    };
+}

package/dist/trello/api.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/** 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 declare 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;
+    });
+}
+/**
+ * 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 declare function getTrelloApi(secret: Record<string, unknown>): TrelloApi;
+/**
+ * Accepts a raw card ID, short link, or standard Trello card URL.
+ *
+ * @param card - Card reference to normalize.
+ */
+export declare function normalizeTrelloCardId(card: string): string;
+/**
+ * Accepts a raw board ID, short link, or standard Trello board URL.
+ *
+ * @param board - Board reference to normalize.
+ */
+export declare function normalizeTrelloBoardId(board: string): string;
+export {};

package/dist/trello/api.js

@@ -0,0 +1,140 @@
+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(),
+});
+/** Structured Trello REST request error. */
+export class TrelloApiError extends Error {
+    /** Provider error body, when Trello returned text. */
+    providerMessage;
+    /** Retry delay from Trello's `Retry-After` header, in seconds. */
+    retryAfter;
+    /** HTTP status returned by Trello. */
+    status;
+    /**
+     * 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) {
+        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) {
+    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) {
+    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) {
+    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, resource) {
+    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) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses Trello's integer retry delay header.
+ *
+ * @param value - Raw `Retry-After` header.
+ */
+function parseRetryAfter(value) {
+    if (value === null)
+        return undefined;
+    const seconds = Number(value);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}