@automate.ax/integration-contracts 0.89.2 → 0.91.0

package/dist/jobnimbus/api.d.ts

@@ -0,0 +1,71 @@
+import { type Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+declare const JOB_NIMBUS_API_ORIGINS: {
+    readonly accountsReceivable: "https://api.jobnimbus.com/accounts-receivable/v1/";
+    readonly activities: "https://api.jobnimbus.com/activities/v1/";
+    readonly files: "https://api.jobnimbus.com/files/v1/";
+    readonly identity: "https://api.jobnimbus.com/identity/v1/";
+    readonly public: "https://app.jobnimbus.com/api1/";
+};
+export declare const JOB_NIMBUS_VALUE_SCHEMA: z.ZodCustom<Encodable, Encodable>;
+export declare const JOB_NIMBUS_RESPONSE_SCHEMA: z.ZodUnion<readonly [z.ZodCustom<Encodable, Encodable>, z.ZodPipe<z.ZodUndefined, z.ZodTransform<null, undefined>>]>;
+export type JobNimbusApi = keyof typeof JOB_NIMBUS_API_ORIGINS;
+interface JobNimbusRequestOptions<TSchema extends z.ZodType> {
+    body?: Encodable;
+    contentType?: string;
+    headers?: Record<string, string | undefined>;
+    method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    query?: Record<string, boolean | number | string | readonly (boolean | number | string)[] | null | undefined>;
+    responseSchema: TSchema;
+}
+/** Error returned by a rejected JobNimbus API request. */
+export declare class JobNimbusApiError extends Error {
+    readonly details: Encodable;
+    readonly status: number;
+    /**
+     * Creates an error from a rejected JobNimbus response.
+     *
+     * @param status - HTTP response status.
+     * @param details - Codec-safe response details.
+     */
+    constructor(status: number, details: Encodable);
+}
+/**
+ * Creates an authenticated client for one documented JobNimbus API root.
+ *
+ * @param secret - Stored JobNimbus API key.
+ * @param api - Public API or one current Platform service.
+ */
+export declare function getJobNimbusApi(secret: unknown, api: JobNimbusApi): {
+    /**
+     * Sends one JSON request below the selected JobNimbus API root.
+     *
+     * @param path - Relative path below the selected root.
+     * @param options - Request method, query, body, headers, and response
+     *   schema.
+     */
+    request<TSchema extends z.ZodType>(path: string, options: JobNimbusRequestOptions<TSchema>): Promise<z.output<TSchema>>;
+};
+/**
+ * Downloads one JobNimbus attachment from its documented non-API route.
+ *
+ * @param secret - Stored JobNimbus API key.
+ * @param fileId - Attachment JNID.
+ */
+export declare function downloadJobNimbusFile(secret: unknown, fileId: string): Promise<import("buffer").Blob>;
+/**
+ * Converts public camelCase JSON into JobNimbus's provider-native keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export declare function toJobNimbus(value: Encodable): Encodable;
+/**
+ * Converts JobNimbus JSON into public camelCase values.
+ *
+ * Documented legacy Unix date fields become Date instances. Unknown fields are
+ * preserved so account-defined CRM fields survive normalization.
+ *
+ * @param value - Raw provider value.
+ */
+export declare function fromJobNimbus(value: unknown): Encodable;
+export {};

package/dist/jobnimbus/api.js

@@ -0,0 +1,231 @@
+import { isEncodable } from "@automate.ax/codec";
+import * as z from "zod";
+const JOB_NIMBUS_API_ORIGINS = {
+    accountsReceivable: "https://api.jobnimbus.com/accounts-receivable/v1/",
+    activities: "https://api.jobnimbus.com/activities/v1/",
+    files: "https://api.jobnimbus.com/files/v1/",
+    identity: "https://api.jobnimbus.com/identity/v1/",
+    public: "https://app.jobnimbus.com/api1/",
+};
+const JOB_NIMBUS_SECRET_SCHEMA = z.object({
+    apiKey: z.string().trim().min(1),
+});
+export const JOB_NIMBUS_VALUE_SCHEMA = z.custom(isEncodable, {
+    message: "Expected a codec-safe JobNimbus value.",
+});
+export const JOB_NIMBUS_RESPONSE_SCHEMA = z.union([
+    JOB_NIMBUS_VALUE_SCHEMA,
+    z.undefined().transform(() => null),
+]);
+/** Error returned by a rejected JobNimbus API request. */
+export class JobNimbusApiError extends Error {
+    details;
+    status;
+    /**
+     * Creates an error from a rejected JobNimbus response.
+     *
+     * @param status - HTTP response status.
+     * @param details - Codec-safe response details.
+     */
+    constructor(status, details) {
+        super(`JobNimbus API request failed (${status}).`);
+        this.name = "JobNimbusApiError";
+        this.details = details;
+        this.status = status;
+    }
+}
+/**
+ * Creates an authenticated client for one documented JobNimbus API root.
+ *
+ * @param secret - Stored JobNimbus API key.
+ * @param api - Public API or one current Platform service.
+ */
+export function getJobNimbusApi(secret, api) {
+    const { apiKey } = JOB_NIMBUS_SECRET_SCHEMA.parse(secret);
+    const origin = JOB_NIMBUS_API_ORIGINS[api];
+    const root = new URL(origin);
+    return {
+        /**
+         * Sends one JSON request below the selected JobNimbus API root.
+         *
+         * @param path - Relative path below the selected root.
+         * @param options - Request method, query, body, headers, and response
+         *   schema.
+         */
+        async request(path, options) {
+            const normalizedPath = path.replace(/^\/+/, "");
+            if (!normalizedPath ||
+                normalizedPath.includes("://") ||
+                normalizedPath.includes("\\")) {
+                throw new TypeError("JobNimbus API paths must be relative.");
+            }
+            const url = new URL(normalizedPath, origin);
+            if (url.origin !== root.origin ||
+                !url.pathname.startsWith(root.pathname)) {
+                throw new TypeError("JobNimbus API paths must remain below the selected root.");
+            }
+            for (const [key, value] of Object.entries(options.query ?? {})) {
+                if (value == null)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const item of value)
+                        url.searchParams.append(key, String(item));
+                }
+                else {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+            const headers = new Headers({
+                Accept: "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            });
+            for (const [key, value] of Object.entries(options.headers ?? {})) {
+                if (value !== undefined)
+                    headers.set(key, value);
+            }
+            if (options.body !== undefined) {
+                headers.set("Content-Type", options.contentType ?? "application/json");
+            }
+            const response = await fetch(url, {
+                body: options.body === undefined
+                    ? undefined
+                    : JSON.stringify(api === "public" ? toJobNimbus(options.body) : options.body),
+                headers,
+                method: options.method ?? "GET",
+            });
+            const text = await response.text();
+            const parsed = JOB_NIMBUS_RESPONSE_SCHEMA.safeParse(fromJobNimbus(text ? parseJson(text) : null));
+            if (!response.ok || !parsed.success) {
+                throw new JobNimbusApiError(response.status, parsed.success ? parsed.data : { response: text });
+            }
+            return options.responseSchema.parse(parsed.data);
+        },
+    };
+}
+/**
+ * Downloads one JobNimbus attachment from its documented non-API route.
+ *
+ * @param secret - Stored JobNimbus API key.
+ * @param fileId - Attachment JNID.
+ */
+export async function downloadJobNimbusFile(secret, fileId) {
+    const { apiKey } = JOB_NIMBUS_SECRET_SCHEMA.parse(secret);
+    const response = await fetch(new URL(encodeURIComponent(z.string().trim().min(1).parse(fileId)), "https://app.jobnimbus.com/files/"), { headers: { Authorization: `Bearer ${apiKey}` } });
+    if (!response.ok) {
+        throw new JobNimbusApiError(response.status, {
+            response: await response.text(),
+        });
+    }
+    return response.blob();
+}
+/**
+ * Converts public camelCase JSON into JobNimbus's provider-native keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export function toJobNimbus(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(toJobNimbus);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => key === "customFields" && isPlainObject(item)
+        ? Object.entries(item).map(([field, fieldValue]) => [
+            field,
+            toJobNimbus(fieldValue),
+        ])
+        : [[toSnakeCase(key), toJobNimbus(item)]]));
+}
+/**
+ * Converts JobNimbus JSON into public camelCase values.
+ *
+ * Documented legacy Unix date fields become Date instances. Unknown fields are
+ * preserved so account-defined CRM fields survive normalization.
+ *
+ * @param value - Raw provider value.
+ */
+export function fromJobNimbus(value) {
+    return normalizeJobNimbusValue(value);
+}
+/**
+ * Recursively normalizes one raw provider value and its original key.
+ *
+ * @param value - Raw provider value.
+ * @param providerKey - Original provider field name, when nested in an object.
+ */
+function normalizeJobNimbusValue(value, providerKey) {
+    if (typeof value === "number" && providerKey?.startsWith("date_")) {
+        return new Date(value * 1_000);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeJobNimbusValue(item));
+    }
+    if (!isPlainObject(value))
+        return JOB_NIMBUS_VALUE_SCHEMA.parse(value);
+    const customFields = {};
+    return Object.fromEntries([
+        ...Object.entries(value).flatMap(([key, item]) => {
+            if (/^cf_(?:boolean|date|double|long|string)_\d+$/.test(key)) {
+                customFields[key] = normalizeJobNimbusValue(item, key);
+                return [];
+            }
+            return [
+                [
+                    key === "extermal_id"
+                        ? "externalId"
+                        : key === "jnid"
+                            ? "id"
+                            : key === "recid"
+                                ? "recordId"
+                                : toCamelCase(key),
+                    normalizeJobNimbusValue(item, key),
+                ],
+            ];
+        }),
+        ...(Object.keys(customFields).length > 0
+            ? [["customFields", customFields]]
+            : []),
+    ]);
+}
+/**
+ * Parses a response body while preserving non-JSON diagnostics.
+ *
+ * @param value - Raw response body.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return { response: value };
+    }
+}
+/**
+ * Checks whether a value can be traversed as a JSON-style object.
+ *
+ * @param value - Candidate object value.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Converts one provider snake-case key to camel case.
+ *
+ * @param value - Provider field name.
+ */
+function toCamelCase(value) {
+    return value
+        .replace(/_([a-z0-9])/g, (_match, character) => character.toUpperCase())
+        .replace(/^[A-Z]/, (character) => character.toLowerCase());
+}
+/**
+ * Converts one public camel-case key to provider snake case.
+ *
+ * @param value - Public field name.
+ */
+function toSnakeCase(value) {
+    return value
+        .replace(/([a-zA-Z])([0-9])/g, "$1_$2")
+        .replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`);
+}

package/dist/jobnimbus/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./schemas.js";

package/dist/jobnimbus/index.js

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./schemas.js";