@automate.ax/integration-contracts 0.145.2 → 0.146.0

package/dist/highlevel/api.d.ts

@@ -0,0 +1,43 @@
+import { type Encodable } from "@automate.ax/codec";
+import type { HighLevelOperationKey } from "./operation-manifest.js";
+import type { HighLevelOperationInput, HighLevelOperationOutput } from "./types.js";
+/** Resolved account accepted by the shared HighLevel API client. */
+export interface HighLevelResolvedAccount {
+    connectionMethodId: string;
+    secret: Record<string, unknown>;
+    serviceId: "highlevel";
+}
+/** Structured error returned by a rejected HighLevel request. */
+export declare class HighLevelApiError extends Error {
+    readonly body?: Encodable;
+    readonly retryAfter?: string;
+    readonly status: number;
+    /**
+     * Creates an error from one rejected HighLevel response.
+     *
+     * @param options - Rejected response details.
+     * @param options.body - Encodable provider error body.
+     * @param options.retryAfter - Provider retry timing.
+     * @param options.status - HTTP status.
+     */
+    constructor(options: {
+        body?: Encodable;
+        retryAfter?: string;
+        status: number;
+    });
+}
+/**
+ * Creates an authenticated client for the frozen HighLevel action surface.
+ *
+ * @param account - Resolved HighLevel account.
+ * @throws When the connection method or secret is invalid.
+ */
+export declare function getHighLevelApi(account: HighLevelResolvedAccount): {
+    /**
+     * Executes and validates one named HighLevel OpenAPI operation.
+     *
+     * @param key - Frozen operation key.
+     * @param input - Flattened operation input.
+     */
+    operation<TKey extends HighLevelOperationKey>(key: TKey, input: HighLevelOperationInput<TKey>): Promise<HighLevelOperationOutput<TKey>>;
+};

package/dist/highlevel/api.js

@@ -0,0 +1,236 @@
+import { encodableSchema } from "@automate.ax/codec";
+import * as z from "zod";
+import { highLevelOperation, highLevelOperationOutputSchema } from "./schemas.js";
+const HIGH_LEVEL_API_BASE_URL = "https://services.leadconnectorhq.com/";
+const HIGH_LEVEL_API_ORIGIN = new URL(HIGH_LEVEL_API_BASE_URL).origin;
+const HIGH_LEVEL_SECRET_SCHEMA = z.object({
+    accessToken: z.string().min(1),
+    locationId: z.string().min(1),
+});
+/** Structured error returned by a rejected HighLevel request. */
+export class HighLevelApiError extends Error {
+    body;
+    retryAfter;
+    status;
+    /**
+     * Creates an error from one rejected HighLevel response.
+     *
+     * @param options - Rejected response details.
+     * @param options.body - Encodable provider error body.
+     * @param options.retryAfter - Provider retry timing.
+     * @param options.status - HTTP status.
+     */
+    constructor(options) {
+        super(getErrorMessage(options.body) ??
+            `HighLevel API request failed with status ${options.status}.`);
+        this.name = "HighLevelApiError";
+        this.body = options.body;
+        this.retryAfter = options.retryAfter;
+        this.status = options.status;
+    }
+}
+/**
+ * Creates an authenticated client for the frozen HighLevel action surface.
+ *
+ * @param account - Resolved HighLevel account.
+ * @throws When the connection method or secret is invalid.
+ */
+export function getHighLevelApi(account) {
+    const credentials = HIGH_LEVEL_SECRET_SCHEMA.parse(account.secret);
+    if (account.connectionMethodId !== "oauth" &&
+        account.connectionMethodId !== "private-integration-token") {
+        throw new Error(`Unsupported HighLevel connection method: ${account.connectionMethodId}`);
+    }
+    return {
+        /**
+         * Executes and validates one named HighLevel OpenAPI operation.
+         *
+         * @param key - Frozen operation key.
+         * @param input - Flattened operation input.
+         */
+        async operation(key, input) {
+            const definition = highLevelOperation(key);
+            const pathValues = new Map();
+            const queryValues = new Map();
+            const bodyValues = {};
+            const inputRecord = input;
+            for (const name of definition.pathParameters) {
+                pathValues.set(name, inputRecord[name]);
+            }
+            for (const { name } of definition.queryParameters) {
+                queryValues.set(name, inputRecord[name]);
+            }
+            for (const name of definition.bodyParameters) {
+                if (inputRecord[name] !== undefined)
+                    bodyValues[name] = inputRecord[name];
+            }
+            for (const placement of definition.locationPlacements) {
+                if (placement === "path")
+                    pathValues.set("locationId", credentials.locationId);
+                if (placement === "query")
+                    queryValues.set("locationId", credentials.locationId);
+                if (placement === "body")
+                    bodyValues.locationId = credentials.locationId;
+            }
+            // Resolve path placeholders before applying the fixed-origin guard.
+            const path = definition.path.replace(/\{([^}]+)\}/g, (_match, name) => encodePathSegment(pathValues.get(name), name));
+            const normalizedPath = path.replace(/^\/+/, "");
+            const url = new URL(normalizedPath, HIGH_LEVEL_API_BASE_URL);
+            if (!normalizedPath ||
+                normalizedPath.includes("://") ||
+                normalizedPath.includes("\\") ||
+                normalizedPath.includes("?") ||
+                normalizedPath.includes("#") ||
+                url.origin !== HIGH_LEVEL_API_ORIGIN) {
+                throw new TypeError("HighLevel API paths must remain provider-relative.");
+            }
+            for (const parameter of definition.queryParameters) {
+                appendQuery(url, { ...parameter, name: parameter.providerName }, queryValues.get(parameter.name));
+            }
+            if (definition.locationPlacements.includes("query")) {
+                url.searchParams.set(definition.locationParameterNames.query ?? "locationId", credentials.locationId);
+            }
+            const hasBody = definition.bodyParameters.length > 0 ||
+                definition.locationPlacements.includes("body");
+            const response = await fetch(url, {
+                body: hasBody ? JSON.stringify(bodyValues) : undefined,
+                headers: {
+                    Accept: "application/json",
+                    Authorization: `Bearer ${credentials.accessToken}`,
+                    Version: definition.apiVersion,
+                    ...(hasBody ? { "Content-Type": "application/json" } : {}),
+                },
+                method: definition.method,
+                redirect: "error",
+            });
+            const parsed = response.ok && definition.responseMode === "binary"
+                ? {
+                    contentType: response.headers.get("Content-Type") ??
+                        "application/octet-stream",
+                    data: Buffer.from(await response.arrayBuffer()).toString("base64"),
+                }
+                : await parseResponseText(response);
+            if (!response.ok) {
+                const body = encodableSchema.safeParse(parsed);
+                throw new HighLevelApiError({
+                    ...(body.success && { body: body.data }),
+                    retryAfter: getRetryAfter(response.headers),
+                    status: response.status,
+                });
+            }
+            return highLevelOperationOutputSchema(key).parse(parsed);
+        },
+    };
+}
+/**
+ * Encodes one required path parameter.
+ *
+ * @param value - Parameter value.
+ * @param name - Parameter name.
+ * @throws When the value is not scalar.
+ */
+function encodePathSegment(value, name) {
+    if (typeof value !== "number" && typeof value !== "string") {
+        throw new TypeError(`HighLevel path parameter ${name} is required.`);
+    }
+    return encodeURIComponent(String(value));
+}
+/**
+ * Appends one OpenAPI query parameter.
+ *
+ * @param url - Provider request URL.
+ * @param parameter - Query serialization metadata.
+ * @param parameter.explode - Whether array items repeat the query key.
+ * @param parameter.name - Query parameter name.
+ * @param parameter.style - OpenAPI serialization style.
+ * @param value - Parameter value.
+ * @throws When the value is not scalar or an array of scalars.
+ */
+function appendQuery(url, parameter, value) {
+    if (value == null)
+        return;
+    if (Array.isArray(value)) {
+        if (parameter.style === "form" && parameter.explode) {
+            for (const item of value)
+                url.searchParams.append(parameter.name, stringifyQueryValue(item));
+        }
+        else {
+            url.searchParams.set(parameter.name, value.map(stringifyQueryValue).join(","));
+        }
+        return;
+    }
+    url.searchParams.set(parameter.name, stringifyQueryValue(value));
+}
+/**
+ * Converts one supported query value to text.
+ *
+ * @param value - Query value.
+ * @throws When the value is not scalar.
+ */
+function stringifyQueryValue(value) {
+    if (typeof value !== "boolean" &&
+        typeof value !== "number" &&
+        typeof value !== "string") {
+        throw new TypeError("HighLevel query parameters must be scalar.");
+    }
+    return String(value);
+}
+/**
+ * Reads provider-directed retry timing.
+ *
+ * @param headers - Rejected response headers.
+ */
+function getRetryAfter(headers) {
+    const retryAfter = headers.get("Retry-After");
+    if (retryAfter)
+        return retryAfter;
+    const interval = headers.get("X-RateLimit-Interval-Milliseconds");
+    if (!interval || !/^\d+$/.test(interval))
+        return undefined;
+    return String(Math.ceil(Number(interval) / 1_000));
+}
+/**
+ * Extracts a provider error message.
+ *
+ * @param value - Encodable provider error body.
+ */
+function getErrorMessage(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    for (const key of ["message", "error", "error_description"]) {
+        const candidate = value[key];
+        if (typeof candidate === "string" && candidate.trim())
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Narrows a value to a plain object.
+ *
+ * @param value - Candidate value.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parses JSON while retaining non-JSON provider bodies.
+ *
+ * @param value - Response body text.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return { response: value };
+    }
+}
+/**
+ * Reads one text or JSON provider response.
+ *
+ * @param response - Provider response to decode.
+ */
+async function parseResponseText(response) {
+    const text = await response.text();
+    return text ? parseJson(text) : null;
+}