@automate.ax/integration-contracts 0.139.2 → 0.142.0

package/dist/clickup/api.d.ts

@@ -0,0 +1,76 @@
+import { type Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+/** Resolved ClickUp account accepted by the shared API client. */
+export interface ClickUpResolvedAccount {
+    connectionMethodId: string;
+    secret: Record<string, unknown>;
+    serviceId: "clickup";
+}
+/** Scalar value serialized into one ClickUp query parameter. */
+export type ClickUpQueryValue = boolean | number | readonly (number | string)[] | string | undefined;
+/** Options for one authenticated ClickUp REST request. */
+export interface ClickUpRequestOptions<TSchema extends z.ZodType> {
+    /** Public camelCase JSON body. */
+    body?: Encodable;
+    /** HTTP verb. Defaults to `GET`. */
+    method?: "DELETE" | "GET" | "POST" | "PUT";
+    /** Public camelCase query parameters. */
+    query?: Record<string, ClickUpQueryValue>;
+    /** Schema for the normalized provider response. */
+    responseSchema: TSchema;
+}
+/** Authenticated ClickUp REST API helper for packaged actions. */
+export interface ClickUpApi {
+    /**
+     * Calls a ClickUp API v2 endpoint and validates its normalized response.
+     *
+     * @param path - API path relative to `/api/v2/`.
+     * @param options - Request data and response schema.
+     */
+    request<TSchema extends z.ZodType>(path: string, options: ClickUpRequestOptions<TSchema>): Promise<z.output<TSchema>>;
+}
+/** Structured ClickUp REST error. */
+export declare class ClickUpApiError extends Error {
+    /** Normalized provider error payload, when it was valid JSON. */
+    readonly body?: Encodable;
+    /** API path that failed. */
+    readonly path: string;
+    /** Unix timestamp in seconds when the current rate-limit window resets. */
+    readonly rateLimitReset?: number;
+    /** HTTP status returned by ClickUp. */
+    readonly status: number;
+    /**
+     * Creates a structured ClickUp API error.
+     *
+     * @param options - Provider and transport error details.
+     * @param options.body - Normalized provider error payload.
+     * @param options.path - API path that failed.
+     * @param options.rateLimitReset - Unix reset timestamp in seconds.
+     * @param options.status - HTTP response status.
+     */
+    constructor(options: {
+        body?: Encodable;
+        path: string;
+        rateLimitReset?: number;
+        status: number;
+    });
+}
+/**
+ * Creates an authenticated ClickUp API v2 client.
+ *
+ * @param account - Resolved ClickUp integration account.
+ * @throws When the account uses an unsupported connection method.
+ */
+export declare function getClickUpApi(account: ClickUpResolvedAccount): ClickUpApi;
+/**
+ * Converts public camelCase JSON to ClickUp wire keys.
+ *
+ * @param value - Public JSON value.
+ */
+export declare function toClickUp(value: Encodable): Encodable;
+/**
+ * Converts ClickUp response keys to public camelCase recursively.
+ *
+ * @param value - Provider response value.
+ */
+export declare function fromClickUp(value: unknown): unknown;

package/dist/clickup/api.js

@@ -0,0 +1,195 @@
+import { encodableSchema } from "@automate.ax/codec";
+import * as z from "zod";
+const CLICKUP_API_BASE_URL = "https://api.clickup.com/api/v2/";
+const CLICKUP_API_ORIGIN = new URL(CLICKUP_API_BASE_URL).origin;
+const CLICKUP_OAUTH_SECRET_SCHEMA = z.object({ accessToken: z.string().min(1) });
+const CLICKUP_TOKEN_SECRET_SCHEMA = z.object({ apiKey: z.string().min(1) });
+/** Structured ClickUp REST error. */
+export class ClickUpApiError extends Error {
+    /** Normalized provider error payload, when it was valid JSON. */
+    body;
+    /** API path that failed. */
+    path;
+    /** Unix timestamp in seconds when the current rate-limit window resets. */
+    rateLimitReset;
+    /** HTTP status returned by ClickUp. */
+    status;
+    /**
+     * Creates a structured ClickUp API error.
+     *
+     * @param options - Provider and transport error details.
+     * @param options.body - Normalized provider error payload.
+     * @param options.path - API path that failed.
+     * @param options.rateLimitReset - Unix reset timestamp in seconds.
+     * @param options.status - HTTP response status.
+     */
+    constructor(options) {
+        super(getErrorMessage(options.body) ??
+            `ClickUp API request failed with status ${options.status}.`);
+        this.name = "ClickUpApiError";
+        this.body = options.body;
+        this.path = options.path;
+        this.rateLimitReset = options.rateLimitReset;
+        this.status = options.status;
+    }
+}
+/**
+ * Creates an authenticated ClickUp API v2 client.
+ *
+ * @param account - Resolved ClickUp integration account.
+ * @throws When the account uses an unsupported connection method.
+ */
+export function getClickUpApi(account) {
+    const accessToken = account.connectionMethodId === "oauth"
+        ? CLICKUP_OAUTH_SECRET_SCHEMA.parse(account.secret).accessToken
+        : account.connectionMethodId === "personal-token"
+            ? CLICKUP_TOKEN_SECRET_SCHEMA.parse(account.secret).apiKey
+            : "";
+    if (!accessToken) {
+        throw new Error(`Unsupported ClickUp connection method: ${account.connectionMethodId}`);
+    }
+    return {
+        request: async (path, options) => {
+            const normalizedPath = path.replace(/^\/+/, "");
+            const url = new URL(normalizedPath, CLICKUP_API_BASE_URL);
+            const expectedPathname = `/api/v2/${normalizedPath}`;
+            if (url.origin !== CLICKUP_API_ORIGIN ||
+                url.pathname !== expectedPathname) {
+                throw new Error("ClickUp API paths must remain under /api/v2.");
+            }
+            for (const [name, value] of Object.entries(options.query ?? {})) {
+                if (value === undefined)
+                    continue;
+                const wireName = toSnakeCase(name);
+                if (Array.isArray(value)) {
+                    for (const item of value)
+                        url.searchParams.append(`${wireName}[]`, String(item));
+                }
+                else {
+                    url.searchParams.set(wireName, String(value));
+                }
+            }
+            const response = await fetch(url, {
+                body: options.body === undefined
+                    ? undefined
+                    : JSON.stringify(toClickUp(options.body)),
+                headers: {
+                    Accept: "application/json",
+                    Authorization: account.connectionMethodId === "oauth"
+                        ? `Bearer ${accessToken}`
+                        : accessToken,
+                    ...(options.body === undefined
+                        ? {}
+                        : { "Content-Type": "application/json" }),
+                },
+                method: options.method ?? "GET",
+            });
+            const responseText = await response.text();
+            const normalized = responseText === "" ? undefined : fromClickUp(parseJson(responseText));
+            if (!response.ok) {
+                const body = encodableSchema.safeParse(normalized);
+                throw new ClickUpApiError({
+                    ...(body.success && { body: body.data }),
+                    path: `/${normalizedPath}`,
+                    rateLimitReset: parseFiniteNumber(response.headers.get("X-RateLimit-Reset")),
+                    status: response.status,
+                });
+            }
+            return options.responseSchema.parse(normalized);
+        },
+    };
+}
+/**
+ * Converts public camelCase JSON to ClickUp wire keys.
+ *
+ * @param value - Public JSON value.
+ */
+export function toClickUp(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(toClickUp);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        toSnakeCase(key),
+        toClickUp(item),
+    ]));
+}
+/**
+ * Converts ClickUp response keys to public camelCase recursively.
+ *
+ * @param value - Provider response value.
+ */
+export function fromClickUp(value) {
+    if (Array.isArray(value))
+        return value.map(fromClickUp);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        toCamelCase(key),
+        fromClickUp(item),
+    ]));
+}
+/**
+ * Returns whether a value is a non-array object.
+ *
+ * @param value - Candidate value.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parses JSON without masking the provider's response status.
+ *
+ * @param value - Raw response text.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses a finite number from an optional response header.
+ *
+ * @param value - Raw response header.
+ */
+function parseFiniteNumber(value) {
+    if (value === null)
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+/**
+ * Reads ClickUp's human-readable error message from a response body.
+ *
+ * @param body - Normalized provider response body.
+ */
+function getErrorMessage(body) {
+    if (!isPlainObject(body))
+        return undefined;
+    if (typeof body.err === "string")
+        return body.err;
+    if (typeof body.message === "string")
+        return body.message;
+    return undefined;
+}
+/**
+ * Converts one camelCase key to ClickUp's snake_case wire format.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value) {
+    return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+/**
+ * Converts one ClickUp snake_case key to camelCase.
+ *
+ * @param value - Provider wire key.
+ */
+function toCamelCase(value) {
+    return value.replace(/_([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+}