@automate.ax/integration-contracts 0.87.5 → 0.88.0

package/dist/close/api.d.ts

@@ -0,0 +1,54 @@
+import { type Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+export declare const CLOSE_VALUE_SCHEMA: z.ZodCustom<Encodable, Encodable>;
+export declare const CLOSE_OBJECT_SCHEMA: z.ZodCustom<Record<string, Encodable>, Record<string, Encodable>>;
+export declare const CLOSE_RESPONSE_SCHEMA: z.ZodUnion<readonly [z.ZodCustom<Encodable, Encodable>, z.ZodPipe<z.ZodUndefined, z.ZodTransform<null, undefined>>]>;
+interface CloseRequestOptions<TSchema extends z.ZodType> {
+    body?: Encodable;
+    method?: "DELETE" | "GET" | "POST" | "PUT";
+    query?: Record<string, boolean | number | string | readonly string[] | null | undefined>;
+    responseSchema: TSchema;
+}
+/** Error returned by a rejected Close API request. */
+export declare class CloseApiError extends Error {
+    readonly details: Encodable;
+    readonly status: number;
+    /**
+     * Creates an error from a rejected Close response.
+     *
+     * @param status - HTTP response status.
+     * @param details - Codec-safe response details.
+     */
+    constructor(status: number, details: Encodable);
+}
+/**
+ * Creates a minimal authenticated Close REST client.
+ *
+ * @param secret - Stored Close OAuth token or API key.
+ */
+export declare function getCloseApi(secret: unknown): {
+    /**
+     * Sends one JSON request to a path below Close's `/api/v1/` root.
+     *
+     * Query keys are provider-native so callers can use Close's
+     * double-underscore filters. Request bodies and responses use public
+     * camelCase keys.
+     *
+     * @param path - Relative path below Close's API root.
+     * @param options - Request method, query, body, and response schema.
+     */
+    request<TSchema extends z.ZodType>(path: string, options: CloseRequestOptions<TSchema>): Promise<z.output<TSchema>>;
+};
+/**
+ * Converts a public camelCase value into Close's provider-native JSON keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export declare function toClose(value: Encodable): Encodable;
+/**
+ * Converts Close's provider-native JSON keys to public camelCase keys.
+ *
+ * @param value - Raw provider value.
+ */
+export declare function fromClose(value: unknown): Encodable;
+export {};

package/dist/close/api.js

@@ -0,0 +1,191 @@
+import { isEncodable } from "@automate.ax/codec";
+import * as z from "zod";
+const CLOSE_API_ORIGIN = "https://api.close.com/api/v1/";
+const CLOSE_API_URL = new URL(CLOSE_API_ORIGIN);
+const CLOSE_SECRET_SCHEMA = z.union([
+    z.object({ accessToken: z.string().min(1) }),
+    z.object({ apiKey: z.string().min(1) }),
+]);
+export const CLOSE_VALUE_SCHEMA = z.custom(isEncodable, {
+    message: "Expected a codec-safe Close value.",
+});
+export const CLOSE_OBJECT_SCHEMA = z.custom((value) => isPlainObject(value) && isEncodable(value), { message: "Expected a codec-safe Close object." });
+export const CLOSE_RESPONSE_SCHEMA = z.union([
+    CLOSE_VALUE_SCHEMA,
+    z.undefined().transform(() => null),
+]);
+/** Error returned by a rejected Close API request. */
+export class CloseApiError extends Error {
+    details;
+    status;
+    /**
+     * Creates an error from a rejected Close response.
+     *
+     * @param status - HTTP response status.
+     * @param details - Codec-safe response details.
+     */
+    constructor(status, details) {
+        super(`Close API request failed (${status}).`);
+        this.name = "CloseApiError";
+        this.details = details;
+        this.status = status;
+    }
+}
+/**
+ * Creates a minimal authenticated Close REST client.
+ *
+ * @param secret - Stored Close OAuth token or API key.
+ */
+export function getCloseApi(secret) {
+    const credentials = CLOSE_SECRET_SCHEMA.parse(secret);
+    return {
+        /**
+         * Sends one JSON request to a path below Close's `/api/v1/` root.
+         *
+         * Query keys are provider-native so callers can use Close's
+         * double-underscore filters. Request bodies and responses use public
+         * camelCase keys.
+         *
+         * @param path - Relative path below Close's API root.
+         * @param options - Request method, query, body, and response schema.
+         */
+        async request(path, options) {
+            const normalizedPath = path.replace(/^\/+/, "");
+            if (!normalizedPath ||
+                normalizedPath.includes("://") ||
+                normalizedPath.includes("\\")) {
+                throw new TypeError("Close API paths must be relative to /api/v1/.");
+            }
+            const url = new URL(normalizedPath, CLOSE_API_ORIGIN);
+            if (url.origin !== CLOSE_API_URL.origin ||
+                !url.pathname.startsWith(CLOSE_API_URL.pathname)) {
+                throw new TypeError("Close API paths must remain below /api/v1/.");
+            }
+            for (const [key, value] of Object.entries(options.query ?? {})) {
+                if (value == null)
+                    continue;
+                url.searchParams.set(key, Array.isArray(value) ? value.join(",") : String(value));
+            }
+            const headers = new Headers({ Accept: "application/json" });
+            headers.set("Authorization", "accessToken" in credentials
+                ? `Bearer ${credentials.accessToken}`
+                : `Basic ${btoa(`${credentials.apiKey}:`)}`);
+            if (options.body !== undefined) {
+                headers.set("Content-Type", "application/json");
+            }
+            const response = await fetch(url, {
+                body: options.body === undefined
+                    ? undefined
+                    : JSON.stringify(toClose(options.body)),
+                headers,
+                method: options.method ?? "GET",
+            });
+            const text = await response.text();
+            const result = CLOSE_RESPONSE_SCHEMA.safeParse(fromClose(text ? parseJson(text) : null));
+            if (!response.ok || !result.success) {
+                throw new CloseApiError(response.status, result.success ? result.data : { response: text });
+            }
+            return options.responseSchema.parse(result.data);
+        },
+    };
+}
+/**
+ * Converts a public camelCase value into Close's provider-native JSON keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export function toClose(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(toClose);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
+        if (key === "customFields" && isPlainObject(item)) {
+            return Object.entries(item).map(([fieldId, fieldValue]) => [
+                `custom.${fieldId}`,
+                toClose(fieldValue),
+            ]);
+        }
+        return [[toSnakeCase(key), toClose(item)]];
+    }));
+}
+/**
+ * Converts Close's provider-native JSON keys to public camelCase keys.
+ *
+ * @param value - Raw provider value.
+ */
+export function fromClose(value) {
+    if (Array.isArray(value))
+        return value.map(fromClose);
+    if (!isPlainObject(value))
+        return CLOSE_VALUE_SCHEMA.parse(value);
+    const customFields = {};
+    // Collect flattened custom fields while normalizing the ordinary entries.
+    const entries = Object.entries(value).flatMap(([key, item]) => {
+        if (key.startsWith("custom.")) {
+            customFields[key.slice("custom.".length)] = fromClose(item);
+            return [];
+        }
+        return [
+            [
+                key === "date_created"
+                    ? "createdAt"
+                    : key === "date_updated"
+                        ? "updatedAt"
+                        : key === "_type"
+                            ? "type"
+                            : key === "__object_type"
+                                ? "objectType"
+                                : toCamelCase(key),
+                fromClose(item),
+            ],
+        ];
+    });
+    return Object.fromEntries([
+        ...entries,
+        ...(Object.keys(customFields).length > 0
+            ? [["customFields", customFields]]
+            : []),
+    ]);
+}
+/**
+ * Parses a response body while preserving non-JSON error text.
+ *
+ * @param value - Raw response text.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return { response: value };
+    }
+}
+/**
+ * Checks whether a value is a non-array object.
+ *
+ * @param value - Candidate value.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Converts one provider key to public camelCase.
+ *
+ * @param value - Provider key.
+ */
+function toCamelCase(value) {
+    return value.replace(/_([a-z0-9])/g, (_match, character) => character.toUpperCase());
+}
+/**
+ * Converts one public key to provider snake_case.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value) {
+    return value
+        .replace(/([a-zA-Z])([0-9])/g, "$1_$2")
+        .replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`);
+}