@automate.ax/integration-contracts 0.143.9 → 0.144.0

package/dist/calendly/api.d.ts

@@ -0,0 +1,55 @@
+import type { Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+/** Resolved Calendly OAuth account accepted by the shared API client. */
+export interface CalendlyResolvedAccount {
+    connectionMethodId: string;
+    secret: Record<string, unknown>;
+    serviceId: "calendly";
+}
+/** Options for one authenticated Calendly REST request. */
+export interface CalendlyRequestOptions<TSchema extends z.ZodType> {
+    body?: Encodable;
+    method?: "DELETE" | "GET" | "PATCH" | "POST";
+    query?: Record<string, boolean | number | string | undefined>;
+    responseSchema: TSchema;
+}
+/** Structured Calendly REST error. */
+export declare class CalendlyApiError extends Error {
+    readonly body?: Encodable;
+    readonly rateLimitReset?: number;
+    readonly status: number;
+    /**
+     * Creates a structured Calendly API error.
+     *
+     * @param options - Provider response details.
+     * @param options.body - Parsed provider error body.
+     * @param options.rateLimitReset - Provider retry delay, in seconds.
+     * @param options.status - HTTP response status.
+     */
+    constructor(options: {
+        body?: Encodable;
+        rateLimitReset?: number;
+        status: number;
+    });
+}
+/**
+ * Creates an authenticated Calendly REST client.
+ *
+ * @param account - Resolved Calendly OAuth account.
+ * @throws When the account method or secret is invalid.
+ */
+export declare function getCalendlyApi(account: CalendlyResolvedAccount): {
+    request: <TSchema extends z.ZodType>(path: string, options: CalendlyRequestOptions<TSchema>) => Promise<z.output<TSchema>>;
+};
+/**
+ * Converts public camelCase JSON to Calendly wire keys.
+ *
+ * @param value - Public action input.
+ */
+export declare function toCalendly(value: Encodable): Encodable;
+/**
+ * Converts Calendly wire JSON to public camelCase keys.
+ *
+ * @param value - Parsed Calendly response value.
+ */
+export declare function fromCalendly(value: unknown): unknown;

package/dist/calendly/api.js

@@ -0,0 +1,176 @@
+import { encodableSchema } from "@automate.ax/codec";
+import * as z from "zod";
+const CALENDLY_API_BASE_URL = "https://api.calendly.com/";
+const CALENDLY_API_ORIGIN = new URL(CALENDLY_API_BASE_URL).origin;
+const CALENDLY_OAUTH_SECRET_SCHEMA = z.object({
+    accessToken: z.string().min(1),
+});
+/** Structured Calendly REST error. */
+export class CalendlyApiError extends Error {
+    body;
+    rateLimitReset;
+    status;
+    /**
+     * Creates a structured Calendly API error.
+     *
+     * @param options - Provider response details.
+     * @param options.body - Parsed provider error body.
+     * @param options.rateLimitReset - Provider retry delay, in seconds.
+     * @param options.status - HTTP response status.
+     */
+    constructor(options) {
+        super(getErrorMessage(options.body) ??
+            `Calendly API request failed with status ${options.status}.`);
+        this.name = "CalendlyApiError";
+        this.body = options.body;
+        this.rateLimitReset = options.rateLimitReset;
+        this.status = options.status;
+    }
+}
+/**
+ * Creates an authenticated Calendly REST client.
+ *
+ * @param account - Resolved Calendly OAuth account.
+ * @throws When the account method or secret is invalid.
+ */
+export function getCalendlyApi(account) {
+    if (account.connectionMethodId !== "oauth") {
+        throw new Error(`Unsupported Calendly connection method: ${account.connectionMethodId}`);
+    }
+    const { accessToken } = CALENDLY_OAUTH_SECRET_SCHEMA.parse(account.secret);
+    /**
+     * Calls one Calendly endpoint and validates the response.
+     *
+     * @param path - Calendly API path.
+     * @param options - Request options and response schema.
+     */
+    async function request(path, options) {
+        const url = new URL(path.replace(/^\//, ""), CALENDLY_API_BASE_URL);
+        if (url.origin !== CALENDLY_API_ORIGIN) {
+            throw new Error("Calendly API paths must use the Calendly API origin.");
+        }
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(toSnakeCase(name), String(value));
+        }
+        const response = await fetch(url, {
+            body: options.body === undefined
+                ? undefined
+                : JSON.stringify(toCalendly(options.body)),
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${accessToken}`,
+                ...(options.body === undefined
+                    ? {}
+                    : { "Content-Type": "application/json" }),
+            },
+            method: options.method ?? "GET",
+        });
+        const text = await response.text();
+        const normalized = text ? fromCalendly(parseJson(text)) : undefined;
+        if (!response.ok) {
+            const body = encodableSchema.safeParse(normalized);
+            throw new CalendlyApiError({
+                ...(body.success && { body: body.data }),
+                rateLimitReset: parseFiniteNumber(response.headers.get("X-RateLimit-Reset")),
+                status: response.status,
+            });
+        }
+        return options.responseSchema.parse(normalized);
+    }
+    return { request };
+}
+/**
+ * Converts public camelCase JSON to Calendly wire keys.
+ *
+ * @param value - Public action input.
+ */
+export function toCalendly(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(toCalendly);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        toSnakeCase(key),
+        toCalendly(item),
+    ]));
+}
+/**
+ * Converts Calendly wire JSON to public camelCase keys.
+ *
+ * @param value - Parsed Calendly response value.
+ */
+export function fromCalendly(value) {
+    if (Array.isArray(value))
+        return value.map(fromCalendly);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        toCamelCase(key),
+        fromCalendly(item),
+    ]));
+}
+/**
+ * Whether a value can be traversed as a plain JSON object.
+ *
+ * @param value - Candidate JSON value.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parses a provider body without masking its HTTP failure.
+ *
+ * @param value - Provider response body.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses a finite numeric response header.
+ *
+ * @param value - Response header value.
+ */
+function parseFiniteNumber(value) {
+    if (value === null)
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+/**
+ * Extracts Calendly's human-readable error message.
+ *
+ * @param body - Parsed provider error body.
+ */
+function getErrorMessage(body) {
+    if (!isPlainObject(body))
+        return undefined;
+    if (typeof body.message === "string")
+        return body.message;
+    if (typeof body.title === "string")
+        return body.title;
+    return undefined;
+}
+/**
+ * Converts one public field name to Calendly's wire convention.
+ *
+ * @param value - Public field name.
+ */
+function toSnakeCase(value) {
+    return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+/**
+ * Converts one Calendly wire field name to the public convention.
+ *
+ * @param value - Calendly wire field name.
+ */
+function toCamelCase(value) {
+    return value.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}