@automate.ax/integration-contracts 0.89.2 → 0.91.0

package/dist/whatsapp/index.d.ts

@@ -330,11 +330,11 @@ export declare const whatsappTriggerContracts: {
                     video: "video";
                     location: "location";
                     system: "system";
+                    order: "order";
                     reaction: "reaction";
                     button: "button";
                     contacts: "contacts";
                     interactive: "interactive";
-                    order: "order";
                     sticker: "sticker";
                     unsupported: "unsupported";
                 }>;
@@ -425,11 +425,11 @@ export declare const whatsappTriggerContracts: {
                     video: "video";
                     location: "location";
                     system: "system";
+                    order: "order";
                     reaction: "reaction";
                     button: "button";
                     contacts: "contacts";
                     interactive: "interactive";
-                    order: "order";
                     sticker: "sticker";
                     unsupported: "unsupported";
                 }>;

package/dist/whatsapp/schemas.d.ts

@@ -96,11 +96,11 @@ export declare const WHATSAPP_WEBHOOK_SCHEMA: z.ZodObject<{
                         video: "video";
                         location: "location";
                         system: "system";
+                        order: "order";
                         reaction: "reaction";
                         button: "button";
                         contacts: "contacts";
                         interactive: "interactive";
-                        order: "order";
                         sticker: "sticker";
                         unsupported: "unsupported";
                     }>;
@@ -189,11 +189,11 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
             video: "video";
             location: "location";
             system: "system";
+            order: "order";
             reaction: "reaction";
             button: "button";
             contacts: "contacts";
             interactive: "interactive";
-            order: "order";
             sticker: "sticker";
             unsupported: "unsupported";
         }>;
@@ -284,11 +284,11 @@ export declare const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA: z.ZodObject<{
             video: "video";
             location: "location";
             system: "system";
+            order: "order";
             reaction: "reaction";
             button: "button";
             contacts: "contacts";
             interactive: "interactive";
-            order: "order";
             sticker: "sticker";
             unsupported: "unsupported";
         }>;
@@ -768,7 +768,7 @@ export declare function normalizeWhatsAppWebhook(input: unknown): {
         message: {
             id: string;
             timestamp: string;
-            type: "unknown" | "text" | "document" | "audio" | "image" | "video" | "location" | "system" | "reaction" | "button" | "contacts" | "interactive" | "order" | "sticker" | "unsupported";
+            type: "unknown" | "text" | "document" | "audio" | "image" | "video" | "location" | "system" | "order" | "reaction" | "button" | "contacts" | "interactive" | "sticker" | "unsupported";
             content?: z.core.util.JSONType | undefined;
             context?: {
                 messageId: string;
@@ -781,7 +781,7 @@ export declare function normalizeWhatsAppWebhook(input: unknown): {
             from: string;
             id: string;
             timestamp: string;
-            type: "unknown" | "text" | "document" | "audio" | "image" | "video" | "location" | "system" | "reaction" | "button" | "contacts" | "interactive" | "order" | "sticker" | "unsupported";
+            type: "unknown" | "text" | "document" | "audio" | "image" | "video" | "location" | "system" | "order" | "reaction" | "button" | "contacts" | "interactive" | "sticker" | "unsupported";
             audio?: {
                 id: string;
                 mime_type?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.89.2",
+  "version": "0.91.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
       "./google-forms": "./src/google-forms/index.ts",
       "./google-meet": "./src/google-meet/index.ts",
       "./github": "./src/github/index.ts",
+      "./jobnimbus": "./src/jobnimbus/index.ts",
       "./linear": "./src/linear/index.ts",
       "./notion": "./src/notion/index.ts",
       "./outlook": "./src/outlook/index.ts",
@@ -47,7 +48,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.89.2",
+    "@automate.ax/codec": "0.91.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -148,6 +149,11 @@
       "types": "./dist/github/index.d.ts",
       "default": "./dist/github/index.js"
     },
+    "./jobnimbus": {
+      "bun": "./src/jobnimbus/index.ts",
+      "types": "./dist/jobnimbus/index.d.ts",
+      "default": "./dist/jobnimbus/index.js"
+    },
     "./linear": {
       "bun": "./src/linear/index.ts",
       "types": "./dist/linear/index.d.ts",

package/src/jobnimbus/api.ts

@@ -0,0 +1,294 @@
+import { isEncodable, type Encodable } 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/",
+} as const
+
+const JOB_NIMBUS_SECRET_SCHEMA = z.object({
+  apiKey: z.string().trim().min(1),
+})
+
+export const JOB_NIMBUS_VALUE_SCHEMA = z.custom<Encodable>(isEncodable, {
+  message: "Expected a codec-safe JobNimbus value.",
+})
+
+export const JOB_NIMBUS_RESPONSE_SCHEMA = z.union([
+  JOB_NIMBUS_VALUE_SCHEMA,
+  z.undefined().transform(() => null),
+])
+
+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 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) {
+    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: unknown, api: JobNimbusApi) {
+  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<TSchema extends z.ZodType>(
+      path: string,
+      options: JobNimbusRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      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: unknown, fileId: string) {
+  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: Encodable): Encodable {
+  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: unknown): Encodable {
+  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: unknown,
+  providerKey?: string,
+): Encodable {
+  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: Record<string, Encodable> = {}
+  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),
+        ] as const,
+      ]
+    }),
+    ...(Object.keys(customFields).length > 0
+      ? [["customFields", customFields] as const]
+      : []),
+  ])
+}
+
+/**
+ * Parses a response body while preserving non-JSON diagnostics.
+ *
+ * @param value - Raw response body.
+ */
+function parseJson(value: string): unknown {
+  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: unknown): value is Record<string, unknown> {
+  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: string) {
+  return value
+    .replace(/_([a-z0-9])/g, (_match, character: string) =>
+      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: string) {
+  return value
+    .replace(/([a-zA-Z])([0-9])/g, "$1_$2")
+    .replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`)
+}

package/src/jobnimbus/index.ts

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